@vc-shell/vc-app-skill 2.5.0 → 2.6.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.5.0",
+  "version": "2.6.0-rc.0",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [

package/runtime/VERSION

@@ -1 +1 @@
-2.5.0
+2.6.0-rc.0

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 2964ccbe3 on 2026-08-19T10:23:33.758Z
+Synced from framework at commit 9cf874d09 on 2026-09-02T10:19:47.488Z

package/runtime/knowledge/docs/core/blade-navigation/blade-nav-composables.docs.md

@@ -44,10 +44,36 @@ The `createBladeStack` / `createBladeMessaging` factories are internal (not re-e
 
 The blade stack state machine. Manages an ordered array of `BladeDescriptor` objects.
 
-### Factory: `createBladeStack(bladeRegistry, hasAccess?)`
+### Factory: `createBladeStack(bladeRegistry, hasAccess?, urlSink?)`
 
 Creates a new stack instance. Called once by the navigation plugin.
 
+`urlSink` is where the stack writes the address bar. It defaults to a no-op, so a
+stack created without one (Storybook, standalone mounts, unit tests) simply never
+touches the URL. The plugin passes the router-backed sink.
+
+### The stack owns the URL
+
+Every navigation action syncs the URL itself, with the verb the action implies.
+Callers mutate the stack and nothing else — there is no "and now sync the URL"
+step to forget.
+
+| Action                | Verb      | When                                   |
+| --------------------- | --------- | -------------------------------------- |
+| `openWorkspace`       | `push`    | the resulting active blade has a `url` |
+| `openBlade`           | `push`    | the resulting active blade has a `url` |
+| `coverCurrentBlade`   | `push`    | the resulting active blade has a `url` |
+| `replaceCurrentBlade` | `replace` | the resulting active blade has a `url` |
+| `closeBlade`          | `replace` | the close was not prevented by a guard |
+| `closeChildren`       | `replace` | always                                 |
+
+Everything else — `updateBladeQuery`, `setBladeTitle`, `setBladeError`,
+`_restoreStack` — never writes the URL.
+
+The router guard restores the stack **from** the URL, so it suppresses the sink
+for the duration of the navigation (`RouterUrlSink.suppressWhile`): during
+resolution the URL is the source, and writing back would re-enter the guard.
+
 ### API
 
 | Method                                | Description                                                                                                                                        |
@@ -162,6 +188,7 @@ The plain data object stored in the stack for each blade:
 - 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.
+- The stack writes the URL, not the caller. `createUrlSync` remains for the two writes that are not stack mutations: the post-restore reconcile in `VcBladeNavigation` and the debounced table-query-state writer.
 - `useBladeNavigation()` requires the navigation plugin to be installed. It throws if called before plugin initialization.
 
 ## Related

package/runtime/knowledge/docs/core/composables/useBlade/useBlade.docs.md

@@ -790,7 +790,7 @@ if (param.value) {
 1. **Plugin setup:** `BladeNavigationPlugin` (plugin-v2) installs a `BladeStack` and `BladeMessaging` singleton and provides them via Vue's dependency injection.
 2. **Inside a blade:** `VcBladeSlot` provides a `BladeDescriptor` ref for each blade instance. `useBlade()` injects this descriptor to access identity, register guards, and set errors.
 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.
+4. **URL sync:** When blades with a `url` property are opened or closed, the blade stack synchronizes the browser URL itself (push on open, replace on close), enabling deep linking and back/forward navigation. `useBlade()` only mutates the stack.
 
 <!-- internal:end -->
 

package/runtime/knowledge/docs/core/composables/useLatestRequest/useLatestRequest.docs.md

@@ -35,35 +35,37 @@ const search = useLatestRequest();
 const items = ref([]);
 
 async function load(criteria) {
-  const request = search.begin();
-  try {
-    const result = await client.search(criteria);
-    if (!request.isCurrent()) return; // a newer search already won
-    items.value = result;
-  } finally {
-    request.complete();
-  }
+  const result = await search.latest(client.search(criteria));
+  if (!result) return; // a newer search already won
+  items.value = result;
 }
 ```
 
-Two rules make it correct:
+`latest()` owns the bookkeeping: it marks the request as the newest, releases it
+when it settles — including on a throw — and hands back `undefined` if a newer
+request started meanwhile. There is no `finally` to forget.
 
-1. Check `isCurrent()` **after** the await and before writing any state.
-2. Call `complete()` in a `finally`, so a throwing request still releases `pending`.
+!!! note "When `undefined` is ambiguous"
+`undefined` means superseded. A request whose own successful result can be
+`undefined` cannot distinguish the two, and should use `begin()` below.
 
 ## API Reference
 
 ### Returns
 
-| Member       | Type                     | Description                                                                       |
-| ------------ | ------------------------ | --------------------------------------------------------------------------------- |
-| `begin`      | `() => LatestRequest`    | Starts a request and supersedes any earlier one                                   |
-| `invalidate` | `() => void`             | Supersedes the in-flight request without starting a new one                       |
-| `dispose`    | `() => void`             | Permanently supersedes everything. Runs automatically when the owning scope stops |
-| `pending`    | `Readonly<Ref<boolean>>` | `true` while the newest request is still running                                  |
+| Member       | Type                                                  | Description                                                                       |
+| ------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `latest`     | `<T>(request: Promise<T>) => Promise<T \| undefined>` | Runs a request, resolving to `undefined` if a newer one superseded it             |
+| `begin`      | `() => LatestRequest`                                 | Starts a request and supersedes any earlier one. The manual form behind `latest`  |
+| `invalidate` | `() => void`                                          | Supersedes the in-flight request without starting a new one                       |
+| `dispose`    | `() => void`                                          | Permanently supersedes everything. Runs automatically when the owning scope stops |
+| `pending`    | `Readonly<Ref<boolean>>`                              | `true` while the newest request is still running                                  |
 
 ### `LatestRequest`
 
+Returned by `begin()`, for the cases `latest()` cannot serve: the request and the
+check living in different functions, or a result that is legitimately `undefined`.
+
 | Member      | Type            | Description                                                                        |
 | ----------- | --------------- | ---------------------------------------------------------------------------------- |
 | `isCurrent` | `() => boolean` | `false` once a newer request started, or after `invalidate()` / `dispose()`        |

package/runtime/knowledge/docs/core/composables/useModificationTracker/useModificationTracker.docs.md

@@ -6,6 +6,17 @@ group: forms
 
 # useModificationTracker
 
+!!! warning "Deprecated — use `useBladeForm`"
+`useBladeForm` owns validation, the dirty flag, the unsaved-changes guard and the
+close prompt together, where this tracks only the dirty flag. It has no callers
+left in the framework or the reference app, and `cli/migrate`'s `use-blade-form`
+transform already flags the `useForm` + `useBeforeUnload` +
+`useModificationTracker` combination for the same move.
+
+    Its comparator is deliberately not being aligned with `useBladeForm`'s: an
+    empty array counts as empty there and not here, and changing that would move
+    the dirty flag under anyone still on this composable.
+
 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.
 
 The composable maintains two copies of the data: the `pristineValue` (the clean baseline) and the `currentValue` (the working copy bound to form fields). Any deep difference between the two sets `isModified` to `true`.

package/runtime/knowledge/docs/core/composables/usePopup/usePopup.docs.md

@@ -110,6 +110,8 @@ The plugin instance is resolved via `inject(PopupPluginKey)`. If called outside
 
 Multiple popups can be open simultaneously — they stack with the most recent on top.
 
+On close, focus returns to the control that opened the popup (WCAG 2.4.3 Focus Order). When that control was never focused, or has since been removed from the page, focus goes to the app workspace instead — never left on `<body>`, which would make the next Tab restart at the top of the document. A popup that deliberately moved focus somewhere else keeps it; this repairs lost focus rather than dictating it.
+
 ## Recipe: Delete Confirmation with Notification
 
 ```vue

package/runtime/knowledge/docs/core/composables/useSidebarState/useSidebarState.docs.md

@@ -8,8 +8,6 @@ group: ui-state
 
 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.
 
-Internally, it delegates to `useMenuExpanded()` to share reactive state with other components like `UserDropdownButton` that also need to know the sidebar state.
-
 ## When to Use
 
 - Toggle or read sidebar expanded/collapsed state from any component inside VcApp
@@ -82,6 +80,20 @@ provideSidebarState();
 
 <!-- internal:end -->
 
+## Storage key
+
+The pinned state lives in `localStorage` under an app-scoped key -- the first segment of the URL path, so several vc-shell apps on one domain keep independent sidebars. `sidebarStorageKey()` returns that key, so tests and stories can seed the state before `VcApp` mounts instead of hard-coding the string:
+
+```typescript
+import { sidebarStorageKey } from "@vc-shell/framework";
+
+// Served from "/operations/catalog" -> "VC_APP_MENU_EXPANDED_operations"
+localStorage.setItem(sidebarStorageKey(), "true");
+
+// Or name the app explicitly
+localStorage.setItem(sidebarStorageKey("operations"), "false");
+```
+
 ## Recipe: Auto-Close Mobile Menu After Navigation
 
 ```vue
@@ -138,10 +150,9 @@ const contentClass = computed(() => (isExpanded.value ? "tw-ml-64" : "tw-ml-16")
 ## Tips
 
 - **Hover delay prevents flicker.** The 200ms delay on `setHoverExpanded(true)` means that quickly passing the mouse over the sidebar does not cause it to flash open. Closing is instant so the sidebar feels responsive.
-- **`isPinned` is persisted to localStorage.** If a user pins the sidebar, it stays pinned across page reloads and browser sessions. The key is managed internally by `useMenuExpanded`.
+- **`isPinned` is persisted to localStorage.** If a user pins the sidebar, it stays pinned across page reloads and browser sessions. The key is app-scoped -- `sidebarStorageKey()` returns it.
 - **Do not call outside VcApp.** If you call `useSidebarState()` in a component that is not a descendant of VcApp (e.g., in a standalone dialog or a separate Vue app instance), it will throw an error.
 
 ## Related
 
-- `useMenuExpanded` -- lower-level composable that manages pinned/hover state and localStorage persistence
 - `VcApp` -- the root component that calls `provideSidebarState()`

package/runtime/knowledge/docs/core/composables/useToolbar/useToolbar.docs.md

@@ -350,6 +350,10 @@ function helperFunction() {
 | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `provideToolbarService()` | Creates and provides the toolbar service via Vue injection. Idempotent -- returns existing service if already provided. Cleans up via `onScopeDispose`. |
 
+!!! note "When you need it"
+
+    Inside a shell app the framework install already provides the toolbar service, so `provideToolbarService()` returns the existing instance and you do not need to call it. Use it when bootstrapping an isolated tree (stories, tests) that has not installed the framework, the same way as `provideWidgetService()` and `provideDashboardService()`.
+
 ### IToolbarItem
 
 | Property       | Type                                                                                                              | Required | Description                                                                                                                 |

package/runtime/knowledge/docs/core/services/services.docs.md

@@ -41,7 +41,6 @@ Every service follows the same architecture:
 | **SettingsMenuService**        | `createSettingsMenuService()`            | `addSettingsMenuItem()`                                                                                                   | `ISettingsMenuItem`                       |
 | **AppBarWidgetService**        | `createAppBarWidgetService()`            | `addAppBarWidget()`                                                                                                       | `AppBarWidget`                            |
 | **AppBarMobileButtonsService** | `createAppBarMobileButtonsService()`     | (direct API)                                                                                                              | `AppBarButtonContent`                     |
-| **GlobalSearchService**        | `createGlobalSearchService()`            | (direct API)                                                                                                              | per-blade search state                    |
 | **LanguageService**            | `createLanguageService()`                | (direct API)                                                                                                              | locale strings                            |
 
 ## Usage

package/runtime/knowledge/docs/ui/components/atoms/vc-button/vc-button.docs.md

@@ -315,6 +315,7 @@ All visual properties are customizable through CSS custom properties. Each varia
 - `aria-pressed` reflects the `selected` prop for toggle buttons
 - Icon-only buttons **must** include `ariaLabel` for screen reader users
 - Disabled buttons use `pointer-events: none` and `opacity: 0.5` to prevent interaction
+- A button that becomes disabled **while it holds focus** keeps the focus: it switches to `aria-disabled` instead of the native attribute, since a natively disabled element cannot be focused and focus would fall to `<body>` (WCAG 2.4.3). It stays inert, and the user is still on it when the work finishes. Every other disabled button keeps the native attribute and stays out of the tab order.
 - The `click` event calls `e.preventDefault()` -- use `type="submit"` for form submissions
 
 ## Related Components

package/runtime/knowledge/docs/ui/components/molecules/vc-popover/vc-popover.docs.md

@@ -59,6 +59,7 @@ const open = ref(false);
 | `contentScrollable`   | `boolean`                  | `true`           | Enable scrolling in the content area                                                                                                                                                                                                                                                                                                                                                      |
 | `closeOnClickOutside` | `boolean`                  | `true`           | Close when clicking outside                                                                                                                                                                                                                                                                                                                                                               |
 | `closeOnEscape`       | `boolean`                  | `true`           | Close on Escape key                                                                                                                                                                                                                                                                                                                                                                       |
+| `inert`               | `boolean`                  | `false`          | Hide the panel from assistive technology and keyboard focus while something covers it. The panel is teleported, so it does not inherit `inert` from an ancestor — pass it explicitly                                                                                                                                                                                                      |
 
 ## Events
 
@@ -143,7 +144,7 @@ The panel's z-index comes from the global `--z-critical-floating-panel` token an
 - Escape key dismisses the panel (configurable via `closeOnEscape`)
 - Click-outside detection uses `pointerdown` for reliable z-index handling
 - Supports nested panels via an internal anchor registry -- child panel clicks do not close parent panels
-- Exposes `close()` method via template ref
+- Exposes `close()` and `panelEl` (the teleported panel element) via template ref
 
 ## Related Components
 
@@ -157,7 +158,7 @@ The panel's z-index comes from the global `--z-critical-floating-panel` token an
 - 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, Element | null>` that maps each open panel's DOM element to its anchor element. When `anchorRef` is a floating-ui `VirtualElement`, the registry stores its `contextElement` (the live DOM element backing the virtual reference). 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.
+- The panel exposes `close()` and `panelEl` via `defineExpose` for use with template refs. `panelEl` is the teleported panel itself — a call site managing focus needs it to answer "is focus still inside?", and cannot reach it any other way.
 - `useTeleportTarget` resolves the teleport destination (typically `body`) respecting any custom portal container.
 
 <!-- internal:end -->

package/runtime/knowledge/docs/ui/components/organisms/vc-app/vc-app.docs.md

@@ -79,7 +79,7 @@ VcApp orchestrates several internal systems:
 1. **Layout** -- switches between `DesktopLayout` (sidebar) and `MobileLayout` (top bar) based on viewport width. The breakpoint is managed by the framework's responsive detection system.
 2. **Blade Navigation** -- renders `VcBladeNavigation` for the stacked panel workspace. Blades open to the right and scroll horizontally.
 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.
+4. **Services** -- provides the shell-scoped services via `useShellBootstrap`: dashboard, app bar mobile buttons, and the AI agent when configured. Menu, toolbar, widget and settings services are provided earlier, by the framework install. All are reachable from child components through provide/inject.
 
 <!-- internal:end -->
 

package/runtime/knowledge/docs/ui/components/organisms/vc-data-table/vc-data-table.docs.md

@@ -211,6 +211,83 @@ For any rendering not covered by built-in types, use the `#body` slot:
 </VcColumn>
 ```
 
+### Custom Cell Types
+
+A `#body` slot covers one-off formatting. When the same rendering should apply
+to a column `type` across every table in the app, register a cell component
+instead. Registration is global and reactive — already-mounted tables pick the
+new component up.
+
+```ts
+// src/cells/register.ts — imported once from your app entry point
+import { useCellRegistry } from "@vc-shell/framework";
+import CellRating from "./CellRating.vue";
+
+const { register } = useCellRegistry();
+
+register({
+  type: "rating",
+  component: CellRating,
+  config: { editable: false },
+});
+```
+
+```vue
+<VcColumn id="rating" field="rating" title="Rating" type="rating" />
+```
+
+The cell component receives a `value` prop holding the resolved field value.
+When `config.editable` is `true`, it also receives `editable`, `label`,
+`fieldName`, `fieldId`, `rules` and `rowIndex` while the row is being edited —
+mirror `CellDefault.vue` for that contract.
+
+Registering an existing type replaces the built-in for the whole app:
+
+```ts
+register({ type: "money", component: MyMoneyCell, config: { editable: true } });
+```
+
+The 12 built-ins are registered by `registerBuiltinCells()`, which runs once
+when the table's cell renderer module is loaded — that is, as soon as anything
+imports `VcDataTable`. Because ES modules finish evaluating before the module
+that imported them runs, that always happens before your own registration code,
+and `register()` is last-write-wins — so a type you register replaces the
+built-in. `registerBuiltinCells()` itself skips types that are already present,
+which keeps it idempotent and stops it clobbering a registration that did manage
+to land first (for instance when the table is loaded through a dynamic
+`import()`). `BUILTIN_CELL_TYPES` lists the names that are taken.
+
+A `type` that resolves to nothing falls back to `CellDefault`, which renders the
+raw value. Custom names are allowed, so a misspelt built-in is not a type error;
+in development builds an unresolved type logs a warning naming the type.
+
+#### Cell registry API
+
+| Member               | Signature                                         | Description                                              |
+| -------------------- | ------------------------------------------------- | -------------------------------------------------------- |
+| `register`           | `(registration: CellRegistration) => void`        | Register or replace a cell type.                         |
+| `get`                | `(type: string) => CellRegistration \| undefined` | Look up a registration.                                  |
+| `has`                | `(type: string) => boolean`                       | Whether a type is registered.                            |
+| `getRegisteredTypes` | `() => string[]`                                  | All registered type names.                               |
+| `unregister`         | `(type: string) => boolean`                       | Remove a type. Returns `false` if it was not registered. |
+| `clear`              | `() => void`                                      | Remove every registration, including the built-ins.      |
+
+Two module-level exports come with it:
+
+| Export                 | Signature             | Description                                                                                               |
+| ---------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- |
+| `registerBuiltinCells` | `() => void`          | Register the 12 built-in cell types. Idempotent and non-destructive; called for you when the table loads. |
+| `BUILTIN_CELL_TYPES`   | `readonly CellType[]` | The names of the 12 built-in types.                                                                       |
+
+`CellRegistration` is `{ type: CellType | string; component: Component; config?: { editable?: boolean; additionalProps?: string[] } }`.
+
+`clear()` empties the registry permanently — `registerBuiltinCells()` runs once
+per module load, so it will not repopulate on its own. Call it again yourself if
+you need the built-ins back.
+
+`CellType` accepts the 12 built-in names with autocomplete plus any custom
+string. `BuiltinCellType` is the narrow union of just the built-ins.
+
 ---
 
 ## Sorting

package/runtime/knowledge/docs/ui/components/organisms/vc-scheduler/vc-scheduler.docs.md

@@ -162,6 +162,8 @@ With `editable`, `VcScheduler` ships a complete built-in create/edit flow -- no
 
 The editor modal additionally exposes all-day toggle, start/end date-time, and color, plus a Delete action in edit mode (commits via `event-delete`). Saving from either surface emits the public `event-create`/`event-update` event -- see [Events](#events) for the exact payloads.
 
+For an **all-day** event the editor's End field is the last day the event covers, matching what the chip and the quick-info popover announce -- so a one-day event has End equal to Start. The `end` in the emitted payload is still the exclusive midnight boundary the layout works in; the editor converts on save. An End before Start is refused rather than saved.
+
 This entire flow is internal state: no `v-model` or extra event wiring is needed to make it work, beyond `editable` and the `event-create`/`event-update`/`event-delete` handlers you already have for persisting the result.
 
 ### `editorMode`: opting out of the built-in UI
@@ -498,8 +500,8 @@ const events = [{ id: "a", title: "Promo", start, end, allDay: true, color: "#a2
 - The Month grid uses `role="grid"` / `role="row"` / `role="gridcell"` / `role="columnheader"` for the weekday header and day cells, each `gridcell` carrying a full formatted-date `aria-label`.
 - Each event bar and timed chip is a focusable `role="button"` element (`tabindex="0"`) with an `aria-label` built from its title and formatted start/end dates -- activate with click or `Enter`. For an all-day event the announced end is the **last inclusive day**, not the exclusive `end` you pass: an event with `end` at midnight runs through the previous day, so a one-day event is announced as a single date rather than a two-day range. Timed events are announced with their real times.
 - The "+N more" overflow control is a `<button>` whose visible text is its accessible name; the date it belongs to comes from the enclosing `gridcell`. Activating it moves focus to the first event in the popover, and closing the popover (Escape, or the close button) returns focus to the "+N more" button. Each event inside the popover is a `<button>` too, so a day's 4th and later events are reachable and operable by keyboard.
-- The overflow popover's panel is a `VcPopover`, which supplies a titled header (the formatted date) and Escape-to-close. It does **not** apply `role="dialog"` or trap focus -- `VcPopover` has no focus management of its own, so any popover-based surface that needs focus moved into it does that itself, as the overflow popover above does.
-- The editor modal and the This event/All events scope dialog are `VcPopup`, which is a Headless UI `Dialog` -- those do get accessible naming, a focus trap, focus restore and `inert` on the background from the library. The built-in quick-create popover is a `VcPopover` and focuses its title field on open.
+- All three anchored popovers -- "+N more" overflow, quick-info and quick-create -- are `VcPopover` panels carrying `role="dialog"` and an accessible name (the formatted date, the event title, and "New event" respectively). They do **not** trap focus: `VcPopover` has no focus management of its own, so each one moves focus into itself on open and hands it back to whatever opened it on close. Focus is repaired, not dictated -- a user who moves focus out of the panel keeps it there when the panel closes.
+- The editor modal and the This event/All events scope dialog are `VcPopup`, which is a Headless UI `Dialog` -- those do get accessible naming, a focus trap, focus restore and `inert` on the background from the library.
 - The recurrence editor's weekday toggle buttons expose `aria-pressed` (selected state) and an `aria-label` with the full weekday name, since their visible narrow labels ("S", "M", "T", ...) collide (Sun/Sat, Tue/Thu). The "↻" recurring-occurrence marker is `aria-hidden` -- purely visual, redundant with the event's own accessible name.
 - The toolbar's prev/next buttons carry an explicit `aria-label` ("Previous" / "Next") since they are icon-only; the today/view-switch buttons show text labels.
 - Event move/resize (Month view's `editable`) is a pointer-drag interaction with no keyboard equivalent yet; use a form outside VcScheduler for keyboard-only date edits. Timeline view is read-only (click still opens the quick-info popover).

package/runtime/vc-app.md

@@ -101,6 +101,7 @@ Collect project parameters through dialog, then run CLI in **non-interactive mod
    - `--dashboard` — Include a dashboard page
    - `--tenant-routes` — Include tenant-aware routing
    - `--ai-agent` — Include AI agent integration scaffold
+   - `--module-federation` — Include the Module Federation host runtime (load remote modules)
    - `--mocks` — Include sample modules with mock data (demo content to explore the framework)
 
 ### Execution
@@ -110,7 +111,7 @@ Collect project parameters through dialog, then run CLI in **non-interactive mod
 ```bash
 npx @vc-shell/create-vc-app@alpha <projectName> \
   --type standalone \
-  [--dashboard] [--tenant-routes] [--ai-agent] [--mocks]
+  [--dashboard] [--tenant-routes] [--ai-agent] [--module-federation] [--mocks]
 ```
 
 **IMPORTANT:** Do NOT pass `--module-name` — the starter module is opt-in and unnecessary because this skill generates custom modules via `/vc-app generate`.
@@ -125,6 +126,7 @@ Available CLI flags (see `cli/create-vc-app/README.md` for full list):
 | `--dashboard` | Include Dashboard |
 | `--tenant-routes` | Include tenant routing |
 | `--ai-agent` | Include AI Agent config |
+| `--module-federation` | Include Module Federation host runtime |
 | `--mocks` | Include sample modules with mock data (demo content) |
 | `--overwrite` | Overwrite existing files |
 
@@ -1198,7 +1200,7 @@ After the user confirms the plan:
 If `DESIGN_PLAN.needsScaffold` is true, run the `/vc-app create` flow:
 
 - Use `DESIGN_PLAN.appName` as the project name
-- Enable default options (no dashboard, no tenant-routes, no ai-agent, no mocks)
+- Enable default options (no dashboard, no tenant-routes, no ai-agent, no module-federation, no mocks)
 - After scaffold completes, `cd` into the new project directory
 - Update project root for subsequent steps
 

package/runtime/knowledge/docs/core/composables/useMenuExpanded/index.docs.md

@@ -1,93 +0,0 @@
----
-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).
-
-## When to Use
-
-- Low-level control over sidebar pin and hover state
-- Building a custom sidebar component that needs expand/collapse persistence
-- When NOT to use: prefer `useSidebarState` which wraps this composable and adds mobile menu support, derived `isExpanded` computed, and responsive breakpoint handling
-
-## Basic Usage
-
-```typescript
-import { useMenuExpanded } from "@vc-shell/framework";
-
-const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded();
-
-// Toggle pin state (persisted to localStorage)
-toggleExpanded();
-
-// Hover expand with 200ms delay
-toggleHoverExpanded(true); // opens after delay
-toggleHoverExpanded(false); // closes immediately
-```
-
-## API
-
-### Returns
-
-| Property              | Type                               | Description                                                      |
-| --------------------- | ---------------------------------- | ---------------------------------------------------------------- |
-| `isExpanded`          | `Ref<boolean>`                     | Pinned state, persisted via `useLocalStorage`                    |
-| `toggleExpanded`      | `() => void`                       | Toggle the pinned state                                          |
-| `isHoverExpanded`     | `Ref<boolean>`                     | Temporary hover expansion (not persisted)                        |
-| `toggleHoverExpanded` | `(shouldExpand?: boolean) => void` | Set hover state; opening has a 200ms delay, closing is immediate |
-
-## Recipe: Custom Sidebar with Hover Expand
-
-A common pattern is binding mouse events on the sidebar rail so the menu previews its full width on hover, without permanently pinning it open:
-
-```vue
-<script setup lang="ts">
-import { computed } from "vue";
-import { useMenuExpanded } from "@vc-shell/framework";
-
-const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded();
-
-// The sidebar is visually expanded if pinned OR hover-expanded
-const isVisuallyExpanded = computed(() => isExpanded.value || isHoverExpanded.value);
-</script>
-
-<template>
-  <aside
-    :class="{ 'sidebar--expanded': isVisuallyExpanded }"
-    @mouseenter="toggleHoverExpanded(true)"
-    @mouseleave="toggleHoverExpanded(false)"
-  >
-    <nav>
-      <!-- menu items -->
-    </nav>
-    <button @click="toggleExpanded">
-      {{ isExpanded ? "Unpin" : "Pin" }}
-    </button>
-  </aside>
-</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 `/operations/`, the key is `VC_APP_MENU_EXPANDED_operations`. 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
-
-- If you call `toggleHoverExpanded(true)` and then `toggleHoverExpanded(false)` within the 200ms window, the expansion is canceled -- the timeout is cleared before it fires.
-- The composable does not handle mobile breakpoints. For responsive behavior, use `useSidebarState` instead, which combines `useMenuExpanded` with mobile detection.
-- Each call to `useMenuExpanded()` creates a new instance with its own timeout tracking, but they share the same localStorage-backed `isExpanded` ref (via `useLocalStorage`). Multiple instances will stay in sync for the pinned state.
-
-## Related
-
-- `useSidebarState` -- higher-level composable that adds mobile menu and derived `isExpanded` computed