@vc-shell/vc-app-skill 2.0.3-pr227.0c4f2c3 → 2.0.4-pr228.1e79eae

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

@@ -1,3 +1,12 @@
+---
+title: useMenuService
+category: composables
+group: services
+---
+
+!!! tip "Long page"
+Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Grouping Menu Items](#grouping-menu-items), [Badges and Indicators](#badges-and-indicators), or [API Reference](#api-reference).
+
 # useMenuService
 
 Accesses the navigation menu service for adding, removing, and badging menu items in the application sidebar. The service supports a pre-registration pattern that allows modules to declare menu items before the service is initialized, and a grouping system that organizes items into collapsible sections.

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

@@ -1,3 +1,9 @@
+---
+title: useModificationTracker
+category: composables
+group: forms
+---
+
 # useModificationTracker
 
 Tracks deep changes to a value and reports whether it has been modified compared to its original (pristine) state. This is the core composable behind the "unsaved changes" detection pattern in vc-shell blades. It handles complex nested objects, arrays, and the common API quirk where `null`, `undefined`, and `""` should be treated as equivalent empty values.

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

@@ -1,3 +1,9 @@
+---
+title: useNotifications
+category: composables
+group: notifications
+---
+
 # useNotifications
 
 Provides access to the push-notification system: reading notification history, filtering by type, marking as read, and registering handlers for real-time notifications. This composable wraps the Pinia-based `useNotificationStore` and adds type-based filtering and subscription management. It subscribes to specific notification types via the store's pub/sub system and automatically unsubscribes when the component scope is disposed.

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

@@ -1,7 +1,16 @@
+---
+title: usePermissions
+category: composables
+group: user
+---
+
 # usePermissions
 
 Checks whether the current user has specific platform permissions. This composable reads the authenticated user's permission list and provides a `hasAccess` function for conditional UI rendering and access control. It is client-side only -- it does not enforce server-side authorization.
 
+!!! warning "Client-side only"
+`usePermissions` is a UI guard, not a security boundary. Always enforce authorization on the server side as well.
+
 ## When to Use
 
 - Conditionally show or hide UI elements (buttons, toolbar items, sections) based on the current user's permissions

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

@@ -1,7 +1,16 @@
+---
+title: usePopup
+category: composables
+group: notifications
+---
+
 # usePopup
 
 Programmatic popup management for modal dialogs. Returns methods to open confirmation, error, and info dialogs, as well as fully custom popup components with typed props and emits. Popups are rendered in a dedicated container at the app root level, ensuring they overlay all other content including blades and sidebars.
 
+!!! tip "Always await showConfirmation"
+`showConfirmation` returns a `Promise<boolean>`. Always `await` it before executing the guarded action, or the action will run before the user responds.
+
 ## When to Use
 
 - Show confirmation dialogs before destructive actions (delete, discard, bulk operations)

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

@@ -1,3 +1,9 @@
+---
+title: useResponsive
+category: composables
+group: ui-state
+---
+
 # useResponsive
 
 Reactive breakpoint state for building responsive blade UIs. Returns refs that indicate the current viewport category (phone, tablet, mobile, desktop) and whether the device supports touch input. Replaces the legacy `$isMobile.value` global properties in templates and `inject(IsMobileKey)` in script setup with a single, consistent API.
@@ -53,12 +59,16 @@ Breakpoint thresholds: phone < 480px, tablet 480–1023px, desktop >= 1024px. Th
 
 Note: `isMobile` is the union of `isPhone` and `isTablet` — it covers all viewports below the desktop threshold.
 
+<!-- internal:start -->
+
 ## How It Works
 
 Under the hood, `useResponsive()` calls `inject()` for each breakpoint key (`IsMobileKey`, `IsDesktopKey`, etc.) with sensible defaults. The framework's root `VcApp` component provides these refs during app initialization using VueUse's `useBreakpoints`. Because the return values are the same `Ref<boolean>` instances provided at the app level, they are reactive and shared across all components.
 
 The defaults ensure the composable works even outside the VcApp provider tree (e.g., in unit tests or Storybook), defaulting to desktop mode.
 
+<!-- internal:end -->
+
 ## Recipe: Responsive Blade with Mobile Card Layout
 
 ```vue

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

@@ -1,3 +1,9 @@
+---
+title: useSettings
+category: composables
+group: services
+---
+
 # useSettings
 
 Loads and manages UI customization settings (logo, title, avatar) from the platform's Settings API. Supports overriding defaults with custom values.

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

@@ -1,3 +1,9 @@
+---
+title: useSettingsMenu
+category: composables
+group: services
+---
+
 # useSettingsMenu
 
 Accesses the settings menu service for registering and managing items in the application settings sidebar.

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

@@ -1,3 +1,9 @@
+---
+title: useSidebarState
+category: composables
+group: ui-state
+---
+
 # useSidebarState
 
 Controls the sidebar (left navigation panel) expansion, pinning, hover, and mobile menu state. This composable exposes a unified API for reading and toggling all sidebar states from any component within the VcApp tree. The sidebar has three independent dimensions: **pinned** (user explicitly locked it open, persisted to localStorage), **hover-expanded** (mouse is hovering over the collapsed sidebar on desktop), and **mobile menu** (overlay drawer on small screens). The derived `isExpanded` computed combines pinned and hover states for convenience.
@@ -61,6 +67,8 @@ const { isExpanded, isPinned, togglePin, openMenu, closeMenu } = useSidebarState
 | `openMenu`         | `() => void`               | Show the mobile menu overlay.                                                                                    |
 | `closeMenu`        | `() => void`               | Hide the mobile menu overlay.                                                                                    |
 
+<!-- internal:start -->
+
 ## Setup
 
 `provideSidebarState()` must be called once in VcApp's setup. It is idempotent -- if called multiple times in the same injection tree, it returns the existing instance. All descendant components then call `useSidebarState()` to access the shared state.
@@ -72,6 +80,8 @@ import { provideSidebarState } from "@vc-shell/framework";
 provideSidebarState();
 ```
 
+<!-- internal:end -->
+
 ## Recipe: Auto-Close Mobile Menu After Navigation
 
 ```vue

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

@@ -1,3 +1,9 @@
+---
+title: useSlowNetworkDetection
+category: composables
+group: ui-state
+---
+
 # useSlowNetworkDetection
 
 Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 10 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`.
@@ -56,6 +62,8 @@ 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)
@@ -73,6 +81,7 @@ The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequ
 3. If `isSlowNetwork` goes back to `true` within those 3 seconds → cancel dismiss, notification stays
 4. If the browser goes offline → immediately hide the slow notification (the offline notification takes over)
 5. If the browser comes back online and `isSlowNetwork` is still `true` → re-show
