@vc-shell/vc-app-skill 2.1.0 → 2.2.0-pr260.a8bd3a7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.1.0",
+  "version": "2.2.0-pr260.a8bd3a7",
   "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.1.0
+2.2.0

package/runtime/agents/migration-agent.md

@@ -37,8 +37,10 @@ Process topics in this order (dependencies first):
 5. `use-blade-form` — depends on correct types from nswag
 6. `blade-props-simplification` — final cleanup of reusable components
 7. `vctable-audit` — VcTable → VcDataTable component and API rewrite
-8. `icon-audit` — replace all non-lucide icons with lucide equivalents (last among mechanical manual edits)
-9. `manual-migration-audit` — catch-all manual refactors (run last to avoid overlap)
+8. `use-data-table-pagination-audit` — manual pagination boilerplate → `useDataTablePagination()`
+9. `table-url-state-audit` — opt a VcDataTable list into URL-query state (sort/search/page via `stateKey`); run after the table is on VcDataTable and pagination uses the composable
+10. `icon-audit` — replace all non-lucide icons with lucide equivalents (last among mechanical manual edits)
+11. `manual-migration-audit` — catch-all manual refactors (run last to avoid overlap)
 
 Skip topics not present in the `topics` input.
 

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 3a32dc437 on 2026-06-22T17:27:53.738Z
+Synced from framework at commit 694fdf620 on 2026-07-20T17:03:47.353Z

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

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

@@ -2,6 +2,7 @@
 title: useConnectionStatus
 category: composables
 group: ui-state
+internal: true
 ---
 
 # useConnectionStatus
@@ -18,7 +19,7 @@ Monitors the browser's network connectivity and shows a persistent notification
 
 ```vue
 <script setup lang="ts">
-import { useConnectionStatus } from "@vc-shell/framework";
+import { useConnectionStatus } from "@core/composables/useConnectionStatus";
 
 const { isOnline } = useConnectionStatus();
 </script>
@@ -69,7 +70,7 @@ When connectivity is restored, the notification is removed, the CSS class is cle
 
 ```vue
 <script setup lang="ts">
-import { useConnectionStatus } from "@vc-shell/framework";
+import { useConnectionStatus } from "@core/composables/useConnectionStatus";
 import { watch, ref } from "vue";
 
 const { isOnline } = useConnectionStatus();
@@ -125,4 +126,4 @@ html.vc-offline {
 ## Related
 
 - `@vueuse/core` `useNetwork` -- underlying browser API wrapper
-- `notification` from `@shared/components/notifications` -- the notification system used to display the offline warning
+- `notification` from `@core/notifications/notification` -- the notification system used to display the offline warning

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

@@ -55,6 +55,7 @@ const { getPropertyValue, setPropertyValue, loadDictionaries, loadMeasurements,
 | `value`           | `string \| IBasePropertyValue[] \| (IBasePropertyDictionaryItem & { value: string })[]` | The new value. Type depends on property configuration.      |
 | `dictionary`      | `IBasePropertyDictionaryItem[]?`                                                        | Dictionary items. Required when setting a dictionary value. |
 | `locale`          | `string?`                                                                               | Current locale for multilanguage properties.                |
+| `initialProp`     | `IBaseProperty?`                                                                        | Original property snapshot, used to reconcile prior values. |
 | `unitOfMeasureId` | `string?`                                                                               | Unit of measure ID for measure-type properties.             |
 | `colorCode`       | `string?`                                                                               | Color hex code for color-type properties.                   |
 

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

@@ -59,9 +59,9 @@ initOnce(); // still returns cached result
 ## How They Work
 
 - **debounce**: Uses `setTimeout` / `clearTimeout` internally. Each call clears the previous timeout and starts a new one. The function only fires when there is a pause of at least `delay` ms between calls.
-- **throttle**: Uses a `Date.now()` timestamp check. The first call fires immediately and records the timestamp. Subsequent calls are silently dropped until enough time has passed.
+- **throttle**: Uses a `wasThrottled` boolean flag. The first call fires immediately and sets the flag; a `setTimeout` clears the flag after `delay` ms. Calls within that window are silently dropped.
 - **delay**: A simple wrapper around `setTimeout`. Useful for readability when you want to express "do X after Y ms" without creating a raw timeout.
-- **once**: Wraps the function with a boolean guard. After the first call, the result is cached and the original function reference is never called again.
+- **once**: Caches the result in a module-level `WeakMap` keyed by the wrapped function. The first call invokes the function and stores its result; every later call returns the stored value via the map and never re-invokes.
 
 ## Recipe: Debounced Search in a Blade Toolbar
 
@@ -111,7 +111,7 @@ function onSearchInput(value: string) {
 
 - **No cancellation API.** Unlike `@vueuse/core`'s `useDebounceFn`, the `debounce` here does not return a cancel method. If you need to cancel a pending debounce on component unmount, use VueUse instead or manually clear the timeout.
 - **Throttle uses leading-edge firing.** The first call always executes immediately. If you need trailing-edge throttle (fire after the window closes), this implementation does not support it -- use lodash `throttle` with `{ trailing: true }` instead.
-- **`once` caches even `undefined` results.** If the wrapped function returns `undefined`, subsequent calls still skip execution and return `undefined`. The guard is based on "has it been called", not "did it return a truthy value".
+- **`once` caches even `undefined` results.** If the wrapped function returns `undefined`, subsequent calls still skip execution and return `undefined`. Caching is based on the WeakMap having an entry for the function ("has it been called"), not on whether the result was truthy.
 - **`delay(fn, 0)` is not the same as `nextTick`.** `delay` uses `setTimeout(fn, 0)`, which defers to the next macrotask. Vue's `nextTick` defers to the next microtask, which fires sooner. Use `nextTick` for DOM update timing.
 
 ## Related