@vc-shell/vc-app-skill 2.0.0-alpha.23 → 2.0.0-alpha.25

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

@@ -1,15 +1,19 @@
-# useBladeWidgets
+# useBladeWidgets / useWidgetTrigger
 
-Declarative headless widget registration for blades. Widgets are automatically registered with the WidgetService on mount and cleaned up on unmount, following the Vue component lifecycle. This composable is the recommended way to add sidebar counter widgets, action buttons, and status indicators to a blade without creating separate Vue component files for each widget.
+Two composables for the widget system — one for the **blade side**, one for the **widget side**.
 
-Headless widgets are defined as plain configuration objects with reactive refs for dynamic values like badge counts and loading states. The WidgetService renders them in the blade sidebar.
+| Composable | Called from | Purpose |
+|---|---|---|
+| `useBladeWidgets` | Blade component | Register headless widgets + get `refresh()` / `refreshAll()` |
+| `useWidgetTrigger` | External widget component | Register trigger callbacks (`onRefresh`, `onClick`) via provide/inject |
+
+Headless widgets are defined as plain configuration objects with reactive refs for dynamic values like badge counts and loading states. External component-based widgets use `useWidgetTrigger` to register their refresh callbacks so the hosting blade can trigger them.
 
 ## When to Use
 
-- Register sidebar widgets (counters, action buttons) for a blade without creating Vue components
-- Refresh widget data programmatically after blade operations (save, delete, status change)
-- Show/hide widgets conditionally based on blade state (e.g., only show after entity is saved)
-- When NOT to use: for widgets that need their own template or complex UI (use a full widget component instead)
+- **`useBladeWidgets`**: Register sidebar widgets (counters, action buttons) for a blade without creating Vue components. Refresh widget data after blade operations (save, delete).
+- **`useWidgetTrigger`**: Inside an external widget component (registered via `registerExternalWidget`) to register `onRefresh` / `onClick` callbacks. The blade can then call `refresh(widgetId)` or `refreshAll()` to trigger them.
+- When NOT to use `useBladeWidgets`: for widgets that need their own template or complex UI (use `registerExternalWidget` + `useWidgetTrigger` instead).
 
 ## Basic Usage
 
@@ -70,6 +74,121 @@ refreshAll();
 | `refresh` | `(widgetId: string) => void` | Trigger `onRefresh` on a specific widget |
 | `refreshAll` | `() => void` | Trigger `onRefresh` on all widgets that have one |
 
