@vc-shell/vc-app-skill 2.1.0-pr255.4dc5c0d → 2.1.0-pr256.0fe3abb

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.1.0-pr255.4dc5c0d",
+  "version": "2.1.0-pr256.0fe3abb",
   "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/knowledge/docs/core/api/platform.docs.md

@@ -31,9 +31,11 @@ All clients extend `AuthApiBase` and accept an optional `baseUrl` and `http` fet
 | Client                      | Description                                              |
 | --------------------------- | -------------------------------------------------------- |
 | `ExternalSignInClient`      | External authentication provider sign-in                 |
+| `AppManifestClient`         | Application manifest descriptor operations               |
 | `AppsClient`                | Application descriptor operations                        |
 | `AuthorizationClient`       | Permission and role checking                             |
 | `ChangeLogClient`           | Platform change log / audit trail                        |
+| `DeveloperToolsClient`      | Developer-tools endpoint                                 |
 | `DiagnosticsClient`         | System diagnostics and health                            |
 | `DynamicPropertiesClient`   | Dynamic property CRUD and dictionary management          |
 | `JobsClient`                | Background job management                                |
@@ -46,20 +48,20 @@ All clients extend `AuthApiBase` and accept an optional `baseUrl` and `http` fet
 
 ## Key DTOs (Interfaces)
 
-| Interface                        | Description                                                                       |
-| -------------------------------- | --------------------------------------------------------------------------------- |
-| `PushNotification`               | Push notification payload: `id`, `title`, `notifyType`, `isNew`, `finished`, etc. |
-| `PushNotificationSearchCriteria` | Search criteria for notification queries                                          |
-| `ApplicationUser`                | Platform user with roles, permissions, logins                                     |
-| `Role`                           | Security role with permissions                                                    |
-| `Permission`                     | Individual permission entry                                                       |
-| `DynamicProperty`                | Dynamic property definition                                                       |
-| `DynamicObjectProperty`          | Property value bound to an object                                                 |
-| `ModuleDescriptor`               | Module metadata (id, version, dependencies)                                       |
-| `ChangeLogSearchCriteria`        | Audit log search parameters                                                       |
-| `ChangeLogSearchResult`          | Paginated audit log results                                                       |
-| `ObjectSettingEntry`             | Setting entry with value and metadata                                             |
-| `License`                        | Platform license information                                                      |
+| Interface                        | Description                                                                      |
+| -------------------------------- | -------------------------------------------------------------------------------- |
+| `PushNotification`               | Push notification payload: `id`, `title`, `notifyType`, `isNew`, `created`, etc. |
+| `PushNotificationSearchCriteria` | Search criteria for notification queries                                         |
+| `ApplicationUser`                | Platform user with roles, permissions, logins                                    |
+| `Role`                           | Security role with permissions                                                   |
+| `Permission`                     | Individual permission entry                                                      |
+| `DynamicProperty`                | Dynamic property definition                                                      |
+| `DynamicObjectProperty`          | Property value bound to an object                                                |
+| `ModuleDescriptor`               | Module metadata (id, version, dependencies)                                      |
+| `ChangeLogSearchCriteria`        | Audit log search parameters                                                      |
+| `ChangeLogSearchResult`          | Paginated audit log results                                                      |
+| `ObjectSettingEntry`             | Setting entry with value and metadata                                            |
+| `License`                        | Platform license information                                                     |
 
 ## Base Class
 
@@ -67,7 +69,7 @@ All clients extend `AuthApiBase` and accept an optional `baseUrl` and `http` fet
 export class AuthApiBase {
   authToken: string;
   setAuthToken(token: string): void;
-  protected getBaseUrl(defaultUrl: string, baseUrl: string): string; // always returns ""
+  getBaseUrl(defaultUrl: string, baseUrl: string): string; // always returns ""
   protected transformOptions(options: RequestInit): Promise<RequestInit>; // sets the Bearer header only if `authToken` is non-empty
 }
 ```
@@ -86,7 +88,7 @@ const criteria: PushNotificationSearchCriteria = { take: 20, skip: 0 };
 const result = await client.searchPushNotification(criteria);
 
 console.log(`Found ${result.totalCount} notifications`);
-for (const notification of result.results ?? []) {
+for (const notification of result.notifyEvents ?? []) {
   console.log(`${notification.title} (${notification.notifyType})`);
 }
 ```
