@vc-shell/vc-app-skill 2.0.0-alpha.33 → 2.0.0-alpha.34

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

@@ -30,21 +30,21 @@ const { uiSettings, loading } = useSettings();
 
 ### Returns
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `uiSettings` | `Ref<IUISetting>` | Reactive object with current UI customization values |
-| `loading` | `ComputedRef<boolean>` | Whether settings are being fetched from the API |
+| Property        | Type                                                | Description                                               |
+| --------------- | --------------------------------------------------- | --------------------------------------------------------- |
+| `uiSettings`    | `Ref<IUISetting>`                                   | Reactive object with current UI customization values      |
+| `loading`       | `ComputedRef<boolean>`                              | Whether settings are being fetched from the API           |
 | `applySettings` | `(args: { logo?, title?, avatar?, role? }) => void` | Override settings with custom values (prevents API fetch) |
 
 ### IUISetting
 
-| Property | Type | Description |
-|----------|------|-------------|
+| Property        | Type      | Description                                |
+| --------------- | --------- | ------------------------------------------ |
 | `contrast_logo` | `string?` | Logo variant for dark/contrast backgrounds |
-| `logo` | `string?` | Primary application logo URL |
-| `title` | `string?` | Application title |
-| `avatar` | `string?` | Current user avatar URL |
-| `role` | `string?` | Current user role display name |
+| `logo`          | `string?` | Primary application logo URL               |
+| `title`         | `string?` | Application title                          |
+| `avatar`        | `string?` | Current user avatar URL                    |
+| `role`          | `string?` | Current user role display name             |
 
 ## Common Patterns
 
@@ -58,14 +58,20 @@ const { uiSettings, loading } = useSettings();
 </script>
 
 <template>
-  <div v-loading="loading" class="tw-min-h-[40px]">
+  <div
+    v-loading="loading"
+    class="tw-min-h-[40px]"
+  >
     <img
       v-if="uiSettings.logo"
       :src="uiSettings.logo"
       :alt="uiSettings.title ?? 'Application Logo'"
       class="tw-h-10"
     />
-    <span v-if="uiSettings.title" class="tw-ml-2 tw-text-lg tw-font-semibold">
+    <span
+      v-if="uiSettings.title"
+      class="tw-ml-2 tw-text-lg tw-font-semibold"
+    >
       {{ uiSettings.title }}
     </span>
   </div>
