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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.5.0-pr351.8e074ad",
+  "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/useKeyboardShortcuts/useKeyboardShortcuts.docs.md

@@ -0,0 +1,219 @@
+---
+title: useKeyboardShortcuts
+category: composables
+group: utilities
+---
+
+!!! tip "Long page"
+Use the section headings to jump directly to what you need: [Primary pattern: declare a shortcut on a toolbar item](#primary-pattern-declare-a-shortcut-on-a-toolbar-item), [Quick Start](#quick-start), [Built-in blade shortcuts](#built-in-blade-shortcuts), or [API Reference](#api-reference).
+
+# useKeyboardShortcuts
+
+`useKeyboardShortcuts` is the framework's keyboard-shortcut toolkit: the `hotkey` fluent builder for describing a combination, and OS-aware formatting for the tooltip and `aria-keyshortcuts` that a toolbar button shows automatically once it declares one. There is no manual `keydown` wiring in module code -- a shortcut is a plain field on a toolbar item, and the blade navigation layer dispatches it globally.
+
+## Primary pattern: declare a shortcut on a toolbar item
+
+Add `shortcut: hotkey.mod.s` to any `IBladeToolbar` entry. `hotkey.mod.s` resolves to `{ key: "s", mod: true }` -- `mod` is the platform's primary modifier (Cmd on macOS, Ctrl elsewhere), so one definition covers both operating systems.
+
+```vue title="orders-details.vue"
+<script setup lang="ts">
+import { ref } from "vue";
+import { hotkey, VcBlade, type IBladeToolbar } from "@vc-shell/framework";
+
+const bladeToolbar = ref<IBladeToolbar[]>([
+  {
+    id: "save",
+    title: "Save",
+    icon: "lucide-save",
+    shortcut: hotkey.mod.s,
+    clickHandler: () => save(),
+  },
+]);
+</script>
+
+<template>
+  <VcBlade :toolbar-items="bladeToolbar" />
+</template>
+```
+
+That single field is the whole integration. The rendered "Save" button now shows a `⌘S` / `Ctrl+S` tooltip, sets `aria-keyshortcuts="Meta+S"`, and the blade navigation layer fires `clickHandler` when the user presses the combination while the blade is active -- no listener, no cleanup.
+
+## When to reach for it
+
+- **Declaring a shortcut on a toolbar item.** The common case: add `shortcut: hotkey.mod.s` next to `clickHandler` on an `IBladeToolbar` entry (array pattern or `useToolbar().registerToolbarItem`, see [useToolbar](../useToolbar/)).
+- **Formatting a shortcut for custom UI.** Call `useKeyboardShortcuts()` and use `formatShortcut(def)` when you need the OS-aware label somewhere other than the built-in toolbar tooltip (a help panel, a command palette row).
+- **Detecting the platform.** `isMac` is exposed for any OS-conditional copy or icon choice tied to a shortcut.
+- **Not for building your own key listener.** There is no public "register a global shortcut" API outside toolbar items -- see [Common mistakes](#common-mistakes).
+
+## Quick Start
+
+### Import vs `useKeyboardShortcuts()` destructure
+
+`hotkey` is a context-free singleton -- import it directly wherever you only need to build a definition:
+
+```typescript
+import { hotkey } from "@vc-shell/framework";
+
+const saveShortcut = hotkey.mod.s; // { key: "s", mod: true }
+```
+
+Reach for the composable form only when you also need `formatShortcut` or `isMac` (both are bound together so `formatShortcut` doesn't need an `isMac` argument at the call site):
+
+```typescript
+import { useKeyboardShortcuts } from "@vc-shell/framework";
+
+const { hotkey, formatShortcut, isMac } = useKeyboardShortcuts();
+
+const saveShortcut = hotkey.mod.s;
+const { parts, aria } = formatShortcut(saveShortcut);
+// isMac ? parts = ["⌘", "S"] : parts = ["Ctrl", "S"]
+// aria = "Meta+S" on macOS, "Control+S" elsewhere
+```
+
+Both forms return the same `hotkey` singleton -- the composable exists for convenience when a component already needs `isMac`/`formatShortcut`, not because `hotkey` itself carries state.
+
+## Built-in blade shortcuts
+
+Two shortcuts are wired up by the framework at the blade navigation root -- no client code required, and no toolbar item needed to get them:
+
+| Shortcut     | Effect                  | Gate                                                                        |
+| ------------ | ----------------------- | --------------------------------------------------------------------------- |
+| `Esc`        | Closes the active blade | Only if the blade is closable (has a `parentId`; workspace roots ignore it) |
+| `Cmd/Ctrl+\` | Toggles expand/maximize | Only on desktop and only if the blade is closable                           |
+
+Both are evaluated against the currently active blade, and both are skipped while the corresponding condition doesn't hold -- `Esc` on a non-closable workspace root does nothing, and `Cmd/Ctrl+\` does nothing on mobile viewports even on a closable blade.
+
+**An explicit toolbar shortcut always wins.** The dispatcher checks the active blade's toolbar items before either built-in, so a toolbar item declared with `shortcut: hotkey.escape` (for example, a "Cancel" button) intercepts `Esc` and the built-in close never runs.
+
+## OS adaptation
+
+`formatShortcut(def)` returns two independent representations from one `ShortcutDefinition`, so you never branch on OS yourself:
+
+- `parts` -- an array of OS-native keycap labels for display. macOS renders modifier glyphs in Apple's canonical order (`⌃ ⌥ ⇧ ⌘`) with no separator; Windows/Linux render words (`Ctrl`, `Alt`, `Shift`) with a `+` between chips.
+- `aria` -- a single canonical string in W3C `aria-keyshortcuts` format (`"Control+Shift+S"`), OS-independent by design -- this is what assistive tech reads, not what's painted on screen.
+
+```typescript
+import { useKeyboardShortcuts } from "@vc-shell/framework";
+
+const { hotkey, formatShortcut, isMac } = useKeyboardShortcuts();
+const { parts } = formatShortcut(hotkey.mod.s);
+
+// isMac === true  → parts = ["⌘", "S"]      → tooltip renders "⌘S" (no separator)
+// isMac === false → parts = ["Ctrl", "S"]   → tooltip renders "Ctrl+S" (with separator)
+```
+
+The toolbar button itself (`ToolbarBaseButton`) already does this for you: it calls `formatShortcut` internally and renders the result through the `ShortcutKbd` chip component inside a tooltip. `isMac` also determines `matchesEvent`'s runtime resolution of `mod` -- the same flag drives both what the user sees and what actually fires.
+
+## Accessibility
+
+- **`aria-keyshortcuts`.** Set automatically on the button element whenever `shortcut` is present, using the canonical `aria` string from `formatShortcut` (for example `aria-keyshortcuts="Meta+S"`). No shortcut, no attribute -- it's never rendered empty.
+- **Tooltip discovery.** A sighted user discovers the shortcut through the `<kbd>` chips shown on hover/focus of the toolbar button (`ShortcutKbd`, wrapped in `VcTooltip`). This is the only visual affordance; there is no separate "shortcuts list" surface in v1.
+- **No button, no discovery.** Both `aria-keyshortcuts` and the tooltip are properties of the rendered toolbar button -- they exist only because `shortcut` lives on an `IBladeToolbar` item that renders as a button. There is currently no way to advertise a shortcut that isn't attached to a visible button (see [Common mistakes](#common-mistakes)).
+- **Accessible name still comes from the title.** `shortcut` does not change how the button's accessible name is computed -- it still comes from the visible `title` text. Keep `title` non-empty; `shortcut` is additive, not a substitute for a labeled button.
+- **Suppressed behind a modal.** Blade shortcuts (toolbar and built-in) do not fire while a modal (`aria-modal="true"`) is open, so a shortcut never acts on a blade hidden behind it.
+
+## Common mistakes
+
+### Expecting a bare key to fire while an input is focused
+
+```typescript
+// Wrong -- assumes "e" fires globally
+registerToolbarItem({ id: "edit", title: "Edit", shortcut: { key: "e" }, clickHandler: () => edit() });
+```
+
+A shortcut with no modifier is suppressed while focus is inside a text input, textarea, select, or a `contenteditable` element -- otherwise typing the letter "e" into a form field would trigger the button. This guard only applies to bare keys; add a modifier (`hotkey.mod.e`) if the shortcut must also fire while a field is focused.
+
+```typescript
+// Correct -- a modified combination is not suppressed by input focus
+registerToolbarItem({ id: "edit", title: "Edit", shortcut: hotkey.mod.e, clickHandler: () => edit() });
+```
+
+### Two toolbar items sharing the same combination
+
+```typescript
+// Wrong -- both items declare mod+s on the same blade
+const bladeToolbar = ref<IBladeToolbar[]>([
+  { id: "save", title: "Save", shortcut: hotkey.mod.s, clickHandler: () => save() },
+  { id: "save-as", title: "Save As", shortcut: hotkey.mod.s, clickHandler: () => saveAs() },
+]);
+```
+
+The dispatcher walks a blade's toolbar items in declaration order and fires the _first_ item whose shortcut matches, then stops -- `save-as` never receives `Cmd/Ctrl+S` as long as `save` is registered ahead of it. In development, the dispatcher emits a deduplicated `console.warn` on keydown for this case (first item wins, second is named in the warning), for a toolbar item with an unrecognized `shortcut.key`, and for a toolbar item that overrides a built-in (`Esc`, `Cmd/Ctrl+\`). Production stays silent -- these are warnings, not thrown errors -- so still treat shortcut collisions within a blade's toolbar as a review-time concern: keep combinations unique per blade.
+
+```typescript
+// Correct -- distinct combinations
+const bladeToolbar = ref<IBladeToolbar[]>([
+  { id: "save", title: "Save", shortcut: hotkey.mod.s, clickHandler: () => save() },
+  { id: "save-as", title: "Save As", shortcut: hotkey.mod.shift.s, clickHandler: () => saveAs() },
+]);
+```
+
+### Expecting a button-less shortcut
+
+```typescript
+// Wrong -- there is no API to register a shortcut without a toolbar item
+onMounted(() => {
+  window.addEventListener("keydown", (e) => {
+    if (e.metaKey && e.key === "s") save();
+  });
+});
+```
+
+Rolling your own `keydown` listener bypasses `isTextInputFocused` suppression, the active-blade scoping, and the tooltip/`aria-keyshortcuts` discovery that toolbar shortcuts get for free -- and it risks double-firing alongside the framework dispatcher. In v1, every shortcut must be attached to a visible `IBladeToolbar` item; there is no headless/button-less registration path. If the action genuinely has no natural button, add one (it can be low-priority/overflowed) rather than reaching for a manual listener.
+
+## API Reference
+
+### `hotkey`
+
+A fluent builder, importable directly or via the composable. Modifier and key names are finite string unions, so a typo (`hotkey.mdo.s`) is a compile error, not a silent no-op.
+
+```typescript
+hotkey.mod.s; // { key: "s", mod: true }
+hotkey.mod.shift.s; // { key: "s", mod: true, shift: true }
+hotkey.ctrl.alt.delete; // { key: "delete", ctrl: true, alt: true }
+hotkey.escape; // { key: "escape" }
+```
+
+Chainable modifiers: `mod`, `ctrl`, `meta`, `alt`, `shift` (any order, any combination). Terminal keys: letters `a`-`z`, digits `0`-`9`, `enter`, `escape`, `tab`, `space`, `delete`, `backspace`, `arrowup`/`arrowdown`/`arrowleft`/`arrowright`, `f1`-`f12`, `backslash`, `period`, `comma`, `slash`.
+
+### `useKeyboardShortcuts()`
+
+Context-free -- no inject/lifecycle, usable in or out of a component `setup()`.
+
+#### Returns: `UseKeyboardShortcutsReturn`
+
+| Property         | Type                                                             | Description                                                               |
+| ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `hotkey`         | `HotkeyBuilder`                                                  | The same singleton as the named `hotkey` import                           |
+| `formatShortcut` | `(def: ShortcutDefinition) => { parts: string[]; aria: string }` | `isMac`-bound: formats a definition into display chips and an aria string |
+| `isMac`          | `boolean`                                                        | `true` when the user agent reports macOS/iOS                              |
+
+### `formatShortcut(def, isMac)`
+
+The standalone function (also exported directly) if you need to format for an explicit `isMac` value instead of the detected one:
+
+```typescript
+import { formatShortcut } from "@vc-shell/framework";
+
+formatShortcut({ key: "s", mod: true }, true); // { parts: ["⌘", "S"], aria: "Meta+S" }
+formatShortcut({ key: "s", mod: true }, false); // { parts: ["Ctrl", "S"], aria: "Control+S" }
+```
+
+### `ShortcutDefinition`
+
+| Property | Type      | Required | Description                                                                         |
+| -------- | --------- | -------- | ----------------------------------------------------------------------------------- |
+| `key`    | `string`  | Yes      | Single key: `"s"`, `"1"`, `"enter"`, `"escape"`, `"f2"`, `"arrowup"`, `"backslash"` |
+| `mod`    | `boolean` | No       | Platform primary modifier -- Cmd on macOS, Ctrl elsewhere                           |
+| `ctrl`   | `boolean` | No       | Literal Ctrl, regardless of platform                                                |
+| `meta`   | `boolean` | No       | Literal Cmd/Win key, regardless of platform                                         |
+| `alt`    | `boolean` | No       | Alt/Option                                                                          |
+| `shift`  | `boolean` | No       | Shift                                                                               |
+
+Building definitions by hand (`{ key: "s", mod: true }`) works identically to `hotkey.mod.s` -- the builder is sugar over this shape, useful when a definition needs to be constructed dynamically.
+
+## Related
+
+- [useToolbar](../useToolbar/) -- registers the toolbar items that carry `shortcut`; see its `IBladeToolbar`/`IToolbarItem` reference for the full item shape
+- [Blade Navigation Composables](../../blade-navigation/) -- the blade stack that scopes shortcut dispatch to the active blade and hosts the two built-in shortcuts
+- `IBladeToolbar` in [Core types](../../types/) -- the `shortcut?: ShortcutDefinition` field lives here

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

@@ -0,0 +1,151 @@
+---
+title: useLatestRequest
+category: composables
+group: utilities
+---
+
+# useLatestRequest
+
+Latest-wins sequencing for overlapping async work: lets a caller drop a response
+that a newer request already superseded.
+
+`useAsync` covers loading state, error state and error notifications, but it has
+no notion of a superseded call — a slow earlier response can overwrite a newer
+one. This composable fills that gap.
+
+## When to Use
+
+- A search field that fires a request per keystroke, where the slowest response must not win
+- A master/detail pair, where clicking row A then row B must not leave A's details on screen
+- Any load that can still be in flight when its blade closes
+- When NOT to use: for a single request with no concurrent sibling — plain `useAsync` is enough
+
+!!! note "Discards, does not cancel"
+The superseded request still completes; its result is thrown away. The generated
+API clients build their own `RequestInit` and accept no `AbortSignal`, so there
+is nothing to cancel through. Aborting would additionally save the round trip and
+belongs with a client that takes a signal.
+
+## Quick Start
+
+```typescript
+import { useLatestRequest } from "@vc-shell/framework";
+
+const search = useLatestRequest();
+const items = ref([]);
+
+async function load(criteria) {
+  const result = await search.latest(client.search(criteria));
+  if (!result) return; // a newer search already won
+  items.value = result;
+}
+```
+
+`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.
+
+!!! 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                                                                       |
+| ------------ | ----------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `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()`        |
+| `complete`  | `() => void`    | Marks this request finished. Idempotent; only the current request clears `pending` |
+
+## Features
+
+### `pending` tracks the newest request only
+
+A superseded request finishing does **not** clear `pending` — the newer one is
+still running, and clearing there would hide the spinner while the screen is
+still waiting for data.
+
+### Automatic disposal
+
+When called inside a component or effect scope, the tracker disposes itself when
+that scope stops, so a response landing after its blade closed can never write
+into a dead scope. Call `dispose()` by hand only outside a scope.
+
+## Recipes
+
+### Driving a spinner
+
+```typescript
+const details = useLatestRequest();
+// `pending` is a ref, so watch it, render it, or hand it to useLoading.
+const loading = details.pending;
+```
+
+### Dropping a request on selection change
+
+```typescript
+watch(selectedId, () => {
+  // Nothing new starts yet; whatever is in flight stops being current.
+  details.invalidate();
+});
+```
+
+## Common Mistakes
+
+**Wrong: checking before the await**
+
+```typescript
+const request = search.begin();
+if (!request.isCurrent()) return; // always true here — nothing has superseded it yet
+const result = await client.search(criteria);
+items.value = result; // still overwrites newer data
+```
+
+**Right: checking after**
+
+```typescript
+const request = search.begin();
+const result = await client.search(criteria);
+if (!request.isCurrent()) return;
+items.value = result;
+```
+
+**Wrong: completing only on success**
+
+```typescript
+const request = search.begin();
+const result = await client.search(criteria); // throws → pending stays true forever
+request.complete();
+```
+
+**Right: completing in `finally`**
+
+```typescript
+const request = search.begin();
+try {
+  const result = await client.search(criteria);
+  if (!request.isCurrent()) return;
+  items.value = result;
+} finally {
+  request.complete();
+}
+```
+
+## Related
+
+- [useAsync](./useAsync.md) — loading state, error state and error notifications for a single call
+- [useLoading](./useLoading.md) — aggregates several loading flags

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/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