+## useWidgetTrigger
+
+Widget-side composable for external component-based widgets. Registers a trigger contract (`onRefresh`, `onClick`, `badge`) via provide/inject — no props, IDs, or service knowledge required.
+
+### Basic Usage
+
+```typescript
+import { useWidgetTrigger } from '@vc-shell/framework';
+
+// Inside an external widget component:
+useWidgetTrigger({ onRefresh: loadData });
+```
+
+### IWidgetTrigger
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `icon` | `string` | No | Lucide icon name for dropdown rendering |
+| `title` | `string` | No | Display title (fallback: widget's title) |
+| `badge` | `Ref<number \| string>` | No | Reactive badge value |
+| `onClick` | `() => void` | No | Handler called when widget is clicked in dropdown |
+| `onRefresh` | `() => void \| Promise<void>` | No | Handler called to refresh widget data |
+| `disabled` | `Ref<boolean> \| boolean` | No | Disabled state |
+
+### How It Works
+
+1. `WidgetContainer` wraps each component-based widget in a `WidgetScope` provider
+2. `WidgetScope` provides a `setTrigger` function scoped to the specific widget ID and blade ID
+3. `useWidgetTrigger` injects this scope and calls `setTrigger` — no props or IDs needed
+4. When the blade calls `refresh(widgetId)` or `refreshAll()`, the registered `onRefresh` is invoked
+
+## Recipe: External Widget with Refresh
+
+A complete example of an external widget that shows an unread message count and supports refresh from the blade:
+
+**1. Register the external widget (module index.ts):**
+
+```typescript
+import { createAppModule, registerExternalWidget, IBladeInstance } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import { MessageWidget } from "./components/widgets";
+
+registerExternalWidget({
+  id: "MessageWidget",
+  component: markRaw(MessageWidget),
+  targetBlades: ["ProductDetails", "OrderDetails"],
+  isVisible: (blade?: IBladeInstance) => !!blade?.param,
+});
+```
+
+**2. Widget component (message-widget.vue):**
+
+```vue
+<template>
+  <VcWidget
+    v-loading:500="loading"
+    :title="$t('MESSENGER.WIDGET.TITLE')"
+    icon="lucide-message-circle"
+    :value="messageCount"
+    @click="openMessageBlade"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted } from "vue";
+import {
+  loading as vLoading,
+  useBlade,
+  injectBladeContext,
+  useWidgetTrigger,
+  VcWidget,
+} from "@vc-shell/framework";
+
+const ctx = injectBladeContext();
+const entityId = computed(() => (ctx.value.item as { id?: string })?.id ?? "");
+
+const messageCount = ref(0);
+const loading = ref(false);
+
+const loadData = async () => {
+  loading.value = true;
+  try {
+    messageCount.value = await api.getUnreadCount(entityId.value);
+  } finally {
+    loading.value = false;
+  }
+};
+
+// Register refresh callback — blade can call refreshAll() after save
+useWidgetTrigger({ onRefresh: loadData });
+
+onMounted(() => {
+  if (entityId.value) loadData();
+});
+</script>
+```
+
+**3. Blade refreshes widgets after save:**
+
+```vue
+<script setup lang="ts">
+import { useBladeWidgets } from "@vc-shell/framework";
+
+// Empty array — blade doesn't register headless widgets,
+// but gets refresh/refreshAll for external widgets
+const { refresh, refreshAll } = useBladeWidgets([]);
+
+async function save() {
+  await api.saveProduct(product.value);
+  refreshAll();           // refresh all widgets (including MessageWidget)
+  // or: refresh("MessageWidget");  // refresh a specific widget by ID
+}
+</script>
+```
+
 ## Recipe: Product Detail Blade with Multiple Widgets
 
 ```vue
@@ -126,10 +245,15 @@ async function save() {
 
 ## Prerequisites
 
+**`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).
 - 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).
