@vc-shell/vc-app-skill 2.5.0 → 2.6.0-pr370.de147ea

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.5.0",
+  "version": "2.6.0-pr370.de147ea",
   "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

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 1919c06af on 2026-09-22T14:57:56.467Z

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/useKeyboardNavigation/useKeyboardNavigation.docs.md

@@ -71,13 +71,13 @@ function openMenu() {
 
 ### Parameters (Options Object)
 
-| Parameter           | Type                        | Default            | Description                                                                                                      |
-| ------------------- | --------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| `containerSelector` | `string`                    | `'[role="menu"]'`  | CSS selector to auto-find the container on mount. Set to empty string to disable auto-attach.                    |
-| `itemSelector`      | `string`                    | `'[tabindex="0"]'` | CSS selector for focusable items inside the container.                                                           |
-| `onEnter`           | `(el: HTMLElement) => void` | `undefined`        | Called when Enter or Space is pressed on a focused item. Falls back to `el.click()` if not provided.             |
-| `onEscape`          | `() => void`                | `undefined`        | Called when Escape is pressed. Typically used to close the menu or popover.                                      |
-| `loop`              | `boolean`                   | `true`             | When `true`, pressing ArrowDown on the last item wraps to the first, and ArrowUp on the first wraps to the last. |
+| Parameter           | Type                        | Default            | Description                                                                                                           |
+| ------------------- | --------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `containerSelector` | `string`                    | `'[role="menu"]'`  | CSS selector to auto-find the container on mount. Set to empty string to disable auto-attach.                         |
+| `itemSelector`      | `string`                    | `'[tabindex="0"]'` | CSS selector for focusable items inside the container.                                                                |
+| `onEnter`           | `(el: HTMLElement) => void` | `undefined`        | Called when Enter or Space is pressed on a focused item. Falls back to `el.click()` if not provided.                  |
+| `onEscape`          | `() => void`                | `undefined`        | Called when Escape is pressed, and makes the composable consume the key. Typically used to close the menu or popover. |
+| `loop`              | `boolean`                   | `true`             | When `true`, pressing ArrowDown on the last item wraps to the first, and ArrowUp on the first wraps to the last.      |
 
 ### Returns
 
@@ -101,7 +101,7 @@ The composable listens for `keydown` events on the container element and handles
 - **ArrowDown / Tab**: Move focus to the next item (`focusNextElement`)
 - **ArrowUp / Shift+Tab**: Move focus to the previous item (`focusPreviousElement`)
 - **Enter / Space**: Activate the focused item (calls `onEnter` callback, or `el.click()`)
-- **Escape**: Call `onEscape` callback
+- **Escape**: Call `onEscape` callback. When a callback is given the event is consumed (`preventDefault` + `stopPropagation`), so a sidebar or dialog listening on `document` does not also close behind the overlay. With no `onEscape`, the key passes through untouched.
 
 On each key event, the composable re-queries the container for matching items (`itemSelector`), so it naturally handles dynamic lists where items are added or removed. The focused index is validated against the current item count before every operation to prevent stale-index bugs.
 

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/useSlowNetworkDetection/useSlowNetworkDetection.docs.md

@@ -7,15 +7,17 @@ internal: true
 
 # 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`.
+Detects slow network conditions and publishes them as the `vc-slow-network` class on `<html>`, which the framework renders as a 2px sweep along the top edge of the viewport. 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 idempotent API requests that have been pending for more than 10 seconds. The class is removed with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the class is dropped in favor of the offline notification from `useConnectionStatus`.
+
+A slow network is a state, not an event, so it is never announced as a toast: a dismissable one reappears on every action that outruns the threshold, and a sticky one sits on the screen for the whole session on a 2g connection (VCST-6045).
 
 Like `useConnectionStatus`, this is a module-level singleton — calling it from multiple components shares the same state and listeners.
 
 ## When to Use
 
 - Reactively check `isSlowNetwork` to show skeleton loaders, disable auto-refresh, or display inline warnings
-- The notification is automatic — no extra code needed beyond calling the composable once at app startup (already done in `framework/index.ts`)
-- Use `trackRequest` / `untrackRequest` only if you have custom fetch logic outside the standard interceptor (the built-in fetch interceptor already tracks all `/api/*` requests)
+- The `vc-slow-network` class is automatic — no extra code needed beyond calling the composable once at app startup (already done in `framework/index.ts`)
+- Use `trackRequest` / `untrackRequest` only if you have custom fetch logic outside the standard interceptor (the built-in fetch interceptor already tracks idempotent `/api/*` requests)
 - When NOT to use: for offline detection (use `useConnectionStatus` instead) or for measuring exact latency/bandwidth
 
 ## Quick Start
@@ -61,11 +63,12 @@ const { isSlowNetwork } = useSlowNetworkDetection();
 
 These are module-private `const` declarations, not exported symbols — do not `import` them. They document the thresholds baked into the composable.
 
-| Name                        | Value               | Purpose                                             |
-| --------------------------- | ------------------- | --------------------------------------------------- |
-| `SLOW_REQUEST_THRESHOLD_MS` | `10000`             | Time before a pending request is considered slow    |
-| `DISMISS_DELAY_MS`          | `3000`              | Delay before hiding the notification after recovery |
-| `SLOW_EFFECTIVE_TYPES`      | `["slow-2g", "2g"]` | Connection types flagged as slow                    |
+| Name                        | Value               | Purpose                                          |
+| --------------------------- | ------------------- | ------------------------------------------------ |
+| `SLOW_REQUEST_THRESHOLD_MS` | `10000`             | Time before a pending request is considered slow |
+| `DISMISS_DELAY_MS`          | `3000`              | Delay before dropping the class after recovery   |
+| `SLOW_EFFECTIVE_TYPES`      | `["slow-2g", "2g"]` | Connection types flagged as slow                 |
+| `SLOW_NETWORK_CLASS`        | `"vc-slow-network"` | Class the state is published as, on `<html>`     |
 
 ## How It Works
 
@@ -75,15 +78,15 @@ On first call, the composable checks `navigator.connection.effectiveType` (Netwo
 
 ### Channel 2: Request timers (reactive)
 
-The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every `/api/*` request and `untrackRequest(id)` in the `finally` block. Each tracked request gets a 10-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
+The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every idempotent `/api/*` request (GET and HEAD) and `untrackRequest(id)` in the `finally` block. An upload or any other mutation is left out: its duration is the operator's uplink, not a stalled server, and a large file would otherwise claim the network is slow every time. Each tracked request gets a 10-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
 
-### Notification lifecycle
+### Class lifecycle
 
-1. `isSlowNetwork` becomes `true` → show `notification.warning` (deduplicated by fixed ID, persists until removed)
-2. `isSlowNetwork` becomes `false` → start a 3-second dismiss timer
-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
+1. `isSlowNetwork` becomes `true` → add `vc-slow-network` to `<html>`, and the bar appears
+2. `isSlowNetwork` becomes `false` → start a 3-second removal timer
+3. If `isSlowNetwork` goes back to `true` within those 3 seconds → cancel removal, the class stays
+4. If the browser goes offline → remove the class at once (the offline notification takes over)
+5. If the browser comes back online and `isSlowNetwork` is still `true` → add it again
 <!-- internal:end -->
 
 ## Recipe: Custom Slow-Network Behavior in a Blade
@@ -131,8 +134,9 @@ async function fetchFromExternalApi(url: string) {
 ## Tips
 
 - **Singleton by design.** Multiple calls to `useSlowNetworkDetection()` share the same state. No overhead from calling it in many components.
-- **The notification cannot stack.** It uses a fixed `notificationId`, so even if multiple requests become slow simultaneously, only one notification is shown.
-- **The 3-second dismiss delay prevents flicker.** Without it, a burst of requests completing one-by-one would cause the notification to flash on and off rapidly.
+- **The state cannot stack.** A class is present or it is not, so concurrent slow requests read as one state.
+- **The 3-second removal delay prevents flicker.** Without it, a burst of requests completing one-by-one would toggle the class on and off rapidly.
+- **The bar lives in one CSS rule.** `framework/assets/styles/index.scss` draws it next to the `html.vc-offline` rule, so an app can restyle or suppress it without touching the composable. Under `prefers-reduced-motion` it becomes a static line.
 - **`navigator.connection` has limited support.** Only Chromium-based browsers support it. Firefox and Safari users will only get the request-timer channel, which is still effective.
 - **The composable does not block requests.** Unlike the offline guard in the interceptor, slow-network detection is purely informational — it never prevents or delays a fetch.
 
@@ -171,4 +175,4 @@ trackRequest("my-request-2");
 
 - [`useConnectionStatus`](../useConnectionStatus/useConnectionStatus.docs.md) — offline detection (binary online/offline)
 - [`registerInterceptors`](https://github.com/VirtoCommerce/vc-shell/blob/main/framework/core/interceptors/index.ts) — the fetch wrapper that calls `trackRequest`/`untrackRequest`
-- `notification` from `@core/notifications/notification` — the notification system used to display the warning
+- `framework/assets/styles/index.scss` — the top-edge sweep this class renders as, alongside the `html.vc-offline` rule

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-color-input/vc-color-input.docs.md

@@ -50,15 +50,16 @@ const color = ref<string | null>(null);
 
 ## Key Props
 
-| Prop                     | Type                   | Default     | Description                                              |
-| ------------------------ | ---------------------- | ----------- | -------------------------------------------------------- |
-| `modelValue`             | `string \| null`       | `undefined` | Color value via `v-model` (hex string or CSS color name) |
-| `label`                  | `string`               | --          | Label text above the field                               |
-| `placeholder`            | `string`               | --          | Placeholder text                                         |
-| `clearable`              | `boolean`              | `false`     | Shows a clear button when a value is present             |
-| `size`                   | `"default" \| "small"` | `"default"` | Field height variant                                     |
-| `error` / `errorMessage` | `boolean` / `string`   | --          | Error styling and validation message                     |
-| `disabled`               | `boolean`              | `false`     | Disables the input and color picker                      |
+| Prop                     | Type                   | Default     | Description                                                            |
+| ------------------------ | ---------------------- | ----------- | ---------------------------------------------------------------------- |
+| `modelValue`             | `string \| null`       | `undefined` | Color value via `v-model` (hex string or CSS color name)               |
+| `label`                  | `string`               | --          | Label text above the field                                             |
+| `ariaLabel`              | `string`               | --          | Accessible name for the text input when no visible `label` is provided |
+| `placeholder`            | `string`               | --          | Placeholder text                                                       |
+| `clearable`              | `boolean`              | `false`     | Shows a clear button when a value is present                           |
+| `size`                   | `"default" \| "small"` | `"default"` | Field height variant                                                   |
+| `error` / `errorMessage` | `boolean` / `string`   | --          | Error styling and validation message                                   |
+| `disabled`               | `boolean`              | `false`     | Disables the input and color picker                                    |
 
 ## Events
 

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

@@ -294,26 +294,27 @@ const date = ref<Date | null>(new Date("2025-01-15"));
 
 ## Props
 
-| Prop                | Type                         | Default          | Description                                                  |
-| ------------------- | ---------------------------- | ---------------- | ------------------------------------------------------------ |
-| `modelValue`        | `Date \| string \| null`     | `undefined`      | Bound value via `v-model`                                    |
-| `type`              | `"date" \| "datetime-local"` | `"date"`         | Date only or date + time mode                                |
-| `label`             | `string`                     | --               | Label text above the field                                   |
-| `placeholder`       | `string`                     | auto (localized) | Placeholder text; auto-generated from locale if not provided |
-| `hint`              | `string`                     | --               | Helper text below the field                                  |
-| `tooltip`           | `string`                     | --               | Tooltip on the label info icon                               |
-| `clearable`         | `boolean`                    | `false`          | Shows a clear button when a date is selected                 |
-| `loading`           | `boolean`                    | `false`          | Shows a spinning loader icon                                 |
-| `size`              | `"default" \| "small"`       | `"default"`      | Field height variant                                         |
-| `required`          | `boolean`                    | `false`          | Shows a required indicator                                   |
-| `error`             | `boolean`                    | `false`          | Enables error styling                                        |
-| `errorMessage`      | `string`                     | --               | Error message below the field                                |
-| `disabled`          | `boolean`                    | `false`          | Disables the date picker                                     |
-| `autofocus`         | `boolean`                    | `false`          | Focus the field on mount                                     |
-| `name`              | `string`                     | `"Field"`        | HTML name attribute                                          |
-| `multilanguage`     | `boolean`                    | `false`          | Shows language badge on the label                            |
-| `currentLanguage`   | `string`                     | --               | Language code for the badge                                  |
-| `datePickerOptions` | `VueDatePickerProps`         | --               | Pass-through options to VueDatePicker                        |
+| Prop                | Type                         | Default          | Description                                                                                                                     |
+| ------------------- | ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `modelValue`        | `Date \| string \| null`     | `undefined`      | Bound value via `v-model`                                                                                                       |
+| `type`              | `"date" \| "datetime-local"` | `"date"`         | Date only or date + time mode                                                                                                   |
+| `label`             | `string`                     | --               | Label text above the field                                                                                                      |
+| `ariaLabel`         | `string`                     | --               | Accessible name for the date input when no visible `label` is provided; applied through the library's `ariaLabels.input` option |
+| `placeholder`       | `string`                     | auto (localized) | Placeholder text; auto-generated from locale if not provided                                                                    |
+| `hint`              | `string`                     | --               | Helper text below the field                                                                                                     |
+| `tooltip`           | `string`                     | --               | Tooltip on the label info icon                                                                                                  |
+| `clearable`         | `boolean`                    | `false`          | Shows a clear button when a date is selected                                                                                    |
+| `loading`           | `boolean`                    | `false`          | Shows a spinning loader icon                                                                                                    |
+| `size`              | `"default" \| "small"`       | `"default"`      | Field height variant                                                                                                            |
+| `required`          | `boolean`                    | `false`          | Shows a required indicator                                                                                                      |
+| `error`             | `boolean`                    | `false`          | Enables error styling                                                                                                           |
+| `errorMessage`      | `string`                     | --               | Error message below the field                                                                                                   |
+| `disabled`          | `boolean`                    | `false`          | Disables the date picker                                                                                                        |
+| `autofocus`         | `boolean`                    | `false`          | Focus the field on mount                                                                                                        |
+| `name`              | `string`                     | `"Field"`        | HTML name attribute                                                                                                             |
+| `multilanguage`     | `boolean`                    | `false`          | Shows language badge on the label                                                                                               |
+| `currentLanguage`   | `string`                     | --               | Language code for the badge                                                                                                     |
+| `datePickerOptions` | `VueDatePickerProps`         | --               | Pass-through options to VueDatePicker                                                                                           |
 
 ## Events
 

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

@@ -671,32 +671,33 @@ VcInput blocks the minus key for both `number` and `integer` types. If you need
 
 ### Props
 
-| Prop                | Type                                                                                                                            | Default     | Description                                                                                     |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
-| `modelValue`        | `string \| number \| Date \| null`                                                                                              | `undefined` | Bound value via `v-model`                                                                       |
-| `type`              | `"text" \| "password" \| "email" \| "tel" \| "url" \| "time" \| "number" \| "integer" \| "date" \| "datetime-local" \| "color"` | `"text"`    | Input type. `date`/`datetime-local` delegate to VcDatePicker; `color` delegates to VcColorInput |
-| `label`             | `string`                                                                                                                        | --          | Label text displayed above the field                                                            |
-| `placeholder`       | `string`                                                                                                                        | --          | Placeholder text inside the field                                                               |
-| `hint`              | `string`                                                                                                                        | --          | Help text displayed below the field                                                             |
-| `tooltip`           | `string`                                                                                                                        | --          | Tooltip text shown on hover next to the label                                                   |
-| `prefix`            | `string`                                                                                                                        | --          | Static text rendered before the input value                                                     |
-| `suffix`            | `string`                                                                                                                        | --          | Static text rendered after the input value                                                      |
-| `name`              | `string`                                                                                                                        | `"Field"`   | HTML `name` attribute on the native input                                                       |
-| `clearable`         | `boolean`                                                                                                                       | `false`     | Shows a clear (x) button when the field has a value                                             |
-| `disabled`          | `boolean`                                                                                                                       | `false`     | Disables the input (also inherits from `VcInputGroup` context)                                  |
-| `required`          | `boolean`                                                                                                                       | `false`     | Adds a red asterisk to the label (visual only, no validation)                                   |
-| `loading`           | `boolean`                                                                                                                       | `false`     | Shows a spinning loader icon inside the field                                                   |
-| `autofocus`         | `boolean`                                                                                                                       | `false`     | Auto-focuses the input on mount                                                                 |
-| `autocomplete`      | `string`                                                                                                                        | --          | Autofill hint set on the native input (e.g. `"username"`, `"current-password"`)                 |
-| `error`             | `boolean`                                                                                                                       | `false`     | Activates error styling (red border and ring)                                                   |
-| `errorMessage`      | `string`                                                                                                                        | --          | Error text shown below the field; also activates error styling when truthy                      |
-| `debounce`          | `string \| number`                                                                                                              | --          | Delay in ms before emitting model updates                                                       |
-| `maxlength`         | `string \| number`                                                                                                              | `"1024"`    | Maximum character length                                                                        |
-| `step`              | `string`                                                                                                                        | `"1"`       | Step granularity for number inputs                                                              |
-| `size`              | `"default" \| "small"`                                                                                                          | `"default"` | Field height variant (36px / 32px)                                                              |
-| `multilanguage`     | `boolean`                                                                                                                       | `false`     | Shows a language indicator badge on the label                                                   |
-| `currentLanguage`   | `string`                                                                                                                        | --          | Language code to display in the multilanguage badge                                             |
-| `datePickerOptions` | `VueDatePickerProps`                                                                                                            | --          | Options forwarded to VcDatePicker (only when `type` is `date` or `datetime-local`)              |
+| Prop                | Type                                                                                                                            | Default     | Description                                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
+| `modelValue`        | `string \| number \| Date \| null`                                                                                              | `undefined` | Bound value via `v-model`                                                                                            |
+| `type`              | `"text" \| "password" \| "email" \| "tel" \| "url" \| "time" \| "number" \| "integer" \| "date" \| "datetime-local" \| "color"` | `"text"`    | Input type. `date`/`datetime-local` delegate to VcDatePicker; `color` delegates to VcColorInput                      |
+| `label`             | `string`                                                                                                                        | --          | Label text displayed above the field                                                                                 |
+| `placeholder`       | `string`                                                                                                                        | --          | Placeholder text inside the field                                                                                    |
+| `hint`              | `string`                                                                                                                        | --          | Help text displayed below the field                                                                                  |
+| `tooltip`           | `string`                                                                                                                        | --          | Tooltip text shown on hover next to the label                                                                        |
+| `prefix`            | `string`                                                                                                                        | --          | Static text rendered before the input value                                                                          |
+| `suffix`            | `string`                                                                                                                        | --          | Static text rendered after the input value                                                                           |
+| `name`              | `string`                                                                                                                        | `"Field"`   | HTML `name` attribute on the native input                                                                            |
+| `clearable`         | `boolean`                                                                                                                       | `false`     | Shows a clear (x) button when the field has a value                                                                  |
+| `disabled`          | `boolean`                                                                                                                       | `false`     | Disables the input (also inherits from `VcInputGroup` context)                                                       |
+| `required`          | `boolean`                                                                                                                       | `false`     | Adds a red asterisk to the label (visual only, no validation)                                                        |
+| `loading`           | `boolean`                                                                                                                       | `false`     | Shows a spinning loader icon inside the field                                                                        |
+| `autofocus`         | `boolean`                                                                                                                       | `false`     | Auto-focuses the input on mount                                                                                      |
+| `autocomplete`      | `string`                                                                                                                        | --          | Autofill hint set on the native input (e.g. `"username"`, `"current-password"`)                                      |
+| `ariaLabel`         | `string`                                                                                                                        | --          | Accessible name used when no visible `label` is provided; forwarded to the delegated date picker and color input too |
+| `error`             | `boolean`                                                                                                                       | `false`     | Activates error styling (red border and ring)                                                                        |
+| `errorMessage`      | `string`                                                                                                                        | --          | Error text shown below the field; also activates error styling when truthy                                           |
+| `debounce`          | `string \| number`                                                                                                              | --          | Delay in ms before emitting model updates                                                                            |
+| `maxlength`         | `string \| number`                                                                                                              | `"1024"`    | Maximum character length                                                                                             |
+| `step`              | `string`                                                                                                                        | `"1"`       | Step granularity for number inputs                                                                                   |
+| `size`              | `"default" \| "small"`                                                                                                          | `"default"` | Field height variant (36px / 32px)                                                                                   |
+| `multilanguage`     | `boolean`                                                                                                                       | `false`     | Shows a language indicator badge on the label                                                                        |
+| `currentLanguage`   | `string`                                                                                                                        | --          | Language code to display in the multilanguage badge                                                                  |
+| `datePickerOptions` | `VueDatePickerProps`                                                                                                            | --          | Options forwarded to VcDatePicker (only when `type` is `date` or `datetime-local`)                                   |
 
 ### Events
 

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

@@ -268,6 +268,7 @@ Replace the default dropdown toggle with a custom element using the `button` slo
 | `name`            | `string`                                                                                                             | --        | HTML name attribute for the input                                                 |
 | `multilanguage`   | `boolean`                                                                                                            | `false`   | Enable multilanguage editing (forwarded to VcSelect)                              |
 | `currentLanguage` | `string`                                                                                                             | --        | Active language for multilanguage mode (forwarded to VcSelect)                    |
+| `ariaLabel`       | `string`                                                                                                             | --        | Accessible name for the value input when no visible `label` is provided           |
 
 ## Events
 

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/molecules/vc-rating/vc-rating.docs.md

@@ -234,20 +234,23 @@ Use the `"star-and-text"` or `"text"` variant in table cell slots for a compact
 
 ## Props
 
-| Prop          | Type                                   | Default   | Description                              |
-| ------------- | -------------------------------------- | --------- | ---------------------------------------- |
-| `modelValue`  | `number`                               | --        | Current rating value to display          |
-| `max`         | `number`                               | `5`       | Maximum rating value (defines the scale) |
-| `variant`     | `"stars" \| "star-and-text" \| "text"` | `"stars"` | Display variant                          |
-| `label`       | `string`                               | --        | Field label text above the rating        |
-| `tooltip`     | `string`                               | --        | Tooltip shown on the label               |
-| `placeholder` | `string`                               | --        | Text shown when `modelValue` is falsy    |
+| Prop           | Type                                   | Default   | Description                                                             |
+| -------------- | -------------------------------------- | --------- | ----------------------------------------------------------------------- |
+| `modelValue`   | `number`                               | --        | Current rating value to display                                         |
+| `max`          | `number`                               | `5`       | Maximum rating value (defines the scale)                                |
+| `variant`      | `"stars" \| "star-and-text" \| "text"` | `"stars"` | Display variant                                                         |
+| `label`        | `string`                               | --        | Field label text above the rating                                       |
+| `tooltip`      | `string`                               | --        | Tooltip shown on the label                                              |
+| `placeholder`  | `string`                               | --        | Text shown when `modelValue` is falsy                                   |
+| `error`        | `boolean`                              | --        | Marks the field invalid without a message                               |
+| `errorMessage` | `string`                               | --        | Validation message shown below the rating; also marks the field invalid |
 
 ## Slots
 
-| Slot      | Scope | Description                                                                            |
-| --------- | ----- | -------------------------------------------------------------------------------------- |
-| `details` | --    | Additional content below the rating (available in `star-and-text` and `text` variants) |
+| Slot      | Scope | Description                                                                                                                             |
+| --------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `details` | --    | Additional content below the rating (available in `star-and-text` and `text` variants)                                                  |
+| `error`   | --    | Replaces the default validation message element. Keep the slotted element's `id`, or the control's `aria-describedby` points at nothing |
 
 ## CSS Variables
 
@@ -266,6 +269,8 @@ Use the `"star-and-text"` or `"text"` variant in table cell slots for a compact
 - When no value is present, the `aria-label` falls back to the placeholder text or "No rating".
 - The label is rendered via `VcLabel` with optional tooltip, maintaining consistent label semantics.
 - Star icons are decorative and do not receive focus since the component is display-only.
+- A validation message is rendered below the rating and referenced from the control through `aria-describedby`, so a screen reader is told what is wrong rather than only that something is.
+- Invalid state comes from `useFormField`, so it reflects a surrounding `VcInputGroup` as well as the component's own `error` / `errorMessage`.
 
 ## Related Components
 

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

@@ -251,6 +251,7 @@ const description = ref<string>("");
 | `name`            | `string`  | `"Field"`   | Field name used for validation/id generation (not applied as an HTML name attribute on the textarea) |
 | `multilanguage`   | `boolean` | `false`     | Shows language badge on the label                                                                    |
 | `currentLanguage` | `string`  | --          | Language code displayed in the badge                                                                 |
+| `ariaLabel`       | `string`  | --          | Accessible name used when no visible `label` is provided                                             |
 
 ## Events
 

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