@@ -100,7 +102,7 @@ const securityClient = new SecurityClient();
 const user = await securityClient.getCurrentUser();
 
 console.log(`Logged in as: ${user.userName}`);
-console.log(`Roles: ${user.roles?.map((r) => r.name).join(", ")}`);
+console.log(`Permissions: ${user.permissions?.join(", ")}`);
 console.log(`Is admin: ${user.isAdministrator}`);
 ```
 
@@ -142,7 +144,7 @@ import { SettingClient, ObjectSettingEntry } from "@vc-shell/framework";
 const client = new SettingClient();
 
 // Read a specific setting
-const settings = await client.getValues(["VirtoCommerce.Notifications.SendGrid.ApiKey"]);
+const setting = await client.getGlobalSetting("VirtoCommerce.Notifications.SendGrid.ApiKey");
 
 // Update a setting
 const entry: ObjectSettingEntry = {

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

@@ -2,6 +2,7 @@
 title: Blade Navigation Composables
 category: composables
 group: blade-navigation
+internal: true
 ---
 
 # Blade Navigation Composables
@@ -27,11 +28,16 @@ Blade navigation manages an ordered stack of blade descriptors (plain data objec
 ## Exports
 
 ```typescript
-export { useBladeNavigation } from "./useBladeNavigationAdapter";
-export { createBladeStack, useBladeStack } from "./useBladeStack";
-export { createBladeMessaging, useBladeMessaging } from "./useBladeMessaging";
+export { useBladeStack } from "@core/blade-navigation/useBladeStack";
+export { useBladeMessaging } from "@core/blade-navigation/useBladeMessaging";
+export * from "@core/blade-navigation/types";
+export { __registerBladeConfig, getBladeConfig, getAllBladeConfigs } from "@core/blade-navigation/bladeConfigRegistry";
+export { useTableQueryState } from "@core/blade-navigation/table-query-state";
+export type { UseTableQueryStateReturn, TableQueryPatch } from "@core/blade-navigation/table-query-state";
 ```
 
+The `createBladeStack` / `createBladeMessaging` factories are internal (not re-exported); they are consumed directly by the framework rendering layer. `useBladeNavigation` is the adapter API documented below, which lives under `core/composables/useBladeNavigationAdapter/`, not in this package.
+
 <!-- internal:end -->
 
 ## useBladeStack
@@ -44,27 +50,28 @@ Creates a new stack instance. Called once by the navigation plugin.
 
 ### API
 
-| Method                                | Description                                                                                                                                |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `openWorkspace(event)`                | Sets the root blade (index 0). Closes all existing blades unconditionally.                                                                 |
-| `openBlade(event)`                    | Opens a child blade after a parent. Closes any blades deeper than the parent (with guard checks).                                          |
-| `closeBlade(bladeId)`                 | Closes a blade and all its children. Returns `true` if a guard prevented closing.                                                          |
-| `closeChildren(parentId)`             | Closes all blades after the given parent.                                                                                                  |
-| `replaceCurrentBlade(event)`          | Destroys the current active blade and creates a new one at the same stack index with the same `parentId`.                                  |
-| `coverCurrentBlade(event)`            | Hides the current active blade (keeps it in the stack) and opens a new blade on top. Closing the covering blade restores the hidden blade. |
-| `registerBeforeClose(bladeId, guard)` | Registers a guard function. Return `true` from the guard to PREVENT closing.                                                               |
-| `unregisterBeforeClose(bladeId)`      | Removes a close guard.                                                                                                                     |
-| `setBladeError(bladeId, error)`       | Sets an error on a blade descriptor (displayed as error banner).                                                                           |
-| `clearBladeError(bladeId)`            | Clears a blade's error.                                                                                                                    |
-| `setBladeTitle(bladeId, title)`       | Updates the blade's title in the descriptor.                                                                                               |
+| Method                                | Description                                                                                                                                        |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `openWorkspace(event)`                | Sets the root blade (index 0). Closes all existing blades unconditionally.                                                                         |
+| `openBlade(event)`                    | Opens a child blade after a parent. Closes any blades deeper than the parent (with guard checks).                                                  |
+| `closeBlade(bladeId)`                 | Closes a blade and all its children. Returns `true` if a guard prevented closing.                                                                  |
+| `closeChildren(parentId)`             | Closes all blades after the given parent.                                                                                                          |
+| `replaceCurrentBlade(event)`          | Destroys the current active blade and creates a new one at the same stack index with the same `parentId`.                                          |
+| `coverCurrentBlade(event)`            | Hides the current active blade (keeps it in the stack) and opens a new blade on top. Closing the covering blade restores the hidden blade.         |
+| `registerBeforeClose(bladeId, guard)` | Registers a guard function. Return `true` from the guard to PREVENT closing.                                                                       |
+| `unregisterBeforeClose(bladeId)`      | Removes a close guard.                                                                                                                             |
+| `setBladeError(bladeId, error)`       | Sets an error on a blade descriptor (displayed as error banner).                                                                                   |
+| `clearBladeError(bladeId)`            | Clears a blade's error.                                                                                                                            |
+| `setBladeTitle(bladeId, title)`       | Updates the blade's title in the descriptor.                                                                                                       |
+| `updateBladeQuery(bladeId, patch)`    | Merges `patch` into the blade descriptor's `query`; keys with empty-string or nullish values are removed. Backs table URL-query-state persistence. |
 
 ### Computed
 
-| Property      | Type                         | Description              |
-| ------------- | ---------------------------- | ------------------------ |
-| `workspace`   | `BladeDescriptor`            | The root blade (index 0) |
-| `blades`      | `readonly BladeDescriptor[]` | Full ordered stack       |
-| `activeBlade` | `BladeDescriptor`            | The last visible blade   |
+| Property      | Type                                        | Description              |
+| ------------- | ------------------------------------------- | ------------------------ |
+| `workspace`   | `ComputedRef<BladeDescriptor \| undefined>` | The root blade (index 0) |
+| `blades`      | `ComputedRef<readonly BladeDescriptor[]>`   | Full ordered stack       |
+| `activeBlade` | `ComputedRef<BladeDescriptor \| undefined>` | The last visible blade   |
 
 ### Composable: `useBladeStack()`
 
@@ -134,18 +141,20 @@ openBlade({
 
 The plain data object stored in the stack for each blade:
 
-| Field      | Type       | Description                                                                |
-| ---------- | ---------- | -------------------------------------------------------------------------- |
-| `id`       | `string`   | Unique instance ID (auto-generated)                                        |
-| `name`     | `string`   | Blade registration name                                                    |
-| `url`      | `string?`  | URL segment for address bar sync                                           |
-| `param`    | `unknown`  | Parameter passed when opening (e.g., entity ID)                            |
-| `query`    | `Record?`  | Query parameters                                                           |
-| `options`  | `unknown`  | Arbitrary options passed to the blade                                      |
-| `parentId` | `string?`  | ID of the parent blade                                                     |
-| `visible`  | `boolean`  | Whether the blade is rendered (false when covered via `coverCurrentBlade`) |
-| `error`    | `unknown?` | Error state for the error banner                                           |
-| `title`    | `string?`  | Dynamic title override                                                     |
+| Field         | Type                       | Description                                                                |
+| ------------- | -------------------------- | -------------------------------------------------------------------------- |
+| `id`          | `string`                   | Unique instance ID (auto-generated)                                        |
+| `name`        | `string`                   | Blade registration name                                                    |
+| `url`         | `string?`                  | URL segment for address bar sync                                           |
+| `param`       | `string?`                  | Parameter passed when opening (e.g., entity ID)                            |
+| `query`       | `Record<string, string>?`  | Query parameters                                                           |
+| `options`     | `Record<string, unknown>?` | Arbitrary options passed to the blade                                      |
+| `parentId`    | `string?`                  | ID of the parent blade                                                     |
+| `visible`     | `boolean`                  | Whether the blade is rendered (false when covered via `coverCurrentBlade`) |
+| `error`       | `unknown?`                 | Error state for the error banner                                           |
+| `title`       | `string?`                  | Dynamic title override                                                     |
+| `maximized`   | `boolean?`                 | Whether this blade is maximized (fullscreen) — set by VcBladeSlot          |
+| `breadcrumbs` | `Breadcrumbs[]?`           | Navigation breadcrumbs — set by VcBladeSlot                                |
 
 ## Tips
 
@@ -163,6 +172,6 @@ The plain data object stored in the stack for each blade:
 <!-- internal:start -->
 
 - `framework/core/composables/useBlade/` -- `useBlade()`, `useBladeContext()` (new API)
-- `framework/shell/_internal/blade-nav/plugin-v2.ts` -- plugin that creates and provides the stack/messaging
+- `framework/shell/_internal/blade-navigation/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/blade-navigation/table-query-state/useTableQueryState.docs.md