+- 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.
@@ -143,8 +267,39 @@ async function save() {
 - Keep widget IDs unique within a blade. Duplicate IDs will overwrite previous registrations.
 - Combine with `defineBladeContext` to expose blade entity data that widget components (non-headless) can consume via `injectBladeContext`.
 
+## Common Mistakes
+
+### Calling useWidgetTrigger outside WidgetContainer scope
+
+```typescript
+// Wrong — called in a standalone component, not rendered inside a blade widget slot
+export default defineComponent({
+  setup() {
+    useWidgetTrigger({ onRefresh: loadData }); // ⚠️ Logs warning, trigger not registered
+  },
+});
+```
+
+```typescript
+// Correct — called inside a widget component registered via registerExternalWidget
+// and rendered by WidgetContainer within a blade
+useWidgetTrigger({ onRefresh: loadData }); // ✓ WidgetScope provides context
+```
+
+### Forgetting to pass empty array to useBladeWidgets for refresh-only usage
+
+```typescript
+// Wrong — useBladeWidgets requires an array argument
+const { refreshAll } = useBladeWidgets(); // TS error
+
+// Correct — pass empty array when you only need refresh/refreshAll
+const { refreshAll } = useBladeWidgets([]);
+```
+
 ## Related
 
-- `defineBladeContext` -- expose blade data to widgets
-- `WidgetService` in `@core/services/widget-service`
+- `defineBladeContext` / `injectBladeContext` -- 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`

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

@@ -2,6 +2,12 @@
 
 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.
 
+## When to Use
+
+- Register dashboard widgets during module setup (use standalone `registerDashboardWidget`)
+- Read or update widget layout at runtime inside a dashboard view component (use `useDashboard()`)
+- When NOT to use: for sidebar navigation items -- use `useMenuService` / `addMenuItem`; for settings-page entries -- use `useSettingsMenu`
+
 ## Quick Start
 
 ```typescript

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

@@ -2,6 +2,12 @@
 
 Accesses the navigation menu service for adding, removing, and badging menu items in the application sidebar. The service supports a pre-registration pattern that allows modules to declare menu items before the service is initialized, and a grouping system that organizes items into collapsible sections.
 
+## When to Use
+
+- Register sidebar navigation items during module setup (use standalone `addMenuItem`)
+- Add, remove, or badge menu items at runtime inside components (use `useMenuService()`)
+- When NOT to use: for dashboard widgets -- use `useDashboard` / `registerDashboardWidget`; for settings-page entries -- use `useSettingsMenu`
+
 ## Quick Start
 
 ```typescript

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

@@ -2,6 +2,12 @@
 
 Checks whether the current user has specific platform permissions. This composable reads the authenticated user's permission list and provides a `hasAccess` function for conditional UI rendering and access control. It is client-side only -- it does not enforce server-side authorization.
 
+## When to Use
+
+- Conditionally show or hide UI elements (buttons, toolbar items, sections) based on the current user's permissions
+- Guard blade access or toolbar registration with client-side permission checks
+- When NOT to use: as the sole authorization mechanism -- always pair with server-side enforcement; for checking authentication status -- use `useUser` instead
+
 ## Quick Start
 
 ```typescript

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

@@ -2,6 +2,12 @@
 
 Manages toolbar buttons for blades. Each blade in the application has its own toolbar area at the top of the blade header. `useToolbar` provides a scoped API to register, update, and remove buttons within that toolbar. It automatically resolves the current blade context and cleans up registered items when the component unmounts.
 
+## When to Use
+
+- Add action buttons (Save, Delete, Refresh, Export) to a blade's toolbar header
+- Dynamically update button state (disabled, visible, icon) in response to loading or form changes
+- When NOT to use: for global app-bar actions -- use `useAppBarWidget`; for navigation links -- use `useMenuService`
+
 ## Quick Start
 
 ```typescript

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

@@ -9,7 +9,7 @@ Also exports `provideWidgetService()` for framework-level initialization and `re
 - When you need low-level access to the widget service (register, unregister, query widgets)
 - When building framework infrastructure that manages widget lifecycles
 - When pre-registering widgets from a module's `install()` function before the component tree exists
-- When NOT to use: for typical blade widget work, prefer `useBladeWidgets()` which handles lifecycle automatically. For widget-side logic (badge, refresh), use `useWidget()`.
+- When NOT to use: for typical blade widget work, prefer `useBladeWidgets()` which handles lifecycle automatically. For widget-side logic (badge, refresh), use headless widgets.
 
 ## Quick Start
 
@@ -46,7 +46,7 @@ None.
 | `setActiveWidget` | `(args) => void` | Sets a widget as active with its exposed instance. |
 | `updateActiveWidget` | `() => void` | Triggers the active widget's update function. Deprecated -- use headless widgets instead. |
 | `isWidgetRegistered` | `(id: string) => boolean` | Checks if a widget ID exists in any blade's registry. |
-| `updateWidget` | `(args) => void` | Updates properties of a registered widget (trigger, badge, etc.). Used by `useWidget().setTrigger()`. |
+| `updateWidget` | `(args) => void` | Updates properties of a registered widget (trigger, badge, etc.). |
 | `resolveWidgetProps` | `(widget, bladeData) => Record<string, unknown>` | Resolves widget props from blade data. Deprecated. |
 | `getExternalWidgetsForBlade` | `(bladeId: string) => IExternalWidgetRegistration[]` | Gets external widgets that target a specific blade (registered by other modules). |
 | `getAllExternalWidgets` | `() => IExternalWidgetRegistration[]` | Gets all registered external widgets across all modules. |

package/runtime/knowledge/docs/core/plugins/ai-agent/ai-agent.docs.md

@@ -6,6 +6,12 @@ Integrates an AI assistant panel (chatbot iframe) into the vc-shell application.
 
 The AI agent plugin embeds an external chatbot via an iframe panel that slides in from the right side of the application. It automatically sends the current blade context (user, active blade, selected items) to the chatbot and handles incoming commands (navigate, preview changes, download files). The plugin is optional -- if no `APP_AI_AGENT_URL` environment variable or `config.url` is provided, it silently skips installation.
 
+## When to Use
+
+- Embed an AI assistant chatbot panel into your vc-shell application with automatic blade context passing
+- Enable preview/apply workflows where AI suggests changes and the user confirms them
+- When NOT to use: if you don't have an AI agent backend -- the plugin silently skips when no `APP_AI_AGENT_URL` is set
+
 ## Installation / Registration
 
 ```typescript

package/runtime/knowledge/docs/core/plugins/extension-points/extension-points.docs.md

@@ -4,6 +4,12 @@ Extension points enable **cross-module UI composition** without direct imports.
 
 This is how vc-shell achieves its modular architecture: modules can extend each other without compile-time dependencies.
 
+## When to Use
+
+- Module A needs to inject UI into Module B without a compile-time dependency (e.g., a "Reviews" tab inside a "Product Details" blade owned by another module)
+- You need order-independent, runtime-resolved composition -- modules can load in any order
+- When NOT to use: for simple parent-child communication within one module -- use props/slots/provide-inject instead; for data-only integration -- use events or a shared composable
+
 ---
 
 ## Table of Contents

package/runtime/knowledge/docs/core/plugins/global-error-handler/global-error-handler.docs.md

@@ -8,6 +8,12 @@ In a complex admin shell with dynamically loaded modules, errors can originate f
 
 The global error handler solves this by installing three layers of error catching that cover all common error sources. Every caught error is parsed into a human-readable message and displayed as a toast notification, ensuring users always know when something goes wrong -- even if the module developer forgot to add error handling.
 
+## When to Use
+
+- This plugin is always active -- it catches unhandled errors from Vue components, async rejections, and uncaught JS errors automatically
+- You don't need to install or configure it -- the framework does this during app setup
+- When to be aware: if you handle errors manually in a composable (try/catch), the global handler won't fire for those -- which is the desired behavior
+
 ### Three Layers of Error Catching
 
 1. **Vue `app.config.errorHandler`** -- catches errors thrown inside Vue components (render functions, lifecycle hooks, watchers, event handlers)

package/runtime/knowledge/docs/core/plugins/i18n/i18n.docs.md

@@ -8,6 +8,12 @@ The vc-shell framework supports multiple languages through a centralized `vue-i1
 
 This approach ensures consistency across the application: switching the active locale updates all modules simultaneously, fallback behavior is uniform, and there is a single source of truth for the current language.
 
+## When to Use
+
+- Add translated labels, messages, and error strings to any module (provide locale files via `defineAppModule({ locales })`)
+- Access the current locale or switch languages at runtime via `useI18n()` or `useLanguages()`
+- When NOT to use: this plugin is always active -- you never skip it. If you only need a single language, still use i18n keys for consistency
+
 Modules do not install this plugin directly. Instead, they provide their locale messages via `defineAppModule({ locales })`, and the framework merges them into the global i18n instance using `i18n.global.mergeLocaleMessage()` during module installation.
 
 ## Installation / Registration
@@ -175,6 +181,74 @@ import { i18n } from "@vc-shell/framework";
 const message = i18n.global.t("MY_MODULE.SOME_KEY");
 ```
 
+## Customizing Framework Translations
+
+The framework exports its locale files as typed ES modules. App developers can import them to create full translations or override specific keys.
+
+### Importing Framework Locales
+
+```typescript
+import en from '@vc-shell/framework/locales/en'
+import de from '@vc-shell/framework/locales/de'
+import type { VcShellLocale, VcShellLocalePartial } from '@vc-shell/framework/locales/types'
+```
+
+The `VcShellLocale` interface provides autocomplete for all framework translation keys. Use it when creating a full translation to ensure no keys are missed.
+
+### Creating a New Language
+
+Spread the English locale as a base and override all sections:
+
+```typescript
+import en from '@vc-shell/framework/locales/en'
+import type { VcShellLocale } from '@vc-shell/framework/locales/types'
+
+const fr: VcShellLocale = {
+  ...en,
+  CORE: { THEMES: { LIGHT: "Clair", DARK: "Sombre" } },
+  SHELL: {
+    ...en.SHELL,
+    ACCOUNT: {
+      SETTINGS: "Paramètres",
+      CHANGE_PASSWORD: "Changer le mot de passe",
+      PROFILE: "Profil",
+      LOGOUT: "Déconnexion",
+    },
+  },
+  COMPONENTS: {
+    ...en.COMPONENTS,
+    // ... translate component strings
+  },
+}
+
+// Register in your app's main.ts or plugin setup:
+app.config.globalProperties.$mergeLocaleMessage('fr', fr)
+```
+
+### Overriding Specific Keys
+
+Use `VcShellLocalePartial` for partial overrides — all keys are optional:
+
+```typescript
+import type { VcShellLocalePartial } from '@vc-shell/framework/locales/types'
+
+const overrides: VcShellLocalePartial = {
+  SHELL: { ACCOUNT: { LOGOUT: "Sign Out" } }
+}
+
+app.config.globalProperties.$mergeLocaleMessage('en', overrides)
+```
+
+### Validating Your Translation
+
+Run the CLI tool to check for missing or extra keys:
+
+```bash
+npx vc-check-locales ./src/locales/fr.json
+```
+
+In development mode, the framework also logs console warnings when a translation key is accessed but has no value for the current locale.
+
 ## Related
 
 - `framework/core/plugins/modularity/index.ts` -- `defineAppModule` merges locale messages via `i18n.global.mergeLocaleMessage()`

package/runtime/knowledge/docs/core/plugins/modularity/modularity.docs.md

@@ -4,6 +4,12 @@ The modularity plugin is the backbone of every vc-shell application. It defines
 
 If you are building anything in vc-shell -- a new page, a CRUD flow, a dashboard widget, a notification handler -- you will start by creating a module.
 
+## When to Use
+
+- Package any feature as a self-contained unit with blades, menu items, locales, notifications, and permissions
+- Every vc-shell feature starts here -- `defineAppModule()` is the entry point for all module development
+- When NOT to use: for shared utilities or composables that have no UI -- export them as plain TypeScript modules instead
+
 ---
 
 ## Table of Contents

package/runtime/knowledge/docs/core/plugins/permissions/permissions.docs.md

@@ -8,6 +8,12 @@ The VirtoCommerce platform uses a role-based permission system where each user i
 
 The plugin installs the `hasAccess()` function from the `usePermissions()` composable as both a Vue global property (`$hasAccess`) and a provide/inject injectable (`"$hasAccess"`). This means permission checks are available everywhere: in templates via `$hasAccess()`, in composition API code via `usePermissions()`, and in any injecting component.
 
+## When to Use
+
+- Show/hide UI elements based on user permissions: `v-if="$hasAccess('order:create')"` in templates or `hasAccess()` in composables
+- Guard toolbar buttons, menu items, or entire blade sections with client-side permission checks
+- When NOT to use: as the sole authorization layer -- always enforce permissions server-side too; for authentication checks (logged in / logged out) -- use `useUser` instead
+
 The framework installs this plugin automatically during app setup. Module developers never need to register it manually.
 
 ## Installation / Registration

package/runtime/knowledge/docs/core/plugins/signalR/signalR.docs.md

@@ -4,6 +4,12 @@ Real-time push notification transport via ASP.NET SignalR. Connects to the platf
 
 ## Overview
 
+## When to Use
+
+- Receive real-time push notifications from the platform (order updates, export progress, background job status)
+- Display live notification toasts and badge counts without polling
+- When NOT to use: for request-response API calls -- use `useApiClient`; for periodic data refresh -- use polling with `useAsync` instead
+
 The VirtoCommerce platform uses ASP.NET SignalR to push real-time notifications to connected clients. These notifications cover events like order status changes, catalog exports completing, background job progress, and system alerts.
 
 The SignalR plugin establishes a persistent WebSocket connection to the platform hub and listens for two event channels:

package/runtime/knowledge/docs/core/plugins/validation/validation.docs.md

@@ -8,6 +8,12 @@ Form validation is a critical part of any admin interface. The vc-shell framewor
 
 This plugin auto-registers every rule from `@vee-validate/rules` (required, email, min, max, etc.) via `defineRule()`, then adds custom rules specific to vc-shell use cases. Once registered, rules are available globally in any `<Field>` component, `useField()` composable, or validation schema -- no per-component imports needed.
 
+## When to Use
+
+- Validate form fields in blades using `<Field>` components or `useField()` with declarative rules (`required`, `email`, `min`, etc.)
+- Use custom vc-shell rules: image dimensions (`validateImageMinSize`), file weight, date comparisons, BigInt safety
+- When NOT to use: for API-level validation -- that belongs server-side; for simple presence checks on non-form data -- use plain conditionals
+
 The framework imports this module during setup. No manual installation is needed by module developers.
 
 ## Installation / Registration

package/runtime/knowledge/docs/injection-keys.docs.md

@@ -62,7 +62,7 @@ This centralized approach has several advantages:
 
 | Key | Type | Description |
 |-----|------|-------------|
-| `WidgetIdKey` | `string` | Widget identity (provided by WidgetProvider) |
+| `WidgetScopeKey` | `IWidgetScope` | Widget scope (provided by WidgetContainer for component-based widgets via `WidgetScope.vue`) |
 | `AppRootElementKey` | `Ref<HTMLElement \| undefined>` | App root element for scoped Teleport |
 | `EmbeddedModeKey` | `boolean` | Whether the app runs in embedded mode |
 | `ShellIndicatorsKey` | `ComputedRef<boolean>` | Unread indicator state for sidebar |

package/runtime/knowledge/docs/modules/assets-manager/assets-manager.docs.md

@@ -4,7 +4,7 @@ A built-in blade module for managing file assets (images, documents, archives).
 
 ## Overview
 
-The Assets Manager is registered as an app module via `defineAppModule` and opened as a child blade from any parent blade that needs asset management. The parent provides handler callbacks for upload, edit, and remove operations -- the module handles the UI and delegates data mutations back to the parent.
+The Assets Manager is registered as an app module via `defineAppModule` and opened as a child blade from any parent blade that needs asset management. The parent creates a `useAssetsManager` instance and passes it through `options.manager` -- the module handles the UI and delegates data mutations through the manager.
 
 ## Module Registration
 
@@ -17,56 +17,51 @@ import { AssetsManagerModule } from "@vc-shell/framework";
 
 The module exports `AssetsManagerModule` (a Vue plugin) and the `AssetsManager` component, which is declared as a global component.
 
-## Props (Options)
+## Options (via `useBlade`)
 
-The blade receives its configuration via the `options` prop when opened:
+The blade reads its configuration from `options` via `useBlade<AssetsManagerOptions>()` (not props):
 
 | Option | Type | Description |
 |---|---|---|
-| `title` | `string` | Custom blade title (defaults to i18n `ASSETS_MANAGER.TITLE`) |
-| `assets` | `ICommonAsset[]` | Initial array of assets to display |
-| `loading` | `Ref<boolean>` | Reactive loading state for the table overlay |
-| `assetsEditHandler` | `(assets) => ICommonAsset[]` | Called when assets are reordered or edited |
-| `assetsUploadHandler` | `(files) => Promise<ICommonAsset[]>` | Called with selected files for upload |
-| `assetsRemoveHandler` | `(assets) => Promise<ICommonAsset[]>` | Called to delete selected assets |
-| `disabled` | `boolean` | When true, hides upload/delete actions and disables reordering |
-| `hiddenFields` | `string[]` | Fields to hide in the detail view |
+| `title` | `string?` | Custom blade title (defaults to i18n `ASSETS_MANAGER.TITLE`) |
+| `manager` | `UseAssetsManagerReturn` | The asset manager instance from `useAssetsManager()`. **Must be wrapped in `markRaw()`** |
+| `disabled` | `boolean?` | When true, hides upload/delete actions and disables reordering |
+| `hiddenFields` | `string[]?` | Fields to hide in the detail view |
+
+> **Breaking change:** The old options (`assets`, `loading`, `assetsUploadHandler`, `assetsEditHandler`, `assetsRemoveHandler`) have been removed. Pass a single `manager` instance instead. See [migration guide #32](../../../migration/32-use-assets-manager.md).
 
 ## Usage
 
 Open the Assets Manager as a child blade:
 
 ```typescript
-import { useBladeNavigation } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import { useBlade, useAssetsManager } from "@vc-shell/framework";
+
+const { openBlade } = useBlade();
 
-const { openBlade, resolveBladeByName } = useBladeNavigation();
+const assetsManager = useAssetsManager(product.assets, {
+  uploadPath: () => `/catalog/${product.id}`,
+  confirmRemove: () => confirm("Delete selected assets?"),
+});
 
 openBlade({
-  blade: resolveBladeByName("AssetsManager"),
+  name: "AssetsManager",
   options: {
-    assets: product.assets,
-    loading: isLoading,
+    // IMPORTANT: markRaw prevents Vue from wrapping the manager in a
+    // deep reactive proxy. Without it, blade options (stored in
+    // ref<BladeDescriptor[]>) auto-unwrap nested Refs, breaking
+    // manager.items.value and manager.loading.value access.
+    manager: markRaw(assetsManager),
     disabled: !canEdit.value,
     hiddenFields: ["sortOrder"],
-    assetsUploadHandler: async (files) => {
-      const uploaded = await uploadFiles(files);
-      return [...product.assets, ...uploaded];
-    },
-    assetsEditHandler: (assets) => {
-      product.assets = assets;
-      return assets;
-    },
-    assetsRemoveHandler: async (assets) => {
-      await deleteAssets(assets);
-      return product.assets.filter(a => !assets.includes(a));
-    },
   },
 });
 ```
 
 ## Features
 
-- **Table view**: Displays assets with thumbnail, name, size, sort order, and creation date columns.
+- **Table view**: Displays assets with thumbnail, name, size, sort order, and creation date columns using `VcDataTable` with declarative `<VcColumn>` API.
 - **Upload**: Via toolbar button or drag-and-drop onto the table. Handles duplicate filenames by appending `_1`, `_2`, etc.
 - **Delete**: Toolbar delete button (requires selection) and per-row action button.
 - **Reorder**: Drag-and-drop row reordering when not in readonly mode.
@@ -79,17 +74,18 @@ openBlade({
 | Button | Condition | Action |
 |---|---|---|
 | Add | `!disabled` | Opens file picker for upload |
-| Delete | `!disabled` and items selected | Calls `assetsRemoveHandler` with selected items |
+| Delete | `!disabled` and items selected | Calls `manager.removeMany()` with selected items |
 
 ## Tips
 
-- All mutation handlers must return the updated full asset array -- the module replaces its internal list with the return value.
+- **Always use `markRaw()` when passing manager through blade options.** Blade descriptors are stored in `ref<BladeDescriptor[]>()`, which creates a deep reactive proxy. Vue auto-unwraps `Ref` values inside reactive objects, so `manager.items` would become a plain array instead of `Ref<AssetLike[]>` — breaking `.value` access. `markRaw()` prevents this by telling Vue not to make the manager reactive.
+- The `manager` object (from `useAssetsManager()`) owns the reactive asset list and all mutation methods. The blade reads `manager.items` and calls `manager.upload()`, `manager.remove()`, `manager.removeMany()`, `manager.reorder()`, and `manager.updateItem()`.
 - The `disabled` prop makes the entire blade readonly: no upload, no delete, no reorder.
 - Asset thumbnails use `isImage()` from shared utilities to determine if an image preview or a file-type icon should be shown.
-- The module uses `useBladeNavigation()` internally to open the detail sub-blade.
+- The module uses `useBlade()` internally to open the detail sub-blade.
 
 ## Related
 
+- `framework/core/composables/useAssetsManager/` -- `useAssetsManager`, `AssetLike`, `UseAssetsManagerReturn`
 - `framework/shared/utilities/assets.ts` -- `isImage`, `getFileThumbnail`, `readableSize`
 - `framework/core/utilities/date/` -- `formatDateRelative` for creation dates
-- `framework/core/types/` -- `ICommonAsset` interface

package/runtime/knowledge/docs/shell/components/logout-button/logout-button.docs.md

@@ -1,6 +1,6 @@
 # LogoutButton
 
-Settings menu action that signs the user out, closes all open blades, and redirects to the login page. This component encapsulates the full sign-out flow: it injects `CloseSettingsMenuKey` to dismiss the parent menu before navigation, calls `useUserManagement().signOut()` to clear the authentication token, and uses `useBladeNavigation()` to close any open blades so the user does not return to stale blade state on next login.
+Settings menu action that signs the user out, closes all open blades, and redirects to the login page. This component encapsulates the full sign-out flow: it injects `CloseSettingsMenuKey` to dismiss the parent menu before navigation, calls `useUserManagement().signOut()` to clear the authentication token, and uses `useBladeStack()` to close open child blades so the user does not return to stale blade state on next login.
 
 ## When to Use
 
@@ -37,7 +37,7 @@ settingsMenu.register({
 
 ## Key Props
 
-This component has no props. It uses `useUserManagement()` for sign-out and `useBladeNavigation()` to close blades.
+This component has no props. It uses `useUserManagement()` for sign-out and `useBladeStack()` to close blades.
 
 ## Recipe: Module with Complete Settings Menu Registration
 
@@ -71,7 +71,7 @@ export default {
 ## Details
 
 - **Menu dismissal**: Before starting the sign-out flow, the component calls the injected `CloseSettingsMenuKey` function to close the dropdown. This prevents a visual artifact where the menu stays open while the page redirects.
-- **Blade cleanup**: All open blades are closed via `useBladeNavigation()` before redirecting. This avoids orphaned blade state in the navigation stack.
+- **Blade cleanup**: All open child blades are closed via `useBladeStack()` before redirecting. This avoids orphaned blade state in the navigation stack.
 - **Redirect**: After sign-out completes, the user is redirected to the `/login` route.
 - **External providers**: If the user signed in through an external SSO provider, the sign-out flow also triggers the provider's logout redirect via `useExternalProvider().signOut()`.
 

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

@@ -2,6 +2,17 @@
 
 A versatile button component supporting 9 style variants, 5 size options, loading state, and icon integration. VcButton is the primary interactive element for triggering actions throughout the application -- from toolbar buttons and form submissions to inline table actions and navigation.
 
+## When to Use
+
+| Scenario | Component |
+|----------|-----------|
+| Triggering an action (save, delete, submit) | **VcButton** |
+| Navigating to another URL or route | `<router-link>` or `<a>` tag |
+| Action inside a blade toolbar | `IBladeToolbar` items (rendered as buttons automatically) |
+| Inline text-style link within a paragraph | Native `<a>` or `<router-link>` |
+
+Use VcButton for any user-initiated action that does not navigate to a URL. **Do not use** VcButton for navigation -- the `link` variant looks like a link but calls `preventDefault()`, so actual URL navigation will not work. For toolbar actions, define `IBladeToolbar` objects instead of placing VcButton manually.
+
 ## Quick Start
 
 ```vue