@vc-shell/vc-app-skill 2.0.3 → 2.0.4-pr228.1e79eae

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## [2.0.4](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.3...v2.0.4) (2026-05-18)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
 ## [2.0.3](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.2...v2.0.3) (2026-04-30)
 
 **Note:** Version bump only for package @vc-shell/vc-app-skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.3",
+  "version": "2.0.4-pr228.1e79eae",
   "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.0.3
+2.0.4

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit d658f5b4c on 2026-04-30T07:59:28.391Z
+Synced from framework at commit d15c26a1e on 2026-05-18T12:39:15.446Z

package/runtime/knowledge/docs/core/api/platform.docs.md

@@ -1,3 +1,10 @@
+---
+title: Platform Client
+category: reference
+group: api
+slug: platform-client
+---
+
 # Platform API Client
 
 Auto-generated TypeScript API client for the VirtoCommerce Platform REST API. Generated by NSwag from the platform's Swagger/OpenAPI specification.

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

@@ -1,3 +1,9 @@
+---
+title: Blade Navigation Composables
+category: composables
+group: blade-navigation
+---
+
 # Blade Navigation Composables
 
 The core composables that implement the blade navigation system -- the stacked-panel UI paradigm used throughout VirtoCommerce admin applications.
@@ -14,7 +20,9 @@ Blade navigation manages an ordered stack of blade descriptors (plain data objec
 
 - Build or extend the blade navigation infrastructure itself (plugin authors, framework internals)
 - Need direct access to the blade stack state machine (`useBladeStack`) or inter-blade messaging (`useBladeMessaging`)
-- When NOT to use: for everyday blade operations in modules -- prefer `useBlade()` from `core/composables/useBlade/`, which wraps these low-level composables with a cleaner, context-aware API
+- When NOT to use: for everyday blade operations in modules -- prefer `useBlade()`, which wraps these low-level composables with a cleaner, context-aware API
+
+<!-- internal:start -->
 
 ## Exports
 
@@ -24,6 +32,8 @@ export { createBladeStack, useBladeStack } from "./useBladeStack";
 export { createBladeMessaging, useBladeMessaging } from "./useBladeMessaging";
 ```
 
+<!-- internal:end -->
+
 ## useBladeStack
 
 The blade stack state machine. Manages an ordered array of `BladeDescriptor` objects.
@@ -139,7 +149,7 @@ The plain data object stored in the stack for each blade:
 
 ## Tips
 
-- Prefer `useBlade()` / `useBladeContext()` (from `core/composables/useBlade/`) for new code -- they provide a cleaner API than the legacy adapter.
+- Prefer `useBlade()` / `useBladeContext()` for new code -- they provide a cleaner API than the legacy adapter.
 - Close guards return `true` to PREVENT closing (opposite of the legacy convention where `false` prevented closing). The adapter handles the inversion.
 - `replaceCurrentBlade` destroys the current blade and creates a new one at the same index with the same `parentId`. Use `coverCurrentBlade` to hide instead of destroy — the covering blade's `callParent` reaches the hidden blade's exposed methods.
 - URL sync only updates the address bar for blades that have a `url` segment. Third-level detail panels without URLs leave the previous URL intact.
@@ -147,6 +157,12 @@ The plain data object stored in the stack for each blade:
 
 ## Related
 
+- [`useBlade`](../composables/useBlade/) -- recommended API for everyday blade operations
+- [`useBladeContext`](../composables/bladeContext/) -- share reactive blade data with descendant components
+
+<!-- internal:start -->
+
 - `framework/core/composables/useBlade/` -- `useBlade()`, `useBladeContext()` (new API)
-- `framework/shared/components/blade-navigation/plugin-v2.ts` -- plugin that creates and provides the stack/messaging
-- `framework/shared/components/blade-navigation/types.ts` -- `BladeDescriptor`, `IBladeStack`, `IBladeMessaging`
+- `framework/shell/_internal/blade-nav/plugin-v2.ts` -- plugin that creates and provides the stack/messaging
+- `framework/core/blade-navigation/types/index.ts` -- `BladeDescriptor`, `IBladeStack`, `IBladeMessaging`
+<!-- internal:end -->

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

@@ -1,3 +1,10 @@
+---
+title: useBladeContext
+category: composables
+group: blade-navigation
+slug: useBladeContext
+---
+
 # useBladeContext (defineBladeContext / injectBladeContext)
 
 Exposes blade-level data to descendant widgets, extensions, and nested components via Vue's provide/inject mechanism. This pair of functions eliminates the need for prop drilling when child widgets or extension points need access to the parent blade's entity data, loading flags, or other shared state.
@@ -96,7 +103,7 @@ defineBladeContext(
 
 - **Automatic ref unwrapping**: `defineBladeContext` shallow-unwraps all ref/computed values in the provided object. Consumers get plain values directly (`ctx.value.item` instead of `ctx.value.item.value`). This works reactively — when the source ref changes, the context updates automatically.
 - **Reactivity**: The provided context is always wrapped in a `computed`, so consumers receive a `ComputedRef` regardless of whether the provider passed a plain object, a ref, or a getter. Changes propagate automatically.
-- **Injection key**: Uses `BladeContextKey` from `framework/injection-keys.ts`. This is a framework-level Symbol, so there is no risk of key collision with application code.
+- **Injection key**: Uses `BladeContextKey` (a framework-level Symbol), so there is no risk of key collision with application code.
 - **Error handling**: `injectBladeContext` throws an `InjectionError` with a descriptive message if called outside a blade component tree. This fails fast during development rather than silently returning `undefined`.
 - **Scope**: The context is scoped to the Vue component subtree. Each blade in the stack has its own context, so nested blades do not leak data upward or sideways.
 
@@ -108,6 +115,11 @@ defineBladeContext(
 
 ## Related
 
+- [`useBladeWidgets`](../useBladeWidgets/) -- widgets that consume blade context
+- [`useBlade`](../useBlade/) -- cross-blade communication via `callParent` / `exposeToChildren`
+
+<!-- internal:start -->
+
 - `BladeContextKey` in `framework/injection-keys.ts`
-- `useBladeWidgets` -- widgets that consume blade context
-- `useBladeStack` -- manages the blade navigation stack
+- `useBladeStack` in `framework/core/blade-navigation/` -- manages the blade navigation stack
+<!-- internal:end -->

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

@@ -1,7 +1,16 @@
+---
+title: useApiClient
+category: composables
+group: data
+---
+
 # useApiClient
 
 Creates a typed API client instance for communicating with VirtoCommerce platform APIs. The composable accepts a generated client class constructor and returns an async factory function that produces a configured, authenticated client. Base URL resolution and authentication token injection are handled automatically.
 
+!!! tip "Always call getApiClient inside async functions"
+`getApiClient` is async. Never call it at the top level of `<script setup>` — always call it inside the async function you pass to `useAsync`. Storing the client in a variable outside the function gives you a stale reference when tokens rotate.
+
 ## When to Use
 
 - Instantiate a generated VirtoCommerce API client with automatic authentication and base-URL resolution
@@ -291,7 +300,7 @@ API clients are generated from Swagger/OpenAPI specs using the `@vc-shell/api-cl
 
 ## Related
 
-- [useAsync](../useAsync/) -- wraps async API calls with loading/error state management
-- [CLI API Client Generator](../../../../cli/) -- generates typed client classes from Swagger specs
-- [useToolbar](../useToolbar/) -- disable toolbar buttons during API calls using the loading ref
-- [useNotifications](../useNotifications/) -- display success/error messages after API operations
+- [`useAsync`](../useAsync/) -- wraps async API calls with loading/error state management
+- CLI API Client Generator (`@vc-shell/api-client-generator`) -- generates typed client classes from Swagger specs
+- [`useToolbar`](../useToolbar/) -- disable toolbar buttons during API calls using the loading ref
+- [`useNotifications`](../useNotifications/) -- display success/error messages after API operations

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

@@ -1,3 +1,9 @@
+---
+title: useAppBarMobileButtons
+category: composables
+group: services
+---
+
 # useAppBarMobileButtons
 
 Manages custom action buttons in the mobile app bar. Uses provide/inject to share a singleton service across the component tree. This composable gives any blade or module the ability to register, update, and remove buttons that appear in the top app bar on mobile devices. Buttons are sorted by their `order` property and can include icons, custom Vue components, click handlers, badges, and reactive visibility toggles. The service is scoped to the VcApp tree and automatically cleans up when the scope is disposed.
@@ -59,6 +65,8 @@ onUnmounted(() => unregister("notifications-btn"));
 | `isVisible` | `MaybeRef<boolean>`       | No       | Reactive visibility toggle. When `false`, the button is excluded from `getButtons`. Defaults to `true`. |
 | `badge`     | `MaybeRef<boolean>`       | No       | Show a small badge indicator on the button (e.g., for unread notifications).                            |
 
+<!-- internal:start -->
+
 ## Setup
 
 `provideAppBarMobileButtonsService()` must be called once in the app root (VcApp). It is idempotent -- calling it again in the same injection tree returns the existing service. Descendant components then call `useAppBarMobileButtons()` to register buttons.
@@ -70,6 +78,8 @@ import { provideAppBarMobileButtonsService } from "@vc-shell/framework";
 provideAppBarMobileButtonsService();
 ```
 
+<!-- internal:end -->
+
 ## Recipe: Filter Toggle Button That Reflects Active State
 
 ```vue

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

@@ -1,3 +1,9 @@
+---
+title: useAppBarWidget
+category: composables
+group: services
+---
+
 # useAppBarWidget
 
 Provides access to the app bar widget service for registering custom widgets (buttons, icons, dropdowns) in the application's top navigation bar. Uses Vue's provide/inject system.

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

@@ -1,3 +1,9 @@
+---
+title: useAppInsights
+category: composables
+group: utilities
+---
+
 # useAppInsights
 
 Integrates Azure Application Insights page-view tracking with Vue Router and the current user context. This composable bridges the `vue3-application-insights` plugin with the vc-shell framework by automatically enriching every page-view event with the authenticated user's ID and name, generating fresh W3C trace IDs per navigation for distributed tracing, and optionally prefixing page names with the application name (e.g., `[Vendor Portal] Dashboard`).

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

@@ -1,3 +1,9 @@
+---
+title: useAssets
+category: composables
+group: data
+---
+
 # useAssets
 
 Handles file upload, removal, and editing for `ICommonAsset` arrays (images, documents, etc.). This composable encapsulates the platform's asset storage API, handling multipart form upload with batched concurrency (max 4 simultaneous uploads), sort-order assignment, URL decoding, and immutable array operations for remove and edit. It returns a new array from every operation rather than mutating in place, which plays well with Vue's reactivity system and makes undo/redo patterns straightforward.
@@ -131,5 +137,6 @@ async function handleUpload(files: FileList) {
 
 ## Related
 
-- `ICommonAsset` type in `@core/types`
+- `ICommonAsset` -- type imported from `@vc-shell/framework`
 - `VcGallery` / `VcImageTile` -- UI components that consume asset arrays
+- [`useAssetsManager`](../useAssetsManager/) -- higher-level composable that wraps `useAssets` with two-way sync

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

@@ -1,3 +1,9 @@
+---
+title: useAssetsManager
+category: composables
+group: data
+---
+
 # useAssetsManager
 
 High-level composable for managing asset arrays (images, documents, files). Wraps upload, remove, reorder, and metadata editing operations, mutating a reactive ref directly — no manual wiring needed.
@@ -147,7 +153,12 @@ interface AssetLike {
 
 ## Related
 
-- `framework/modules/assets-manager/` — AssetsManager blade (table UI for managing assets)
-- `framework/modules/assets/` — AssetsDetails blade (single asset editing)
-- `framework/ui/components/organisms/vc-gallery/` — VcGallery component
-- `framework/core/composables/useAssets/` — deprecated low-level composable
+- `VcGallery` -- gallery component that integrates with `useAssetsManager` events
+- [`useAssets`](../useAssets/) -- lower-level composable for manual upload/remove operations
+
+<!-- internal:start -->
+
+- `framework/modules/assets-manager/` -- AssetsManager blade (table UI for managing assets)
+- `framework/modules/assets/` -- AssetsDetails blade (single asset editing)
+- `framework/ui/components/organisms/vc-gallery/` -- VcGallery component source
+<!-- internal:end -->

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

@@ -1,3 +1,12 @@
+---
+title: useAsync
+category: composables
+group: utilities
+---
+
+!!! note "Large reference"
+This page is long. Use the section headings to navigate: [Quick Start](#quick-start), [API Reference](#api-reference), [Features](#features), [Recipes](#recipes), [Common Mistakes](#common-mistakes).
+
 # useAsync
 
 Wraps an asynchronous function with reactive `loading` state, reactive `error` state, and automatic error notifications. This is the standard way to handle API calls, saves, deletes, and other async operations throughout VC-Shell applications.
@@ -400,12 +409,16 @@ const { action: save, loading: saveLoading } = useAsync(async () => saveData());
 
 ---
 
+<!-- internal:start -->
+
 ## Internals
 
 - Errors are parsed via `parseError()` into `DisplayableError` objects that have a user-friendly `message` property.
 - Toast notifications are deferred with `setTimeout(0)` and registered via `setPendingErrorNotification`. The `ErrorInterceptor` (blade-level `onErrorCaptured`) can call `cancelPendingErrorNotification` to suppress the toast when a blade error banner is shown instead.
 - The notification module is lazy-imported to avoid circular dependencies with `@core/composables`.
 
+<!-- internal:end -->
+
 ---
 
 ## Related

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

@@ -1,3 +1,9 @@
+---
+title: useBeforeUnload
+category: composables
+group: utilities
+---
+
 # useBeforeUnload
 
 Prevents the browser tab from closing when unsaved changes exist by hooking into the native `beforeunload` event. This composable is the last line of defense against accidental data loss -- it triggers the browser's built-in "Leave site?" confirmation dialog whenever the user tries to close or refresh the tab while the `modified` flag is `true`. It complements in-app guards (like blade `onBeforeClose`) by covering the case where the user bypasses the application entirely via the browser chrome.

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

@@ -1,3 +1,9 @@
+---
+title: useBlade
+category: composables
+group: blade-navigation
+---
+
 # useBlade
 
 Unified composable for blade navigation, identity, communication, guards, and error management in VC-Shell applications. This is the primary API for working with the blade navigation system -- the stacked panel paradigm (similar to Azure Portal) that drives every screen in a VC-Shell app.
@@ -644,6 +650,9 @@ function goToOrders() {
 
 ## Common Mistakes
 
+!!! warning "Blade-specific methods throw outside blade context"
+Methods like `closeSelf`, `callParent`, `onBeforeClose`, and `setError` require a blade context (i.e., must be called from inside a blade component's `<script setup>`). Calling them from a dashboard card, a toolbar handler, or a plain composable throws a descriptive runtime error. Only `openBlade` works everywhere.
+
 ### Calling blade-specific methods outside blade context
 
 ```typescript
@@ -740,6 +749,8 @@ if (param.value) {
 
 ---
 
+<!-- internal:start -->
+
 ## How It Works Under the Hood
 
 1. **Plugin setup:** `BladeNavigationPlugin` (plugin-v2) installs a `BladeStack` and `BladeMessaging` singleton and provides them via Vue's dependency injection.
@@ -747,6 +758,8 @@ if (param.value) {
 3. **Outside a blade:** `useBlade()` falls back to the singleton instances. Only `openBlade` works because it does not need a blade descriptor.
 4. **URL sync:** When blades with a `url` property are opened or closed, `useBlade()` synchronizes the browser URL via `createUrlSync`, enabling deep linking and back/forward navigation.
 
+<!-- internal:end -->
+
 ---
 
 ## Related

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

@@ -1,3 +1,9 @@
+---
+title: useBladeForm
+category: composables
+group: forms
+---
+
 # useBladeForm
 
 Unified form state management for blades. Replaces manual combination of `useForm` + `useModificationTracker` + `useBeforeUnload` + `onBeforeClose` with a single composable.
@@ -152,8 +158,8 @@ onMounted(async () => {
 
 At composable creation, `useBladeForm` takes a snapshot of `data` (the **setup-time snapshot**). When `markReady()` is called:
 
-1. `isReady` → `true` (gates `canSave` and the deep watcher)
-2. `trackerIsModified` = `!semanticEqual(data, setupTimeSnapshot)` — since data was mutated during `onMounted`, this evaluates to `true`
+1. `isReady` → `true` (gates `canSave` and subsequent edit tracking)
+2. Modification state is computed by comparing the current data to the setup-time snapshot — since data was mutated during `onMounted`, `isModified` evaluates to `true`
 3. Subsequent edits are tracked normally by the deep watcher
 
 After save, call `setBaseline()` as usual to capture the saved state as the new pristine snapshot.
@@ -164,6 +170,10 @@ After save, call `setBaseline()` as usual to capture the saved state as the new
 - Validation rules stay in template (`<Field rules="...">`).
 - `setBaseline()` must be called after data is loaded — before that, `canSave` and `isModified` are `false`.
 
+<!-- internal:start -->
+
 ## Migration
 
 See `MIGRATION_GUIDE.md` for step-by-step instructions on migrating existing modules.
+
+<!-- internal:end -->

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

@@ -1,3 +1,9 @@
+---
+title: useBladeRegistry
+category: composables
+group: blade-navigation
+---
+
 # useBladeRegistry
 
 Provides read-only access to the blade registry -- a central map of all registered blade components, their routes, and metadata.
@@ -129,7 +135,7 @@ function canAccessBlade(bladeName: string): boolean {
 
 ## Notes
 
-- The composable must be called after `createBladeRegistry()` has provided the registry via `BladeRegistryKey`. Calling it too early (e.g., outside a setup function or before app bootstrap) throws an error.
+- The composable must be called after the navigation plugin has initialized. Calling it too early (e.g., outside a setup function or before app bootstrap) throws an error.
 - `getBladeComponent()` falls back to Vue's global component registry if the blade is not found in the framework registry. This supports legacy components registered via `app.component()`.
 - The `registeredBladesMap` is a `ComputedRef` wrapping a `ReadonlyMap`, so it updates reactively when new modules are loaded.
 
@@ -147,6 +153,10 @@ if (!registration) {
 
 ## Related
 
-- [useBlade](../useBlade/) -- opens and manages blades by name
-- [Dynamic Module Loading](../../plugins/modularity/) -- registers blades during module initialization
-- `framework/injection-keys.ts` -- `BladeRegistryKey` (defined in the composable file, not in injection-keys.ts)
+- [`useBlade`](../useBlade/) -- opens and manages blades by name
+- Dynamic Module Loading -- registers blades during module initialization
+
+<!-- internal:start -->
+
+- `createBladeRegistry()` in `framework/core/composables/useBladeRegistry/index.ts` -- factory called by the navigation plugin; `BladeRegistryKey` is defined here
+<!-- internal:end -->

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

@@ -1,3 +1,10 @@
+---
+title: useBladeWidgets
+category: composables
+group: blade-navigation
+slug: useBladeWidgets
+---
+
 # useBladeWidgets / useWidgetTrigger
 
 Two composables for the widget system — one for the **blade side**, one for the **widget side**.
@@ -239,21 +246,24 @@ async function save() {
 
 ## Prerequisites
 
+!!! warning "Call site requirements"
+`useBladeWidgets` must be called inside a blade component's `<script setup>` — it requires blade context to be present. `useWidgetTrigger` must be called inside a widget component rendered by `WidgetContainer`. Calling either outside their required scope produces a runtime error or silent no-op respectively.
+
 **`useBladeWidgets`**:
 
-- Must be called inside a blade component rendered by `VcBladeSlot` (requires `BladeDescriptorKey` injection).
-- `WidgetService` must be provided in the component tree (automatically available in vc-shell apps).
+- Must be called inside a blade component's `<script setup>`.
+- Widget service must be provided in the component tree (automatically available in vc-shell apps).
 - Calling outside a blade context throws an error with a descriptive message.
 
 **`useWidgetTrigger`**:
 
-- Must be called inside a widget component rendered by `WidgetContainer` (requires `WidgetScopeKey` injection).
+- Must be called inside a widget component rendered by `WidgetContainer`.
 - If called outside a widget scope, logs a warning and does nothing (does not throw).
 
 ## Details
 
-- **Lifecycle management**: Widgets are registered in `onMounted` and unregistered in `onUnmounted`. This ensures the WidgetService always reflects the currently visible blades.
-- **Blade ID resolution**: The composable injects `BladeDescriptorKey` to determine which blade the widgets belong to. Each blade has its own isolated widget list.
+- **Lifecycle management**: Widgets are registered in `onMounted` and unregistered in `onUnmounted`. This ensures the widget service always reflects the currently visible blades.
+- **Blade ID resolution**: The composable injects the blade descriptor to determine which blade the widgets belong to. Each blade has its own isolated widget list.
 - **Trigger pattern**: The `onRefresh` callback is stored as a `trigger` on the registered widget. When `refresh(id)` or `refreshAll()` is called, the trigger is invoked. Widgets without `onRefresh` are silently skipped.
 
 ## Tips
@@ -294,8 +304,12 @@ const { refreshAll } = useBladeWidgets([]);
 
 ## Related
 
-- `defineBladeContext` / `injectBladeContext` -- expose/consume blade data in external widgets
+- [`defineBladeContext` / `injectBladeContext`](../bladeContext/) -- expose/consume blade data in external widgets
 - `registerExternalWidget` -- register a component-based widget globally for target blades
-- `WidgetService` in `@core/services/widget-service` -- underlying service
-- `WidgetScope` in `vc-blade/_internal/widgets/WidgetScope.vue` -- provides `WidgetScopeKey` to widget components
-- `VcBladeSlot` -- the blade wrapper that provides `BladeDescriptorKey`
+
+<!-- internal:start -->
+
+- `WidgetService` in `framework/core/services/widget-service/` -- underlying service
+- `WidgetScope` in `framework/ui/components/organisms/vc-blade/_internal/widgets/WidgetScope.vue` -- provides `WidgetScopeKey` to widget components
+- `VcBladeSlot` in `framework/shell/_internal/blade-nav/` -- provides `BladeDescriptorKey` to blade components
+<!-- internal:end -->

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

@@ -1,3 +1,9 @@
+---
+title: useBreadcrumbs
+category: composables
+group: ui-state
+---
+
 # useBreadcrumbs
 
 Manages a reactive breadcrumb trail for blade navigation. Supports push, remove, and automatic trail trimming on click.

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

@@ -1,3 +1,9 @@
+---
+title: useConnectionStatus
+category: composables
+group: ui-state
+---
+
 # useConnectionStatus
 
 Monitors the browser's network connectivity and shows a persistent notification when the user goes offline. This composable wraps `@vueuse/core`'s `useNetwork()` and adds framework-specific behavior: it displays a warning notification via the vc-shell notification system, applies a `vc-offline` CSS class to `<html>` for global styling hooks, and logs state changes through the framework logger. The state is a module-level singleton, so only one set of event listeners is ever created regardless of how many components call the composable.
@@ -43,6 +49,8 @@ const { isOnline } = useConnectionStatus();
 | ---------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
 | `isOnline` | `Readonly<Ref<boolean>>` | `true` when the browser has network connectivity, `false` when offline. Read-only to prevent external mutation. |
 
+<!-- internal:start -->
+
 ## How It Works
 
 On the very first call to `useConnectionStatus()`, the composable initializes a watcher on `@vueuse/core`'s `useNetwork().isOnline`. This watcher runs with `{ immediate: true }`, so the state is correct from the start. Subsequent calls skip initialization and return the same shared reactive state.
@@ -55,6 +63,8 @@ When the network drops:
 
 When connectivity is restored, the notification is removed, the CSS class is cleared, and an info message is logged.
 
+<!-- internal:end -->
+
 ## Recipe: Disabling Auto-Save While Offline
 
 ```vue

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

@@ -1,3 +1,12 @@
+---
+title: useDashboard
+category: composables
+group: services
+---
+
+!!! tip "Long page"
+Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Widget Registration](#widget-registration), [Permission-Based Visibility](#permission-based-visibility), or [API Reference](#api-reference).
+
 # useDashboard
 
 Accesses the dashboard service for registering and managing dashboard widgets. Widgets are permission-aware, support layout positioning, and can be pre-registered during module setup before the service is initialized.

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

@@ -1,3 +1,9 @@
+---
+title: useDynamicProperties
+category: composables
+group: forms
+---
+
 # useDynamicProperties
 
 Composable for managing dynamic (runtime-defined) property values with support for multilanguage, multivalue, dictionary, color, and measurement property types.

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

@@ -1,3 +1,9 @@
+---
+title: useErrorHandler
+category: composables
+group: utilities
+---
+
 # useErrorHandler
 
 Captures and normalizes errors within a component's subtree using Vue's `onErrorCaptured` hook. This composable acts as an error boundary: it catches errors thrown by any child component, normalizes them into a `DisplayableError` with a user-friendly `message` and technical `details`, automatically reports them to Application Insights with user context, and emits events so parent components can react. It also includes re-entrancy protection to prevent infinite error loops when the error display itself triggers an error.

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

@@ -1,3 +1,9 @@
+---
+title: useFunctions
+category: composables
+group: utilities
+---
+
 # useFunctions
 
 Provides lightweight utility functions for timing control: debounce, throttle, delay, and once. These are thin, dependency-free implementations that cover the most common use cases without pulling in lodash or other large utility libraries. The composable returns plain functions, not reactive wrappers, making them suitable for event handlers, API calls, and other imperative code paths where you do not need VueUse's reactive cancellation features.

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

@@ -1,3 +1,9 @@
+---
+title: useKeyboardNavigation
+category: composables
+group: ui-state
+---
+
 # useKeyboardNavigation
 
 Implements keyboard navigation (Arrow keys, Tab, Enter, Escape) within a container of focusable elements. This composable provides full WAI-ARIA-style keyboard interaction for custom menus, dropdowns, autocomplete lists, and other composite widgets that are not natively keyboard-accessible. It manages a focused-item index, handles wrap-around (looping), and automatically attaches/detaches event listeners tied to the component lifecycle.
@@ -85,6 +91,8 @@ function openMenu() {
 | `setFocusedIndex`           | `(index: number) => void`   | Set focus to a specific index. No-op if index is out of bounds.                           |
 | `getFocusedIndex`           | `() => number`              | Get the currently focused index (`-1` if no item is focused).                             |
 
+<!-- internal:start -->
+
 ## How It Works
 
 The composable listens for `keydown` events on the container element and handles:
@@ -98,6 +106,8 @@ On each key event, the composable re-queries the container for matching items (`
 
 Auto-attach happens in `onMounted`: if `containerSelector` is set and a matching element exists in the DOM, keyboard navigation is initialized automatically. Cleanup happens in `onBeforeUnmount`.
 
+<!-- internal:end -->
+
 ## Recipe: Keyboard-Navigable Autocomplete Dropdown
 
 ```vue

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

@@ -1,3 +1,9 @@
+---
+title: useLanguages
+category: composables
+group: user
+---
+
 # useLanguages
 
 Provides access to the language service for locale management: getting/setting the current locale, resolving locale tags, and fetching country flags. The service is created once via `provideLanguages()` at the framework level and shared through Vue's injection system. If called outside an injection context (e.g., during module initialization), a fallback singleton service is used so the composable never throws.

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

@@ -1,3 +1,9 @@
+---
+title: useLoading
+category: composables
+group: ui-state
+---
+
 # useLoading
 
 Aggregates multiple reactive boolean loading refs into a single computed that is `true` when any source is loading. This is a minimal utility composable -- just one line of logic -- but it solves a very common problem in blade development: when a component depends on several async data sources, you need a single flag for the loading overlay. Instead of writing `computed(() => loadingA.value || loadingB.value || loadingC.value)` in every blade, `useLoading` provides a clean, readable shorthand that scales to any number of sources.
@@ -31,6 +37,8 @@ const combinedLoading = useLoading(loadingA, loadingB, loadingC);
 | ---------------------- | ------------------------------------------------------------------------------------------------------ |
 | `ComputedRef<boolean>` | `true` if any of the input refs is `true`, `false` otherwise. Re-evaluates whenever any input changes. |
 
+<!-- internal:start -->
+
 ## How It Works
 
 The implementation is a single `computed` that calls `Array.some()` on the input refs:
@@ -41,6 +49,8 @@ computed(() => args.some((item) => item.value));
 
 Because `computed` tracks all `.value` accesses, Vue knows to re-evaluate whenever any of the input refs changes. The `some()` short-circuits on the first `true`, so it is efficient even with many inputs.
 
+<!-- internal:end -->
+
 ## Recipe: Blade with Multiple Data Sources
 
 ```vue

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

@@ -1,3 +1,10 @@
+---
+title: useMenuExpanded
+category: composables
+group: ui-state
+slug: useMenuExpanded
+---
+
 # useMenuExpanded
 
 Manages the sidebar menu expanded/collapsed and hover-expanded state with localStorage persistence. This is the low-level composable that powers the sidebar pin/unpin behavior in the vc-shell admin UI. It tracks two independent states: the permanent "pinned" state (persisted across sessions) and the transient "hover-expanded" state (active only while the user hovers over a collapsed sidebar).
@@ -65,12 +72,15 @@ const isVisuallyExpanded = computed(() => isExpanded.value || isHoverExpanded.va
 </template>
 ```
 
+<!-- internal:start -->
+
 ## Details
 
 - **Storage key scoping**: The key is scoped per application using the first URL path segment: `VC_APP_MENU_EXPANDED_{appName}`. For example, if the app is hosted at `/vendor-portal/`, the key is `VC_APP_MENU_EXPANDED_vendor-portal`. This allows multiple vc-shell apps on the same domain to maintain independent sidebar states.
 - **Hover delay**: Opening uses a 200ms debounce to prevent accidental expansion when the cursor briefly passes over the sidebar. Closing is immediate to feel responsive.
 - **Cleanup**: Pending hover timeouts are cleaned up via `onScopeDispose` to prevent memory leaks when the composable's effect scope is destroyed.
 - **Default state**: The sidebar starts pinned open (`true`) on first visit, which is the most user-friendly default for new users.
+<!-- internal:end -->
 
 ## Tips