@@ -0,0 +1,95 @@
+---
+title: useTableQueryState
+category: composables
+group: data
+---
+
+# useTableQueryState
+
+Reads the table view state (`sort`, `search`, `page`) that `VcDataTable` persists to the URL query for URL-addressable blades. A list page calls `read()` in `setup` to seed its own refs from the restored state before its loader runs, so a reload makes one request.
+
+Read-only: writing the view state to the URL stays inside `VcDataTable`. This composable only exposes the restored values to the page.
+
+## When to Use
+
+- A list blade is URL-addressable (workspace or routable) and uses `VcDataTable` with a `state-key`
+- You want a single, coordinated load on reload (sort + search + page restored together)
+- You are wiring the page's combined loader watcher and need the restored seed values
+
+## When NOT to Use
+
+- The table is standalone or its blade has no URL — there is nothing to restore (`read()` returns `{}`)
+- You only need the live view state — that already lives in your own `sortField`/`searchValue`/`currentPage` refs
+- You want to _write_ to the URL — that is automatic; do not persist manually
+
+## Basic Usage
+
+```ts
+import { ref, watch } from "vue";
+import { useDataTableSort, useTableQueryState, useFunctions } from "@vc-shell/framework";
+
+const PAGE_SIZE = 20;
+const { debounce } = useFunctions();
+const { sortField, sortOrder, sortExpression } = useDataTableSort({
+  initialField: "createdDate",
+  initialDirection: "DESC",
+});
+const searchValue = ref<string>();
+const currentPage = ref(1);
+
+// Seed refs from the URL before the loader runs.
+const restored = useTableQueryState("offers_list").read();
+if (restored.sort) {
+  const [field, dir] = restored.sort.split(":");
+  sortField.value = field;
+  sortOrder.value = dir === "DESC" ? -1 : 1;
+}
+if (restored.search) searchValue.value = restored.search;
+if (restored.page) currentPage.value = restored.page;
+
+function load() {
+  return loadItems({
+    sort: sortExpression.value,
+    keyword: searchValue.value || undefined,
+    skip: (currentPage.value - 1) * PAGE_SIZE,
+  });
+}
+
+load();
+watch(searchValue, () => (currentPage.value = 1));
+watch([sortExpression, searchValue, currentPage], debounce(load, 300));
+```
+
+## API
+
+### Parameters
+
+| Parameter  | Type                  | Default     | Description                                                               |
+| ---------- | --------------------- | ----------- | ------------------------------------------------------------------------- |
+| `stateKey` | `string \| undefined` | `undefined` | The same `state-key` passed to `VcDataTable` for this table (namespacing) |
+
+### Returns
+
+| Property | Type                    | Description                                                                                            |
+| -------- | ----------------------- | ------------------------------------------------------------------------------------------------------ |
+| `read`   | `() => TableQueryPatch` | Reads the restored `{ sort?, search?, page? }` from the URL. Returns `{}` when no service is available |
+
+`TableQueryPatch`: `{ sort?: string; search?: string; page?: number }` — `sort` is a `"field:ASC"` / `"field:DESC"` expression, `page` is 1-based.
+
+## Details
+
+- **Read in `setup`**: `VcDataTable` does not emit restore events on init; the page reads the state and seeds its refs in `setup`. This avoids a separate load per restored field.
+- **No-op without a service**: When no blade provides the persistence service (standalone table, non-URL blade), `read()` returns `{}`, so you can call it unconditionally.
+- **Write-back is automatic**: View state → URL (debounced `router.replace`) is handled by `VcDataTable` via `useTableQueryPersistence`. Pages do not persist manually.
+
+## Tips
+
+- Call `read()` once, synchronously, before the loader. Seeding after it runs causes an extra load.
+- Use `useDataTablePagination`'s `setPage(n)` to seed the page without firing `onPageChange`.
+- Pass the same `state-key` you give `VcDataTable`, so the URL keys match.
+
+## Related
+
+- [`useDataTableSort`](../../../ui/composables/useDataTableSort.docs.md) — sort state composable for `VcDataTable`
+- [`useDataTablePagination`](../../../ui/composables/useDataTablePagination.docs.md) — pagination state composable (`setPage` for restore seed)
+- `VcDataTable` → _URL query persistence_ — the write-back side of this contract

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

