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

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

@@ -2,6 +2,7 @@
 title: useKeyboardNavigation
 category: composables
 group: ui-state
+internal: true
 ---
 
 # useKeyboardNavigation
@@ -20,8 +21,8 @@ The composable supports two attachment modes: **auto-attach** on mount via a CSS
 
 ```vue
 <script setup lang="ts">
-import { useKeyboardNavigation } from "@vc-shell/framework";
-import { ref } from "vue";
+import { useKeyboardNavigation } from "@core/composables/useKeyboardNavigation";
+import { ref, nextTick } from "vue";
 
 const menuRef = ref<HTMLElement | null>(null);
 const items = ref(["Dashboard", "Products", "Orders", "Settings"]);
@@ -112,7 +113,7 @@ Auto-attach happens in `onMounted`: if `containerSelector` is set and a matching
 
 ```vue
 <script setup lang="ts">
-import { useKeyboardNavigation } from "@vc-shell/framework";
+import { useKeyboardNavigation } from "@core/composables/useKeyboardNavigation";
 import { ref, watch, nextTick } from "vue";
 
 const dropdownRef = ref<HTMLElement | null>(null);
@@ -180,7 +181,7 @@ function selectSuggestion(value: string) {
 - **Items are re-queried on every key press.** This means dynamically added or removed items are picked up automatically. You do not need to re-initialize after the list changes.
 - **`loop: false` stops at boundaries.** When looping is disabled, pressing ArrowDown on the last item or ArrowUp on the first item does nothing. This is appropriate for linear navigation patterns.
 - **Clean up if you manually init.** While auto-attached listeners are cleaned up on `onBeforeUnmount`, if you call `initKeyboardNavigation` on a dynamic element, call `cleanupKeyboardNavigation` when that element is removed.
-- **Tab key is intercepted.** The composable handles Tab/Shift+Tab within the container, moving focus between items rather than leaving the container. This follows the WAI-ARIA composite widget pattern.
+- **Tab moves the focused index but is not trapped.** Tab/Shift+Tab advances the composable's focused item, but it does not call `preventDefault`, so the browser's native Tab behavior still applies and focus can leave the container. This follows the WAI-ARIA composite widget pattern.
 
 ## Related
 

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

@@ -67,9 +67,9 @@ None.
 | `currentLocale`          | `ComputedRef<string>`                        | The currently active locale code (e.g., `"en-US"`, `"de-DE"`).                                                                                                                                                                                                                  |
 | `setLocale`              | `(locale: string) => void`                   | Switches the application locale. This updates `vue-i18n`'s locale and triggers re-rendering of all translated text.                                                                                                                                                             |
 | `getLocaleByTag`         | `(localeTag: string) => string \| undefined` | Resolves a locale tag to its native display name. Regional tags stay distinct (e.g., `"en-US"` → `"American English"`, `"en-GB"` → `"British English"`); plain codes resolve to the base native name (`"fr"` → `"Français"`). Returns `undefined` if the tag is not recognized. |
-| `resolveCamelCaseLocale` | `(locale: string) => string`                 | Converts a locale code to camelCase format (e.g., `"en-US"` to `"enUs"`). Useful for dynamic property access on objects keyed by locale.                                                                                                                                        |
+| `resolveCamelCaseLocale` | `(locale: string) => string`                 | Normalizes and validates a locale code to a supported hyphenated lowercase locale (e.g., `"enUS"` to `"en-us"`), falling back to `"en"` if the locale is not supported. Delegates to `resolveSupportedLocale`.                                                                  |
 | `getFlag`                | `(language: string) => Promise<string>`      | Fetches a flag image URL for the given language/locale. Returns a promise because flags may be loaded lazily.                                                                                                                                                                   |
-| `getCountryCode`         | `(language: string) => string`               | Extracts the country code from a language tag (e.g., `"en-US"` to `"US"`, `"de-DE"` to `"DE"`).                                                                                                                                                                                 |
+| `getCountryCode`         | `(language: string) => string`               | Extracts the lowercase country code from a language tag (e.g., `"en-US"` to `"us"`, `"de-DE"` to `"de"`). Falls back to `"xx"` for unknown languages.                                                                                                                           |
 
 ### Additional Exports
 
@@ -149,7 +149,7 @@ const displayValue = computed(() => getPropertyValue(property.value, currentLoca
 - **`setLocale` triggers a full re-render of translated text.** This is expected behavior from Vue I18n. If your app has many translated strings, the switch may cause a brief layout recalculation. There is no way to avoid this.
 - **`getFlag` is async.** Flag images may be loaded from a CDN or bundled as lazy imports. Always await the result before using it in templates.
 - **Fallback singleton is not reactive to injection changes.** If `provideLanguages()` is called after `useLanguages()` was already invoked outside an injection context, the fallback instance is not replaced. This is rarely an issue in practice since `provideLanguages()` runs before module installation.
-- **`resolveCamelCaseLocale` is useful for object property access.** Platform API responses sometimes key multilanguage data by camelCase locale (e.g., `{ enUs: "Hello", deDe: "Hallo" }`).
+- **`resolveCamelCaseLocale` normalizes locale codes.** It returns a supported hyphenated lowercase locale (e.g., `"enUS"` -> `"en-us"`), or `"en"` when the locale is not supported. Despite the name, it does not produce camelCase output.
 
 ## Related
 

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

@@ -37,6 +37,8 @@ const combinedLoading = useLoading(loadingA, loadingB, loadingC);
 | ---------------------- | ------------------------------------------------------------------------------------------------------ |
 | `ComputedRef<boolean>` | `true` if any of the input refs is `true`, `false` otherwise. Re-evaluates whenever any input changes. |
 
+The module also exports a shape-helper interface `HasLoading` (`{ loading: Readonly<Ref<boolean>> }`), for typing objects that expose a readonly `loading` ref. It is not part of `useLoading`'s call signature.
+
 <!-- internal:start -->
 
 ## How It Works

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

@@ -58,8 +58,7 @@ resetModificationState(); // currentValue becomes the new pristine baseline
 ```vue
 <script setup lang="ts">
 import { ref, watch } from "vue";
-import { useModificationTracker } from "@vc-shell/framework";
-import { useBeforeUnload } from "@vueuse/core";
+import { useModificationTracker, useBeforeUnload } from "@vc-shell/framework";
 
 // Simulate API data loaded into a ref
 const apiData = ref({ name: "Widget A", price: 19.99, tags: ["sale"] });

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

@@ -78,7 +78,7 @@ For the canonical blade-side example and the registration of notification types
 
 4. **Module notifications**: The `moduleNotifications` computed filters the store's real-time queue for items that are new (`isNew: true`) and match the subscribed types.
 
-5. **History**: `loadFromHistory` delegates to the store, which fetches from the platform API and merges into the local history.
+5. **History**: `loadFromHistory` delegates to `store.loadHistory`, which fetches a page from the platform API and replaces the local history with the result (`take` controls page size, default 10). It does not merge with or page onto existing entries.
 
 ## Recipe: Notification Panel with Real-Time Updates
 

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

@@ -130,13 +130,13 @@ Use `hasAccess` in a blade component to redirect users who lack the required per
 
 ```typescript
 <script setup lang="ts">
-import { usePermissions, useBladeContext } from "@vc-shell/framework";
+import { usePermissions, useBlade } from "@vc-shell/framework";
 
 const { hasAccess } = usePermissions();
-const { closeSelf } = useBladeContext();
+const { closeSelf } = useBlade();
 
 if (!hasAccess("order:read")) {
-  closeSelf();
+  await closeSelf(); // returns Promise<boolean>
   return;
 }
 </script>

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

@@ -2,6 +2,7 @@
 title: usePlatformLocaleSync
 category: composables
 group: user
+internal: true
 ---
 
 # usePlatformLocaleSync

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

@@ -62,7 +62,7 @@ async function deleteProduct(id: string) {
 
 | Field       | Type                                          | Required | Description                                                               |
 | ----------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------- |
-| `component` | `ComponentPublicInstanceConstructor`          | Yes      | The popup component to render                                             |
+| `component` | `T` (`extends Component`)                     | Yes      | The popup component to render                                             |
 | `props`     | `RawProps<T>`                                 | No       | Props to pass to the component (typed from the component's `defineProps`) |
 | `emits`     | `RawEmits<T>`                                 | No       | Event handlers (typed from the component's `defineEmits`)                 |
 | `slots`     | `Record<string, string \| Component \| Slot>` | No       | Named slots — strings render as text, components render as VNodes         |

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

@@ -50,12 +50,12 @@ None. The composable reads breakpoint state from the framework's provide/inject
 | Property    | Type           | Default | Description                                                           |
 | ----------- | -------------- | ------- | --------------------------------------------------------------------- |
 | `isMobile`  | `Ref<boolean>` | `false` | `true` when viewport width < 1024px                                   |
-| `isDesktop` | `Ref<boolean>` | `true`  | `true` when viewport width >= 1024px                                  |
+| `isDesktop` | `Ref<boolean>` | `true`  | `true` when viewport width > 1024px                                   |
 | `isPhone`   | `Ref<boolean>` | `false` | `true` when viewport width < 480px                                    |
 | `isTablet`  | `Ref<boolean>` | `false` | `true` when 480px <= viewport width < 1024px                          |
 | `isTouch`   | `boolean`      | `false` | `true` on touch-capable devices (not reactive — set once at app init) |
 
-Breakpoint thresholds: phone < 480px, tablet 480–1023px, desktop >= 1024px. These match the framework's `setupBreakpoints()` configuration.
+Breakpoint thresholds: phone < 480px, tablet 480–1023px, desktop > 1024px (bound to `bp.greater("desktop")`, strictly greater than 1024px). These match the framework's `setupBreakpoints()` configuration.
 
 Note: `isMobile` is the union of `isPhone` and `isTablet` — it covers all viewports below the desktop threshold.
 

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

@@ -104,10 +104,11 @@ applySettings({
 
 ```vue
 <script setup lang="ts">
+import { watch } from "vue";
 import { useSettings } from "@vc-shell/framework";
 import { useUserManagement } from "@vc-shell/framework";
 
-const { uiSettings } = useSettings();
+const { uiSettings, applySettings } = useSettings();
 const { user } = useUserManagement();
 
 // Apply user-specific settings after login

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

@@ -41,6 +41,18 @@ const items = settingsMenu.items.value;
 | `unregister` | `(id: string) => void`                                 | Remove a settings menu item by ID                    |
 | `items`      | `ComputedRef<ISettingsMenuItem[]>`                     | Reactive array of all registered settings menu items |
 
+### RegisterSettingsMenuItemOptions
+
+| Field       | Type                      | Required | Description                                                              |
+| ----------- | ------------------------- | -------- | ------------------------------------------------------------------------ |
+| `id`        | `string`                  | No       | Item ID. If omitted, a UUID is generated and returned from `register()`. |
+| `order`     | `number`                  | No       | Sort order. Defaults to the current registry size (appended at the end). |
+| `group`     | `string`                  | No       | Group key used to cluster related items.                                 |
+| `component` | `Component`               | Yes      | Component rendered for this item. Wrapped in `markRaw()` internally.     |
+| `props`     | `Record<string, unknown>` | No       | Props passed to the component.                                           |
+
+There is no `title` or `icon` field; the registered component is responsible for rendering its own label and icon.
+
 ### Related Exports
 
 | Export                  | Description                                        |
@@ -58,11 +70,9 @@ const settingsMenu = useSettingsMenu();
 
 const itemId = settingsMenu.register({
   id: "notification-preferences",
-  title: "Notifications",
-  icon: "fas fa-bell",
   component: NotificationSettingsPage,
   group: "General",
-  priority: 10,
+  order: 10,
 });
 ```
 
@@ -77,29 +87,23 @@ const settingsMenu = useSettingsMenu();
 // Group related settings under a common section
 settingsMenu.register({
   id: "catalog-general",
-  title: "General",
-  icon: "lucide-settings",
   component: markRaw(CatalogGeneralSettings),
   group: "Catalog",
-  priority: 1,
+  order: 1,
 });
 
 settingsMenu.register({
   id: "catalog-seo",
-  title: "SEO Settings",
-  icon: "lucide-search",
   component: markRaw(CatalogSeoSettings),
   group: "Catalog",
-  priority: 2,
+  order: 2,
 });
 
 settingsMenu.register({
   id: "catalog-import-export",
-  title: "Import / Export",
-  icon: "lucide-arrow-left-right",
   component: markRaw(CatalogImportExportSettings),
   group: "Catalog",
-  priority: 3,
+  order: 3,
 });
 ```
 
@@ -112,11 +116,9 @@ import { onBeforeUnmount } from "vue";
 const settingsMenu = useSettingsMenu();
 const itemId = settingsMenu.register({
   id: "my-settings",
-  title: "My Module Settings",
-  icon: "lucide-wrench",
   component: markRaw(MySettingsPage),
   group: "Modules",
-  priority: 10,
+  order: 10,
 });
 
 onBeforeUnmount(() => {
@@ -136,11 +138,9 @@ const { hasAccess } = usePermissions();
 if (hasAccess("catalog:manage")) {
   settingsMenu.register({
     id: "catalog-advanced",
-    title: "Advanced Catalog Settings",
-    icon: "lucide-settings-2",
     component: markRaw(AdvancedCatalogSettings),
     group: "Catalog",
-    priority: 99,
+    order: 99,
   });
 }
 ```

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

@@ -87,10 +87,10 @@ provideSidebarState();
 ```vue
 <script setup lang="ts">
 import { useSidebarState } from "@vc-shell/framework";
-import { useBladeContext } from "@vc-shell/framework";
+import { useBlade } from "@vc-shell/framework";
 
 const { closeMenu, isMenuOpen } = useSidebarState();
-const { openBlade } = useBladeContext();
+const { openBlade } = useBlade();
 
 async function navigateToProducts() {
   // Close the mobile menu first so it does not overlay the new blade
@@ -99,7 +99,7 @@ async function navigateToProducts() {
   }
 
   await openBlade({
-    component: ProductListBlade,
+    name: "ProductList",
     param: { catalogId: "default" },
   });
 }

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

@@ -2,6 +2,7 @@
 title: useSlowNetworkDetection
 category: composables
 group: ui-state
+internal: true
 ---
 
 # useSlowNetworkDetection
@@ -23,7 +24,7 @@ The composable is initialized automatically at app startup. To reactively read t
 
 ```vue
 <script setup lang="ts">
-import { useSlowNetworkDetection } from "@vc-shell/framework";
+import { useSlowNetworkDetection } from "@core/composables/useSlowNetworkDetection";
 
 const { isSlowNetwork } = useSlowNetworkDetection();
 </script>
@@ -54,7 +55,11 @@ const { isSlowNetwork } = useSlowNetworkDetection();
 | `trackRequest`   | `(id: string) => void`   | Start tracking a request. If it isn't untracked within 10 s, it counts as slow. |
 | `untrackRequest` | `(id: string) => void`   | Stop tracking a request. Cancels the timer or decrements the slow count.        |
 
-### Constants
+<!-- internal:start -->
+
+### Internal Constants
+
+These are module-private `const` declarations, not exported symbols — do not `import` them. They document the thresholds baked into the composable.
 
 | Name                        | Value               | Purpose                                             |
 | --------------------------- | ------------------- | --------------------------------------------------- |
@@ -62,8 +67,6 @@ const { isSlowNetwork } = useSlowNetworkDetection();
 | `DISMISS_DELAY_MS`          | `3000`              | Delay before hiding the notification after recovery |
 | `SLOW_EFFECTIVE_TYPES`      | `["slow-2g", "2g"]` | Connection types flagged as slow                    |
 
-<!-- internal:start -->
-
 ## How It Works
 
 ### Channel 1: effectiveType (proactive)
@@ -88,7 +91,7 @@ The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequ
 ```vue
 <script setup lang="ts">
 import { watch } from "vue";
-import { useSlowNetworkDetection } from "@vc-shell/framework";
+import { useSlowNetworkDetection } from "@core/composables/useSlowNetworkDetection";
 
 const { isSlowNetwork } = useSlowNetworkDetection();
 
@@ -109,7 +112,7 @@ watch(isSlowNetwork, (slow) => {
 If you bypass the standard fetch interceptor (e.g., direct `XMLHttpRequest` or third-party SDK), you can manually track the request:
 
 ```ts
-import { useSlowNetworkDetection } from "@vc-shell/framework";
+import { useSlowNetworkDetection } from "@core/composables/useSlowNetworkDetection";
 
 const { trackRequest, untrackRequest } = useSlowNetworkDetection();
 
@@ -168,4 +171,4 @@ trackRequest("my-request-2");
 
 - [`useConnectionStatus`](../useConnectionStatus/useConnectionStatus.docs.md) — offline detection (binary online/offline)
 - [`registerInterceptors`](https://github.com/VirtoCommerce/vc-shell/blob/main/framework/core/interceptors/index.ts) — the fetch wrapper that calls `trackRequest`/`untrackRequest`
-- `notification` from `@shared/components/notifications` — the notification system used to display the warning
+- `notification` from `@core/notifications/notification` — the notification system used to display the warning

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

@@ -6,7 +6,7 @@ group: ui-state
 
 # useTheme
 
-Manages color theme registration, switching, and persistence. Themes are applied via a `data-theme` attribute on `<html>`, and the active theme key is persisted to localStorage via `@vueuse/core`'s `useColorMode`. The composable maintains a global registry of theme definitions, supports runtime registration/unregistration from modules, and provides both explicit (`setTheme`) and sequential (`next`) theme switching. A default `"light"` theme is always registered out of the box.
+Manages color theme registration, switching, and persistence. Themes are applied via a `data-theme` attribute on `<html>`, and the active theme key is persisted to localStorage via `@vueuse/core`'s `useColorMode`. The composable maintains a global registry of theme definitions, supports runtime registration/unregistration from modules, and provides both explicit (`setTheme`) and sequential (`next`) theme switching. Both `"light"` and `"dark"` themes are registered out of the box.
 
 ## When to Use
 
@@ -23,13 +23,13 @@ import { useTheme } from "@vc-shell/framework";
 
 const { themes, currentThemeKey, currentLocalizedName, next, setTheme, register } = useTheme();
 
-// Register a dark theme from your module
-register({ key: "dark", localizationKey: "CORE.THEMES.DARK" });
+// light and dark are registered by default; register a custom theme from your module
+register({ key: "ocean", localizationKey: "MY_MODULE.THEMES.OCEAN" });
 
 // Switch to it explicitly
-setTheme("dark");
+setTheme("ocean");
 
-// Or cycle through all registered themes (light -> dark -> light -> ...)
+// Or cycle through all registered themes (light -> dark -> ocean -> light -> ...)
 next();
 </script>
 
@@ -47,9 +47,9 @@ next();
 
 | Property               | Type                                                     | Description                                                                                                               |
 | ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `themes`               | `ComputedRef<DisplayTheme[]>`                            | All registered themes with their `key` and localized `name`. Reactive -- updates when themes are registered/unregistered. |
+| `themes`               | `Ref<DisplayTheme[]>`                                    | All registered themes with their `key` and localized `name`. Reactive -- updates when themes are registered/unregistered. |
 | `currentThemeKey`      | `Ref<string>`                                            | Active theme key (e.g., `"light"`, `"dark"`). Two-way reactive -- setting it switches the theme.                          |
-| `currentLocalizedName` | `ComputedRef<string>`                                    | Localized display name of the active theme (e.g., "Light", "Dark"). Falls back to capitalized key.                        |
+| `currentLocalizedName` | `Ref<string>`                                            | Localized display name of the active theme (e.g., "Light", "Dark"). Falls back to capitalized key.                        |
 | `next`                 | `() => void`                                             | Cycle to the next registered theme in order. Wraps around at the end.                                                     |
 | `setTheme`             | `(themeKey: string) => void`                             | Switch to a specific registered theme. Logs a warning if the key is not registered.                                       |
 | `register`             | `(themes: ThemeDefinition \| ThemeDefinition[]) => void` | Add one or more themes to the global registry. Duplicates (by key) are silently ignored.                                  |

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

@@ -326,20 +326,26 @@ function helperFunction() {
 | `isToolbarItemRegistered` | `(id: string) => boolean`                                                      | Check if a toolbar item with the given ID exists               |
 | `registeredToolbarItems`  | `IToolbarRegistration[]`                                                       | All registered toolbar items across all blades                 |
 
+### Additional Exports
+
+| Export                    | Description                                                                                                                                             |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `provideToolbarService()` | Creates and provides the toolbar service via Vue injection. Idempotent -- returns existing service if already provided. Cleans up via `onScopeDispose`. |
+
 ### IToolbarItem
 
-| Property       | Type                                                                       | Required | Description                                                    |
-| -------------- | -------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
-| `id`           | `string`                                                                   | Yes      | Unique identifier for the button                               |
-| `title`        | `string \| Ref<string> \| ComputedRef<string>`                             | No       | Button label (supports reactive values)                        |
-| `icon`         | `string \| (() => string)`                                                 | No       | Icon class (e.g., `"fas fa-save"`) or a function returning one |
-| `clickHandler` | `(app?) => void`                                                           | No       | Click callback                                                 |
-| `disabled`     | `boolean \| ComputedRef<boolean>`                                          | No       | Whether the button is disabled                                 |
-| `isVisible`    | `boolean \| Ref<boolean> \| ComputedRef<boolean> \| ((blade?) => boolean)` | No       | Controls button visibility                                     |
-| `priority`     | `number`                                                                   | No       | Sort order (higher = displayed first, default `0`)             |
-| `separator`    | `"left" \| "right" \| "both"`                                              | No       | Adds a visual divider next to the button                       |
-| `permissions`  | `string \| string[]`                                                       | No       | Required permission(s) to display the button                   |
-| `bladeId`      | `string`                                                                   | No       | Target blade ID (auto-resolved from context)                   |
+| Property       | Type                                                                                                              | Required | Description                                                    |
+| -------------- | ----------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
+| `id`           | `string`                                                                                                          | Yes      | Unique identifier for the button                               |
+| `title`        | `string \| Ref<string> \| ComputedRef<string>`                                                                    | No       | Button label (supports reactive values)                        |
+| `icon`         | `string \| (() => string)`                                                                                        | No       | Icon class (e.g., `"fas fa-save"`) or a function returning one |
+| `clickHandler` | `(app?) => void`                                                                                                  | No       | Click callback                                                 |
+| `disabled`     | `boolean \| ComputedRef<boolean \| undefined>`                                                                    | No       | Whether the button is disabled                                 |
+| `isVisible`    | `boolean \| Ref<boolean \| undefined> \| ComputedRef<boolean \| undefined> \| ((blade?) => boolean \| undefined)` | No       | Controls button visibility                                     |
+| `priority`     | `number`                                                                                                          | No       | Sort order (higher = displayed first, default `0`)             |
+| `separator`    | `"left" \| "right" \| "both"`                                                                                     | No       | Adds a visual divider next to the button                       |
+| `permissions`  | `string \| string[]`                                                                                              | No       | Required permission(s) to display the button                   |
+| `bladeId`      | `string`                                                                                                          | No       | Target blade ID (auto-resolved from context)                   |
 
 `IToolbarItem` is the shape consumed by `ToolbarService`. The blade-level array binding uses `IBladeToolbar` (see [Core types](../../types/)), a near-identical shape that the framework normalizes into `IToolbarItem` before render.
 

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

@@ -60,7 +60,7 @@ None.
 
 | Property          | Type                                   | Description                                                                                                                                                                                      |
 | ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `user`            | `ComputedRef<UserDetail \| undefined>` | Current user details (userName, email, id, etc.), or `undefined` if not authenticated.                                                                                                           |
+| `user`            | `ComputedRef<UserDetail \| undefined>` | Current user details (userName, id, permissions, isAdministrator, etc.), or `undefined` if not authenticated.                                                                                    |
 | `loading`         | `ComputedRef<boolean>`                 | Whether a user operation (loadUser, signOut) is in progress.                                                                                                                                     |
 | `isAuthenticated` | `ComputedRef<boolean>`                 | Whether a user session is active. Derived from `user.userName != null`.                                                                                                                          |
 | `isAdministrator` | `ComputedRef<boolean \| undefined>`    | Whether the current user has admin privileges. `undefined` if user is not loaded.                                                                                                                |
@@ -118,7 +118,7 @@ router.beforeEach(async (to) => {
     />
     <div>
       <p class="tw-text-sm tw-font-medium">{{ user?.userName }}</p>
-      <p class="tw-text-xs tw-text-gray-500">{{ user?.email }}</p>
+      <p class="tw-text-xs tw-text-gray-500">{{ user?.id }}</p>
     </div>
     <VcButton
       size="sm"

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

@@ -75,21 +75,21 @@ None.
 
 ### Returns
 
-| Property               | Type                                                                                 | Description                                                                                                                                                                                                                                |
-| ---------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `user`                 | `ComputedRef<UserDetail \| undefined>`                                               | Current user details.                                                                                                                                                                                                                      |
-| `loading`              | `ComputedRef<boolean>`                                                               | Whether any operation is in progress.                                                                                                                                                                                                      |
-| `isAdministrator`      | `ComputedRef<boolean \| undefined>`                                                  | Admin status of the current user.                                                                                                                                                                                                          |
-| `isAuthenticated`      | `ComputedRef<boolean>`                                                               | Whether user session is active.                                                                                                                                                                                                            |
-| `signIn`               | `(username: string, password: string) => Promise<SignInResult>`                      | Authenticates with username/password. Performs cookie-based login, obtains an OAuth token with offline_access scope, and loads user details. Returns `{ succeeded: true }` on success or `{ succeeded: false, error: string }` on failure. |
-| `signOut`              | `() => Promise<void>`                                                                | Clears session, auth data, and localStorage. Handles both standard and external SSO sign-out.                                                                                                                                              |
-| `loadUser`             | `() => Promise<UserDetail>`                                                          | Loads/reloads user info from the server. Deduplicates concurrent calls.                                                                                                                                                                    |
-| `validateToken`        | `(userId: string, token: string) => Promise<boolean>`                                | Validates a password-reset token. Returns `true` if valid.                                                                                                                                                                                 |
-| `validatePassword`     | `(password: string) => Promise<IdentityResult>`                                      | Validates a password against the platform's password policy (length, complexity, etc.).                                                                                                                                                    |
-| `resetPasswordByToken` | `(userId: string, password: string, token: string) => Promise<SecurityResult>`       | Resets a user's password using a reset token. Returns `{ succeeded: true }` on success.                                                                                                                                                    |
-| `requestPasswordReset` | `(loginOrEmail: string) => Promise<RequestPasswordResult>`                           | Sends a password-reset email to the user. Returns `{ succeeded: true }` on success.                                                                                                                                                        |
-| `changeUserPassword`   | `(oldPassword: string, newPassword: string) => Promise<SecurityResult \| undefined>` | Changes the current user's password. Requires the old password for verification.                                                                                                                                                           |
-| `getLoginType`         | `() => Promise<LoginType[]>`                                                         | Returns available login types (password-based, external SSO providers, etc.). Used to render the appropriate sign-in UI.                                                                                                                   |
+| Property               | Type                                                                                                   | Description                                                                                                                                                                                                                                |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `user`                 | `ComputedRef<UserDetail \| undefined>`                                                                 | Current user details.                                                                                                                                                                                                                      |
+| `loading`              | `ComputedRef<boolean>`                                                                                 | Whether any operation is in progress.                                                                                                                                                                                                      |
+| `isAdministrator`      | `ComputedRef<boolean \| undefined>`                                                                    | Admin status of the current user.                                                                                                                                                                                                          |
+| `isAuthenticated`      | `ComputedRef<boolean>`                                                                                 | Whether user session is active.                                                                                                                                                                                                            |
+| `signIn`               | `(username: string, password: string) => Promise<SignInResult \| { succeeded: boolean; error?: any }>` | Authenticates with username/password. Performs cookie-based login, obtains an OAuth token with offline_access scope, and loads user details. Returns `{ succeeded: true }` on success or `{ succeeded: false, error: string }` on failure. |
+| `signOut`              | `() => Promise<void>`                                                                                  | Clears session, auth data, and localStorage. Handles both standard and external SSO sign-out.                                                                                                                                              |
+| `loadUser`             | `() => Promise<UserDetail>`                                                                            | Loads/reloads user info from the server. Deduplicates concurrent calls.                                                                                                                                                                    |
+| `validateToken`        | `(userId: string, token: string) => Promise<boolean>`                                                  | Validates a password-reset token. Returns `true` if valid.                                                                                                                                                                                 |
+| `validatePassword`     | `(password: string) => Promise<IdentityResult>`                                                        | Validates a password against the platform's password policy (length, complexity, etc.).                                                                                                                                                    |
+| `resetPasswordByToken` | `(userId: string, password: string, token: string) => Promise<SecurityResult>`                         | Resets a user's password using a reset token. Returns `{ succeeded: true }` on success.                                                                                                                                                    |
+| `requestPasswordReset` | `(loginOrEmail: string) => Promise<RequestPasswordResult>`                                             | Sends a password-reset email to the user. Returns `{ succeeded: true }` on success.                                                                                                                                                        |
+| `changeUserPassword`   | `(oldPassword: string, newPassword: string) => Promise<SecurityResult \| undefined>`                   | Changes the current user's password. Requires the old password for verification.                                                                                                                                                           |
+| `getLoginType`         | `() => Promise<LoginType[]>`                                                                           | Returns available login types (password-based, external SSO providers, etc.). Used to render the appropriate sign-in UI.                                                                                                                   |
 
 ## How It Works
 
@@ -139,7 +139,7 @@ async function handleReset() {
   // Validate against password policy
   const validation = await validatePassword(newPassword.value);
   if (!validation.succeeded) {
-    error.value = validation.errors?.join(", ") ?? "Password does not meet requirements.";
+    error.value = validation.errors?.map((e) => e.description).join(", ") ?? "Password does not meet requirements.";
     return;
   }
 
@@ -167,7 +167,7 @@ const showPasswordForm = ref(false);
 onMounted(async () => {
   loginTypes.value = await getLoginType();
   // Show password form only if password auth is available
-  showPasswordForm.value = loginTypes.value.some((t) => t.loginProvider === "password");
+  showPasswordForm.value = loginTypes.value.some((t) => t.hasLoginForm);
 });
 </script>
 
@@ -181,10 +181,10 @@ onMounted(async () => {
     </form>
 
     <div
-      v-for="provider in loginTypes.filter((t) => t.loginProvider !== 'password')"
-      :key="provider.loginProvider"
+      v-for="provider in loginTypes.filter((t) => !t.hasLoginForm)"
+      :key="provider.authenticationType"
     >
-      <VcButton @click="redirectToSSO(provider)"> Sign in with {{ provider.loginProvider }} </VcButton>
+      <VcButton @click="redirectToSSO(provider)"> Sign in with {{ provider.authenticationType }} </VcButton>
     </div>
   </div>
 </template>

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

@@ -6,7 +6,7 @@ group: services
 
 # useWidgets
 
-Provides access to the `IWidgetService` singleton for managing blade widget registrations, activation state, and external widgets. This is the low-level composable for direct widget service interaction. It exposes the full widget lifecycle API: registering widgets to specific blades, querying registered widgets, tracking active widget state, and managing external (cross-module) widget registrations.
+Provides access to the `IWidgetService` singleton for managing blade widget registrations and external widgets. This is the low-level composable for direct widget service interaction. It exposes the widget lifecycle API: registering widgets to specific blades, querying and updating registered widgets, and managing external (cross-module) widget registrations.
 
 Also exports `provideWidgetService()` for framework-level initialization and `registerWidget()` / `registerExternalWidget()` for global pre-registration before the service is created.
 
@@ -27,10 +27,8 @@ const widgetService = useWidgets();
 // Query all widgets registered for a specific blade
 const widgets = widgetService.getWidgets("order-details");
 
-// Check if a widget is currently active (visible and expanded)
-if (widgetService.isActiveWidget("order-status-widget")) {
-  // widget is currently in focus
-}
+// Query external widgets contributed by other modules
+const externalWidgets = widgetService.getExternalWidgetsForBlade("order-details");
 ```
 
 ## API
@@ -41,21 +39,15 @@ None.
 
 ### Returns (`IWidgetService`)
 
-| Property / Method            | Type                                                 | Description                                                                                  |
-| ---------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `registerWidget`             | `(widget: IWidget, bladeId: string) => void`         | Registers a widget for a specific blade. The widget will appear in that blade's widget area. |
-| `unregisterWidget`           | `(widgetId: string, bladeId: string) => void`        | Removes a widget from a blade by ID.                                                         |
-| `getWidgets`                 | `(bladeId: string) => IWidget[]`                     | Returns all widgets registered for a specific blade.                                         |
-| `clearBladeWidgets`          | `(bladeId: string) => void`                          | Removes all widgets for a blade (used during blade teardown).                                |
-| `registeredWidgets`          | `IWidgetRegistration[]`                              | All widget registrations across all blades.                                                  |
-| `isActiveWidget`             | `(id: string) => boolean`                            | Checks if a widget is currently active (selected/expanded).                                  |
-| `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.).                            |
-| `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.                                     |
+| Property / Method            | Type                                                                                           | Description                                                                                  |
+| ---------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `registerWidget`             | `(widget: IWidget, bladeId: string) => void`                                                   | Registers a widget for a specific blade. The widget will appear in that blade's widget area. |
+| `unregisterWidget`           | `(widgetId: string, bladeId: string) => void`                                                  | Removes a widget from a blade by ID.                                                         |
+| `getWidgets`                 | `(bladeId: string) => IWidget[]`                                                               | Returns all widgets registered for a specific blade.                                         |
+| `updateWidget`               | `({ id, bladeId, widget }: { id: string; bladeId: string; widget: Partial<IWidget> }) => void` | Updates properties of a registered widget (trigger, badge, etc.).                            |
+| `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.                                     |
+| `cloneWidget`                | `<T extends IWidget \| IExternalWidgetRegistration>(widget: T) => T`                           | Returns a deep-ish clone of a widget or external widget registration.                        |
 
 ### Additional Exports
 
@@ -77,7 +69,7 @@ The widget system has three layers:
 
 3. **Runtime access** (`useWidgets()`): Components inject the service and use it to query or modify widget state.
 
-The service tracks active widgets (which widget is currently expanded/focused) separately from registrations, enabling the widget panel to highlight the active widget and call its update function.
+The service stores widget registrations per blade and returns cloned widget definitions on query. It does not track active/expanded/focused state.
 
 <!-- internal:end -->
 
@@ -117,11 +109,10 @@ import ShippingTracker from "./widgets/ShippingTracker.vue";
 export default {
   install() {
     registerExternalWidget({
-      widgetId: "shipping-tracker",
-      bladeId: "order-details", // target blade from another module
+      id: "shipping-tracker",
+      targetBlades: ["order-details"], // target blades from other modules
       component: markRaw(ShippingTracker),
       title: "Shipping",
-      icon: "fas fa-truck",
     });
   },
 };