+<!-- internal:end -->
 
 ## Recipe: Custom Slow-Network Behavior in a Blade
 

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

@@ -1,3 +1,9 @@
+---
+title: useTheme
+category: composables
+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.
@@ -63,6 +69,8 @@ next();
 | `key`  | `string` | Theme identifier                                                             |
 | `name` | `string` | Localized display name, resolved from `localizationKey` or capitalized `key` |
 
+<!-- internal:start -->
+
 ## How It Works
 
 1. **Registration**: Themes are stored in a module-level `Ref<ThemeDefinition[]>` array. `register()` appends new definitions (skipping duplicates), and `unregister()` removes by key.
@@ -72,6 +80,7 @@ next();
 3. **Reactivity**: A `watchEffect` syncs the cycle-list state to `useColorMode`'s mode whenever the active theme changes.
 
 4. **Localization**: Display names are resolved via `vue-i18n`'s `t()` function using the `localizationKey`. If no key is provided, the theme's `key` is capitalized with lodash.
+<!-- internal:end -->
 
 ## Recipe: Module That Registers a Theme on Install
 

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

@@ -1,3 +1,12 @@
+---
+title: useToolbar
+category: composables
+group: services
+---
+
+!!! tip "Long page"
+Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Updating Button State Dynamically](#updating-button-state-dynamically), [Visibility and Permissions](#visibility-and-permissions), or [API Reference](#api-reference).
+
 # useToolbar
 
 Manages toolbar buttons for blades. Each blade in the application has its own toolbar area at the top of the blade header. `useToolbar` provides a scoped API to register, update, and remove buttons within that toolbar. It automatically resolves the current blade context and cleans up registered items when the component unmounts.

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

@@ -1,3 +1,9 @@
+---
+title: useUser
+category: composables
+group: user
+---
+
 # useUser
 
 Shared composable providing read-only access to the current user's session state. Returns reactive user details, authentication status, and core session operations (load, sign out, get access token). This is the primary composable for user-related reads in regular blades and components. It deliberately exposes a narrow API surface -- no sign-in, password reset, or admin operations -- to encourage separation of concerns between user consumption and user management.

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

@@ -1,3 +1,10 @@
+---
+title: useUserManagement
+category: composables
+group: user
+internal: true
+---
+
 # useUserManagement
 
 Shared composable exposing the full user management API: sign-in, sign-out, password reset, token validation, and login type discovery. This composable extends the same internal logic as `useUser` but surfaces the administrative and authentication-flow methods that `useUser` intentionally hides. The separation ensures that regular blades only have access to read-only user state, while auth pages and admin screens get the full API.

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

@@ -1,3 +1,9 @@
+---
+title: useWebVitals
+category: composables
+group: utilities
+---
+
 # useWebVitals
 
 Registers Core Web Vitals observers (FCP, LCP, CLS, INP, TTFB) and reports metrics via a callback. Core Web Vitals are Google's standardized set of real-user performance metrics that measure loading speed, interactivity, and visual stability. This composable wraps the `web-vitals` npm package and normalizes its output into a simple `{ name, value, rating }` shape. In development mode, metrics are logged to the console by default so you can catch performance regressions early without setting up external analytics.

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

@@ -1,3 +1,9 @@
+---
+title: useWidgets
+category: composables
+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.
@@ -59,6 +65,8 @@ None.
 | `registerWidget(widget, bladeId)`      | Global pre-registration. Widgets registered this way are picked up when `provideWidgetService()` creates the service. Use in module `install()`.       |
 | `registerExternalWidget(registration)` | Global pre-registration for cross-module widgets. These widgets are rendered in blades owned by other modules.                                         |
 
+<!-- internal:start -->
+
 ## How It Works
 
 The widget system has three layers:
@@ -71,6 +79,8 @@ The widget system has three layers:
 
 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.
 
+<!-- internal:end -->
+
 ## Recipe: Pre-Registering a Widget from a Module
 
 ```typescript

package/runtime/knowledge/docs/core/directives/autofocus/autofocus.docs.md

@@ -1,3 +1,10 @@
+---
+title: v-autofocus
+category: reference
+group: api/directives
+slug: v-autofocus
+---
+
 # v-autofocus Directive
 
 Focuses an element when it is mounted, conditionally based on the binding value.

package/runtime/knowledge/docs/core/directives/loading/loading.docs.md

@@ -1,3 +1,10 @@
+---
+title: v-loading
+category: reference
+group: api/directives
+slug: v-loading
+---
+
 # v-loading Directive
 
 Displays a loading overlay with a spinner on any element. Supports size variants, custom color, blur backdrop, fullscreen mode, and z-index control.

package/runtime/knowledge/docs/core/notifications/notifications.docs.md

@@ -1,3 +1,13 @@
+---
+title: Notifications
+category: plugins
+group: root
+slug: notifications
+---
+
+!!! info "Two-level architecture"
+Level 1 (module-level, always-on toasts) and Level 2 (blade-level, auto-cleanup subscriptions).
+
 # Notification System
 
 Centralized push notification handling for the vc-shell framework. Provides a two-level architecture: **Level 1** (module-level, always-on toasts and dropdown) and **Level 2** (blade-level, scoped subscriptions that auto-cleanup on unmount).
@@ -234,3 +244,14 @@ await store.markAllAsRead(); // optimistic update with rollback on failure
 - `framework/injection-keys.ts` -- `NotificationStoreKey`, `NotificationTemplatesKey`
 - `framework/shared/components/notifications/` -- Notification dropdown UI
 - `framework/core/api/platform.ts` -- `PushNotification`, `PushNotificationClient`
+
+<!-- internal:start -->
+
+## Internal Files
+
+- `framework/core/notifications/store.ts` -- `NotificationStore` implementation
+- `framework/core/notifications/toast-controller.ts` -- Toast lifecycle management
+- `framework/core/notifications/composables/` -- `useNotificationStore`, `useBladeNotifications`, `useNotificationContext`, `useBroadcastFilter`
+- `framework/core/notifications/types.ts` -- All notification type definitions
+
+<!-- internal:end -->

package/runtime/knowledge/docs/core/plugins/ai-agent/ai-agent.docs.md

@@ -1,3 +1,10 @@
+---
+title: AI Agent
+category: plugins
+group: root
+slug: ai-agent
+---
+
 # AI Agent Plugin
 
 Integrates an AI assistant panel (chatbot iframe) into the vc-shell application. Provides blade-aware context passing, bidirectional postMessage communication, and preview/apply workflows.

package/runtime/knowledge/docs/core/plugins/extension-points/extension-points.docs.md

@@ -1,3 +1,13 @@
+---
+title: Extension Points
+category: plugins
+group: root
+slug: extension-points
+---
+
+!!! tip "Navigation"
+This page is long. Use the [Table of Contents](#table-of-contents) to jump to the section you need.
+
 # Extension Points Plugin
 
 Extension points enable **cross-module UI composition** without direct imports. One module declares a named slot ("I accept plugins here"), and other modules inject components into that slot -- at any time, in any order. The system is fully reactive and order-independent.

package/runtime/knowledge/docs/core/plugins/global-error-handler/global-error-handler.docs.md

@@ -1,3 +1,10 @@
+---
+title: Global Error Handler
+category: plugins
+group: root
+slug: global-error-handler
+---
+
 # Global Error Handler Plugin
 
 Catches unhandled errors across the application and displays user-facing toast notifications. Covers Vue component errors, unhandled promise rejections, and uncaught JavaScript errors.

package/runtime/knowledge/docs/core/plugins/i18n/i18n.docs.md

@@ -1,3 +1,13 @@
+---
+title: Internationalization
+category: plugins
+group: root
+slug: i18n
+---
+
+!!! tip "Module integration"
+Modules provide translations via `defineAppModule({ locales })` — no direct plugin installation needed.
+
 # i18n Plugin
 
 Vue-i18n integration for the vc-shell framework. Provides a pre-configured i18n instance used by all modules for localization.

package/runtime/knowledge/docs/core/plugins/modularity/modularity.docs.md

@@ -1,3 +1,13 @@
+---
+title: Modularity
+category: plugins
+group: root
+slug: modularity
+---
+
+!!! tip "Navigation"
+This page is long. Use the [Table of Contents](#table-of-contents) to jump to the section you need.
+
 # Modularity Plugin
 
 The modularity plugin is the backbone of every vc-shell application. It defines how features are packaged as **modules**, how those modules are registered at runtime, and how they integrate with the framework's blade navigation, localization, menu, and notification systems.

package/runtime/knowledge/docs/core/plugins/permissions/permissions.docs.md

@@ -1,4 +1,11 @@
-# Permissions Plugin
+---
+title: Permissions
+category: plugins
+group: root
+slug: permissions
+---
+
+# Permissions
 
 Permission-based access control plugin. Exposes a global `$hasAccess` helper for checking user permissions throughout the application.
 

package/runtime/knowledge/docs/core/plugins/signalR/signalR.docs.md

@@ -1,3 +1,10 @@
+---
+title: SignalR
+category: plugins
+group: root
+slug: signalr
+---
+
 # SignalR Plugin
 
 Real-time push notification transport via ASP.NET SignalR. Connects to the platform's `/pushNotificationHub` and routes incoming messages to the notification store.

package/runtime/knowledge/docs/core/plugins/validation/validation.docs.md

@@ -1,3 +1,13 @@
+---
+title: Validation
+category: plugins
+group: root
+slug: validation
+---
+
+!!! tip "Zero setup"
+All vee-validate standard rules plus custom vc-shell rules are registered automatically — no per-component imports needed.
+
 # Validation Plugin
 
 Form validation integration using vee-validate. Registers all standard validation rules plus custom vc-shell rules for image dimensions, file weight, date comparisons, and BigInt safety.

package/runtime/knowledge/docs/core/services/services.docs.md

@@ -1,3 +1,10 @@
+---
+title: Services
+category: composables
+group: services
+placement: index
+---
+
 # Core Services
 
 Singleton service layer for registering and querying application-level entities: menu items, widgets, toolbar buttons, dashboard widgets, settings panels, app-bar items, and more.
@@ -11,6 +18,8 @@ Every service follows the same architecture:
 3. **Module-level helper** (e.g., `addMenuItem()`, `registerWidget()`) -- lets modules register items at import time, before the Vue app mounts.
 4. **Corresponding `use*` composable** (in `core/composables/`) -- injects the service instance via provide/inject for use inside components.
 
+<!-- internal:start -->
+
 ### Internal Building Blocks (`_internal/`)
 
 | Helper                      | Purpose                                                                                                                           |
@@ -19,6 +28,8 @@ Every service follows the same architecture:
 | `createBladeScopedRegistry` | Reactive `Map<bladeId, Item[]>` with register/unregister/update/clear. Used by WidgetService and ToolbarService.                  |
 | `createSimpleMapRegistry`   | Reactive `Map<id, Item>` with sorted computed output. Used by SettingsMenuService and AppBarMenuService.                          |
 
+<!-- internal:end -->
+
 ## Services
 
 | Service                        | Factory                              | Module-level API                                                | Key Type               |
@@ -78,8 +89,12 @@ removeMenuBadge("OrdersList");
 - `MenuService` builds a tree from flat items: items with `group` or `groupConfig` are nested under group nodes, sorted by `priority`.
 - `DashboardService` accepts a `hasAccess` callback for permission-based widget filtering.
 
-## Related
+<!-- internal:start -->
+
+## Related (internal paths)
 
 - `framework/core/composables/` -- `useMenu`, `useToolbar`, `useWidgets`, `useDashboard`, etc.
 - `framework/core/services/_internal/` -- shared registry and bus implementations
 - `framework/core/plugins/` -- services are created and provided during plugin installation
+
+<!-- internal:end -->

package/runtime/knowledge/docs/core/types/types.docs.md

@@ -1,3 +1,10 @@
+---
+title: Core Types
+category: reference
+group: api
+slug: types-core
+---
+
 # Core Types
 
 Shared TypeScript interfaces and types used across the vc-shell framework for validation, menus, toolbars, tables, assets, and service abstractions.

package/runtime/knowledge/docs/core/utilities/date/date-utilities.docs.md

@@ -1,3 +1,10 @@
+---
+title: Date Utilities
+category: reference
+group: api
+slug: date-utilities
+---
+
 # Date Utilities
 
 Pure functions for date formatting, relative time display, and Moment.js-to-date-fns format conversion. Built on `date-fns` with locale-aware output.

package/runtime/knowledge/docs/core/utilities/shared-utilities.docs.md

@@ -1,3 +1,10 @@
+---
+title: Shared Utilities
+category: reference
+group: api
+slug: shared-utilities
+---
+
 # Shared Utilities
 
 Helper functions and TypeScript type utilities used across the shared layer of the framework.

package/runtime/knowledge/docs/core/utilities/thumbnail/thumbnail.docs.md

@@ -1,3 +1,10 @@
+---
+title: Thumbnail Utility
+category: reference
+group: api
+slug: thumbnail
+---
+
 # Thumbnail URL Utility
 
 Transforms full-size image URLs into thumbnail variants by appending size suffixes before the file extension. VirtoCommerce backend generates thumbnails automatically with these suffixes.

package/runtime/knowledge/docs/core/utilities/utilities.docs.md

@@ -1,3 +1,10 @@
+---
+title: Utilities Overview
+category: reference
+group: api
+slug: utilities-overview
+---
+
 # Framework Utilities
 
 Utility functions exported from `@vc-shell/framework` via `core/utilities/index.ts`.

package/runtime/knowledge/docs/injection-keys.docs.md

@@ -1,3 +1,10 @@
+---
+title: Injection Keys
+category: reference
+group: api
+slug: injection-keys
+---
+
 # Injection Keys
 
 Centralized Vue `InjectionKey` symbols for the vc-shell framework's provide/inject dependency injection system. All keys are typed via `InjectionKey<T>` for full TypeScript safety.
@@ -76,6 +83,8 @@ This centralized approach has several advantages:
 | `IsTabletKey`  | `Ref<boolean>` | Tablet breakpoint      |
 | `IsTouchKey`   | `boolean`      | Touch device detection |
 
+<!-- internal:start -->
+
 ### Legacy Aliases (Deprecated)
 
 | Deprecated          | Use Instead          |
@@ -96,6 +105,8 @@ These keys existed in v1.2.3 but have been removed from the framework entirely.
 | `NotificationTemplatesSymbol` | Template system replaced by `NotificationStoreKey` + `useBladeNotifications()` |
 | `GlobalSearchKey`             | Internal concern now — no public replacement                                   |
 
+<!-- internal:end -->
+
 ## Usage Examples
 
 ### Injecting a service in a component