@@ -2,6 +2,7 @@
 title: useAppBarMobileButtons
 category: composables
 group: services
+internal: true
 ---
 
 # useAppBarMobileButtons
@@ -19,7 +20,7 @@ Manages custom action buttons in the mobile app bar. Uses provide/inject to shar
 
 ```vue
 <script setup lang="ts">
-import { useAppBarMobileButtons } from "@vc-shell/framework";
+import { useAppBarMobileButtons } from "@core/composables/useAppBarMobileButtons";
 import { onUnmounted, computed, ref } from "vue";
 
 const { register, unregister } = useAppBarMobileButtons();
@@ -56,6 +57,7 @@ onUnmounted(() => unregister("notifications-btn"));
 | Field       | Type                      | Required | Description                                                                                             |
 | ----------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
 | `id`        | `string`                  | Yes      | Unique identifier. Used for register/unregister/lookup.                                                 |
+| `title`     | `string`                  | No       | Accessible name for the icon-only button (used as its `aria-label`; falls back to `id`).                |
 | `icon`      | `Component \| string`     | No       | Icon component or CSS class string (e.g., `'fas fa-bell'`).                                             |
 | `component` | `Component`               | No       | Custom Vue component to render instead of a default icon button.                                        |
 | `props`     | `Record<string, unknown>` | No       | Props passed to the custom `component`.                                                                 |
@@ -84,7 +86,7 @@ provideAppBarMobileButtonsService();
 
 ```vue
 <script setup lang="ts">
