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

package/runtime/knowledge/docs/shell/components/settings-menu/settings-menu.docs.md

@@ -98,12 +98,13 @@ export default {
 
 ### Registration options
 
-| Option      | Type        | Required | Description                                                                                                                                    |
-| ----------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`        | `string`    | No       | Unique identifier for the entry. Auto-generated when omitted.                                                                                  |
-| `group`     | `string`    | No       | Group name (entries are grouped and separated by dividers). Defaults to `"general"`.                                                           |
-| `order`     | `number`    | No       | Sort order within the group (lower = higher position). Defaults to the current registry size at registration time, preserving insertion order. |
-| `component` | `Component` | Yes      | Vue component to render as the menu item.                                                                                                      |
+| Option      | Type                      | Required | Description                                                                                                                                    |
+| ----------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`        | `string`                  | No       | Unique identifier for the entry. Auto-generated when omitted.                                                                                  |
+| `group`     | `string`                  | No       | Group name (entries are grouped and separated by dividers). Defaults to `"general"`.                                                           |
+| `order`     | `number`                  | No       | Sort order within the group (lower = higher position). Defaults to the current registry size at registration time, preserving insertion order. |
+| `component` | `Component`               | Yes      | Vue component to render as the menu item.                                                                                                      |
+| `props`     | `Record<string, unknown>` | No       | Props bound to the rendered component via `v-bind`.                                                                                            |
 
 ### Group rendering
 
@@ -117,7 +118,7 @@ Groups are separated by a horizontal divider and items within each group are sor
 ## Details
 
 - **Service-driven content**: The menu has no props and renders entirely from the `useSettingsMenu()` registry. This makes it fully extensible -- any module can add entries.
-- **CloseSettingsMenuKey injection**: The menu provides a `CloseSettingsMenuKey` injection to its children. Menu items inject this to close the dropdown before performing their action (e.g., opening a popup or navigating).
+- **CloseSettingsMenuKey injection**: `CloseSettingsMenuKey` is provided by the containing `UserDropdownButton`, not by `SettingsMenu`. `SettingsMenu` itself provides nothing; it only reads `useSettingsMenu().items` and renders them. Menu item children inject the key supplied by the parent dropdown to close it before performing their action (e.g., opening a popup or navigating). Rendering `SettingsMenu` standalone leaves `CloseSettingsMenuKey` undefined for its children.
 - **Ordering**: Items are sorted by `order` within their group. Use consistent order ranges across modules to maintain a predictable menu layout.
 - **Dynamic registration**: Items can be registered at any time, but registering during module `install()` ensures they are available when the menu first renders.
 

package/runtime/knowledge/docs/shell/components/settings-menu-item/settings-menu-item.docs.md

@@ -21,10 +21,10 @@ The component handles the visual representation of a single menu entry: an icon
 
 The component includes a `submenu` slot that **automatically adapts to the viewport**:
 
-- **Desktop**: renders a floating `VcDropdownPanel` anchored to the menu item (`placement="right-start"`)
+- **Desktop**: renders a floating `VcPopover` anchored to the menu item (`placement="right-start"`)
 - **Mobile**: renders an inline accordion with animated expand/collapse (via `useCollapsible`)
 
-This removes the need for consumers to manage `VcDropdownPanel`, `isMobile` checks, or z-index issues manually.
+This removes the need for consumers to manage `VcPopover`, `isMobile` checks, or z-index issues manually.
 
 ## When to Use
 
@@ -51,23 +51,25 @@ import { SettingsMenuItem } from "@vc-shell/framework";
 
 ## Key Props
 
-| Prop            | Type                           | Default     | Description                                                                      |
-| --------------- | ------------------------------ | ----------- | -------------------------------------------------------------------------------- |
-| `title`         | `string`                       | `undefined` | Menu item label                                                                  |
-| `icon`          | `string \| Component`          | `undefined` | Icon name or component                                                           |
-| `image`         | `string`                       | `undefined` | Image URL (alternative to icon)                                                  |
-| `value`         | `string`                       | `undefined` | Current value displayed on the right                                             |
-| `showChevron`   | `boolean`                      | `false`     | Shows right chevron for sub-menus (auto-enabled when `submenu` slot is provided) |
-| `isActive`      | `boolean`                      | `false`     | Highlights the item (auto-managed when `submenu` slot is provided)               |
-| `disabled`      | `boolean`                      | `false`     | Disables click interaction                                                       |
-| `triggerAction` | `"click" \| "hover" \| "none"` | `"click"`   | What interaction opens the item                                                  |
+| Prop            | Type                           | Default     | Description                                                                                                                               |
+| --------------- | ------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`         | `string`                       | `undefined` | Menu item label                                                                                                                           |
+| `icon`          | `string \| Component`          | `undefined` | Icon name or component                                                                                                                    |
+| `image`         | `string`                       | `undefined` | Image URL (alternative to icon)                                                                                                           |
+| `emptyIcon`     | `string`                       | `undefined` | Fallback icon shown on the `VcImage` when `image` fails to load                                                                           |
+| `value`         | `string`                       | `undefined` | Current value displayed on the right                                                                                                      |
+| `showChevron`   | `boolean`                      | `false`     | Shows right chevron for sub-menus (auto-enabled when `submenu` slot is provided)                                                          |
+| `isActive`      | `boolean`                      | `false`     | Highlights the item (auto-managed when `submenu` slot is provided)                                                                        |
+| `disabled`      | `boolean`                      | `false`     | Disables click interaction                                                                                                                |
+| `isVisible`     | `boolean`                      | `true`      | Hides the item when `false` via the `--invisible` class                                                                                   |
+| `triggerAction` | `"click" \| "hover" \| "none"` | `"click"`   | What interaction opens the item. Note: `"hover"` is not implemented (no hover handler); only `"click"` and `"none"` have runtime behavior |
 
 ## Events
 
-| Event           | Payload | Description                                                          |
-| --------------- | ------- | -------------------------------------------------------------------- |
-| `trigger:click` | --      | Emitted when the item is clicked (only when `triggerAction="click"`) |
-| `trigger:hover` | --      | Emitted when hovered (only when `triggerAction="hover"`)             |
+| Event           | Payload | Description                                                                                             |
+| --------------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `trigger:click` | --      | Emitted when the item is clicked (only when `triggerAction="click"`)                                    |
+| `trigger:hover` | --      | Declared but not implemented: `triggerAction="hover"` has no runtime handler, so this event never fires |
 
 ## Slots
 
@@ -156,15 +158,15 @@ The `submenu` slot can contain any content, not just `VcDropdownItem`:
 </SettingsMenuItem>
 ```
 
-## Migration: Manual VcDropdownPanel to Submenu Slot
+## Migration: Manual VcPopover to Submenu Slot
 
 Before (manual dropdown management):
 
 ```vue
 <SettingsMenuItem ref="menuItemRef" icon="lucide-palette" title="Theme" :value="currentTheme" :show-chevron="true" :is-active="isOpen" @trigger:click="isOpen = !isOpen" />
-<VcDropdownPanel v-model:show="isOpen" :anchor-ref="menuItemRef?.triggerRef ?? null" placement="right-start" width="180px">
+<VcPopover v-model:show="isOpen" :anchor-ref="menuItemRef?.triggerRef ?? null" placement="right-start" width="180px">
   <!-- options -->
-</VcDropdownPanel>
+</VcPopover>
 ```
 
 After (submenu slot):
@@ -180,7 +182,7 @@ After (submenu slot):
 **What changes:**
 
 - Remove `ref`, `isOpen`, `:show-chevron`, `:is-active`, `@trigger:click` toggle -- all auto-managed
-- Remove `VcDropdownPanel` wrapper entirely
+- Remove `VcPopover` wrapper entirely
 - Move dropdown content into `#submenu` slot
 - Mobile adaptation is automatic (no `isMobile` check needed)
 
@@ -201,5 +203,5 @@ Do not set `triggerAction="none"` and then rely on `@trigger:click` -- the event
 - [SettingsMenu](../settings-menu/settings-menu.docs.md) -- parent container
 - [ThemeSelector](../theme-selector/theme-selector.docs.md) -- uses SettingsMenuItem with submenu slot
 - [LanguageSelector](../language-selector/language-selector.docs.md) -- uses SettingsMenuItem with submenu slot
-- [VcDropdownPanel](../../../ui/components/molecules/vc-dropdown-panel/vc-dropdown-panel.docs.md) -- used internally for desktop sub-menus
+- [VcPopover](../../../ui/components/molecules/vc-popover/vc-popover.docs.md) -- used internally for desktop sub-menus
 - [VcDropdown](../../../ui/components/molecules/vc-dropdown/vc-dropdown.docs.md) -- recommended for sub-menu option rows

package/runtime/knowledge/docs/shell/components/sidebar/sidebar.docs.md

@@ -7,6 +7,8 @@ internal: true
 
 # Sidebar Component
 
+> **Deprecated.** The `Sidebar` wrapper is deprecated in favor of `VcSidebar` (`framework/ui/components/organisms/vc-sidebar`) and may be removed in a future release. Use this page as legacy/migration guidance only; build new code on `VcSidebar` directly.
+
 A responsive sidebar wrapper that conditionally renders content inside a `VcSidebar` panel or inline, based on viewport and expansion state.
 
 ## Overview
@@ -62,7 +64,7 @@ When `render="mobile"` and the viewport is desktop, the content slot renders inl
 
 ## Behavior
 
-- **Visibility**: The sidebar is visible when `isExpanded === true` AND the `render` mode matches the current viewport (injected via `IsMobileKey` / `IsDesktopKey`).
+- **Visibility**: The sidebar is visible when `isExpanded === true` AND the `render` mode matches the current viewport (resolved via `useResponsive()` -- `isMobile` / `isDesktop`).
 - **Teleport**: On mobile, the inner `VcSidebar` teleports to the document body for proper overlay stacking.
 - **Close**: Closing the sidebar emits `close` -- the parent must update `isExpanded`.
 
@@ -70,9 +72,9 @@ When `render="mobile"` and the viewport is desktop, the content slot renders inl
 
 - Use `render="mobile"` for panels that should be drawers on phones but inline panels on desktop.
 - The `header` slot receives a `close` function so custom headers can include their own close button.
-- The component injects `IsMobileKey` and `IsDesktopKey` from the framework's injection keys.
+- The component resolves the viewport via `useResponsive()` (`isMobile` / `isDesktop`).
 
 ## Related
 
 - `framework/ui/components/organisms/vc-sidebar/` -- the underlying `VcSidebar` organism
-- `framework/injection-keys.ts` -- `IsMobileKey`, `IsDesktopKey`
+- `framework/core/composables/useResponsive/` -- `isMobile` / `isDesktop` viewport helper

package/runtime/knowledge/docs/shell/components/theme-selector/theme-selector.docs.md

@@ -48,12 +48,12 @@ This component has no props. Themes are managed via the `useTheme()` composable.
 
 ## Recipe: Registering Custom Themes
 
-Before the `ThemeSelector` can show themes, they must be registered with the theme service. Themes are defined as objects with a `key` that corresponds to a CSS class or custom property set:
+Before the `ThemeSelector` can show themes, they must be registered with the theme service. Themes are defined as objects with a `key` that corresponds to a `data-theme` attribute value and its custom property set:
 
 ```ts
 import { useTheme } from "@vc-shell/framework";
 
-const { register, setTheme, currentTheme } = useTheme();
+const { register, setTheme, currentThemeKey } = useTheme();
 
 // Register available themes during app initialization
 register([
@@ -66,16 +66,16 @@ register([
 setTheme("light");
 ```
 
-The theme `key` is applied as a CSS class on the root element, allowing CSS custom properties to cascade:
+The theme `key` is written to the `data-theme` attribute on the root element (`<html data-theme="light">`, via `useColorMode({ attribute: "data-theme" })`), allowing CSS custom properties to cascade:
 
 ```scss
 // In your theme CSS files
-.light {
+:root[data-theme="light"] {
   --primary-500: #3b82f6;
   --surface-bg: #ffffff;
 }
 
-.dark {
+:root[data-theme="dark"] {
   --primary-500: #60a5fa;
   --surface-bg: #1e1e2e;
 }
@@ -103,14 +103,14 @@ window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", (e)
 ## Details
 
 - **Theme persistence**: The selected theme is persisted to localStorage, so the user's preference survives page reloads and browser restarts.
-- **Toast notification**: When the user switches themes via the selector, a brief toast notification confirms the change (e.g., "Theme changed to Dark").
+- **Toast notification**: When the user switches themes via the selector, a brief toast notification shows the new theme's localized name (e.g., "Dark").
 - **Cascading submenu**: On desktop, selecting the theme entry opens a submenu listing all registered themes. The current theme is highlighted.
 - **CSS custom properties**: Themes work by switching CSS custom properties defined in `framework/assets/styles/theme/colors.scss`. Components reference these variables (e.g., `tw-bg-[var(--primary-500)]`), so theme changes are instant.
 
 ## Tips
 
 - If only one theme is registered, the `ThemeSelector` still renders but the submenu will have only one option. Consider hiding it if theming is not a feature of your application.
-- Theme keys should be short, lowercase identifiers. They are used as CSS class names on the root element.
+- Theme keys should be short, lowercase identifiers. They are written to the `data-theme` attribute on the root element.
 - Always pair theme registration with corresponding CSS custom property definitions. A registered theme without CSS variables will result in unstyled or broken visuals.
 - The framework's built-in components use CSS custom properties from the theme system. Custom components should follow the same pattern for consistent theming.
 

package/runtime/knowledge/docs/shell/components/user-dropdown-button/user-dropdown-button.docs.md

@@ -33,12 +33,12 @@ import { UserDropdownButton } from "@vc-shell/framework";
 
 ## Key Props
 
-| Prop        | Type      | Default     | Description                   |
-| ----------- | --------- | ----------- | ----------------------------- |
-| `name`      | `string`  | `undefined` | User display name             |
-| `role`      | `string`  | `undefined` | User role label               |
-| `avatarUrl` | `string`  | `undefined` | URL for the user avatar image |
-| `disabled`  | `boolean` | `false`     | Prevents menu from opening    |
+| Prop        | Type      | Default     | Description                                                                                                     |
+| ----------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
+| `name`      | `string`  | `undefined` | User display name                                                                                               |
+| `role`      | `string`  | `undefined` | User role label                                                                                                 |
+| `avatarUrl` | `string`  | `undefined` | URL for the user avatar image                                                                                   |
+| `disabled`  | `boolean` | `false`     | Visual-only: applies the `--auto-width` layout class. Does not suppress clicks or prevent the menu from opening |
 
 ## Recipe: Wiring to User Management Composable
 
@@ -50,11 +50,11 @@ import { computed } from "vue";
 import { UserDropdownButton } from "@vc-shell/framework";
 import { useUserManagement } from "@vc-shell/framework";
 
-const { currentUser } = useUserManagement();
+const { user } = useUserManagement();
 
-const displayName = computed(() => (currentUser.value ? `${currentUser.value.firstName} ${currentUser.value.lastName}` : ""));
-const role = computed(() => currentUser.value?.roles?.[0]?.name ?? "");
-const avatarUrl = computed(() => currentUser.value?.photoUrl);
+const displayName = computed(() => (user.value ? `${user.value.firstName} ${user.value.lastName}` : ""));
+const role = computed(() => user.value?.roles?.[0]?.name ?? "");
+const avatarUrl = computed(() => user.value?.photoUrl);
 </script>
 
 <template>
@@ -86,7 +86,7 @@ On mobile viewports (`$isMobile`), clicking the button opens a full-height slide
 ## Tips
 
 - The component is typically placed in the sidebar footer slot of the app shell. You rarely need to instantiate it manually -- the framework shell handles its placement.
-- If `disabled` is `true`, clicking the button does nothing and the menu does not open. Use this during critical operations where navigation should be prevented.
+- The `disabled` prop is visual-only (it applies the `--auto-width` layout class). It does not block clicks or prevent the menu from opening; the handler always toggles the menu.
 - All menu items are driven by `useSettingsMenu()` registrations. To add custom items to the user menu, register them via the service rather than modifying this component.
 
 ## Related Components

package/runtime/knowledge/docs/shell/dashboard/dashboard-charts/dashboard-charts.docs.md

@@ -61,25 +61,36 @@ const config: ChartConfig = {
 
 ## Key Props (shared across chart types)
 
-| Prop          | Type          | Default     | Description                          |
-| ------------- | ------------- | ----------- | ------------------------------------ |
-| `data`        | `T[]`         | --          | Array of data points                 |
-| `config`      | `ChartConfig` | --          | Series color and label configuration |
-| `xKey`        | `keyof T`     | --          | Key for x-axis values (line/bar)     |
-| `yKeys`       | `(keyof T)[]` | --          | Keys for y-axis series (line/bar)    |
-| `showTooltip` | `boolean`     | `true`      | Enable hover tooltips                |
-| `showLegend`  | `boolean`     | `true`      | Show color legend below chart        |
-| `rangeStart`  | `number`      | `undefined` | Filter data from this x value        |
-| `rangeEnd`    | `number`      | `undefined` | Filter data up to this x value       |
+| Prop          | Type                                           | Default     | Description                          |
+| ------------- | ---------------------------------------------- | ----------- | ------------------------------------ |
+| `data`        | `T[]`                                          | --          | Array of data points                 |
+| `config`      | `ChartConfig`                                  | --          | Series color and label configuration |
+| `xKey`        | `keyof T`                                      | --          | Key for x-axis values (line/bar)     |
+| `yKeys`       | `(keyof T)[]`                                  | --          | Keys for y-axis series (line/bar)    |
+| `showTooltip` | `boolean`                                      | `true`      | Enable hover tooltips                |
+| `showLegend`  | `boolean`                                      | `true`      | Show color legend below chart        |
+| `rangeStart`  | `ChartRangeValue` (`number \| string \| Date`) | `undefined` | Filter data from this x value        |
+| `rangeEnd`    | `ChartRangeValue` (`number \| string \| Date`) | `undefined` | Filter data up to this x value       |
+| `showXAxis`   | `boolean`                                      | `true`      | Show the x-axis (line/bar)           |
+| `showYAxis`   | `boolean`                                      | `true`      | Show the y-axis (line/bar)           |
+| `showGrid`    | `boolean`                                      | `true`      | Show y-axis grid lines (line/bar)    |
+| `numXTicks`   | `number`                                       | `undefined` | Number of x-axis ticks (line/bar)    |
+| `numYTicks`   | `number`                                       | `5`         | Number of y-axis ticks (line/bar)    |
+| `xTickFormat` | `(value: number \| Date) => string`            | `undefined` | Format x-axis tick labels (line/bar) |
+| `yTickFormat` | `(value: number) => string`                    | `undefined` | Format y-axis tick labels (line/bar) |
+| `height`      | `number`                                       | `undefined` | Fixed chart height in px             |
 
 ### Donut-specific props
 
-| Prop              | Type      | Default     | Description                    |
-| ----------------- | --------- | ----------- | ------------------------------ |
-| `valueKey`        | `keyof T` | --          | Key for segment values         |
-| `centralLabel`    | `string`  | `undefined` | Large text in donut center     |
-| `centralSubLabel` | `string`  | `undefined` | Small text below central label |
-| `arcWidth`        | `number`  | `60`        | Donut arc thickness            |
+| Prop              | Type                        | Default     | Description                             |
+| ----------------- | --------------------------- | ----------- | --------------------------------------- |
+| `valueKey`        | `keyof T`                   | --          | Key for segment values                  |
+| `centralLabel`    | `string`                    | `undefined` | Large text in donut center              |
+| `centralSubLabel` | `string`                    | `undefined` | Small text below central label          |
+| `arcWidth`        | `number`                    | `60`        | Donut arc thickness                     |
+| `valueFormat`     | `(value: number) => string` | `undefined` | Formats segment values in tooltip/label |
+| `colorKey`        | `keyof T`                   | `undefined` | Data key holding a per-segment color    |
+| `cornerRadius`    | `number`                    | `4`         | Rounded corner radius of arcs           |
 
 ## ChartConfig Type
 
@@ -91,6 +102,7 @@ type ChartConfig = Record<
   {
     label: string; // Display name in legend and tooltip
     color: string; // CSS color value (hex, var(), rgb, etc.)
+    icon?: string; // Optional icon shown alongside the series label
   }
 >;
 ```

package/runtime/knowledge/docs/shell/dashboard/dashboard-widget-card/dashboard-widget-card.docs.md

@@ -67,20 +67,17 @@ import { DashboardWidgetCard } from "@vc-shell/framework";
 ```vue
 <DashboardWidgetCard header="Orders" icon="lucide-shopping-cart">
   <template #stats>
-    <DashboardStatItem :value="48" label="Total" />
-    <DashboardStatItem :value="12" label="Today" variant="info" />
+    <DashboardStatItem :value="48" label="Total" variant="success" />
+    <DashboardStatItem :value="12" label="Today" />
     <DashboardStatItem :value="3" label="Pending" variant="warning" />
-    <DashboardStatItem :value="1" label="Failed" variant="error" />
+    <DashboardStatItem :value="1" label="Failed" variant="danger" />
   </template>
   <template #content>
     <DashboardFeedList>
-      <DashboardFeedRow v-for="order in recentOrders" :key="order.id">
-        <template #icon>
-          <VcIcon :icon="getOrderIcon(order.status)" size="s" />
-        </template>
-        <template #title>{{ order.number }}</template>
-        <template #subtitle>{{ order.customerName }}</template>
-        <template #meta>{{ formatDateRelative(order.createdDate) }}</template>
+      <DashboardFeedRow v-for="order in recentOrders" :key="order.id" @click="openOrder(order)">
+        <VcIcon :icon="getOrderIcon(order.status)" size="s" />
+        <span>{{ order.number }} — {{ order.customerName }}</span>
+        <template #trailing>{{ formatDateRelative(order.createdDate) }}</template>
       </DashboardFeedRow>
     </DashboardFeedList>
   </template>
@@ -167,22 +164,23 @@ import OrdersWidget from "./OrdersWidget.vue";
 
 const dashboard = useDashboard();
 
-dashboard.register({
+dashboard.registerWidget({
   id: "orders-overview",
+  name: "Orders overview",
   component: markRaw(OrdersWidget),
+  size: { width: 6, height: 4 },
+  position: { x: 0, y: 0 },
   props: { limit: 10 },
-  order: 1,
-  layout: { w: 6, h: 4, x: 0, y: 0 },
 });
 ```
 
 ## Companion Components
 
-| Component           | Description                                                     |
-| ------------------- | --------------------------------------------------------------- |
-| `DashboardStatItem` | Single KPI stat with value, label, and optional color variant   |
-| `DashboardFeedList` | Scrollable list container for feed rows                         |
-| `DashboardFeedRow`  | Individual feed item with icon, title, subtitle, and meta slots |
+| Component           | Description                                                                                                    |
+| ------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `DashboardStatItem` | Single KPI stat with value, label, and optional color variant                                                  |
+| `DashboardFeedList` | Scrollable list container for feed rows                                                                        |
+| `DashboardFeedRow`  | Individual feed item: default slot for leading content, `#trailing` slot for right-side content, emits `click` |
 
 ## Tip: Set a Minimum Height
 
@@ -200,4 +198,4 @@ When the card content is loaded asynchronously, the card may collapse to zero he
 
 - [DraggableDashboard](../draggable-dashboard/draggable-dashboard.docs.md) -- grid layout container
 - [DashboardCharts](../dashboard-charts/dashboard-charts.docs.md) -- chart components for widget content
-- [useDashboard](../../../core/composables/useDashboard/) -- dashboard widget registration service
+- [useDashboard](../../../core/composables/useDashboard/useDashboard.docs.md) -- dashboard widget registration service

package/runtime/knowledge/docs/shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md

@@ -0,0 +1,33 @@
+---
+title: DashboardWidgetSkeleton
+category: composables
+group: utilities
+internal: true
+---
+
+# DashboardWidgetSkeleton
+
+Internal placeholder card used by `GridstackDashboard` while remote modules are still loading. Mimics the shape of `DashboardWidgetCard` (header with icon + title, stats row, content lines) with a shimmer animation. Not exported from `@vc-shell/framework` — consumed only inside the dashboard organism.
+
+## When to Use
+
+- You won't use this directly. `GridstackDashboard` renders one per `SkeletonItem` while `ModulesReadyKey` resolves to `false`.
+- If you build a custom dashboard layout and want the same loading aesthetic, copy this file rather than importing it — the component is intentionally internal so the dashboard team can change its markup at any time.
+
+## Layout Contract
+
+The skeleton has no props. Its parent positions it via inline `style` (`grid-column` / `grid-row`) inside a 12-column CSS grid. Card height/width is fully determined by the grid cell it occupies, so the skeleton stretches to fill its slot.
+
+## Accessibility
+
+- The wrapper has `aria-hidden="true"` so screen readers ignore the visual placeholders. The parent grid carries `role="status"` + `aria-busy="true"` to announce loading state once.
+- Shimmer animation is disabled when the user prefers reduced motion.
+
+## Design Tokens
+
+Skeleton inherits dashboard card tokens where possible (`--dashboard-widget-card-background`, `--dashboard-widget-card-border-color`, `--dashboard-widget-card-border-radius`, `--dashboard-widget-card-shadow`) so its silhouette matches the real card. Shimmer colors are read from `--neutrals-100` / `--neutrals-200`.
+
+## Related
+
+- [DraggableDashboard](./draggable-dashboard.docs.md) — owns the skeleton grid and decides when to render placeholders.
+- [DashboardWidgetCard](../dashboard-widget-card/dashboard-widget-card.docs.md) — the real card whose shape skeletons imitate.

package/runtime/knowledge/docs/shell/dashboard/draggable-dashboard/draggable-dashboard.docs.md

@@ -140,6 +140,27 @@ function resetLayout() {
 - The 12-column grid means common widget widths are: 3 (quarter), 4 (third), 6 (half), and 12 (full width).
 - Register widgets during module `install()` before the dashboard component mounts. Late registrations may not be picked up.
 
+## Advanced / Exports
+
+Besides the `DraggableDashboard` component, `draggable-dashboard/index.ts` re-exports these symbols through the framework root, for building a custom Gridstack dashboard:
+
+| Export                    | Kind       | Description                                                 |
+| ------------------------- | ---------- | ----------------------------------------------------------- |
+| `useGridstack`            | composable | Low-level Gridstack integration for a custom dashboard      |
+| `UseGridstackOptions`     | type       | Options for `useGridstack`                                  |
+| `UseGridstackReturn`      | type       | Return shape of `useGridstack`                              |
+| `DashboardWidgetSize`     | type       | Widget size shape: `{ width, height }`                      |
+| `DashboardWidgetPosition` | type       | Widget position shape: `{ x, y }`                           |
+| `DashboardDragEvent`      | type       | Payload emitted on widget drag/reorder                      |
+| `DashboardGridConfig`     | type       | Grid configuration options                                  |
+| `toGridstackWidget`       | function   | Maps an `IDashboardWidget` to a Gridstack widget descriptor |
+| `fromGridstackNode`       | function   | Maps a Gridstack node back to layout data                   |
+| `loadLayoutFromStorage`   | function   | Reads persisted layout from localStorage                    |
+| `saveLayoutToStorage`     | function   | Writes layout to localStorage                               |
+| `mergeLayoutWithWidgets`  | function   | Merges a persisted layout onto the registered widget set    |
+| `clearLayoutStorage`      | function   | Clears the persisted layout                                 |
+| `LAYOUT_STORAGE_KEY`      | constant   | localStorage key used for layout persistence                |
+
 ## Related Components
 
 - [DashboardWidgetCard](../dashboard-widget-card/dashboard-widget-card.docs.md) -- card container for widget content

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

@@ -39,6 +39,7 @@ A small indicator component for displaying counts, status dots, or short text la
 | `inline`         | `boolean`                                                                  | `false`     | Renders as an inline element without absolute positioning |
 | `clickable`      | `boolean`                                                                  | `false`     | Makes the badge respond to click events                   |
 | `disabled`       | `boolean`                                                                  | `false`     | Disables interaction on clickable badges                  |
+| `active`         | `boolean`                                                                  | `false`     | Applies the active-state color tokens to the badge        |
 | `customPosition` | `boolean`                                                                  | `false`     | Enables custom `top`/`right` positioning                  |
 | `top`            | `string`                                                                   | --          | Custom top offset (requires `customPosition`)             |
 | `right`          | `string`                                                                   | --          | Custom right offset (requires `customPosition`)           |
@@ -144,7 +145,7 @@ Fine-tune the badge position relative to its parent:
 
 - VcBadge lives in `framework/ui/components/atoms/vc-badge/`.
 - Overlay mode uses `position: absolute` on the badge element; the parent slot wrapper is set to `position: relative` via the `.vc-badge` CSS class.
-- The `inline` prop switches the root element from `<span class="vc-badge">` (overlay) to `<span class="vc-badge--inline">` with no position context.
+- The `inline` prop switches the root element from the `<div class="vc-badge">` wrapper (overlay) to a `<div class="vc-badge__badge vc-badge__badge--inline">` rendered directly with no position context.
 - Color palette tokens: overlay uses `--{variant}-500` fills; inline uses `--{variant}-50` background + `--{variant}-700` text, defined in `framework/assets/styles/theme/colors.scss`.
 - Clickable mode integrates `role="button"` and keyboard handlers directly in the component — no separate button wrapper — to preserve the overlay stacking context.
 

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

@@ -172,8 +172,8 @@ Override the default "Show more" button with a custom trigger:
 
 ## Architecture notes
 
-- Legacy variants `"light-danger"`, `"info-dark"`, and `"primary"` are mapped in `vc-banner.vue` via a computed `resolvedVariant`. A `console.warn` is emitted in development mode only.
-- The collapse animation is driven by `max-height` CSS transition with a JS-measured `scrollHeight`. The `--vc-banner-collapsed-height` CSS variable is injected inline as a style binding.
+- Legacy variants `"light-danger"`, `"info-dark"`, and `"primary"` are mapped in `vc-banner.vue` via a computed `normalizedVariant` (backed by the `normalizeVariant` function). A `console.warn` is emitted in development mode only.
+- The collapse is driven by an inline `max-height` style bound via `wrapperStyle` from `useCollapsible` (max-height set to the measured `collapsedHeight` in px when collapsed), transitioned in CSS. There is no `--vc-banner-collapsed-height` custom property.
 - Source: `framework/ui/components/atoms/vc-banner/vc-banner.vue`
 
 <!-- internal:end -->

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

@@ -265,19 +265,19 @@ Use the `loading` prop, not `disabled`. A disabled button gives no progress feed
 
 ## Props
 
-| Prop        | Type                                                                                                         | Default     | Description                                                     |
-| ----------- | ------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------- |
-| `variant`   | `"primary" \| "secondary" \| "danger" \| "warning" \| "success" \| "info" \| "outline" \| "ghost" \| "link"` | `"primary"` | Visual style variant                                            |
-| `size`      | `"sm" \| "default" \| "lg" \| "icon" \| "icon-sm"`                                                           | `"default"` | Button size                                                     |
-| `icon`      | `string \| Component`                                                                                        | --          | Icon identifier or Vue component                                |
-| `iconClass` | `string`                                                                                                     | --          | Additional CSS class for the icon element                       |
-| `iconSize`  | `IconSize`                                                                                                   | `"s"`       | Size of the icon (`"xs"`, `"s"`, `"m"`, `"l"`, `"xl"`, `"xxl"`) |
-| `loading`   | `boolean`                                                                                                    | `false`     | Shows spinner, disables interaction, sets `aria-busy`           |
-| `disabled`  | `boolean`                                                                                                    | `false`     | Disables the button                                             |
-| `selected`  | `boolean`                                                                                                    | `false`     | Applies selected/active visual state, sets `aria-pressed`       |
-| `text`      | `boolean`                                                                                                    | `false`     | Renders as borderless text in the variant's color               |
-| `type`      | `"button" \| "submit" \| "reset"`                                                                            | `"button"`  | HTML button type                                                |
-| `ariaLabel` | `string`                                                                                                     | --          | Accessible label (required for icon-only buttons)               |
+| Prop        | Type                                                                                                         | Default     | Description                                                               |
+| ----------- | ------------------------------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------- |
+| `variant`   | `"primary" \| "secondary" \| "danger" \| "warning" \| "success" \| "info" \| "outline" \| "ghost" \| "link"` | `"primary"` | Visual style variant                                                      |
+| `size`      | `"sm" \| "default" \| "lg" \| "icon" \| "icon-sm"`                                                           | `"default"` | Button size                                                               |
+| `icon`      | `string \| Component`                                                                                        | --          | Icon identifier or Vue component                                          |
+| `iconClass` | `string`                                                                                                     | --          | Additional CSS class for the icon element                                 |
+| `iconSize`  | `IconSize`                                                                                                   | `"s"`       | Size of the icon (`"xs"`, `"s"`, `"m"`, `"l"`, `"xl"`, `"xxl"`, `"xxxl"`) |
+| `loading`   | `boolean`                                                                                                    | `false`     | Shows spinner, disables interaction, sets `aria-busy`                     |
+| `disabled`  | `boolean`                                                                                                    | `false`     | Disables the button                                                       |
+| `selected`  | `boolean`                                                                                                    | `false`     | Applies selected/active visual state, sets `aria-pressed`                 |
+| `text`      | `boolean`                                                                                                    | `false`     | Renders as borderless text in the variant's color                         |
+| `type`      | `"button" \| "submit" \| "reset"`                                                                            | `"button"`  | HTML button type                                                          |
+| `ariaLabel` | `string`                                                                                                     | --          | Accessible label (required for icon-only buttons)                         |
 
 ## Events
 
@@ -304,6 +304,7 @@ All visual properties are customizable through CSS custom properties. Each varia
 | `--button-border-radius`                    | `6px`                                     | Corner radius for all buttons |
 | `--button-focus-ring-color`                 | `var(--primary-300)`                      | Focus ring color              |
 | `--button-focus-ring-width`                 | `2px`                                     | Focus ring thickness          |
+| `--button-focus-ring-offset`                | `2px`                                     | Focus ring offset             |
 | `--button-{size}-height`                    | `--button-default-height: 36px`           | Height per size               |
 
 ## Accessibility
@@ -327,6 +328,6 @@ All visual properties are customizable through CSS custom properties. Each varia
 ## Architecture notes
 
 - VcButton calls `e.preventDefault()` on click to support `link` variant pattern. Form submit buttons must use `type="submit"` to bypass this.
-- `VcButtonGroup` integration is via provide/inject (`vcButtonGroupSize` injection key in `framework/injection-keys.ts`).
+- `VcButtonGroup` integration is via provide/inject using the `ButtonGroupKey` injection key defined in `framework/ui/components/atoms/vc-button/types.ts`.
 - Size aliases `xs`/`base` are kept for backward compatibility — slated for removal in v3.
 <!-- internal:end -->

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

@@ -57,12 +57,15 @@ The `shadow` prop adds an inset shadow as a scroll cue. Use it for content that
 
 ## CSS Variables
 
-| Variable                    | Default       | Description                          |
-| --------------------------- | ------------- | ------------------------------------ |
-| `--container-padding`       | `16px`        | Inner padding of the scrollable area |
-| `--container-bg`            | `transparent` | Background color                     |
-| `--container-border-radius` | `0`           | Border radius                        |
-| `--container-gap`           | `0`           | Gap between child elements           |
+| Variable                     | Default                                                                                | Description                                                     |
+| ---------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `--container-padding`        | `16px`                                                                                 | Inner padding of the scrollable area                            |
+| `--container-bg`             | `transparent`                                                                          | Background color                                                |
+| `--container-border-radius`  | `0`                                                                                    | Border radius                                                   |
+| `--container-gap`            | `0`                                                                                    | Gap between child elements                                      |
+| `--container-shadow-color`   | `var(--additional-950)`                                                                | Scroll-shadow color (RGB channels used by `--container-shadow`) |
+| `--container-shadow-opacity` | `0.1`                                                                                  | Scroll-shadow opacity                                           |
+| `--container-shadow`         | `0 3px 2px rgba(var(--container-shadow-color), var(--container-shadow-opacity)) inset` | Inset shadow applied when the `shadow` prop is set              |
 
 ## Exposed Methods
 

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

@@ -0,0 +1,42 @@
+---
+title: VcEnvironmentBanner
+category: components
+group: feedback
+---
+
+# VcEnvironmentBanner
+
+Centered badge pinned to the top of the application that labels the current
+environment (Development, QA, Demo, etc.). Mirrors the platform environment
+banner (vc-env-badge). Purely presentational — it renders the colored badge and
+its label, and does not know where the name comes from. Visibility and color are
+decided by the caller (see `useEnvironmentName`).
+
+## When to Use
+
+- Inside the app shell to make non-production environments visually obvious
+- When NOT to use: do not place it manually in blades — `VcApp` already mounts it
+
+## Props
+
+- `name: string` — environment label to render
+- `color?: string` — badge color (vc-shell theme tokens); recognized values are `primary | secondary | info | success | warning | danger | neutral`, any other value falls back to neutral via CSS, default `neutral`
+
+## Quick Start
+
+```vue
+<template>
+  <VcEnvironmentBanner
+    v-if="!isIgnored"
+    :name="environmentName"
+    :color="color"
+  />
+</template>
+
+<script setup>
+import { VcEnvironmentBanner } from "@vc-shell/framework";
+import { useEnvironmentName } from "@vc-shell/framework";
+
+const { environmentName, isIgnored, color } = useEnvironmentName();
+</script>
+```