@vc-shell/vc-app-skill 2.0.4 → 2.0.6

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [2.0.6](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.5...v2.0.6) (2026-05-25)
+
+### Features
+
+- docs-sync improvements, lint rules, and reference docs alignment (#229) ([a3ddbc2](https://github.com/VirtoCommerce/vc-shell/commit/a3ddbc29a90e55632df702f776e11bc8bc4aec67)), closes [#229](https://github.com/VirtoCommerce/vc-shell/issues/229)
+
+## [2.0.5](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.4...v2.0.5) (2026-05-25)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
 ## [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

package/README.md

@@ -22,7 +22,7 @@ The skill covers:
 ### Claude Code / Cursor / GitHub Copilot
 
 ```bash
-npx @vc-shell/vc-app-skill@alpha install
+npx @vc-shell/vc-app-skill@latest install
 ```
 
 Installs skill files into `~/.claude/vc-app-skill/` and registers the `/vc-app` slash command.
@@ -30,19 +30,19 @@ Installs skill files into `~/.claude/vc-app-skill/` and registers the `/vc-app`
 ### OpenCode
 
 ```bash
-npx @vc-shell/vc-app-skill@alpha install --runtime opencode
+npx @vc-shell/vc-app-skill@latest install --runtime opencode
 ```
 
 ### Gemini CLI
 
 ```bash
-npx @vc-shell/vc-app-skill@alpha install --runtime gemini
+npx @vc-shell/vc-app-skill@latest install --runtime gemini
 ```
 
 ### Codex
 
 ```bash
-npx @vc-shell/vc-app-skill@alpha install --runtime codex
+npx @vc-shell/vc-app-skill@latest install --runtime codex
 ```
 
 ### Verify installation
@@ -180,7 +180,7 @@ Handles topics: widgets, form management (`useBladeForm`), injection-key renames
 ## Update
 
 ```bash
-npx @vc-shell/vc-app-skill@alpha install
+npx @vc-shell/vc-app-skill@latest install
 ```
 
 Or from within your AI tool:
@@ -194,7 +194,7 @@ The installer checks the installed version against the package version and overw
 ## Uninstall
 
 ```bash
-npx @vc-shell/vc-app-skill@alpha uninstall
+npx @vc-shell/vc-app-skill@latest uninstall
 ```
 
 Removes skill files from the AI tool's configuration directory. Does not affect your application source code.
@@ -202,7 +202,7 @@ Removes skill files from the AI tool's configuration directory. Does not affect
 To uninstall for a specific runtime:
 
 ```bash
-npx @vc-shell/vc-app-skill@alpha uninstall --runtime opencode
+npx @vc-shell/vc-app-skill@latest uninstall --runtime opencode
 ```
 
 ## Architecture

package/package.json

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

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit d15c26a1e on 2026-05-18T12:39:15.446Z
+Synced from framework at commit a3ddbc29a on 2026-05-25T13:00:53.288Z

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

@@ -11,9 +11,9 @@ Auto-generated TypeScript API client for the VirtoCommerce Platform REST API. Ge
 
 ## Overview
 
-Communicating with the VirtoCommerce platform backend requires typed HTTP client classes that match the platform's REST endpoints. Rather than manually writing fetch calls or Axios requests, the framework provides auto-generated client classes that handle URL construction, request serialization, response deserialization, and authentication token injection.
+Communicating with the VirtoCommerce platform backend requires typed HTTP client classes that match the platform's REST endpoints. Rather than manually writing fetch calls or Axios requests, the framework provides auto-generated client classes that handle URL construction, request serialization, and response deserialization.
 
-Each API client class extends `AuthApiBase`, which automatically attaches the Bearer token to every request. Data model types (DTOs, Commands, Queries) are generated as **interfaces** (not classes), so they cannot be instantiated with `new` -- use object literals with type annotations instead. The clients are generated by NSwag from the platform's Swagger/OpenAPI specification and should not be edited manually -- any manual changes will be overwritten during regeneration.
+Each API client class extends `AuthApiBase`. The base class carries an `authToken` field and, when that field has a value, attaches it as a `Bearer` header through `transformOptions`. In the default `useApiClient` flow, the client is instantiated without arguments and `authToken` stays empty — same-origin API calls are authenticated by the session cookie that the browser replays automatically. Code that needs to bypass cookies (cross-origin, non-browser, manual flows) can call `setAuthToken(token)` on a client instance directly. Data model types (DTOs, Commands, Queries) are generated as **interfaces** (not classes), so they cannot be instantiated with `new` -- use object literals with type annotations instead. The clients are generated by NSwag from the platform's Swagger/OpenAPI specification and should not be edited manually -- any manual changes will be overwritten during regeneration.
 
 **File:** `platform.ts` (auto-generated, do not edit manually)
 
@@ -21,7 +21,7 @@ Each API client class extends `AuthApiBase`, which automatically attaches the Be
 
 - Call platform-level REST endpoints (security, settings, notifications, modules, dynamic properties) from typed TypeScript clients
 - Access platform DTOs (`ApplicationUser`, `PushNotification`, `Role`, `Permission`, etc.) as typed interfaces
-- Combine with `useApiClient` for automatic token management and caching
+- Combine with `useApiClient` to obtain a configured client instance through a single composable
 - When NOT to use: for domain-module APIs (orders, catalog, inventory) -- use their own generated clients instead; for third-party APIs -- use `fetch` or Axios directly
 
 ## API Clients
@@ -68,7 +68,7 @@ export class AuthApiBase {
   authToken: string;
   setAuthToken(token: string): void;
   protected getBaseUrl(defaultUrl: string, baseUrl: string): string; // always returns ""
-  protected transformOptions(options: RequestInit): Promise<RequestInit>; // injects Bearer token
+  protected transformOptions(options: RequestInit): Promise<RequestInit>; // sets the Bearer header only if `authToken` is non-empty
 }
 ```
 
@@ -161,8 +161,8 @@ You do not need to manually set the auth token on client instances. The `useApiC
 Do not import from the `platform.ts` file path directly. Always import from `@vc-shell/framework` to ensure proper module resolution and tree-shaking:
 
 ```typescript
-// Bad: direct file import
-import { SecurityClient } from "@core/api/platform";
+// Bad: direct file path
+"@core/api/platform";
 
 // Good: framework re-export
 import { SecurityClient } from "@vc-shell/framework";

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

@@ -158,7 +158,7 @@ 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
+- [`useBladeContext`](../composables/bladeContext/index.docs.md) -- share reactive blade data with descendant components
 
 <!-- internal:start -->
 

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

@@ -115,8 +115,8 @@ defineBladeContext(
 
 ## Related
 
-- [`useBladeWidgets`](../useBladeWidgets/) -- widgets that consume blade context
-- [`useBlade`](../useBlade/) -- cross-blade communication via `callParent` / `exposeToChildren`
+- [`useBladeWidgets`](../useBladeWidgets/index.docs.md) -- widgets that consume blade context
+- [`useBlade`](../useBlade/useBlade.docs.md) -- cross-blade communication via `callParent` / `exposeToChildren`
 
 <!-- internal:start -->
 

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

@@ -6,31 +6,48 @@ 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.
+Creates a typed API client instance for communicating with VirtoCommerce platform APIs. The composable accepts a generated client class constructor (extending `AuthApiBase`) and returns an async factory function that produces a client instance. The composable itself is intentionally thin — it constructs the client and returns it. Platform authentication flows through the session cookie that the browser replays on every same-origin API call; the framework's fetch wrapper enforces timeout, offline checks, and 401-redirect on top.
 
 !!! 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.
+`getApiClient` is async. Never call it at the top level of `<script setup>` — call it inside the async function you pass to `useAsync`. Holding one client instance for the lifetime of the component couples your code to a single object across action runs; prefer one `await getApiClient()` per action so the call shape stays uniform with `useAsync`.
 
 ## When to Use
 
-- Instantiate a generated VirtoCommerce API client with automatic authentication and base-URL resolution
+- Instantiate a generated VirtoCommerce API client that extends `AuthApiBase`
 - Pair with `useAsync` for loading/error state on every API call in a blade or composable
 - When NOT to use: for third-party or non-platform APIs that do not extend `AuthApiBase` -- use `fetch` or Axios directly
 
 ## Quick Start
 
-```typescript
-<script setup lang="ts">
-import { useApiClient } from "@vc-shell/framework";
-import { OrderClient } from "@api/orders";
+The canonical place to call `useApiClient` is at the top of a domain composable file. The factory is created once per module-scope; every action that needs the client awaits `getApiClient()` from the same closure.
 
-const { getApiClient } = useApiClient(OrderClient);
+```typescript title="modules/orders/composables/useOrder/index.ts"
+// pseudo-code: replace OrderClient with your generated API client
+import { useApiClient, useAsync } from "@vc-shell/framework";
+import { OrderClient, type Order } from "@api/orders";
+import { ref } from "vue";
 
-async function loadOrder(orderId: string) {
-  const client = await getApiClient();
-  const order = await client.getOrderById(orderId);
-  return order;
+export function useOrder() {
+  const { getApiClient } = useApiClient(OrderClient);
+  const item = ref<Order>();
+
+  const { action: loadItem, loading } = useAsync<{ id: string }>(async ({ id }) => {
+    const client = await getApiClient();
+    item.value = await client.getOrderById(id);
+  });
+
+  return { item, loading, loadItem };
 }
+```
+
+If you call `useApiClient` inside a blade's `<script setup>` directly, the same shape works. The composable pattern above is preferred because it keeps API access encapsulated behind a domain interface that the blade consumes.
+
+```vue title="modules/orders/pages/order-details.vue"
+<script setup lang="ts">
+import { useOrder } from "../composables/useOrder";
+
+const { item, loading, loadItem } = useOrder();
+onMounted(() => loadItem({ id: param.value }));
 </script>
 ```
 
@@ -39,6 +56,7 @@ async function loadOrder(orderId: string) {
 The standard pattern for API calls in blades combines `useApiClient` with `useAsync`. This gives you automatic loading state, error handling, and a clean async action:
 
 ```typescript
+// pseudo-code: replace ProductClient with your generated API client
 <script setup lang="ts">
 import { useApiClient, useAsync } from "@vc-shell/framework";
 import { ProductClient, Product } from "@api/catalog";
@@ -78,6 +96,7 @@ The `loading` ref is `true` while the request is in-flight. The `error` ref capt
 When a blade needs data from multiple platform modules, create multiple client instances using destructuring aliases:
 
 ```typescript
+// pseudo-code: replace these clients with your generated API clients
 <script setup lang="ts">
 import { useApiClient, useAsync } from "@vc-shell/framework";
 import { OrderClient } from "@api/orders";
@@ -105,6 +124,7 @@ const { action: loadOrderDetails } = useAsync(async (orderId: string) => {
 API clients generated from VirtoCommerce platform endpoints follow a consistent search pattern with `SearchCriteria` objects:
 
 ```typescript
+// pseudo-code: replace OrderClient with your generated API client
 <script setup lang="ts">
 import { useApiClient, useAsync } from "@vc-shell/framework";
 import { OrderClient, OrderSearchCriteria, OrderSearchResult } from "@api/orders";
@@ -129,60 +149,63 @@ searchOrders();
 
 ## CRUD Operations Pattern
 
-A complete CRUD composable for a domain entity:
+A complete CRUD composable for a domain entity. The toolbar is declared as a plain `IBladeToolbar[]` array and bound via `<VcBlade :toolbar-items>`; reactive `disabled` follows the `loading` refs directly, without a `watch`/`updateToolbarItem` pair:
 
-```typescript
+```vue
+<!-- pseudo-code: replace ProductClient with your generated API client -->
 <script setup lang="ts">
-import { ref, onMounted } from "vue";
-import { useApiClient, useAsync, useToolbar } from "@vc-shell/framework";
-import { ProductClient, Product } from "@api/catalog";
+import { computed, onMounted, ref } from "vue";
+import { useApiClient, useAsync, VcBlade, type IBladeToolbar } from "@vc-shell/framework";
+import { ProductClient, type Product } from "@api/catalog";
 
 const props = defineProps<{ param: string }>();
 
 const { getApiClient } = useApiClient(ProductClient);
-const { registerToolbarItem, updateToolbarItem } = useToolbar();
 const product = ref<Product>();
 
-// Load
 const { loading, action: load } = useAsync(async () => {
   const client = await getApiClient();
   product.value = await client.getProductById(props.param);
 });
 
-// Save
 const { loading: saving, action: save } = useAsync(async () => {
   const client = await getApiClient();
   product.value = await client.updateProduct(product.value);
 });
 
-// Delete
 const { loading: deleting, action: remove } = useAsync(async () => {
   const client = await getApiClient();
   await client.deleteProducts([props.param]);
 });
 
-registerToolbarItem({
-  id: "save",
-  title: "Save",
-  icon: "fas fa-save",
-  clickHandler: () => save(),
-  priority: 100,
-});
-
-registerToolbarItem({
-  id: "refresh",
-  title: "Refresh",
-  icon: "fas fa-sync",
-  clickHandler: () => load(),
-  priority: 50,
-});
-
-watch([saving, deleting, loading], ([s, d, l]) => {
-  updateToolbarItem("save", { disabled: s || d || l });
-});
+const busy = computed(() => saving.value || deleting.value || loading.value);
+
+const bladeToolbar = ref<IBladeToolbar[]>([
+  {
+    id: "save",
+    title: "Save",
+    icon: "fas fa-save",
+    clickHandler: () => save(),
+    disabled: busy,
+  },
+  {
+    id: "refresh",
+    title: "Refresh",
+    icon: "fas fa-sync",
+    clickHandler: () => load(),
+    disabled: busy,
+  },
+]);
 
 onMounted(() => load());
 </script>
+
+<template>
+  <VcBlade
+    :loading="loading"
+    :toolbar-items="bladeToolbar"
+  />
+</template>
 ```
 
 ## Recipes
@@ -281,7 +304,7 @@ const response = await fetch("https://api.weather.com/forecast");
 
 ### IAuthApiBase Interface
 
-All generated API client classes implement this interface:
+All generated API client classes extend `AuthApiBase`, which conforms to this interface:
 
 | Property / Method | Type                                              | Description                   |
 | ----------------- | ------------------------------------------------- | ----------------------------- |
@@ -289,6 +312,8 @@ All generated API client classes implement this interface:
 | `setAuthToken`    | `(token: string) => void`                         | Sets the authentication token |
 | `getBaseUrl`      | `(defaultUrl: string, baseUrl: string) => string` | Resolves the API base URL     |
 
+The interface is the public contract used by `useApiClient`'s type parameter. In the everyday flow, application code does not call `setAuthToken` — `useApiClient` constructs the client with no arguments, the `authToken` field stays empty, and authentication flows through the session cookie attached by the browser to each same-origin `/api/*` request. `setAuthToken` is the explicit-token path consumed by code that needs to attach a token directly (for example, when calling the API from a context where the cookie is unavailable).
+
 ### Generated Client Classes
 
 API clients are generated from Swagger/OpenAPI specs using the `@vc-shell/api-client-generator` CLI tool. Each generated class:
@@ -302,5 +327,5 @@ API clients are generated from Swagger/OpenAPI specs using the `@vc-shell/api-cl
 
 - [`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
+- Blade toolbar — declare as `ref<IBladeToolbar[]>([...])` and bind via `<VcBlade :toolbar-items>`; see [`useToolbar`](../useToolbar/) for the advanced dynamic-registration API
 - [`useNotifications`](../useNotifications/) -- display success/error messages after API operations

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

@@ -13,7 +13,7 @@ Manages custom action buttons in the mobile app bar. Uses provide/inject to shar
 - Register custom buttons (icons, components) in the mobile top bar from any blade or module
 - Show notification badges, filter toggles, or action shortcuts in the mobile app bar
 - Dynamically show/hide buttons based on blade state (e.g., only show a "filter" button when a list blade is active)
-- When NOT to use: for desktop-only toolbar actions (use `useToolbar` instead); for buttons inside blade content (just use regular template markup)
+- When NOT to use: for desktop blade toolbar actions, declare an `IBladeToolbar[]` array and pass it to `<VcBlade :toolbar-items>` (reach for `useToolbar` only when toolbar items must be added after mount); for buttons inside blade content, just use regular template markup
 
 ## Quick Start
 
@@ -137,6 +137,6 @@ onUnmounted(() => unregister("language-switcher"));
 
 ## Related
 
-- `useToolbar` -- desktop toolbar actions (different service, different UI placement)
+- Desktop blade toolbar actions — declare an `IBladeToolbar[]` array bound via `<VcBlade :toolbar-items>`; `useToolbar` is the advanced API for dynamic registration after mount
 - `framework/core/services/app-bar-mobile-buttons-service.ts` -- underlying service implementation
 - `VcApp` -- provides the service via `provideAppBarMobileButtonsService()`

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

@@ -6,23 +6,25 @@ 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.
+Provides access to the widget service that powers the **Widgets** section of the App hub popover. Modules use it to register cross-app widgets — sync status indicators, language pickers, feature shortcuts — that the shell renders next to the apps grid in the hub. Uses Vue's provide/inject system.
 
 Also exports `provideAppBarWidget()` for framework-level initialization.
 
+> The `useAppBarWidget` name is a holdover from an earlier shell version where widgets rendered directly in the sidebar app-bar. In the current shell, the API name is the only place "app-bar" survives — the actual surface is the App hub popover.
+
 ## Overview
 
-The vc-shell application header (app bar) contains a row of widget slots for global actions: notification bell, language picker, user menu, and more. Modules can add their own widgets to this bar -- for example, a "quick create" button, a sync status indicator, or a custom dropdown.
+In the default VcApp shell, registered widgets render inside the **Widgets** section of the App hub popover (the panel that opens from the app-hub trigger button in the sidebar). The sidebar app-bar itself only holds the notification bell and the app-hub trigger; widgets do not appear there. On mobile, the same widgets surface in the hub tab and fly out below the panel when activated.
 
-The `useAppBarWidget()` composable provides the `IAppBarWidgetService` interface, which allows registering, unregistering, and listing app bar widgets. Widgets can be simple icon buttons with click handlers or fully custom Vue components.
+The `useAppBarWidget()` composable provides the `IAppBarWidgetService` interface, which allows registering, unregistering, and listing widgets. Each widget is either an action widget (an icon plus an `onClick` handler) or a component widget (a custom Vue component that the hub expands inline when clicked).
 
 The service follows the same provide/inject singleton pattern as other framework services. The framework calls `provideAppBarWidget()` during bootstrap; modules consume it via `useAppBarWidget()`.
 
 ## When to Use
 
-- To register a custom widget (notification bell, language picker, user avatar) in the app bar
-- To list or manage currently registered app bar widgets
-- When NOT to use: for blade-level toolbar actions, use `useToolbar()` instead
+- To register a cross-app widget (sync status, language picker, feature shortcut) in the App hub
+- To list or manage currently registered hub widgets
+- When NOT to use: for blade-level toolbar actions, declare an `IBladeToolbar[]` array and pass it to `<VcBlade :toolbar-items>` (use `useToolbar()` only for dynamic registration after mount)
 
 ## Basic Usage
 
@@ -49,16 +51,16 @@ None.
 
 | Property / Method | Type                                               | Description                                                |
 | ----------------- | -------------------------------------------------- | ---------------------------------------------------------- |
-| `register`        | `(options: registerAppBarWidgetOptions) => string` | Registers a widget in the app bar, returns the assigned ID |
-| `unregister`      | `(id: string) => void`                             | Removes a widget from the app bar by ID                    |
-| `items`           | `ComputedRef<AppBarWidget[]>`                      | Reactive list of all registered app bar widgets            |
+| `register`        | `(options: registerAppBarWidgetOptions) => string` | Registers a widget in the App hub, returns the assigned ID |
+| `unregister`      | `(id: string) => void`                             | Removes a widget from the App hub by ID                    |
+| `items`           | `ComputedRef<AppBarWidget[]>`                      | Reactive list of all registered hub widgets                |
 
 ### registerAppBarWidgetOptions
 
 | Field       | Type                      | Required | Description                                                   |
 | ----------- | ------------------------- | -------- | ------------------------------------------------------------- |
 | `id`        | `string`                  | No       | Custom ID; auto-generated if omitted                          |
-| `order`     | `number`                  | No       | Sort order in the app bar (lower = further left)              |
+| `order`     | `number`                  | No       | Sort order in the hub Widgets list (lower = appears first)    |
 | `title`     | `string`                  | No       | Tooltip or label text                                         |
 | `icon`      | `Component \| string`     | No       | Lucide icon name or a Vue component                           |
 | `component` | `Component`               | No       | Custom Vue component to render instead of default icon button |
@@ -136,14 +138,14 @@ const { items } = useAppBarWidget();
 
 // Iterate over all widgets (sorted by order)
 watchEffect(() => {
-  console.log(`${items.value.length} widgets in app bar`);
+  console.log(`${items.value.length} widgets in the App hub`);
   items.value.forEach((w) => console.log(`  - ${w.title ?? w.id}`));
 });
 ```
 
 ### Pre-registration before service exists
 
-If your module code runs before the app bar service is provided (e.g., during module `install()`), use the `addAppBarWidget()` bus function. Items are automatically flushed when `provideAppBarWidget()` runs:
+If your module code runs before the widget service is provided (e.g., during module `install()`), use the `addAppBarWidget()` bus function. Items are automatically flushed when `provideAppBarWidget()` runs:
 
 ```typescript
 import { addAppBarWidget } from "@vc-shell/framework";
@@ -185,7 +187,7 @@ register({ component: markRaw(MyWidget) });
 
 ## Related
 
-- [useToolbar](../useToolbar/) -- blade-level toolbar actions (different scope than app bar)
+- Blade toolbar actions — declare an `IBladeToolbar[]` array and bind it via `<VcBlade :toolbar-items>`; see [useToolbar](../useToolbar/) for the advanced dynamic-registration API
 - [useWidgets](../useWidgets/useWidgets.docs.md) -- blade widget registration system
 - `framework/injection-keys.ts` -- `AppBarWidgetServiceKey`
 - `framework/core/services/app-bar-menu-service.ts` -- the underlying service implementation

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

@@ -6,7 +6,7 @@ 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`).
+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 (for example, `[Operations Console] Dashboard`).
 
 ## When to Use
 
@@ -42,17 +42,17 @@ export default router;
 
 ### Returns
 
-| Property                       | Type                                                  | Description                                                                                            |
-| ------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `setupPageTracking.beforeEach` | `(route: { name: string }) => void`                   | Call in router `beforeEach` to start page-view timing and generate a new trace ID                      |
-| `setupPageTracking.afterEach`  | `(route: { name: string; fullPath: string }) => void` | Call in router `afterEach` to stop page-view timing and flush the telemetry event                      |
-| `appInsights`                  | `ApplicationInsights`                                 | Raw Application Insights instance for custom telemetry (trackEvent, trackException, trackMetric, etc.) |
+| Property                       | Type                                                  | Description                                                                                                                                                                                                       |
+| ------------------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `setupPageTracking.beforeEach` | `(route: { name: string }) => void`                   | Call in router `beforeEach` to start page-view timing and generate a new trace ID                                                                                                                                 |
+| `setupPageTracking.afterEach`  | `(route: { name: string; fullPath: string }) => void` | Call in router `afterEach` to stop page-view timing and flush the telemetry event                                                                                                                                 |
+| `appInsights`                  | `ApplicationInsights \| null`                         | Raw Application Insights instance for custom telemetry (`trackEvent`, `trackException`, `trackMetric`, etc.). `null` when the AI plugin is not installed -- `setupPageTracking` handlers are no-ops in that case. |
 
 ### Injection Key
 
-| Key                     | Type                                     | Description                                                                                       |
-| ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `AppInsightsOptionsKey` | `InjectionKey<AppInsightsPluginOptions>` | Optional. Provide this at app level with `{ appName: 'Vendor Portal' }` to prefix all page names. |
+| Key                     | Type                                     | Description                                                                                            |
+| ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `AppInsightsOptionsKey` | `InjectionKey<AppInsightsPluginOptions>` | Optional. Provide this at app level with `{ appName: 'Operations Console' }` to prefix all page names. |
 
 ## How It Works
 
@@ -99,12 +99,12 @@ import { AppInsightsOptionsKey } from "@vc-shell/framework";
 const app = createApp(App);
 
 app.provide(AppInsightsOptionsKey, {
-  appName: "Vendor Portal",
+  appName: "Operations Console",
   // ... other AppInsightsPluginOptions
 });
 ```
 
-This results in page names like `[Vendor Portal] Dashboard` instead of just `Dashboard`.
+This results in page names like `[Operations Console] Dashboard` instead of just `Dashboard`.
 
 ## Tips
 

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

@@ -28,26 +28,27 @@ When the returned `action` is called, `useAsync` automatically:
 ## Quick Start
 
 ```typescript
+// pseudo-code: replace OrderClient with your generated API client
 import { useAsync, useApiClient } from "@vc-shell/framework";
 import { OrderClient } from "@api/orders";
 
 const { getApiClient } = useApiClient(OrderClient);
 
-const {
-  loading,
-  error,
-  action: loadOrder,
-} = useAsync<string>(async (id) => {
+// Alias `loading` and `action` to domain names so multiple useAsync blocks in the
+// same composable can coexist without colliding on `loading` / `action`.
+const { loading: loadOrderLoading, action: loadOrder } = useAsync<string>(async (id) => {
   const client = await getApiClient();
   return await client.getOrderById(id);
 });
 
-// In a blade's onMounted:
 await loadOrder("order-123");
-// loading.value was true during the call, now false
-// error.value is null on success, or a DisplayableError on failure
+// loadOrderLoading.value was true during the call, now false.
+// Errors auto-toast through the default `notify: true` option — no need to read
+// `error` unless you want to render a custom error UI.
 ```
 
+Per-action aliasing scales: a CRUD composable typically has `loadItemLoading`, `saveItemLoading`, `removeItemLoading` from three separate `useAsync` calls. Aggregate them through `useLoading` to drive a single blade-level loading state.
+
 ## API Reference
 
 ### Import
@@ -204,6 +205,7 @@ const { action: silentRefresh } = useAsync(
 The standard pattern for API operations in VC-Shell:
 
 ```typescript
+// pseudo-code: replace VcmpSellerCatalogClient with your generated API client
 import { useAsync, useApiClient } from "@vc-shell/framework";
 import { VcmpSellerCatalogClient } from "@api/client";
 
@@ -246,6 +248,7 @@ The standard VC-Shell pattern: encapsulate all CRUD operations for an entity in
 
 ```typescript
 // composables/useFulfillmentCenter/index.ts
+// pseudo-code: replace VcmpSellerCatalogClient with your generated API client
 import { useApiClient, useAsync, useLoading } from "@vc-shell/framework";
 import { VcmpSellerCatalogClient, type FulfillmentCenter } from "@api/client";
 
@@ -423,9 +426,9 @@ const { action: save, loading: saveLoading } = useAsync(async () => saveData());
 
 ## Related
 
-| Resource                                                    | Description                                                                         |
-| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| [`useApiClient`](../useApiClient/)                          | Provides typed API client instances to pass into `useAsync`                         |
-| [`useLoading`](../useLoading/)                              | Combines multiple `loading` refs into a single boolean                              |
-| [`useModificationTracker`](../useModificationTracker/)      | Tracks dirty state for forms -- often used alongside `useAsync` for save operations |
-| [`notification`](../../../shared/components/notifications/) | The toast notification system used by `useAsync` for error display                  |
+| Resource                                                   | Description                                                                         |
+| ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| [`useApiClient`](../useApiClient/)                         | Provides typed API client instances to pass into `useAsync`                         |
+| [`useLoading`](../useLoading/)                             | Combines multiple `loading` refs into a single boolean                              |
+| [`useModificationTracker`](../useModificationTracker/)     | Tracks dirty state for forms -- often used alongside `useAsync` for save operations |
+| [Notifications](../../notifications/notifications.docs.md) | The notification and toast system used by `useAsync` for error display              |

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

@@ -8,11 +8,13 @@ group: utilities
 
 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.
 
+> Form blades already wire this for you. `useBladeForm` registers `useBeforeUnload(isModified)` by default; pass `autoBeforeUnload: false` if you ever need to opt out. Reach for `useBeforeUnload` directly only when the unsaved state lives outside a form (a kanban board, a wizard, a custom editor not backed by `useBladeForm`).
+
 ## When to Use
 
-- Protect forms or blades with unsaved edits from accidental tab/window close or page refresh
+- Protect non-form blades with unsaved edits (kanban, wizard, custom editor) from accidental tab/window close or page refresh
 - Pair with `useModificationTracker` to get a reactive `modified` flag automatically
-- When NOT to use: for in-app navigation guards (use Vue Router `beforeRouteLeave` or blade `onBeforeClose` instead). This composable only handles the browser-level close/refresh event, not SPA route changes.
+- When NOT to use: inside a blade backed by `useBladeForm` (the form already registers it); for in-app navigation guards (use Vue Router `beforeRouteLeave` or blade `onBeforeClose` instead). This composable only handles the browser-level close/refresh event, not SPA route changes.
 
 ## Quick Start