-import { useAppBarMobileButtons } from "@vc-shell/framework";
+import { useAppBarMobileButtons } from "@core/composables/useAppBarMobileButtons";
 import { ref, computed, onUnmounted } from "vue";
 
 const { register, unregister } = useAppBarMobileButtons();
@@ -111,7 +113,7 @@ If you need more than an icon and a click handler (e.g., a dropdown or popover),
 
 ```vue
 <script setup lang="ts">
-import { useAppBarMobileButtons } from "@vc-shell/framework";
+import { useAppBarMobileButtons } from "@core/composables/useAppBarMobileButtons";
 import { onUnmounted, markRaw } from "vue";
 import LanguageSwitcher from "./LanguageSwitcher.vue";
 

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

@@ -57,16 +57,18 @@ None.
 
 ### registerAppBarWidgetOptions
 
-| Field       | Type                      | Required | Description                                                   |
-| ----------- | ------------------------- | -------- | ------------------------------------------------------------- |
-| `id`        | `string`                  | No       | Custom ID; auto-generated if omitted                          |
-| `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 |
-| `props`     | `Record<string, unknown>` | No       | Props to pass to the custom component                         |
-| `onClick`   | `() => void`              | No       | Click handler for the default icon button                     |
-| `slot`      | `string`                  | No       | Named slot target for placement control                       |
+| Field         | Type                         | Required | Description                                                   |
+| ------------- | ---------------------------- | -------- | ------------------------------------------------------------- |
+| `id`          | `string`                     | No       | Custom ID; auto-generated if omitted                          |
+| `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 |
+| `props`       | `Record<string, unknown>`    | No       | Props to pass to the custom component                         |
+| `onClick`     | `() => void`                 | No       | Click handler for the default icon button                     |
+| `slot`        | `string`                     | No       | Named slot target for placement control                       |
+| `badge`       | `boolean \| (() => boolean)` | No       | Show a badge indicator; pass a getter for reactive state      |
+| `searchTerms` | `string[]`                   | No       | Extra keywords used to match the widget in hub search         |
 
 ### Additional Exports
 

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

@@ -50,9 +50,10 @@ export default router;
 
 ### Injection Key
 
-| Key                     | Type                                     | Description                                                                                            |
-| ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `AppInsightsOptionsKey` | `InjectionKey<AppInsightsPluginOptions>` | Optional. Provide this at app level with `{ appName: 'Operations Console' }` 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. |
+| `AppInsightsInstanceKey` | `InjectionKey<ApplicationInsights \| null>` | Carries the Application Insights instance that `useAppInsights` injects (returned as `appInsights`).   |
 
 ## How It Works
 
@@ -72,7 +73,8 @@ import { useAppInsights } from "@vc-shell/framework";
 const { appInsights } = useAppInsights();
 
 function trackOrderPlaced(orderId: string, total: number) {
-  appInsights.trackEvent({
+  // appInsights is null when the AI plugin is not installed
+  appInsights?.trackEvent({
     name: "OrderPlaced",
     properties: { orderId },
     measurements: { orderTotal: total },
@@ -80,7 +82,7 @@ function trackOrderPlaced(orderId: string, total: number) {
 }
 
 function trackSearchPerformed(query: string, resultCount: number) {
-  appInsights.trackEvent({
+  appInsights?.trackEvent({
     name: "SearchPerformed",
     properties: { query },
     measurements: { resultCount },

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

@@ -6,6 +6,8 @@ group: data
 
 # useAssets
 
+> **Deprecated.** `useAssets` is deprecated in favor of [`useAssetsManager(ref, options)`](../useAssetsManager/). Calling it logs a DEV console warning. This page is kept as legacy/migration guidance; new code should use `useAssetsManager`, which wraps `useAssets` with two-way sync.
+
 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.
 
 ## When to Use
@@ -32,8 +34,8 @@ async function onFilesSelected(fileList: FileList) {
   assets.value = [...assets.value, ...newAssets];
 }
 
-function onDeleteAssets(toDelete: ICommonAsset[]) {
-  assets.value = remove(toDelete, assets.value);
+function onRemoveAsset(toDelete: ICommonAsset) {
+  assets.value = remove([toDelete], assets.value);
 }
 
 function onUpdateAltText(asset: ICommonAsset, altText: string) {
@@ -47,9 +49,9 @@ function onUpdateAltText(asset: ICommonAsset, altText: string) {
     :loading="loading"
   >
     <VcGallery
-      :assets="assets"
+      :images="assets"
       @upload="onFilesSelected"
-      @delete="onDeleteAssets"
+      @remove="onRemoveAsset"
     />
   </VcBlade>
 </template>
@@ -62,7 +64,7 @@ function onUpdateAltText(asset: ICommonAsset, altText: string) {
 | Property  | Type                                                                                           | Description                                                                                                                                                          |
 | --------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `upload`  | `(files: FileList, uploadPath: string, startingSortOrder?: number) => Promise<ICommonAsset[]>` | Upload files in parallel batches (max 4 concurrent). Returns only successfully uploaded assets. Sort orders are assigned incrementally from `startingSortOrder + 1`. |
-| `remove`  | `(filesToDelete: ICommonAsset[], initialAssetArr: ICommonAsset[]) => ICommonAsset[]`           | Return a new array with deleted items removed. Matching is done by `url` field. The original array is not mutated.                                                   |
+| `remove`  | `(filesToDelete: ICommonAsset[], initialAssetArr: ICommonAsset[]) => ICommonAsset[]`           | Return a new array with deleted items removed. Matching is done by `url`. The original array is not mutated.                                                         |
 | `edit`    | `(updatedFiles: ICommonAsset[], initialAssetArr: ICommonAsset[]) => ICommonAsset[]`            | Merge updated fields into existing assets (matched by `url`). If `updatedFiles.length === initialAssetArr.length`, the entire array is replaced (reorder mode).      |
 | `loading` | `ComputedRef<boolean>`                                                                         | Whether an upload or remove operation is currently in progress.                                                                                                      |
 
@@ -130,7 +132,7 @@ async function handleUpload(files: FileList) {
 
 ## Tips
 
-- **Sort order starts from `startingSortOrder + 1`.** If you pass `startingSortOrder: 5` and upload 3 files, they get sort orders 6, 7, and 8. Pass `0` or omit it to start from 1.
+- **Sort order starts from `startingSortOrder + 1`.** If you pass `startingSortOrder: 5` and upload 3 files, they get sort orders 6, 7, and 8. Pass `0` to start from 1. Omitting `startingSortOrder` assigns `0` to every uploaded asset (no incremental ordering).
 - **Failed uploads are silently filtered.** If one file in a batch fails, the others still succeed. The returned array only contains successfully uploaded assets. Check the browser console for error logs from the `use-assets` logger.
 - **`remove` matches by `url`, not by `id`.** Assets may not have stable IDs before they are saved to the server. The `url` field is used as the matching key because it is always present after upload.
 - **Each `useAssets()` call creates an independent instance.** Unlike singleton composables, calling `useAssets()` twice gives you two separate `loading` states. This is useful if different parts of your blade upload to different paths.

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

@@ -58,7 +58,7 @@ const assets = useAssetsManager(ref, options);
 
 ```typescript
 import { useAssetsManager } from "@vc-shell/framework";
