diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index a763a03cd..f06cba747 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -136,6 +136,18 @@ All story files must follow `.storybook/STORY_STANDARD.md`. Key rules:
 - After editing code, verify with `yarn typecheck` to catch TypeScript errors immediately.
 - After completing a task or during planning, verify no circular dependencies or barrel import cycles are introduced. Use `npx madge --circular --extensions ts,vue framework/` or manual inspection of import chains.
 
+## Documentation
+
+`*.docs.md` files in `framework/` are the source of truth for vc-docs. The `cli/docs-sync` package transforms and publishes them.
+
+```bash
+yarn docs:lint                                       # validate *.docs.md template compliance
+yarn docs:sync                                       # sync to ../vc-docs (must exist as a sibling checkout)
+yarn docs:screenshot --story <id> --out <path>.png   # capture a Storybook screenshot per style guide
+```
+
+CI auto-syncs on framework releases. See `cli/docs-sync/README.md` for details.
+
 ## Debugging Tips
 
 - Check git history first for regression bugs: `git log --oneline -15` and `git diff HEAD~3`
diff --git a/.github/workflows/docs-lint.yml b/.github/workflows/docs-lint.yml
new file mode 100644
index 000000000..aae7c0c14
--- /dev/null
+++ b/.github/workflows/docs-lint.yml
@@ -0,0 +1,22 @@
+name: docs-lint
+
+on:
+  pull_request:
+    paths:
+      - "framework/**/*.docs.md"
+      - "framework/**/*.stories.ts"
+      - "cli/docs-sync/**"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+      - run: corepack enable
+      - run: yarn install --immutable
+      - run: yarn workspace @vc-shell/docs-sync build
+      - run: yarn workspace @vc-shell/docs-sync exec docs-sync lint
diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml
new file mode 100644
index 000000000..7886a9a14
--- /dev/null
+++ b/.github/workflows/sync-docs.yml
@@ -0,0 +1,56 @@
+# Requires repository secret VC_DOCS_BOT_TOKEN — a personal access token
+# (or GitHub App installation token) with write access to VirtoCommerce/vc-docs
+# (specifically: contents:write and pull-requests:write).
+# Set up via Settings → Secrets and variables → Actions.
+name: sync-docs
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  sync:
+    if: ${{ !github.event.release.prerelease }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+        with:
+          repository: VirtoCommerce/vc-docs
+          path: vc-docs
+          token: ${{ secrets.VC_DOCS_BOT_TOKEN }}
+          ref: main
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+      - run: corepack enable
+      - run: yarn install --immutable
+      - run: yarn workspace @vc-shell/docs-sync build
+      - name: Run sync
+        run: |
+          yarn workspace @vc-shell/docs-sync exec docs-sync sync \
+            --target ./vc-docs \
+            --report ./sync-report.md
+      - name: Open PR
+        env:
+          GH_TOKEN: ${{ secrets.VC_DOCS_BOT_TOKEN }}
+        run: |
+          BRANCH="auto/sync-vc-shell-${{ github.event.release.tag_name }}"
+          cd vc-docs
+          if [[ -z "$(git status --porcelain)" ]]; then
+            echo "No changes to sync."
+            exit 0
+          fi
+          git checkout -b "$BRANCH"
+          git config user.email "bot@virto.dev"
+          git config user.name "vc-shell-docs-bot"
+          git add .
+          git commit -m "docs: sync from vc-shell@${{ github.event.release.tag_name }}"
+          git push origin "$BRANCH"
+          gh pr create \
+            --base main \
+            --head "$BRANCH" \
+            --title "docs: sync from vc-shell@${{ github.event.release.tag_name }}" \
+            --body-file ../sync-report.md \
+            --label auto-generated
diff --git a/cli/docs-sync/README.md b/cli/docs-sync/README.md
new file mode 100644
index 000000000..5b51c8475
--- /dev/null
+++ b/cli/docs-sync/README.md
@@ -0,0 +1,497 @@
+# @vc-shell/docs-sync
+
+Internal CLI tool that publishes co-located `*.docs.md` files from the vc-shell framework to the public documentation site (vc-docs). Generates Markdown pages, copies image assets, validates the docs template, captures Storybook screenshots, and emits `awesome-pages` navigation files — all driven by frontmatter declared next to the source code.
+
+This package is **internal**. It is not published to npm. It is invoked locally by maintainers and by GitHub Actions on framework releases.
+
+> Design spec: `docs/superpowers/specs/2026-04-28-vc-shell-docs-sync-design.md`
+> Implementation plan: `docs/superpowers/plans/2026-04-28-vc-shell-docs-sync.md`
+
+---
+
+## Why this exists
+
+Documentation for `@vc-shell/framework` lives next to the code in `*.docs.md` files. The public docs site is a separate repository (`vc-docs`) built with mkdocs-material and versioned via [`mike`](https://github.com/jimporter/mike). Without automation those two sources drift — fixes to a component's docs file never reach users.
+
+`docs-sync` is a one-way pipeline: framework `*.docs.md` → transformed Markdown in vc-docs. Manual pages in vc-docs (introduction, getting-started guides, how-tos) are untouched.
+
+---
+
+## Quick start
+
+From the vc-shell repo root:
+
+```bash
+# 1. Validate every *.docs.md against the template
+yarn docs:lint
+
+# 2. Sync all docs into a sibling vc-docs checkout
+yarn docs:sync
+
+# 3. Capture a Storybook screenshot via Playwright
+yarn docs:screenshot --story organisms-vc-data-table--default --out /tmp/preview.png
+```
+
+The root-level shortcuts assume `../vc-docs` exists as a sibling checkout. To target a different path:
+
+```bash
+yarn workspace @vc-shell/docs-sync exec docs-sync sync --target /custom/path/to/vc-docs
+```
+
+---
+
+## Pipeline at a glance
+
+```
+┌──────────────────────┐
+│  framework/**/*.docs.md │  ← source of truth (frontmatter + Markdown)
+└──────────┬───────────┘
+           │
+           ▼
+   ┌──────────────┐
+   │   parser     │  zod-validate frontmatter, gray-matter body, extract image refs
+   └───────┬──────┘
+           ▼
+   ┌──────────────┐
+   │ transformer  │  strip-internal → expand-storybook → rewrite-links → AUTO-GENERATED header
+   └───────┬──────┘
+           ▼
+   ┌──────────────┐
+   │   writer     │  atomic write to target tree, copy image assets, emit .pages files
+   └───────┬──────┘
+           ▼
+   ┌──────────────┐
+   │   report     │  detect orphans, render markdown report, exit code
+   └───────┬──────┘
+           ▼
+┌────────────────────────────────────┐
+│  vc-docs/.../vc-shell/<category>/   │
+│   ├── components/                   │
+│   ├── composables/                  │
+│   ├── concepts/                     │
+│   └── reference/                    │
+└────────────────────────────────────┘
+```
+
+The pipeline is deterministic and idempotent — running `yarn docs:sync` twice in a row produces zero changes the second time.
+
+---
+
+## The `*.docs.md` format
+
+Every file destined for the public site declares its routing and metadata in frontmatter:
+
+````markdown
+---
+title: VcDataTable
+category: components
+group: data-display
+slug: vc-data-table # optional; defaults to source filename without `.docs`
+---
+
+# VcDataTable
+
+Public-facing description (1–2 sentences for the developer using the framework).
+
+## Quick Start
+
+::storybook id="organisms-vc-data-table--default"
+
+## Examples
+
+### With Sorting
+
+::storybook id="organisms-vc-data-table--with-sorting" height="500"
+
+```vue
+<VcDataTable :items="products">
+  <VcColumn id="name" field="name" sortable />
+</VcDataTable>
+```
+````
+
+## Props
+
+| Name  | Type  | Default | Description |
+| ----- | ----- | ------- | ----------- |
+| items | `T[]` | `[]`    | Row data.   |
+
+<!-- internal:start -->
+
+## Architecture notes
+
+This block is for vc-shell contributors. Stripped from the public site.
+
+<!-- internal:end -->
+
+````
+
+### Frontmatter contract
+
+| Field      | Required | Allowed values                                                 |
+| ---------- | -------- | -------------------------------------------------------------- |
+| `title`    | yes      | Free text — used in mkdocs nav.                                |
+| `category` | yes      | `components` / `composables` / `concepts` / `reference`        |
+| `group`    | yes      | A folder under `category/`. See below.                         |
+| `slug`     | no       | Filename in target without `.md`. Defaults to source filename. |
+| `internal` | no       | `true` to skip this file entirely.                             |
+
+### Allowed groups per category
+
+| Category     | Groups                                                                                                                                                |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| components   | `layout` · `form` · `data-display` · `feedback` · `navigation` · `media` · `misc`                                                                     |
+| composables  | `blade-navigation` · `data` · `ui-state` · `services` · `user` · `notifications` · `forms` · `utilities`                                              |
+| concepts     | `root` (single-level — files land directly in `concepts/<slug>.md`)                                                                                   |
+| reference    | `api` · `api/directives` · `modules` · `cli`                                                                                                          |
+
+A wrong `group` for the chosen `category` is rejected by `frontmatter-required` lint with a clear "allowed groups" message.
+
+### Routing rules
+
+Target path is computed as `<category>/<group>/<slug>.md`, with one special case: `group: root` flattens (no group folder).
+
+| Source                                                                | Target                                       |
+| --------------------------------------------------------------------- | -------------------------------------------- |
+| `framework/ui/components/organisms/vc-data-table/vc-data-table.docs.md` | `components/data-display/vc-data-table.md`   |
+| `framework/ui/composables/useDataTableSort.docs.md`                   | `composables/data/useDataTableSort.md`       |
+| `framework/core/services/services.docs.md` (group: root)              | `concepts/services.md`                       |
+| `framework/core/directives/loading/loading.docs.md`                   | `reference/api/directives/v-loading.md`      |
+
+### Internal-only blocks
+
+Wrap any contributor-only sections in `<!-- internal:start -->` / `<!-- internal:end -->` markers. The transformer strips them on every sync. Use this for architecture notes, gotchas, and references to internal file paths that don't belong in the public site.
+
+### Storybook embeds
+
+Use the `::storybook` directive to embed a live story:
+
+```markdown
+::storybook id="organisms-vc-data-table--with-filters" height="500" theme="dark"
+````
+
+| Param    | Purpose                                              | Default  |
+| -------- | ---------------------------------------------------- | -------- |
+| `id`     | Story ID matching the URL slug.                      | required |
+| `height` | iframe height in px.                                 | `400`    |
+| `theme`  | `light` / `dark` / `auto`. Sets `?globals=theme:..`. | `auto`   |
+
+The directive expands at sync time into a styled iframe block plus an "Open in Storybook" link, both styled by `vc-shell-docs.css` in the docs site. Story IDs are validated against the live Storybook `index.json` — unknown IDs fail the lint.
+
+### Image assets
+
+Images referenced relative to the source file are copied alongside the Markdown:
+
+```
+framework/ui/components/organisms/vc-data-table/
+  vc-data-table.docs.md
+  images/
+    column-resize.png
+    mobile-card-view.png
+```
+
+```markdown
+![Column resize](./images/column-resize.png)
+```
+
+The writer copies `./images/X.png` into the target tree at the parallel relative path. Allowed extensions: `png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`. Anything else is rejected by `image-size-limit` lint (also enforces 500 KB warn / 2 MB error budgets).
+
+### Cross-doc links
+
+Internal cross-references between two `*.docs.md` files (e.g. linking from `vc-button` to `vc-link`) are rewritten at sync time to point at the correct target path:
+
+```markdown
+<!-- in vc-button.docs.md -->
+
+See also [VcLink](../vc-link).
+```
+
+becomes
+
+```markdown
+<!-- in components/misc/vc-button.md -->
+
+See also [VcLink](../navigation/vc-link.md).
+```
+
+External URLs and anchor-only fragments are left alone. Image refs (`![...](...)`) are handled by the asset copier, not the link rewriter.
+
+### AUTO-GENERATED marker
+
+Every synced page begins with:
+
+```markdown
+<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY -->
+<!-- Source: framework/ui/components/.../X.docs.md -->
+<!-- To update: edit the source file in vc-shell, then run yarn docs:sync -->
+```
+
+The vc-docs `.github/workflows/protect-generated.yml` workflow blocks PRs (other than from the bot) that try to edit files containing this marker.
+
+---
+
+## Commands
+
+### `yarn docs:sync`
+
+Walks `framework/**/*.docs.md`, applies the transform pipeline, and writes into a vc-docs checkout.
+
+```bash
+yarn docs:sync                                              # default --target ../vc-docs
+yarn workspace @vc-shell/docs-sync exec docs-sync sync \
+  --target /Users/me/DEV/vc-docs                            # explicit target
+  --dry-run                                                 # report only, no writes
+  --report ./my-report.md                                   # custom report path
+  --framework-dir /alt/framework                            # override source root (testing)
+```
+
+Output:
+
+```
+vc-shell@v2.0.3 → /Users/me/DEV/vc-docs
+  changes: 47
+  skipped: 5
+  orphans: 1
+  errors:  0
+  report:  /Users/me/.../sync-report.md
+```
+
+Exit code: `0` on success, `1` if any errors were recorded.
+
+### `yarn docs:lint`
+
+Runs all lint rules against every `*.docs.md` in `framework/`. Returns exit `1` on any error so CI can block bad PRs.
+
+```bash
+yarn docs:lint
+```
+
+Sample output:
+
+````
+warn  vue-block-present  framework/ui/.../vc-button.docs.md: component page contains no ```vue example block
+error frontmatter-required  framework/ui/.../bad.docs.md: missing frontmatter
+
+1 errors, 1 warnings
+````
+
+### `yarn docs:screenshot`
+
+Capture a Playwright screenshot using the style-guide defaults below.
+
+```bash
+# Capture from a running dev server
+yarn workspace @vc-shell/docs-sync exec docs-sync screenshot \
+  --url http://localhost:3000/products \
+  --selector ".vc-blade--list" \
+  --out apps/vendor-portal/.../guides/blades/images/list-blade.png
+
+# Capture a Storybook story
+yarn workspace @vc-shell/docs-sync exec docs-sync screenshot \
+  --story organisms-vc-data-table--with-filters \
+  --theme dark \
+  --viewport 1280x800 \
+  --out framework/.../images/data-table-filters-dark.png
+```
+
+| Option       | Purpose                                                     |
+| ------------ | ----------------------------------------------------------- |
+| `--url`      | Direct URL (dev server, deployed site).                     |
+| `--story`    | Storybook story ID. Loads `<storybookUrl>/iframe.html?id=…` |
+| `--selector` | CSS selector to crop to. Default: full viewport.            |
+| `--theme`    | `light` / `dark` for theme-aware components.                |
+| `--viewport` | `<width>x<height>`. Default: `1280x800`.                    |
+| `--out`      | Output file path. Required.                                 |
+
+#### Screenshot style guide
+
+| Rule           | Value                                                                             |
+| -------------- | --------------------------------------------------------------------------------- |
+| Viewport       | `1280×800` desktop, `390×844` mobile (iPhone 14 frame)                            |
+| Pixel density  | `2×` (retina)                                                                     |
+| Browser chrome | None (headless)                                                                   |
+| Theme          | Both light + dark when visual differs meaningfully; light only otherwise          |
+| Format         | `png` (Playwright limitation — webp post-process via `sharp` is a follow-up)      |
+| Filename       | kebab-case, descriptive: `list-blade-with-filters.png`                            |
+| Crop           | Crop to relevant CSS selector, not viewport. Avoid empty space.                   |
+| Demo data      | Realistic — product names, prices, emails. **No "Test 1 / Test 2 / Lorem ipsum"** |
+| Sensitive data | Never real customer data. Use seed fixtures or Storybook story args.              |
+
+---
+
+## Lint rules
+
+`yarn docs:lint` runs six rules against every `*.docs.md`. Errors block CI; warnings are advisory.
+
+| Rule                    | Severity                     | What it checks                                                                                                                  |
+| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `frontmatter-required`  | error                        | Frontmatter is present and parses against the schema (title/category/group).                                                    |
+| `storybook-id-valid`    | error                        | Every `::storybook id="X"` directive references a real story in `index.json`. Skipped gracefully when Storybook is unreachable. |
+| `image-size-limit`      | warn @ 500 KB / error @ 2 MB | Referenced images stay under size budget. Allowed types: png/jpg/jpeg/gif/webp/svg.                                             |
+| `vue-block-present`     | warn                         | Component pages should include at least one ` ```vue ` block.                                                                   |
+| `material-feature-warn` | warn                         | Long pages (>200 lines) without any admonition / tabs / details / mermaid block — likely missing structure.                     |
+| `mermaid-syntax`        | error                        | Each ` ```mermaid ` block is non-empty and starts with a known diagram keyword.                                                 |
+
+---
+
+## CI integration
+
+Three GitHub Actions wire docs-sync into the release flow.
+
+| Workflow                                  | Repo     | Trigger                                                       | Effect                                                                                      |
+| ----------------------------------------- | -------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `.github/workflows/docs-lint.yml`         | vc-shell | PR touching `*.docs.md` / `*.stories.ts` / `cli/docs-sync/**` | Runs `yarn docs:lint`. Failure blocks merge.                                                |
+| `.github/workflows/sync-docs.yml`         | vc-shell | `release: published` (non-prerelease)                         | Syncs into vc-docs `main` and opens an auto-PR labeled `auto-generated` from a bot account. |
+| `.github/workflows/protect-generated.yml` | vc-docs  | PR touching `vc-shell/**`                                     | Blocks edits to AUTO-GENERATED files unless from the bot or label `auto-generated`.         |
+
+The release sync workflow requires repo secret `VC_DOCS_BOT_TOKEN` — a PAT or GitHub App token with `contents:write` and `pull-requests:write` on `VirtoCommerce/vc-docs`.
+
+---
+
+## Versioning model
+
+vc-docs is versioned via [`mike`](https://github.com/jimporter/mike). Each major (`2.0`, `3.0`, …) lives on its own branch (`main` for current, `release/X.0` for frozen previous majors). vc-shell and vc-docs version **independently**.
+
+Implications for docs-sync:
+
+- Generator only ever writes to vc-docs `main`. Frozen `release/X.0` branches stay immutable.
+- Each vc-shell release re-syncs into the active major. There's no per-release mapping table — `git log` of vc-docs gives the audit trail of which framework version produced which content.
+- Live Storybook embeds in frozen snapshots will show the **latest** framework version (single Storybook deployment in Phase 1). A banner injected via `overrides/main.html` in vc-docs alerts users on numbered-release URLs ("Live demos may differ from documented version").
+- Phase 2 follow-up: per-version Storybook deployments at `vc-shell-storybook.govirto.com/<docs-version>/`. The generator will read the active docs version from `vc-docs/VERSION` and substitute it into iframe URLs at sync time.
+
+---
+
+## Development
+
+### Build and test
+
+From the vc-shell repo root:
+
+```bash
+yarn workspace @vc-shell/docs-sync build       # tsc → dist/
+yarn workspace @vc-shell/docs-sync test        # vitest run, 47 tests
+yarn workspace @vc-shell/docs-sync test:watch  # vitest watch
+```
+
+### Project layout
+
+```
+cli/docs-sync/
+  src/
+    index.ts                        # CLI entry, commander setup
+    config.ts                       # paths, allowed categories/groups, env override
+    types.ts                        # Frontmatter, ParsedDoc, SyncReport, …
+    commands/
+      sync.ts                       # `sync` command
+      lint.ts                       # `lint` command
+      screenshot.ts                 # `screenshot` command
+    parser/
+      frontmatter.ts                # zod schema + cross-field refinement
+      images.ts                     # extract relative ![alt](./path) refs
+      parser.ts                     # gray-matter + frontmatter validation
+    transformer/
+      strip-internal.ts             # remove <!-- internal:* --> blocks
+      storybook-directive.ts        # ::storybook → iframe HTML
+      header.ts                     # AUTO-GENERATED header
+      links.ts                      # rewrite cross-doc relative links
+      pipeline.ts                   # orchestrator
+    storybook/
+      index-fetcher.ts              # download index.json, validate IDs
+    writer/
+      atomic.ts                     # write-file-atomic wrapper
+      writer.ts                     # computeTargetPath + writeMarkdown
+      assets.ts                     # copy referenced images
+      pages.ts                      # emit .pages files for awesome-pages
+    report/
+      tracker.ts                    # accumulate change/skip/error/orphan entries
+      orphans.ts                    # detect orphaned auto-generated files
+      formatter.ts                  # render SyncReport → markdown
+    screenshot/
+      defaults.ts                   # style-guide constants
+      capture.ts                    # Playwright wrapper
+    lint/
+      runner.ts                     # rules registry, runLint orchestrator
+      rules/
+        frontmatter-required.ts
+        storybook-id-valid.ts
+        image-size-limit.ts
+        vue-block-present.ts
+        material-feature-warn.ts
+        mermaid-syntax.ts
+  tests/
+    *.test.ts                       # 14 unit + 1 integration test files
+    fixtures/                       # *.docs.md fixtures (simple-component, integration source tree)
+```
+
+Tests use real `fs.mkdtemp` for isolation and `vi.spyOn(globalThis, "fetch")` to mock network calls.
+
+### Adding a new lint rule
+
+1. Implement `src/lint/rules/<rule-name>.ts` exporting a `LintRule` (object with `name` and `check(file, ctx) -> LintIssue[]` — sync or async).
+2. Register it in `src/lint/runner.ts` `ALL_RULES`.
+3. Add a test case to `tests/lint.test.ts`.
+4. Update the **Lint rules** table in this README.
+
+### Adding a new transformer step
+
+1. Implement `src/transformer/<step>.ts` exporting a pure function `(body: string, ctx: TransformContext) => string`.
+2. Wire it into `src/transformer/pipeline.ts` in the right order. Order matters — `strip-internal` runs before `expand-storybook` so internal blocks containing storybook directives don't get expanded.
+3. Add unit tests for the step.
+
+### Stack
+
+- TypeScript ESM with `moduleResolution: "NodeNext"` (matches `cli/migrate`)
+- Node 20+
+- `commander` (CLI argv)
+- `gray-matter` (frontmatter)
+- `zod` (frontmatter schema)
+- `globby` (file walking)
+- `write-file-atomic` (safe atomic writes)
+- `chalk` (terminal output)
+- `@playwright/test` (screenshot)
+- `vitest` (tests)
+
+---
+
+## Phase 0 — editorial pass
+
+Before automation can produce useful docs the source files need a one-time editorial pass: 150 `*.docs.md` files normalised to the template (frontmatter added, sections aligned, contributor-only chunks wrapped in `<!-- internal:* -->`, examples added, Storybook embeds added). This is content work, not engineering work — done as a separate workstream over several PRs grouped by category.
+
+Until Phase 0 is complete, `yarn docs:lint` reports many errors and warnings against the current framework. That's expected. CI for `docs-lint.yml` may need `continue-on-error: true` while Phase 0 is in flight.
+
+---
+
+## Troubleshooting
+
+**`error frontmatter-required: missing frontmatter`** — the file has no `---` block at the top, or the block parses to an empty object. Add the four required fields.
+
+**`error storybook-id-valid: unknown Storybook story id "X"`** — the story ID doesn't exist in the live Storybook `index.json`. Either the story was renamed in the `.stories.ts` file, or there's a typo in the directive. Check `https://vc-shell-storybook.govirto.com/index.json`.
+
+**Sync exits 1 with no error in stdout** — open `sync-report.md` in the working directory; the full error list is there.
+
+**Newly created `*.docs.md` is skipped without comment** — `yarn docs:lint` to surface the reason. Most often a frontmatter issue.
+
+**`docs:sync` shows N orphans** — files in vc-docs that carry the AUTO-GENERATED marker but no longer have a matching source. Decide per-file: either restore the source (rename happened?), or delete the orphan in a follow-up PR. The generator never deletes orphans automatically.
+
+**Screenshot command hangs / times out** — Playwright needs the chromium binary on first run. From inside the workspace: `yarn workspace @vc-shell/docs-sync exec playwright install chromium`.
+
+**Storybook iframe inside synced docs shows the wrong version** — expected during Phase 1. See "Versioning model" above. The frozen-snapshot banner explains this to readers.
+
+---
+
+## Status (2026-05)
+
+| Component                                | Status                          |
+| ---------------------------------------- | ------------------------------- |
+| `cli/docs-sync` package                  | ✅ shipped                      |
+| 6 lint rules                             | ✅ shipped                      |
+| Sync, lint, screenshot commands          | ✅ shipped                      |
+| `docs-lint.yml` workflow (vc-shell)      | ✅ shipped                      |
+| `sync-docs.yml` workflow (vc-shell)      | ✅ shipped                      |
+| `protect-generated.yml` (vc-docs)        | ✅ on branch, awaiting merge    |
+| `vc-shell-docs.css` (vc-docs)            | ✅ on branch, awaiting merge    |
+| Frozen-version banner (vc-docs)          | ✅ on branch, awaiting merge    |
+| Phase 0 editorial pass (150 files)       | ⏳ separate workstream          |
+| Folder restructure in vc-docs            | ⏳ deferred until Phase 0 lands |
+| Versioned Storybook deployment (Phase 2) | ⏳ follow-up                    |
+| Auto-screenshot pipeline                 | ⏳ follow-up                    |
diff --git a/cli/docs-sync/package.json b/cli/docs-sync/package.json
new file mode 100644
index 000000000..5ec898c09
--- /dev/null
+++ b/cli/docs-sync/package.json
@@ -0,0 +1,37 @@
+{
+  "name": "@vc-shell/docs-sync",
+  "version": "2.0.3",
+  "private": true,
+  "type": "module",
+  "bin": "./dist/index.js",
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "sync": "tsx src/index.ts sync",
+    "lint:docs": "tsx src/index.ts lint",
+    "screenshot": "tsx src/index.ts screenshot"
+  },
+  "dependencies": {
+    "@playwright/test": "^1.52.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "globby": "^14.0.0",
+    "gray-matter": "^4.0.3",
+    "write-file-atomic": "^7.0.1",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "@types/write-file-atomic": "^4.0.3",
+    "@vc-shell/ts-config": "workspace:*",
+    "tsx": "^4.7.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
+}
diff --git a/cli/docs-sync/src/commands/lint.ts b/cli/docs-sync/src/commands/lint.ts
new file mode 100644
index 000000000..72c3d577c
--- /dev/null
+++ b/cli/docs-sync/src/commands/lint.ts
@@ -0,0 +1,39 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { globby } from "globby";
+import chalk from "chalk";
+import { FRAMEWORK_DIR, STORYBOOK_URL } from "../config.js";
+import { fetchStorybookIds } from "../storybook/index-fetcher.js";
+import { runLint } from "../lint/runner.js";
+
+export async function runLintCommand(): Promise<{ exitCode: number }> {
+  const sources = await globby(["**/*.docs.md"], { cwd: FRAMEWORK_DIR, absolute: true });
+  const files = await Promise.all(
+    sources.map(async (abs) => ({
+      absPath: abs,
+      relPath: path.relative(FRAMEWORK_DIR, abs),
+      raw: await fs.readFile(abs, "utf8"),
+    })),
+  );
+
+  let knownStoryIds = new Set<string>();
+  try {
+    knownStoryIds = await fetchStorybookIds(STORYBOOK_URL);
+  } catch (err) {
+    console.warn(
+      chalk.yellow(`warning: could not fetch Storybook index (${(err as Error).message}); skipping story-id checks`),
+    );
+  }
+
+  const result = await runLint({ sources: files, knownStoryIds });
+
+  for (const w of result.warnings) {
+    console.log(chalk.yellow(`warn  ${w.rule}  ${w.file}: ${w.message}`));
+  }
+  for (const e of result.errors) {
+    console.log(chalk.red(`error ${e.rule}  ${e.file}: ${e.message}`));
+  }
+  console.log(chalk.bold(`\n${result.errors.length} errors, ${result.warnings.length} warnings`));
+
+  return { exitCode: result.errors.length > 0 ? 1 : 0 };
+}
diff --git a/cli/docs-sync/src/commands/screenshot.ts b/cli/docs-sync/src/commands/screenshot.ts
new file mode 100644
index 000000000..c7ecff0dc
--- /dev/null
+++ b/cli/docs-sync/src/commands/screenshot.ts
@@ -0,0 +1,33 @@
+import path from "node:path";
+import { captureScreenshot } from "../screenshot/capture.js";
+
+export interface ScreenshotArgs {
+  url?: string;
+  story?: string;
+  selector?: string;
+  theme?: "light" | "dark";
+  viewport?: string; // "1280x800"
+  out: string;
+}
+
+export async function runScreenshotCommand(args: ScreenshotArgs): Promise<{ exitCode: number }> {
+  let viewportWidth: number | undefined;
+  let viewportHeight: number | undefined;
+  if (args.viewport) {
+    const [w, h] = args.viewport.split("x").map((n) => parseInt(n, 10));
+    if (Number.isFinite(w) && Number.isFinite(h)) {
+      viewportWidth = w;
+      viewportHeight = h;
+    }
+  }
+  await captureScreenshot({
+    url: args.url,
+    story: args.story,
+    selector: args.selector,
+    theme: args.theme,
+    viewportWidth,
+    viewportHeight,
+    out: path.resolve(args.out),
+  });
+  return { exitCode: 0 };
+}
diff --git a/cli/docs-sync/src/commands/sync.ts b/cli/docs-sync/src/commands/sync.ts
new file mode 100644
index 000000000..3177f7c86
--- /dev/null
+++ b/cli/docs-sync/src/commands/sync.ts
@@ -0,0 +1,155 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { globby } from "globby";
+import chalk from "chalk";
+import { FRAMEWORK_DIR, STORYBOOK_URL, VC_DOCS_RELATIVE_BASE } from "../config.js";
+import { parseDocFile, FrontmatterError } from "../parser/parser.js";
+import { runTransformPipeline } from "../transformer/pipeline.js";
+import { fetchStorybookIds } from "../storybook/index-fetcher.js";
+import { computeTargetPath, writeMarkdown } from "../writer/writer.js";
+import { copyImageAssets } from "../writer/assets.js";
+import { writePagesFiles } from "../writer/pages.js";
+import { findOrphans } from "../report/orphans.js";
+import { ReportTracker } from "../report/tracker.js";
+import { formatReport } from "../report/formatter.js";
+import type { Frontmatter } from "../types.js";
+
+export interface SyncArgs {
+  target: string; // path to vc-docs root
+  frameworkDir?: string; // override: defaults to FRAMEWORK_DIR (vc-shell/framework)
+  dryRun?: boolean;
+  reportPath?: string; // optional override for report output
+}
+
+export async function runSync(args: SyncArgs): Promise<{ exitCode: number }> {
+  const frameworkDir = args.frameworkDir ?? FRAMEWORK_DIR;
+  const targetAbs = path.resolve(args.target);
+  const targetSection = path.join(targetAbs, VC_DOCS_RELATIVE_BASE);
+
+  // Read framework version.
+  const fwPkg = JSON.parse(await fs.readFile(path.join(frameworkDir, "package.json"), "utf8"));
+  const vcShellVersion = `v${fwPkg.version}`;
+
+  // Fetch Storybook story IDs.
+  const knownStoryIds = await fetchStorybookIds(STORYBOOK_URL);
+
+  // Discover all *.docs.md.
+  const sources = await globby(["**/*.docs.md"], { cwd: frameworkDir, absolute: true });
+
+  const tracker = new ReportTracker();
+
+  // First pass: parse all docs to build a path map for cross-doc link resolution.
+  const parsed = new Map<string, { fm: Frontmatter; rel: string; target: string }>();
+  for (const abs of sources) {
+    const rel = path.relative(frameworkDir, abs);
+    try {
+      const doc = await parseDocFile(abs);
+      if (doc.frontmatter.internal) {
+        tracker.recordSkip({ source: rel, reason: "internal" });
+        continue;
+      }
+      const target = computeTargetPath(doc.frontmatter, path.basename(abs));
+      parsed.set(abs, { fm: doc.frontmatter, rel, target });
+    } catch (err) {
+      if (err instanceof FrontmatterError) {
+        // Distinguish "no frontmatter at all" from "invalid frontmatter" by checking the source.
+        const raw = await fs.readFile(abs, "utf8");
+        if (!raw.startsWith("---")) {
+          tracker.recordSkip({ source: rel, reason: "no-frontmatter" });
+        } else {
+          tracker.recordSkip({ source: rel, reason: "invalid-frontmatter", detail: err.message });
+        }
+      } else {
+        tracker.recordError({ source: rel, message: (err as Error).message });
+      }
+    }
+  }
+
+  // Build resolveTarget: map (sourcePath, href) → target path.
+  // Strategy: for any link href, resolve absolutely from sourceDir, normalize to .docs.md
+  // suffix, and look up in `parsed`.
+  const sourceToTarget = new Map<string, string>();
+  for (const [absSrc, info] of parsed) {
+    sourceToTarget.set(absSrc, info.target);
+  }
+  const resolveTarget = (sourceRel: string, href: string): string | null => {
+    const sourceAbs = path.join(frameworkDir, sourceRel);
+    const sourceDir = path.dirname(sourceAbs);
+    // Try a few common patterns: `../foo`, `../foo/foo`, `../foo/foo.docs.md`.
+    const candidates = [
+      path.resolve(sourceDir, href),
+      path.resolve(sourceDir, href + ".docs.md"),
+      path.resolve(sourceDir, href, path.basename(href) + ".docs.md"),
+    ];
+    for (const cand of candidates) {
+      const found = sourceToTarget.get(cand);
+      if (found) return found;
+    }
+    return null;
+  };
+
+  // Second pass: transform and write.
+  const synced: { target: string; title: string }[] = [];
+  for (const [abs, info] of parsed) {
+    try {
+      const doc = await parseDocFile(abs);
+      const transformed = runTransformPipeline(doc.body, {
+        sourceRelPath: info.rel,
+        sourcePath: info.rel,
+        targetPath: info.target,
+        storybookUrl: STORYBOOK_URL,
+        knownStoryIds,
+        resolveTarget,
+      });
+
+      if (args.dryRun) {
+        tracker.recordChange({ source: info.rel, target: info.target, kind: "created" });
+        synced.push({ target: info.target, title: info.fm.title });
+        continue;
+      }
+
+      const writeRes = await writeMarkdown(targetSection, info.target, transformed);
+      tracker.recordChange({ source: info.rel, target: info.target, kind: writeRes.kind });
+      synced.push({ target: info.target, title: info.fm.title });
+
+      if (doc.imageRefs.length > 0) {
+        await copyImageAssets({
+          sourceFile: abs,
+          targetFile: path.join(targetSection, info.target),
+          imageRefs: doc.imageRefs,
+        });
+      }
+    } catch (err) {
+      tracker.recordError({ source: info.rel, message: (err as Error).message });
+    }
+  }
+
+  // Emit .pages files.
+  if (!args.dryRun) {
+    await writePagesFiles(targetSection, { synced });
+  }
+
+  // Detect orphans.
+  const syncedSet = new Set(synced.map((s) => s.target));
+  const orphans = await findOrphans(targetSection, syncedSet);
+  tracker.setOrphans(orphans);
+
+  // Build and write report.
+  const report = tracker.build({
+    vcShellVersion,
+    timestamp: new Date().toISOString(),
+  });
+  const md = formatReport(report);
+  const reportPath = args.reportPath ?? path.join(process.cwd(), "sync-report.md");
+  await fs.writeFile(reportPath, md, "utf8");
+
+  // Print summary to stdout.
+  console.log(chalk.bold(`vc-shell@${vcShellVersion} → ${args.target}`));
+  console.log(`  changes: ${report.changes.length}`);
+  console.log(`  skipped: ${report.skipped.length}`);
+  console.log(`  orphans: ${orphans.length}`);
+  console.log(`  errors:  ${report.errors.length}`);
+  console.log(`  report:  ${reportPath}`);
+
+  return { exitCode: report.errors.length > 0 ? 1 : 0 };
+}
diff --git a/cli/docs-sync/src/config.ts b/cli/docs-sync/src/config.ts
new file mode 100644
index 000000000..20be339df
--- /dev/null
+++ b/cli/docs-sync/src/config.ts
@@ -0,0 +1,36 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// vc-shell repo root: cli/docs-sync/src/ → ../../..
+export const FRAMEWORK_ROOT = path.resolve(__dirname, "../../..");
+
+export const FRAMEWORK_DIR = path.join(FRAMEWORK_ROOT, "framework");
+
+export const VC_DOCS_RELATIVE_BASE = "platform/developer-guide/docs/custom-apps-development/vc-shell";
+
+export const STORYBOOK_URL = "https://vc-shell-storybook.govirto.com";
+
+export const ALLOWED_CATEGORIES = ["components", "composables", "concepts", "plugins", "reference"] as const;
+
+export type Category = (typeof ALLOWED_CATEGORIES)[number];
+
+// Allowed groups per category. Match the spec's structure section exactly.
+export const ALLOWED_GROUPS: Record<Category, string[]> = {
+  components: ["layout", "form", "data-display", "feedback", "navigation", "media", "misc"],
+  composables: ["blade-navigation", "data", "ui-state", "services", "user", "notifications", "forms", "utilities"],
+  concepts: ["root"], // concepts has no sub-grouping; group="root" → file lands at concepts/<slug>.md
+  plugins: ["root"],
+  reference: ["api", "api/directives", "modules", "cli"],
+};
+
+// Folders inside vc-docs that the generator MUST NOT touch.
+export const MANUAL_ONLY_FOLDERS = [
+  "introduction",
+  "getting-started",
+  "guides",
+  "concepts",
+  "reference/migration",
+  "reference/cli",
+];
diff --git a/cli/docs-sync/src/index.ts b/cli/docs-sync/src/index.ts
new file mode 100644
index 000000000..7e14df484
--- /dev/null
+++ b/cli/docs-sync/src/index.ts
@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+
+const program = new Command();
+program.name("docs-sync").description("vc-shell → vc-docs sync tool").version("0.1.0");
+
+program
+  .command("sync")
+  .description("Sync *.docs.md from vc-shell into vc-docs")
+  .requiredOption("--target <path>", "path to vc-docs checkout")
+  .option("--dry-run", "do not write files; only report what would change")
+  .option("--report <path>", "where to write sync-report.md (default: ./sync-report.md)")
+  .option("--framework-dir <path>", "override path to vc-shell framework root (for testing)")
+  .action(async (opts) => {
+    const { runSync } = await import("./commands/sync.js");
+    const res = await runSync({
+      target: opts.target,
+      frameworkDir: opts.frameworkDir,
+      dryRun: opts.dryRun,
+      reportPath: opts.report,
+    });
+    process.exit(res.exitCode);
+  });
+
+program
+  .command("lint")
+  .description("Validate *.docs.md against the template")
+  .action(async () => {
+    const { runLintCommand } = await import("./commands/lint.js");
+    const res = await runLintCommand();
+    process.exit(res.exitCode);
+  });
+
+program
+  .command("screenshot")
+  .description("Capture a Playwright screenshot using style-guide defaults")
+  .option("--url <url>", "direct URL (e.g. dev server)")
+  .option("--story <id>", "Storybook story id")
+  .option("--selector <css>", "CSS selector to crop to")
+  .option("--theme <theme>", "light | dark")
+  .option("--viewport <wxh>", "viewport size, e.g. 1280x800")
+  .requiredOption("--out <path>", "output file path (.webp)")
+  .action(async (opts) => {
+    const { runScreenshotCommand } = await import("./commands/screenshot.js");
+    const res = await runScreenshotCommand(opts);
+    process.exit(res.exitCode);
+  });
+
+program.parse();
diff --git a/cli/docs-sync/src/lint/rules/frontmatter-required.ts b/cli/docs-sync/src/lint/rules/frontmatter-required.ts
new file mode 100644
index 000000000..1d14e3ad8
--- /dev/null
+++ b/cli/docs-sync/src/lint/rules/frontmatter-required.ts
@@ -0,0 +1,18 @@
+import matter from "gray-matter";
+import { validateFrontmatter } from "../../parser/frontmatter.js";
+import type { LintRule, LintIssue } from "../runner.js";
+
+export const frontmatterRequired: LintRule = {
+  name: "frontmatter-required",
+  check(file): LintIssue[] {
+    const parsed = matter(file.raw);
+    if (!parsed.data || Object.keys(parsed.data).length === 0) {
+      return [{ rule: "frontmatter-required", file: file.relPath, severity: "error", message: "missing frontmatter" }];
+    }
+    const v = validateFrontmatter(parsed.data);
+    if (!v.success) {
+      return [{ rule: "frontmatter-required", file: file.relPath, severity: "error", message: v.error }];
+    }
+    return [];
+  },
+};
diff --git a/cli/docs-sync/src/lint/rules/image-size-limit.ts b/cli/docs-sync/src/lint/rules/image-size-limit.ts
new file mode 100644
index 000000000..b61915abf
--- /dev/null
+++ b/cli/docs-sync/src/lint/rules/image-size-limit.ts
@@ -0,0 +1,44 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { findRelativeImageRefs } from "../../parser/images.js";
+import type { LintRule, LintIssue } from "../runner.js";
+
+const WARN_BYTES = 500 * 1024;
+const ERROR_BYTES = 2 * 1024 * 1024;
+
+export const imageSizeLimit: LintRule = {
+  name: "image-size-limit",
+  async check(file): Promise<LintIssue[]> {
+    const refs = findRelativeImageRefs(file.raw);
+    const out: LintIssue[] = [];
+    const dir = path.dirname(file.absPath);
+    for (const ref of refs) {
+      const abs = path.resolve(dir, ref);
+      try {
+        const stat = await fs.stat(abs);
+        if (stat.size > ERROR_BYTES) {
+          out.push({
+            rule: "image-size-limit",
+            file: file.relPath,
+            severity: "error",
+            message: `${ref} is ${formatKB(stat.size)} (> 2 MB)`,
+          });
+        } else if (stat.size > WARN_BYTES) {
+          out.push({
+            rule: "image-size-limit",
+            file: file.relPath,
+            severity: "warning",
+            message: `${ref} is ${formatKB(stat.size)} (> 500 KB)`,
+          });
+        }
+      } catch {
+        // missing image — handled by a separate rule if needed
+      }
+    }
+    return out;
+  },
+};
+
+function formatKB(bytes: number): string {
+  return `${(bytes / 1024).toFixed(0)} KB`;
+}
diff --git a/cli/docs-sync/src/lint/rules/material-feature-warn.ts b/cli/docs-sync/src/lint/rules/material-feature-warn.ts
new file mode 100644
index 000000000..ca3f49b06
--- /dev/null
+++ b/cli/docs-sync/src/lint/rules/material-feature-warn.ts
@@ -0,0 +1,23 @@
+import matter from "gray-matter";
+import type { LintRule, LintIssue } from "../runner.js";
+
+const FEATURE_RE = /(^!!! )|(^=== ")|(^\?\?\? )|(^```mermaid)/m;
+const LINE_THRESHOLD = 200;
+
+export const materialFeatureWarn: LintRule = {
+  name: "material-feature-warn",
+  check(file): LintIssue[] {
+    const parsed = matter(file.raw);
+    const lines = parsed.content.split("\n").length;
+    if (lines < LINE_THRESHOLD) return [];
+    if (FEATURE_RE.test(parsed.content)) return [];
+    return [
+      {
+        rule: "material-feature-warn",
+        file: file.relPath,
+        severity: "warning",
+        message: `${lines}-line page uses no admonition / tabs / details / mermaid — consider breaking up with material features`,
+      },
+    ];
+  },
+};
diff --git a/cli/docs-sync/src/lint/rules/mermaid-syntax.ts b/cli/docs-sync/src/lint/rules/mermaid-syntax.ts
new file mode 100644
index 000000000..e1e24485a
--- /dev/null
+++ b/cli/docs-sync/src/lint/rules/mermaid-syntax.ts
@@ -0,0 +1,31 @@
+import type { LintRule, LintIssue } from "../runner.js";
+
+const BLOCK_RE = /```mermaid\n([\s\S]*?)```/g;
+
+export const mermaidSyntax: LintRule = {
+  name: "mermaid-syntax",
+  check(file): LintIssue[] {
+    const out: LintIssue[] = [];
+    for (const m of file.raw.matchAll(BLOCK_RE)) {
+      const body = m[1].trim();
+      if (!body) {
+        out.push({ rule: "mermaid-syntax", file: file.relPath, severity: "error", message: "empty mermaid block" });
+        continue;
+      }
+      // Crude: must start with a recognized diagram keyword.
+      if (
+        !/^(graph|flowchart|sequenceDiagram|classDiagram|stateDiagram|erDiagram|journey|gantt|pie|gitGraph)\b/.test(
+          body,
+        )
+      ) {
+        out.push({
+          rule: "mermaid-syntax",
+          file: file.relPath,
+          severity: "error",
+          message: "mermaid block does not start with a known diagram keyword",
+        });
+      }
+    }
+    return out;
+  },
+};
diff --git a/cli/docs-sync/src/lint/rules/storybook-id-valid.ts b/cli/docs-sync/src/lint/rules/storybook-id-valid.ts
new file mode 100644
index 000000000..31bacc72e
--- /dev/null
+++ b/cli/docs-sync/src/lint/rules/storybook-id-valid.ts
@@ -0,0 +1,23 @@
+import type { LintRule, LintIssue } from "../runner.js";
+
+const RE = /::storybook\s+[^\n]*\bid="([^"]+)"/g;
+
+export const storybookIdValid: LintRule = {
+  name: "storybook-id-valid",
+  check(file, ctx): LintIssue[] {
+    const issues: LintIssue[] = [];
+    for (const m of file.raw.matchAll(RE)) {
+      const id = m[1];
+      if (ctx.knownStoryIds.size === 0) continue; // skip when index unavailable
+      if (!ctx.knownStoryIds.has(id)) {
+        issues.push({
+          rule: "storybook-id-valid",
+          file: file.relPath,
+          severity: "error",
+          message: `unknown Storybook story id: "${id}"`,
+        });
+      }
+    }
+    return issues;
+  },
+};
diff --git a/cli/docs-sync/src/lint/rules/vue-block-present.ts b/cli/docs-sync/src/lint/rules/vue-block-present.ts
new file mode 100644
index 000000000..19b2aa6df
--- /dev/null
+++ b/cli/docs-sync/src/lint/rules/vue-block-present.ts
@@ -0,0 +1,19 @@
+import matter from "gray-matter";
+import type { LintRule, LintIssue } from "../runner.js";
+
+export const vueBlockPresent: LintRule = {
+  name: "vue-block-present",
+  check(file): LintIssue[] {
+    const parsed = matter(file.raw);
+    if ((parsed.data?.category as string) !== "components") return [];
+    if (/```vue\b/.test(parsed.content)) return [];
+    return [
+      {
+        rule: "vue-block-present",
+        file: file.relPath,
+        severity: "warning",
+        message: "component page contains no ```vue example block",
+      },
+    ];
+  },
+};
diff --git a/cli/docs-sync/src/lint/runner.ts b/cli/docs-sync/src/lint/runner.ts
new file mode 100644
index 000000000..9eba5c527
--- /dev/null
+++ b/cli/docs-sync/src/lint/runner.ts
@@ -0,0 +1,65 @@
+import { frontmatterRequired } from "./rules/frontmatter-required.js";
+import { storybookIdValid } from "./rules/storybook-id-valid.js";
+import { imageSizeLimit } from "./rules/image-size-limit.js";
+import { vueBlockPresent } from "./rules/vue-block-present.js";
+import { materialFeatureWarn } from "./rules/material-feature-warn.js";
+import { mermaidSyntax } from "./rules/mermaid-syntax.js";
+
+export interface LintFile {
+  absPath: string;
+  relPath: string;
+  raw: string;
+}
+
+export type LintSeverity = "error" | "warning";
+
+export interface LintIssue {
+  rule: string;
+  file: string;
+  severity: LintSeverity;
+  message: string;
+}
+
+export interface LintRule {
+  name: string;
+  check(file: LintFile, ctx: LintContext): LintIssue[] | Promise<LintIssue[]>;
+}
+
+export interface LintContext {
+  knownStoryIds: Set<string>;
+}
+
+export interface LintArgs {
+  sources: LintFile[];
+  knownStoryIds: Set<string>;
+}
+
+export interface LintResult {
+  errors: LintIssue[];
+  warnings: LintIssue[];
+}
+
+const ALL_RULES: LintRule[] = [
+  frontmatterRequired,
+  storybookIdValid,
+  imageSizeLimit,
+  vueBlockPresent,
+  materialFeatureWarn,
+  mermaidSyntax,
+];
+
+export async function runLint(args: LintArgs): Promise<LintResult> {
+  const errors: LintIssue[] = [];
+  const warnings: LintIssue[] = [];
+  const ctx: LintContext = { knownStoryIds: args.knownStoryIds };
+  for (const file of args.sources) {
+    for (const rule of ALL_RULES) {
+      const issues = await rule.check(file, ctx);
+      for (const issue of issues) {
+        if (issue.severity === "error") errors.push(issue);
+        else warnings.push(issue);
+      }
+    }
+  }
+  return { errors, warnings };
+}
diff --git a/cli/docs-sync/src/parser/frontmatter.ts b/cli/docs-sync/src/parser/frontmatter.ts
new file mode 100644
index 000000000..865492ee2
--- /dev/null
+++ b/cli/docs-sync/src/parser/frontmatter.ts
@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { ALLOWED_CATEGORIES, ALLOWED_GROUPS } from "../config.js";
+import type { Frontmatter } from "../types.js";
+
+const schema = z
+  .object({
+    title: z.string().min(1),
+    category: z.enum(ALLOWED_CATEGORIES),
+    group: z.string().min(1),
+    slug: z.string().optional(),
+    placement: z.enum(["index"]).optional(),
+    internal: z.boolean().optional(),
+  })
+  .refine(
+    (data) => ALLOWED_GROUPS[data.category]?.includes(data.group) ?? false,
+    (data) => ({
+      message: `group "${data.group}" is not allowed for category "${data.category}". Allowed: ${ALLOWED_GROUPS[data.category]?.join(", ") ?? "none"}`,
+      path: ["group"],
+    }),
+  )
+  .refine((data) => !(data.placement === "index" && data.group === "root"), {
+    message: "placement: index requires a named group, not 'root'",
+    path: ["placement"],
+  });
+
+export type ValidationResult = { success: true; data: Frontmatter } | { success: false; error: string };
+
+export function validateFrontmatter(input: unknown): ValidationResult {
+  const result = schema.safeParse(input);
+  if (result.success) {
+    return { success: true, data: result.data as Frontmatter };
+  }
+  const message = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+  return { success: false, error: message };
+}
diff --git a/cli/docs-sync/src/parser/images.ts b/cli/docs-sync/src/parser/images.ts
new file mode 100644
index 000000000..b863de6da
--- /dev/null
+++ b/cli/docs-sync/src/parser/images.ts
@@ -0,0 +1,9 @@
+const RE = /!\[[^\]]*\]\((\.\.?\/[^)]+)\)/g;
+
+export function findRelativeImageRefs(body: string): string[] {
+  const refs: string[] = [];
+  for (const match of body.matchAll(RE)) {
+    refs.push(match[1]);
+  }
+  return refs;
+}
diff --git a/cli/docs-sync/src/parser/parser.ts b/cli/docs-sync/src/parser/parser.ts
new file mode 100644
index 000000000..d00e0fd85
--- /dev/null
+++ b/cli/docs-sync/src/parser/parser.ts
@@ -0,0 +1,32 @@
+import fs from "node:fs/promises";
+import matter from "gray-matter";
+import { validateFrontmatter } from "./frontmatter.js";
+import { findRelativeImageRefs } from "./images.js";
+import type { ParsedDoc } from "../types.js";
+
+export class FrontmatterError extends Error {
+  constructor(
+    public readonly file: string,
+    message: string,
+  ) {
+    super(`[${file}] ${message}`);
+    this.name = "FrontmatterError";
+  }
+}
+
+export async function parseDocFile(absolutePath: string): Promise<ParsedDoc> {
+  const raw = await fs.readFile(absolutePath, "utf8");
+  const parsed = matter(raw);
+
+  const validation = validateFrontmatter(parsed.data);
+  if (!validation.success) {
+    throw new FrontmatterError(absolutePath, validation.error);
+  }
+
+  return {
+    sourcePath: absolutePath,
+    frontmatter: validation.data,
+    body: parsed.content,
+    imageRefs: findRelativeImageRefs(parsed.content),
+  };
+}
diff --git a/cli/docs-sync/src/report/formatter.ts b/cli/docs-sync/src/report/formatter.ts
new file mode 100644
index 000000000..0ebf67a84
--- /dev/null
+++ b/cli/docs-sync/src/report/formatter.ts
@@ -0,0 +1,61 @@
+import type { SyncReport, ChangeKind } from "../types.js";
+
+const KINDS: ChangeKind[] = ["created", "updated", "unchanged"];
+
+export function formatReport(report: SyncReport): string {
+  const lines: string[] = [];
+  lines.push(`# vc-docs sync report — vc-shell@${report.vcShellVersion} — ${report.timestamp}`);
+  lines.push("");
+
+  const counts: Record<ChangeKind, number> = { created: 0, updated: 0, unchanged: 0 };
+  for (const c of report.changes) counts[c.kind]++;
+  const skippedInternal = report.skipped.filter((s) => s.reason === "internal").length;
+  const skippedNoFm = report.skipped.filter((s) => s.reason === "no-frontmatter").length;
+  const skippedInvalid = report.skipped.filter((s) => s.reason === "invalid-frontmatter").length;
+
+  lines.push("## Summary");
+  lines.push(`- Created: ${counts.created}`);
+  lines.push(`- Updated: ${counts.updated}`);
+  lines.push(`- Unchanged: ${counts.unchanged}`);
+  lines.push(`- Skipped (no frontmatter): ${skippedNoFm}`);
+  lines.push(`- Skipped (internal): ${skippedInternal}`);
+  lines.push(`- Skipped (invalid frontmatter): ${skippedInvalid}`);
+  lines.push(`- Orphaned: ${report.orphans.length}`);
+  lines.push(`- Errors: ${report.errors.length}`);
+  lines.push("");
+
+  for (const kind of KINDS) {
+    const list = report.changes.filter((c) => c.kind === kind);
+    if (list.length === 0) continue;
+    lines.push(`## ${capitalize(kind)}`);
+    for (const c of list) lines.push(`- ${c.target}  (← ${c.source})`);
+    lines.push("");
+  }
+
+  if (report.orphans.length > 0) {
+    lines.push("## Orphaned (synced previously, source gone)");
+    for (const o of report.orphans) lines.push(`- ${o.target}`);
+    lines.push("");
+  }
+
+  if (report.skipped.length > 0) {
+    lines.push("## Skipped");
+    for (const s of report.skipped)
+      lines.push(`- ${s.source}  — reason: ${s.reason}${s.detail ? ` (${s.detail})` : ""}`);
+    lines.push("");
+  }
+
+  lines.push("## Errors");
+  if (report.errors.length === 0) {
+    lines.push("(none)");
+  } else {
+    for (const e of report.errors) lines.push(`- ${e.source}: ${e.message}`);
+  }
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
diff --git a/cli/docs-sync/src/report/orphans.ts b/cli/docs-sync/src/report/orphans.ts
new file mode 100644
index 000000000..4b23a9bf9
--- /dev/null
+++ b/cli/docs-sync/src/report/orphans.ts
@@ -0,0 +1,18 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { globby } from "globby";
+import { hasAutoGeneratedMarker } from "../transformer/header.js";
+import type { OrphanEntry } from "../types.js";
+
+export async function findOrphans(targetRoot: string, syncedRelPaths: Set<string>): Promise<OrphanEntry[]> {
+  const files = await globby(["**/*.md"], { cwd: targetRoot, absolute: false });
+  const out: OrphanEntry[] = [];
+  for (const rel of files) {
+    if (syncedRelPaths.has(rel)) continue;
+    const content = await fs.readFile(path.join(targetRoot, rel), "utf8");
+    if (hasAutoGeneratedMarker(content)) {
+      out.push({ target: rel });
+    }
+  }
+  return out;
+}
diff --git a/cli/docs-sync/src/report/tracker.ts b/cli/docs-sync/src/report/tracker.ts
new file mode 100644
index 000000000..4f0f20198
--- /dev/null
+++ b/cli/docs-sync/src/report/tracker.ts
@@ -0,0 +1,30 @@
+import type { SyncReport, SyncEntry, SkippedEntry, OrphanEntry, ErrorEntry } from "../types.js";
+
+export class ReportTracker {
+  private changes: SyncEntry[] = [];
+  private skipped: SkippedEntry[] = [];
+  private orphans: OrphanEntry[] = [];
+  private errors: ErrorEntry[] = [];
+
+  recordChange(entry: SyncEntry): void {
+    this.changes.push(entry);
+  }
+  recordSkip(entry: SkippedEntry): void {
+    this.skipped.push(entry);
+  }
+  recordError(entry: ErrorEntry): void {
+    this.errors.push(entry);
+  }
+  setOrphans(orphans: OrphanEntry[]): void {
+    this.orphans = orphans;
+  }
+  build(meta: { vcShellVersion: string; timestamp: string }): SyncReport {
+    return {
+      ...meta,
+      changes: this.changes,
+      skipped: this.skipped,
+      orphans: this.orphans,
+      errors: this.errors,
+    };
+  }
+}
diff --git a/cli/docs-sync/src/screenshot/capture.ts b/cli/docs-sync/src/screenshot/capture.ts
new file mode 100644
index 000000000..0084da394
--- /dev/null
+++ b/cli/docs-sync/src/screenshot/capture.ts
@@ -0,0 +1,53 @@
+import { chromium, type Page } from "@playwright/test";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { SCREENSHOT_DEFAULTS } from "./defaults.js";
+
+export interface CaptureArgs {
+  url?: string; // direct URL (e.g. dev server)
+  story?: string; // Storybook story id
+  selector?: string; // crop to this selector; defaults to <body>
+  theme?: "light" | "dark";
+  viewportWidth?: number;
+  viewportHeight?: number;
+  out: string; // absolute output path
+}
+
+export async function captureScreenshot(args: CaptureArgs): Promise<void> {
+  if (!args.url && !args.story) {
+    throw new Error("either --url or --story is required");
+  }
+  const url = args.url
+    ? args.url
+    : `${SCREENSHOT_DEFAULTS.storybookUrl}/iframe.html?id=${args.story}&viewMode=story&globals=theme:${args.theme ?? SCREENSHOT_DEFAULTS.theme}`;
+
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const context = await browser.newContext({
+      viewport: {
+        width: args.viewportWidth ?? SCREENSHOT_DEFAULTS.viewport.width,
+        height: args.viewportHeight ?? SCREENSHOT_DEFAULTS.viewport.height,
+      },
+      deviceScaleFactor: SCREENSHOT_DEFAULTS.deviceScaleFactor,
+    });
+    const page: Page = await context.newPage();
+    await page.goto(url, { waitUntil: "networkidle" });
+
+    await fs.mkdir(path.dirname(args.out), { recursive: true });
+
+    if (args.selector) {
+      await page.locator(args.selector).screenshot({
+        path: args.out,
+        type: SCREENSHOT_DEFAULTS.format,
+      });
+    } else {
+      await page.screenshot({
+        path: args.out,
+        fullPage: false,
+        type: SCREENSHOT_DEFAULTS.format,
+      });
+    }
+  } finally {
+    await browser.close();
+  }
+}
diff --git a/cli/docs-sync/src/screenshot/defaults.ts b/cli/docs-sync/src/screenshot/defaults.ts
new file mode 100644
index 000000000..bc04c0241
--- /dev/null
+++ b/cli/docs-sync/src/screenshot/defaults.ts
@@ -0,0 +1,8 @@
+export const SCREENSHOT_DEFAULTS = {
+  viewport: { width: 1280, height: 800 },
+  deviceScaleFactor: 2,
+  // PNG keeps Playwright happy across versions; webp post-processing via sharp is a follow-up if smaller files become important.
+  format: "png" as const,
+  theme: "light" as "light" | "dark",
+  storybookUrl: "https://vc-shell-storybook.govirto.com",
+};
diff --git a/cli/docs-sync/src/storybook/index-fetcher.ts b/cli/docs-sync/src/storybook/index-fetcher.ts
new file mode 100644
index 000000000..7e348e2b1
--- /dev/null
+++ b/cli/docs-sync/src/storybook/index-fetcher.ts
@@ -0,0 +1,23 @@
+interface IndexEntry {
+  id: string;
+  type: string;
+}
+
+interface IndexJson {
+  v?: number;
+  entries: Record<string, IndexEntry>;
+}
+
+export async function fetchStorybookIds(storybookUrl: string): Promise<Set<string>> {
+  const url = `${storybookUrl}/index.json`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch Storybook index from ${url}: HTTP ${res.status}`);
+  }
+  const data = (await res.json()) as IndexJson;
+  const ids = new Set<string>();
+  for (const entry of Object.values(data.entries ?? {})) {
+    if (entry.type === "story") ids.add(entry.id);
+  }
+  return ids;
+}
diff --git a/cli/docs-sync/src/transformer/header.ts b/cli/docs-sync/src/transformer/header.ts
new file mode 100644
index 000000000..af27aa7c9
--- /dev/null
+++ b/cli/docs-sync/src/transformer/header.ts
@@ -0,0 +1,14 @@
+export const AUTO_GEN_MARKER = "AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY";
+
+export function prependAutoGeneratedHeader(body: string, sourceRelPath: string): string {
+  const header = [
+    `<!-- ${AUTO_GEN_MARKER} -->`,
+    `<!-- Source: ${sourceRelPath} -->`,
+    `<!-- To update: edit the source file in vc-shell, then run yarn docs:sync -->`,
+  ].join("\n");
+  return `${header}\n\n${body}`;
+}
+
+export function hasAutoGeneratedMarker(content: string): boolean {
+  return content.includes(AUTO_GEN_MARKER);
+}
diff --git a/cli/docs-sync/src/transformer/links.ts b/cli/docs-sync/src/transformer/links.ts
new file mode 100644
index 000000000..eb0b8aa0f
--- /dev/null
+++ b/cli/docs-sync/src/transformer/links.ts
@@ -0,0 +1,27 @@
+import path from "node:path";
+
+export interface LinkRewriteContext {
+  sourcePath: string; // relative path of source *.docs.md inside vc-shell
+  targetPath: string; // relative path of output inside vc-docs
+  resolveTarget(sourcePath: string, href: string): string | null;
+}
+
+// Match [text](href) but NOT image refs (preceded by `!`) and NOT external URLs.
+// Group 1: link text. Group 2: href.
+const LINK_RE = /(?<!!)\[([^\]]+)\]\(([^)]+)\)/g;
+
+export function rewriteCrossDocLinks(body: string, ctx: LinkRewriteContext): string {
+  return body.replace(LINK_RE, (full, text: string, href: string) => {
+    if (/^[a-z]+:/i.test(href) || href.startsWith("//")) return full; // external
+    if (href.startsWith("#")) return full; // anchor
+
+    const resolved = ctx.resolveTarget(ctx.sourcePath, href);
+    if (!resolved) return full;
+
+    // Compute relative path from current target to the resolved target.
+    const fromDir = path.posix.dirname(ctx.targetPath);
+    const rel = path.posix.relative(fromDir, resolved);
+    const normalized = rel.startsWith(".") ? rel : `./${rel}`;
+    return `[${text}](${normalized})`;
+  });
+}
diff --git a/cli/docs-sync/src/transformer/pipeline.ts b/cli/docs-sync/src/transformer/pipeline.ts
new file mode 100644
index 000000000..7c69b4004
--- /dev/null
+++ b/cli/docs-sync/src/transformer/pipeline.ts
@@ -0,0 +1,30 @@
+import { stripInternalBlocks } from "./strip-internal.js";
+import { expandStorybookDirectives } from "./storybook-directive.js";
+import { rewriteCrossDocLinks } from "./links.js";
+import { prependAutoGeneratedHeader } from "./header.js";
+
+export interface TransformContext {
+  sourceRelPath: string; // path shown in AUTO-GENERATED header
+  sourcePath: string; // for resolveTarget lookups
+  targetPath: string; // relative inside vc-docs
+  storybookUrl: string;
+  knownStoryIds: Set<string>;
+  resolveTarget(sourcePath: string, href: string): string | null;
+}
+
+export function runTransformPipeline(body: string, ctx: TransformContext): string {
+  let out = body;
+  out = stripInternalBlocks(out);
+  out = expandStorybookDirectives(out, {
+    storybookUrl: ctx.storybookUrl,
+    knownIds: ctx.knownStoryIds,
+    sourcePath: ctx.sourcePath,
+  });
+  out = rewriteCrossDocLinks(out, {
+    sourcePath: ctx.sourcePath,
+    targetPath: ctx.targetPath,
+    resolveTarget: ctx.resolveTarget,
+  });
+  out = prependAutoGeneratedHeader(out, ctx.sourceRelPath);
+  return out;
+}
diff --git a/cli/docs-sync/src/transformer/storybook-directive.ts b/cli/docs-sync/src/transformer/storybook-directive.ts
new file mode 100644
index 000000000..8f075f416
--- /dev/null
+++ b/cli/docs-sync/src/transformer/storybook-directive.ts
@@ -0,0 +1,54 @@
+const DIRECTIVE_RE = /^::storybook\s+([^\n]+)$/gm;
+const ATTR_RE = /(\w+)="([^"]*)"/g;
+
+export interface DirectiveContext {
+  storybookUrl: string;
+  knownIds: Set<string>;
+  sourcePath: string;
+}
+
+export class UnknownStoryError extends Error {
+  constructor(
+    public readonly id: string,
+    public readonly source: string,
+  ) {
+    super(`[${source}] unknown storybook id: "${id}"`);
+    this.name = "UnknownStoryError";
+  }
+}
+
+export function expandStorybookDirectives(body: string, ctx: DirectiveContext): string {
+  return body.replace(DIRECTIVE_RE, (_match, attrsStr: string) => {
+    const attrs = parseAttrs(attrsStr);
+    const id = attrs.id;
+    if (!id) throw new Error(`[${ctx.sourcePath}] ::storybook missing id attribute`);
+    if (!ctx.knownIds.has(id)) throw new UnknownStoryError(id, ctx.sourcePath);
+
+    const height = parseInt(attrs.height ?? "400", 10);
+    const theme = attrs.theme;
+    const globals = theme && theme !== "auto" ? `&globals=theme:${theme}` : "";
+
+    const iframeSrc = `${ctx.storybookUrl}/iframe.html?id=${id}&viewMode=story${globals}`;
+    const linkHref = `${ctx.storybookUrl}/?path=/story/${id}`;
+    const titleText = attrs.title ?? id;
+
+    return [
+      `<div class="vc-storybook-embed" style="--height: ${height}px">`,
+      `  <iframe`,
+      `    src="${iframeSrc}"`,
+      `    loading="lazy"`,
+      `    title="${titleText}"`,
+      `  ></iframe>`,
+      `  <a href="${linkHref}" target="_blank" rel="noopener">Open in Storybook ↗</a>`,
+      `</div>`,
+    ].join("\n");
+  });
+}
+
+function parseAttrs(s: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const match of s.matchAll(ATTR_RE)) {
+    out[match[1]] = match[2];
+  }
+  return out;
+}
diff --git a/cli/docs-sync/src/transformer/strip-internal.ts b/cli/docs-sync/src/transformer/strip-internal.ts
new file mode 100644
index 000000000..f1088f697
--- /dev/null
+++ b/cli/docs-sync/src/transformer/strip-internal.ts
@@ -0,0 +1,5 @@
+const RE = /<!--\s*internal:start\s*-->([\s\S]*?)<!--\s*internal:end\s*-->/g;
+
+export function stripInternalBlocks(body: string): string {
+  return body.replace(RE, "");
+}
diff --git a/cli/docs-sync/src/types.ts b/cli/docs-sync/src/types.ts
new file mode 100644
index 000000000..b079c7ca6
--- /dev/null
+++ b/cli/docs-sync/src/types.ts
@@ -0,0 +1,58 @@
+export type { Category } from "./config.js";
+import type { Category } from "./config.js";
+
+export interface Frontmatter {
+  title: string;
+  category: Category;
+  group: string;
+  slug?: string;
+  placement?: "index";
+  internal?: boolean;
+}
+
+export interface ParsedDoc {
+  sourcePath: string; // absolute path to source *.docs.md
+  frontmatter: Frontmatter;
+  body: string; // body without frontmatter
+  imageRefs: string[]; // relative image paths found in body
+}
+
+export interface SyncContext {
+  frameworkRoot: string; // absolute path to vc-shell
+  targetRoot: string; // absolute path to vc-docs
+  storybookUrl: string; // e.g. https://vc-shell-storybook.govirto.com
+  storybookIds: Set<string>; // populated from index.json
+  vcShellVersion: string; // read from framework/package.json
+}
+
+export type ChangeKind = "created" | "updated" | "unchanged";
+
+export interface SyncEntry {
+  source: string; // relative path inside vc-shell
+  target: string; // relative path inside vc-docs
+  kind: ChangeKind;
+}
+
+export interface SkippedEntry {
+  source: string;
+  reason: "no-frontmatter" | "internal" | "invalid-frontmatter";
+  detail?: string;
+}
+
+export interface OrphanEntry {
+  target: string; // path in vc-docs that has no source
+}
+
+export interface ErrorEntry {
+  source: string;
+  message: string;
+}
+
+export interface SyncReport {
+  vcShellVersion: string;
+  timestamp: string;
+  changes: SyncEntry[];
+  skipped: SkippedEntry[];
+  orphans: OrphanEntry[];
+  errors: ErrorEntry[];
+}
diff --git a/cli/docs-sync/src/writer/assets.ts b/cli/docs-sync/src/writer/assets.ts
new file mode 100644
index 000000000..6d667306c
--- /dev/null
+++ b/cli/docs-sync/src/writer/assets.ts
@@ -0,0 +1,34 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const ALLOWED_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"]);
+
+export interface CopyAssetsArgs {
+  sourceFile: string; // absolute path to the source *.docs.md
+  targetFile: string; // absolute path to the target *.md (already resolved)
+  imageRefs: string[]; // relative paths from the source body
+}
+
+export interface CopyAssetsResult {
+  copied: string[];
+}
+
+export async function copyImageAssets(args: CopyAssetsArgs): Promise<CopyAssetsResult> {
+  const sourceDir = path.dirname(args.sourceFile);
+  const targetDir = path.dirname(args.targetFile);
+  const copied: string[] = [];
+
+  for (const ref of args.imageRefs) {
+    const ext = path.extname(ref).toLowerCase();
+    if (!ALLOWED_EXT.has(ext)) {
+      throw new Error(`disallowed file type for ${ref}: only png/jpg/jpeg/gif/webp/svg are allowed`);
+    }
+    const srcAbs = path.resolve(sourceDir, ref);
+    const dstAbs = path.resolve(targetDir, ref);
+    await fs.mkdir(path.dirname(dstAbs), { recursive: true });
+    await fs.copyFile(srcAbs, dstAbs);
+    copied.push(ref);
+  }
+
+  return { copied };
+}
diff --git a/cli/docs-sync/src/writer/atomic.ts b/cli/docs-sync/src/writer/atomic.ts
new file mode 100644
index 000000000..cf17dfbac
--- /dev/null
+++ b/cli/docs-sync/src/writer/atomic.ts
@@ -0,0 +1,7 @@
+import writeFileAtomic from "write-file-atomic";
+
+export function writeAtomic(filePath: string, content: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    writeFileAtomic(filePath, content, "utf8", (err) => (err ? reject(err) : resolve()));
+  });
+}
diff --git a/cli/docs-sync/src/writer/pages.ts b/cli/docs-sync/src/writer/pages.ts
new file mode 100644
index 000000000..7aa9c32ce
--- /dev/null
+++ b/cli/docs-sync/src/writer/pages.ts
@@ -0,0 +1,116 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeAtomic } from "./atomic.js";
+import { AUTO_GEN_MARKER } from "../transformer/header.js";
+
+const PAGES_MARKER = `# ${AUTO_GEN_MARKER}\n# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync\n`;
+
+// Top-level group order per category (matches spec).
+const GROUP_ORDER: Record<string, string[]> = {
+  components: ["layout", "form", "data-display", "feedback", "navigation", "media", "misc"],
+  composables: ["blade-navigation", "data", "ui-state", "services", "user", "notifications", "forms", "utilities"],
+  reference: ["cli", "api", "modules", "migration"],
+};
+
+const TOP_LEVEL_TITLES: Record<string, string> = {
+  components: "Components",
+  composables: "Composables",
+  plugins: "Plugins",
+  reference: "Reference",
+};
+
+const NESTED_TITLES: Record<string, string> = {
+  layout: "Layout",
+  form: "Form",
+  "data-display": "Data Display",
+  feedback: "Feedback",
+  navigation: "Navigation",
+  media: "Media",
+  misc: "Misc",
+  "blade-navigation": "Blade Navigation",
+  data: "Data",
+  "ui-state": "UI State",
+  services: "Services",
+  user: "User",
+  notifications: "Notifications",
+  forms: "Forms",
+  utilities: "Utilities",
+  api: "API",
+  directives: "Directives",
+  modules: "Modules",
+  cli: "CLI",
+};
+
+// Folders for which the generator emits .pages.
+const AUTO_PAGES_TOP = new Set(["components", "composables", "plugins"]);
+const AUTO_PAGES_REFERENCE_SUB = new Set(["api", "api/directives", "modules"]);
+// concepts/ and reference root NOT in auto set — manual .pages.
+
+export interface SyncedPage {
+  target: string; // e.g. components/data-display/vc-data-table.md
+  title: string;
+}
+
+export interface WritePagesArgs {
+  synced: SyncedPage[];
+}
+
+export async function writePagesFiles(targetRoot: string, args: WritePagesArgs): Promise<void> {
+  // Bucket by top folder and group.
+  const byTopFolder = new Map<string, Map<string, SyncedPage[]>>();
+  for (const p of args.synced) {
+    const parts = p.target.split("/");
+    const top = parts[0];
+    const group = parts.length > 2 ? parts.slice(1, -1).join("/") : "";
+    if (!byTopFolder.has(top)) byTopFolder.set(top, new Map());
+    const groups = byTopFolder.get(top)!;
+    if (!groups.has(group)) groups.set(group, []);
+    groups.get(group)!.push(p);
+  }
+
+  for (const [top, groups] of byTopFolder) {
+    const isAutoTop = AUTO_PAGES_TOP.has(top);
+
+    // Emit top-level .pages for components / composables / plugins.
+    if (isAutoTop) {
+      const hasOnlyRoot = groups.size === 1 && groups.has("");
+      let navContent: string;
+      if (hasOnlyRoot) {
+        // Flat top folder (e.g., plugins/) — emit explicit titles, alphabetical
+        const allPages = groups.get("")!;
+        const sorted = [...allPages].sort((a, b) => a.title.localeCompare(b.title));
+        navContent = sorted.map((p) => `  - ${p.title}: ${path.basename(p.target)}`).join("\n");
+      } else {
+        // Existing logic: list sub-groups in declared order
+        const order = (GROUP_ORDER[top] ?? []).filter((g) => groups.has(g));
+        navContent = order.map((g) => `  - ${g}`).join("\n");
+      }
+      const yaml = PAGES_MARKER + `title: ${TOP_LEVEL_TITLES[top]}\n` + `nav:\n` + navContent + "\n";
+      const filePath = path.join(targetRoot, top, ".pages");
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await writeAtomic(filePath, yaml);
+    }
+
+    // Emit per-group .pages.
+    for (const [group, pages] of groups) {
+      if (!group) continue; // single-file in top folder (e.g. concepts/services.md) — no group .pages
+      const isReferenceSub = top === "reference" && AUTO_PAGES_REFERENCE_SUB.has(group);
+      if (!isAutoTop && !isReferenceSub) continue; // skip mixed/manual folders
+
+      const indexPage = pages.find((p) => path.basename(p.target) === "index.md");
+      const otherPages = pages.filter((p) => path.basename(p.target) !== "index.md");
+      const sorted = [...otherPages].sort((a, b) => a.title.localeCompare(b.title));
+      const groupTitle = NESTED_TITLES[group.split("/").at(-1)!] ?? group;
+
+      const navLines: string[] = [];
+      if (indexPage) navLines.push("  - Overview: index.md");
+      navLines.push(...sorted.map((p) => `  - ${p.title}: ${path.basename(p.target)}`));
+
+      const yaml = PAGES_MARKER + `title: ${groupTitle}\n` + `nav:\n` + navLines.join("\n") + "\n";
+
+      const filePath = path.join(targetRoot, top, group, ".pages");
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+      await writeAtomic(filePath, yaml);
+    }
+  }
+}
diff --git a/cli/docs-sync/src/writer/writer.ts b/cli/docs-sync/src/writer/writer.ts
new file mode 100644
index 000000000..16895e7c7
--- /dev/null
+++ b/cli/docs-sync/src/writer/writer.ts
@@ -0,0 +1,33 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeAtomic } from "./atomic.js";
+import type { Frontmatter, ChangeKind } from "../types.js";
+
+export function computeTargetPath(fm: Frontmatter, sourceFilename: string): string {
+  const slug = fm.slug ?? sourceFilename.replace(/\.docs\.md$/, "");
+  const groupPart = fm.group === "root" ? "" : fm.group;
+  const filename = fm.placement === "index" ? "index.md" : `${slug}.md`;
+  return [fm.category, groupPart, filename].filter(Boolean).join("/");
+}
+
+export interface WriteResult {
+  kind: ChangeKind;
+}
+
+export async function writeMarkdown(targetRoot: string, relPath: string, content: string): Promise<WriteResult> {
+  const abs = path.join(targetRoot, relPath);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+
+  let existing: string | null = null;
+  try {
+    existing = await fs.readFile(abs, "utf8");
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+  }
+
+  if (existing === content) {
+    return { kind: "unchanged" };
+  }
+  await writeAtomic(abs, content);
+  return { kind: existing == null ? "created" : "updated" };
+}
diff --git a/cli/docs-sync/sync-report.md b/cli/docs-sync/sync-report.md
new file mode 100644
index 000000000..7fecf8f6c
--- /dev/null
+++ b/cli/docs-sync/sync-report.md
@@ -0,0 +1,176 @@
+# vc-docs sync report — vc-shell@v2.0.3 — 2026-05-08T12:56:54.763Z
+
+## Summary
+
+- Created: 0
+- Updated: 1
+- Unchanged: 126
+- Skipped (no frontmatter): 0
+- Skipped (internal): 24
+- Skipped (invalid frontmatter): 0
+- Orphaned: 0
+- Errors: 0
+
+## Updated
+
+- plugins/permissions.md (← core/plugins/permissions/permissions.docs.md)
+
+## Unchanged
+
+- reference/api/injection-keys.md (← injection-keys.docs.md)
+- reference/api/platform-client.md (← core/api/platform.docs.md)
+- composables/blade-navigation/blade-nav-composables.md (← core/blade-navigation/blade-nav-composables.docs.md)
+- plugins/notifications.md (← core/notifications/notifications.docs.md)
+- composables/services/index.md (← core/services/services.docs.md)
+- reference/api/types-core.md (← core/types/types.docs.md)
+- reference/api/shared-utilities.md (← core/utilities/shared-utilities.docs.md)
+- reference/api/utilities-overview.md (← core/utilities/utilities.docs.md)
+- reference/modules/assets.md (← modules/assets/assets-details.docs.md)
+- reference/modules/assets-manager.md (← modules/assets-manager/assets-manager.docs.md)
+- reference/api/types-ui.md (← ui/types/ui-types.docs.md)
+- composables/ui-state/ui-composables-overview.md (← ui/composables/ui-composables.docs.md)
+- composables/data/useDataTablePagination.md (← ui/composables/useDataTablePagination.docs.md)
+- composables/data/useDataTableSort.md (← ui/composables/useDataTableSort.docs.md)
+- composables/data/useTableSelection.md (← ui/composables/useTableSelection.docs.md)
+- composables/data/useTableSort.md (← ui/composables/useTableSort.docs.md)
+- composables/blade-navigation/useBladeContext.md (← core/composables/bladeContext/index.docs.md)
+- composables/data/useApiClient.md (← core/composables/useApiClient/useApiClient.docs.md)
+- composables/services/useAppBarMobileButtons.md (← core/composables/useAppBarMobileButtons/useAppBarMobileButtons.docs.md)
+- composables/services/useAppBarWidget.md (← core/composables/useAppBarWidget/useAppBarWidget.docs.md)
+- composables/utilities/useAppInsights.md (← core/composables/useAppInsights/useAppInsights.docs.md)
+- composables/data/useAssets.md (← core/composables/useAssets/useAssets.docs.md)
+- composables/utilities/useAsync.md (← core/composables/useAsync/useAsync.docs.md)
+- composables/data/useAssetsManager.md (← core/composables/useAssetsManager/useAssetsManager.docs.md)
+- composables/utilities/useBeforeUnload.md (← core/composables/useBeforeUnload/useBeforeUnload.docs.md)
+- composables/blade-navigation/useBlade.md (← core/composables/useBlade/useBlade.docs.md)
+- composables/forms/useBladeForm.md (← core/composables/useBladeForm/useBladeForm.docs.md)
+- composables/blade-navigation/useBladeRegistry.md (← core/composables/useBladeRegistry/useBladeRegistry.docs.md)
+- composables/blade-navigation/useBladeWidgets.md (← core/composables/useBladeWidgets/index.docs.md)
+- composables/ui-state/useBreadcrumbs.md (← core/composables/useBreadcrumbs/useBreadcrumbs.docs.md)
+- composables/ui-state/useConnectionStatus.md (← core/composables/useConnectionStatus/useConnectionStatus.docs.md)
+- composables/services/useDashboard.md (← core/composables/useDashboard/useDashboard.docs.md)
+- composables/forms/useDynamicProperties.md (← core/composables/useDynamicProperties/useDynamicProperties.docs.md)
+- composables/utilities/useErrorHandler.md (← core/composables/useErrorHandler/useErrorHandler.docs.md)
+- composables/utilities/useFunctions.md (← core/composables/useFunctions/useFunctions.docs.md)
+- composables/ui-state/useKeyboardNavigation.md (← core/composables/useKeyboardNavigation/useKeyboardNavigation.docs.md)
+- composables/user/useLanguages.md (← core/composables/useLanguages/useLanguages.docs.md)
+- composables/services/useMenuService.md (← core/composables/useMenuService/useMenuService.docs.md)
+- composables/ui-state/useLoading.md (← core/composables/useLoading/useLoading.docs.md)
+- composables/ui-state/useMenuExpanded.md (← core/composables/useMenuExpanded/index.docs.md)
+- composables/forms/useModificationTracker.md (← core/composables/useModificationTracker/useModificationTracker.docs.md)
+- composables/notifications/useNotifications.md (← core/composables/useNotifications/useNotifications.docs.md)
+- composables/user/usePlatformLocaleSync.md (← core/composables/usePlatformLocaleSync/usePlatformLocaleSync.docs.md)
+- composables/user/usePermissions.md (← core/composables/usePermissions/usePermissions.docs.md)
+- composables/notifications/usePopup.md (← core/composables/usePopup/usePopup.docs.md)
+- composables/services/useSettings.md (← core/composables/useSettings/useSettings.docs.md)
+- composables/services/useSettingsMenu.md (← core/composables/useSettingsMenu/useSettingsMenu.docs.md)
+- composables/ui-state/useSidebarState.md (← core/composables/useSidebarState/useSidebarState.docs.md)
+- composables/ui-state/useResponsive.md (← core/composables/useResponsive/useResponsive.docs.md)
+- composables/ui-state/useSlowNetworkDetection.md (← core/composables/useSlowNetworkDetection/useSlowNetworkDetection.docs.md)
+- composables/services/useToolbar.md (← core/composables/useToolbar/useToolbar.docs.md)
+- composables/ui-state/useTheme.md (← core/composables/useTheme/useTheme.docs.md)
+- composables/user/useUser.md (← core/composables/useUser/useUser.docs.md)
+- composables/utilities/useWebVitals.md (← core/composables/useWebVitals/useWebVitals.docs.md)
+- composables/services/useWidgets.md (← core/composables/useWidgets/useWidgets.docs.md)
+- reference/api/directives/v-autofocus.md (← core/directives/autofocus/autofocus.docs.md)
+- reference/api/directives/v-loading.md (← core/directives/loading/loading.docs.md)
+- plugins/ai-agent.md (← core/plugins/ai-agent/ai-agent.docs.md)
+- plugins/extension-points.md (← core/plugins/extension-points/extension-points.docs.md)
+- plugins/global-error-handler.md (← core/plugins/global-error-handler/global-error-handler.docs.md)
+- plugins/i18n.md (← core/plugins/i18n/i18n.docs.md)
+- plugins/modularity.md (← core/plugins/modularity/modularity.docs.md)
+- plugins/signalr.md (← core/plugins/signalR/signalR.docs.md)
+- plugins/validation.md (← core/plugins/validation/validation.docs.md)
+- reference/api/date-utilities.md (← core/utilities/date/date-utilities.docs.md)
+- reference/api/thumbnail.md (← core/utilities/thumbnail/thumbnail.docs.md)
+- components/form/multilanguage-selector.md (← ui/components/molecules/multilanguage-selector/multilanguage-selector.docs.md)
+- components/navigation/vc-breadcrumbs.md (← ui/components/molecules/vc-breadcrumbs/vc-breadcrumbs.docs.md)
+- components/form/vc-checkbox-group.md (← ui/components/molecules/vc-checkbox-group/vc-checkbox-group.docs.md)
+- components/form/vc-checkbox.md (← ui/components/molecules/vc-checkbox/vc-checkbox.docs.md)
+- components/data-display/vc-accordion.md (← ui/components/molecules/vc-accordion/vc-accordion.docs.md)
+- components/form/vc-date-picker.md (← ui/components/molecules/vc-date-picker/vc-date-picker.docs.md)
+- components/navigation/vc-dropdown.md (← ui/components/molecules/vc-dropdown/vc-dropdown.docs.md)
+- components/form/vc-color-input.md (← ui/components/molecules/vc-color-input/vc-color-input.docs.md)
+- components/navigation/vc-dropdown-panel.md (← ui/components/molecules/vc-dropdown-panel/vc-dropdown-panel.docs.md)
+- components/form/vc-editor.md (← ui/components/molecules/vc-editor/vc-editor.docs.md)
+- components/form/vc-field.md (← ui/components/molecules/vc-field/vc-field.docs.md)
+- components/form/vc-form.md (← ui/components/molecules/vc-form/vc-form.docs.md)
+- components/data-display/vc-image-tile.md (← ui/components/molecules/vc-image-tile/vc-image-tile.docs.md)
+- components/form/vc-file-upload.md (← ui/components/molecules/vc-file-upload/vc-file-upload.docs.md)
+- components/form/vc-input.md (← ui/components/molecules/vc-input/vc-input.docs.md)
+- components/form/vc-input-currency.md (← ui/components/molecules/vc-input-currency/vc-input-currency.docs.md)
+- components/form/vc-input-dropdown.md (← ui/components/molecules/vc-input-dropdown/vc-input-dropdown.docs.md)
+- components/form/vc-multivalue.md (← ui/components/molecules/vc-multivalue/vc-multivalue.docs.md)
+- components/form/vc-input-group.md (← ui/components/molecules/vc-input-group/vc-input-group.docs.md)
+- components/navigation/vc-menu.md (← ui/components/molecules/vc-menu/vc-menu.docs.md)
+- components/navigation/vc-pagination.md (← ui/components/molecules/vc-pagination/vc-pagination.docs.md)
+- components/form/vc-rating.md (← ui/components/molecules/vc-rating/vc-rating.docs.md)
+- components/form/vc-radio-group.md (← ui/components/molecules/vc-radio-group/vc-radio-group.docs.md)
+- components/form/vc-radio-button.md (← ui/components/molecules/vc-radio-button/vc-radio-button.docs.md)
+- components/form/vc-select.md (← ui/components/molecules/vc-select/vc-select.docs.md)
+- components/form/vc-switch.md (← ui/components/molecules/vc-switch/vc-switch.docs.md)
+- components/form/vc-textarea.md (← ui/components/molecules/vc-textarea/vc-textarea.docs.md)
+- components/form/vc-slider.md (← ui/components/molecules/vc-slider/vc-slider.docs.md)
+- components/feedback/vc-toast.md (← ui/components/molecules/vc-toast/vc-toast.docs.md)
+- components/layout/vc-auth-layout.md (← ui/components/organisms/vc-auth-layout/vc-auth-layout.docs.md)
+- components/layout/vc-app.md (← ui/components/organisms/vc-app/vc-app.docs.md)
+- components/layout/vc-blade.md (← ui/components/organisms/vc-blade/vc-blade.docs.md)
+- components/data-display/vc-data-table.md (← ui/components/organisms/vc-data-table/vc-data-table.docs.md)
+- components/form/vc-dynamic-property.md (← ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md)
+- components/media/vc-image-upload.md (← ui/components/organisms/vc-image-upload/vc-image-upload.docs.md)
+- components/data-display/vc-gallery.md (← ui/components/organisms/vc-gallery/vc-gallery.docs.md)
+- components/feedback/vc-popup.md (← ui/components/organisms/vc-popup/vc-popup.docs.md)
+- components/layout/vc-sidebar.md (← ui/components/organisms/vc-sidebar/vc-sidebar.docs.md)
+- components/misc/vc-badge.md (← ui/components/atoms/vc-badge/vc-badge.docs.md)
+- components/layout/vc-card.md (← ui/components/atoms/vc-card/vc-card.docs.md)
+- components/misc/vc-button.md (← ui/components/atoms/vc-button/vc-button.docs.md)
+- components/feedback/vc-banner.md (← ui/components/atoms/vc-banner/vc-banner.docs.md)
+- components/layout/vc-col.md (← ui/components/atoms/vc-col/vc-col.docs.md)
+- components/layout/vc-container.md (← ui/components/atoms/vc-container/vc-container.docs.md)
+- components/feedback/vc-hint.md (← ui/components/atoms/vc-hint/vc-hint.docs.md)
+- components/media/vc-image.md (← ui/components/atoms/vc-image/vc-image.docs.md)
+- components/misc/vc-icon.md (← ui/components/atoms/vc-icon/vc-icon.docs.md)
+- components/navigation/vc-link.md (← ui/components/atoms/vc-link/vc-link.docs.md)
+- components/feedback/vc-loading.md (← ui/components/atoms/vc-loading/vc-loading.docs.md)
+- components/misc/vc-label.md (← ui/components/atoms/vc-label/vc-label.docs.md)
+- components/feedback/vc-progress.md (← ui/components/atoms/vc-progress/vc-progress.docs.md)
+- components/layout/vc-row.md (← ui/components/atoms/vc-row/vc-row.docs.md)
+- components/layout/vc-scrollable-container.md (← ui/components/atoms/vc-scrollable-container/vc-scrollable-container.docs.md)
+- components/feedback/vc-skeleton.md (← ui/components/atoms/vc-skeleton/vc-skeleton.docs.md)
+- components/feedback/vc-status-icon.md (← ui/components/atoms/vc-status-icon/vc-status-icon.docs.md)
+- components/feedback/vc-tooltip.md (← ui/components/atoms/vc-tooltip/vc-tooltip.docs.md)
+- components/feedback/vc-status.md (← ui/components/atoms/vc-status/vc-status.docs.md)
+- components/media/vc-video.md (← ui/components/atoms/vc-video/vc-video.docs.md)
+- components/misc/vc-widget.md (← ui/components/atoms/vc-widget/vc-widget.docs.md)
+- composables/data/table-composables.md (← ui/components/organisms/vc-data-table/composables/table-composables.docs.md)
+
+## Skipped
+
+- core/composables/useUserManagement/useUserManagement.docs.md — reason: internal
+- shell/auth/ChangePasswordPage/change-password-page.docs.md — reason: internal
+- shell/auth/ForgotPasswordPage/forgot-password-page.docs.md — reason: internal
+- shell/auth/InvitePage/invite-page.docs.md — reason: internal
+- shell/auth/LoginPage/login-page.docs.md — reason: internal
+- shell/auth/ResetPasswordPage/reset-password-page.docs.md — reason: internal
+- shell/auth/sign-in/sign-in.docs.md — reason: internal
+- shell/dashboard/dashboard-charts/dashboard-charts.docs.md — reason: internal
+- shell/dashboard/dashboard-widget-card/dashboard-widget-card.docs.md — reason: internal
+- shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md — reason: internal
+- shell/dashboard/draggable-dashboard/draggable-dashboard.docs.md — reason: internal
+- shell/components/error-interceptor/error-interceptor.docs.md — reason: internal
+- shell/components/language-selector/language-selector.docs.md — reason: internal
+- shell/components/change-password-button/change-password-button.docs.md — reason: internal
+- shell/components/change-password/change-password.docs.md — reason: internal
+- shell/components/logout-button/logout-button.docs.md — reason: internal
+- shell/components/notification-template/notification-template.docs.md — reason: internal
+- shell/components/notification-dropdown/notification-dropdown.docs.md — reason: internal
+- shell/components/settings-menu-item/settings-menu-item.docs.md — reason: internal
+- shell/components/sidebar/sidebar.docs.md — reason: internal
+- shell/components/settings-menu/settings-menu.docs.md — reason: internal
+- shell/components/theme-selector/theme-selector.docs.md — reason: internal
+- shell/components/user-dropdown-button/user-dropdown-button.docs.md — reason: internal
+- shell/\_internal/popup/common/popup-common.docs.md — reason: internal
+
+## Errors
+
+(none)
diff --git a/cli/docs-sync/tests/assets.test.ts b/cli/docs-sync/tests/assets.test.ts
new file mode 100644
index 000000000..80c355404
--- /dev/null
+++ b/cli/docs-sync/tests/assets.test.ts
@@ -0,0 +1,43 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { copyImageAssets } from "../src/writer/assets.js";
+
+describe("copyImageAssets", () => {
+  let tmpSrc: string;
+  let tmpDst: string;
+  beforeEach(async () => {
+    tmpSrc = await fs.mkdtemp(path.join(os.tmpdir(), "docs-sync-src-"));
+    tmpDst = await fs.mkdtemp(path.join(os.tmpdir(), "docs-sync-dst-"));
+    await fs.mkdir(path.join(tmpSrc, "images"), { recursive: true });
+    await fs.writeFile(path.join(tmpSrc, "images/a.png"), "PNGDATA");
+    await fs.writeFile(path.join(tmpSrc, "images/b.png"), "PNGDATA-B");
+  });
+  afterEach(async () => {
+    await fs.rm(tmpSrc, { recursive: true, force: true });
+    await fs.rm(tmpDst, { recursive: true, force: true });
+  });
+
+  it("copies referenced images to parallel target path", async () => {
+    const result = await copyImageAssets({
+      sourceFile: path.join(tmpSrc, "doc.docs.md"),
+      targetFile: path.join(tmpDst, "components/misc/doc.md"),
+      imageRefs: ["./images/a.png", "./images/b.png"],
+    });
+    expect(result.copied).toEqual(["./images/a.png", "./images/b.png"]);
+    const a = await fs.readFile(path.join(tmpDst, "components/misc/images/a.png"), "utf8");
+    expect(a).toBe("PNGDATA");
+  });
+
+  it("rejects forbidden file types", async () => {
+    await fs.writeFile(path.join(tmpSrc, "images/c.mp4"), "MP4");
+    await expect(
+      copyImageAssets({
+        sourceFile: path.join(tmpSrc, "doc.docs.md"),
+        targetFile: path.join(tmpDst, "components/misc/doc.md"),
+        imageRefs: ["./images/c.mp4"],
+      }),
+    ).rejects.toThrow(/disallowed file type/);
+  });
+});
diff --git a/cli/docs-sync/tests/fixtures/composable-with-internal.docs.md b/cli/docs-sync/tests/fixtures/composable-with-internal.docs.md
new file mode 100644
index 000000000..358cb66cb
--- /dev/null
+++ b/cli/docs-sync/tests/fixtures/composable-with-internal.docs.md
@@ -0,0 +1,21 @@
+---
+title: useBlade
+category: composables
+group: blade-navigation
+---
+
+# useBlade
+
+Public description here.
+
+<!-- internal:start -->
+
+## Implementation notes
+
+This part is for contributors only.
+
+<!-- internal:end -->
+
+## See Also
+
+Public again.
diff --git a/cli/docs-sync/tests/fixtures/integration/source/_internal/secret.docs.md b/cli/docs-sync/tests/fixtures/integration/source/_internal/secret.docs.md
new file mode 100644
index 000000000..1bd05f206
--- /dev/null
+++ b/cli/docs-sync/tests/fixtures/integration/source/_internal/secret.docs.md
@@ -0,0 +1,8 @@
+---
+title: Internal
+category: components
+group: misc
+internal: true
+---
+
+# Internal stuff
diff --git a/cli/docs-sync/tests/fixtures/integration/source/components/atoms/vc-foo/images/screen.png b/cli/docs-sync/tests/fixtures/integration/source/components/atoms/vc-foo/images/screen.png
new file mode 100644
index 000000000..0cadfa2b3
--- /dev/null
+++ b/cli/docs-sync/tests/fixtures/integration/source/components/atoms/vc-foo/images/screen.png
@@ -0,0 +1 @@
+PNGDATA
\ No newline at end of file
diff --git a/cli/docs-sync/tests/fixtures/integration/source/components/atoms/vc-foo/vc-foo.docs.md b/cli/docs-sync/tests/fixtures/integration/source/components/atoms/vc-foo/vc-foo.docs.md
new file mode 100644
index 000000000..257ba5008
--- /dev/null
+++ b/cli/docs-sync/tests/fixtures/integration/source/components/atoms/vc-foo/vc-foo.docs.md
@@ -0,0 +1,11 @@
+---
+title: VcFoo
+category: components
+group: misc
+---
+
+# VcFoo
+
+A foo component.
+
+![Screen](./images/screen.png)
diff --git a/cli/docs-sync/tests/fixtures/integration/source/package.json b/cli/docs-sync/tests/fixtures/integration/source/package.json
new file mode 100644
index 000000000..7688db3b2
--- /dev/null
+++ b/cli/docs-sync/tests/fixtures/integration/source/package.json
@@ -0,0 +1,3 @@
+{
+  "version": "0.0.0-test"
+}
diff --git a/cli/docs-sync/tests/fixtures/simple-component.docs.md b/cli/docs-sync/tests/fixtures/simple-component.docs.md
new file mode 100644
index 000000000..6cc221839
--- /dev/null
+++ b/cli/docs-sync/tests/fixtures/simple-component.docs.md
@@ -0,0 +1,14 @@
+---
+title: VcButton
+category: components
+group: misc
+---
+
+# VcButton
+
+A simple button.
+
+![Default state](./images/default.png)
+![Hover state](./images/hover.png)
+
+::storybook id="atoms-vc-button--default"
diff --git a/cli/docs-sync/tests/frontmatter.test.ts b/cli/docs-sync/tests/frontmatter.test.ts
new file mode 100644
index 000000000..99db84229
--- /dev/null
+++ b/cli/docs-sync/tests/frontmatter.test.ts
@@ -0,0 +1,83 @@
+import { describe, it, expect } from "vitest";
+import { validateFrontmatter } from "../src/parser/frontmatter.js";
+
+describe("validateFrontmatter", () => {
+  it("accepts a valid component frontmatter", () => {
+    const result = validateFrontmatter({
+      title: "VcDataTable",
+      category: "components",
+      group: "data-display",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts optional slug and internal", () => {
+    const result = validateFrontmatter({
+      title: "Foo",
+      category: "components",
+      group: "misc",
+      slug: "vc-foo",
+      internal: false,
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects missing title", () => {
+    const result = validateFrontmatter({
+      category: "components",
+      group: "misc",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects unknown category", () => {
+    const result = validateFrontmatter({
+      title: "X",
+      category: "frobnitz",
+      group: "misc",
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects group not allowed for the category", () => {
+    const result = validateFrontmatter({
+      title: "X",
+      category: "components",
+      group: "blade-navigation", // valid for composables, not components
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts category: plugins with group: root", () => {
+    const result = validateFrontmatter({
+      title: "AI Agent",
+      category: "plugins",
+      group: "root",
+      slug: "ai-agent",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts placement: index when group is named", () => {
+    const result = validateFrontmatter({
+      title: "Services",
+      category: "composables",
+      group: "services",
+      placement: "index",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects placement: index when group is root", () => {
+    const result = validateFrontmatter({
+      title: "Foo",
+      category: "concepts",
+      group: "root",
+      placement: "index",
+    });
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      expect(result.error).toContain("placement");
+    }
+  });
+});
diff --git a/cli/docs-sync/tests/integration-sync.test.ts b/cli/docs-sync/tests/integration-sync.test.ts
new file mode 100644
index 000000000..9cf74136e
--- /dev/null
+++ b/cli/docs-sync/tests/integration-sync.test.ts
@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FIXTURE_SRC = path.join(__dirname, "fixtures/integration/source");
+
+describe("end-to-end sync (integration)", () => {
+  let target: string;
+
+  beforeEach(async () => {
+    target = await fs.mkdtemp(path.join(os.tmpdir(), "docs-sync-int-"));
+    // Mock fetch for Storybook index.json.
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({ entries: {} }),
+    } as Response);
+  });
+
+  afterEach(async () => {
+    await fs.rm(target, { recursive: true, force: true });
+    vi.restoreAllMocks();
+    // Restore the fixture file to its committed (Prettier-formatted) state so
+    // the working tree stays clean after each test run.
+    await fs.writeFile(
+      path.join(FIXTURE_SRC, "package.json"),
+      JSON.stringify({ version: "0.0.0-test" }, null, 2) + "\n",
+      "utf8",
+    );
+  });
+
+  it("syncs a fixture component, copies images, skips internal files", async () => {
+    // Stub framework/package.json under fixture (runSync reads version from it).
+    await fs.writeFile(path.join(FIXTURE_SRC, "package.json"), JSON.stringify({ version: "0.0.0-test" }), "utf8");
+    const { runSync } = await import("../src/commands/sync.js");
+    const res = await runSync({
+      target,
+      frameworkDir: FIXTURE_SRC,
+      reportPath: path.join(target, "report.md"),
+    });
+    expect(res.exitCode).toBe(0);
+
+    const targetSection = path.join(target, "platform/developer-guide/docs/custom-apps-development/vc-shell");
+    const out = await fs.readFile(path.join(targetSection, "components/misc/vc-foo.md"), "utf8");
+    expect(out).toContain("AUTO-GENERATED FROM vc-shell");
+    expect(out).toContain("# VcFoo");
+
+    // Image was copied.
+    await fs.access(path.join(targetSection, "components/misc/images/screen.png"));
+
+    // Internal file skipped.
+    let exists = true;
+    try {
+      await fs.access(path.join(targetSection, "components/misc/secret.md"));
+    } catch {
+      exists = false;
+    }
+    expect(exists).toBe(false);
+
+    // Report exists and mentions the synced file.
+    const report = await fs.readFile(path.join(target, "report.md"), "utf8");
+    expect(report).toContain("components/misc/vc-foo.md");
+  });
+});
diff --git a/cli/docs-sync/tests/lint.test.ts b/cli/docs-sync/tests/lint.test.ts
new file mode 100644
index 000000000..719211b55
--- /dev/null
+++ b/cli/docs-sync/tests/lint.test.ts
@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import { runLint } from "../src/lint/runner.js";
+
+describe("runLint", () => {
+  it("returns errors for files without frontmatter", async () => {
+    const result = await runLint({
+      sources: [{ absPath: "/abs/x.docs.md", relPath: "framework/x.docs.md", raw: "# no frontmatter" }],
+      knownStoryIds: new Set(),
+    });
+    expect(result.errors.length).toBeGreaterThan(0);
+    expect(result.errors[0].rule).toBe("frontmatter-required");
+  });
+
+  it("passes for valid files", async () => {
+    const valid = `---\ntitle: Foo\ncategory: components\ngroup: misc\n---\n\n# Foo\n`;
+    const result = await runLint({
+      sources: [{ absPath: "/abs/x.docs.md", relPath: "framework/x.docs.md", raw: valid }],
+      knownStoryIds: new Set(),
+    });
+    expect(result.errors).toEqual([]);
+  });
+
+  it("flags unknown ::storybook id", async () => {
+    const raw = `---\ntitle: X\ncategory: components\ngroup: misc\n---\n\n::storybook id="bogus"\n`;
+    const result = await runLint({
+      sources: [{ absPath: "/x.docs.md", relPath: "x.docs.md", raw }],
+      knownStoryIds: new Set(["real-id"]),
+    });
+    expect(result.errors.find((e) => e.rule === "storybook-id-valid")).toBeTruthy();
+  });
+});
diff --git a/cli/docs-sync/tests/orphans.test.ts b/cli/docs-sync/tests/orphans.test.ts
new file mode 100644
index 000000000..b02e641e8
--- /dev/null
+++ b/cli/docs-sync/tests/orphans.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { findOrphans } from "../src/report/orphans.js";
+
+describe("findOrphans", () => {
+  let tmp: string;
+  beforeEach(async () => {
+    tmp = await fs.mkdtemp(path.join(os.tmpdir(), "docs-sync-orphans-"));
+  });
+  afterEach(async () => {
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("flags files with AUTO-GENERATED marker that are not in synced set", async () => {
+    await fs.mkdir(path.join(tmp, "components/misc"), { recursive: true });
+    await fs.writeFile(
+      path.join(tmp, "components/misc/old-button.md"),
+      "<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY -->\n# Old",
+    );
+    await fs.writeFile(
+      path.join(tmp, "components/misc/vc-button.md"),
+      "<!-- AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY -->\n# New",
+    );
+    const synced = new Set(["components/misc/vc-button.md"]);
+    const orphans = await findOrphans(tmp, synced);
+    expect(orphans.map((o) => o.target)).toEqual(["components/misc/old-button.md"]);
+  });
+
+  it("ignores manual files (no marker)", async () => {
+    await fs.mkdir(path.join(tmp, "guides"), { recursive: true });
+    await fs.writeFile(path.join(tmp, "guides/intro.md"), "# manual page");
+    const orphans = await findOrphans(tmp, new Set());
+    expect(orphans).toEqual([]);
+  });
+});
diff --git a/cli/docs-sync/tests/pages.test.ts b/cli/docs-sync/tests/pages.test.ts
new file mode 100644
index 000000000..ca1127532
--- /dev/null
+++ b/cli/docs-sync/tests/pages.test.ts
@@ -0,0 +1,90 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { writePagesFiles } from "../src/writer/pages.js";
+
+describe("writePagesFiles", () => {
+  let tmp: string;
+  beforeEach(async () => {
+    tmp = await fs.mkdtemp(path.join(os.tmpdir(), "docs-sync-pages-"));
+  });
+  afterEach(async () => {
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("emits a top-level components/.pages with subgroups in declared order", async () => {
+    await writePagesFiles(tmp, {
+      synced: [
+        { target: "components/data-display/vc-data-table.md", title: "VcDataTable" },
+        { target: "components/misc/vc-button.md", title: "VcButton" },
+      ],
+    });
+    const top = await fs.readFile(path.join(tmp, "components/.pages"), "utf8");
+    expect(top).toContain("AUTO-GENERATED FROM vc-shell");
+    expect(top).toContain("title: Components");
+    expect(top.indexOf("data-display")).toBeLessThan(top.indexOf("misc"));
+  });
+
+  it("emits a per-group .pages alphabetically by title", async () => {
+    await writePagesFiles(tmp, {
+      synced: [
+        { target: "components/form/vc-input.md", title: "VcInput" },
+        { target: "components/form/vc-checkbox.md", title: "VcCheckbox" },
+        { target: "components/form/vc-select.md", title: "VcSelect" },
+      ],
+    });
+    const group = await fs.readFile(path.join(tmp, "components/form/.pages"), "utf8");
+    const lines = group.split("\n").filter((l) => l.startsWith("  - "));
+    expect(lines).toEqual(["  - VcCheckbox: vc-checkbox.md", "  - VcInput: vc-input.md", "  - VcSelect: vc-select.md"]);
+  });
+
+  it("does NOT emit .pages for concepts (mixed-folder)", async () => {
+    await writePagesFiles(tmp, {
+      synced: [{ target: "concepts/services.md", title: "Services" }],
+    });
+    let exists = true;
+    try {
+      await fs.access(path.join(tmp, "concepts/.pages"));
+    } catch {
+      exists = false;
+    }
+    expect(exists).toBe(false);
+  });
+
+  it("emits a flat plugins/.pages with explicit titles, alphabetical", async () => {
+    await writePagesFiles(tmp, {
+      synced: [
+        { target: "plugins/signalr.md", title: "SignalR" },
+        { target: "plugins/ai-agent.md", title: "AI Agent" },
+        { target: "plugins/i18n.md", title: "Internationalization" },
+      ],
+    });
+    const pagesFile = await fs.readFile(path.join(tmp, "plugins/.pages"), "utf8");
+    expect(pagesFile).toContain("AUTO-GENERATED FROM vc-shell");
+    expect(pagesFile).toContain("title: Plugins");
+    const lines = pagesFile.split("\n").filter((l) => l.startsWith("  - "));
+    expect(lines).toEqual([
+      "  - AI Agent: ai-agent.md",
+      "  - Internationalization: i18n.md",
+      "  - SignalR: signalr.md",
+    ]);
+  });
+
+  it("emits Overview: index.md first when a group has an index page", async () => {
+    await writePagesFiles(tmp, {
+      synced: [
+        { target: "composables/services/useDashboard.md", title: "useDashboard" },
+        { target: "composables/services/index.md", title: "Services" },
+        { target: "composables/services/useToolbar.md", title: "useToolbar" },
+      ],
+    });
+    const pagesFile = await fs.readFile(path.join(tmp, "composables/services/.pages"), "utf8");
+    const lines = pagesFile.split("\n").filter((l) => l.startsWith("  - "));
+    expect(lines).toEqual([
+      "  - Overview: index.md",
+      "  - useDashboard: useDashboard.md",
+      "  - useToolbar: useToolbar.md",
+    ]);
+  });
+});
diff --git a/cli/docs-sync/tests/parser.test.ts b/cli/docs-sync/tests/parser.test.ts
new file mode 100644
index 000000000..70ffbb236
--- /dev/null
+++ b/cli/docs-sync/tests/parser.test.ts
@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseDocFile } from "../src/parser/parser.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fixtures = path.join(__dirname, "fixtures");
+
+describe("parseDocFile", () => {
+  it("parses a simple component doc", async () => {
+    const result = await parseDocFile(path.join(fixtures, "simple-component.docs.md"));
+    expect(result.frontmatter.title).toBe("VcButton");
+    expect(result.frontmatter.category).toBe("components");
+    expect(result.frontmatter.group).toBe("misc");
+    expect(result.body).toContain("# VcButton");
+    expect(result.body).not.toContain("---\ntitle:");
+  });
+
+  it("extracts relative image references", async () => {
+    const result = await parseDocFile(path.join(fixtures, "simple-component.docs.md"));
+    expect(result.imageRefs).toEqual(["./images/default.png", "./images/hover.png"]);
+  });
+
+  it("preserves internal blocks in body (transformer strips them later)", async () => {
+    const result = await parseDocFile(path.join(fixtures, "composable-with-internal.docs.md"));
+    expect(result.body).toContain("<!-- internal:start -->");
+    expect(result.body).toContain("<!-- internal:end -->");
+  });
+});
diff --git a/cli/docs-sync/tests/report-formatter.test.ts b/cli/docs-sync/tests/report-formatter.test.ts
new file mode 100644
index 000000000..c808b068b
--- /dev/null
+++ b/cli/docs-sync/tests/report-formatter.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { formatReport } from "../src/report/formatter.js";
+
+describe("formatReport", () => {
+  it("renders all sections in markdown", () => {
+    const md = formatReport({
+      vcShellVersion: "v2.1.0",
+      timestamp: "2026-04-28T10:00:00Z",
+      changes: [
+        { source: "framework/x.docs.md", target: "components/misc/x.md", kind: "created" },
+        { source: "framework/y.docs.md", target: "components/misc/y.md", kind: "updated" },
+        { source: "framework/z.docs.md", target: "components/misc/z.md", kind: "unchanged" },
+      ],
+      skipped: [{ source: "framework/_internal.docs.md", reason: "internal" }],
+      orphans: [{ target: "components/misc/old.md" }],
+      errors: [],
+    });
+    expect(md).toContain("vc-shell@v2.1.0");
+    expect(md).toContain("Created: 1");
+    expect(md).toContain("Updated: 1");
+    expect(md).toContain("Unchanged: 1");
+    expect(md).toContain("Orphaned: 1");
+    expect(md).toContain("components/misc/old.md");
+  });
+
+  it("notes when there are zero errors", () => {
+    const md = formatReport({
+      vcShellVersion: "v0",
+      timestamp: "now",
+      changes: [],
+      skipped: [],
+      orphans: [],
+      errors: [],
+    });
+    expect(md).toContain("(none)");
+  });
+});
diff --git a/cli/docs-sync/tests/storybook-fetcher.test.ts b/cli/docs-sync/tests/storybook-fetcher.test.ts
new file mode 100644
index 000000000..a4b77c7b5
--- /dev/null
+++ b/cli/docs-sync/tests/storybook-fetcher.test.ts
@@ -0,0 +1,34 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { fetchStorybookIds } from "../src/storybook/index-fetcher.js";
+
+describe("fetchStorybookIds", () => {
+  beforeEach(() => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        v: 5,
+        entries: {
+          "atoms-vc-button--default": { id: "atoms-vc-button--default", type: "story" },
+          "atoms-vc-button--primary": { id: "atoms-vc-button--primary", type: "story" },
+          "docs-overview--page": { id: "docs-overview--page", type: "docs" }, // non-story
+        },
+      }),
+    } as Response);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns a Set of story IDs (excludes type=docs)", async () => {
+    const ids = await fetchStorybookIds("https://example.com");
+    expect(ids.has("atoms-vc-button--default")).toBe(true);
+    expect(ids.has("atoms-vc-button--primary")).toBe(true);
+    expect(ids.has("docs-overview--page")).toBe(false);
+  });
+
+  it("throws on fetch failure", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue({ ok: false, status: 404 } as Response);
+    await expect(fetchStorybookIds("https://example.com")).rejects.toThrow(/Storybook index/);
+  });
+});
diff --git a/cli/docs-sync/tests/transformer-header.test.ts b/cli/docs-sync/tests/transformer-header.test.ts
new file mode 100644
index 000000000..2ebb91735
--- /dev/null
+++ b/cli/docs-sync/tests/transformer-header.test.ts
@@ -0,0 +1,21 @@
+import { describe, it, expect } from "vitest";
+import { prependAutoGeneratedHeader, hasAutoGeneratedMarker, AUTO_GEN_MARKER } from "../src/transformer/header.js";
+
+describe("prependAutoGeneratedHeader", () => {
+  it("adds three-line HTML comment header pointing back at source", () => {
+    const out = prependAutoGeneratedHeader("# Title", "framework/ui/foo.docs.md");
+    expect(out.startsWith("<!--")).toBe(true);
+    expect(out).toContain(AUTO_GEN_MARKER);
+    expect(out).toContain("Source: framework/ui/foo.docs.md");
+    expect(out).toContain("yarn docs:sync");
+    // The original body comes after the header, separated by a blank line.
+    expect(out).toMatch(/\n\n# Title$/);
+  });
+});
+
+describe("hasAutoGeneratedMarker", () => {
+  it("detects marker presence", () => {
+    expect(hasAutoGeneratedMarker(`<!-- ${AUTO_GEN_MARKER} -->\n# x`)).toBe(true);
+    expect(hasAutoGeneratedMarker("# x")).toBe(false);
+  });
+});
diff --git a/cli/docs-sync/tests/transformer-links.test.ts b/cli/docs-sync/tests/transformer-links.test.ts
new file mode 100644
index 000000000..75f2b4f7c
--- /dev/null
+++ b/cli/docs-sync/tests/transformer-links.test.ts
@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { rewriteCrossDocLinks } from "../src/transformer/links.js";
+
+describe("rewriteCrossDocLinks", () => {
+  // resolveTarget: given a (sourcePath, linkHref), returns the target relative
+  // path inside vc-docs if the link points to another synced doc, or null.
+  const resolveTarget = (source: string, href: string): string | null => {
+    const map: Record<string, Record<string, string>> = {
+      "framework/ui/components/atoms/vc-button/vc-button.docs.md": {
+        "../vc-link": "components/navigation/vc-link.md",
+      },
+    };
+    return map[source]?.[href] ?? null;
+  };
+
+  it("rewrites a recognised cross-doc link to its target relative path", () => {
+    const body = "See also [VcLink](../vc-link).";
+    const out = rewriteCrossDocLinks(body, {
+      sourcePath: "framework/ui/components/atoms/vc-button/vc-button.docs.md",
+      targetPath: "components/misc/vc-button.md",
+      resolveTarget,
+    });
+    expect(out).toContain("[VcLink](../navigation/vc-link.md)");
+  });
+
+  it("leaves external links untouched", () => {
+    const body = "See [Vue](https://vuejs.org).";
+    const out = rewriteCrossDocLinks(body, {
+      sourcePath: "framework/ui/components/atoms/vc-button/vc-button.docs.md",
+      targetPath: "components/misc/vc-button.md",
+      resolveTarget,
+    });
+    expect(out).toContain("https://vuejs.org");
+  });
+
+  it("leaves links with no resolved target untouched (warning is caller's job)", () => {
+    const body = "See [Mystery](../non-synced-doc).";
+    const out = rewriteCrossDocLinks(body, {
+      sourcePath: "framework/ui/components/atoms/vc-button/vc-button.docs.md",
+      targetPath: "components/misc/vc-button.md",
+      resolveTarget,
+    });
+    expect(out).toContain("../non-synced-doc");
+  });
+
+  it("leaves image references alone", () => {
+    const body = "![hi](./images/x.png)";
+    const out = rewriteCrossDocLinks(body, {
+      sourcePath: "framework/ui/components/atoms/vc-button/vc-button.docs.md",
+      targetPath: "components/misc/vc-button.md",
+      resolveTarget,
+    });
+    expect(out).toBe(body);
+  });
+});
diff --git a/cli/docs-sync/tests/transformer-pipeline.test.ts b/cli/docs-sync/tests/transformer-pipeline.test.ts
new file mode 100644
index 000000000..71d1a94c1
--- /dev/null
+++ b/cli/docs-sync/tests/transformer-pipeline.test.ts
@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { runTransformPipeline } from "../src/transformer/pipeline.js";
+
+describe("runTransformPipeline", () => {
+  it("runs all transformers in order", () => {
+    const body = [
+      `# Foo`,
+      ``,
+      `<!-- internal:start -->`,
+      `secret`,
+      `<!-- internal:end -->`,
+      ``,
+      `::storybook id="atoms-vc-button--default"`,
+    ].join("\n");
+
+    const out = runTransformPipeline(body, {
+      sourceRelPath: "framework/x.docs.md",
+      sourcePath: "framework/x.docs.md",
+      targetPath: "components/misc/x.md",
+      storybookUrl: "https://example.com",
+      knownStoryIds: new Set(["atoms-vc-button--default"]),
+      resolveTarget: () => null,
+    });
+
+    // header prepended
+    expect(out.startsWith("<!--")).toBe(true);
+    // internal stripped
+    expect(out).not.toContain("secret");
+    // storybook expanded
+    expect(out).toContain("vc-storybook-embed");
+    // body still present
+    expect(out).toContain("# Foo");
+  });
+});
diff --git a/cli/docs-sync/tests/transformer-storybook.test.ts b/cli/docs-sync/tests/transformer-storybook.test.ts
new file mode 100644
index 000000000..d40fec5bd
--- /dev/null
+++ b/cli/docs-sync/tests/transformer-storybook.test.ts
@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest";
+import { expandStorybookDirectives } from "../src/transformer/storybook-directive.js";
+
+const STORY_IDS = new Set(["organisms-vc-data-table--default", "organisms-vc-data-table--with-sorting"]);
+
+describe("expandStorybookDirectives", () => {
+  it("expands a basic directive", () => {
+    const out = expandStorybookDirectives(`::storybook id="organisms-vc-data-table--default"`, {
+      storybookUrl: "https://example.com",
+      knownIds: STORY_IDS,
+      sourcePath: "x.docs.md",
+    });
+    expect(out).toContain('<div class="vc-storybook-embed"');
+    expect(out).toContain('src="https://example.com/iframe.html?id=organisms-vc-data-table--default&viewMode=story"');
+    expect(out).toContain('href="https://example.com/?path=/story/organisms-vc-data-table--default"');
+  });
+
+  it("respects height parameter", () => {
+    const out = expandStorybookDirectives(`::storybook id="organisms-vc-data-table--default" height="600"`, {
+      storybookUrl: "https://example.com",
+      knownIds: STORY_IDS,
+      sourcePath: "x.docs.md",
+    });
+    expect(out).toContain("--height: 600px");
+  });
+
+  it("defaults height to 400px", () => {
+    const out = expandStorybookDirectives(`::storybook id="organisms-vc-data-table--default"`, {
+      storybookUrl: "https://example.com",
+      knownIds: STORY_IDS,
+      sourcePath: "x.docs.md",
+    });
+    expect(out).toContain("--height: 400px");
+  });
+
+  it("appends theme global when theme=dark", () => {
+    const out = expandStorybookDirectives(`::storybook id="organisms-vc-data-table--default" theme="dark"`, {
+      storybookUrl: "https://example.com",
+      knownIds: STORY_IDS,
+      sourcePath: "x.docs.md",
+    });
+    expect(out).toContain("globals=theme:dark");
+  });
+
+  it("throws on unknown story id", () => {
+    expect(() =>
+      expandStorybookDirectives(`::storybook id="bogus--id"`, {
+        storybookUrl: "https://example.com",
+        knownIds: STORY_IDS,
+        sourcePath: "x.docs.md",
+      }),
+    ).toThrow(/unknown storybook id/i);
+  });
+});
diff --git a/cli/docs-sync/tests/transformer-strip-internal.test.ts b/cli/docs-sync/tests/transformer-strip-internal.test.ts
new file mode 100644
index 000000000..93a4e1f77
--- /dev/null
+++ b/cli/docs-sync/tests/transformer-strip-internal.test.ts
@@ -0,0 +1,30 @@
+import { describe, it, expect } from "vitest";
+import { stripInternalBlocks } from "../src/transformer/strip-internal.js";
+
+describe("stripInternalBlocks", () => {
+  it("removes a single internal block", () => {
+    const input = "before\n<!-- internal:start -->\nhidden\n<!-- internal:end -->\nafter";
+    expect(stripInternalBlocks(input)).toBe("before\n\nafter");
+  });
+
+  it("removes multiple internal blocks", () => {
+    const input =
+      "a\n<!-- internal:start -->X<!-- internal:end -->\nb\n<!-- internal:start -->Y<!-- internal:end -->\nc";
+    expect(stripInternalBlocks(input)).toBe("a\n\nb\n\nc");
+  });
+
+  it("handles internal block at the very end", () => {
+    const input = "kept\n<!-- internal:start -->\ngone\n<!-- internal:end -->";
+    expect(stripInternalBlocks(input)).toBe("kept\n");
+  });
+
+  it("returns input unchanged when no markers", () => {
+    expect(stripInternalBlocks("plain text")).toBe("plain text");
+  });
+
+  it("leaves unbalanced markers alone (and warns is caller's job)", () => {
+    const input = "<!-- internal:start -->\nno end here";
+    // We strip only when start AND end present and balanced; unbalanced → no-op.
+    expect(stripInternalBlocks(input)).toBe(input);
+  });
+});
diff --git a/cli/docs-sync/tests/writer.test.ts b/cli/docs-sync/tests/writer.test.ts
new file mode 100644
index 000000000..25357197d
--- /dev/null
+++ b/cli/docs-sync/tests/writer.test.ts
@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { computeTargetPath, writeMarkdown } from "../src/writer/writer.js";
+import type { Frontmatter } from "../src/types.js";
+
+describe("computeTargetPath", () => {
+  it("uses category/group/slug.md when slug is provided", () => {
+    const fm: Frontmatter = {
+      title: "VcDataTable",
+      category: "components",
+      group: "data-display",
+      slug: "vc-data-table",
+    };
+    expect(computeTargetPath(fm, "vc-data-table.docs.md")).toBe("components/data-display/vc-data-table.md");
+  });
+
+  it("falls back to source filename without .docs.md", () => {
+    const fm: Frontmatter = { title: "VcButton", category: "components", group: "misc" };
+    expect(computeTargetPath(fm, "vc-button.docs.md")).toBe("components/misc/vc-button.md");
+  });
+
+  it("treats group=root as no group folder for concepts", () => {
+    const fm: Frontmatter = { title: "Services", category: "concepts", group: "root", slug: "services" };
+    expect(computeTargetPath(fm, "services.docs.md")).toBe("concepts/services.md");
+  });
+
+  it("supports nested groups (reference/api/directives)", () => {
+    const fm: Frontmatter = { title: "v-loading", category: "reference", group: "api/directives", slug: "v-loading" };
+    expect(computeTargetPath(fm, "loading.docs.md")).toBe("reference/api/directives/v-loading.md");
+  });
+
+  it("emits plugins/<slug>.md for category=plugins, group=root", () => {
+    const fm: Frontmatter = {
+      title: "AI Agent",
+      category: "plugins",
+      group: "root",
+      slug: "ai-agent",
+    };
+    expect(computeTargetPath(fm, "ai-agent.docs.md")).toBe("plugins/ai-agent.md");
+  });
+
+  it("emits <category>/<group>/index.md when placement=index", () => {
+    const fm: Frontmatter = {
+      title: "Services",
+      category: "composables",
+      group: "services",
+      placement: "index",
+    };
+    expect(computeTargetPath(fm, "services.docs.md")).toBe("composables/services/index.md");
+  });
+
+  it("ignores slug when placement=index", () => {
+    const fm: Frontmatter = {
+      title: "Services",
+      category: "composables",
+      group: "services",
+      slug: "services-overview",
+      placement: "index",
+    };
+    expect(computeTargetPath(fm, "services.docs.md")).toBe("composables/services/index.md");
+  });
+});
+
+describe("writeMarkdown", () => {
+  let tmp: string;
+  beforeEach(async () => {
+    tmp = await fs.mkdtemp(path.join(os.tmpdir(), "docs-sync-"));
+  });
+  afterEach(async () => {
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("creates the file and parent directories", async () => {
+    const result = await writeMarkdown(tmp, "components/misc/x.md", "# x");
+    expect(result.kind).toBe("created");
+    const onDisk = await fs.readFile(path.join(tmp, "components/misc/x.md"), "utf8");
+    expect(onDisk).toBe("# x");
+  });
+
+  it("returns 'unchanged' when content is identical", async () => {
+    await writeMarkdown(tmp, "x.md", "same");
+    const result = await writeMarkdown(tmp, "x.md", "same");
+    expect(result.kind).toBe("unchanged");
+  });
+
+  it("returns 'updated' when content differs", async () => {
+    await writeMarkdown(tmp, "x.md", "v1");
+    const result = await writeMarkdown(tmp, "x.md", "v2");
+    expect(result.kind).toBe("updated");
+  });
+});
diff --git a/cli/docs-sync/tsconfig.json b/cli/docs-sync/tsconfig.json
new file mode 100644
index 000000000..d187513db
--- /dev/null
+++ b/cli/docs-sync/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "extends": "@vc-shell/ts-config/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "es2022",
+    "declaration": false,
+    "declarationMap": false,
+    "composite": false,
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["dist", "node_modules", "tests"]
+}
diff --git a/cli/docs-sync/vitest.config.ts b/cli/docs-sync/vitest.config.ts
new file mode 100644
index 000000000..ab679252d
--- /dev/null
+++ b/cli/docs-sync/vitest.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["tests/**/*.test.ts"],
+    passWithNoTests: true,
+  },
+});
diff --git a/framework/core/api/platform.docs.md b/framework/core/api/platform.docs.md
index e949cee10..dfa423bfe 100644
--- a/framework/core/api/platform.docs.md
+++ b/framework/core/api/platform.docs.md
@@ -1,3 +1,10 @@
+---
+title: Platform Client
+category: reference
+group: api
+slug: platform-client
+---
+
 # Platform API Client
 
 Auto-generated TypeScript API client for the VirtoCommerce Platform REST API. Generated by NSwag from the platform's Swagger/OpenAPI specification.
diff --git a/framework/core/blade-navigation/blade-nav-composables.docs.md b/framework/core/blade-navigation/blade-nav-composables.docs.md
index 73b46623b..49872575a 100644
--- a/framework/core/blade-navigation/blade-nav-composables.docs.md
+++ b/framework/core/blade-navigation/blade-nav-composables.docs.md
@@ -1,3 +1,9 @@
+---
+title: Blade Navigation Composables
+category: composables
+group: blade-navigation
+---
+
 # Blade Navigation Composables
 
 The core composables that implement the blade navigation system -- the stacked-panel UI paradigm used throughout VirtoCommerce admin applications.
@@ -14,7 +20,9 @@ Blade navigation manages an ordered stack of blade descriptors (plain data objec
 
 - Build or extend the blade navigation infrastructure itself (plugin authors, framework internals)
 - Need direct access to the blade stack state machine (`useBladeStack`) or inter-blade messaging (`useBladeMessaging`)
-- When NOT to use: for everyday blade operations in modules -- prefer `useBlade()` from `core/composables/useBlade/`, which wraps these low-level composables with a cleaner, context-aware API
+- When NOT to use: for everyday blade operations in modules -- prefer `useBlade()`, which wraps these low-level composables with a cleaner, context-aware API
+
+<!-- internal:start -->
 
 ## Exports
 
@@ -24,6 +32,8 @@ export { createBladeStack, useBladeStack } from "./useBladeStack";
 export { createBladeMessaging, useBladeMessaging } from "./useBladeMessaging";
 ```
 
+<!-- internal:end -->
+
 ## useBladeStack
 
 The blade stack state machine. Manages an ordered array of `BladeDescriptor` objects.
@@ -139,7 +149,7 @@ The plain data object stored in the stack for each blade:
 
 ## Tips
 
-- Prefer `useBlade()` / `useBladeContext()` (from `core/composables/useBlade/`) for new code -- they provide a cleaner API than the legacy adapter.
+- Prefer `useBlade()` / `useBladeContext()` for new code -- they provide a cleaner API than the legacy adapter.
 - Close guards return `true` to PREVENT closing (opposite of the legacy convention where `false` prevented closing). The adapter handles the inversion.
 - `replaceCurrentBlade` destroys the current blade and creates a new one at the same index with the same `parentId`. Use `coverCurrentBlade` to hide instead of destroy — the covering blade's `callParent` reaches the hidden blade's exposed methods.
 - URL sync only updates the address bar for blades that have a `url` segment. Third-level detail panels without URLs leave the previous URL intact.
@@ -147,6 +157,12 @@ The plain data object stored in the stack for each blade:
 
 ## Related
 
+- [`useBlade`](../composables/useBlade/) -- recommended API for everyday blade operations
+- [`useBladeContext`](../composables/bladeContext/) -- share reactive blade data with descendant components
+
+<!-- internal:start -->
+
 - `framework/core/composables/useBlade/` -- `useBlade()`, `useBladeContext()` (new API)
-- `framework/shared/components/blade-navigation/plugin-v2.ts` -- plugin that creates and provides the stack/messaging
-- `framework/shared/components/blade-navigation/types.ts` -- `BladeDescriptor`, `IBladeStack`, `IBladeMessaging`
+- `framework/shell/_internal/blade-nav/plugin-v2.ts` -- plugin that creates and provides the stack/messaging
+- `framework/core/blade-navigation/types/index.ts` -- `BladeDescriptor`, `IBladeStack`, `IBladeMessaging`
+<!-- internal:end -->
diff --git a/framework/core/composables/bladeContext/index.docs.md b/framework/core/composables/bladeContext/index.docs.md
index a1cca3ebc..297a68f4c 100644
--- a/framework/core/composables/bladeContext/index.docs.md
+++ b/framework/core/composables/bladeContext/index.docs.md
@@ -1,3 +1,10 @@
+---
+title: useBladeContext
+category: composables
+group: blade-navigation
+slug: useBladeContext
+---
+
 # useBladeContext (defineBladeContext / injectBladeContext)
 
 Exposes blade-level data to descendant widgets, extensions, and nested components via Vue's provide/inject mechanism. This pair of functions eliminates the need for prop drilling when child widgets or extension points need access to the parent blade's entity data, loading flags, or other shared state.
@@ -96,7 +103,7 @@ defineBladeContext(
 
 - **Automatic ref unwrapping**: `defineBladeContext` shallow-unwraps all ref/computed values in the provided object. Consumers get plain values directly (`ctx.value.item` instead of `ctx.value.item.value`). This works reactively — when the source ref changes, the context updates automatically.
 - **Reactivity**: The provided context is always wrapped in a `computed`, so consumers receive a `ComputedRef` regardless of whether the provider passed a plain object, a ref, or a getter. Changes propagate automatically.
-- **Injection key**: Uses `BladeContextKey` from `framework/injection-keys.ts`. This is a framework-level Symbol, so there is no risk of key collision with application code.
+- **Injection key**: Uses `BladeContextKey` (a framework-level Symbol), so there is no risk of key collision with application code.
 - **Error handling**: `injectBladeContext` throws an `InjectionError` with a descriptive message if called outside a blade component tree. This fails fast during development rather than silently returning `undefined`.
 - **Scope**: The context is scoped to the Vue component subtree. Each blade in the stack has its own context, so nested blades do not leak data upward or sideways.
 
@@ -108,6 +115,11 @@ defineBladeContext(
 
 ## Related
 
+- [`useBladeWidgets`](../useBladeWidgets/) -- widgets that consume blade context
+- [`useBlade`](../useBlade/) -- cross-blade communication via `callParent` / `exposeToChildren`
+
+<!-- internal:start -->
+
 - `BladeContextKey` in `framework/injection-keys.ts`
-- `useBladeWidgets` -- widgets that consume blade context
-- `useBladeStack` -- manages the blade navigation stack
+- `useBladeStack` in `framework/core/blade-navigation/` -- manages the blade navigation stack
+<!-- internal:end -->
diff --git a/framework/core/composables/useApiClient/useApiClient.docs.md b/framework/core/composables/useApiClient/useApiClient.docs.md
index 9a3c35aa1..f36064a4e 100644
--- a/framework/core/composables/useApiClient/useApiClient.docs.md
+++ b/framework/core/composables/useApiClient/useApiClient.docs.md
@@ -1,7 +1,16 @@
+---
+title: useApiClient
+category: composables
+group: data
+---
+
 # useApiClient
 
 Creates a typed API client instance for communicating with VirtoCommerce platform APIs. The composable accepts a generated client class constructor and returns an async factory function that produces a configured, authenticated client. Base URL resolution and authentication token injection are handled automatically.
 
+!!! tip "Always call getApiClient inside async functions"
+`getApiClient` is async. Never call it at the top level of `<script setup>` — always call it inside the async function you pass to `useAsync`. Storing the client in a variable outside the function gives you a stale reference when tokens rotate.
+
 ## When to Use
 
 - Instantiate a generated VirtoCommerce API client with automatic authentication and base-URL resolution
@@ -291,7 +300,7 @@ API clients are generated from Swagger/OpenAPI specs using the `@vc-shell/api-cl
 
 ## Related
 
-- [useAsync](../useAsync/) -- wraps async API calls with loading/error state management
-- [CLI API Client Generator](../../../../cli/) -- generates typed client classes from Swagger specs
-- [useToolbar](../useToolbar/) -- disable toolbar buttons during API calls using the loading ref
-- [useNotifications](../useNotifications/) -- display success/error messages after API operations
+- [`useAsync`](../useAsync/) -- wraps async API calls with loading/error state management
+- CLI API Client Generator (`@vc-shell/api-client-generator`) -- generates typed client classes from Swagger specs
+- [`useToolbar`](../useToolbar/) -- disable toolbar buttons during API calls using the loading ref
+- [`useNotifications`](../useNotifications/) -- display success/error messages after API operations
diff --git a/framework/core/composables/useAppBarMobileButtons/useAppBarMobileButtons.docs.md b/framework/core/composables/useAppBarMobileButtons/useAppBarMobileButtons.docs.md
index fa417075d..94e220f42 100644
--- a/framework/core/composables/useAppBarMobileButtons/useAppBarMobileButtons.docs.md
+++ b/framework/core/composables/useAppBarMobileButtons/useAppBarMobileButtons.docs.md
@@ -1,3 +1,9 @@
+---
+title: useAppBarMobileButtons
+category: composables
+group: services
+---
+
 # useAppBarMobileButtons
 
 Manages custom action buttons in the mobile app bar. Uses provide/inject to share a singleton service across the component tree. This composable gives any blade or module the ability to register, update, and remove buttons that appear in the top app bar on mobile devices. Buttons are sorted by their `order` property and can include icons, custom Vue components, click handlers, badges, and reactive visibility toggles. The service is scoped to the VcApp tree and automatically cleans up when the scope is disposed.
@@ -59,6 +65,8 @@ onUnmounted(() => unregister("notifications-btn"));
 | `isVisible` | `MaybeRef<boolean>`       | No       | Reactive visibility toggle. When `false`, the button is excluded from `getButtons`. Defaults to `true`. |
 | `badge`     | `MaybeRef<boolean>`       | No       | Show a small badge indicator on the button (e.g., for unread notifications).                            |
 
+<!-- internal:start -->
+
 ## Setup
 
 `provideAppBarMobileButtonsService()` must be called once in the app root (VcApp). It is idempotent -- calling it again in the same injection tree returns the existing service. Descendant components then call `useAppBarMobileButtons()` to register buttons.
@@ -70,6 +78,8 @@ import { provideAppBarMobileButtonsService } from "@vc-shell/framework";
 provideAppBarMobileButtonsService();
 ```
 
+<!-- internal:end -->
+
 ## Recipe: Filter Toggle Button That Reflects Active State
 
 ```vue
diff --git a/framework/core/composables/useAppBarWidget/useAppBarWidget.docs.md b/framework/core/composables/useAppBarWidget/useAppBarWidget.docs.md
index 454664fdc..6ff9f35c3 100644
--- a/framework/core/composables/useAppBarWidget/useAppBarWidget.docs.md
+++ b/framework/core/composables/useAppBarWidget/useAppBarWidget.docs.md
@@ -1,3 +1,9 @@
+---
+title: useAppBarWidget
+category: composables
+group: services
+---
+
 # useAppBarWidget
 
 Provides access to the app bar widget service for registering custom widgets (buttons, icons, dropdowns) in the application's top navigation bar. Uses Vue's provide/inject system.
diff --git a/framework/core/composables/useAppInsights/useAppInsights.docs.md b/framework/core/composables/useAppInsights/useAppInsights.docs.md
index 37b4789de..37a8a6c04 100644
--- a/framework/core/composables/useAppInsights/useAppInsights.docs.md
+++ b/framework/core/composables/useAppInsights/useAppInsights.docs.md
@@ -1,3 +1,9 @@
+---
+title: useAppInsights
+category: composables
+group: utilities
+---
+
 # useAppInsights
 
 Integrates Azure Application Insights page-view tracking with Vue Router and the current user context. This composable bridges the `vue3-application-insights` plugin with the vc-shell framework by automatically enriching every page-view event with the authenticated user's ID and name, generating fresh W3C trace IDs per navigation for distributed tracing, and optionally prefixing page names with the application name (e.g., `[Vendor Portal] Dashboard`).
diff --git a/framework/core/composables/useAssets/useAssets.docs.md b/framework/core/composables/useAssets/useAssets.docs.md
index 83b3fcb94..142d31654 100644
--- a/framework/core/composables/useAssets/useAssets.docs.md
+++ b/framework/core/composables/useAssets/useAssets.docs.md
@@ -1,3 +1,9 @@
+---
+title: useAssets
+category: composables
+group: data
+---
+
 # useAssets
 
 Handles file upload, removal, and editing for `ICommonAsset` arrays (images, documents, etc.). This composable encapsulates the platform's asset storage API, handling multipart form upload with batched concurrency (max 4 simultaneous uploads), sort-order assignment, URL decoding, and immutable array operations for remove and edit. It returns a new array from every operation rather than mutating in place, which plays well with Vue's reactivity system and makes undo/redo patterns straightforward.
@@ -131,5 +137,6 @@ async function handleUpload(files: FileList) {
 
 ## Related
 
-- `ICommonAsset` type in `@core/types`
+- `ICommonAsset` -- type imported from `@vc-shell/framework`
 - `VcGallery` / `VcImageTile` -- UI components that consume asset arrays
+- [`useAssetsManager`](../useAssetsManager/) -- higher-level composable that wraps `useAssets` with two-way sync
diff --git a/framework/core/composables/useAssetsManager/useAssetsManager.docs.md b/framework/core/composables/useAssetsManager/useAssetsManager.docs.md
index 82055af8f..2206226e0 100644
--- a/framework/core/composables/useAssetsManager/useAssetsManager.docs.md
+++ b/framework/core/composables/useAssetsManager/useAssetsManager.docs.md
@@ -1,3 +1,9 @@
+---
+title: useAssetsManager
+category: composables
+group: data
+---
+
 # useAssetsManager
 
 High-level composable for managing asset arrays (images, documents, files). Wraps upload, remove, reorder, and metadata editing operations, mutating a reactive ref directly — no manual wiring needed.
@@ -147,7 +153,12 @@ interface AssetLike {
 
 ## Related
 
-- `framework/modules/assets-manager/` — AssetsManager blade (table UI for managing assets)
-- `framework/modules/assets/` — AssetsDetails blade (single asset editing)
-- `framework/ui/components/organisms/vc-gallery/` — VcGallery component
-- `framework/core/composables/useAssets/` — deprecated low-level composable
+- `VcGallery` -- gallery component that integrates with `useAssetsManager` events
+- [`useAssets`](../useAssets/) -- lower-level composable for manual upload/remove operations
+
+<!-- internal:start -->
+
+- `framework/modules/assets-manager/` -- AssetsManager blade (table UI for managing assets)
+- `framework/modules/assets/` -- AssetsDetails blade (single asset editing)
+- `framework/ui/components/organisms/vc-gallery/` -- VcGallery component source
+<!-- internal:end -->
diff --git a/framework/core/composables/useAsync/useAsync.docs.md b/framework/core/composables/useAsync/useAsync.docs.md
index 15ea786bb..921ee49be 100644
--- a/framework/core/composables/useAsync/useAsync.docs.md
+++ b/framework/core/composables/useAsync/useAsync.docs.md
@@ -1,3 +1,12 @@
+---
+title: useAsync
+category: composables
+group: utilities
+---
+
+!!! note "Large reference"
+This page is long. Use the section headings to navigate: [Quick Start](#quick-start), [API Reference](#api-reference), [Features](#features), [Recipes](#recipes), [Common Mistakes](#common-mistakes).
+
 # useAsync
 
 Wraps an asynchronous function with reactive `loading` state, reactive `error` state, and automatic error notifications. This is the standard way to handle API calls, saves, deletes, and other async operations throughout VC-Shell applications.
@@ -400,12 +409,16 @@ const { action: save, loading: saveLoading } = useAsync(async () => saveData());
 
 ---
 
+<!-- internal:start -->
+
 ## Internals
 
 - Errors are parsed via `parseError()` into `DisplayableError` objects that have a user-friendly `message` property.
 - Toast notifications are deferred with `setTimeout(0)` and registered via `setPendingErrorNotification`. The `ErrorInterceptor` (blade-level `onErrorCaptured`) can call `cancelPendingErrorNotification` to suppress the toast when a blade error banner is shown instead.
 - The notification module is lazy-imported to avoid circular dependencies with `@core/composables`.
 
+<!-- internal:end -->
+
 ---
 
 ## Related
diff --git a/framework/core/composables/useBeforeUnload/useBeforeUnload.docs.md b/framework/core/composables/useBeforeUnload/useBeforeUnload.docs.md
index f8c5dae46..ac3fc5f6f 100644
--- a/framework/core/composables/useBeforeUnload/useBeforeUnload.docs.md
+++ b/framework/core/composables/useBeforeUnload/useBeforeUnload.docs.md
@@ -1,3 +1,9 @@
+---
+title: useBeforeUnload
+category: composables
+group: utilities
+---
+
 # useBeforeUnload
 
 Prevents the browser tab from closing when unsaved changes exist by hooking into the native `beforeunload` event. This composable is the last line of defense against accidental data loss -- it triggers the browser's built-in "Leave site?" confirmation dialog whenever the user tries to close or refresh the tab while the `modified` flag is `true`. It complements in-app guards (like blade `onBeforeClose`) by covering the case where the user bypasses the application entirely via the browser chrome.
diff --git a/framework/core/composables/useBlade/useBlade.docs.md b/framework/core/composables/useBlade/useBlade.docs.md
index ad6da47ae..de136dae5 100644
--- a/framework/core/composables/useBlade/useBlade.docs.md
+++ b/framework/core/composables/useBlade/useBlade.docs.md
@@ -1,3 +1,9 @@
+---
+title: useBlade
+category: composables
+group: blade-navigation
+---
+
 # useBlade
 
 Unified composable for blade navigation, identity, communication, guards, and error management in VC-Shell applications. This is the primary API for working with the blade navigation system -- the stacked panel paradigm (similar to Azure Portal) that drives every screen in a VC-Shell app.
@@ -644,6 +650,9 @@ function goToOrders() {
 
 ## Common Mistakes
 
+!!! warning "Blade-specific methods throw outside blade context"
+Methods like `closeSelf`, `callParent`, `onBeforeClose`, and `setError` require a blade context (i.e., must be called from inside a blade component's `<script setup>`). Calling them from a dashboard card, a toolbar handler, or a plain composable throws a descriptive runtime error. Only `openBlade` works everywhere.
+
 ### Calling blade-specific methods outside blade context
 
 ```typescript
@@ -740,6 +749,8 @@ if (param.value) {
 
 ---
 
+<!-- internal:start -->
+
 ## How It Works Under the Hood
 
 1. **Plugin setup:** `BladeNavigationPlugin` (plugin-v2) installs a `BladeStack` and `BladeMessaging` singleton and provides them via Vue's dependency injection.
@@ -747,6 +758,8 @@ if (param.value) {
 3. **Outside a blade:** `useBlade()` falls back to the singleton instances. Only `openBlade` works because it does not need a blade descriptor.
 4. **URL sync:** When blades with a `url` property are opened or closed, `useBlade()` synchronizes the browser URL via `createUrlSync`, enabling deep linking and back/forward navigation.
 
+<!-- internal:end -->
+
 ---
 
 ## Related
diff --git a/framework/core/composables/useBladeForm/useBladeForm.docs.md b/framework/core/composables/useBladeForm/useBladeForm.docs.md
index d0994dcdd..28430a84b 100644
--- a/framework/core/composables/useBladeForm/useBladeForm.docs.md
+++ b/framework/core/composables/useBladeForm/useBladeForm.docs.md
@@ -1,3 +1,9 @@
+---
+title: useBladeForm
+category: composables
+group: forms
+---
+
 # useBladeForm
 
 Unified form state management for blades. Replaces manual combination of `useForm` + `useModificationTracker` + `useBeforeUnload` + `onBeforeClose` with a single composable.
@@ -152,8 +158,8 @@ onMounted(async () => {
 
 At composable creation, `useBladeForm` takes a snapshot of `data` (the **setup-time snapshot**). When `markReady()` is called:
 
-1. `isReady` → `true` (gates `canSave` and the deep watcher)
-2. `trackerIsModified` = `!semanticEqual(data, setupTimeSnapshot)` — since data was mutated during `onMounted`, this evaluates to `true`
+1. `isReady` → `true` (gates `canSave` and subsequent edit tracking)
+2. Modification state is computed by comparing the current data to the setup-time snapshot — since data was mutated during `onMounted`, `isModified` evaluates to `true`
 3. Subsequent edits are tracked normally by the deep watcher
 
 After save, call `setBaseline()` as usual to capture the saved state as the new pristine snapshot.
@@ -164,6 +170,10 @@ After save, call `setBaseline()` as usual to capture the saved state as the new
 - Validation rules stay in template (`<Field rules="...">`).
 - `setBaseline()` must be called after data is loaded — before that, `canSave` and `isModified` are `false`.
 
+<!-- internal:start -->
+
 ## Migration
 
 See `MIGRATION_GUIDE.md` for step-by-step instructions on migrating existing modules.
+
+<!-- internal:end -->
diff --git a/framework/core/composables/useBladeRegistry/useBladeRegistry.docs.md b/framework/core/composables/useBladeRegistry/useBladeRegistry.docs.md
index e8e1eec6d..35b356909 100644
--- a/framework/core/composables/useBladeRegistry/useBladeRegistry.docs.md
+++ b/framework/core/composables/useBladeRegistry/useBladeRegistry.docs.md
@@ -1,3 +1,9 @@
+---
+title: useBladeRegistry
+category: composables
+group: blade-navigation
+---
+
 # useBladeRegistry
 
 Provides read-only access to the blade registry -- a central map of all registered blade components, their routes, and metadata.
@@ -129,7 +135,7 @@ function canAccessBlade(bladeName: string): boolean {
 
 ## Notes
 
-- The composable must be called after `createBladeRegistry()` has provided the registry via `BladeRegistryKey`. Calling it too early (e.g., outside a setup function or before app bootstrap) throws an error.
+- The composable must be called after the navigation plugin has initialized. Calling it too early (e.g., outside a setup function or before app bootstrap) throws an error.
 - `getBladeComponent()` falls back to Vue's global component registry if the blade is not found in the framework registry. This supports legacy components registered via `app.component()`.
 - The `registeredBladesMap` is a `ComputedRef` wrapping a `ReadonlyMap`, so it updates reactively when new modules are loaded.
 
@@ -147,6 +153,10 @@ if (!registration) {
 
 ## Related
 
-- [useBlade](../useBlade/) -- opens and manages blades by name
-- [Dynamic Module Loading](../../plugins/modularity/) -- registers blades during module initialization
-- `framework/injection-keys.ts` -- `BladeRegistryKey` (defined in the composable file, not in injection-keys.ts)
+- [`useBlade`](../useBlade/) -- opens and manages blades by name
+- Dynamic Module Loading -- registers blades during module initialization
+
+<!-- internal:start -->
+
+- `createBladeRegistry()` in `framework/core/composables/useBladeRegistry/index.ts` -- factory called by the navigation plugin; `BladeRegistryKey` is defined here
+<!-- internal:end -->
diff --git a/framework/core/composables/useBladeWidgets/index.docs.md b/framework/core/composables/useBladeWidgets/index.docs.md
index fc28f4f55..b7a1ef4fd 100644
--- a/framework/core/composables/useBladeWidgets/index.docs.md
+++ b/framework/core/composables/useBladeWidgets/index.docs.md
@@ -1,3 +1,10 @@
+---
+title: useBladeWidgets
+category: composables
+group: blade-navigation
+slug: useBladeWidgets
+---
+
 # useBladeWidgets / useWidgetTrigger
 
 Two composables for the widget system — one for the **blade side**, one for the **widget side**.
@@ -239,21 +246,24 @@ async function save() {
 
 ## Prerequisites
 
+!!! warning "Call site requirements"
+`useBladeWidgets` must be called inside a blade component's `<script setup>` — it requires blade context to be present. `useWidgetTrigger` must be called inside a widget component rendered by `WidgetContainer`. Calling either outside their required scope produces a runtime error or silent no-op respectively.
+
 **`useBladeWidgets`**:
 
-- Must be called inside a blade component rendered by `VcBladeSlot` (requires `BladeDescriptorKey` injection).
-- `WidgetService` must be provided in the component tree (automatically available in vc-shell apps).
+- Must be called inside a blade component's `<script setup>`.
+- Widget service must be provided in the component tree (automatically available in vc-shell apps).
 - Calling outside a blade context throws an error with a descriptive message.
 
 **`useWidgetTrigger`**:
 
-- Must be called inside a widget component rendered by `WidgetContainer` (requires `WidgetScopeKey` injection).
+- Must be called inside a widget component rendered by `WidgetContainer`.
 - If called outside a widget scope, logs a warning and does nothing (does not throw).
 
 ## Details
 
-- **Lifecycle management**: Widgets are registered in `onMounted` and unregistered in `onUnmounted`. This ensures the WidgetService always reflects the currently visible blades.
-- **Blade ID resolution**: The composable injects `BladeDescriptorKey` to determine which blade the widgets belong to. Each blade has its own isolated widget list.
+- **Lifecycle management**: Widgets are registered in `onMounted` and unregistered in `onUnmounted`. This ensures the widget service always reflects the currently visible blades.
+- **Blade ID resolution**: The composable injects the blade descriptor to determine which blade the widgets belong to. Each blade has its own isolated widget list.
 - **Trigger pattern**: The `onRefresh` callback is stored as a `trigger` on the registered widget. When `refresh(id)` or `refreshAll()` is called, the trigger is invoked. Widgets without `onRefresh` are silently skipped.
 
 ## Tips
@@ -294,8 +304,12 @@ const { refreshAll } = useBladeWidgets([]);
 
 ## Related
 
-- `defineBladeContext` / `injectBladeContext` -- expose/consume blade data in external widgets
+- [`defineBladeContext` / `injectBladeContext`](../bladeContext/) -- expose/consume blade data in external widgets
 - `registerExternalWidget` -- register a component-based widget globally for target blades
-- `WidgetService` in `@core/services/widget-service` -- underlying service
-- `WidgetScope` in `vc-blade/_internal/widgets/WidgetScope.vue` -- provides `WidgetScopeKey` to widget components
-- `VcBladeSlot` -- the blade wrapper that provides `BladeDescriptorKey`
+
+<!-- internal:start -->
+
+- `WidgetService` in `framework/core/services/widget-service/` -- underlying service
+- `WidgetScope` in `framework/ui/components/organisms/vc-blade/_internal/widgets/WidgetScope.vue` -- provides `WidgetScopeKey` to widget components
+- `VcBladeSlot` in `framework/shell/_internal/blade-nav/` -- provides `BladeDescriptorKey` to blade components
+<!-- internal:end -->
diff --git a/framework/core/composables/useBreadcrumbs/useBreadcrumbs.docs.md b/framework/core/composables/useBreadcrumbs/useBreadcrumbs.docs.md
index d0b6cfba8..97ff7d0ab 100644
--- a/framework/core/composables/useBreadcrumbs/useBreadcrumbs.docs.md
+++ b/framework/core/composables/useBreadcrumbs/useBreadcrumbs.docs.md
@@ -1,3 +1,9 @@
+---
+title: useBreadcrumbs
+category: composables
+group: ui-state
+---
+
 # useBreadcrumbs
 
 Manages a reactive breadcrumb trail for blade navigation. Supports push, remove, and automatic trail trimming on click.
diff --git a/framework/core/composables/useConnectionStatus/useConnectionStatus.docs.md b/framework/core/composables/useConnectionStatus/useConnectionStatus.docs.md
index bd57123b9..d03697a28 100644
--- a/framework/core/composables/useConnectionStatus/useConnectionStatus.docs.md
+++ b/framework/core/composables/useConnectionStatus/useConnectionStatus.docs.md
@@ -1,3 +1,9 @@
+---
+title: useConnectionStatus
+category: composables
+group: ui-state
+---
+
 # useConnectionStatus
 
 Monitors the browser's network connectivity and shows a persistent notification when the user goes offline. This composable wraps `@vueuse/core`'s `useNetwork()` and adds framework-specific behavior: it displays a warning notification via the vc-shell notification system, applies a `vc-offline` CSS class to `<html>` for global styling hooks, and logs state changes through the framework logger. The state is a module-level singleton, so only one set of event listeners is ever created regardless of how many components call the composable.
@@ -43,6 +49,8 @@ const { isOnline } = useConnectionStatus();
 | ---------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
 | `isOnline` | `Readonly<Ref<boolean>>` | `true` when the browser has network connectivity, `false` when offline. Read-only to prevent external mutation. |
 
+<!-- internal:start -->
+
 ## How It Works
 
 On the very first call to `useConnectionStatus()`, the composable initializes a watcher on `@vueuse/core`'s `useNetwork().isOnline`. This watcher runs with `{ immediate: true }`, so the state is correct from the start. Subsequent calls skip initialization and return the same shared reactive state.
@@ -55,6 +63,8 @@ When the network drops:
 
 When connectivity is restored, the notification is removed, the CSS class is cleared, and an info message is logged.
 
+<!-- internal:end -->
+
 ## Recipe: Disabling Auto-Save While Offline
 
 ```vue
diff --git a/framework/core/composables/useDashboard/useDashboard.docs.md b/framework/core/composables/useDashboard/useDashboard.docs.md
index ad0b4fb24..d1af09338 100644
--- a/framework/core/composables/useDashboard/useDashboard.docs.md
+++ b/framework/core/composables/useDashboard/useDashboard.docs.md
@@ -1,3 +1,12 @@
+---
+title: useDashboard
+category: composables
+group: services
+---
+
+!!! tip "Long page"
+Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Widget Registration](#widget-registration), [Permission-Based Visibility](#permission-based-visibility), or [API Reference](#api-reference).
+
 # useDashboard
 
 Accesses the dashboard service for registering and managing dashboard widgets. Widgets are permission-aware, support layout positioning, and can be pre-registered during module setup before the service is initialized.
diff --git a/framework/core/composables/useDynamicProperties/useDynamicProperties.docs.md b/framework/core/composables/useDynamicProperties/useDynamicProperties.docs.md
index 14a9f9ea7..f08eb0c87 100644
--- a/framework/core/composables/useDynamicProperties/useDynamicProperties.docs.md
+++ b/framework/core/composables/useDynamicProperties/useDynamicProperties.docs.md
@@ -1,3 +1,9 @@
+---
+title: useDynamicProperties
+category: composables
+group: forms
+---
+
 # useDynamicProperties
 
 Composable for managing dynamic (runtime-defined) property values with support for multilanguage, multivalue, dictionary, color, and measurement property types.
diff --git a/framework/core/composables/useErrorHandler/useErrorHandler.docs.md b/framework/core/composables/useErrorHandler/useErrorHandler.docs.md
index 6427a545f..7e76fb884 100644
--- a/framework/core/composables/useErrorHandler/useErrorHandler.docs.md
+++ b/framework/core/composables/useErrorHandler/useErrorHandler.docs.md
@@ -1,3 +1,9 @@
+---
+title: useErrorHandler
+category: composables
+group: utilities
+---
+
 # useErrorHandler
 
 Captures and normalizes errors within a component's subtree using Vue's `onErrorCaptured` hook. This composable acts as an error boundary: it catches errors thrown by any child component, normalizes them into a `DisplayableError` with a user-friendly `message` and technical `details`, automatically reports them to Application Insights with user context, and emits events so parent components can react. It also includes re-entrancy protection to prevent infinite error loops when the error display itself triggers an error.
diff --git a/framework/core/composables/useFunctions/useFunctions.docs.md b/framework/core/composables/useFunctions/useFunctions.docs.md
index cddf1cde8..38978ecbc 100644
--- a/framework/core/composables/useFunctions/useFunctions.docs.md
+++ b/framework/core/composables/useFunctions/useFunctions.docs.md
@@ -1,3 +1,9 @@
+---
+title: useFunctions
+category: composables
+group: utilities
+---
+
 # useFunctions
 
 Provides lightweight utility functions for timing control: debounce, throttle, delay, and once. These are thin, dependency-free implementations that cover the most common use cases without pulling in lodash or other large utility libraries. The composable returns plain functions, not reactive wrappers, making them suitable for event handlers, API calls, and other imperative code paths where you do not need VueUse's reactive cancellation features.
diff --git a/framework/core/composables/useKeyboardNavigation/useKeyboardNavigation.docs.md b/framework/core/composables/useKeyboardNavigation/useKeyboardNavigation.docs.md
index 78d346f04..58c41b819 100644
--- a/framework/core/composables/useKeyboardNavigation/useKeyboardNavigation.docs.md
+++ b/framework/core/composables/useKeyboardNavigation/useKeyboardNavigation.docs.md
@@ -1,3 +1,9 @@
+---
+title: useKeyboardNavigation
+category: composables
+group: ui-state
+---
+
 # useKeyboardNavigation
 
 Implements keyboard navigation (Arrow keys, Tab, Enter, Escape) within a container of focusable elements. This composable provides full WAI-ARIA-style keyboard interaction for custom menus, dropdowns, autocomplete lists, and other composite widgets that are not natively keyboard-accessible. It manages a focused-item index, handles wrap-around (looping), and automatically attaches/detaches event listeners tied to the component lifecycle.
@@ -85,6 +91,8 @@ function openMenu() {
 | `setFocusedIndex`           | `(index: number) => void`   | Set focus to a specific index. No-op if index is out of bounds.                           |
 | `getFocusedIndex`           | `() => number`              | Get the currently focused index (`-1` if no item is focused).                             |
 
+<!-- internal:start -->
+
 ## How It Works
 
 The composable listens for `keydown` events on the container element and handles:
@@ -98,6 +106,8 @@ On each key event, the composable re-queries the container for matching items (`
 
 Auto-attach happens in `onMounted`: if `containerSelector` is set and a matching element exists in the DOM, keyboard navigation is initialized automatically. Cleanup happens in `onBeforeUnmount`.
 
+<!-- internal:end -->
+
 ## Recipe: Keyboard-Navigable Autocomplete Dropdown
 
 ```vue
diff --git a/framework/core/composables/useLanguages/useLanguages.docs.md b/framework/core/composables/useLanguages/useLanguages.docs.md
index 607f89afc..8c3b0fb0a 100644
--- a/framework/core/composables/useLanguages/useLanguages.docs.md
+++ b/framework/core/composables/useLanguages/useLanguages.docs.md
@@ -1,3 +1,9 @@
+---
+title: useLanguages
+category: composables
+group: user
+---
+
 # useLanguages
 
 Provides access to the language service for locale management: getting/setting the current locale, resolving locale tags, and fetching country flags. The service is created once via `provideLanguages()` at the framework level and shared through Vue's injection system. If called outside an injection context (e.g., during module initialization), a fallback singleton service is used so the composable never throws.
diff --git a/framework/core/composables/useLoading/useLoading.docs.md b/framework/core/composables/useLoading/useLoading.docs.md
index 9dc21c294..fd1c15a96 100644
--- a/framework/core/composables/useLoading/useLoading.docs.md
+++ b/framework/core/composables/useLoading/useLoading.docs.md
@@ -1,3 +1,9 @@
+---
+title: useLoading
+category: composables
+group: ui-state
+---
+
 # useLoading
 
 Aggregates multiple reactive boolean loading refs into a single computed that is `true` when any source is loading. This is a minimal utility composable -- just one line of logic -- but it solves a very common problem in blade development: when a component depends on several async data sources, you need a single flag for the loading overlay. Instead of writing `computed(() => loadingA.value || loadingB.value || loadingC.value)` in every blade, `useLoading` provides a clean, readable shorthand that scales to any number of sources.
@@ -31,6 +37,8 @@ const combinedLoading = useLoading(loadingA, loadingB, loadingC);
 | ---------------------- | ------------------------------------------------------------------------------------------------------ |
 | `ComputedRef<boolean>` | `true` if any of the input refs is `true`, `false` otherwise. Re-evaluates whenever any input changes. |
 
+<!-- internal:start -->
+
 ## How It Works
 
 The implementation is a single `computed` that calls `Array.some()` on the input refs:
@@ -41,6 +49,8 @@ computed(() => args.some((item) => item.value));
 
 Because `computed` tracks all `.value` accesses, Vue knows to re-evaluate whenever any of the input refs changes. The `some()` short-circuits on the first `true`, so it is efficient even with many inputs.
 
+<!-- internal:end -->
+
 ## Recipe: Blade with Multiple Data Sources
 
 ```vue
diff --git a/framework/core/composables/useMenuExpanded/index.docs.md b/framework/core/composables/useMenuExpanded/index.docs.md
index d9b5627eb..b567f804b 100644
--- a/framework/core/composables/useMenuExpanded/index.docs.md
+++ b/framework/core/composables/useMenuExpanded/index.docs.md
@@ -1,3 +1,10 @@
+---
+title: useMenuExpanded
+category: composables
+group: ui-state
+slug: useMenuExpanded
+---
+
 # useMenuExpanded
 
 Manages the sidebar menu expanded/collapsed and hover-expanded state with localStorage persistence. This is the low-level composable that powers the sidebar pin/unpin behavior in the vc-shell admin UI. It tracks two independent states: the permanent "pinned" state (persisted across sessions) and the transient "hover-expanded" state (active only while the user hovers over a collapsed sidebar).
@@ -65,12 +72,15 @@ const isVisuallyExpanded = computed(() => isExpanded.value || isHoverExpanded.va
 </template>
 ```
 
+<!-- internal:start -->
+
 ## Details
 
 - **Storage key scoping**: The key is scoped per application using the first URL path segment: `VC_APP_MENU_EXPANDED_{appName}`. For example, if the app is hosted at `/vendor-portal/`, the key is `VC_APP_MENU_EXPANDED_vendor-portal`. This allows multiple vc-shell apps on the same domain to maintain independent sidebar states.
 - **Hover delay**: Opening uses a 200ms debounce to prevent accidental expansion when the cursor briefly passes over the sidebar. Closing is immediate to feel responsive.
 - **Cleanup**: Pending hover timeouts are cleaned up via `onScopeDispose` to prevent memory leaks when the composable's effect scope is destroyed.
 - **Default state**: The sidebar starts pinned open (`true`) on first visit, which is the most user-friendly default for new users.
+<!-- internal:end -->
 
 ## Tips
 
diff --git a/framework/core/composables/useMenuService/useMenuService.docs.md b/framework/core/composables/useMenuService/useMenuService.docs.md
index 4d04531e7..608032490 100644
--- a/framework/core/composables/useMenuService/useMenuService.docs.md
+++ b/framework/core/composables/useMenuService/useMenuService.docs.md
@@ -1,3 +1,12 @@
+---
+title: useMenuService
+category: composables
+group: services
+---
+
+!!! tip "Long page"
+Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Grouping Menu Items](#grouping-menu-items), [Badges and Indicators](#badges-and-indicators), or [API Reference](#api-reference).
+
 # useMenuService
 
 Accesses the navigation menu service for adding, removing, and badging menu items in the application sidebar. The service supports a pre-registration pattern that allows modules to declare menu items before the service is initialized, and a grouping system that organizes items into collapsible sections.
diff --git a/framework/core/composables/useModificationTracker/useModificationTracker.docs.md b/framework/core/composables/useModificationTracker/useModificationTracker.docs.md
index 1e57c2e76..74f3b10db 100644
--- a/framework/core/composables/useModificationTracker/useModificationTracker.docs.md
+++ b/framework/core/composables/useModificationTracker/useModificationTracker.docs.md
@@ -1,3 +1,9 @@
+---
+title: useModificationTracker
+category: composables
+group: forms
+---
+
 # useModificationTracker
 
 Tracks deep changes to a value and reports whether it has been modified compared to its original (pristine) state. This is the core composable behind the "unsaved changes" detection pattern in vc-shell blades. It handles complex nested objects, arrays, and the common API quirk where `null`, `undefined`, and `""` should be treated as equivalent empty values.
diff --git a/framework/core/composables/useNotifications/useNotifications.docs.md b/framework/core/composables/useNotifications/useNotifications.docs.md
index 0a4d5fc13..9b7a31f8c 100644
--- a/framework/core/composables/useNotifications/useNotifications.docs.md
+++ b/framework/core/composables/useNotifications/useNotifications.docs.md
@@ -1,3 +1,9 @@
+---
+title: useNotifications
+category: composables
+group: notifications
+---
+
 # useNotifications
 
 Provides access to the push-notification system: reading notification history, filtering by type, marking as read, and registering handlers for real-time notifications. This composable wraps the Pinia-based `useNotificationStore` and adds type-based filtering and subscription management. It subscribes to specific notification types via the store's pub/sub system and automatically unsubscribes when the component scope is disposed.
diff --git a/framework/core/composables/usePermissions/usePermissions.docs.md b/framework/core/composables/usePermissions/usePermissions.docs.md
index 8e5f7eb1c..3c39ea36f 100644
--- a/framework/core/composables/usePermissions/usePermissions.docs.md
+++ b/framework/core/composables/usePermissions/usePermissions.docs.md
@@ -1,7 +1,16 @@
+---
+title: usePermissions
+category: composables
+group: user
+---
+
 # usePermissions
 
 Checks whether the current user has specific platform permissions. This composable reads the authenticated user's permission list and provides a `hasAccess` function for conditional UI rendering and access control. It is client-side only -- it does not enforce server-side authorization.
 
+!!! warning "Client-side only"
+`usePermissions` is a UI guard, not a security boundary. Always enforce authorization on the server side as well.
+
 ## When to Use
 
 - Conditionally show or hide UI elements (buttons, toolbar items, sections) based on the current user's permissions
diff --git a/framework/core/composables/usePlatformLocaleSync/usePlatformLocaleSync.docs.md b/framework/core/composables/usePlatformLocaleSync/usePlatformLocaleSync.docs.md
index 70b003f39..1178f23aa 100644
--- a/framework/core/composables/usePlatformLocaleSync/usePlatformLocaleSync.docs.md
+++ b/framework/core/composables/usePlatformLocaleSync/usePlatformLocaleSync.docs.md
@@ -1,3 +1,9 @@
+---
+title: usePlatformLocaleSync
+category: composables
+group: user
+---
+
 # usePlatformLocaleSync
 
 One-way reactive bridge from the VirtoCommerce platform's locale storage key (`NG_TRANSLATE_LANG_KEY`, set by AngularJS + angular-translate) to the shell's language service.
diff --git a/framework/core/composables/usePopup/usePopup.docs.md b/framework/core/composables/usePopup/usePopup.docs.md
index 11aea6271..89d2c4d25 100644
--- a/framework/core/composables/usePopup/usePopup.docs.md
+++ b/framework/core/composables/usePopup/usePopup.docs.md
@@ -1,7 +1,16 @@
+---
+title: usePopup
+category: composables
+group: notifications
+---
+
 # usePopup
 
 Programmatic popup management for modal dialogs. Returns methods to open confirmation, error, and info dialogs, as well as fully custom popup components with typed props and emits. Popups are rendered in a dedicated container at the app root level, ensuring they overlay all other content including blades and sidebars.
 
+!!! tip "Always await showConfirmation"
+`showConfirmation` returns a `Promise<boolean>`. Always `await` it before executing the guarded action, or the action will run before the user responds.
+
 ## When to Use
 
 - Show confirmation dialogs before destructive actions (delete, discard, bulk operations)
diff --git a/framework/core/composables/useResponsive/useResponsive.docs.md b/framework/core/composables/useResponsive/useResponsive.docs.md
index b84d9e2a3..3f1d0b790 100644
--- a/framework/core/composables/useResponsive/useResponsive.docs.md
+++ b/framework/core/composables/useResponsive/useResponsive.docs.md
@@ -1,3 +1,9 @@
+---
+title: useResponsive
+category: composables
+group: ui-state
+---
+
 # useResponsive
 
 Reactive breakpoint state for building responsive blade UIs. Returns refs that indicate the current viewport category (phone, tablet, mobile, desktop) and whether the device supports touch input. Replaces the legacy `$isMobile.value` global properties in templates and `inject(IsMobileKey)` in script setup with a single, consistent API.
@@ -53,12 +59,16 @@ Breakpoint thresholds: phone < 480px, tablet 480–1023px, desktop >= 1024px. Th
 
 Note: `isMobile` is the union of `isPhone` and `isTablet` — it covers all viewports below the desktop threshold.
 
+<!-- internal:start -->
+
 ## How It Works
 
 Under the hood, `useResponsive()` calls `inject()` for each breakpoint key (`IsMobileKey`, `IsDesktopKey`, etc.) with sensible defaults. The framework's root `VcApp` component provides these refs during app initialization using VueUse's `useBreakpoints`. Because the return values are the same `Ref<boolean>` instances provided at the app level, they are reactive and shared across all components.
 
 The defaults ensure the composable works even outside the VcApp provider tree (e.g., in unit tests or Storybook), defaulting to desktop mode.
 
+<!-- internal:end -->
+
 ## Recipe: Responsive Blade with Mobile Card Layout
 
 ```vue
diff --git a/framework/core/composables/useSettings/useSettings.docs.md b/framework/core/composables/useSettings/useSettings.docs.md
index cb86b44a1..5352aaf15 100644
--- a/framework/core/composables/useSettings/useSettings.docs.md
+++ b/framework/core/composables/useSettings/useSettings.docs.md
@@ -1,3 +1,9 @@
+---
+title: useSettings
+category: composables
+group: services
+---
+
 # useSettings
 
 Loads and manages UI customization settings (logo, title, avatar) from the platform's Settings API. Supports overriding defaults with custom values.
diff --git a/framework/core/composables/useSettingsMenu/useSettingsMenu.docs.md b/framework/core/composables/useSettingsMenu/useSettingsMenu.docs.md
index fd42f8cef..81e8a18ce 100644
--- a/framework/core/composables/useSettingsMenu/useSettingsMenu.docs.md
+++ b/framework/core/composables/useSettingsMenu/useSettingsMenu.docs.md
@@ -1,3 +1,9 @@
+---
+title: useSettingsMenu
+category: composables
+group: services
+---
+
 # useSettingsMenu
 
 Accesses the settings menu service for registering and managing items in the application settings sidebar.
diff --git a/framework/core/composables/useSidebarState/useSidebarState.docs.md b/framework/core/composables/useSidebarState/useSidebarState.docs.md
index aba2e483d..004456520 100644
--- a/framework/core/composables/useSidebarState/useSidebarState.docs.md
+++ b/framework/core/composables/useSidebarState/useSidebarState.docs.md
@@ -1,3 +1,9 @@
+---
+title: useSidebarState
+category: composables
+group: ui-state
+---
+
 # useSidebarState
 
 Controls the sidebar (left navigation panel) expansion, pinning, hover, and mobile menu state. This composable exposes a unified API for reading and toggling all sidebar states from any component within the VcApp tree. The sidebar has three independent dimensions: **pinned** (user explicitly locked it open, persisted to localStorage), **hover-expanded** (mouse is hovering over the collapsed sidebar on desktop), and **mobile menu** (overlay drawer on small screens). The derived `isExpanded` computed combines pinned and hover states for convenience.
@@ -61,6 +67,8 @@ const { isExpanded, isPinned, togglePin, openMenu, closeMenu } = useSidebarState
 | `openMenu`         | `() => void`               | Show the mobile menu overlay.                                                                                    |
 | `closeMenu`        | `() => void`               | Hide the mobile menu overlay.                                                                                    |
 
+<!-- internal:start -->
+
 ## Setup
 
 `provideSidebarState()` must be called once in VcApp's setup. It is idempotent -- if called multiple times in the same injection tree, it returns the existing instance. All descendant components then call `useSidebarState()` to access the shared state.
@@ -72,6 +80,8 @@ import { provideSidebarState } from "@vc-shell/framework";
 provideSidebarState();
 ```
 
+<!-- internal:end -->
+
 ## Recipe: Auto-Close Mobile Menu After Navigation
 
 ```vue
diff --git a/framework/core/composables/useSlowNetworkDetection/useSlowNetworkDetection.docs.md b/framework/core/composables/useSlowNetworkDetection/useSlowNetworkDetection.docs.md
index 0e7d63881..e3c64aa9c 100644
--- a/framework/core/composables/useSlowNetworkDetection/useSlowNetworkDetection.docs.md
+++ b/framework/core/composables/useSlowNetworkDetection/useSlowNetworkDetection.docs.md
@@ -1,3 +1,9 @@
+---
+title: useSlowNetworkDetection
+category: composables
+group: ui-state
+---
+
 # useSlowNetworkDetection
 
 Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 10 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`.
@@ -56,6 +62,8 @@ const { isSlowNetwork } = useSlowNetworkDetection();
 | `DISMISS_DELAY_MS`          | `3000`              | Delay before hiding the notification after recovery |
 | `SLOW_EFFECTIVE_TYPES`      | `["slow-2g", "2g"]` | Connection types flagged as slow                    |
 
+<!-- internal:start -->
+
 ## How It Works
 
 ### Channel 1: effectiveType (proactive)
@@ -73,6 +81,7 @@ The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequ
 3. If `isSlowNetwork` goes back to `true` within those 3 seconds → cancel dismiss, notification stays
 4. If the browser goes offline → immediately hide the slow notification (the offline notification takes over)
 5. If the browser comes back online and `isSlowNetwork` is still `true` → re-show
+<!-- internal:end -->
 
 ## Recipe: Custom Slow-Network Behavior in a Blade
 
diff --git a/framework/core/composables/useTheme/useTheme.docs.md b/framework/core/composables/useTheme/useTheme.docs.md
index eff8aa27c..8de6cfc7c 100644
--- a/framework/core/composables/useTheme/useTheme.docs.md
+++ b/framework/core/composables/useTheme/useTheme.docs.md
@@ -1,3 +1,9 @@
+---
+title: useTheme
+category: composables
+group: ui-state
+---
+
 # useTheme
 
 Manages color theme registration, switching, and persistence. Themes are applied via a `data-theme` attribute on `<html>`, and the active theme key is persisted to localStorage via `@vueuse/core`'s `useColorMode`. The composable maintains a global registry of theme definitions, supports runtime registration/unregistration from modules, and provides both explicit (`setTheme`) and sequential (`next`) theme switching. A default `"light"` theme is always registered out of the box.
@@ -63,6 +69,8 @@ next();
 | `key`  | `string` | Theme identifier                                                             |
 | `name` | `string` | Localized display name, resolved from `localizationKey` or capitalized `key` |
 
+<!-- internal:start -->
+
 ## How It Works
 
 1. **Registration**: Themes are stored in a module-level `Ref<ThemeDefinition[]>` array. `register()` appends new definitions (skipping duplicates), and `unregister()` removes by key.
@@ -72,6 +80,7 @@ next();
 3. **Reactivity**: A `watchEffect` syncs the cycle-list state to `useColorMode`'s mode whenever the active theme changes.
 
 4. **Localization**: Display names are resolved via `vue-i18n`'s `t()` function using the `localizationKey`. If no key is provided, the theme's `key` is capitalized with lodash.
+<!-- internal:end -->
 
 ## Recipe: Module That Registers a Theme on Install
 
diff --git a/framework/core/composables/useToolbar/useToolbar.docs.md b/framework/core/composables/useToolbar/useToolbar.docs.md
index df46d8c63..3827f3de5 100644
--- a/framework/core/composables/useToolbar/useToolbar.docs.md
+++ b/framework/core/composables/useToolbar/useToolbar.docs.md
@@ -1,3 +1,12 @@
+---
+title: useToolbar
+category: composables
+group: services
+---
+
+!!! tip "Long page"
+Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Updating Button State Dynamically](#updating-button-state-dynamically), [Visibility and Permissions](#visibility-and-permissions), or [API Reference](#api-reference).
+
 # useToolbar
 
 Manages toolbar buttons for blades. Each blade in the application has its own toolbar area at the top of the blade header. `useToolbar` provides a scoped API to register, update, and remove buttons within that toolbar. It automatically resolves the current blade context and cleans up registered items when the component unmounts.
diff --git a/framework/core/composables/useUser/useUser.docs.md b/framework/core/composables/useUser/useUser.docs.md
index fe0c654e0..244619a3b 100644
--- a/framework/core/composables/useUser/useUser.docs.md
+++ b/framework/core/composables/useUser/useUser.docs.md
@@ -1,3 +1,9 @@
+---
+title: useUser
+category: composables
+group: user
+---
+
 # useUser
 
 Shared composable providing read-only access to the current user's session state. Returns reactive user details, authentication status, and core session operations (load, sign out, get access token). This is the primary composable for user-related reads in regular blades and components. It deliberately exposes a narrow API surface -- no sign-in, password reset, or admin operations -- to encourage separation of concerns between user consumption and user management.
diff --git a/framework/core/composables/useUserManagement/useUserManagement.docs.md b/framework/core/composables/useUserManagement/useUserManagement.docs.md
index 08cb06870..c7f876c12 100644
--- a/framework/core/composables/useUserManagement/useUserManagement.docs.md
+++ b/framework/core/composables/useUserManagement/useUserManagement.docs.md
@@ -1,3 +1,10 @@
+---
+title: useUserManagement
+category: composables
+group: user
+internal: true
+---
+
 # useUserManagement
 
 Shared composable exposing the full user management API: sign-in, sign-out, password reset, token validation, and login type discovery. This composable extends the same internal logic as `useUser` but surfaces the administrative and authentication-flow methods that `useUser` intentionally hides. The separation ensures that regular blades only have access to read-only user state, while auth pages and admin screens get the full API.
diff --git a/framework/core/composables/useWebVitals/useWebVitals.docs.md b/framework/core/composables/useWebVitals/useWebVitals.docs.md
index b30a4ecaf..8398f211e 100644
--- a/framework/core/composables/useWebVitals/useWebVitals.docs.md
+++ b/framework/core/composables/useWebVitals/useWebVitals.docs.md
@@ -1,3 +1,9 @@
+---
+title: useWebVitals
+category: composables
+group: utilities
+---
+
 # useWebVitals
 
 Registers Core Web Vitals observers (FCP, LCP, CLS, INP, TTFB) and reports metrics via a callback. Core Web Vitals are Google's standardized set of real-user performance metrics that measure loading speed, interactivity, and visual stability. This composable wraps the `web-vitals` npm package and normalizes its output into a simple `{ name, value, rating }` shape. In development mode, metrics are logged to the console by default so you can catch performance regressions early without setting up external analytics.
diff --git a/framework/core/composables/useWidgets/useWidgets.docs.md b/framework/core/composables/useWidgets/useWidgets.docs.md
index 72c3a4778..50ad487c8 100644
--- a/framework/core/composables/useWidgets/useWidgets.docs.md
+++ b/framework/core/composables/useWidgets/useWidgets.docs.md
@@ -1,3 +1,9 @@
+---
+title: useWidgets
+category: composables
+group: services
+---
+
 # useWidgets
 
 Provides access to the `IWidgetService` singleton for managing blade widget registrations, activation state, and external widgets. This is the low-level composable for direct widget service interaction. It exposes the full widget lifecycle API: registering widgets to specific blades, querying registered widgets, tracking active widget state, and managing external (cross-module) widget registrations.
@@ -59,6 +65,8 @@ None.
 | `registerWidget(widget, bladeId)`      | Global pre-registration. Widgets registered this way are picked up when `provideWidgetService()` creates the service. Use in module `install()`.       |
 | `registerExternalWidget(registration)` | Global pre-registration for cross-module widgets. These widgets are rendered in blades owned by other modules.                                         |
 
+<!-- internal:start -->
+
 ## How It Works
 
 The widget system has three layers:
@@ -71,6 +79,8 @@ The widget system has three layers:
 
 The service tracks active widgets (which widget is currently expanded/focused) separately from registrations, enabling the widget panel to highlight the active widget and call its update function.
 
+<!-- internal:end -->
+
 ## Recipe: Pre-Registering a Widget from a Module
 
 ```typescript
diff --git a/framework/core/directives/autofocus/autofocus.docs.md b/framework/core/directives/autofocus/autofocus.docs.md
index 27b1e1790..e92ec2930 100644
--- a/framework/core/directives/autofocus/autofocus.docs.md
+++ b/framework/core/directives/autofocus/autofocus.docs.md
@@ -1,3 +1,10 @@
+---
+title: v-autofocus
+category: reference
+group: api/directives
+slug: v-autofocus
+---
+
 # v-autofocus Directive
 
 Focuses an element when it is mounted, conditionally based on the binding value.
diff --git a/framework/core/directives/loading/loading.docs.md b/framework/core/directives/loading/loading.docs.md
index d15f8cfc7..fbe4991e1 100644
--- a/framework/core/directives/loading/loading.docs.md
+++ b/framework/core/directives/loading/loading.docs.md
@@ -1,3 +1,10 @@
+---
+title: v-loading
+category: reference
+group: api/directives
+slug: v-loading
+---
+
 # v-loading Directive
 
 Displays a loading overlay with a spinner on any element. Supports size variants, custom color, blur backdrop, fullscreen mode, and z-index control.
diff --git a/framework/core/notifications/notifications.docs.md b/framework/core/notifications/notifications.docs.md
index d6234d7a0..3541ada4b 100644
--- a/framework/core/notifications/notifications.docs.md
+++ b/framework/core/notifications/notifications.docs.md
@@ -1,3 +1,13 @@
+---
+title: Notifications
+category: plugins
+group: root
+slug: notifications
+---
+
+!!! info "Two-level architecture"
+Level 1 (module-level, always-on toasts) and Level 2 (blade-level, auto-cleanup subscriptions).
+
 # Notification System
 
 Centralized push notification handling for the vc-shell framework. Provides a two-level architecture: **Level 1** (module-level, always-on toasts and dropdown) and **Level 2** (blade-level, scoped subscriptions that auto-cleanup on unmount).
@@ -234,3 +244,14 @@ await store.markAllAsRead(); // optimistic update with rollback on failure
 - `framework/injection-keys.ts` -- `NotificationStoreKey`, `NotificationTemplatesKey`
 - `framework/shared/components/notifications/` -- Notification dropdown UI
 - `framework/core/api/platform.ts` -- `PushNotification`, `PushNotificationClient`
+
+<!-- internal:start -->
+
+## Internal Files
+
+- `framework/core/notifications/store.ts` -- `NotificationStore` implementation
+- `framework/core/notifications/toast-controller.ts` -- Toast lifecycle management
+- `framework/core/notifications/composables/` -- `useNotificationStore`, `useBladeNotifications`, `useNotificationContext`, `useBroadcastFilter`
+- `framework/core/notifications/types.ts` -- All notification type definitions
+
+<!-- internal:end -->
diff --git a/framework/core/plugins/ai-agent/ai-agent.docs.md b/framework/core/plugins/ai-agent/ai-agent.docs.md
index 9940b94d2..0cc25cfb7 100644
--- a/framework/core/plugins/ai-agent/ai-agent.docs.md
+++ b/framework/core/plugins/ai-agent/ai-agent.docs.md
@@ -1,3 +1,10 @@
+---
+title: AI Agent
+category: plugins
+group: root
+slug: ai-agent
+---
+
 # AI Agent Plugin
 
 Integrates an AI assistant panel (chatbot iframe) into the vc-shell application. Provides blade-aware context passing, bidirectional postMessage communication, and preview/apply workflows.
diff --git a/framework/core/plugins/extension-points/extension-points.docs.md b/framework/core/plugins/extension-points/extension-points.docs.md
index 772083f36..46f132f97 100644
--- a/framework/core/plugins/extension-points/extension-points.docs.md
+++ b/framework/core/plugins/extension-points/extension-points.docs.md
@@ -1,3 +1,13 @@
+---
+title: Extension Points
+category: plugins
+group: root
+slug: extension-points
+---
+
+!!! tip "Navigation"
+This page is long. Use the [Table of Contents](#table-of-contents) to jump to the section you need.
+
 # Extension Points Plugin
 
 Extension points enable **cross-module UI composition** without direct imports. One module declares a named slot ("I accept plugins here"), and other modules inject components into that slot -- at any time, in any order. The system is fully reactive and order-independent.
diff --git a/framework/core/plugins/global-error-handler/global-error-handler.docs.md b/framework/core/plugins/global-error-handler/global-error-handler.docs.md
index 8e49f49f6..25da03b28 100644
--- a/framework/core/plugins/global-error-handler/global-error-handler.docs.md
+++ b/framework/core/plugins/global-error-handler/global-error-handler.docs.md
@@ -1,3 +1,10 @@
+---
+title: Global Error Handler
+category: plugins
+group: root
+slug: global-error-handler
+---
+
 # Global Error Handler Plugin
 
 Catches unhandled errors across the application and displays user-facing toast notifications. Covers Vue component errors, unhandled promise rejections, and uncaught JavaScript errors.
diff --git a/framework/core/plugins/i18n/i18n.docs.md b/framework/core/plugins/i18n/i18n.docs.md
index 7be94215f..55888267e 100644
--- a/framework/core/plugins/i18n/i18n.docs.md
+++ b/framework/core/plugins/i18n/i18n.docs.md
@@ -1,3 +1,13 @@
+---
+title: Internationalization
+category: plugins
+group: root
+slug: i18n
+---
+
+!!! tip "Module integration"
+Modules provide translations via `defineAppModule({ locales })` — no direct plugin installation needed.
+
 # i18n Plugin
 
 Vue-i18n integration for the vc-shell framework. Provides a pre-configured i18n instance used by all modules for localization.
diff --git a/framework/core/plugins/modularity/modularity.docs.md b/framework/core/plugins/modularity/modularity.docs.md
index c39ece698..e8b8e6f76 100644
--- a/framework/core/plugins/modularity/modularity.docs.md
+++ b/framework/core/plugins/modularity/modularity.docs.md
@@ -1,3 +1,13 @@
+---
+title: Modularity
+category: plugins
+group: root
+slug: modularity
+---
+
+!!! tip "Navigation"
+This page is long. Use the [Table of Contents](#table-of-contents) to jump to the section you need.
+
 # Modularity Plugin
 
 The modularity plugin is the backbone of every vc-shell application. It defines how features are packaged as **modules**, how those modules are registered at runtime, and how they integrate with the framework's blade navigation, localization, menu, and notification systems.
diff --git a/framework/core/plugins/permissions/permissions.docs.md b/framework/core/plugins/permissions/permissions.docs.md
index 61246fa18..88b783909 100644
--- a/framework/core/plugins/permissions/permissions.docs.md
+++ b/framework/core/plugins/permissions/permissions.docs.md
@@ -1,4 +1,11 @@
-# Permissions Plugin
+---
+title: Permissions
+category: plugins
+group: root
+slug: permissions
+---
+
+# Permissions
 
 Permission-based access control plugin. Exposes a global `$hasAccess` helper for checking user permissions throughout the application.
 
diff --git a/framework/core/plugins/signalR/signalR.docs.md b/framework/core/plugins/signalR/signalR.docs.md
index 8c72fbc1c..505c00e18 100644
--- a/framework/core/plugins/signalR/signalR.docs.md
+++ b/framework/core/plugins/signalR/signalR.docs.md
@@ -1,3 +1,10 @@
+---
+title: SignalR
+category: plugins
+group: root
+slug: signalr
+---
+
 # SignalR Plugin
 
 Real-time push notification transport via ASP.NET SignalR. Connects to the platform's `/pushNotificationHub` and routes incoming messages to the notification store.
diff --git a/framework/core/plugins/validation/validation.docs.md b/framework/core/plugins/validation/validation.docs.md
index e07297f87..b182376d4 100644
--- a/framework/core/plugins/validation/validation.docs.md
+++ b/framework/core/plugins/validation/validation.docs.md
@@ -1,3 +1,13 @@
+---
+title: Validation
+category: plugins
+group: root
+slug: validation
+---
+
+!!! tip "Zero setup"
+All vee-validate standard rules plus custom vc-shell rules are registered automatically — no per-component imports needed.
+
 # Validation Plugin
 
 Form validation integration using vee-validate. Registers all standard validation rules plus custom vc-shell rules for image dimensions, file weight, date comparisons, and BigInt safety.
diff --git a/framework/core/services/services.docs.md b/framework/core/services/services.docs.md
index 4230553ba..39c31d1bb 100644
--- a/framework/core/services/services.docs.md
+++ b/framework/core/services/services.docs.md
@@ -1,3 +1,10 @@
+---
+title: Services
+category: composables
+group: services
+placement: index
+---
+
 # Core Services
 
 Singleton service layer for registering and querying application-level entities: menu items, widgets, toolbar buttons, dashboard widgets, settings panels, app-bar items, and more.
@@ -11,6 +18,8 @@ Every service follows the same architecture:
 3. **Module-level helper** (e.g., `addMenuItem()`, `registerWidget()`) -- lets modules register items at import time, before the Vue app mounts.
 4. **Corresponding `use*` composable** (in `core/composables/`) -- injects the service instance via provide/inject for use inside components.
 
+<!-- internal:start -->
+
 ### Internal Building Blocks (`_internal/`)
 
 | Helper                      | Purpose                                                                                                                           |
@@ -19,6 +28,8 @@ Every service follows the same architecture:
 | `createBladeScopedRegistry` | Reactive `Map<bladeId, Item[]>` with register/unregister/update/clear. Used by WidgetService and ToolbarService.                  |
 | `createSimpleMapRegistry`   | Reactive `Map<id, Item>` with sorted computed output. Used by SettingsMenuService and AppBarMenuService.                          |
 
+<!-- internal:end -->
+
 ## Services
 
 | Service                        | Factory                              | Module-level API                                                | Key Type               |
@@ -78,8 +89,12 @@ removeMenuBadge("OrdersList");
 - `MenuService` builds a tree from flat items: items with `group` or `groupConfig` are nested under group nodes, sorted by `priority`.
 - `DashboardService` accepts a `hasAccess` callback for permission-based widget filtering.
 
-## Related
+<!-- internal:start -->
+
+## Related (internal paths)
 
 - `framework/core/composables/` -- `useMenu`, `useToolbar`, `useWidgets`, `useDashboard`, etc.
 - `framework/core/services/_internal/` -- shared registry and bus implementations
 - `framework/core/plugins/` -- services are created and provided during plugin installation
+
+<!-- internal:end -->
diff --git a/framework/core/types/types.docs.md b/framework/core/types/types.docs.md
index 2a9d5c597..efe8daac5 100644
--- a/framework/core/types/types.docs.md
+++ b/framework/core/types/types.docs.md
@@ -1,3 +1,10 @@
+---
+title: Core Types
+category: reference
+group: api
+slug: types-core
+---
+
 # Core Types
 
 Shared TypeScript interfaces and types used across the vc-shell framework for validation, menus, toolbars, tables, assets, and service abstractions.
diff --git a/framework/core/utilities/date/date-utilities.docs.md b/framework/core/utilities/date/date-utilities.docs.md
index 26703edcc..4ff8df904 100644
--- a/framework/core/utilities/date/date-utilities.docs.md
+++ b/framework/core/utilities/date/date-utilities.docs.md
@@ -1,3 +1,10 @@
+---
+title: Date Utilities
+category: reference
+group: api
+slug: date-utilities
+---
+
 # Date Utilities
 
 Pure functions for date formatting, relative time display, and Moment.js-to-date-fns format conversion. Built on `date-fns` with locale-aware output.
diff --git a/framework/core/utilities/shared-utilities.docs.md b/framework/core/utilities/shared-utilities.docs.md
index 2bc11df44..a51aaaf5a 100644
--- a/framework/core/utilities/shared-utilities.docs.md
+++ b/framework/core/utilities/shared-utilities.docs.md
@@ -1,3 +1,10 @@
+---
+title: Shared Utilities
+category: reference
+group: api
+slug: shared-utilities
+---
+
 # Shared Utilities
 
 Helper functions and TypeScript type utilities used across the shared layer of the framework.
diff --git a/framework/core/utilities/thumbnail/thumbnail.docs.md b/framework/core/utilities/thumbnail/thumbnail.docs.md
index c89117e63..f5fb76604 100644
--- a/framework/core/utilities/thumbnail/thumbnail.docs.md
+++ b/framework/core/utilities/thumbnail/thumbnail.docs.md
@@ -1,3 +1,10 @@
+---
+title: Thumbnail Utility
+category: reference
+group: api
+slug: thumbnail
+---
+
 # Thumbnail URL Utility
 
 Transforms full-size image URLs into thumbnail variants by appending size suffixes before the file extension. VirtoCommerce backend generates thumbnails automatically with these suffixes.
diff --git a/framework/core/utilities/utilities.docs.md b/framework/core/utilities/utilities.docs.md
index 005d36b3d..7adde83b6 100644
--- a/framework/core/utilities/utilities.docs.md
+++ b/framework/core/utilities/utilities.docs.md
@@ -1,3 +1,10 @@
+---
+title: Utilities Overview
+category: reference
+group: api
+slug: utilities-overview
+---
+
 # Framework Utilities
 
 Utility functions exported from `@vc-shell/framework` via `core/utilities/index.ts`.
diff --git a/framework/injection-keys.docs.md b/framework/injection-keys.docs.md
index 45d392d48..ada87b2c2 100644
--- a/framework/injection-keys.docs.md
+++ b/framework/injection-keys.docs.md
@@ -1,3 +1,10 @@
+---
+title: Injection Keys
+category: reference
+group: api
+slug: injection-keys
+---
+
 # Injection Keys
 
 Centralized Vue `InjectionKey` symbols for the vc-shell framework's provide/inject dependency injection system. All keys are typed via `InjectionKey<T>` for full TypeScript safety.
@@ -76,6 +83,8 @@ This centralized approach has several advantages:
 | `IsTabletKey`  | `Ref<boolean>` | Tablet breakpoint      |
 | `IsTouchKey`   | `boolean`      | Touch device detection |
 
+<!-- internal:start -->
+
 ### Legacy Aliases (Deprecated)
 
 | Deprecated          | Use Instead          |
@@ -96,6 +105,8 @@ These keys existed in v1.2.3 but have been removed from the framework entirely.
 | `NotificationTemplatesSymbol` | Template system replaced by `NotificationStoreKey` + `useBladeNotifications()` |
 | `GlobalSearchKey`             | Internal concern now — no public replacement                                   |
 
+<!-- internal:end -->
+
 ## Usage Examples
 
 ### Injecting a service in a component
diff --git a/framework/modules/assets-manager/assets-manager.docs.md b/framework/modules/assets-manager/assets-manager.docs.md
index b86c8d22a..d543883f2 100644
--- a/framework/modules/assets-manager/assets-manager.docs.md
+++ b/framework/modules/assets-manager/assets-manager.docs.md
@@ -1,3 +1,10 @@
+---
+title: Assets Manager
+category: reference
+group: modules
+slug: assets-manager
+---
+
 # Assets Manager Module
 
 A built-in blade module for managing file assets (images, documents, archives). Provides upload, delete, reorder, and preview functionality via a table-based UI.
@@ -32,17 +39,27 @@ The blade reads its configuration from `options` via `useBlade<AssetsManagerOpti
 
 ## Usage
 
-Open the Assets Manager as a child blade:
+The canonical pattern is to bind the manager to a writable `computed` over a field of the parent entity, so that uploads/removes/reorders propagate back into the form. `confirmRemove` is wired to the framework's popup service rather than `window.confirm`.
 
 ```typescript
-import { markRaw } from "vue";
-import { useBlade, useAssetsManager } from "@vc-shell/framework";
+import { computed, markRaw } from "vue";
+import { useBlade, useAssetsManager, usePopup } from "@vc-shell/framework";
 
 const { openBlade } = useBlade();
+const { showConfirmation } = usePopup();
+
+// Two-way binding: the manager mutates `productAssets.value`, which writes
+// straight back to `item.value.productData.assets`.
+const productAssets = computed({
+  get: () => item.value?.productData?.assets ?? [],
+  set: (val) => {
+    if (item.value?.productData) item.value.productData.assets = val;
+  },
+});
 
-const assetsManager = useAssetsManager(product.assets, {
-  uploadPath: () => `/catalog/${product.id}`,
-  confirmRemove: () => confirm("Delete selected assets?"),
+const assetsManager = useAssetsManager(productAssets, {
+  uploadPath: () => `/catalog/${item.value?.id}`,
+  confirmRemove: () => showConfirmation("Are you sure you want to delete the selected assets?"),
 });
 
 openBlade({
@@ -54,7 +71,6 @@ openBlade({
     // manager.items.value and manager.loading.value access.
     manager: markRaw(assetsManager),
     disabled: !canEdit.value,
-    hiddenFields: ["sortOrder"],
   },
 });
 ```
@@ -66,8 +82,8 @@ openBlade({
 - **Delete**: Toolbar delete button (requires selection) and per-row action button.
 - **Reorder**: Drag-and-drop row reordering when not in readonly mode.
 - **Detail view**: Clicking a row opens an `AssetsDetails` child blade for single-asset editing.
-- **Mobile**: Responsive card layout for mobile viewports.
-- **Empty state**: Shows upload prompt when no assets exist (or "No assets" in readonly mode).
+- **Non-image assets**: Files without an image extension render a colored badge with the uppercased extension (`PDF`, `DOCX`, `ZIP`, ...) instead of a thumbnail.
+- **Empty state**: Shows upload prompt when no assets exist; the empty-state action button opens the file picker.
 
 ## Toolbar
 
@@ -81,11 +97,72 @@ openBlade({
 - **Always use `markRaw()` when passing manager through blade options.** Blade descriptors are stored in `ref<BladeDescriptor[]>()`, which creates a deep reactive proxy. Vue auto-unwraps `Ref` values inside reactive objects, so `manager.items` would become a plain array instead of `Ref<AssetLike[]>` — breaking `.value` access. `markRaw()` prevents this by telling Vue not to make the manager reactive.
 - The `manager` object (from `useAssetsManager()`) owns the reactive asset list and all mutation methods. The blade reads `manager.items` and calls `manager.upload()`, `manager.remove()`, `manager.removeMany()`, `manager.reorder()`, and `manager.updateItem()`.
 - The `disabled` prop makes the entire blade readonly: no upload, no delete, no reorder.
-- Asset thumbnails use `isImage()` from shared utilities to determine if an image preview or a file-type icon should be shown.
+- Asset thumbnails use `isImage()` from `@core/utilities/assets` to decide between an image preview (`VcImage`) and a colored extension badge (`getExtensionColor` + `getExtensionLabel`).
 - The module uses `useBlade()` internally to open the detail sub-blade.
+- The `manager` instance can be reused as a `useBladeWidgets` badge source — its `items.value.length` updates reactively as uploads/removes happen inside the blade, so a parent widget showing the asset count refreshes without an extra round-trip.
+
+## Recipes
+
+### Open from a blade widget
+
+Most callers don't open `AssetsManager` directly — they expose it as one of the parent blade's widgets. The widget shows the asset count as a live badge and opens the manager on click. The manager is created once per parent blade and reused across openings.
+
+```typescript
+import { computed, markRaw, type Ref, type ComputedRef } from "vue";
+import { useBlade, useBladeWidgets, useAssetsManager, usePopup } from "@vc-shell/framework";
+
+interface Entity {
+  id?: string;
+  productData?: { assets?: Asset[] };
+}
+
+export function useEntityWidgets(opts: { item: Ref<Entity | undefined>; disabled: ComputedRef<boolean>; isVisible: ComputedRef<boolean> }) {
+  const { item, disabled, isVisible } = opts;
+  const { openBlade } = useBlade();
+  const { showConfirmation } = usePopup();
+
+  const entityAssets = computed({
+    get: () => item.value?.productData?.assets ?? [],
+    set: (val) => {
+      if (item.value?.productData) item.value.productData.assets = val;
+    },
+  });
+
+  const assetsManager = useAssetsManager(entityAssets, {
+    uploadPath: () => `/catalog/${item.value?.id}`,
+    confirmRemove: () => showConfirmation("Are you sure you want to delete the selected assets?"),
+  });
+
+  const assetsCount = computed(() => entityAssets.value.length);
+
+  return useBladeWidgets([
+    {
+      id: "AssetsWidget",
+      icon: "lucide-file",
+      title: "WIDGETS.ASSETS",
+      badge: assetsCount,
+      isVisible,
+      onClick: () =>
+        openBlade({
+          name: "AssetsManager",
+          options: {
+            manager: markRaw(assetsManager),
+            disabled: disabled.value,
+          },
+        }),
+    },
+  ]);
+}
+```
+
+Key points:
+
+- `useAssetsManager` is invoked once at widget-setup time, not inside `onClick`. Recreating it per click would lose pending state and break optimistic updates.
+- `disabled.value` is unwrapped at click time. Passing the raw `ComputedRef` would work too, but the blade reads `options.value?.disabled` as a plain value.
+- `assetsCount` reads from the source array (not from `assetsManager.items`), but both stay in sync because the manager mutates the same array via the setter.
 
 ## Related
 
 - `framework/core/composables/useAssetsManager/` -- `useAssetsManager`, `AssetLike`, `UseAssetsManagerReturn`
-- `framework/shared/utilities/assets.ts` -- `isImage`, `getFileThumbnail`, `readableSize`
-- `framework/core/utilities/date/` -- `formatDateRelative` for creation dates
+- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel`
+- `framework/modules/assets/components/assets-details/` -- `AssetsDetails` child blade opened on row click
diff --git a/framework/modules/assets/assets-details.docs.md b/framework/modules/assets/assets-details.docs.md
new file mode 100644
index 000000000..260b4c7c9
--- /dev/null
+++ b/framework/modules/assets/assets-details.docs.md
@@ -0,0 +1,123 @@
+---
+title: Assets Module
+category: reference
+group: modules
+slug: assets
+---
+
+# Assets Details Module
+
+A built-in child blade for editing a single asset's metadata: display name, alt text (images only), and description. Opened by `AssetsManager` when the user clicks a table row, but also usable standalone from any parent blade that needs single-asset editing.
+
+## Overview
+
+The blade reads an `AssetLike` instance from `options.asset`, exposes a form pre-populated from it, and delegates persistence back to the caller through two callbacks (`assetEditHandler`, `assetRemoveHandler`). The blade itself never mutates the original asset and never talks to the network — the caller decides what saving and removing means.
+
+The module is registered as `AssetsDetailsModule` and exposes the `AssetsDetails` blade (registered globally under the name `"AssetsDetails"`).
+
+## Module Registration
+
+```typescript
+import { AssetsDetailsModule } from "@vc-shell/framework";
+
+// Registered automatically when the framework loads
+// Exposes: AssetsDetails blade component
+```
+
+## Options (via `useBlade`)
+
+The blade reads its configuration from `options` via `useBlade<AssetsDetailsOptions>()` (not props):
+
+| Option               | Type                                          | Description                                                                                                                                   |
+| -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `asset`              | `AssetLike`                                   | The asset to edit. The blade clones it into local state — the source object is never mutated until `assetEditHandler` is called.              |
+| `disabled`           | `boolean?`                                    | When true, every input is read-only and the toolbar Save/Delete buttons are disabled.                                                         |
+| `hiddenFields`       | `string[]?`                                   | Field names to hide. Supported values: `"name"`, `"altText"`, `"description"`. The header (preview, size, created date, URL) is always shown. |
+| `assetEditHandler`   | `(asset: AssetLike) => void \| Promise<void>` | Called by the toolbar Save button with the edited copy. The blade closes itself after the handler resolves.                                   |
+| `assetRemoveHandler` | `(asset: AssetLike) => Promise<void>`         | Called by the toolbar Delete button. The blade closes itself after the handler resolves.                                                      |
+
+## Usage
+
+### Direct invocation
+
+```typescript
+import { useBlade } from "@vc-shell/framework";
+
+const { openBlade } = useBlade();
+
+openBlade({
+  name: "AssetsDetails",
+  options: {
+    asset: selectedAsset,
+    disabled: !canEdit.value,
+    hiddenFields: ["altText"],
+    assetEditHandler: async (edited) => {
+      await api.updateAsset(edited);
+    },
+    assetRemoveHandler: async (asset) => {
+      await api.deleteAsset(asset.id);
+    },
+  },
+});
+```
+
+### Used by AssetsManager
+
+When `AssetsManager` opens this blade on row click, it wires the manager's mutation methods into the handlers automatically:
+
+```typescript
+// inside AssetsManager
+openBlade({
+  name: "AssetsDetails",
+  options: {
+    asset,
+    disabled: readonly.value,
+    hiddenFields: options.value?.hiddenFields,
+    assetEditHandler: (asset) => manager.updateItem(asset),
+    assetRemoveHandler: (asset) => manager.remove(asset),
+  },
+});
+```
+
+## Header
+
+The header is always rendered above the editable form and is not configurable through `hiddenFields`:
+
+| Element      | Source                                                                                             |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| Preview      | `VcImage` thumbnail for image extensions (png/jpg/jpeg/svg/gif), colored extension badge otherwise |
+| Size         | `readableSize(asset.size)` — formatted as `KB`/`MB`/`GB`                                           |
+| Created date | `asset.createdDate` rendered with `type="date-ago"`                                                |
+| URL          | `asset.url` displayed as a copyable link with `asset.name` as the visible label                    |
+
+## Form fields
+
+All fields are bound to a local clone of `asset`. They can be hidden individually via `hiddenFields`.
+
+| Field         | Visibility                                        | Notes                                                                                                                          |
+| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `name`        | Hidden if `hiddenFields` includes `"name"`        | Required. Edits the **base name only** — the original extension is preserved on save (e.g. editing `report.pdf` keeps `.pdf`). |
+| `altText`     | Image assets only; hide via `"altText"`           | Plain string. Shown only when `asset.typeId === "Image"`.                                                                      |
+| `description` | Hidden if `hiddenFields` includes `"description"` | Multiline textarea.                                                                                                            |
+
+## Toolbar
+
+| Button | Disabled condition                                                                                                  | Action                                                      |
+| ------ | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| Save   | `disabled === true`, the form is invalid, or the form is not dirty (vee-validate `useIsFormValid`/`useIsFormDirty`) | `await assetEditHandler(editedAsset)`, then `closeSelf()`   |
+| Delete | `disabled === true`                                                                                                 | `await assetRemoveHandler(editedAsset)`, then `closeSelf()` |
+
+## Tips
+
+- **Extension is locked.** The `name` input only edits the base name; the original extension is reattached on save. Renaming `photo.png` to `cover` produces `cover.png`.
+- **Required name validation** uses vee-validate's `required` rule. The Save button stays disabled until validation passes.
+- **`assetEditHandler`** is invoked with the edited clone — the original `options.asset` reference is never mutated. Callers should treat the argument as the new state.
+- **`disabled` makes the blade fully read-only:** inputs are disabled and toolbar Save/Delete are disabled regardless of dirtiness.
+- **`hiddenFields` does not enforce required-ness.** Hiding `"name"` skips the validated `<Field>`, so the Save button only depends on form dirtiness.
+
+## Related
+
+- `framework/modules/assets-manager/` -- parent `AssetsManager` blade that opens `AssetsDetails` on row click
+- `framework/core/composables/useAssetsManager/` -- `AssetLike` type definition
+- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel`
+- `framework/ui/components/molecules/vc-field/` -- `VcField` used by the header for size/date/url
diff --git a/framework/shell/_internal/popup/common/popup-common.docs.md b/framework/shell/_internal/popup/common/popup-common.docs.md
index 8d2d5abb3..0bb72044e 100644
--- a/framework/shell/_internal/popup/common/popup-common.docs.md
+++ b/framework/shell/_internal/popup/common/popup-common.docs.md
@@ -1,3 +1,10 @@
+---
+title: PopupCommon
+category: composables
+group: utilities
+internal: true
+---
+
 # Popup Common Components
 
 Pre-configured popup variants for warning, error, and info dialogs. Built on a shared `VcPopupBase` component that wraps the `VcPopup` organism.
diff --git a/framework/shell/auth/ChangePasswordPage/change-password-page.docs.md b/framework/shell/auth/ChangePasswordPage/change-password-page.docs.md
index b464de24c..ddb9ffd92 100644
--- a/framework/shell/auth/ChangePasswordPage/change-password-page.docs.md
+++ b/framework/shell/auth/ChangePasswordPage/change-password-page.docs.md
@@ -1,3 +1,10 @@
+---
+title: ChangePasswordPage
+category: composables
+group: utilities
+internal: true
+---
+
 # ChangePasswordPage
 
 Change password page with current, new, and confirm password fields. Supports a `forced` mode for expired passwords that displays an info banner and is triggered by post-login redirect. This full-page variant is used when the user must change their password before accessing the application (e.g., expired password policy). For voluntary password changes from within the app, the `ChangePasswordButton` in the settings menu opens a popup instead.
diff --git a/framework/shell/auth/ForgotPasswordPage/forgot-password-page.docs.md b/framework/shell/auth/ForgotPasswordPage/forgot-password-page.docs.md
index f1e8c2fda..77cb8843b 100644
--- a/framework/shell/auth/ForgotPasswordPage/forgot-password-page.docs.md
+++ b/framework/shell/auth/ForgotPasswordPage/forgot-password-page.docs.md
@@ -1,3 +1,10 @@
+---
+title: ForgotPasswordPage
+category: composables
+group: utilities
+internal: true
+---
+
 # ForgotPasswordPage
 
 Password recovery page where the user enters their email to receive a reset link. Shows a masked-email confirmation on success. This page is part of the standard authentication flow in vc-shell and handles the first step of password recovery: collecting the user's email address and dispatching a reset email through the platform API.
diff --git a/framework/shell/auth/InvitePage/invite-page.docs.md b/framework/shell/auth/InvitePage/invite-page.docs.md
index 783c61a48..adddfd273 100644
--- a/framework/shell/auth/InvitePage/invite-page.docs.md
+++ b/framework/shell/auth/InvitePage/invite-page.docs.md
@@ -1,3 +1,10 @@
+---
+title: InvitePage
+category: composables
+group: utilities
+internal: true
+---
+
 # InvitePage
 
 Invitation acceptance page where an invited user sets their password. Validates the invitation token on mount, displays the pre-filled email, and provides password/confirm fields. On successful acceptance, the user is automatically signed in and redirected to the main application. This page is the final step in the user invitation flow initiated from the VirtoCommerce Platform admin.
diff --git a/framework/shell/auth/LoginPage/login-page.docs.md b/framework/shell/auth/LoginPage/login-page.docs.md
index ab90dcded..e3a6c1ad3 100644
--- a/framework/shell/auth/LoginPage/login-page.docs.md
+++ b/framework/shell/auth/LoginPage/login-page.docs.md
@@ -1,3 +1,10 @@
+---
+title: LoginPage
+category: composables
+group: utilities
+internal: true
+---
+
 # LoginPage
 
 Full-page login screen with username/password form, SSO external provider support, and forgot-password navigation. Wraps `VcAuthLayout` and uses `useUserManagement` for authentication. This is the primary entry point for user authentication in vc-shell applications, supporting both standard credential-based login and SSO/external provider authentication.
diff --git a/framework/shell/auth/ResetPasswordPage/reset-password-page.docs.md b/framework/shell/auth/ResetPasswordPage/reset-password-page.docs.md
index 36aa3bbce..fa50f475f 100644
--- a/framework/shell/auth/ResetPasswordPage/reset-password-page.docs.md
+++ b/framework/shell/auth/ResetPasswordPage/reset-password-page.docs.md
@@ -1,3 +1,10 @@
+---
+title: ResetPasswordPage
+category: composables
+group: utilities
+internal: true
+---
+
 # ResetPasswordPage
 
 Password reset page reached via an email link containing a token. Validates the token on mount, then shows password and confirm-password fields. On success, the user is automatically signed in and redirected to the main application. This page is the second step of the password recovery flow, following the `ForgotPasswordPage` which dispatches the reset email.
diff --git a/framework/shell/auth/sign-in/sign-in.docs.md b/framework/shell/auth/sign-in/sign-in.docs.md
index 4f536dfda..4543e1df8 100644
--- a/framework/shell/auth/sign-in/sign-in.docs.md
+++ b/framework/shell/auth/sign-in/sign-in.docs.md
@@ -1,3 +1,10 @@
+---
+title: SignIn
+category: composables
+group: utilities
+internal: true
+---
+
 # SignIn (External Providers)
 
 Components and composable for SSO / external authentication provider integration. Renders provider buttons on the login page and handles the external sign-in redirect flow. This module supports any OAuth2/OpenID Connect provider configured on the VirtoCommerce Platform (Google, Azure AD, ADFS, Okta, etc.) and provides a clean abstraction over the redirect-based authentication flow.
diff --git a/framework/shell/components/change-password-button/change-password-button.docs.md b/framework/shell/components/change-password-button/change-password-button.docs.md
index 637872fda..36078d427 100644
--- a/framework/shell/components/change-password-button/change-password-button.docs.md
+++ b/framework/shell/components/change-password-button/change-password-button.docs.md
@@ -1,3 +1,10 @@
+---
+title: ChangePasswordButton
+category: composables
+group: utilities
+internal: true
+---
+
 # ChangePasswordButton
 
 Settings menu action that opens the change-password popup through the popup handler system. This component bridges the settings menu and the password change form: it injects `CloseSettingsMenuKey` to dismiss the parent menu before showing the password popup, ensuring a clean transition. The popup itself renders a form with current password, new password, and confirm password fields, with real-time password policy validation.
diff --git a/framework/shell/components/change-password/change-password.docs.md b/framework/shell/components/change-password/change-password.docs.md
index ca79e206b..713c85dcf 100644
--- a/framework/shell/components/change-password/change-password.docs.md
+++ b/framework/shell/components/change-password/change-password.docs.md
@@ -1,3 +1,10 @@
+---
+title: ChangePassword
+category: composables
+group: utilities
+internal: true
+---
+
 # Change Password Component
 
 A modal dialog for changing the current user's password, with real-time validation and forced-change support.
diff --git a/framework/shell/components/error-interceptor/error-interceptor.docs.md b/framework/shell/components/error-interceptor/error-interceptor.docs.md
index 0662c7d4f..7466d01b7 100644
--- a/framework/shell/components/error-interceptor/error-interceptor.docs.md
+++ b/framework/shell/components/error-interceptor/error-interceptor.docs.md
@@ -1,3 +1,10 @@
+---
+title: ErrorInterceptor
+category: composables
+group: utilities
+internal: true
+---
+
 # Error Interceptor
 
 A renderless component that captures Vue `onErrorCaptured` errors and surfaces them to child slots or the blade error banner.
diff --git a/framework/shell/components/language-selector/language-selector.docs.md b/framework/shell/components/language-selector/language-selector.docs.md
index 30ae97560..03c2c0dd6 100644
--- a/framework/shell/components/language-selector/language-selector.docs.md
+++ b/framework/shell/components/language-selector/language-selector.docs.md
@@ -1,3 +1,10 @@
+---
+title: LanguageSelector
+category: composables
+group: utilities
+internal: true
+---
+
 # LanguageSelector
 
 Settings menu entry that displays the current UI language and opens a cascading submenu for switching between available locales. Uses the framework `useLanguages` composable and the global vue-i18n locale list. When the user selects a different language, the entire application UI updates immediately without a page reload.
diff --git a/framework/shell/components/logout-button/logout-button.docs.md b/framework/shell/components/logout-button/logout-button.docs.md
index 1838d0e2e..b755f3e2e 100644
--- a/framework/shell/components/logout-button/logout-button.docs.md
+++ b/framework/shell/components/logout-button/logout-button.docs.md
@@ -1,3 +1,10 @@
+---
+title: LogoutButton
+category: composables
+group: utilities
+internal: true
+---
+
 # LogoutButton
 
 Settings menu action that signs the user out, closes all open blades, and redirects to the login page. This component encapsulates the full sign-out flow: it injects `CloseSettingsMenuKey` to dismiss the parent menu before navigation, calls `useUserManagement().signOut()` to clear the authentication token, and uses `useBladeStack()` to close open child blades so the user does not return to stale blade state on next login.
diff --git a/framework/shell/components/notification-dropdown/notification-dropdown.docs.md b/framework/shell/components/notification-dropdown/notification-dropdown.docs.md
index 62d56807a..7c9db4efc 100644
--- a/framework/shell/components/notification-dropdown/notification-dropdown.docs.md
+++ b/framework/shell/components/notification-dropdown/notification-dropdown.docs.md
@@ -1,3 +1,10 @@
+---
+title: NotificationDropdown
+category: composables
+group: utilities
+internal: true
+---
+
 # NotificationDropdown
 
 Dropdown panel that displays the push notification history in reverse chronological order. This component renders a scrollable list of all received push notifications, backed by the `useNotifications()` composable. It automatically marks unread notifications as read when the dropdown is closed (unmounted), updating the unread badge count in the toolbar.
diff --git a/framework/shell/components/notification-template/notification-template.docs.md b/framework/shell/components/notification-template/notification-template.docs.md
index 1a2deeb28..f1a3d0bd3 100644
--- a/framework/shell/components/notification-template/notification-template.docs.md
+++ b/framework/shell/components/notification-template/notification-template.docs.md
@@ -1,3 +1,10 @@
+---
+title: NotificationTemplate
+category: composables
+group: utilities
+internal: true
+---
+
 # NotificationTemplate
 
 Base template for rendering a single push notification with title, relative timestamp, optional icon, and a default slot for extra detail content. This component provides the standard layout that all notification types share, while allowing domain-specific content to be injected through the default slot.
diff --git a/framework/shell/components/settings-menu-item/settings-menu-item.docs.md b/framework/shell/components/settings-menu-item/settings-menu-item.docs.md
index bcd4b1eec..e8cf124f6 100644
--- a/framework/shell/components/settings-menu-item/settings-menu-item.docs.md
+++ b/framework/shell/components/settings-menu-item/settings-menu-item.docs.md
@@ -1,3 +1,10 @@
+---
+title: SettingsMenuItem
+category: composables
+group: utilities
+internal: true
+---
+
 # SettingsMenuItem
 
 Individual menu row used inside the settings menu. Displays an icon, title, optional current value, and a chevron indicator for sub-menus. Supports click and hover trigger actions.
diff --git a/framework/shell/components/settings-menu/settings-menu.docs.md b/framework/shell/components/settings-menu/settings-menu.docs.md
index 50f7a2dca..5c792f58b 100644
--- a/framework/shell/components/settings-menu/settings-menu.docs.md
+++ b/framework/shell/components/settings-menu/settings-menu.docs.md
@@ -1,3 +1,10 @@
+---
+title: SettingsMenu
+category: composables
+group: utilities
+internal: true
+---
+
 # SettingsMenu
 
 Container component that renders registered settings menu items grouped by category and sorted by order. Items are registered through the `useSettingsMenu` service, not through component props. This decoupled architecture allows any module in the application to contribute settings entries without modifying the menu component itself.
diff --git a/framework/shell/components/sidebar/sidebar.docs.md b/framework/shell/components/sidebar/sidebar.docs.md
index bd8b2c798..531db908a 100644
--- a/framework/shell/components/sidebar/sidebar.docs.md
+++ b/framework/shell/components/sidebar/sidebar.docs.md
@@ -1,3 +1,10 @@
+---
+title: Sidebar
+category: composables
+group: utilities
+internal: true
+---
+
 # Sidebar Component
 
 A responsive sidebar wrapper that conditionally renders content inside a `VcSidebar` panel or inline, based on viewport and expansion state.
diff --git a/framework/shell/components/theme-selector/theme-selector.docs.md b/framework/shell/components/theme-selector/theme-selector.docs.md
index 015de3c5f..bcef4f9f8 100644
--- a/framework/shell/components/theme-selector/theme-selector.docs.md
+++ b/framework/shell/components/theme-selector/theme-selector.docs.md
@@ -1,3 +1,10 @@
+---
+title: ThemeSelector
+category: composables
+group: utilities
+internal: true
+---
+
 # ThemeSelector
 
 Settings menu entry that shows the current theme and opens a cascading submenu to switch between registered themes. Uses the `useTheme()` composable for theme management and shows a toast notification when the theme changes, confirming the switch to the user.
diff --git a/framework/shell/components/user-dropdown-button/user-dropdown-button.docs.md b/framework/shell/components/user-dropdown-button/user-dropdown-button.docs.md
index 75bf3ec05..16451b758 100644
--- a/framework/shell/components/user-dropdown-button/user-dropdown-button.docs.md
+++ b/framework/shell/components/user-dropdown-button/user-dropdown-button.docs.md
@@ -1,3 +1,10 @@
+---
+title: UserDropdownButton
+category: composables
+group: utilities
+internal: true
+---
+
 # UserDropdownButton
 
 User account trigger displayed in the shell sidebar footer. Shows the user's avatar, display name, and role. On desktop it opens a floating settings menu dropdown anchored to the button; on mobile it opens a full sidebar panel that slides in from the left. The component automatically adapts its layout based on the sidebar's expanded/collapsed state.
diff --git a/framework/shell/dashboard/dashboard-charts/dashboard-charts.docs.md b/framework/shell/dashboard/dashboard-charts/dashboard-charts.docs.md
index 3398e78c2..fcb2bba36 100644
--- a/framework/shell/dashboard/dashboard-charts/dashboard-charts.docs.md
+++ b/framework/shell/dashboard/dashboard-charts/dashboard-charts.docs.md
@@ -1,3 +1,10 @@
+---
+title: DashboardCharts
+category: composables
+group: utilities
+internal: true
+---
+
 # DashboardCharts
 
 Suite of dashboard chart components (line, bar, donut) built on Unovis. Each chart accepts a generic data array, a `ChartConfig` for series colors/labels, and supports hover tooltips, legends, and optional range filtering.
diff --git a/framework/shell/dashboard/dashboard-widget-card/dashboard-widget-card.docs.md b/framework/shell/dashboard/dashboard-widget-card/dashboard-widget-card.docs.md
index b7b6b0f61..657dab426 100644
--- a/framework/shell/dashboard/dashboard-widget-card/dashboard-widget-card.docs.md
+++ b/framework/shell/dashboard/dashboard-widget-card/dashboard-widget-card.docs.md
@@ -1,3 +1,10 @@
+---
+title: DashboardWidgetCard
+category: composables
+group: utilities
+internal: true
+---
+
 # DashboardWidgetCard
 
 Modern dashboard widget card with header, optional KPI stats area, action buttons, content body, and footer. Used within the GridStack dashboard layout for displaying metrics, feeds, and charts.
diff --git a/framework/shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md b/framework/shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md
index 1cf2d21eb..4df92ed3e 100644
--- a/framework/shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md
+++ b/framework/shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md
@@ -1,3 +1,10 @@
+---
+title: DashboardWidgetSkeleton
+category: composables
+group: utilities
+internal: true
+---
+
 # DashboardWidgetSkeleton
 
 Internal placeholder card used by `GridstackDashboard` while remote modules are still loading. Mimics the shape of `DashboardWidgetCard` (header with icon + title, stats row, content lines) with a shimmer animation. Not exported from `@vc-shell/framework` — consumed only inside the dashboard organism.
diff --git a/framework/shell/dashboard/draggable-dashboard/draggable-dashboard.docs.md b/framework/shell/dashboard/draggable-dashboard/draggable-dashboard.docs.md
index e446b2aa6..d2a76602a 100644
--- a/framework/shell/dashboard/draggable-dashboard/draggable-dashboard.docs.md
+++ b/framework/shell/dashboard/draggable-dashboard/draggable-dashboard.docs.md
@@ -1,3 +1,10 @@
+---
+title: DraggableDashboard
+category: composables
+group: utilities
+internal: true
+---
+
 # DraggableDashboard
 
 Gridstack.js-powered dashboard container that renders registered widgets in a drag-and-drop grid layout. Automatically persists layout changes to localStorage and supports widget resizing. This is the main dashboard component used as the landing page in vc-shell applications, providing a customizable overview with KPI widgets, charts, quick actions, and data summaries.
diff --git a/framework/ui/components/atoms/vc-badge/vc-badge.docs.md b/framework/ui/components/atoms/vc-badge/vc-badge.docs.md
index 15d8416f5..c5a8e8bfb 100644
--- a/framework/ui/components/atoms/vc-badge/vc-badge.docs.md
+++ b/framework/ui/components/atoms/vc-badge/vc-badge.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcBadge
+category: components
+group: misc
+---
+
 # VcBadge
 
 A small indicator component for displaying counts, status dots, or short text labels. Supports two rendering modes: **positioned overlay** on a slotted element (e.g., notification count on a bell icon), or **standalone inline** badge (e.g., a tag/pill label in a list). Inline badges use a softer color palette with tinted backgrounds, while overlay badges use solid fills for maximum contrast.
 
+::storybook id="data-display-vcbadge--default"
+
 ## When to Use
 
 - Show unread notification counts on icons or buttons
@@ -18,6 +26,8 @@ A small indicator component for displaying counts, status dots, or short text la
 </VcBadge>
 ```
 
+::storybook id="data-display-vcbadge--variants" height="300"
+
 ## Key Props
 
 | Prop             | Type                                                                       | Default     | Description                                               |
@@ -34,6 +44,8 @@ A small indicator component for displaying counts, status dots, or short text la
 | `right`          | `string`                                                                   | --          | Custom right offset (requires `customPosition`)           |
 | `ariaLabel`      | `string`                                                                   | --          | Custom accessible label for the badge                     |
 
+::storybook id="data-display-vcbadge--use-cases" height="350"
+
 ## Common Patterns
 
 ### Notification Count on an Icon
@@ -125,3 +137,15 @@ Fine-tune the badge position relative to its parent:
 - [VcIcon](../vc-icon/) -- commonly used as slotted content inside badges
 - [VcBanner](../vc-banner/) -- for longer contextual messages and alerts
 - [VcStatus](../vc-status/) -- labeled multi-variant status indicator
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcBadge lives in `framework/ui/components/atoms/vc-badge/`.
+- Overlay mode uses `position: absolute` on the badge element; the parent slot wrapper is set to `position: relative` via the `.vc-badge` CSS class.
+- The `inline` prop switches the root element from `<span class="vc-badge">` (overlay) to `<span class="vc-badge--inline">` with no position context.
+- Color palette tokens: overlay uses `--{variant}-500` fills; inline uses `--{variant}-50` background + `--{variant}-700` text, defined in `framework/assets/styles/theme/colors.scss`.
+- Clickable mode integrates `role="button"` and keyboard handlers directly in the component — no separate button wrapper — to preserve the overlay stacking context.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-banner/vc-banner.docs.md b/framework/ui/components/atoms/vc-banner/vc-banner.docs.md
index 7f0a800e9..3d345afd5 100644
--- a/framework/ui/components/atoms/vc-banner/vc-banner.docs.md
+++ b/framework/ui/components/atoms/vc-banner/vc-banner.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcBanner
+category: components
+group: feedback
+---
+
 # VcBanner
 
 A contextual alert component for displaying important messages, warnings, or status information. VcBanner supports four semantic variants (`info`, `warning`, `danger`, `success`), each with a distinct accent color and left border stripe. Long content is automatically collapsed behind a "Show more" toggle, keeping the blade layout clean while still giving users access to the full message.
 
+::storybook id="action-vcbanner--default"
+
 ## When to Use
 
 - Display validation errors or decline reasons on detail blades
@@ -19,6 +27,8 @@ A contextual alert component for displaying important messages, warnings, or sta
 </VcBanner>
 ```
 
+::storybook id="action-vcbanner--all-variants" height="500"
+
 ## Key Props
 
 | Prop              | Type                                           | Default  | Description                                                   |
@@ -157,3 +167,13 @@ Override the default "Show more" button with a custom trigger:
 - [VcCard](../vc-card/) -- for general-purpose content containers
 - [VcIcon](../vc-icon/) -- used internally for the leading icon
 - [VcBadge](../vc-badge/) -- for inline status pill labels
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- Legacy variants `"light-danger"`, `"info-dark"`, and `"primary"` are mapped in `vc-banner.vue` via a computed `resolvedVariant`. A `console.warn` is emitted in development mode only.
+- The collapse animation is driven by `max-height` CSS transition with a JS-measured `scrollHeight`. The `--vc-banner-collapsed-height` CSS variable is injected inline as a style binding.
+- Source: `framework/ui/components/atoms/vc-banner/vc-banner.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-button/vc-button.docs.md b/framework/ui/components/atoms/vc-button/vc-button.docs.md
index 204f50cb0..1da110b1b 100644
--- a/framework/ui/components/atoms/vc-button/vc-button.docs.md
+++ b/framework/ui/components/atoms/vc-button/vc-button.docs.md
@@ -1,6 +1,14 @@
+---
+title: VcButton
+category: components
+group: misc
+---
+
 # VcButton
 
-A versatile button component supporting 9 style variants, 5 size options, loading state, and icon integration. VcButton is the primary interactive element for triggering actions throughout the application -- from toolbar buttons and form submissions to inline table actions and navigation.
+A versatile button component supporting 9 style variants, 5 size options, loading state, and icon integration. VcButton is the primary interactive element for triggering actions throughout the application — from toolbar buttons and form submissions to inline table actions and navigation.
+
+::storybook id="action-vcbutton--primary"
 
 ## When to Use
 
@@ -33,6 +41,8 @@ import { VcButton } from "@vc-shell/framework";
 
 VcButton provides 9 visual variants organized into three emphasis levels.
 
+::storybook id="action-vcbutton--all-variants" height="500"
+
 ### Filled Variants (High Emphasis)
 
 Solid background colors for primary and prominent actions.
@@ -85,6 +95,8 @@ No border or background, used for inline or de-emphasized actions.
 
 Five size options cover all common use cases from toolbar icons to prominent CTAs.
 
+::storybook id="action-vcbutton--all-sizes"
+
 ```vue
 <VcButton size="sm">Small</VcButton>
 <VcButton size="default">Default</VcButton>
@@ -101,7 +113,8 @@ Five size options cover all common use cases from toolbar icons to prominent CTA
 | `icon`    | 36x36px | 0 (square)                    | Toolbar icon buttons                |
 | `icon-sm` | 24x24px | 0 (square)                    | Table cell actions, inline controls |
 
-> **Note:** Legacy aliases `xs` (maps to `sm`) and `base` (maps to `default`) are supported for backward compatibility.
+!!! note "Legacy size aliases"
+`xs` (maps to `sm`) and `base` (maps to `default`) are supported for backward compatibility but should not be used in new code.
 
 ## Icons
 
@@ -122,6 +135,8 @@ The `icon` prop accepts a string (icon identifier like `lucide-plus`) or a Vue c
 
 ## Loading State
 
+::storybook id="action-vcbutton--loading"
+
 When `loading` is `true`, the button shows a spinner in place of its icon and becomes non-interactive:
 
 ```vue
@@ -213,6 +228,9 @@ VcButton integrates with `VcButtonGroup` via provide/inject. The group can set a
 </template>
 ```
 
+!!! warning "Don't disable buttons during async actions"
+Use the `loading` prop, not `disabled`. A disabled button gives no progress feedback; a loading button shows a spinner and announces busy state via `aria-busy`.
+
 ## Common Mistakes
 
 ### Missing aria-label on icon-only buttons
@@ -300,6 +318,15 @@ All visual properties are customizable through CSS custom properties. Each varia
 
 ## Related Components
 
-- [VcIcon](../vc-icon/) -- used internally for button icons
-- [VcBadge](../vc-badge/) -- can wrap a button to show notification counts
-- [VcButtonGroup](./vc-button-group.vue) -- groups buttons with shared size context
+- [VcIcon](../vc-icon/) — used internally for button icons
+- [VcBadge](../vc-badge/) — can wrap a button to show notification counts
+- `VcButtonGroup` — groups buttons with shared size context (see component source for usage)
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcButton calls `e.preventDefault()` on click to support `link` variant pattern. Form submit buttons must use `type="submit"` to bypass this.
+- `VcButtonGroup` integration is via provide/inject (`vcButtonGroupSize` injection key in `framework/injection-keys.ts`).
+- Size aliases `xs`/`base` are kept for vendor-portal backward compatibility — slated for removal in v3.
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-card/vc-card.docs.md b/framework/ui/components/atoms/vc-card/vc-card.docs.md
index 457c63ba8..d8d615f31 100644
--- a/framework/ui/components/atoms/vc-card/vc-card.docs.md
+++ b/framework/ui/components/atoms/vc-card/vc-card.docs.md
@@ -1,6 +1,14 @@
+---
+title: VcCard
+category: components
+group: layout
+---
+
 # VcCard
 
-A bordered container with an optional header, icon, action buttons, and collapsible body. VcCard groups related content into visually distinct sections on blades and detail views. It supports three color variants for semantic meaning and smooth animated collapse/expand.
+A bordered container with an optional header, icon, action buttons, and collapsible body.
+
+::storybook id="data-display-vccard--default" VcCard groups related content into visually distinct sections on blades and detail views. It supports three color variants for semantic meaning and smooth animated collapse/expand.
 
 ## When to Use
 
@@ -45,6 +53,8 @@ The icon renders at `xl` size using the `VcIcon` component. It inherits the head
 
 ## Variants
 
+::storybook id="data-display-vccard--all-variants" height="400"
+
 Three variants control the header's background and text color to communicate semantic meaning.
 
 ```vue
@@ -74,6 +84,8 @@ Three variants control the header's background and text color to communicate sem
 
 ## Collapsible Sections
 
+::storybook id="data-display-vccard--collapsable" height="300"
+
 Enable collapse/expand behavior by setting `is-collapsable`. The card header becomes clickable and shows a chevron indicator.
 
 ```vue
@@ -173,7 +185,8 @@ Replace the entire header content using the `#header` slot. This overrides the d
 </VcCard>
 ```
 
-> **Note:** The `header` prop must be set (even to an empty string) for the header section to render. If neither `header` prop nor `#header` slot is provided, no header is displayed.
+!!! note "Header required for header section"
+The `header` prop must be set (even to an empty string) for the header section to render. If neither `header` prop nor `#header` slot is provided, no header is displayed.
 
 ## Fill Mode
 
diff --git a/framework/ui/components/atoms/vc-col/vc-col.docs.md b/framework/ui/components/atoms/vc-col/vc-col.docs.md
index f65676cc1..2895358b6 100644
--- a/framework/ui/components/atoms/vc-col/vc-col.docs.md
+++ b/framework/ui/components/atoms/vc-col/vc-col.docs.md
@@ -1,6 +1,14 @@
+---
+title: VcCol
+category: components
+group: layout
+---
+
 # VcCol
 
-A flexbox column layout primitive that stacks its children vertically. Designed to work with `VcRow` for proportional multi-column layouts. The `size` prop maps directly to `flex-grow`, so columns with higher values consume more horizontal space relative to their siblings.
+A flexbox column layout primitive that stacks its children vertically.
+
+::storybook id="layout-vccol--default" Designed to work with `VcRow` for proportional multi-column layouts. The `size` prop maps directly to `flex-grow`, so columns with higher values consume more horizontal space relative to their siblings.
 
 ## When to Use
 
@@ -68,6 +76,8 @@ A flexbox column layout primitive that stacks its children vertically. Designed
 </VcCol>
 ```
 
+::storybook id="layout-vccol--content-layout" height="400"
+
 ## Recipe: Blade Detail Form with Sidebar
 
 A common blade layout places metadata in a narrow sidebar column and form fields in the wider main column:
diff --git a/framework/ui/components/atoms/vc-container/vc-container.docs.md b/framework/ui/components/atoms/vc-container/vc-container.docs.md
index 0a237f9a0..753d9a402 100644
--- a/framework/ui/components/atoms/vc-container/vc-container.docs.md
+++ b/framework/ui/components/atoms/vc-container/vc-container.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcContainer
+category: components
+group: layout
+---
+
 # VcContainer
 
 A scrollable content wrapper that fills its parent, provides configurable padding, and optionally shows an inset shadow to indicate overflow. The standard building block for blade body content.
 
+::storybook id="layout-vccontainer--default"
+
 ## When to Use
 
 - Wrap blade body content that may exceed the visible area
@@ -11,6 +19,8 @@ A scrollable content wrapper that fills its parent, provides configurable paddin
 
 ## Basic Usage
 
+::storybook id="layout-vccontainer--with-shadow" height="300"
+
 ```vue
 <VcContainer shadow>
   <p>Scrollable content goes here...</p>
diff --git a/framework/ui/components/atoms/vc-hint/vc-hint.docs.md b/framework/ui/components/atoms/vc-hint/vc-hint.docs.md
index a4f969750..8556b7dbe 100644
--- a/framework/ui/components/atoms/vc-hint/vc-hint.docs.md
+++ b/framework/ui/components/atoms/vc-hint/vc-hint.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcHint
+category: components
+group: feedback
+---
+
 # VcHint
 
 A small text component for displaying helper text, validation messages, or supplementary guidance below form fields. It renders as a lightweight `<div>` with muted styling in its default state and switches to a danger color with `role="alert"` when the `error` prop is set, ensuring screen readers announce validation problems immediately.
 
+::storybook id="data-display-vchint--default"
+
 ## When to Use
 
 - Show helper text beneath input fields explaining expected format or constraints
@@ -34,6 +42,8 @@ A small text component for displaying helper text, validation messages, or suppl
 
 ## Common Patterns
 
+::storybook id="data-display-vchint--form-field-hint"
+
 ### Helper Text Below an Input
 
 ```vue
@@ -129,3 +139,13 @@ Show helper text by default, but swap to an error message when validation fails:
 - [VcLabel](../vc-label/) -- field label component, typically placed above the input
 - [VcBanner](../vc-banner/) -- for longer or more prominent alert messages
 - [VcInput](../../molecules/vc-input/) -- form input component often paired with VcHint
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcHint is a single `<div>` element — no wrapper. `role="alert"` is toggled reactively via `:role` binding when `error` prop changes.
+- CSS variables are scoped with `.vc-hint` selector in `vc-hint.vue` `<style scoped>`.
+- Source: `framework/ui/components/atoms/vc-hint/vc-hint.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-icon/vc-icon.docs.md b/framework/ui/components/atoms/vc-icon/vc-icon.docs.md
index 9201fcd92..f70ad5233 100644
--- a/framework/ui/components/atoms/vc-icon/vc-icon.docs.md
+++ b/framework/ui/components/atoms/vc-icon/vc-icon.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcIcon
+category: components
+group: misc
+---
+
 # VcIcon
 
 A unified icon component that renders icons from multiple libraries. Lucide Icons (`lucide-` prefix) are the standard; legacy libraries (FontAwesome, Bootstrap, Material) are deprecated.
 
+::storybook id="layout-vcicon--basic"
+
 ## When to Use
 
 - Display icons in buttons, menus, toolbars, and status indicators
@@ -26,6 +34,8 @@ A unified icon component that renders icons from multiple libraries. Lucide Icon
 | `ariaLabel`  | `string`                                               | —                 | Accessible label for meaningful icons    |
 | `basePath`   | `string`                                               | `"/assets/icons"` | Base path for SVG sprite icons           |
 
+::storybook id="layout-vcicon--all-sizes" height="300"
+
 ## Size Reference
 
 | Size   | Pixels |
@@ -38,6 +48,8 @@ A unified icon component that renders icons from multiple libraries. Lucide Icon
 | `xxl`  | 30px   |
 | `xxxl` | 64px   |
 
+::storybook id="layout-vcicon--all-variants" height="200"
+
 ## Icon Prefix Guide
 
 | Prefix            | Library                | Status                 |
@@ -106,3 +118,15 @@ import MyCustomIcon from "./MyCustomIcon.vue";
 - [VcButton](../vc-button/) — uses VcIcon internally for button icons
 - [VcImage](../vc-image/) — for photos and larger imagery
 - [VcBanner](../vc-banner/) — uses VcIcon for the leading alert icon
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcIcon lives in `framework/ui/components/atoms/vc-icon/`.
+- Icon resolution is handled by a switch on the string prefix: `lucide-` maps to the Lucide component registry; `fa-` / `fas fa-` / `bi-` / `material-` are legacy paths kept for backward compatibility and will be removed in v3.
+- The `svg:` prefix loads from an SVG sprite at `basePath` (default `/assets/icons`) using a `<use>` element. Sprite must be included in the app's static assets.
+- `customSize` takes a number and sets `width`/`height` inline; it overrides the `size` prop class entirely.
+- Color variants (`warning`, `danger`, `success`) apply CSS custom property overrides (`--icon-color`) rather than inline style to allow theme-level customization.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-image/vc-image.docs.md b/framework/ui/components/atoms/vc-image/vc-image.docs.md
index 0c0f92cea..f9714102a 100644
--- a/framework/ui/components/atoms/vc-image/vc-image.docs.md
+++ b/framework/ui/components/atoms/vc-image/vc-image.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcImage
+category: components
+group: media
+---
+
 # VcImage
 
 An image display component with predefined sizes, aspect ratio control, and a placeholder for missing sources. Renders images as CSS backgrounds with automatic HTTPS enforcement.
 
+::storybook id="data-display-vcimage--default"
+
 ## When to Use
 
 - Display product thumbnails, profile avatars, or media previews
@@ -30,6 +38,8 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 | `alt`           | `string`                                                        | —                | Accessible alt text                                                                                                                                |
 | `thumbnailSize` | `ThumbnailSize`                                                 | —                | Load a thumbnail variant instead of full-size image. Values: `"sm"`, `"md"`, `"lg"`, `"64x64"`, `"128x128"`, `"168x168"`, `"216x216"`, `"348x348"` |
 
+::storybook id="data-display-vcimage--size-variants" height="300"
+
 ## Size Reference
 
 | Size   | Width          |
@@ -83,7 +93,23 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 - Focus ring appears on `:focus-visible` for clickable images
 - HTTP URLs are automatically upgraded to HTTPS when the page is served over HTTPS
 
+!!! tip "Use thumbnailSize for faster load times"
+When displaying images in lists or grids, pass a `thumbnailSize` (e.g. `"128x128"`) to request a pre-scaled variant from the platform CDN instead of loading the full-resolution original. This significantly reduces bandwidth and speeds up initial render.
+
 ## Related Components
 
 - [VcIcon](../vc-icon/) — for symbolic icons rather than photographic content
 - [VcImageTile](../../molecules/vc-image-tile/) — combines VcImage with overlay actions for gallery use
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcImage lives in `framework/ui/components/atoms/vc-image/`.
+- Images are rendered as CSS `background-image` on a `<div>` rather than an `<img>` tag; this enables `background-size: cover/contain` and preserves aspect-ratio without JS.
+- HTTPS enforcement: the `src` watcher rewrites `http://` to `https://` when `window.location.protocol === 'https:'`.
+- `thumbnailSize` appends a query parameter to the URL compatible with Virto Commerce image proxy: `?size=128x128`. This is a platform-specific convention.
+- Aspect ratios are implemented as Tailwind aspect-ratio utility classes (`tw-aspect-square`, `tw-aspect-video`, etc.).
+- Clickable mode adds `role="button"` and forwards keyboard Enter/Space to the click handler, consistent with other atom-level interactive components.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-label/vc-label.docs.md b/framework/ui/components/atoms/vc-label/vc-label.docs.md
index 52f1e86e0..dc103bf90 100644
--- a/framework/ui/components/atoms/vc-label/vc-label.docs.md
+++ b/framework/ui/components/atoms/vc-label/vc-label.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcLabel
+category: components
+group: misc
+---
+
 # VcLabel
 
 A form field label component with support for required indicators, info tooltips, multilanguage badges, and error states. Renders as a `<label>` when linked to an input via `htmlFor`, or a `<div>` otherwise. VcLabel is the standard way to label any form control in the framework and is used internally by most input molecules (VcInput, VcSelect, VcTextarea, etc.).
 
+::storybook id="data-display-vclabel--default"
+
 ## When to Use
 
 - Label form inputs, selects, and textareas
@@ -48,6 +56,8 @@ A form field label component with support for required indicators, info tooltips
 | `--label-lang-color`     | `var(--neutrals-500)` | Language badge text color      |
 | `--label-error-color`    | `var(--danger-500)`   | Text color in error state      |
 
+::storybook id="data-display-vclabel--required" height="200"
+
 ## Common Patterns
 
 ### Required Field with Tooltip
@@ -144,8 +154,22 @@ Use a different icon for the tooltip trigger:
 - Tooltip icon is focusable and keyboard-accessible via the underlying VcTooltip component
 - Error state changes the visual color but does not add ARIA attributes to the label; pair with `aria-invalid` and `aria-describedby` on the input
 
+::storybook id="data-display-vclabel--with-form-field" height="300"
+
 ## Related Components
 
 - [VcHint](../vc-hint/) -- helper/error text placed below the input
 - [VcTooltip](../vc-tooltip/) -- used internally for the info tooltip
 - [VcInput](../../molecules/vc-input/) -- form input component commonly paired with VcLabel
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcLabel lives in `framework/ui/components/atoms/vc-label/`.
+- The element type (`<label>` vs `<div>`) is determined by a computed `tag` that checks whether `htmlFor` is a non-empty string.
+- The tooltip trigger is rendered by `VcTooltip` (internal molecule); the `tooltipIcon` prop simply passes through to an inner `VcIcon` instance.
+- `multilanguage` + `currentLanguage` render a small pill via an inline `<span>` with `.vc-label__lang` class — not a separate component.
+- VcLabel is the canonical label primitive consumed by `VcInput`, `VcSelect`, `VcTextarea`, `VcCheckbox`, and `VcRadioButton` in `framework/ui/components/molecules/`.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-link/vc-link.docs.md b/framework/ui/components/atoms/vc-link/vc-link.docs.md
index 796db7e2d..65ca71b50 100644
--- a/framework/ui/components/atoms/vc-link/vc-link.docs.md
+++ b/framework/ui/components/atoms/vc-link/vc-link.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcLink
+category: components
+group: navigation
+---
+
 # VcLink
 
 A clickable inline link element styled as a button, used for navigation or triggering actions within text or toolbars. Despite its link-like appearance, VcLink renders as a native `<button>` element, which provides correct keyboard behavior and avoids the need for an `href` attribute when the action is handled in JavaScript.
 
+::storybook id="action-vclink--default"
+
 ## When to Use
 
 - Trigger navigation or actions inline with other content
@@ -38,6 +46,8 @@ function openDetails() {
 | ------- | ------- | ----------------------------------------------------------- |
 | `click` | none    | Fired when the link is clicked (suppressed when `disabled`) |
 
+::storybook id="action-vclink--navigation-example" height="250"
+
 ## Common Patterns
 
 ### Navigation Bar
@@ -138,3 +148,15 @@ const activeTab = ref("Overview");
 ## Related Components
 
 - [VcButton](../vc-button/) -- for primary actions and form submissions
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcLink lives in `framework/ui/components/atoms/vc-link/`.
+- Renders as a native `<button type="button">` with all default button styles reset via CSS (no background, no border, no padding). The link appearance is achieved purely through color and text-decoration.
+- The `active` prop adds `.vc-link--active` modifier which applies `--link-text-color-active` and removes the hover underline to signal current selection.
+- The `disabled` prop sets both the native `disabled` attribute (removes from tab order) and `aria-disabled="true"` (for assistive technologies that still read disabled buttons).
+- No `href` prop is intentional — VcLink is for JS-driven navigation (e.g., `openBlade`, `router.push`). For real anchor links, use `<a>` or `<router-link>` directly.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-loading/vc-loading.docs.md b/framework/ui/components/atoms/vc-loading/vc-loading.docs.md
index 0e735ee43..da5a9c1ff 100644
--- a/framework/ui/components/atoms/vc-loading/vc-loading.docs.md
+++ b/framework/ui/components/atoms/vc-loading/vc-loading.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcLoading
+category: components
+group: feedback
+---
+
 # VcLoading
 
 A lightweight animated loading overlay that displays a sweeping progress bar over its parent container. The overlay uses a translucent backdrop with a subtle blur effect, drawing user attention to the animated bar while keeping the underlying content partially visible so users retain context about what is loading.
 
+::storybook id="layout-vcloading--default"
+
 ## When to Use
 
 - Show loading state while fetching data for a blade, card, or section
@@ -46,6 +54,8 @@ const isLoading = ref(true);
 | `--loading-bar-height` | `4px`                   | Height of the progress bar    |
 | `--loading-z-index`    | `9998`                  | Z-index of the overlay layer  |
 
+::storybook id="layout-vcloading--interactive"
+
 ## Recipe: Loading State in a Blade
 
 Blades have a built-in loading mechanism, but you can use VcLoading to cover a specific section within a blade body — for example, loading a chart or a related-items panel independently.
@@ -123,3 +133,14 @@ Override the bar color to match a specific status or brand theme:
 
 - **VcBlade** -- blades use VcLoading internally for their loading state
 - [VcProgress](../vc-progress/) -- determinate progress bar when percentage is known
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- The overlay is a single `<div>` with `v-show` (not `v-if`) so it remains in the DOM and retains animation state. `display: none` from `v-show` removes it from the paint tree when inactive.
+- The sweeping bar is a child `<div>` animated via `@keyframes vc-loading-sweep` (translateX from `-100%` to `100%`).
+- `backdrop-filter: blur(3px)` is applied to the overlay div directly; older Safari requires `-webkit-backdrop-filter` as a fallback.
+- Source: `framework/ui/components/atoms/vc-loading/vc-loading.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-progress/vc-progress.docs.md b/framework/ui/components/atoms/vc-progress/vc-progress.docs.md
index af1d6a156..c1904e6f9 100644
--- a/framework/ui/components/atoms/vc-progress/vc-progress.docs.md
+++ b/framework/ui/components/atoms/vc-progress/vc-progress.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcProgress
+category: components
+group: feedback
+---
+
 # VcProgress
 
 A horizontal progress bar that visualizes the completion percentage of a task or process. The bar fills smoothly from left to right using a CSS `transform` transition, and an optional striped variant adds an animated diagonal pattern to indicate active processing.
 
+::storybook id="layout-vcprogress--default"
+
 ## When to Use
 
 - Display upload, import, or export progress
@@ -51,6 +59,8 @@ const uploadPercent = ref(45);
 </template>
 ```
 
+::storybook id="layout-vcprogress--striped"
+
 ### Multiple Progress Stages
 
 ```vue
@@ -164,3 +174,13 @@ async function handleUpload(files: FileList) {
 
 - [VcLoading](../vc-loading/) -- indeterminate loading overlay when percentage is unknown
 - [VcHint](../vc-hint/) -- helper text to display percentage or status message below the bar
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- The fill width is driven by `transform: scaleX(value / 100)` with `transform-origin: left`, not `width`, for smoother GPU-accelerated animation.
+- The `value` prop is clamped via `Math.min(100, Math.max(0, props.value))` in a computed.
+- Source: `framework/ui/components/atoms/vc-progress/vc-progress.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-row/vc-row.docs.md b/framework/ui/components/atoms/vc-row/vc-row.docs.md
index 1eab78975..222f4e8d5 100644
--- a/framework/ui/components/atoms/vc-row/vc-row.docs.md
+++ b/framework/ui/components/atoms/vc-row/vc-row.docs.md
@@ -1,6 +1,14 @@
+---
+title: VcRow
+category: components
+group: layout
+---
+
 # VcRow
 
-A simple layout primitive that arranges child elements in a horizontal flexbox row, automatically switching to a CSS grid on mobile viewports. VcRow has no props of its own — it is a purely presentational wrapper that applies consistent flex behavior and responsive breakpoints so you do not have to repeat the same Tailwind utilities across every horizontal layout.
+A simple layout primitive that arranges child elements in a horizontal flexbox row
+
+::storybook id="layout-vcrow--default", automatically switching to a CSS grid on mobile viewports. VcRow has no props of its own — it is a purely presentational wrapper that applies consistent flex behavior and responsive breakpoints so you do not have to repeat the same Tailwind utilities across every horizontal layout.
 
 ## When to Use
 
@@ -100,6 +108,8 @@ The `--row-gap` CSS variable (default `0`) controls spacing. You can also overri
 </template>
 ```
 
+::storybook id="layout-vcrow--with-cards" height="300"
+
 ## Recipe: Form Section with Label and Fields
 
 Use VcRow to place a section label next to a group of fields in a blade detail view:
diff --git a/framework/ui/components/atoms/vc-scrollable-container/vc-scrollable-container.docs.md b/framework/ui/components/atoms/vc-scrollable-container/vc-scrollable-container.docs.md
index 7a3dc8d42..790960718 100644
--- a/framework/ui/components/atoms/vc-scrollable-container/vc-scrollable-container.docs.md
+++ b/framework/ui/components/atoms/vc-scrollable-container/vc-scrollable-container.docs.md
@@ -1,6 +1,14 @@
+---
+title: VcScrollableContainer
+category: components
+group: layout
+---
+
 # VcScrollableContainer
 
-A container component that wraps overflowing content with auto-hiding scroll arrows at the top and bottom edges. The native scrollbar is hidden via CSS, replaced by subtle chevron indicators that appear only when scrolling in that direction is possible. Users can hover over an arrow to scroll continuously or use keyboard arrow keys when the viewport is focused.
+A container component that wraps overflowing content with auto-hiding scroll arrows at the top and bottom edges.
+
+::storybook id="layout-vcscrollablecontainer--default" The native scrollbar is hidden via CSS, replaced by subtle chevron indicators that appear only when scrolling in that direction is possible. Users can hover over an arrow to scroll continuously or use keyboard arrow keys when the viewport is focused.
 
 ## When to Use
 
@@ -50,6 +58,8 @@ import { VcScrollableContainer } from "@vc-shell/framework";
 | `viewportRef`       | `Ref<HTMLElement \| null>` | Direct reference to the viewport DOM element |
 | `updateScrollState` | `() => void`               | Manually recalculate arrow visibility        |
 
+::storybook id="layout-vcscrollablecontainer--custom-speed" height="350"
+
 ## Recipe: Sidebar Filter List in a Blade
 
 ```vue
diff --git a/framework/ui/components/atoms/vc-skeleton/vc-skeleton.docs.md b/framework/ui/components/atoms/vc-skeleton/vc-skeleton.docs.md
index 0bc1a282c..291b0bd4b 100644
--- a/framework/ui/components/atoms/vc-skeleton/vc-skeleton.docs.md
+++ b/framework/ui/components/atoms/vc-skeleton/vc-skeleton.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcSkeleton
+category: components
+group: feedback
+---
+
 # VcSkeleton
 
 A loading placeholder component that renders animated shimmer shapes (text lines, circles, or rectangular blocks) to indicate content is being fetched.
 
+::storybook id="layout-vcskeleton--default"
+
 ## When to Use
 
 - Show placeholder UI while async data loads for blades, lists, or cards
@@ -47,6 +55,8 @@ The last row automatically renders at 60% width for a natural paragraph feel.
 <VcSkeleton variant="circle" :width="48" :height="48" />
 ```
 
+::storybook id="layout-vcskeleton--card-skeleton" height="450"
+
 ### Card Skeleton
 
 ```vue
@@ -121,3 +131,13 @@ The last row automatically renders at 60% width for a natural paragraph feel.
 
 - [VcLoading](../vc-loading/) -- animated overlay for sections already rendered
 - [VcProgress](../vc-progress/) -- determinate progress bar
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- The `text` variant uses an `Array(rows).fill(0)` to render `<span>` elements via `v-for`. The last row gets a `width: 60%` inline style for a natural paragraph taper.
+- Animation uses a CSS `@keyframes` pulse (opacity oscillation), not a moving shimmer, for simplicity and performance.
+- Source: `framework/ui/components/atoms/vc-skeleton/vc-skeleton.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-status-icon/vc-status-icon.docs.md b/framework/ui/components/atoms/vc-status-icon/vc-status-icon.docs.md
index 1c70987a9..cff89aa18 100644
--- a/framework/ui/components/atoms/vc-status-icon/vc-status-icon.docs.md
+++ b/framework/ui/components/atoms/vc-status-icon/vc-status-icon.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcStatusIcon
+category: components
+group: feedback
+---
+
 # VcStatusIcon
 
 A simple boolean status indicator that displays a green check icon for active/success or a muted cross icon for inactive/failure. It is designed for compact spaces like table cells and lists where a full text label would be too verbose.
 
+::storybook id="data-display-vcstatusicon--both-statuses"
+
 ## When to Use
 
 - Show on/off or pass/fail state in tables and lists (e.g., "Is Active", "Email Verified")
@@ -104,6 +112,8 @@ import { VcStatusIcon } from "@vc-shell/framework";
 </template>
 ```
 
+::storybook id="data-display-vcstatusicon--in-context"
+
 ## Recipe: Status Icon with Custom Label
 
 VcStatusIcon is intentionally minimal. If you need a text label next to the icon, compose it yourself:
@@ -146,3 +156,13 @@ VcStatusIcon is intentionally minimal. If you need a text label next to the icon
 - [VcStatus](../vc-status/) -- labeled multi-variant status badge for richer state display
 - [VcIcon](../vc-icon/) -- standalone icon component used internally
 - [VcBadge](../vc-badge/) -- inline pill badges for multi-state indicators
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcStatusIcon wraps two `VcIcon` instances in a single `<span>` with `v-if`/`v-else` switching on the `status` prop.
+- Icon size inherits from parent font-size; no dedicated size prop is exposed.
+- Source: `framework/ui/components/atoms/vc-status-icon/vc-status-icon.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-status/vc-status.docs.md b/framework/ui/components/atoms/vc-status/vc-status.docs.md
index dced2af7f..2d29b913e 100644
--- a/framework/ui/components/atoms/vc-status/vc-status.docs.md
+++ b/framework/ui/components/atoms/vc-status/vc-status.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcStatus
+category: components
+group: feedback
+---
+
 # VcStatus
 
 A colored badge that communicates the state of an entity -- such as an order, product, or workflow step -- using semantic color variants.
 
+::storybook id="data-display-vcstatus--default"
+
 ## When to Use
 
 - Display order or fulfillment status (e.g., "Paid", "Pending", "Cancelled")
@@ -31,6 +39,8 @@ import { VcStatus } from "@vc-shell/framework";
 
 ## Common Patterns
 
+::storybook id="data-display-vcstatus--all-variants" height="450"
+
 ### Status in a Table Cell
 
 ```vue
@@ -116,3 +126,13 @@ Each variant has its own set of CSS variables following the pattern `--status-{v
 
 - [VcStatusIcon](../vc-status-icon/) -- boolean check/cross icon for active/inactive states
 - [VcBadge](../vc-badge/) -- numeric count badge overlay
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- The `extend` prop switches a CSS class; all color theming is done via `--status-{variant}-*` CSS variables scoped under `.vc-status`.
+- Special variants `"light-danger"`, `"info-dark"`, and `"primary"` are kept for backward compatibility and mapped via a `variantClassMap` in `vc-status.vue`.
+- Source: `framework/ui/components/atoms/vc-status/vc-status.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-tooltip/vc-tooltip.docs.md b/framework/ui/components/atoms/vc-tooltip/vc-tooltip.docs.md
index a2d763a68..7ead3f2a0 100644
--- a/framework/ui/components/atoms/vc-tooltip/vc-tooltip.docs.md
+++ b/framework/ui/components/atoms/vc-tooltip/vc-tooltip.docs.md
@@ -1,9 +1,17 @@
+---
+title: VcTooltip
+category: components
+group: feedback
+---
+
 # VcTooltip
 
 A floating tooltip that appears on hover or focus to provide contextual information about a trigger element. Powered by Floating UI for automatic positioning, collision detection, and arrow alignment. The tooltip is teleported to the document body for proper stacking above all content.
 
 ## Quick Start
 
+::storybook id="overlay-vctooltip--default"
+
 ```vue
 <template>
   <VcTooltip>
@@ -55,6 +63,8 @@ The `start` and `end` variants align the tooltip to the beginning or end of the
 
 ## Variants
 
+::storybook id="overlay-vctooltip--variants"
+
 Three visual themes control the tooltip's appearance.
 
 ```vue
@@ -172,7 +182,8 @@ The `#tooltip` slot accepts any HTML or Vue components, not just text:
 </VcTooltip>
 ```
 
-> **Caution:** Tooltips should not contain interactive content (buttons, links, inputs). If you need interactive content in a floating panel, use a popover or dropdown component instead.
+!!! warning "No interactive content inside tooltips"
+Tooltips should not contain interactive content (buttons, links, inputs). The tooltip panel has `pointer-events: none` — clicks and keyboard focus inside it are blocked. If you need interactive content in a floating panel, use a popover or dropdown component instead.
 
 ## Recipes
 
@@ -330,3 +341,16 @@ const actions = [
 - [VcHint](../vc-hint/) -- inline hint text below form fields (always visible)
 - [VcLabel](../vc-label/) -- label component with built-in tooltip support via its own `#tooltip` slot
 - [VcIcon](../vc-icon/) -- commonly used as a tooltip trigger for info indicators
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcTooltip uses `@floating-ui/vue` (`useFloating`, `autoUpdate`, `flip`, `shift`, `arrow`, `offset` middleware).
+- The tooltip content is teleported to `<body>` via Vue's `<Teleport>` to escape stacking contexts.
+- Show/hide state is managed with a single `isVisible` ref toggled by `mouseenter`/`mouseleave` and `focusin`/`focusout` on the trigger slot wrapper.
+- The delay timer is stored in a `timeoutId` ref and cleared on `mouseleave` to cancel pending show.
+- Arrow positioning is handled by the `arrowEl` template ref passed to the `arrow` middleware; position is applied via `:style` on the arrow element.
+- Source: `framework/ui/components/atoms/vc-tooltip/vc-tooltip.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-video/vc-video.docs.md b/framework/ui/components/atoms/vc-video/vc-video.docs.md
index d31351be0..139934bac 100644
--- a/framework/ui/components/atoms/vc-video/vc-video.docs.md
+++ b/framework/ui/components/atoms/vc-video/vc-video.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcVideo
+category: components
+group: media
+---
+
 # VcVideo
 
 An embedded video player that renders an iframe for external video sources (YouTube, Vimeo, etc.) with an optional label and tooltip. When no source URL is provided, the component displays a centered film icon placeholder instead of a blank space, giving users a clear visual cue that a video can be attached.
 
+::storybook id="data-display-vcvideo--default"
+
 ## When to Use
 
 - Embed product or tutorial videos in blade detail views
@@ -32,6 +40,8 @@ import { VcVideo } from "@vc-shell/framework";
 | `label`   | `string` | --      | Label text displayed above the video               |
 | `tooltip` | `string` | --      | Tooltip text shown on the label's info icon        |
 
+::storybook id="data-display-vcvideo--with-tooltip" height="400"
+
 ## Common Patterns
 
 ### Video with Label and Tooltip
@@ -111,8 +121,23 @@ When `source` is not provided, VcVideo renders a centered film icon placeholder
 - `loading="lazy"` defers iframe load until visible
 - Placeholder state uses `role="img"` with `aria-label="No video source"`
 
+!!! warning "Always use embed URLs, not watch URLs"
+YouTube watch URLs (`youtube.com/watch?v=...`) will be blocked by the browser's frame policy. Always convert to the embed format (`youtube.com/embed/VIDEO_ID`). Vimeo similarly requires `player.vimeo.com/video/VIDEO_ID`.
+
 ## Related Components
 
 - [VcLabel](../vc-label/) -- used internally for the label with tooltip
 - [VcIcon](../vc-icon/) -- renders the placeholder film icon
 - [VcRow](../vc-row/) / [VcCol](../vc-col/) -- layout primitives for placing video alongside other content
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcVideo lives in `framework/ui/components/atoms/vc-video/`.
+- The component is a thin wrapper around a native `<iframe>` — no custom video controls are implemented.
+- The `sandbox` attribute is hardcoded to `allow-scripts allow-same-origin allow-presentation allow-popups`. Apps that need additional iframe permissions must wrap the component or use a plain `<iframe>`.
+- The label is rendered via `VcLabel` (internal atom) with the `tooltip` prop forwarded as the VcLabel tooltip slot content.
+- Placeholder state (`source` is falsy) swaps the iframe for a `<div>` with `role="img"` containing a `VcIcon` with `lucide-film`.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/atoms/vc-widget/vc-widget.docs.md b/framework/ui/components/atoms/vc-widget/vc-widget.docs.md
index dc386b065..4b687f0a1 100644
--- a/framework/ui/components/atoms/vc-widget/vc-widget.docs.md
+++ b/framework/ui/components/atoms/vc-widget/vc-widget.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcWidget
+category: components
+group: misc
+---
+
 # VcWidget
 
 A clickable widget tile with an icon, title, and optional badge counter. Used in blade toolbars and sidebars to trigger blade-level actions or navigation.
 
+::storybook id="data-display-vcwidget--default"
+
 ## When to Use
 
 - Build widget panels in blade sidebars (e.g., "Orders", "Reviews", "Notifications")
@@ -49,6 +57,8 @@ function openNotifications() {
 | ------- | ------- | ------------------------------------------------------------- |
 | `click` | none    | Fired when the widget is clicked (suppressed when `disabled`) |
 
+::storybook id="data-display-vcwidget--sidebar-layout" height="350"
+
 ## Common Patterns
 
 ### Sidebar Widget Panel
@@ -112,3 +122,15 @@ Badge values above 99 are automatically displayed as "99+".
 - [VcBadge](../vc-badge/) -- used internally for the count badge overlay
 - [VcIcon](../vc-icon/) -- used internally for the widget icon
 - [VcButton](../vc-button/) -- for standard action buttons
+
+<!-- internal:start -->
+
+## Architecture notes
+
+- VcWidget lives in `framework/ui/components/atoms/vc-widget/`.
+- The badge overlay is rendered by embedding `VcBadge` with `isDot`/`content` derived from the `value` prop; values above 99 are truncated to `"99+"` in the component template.
+- `isExpanded` applies `.vc-widget--expanded` modifier; used by the shell sidebar to visually distinguish active navigation state.
+- `horizontal` applies `.vc-widget--horizontal` modifier which switches the internal flex direction from `column` to `row`.
+- The widget registers as a keyboard-interactive element (`role="button"`, Enter/Space handlers) rather than using a `<button>` to allow embedding arbitrary icon components without nesting interactive elements.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/multilanguage-selector/multilanguage-selector.docs.md b/framework/ui/components/molecules/multilanguage-selector/multilanguage-selector.docs.md
index 173b1cb20..9d6673fbc 100644
--- a/framework/ui/components/molecules/multilanguage-selector/multilanguage-selector.docs.md
+++ b/framework/ui/components/molecules/multilanguage-selector/multilanguage-selector.docs.md
@@ -1,3 +1,9 @@
+---
+title: MultilanguageSelector
+category: components
+group: form
+---
+
 # MultilanguageSelector
 
 Compact circular flag button that opens a dropdown for selecting a content language. Designed for use in detail blades where entities have multilingual fields (e.g., product name, offer description, category title). This is distinct from the `LanguageSelector` settings entry, which changes the application UI locale -- `MultilanguageSelector` controls which language version of the content the user is editing.
@@ -10,6 +16,8 @@ Compact circular flag button that opens a dropdown for selecting a content langu
 
 ## Basic Usage
 
+::storybook id="shared-multilanguageselector--interactive"
+
 ```vue
 <script setup lang="ts">
 import { ref } from "vue";
@@ -41,6 +49,8 @@ const languages = [
 
 Each `LanguageOption` has: `{ value: string; label: string; flag?: string }`.
 
+::storybook id="shared-multilanguageselector--disabled"
+
 ## Recipe: Multilingual Product Editing Blade
 
 A typical use case is a product detail blade where the user can edit the name and description in multiple languages:
diff --git a/framework/ui/components/molecules/vc-accordion/vc-accordion.docs.md b/framework/ui/components/molecules/vc-accordion/vc-accordion.docs.md
index d1b34f79a..85cbdc849 100644
--- a/framework/ui/components/molecules/vc-accordion/vc-accordion.docs.md
+++ b/framework/ui/components/molecules/vc-accordion/vc-accordion.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcAccordion
+category: components
+group: data-display
+---
+
 # VcAccordion
 
 Collapsible content sections with smooth CSS grid animations, customizable collapsed heights with fade-out preview, and four visual variants. Supports both data-driven rendering via `items` array and slot-based composition with `VcAccordionItem`.
@@ -17,6 +23,8 @@ When NOT to use:
 
 ## Quick Start
 
+::storybook id="action-vcaccordion--default"
+
 ```vue
 <template>
   <VcAccordion
@@ -38,6 +46,9 @@ const faqItems = [
 
 ## Features
 
+!!! tip "Use v-model to control initial open state"
+Without `v-model`, no items are expanded on mount. Pass an initial value to pre-open a specific item.
+
 ### Visual Variants
 
 Four variants control the visual grouping and spacing of accordion items.
@@ -78,6 +89,8 @@ const items = [
 </script>
 ```
 
+::storybook id="action-vcaccordion--bordered-variant"
+
 ### Multiple Open Items
 
 Set `multiple` to `true` to allow expanding several items simultaneously. The `v-model` value becomes an array.
@@ -86,6 +99,8 @@ Set `multiple` to `true` to allow expanding several items simultaneously. The `v
 <VcAccordion v-model="openItems" :items="items" :multiple="true" />
 ```
 
+::storybook id="action-vcaccordion--multiple-open"
+
 ### Partial Content Preview (collapsedHeight)
 
 When `collapsedHeight` > 0, collapsed items show that many pixels of content with a fade-out gradient. The chevron only appears when content overflows.
@@ -262,6 +277,8 @@ interface AccordionItem {
 
 - [VcAccordionItem](./_internal/vc-accordion-item/) -- individual accordion panel (used internally and available via the default slot)
 
+::storybook id="action-vcaccordion--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
diff --git a/framework/ui/components/molecules/vc-breadcrumbs/vc-breadcrumbs.docs.md b/framework/ui/components/molecules/vc-breadcrumbs/vc-breadcrumbs.docs.md
index 113c6e2dd..8148948af 100644
--- a/framework/ui/components/molecules/vc-breadcrumbs/vc-breadcrumbs.docs.md
+++ b/framework/ui/components/molecules/vc-breadcrumbs/vc-breadcrumbs.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcBreadcrumbs
+category: components
+group: navigation
+---
+
+!!! tip "Quick reference"
+Jump to [Props](#props) · [Slots](#slots) · [CSS Variables](#css-variables) · [Accessibility](#accessibility)
+
 # VcBreadcrumbs
 
 Navigation breadcrumb trail that displays the user's location within a hierarchy and adaptively collapses middle items into a dropdown when horizontal space is limited.
 
+::storybook id="navigation-vcbreadcrumbs--default"
+
 ## When to Use
 
 - Showing the user's current position in a blade navigation hierarchy
@@ -51,6 +62,8 @@ interface Breadcrumbs {
 
 ## Adaptive Overflow
 
+::storybook id="navigation-vcbreadcrumbs--many-items"
+
 VcBreadcrumbs monitors the container width with `useAdaptiveItems` and automatically collapses middle items into a dropdown when they do not fit. The first and last items stay visible; overflow items appear behind a "more" button (vertical ellipsis).
 
 The collapse algorithm uses a reverse strategy -- it hides items starting from the left (after the first) so the current page (last item) always remains visible.
@@ -64,6 +77,8 @@ The collapse algorithm uses a reverse strategy -- it hides items starting from t
 
 ## Separated Style
 
+::storybook id="navigation-vcbreadcrumbs--separated"
+
 Enable slash separators between items with the `separated` prop:
 
 ```vue
@@ -275,3 +290,15 @@ clickHandler: () => { navigate(); return true; }
 - [VcDropdown](../vc-dropdown/) -- Used internally to render the overflow menu
 - [VcBreadcrumbsItem](./_internal/vc-breadcrumbs-item/) -- Internal sub-component for individual breadcrumb rendering
 - [VcButton](../../atoms/vc-button/) -- Can be used inside the `trigger` slot for a styled overflow button
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Overflow detection uses `useAdaptiveItems` composable with `calculationStrategy: "reverse"` — items are hidden starting from the second item (left side), keeping the last item (current page) always visible.
+- `MORE_BUTTON_WIDTH = 36` and `INITIAL_ITEM_WIDTH = 60` are conservative estimates used in the initial layout pass before DOM measurement.
+- The `VcDropdown` instance for the overflow menu uses `floating` and `placement="bottom-start"`.
+- `VcBreadcrumbsItem` is an internal sub-component in `_internal/vc-breadcrumbs-item/` — not exported from the index.
+- The `useBreadcrumbs` composable lives in `framework/core/composables/useBreadcrumbs/`.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-checkbox-group/vc-checkbox-group.docs.md b/framework/ui/components/molecules/vc-checkbox-group/vc-checkbox-group.docs.md
index 7bb915b1d..435895ca6 100644
--- a/framework/ui/components/molecules/vc-checkbox-group/vc-checkbox-group.docs.md
+++ b/framework/ui/components/molecules/vc-checkbox-group/vc-checkbox-group.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcCheckboxGroup
+category: components
+group: form
+---
+
 # VcCheckboxGroup
 
 Accessible checkbox group that wraps multiple checkboxes in a semantic fieldset with shared label, hint, error state, and layout control.
 
+::storybook id="form-vccheckboxgroup--default"
+
 ## When to Use
 
 - Selecting multiple options from a set (e.g., notification channels, feature flags)
@@ -75,6 +83,8 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 
 ### Horizontal Layout
 
+::storybook id="form-vccheckboxgroup--horizontal"
+
 ```vue
 <VcCheckboxGroup
   v-model="permissions"
@@ -90,6 +100,8 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 
 ### With Disabled Option
 
+::storybook id="form-vccheckboxgroup--with-disabled-option"
+
 ```vue
 <VcCheckboxGroup
   v-model="selected"
@@ -135,3 +147,14 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcCheckboxGroup delegates rendering to `VcInputGroup` (semantic fieldset wrapper) and renders `VcCheckbox` items from the `options` array, or passes through the default slot for custom layouts.
+- The group generates a unique `name` attribute via `useId()` when none is provided, ensuring native radio group behavior.
+- `normalizedModelValue` guards against non-array `modelValue` to avoid runtime errors when the parent passes `undefined`.
+- Source file: `framework/ui/components/molecules/vc-checkbox-group/vc-checkbox-group.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-checkbox/vc-checkbox.docs.md b/framework/ui/components/molecules/vc-checkbox/vc-checkbox.docs.md
index 62c9d0b80..8cd266625 100644
--- a/framework/ui/components/molecules/vc-checkbox/vc-checkbox.docs.md
+++ b/framework/ui/components/molecules/vc-checkbox/vc-checkbox.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcCheckbox
+category: components
+group: form
+---
+
 # VcCheckbox
 
 A checkbox component supporting boolean toggling, array-based multi-selection, indeterminate state, three size variants, and animated check/uncheck transitions. Works as both a standalone boolean toggle and a member of a multi-select group.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Features](#features), [Props](#props), [CSS Variables](#css-variables).
+
+::storybook id="form-vccheckbox--basic"
+
 ## When to Use
 
 - Single boolean toggle with an inline label (e.g., "I agree to terms")
@@ -69,6 +80,8 @@ const selected = ref<string[]>([]);
 
 ### Size Variants
 
+::storybook id="form-vccheckbox--sizes"
+
 Three sizes are available via the `size` prop:
 
 | Size   | Value           | Pixel dimension |
@@ -85,6 +98,8 @@ Three sizes are available via the `size` prop:
 
 ### Indeterminate State (Select All)
 
+::storybook id="form-vccheckbox--indeterminate"
+
 The `indeterminate` prop renders a horizontal dash instead of a checkmark. This is commonly used for "select all" checkboxes where only some children are selected.
 
 ```vue
@@ -355,3 +370,15 @@ const selected = ref<string[]>([]);
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcCheckbox uses a visually hidden native `<input type="checkbox">` for full keyboard and screen reader support. The custom visual (`vc-checkbox__custom-input`) mirrors its state via CSS sibling selectors (`:checked + .vc-checkbox__custom-input`).
+- Indeterminate state is set imperatively (`checkboxRef.value.indeterminate = val`) since HTML does not support `indeterminate` as an attribute — a watcher syncs the prop to the DOM property.
+- Check/uncheck icons use Vue `<Transition name="vc-checkbox-check">` with `@keyframes` animations for the scale/opacity effect.
+- `useFormField` injects validation context (error, disabled, name) from a parent form provider.
+- Source file: `framework/ui/components/molecules/vc-checkbox/vc-checkbox.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-color-input/vc-color-input.docs.md b/framework/ui/components/molecules/vc-color-input/vc-color-input.docs.md
index 32c283ced..903aae895 100644
--- a/framework/ui/components/molecules/vc-color-input/vc-color-input.docs.md
+++ b/framework/ui/components/molecules/vc-color-input/vc-color-input.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcColorInput
+category: components
+group: form
+---
+
+!!! tip "Quick reference"
+See [Key Props](#key-props) for the full prop table, or jump to [Common Patterns](#common-patterns) for copy-paste examples.
+
 # VcColorInput
 
 A color input that combines a text field for hex values with a clickable color swatch that opens the native browser color picker. Accepts hex codes and CSS color names.
 
+::storybook id="form-vccolorinput--default"
+
 ## Overview
 
 Color selection is needed in various admin scenarios: configuring brand colors, setting category badges, defining product attribute colors, or customizing theme variables. The native HTML `<input type="color">` provides a color picker but lacks text entry, validation, and consistent styling.
@@ -53,6 +64,8 @@ const color = ref<string | null>(null);
 
 ### With Validation
 
+::storybook id="form-vccolorinput--with-error"
+
 ```vue
 <template>
   <VcColorInput
@@ -198,3 +211,14 @@ The native color picker does not support alpha/transparency. If you need RGBA co
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- The swatch button is a native `<button type="button">` that triggers a hidden `<input type="color">` via programmatic `.click()`. The native color picker is not visible — only the swatch button is.
+- Color synchronization: typing in the text field updates `modelValue` directly; selecting from the native picker emits the new hex value and also updates the text field.
+- The component does NOT validate hex format — any string is accepted as-is and the swatch will display whatever color the browser interprets.
+- Source file: `framework/ui/components/molecules/vc-color-input/vc-color-input.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-date-picker/vc-date-picker.docs.md b/framework/ui/components/molecules/vc-date-picker/vc-date-picker.docs.md
index b21c3040d..9a8f8bb28 100644
--- a/framework/ui/components/molecules/vc-date-picker/vc-date-picker.docs.md
+++ b/framework/ui/components/molecules/vc-date-picker/vc-date-picker.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcDatePicker
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcDatePicker
 
 A date and datetime picker that wraps the [VueDatePicker](https://vue3datepicker.com/) library with the standard form field chrome (label, hint, error, focus ring). Formats dates using the browser's locale and automatically detects 12-hour vs. 24-hour time format.
 
+::storybook id="form-vcdatepicker--default"
+
 ## When to Use
 
 - Selecting a single date value (e.g., delivery date, publication date)
@@ -39,6 +50,8 @@ const date = ref<Date | null>(null);
 
 ### Date vs. DateTime Mode
 
+::storybook id="form-vcdatepicker--date-time"
+
 The `type` prop controls whether the picker shows a date-only calendar or includes an inline time picker.
 
 ```vue
@@ -130,6 +143,8 @@ const form = reactive({
 
 ### States
 
+::storybook id="form-vcdatepicker--with-error"
+
 ```vue
 <!-- Required -->
 <VcDatePicker v-model="date" label="Due date" required />
@@ -345,3 +360,15 @@ Uses the same `--input-*` variables as VcInput for consistent styling across all
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Wraps the third-party `VueDatePicker` component. The underlying library is `@vuepic/vue-datepicker`.
+- 12h/24h auto-detection uses the `Intl.DateTimeFormat` API with a sentinel date (midnight on 2023-01-01) to check if the locale's time representation contains "AM" or "PM".
+- The `datePickerOptions` prop is spread onto `<VueDatePicker>` via `v-bind`. Props explicitly set on `VcDatePicker` take precedence over `datePickerOptions` entries of the same name.
+- The `maxDate` for date-only mode is capped at `9999-12-31` to prevent the underlying library from crashing on out-of-range dates.
+- Source file: `framework/ui/components/molecules/vc-date-picker/vc-date-picker.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-dropdown-panel/vc-dropdown-panel.docs.md b/framework/ui/components/molecules/vc-dropdown-panel/vc-dropdown-panel.docs.md
index 8fe17ef3c..138740ac3 100644
--- a/framework/ui/components/molecules/vc-dropdown-panel/vc-dropdown-panel.docs.md
+++ b/framework/ui/components/molecules/vc-dropdown-panel/vc-dropdown-panel.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcDropdownPanel
+category: components
+group: navigation
+---
+
 # VcDropdownPanel
 
 Floating dropdown panel positioned relative to an anchor element, with header, scrollable content, and optional footer. Built on `@floating-ui/vue`.
 
+::storybook id="overlay-vcdropdownpanel--default"
+
 ## When to Use
 
 - Rich dropdown content with a title bar and action buttons (e.g., filter panels, settings popovers)
@@ -70,6 +78,8 @@ const open = ref(false);
 
 ## Common Patterns
 
+::storybook id="overlay-vcdropdownpanel--with-footer"
+
 ### Filter Panel with Footer Actions
 
 ```vue
@@ -142,3 +152,15 @@ const open = ref(false);
 
 - [VcDropdown](../vc-dropdown/) — headless dropdown for simple item lists
 - [VcSelect](../vc-select/) — form field selection dropdown
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Click-outside detection uses a `pointerdown` listener on `document` rather than a backdrop overlay. This ensures clicks on high-z-index siblings (sidebar, other teleported panels) are still caught.
+- `panelAnchorRegistry` (`panel-anchor-registry.ts`) is a `WeakMap<Element, HTMLElement | null>` that maps each open panel's DOM element to its anchor. This is used to distinguish child panels (whose anchor lives inside this panel) from sibling/parent panels when deciding whether to close on outside click.
+- Nested VcSelect dropdowns teleported to `<body>` are exempt from click-outside via an ARIA `aria-controls` check: if the clicked `.vc-select__dropdown` has an `id` that matches an `aria-controls` attribute inside this panel, the close is suppressed.
+- The panel exposes a `close()` method via `defineExpose` for use with template refs.
+- `useTeleportTarget` resolves the teleport destination (typically `body`) respecting any custom portal container.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-dropdown/vc-dropdown.docs.md b/framework/ui/components/molecules/vc-dropdown/vc-dropdown.docs.md
index b82d14e59..4a17f27df 100644
--- a/framework/ui/components/molecules/vc-dropdown/vc-dropdown.docs.md
+++ b/framework/ui/components/molecules/vc-dropdown/vc-dropdown.docs.md
@@ -1,3 +1,12 @@
+---
+title: VcDropdown
+category: components
+group: navigation
+---
+
+!!! tip "Quick reference"
+Jump to [Props](#props) · [Events](#events) · [Slots](#slots) · [CSS Variables](#css-variables) · [Accessibility](#accessibility)
+
 # VcDropdown
 
 A headless, accessible dropdown primitive for building menus and listboxes. Provides floating positioning via `@floating-ui`, full keyboard navigation, slot-based rendering, and configurable close behavior. This is a low-level building block -- for form field selection, use VcSelect instead.
@@ -17,6 +26,8 @@ When NOT to use:
 
 ## Quick Start
 
+::storybook id="overlay-vcdropdown--action-menu"
+
 ```vue
 <template>
   <VcDropdown
@@ -97,6 +108,8 @@ Build rich action menus by customizing the `#item` slot with icons, labels, and
 
 ### Listbox Mode (Selection Switcher)
 
+::storybook id="overlay-vcdropdown--workspace-switcher"
+
 Use `role="listbox"` for option-selection patterns. Combine with `isItemActive` to highlight the current selection and `aria-selected` is set automatically.
 
 ```vue
@@ -369,3 +382,17 @@ By default, `padded` is `true`, which adds compact padding and rounded item back
 - [VcDropdownPanel](../vc-dropdown-panel/) -- floating panel with header, footer, and scrollable content
 - [VcSelect](../vc-select/) -- form field dropdown for selecting values with label and validation
 - [VcMenu](../vc-menu/) -- sidebar navigation menu
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `VcDropdown` is a generic component (`generic="T"`). TypeScript infers `T` from the `items` prop, giving type-safe `item-click` payloads and slot props.
+- Floating positioning uses `useFloatingPosition` (a thin wrapper around `@floating-ui/vue`) with `autoUpdate: true` when `floating` is enabled — the panel recalculates its position on scroll/resize.
+- Teleport target is determined by `useTeleportTarget`. When `floating` is `true`, the panel is teleported to avoid z-index stacking context issues.
+- Keyboard navigation (`ArrowDown`, `ArrowUp`, `Home`, `End`, `Enter`/`Space`, `Escape`) is handled in `onPanelKeydown`. Escape also attaches a document-level listener when the dropdown is open to catch events that bubble past the panel.
+- `syncFocusedIndex` is called on open to pre-focus the active item (via `isItemActive`) or the first item.
+- The `VcDropdownItem` internal sub-component (in `_internal/VcDropdownItem.vue`) is used by `VcBreadcrumbs` for its overflow menu items.
+- Default `zIndex` is `9300` (matches the CSS custom property `--z-critical-dropdown`).
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-editor/vc-editor.docs.md b/framework/ui/components/molecules/vc-editor/vc-editor.docs.md
index 60227eefc..2a785645d 100644
--- a/framework/ui/components/molecules/vc-editor/vc-editor.docs.md
+++ b/framework/ui/components/molecules/vc-editor/vc-editor.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcEditor
+category: components
+group: form
+---
+
 # VcEditor
 
 A rich text editor built on TipTap that supports both Markdown and HTML content. Includes a customizable toolbar, multiple view modes (WYSIWYG, preview, source, split), fullscreen editing, image upload, character limits, and plugin-style custom toolbar buttons.
@@ -17,6 +23,8 @@ When NOT to use:
 
 ## Quick Start
 
+::storybook id="form-vceditor--default" height="500"
+
 ```vue
 <template>
   <VcEditor
@@ -50,6 +58,9 @@ The editor header provides four view modes plus a fullscreen toggle:
 
 The editor automatically detects whether content is Markdown or HTML based on pattern analysis and outputs in the same format. HTML content is auto-formatted with Prettier in source/split views.
 
+!!! note "Content format is auto-detected"
+VcEditor detects whether content is Markdown or HTML and outputs in the same format. If you pass Markdown input, you will get Markdown output. If you need HTML output, start with HTML content.
+
 ### Custom Toolbar Configuration
 
 Limit which toolbar buttons appear by passing a `toolbar` array. Only the specified buttons will render. Available toolbar names:
@@ -80,6 +91,8 @@ When `assetsFolder` is provided, the image toolbar button becomes functional. Cl
 
 Multiple images can be selected at once. The upload accepts any image file type (`image/*`).
 
+::storybook id="form-vceditor--custom-toolbar" height="500"
+
 ### Custom Toolbar Buttons (Plugin System)
 
 Extend the toolbar with custom buttons or dropdowns. Each custom button specifies an `id`, `label`, `icon`, `action` callback, and optional `group`/`order` for positioning.
@@ -133,6 +146,8 @@ Pass extra TipTap extensions via the `extensions` prop to augment the built-in s
 <VcEditor v-model="content" :extensions="[Highlight.configure({ multicolor: true })]" />
 ```
 
+::storybook id="form-vceditor--with-custom-buttons" height="500"
+
 ### Validation with vee-validate Field
 
 Integrate with vee-validate's `Field` component for form-level validation.
@@ -283,6 +298,8 @@ const content = ref("<h1>Title</h1>");
 - [VcTextarea](../vc-textarea/) -- plain multi-line text input (no formatting)
 - [VcInput](../vc-input/) -- single-line text input
 
+::storybook id="form-vceditor--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
diff --git a/framework/ui/components/molecules/vc-field/vc-field.docs.md b/framework/ui/components/molecules/vc-field/vc-field.docs.md
index 3f550d628..05369ae55 100644
--- a/framework/ui/components/molecules/vc-field/vc-field.docs.md
+++ b/framework/ui/components/molecules/vc-field/vc-field.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcField
+category: components
+group: form
+---
+
 # VcField
 
 Read-only display component for labeled information, supporting various content types like text, dates, links, and emails.
@@ -18,6 +24,8 @@ The component uses a vertical layout by default (label above value), but support
 
 ## Basic Usage
 
+::storybook id="form-vcfield--default"
+
 ```vue
 <template>
   <VcField
@@ -31,6 +39,9 @@ import { VcField } from "@vc-shell/framework";
 </script>
 ```
 
+!!! tip "Prefer VcField over disabled VcInput for read-only data"
+VcField renders without form-field chrome (borders, focus rings, placeholders) and formats content in a type-aware way. A disabled `VcInput` carries unnecessary visual noise for display-only scenarios.
+
 ## Key Props
 
 | Prop          | Type                                                  | Default      | Description                                               |
@@ -91,6 +102,8 @@ Each `type` value renders the content differently:
 </template>
 ```
 
+::storybook id="form-vcfield--link" height="300"
+
 ### Horizontal Layout with Custom Ratio
 
 Use horizontal layout for compact key-value displays where the label and value sit side by side. The `aspectRatio` controls the relative widths of the label and value columns:
@@ -121,6 +134,8 @@ Use horizontal layout for compact key-value displays where the label and value s
 </template>
 ```
 
+::storybook id="form-vcfield--horizontal"
+
 ### Copyable ID Fields
 
 The copy button provides visual feedback (checkmark icon for 1 second) after a successful copy:
@@ -211,6 +226,8 @@ In `orientation="horizontal"` the component reserves the `aspectRatio[0]` track
 - [VcLabel](../../atoms/vc-label/) -- standalone label atom used internally
 - [VcCol](../../atoms/vc-col/) -- column layout atom used for aspect ratio
 
+::storybook id="form-vcfield--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
diff --git a/framework/ui/components/molecules/vc-file-upload/vc-file-upload.docs.md b/framework/ui/components/molecules/vc-file-upload/vc-file-upload.docs.md
index 9a4ebb5f3..69d3be7ba 100644
--- a/framework/ui/components/molecules/vc-file-upload/vc-file-upload.docs.md
+++ b/framework/ui/components/molecules/vc-file-upload/vc-file-upload.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcFileUpload
+category: components
+group: form
+---
+
 # VcFileUpload
 
 Drag-and-drop file upload zone with file type filtering, validation, loading state, and error display. Provides both drag-and-drop and click-to-browse interactions in a single drop zone.
@@ -15,6 +21,8 @@ Drag-and-drop file upload zone with file type filtering, validation, loading sta
 
 ## Quick Start
 
+::storybook id="form-vcfileupload--default"
+
 ```vue
 <template>
   <VcFileUpload
@@ -75,6 +83,9 @@ Integrate with vee-validate for file validation rules such as size limits:
 
 When validation fails, the error is displayed below the drop zone using the built-in `VcHint` component. The `upload` event is only emitted when validation passes.
 
+!!! warning "FileList is not a plain Array"
+The `upload` event emits a `FileList` object, not `File[]`. Always convert with `Array.from(files)` before calling array methods like `.map()` or `.filter()`.
+
 ## Loading State
 
 Show a loading overlay while files are being processed or uploaded:
@@ -102,6 +113,8 @@ Override the default drag-and-drop instructions and icon:
 
 The default icon is `"lucide-cloud-upload"`. The default text is pulled from the `COMPONENTS.MOLECULES.VC_FILE_UPLOAD.DRAG_HERE` and `COMPONENTS.MOLECULES.VC_FILE_UPLOAD.BROWSE` locale keys.
 
+::storybook id="form-vcfileupload--loading"
+
 ## Error Display
 
 Errors can come from three sources (by priority): the `errorMessage` prop, vee-validate `rules`, or the `error` slot for fully custom rendering.
@@ -120,6 +133,8 @@ Errors can come from three sources (by priority): the `errorMessage` prop, vee-v
 
 When any error is present, the drop zone border changes to the error color and a ring appears.
 
+::storybook id="form-vcfileupload--with-error-message"
+
 ## Disabled State
 
 Disable all interactions (drag, drop, click, keyboard):
@@ -316,6 +331,8 @@ async function onUpload(files: FileList) {
 - [VcImageTile](../vc-image-tile/) -- Image display tile used inside galleries
 - [VcHint](../../atoms/vc-hint/) -- Used internally for error message display
 
+::storybook id="form-vcfileupload--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
diff --git a/framework/ui/components/molecules/vc-form/vc-form.docs.md b/framework/ui/components/molecules/vc-form/vc-form.docs.md
index a3e0ffaf5..064d349b5 100644
--- a/framework/ui/components/molecules/vc-form/vc-form.docs.md
+++ b/framework/ui/components/molecules/vc-form/vc-form.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcForm
+category: components
+group: form
+---
+
 # VcForm
 
 A lightweight `<form>` wrapper that provides consistent styling, prevents default browser submission, and serves as the standard container for validated form fields in blade detail views.
@@ -16,6 +22,8 @@ A lightweight `<form>` wrapper that provides consistent styling, prevents defaul
 
 ## Quick Start
 
+::storybook id="form-vcform--basic"
+
 ```vue
 <template>
   <VcForm @submit="handleSubmit">
@@ -50,6 +58,9 @@ function handleSubmit() {
 
 ---
 
+!!! note "Form validation is handled by vee-validate"
+VcForm itself does not validate fields — it only provides the `<form>` wrapper. Use vee-validate's `Field` component around each input that needs validation rules.
+
 ## Features
 
 ### Basic Form Layout (VcForm + VcRow + VcCol)
@@ -174,6 +185,8 @@ const bladeToolbar = ref<IBladeToolbar[]>([
 
 ---
 
+::storybook id="form-vcform--with-fieldsets" height="500"
+
 ## Recipes
 
 ### Complete CRUD Blade Form
@@ -303,6 +316,8 @@ onBeforeClose(async () => {
 </script>
 ```
 
+::storybook id="form-vcform--horizontal-layout" height="400"
+
 ### Form with Mixed Field Types
 
 Demonstrates inputs, selects, checkboxes, and switches together in a single form.
diff --git a/framework/ui/components/molecules/vc-image-tile/vc-image-tile.docs.md b/framework/ui/components/molecules/vc-image-tile/vc-image-tile.docs.md
index 899c0fcf8..72d9c4b30 100644
--- a/framework/ui/components/molecules/vc-image-tile/vc-image-tile.docs.md
+++ b/framework/ui/components/molecules/vc-image-tile/vc-image-tile.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcImageTile
+category: components
+group: data-display
+---
+
 # VcImageTile
 
 Square image tile with skeleton loading, fade-in transition, and a slide-up action tray on hover (desktop) or tap (touch devices).
@@ -10,6 +16,8 @@ Square image tile with skeleton loading, fade-in transition, and a slide-up acti
 
 ## Basic Usage
 
+::storybook id="action-vcimagetile--default"
+
 ```vue
 <template>
   <div style="width: 160px;">
@@ -73,6 +81,8 @@ interface VcImageTileActions {
 
 ## Common Patterns
 
+::storybook id="action-vcimagetile--all-actions"
+
 ### Image Grid
 
 ```vue
@@ -114,6 +124,8 @@ interface VcImageTileActions {
 </VcImageTile>
 ```
 
+::storybook id="action-vcimagetile--skeleton"
+
 ### Skeleton State
 
 When `src` is not provided or the image is still loading, a shimmer animation skeleton is displayed automatically. No additional configuration is needed.
diff --git a/framework/ui/components/molecules/vc-input-currency/vc-input-currency.docs.md b/framework/ui/components/molecules/vc-input-currency/vc-input-currency.docs.md
index 4dcf3dab6..53630a867 100644
--- a/framework/ui/components/molecules/vc-input-currency/vc-input-currency.docs.md
+++ b/framework/ui/components/molecules/vc-input-currency/vc-input-currency.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcInputCurrency
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcInputCurrency
 
 A specialized currency input that combines locale-aware number formatting (grouping separators, decimal precision) with a dropdown for selecting the currency. Built on top of [vue-currency-input](https://dm4t2.github.io/vue-currency-input/) and [VcInputDropdown](../vc-input-dropdown/).
 
+::storybook id="form-vcinputcurrency--default"
+
 ## When to Use
 
 - Entering monetary values with currency selection (e.g., product prices, order totals, shipping costs)
@@ -60,6 +71,8 @@ The dropdown portion renders the available currencies. Use `optionLabel` and `op
 
 ### Precision Control
 
+::storybook id="form-vcinputcurrency--precision-options"
+
 The `precision` prop controls the number of decimal places (0--15). The formatting engine rounds and pads the value accordingly.
 
 ```vue
@@ -146,6 +159,8 @@ const form = reactive({
 
 ### States
 
+::storybook id="form-vcinputcurrency--with-error"
+
 ```vue
 <!-- Required -->
 <VcInputCurrency v-model="price" v-model:option="currency" :options="currencies" label="Price" required />
@@ -334,3 +349,15 @@ Additionally inherits all `--input-*` CSS variables from VcInput/VcInputDropdown
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Built as a wrapper around `VcInputDropdown`. The numeric input side uses `vue-currency-input` for locale-aware formatting; the right side is `VcInputDropdown`'s built-in dropdown.
+- The minus key (`-`) and exponential notation key (`e`) are blocked at the `keydown` level, not via `input` validation.
+- `precision` is forwarded directly to `vue-currency-input`'s `CurrencyInputOptions`.
+- `currencyDisplay` maps to the `vue-currency-input` option of the same name.
+- Source file: `framework/ui/components/molecules/vc-input-currency/vc-input-currency.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-input-dropdown/vc-input-dropdown.docs.md b/framework/ui/components/molecules/vc-input-dropdown/vc-input-dropdown.docs.md
index 3e0d7e585..9a8ed1210 100644
--- a/framework/ui/components/molecules/vc-input-dropdown/vc-input-dropdown.docs.md
+++ b/framework/ui/components/molecules/vc-input-dropdown/vc-input-dropdown.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcInputDropdown
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcInputDropdown
 
 A composite component that combines a text input field with a dropdown option selector in a single control. The user types a value in the input while also selecting a category, unit, or format from the attached dropdown.
 
+::storybook id="form-vcinputdropdown--default"
+
 ## When to Use
 
 - Input value paired with a unit selector (e.g., "100 cm", "50 kg")
@@ -42,6 +53,8 @@ The component uses a dual `v-model` pattern: `v-model` controls the input value,
 
 ## Object Options
 
+::storybook id="form-vcinputdropdown--with-object-options"
+
 When options are objects instead of primitives, use `optionValue` and `optionLabel` to tell the component which properties to use:
 
 ```vue
@@ -106,6 +119,8 @@ Supported types: `"text"`, `"password"`, `"email"`, `"tel"`, `"number"`, `"integ
 
 ## Component States
 
+::storybook id="form-vcinputdropdown--states"
+
 VcInputDropdown inherits all standard form field states:
 
 ```vue
@@ -298,3 +313,14 @@ Replace the default dropdown toggle with a custom element using the `button` slo
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Internally composed of two elements side-by-side: a `VcInput` for the text portion and a `VcSelect`-like dropdown panel for the option portion.
+- The `button` slot replaces only the dropdown toggle button element, not the entire dropdown panel.
+- The `option` slot receives `{ index, opt, selected, toggleOption }` — `toggleOption` must be called to actually select the item.
+- Source file: `framework/ui/components/molecules/vc-input-dropdown/vc-input-dropdown.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-input-group/vc-input-group.docs.md b/framework/ui/components/molecules/vc-input-group/vc-input-group.docs.md
index 5a97ee5e2..d0906f41a 100644
--- a/framework/ui/components/molecules/vc-input-group/vc-input-group.docs.md
+++ b/framework/ui/components/molecules/vc-input-group/vc-input-group.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcInputGroup
+category: components
+group: form
+---
+
 # VcInputGroup
 
 A semantic `<fieldset>` wrapper that groups related form controls under a shared label, error state, and ARIA context. Propagates `disabled` and `name` to child controls via provide/inject.
 
+::storybook id="form-vcinputgroup--form-fields"
+
 ## When to Use
 
 - Grouping related form fields with a shared section label (e.g., "Billing details", "Shipping address")
@@ -56,6 +64,8 @@ const lastName = ref("");
 
 ### Radio Group
 
+::storybook id="form-vcinputgroup--radios-horizontal"
+
 ```vue
 <VcInputGroup label="Payment method" role="radiogroup" orientation="horizontal" name="payment">
   <VcRadioButton v-model="payment" value="card" label="Card" />
@@ -111,3 +121,14 @@ const lastName = ref("");
 - [VcRadioButton](../vc-radio-button/) -- radio buttons to group
 - [VcInput](../vc-input/) -- text inputs to group
 - [VcSelect](../vc-select/) -- selects to group
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `disabled` and `name` are provided via Vue's provide/inject mechanism using injection keys from `framework/injection-keys.ts`. Child form controls (`VcInput`, `VcRadioButton`, etc.) inject these to inherit group-level state automatically.
+- The `orientation` prop controls flex direction (`column` vs `row`) on the fieldset's content area.
+- Source file: `framework/ui/components/molecules/vc-input-group/vc-input-group.vue`
+- Context file: `framework/ui/components/molecules/vc-input-group/context.ts`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-input/vc-input.docs.md b/framework/ui/components/molecules/vc-input/vc-input.docs.md
index 739c08062..8bd7f341c 100644
--- a/framework/ui/components/molecules/vc-input/vc-input.docs.md
+++ b/framework/ui/components/molecules/vc-input/vc-input.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcInput
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcInput
 
 A single-line text input component for forms in vc-shell applications. Supports multiple input types (text, number, password, email, and more), prefix/suffix decorations, inner/outer slot content, built-in clearable state, password visibility toggle, loading indicator, debounced model updates, and integration with vee-validate for validation.
 
+::storybook id="form-vcinput--default"
+
 ## When to Use
 
 | Scenario                                             | Component                                                              |
@@ -44,10 +55,14 @@ const productName = ref("");
 
 This renders a labeled text input with placeholder text. The value is two-way bound via `v-model`.
 
+::storybook id="form-vcinput--all-states" height="450"
+
 ---
 
 ## Input Types
 
+::storybook id="form-vcinput--input-types" height="500"
+
 VcInput supports the following `type` values. Each type adjusts the native `<input>` behavior and, in some cases, adds extra UI or filtering logic.
 
 | Type             | Behavior                                                                             |
@@ -298,6 +313,8 @@ Override the default error message or hint text rendering.
 
 ## Sizes
 
+::storybook id="form-vcinput--all-sizes"
+
 Two size variants are available:
 
 | Size        | Height | Use case                                   |
@@ -771,3 +788,16 @@ VcInput follows WAI-ARIA best practices for form fields:
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- The `type="date"`, `type="datetime-local"`, and `type="color"` values trigger internal delegation — the component renders `VcDatePicker` or `VcColorInput` instead of a native `<input>`. All forwarded props are passed via `v-bind="$attrs"`.
+- Debounce is implemented via a `useDebounceFn` wrapper from VueUse. The internal `temp` ref holds the raw typing value; the `modelValue` update is deferred.
+- `number` / `integer` type filtering uses `keydown` event guards — not `input` event filtering — to block `-`, `+`, `e`, and (for `integer`) `.` keys before they reach the input.
+- `type="password"` show/hide toggle is controlled by `showPassword` ref; the native `input` type toggles between `"password"` and `"text"`.
+- The `control` slot replaces the native `<input>` with an arbitrary element. The `emitValue` scope function wraps the debounce logic, so custom controls respect the `debounce` prop automatically.
+- Source file: `framework/ui/components/molecules/vc-input/vc-input.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-input/vc-input.vue b/framework/ui/components/molecules/vc-input/vc-input.vue
index e292497b9..baab3c812 100644
--- a/framework/ui/components/molecules/vc-input/vc-input.vue
+++ b/framework/ui/components/molecules/vc-input/vc-input.vue
@@ -2,7 +2,9 @@
   <!-- Skeleton mode -->
   <div
     v-if="bladeLoading"
+    v-bind="rootAttrs"
     class="vc-input vc-input--skeleton"
+    :class="$attrs.class"
   >
     <VcSkeleton
       v-if="label"
@@ -20,6 +22,7 @@
   <!-- Backward compat delegation: date types -->
   <VcDatePicker
     v-else-if="type === 'date' || type === 'datetime-local'"
+    v-bind="attrs"
     :model-value="modelValue"
     :type="type"
     :date-picker-options="datePickerOptions"
@@ -45,6 +48,7 @@
   <!-- Backward compat delegation: color type -->
   <VcColorInput
     v-else-if="type === 'color'"
+    v-bind="attrs"
     :model-value="(modelValue as string) ?? null"
     :label="label"
     :placeholder="placeholder"
@@ -69,8 +73,10 @@
   <!-- Clean text input -->
   <div
     v-else
+    v-bind="rootAttrs"
     class="vc-input"
     :class="[
+      $attrs.class,
       `vc-input--${type}`,
       {
         'vc-input--clearable': clearable,
@@ -262,7 +268,7 @@
   </div>
 </template>
 <script lang="ts" setup>
-import { computed, ref, unref, watch, type VNode } from "vue";
+import { computed, ref, unref, useAttrs, watch, type VNode } from "vue";
 import { VcLabel } from "@ui/components/atoms/vc-label";
 import { VcIcon } from "@ui/components/atoms/vc-icon";
 import { VcHint } from "@ui/components/atoms/vc-hint";
@@ -339,6 +345,10 @@ export interface Emits {
   (event: "focus"): void;
 }
 
+defineOptions({
+  inheritAttrs: false,
+});
+
 const props = withDefaults(defineProps<Props>(), {
   type: "text",
   name: "Field",
@@ -347,6 +357,12 @@ const props = withDefaults(defineProps<Props>(), {
   size: "default",
 });
 
+const attrs = useAttrs();
+const rootAttrs = computed(() => {
+  const { class: _class, ...rest } = attrs;
+  return rest;
+});
+
 const emit = defineEmits<Emits>();
 const bladeLoading = useBladeLoading();
 
diff --git a/framework/ui/components/molecules/vc-menu/vc-menu.docs.md b/framework/ui/components/molecules/vc-menu/vc-menu.docs.md
index 1183a33dd..1b603104d 100644
--- a/framework/ui/components/molecules/vc-menu/vc-menu.docs.md
+++ b/framework/ui/components/molecules/vc-menu/vc-menu.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcMenu
+category: components
+group: navigation
+---
+
 # VcMenu
 
 Compositional navigation menu component for building sidebar navigation with sections, groups, nested items, badges, and loading skeletons.
 
+::storybook id="navigation-vcmenu--default"
+
 ## When to Use
 
 - Building the main navigation sidebar in admin applications
@@ -64,6 +72,8 @@ import { VcMenu, VcMenuItem, VcMenuGroup } from "@vc-shell/framework";
 
 ## Common Patterns
 
+::storybook id="navigation-vcmenu--sections"
+
 ### Section Groups with Nested Items
 
 ```vue
@@ -93,6 +103,8 @@ import { VcMenu, VcMenuItem, VcMenuGroup } from "@vc-shell/framework";
 
 ### Collapsed State
 
+::storybook id="navigation-vcmenu--collapsed"
+
 When `expanded` is `false`, the menu shows only icons and letter abbreviations. Groups show tooltips on hover. The container width should be reduced (e.g., 64px).
 
 ## CSS Variables
@@ -113,3 +125,15 @@ When `expanded` is `false`, the menu shows only icons and letter abbreviations.
 - [VcMenuItem](../vc-menu/) — individual menu item with icon, title, badge
 - [VcMenuGroup](../vc-menu/) — collapsible group container (supports `variant="section"` for top-level sections)
 - [VcDropdown](../vc-dropdown/) — contextual dropdown menus
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `VcMenuExpandedKey` is the provide/inject key (`framework/ui/components/molecules/vc-menu/constants.ts`) used by `VcMenu` to broadcast the `expanded` state down to all `VcMenuItem` and `VcMenuGroup` descendants. Components can also override it locally via their own `expanded` prop.
+- `VcMenuGroup` persists its open/closed state in `localStorage` with a key scoped to `vc_menu_<appName>_<groupId>_open`, where `appName` is derived from the first URL path segment.
+- The loading skeleton in `VcMenu` is hardcoded to mimic a realistic 2-section structure. It does not reflect actual slot content.
+- `VcMenuItem` uses a `VcTooltip` that activates only when the menu is collapsed (`!menuExpanded`), showing the item title on hover.
+- `VcMenuGroup` children animate via CSS `grid-template-rows: 0fr → 1fr` transition — no JS required.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-multivalue/vc-multivalue.docs.md b/framework/ui/components/molecules/vc-multivalue/vc-multivalue.docs.md
index 9c2f9587c..b62f82b41 100644
--- a/framework/ui/components/molecules/vc-multivalue/vc-multivalue.docs.md
+++ b/framework/ui/components/molecules/vc-multivalue/vc-multivalue.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcMultivalue
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcMultivalue
 
 A multi-value input component for collecting multiple entries as chips/tags. Supports two distinct modes: **free-form entry** (text, number, date, color) where users type values and press Enter, and **dictionary mode** with a searchable dropdown of predefined options.
 
+::storybook id="form-vcmultivalue--default"
+
 ## When to Use
 
 - Collecting multiple tags, keywords, or labels (e.g., product tags, email recipients)
@@ -46,6 +57,8 @@ In the default mode (`multivalue` is `false`), users type a value into the input
 
 ### Dictionary Mode (Dropdown Selection)
 
+::storybook id="form-vcmultivalue--single-value-mode"
+
 When the `multivalue` prop is `true` and `options` are provided, the component displays a searchable dropdown. Users click the field to open the dropdown, search within options, and select items. Already-selected items are automatically excluded from the dropdown.
 
 ```vue
@@ -139,6 +152,8 @@ const form = reactive({
 
 ### Custom Rendering with Slots
 
+::storybook id="form-vcmultivalue--custom-option-display"
+
 Use `#option` for dropdown items and `#selected-item` for chips:
 
 ```vue
@@ -344,3 +359,16 @@ The component uses `--multivalue-*` variables that fall back to `--select-*` tok
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Composed of internal sub-components in `vc-multivalue/_internal/`: the chip list renderer, the dropdown panel, and the trigger input.
+- Composables are in `vc-multivalue/composables/` — chip management and dropdown open/close state are separated into composables.
+- Free-form mode: each `keydown` for Enter or comma (`','`) triggers a chip add; Backspace on empty input removes the last chip.
+- Dictionary mode: already-selected items are filtered out of the dropdown list reactively.
+- Source file: `framework/ui/components/molecules/vc-multivalue/vc-multivalue.vue`
+- Internal components: `framework/ui/components/molecules/vc-multivalue/_internal/`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-pagination/vc-pagination.docs.md b/framework/ui/components/molecules/vc-pagination/vc-pagination.docs.md
index 08c50da0e..3ac51304e 100644
--- a/framework/ui/components/molecules/vc-pagination/vc-pagination.docs.md
+++ b/framework/ui/components/molecules/vc-pagination/vc-pagination.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcPagination
+category: components
+group: navigation
+---
+
+!!! tip "Quick reference"
+Jump to [Props](#props) · [Events](#events) · [CSS Variables](#css-variables) · [Accessibility](#accessibility)
+
 # VcPagination
 
 Page navigation control with first/previous/next/last buttons and a sliding window of page numbers. Automatically adapts the number of visible page buttons for mobile viewports.
 
+::storybook id="navigation-vcpagination--default"
+
 ## When to Use
 
 - Navigating paginated data sets in tables, lists, or grids
@@ -39,6 +50,8 @@ function onPageChange(page: number) {
 
 ## Sliding Page Window
 
+::storybook id="navigation-vcpagination--many-pages"
+
 VcPagination displays a sliding window of page number buttons centered on the current page. The window size adapts automatically:
 
 - **Desktop:** 5 visible page buttons (default)
@@ -290,3 +303,15 @@ currentPage.value = Math.min(currentPage.value, totalPages.value);
 
 - [VcDataTable](../../organisms/vc-table) -- Data table that commonly pairs with pagination for large datasets
 - [VcSelect](../vc-select/) -- Can be used alongside pagination for a "rows per page" selector
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `localCurrentPage` is an internal ref synced from `props.currentPage` via a watcher. This prevents the UI from jumping when the parent has not yet updated the prop after an `itemClick` event.
+- Responsive defaults: `MAX_PAGES_MOBILE = 3`, `MAX_PAGES_DESKTOP = 5`. Both are overridden by `maxPages` prop.
+- `effectiveShowFirstLast` defaults to `true` when `showFirstLast` prop is `undefined`.
+- The `setPage` function clamps clicks to valid range `[1, props.pages]` and handles both `number` and `string` inputs (supports programmatic usage).
+- The `variant` prop is defined but currently unused in the template — reserved for a future "minimal" style.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-radio-button/vc-radio-button.docs.md b/framework/ui/components/molecules/vc-radio-button/vc-radio-button.docs.md
index 19a86c39b..d16b5b7a1 100644
--- a/framework/ui/components/molecules/vc-radio-button/vc-radio-button.docs.md
+++ b/framework/ui/components/molecules/vc-radio-button/vc-radio-button.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcRadioButton
+category: components
+group: form
+---
+
 # VcRadioButton
 
 A radio button component for selecting a single option from a group. Supports string, number, and boolean value types.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Basic Usage](#basic-usage), [Common Patterns](#common-patterns), [Props](#key-props), [Accessibility](#accessibility).
+
+::storybook id="form-vcradiobutton--default"
+
 ## Overview
 
 Radio buttons are the standard UI pattern for selecting exactly one option from a small, visible set. Unlike dropdowns (VcSelect), radio buttons show all options simultaneously, making them ideal when there are 2-6 choices and the user benefits from seeing everything at once.
@@ -115,6 +126,8 @@ const priority = ref(2);
 
 ### Binary Mode
 
+::storybook id="form-vcradiobutton--binary"
+
 In binary mode, clicking toggles between `true` and `false` rather than comparing to a `value`. This is useful for standalone boolean options:
 
 ```vue
@@ -201,3 +214,15 @@ Do not mix `binary` mode with regular `value` comparison in the same group. Bina
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcRadioButton wraps a native `<input type="radio">` with custom CSS appearance. `checked` state is computed via `isEqual` (lodash) to support object-typed values.
+- `binary` mode: `onChange` emits `!checked.value` (a boolean toggle) instead of `props.value`. Do not mix binary and value modes within the same group.
+- The `name` attribute is critical for native keyboard group navigation — always set the same `name` across a group.
+- `useFormField` injects validation context (error, disabled, name) from a parent form provider.
+- Source file: `framework/ui/components/molecules/vc-radio-button/vc-radio-button.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-radio-group/vc-radio-group.docs.md b/framework/ui/components/molecules/vc-radio-group/vc-radio-group.docs.md
index 509041e93..c07e7d88c 100644
--- a/framework/ui/components/molecules/vc-radio-group/vc-radio-group.docs.md
+++ b/framework/ui/components/molecules/vc-radio-group/vc-radio-group.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcRadioGroup
+category: components
+group: form
+---
+
 # VcRadioGroup
 
 Accessible radio button group that wraps radio controls in a semantic fieldset with shared label, hint, error state, and layout control.
 
+::storybook id="form-vcradiogroup--default"
+
 ## When to Use
 
 - Selecting exactly one option from a set (e.g., payment method, shipping speed)
@@ -74,6 +82,8 @@ interface RadioGroupOption<V = string | number | boolean> {
 
 ### Horizontal Layout
 
+::storybook id="form-vcradiogroup--horizontal"
+
 ```vue
 <VcRadioGroup
   v-model="priority"
@@ -89,6 +99,8 @@ interface RadioGroupOption<V = string | number | boolean> {
 
 ### With Disabled Option
 
+::storybook id="form-vcradiogroup--with-disabled-option"
+
 ```vue
 <VcRadioGroup
   v-model="plan"
@@ -135,3 +147,13 @@ interface RadioGroupOption<V = string | number | boolean> {
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcRadioGroup delegates rendering to `VcInputGroup` (semantic fieldset wrapper) and renders `VcRadioButton` items from the `options` array, or passes through the default slot for custom layouts.
+- The group generates a unique `name` attribute via `useId()` when none is provided, ensuring native radio group behavior.
+- Source file: `framework/ui/components/molecules/vc-radio-group/vc-radio-group.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-rating/vc-rating.docs.md b/framework/ui/components/molecules/vc-rating/vc-rating.docs.md
index b9b78772f..51982710e 100644
--- a/framework/ui/components/molecules/vc-rating/vc-rating.docs.md
+++ b/framework/ui/components/molecules/vc-rating/vc-rating.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcRating
+category: components
+group: form
+---
+
 # VcRating
 
 Read-only rating display component that visualizes a numeric value as stars, a star-and-text combination, or plain text. Designed for displaying aggregate ratings in detail views, list columns, and dashboards.
@@ -15,6 +21,8 @@ Read-only rating display component that visualizes a numeric value as stars, a s
 
 ## Quick Start
 
+::storybook id="form-vcrating--stars"
+
 ```vue
 <template>
   <VcRating
@@ -29,6 +37,9 @@ import { VcRating } from "@vc-shell/framework";
 </script>
 ```
 
+!!! tip "Display-only component"
+VcRating is a read-only display component. It does not support user interaction for selecting a rating. For interactive rating input, build a custom component.
+
 ## Display Variants
 
 VcRating offers three visual modes controlled by the `variant` prop:
@@ -55,6 +66,8 @@ Shows a single filled star icon alongside a numeric fraction. Compact and precis
 
 Displays just the numeric fraction. Minimal footprint for dense layouts like table cells.
 
+::storybook id="form-vcrating--text-only"
+
 ```vue
 <VcRating :model-value="8" :max="10" variant="text" />
 <!-- Renders: 8/10 -->
@@ -74,6 +87,8 @@ The default scale is 1-5 stars. Override with the `max` prop for different scale
 
 > **Tip:** For scales larger than 5, prefer the `"star-and-text"` or `"text"` variant. Rendering 10 individual star icons can be visually crowded.
 
+::storybook id="form-vcrating--star-and-text"
+
 ## Placeholder for No Rating
 
 When `modelValue` is `0`, `null`, or `undefined`, display a placeholder message:
@@ -258,6 +273,8 @@ Use the `"star-and-text"` or `"text"` variant in table cell slots for a compact
 - [VcLabel](../../atoms/vc-label/) -- Label atom used internally for the label and tooltip
 - [VcIcon](../../atoms/vc-icon/) -- Renders the star icons internally
 
+::storybook id="form-vcrating--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
diff --git a/framework/ui/components/molecules/vc-select/vc-select.docs.md b/framework/ui/components/molecules/vc-select/vc-select.docs.md
index 823092668..9043ec98f 100644
--- a/framework/ui/components/molecules/vc-select/vc-select.docs.md
+++ b/framework/ui/components/molecules/vc-select/vc-select.docs.md
@@ -1,9 +1,20 @@
+---
+title: VcSelect
+category: components
+group: form
+---
+
 # VcSelect
 
 A dropdown list component for selecting one or multiple values. Supports synchronous and asynchronous data sources, search with debounce, infinite scrolling, custom option templates, and full integration with the framework's validation system.
 
 VcSelect is one of the most widely used components in vc-shell. It covers most selection scenarios: from a simple dropdown with a static list to searching via a server API with pagination.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Data Sources](#data-sources), [Multiple Selection](#multiple-selection), [Slots](#slots), [Props](#props).
+
+::storybook id="form-vcselect--basic"
+
 ## When to Use
 
 | Scenario                                | Component                                |
@@ -82,6 +93,8 @@ In this case `optionValue` and `optionLabel` are not needed — the component us
 
 ### Async Function (Server API)
 
+::storybook id="form-vcselect--async-options" height="450"
+
 To load data from a server, pass a function instead of an array. This is the most powerful mode — it automatically provides:
 
 - Search with debounce (500ms by default)
@@ -142,6 +155,8 @@ const loadProducts = async (keyword?: string, skip?: number, ids?: string[]) =>
 
 ## Multiple Selection
 
+::storybook id="form-vcselect--multiple-selection"
+
 Add `multiple` to enable selecting several values. The model becomes an array:
 
 ```vue
@@ -178,6 +193,8 @@ Selected values are displayed as chips with a remove button. The `clearable` but
 
 ## Search and Filtering
 
+::storybook id="form-vcselect--searchable"
+
 Enable `searchable` to add a search field to the dropdown:
 
 ```vue
@@ -192,6 +209,8 @@ Enable `searchable` to add a search field to the dropdown:
 
 ## Custom Option Rendering
 
+::storybook id="form-vcselect--custom-option-slot" height="450"
+
 Use the `#option` slot for full control over how each option is rendered:
 
 ```vue
@@ -678,3 +697,16 @@ Don't forget `:key` with cascading selects, otherwise the second select will ret
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcSelect is split into three layers: `vc-select.vue` (orchestrator), `SelectTrigger.vue` (trigger button + chips), `SelectDropdown.vue` (popup list).
+- Composable split: `useSelectDataSource` (options loading, infinite scroll, search), `useSelectSelection` (model-to-option mapping, toggle, remove), `useSelectValueMapping` (optionValue/optionLabel getters), `useSelectDropdown` (Floating UI positioning), `useSelectVisibility` (IntersectionObserver for lazy open).
+- `emitValue: true` (default) means `modelValue` is always a primitive (string/number/boolean). `emitValue: false` means full option object. The `mapOptions` flag controls whether resolved objects are stored in the cache for label resolution.
+- Infinite scroll is driven by `useIntersectionObserver` on a 1px sentinel element inside the dropdown viewport.
+- Keyboard navigation is managed by `useKeyboardNavigation` (`core/composables/`) — arrow keys, Enter, Escape. The composable attaches/detaches listeners when the dropdown opens/closes.
+- Source files: `framework/ui/components/molecules/vc-select/`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-select/vc-select.vue b/framework/ui/components/molecules/vc-select/vc-select.vue
index 1ee22c925..225611c98 100644
--- a/framework/ui/components/molecules/vc-select/vc-select.vue
+++ b/framework/ui/components/molecules/vc-select/vc-select.vue
@@ -2,7 +2,9 @@
   <!-- Skeleton mode -->
   <div
     v-if="bladeLoading"
+    v-bind="rootAttrs"
     class="vc-select vc-select--skeleton"
+    :class="$attrs.class"
   >
     <VcSkeleton
       v-if="label"
@@ -21,15 +23,19 @@
   <div
     v-else
     ref="selectRootRef"
+    v-bind="rootAttrs"
     class="vc-select"
-    :class="{
-      'vc-select--opened': isOpened,
-      'vc-select--error': invalid,
-      'vc-select--disabled': resolvedDisabled,
-      'vc-select--has-hint-or-error': invalid || hint,
-      'vc-select--no-outline': !outline,
-      'vc-select--focused': isFocused,
-    }"
+    :class="[
+      $attrs.class,
+      {
+        'vc-select--opened': isOpened,
+        'vc-select--error': invalid,
+        'vc-select--disabled': resolvedDisabled,
+        'vc-select--has-hint-or-error': invalid || hint,
+        'vc-select--no-outline': !outline,
+        'vc-select--focused': isFocused,
+      },
+    ]"
   >
     <!-- Select label -->
     <VcLabel
@@ -186,7 +192,7 @@
     P extends { results?: T[]; totalCount?: number } | undefined = undefined
   "
 >
-import { ref, computed, watch, watchEffect, nextTick } from "vue";
+import { ref, computed, watch, watchEffect, nextTick, useAttrs } from "vue";
 import { useFormField } from "@ui/composables/useFormField";
 import { useBladeLoading } from "@ui/composables/useBladeLoading";
 import { useIntersectionObserver } from "@vueuse/core";
@@ -249,6 +255,10 @@ type SelectProps<ModelValueType> = IFormFieldProps &
     emitValue?: boolean;
   };
 
+defineOptions({
+  inheritAttrs: false,
+});
+
 defineSlots<{
   /**
    * Custom select control
@@ -340,6 +350,12 @@ const props = withDefaults(defineProps<SelectProps<V>>(), {
   placement: "bottom",
 });
 
+const attrs = useAttrs();
+const rootAttrs = computed(() => {
+  const { class: _class, ...rest } = attrs;
+  return rest;
+});
+
 const emit = defineEmits<{
   /**
    * Emitted when the component needs to change the model; Is also used by v-model
diff --git a/framework/ui/components/molecules/vc-slider/vc-slider.docs.md b/framework/ui/components/molecules/vc-slider/vc-slider.docs.md
index 984969d9c..f8fe1dafe 100644
--- a/framework/ui/components/molecules/vc-slider/vc-slider.docs.md
+++ b/framework/ui/components/molecules/vc-slider/vc-slider.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcSlider
+category: components
+group: form
+---
+
 # VcSlider
 
 A content carousel component built on Swiper.js for displaying slides with optional navigation buttons. Renders any content via the default slot.
 
+::storybook id="form-vcslider--default"
+
 ## When to Use
 
 - Image carousels (product galleries, banners)
@@ -65,6 +73,8 @@ const products = [
 
 ### Custom Navigation Buttons
 
+::storybook id="form-vcslider--custom-navigation"
+
 ```vue
 <VcSlider :slides="items" navigation>
   <template #default="{ slide }">
@@ -123,3 +133,15 @@ const products = [
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcSlider wraps the `swiper/vue` `<Swiper>` / `<SwiperSlide>` components with the `Navigation` module. Navigation buttons are custom DOM elements (`.vc-slider__prev` / `.vc-slider__next`) referenced by Swiper's `navigation.prevEl` / `nextEl` selectors.
+- `overflow` prop toggles `overflow: visible` on the swiper container, allowing slides to bleed outside bounds — useful for "peek" effects.
+- `slidesPerView="auto"` (default) lets each slide size itself from content. Pass a number for fixed-count layouts.
+- The `slides` prop accepts any array. Each item is exposed as `{ slide }` in the default scoped slot.
+- Source file: `framework/ui/components/molecules/vc-slider/vc-slider.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-switch/vc-switch.docs.md b/framework/ui/components/molecules/vc-switch/vc-switch.docs.md
index ac39fb662..f68c8993a 100644
--- a/framework/ui/components/molecules/vc-switch/vc-switch.docs.md
+++ b/framework/ui/components/molecules/vc-switch/vc-switch.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcSwitch
+category: components
+group: form
+---
+
 # VcSwitch
 
 A toggle switch component for binary on/off choices. Renders as a sliding track with a thumb indicator and supports labels, hints, validation, and value inversion.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Features](#features), [Props](#props), [CSS Variables](#css-variables).
+
+::storybook id="form-vcswitch--default"
+
 ## When to Use
 
 - Toggling a feature or setting on/off (e.g., "Enable notifications", "Publish product")
@@ -46,6 +57,8 @@ The `label` prop renders text above the switch. Use `hint` for helper text below
 
 ### Value Inversion with trueValue / falseValue
 
+::storybook id="form-vcswitch--variants"
+
 By default, `v-model` maps `true` to the checked (on) state and `false` to unchecked (off). The `trueValue` and `falseValue` props let you invert the mapping when your data model uses opposite semantics.
 
 ```vue
@@ -294,3 +307,15 @@ const isActive = ref(true);
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcSwitch renders a hidden `<input type="checkbox">` with `role="switch"`. Visual state is driven by CSS (`:checked + .vc-switch__slider`). No JavaScript DOM manipulation needed for toggling.
+- `invertValue` handles the `trueValue`/`falseValue` mapping — both on read (for rendering) and on write (for emitting). When `trueValue` is `false`, the display is inverted.
+- The `tooltip` prop is kept for backward compatibility (legacy vc-shell code used it as hint text). A dev-mode `console.warn` nudges maintainers to migrate. The prop is mapped to `hintText` computed.
+- `useFormField` injects validation context (error, disabled, name) from a parent form provider.
+- Source file: `framework/ui/components/molecules/vc-switch/vc-switch.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-textarea/vc-textarea.docs.md b/framework/ui/components/molecules/vc-textarea/vc-textarea.docs.md
index 1748ab047..8fbb2a680 100644
--- a/framework/ui/components/molecules/vc-textarea/vc-textarea.docs.md
+++ b/framework/ui/components/molecules/vc-textarea/vc-textarea.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcTextarea
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcTextarea
 
 A multi-line text input field for entering and editing large blocks of text. Provides label, placeholder, hint text, validation error display, character limits, and multilanguage support out of the box.
 
+::storybook id="form-vctextarea--default"
+
 ## When to Use
 
 - Multi-line free-form text: descriptions, comments, notes, addresses, bios
@@ -99,6 +110,8 @@ const form = reactive({
 
 ### States
 
+::storybook id="form-vctextarea--with-error"
+
 ```vue
 <!-- Required field -->
 <VcTextarea v-model="value" label="Address" required />
@@ -112,6 +125,8 @@ const form = reactive({
 
 ## Recipes
 
+::storybook id="form-vctextarea--with-max-length"
+
 ### Product Description in a Blade Form
 
 A typical product-editing blade with a description textarea and character limit:
@@ -293,3 +308,15 @@ const description = ref<string>("");
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- The native `<textarea>` element is exposed via `defineExpose({ focus })` so parent components can call `focus()` programmatically.
+- The `invalid` computed is `props.error || !!props.errorMessage` — either flag alone triggers error styling.
+- There is no debounce on the textarea; all `input` events fire `update:modelValue` immediately.
+- The `disabled` state is inherited from the nearest `VcInputGroup` ancestor via provide/inject (when used inside a group).
+- Source file: `framework/ui/components/molecules/vc-textarea/vc-textarea.vue`
+
+<!-- internal:end -->
diff --git a/framework/ui/components/molecules/vc-toast/vc-toast.docs.md b/framework/ui/components/molecules/vc-toast/vc-toast.docs.md
index e9896d585..1319d3931 100644
--- a/framework/ui/components/molecules/vc-toast/vc-toast.docs.md
+++ b/framework/ui/components/molecules/vc-toast/vc-toast.docs.md
@@ -1,3 +1,12 @@
+---
+title: VcToast
+category: components
+group: feedback
+---
+
+!!! tip "Quick reference"
+Jump to [Props](#props-component) · [Events](#events) · [Notification Service Methods](#notification-service-methods) · [CSS Variables](#css-variables)
+
 # VcToast
 
 Toast notification component with type-based styling, auto-dismiss timer, swipe-to-dismiss on touch devices, and Sonner-style stacking animations. Most applications interact with toasts through the `notification` service rather than mounting the component directly.
@@ -17,6 +26,8 @@ When NOT to use:
 
 ## Quick Start
 
+::storybook id="overlay-vctoast--notification-service"
+
 The recommended approach is the `notification` service, not direct component usage:
 
 ```ts
@@ -98,6 +109,8 @@ Available positions: `"top-center"`, `"top-right"`, `"top-left"`, `"bottom-cente
 
 ### Notification Types
 
+::storybook id="overlay-vctoast--success"
+
 Each type displays a distinct icon and colored left accent border.
 
 | Type      | Icon           | Accent Color             | Use Case                     |
@@ -129,6 +142,8 @@ notification(OrderNotification, { timeout: 10000, pauseOnHover: true });
 
 ### Stacking, Swipe, and Auto-dismiss
 
+::storybook id="overlay-vctoast--multiple-notifications"
+
 Toasts use Sonner-style stacking: the newest toast is in front, older toasts scale down behind it, and hovering expands the full stack. Only 3 toasts are visible by default in the collapsed state.
 
 On touch devices, horizontal swipe dismisses toasts (threshold: 45px or velocity > 0.11px/ms).
@@ -298,3 +313,16 @@ These props are used internally by the notification system. You rarely need to s
 
 - [VcHint](../../atoms/vc-hint/) -- inline hint/error text for form fields
 - [VcIcon](../../atoms/vc-icon/) -- used internally for type-specific icons
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `VcToast` is managed by the notification system's container component (in `framework/shell/_internal/notifications/`). Direct mounting is unusual and bypasses the stacking/positioning logic.
+- Stacking CSS uses data attributes (`data-mounted`, `data-removed`, `data-expanded`, `data-front`, `data-y-position`, `data-visible`, `data-swiping`, `data-swiped-out`) rather than class bindings for animation state — this matches the Sonner pattern and avoids Vue transition conflicts.
+- `TIME_BEFORE_UNMOUNT = 200ms` — the toast sets `data-removed="true"` to trigger CSS exit animation, then emits `close` after 200ms to remove it from the reactive list.
+- The `Timer` helper (defined inline) is a pauseable/resumeable setTimeout — `pause()` records remaining time, `resume()` restarts from remaining. Used for `pauseOnHover`.
+- Height reporting via `ResizeObserver` + `onReportHeight` callback allows the container to compute accurate stack offsets using `getBoundingClientRect()` on an `height: auto` snapshot.
+- Swipe detection uses pointer capture (`setPointerCapture`) to track moves even when the pointer leaves the element. Threshold: 45px displacement or velocity > 0.11 px/ms.
+
+<!-- internal:end -->
diff --git a/framework/ui/components/organisms/vc-app/vc-app.docs.md b/framework/ui/components/organisms/vc-app/vc-app.docs.md
index 6f1f837e5..6e6c99d54 100644
--- a/framework/ui/components/organisms/vc-app/vc-app.docs.md
+++ b/framework/ui/components/organisms/vc-app/vc-app.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcApp
+category: components
+group: layout
+---
+
 # VcApp
 
 The root application shell that bootstraps the VirtoCommerce admin UI. It provides the desktop sidebar / mobile top bar layout, blade navigation workspace, popup container, module loading, and service registration. Every VirtoCommerce admin application must render exactly one `VcApp` at the root of its authenticated route tree.
 
+::storybook id="layout-vcapp--desktop-expanded"
+
+!!! note "One VcApp per application"
+Every VirtoCommerce admin application must render exactly one `VcApp` at the root of its authenticated route tree. Multiple instances cause service registration conflicts.
+
 ## When to Use
 
 - Every VirtoCommerce admin application must have exactly one `VcApp` at the root.
@@ -59,6 +70,8 @@ const user = reactive({ name: "John", role: "Admin" });
 | `workspace`      | `{ isAuthenticated }`                                                       | Override the blade navigation workspace.                                                                              |
 | `app-hub`        | `{ appsList, switchApp }`                                                   | Custom content for the Applications section of the App Hub.                                                           |
 
+<!-- internal:start -->
+
 ## Architecture
 
 VcApp orchestrates several internal systems:
@@ -68,6 +81,8 @@ VcApp orchestrates several internal systems:
 3. **Module Loading** -- consumes `DynamicModulesKey` for runtime module registration; shows error notifications on failure. Modules declare routes, menu items, and services.
 4. **Services** -- bootstraps shell services (Menu, Toolbar, Settings, Dashboard, GlobalSearch, etc.) via `useShellBootstrap`. These services are available to all child components through provide/inject.
 
+<!-- internal:end -->
+
 ## Features
 
 ### Responsive Layout Switching
@@ -76,6 +91,8 @@ On desktop viewports, VcApp renders a collapsible sidebar on the left with navig
 
 ### Sidebar Menu Search
 
+::storybook id="layout-vcapp--with-sidebar-search" height="500"
+
 When `showSearch` is `true`, a search input appears at the top of the sidebar (desktop) or mobile navigation panel. It filters menu items in real time (300ms debounce) by matching the search query against translated item titles:
 
 - **Standalone items** — shown if their title contains the query.
@@ -134,6 +151,8 @@ The App Hub is a popover panel (desktop) or a swipeable tab (mobile) that combin
 
 On desktop, the App Hub opens from the sidebar header menu button (`AppHubPopover`). On mobile, it appears as a second tab ("Hub") in the slide-out navigation panel — users can swipe between Menu and Hub tabs.
 
+::storybook id="layout-vcapp--mobile" height="500"
+
 ## Recipe: Minimal App Setup
 
 ```vue
diff --git a/framework/ui/components/organisms/vc-auth-layout/vc-auth-layout.docs.md b/framework/ui/components/organisms/vc-auth-layout/vc-auth-layout.docs.md
index e74dd8d16..6d13f47c9 100644
--- a/framework/ui/components/organisms/vc-auth-layout/vc-auth-layout.docs.md
+++ b/framework/ui/components/organisms/vc-auth-layout/vc-auth-layout.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcAuthLayout
+category: components
+group: layout
+---
+
 # VcAuthLayout
 
 A full-page centered authentication layout for login, registration, password reset, and other auth-related screens. VcAuthLayout renders a vertically and horizontally centered card on top of an optional background image, with a logo, title, subtitle, form content area, and a footer slot for legal links. It is the standard layout for all pre-authentication pages in VirtoCommerce admin applications.
 
+::storybook id="layout-vcauthlayout--default"
+
+!!! warning "Use outside VcApp"
+VcAuthLayout is a full-page layout meant to replace `VcApp`, not nest inside it. Your router should switch between VcAuthLayout (for auth routes) and VcApp (for authenticated routes) at the top level.
+
 ## When to Use
 
 - Use for any authentication page: sign-in, sign-up, password reset, email verification
@@ -132,6 +143,8 @@ The layout uses a `<main>` element as the page landmark and an `<h2>` for the ca
 </template>
 ```
 
+::storybook id="layout-vcauthlayout--with-sso-providers" height="500"
+
 ## Recipe: Password Reset Page
 
 ```vue
diff --git a/framework/ui/components/organisms/vc-blade/_internal/BladeHeader.test.ts b/framework/ui/components/organisms/vc-blade/_internal/BladeHeader.test.ts
index 2a7c56ff2..7ff75b706 100644
--- a/framework/ui/components/organisms/vc-blade/_internal/BladeHeader.test.ts
+++ b/framework/ui/components/organisms/vc-blade/_internal/BladeHeader.test.ts
@@ -228,4 +228,52 @@ describe("BladeHeader", () => {
     const wrapper = factory({ title: "Test", titleId: "blade-title-42" });
     expect(wrapper.find(".vc-blade-header__title").attributes("id")).toBe("blade-title-42");
   });
+
+  describe("loading state", () => {
+    it("hides title/subtitle text when loading=true", () => {
+      const wrapper = factory({ title: "My Blade", subtitle: "Sub", loading: true });
+      expect(wrapper.find(".vc-blade-header__title").exists()).toBe(false);
+      expect(wrapper.find(".vc-blade-header__subtitle").exists()).toBe(false);
+    });
+
+    it("renders skeleton placeholders inside content when loading=true", () => {
+      const wrapper = factory({ loading: true });
+      expect(wrapper.find(".vc-blade-header__content--loading").exists()).toBe(true);
+    });
+
+    it("keeps close button operational when loading=true", async () => {
+      const wrapper = factory({ closable: true, loading: true }, { maximized: false });
+      const buttons = wrapper.findAll(".vc-blade-header__button");
+      // expand + close
+      expect(buttons.length).toBe(2);
+      await buttons[buttons.length - 1].trigger("click");
+      expect(wrapper.emitted("close")).toBeTruthy();
+    });
+
+    it("hides modified status dot when loading=true", () => {
+      const wrapper = factory({ modified: true, loading: true });
+      expect(wrapper.find(".vc-blade-header__status-edited").exists()).toBe(false);
+    });
+
+    it("hides actions slot when loading=true", () => {
+      const wrapper = mount(BladeHeader, {
+        props: { title: "Test", loading: true },
+        slots: { actions: '<button class="action-btn">Save</button>' },
+        global: {
+          provide: {
+            [BladeDescriptorKey as symbol]: computed<BladeDescriptor>(() => ({
+              id: "blade-1",
+              name: "TestBlade",
+              visible: true,
+            })),
+            [IsMobileKey as symbol]: ref(false),
+            [IsDesktopKey as symbol]: ref(true),
+          },
+          stubs: { VcIcon: true, teleport: true },
+          mocks: { $t: (k: string) => k },
+        },
+      });
+      expect(wrapper.find(".vc-blade-header__actions").exists()).toBe(false);
+    });
+  });
 });
diff --git a/framework/ui/components/organisms/vc-blade/_internal/BladeHeader.vue b/framework/ui/components/organisms/vc-blade/_internal/BladeHeader.vue
index 6371f844f..a499f6a76 100644
--- a/framework/ui/components/organisms/vc-blade/_internal/BladeHeader.vue
+++ b/framework/ui/components/organisms/vc-blade/_internal/BladeHeader.vue
@@ -9,7 +9,7 @@
 
     <div class="vc-blade-header__status-container">
       <div
-        v-if="typeof modified !== 'undefined'"
+        v-if="!loading && typeof modified !== 'undefined'"
         ref="tooltipIconRef"
         :class="{
           'vc-blade-header__status-not-edited': !modified,
@@ -36,7 +36,17 @@
       </div>
 
       <div
-        v-if="icon"
+        v-if="loading"
+        class="vc-blade-header__icon"
+      >
+        <VcSkeleton
+          variant="circle"
+          :width="24"
+          :height="24"
+        />
+      </div>
+      <div
+        v-else-if="icon"
         class="vc-blade-header__icon"
       >
         <VcIcon
@@ -46,7 +56,27 @@
       </div>
 
       <div class="vc-blade-header__wrapper">
-        <div class="vc-blade-header__content">
+        <div
+          v-if="loading"
+          class="vc-blade-header__content vc-blade-header__content--loading"
+        >
+          <VcSkeleton
+            variant="block"
+            :width="180"
+            :height="19"
+          />
+          <div class="tw-mt-1.5">
+            <VcSkeleton
+              variant="block"
+              :width="120"
+              :height="12"
+            />
+          </div>
+        </div>
+        <div
+          v-else
+          class="vc-blade-header__content"
+        >
           <div
             :id="titleId"
             class="vc-blade-header__title"
@@ -65,7 +95,7 @@
         </div>
 
         <div
-          v-if="$slots['actions']"
+          v-if="!loading && $slots['actions']"
           class="vc-blade-header__actions"
         >
           <slot name="actions"></slot>
@@ -73,27 +103,24 @@
       </div>
 
       <div
-        v-if="!isMobile"
+        v-if="!isMobile && closable"
         class="vc-blade-header__controls"
       >
-        <template v-if="closable">
-          <div
-            v-if="descriptor?.maximized"
-            class="vc-blade-header__button"
-            @click="onCollapse"
-          >
-            <VcIcon icon="lucide-minus" />
-          </div>
-          <div
-            v-else
-            class="vc-blade-header__button"
-            @click="onExpand"
-          >
-            <VcIcon icon="lucide-panel-top" />
-          </div>
-        </template>
         <div
-          v-if="closable"
+          v-if="descriptor?.maximized"
+          class="vc-blade-header__button"
+          @click="onCollapse"
+        >
+          <VcIcon icon="lucide-minus" />
+        </div>
+        <div
+          v-else
+          class="vc-blade-header__button"
+          @click="onExpand"
+        >
+          <VcIcon icon="lucide-panel-top" />
+        </div>
+        <div
           class="vc-blade-header__button"
           @click="onClose"
         >
@@ -106,6 +133,7 @@
 
 <script lang="ts" setup>
 import { VcIcon } from "@ui/components/atoms/vc-icon";
+import { VcSkeleton } from "@ui/components/atoms/vc-skeleton";
 import { ref, inject } from "vue";
 import { useResponsive } from "@framework/core/composables/useResponsive";
 import { shift } from "@floating-ui/vue";
@@ -120,6 +148,8 @@ export interface Props {
   modified?: boolean;
   /** Id to apply to the title element, for aria-labelledby linking from VcBlade */
   titleId?: string;
+  /** When true, shows skeleton placeholders for icon/title/subtitle while keeping controls usable */
+  loading?: boolean;
 }
 const props = defineProps<Props>();
 
diff --git a/framework/ui/components/organisms/vc-blade/_internal/BladeHeaderSkeleton.test.ts b/framework/ui/components/organisms/vc-blade/_internal/BladeHeaderSkeleton.test.ts
deleted file mode 100644
index 40115eff3..000000000
--- a/framework/ui/components/organisms/vc-blade/_internal/BladeHeaderSkeleton.test.ts
+++ /dev/null
@@ -1,37 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { mount } from "@vue/test-utils";
-import { defineComponent, h } from "vue";
-import BladeHeaderSkeleton from "./BladeHeaderSkeleton.vue";
-
-vi.mock("@ui/components/atoms/vc-skeleton", () => ({
-  VcSkeleton: defineComponent({
-    name: "VcSkeleton",
-    props: ["variant", "width", "height"],
-    setup(props) {
-      return () => h("div", { class: "mock-skeleton", "data-variant": props.variant });
-    },
-  }),
-}));
-
-describe("BladeHeaderSkeleton.vue", () => {
-  it("renders the root element", () => {
-    const wrapper = mount(BladeHeaderSkeleton);
-    expect(wrapper.find(".vc-blade-header-skeleton").exists()).toBe(true);
-  });
-
-  it("renders icon placeholder with circle variant", () => {
-    const wrapper = mount(BladeHeaderSkeleton);
-    const icon = wrapper.find(".vc-blade-header-skeleton__icon .mock-skeleton");
-    expect(icon.exists()).toBe(true);
-    expect(icon.attributes("data-variant")).toBe("circle");
-  });
-
-  it("renders text section with title and subtitle skeletons", () => {
-    const wrapper = mount(BladeHeaderSkeleton);
-    const textSection = wrapper.find(".vc-blade-header-skeleton__text");
-    expect(textSection.exists()).toBe(true);
-    // Title + subtitle = 2 block skeletons in text section
-    const blockSkeletons = textSection.findAll(".mock-skeleton");
-    expect(blockSkeletons.length).toBe(2);
-  });
-});
diff --git a/framework/ui/components/organisms/vc-blade/_internal/BladeHeaderSkeleton.vue b/framework/ui/components/organisms/vc-blade/_internal/BladeHeaderSkeleton.vue
deleted file mode 100644
index 72702a09c..000000000
--- a/framework/ui/components/organisms/vc-blade/_internal/BladeHeaderSkeleton.vue
+++ /dev/null
@@ -1,52 +0,0 @@
-<template>
-  <div class="vc-blade-header-skeleton">
-    <!-- Icon placeholder -->
-    <div class="vc-blade-header-skeleton__icon">
-      <VcSkeleton
-        variant="circle"
-        :width="24"
-        :height="24"
-      />
-    </div>
-
-    <div class="vc-blade-header-skeleton__text">
-      <!-- Title placeholder -->
-      <VcSkeleton
-        variant="block"
-        :width="180"
-        :height="19"
-      />
-      <!-- Subtitle placeholder -->
-      <div class="tw-mt-1.5">
-        <VcSkeleton
-          variant="block"
-          :width="120"
-          :height="12"
-        />
-      </div>
-    </div>
-  </div>
-</template>
-
-<script lang="ts" setup>
-import { VcSkeleton } from "@ui/components/atoms/vc-skeleton";
-
-defineOptions({ name: "BladeHeaderSkeleton" });
-</script>
-
-<style lang="scss">
-.vc-blade-header-skeleton {
-  @apply tw-shrink-0 tw-flex tw-items-center tw-gap-3 tw-px-6
-    tw-border-solid tw-border-b tw-border-b-[color:var(--blade-header-border-color)]
-    tw-bg-[color:var(--blade-header-background-color)];
-  height: var(--blade-header-height, 70px);
-
-  &__icon {
-    @apply tw-shrink-0;
-  }
-
-  &__text {
-    @apply tw-overflow-hidden;
-  }
-}
-</style>
diff --git a/framework/ui/components/organisms/vc-blade/_internal/BladeToolbar.test.ts b/framework/ui/components/organisms/vc-blade/_internal/BladeToolbar.test.ts
index dacec07e8..cff0d1ee0 100644
--- a/framework/ui/components/organisms/vc-blade/_internal/BladeToolbar.test.ts
+++ b/framework/ui/components/organisms/vc-blade/_internal/BladeToolbar.test.ts
@@ -114,4 +114,44 @@ describe("BladeToolbar", () => {
     const desktop = wrapper.findComponent({ name: "ToolbarDesktop" });
     expect(desktop.exists()).toBe(true);
   });
+
+  describe("loading state", () => {
+    it("renders skeleton placeholders instead of toolbar buttons when loading=true", () => {
+      const wrapper = factory({ loading: true });
+      expect(wrapper.find(".vc-blade-toolbar-skeleton__buttons").exists()).toBe(true);
+      expect(wrapper.find(".toolbar-desktop-stub").exists()).toBe(false);
+      expect(wrapper.find(".toolbar-mobile-stub").exists()).toBe(false);
+    });
+
+    it("hides widgets-container slot when loading=true", () => {
+      const wrapper = factory(
+        { loading: true },
+        { "widgets-container": '<div class="widget-container-test">Widgets</div>' },
+      );
+      expect(wrapper.find(".widget-container-test").exists()).toBe(false);
+      expect(wrapper.find(".vc-blade-toolbar-skeleton__widgets").exists()).toBe(true);
+    });
+
+    it("applies loading class on toolbar root", () => {
+      const wrapper = factory({ loading: true });
+      expect(wrapper.find(".vc-blade-toolbar--loading").exists()).toBe(true);
+    });
+
+    it("does not render toolbar at all on mobile when loading=true", () => {
+      const wrapper = mount(BladeToolbar, {
+        props: { items: [], loading: true },
+        global: {
+          stubs: {
+            ToolbarMobile: { template: "<div />" },
+            ToolbarDesktop: { template: "<div />" },
+          },
+          provide: {
+            [IsMobileKey as symbol]: ref(true),
+            [IsDesktopKey as symbol]: ref(false),
+          },
+        },
+      });
+      expect(wrapper.find(".vc-blade-toolbar").exists()).toBe(false);
+    });
+  });
 });
diff --git a/framework/ui/components/organisms/vc-blade/_internal/BladeToolbar.vue b/framework/ui/components/organisms/vc-blade/_internal/BladeToolbar.vue
index 322556be1..2a229e808 100644
--- a/framework/ui/components/organisms/vc-blade/_internal/BladeToolbar.vue
+++ b/framework/ui/components/organisms/vc-blade/_internal/BladeToolbar.vue
@@ -1,27 +1,71 @@
 <template>
   <div
+    v-if="!(loading && isMobile)"
     class="vc-blade-toolbar"
     :class="{
       'vc-blade-toolbar--mobile': isMobile,
+      'vc-blade-toolbar--loading': loading,
     }"
   >
     <div class="vc-blade-toolbar__content">
-      <div class="vc-blade-toolbar__buttons">
-        <ToolbarMobile
-          v-if="isMobile"
-          :items="visibleItems"
-        />
-        <ToolbarDesktop
-          v-else
-          :items="visibleItems"
-          :is-expanded="isExpanded"
-        />
-      </div>
+      <template v-if="loading">
+        <div class="vc-blade-toolbar-skeleton__buttons">
+          <div
+            v-for="i in 3"
+            :key="i"
+            class="vc-blade-toolbar-skeleton__button"
+          >
+            <VcSkeleton
+              variant="circle"
+              :width="18"
+              :height="18"
+            />
+            <VcSkeleton
+              variant="block"
+              :width="28 + i * 6"
+              :height="10"
+            />
+          </div>
+        </div>
 
-      <slot
-        v-if="$slots['widgets-container']"
-        name="widgets-container"
-      />
+        <div class="vc-blade-toolbar-skeleton__widgets">
+          <div
+            v-for="i in 2"
+            :key="'w' + i"
+            class="vc-blade-toolbar-skeleton__widget"
+          >
+            <VcSkeleton
+              variant="circle"
+              :width="18"
+              :height="18"
+            />
+            <VcSkeleton
+              variant="block"
+              :width="30 + i * 4"
+              :height="10"
+              class="tw-mt-1"
+            />
+          </div>
+        </div>
+      </template>
+      <template v-else>
+        <div class="vc-blade-toolbar__buttons">
+          <ToolbarMobile
+            v-if="isMobile"
+            :items="visibleItems"
+          />
+          <ToolbarDesktop
+            v-else
+            :items="visibleItems"
+            :is-expanded="isExpanded"
+          />
+        </div>
+
+        <slot
+          v-if="$slots['widgets-container']"
+          name="widgets-container"
+        />
+      </template>
     </div>
   </div>
 </template>
@@ -30,12 +74,15 @@
 import { toRef } from "vue";
 import { useResponsive } from "@framework/core/composables/useResponsive";
 import type { IBladeToolbar } from "@core/types";
+import { VcSkeleton } from "@ui/components/atoms/vc-skeleton";
 import ToolbarMobile from "@ui/components/organisms/vc-blade/_internal/toolbar/ToolbarMobile.vue";
 import ToolbarDesktop from "@ui/components/organisms/vc-blade/_internal/toolbar/ToolbarDesktop.vue";
 import { useToolbarRegistration } from "@ui/components/organisms/vc-blade/_internal/composables/useToolbarRegistration";
 
 export interface Props {
   items?: IBladeToolbar[];
+  /** When true, renders skeleton placeholders instead of toolbar buttons/widgets */
+  loading?: boolean;
 }
 
 const props = withDefaults(defineProps<Props>(), {
@@ -71,4 +118,23 @@ const { visibleItems } = useToolbarRegistration(toRef(props, "items"));
     @apply tw-fixed tw-bottom-0 tw-right-0 tw-z-[var(--z-layout-sidebar)] tw-p-4 tw-bg-transparent tw-border-0 tw-w-auto;
   }
 }
+
+.vc-blade-toolbar-skeleton {
+  &__buttons {
+    @apply tw-flex tw-items-center tw-px-4 tw-flex-1 tw-min-w-0;
+  }
+
+  &__button {
+    @apply tw-shrink-0 tw-px-3 tw-inline-flex tw-flex-col tw-items-center tw-gap-1;
+  }
+
+  &__widgets {
+    @apply tw-flex tw-flex-row tw-gap-1 tw-shrink-0;
+    background-color: var(--blade-toolbar-widgets-bg-color);
+  }
+
+  &__widget {
+    @apply tw-shrink-0 tw-px-2 tw-py-1.5 tw-flex tw-flex-col tw-items-center tw-justify-center;
+  }
+}
 </style>
diff --git a/framework/ui/components/organisms/vc-blade/_internal/BladeToolbarSkeleton.test.ts b/framework/ui/components/organisms/vc-blade/_internal/BladeToolbarSkeleton.test.ts
deleted file mode 100644
index 4467f1b5a..000000000
--- a/framework/ui/components/organisms/vc-blade/_internal/BladeToolbarSkeleton.test.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import { mount } from "@vue/test-utils";
-import { defineComponent, h, ref } from "vue";
-import { IsMobileKey } from "@framework/injection-keys";
-import BladeToolbarSkeleton from "./BladeToolbarSkeleton.vue";
-
-vi.mock("@ui/components/atoms/vc-skeleton", () => ({
-  VcSkeleton: defineComponent({
-    name: "VcSkeleton",
-    props: ["variant", "width", "height"],
-    setup() {
-      return () => h("div", { class: "mock-skeleton" });
-    },
-  }),
-}));
-
-describe("BladeToolbarSkeleton.vue", () => {
-  it("renders the root element with toolbar class", () => {
-    const wrapper = mount(BladeToolbarSkeleton, {
-      global: {
-        provide: {
-          [IsMobileKey as symbol]: ref(false),
-        },
-      },
-    });
-    expect(wrapper.find(".vc-blade-toolbar-skeleton").exists()).toBe(true);
-  });
-
-  it("renders 3 skeleton button placeholders", () => {
-    const wrapper = mount(BladeToolbarSkeleton, {
-      global: {
-        provide: {
-          [IsMobileKey as symbol]: ref(false),
-        },
-      },
-    });
-    const buttonPlaceholders = wrapper.findAll(".vc-blade-toolbar-skeleton__button");
-    expect(buttonPlaceholders.length).toBe(3);
-  });
-
-  it("does not render when $isMobile is true", () => {
-    const wrapper = mount(BladeToolbarSkeleton, {
-      global: {
-        provide: {
-          [IsMobileKey as symbol]: ref(true),
-        },
-      },
-    });
-    expect(wrapper.find(".vc-blade-toolbar-skeleton").exists()).toBe(false);
-  });
-});
diff --git a/framework/ui/components/organisms/vc-blade/_internal/BladeToolbarSkeleton.vue b/framework/ui/components/organisms/vc-blade/_internal/BladeToolbarSkeleton.vue
deleted file mode 100644
index 9f0327d84..000000000
--- a/framework/ui/components/organisms/vc-blade/_internal/BladeToolbarSkeleton.vue
+++ /dev/null
@@ -1,77 +0,0 @@
-<template>
-  <div
-    v-if="!isMobile"
-    class="vc-blade-toolbar vc-blade-toolbar-skeleton"
-  >
-    <div class="vc-blade-toolbar__content">
-      <div class="vc-blade-toolbar-skeleton__buttons">
-        <div
-          v-for="i in 3"
-          :key="i"
-          class="vc-blade-toolbar-skeleton__button"
-        >
-          <VcSkeleton
-            variant="circle"
-            :width="18"
-            :height="18"
-          />
-          <VcSkeleton
-            variant="block"
-            :width="28 + i * 6"
-            :height="10"
-          />
-        </div>
-      </div>
-
-      <div class="vc-blade-toolbar-skeleton__widgets">
-        <div
-          v-for="i in 2"
-          :key="'w' + i"
-          class="vc-blade-toolbar-skeleton__widget"
-        >
-          <VcSkeleton
-            variant="circle"
-            :width="18"
-            :height="18"
-          />
-          <VcSkeleton
-            variant="block"
-            :width="30 + i * 4"
-            :height="10"
-            class="tw-mt-1"
-          />
-        </div>
-      </div>
-    </div>
-  </div>
-</template>
-
-<script lang="ts" setup>
-import { VcSkeleton } from "@ui/components/atoms/vc-skeleton";
-import { useResponsive } from "@framework/core/composables/useResponsive";
-
-defineOptions({ name: "BladeToolbarSkeleton" });
-
-const { isMobile } = useResponsive();
-</script>
-
-<style lang="scss">
-.vc-blade-toolbar-skeleton {
-  &__buttons {
-    @apply tw-flex tw-items-center tw-px-4 tw-flex-1 tw-min-w-0;
-  }
-
-  &__button {
-    @apply tw-shrink-0 tw-px-3 tw-inline-flex tw-flex-col tw-items-center tw-gap-1;
-  }
-
-  &__widgets {
-    @apply tw-flex tw-flex-row tw-gap-1 tw-shrink-0;
-    background-color: var(--blade-toolbar-widgets-bg-color);
-  }
-
-  &__widget {
-    @apply tw-shrink-0 tw-px-2 tw-py-1.5 tw-flex tw-flex-col tw-items-center tw-justify-center;
-  }
-}
-</style>
diff --git a/framework/ui/components/organisms/vc-blade/vc-blade.a11y.test.ts b/framework/ui/components/organisms/vc-blade/vc-blade.a11y.test.ts
index b97008a5f..0e0a375cb 100644
--- a/framework/ui/components/organisms/vc-blade/vc-blade.a11y.test.ts
+++ b/framework/ui/components/organisms/vc-blade/vc-blade.a11y.test.ts
@@ -111,9 +111,7 @@ describe("VcBlade a11y", () => {
             template:
               '<div role="heading" aria-level="2"><h2 :id="titleId">{{ title }}</h2><slot /><slot name="prepend" /><slot name="actions" /></div>',
           },
-          BladeHeaderSkeleton: true,
           BladeToolbar: true,
-          BladeToolbarSkeleton: true,
           BladeContentSkeleton: true,
           BladeStatusBanners: true,
           WidgetContainer: true,
diff --git a/framework/ui/components/organisms/vc-blade/vc-blade.docs.md b/framework/ui/components/organisms/vc-blade/vc-blade.docs.md
index 102eed633..c5ea27bc6 100644
--- a/framework/ui/components/organisms/vc-blade/vc-blade.docs.md
+++ b/framework/ui/components/organisms/vc-blade/vc-blade.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcBlade
+category: components
+group: layout
+---
+
 # VcBlade
 
 The foundational container component of the VirtoCommerce admin shell. Blades are stacked panels -- inspired by the Azure Portal -- that form the primary navigation paradigm. Every screen in a vc-shell application is a blade.
@@ -34,6 +40,8 @@ Traditional admin panels use page-based routing: click a link, the entire viewpo
 | Full-page route without blade stack               | Vue Router view                              |
 | Scrollable content section inside a blade         | [VcContainer](../../molecules/vc-container/) |
 
+::storybook id="navigation-vcblade--default"
+
 Use VcBlade for every screen in a vc-shell application -- it is the standard container that integrates with the navigation system, toolbar, breadcrumbs, and unsaved-changes guards. **Do not use** VcBlade for transient dialogs (use `VcPopup` / `usePopup()`) or for content areas that do not need their own header and close button.
 
 ## Quick Start
@@ -54,7 +62,8 @@ defineOptions({ name: "MyFirstBlade", url: "/my-first-blade" });
 </script>
 ```
 
-> **Tip:** Every blade needs a `name` in `defineOptions`. This is how other blades reference it: `openBlade({ name: "MyFirstBlade" })`. The `url` is optional and controls the URL segment.
+!!! tip "Every blade needs a name"
+Every blade must define a `name` in `defineOptions`. This is how other blades reference it: `openBlade({ name: "MyFirstBlade" })`. The `url` is optional and controls the URL segment.
 
 ## Blade Anatomy
 
@@ -374,6 +383,8 @@ interface IBladeToolbar {
 
 ## Loading State and Skeleton
 
+::storybook id="navigation-vcblade--loading" height="500"
+
 `loading` shows skeleton placeholders for header, toolbar, and content:
 
 ```vue
@@ -384,6 +395,10 @@ interface IBladeToolbar {
 
 > **Tip:** Content is hidden (not unmounted) while loading, so `onMounted` hooks still fire.
 
+> **Note:** During `loading=true`, the header keeps its **close/expand controls operational** — only the icon, title, and subtitle are replaced with skeleton placeholders. Users can always close or maximize a loading blade. The `actions` slot, breadcrumbs, and modified-status dot are hidden until loading finishes.
+
+> **Note:** The toolbar zone uses an in-place skeleton: `BladeToolbar` itself renders skeleton buttons/widgets when its `loading` prop is true (no separate skeleton component is mounted). On mobile, the toolbar is omitted entirely while loading.
+
 Merge multiple loading sources with `useLoading`:
 
 ```ts
@@ -409,6 +424,8 @@ useBeforeUnload(hasChanges); // Browser tab close warning
 
 ## Custom Banners
 
+::storybook id="navigation-vcblade--custom-banners" height="500"
+
 Add informational, warning, or success banners to a blade programmatically. Banners appear between the header and toolbar, sorted by severity.
 
 ```vue
@@ -675,6 +692,8 @@ openBlade({ name: "ProductsList" });
 | `usePopup()`                                    | Confirmation dialogs and error messages.                                           |
 | `useBladeWidgets()`                             | Register contextual widgets for the blade widget area.                             |
 
+<!-- internal:start -->
+
 ## Content Skeleton Mode
 
 When `loading=true`, VcBlade provides `BladeLoadingKey` to all descendant components via Vue's provide/inject. Each framework UI component automatically renders a skeleton placeholder matching its visual footprint.
@@ -704,3 +723,5 @@ import { useBladeLoading } from "@vc-shell/framework";
 const bladeLoading = useBladeLoading();
 // bladeLoading.value === true when parent VcBlade is loading
 ```
+
+<!-- internal:end -->
diff --git a/framework/ui/components/organisms/vc-blade/vc-blade.vue b/framework/ui/components/organisms/vc-blade/vc-blade.vue
index 1a6f7351f..b6e121bbb 100644
--- a/framework/ui/components/organisms/vc-blade/vc-blade.vue
+++ b/framework/ui/components/organisms/vc-blade/vc-blade.vue
@@ -1,6 +1,7 @@
 <template>
   <div
     ref="bladeRef"
+    v-bind="rootAttrs"
     class="vc-blade"
     role="region"
     :class="[
@@ -15,64 +16,59 @@
     :aria-labelledby="props.title && !showSkeleton ? bladeTitleId : undefined"
     :aria-label="!props.title || showSkeleton ? $t('COMPONENTS.ORGANISMS.VC_BLADE.PANEL') : undefined"
   >
-    <!-- Header zone: v-show keeps BladeHeader mounted to avoid Teleport unmount bug -->
-    <template v-if="!(isMobile && blades.length === 1 && !$slots['actions'])">
-      <BladeHeaderSkeleton
-        v-if="showSkeleton"
-        class="vc-blade__header"
-      />
-      <BladeHeader
-        v-show="!showSkeleton"
-        class="vc-blade__header"
-        :closable="isClosable"
-        :icon="icon"
-        :title="title"
-        :subtitle="subtitle"
-        :modified="effectiveModified"
-        :title-id="bladeTitleId"
-        @close="handleClose"
-        @expand="handleExpand"
-        @collapse="handleCollapse"
-      >
-        <template #prepend>
-          <component
-            :is="backButton"
-            v-if="backButton && isMobile"
-            class="vc-blade__back-button"
-          />
-
-          <div
-            v-if="descriptor?.breadcrumbs?.length && isDesktop"
-            class="vc-blade__breadcrumbs"
-          >
-            <VcBreadcrumbs
-              :items="descriptor?.breadcrumbs"
-              collapsed
-            >
-              <template #trigger="{ click, isActive }">
-                <VcButton
-                  text
-                  icon="lucide-ellipsis-vertical"
-                  icon-size="xl"
-                  class="vc-blade__breadcrumbs-button"
-                  :class="{
-                    'vc-blade__breadcrumbs-button--active': isActive,
-                  }"
-                  @click="click"
-                />
-              </template>
-            </VcBreadcrumbs>
-          </div>
-        </template>
-
-        <template
-          v-if="$slots['actions']"
-          #actions
+    <!-- Header zone -->
+    <BladeHeader
+      v-if="!(isMobile && blades.length === 1 && !$slots['actions'])"
+      class="vc-blade__header"
+      :closable="isClosable"
+      :icon="icon"
+      :title="title"
+      :subtitle="subtitle"
+      :modified="effectiveModified"
+      :title-id="bladeTitleId"
+      :loading="showSkeleton"
+      @close="handleClose"
+      @expand="handleExpand"
+      @collapse="handleCollapse"
+    >
+      <template #prepend>
+        <component
+          :is="backButton"
+          v-if="backButton && isMobile"
+          class="vc-blade__back-button"
+        />
+
+        <div
+          v-if="!showSkeleton && descriptor?.breadcrumbs?.length && isDesktop"
+          class="vc-blade__breadcrumbs"
         >
-          <slot name="actions"></slot>
-        </template>
-      </BladeHeader>
-    </template>
+          <VcBreadcrumbs
+            :items="descriptor?.breadcrumbs"
+            collapsed
+          >
+            <template #trigger="{ click, isActive }">
+              <VcButton
+                text
+                icon="lucide-ellipsis-vertical"
+                icon-size="xl"
+                class="vc-blade__breadcrumbs-button"
+                :class="{
+                  'vc-blade__breadcrumbs-button--active': isActive,
+                }"
+                @click="click"
+              />
+            </template>
+          </VcBreadcrumbs>
+        </div>
+      </template>
+
+      <template
+        v-if="$slots['actions']"
+        #actions
+      >
+        <slot name="actions"></slot>
+      </template>
+    </BladeHeader>
 
     <BladeStatusBanners
       v-if="!showSkeleton"
@@ -80,14 +76,11 @@
     />
 
     <!-- Toolbar zone -->
-    <BladeToolbarSkeleton
-      v-if="showSkeleton"
-      class="vc-blade__toolbar"
-    />
     <BladeToolbar
-      v-else
+      data-test-id="blade-toolbar"
       class="vc-blade__toolbar"
       :items="toolbarItems"
+      :loading="showSkeleton"
     >
       <template #widgets-container>
         <WidgetContainer :blade-id="bladeId" />
@@ -121,9 +114,7 @@ import { ref, inject, provide, computed, getCurrentInstance, useAttrs, watchEffe
 import { IBladeToolbar } from "@core/types";
 import { useBladeStack } from "@core/blade-navigation";
 import BladeHeader from "@ui/components/organisms/vc-blade/_internal/BladeHeader.vue";
-import BladeHeaderSkeleton from "@ui/components/organisms/vc-blade/_internal/BladeHeaderSkeleton.vue";
 import BladeToolbar from "@ui/components/organisms/vc-blade/_internal/BladeToolbar.vue";
-import BladeToolbarSkeleton from "@ui/components/organisms/vc-blade/_internal/BladeToolbarSkeleton.vue";
 import BladeStatusBanners from "@ui/components/organisms/vc-blade/_internal/BladeStatusBanners.vue";
 import { VcButton } from "@ui/components/atoms/vc-button";
 import { VcBreadcrumbs } from "@ui/components/molecules/vc-breadcrumbs";
@@ -211,6 +202,10 @@ const isClosable = computed(() => {
 });
 
 const attrs = useAttrs();
+const rootAttrs = computed(() => {
+  const { class: _class, style: _style, onClose: _onClose, ...rest } = attrs;
+  return rest;
+});
 
 function handleClose() {
   if (attrs.onClose) {
diff --git a/framework/ui/components/organisms/vc-data-table/composables/table-composables.docs.md b/framework/ui/components/organisms/vc-data-table/composables/table-composables.docs.md
index c11d4ea74..54d4f5f12 100644
--- a/framework/ui/components/organisms/vc-data-table/composables/table-composables.docs.md
+++ b/framework/ui/components/organisms/vc-data-table/composables/table-composables.docs.md
@@ -1,3 +1,10 @@
+---
+title: Table Composables
+category: composables
+group: data
+slug: table-composables
+---
+
 # VcTable Composables
 
 Composables that power VcDataTable's functionality. Each handles a single concern and is wired together by the table component. Module developers rarely use these directly -- they are consumed internally by `VcDataTable.vue`.
@@ -144,14 +151,32 @@ register({
 
 - `useTableColumns` never removes entries from `columnState` — hidden columns preserve their weight and order for when they reappear. Use `engineOutput` (not `columnState` directly) to read computed pixel widths for rendering.
 - Call `recompute()` (returned by `useTableColumns`) whenever the container width changes to force the engine to redistribute widths without altering weights.
-- `useDataTableState` stores the v2 schema (weights, order, hidden/shown IDs). It automatically migrates v1 state (pixel-based) on the first restore. Guard against save-during-restore loops with the `isRestoring` flag.
+- `useDataTableState` stores the v2 schema (weights, order, hidden/shown IDs). It auto-migrates v1 state (pixel-based) on the first restore.
 - `useColumnWidthEngine` functions are pure — pass immutable copies of `specs` when testing or previewing layouts without committing to state.
+- `useVirtualScroll` requires a fixed `itemSize` (row height in pixels) for accurate positioning.
+
+<!-- internal:start -->
+
+### Contributor notes
+
+- `useDataTableState`: Guard against save-during-restore loops with the `isRestoring` flag.
 - `useTableRowReorder`: `event.preventDefault()` in `dragover` MUST be called on every event or `drop` never fires.
 - `useTableColumnsResize` applies DOM-level px changes during drag for 60fps performance, then commits final weights to `columnState` on mouseup. No `ResizeObserver` scaling is involved.
-- `useVirtualScroll` requires a fixed `itemSize` (row height in pixels) for accurate positioning.
+
+<!-- internal:end -->
 
 ## Related
 
-- `framework/ui/components/organisms/vc-table/VcDataTable.vue` -- main consumer
-- `framework/ui/components/organisms/vc-table/VcTableAdapter.vue` -- legacy API adapter
-- `framework/ui/components/organisms/vc-table/components/` -- sub-components (TableHead, TableRow, cells)
+- [VcDataTable](../../vc-data-table) -- the main consumer of these composables
+- [VcColumn](../../vc-data-table) -- declarative column definitions
+
+<!-- internal:start -->
+
+## Source references
+
+- `framework/ui/components/organisms/vc-data-table/VcDataTable.vue` -- main consumer
+- `framework/ui/components/organisms/vc-data-table/VcTableAdapter.vue` -- legacy API adapter
+- `framework/ui/components/organisms/vc-data-table/components/` -- sub-components (TableHead, TableRow, cells)
+- `framework/ui/components/organisms/vc-data-table/composables/` -- full composable list
+
+<!-- internal:end -->
diff --git a/framework/ui/components/organisms/vc-data-table/vc-data-table.docs.md b/framework/ui/components/organisms/vc-data-table/vc-data-table.docs.md
index c73946af2..e1b6383bc 100644
--- a/framework/ui/components/organisms/vc-data-table/vc-data-table.docs.md
+++ b/framework/ui/components/organisms/vc-data-table/vc-data-table.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcDataTable
+category: components
+group: data-display
+---
+
 # VcDataTable
 
 The flagship data table component for VirtoCommerce admin shell. VcDataTable provides a fully declarative, template-driven API for building interactive tables with sorting, selection, inline editing, filtering, pagination, column management, row reordering, and more.
@@ -107,6 +113,8 @@ const products = ref([
 
 > **Note:** Each item must have a unique identifier field. The default is `id` -- override with the `data-key` prop if your field is named differently (e.g., `data-key="sku"`).
 
+::storybook id="data-display-vcdatatable--basic"
+
 ---
 
 ## Column Types
@@ -207,6 +215,8 @@ For any rendering not covered by built-in types, use the `#body` slot:
 
 ## Sorting
 
+::storybook id="data-display-vcdatatable--with-sorting" height="500"
+
 ### Single Column Sort
 
 Mark columns as sortable and bind the sort state:
@@ -293,6 +303,8 @@ When the backend sort field differs from the column id:
 
 ## Selection
 
+::storybook id="data-display-vcdatatable--with-selection" height="450"
+
 ### Multiple Selection (checkboxes)
 
 ```vue
@@ -1015,6 +1027,9 @@ async function loadNextPage() {
 
 ## State Persistence
 
+!!! tip "Use unique state keys"
+Every table in your application must have a distinct `state-key`. Two tables sharing the same key will silently overwrite each other's persisted column widths, order, and sort state.
+
 Persist column widths, column order, hidden columns, sort, and filters across page reloads:
 
 ```vue
@@ -1862,6 +1877,9 @@ function onRowRemove(event: { data: PriceEntry; cancel: () => void }) {
 
 ## Common Mistakes
 
+!!! warning "Performance: avoid mutating the items array in-place"
+Always replace `items` with a new array reference instead of using `splice` or `push` directly on the reactive array. Vue cannot track in-place mutations reliably in all scenarios, and VcDataTable's row reorder logic depends on receiving a fresh array to reset the pending-reorder state.
+
 ### 1. Missing `dataKey` with non-`id` identifiers
 
 ```vue
diff --git a/framework/ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md b/framework/ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md
index 4aa80d306..7343e6de9 100644
--- a/framework/ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md
+++ b/framework/ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcDynamicProperty
+category: components
+group: form
+---
+
 # VcDynamicProperty
 
 Renders a VirtoCommerce platform dynamic property as the appropriate form control, automatically selecting the input component based on value type, dictionary, and multivalue flags. VcDynamicProperty eliminates the need for manual `v-if` chains when rendering properties whose type is determined at runtime — it maps each combination of `valueType`, `dictionary`, and `multivalue` to the correct input molecule and passes through all relevant props.
 
+::storybook id="data-display-vcdynamicproperty--default"
+
 ## When to Use
 
 - Use to render dynamic properties from the VirtoCommerce platform (catalog properties, member properties, store properties, etc.)
@@ -44,6 +52,8 @@ Renders a VirtoCommerce platform dynamic property as the appropriate form contro
 | `measurementsGetter` | `Function` | -       | Async loader for measurement units                                            |
 | `rules`              | `object`   | -       | Validation rules: `{ min, max, regex }`                                       |
 
+::storybook id="data-display-vcdynamicproperty--property-form" height="500"
+
 ## Value Type to Component Mapping
 
 | valueType | dictionary | multivalue | Component                    |
@@ -109,6 +119,8 @@ function handlePropertyUpdate(property: any, newValue: any) {
 </template>
 ```
 
+::storybook id="data-display-vcdynamicproperty--required-with-validation" height="300"
+
 ## Recipe: Dynamic Property with Validation
 
 ```vue
diff --git a/framework/ui/components/organisms/vc-gallery/vc-gallery.docs.md b/framework/ui/components/organisms/vc-gallery/vc-gallery.docs.md
index eb7320bb1..122a74489 100644
--- a/framework/ui/components/organisms/vc-gallery/vc-gallery.docs.md
+++ b/framework/ui/components/organisms/vc-gallery/vc-gallery.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcGallery
+category: components
+group: data-display
+---
+
 # VcGallery
 
 A responsive multi-image gallery with drag-and-drop reorder, file upload, lightbox preview, and per-image actions. VcGallery renders images in a CSS grid that auto-fills based on the container width, with a built-in upload zone tile at the end of the grid. It is the standard component for managing collections of images such as product photos, media libraries, and document attachments.
 
+::storybook id="data-display-vcgallery--default"
+
 ## When to Use
 
 - Use **VcGallery** for multi-image fields (product images, media libraries, banner collections).
@@ -64,12 +72,16 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 <VcGallery label="Product Images" required :images="product.images" imagefit="cover" @upload="handleUpload" @sort="handleSort" @edit="handleEdit" @remove="handleRemove" />
 ```
 
+::storybook id="data-display-vcgallery--filmstrip-default" height="400"
+
 ## Filmstrip Layout (Default)
 
 ```vue
 <VcGallery label="Images" :images="product.images" imagefit="cover" @upload="handleUpload" @sort="handleSort" @remove="handleRemove" />
 ```
 
+::storybook id="data-display-vcgallery--grid-layout" height="400"
+
 ## Classic Grid Layout
 
 ```vue
@@ -128,6 +140,8 @@ function handleRemove(image: ICommonAsset) {
 </template>
 ```
 
+::storybook id="data-display-vcgallery--disabled" height="300"
+
 ## Recipe: Read-Only Gallery (Disabled)
 
 ```vue
diff --git a/framework/ui/components/organisms/vc-image-upload/vc-image-upload.docs.md b/framework/ui/components/organisms/vc-image-upload/vc-image-upload.docs.md
index 94012c0ef..f1f82a0f5 100644
--- a/framework/ui/components/organisms/vc-image-upload/vc-image-upload.docs.md
+++ b/framework/ui/components/organisms/vc-image-upload/vc-image-upload.docs.md
@@ -1,7 +1,15 @@
+---
+title: VcImageUpload
+category: components
+group: media
+---
+
 # VcImageUpload
 
 A single-image upload organism that displays either a drag-and-drop upload zone or an image tile with preview and remove actions. VcImageUpload manages three visual states automatically: an interactive dropzone when no image is set, an image tile with action overlays when an image is provided, and a disabled empty state with a hint message. It integrates with vee-validate for file validation (size, format) and supports lightbox preview via the built-in VcImageTile component.
 
+::storybook id="data-display-vcimageupload--empty"
+
 ## When to Use
 
 - Use **VcImageUpload** for single-image fields (avatar, logo, thumbnail, hero image).
@@ -31,6 +39,8 @@ A single-image upload organism that displays either a drag-and-drop upload zone
 | `upload` | `FileList`     | Emitted when files are selected or dropped. |
 | `remove` | `ICommonAsset` | Emitted when the remove button is clicked.  |
 
+::storybook id="data-display-vcimageupload--with-image" height="300"
+
 ## Visual States
 
 The component has three visual states:
@@ -83,6 +93,8 @@ function handleRemove() {
 </template>
 ```
 
+::storybook id="data-display-vcimageupload--loading" height="250"
+
 ## Recipe: Conditional Upload with Loading State
 
 ```vue
diff --git a/framework/ui/components/organisms/vc-popup/vc-popup.docs.md b/framework/ui/components/organisms/vc-popup/vc-popup.docs.md
index 7571cd640..689bcff46 100644
--- a/framework/ui/components/organisms/vc-popup/vc-popup.docs.md
+++ b/framework/ui/components/organisms/vc-popup/vc-popup.docs.md
@@ -1,3 +1,9 @@
+---
+title: VcPopup
+category: components
+group: feedback
+---
+
 # VcPopup
 
 A modal dialog component built on [HeadlessUI Dialog](https://headlessui.com/vue/dialog). Use it for confirmations, alerts, error messages, and focused form interactions that require the user's immediate attention.
@@ -12,7 +18,10 @@ A modal dialog component built on [HeadlessUI Dialog](https://headlessui.com/vue
 | Side panel for contextual workflows               | VcSidebar   |
 | Stacked detail views (master-detail)              | VcBlade     |
 
-> **Tip:** Prefer blades for CRUD workflows. Reserve popups for brief, interruptive interactions such as confirmations and alerts.
+!!! tip "Prefer blades for CRUD workflows"
+Reserve popups for brief, interruptive interactions such as confirmations and alerts. Use `VcBlade` for CRUD detail views and `VcSidebar` for contextual side panels.
+
+::storybook id="overlay-vcpopup--default"
 
 ---
 
@@ -49,6 +58,8 @@ const showPopup = ref(false);
 
 ### Variants
 
+::storybook id="overlay-vcpopup--variants" height="500"
+
 The `variant` prop adds a semantic icon and color to the popup. Available values: `"default"`, `"info"`, `"success"`, `"warning"`, `"error"`.
 
 ```vue
@@ -248,6 +259,8 @@ Two props control fullscreen behavior:
 
 ### Confirmation Dialog
 
+::storybook id="overlay-vcpopup--with-footer" height="400"
+
 The most common pattern. Uses the `warning` variant and a two-button footer.
 
 ```vue
diff --git a/framework/ui/components/organisms/vc-sidebar/vc-sidebar.docs.md b/framework/ui/components/organisms/vc-sidebar/vc-sidebar.docs.md
index f3937c6a1..3fd38adc3 100644
--- a/framework/ui/components/organisms/vc-sidebar/vc-sidebar.docs.md
+++ b/framework/ui/components/organisms/vc-sidebar/vc-sidebar.docs.md
@@ -1,7 +1,18 @@
+---
+title: VcSidebar
+category: components
+group: layout
+---
+
 # VcSidebar
 
 A slide-over panel for contextual workflows, settings, and detail views. Supports left, right, and bottom positions with animated transitions, focus trapping, scroll locking, and swipe-to-dismiss gestures. VcSidebar is built for use cases where a full blade is too heavy but a popup is too small — settings panels, filter drawers, item detail previews, and mobile bottom sheets.
 
+::storybook id="overlay-vcsidebar--elevated-panel"
+
+!!! tip "Sidebar vs Popup vs Blade"
+Use VcSidebar for contextual workflows that need persistent visibility. Use `VcPopup` for brief confirmation dialogs. Use `VcBlade` for primary CRUD content that belongs in the navigation stack.
+
 ## When to Use
 
 - Settings panels, filter drawers, or contextual detail views.
@@ -104,6 +115,8 @@ Override with the `width` or `height` prop for custom dimensions.
 
 ### Bottom Sheet with Swipe-to-Dismiss
 
+::storybook id="overlay-vcsidebar--bottom-sheet" height="500"
+
 ```vue
 <VcSidebar v-model="open" position="bottom" size="md" draggable drag-handle>
   <div class="tw-p-4">Swipe down to close</div>
diff --git a/framework/ui/composables/ui-composables.docs.md b/framework/ui/composables/ui-composables.docs.md
index 55091f751..aa512e7cf 100644
--- a/framework/ui/composables/ui-composables.docs.md
+++ b/framework/ui/composables/ui-composables.docs.md
@@ -1,3 +1,10 @@
+---
+title: UI Composables
+category: composables
+group: ui-state
+slug: ui-composables-overview
+---
+
 # UI Composables
 
 Shared composables for the VC-Shell UI component library. These provide reusable logic for layout, positioning, form fields, and scroll behavior.
diff --git a/framework/ui/composables/useDataTablePagination.docs.md b/framework/ui/composables/useDataTablePagination.docs.md
index 150ca07ee..5df1a597c 100644
--- a/framework/ui/composables/useDataTablePagination.docs.md
+++ b/framework/ui/composables/useDataTablePagination.docs.md
@@ -1,3 +1,9 @@
+---
+title: useDataTablePagination
+category: composables
+group: data
+---
+
 # useDataTablePagination
 
 Manages page-level pagination state for `VcDataTable`. Derives `pages`, `skip`, `totalCount` from a reactive input, and fires an optional `onPageChange` callback when the page changes. Returns a `reactive()` object — all properties are plain values (no `.value` needed), and the object is directly passable as the VcDataTable `:pagination` prop.
@@ -159,6 +165,6 @@ Blade then simply binds:
 
 ## Related
 
-- [`useDataTableSort`](./useDataTableSort.docs.md) — sort state composable for VcDataTable
-- `VcDataTable` `:pagination` prop — accepts `DataTablePagination` object
-- `DataTablePagination` type — defined in `vc-data-table/types.ts`
+- [`useDataTableSort`](./useDataTableSort.docs.md) -- sort state composable for VcDataTable
+- `VcDataTable` `:pagination` prop -- accepts `DataTablePagination` object
+- `DataTablePagination` -- type exported from `@vc-shell/framework`
diff --git a/framework/ui/composables/useDataTableSort.docs.md b/framework/ui/composables/useDataTableSort.docs.md
index b55fbaffe..7f1baed63 100644
--- a/framework/ui/composables/useDataTableSort.docs.md
+++ b/framework/ui/composables/useDataTableSort.docs.md
@@ -1,3 +1,9 @@
+---
+title: useDataTableSort
+category: composables
+group: data
+---
+
 # useDataTableSort
 
 Manages page-level sort state for `VcDataTable` using numeric sort order conventions (`1` = ASC, `-1` = DESC, `0` = none). Provides `sortField` and `sortOrder` refs for `v-model` binding directly on `VcDataTable`, plus a `sortExpression` computed string for API calls.
diff --git a/framework/ui/composables/useTableSelection.docs.md b/framework/ui/composables/useTableSelection.docs.md
index 26f76c30a..c49ec5bea 100644
--- a/framework/ui/composables/useTableSelection.docs.md
+++ b/framework/ui/composables/useTableSelection.docs.md
@@ -1,3 +1,9 @@
+---
+title: useTableSelection
+category: composables
+group: data
+---
+
 # useTableSelection
 
 Manages table row selection state including multi-select, select-all, and programmatic selection. This composable provides a complete external selection API for VcDataTable, enabling bulk operations like delete, export, or status changes on selected rows.
diff --git a/framework/ui/composables/useTableSort.docs.md b/framework/ui/composables/useTableSort.docs.md
index b8404715e..b9ca0d557 100644
--- a/framework/ui/composables/useTableSort.docs.md
+++ b/framework/ui/composables/useTableSort.docs.md
@@ -1,3 +1,9 @@
+---
+title: useTableSort
+category: composables
+group: data
+---
+
 # useTableSort
 
 Manages table sort state with three-state cycling (ASC, DESC, none) and a formatted sort expression string. This composable externalizes the sort logic from VcDataTable, making it easy to drive server-side sorting, persist sort preferences, or share sort state across multiple components.
diff --git a/framework/ui/types/ui-types.docs.md b/framework/ui/types/ui-types.docs.md
index 44a755e27..8a702105c 100644
--- a/framework/ui/types/ui-types.docs.md
+++ b/framework/ui/types/ui-types.docs.md
@@ -1,3 +1,10 @@
+---
+title: UI Types
+category: reference
+group: api
+slug: types-ui
+---
+
 # UI Types
 
 TypeScript interfaces for UI component props shared across all form field components in the framework.
diff --git a/package.json b/package.json
index 256b7d986..b853417ec 100644
--- a/package.json
+++ b/package.json
@@ -45,7 +45,10 @@
     "diff": "LAST_TAG=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null) && git diff --stat \"${LAST_TAG}\"..HEAD || git diff --stat",
     "clean": "find . -name node_modules -type d -prune -exec rm -rf {} + && find . -name dist -type d -prune -exec rm -rf {} +",
     "lint-staged": "lint-staged",
-    "pre-commit": "yarn lint-staged && yarn check:locales && yarn check:layers"
+    "pre-commit": "yarn lint-staged && yarn check:locales && yarn check:layers",
+    "docs:sync": "yarn workspace @vc-shell/docs-sync exec docs-sync sync --target ../vc-docs",
+    "docs:lint": "yarn workspace @vc-shell/docs-sync exec docs-sync lint",
+    "docs:screenshot": "yarn workspace @vc-shell/docs-sync exec docs-sync screenshot"
   },
   "workspaces": [
     "framework",
diff --git a/yarn.lock b/yarn.lock
index 5c81a7d65..c31bda80a 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2844,6 +2844,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@playwright/test@npm:^1.52.0":
+  version: 1.59.1
+  resolution: "@playwright/test@npm:1.59.1"
+  dependencies:
+    playwright: "npm:1.59.1"
+  bin:
+    playwright: cli.js
+  checksum: 10/27a894c4d4216b51cddc96e18fd0638a9e2e0a3f0b7ee32a56121fb61df395ec43529f5dcdca32578af8a34a04722ee3767f99f0ae4d39fa8edceda89a96014c
+  languageName: node
+  linkType: hard
+
 "@polka/url@npm:^1.0.0-next.24":
   version: 1.0.0-next.29
   resolution: "@polka/url@npm:1.0.0-next.29"
@@ -3188,6 +3199,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@sindresorhus/merge-streams@npm:^2.1.0":
+  version: 2.3.0
+  resolution: "@sindresorhus/merge-streams@npm:2.3.0"
+  checksum: 10/798bcb53cd1ace9df84fcdd1ba86afdc9e0cd84f5758d26ae9b1eefd8e8887e5fc30051132b9e74daf01bb41fa5a2faf1369361f83d76a3b3d7ee938058fd71c
+  languageName: node
+  linkType: hard
+
 "@sindresorhus/merge-streams@npm:^4.0.0":
   version: 4.0.0
   resolution: "@sindresorhus/merge-streams@npm:4.0.0"
@@ -4739,6 +4757,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/write-file-atomic@npm:^4.0.3":
+  version: 4.0.3
+  resolution: "@types/write-file-atomic@npm:4.0.3"
+  dependencies:
+    "@types/node": "npm:*"
+  checksum: 10/d8b8a3e5c21dca099196724066de44f5ea5612e1295b594d02ac9c5e3a91d9f3fa220ea860c1afd09e957914129009b3b84a86b49d42878f738b21cb179179a4
+  languageName: node
+  linkType: hard
+
 "@types/yargs-parser@npm:*":
   version: 21.0.3
   resolution: "@types/yargs-parser@npm:21.0.3"
@@ -5210,6 +5237,28 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@vc-shell/docs-sync@workspace:cli/docs-sync":
+  version: 0.0.0-use.local
+  resolution: "@vc-shell/docs-sync@workspace:cli/docs-sync"
+  dependencies:
+    "@playwright/test": "npm:^1.52.0"
+    "@types/node": "npm:^20.10.5"
+    "@types/write-file-atomic": "npm:^4.0.3"
+    "@vc-shell/ts-config": "workspace:*"
+    chalk: "npm:^5.3.0"
+    commander: "npm:^12.0.0"
+    globby: "npm:^14.0.0"
+    gray-matter: "npm:^4.0.3"
+    tsx: "npm:^4.7.0"
+    typescript: "npm:^5.8.3"
+    vitest: "npm:^3.1.2"
+    write-file-atomic: "npm:^7.0.1"
+    zod: "npm:^3.23.0"
+  bin:
+    docs-sync: ./dist/index.js
+  languageName: unknown
+  linkType: soft
+
 "@vc-shell/framework@workspace:*, @vc-shell/framework@workspace:framework":
   version: 0.0.0-use.local
   resolution: "@vc-shell/framework@workspace:framework"
@@ -6404,14 +6453,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"argparse@npm:^2.0.1":
-  version: 2.0.1
-  resolution: "argparse@npm:2.0.1"
-  checksum: 10/18640244e641a417ec75a9bd38b0b2b6b95af5199aa241b131d4b2fb206f334d7ecc600bd194861610a5579084978bfcbb02baa399dbe442d56d0ae5e60dbaef
-  languageName: node
-  linkType: hard
-
-"argparse@npm:~1.0.9":
+"argparse@npm:^1.0.7, argparse@npm:~1.0.9":
   version: 1.0.10
   resolution: "argparse@npm:1.0.10"
   dependencies:
@@ -6420,6 +6462,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"argparse@npm:^2.0.1":
+  version: 2.0.1
+  resolution: "argparse@npm:2.0.1"
+  checksum: 10/18640244e641a417ec75a9bd38b0b2b6b95af5199aa241b131d4b2fb206f334d7ecc600bd194861610a5579084978bfcbb02baa399dbe442d56d0ae5e60dbaef
+  languageName: node
+  linkType: hard
+
 "aria-query@npm:5.3.0":
   version: 5.3.0
   resolution: "aria-query@npm:5.3.0"
@@ -10383,6 +10432,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"extend-shallow@npm:^2.0.1":
+  version: 2.0.1
+  resolution: "extend-shallow@npm:2.0.1"
+  dependencies:
+    is-extendable: "npm:^0.1.0"
+  checksum: 10/8fb58d9d7a511f4baf78d383e637bd7d2e80843bd9cd0853649108ea835208fb614da502a553acc30208e1325240bb7cc4a68473021612496bb89725483656d8
+  languageName: node
+  linkType: hard
+
 "extend@npm:~3.0.2":
   version: 3.0.2
   resolution: "extend@npm:3.0.2"
@@ -11335,6 +11393,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"globby@npm:^14.0.0":
+  version: 14.1.0
+  resolution: "globby@npm:14.1.0"
+  dependencies:
+    "@sindresorhus/merge-streams": "npm:^2.1.0"
+    fast-glob: "npm:^3.3.3"
+    ignore: "npm:^7.0.3"
+    path-type: "npm:^6.0.0"
+    slash: "npm:^5.1.0"
+    unicorn-magic: "npm:^0.3.0"
+  checksum: 10/e527ff54f0dddf60abfabd0d9e799768619d957feecd8b13ef60481f270bfdce0d28f6b09267c60f8064798fb3003b8ec991375f7fe0233fbce5304e1741368c
+  languageName: node
+  linkType: hard
+
 "globby@npm:^16.2.0":
   version: 16.2.0
   resolution: "globby@npm:16.2.0"
@@ -11388,6 +11460,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"gray-matter@npm:^4.0.3":
+  version: 4.0.3
+  resolution: "gray-matter@npm:4.0.3"
+  dependencies:
+    js-yaml: "npm:^3.13.1"
+    kind-of: "npm:^6.0.2"
+    section-matter: "npm:^1.0.0"
+    strip-bom-string: "npm:^1.0.0"
+  checksum: 10/9a8f146a7a918d2524d5d60e0b4d45729f5bca54aa41247f971d9e4bc984943fda58159435763d463ec2abc8a0e238e807bd9b05e3a48f4a613a325c9dd5ad0c
+  languageName: node
+  linkType: hard
+
 "gridstack@npm:^12.4.2":
   version: 12.6.0
   resolution: "gridstack@npm:12.6.0"
@@ -11779,7 +11863,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ignore@npm:^7.0.5":
+"ignore@npm:^7.0.3, ignore@npm:^7.0.5":
   version: 7.0.5
   resolution: "ignore@npm:7.0.5"
   checksum: 10/f134b96a4de0af419196f52c529d5c6120c4456ff8a6b5a14ceaaa399f883e15d58d2ce651c9b69b9388491d4669dda47285d307e827de9304a53a1824801bc6
@@ -12068,6 +12152,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"is-extendable@npm:^0.1.0":
+  version: 0.1.1
+  resolution: "is-extendable@npm:0.1.1"
+  checksum: 10/3875571d20a7563772ecc7a5f36cb03167e9be31ad259041b4a8f73f33f885441f778cee1f1fe0085eb4bc71679b9d8c923690003a36a6a5fdf8023e6e3f0672
+  languageName: node
+  linkType: hard
+
 "is-extglob@npm:^2.1.1":
   version: 2.1.1
   resolution: "is-extglob@npm:2.1.1"
@@ -12779,6 +12870,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"js-yaml@npm:^3.13.1":
+  version: 3.14.2
+  resolution: "js-yaml@npm:3.14.2"
+  dependencies:
+    argparse: "npm:^1.0.7"
+    esprima: "npm:^4.0.0"
+  bin:
+    js-yaml: bin/js-yaml.js
+  checksum: 10/172e0b6007b0bf0fc8d2469c94424f7dd765c64a047d2b790831fecef2204a4054eabf4d911eb73ab8c9a3256ab8ba1ee8d655b789bf24bf059c772acc2075a1
+  languageName: node
+  linkType: hard
+
 "js-yaml@npm:^4.1.0, js-yaml@npm:^4.1.1":
   version: 4.1.1
   resolution: "js-yaml@npm:4.1.1"
@@ -13051,7 +13154,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"kind-of@npm:^6.0.2, kind-of@npm:^6.0.3":
+"kind-of@npm:^6.0.0, kind-of@npm:^6.0.2, kind-of@npm:^6.0.3":
   version: 6.0.3
   resolution: "kind-of@npm:6.0.3"
   checksum: 10/5873d303fb36aad875b7538798867da2ae5c9e328d67194b0162a3659a627d22f742fc9c4ae95cd1704132a24b00cae5041fc00c0f6ef937dc17080dc4dbb962
@@ -15068,6 +15171,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"path-type@npm:^6.0.0":
+  version: 6.0.0
+  resolution: "path-type@npm:6.0.0"
+  checksum: 10/b9f6eaf7795c48d5c9bc4c6bc3ac61315b8d36975a73497ab2e02b764c0836b71fb267ea541863153f633a069a1c2ed3c247cb781633842fc571c655ac57c00e
+  languageName: node
+  linkType: hard
+
 "path@npm:^0.12.7":
   version: 0.12.7
   resolution: "path@npm:0.12.7"
@@ -15234,7 +15344,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"playwright@npm:^1.52.0":
+"playwright@npm:1.59.1, playwright@npm:^1.52.0":
   version: 1.59.1
   resolution: "playwright@npm:1.59.1"
   dependencies:
@@ -16931,6 +17041,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"section-matter@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "section-matter@npm:1.0.0"
+  dependencies:
+    extend-shallow: "npm:^2.0.1"
+    kind-of: "npm:^6.0.0"
+  checksum: 10/cedfda3a9238f66942d92531fe043dd134702a462cdc9e254cd6aa418c66ca0d229900e4da78ffd1a07051e7b239251c4dc4748e9d1c76bf41a37bff7a478556
+  languageName: node
+  linkType: hard
+
 "semver@npm:2 || 3 || 4 || 5, semver@npm:^5.6.0":
   version: 5.7.2
   resolution: "semver@npm:5.7.2"
@@ -17691,6 +17811,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"strip-bom-string@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "strip-bom-string@npm:1.0.0"
+  checksum: 10/5635a3656d8512a2c194d6c8d5dee7ef0dde6802f7be9413b91e201981ad4132506656d9cf14137f019fd50f0269390d91c7f6a2601b1bee039a4859cfce4934
+  languageName: node
+  linkType: hard
+
 "strip-bom@npm:^3.0.0":
   version: 3.0.0
   resolution: "strip-bom@npm:3.0.0"
@@ -20234,7 +20361,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"zod@npm:^3.24.1":
+"zod@npm:^3.23.0, zod@npm:^3.24.1":
   version: 3.25.76
   resolution: "zod@npm:3.25.76"
   checksum: 10/f0c963ec40cd96858451d1690404d603d36507c1fc9682f2dae59ab38b578687d542708a7fdbf645f77926f78c9ed558f57c3d3aa226c285f798df0c4da16995