@@ -117,7 +123,10 @@ watch(user, (currentUser) => {
       alt="User avatar"
       class="tw-w-8 tw-h-8 tw-rounded-full"
     />
-    <span v-if="uiSettings.role" class="tw-text-sm tw-text-gray-500">
+    <span
+      v-if="uiSettings.role"
+      class="tw-text-sm tw-text-gray-500"
+    >
       {{ uiSettings.role }}
     </span>
   </div>

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

@@ -29,16 +29,16 @@ const items = settingsMenu.items.value;
 
 ### Returns (`ISettingsMenuService`)
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `register` | `(options: RegisterSettingsMenuItemOptions) => string` | Register a settings menu item; returns the item ID |
-| `unregister` | `(id: string) => void` | Remove a settings menu item by ID |
-| `items` | `ComputedRef<ISettingsMenuItem[]>` | Reactive array of all registered settings menu items |
+| Property     | Type                                                   | Description                                          |
+| ------------ | ------------------------------------------------------ | ---------------------------------------------------- |
+| `register`   | `(options: RegisterSettingsMenuItemOptions) => string` | Register a settings menu item; returns the item ID   |
+| `unregister` | `(id: string) => void`                                 | Remove a settings menu item by ID                    |
+| `items`      | `ComputedRef<ISettingsMenuItem[]>`                     | Reactive array of all registered settings menu items |
 
 ### Related Exports
 
-| Export | Description |
-|--------|-------------|
+| Export                  | Description                                        |
+| ----------------------- | -------------------------------------------------- |
 | `provideSettingsMenu()` | Create and provide the service in a root component |
 
 ## Common Patterns

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

@@ -15,7 +15,7 @@ Internally, it delegates to `useMenuExpanded()` to share reactive state with oth
 
 ```vue
 <script setup lang="ts">
-import { useSidebarState } from '@vc-shell/framework';
+import { useSidebarState } from "@vc-shell/framework";
 
 const { isExpanded, isPinned, togglePin, openMenu, closeMenu } = useSidebarState();
 </script>
@@ -24,10 +24,17 @@ const { isExpanded, isPinned, togglePin, openMenu, closeMenu } = useSidebarState
   <div class="tw-flex tw-items-center">
     <!-- Show full label when expanded, icon-only when collapsed -->
     <VcIcon icon="fas fa-box" />
-    <span v-if="isExpanded" class="tw-ml-2">Products</span>
+    <span
+      v-if="isExpanded"
+      class="tw-ml-2"
+      >Products</span
+    >
 
     <!-- Pin/unpin toggle button -->
-    <button @click="togglePin" class="tw-ml-auto">
+    <button
+      @click="togglePin"
+      class="tw-ml-auto"
+    >
       <VcIcon :icon="isPinned ? 'fas fa-thumbtack' : 'fas fa-thumbtack tw-rotate-45'" />
     </button>
   </div>
@@ -38,21 +45,21 @@ const { isExpanded, isPinned, togglePin, openMenu, closeMenu } = useSidebarState
 
 ### Returns -- State
 
-| Property | Type | Description |
-|---|---|---|
-| `isPinned` | `Ref<boolean>` | Sidebar is pinned open by the user. Persisted to localStorage so it survives page reloads. |
-| `isHoverExpanded` | `Ref<boolean>` | Sidebar is temporarily expanded because the mouse is hovering over it (desktop only). |
-| `isMenuOpen` | `Ref<boolean>` | Mobile menu overlay is visible. |
-| `isExpanded` | `ComputedRef<boolean>` | Derived: `isPinned || isHoverExpanded`. Use this when you just need to know if sidebar content is visible. |
+| Property          | Type                   | Description                                                                                |
+| ----------------- | ---------------------- | ------------------------------------------------------------------------------------------ | --- | ------------------------------------------------------------------------------------ |
+| `isPinned`        | `Ref<boolean>`         | Sidebar is pinned open by the user. Persisted to localStorage so it survives page reloads. |
+| `isHoverExpanded` | `Ref<boolean>`         | Sidebar is temporarily expanded because the mouse is hovering over it (desktop only).      |
+| `isMenuOpen`      | `Ref<boolean>`         | Mobile menu overlay is visible.                                                            |
+| `isExpanded`      | `ComputedRef<boolean>` | Derived: `isPinned                                                                         |     | isHoverExpanded`. Use this when you just need to know if sidebar content is visible. |
 
 ### Returns -- Actions
 
-| Property | Type | Description |
-|---|---|---|
-| `togglePin` | `() => void` | Toggle pinned state. Persists the new value to localStorage immediately. |
+| Property           | Type                       | Description                                                                                                      |
+| ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `togglePin`        | `() => void`               | Toggle pinned state. Persists the new value to localStorage immediately.                                         |
 | `setHoverExpanded` | `(value: boolean) => void` | Set hover expansion. Opening has a 200ms delay to prevent flicker from brief mouse passes; closing is immediate. |
-| `openMenu` | `() => void` | Show the mobile menu overlay. |
-| `closeMenu` | `() => void` | Hide the mobile menu overlay. |
+| `openMenu`         | `() => void`               | Show the mobile menu overlay.                                                                                    |
+| `closeMenu`        | `() => void`               | Hide the mobile menu overlay.                                                                                    |
 
 ## Setup
 
@@ -60,7 +67,7 @@ const { isExpanded, isPinned, togglePin, openMenu, closeMenu } = useSidebarState
 
 ```typescript
 // Inside VcApp.vue setup
-import { provideSidebarState } from '@vc-shell/framework';
+import { provideSidebarState } from "@vc-shell/framework";
 
 provideSidebarState();
 ```
@@ -69,8 +76,8 @@ provideSidebarState();
 
 ```vue
 <script setup lang="ts">
-import { useSidebarState } from '@vc-shell/framework';
-import { useBladeContext } from '@vc-shell/framework';
+import { useSidebarState } from "@vc-shell/framework";
+import { useBladeContext } from "@vc-shell/framework";
 
 const { closeMenu, isMenuOpen } = useSidebarState();
 const { openBlade } = useBladeContext();
@@ -83,7 +90,7 @@ async function navigateToProducts() {
 
   await openBlade({
     component: ProductListBlade,
-    param: { catalogId: 'default' },
+    param: { catalogId: "default" },
   });
 }
 </script>
@@ -100,18 +107,19 @@ async function navigateToProducts() {
 
 ```vue
 <script setup lang="ts">
-import { useSidebarState } from '@vc-shell/framework';
-import { computed } from 'vue';
+import { useSidebarState } from "@vc-shell/framework";
+import { computed } from "vue";
 
 const { isExpanded } = useSidebarState();
 
-const contentClass = computed(() =>
-  isExpanded.value ? 'tw-ml-64' : 'tw-ml-16',
-);
+const contentClass = computed(() => (isExpanded.value ? "tw-ml-64" : "tw-ml-16"));
 </script>
 
 <template>
-  <div :class="contentClass" class="tw-transition-all tw-duration-200">
+  <div
+    :class="contentClass"
+    class="tw-transition-all tw-duration-200"
+  >
     <slot />
   </div>
 </template>

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

@@ -17,14 +17,18 @@ 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 "@vc-shell/framework";
 
 const { isSlowNetwork } = useSlowNetworkDetection();
 </script>
 
 <template>
   <VcBlade title="Products">
-    <VcBanner v-if="isSlowNetwork" variant="warning" icon="lucide-wifi">
+    <VcBanner
+      v-if="isSlowNetwork"
+      variant="warning"
+      icon="lucide-wifi"
+    >
       <template #title>Slow connection</template>
       Loading may take longer than usual.
     </VcBanner>
@@ -38,19 +42,19 @@ const { isSlowNetwork } = useSlowNetworkDetection();
 
 ### Returns
 
-| Property | Type | Description |
-|---|---|---|
-| `isSlowNetwork` | `Readonly<Ref<boolean>>` | `true` when the network is slow (either channel active). Read-only. |
-| `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. |
+| Property         | Type                     | Description                                                                     |
+| ---------------- | ------------------------ | ------------------------------------------------------------------------------- |
+| `isSlowNetwork`  | `Readonly<Ref<boolean>>` | `true` when the network is slow (either channel active). Read-only.             |
+| `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
 
-| Name | Value | Purpose |
-|---|---|---|
-| `SLOW_REQUEST_THRESHOLD_MS` | `10000` | Time before a pending request is considered slow |
-| `DISMISS_DELAY_MS` | `3000` | Delay before hiding the notification after recovery |
-| `SLOW_EFFECTIVE_TYPES` | `["slow-2g", "2g"]` | Connection types flagged as slow |
+| Name                        | Value               | Purpose                                             |
+| --------------------------- | ------------------- | --------------------------------------------------- |
+| `SLOW_REQUEST_THRESHOLD_MS` | `10000`             | Time before a pending request is considered slow    |
+| `DISMISS_DELAY_MS`          | `3000`              | Delay before hiding the notification after recovery |
+| `SLOW_EFFECTIVE_TYPES`      | `["slow-2g", "2g"]` | Connection types flagged as slow                    |
 
 ## How It Works
 
@@ -74,18 +78,18 @@ 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 { watch } from "vue";
+import { useSlowNetworkDetection } from "@vc-shell/framework";
 
 const { isSlowNetwork } = useSlowNetworkDetection();
 
 // Switch to a lightweight polling interval when the network is slow
-const pollInterval = computed(() => isSlowNetwork.value ? 30000 : 5000);
+const pollInterval = computed(() => (isSlowNetwork.value ? 30000 : 5000));
 
 // Warn before navigating away during slow network + unsaved changes
 watch(isSlowNetwork, (slow) => {
   if (slow) {
-    console.info('Network is slow — consider disabling auto-refresh');
+    console.info("Network is slow — consider disabling auto-refresh");
   }
 });
 </script>
@@ -96,7 +100,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 "@vc-shell/framework";
 
 const { trackRequest, untrackRequest } = useSlowNetworkDetection();
 

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

@@ -13,15 +13,15 @@ Manages color theme registration, switching, and persistence. Themes are applied
 
 ```vue
 <script setup lang="ts">
-import { useTheme } from '@vc-shell/framework';
+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' });
+register({ key: "dark", localizationKey: "CORE.THEMES.DARK" });
 
 // Switch to it explicitly
-setTheme('dark');
+setTheme("dark");
 
 // Or cycle through all registered themes (light -> dark -> light -> ...)
 next();
@@ -39,28 +39,28 @@ next();
 
 ### Returns
 
-| Property | Type | Description |
-|---|---|---|
-| `themes` | `ComputedRef<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. |
-| `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. |
-| `unregister` | `(keys: string \| string[]) => void` | Remove themes from the registry by key. |
+| Property               | Type                                                     | Description                                                                                                               |
+| ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `themes`               | `ComputedRef<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.                        |
+| `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.                                  |
+| `unregister`           | `(keys: string \| string[]) => void`                     | Remove themes from the registry by key.                                                                                   |
 
 ### ThemeDefinition
 
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `key` | `string` | Yes | Unique theme identifier. Used as the `data-theme` attribute value on `<html>` and as the localStorage persistence key. |
-| `localizationKey` | `string` | No | i18n key for the display name (e.g., `"CORE.THEMES.DARK"`). Falls back to the capitalized `key` (e.g., `"Dark"`). |
+| Field             | Type     | Required | Description                                                                                                            |
+| ----------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `key`             | `string` | Yes      | Unique theme identifier. Used as the `data-theme` attribute value on `<html>` and as the localStorage persistence key. |
+| `localizationKey` | `string` | No       | i18n key for the display name (e.g., `"CORE.THEMES.DARK"`). Falls back to the capitalized `key` (e.g., `"Dark"`).      |
 
 ### DisplayTheme
 
-| Field | Type | Description |
-|---|---|---|
-| `key` | `string` | Theme identifier |
+| Field  | Type     | Description                                                                  |
+| ------ | -------- | ---------------------------------------------------------------------------- |
+| `key`  | `string` | Theme identifier                                                             |
 | `name` | `string` | Localized display name, resolved from `localizationKey` or capitalized `key` |
 
 ## How It Works
@@ -77,16 +77,16 @@ next();
 
 ```typescript
 // my-module/index.ts
-import type { App } from 'vue';
-import { useTheme } from '@vc-shell/framework';
+import type { App } from "vue";
+import { useTheme } from "@vc-shell/framework";
 
 export default {
   install(app: App) {
     const { register } = useTheme();
 
     register([
-      { key: 'ocean', localizationKey: 'MY_MODULE.THEMES.OCEAN' },
-      { key: 'forest', localizationKey: 'MY_MODULE.THEMES.FOREST' },
+      { key: "ocean", localizationKey: "MY_MODULE.THEMES.OCEAN" },
+      { key: "forest", localizationKey: "MY_MODULE.THEMES.FOREST" },
     ]);
   },
 };
@@ -113,7 +113,7 @@ Then define your theme's CSS variables scoped by the `data-theme` attribute:
 
 ```vue
 <script setup lang="ts">
-import { useTheme } from '@vc-shell/framework';
+import { useTheme } from "@vc-shell/framework";
 
 const { themes, currentThemeKey, setTheme } = useTheme();
 </script>

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

@@ -170,10 +170,7 @@ By default, all methods operate on the current blade. Pass an explicit `targetBl
 
 ```typescript
 // Register a button on a specific child blade
-registerToolbarItem(
-  { id: "child-action", title: "Action", clickHandler: () => {} },
-  "ChildBlade",
-);
+registerToolbarItem({ id: "child-action", title: "Action", clickHandler: () => {} }, "ChildBlade");
 
 // Clear another blade's toolbar
 clearBladeToolbarItems("ChildBlade");
@@ -325,42 +322,42 @@ function helperFunction() {
 
 ### Parameters
 
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `options` | `UseToolbarOptions` | No | `{}` | Configuration options |
+| Parameter | Type                | Required | Default | Description           |
+| --------- | ------------------- | -------- | ------- | --------------------- |
+| `options` | `UseToolbarOptions` | No       | `{}`    | Configuration options |
 
 #### UseToolbarOptions
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `autoCleanup` | `boolean` | `true` | Clear all toolbar items for the current blade on component unmount |
+| Option        | Type      | Default | Description                                                        |
+| ------------- | --------- | ------- | ------------------------------------------------------------------ |
+| `autoCleanup` | `boolean` | `true`  | Clear all toolbar items for the current blade on component unmount |
 
 ### Returns: `UseToolbarReturn`
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `registerToolbarItem` | `(item: IToolbarItem, targetBladeId?: string) => void` | Register a toolbar button (scoped to current blade by default) |
-| `unregisterToolbarItem` | `(id: string, targetBladeId?: string) => void` | Remove a toolbar button by ID |
-| `updateToolbarItem` | `(id: string, partial: Partial<IToolbarItem>, targetBladeId?: string) => void` | Update properties of an existing toolbar button |
-| `getToolbarItems` | `(targetBladeId?: string) => IToolbarItem[]` | Get all toolbar items for a blade |
-| `clearBladeToolbarItems` | `(targetBladeId?: string) => void` | Remove all toolbar items for a blade |
-| `isToolbarItemRegistered` | `(id: string) => boolean` | Check if a toolbar item with the given ID exists |
-| `registeredToolbarItems` | `IToolbarRegistration[]` | All registered toolbar items across all blades |
+| Property                  | Type                                                                           | Description                                                    |
+| ------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+| `registerToolbarItem`     | `(item: IToolbarItem, targetBladeId?: string) => void`                         | Register a toolbar button (scoped to current blade by default) |
+| `unregisterToolbarItem`   | `(id: string, targetBladeId?: string) => void`                                 | Remove a toolbar button by ID                                  |
+| `updateToolbarItem`       | `(id: string, partial: Partial<IToolbarItem>, targetBladeId?: string) => void` | Update properties of an existing toolbar button                |
+| `getToolbarItems`         | `(targetBladeId?: string) => IToolbarItem[]`                                   | Get all toolbar items for a blade                              |
+| `clearBladeToolbarItems`  | `(targetBladeId?: string) => void`                                             | Remove all toolbar items for a blade                           |
+| `isToolbarItemRegistered` | `(id: string) => boolean`                                                      | Check if a toolbar item with the given ID exists               |
+| `registeredToolbarItems`  | `IToolbarRegistration[]`                                                       | All registered toolbar items across all blades                 |
 
 ### 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>`                                          | 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)                   |
 
 ## Related
 

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

@@ -16,17 +16,26 @@ Uses `createSharedComposable` from VueUse, so all callers across the entire appl
 
 ```vue
 <script setup lang="ts">
-import { useUser } from '@vc-shell/framework';
+import { useUser } from "@vc-shell/framework";
 
 const { user, isAuthenticated, isAdministrator, loading } = useUser();
 </script>
 
 <template>
-  <div v-if="loading" class="tw-animate-pulse">Loading user...</div>
+  <div
+    v-if="loading"
+    class="tw-animate-pulse"
+  >
+    Loading user...
+  </div>
 
   <div v-else-if="isAuthenticated">
     <p>Welcome, {{ user?.userName }}</p>
-    <span v-if="isAdministrator" class="tw-badge tw-badge-primary">Admin</span>
+    <span
+      v-if="isAdministrator"
+      class="tw-badge tw-badge-primary"
+      >Admin</span
+    >
   </div>
 
   <div v-else>
@@ -43,15 +52,15 @@ None.
 
 ### Returns
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `user` | `ComputedRef<UserDetail \| undefined>` | Current user details (userName, email, id, 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. |
-| `loadUser` | `() => Promise<UserDetail>` | Loads/reloads user info from the server. Deduplicates concurrent calls -- if two components call `loadUser()` at the same time, only one API request is made. |
-| `signOut` | `() => Promise<void>` | Signs out the current user, clears auth data from localStorage, and resets the user state. Handles both standard and external (SSO) sign-out flows. |
-| `getAccessToken` | `() => Promise<string \| null>` | Returns the current OAuth access token. Automatically refreshes using the refresh token if the access token has expired or will expire within 60 seconds. Returns `null` if no auth data exists. |
+| Property          | Type                                   | Description                                                                                                                                                                                      |
+| ----------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `user`            | `ComputedRef<UserDetail \| undefined>` | Current user details (userName, email, id, 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.                                                                                                                |
+| `loadUser`        | `() => Promise<UserDetail>`            | Loads/reloads user info from the server. Deduplicates concurrent calls -- if two components call `loadUser()` at the same time, only one API request is made.                                    |
+| `signOut`         | `() => Promise<void>`                  | Signs out the current user, clears auth data from localStorage, and resets the user state. Handles both standard and external (SSO) sign-out flows.                                              |
+| `getAccessToken`  | `() => Promise<string \| null>`        | Returns the current OAuth access token. Automatically refreshes using the refresh token if the access token has expired or will expire within 60 seconds. Returns `null` if no auth data exists. |
 
 ## How It Works
 
@@ -63,14 +72,16 @@ The composable delegates to `_createInternalUserLogic()`, which manages:
 
 3. **Token refresh**: `getAccessToken()` checks the expiration time with a 60-second buffer. If the token is expired or about to expire and a refresh token is available, it makes a `POST /connect/token` request with `grant_type: refresh_token`.
 
-4. **Shared state**: `createSharedComposable` from VueUse ensures all calls to `useUser()` return the same reactive refs. The underlying `user` ref is module-level, so it persists across component lifecycles.
+4. **Shared state**: `createSharedComposable` from VueUse wraps `_createInternalUserLogic` so every call to `useUser()` or `useUserManagement()` reads from the same singleton internal logic. The `user` ref lives inside that singleton. App bootstrap registers `useUserManagement()` outside any component scope, which pins the singleton for the app lifetime — transient component mount/unmount cycles don't discard it.
 
 ## Recipe: Route Guard Based on Authentication
 
 ```typescript
-import { useUser } from '@vc-shell/framework';
+import { useUser } from "@vc-shell/framework";
 
-const router = createRouter({ /* ... */ });
+const router = createRouter({
+  /* ... */
+});
 
 router.beforeEach(async (to) => {
   const { isAuthenticated, loadUser } = useUser();
@@ -85,7 +96,7 @@ router.beforeEach(async (to) => {
   }
 
   if (to.meta.requiresAuth && !isAuthenticated.value) {
-    return { name: 'SignIn' };
+    return { name: "SignIn" };
   }
 });
 ```
@@ -95,25 +106,33 @@ router.beforeEach(async (to) => {
 ```vue
 <template>
   <div class="tw-flex tw-items-center tw-gap-2">
-    <VcAvatar :name="user?.userName" size="sm" />
+    <VcAvatar
+      :name="user?.userName"
+      size="sm"
+    />
     <div>
       <p class="tw-text-sm tw-font-medium">{{ user?.userName }}</p>
       <p class="tw-text-xs tw-text-gray-500">{{ user?.email }}</p>
     </div>
-    <VcButton size="sm" variant="ghost" @click="handleSignOut">Sign Out</VcButton>
+    <VcButton
+      size="sm"
+      variant="ghost"
+      @click="handleSignOut"
+      >Sign Out</VcButton
+    >
   </div>
 </template>
 
 <script setup lang="ts">
-import { useUser } from '@vc-shell/framework';
-import { useRouter } from 'vue-router';
+import { useUser } from "@vc-shell/framework";
+import { useRouter } from "vue-router";
 
 const { user, signOut } = useUser();
 const router = useRouter();
 
 async function handleSignOut() {
   await signOut();
-  router.push({ name: 'SignIn' });
+  router.push({ name: "SignIn" });
 }
 </script>
 ```
@@ -121,7 +140,7 @@ async function handleSignOut() {
 ## Recipe: Adding Access Token to Custom API Calls
 
 ```typescript
-import { useUser } from '@vc-shell/framework';
+import { useUser } from "@vc-shell/framework";
 
 const { getAccessToken } = useUser();
 
@@ -130,7 +149,7 @@ async function fetchCustomEndpoint(url: string) {
 
   const response = await fetch(url, {
     headers: {
-      Authorization: token ? `Bearer ${token}` : '',
+      Authorization: token ? `Bearer ${token}` : "",
     },
   });
 
@@ -140,7 +159,7 @@ async function fetchCustomEndpoint(url: string) {
 
 ## Tips
 
-- **`loadUser` deduplicates concurrent calls.** If your app loads multiple blades simultaneously and each calls `loadUser()`, only one API request is made. All calls resolve with the same result.
+- **`loadUser` deduplicates concurrent calls across composables.** If multiple blades call `loadUser()` simultaneously — or if `useUser()` and `useUserManagement()` are both used in the same flow — only one API request is made. `useUser` and `useUserManagement` share the singleton internal logic, so request deduplication works across both.
 - **Token refresh is transparent.** `getAccessToken()` handles expiration checking and refresh internally. You never need to manually check token expiration or call a refresh endpoint.
 - **`isAuthenticated` checks `userName`, not the token.** A user is considered authenticated if `user.value?.userName` is not null. This means the user could have an expired token but still appear "authenticated" until the next API call fails.
 - **`signOut` clears localStorage.** After sign-out, the `vc_auth_data` key is removed from localStorage. Any cached tokens are gone permanently.