-import { toRef } from "vue";
+import { computed } from "vue";
 
 const assets = useAssetsManager(
   computed({
@@ -89,6 +89,8 @@ const assets = useAssetsManager(
 Wrap a single value in a computed array:
 
 ```typescript
+import { computed } from "vue";
+
 const photoAssets = computed({
   get: () => (user.value?.iconUrl ? [{ url: user.value.iconUrl }] : []),
   set: (val) => {

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

@@ -81,7 +81,7 @@ type AsyncAction<Payload = void, Result = void> = (payload?: Payload, ...rest: a
 
 | Property  | Type                                          | Description                                                    |
 | --------- | --------------------------------------------- | -------------------------------------------------------------- |
-| `loading` | `DeepReadonly<Ref<boolean>>`                  | Reactive loading state -- `true` while the action is executing |
+| `loading` | `Readonly<Ref<boolean>>`                      | Reactive loading state -- `true` while the action is executing |
 | `error`   | `DeepReadonly<Ref<DisplayableError \| null>>` | Reactive error -- set on failure, cleared on next invocation   |
 | `action`  | `AsyncAction<Payload, Result>`                | Wrapped function with the same signature as `innerAction`      |
 

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

@@ -2,6 +2,7 @@
 title: useBladeRegistry
 category: composables
 group: blade-navigation
+internal: true
 ---
 
 # useBladeRegistry
@@ -26,7 +27,7 @@ Internally, the registry maintains a reactive `Map<string, IBladeRegistrationDat
 ## Basic Usage
 
 ```typescript
-import { useBladeRegistry } from "@vc-shell/framework";
+import { useBladeRegistry } from "@core/composables/useBladeRegistry";
 
 const { getBlade, getBladeComponent } = useBladeRegistry();
 
@@ -61,7 +62,8 @@ const component = getBladeComponent("OrderDetails");
 
 ```typescript
 <script setup lang="ts">
-import { useBladeRegistry, useBlade } from "@vc-shell/framework";
+import { useBladeRegistry } from "@core/composables/useBladeRegistry";
+import { useBlade } from "@vc-shell/framework";
 
 const { getBlade } = useBladeRegistry();
 const { openBlade } = useBlade();
@@ -80,7 +82,7 @@ function navigateTo(bladeName: string, param?: string) {
 ### Deep link resolution
 
 ```typescript
-import { useBladeRegistry } from "@vc-shell/framework";
+import { useBladeRegistry } from "@core/composables/useBladeRegistry";
 
 const { getBladeByRoute } = useBladeRegistry();
 
@@ -105,7 +107,7 @@ resolveDeepLink("/orders"); // Same result
 
 ```typescript
 <script setup lang="ts">
-import { useBladeRegistry } from "@vc-shell/framework";
+import { useBladeRegistry } from "@core/composables/useBladeRegistry";
 
 const { registeredBladesMap } = useBladeRegistry();
 
@@ -121,7 +123,8 @@ const workspaceBlades = computed(() =>
 ### Checking permissions before navigation
 
 ```typescript
-import { useBladeRegistry, usePermissions } from "@vc-shell/framework";
+import { useBladeRegistry } from "@core/composables/useBladeRegistry";
+import { usePermissions } from "@vc-shell/framework";
 
 const { getBlade } = useBladeRegistry();
 const { hasAccess } = usePermissions();

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

@@ -82,17 +82,17 @@ Inline `useBladeWidgets([...])` is fine for one-off widgets, but extracting beco
 
 ### HeadlessWidgetDeclaration
 
-| Field       | Type                              | Required | Description                               |
-| ----------- | --------------------------------- | -------- | ----------------------------------------- |
-| `id`        | `string`                          | Yes      | Unique widget identifier                  |
-| `icon`      | `string`                          | Yes      | Icon name (e.g., `"lucide-tag"`)          |
-| `title`     | `string`                          | Yes      | i18n key or display title                 |
-| `badge`     | `Ref<number \| string>`           | No       | Badge counter value                       |
-| `loading`   | `Ref<boolean>`                    | No       | Show loading indicator                    |
-| `disabled`  | `Ref<boolean> \| boolean`         | No       | Disable the widget                        |
-| `isVisible` | `ComputedRef<boolean> \| boolean` | No       | Toggle visibility                         |
-| `onClick`   | `() => void`                      | No       | Action when widget is clicked             |
-| `onRefresh` | `() => void \| Promise<void>`     | No       | Called by `refresh(id)` or `refreshAll()` |
+| Field       | Type                                                     | Required | Description                               |
+| ----------- | -------------------------------------------------------- | -------- | ----------------------------------------- |
+| `id`        | `string`                                                 | Yes      | Unique widget identifier                  |
+| `icon`      | `string`                                                 | Yes      | Icon name (e.g., `"lucide-tag"`)          |
+| `title`     | `string`                                                 | Yes      | i18n key or display title                 |
+| `badge`     | `Ref<number \| string> \| ComputedRef<number \| string>` | No       | Badge counter value                       |
+| `loading`   | `Ref<boolean> \| ComputedRef<boolean>`                   | No       | Show loading indicator                    |
+| `disabled`  | `Ref<boolean> \| boolean`                                | No       | Disable the widget                        |
+| `isVisible` | `ComputedRef<boolean> \| Ref<boolean> \| boolean`        | No       | Toggle visibility                         |
+| `onClick`   | `() => void`                                             | No       | Action when widget is clicked             |
+| `onRefresh` | `() => void \| Promise<void>`                            | No       | Called by `refresh(id)` or `refreshAll()` |
 
 ### Returns
 
@@ -331,5 +331,5 @@ const { refreshAll } = useBladeWidgets([]);
 
 - `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
+- `VcBladeSlot` in `framework/shell/_internal/blade-navigation/components/vc-blade-slot/` -- provides `BladeDescriptorKey` to blade components
 <!-- internal:end -->

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

@@ -81,10 +81,10 @@ push({
 
 ```typescript
 <script setup lang="ts">
-import { useBreadcrumbs, useBladeContext } from "@vc-shell/framework";
+import { useBreadcrumbs, useBlade } from "@vc-shell/framework";
 
 const { push } = useBreadcrumbs();
-const { openBlade } = useBladeContext();
+const { openBlade } = useBlade();
 
 // Level 1: Catalog
 push({
@@ -183,4 +183,4 @@ onBeforeUnmount(() => remove([crumbId]));
 
 - [useBlade](../useBlade/) -- blade navigation composable
 - [VcBlade](../../../ui/components/organisms/vc-blade/) -- blade component that displays breadcrumbs
-- `framework/ui/types/form-field.ts` -- `Breadcrumbs` interface definition
+- `framework/core/types/breadcrumbs.ts` -- `Breadcrumbs` interface definition