@vc-shell/vc-app-skill 2.0.0-alpha.23 → 2.0.0-alpha.24

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

@@ -2,6 +2,12 @@
 
 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.
 
+## When to Use
+
+- Register sidebar navigation items during module setup (use standalone `addMenuItem`)
+- Add, remove, or badge menu items at runtime inside components (use `useMenuService()`)
+- When NOT to use: for dashboard widgets -- use `useDashboard` / `registerDashboardWidget`; for settings-page entries -- use `useSettingsMenu`
+
 ## Quick Start
 
 ```typescript

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

@@ -2,6 +2,12 @@
 
 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.
 
+## When to Use
+
+- Conditionally show or hide UI elements (buttons, toolbar items, sections) based on the current user's permissions
+- Guard blade access or toolbar registration with client-side permission checks
+- When NOT to use: as the sole authorization mechanism -- always pair with server-side enforcement; for checking authentication status -- use `useUser` instead
+
 ## Quick Start
 
 ```typescript

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

@@ -2,6 +2,12 @@
 
 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.
 
+## When to Use
+
+- Add action buttons (Save, Delete, Refresh, Export) to a blade's toolbar header
+- Dynamically update button state (disabled, visible, icon) in response to loading or form changes
+- When NOT to use: for global app-bar actions -- use `useAppBarWidget`; for navigation links -- use `useMenuService`
+
 ## Quick Start
 
 ```typescript

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

@@ -6,6 +6,12 @@ Integrates an AI assistant panel (chatbot iframe) into the vc-shell application.
 
 The AI agent plugin embeds an external chatbot via an iframe panel that slides in from the right side of the application. It automatically sends the current blade context (user, active blade, selected items) to the chatbot and handles incoming commands (navigate, preview changes, download files). The plugin is optional -- if no `APP_AI_AGENT_URL` environment variable or `config.url` is provided, it silently skips installation.
 
+## When to Use
+
+- Embed an AI assistant chatbot panel into your vc-shell application with automatic blade context passing
+- Enable preview/apply workflows where AI suggests changes and the user confirms them
+- When NOT to use: if you don't have an AI agent backend -- the plugin silently skips when no `APP_AI_AGENT_URL` is set
+
 ## Installation / Registration
 
 ```typescript

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

@@ -4,6 +4,12 @@ Extension points enable **cross-module UI composition** without direct imports.
 
 This is how vc-shell achieves its modular architecture: modules can extend each other without compile-time dependencies.
 
+## When to Use
+
+- Module A needs to inject UI into Module B without a compile-time dependency (e.g., a "Reviews" tab inside a "Product Details" blade owned by another module)
+- You need order-independent, runtime-resolved composition -- modules can load in any order
+- When NOT to use: for simple parent-child communication within one module -- use props/slots/provide-inject instead; for data-only integration -- use events or a shared composable
+
 ---
 
 ## Table of Contents

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

@@ -8,6 +8,12 @@ In a complex admin shell with dynamically loaded modules, errors can originate f
 
 The global error handler solves this by installing three layers of error catching that cover all common error sources. Every caught error is parsed into a human-readable message and displayed as a toast notification, ensuring users always know when something goes wrong -- even if the module developer forgot to add error handling.
 
+## When to Use
+
+- This plugin is always active -- it catches unhandled errors from Vue components, async rejections, and uncaught JS errors automatically
+- You don't need to install or configure it -- the framework does this during app setup
+- When to be aware: if you handle errors manually in a composable (try/catch), the global handler won't fire for those -- which is the desired behavior
+
 ### Three Layers of Error Catching
 
 1. **Vue `app.config.errorHandler`** -- catches errors thrown inside Vue components (render functions, lifecycle hooks, watchers, event handlers)

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

@@ -8,6 +8,12 @@ The vc-shell framework supports multiple languages through a centralized `vue-i1
 
 This approach ensures consistency across the application: switching the active locale updates all modules simultaneously, fallback behavior is uniform, and there is a single source of truth for the current language.
 
+## When to Use
+
+- Add translated labels, messages, and error strings to any module (provide locale files via `defineAppModule({ locales })`)
+- Access the current locale or switch languages at runtime via `useI18n()` or `useLanguages()`
+- When NOT to use: this plugin is always active -- you never skip it. If you only need a single language, still use i18n keys for consistency
+
 Modules do not install this plugin directly. Instead, they provide their locale messages via `defineAppModule({ locales })`, and the framework merges them into the global i18n instance using `i18n.global.mergeLocaleMessage()` during module installation.
 
 ## Installation / Registration
@@ -175,6 +181,74 @@ import { i18n } from "@vc-shell/framework";
 const message = i18n.global.t("MY_MODULE.SOME_KEY");
 ```
 
+## Customizing Framework Translations
+
+The framework exports its locale files as typed ES modules. App developers can import them to create full translations or override specific keys.
+
+### Importing Framework Locales
+
+```typescript
+import en from '@vc-shell/framework/locales/en'
+import de from '@vc-shell/framework/locales/de'
+import type { VcShellLocale, VcShellLocalePartial } from '@vc-shell/framework/locales/types'
+```
+
+The `VcShellLocale` interface provides autocomplete for all framework translation keys. Use it when creating a full translation to ensure no keys are missed.
+
+### Creating a New Language
+
+Spread the English locale as a base and override all sections:
+
+```typescript
+import en from '@vc-shell/framework/locales/en'
+import type { VcShellLocale } from '@vc-shell/framework/locales/types'
+
+const fr: VcShellLocale = {
+  ...en,
+  CORE: { THEMES: { LIGHT: "Clair", DARK: "Sombre" } },
+  SHELL: {
+    ...en.SHELL,
+    ACCOUNT: {
+      SETTINGS: "Paramètres",
+      CHANGE_PASSWORD: "Changer le mot de passe",
+      PROFILE: "Profil",
+      LOGOUT: "Déconnexion",
+    },
+  },
+  COMPONENTS: {
+    ...en.COMPONENTS,
+    // ... translate component strings
+  },
+}
+
+// Register in your app's main.ts or plugin setup:
+app.config.globalProperties.$mergeLocaleMessage('fr', fr)
+```
+
+### Overriding Specific Keys
+
+Use `VcShellLocalePartial` for partial overrides — all keys are optional:
+
+```typescript
+import type { VcShellLocalePartial } from '@vc-shell/framework/locales/types'
+
+const overrides: VcShellLocalePartial = {
+  SHELL: { ACCOUNT: { LOGOUT: "Sign Out" } }
+}
+
+app.config.globalProperties.$mergeLocaleMessage('en', overrides)
+```
+
+### Validating Your Translation
+
+Run the CLI tool to check for missing or extra keys:
+
+```bash
+npx vc-check-locales ./src/locales/fr.json
+```
+
+In development mode, the framework also logs console warnings when a translation key is accessed but has no value for the current locale.
+
 ## Related
 
 - `framework/core/plugins/modularity/index.ts` -- `defineAppModule` merges locale messages via `i18n.global.mergeLocaleMessage()`

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

@@ -4,6 +4,12 @@ The modularity plugin is the backbone of every vc-shell application. It defines
 
 If you are building anything in vc-shell -- a new page, a CRUD flow, a dashboard widget, a notification handler -- you will start by creating a module.
 
+## When to Use
+
+- Package any feature as a self-contained unit with blades, menu items, locales, notifications, and permissions
+- Every vc-shell feature starts here -- `defineAppModule()` is the entry point for all module development
+- When NOT to use: for shared utilities or composables that have no UI -- export them as plain TypeScript modules instead
+
 ---
 
 ## Table of Contents

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

@@ -8,6 +8,12 @@ The VirtoCommerce platform uses a role-based permission system where each user i
 
 The plugin installs the `hasAccess()` function from the `usePermissions()` composable as both a Vue global property (`$hasAccess`) and a provide/inject injectable (`"$hasAccess"`). This means permission checks are available everywhere: in templates via `$hasAccess()`, in composition API code via `usePermissions()`, and in any injecting component.
 
+## When to Use
+
+- Show/hide UI elements based on user permissions: `v-if="$hasAccess('order:create')"` in templates or `hasAccess()` in composables
+- Guard toolbar buttons, menu items, or entire blade sections with client-side permission checks
+- When NOT to use: as the sole authorization layer -- always enforce permissions server-side too; for authentication checks (logged in / logged out) -- use `useUser` instead
+
 The framework installs this plugin automatically during app setup. Module developers never need to register it manually.
 
 ## Installation / Registration

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

@@ -4,6 +4,12 @@ Real-time push notification transport via ASP.NET SignalR. Connects to the platf
 
 ## Overview
 
+## When to Use
+
+- Receive real-time push notifications from the platform (order updates, export progress, background job status)
+- Display live notification toasts and badge counts without polling
+- When NOT to use: for request-response API calls -- use `useApiClient`; for periodic data refresh -- use polling with `useAsync` instead
+
 The VirtoCommerce platform uses ASP.NET SignalR to push real-time notifications to connected clients. These notifications cover events like order status changes, catalog exports completing, background job progress, and system alerts.
 
 The SignalR plugin establishes a persistent WebSocket connection to the platform hub and listens for two event channels:

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

@@ -8,6 +8,12 @@ Form validation is a critical part of any admin interface. The vc-shell framewor
 
 This plugin auto-registers every rule from `@vee-validate/rules` (required, email, min, max, etc.) via `defineRule()`, then adds custom rules specific to vc-shell use cases. Once registered, rules are available globally in any `<Field>` component, `useField()` composable, or validation schema -- no per-component imports needed.
 
+## When to Use
+
+- Validate form fields in blades using `<Field>` components or `useField()` with declarative rules (`required`, `email`, `min`, etc.)
+- Use custom vc-shell rules: image dimensions (`validateImageMinSize`), file weight, date comparisons, BigInt safety
+- When NOT to use: for API-level validation -- that belongs server-side; for simple presence checks on non-form data -- use plain conditionals
+
 The framework imports this module during setup. No manual installation is needed by module developers.
 
 ## Installation / Registration

package/runtime/knowledge/docs/modules/assets-manager/assets-manager.docs.md

@@ -4,7 +4,7 @@ A built-in blade module for managing file assets (images, documents, archives).
 
 ## Overview
 
-The Assets Manager is registered as an app module via `defineAppModule` and opened as a child blade from any parent blade that needs asset management. The parent provides handler callbacks for upload, edit, and remove operations -- the module handles the UI and delegates data mutations back to the parent.
+The Assets Manager is registered as an app module via `defineAppModule` and opened as a child blade from any parent blade that needs asset management. The parent creates a `useAssetsManager` instance and passes it through `options.manager` -- the module handles the UI and delegates data mutations through the manager.
 
 ## Module Registration
 
@@ -17,56 +17,51 @@ import { AssetsManagerModule } from "@vc-shell/framework";
 
 The module exports `AssetsManagerModule` (a Vue plugin) and the `AssetsManager` component, which is declared as a global component.
 
-## Props (Options)
+## Options (via `useBlade`)
 
-The blade receives its configuration via the `options` prop when opened:
+The blade reads its configuration from `options` via `useBlade<AssetsManagerOptions>()` (not props):
 
 | Option | Type | Description |
 |---|---|---|
-| `title` | `string` | Custom blade title (defaults to i18n `ASSETS_MANAGER.TITLE`) |
-| `assets` | `ICommonAsset[]` | Initial array of assets to display |
-| `loading` | `Ref<boolean>` | Reactive loading state for the table overlay |
-| `assetsEditHandler` | `(assets) => ICommonAsset[]` | Called when assets are reordered or edited |
-| `assetsUploadHandler` | `(files) => Promise<ICommonAsset[]>` | Called with selected files for upload |
-| `assetsRemoveHandler` | `(assets) => Promise<ICommonAsset[]>` | Called to delete selected assets |
-| `disabled` | `boolean` | When true, hides upload/delete actions and disables reordering |
-| `hiddenFields` | `string[]` | Fields to hide in the detail view |
+| `title` | `string?` | Custom blade title (defaults to i18n `ASSETS_MANAGER.TITLE`) |
+| `manager` | `UseAssetsManagerReturn` | The asset manager instance from `useAssetsManager()`. **Must be wrapped in `markRaw()`** |
+| `disabled` | `boolean?` | When true, hides upload/delete actions and disables reordering |
+| `hiddenFields` | `string[]?` | Fields to hide in the detail view |
+
+> **Breaking change:** The old options (`assets`, `loading`, `assetsUploadHandler`, `assetsEditHandler`, `assetsRemoveHandler`) have been removed. Pass a single `manager` instance instead. See [migration guide #32](../../../migration/32-use-assets-manager.md).
 
 ## Usage
 
 Open the Assets Manager as a child blade:
 
 ```typescript
-import { useBladeNavigation } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import { useBlade, useAssetsManager } from "@vc-shell/framework";
+
+const { openBlade } = useBlade();
 
-const { openBlade, resolveBladeByName } = useBladeNavigation();
+const assetsManager = useAssetsManager(product.assets, {
+  uploadPath: () => `/catalog/${product.id}`,
+  confirmRemove: () => confirm("Delete selected assets?"),
+});
 
 openBlade({
-  blade: resolveBladeByName("AssetsManager"),
+  name: "AssetsManager",
   options: {
-    assets: product.assets,
-    loading: isLoading,
+    // IMPORTANT: markRaw prevents Vue from wrapping the manager in a
+    // deep reactive proxy. Without it, blade options (stored in
+    // ref<BladeDescriptor[]>) auto-unwrap nested Refs, breaking
+    // manager.items.value and manager.loading.value access.
+    manager: markRaw(assetsManager),
     disabled: !canEdit.value,
     hiddenFields: ["sortOrder"],
-    assetsUploadHandler: async (files) => {
-      const uploaded = await uploadFiles(files);
-      return [...product.assets, ...uploaded];
-    },
-    assetsEditHandler: (assets) => {
-      product.assets = assets;
-      return assets;
-    },
-    assetsRemoveHandler: async (assets) => {
-      await deleteAssets(assets);
-      return product.assets.filter(a => !assets.includes(a));
-    },
   },
 });
 ```
 
 ## Features
 
-- **Table view**: Displays assets with thumbnail, name, size, sort order, and creation date columns.
+- **Table view**: Displays assets with thumbnail, name, size, sort order, and creation date columns using `VcDataTable` with declarative `<VcColumn>` API.
 - **Upload**: Via toolbar button or drag-and-drop onto the table. Handles duplicate filenames by appending `_1`, `_2`, etc.
 - **Delete**: Toolbar delete button (requires selection) and per-row action button.
 - **Reorder**: Drag-and-drop row reordering when not in readonly mode.
@@ -79,17 +74,18 @@ openBlade({
 | Button | Condition | Action |
 |---|---|---|
 | Add | `!disabled` | Opens file picker for upload |
-| Delete | `!disabled` and items selected | Calls `assetsRemoveHandler` with selected items |
+| Delete | `!disabled` and items selected | Calls `manager.removeMany()` with selected items |
 
 ## Tips
 
-- All mutation handlers must return the updated full asset array -- the module replaces its internal list with the return value.
+- **Always use `markRaw()` when passing manager through blade options.** Blade descriptors are stored in `ref<BladeDescriptor[]>()`, which creates a deep reactive proxy. Vue auto-unwraps `Ref` values inside reactive objects, so `manager.items` would become a plain array instead of `Ref<AssetLike[]>` — breaking `.value` access. `markRaw()` prevents this by telling Vue not to make the manager reactive.
+- The `manager` object (from `useAssetsManager()`) owns the reactive asset list and all mutation methods. The blade reads `manager.items` and calls `manager.upload()`, `manager.remove()`, `manager.removeMany()`, `manager.reorder()`, and `manager.updateItem()`.
 - The `disabled` prop makes the entire blade readonly: no upload, no delete, no reorder.
 - Asset thumbnails use `isImage()` from shared utilities to determine if an image preview or a file-type icon should be shown.
-- The module uses `useBladeNavigation()` internally to open the detail sub-blade.
+- The module uses `useBlade()` internally to open the detail sub-blade.
 
 ## Related
 
+- `framework/core/composables/useAssetsManager/` -- `useAssetsManager`, `AssetLike`, `UseAssetsManagerReturn`
 - `framework/shared/utilities/assets.ts` -- `isImage`, `getFileThumbnail`, `readableSize`
 - `framework/core/utilities/date/` -- `formatDateRelative` for creation dates
-- `framework/core/types/` -- `ICommonAsset` interface

package/runtime/knowledge/docs/shell/components/logout-button/logout-button.docs.md

@@ -1,6 +1,6 @@
 # LogoutButton
 
-Settings menu action that signs the user out, closes all open blades, and redirects to the login page. This component encapsulates the full sign-out flow: it injects `CloseSettingsMenuKey` to dismiss the parent menu before navigation, calls `useUserManagement().signOut()` to clear the authentication token, and uses `useBladeNavigation()` to close any open blades so the user does not return to stale blade state on next login.
+Settings menu action that signs the user out, closes all open blades, and redirects to the login page. This component encapsulates the full sign-out flow: it injects `CloseSettingsMenuKey` to dismiss the parent menu before navigation, calls `useUserManagement().signOut()` to clear the authentication token, and uses `useBladeStack()` to close open child blades so the user does not return to stale blade state on next login.
 
 ## When to Use
 
@@ -37,7 +37,7 @@ settingsMenu.register({
 
 ## Key Props
 
-This component has no props. It uses `useUserManagement()` for sign-out and `useBladeNavigation()` to close blades.
+This component has no props. It uses `useUserManagement()` for sign-out and `useBladeStack()` to close blades.
 
 ## Recipe: Module with Complete Settings Menu Registration
 
@@ -71,7 +71,7 @@ export default {
 ## Details
 
 - **Menu dismissal**: Before starting the sign-out flow, the component calls the injected `CloseSettingsMenuKey` function to close the dropdown. This prevents a visual artifact where the menu stays open while the page redirects.
-- **Blade cleanup**: All open blades are closed via `useBladeNavigation()` before redirecting. This avoids orphaned blade state in the navigation stack.
+- **Blade cleanup**: All open child blades are closed via `useBladeStack()` before redirecting. This avoids orphaned blade state in the navigation stack.
 - **Redirect**: After sign-out completes, the user is redirected to the `/login` route.
 - **External providers**: If the user signed in through an external SSO provider, the sign-out flow also triggers the provider's logout redirect via `useExternalProvider().signOut()`.
 

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

@@ -2,6 +2,17 @@
 
 A versatile button component supporting 9 style variants, 5 size options, loading state, and icon integration. VcButton is the primary interactive element for triggering actions throughout the application -- from toolbar buttons and form submissions to inline table actions and navigation.
 
+## When to Use
+
+| Scenario | Component |
+|----------|-----------|
+| Triggering an action (save, delete, submit) | **VcButton** |
+| Navigating to another URL or route | `<router-link>` or `<a>` tag |
+| Action inside a blade toolbar | `IBladeToolbar` items (rendered as buttons automatically) |
+| Inline text-style link within a paragraph | Native `<a>` or `<router-link>` |
+
+Use VcButton for any user-initiated action that does not navigate to a URL. **Do not use** VcButton for navigation -- the `link` variant looks like a link but calls `preventDefault()`, so actual URL navigation will not work. For toolbar actions, define `IBladeToolbar` objects instead of placing VcButton manually.
+
 ## Quick Start
 
 ```vue

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

@@ -2,6 +2,17 @@
 
 A bordered container with an optional header, icon, action buttons, and collapsible body. VcCard groups related content into visually distinct sections on blades and detail views. It supports three color variants for semantic meaning and smooth animated collapse/expand.
 
+## When to Use
+
+| Scenario | Component |
+|----------|-----------|
+| Grouping form fields or content with a header | **VcCard** |
+| Scrollable content wrapper without a header | [VcContainer](../vc-container/) |
+| Collapsible section with rich toggle behavior | [VcAccordion](../../molecules/vc-accordion/) (for multiple exclusive panels) |
+| Alert or notification banner | [VcBanner](../vc-banner/) |
+
+Use VcCard to visually separate content sections on a blade -- especially when you need a titled header, action buttons, or collapsible body. **Do not use** VcCard for dismissible alerts or status messages (use `VcBanner`), and avoid nesting VcCard when a simple `VcContainer` with padding would suffice.
+
 ## Quick Start
 
 ```vue

package/runtime/knowledge/docs/ui/components/organisms/vc-blade/vc-blade.docs.md

@@ -25,6 +25,17 @@ Traditional admin panels use page-based routing: click a link, the entire viewpo
 | Layout | Full viewport | Side-by-side panels |
 | Depth | Flat (1 level) | Unlimited nesting |
 
+## When to Use
+
+| Scenario | Component |
+|----------|-----------|
+| Stacked panel with toolbar, header, and lifecycle | **VcBlade** |
+| One-off confirmation or input dialog | [VcPopup](../../molecules/vc-popup/) |
+| Full-page route without blade stack | Vue Router view |
+| Scrollable content section inside a blade | [VcContainer](../../molecules/vc-container/) |
+
+Use VcBlade for every screen in a vc-shell application -- it is the standard container that integrates with the navigation system, toolbar, breadcrumbs, and unsaved-changes guards. **Do not use** VcBlade for transient dialogs (use `VcPopup` / `usePopup()`) or for content areas that do not need their own header and close button.
+
 ## Quick Start
 
 ```vue

package/runtime/knowledge/docs/ui/components/organisms/vc-table/vc-data-table.docs.md

@@ -18,6 +18,17 @@ Columns are defined as `<VcColumn>` child components -- no configuration objects
 - State persistence (column widths, order, sort, filters) to localStorage/sessionStorage
 - Full TypeScript generics -- `VcDataTable<Product>` propagates types to events and slots
 
+## When to Use
+
+| Scenario | Component |
+|----------|-----------|
+| Tabular data with sorting, selection, pagination | **VcDataTable** |
+| Simple short list without table features | `v-for` with custom markup |
+| Image/card grid layout | [VcGallery](../vc-gallery/) |
+| Key-value detail display | [VcField](../../molecules/vc-field/) or [VcCard](../../atoms/vc-card/) |
+
+Use VcDataTable whenever you need structured rows and columns with any combination of sorting, filtering, inline editing, or column management. **Do not use** VcDataTable for simple lists of 5-10 items that need no table features -- a plain `v-for` loop is lighter. For thumbnail/card grids, prefer VcGallery.
+
 ---
 
 ## Table of Contents
@@ -1329,6 +1340,7 @@ function onRowRemove(event: { data: Product; index: number; cancel: () => void }
 
 | Event | Payload | Description |
 |-------|---------|-------------|
+| `update:editingRows` | `T[]` | v-model update for currently editing rows. |
 | `cell-edit-init` | `{ data: T, field: string, index: number }` | Cell entered edit mode. |
 | `cell-edit-complete` | `{ data: T, field: string, newValue: unknown, index: number }` | Cell edit committed. |
 | `cell-edit-cancel` | `{ data: T, field: string, index: number }` | Cell edit cancelled. |

package/runtime/knowledge/index.md

@@ -29,9 +29,23 @@ Notable location: `useDataTableSort.docs.md` is under `ui/composables/`, not `co
 - `knowledge/patterns/blade-navigation.md`
 
 ### Framework docs to read (basename glob):
+
+**Core table components (always read):**
 - `**/vc-blade.docs.md`
 - `**/vc-data-table.docs.md`
 - `**/vc-pagination.docs.md`
+
+**Cell renderer components (read for custom #body slots in VcColumn):**
+- `**/vc-status.docs.md` — for status/state columns (variant-colored badge)
+- `**/vc-status-icon.docs.md` — for boolean columns (check/cross icon)
+- `**/vc-badge.docs.md` — for count/tag columns (numeric badge, category tag)
+- `**/vc-image.docs.md` — for image/avatar/thumbnail columns
+- `**/vc-link.docs.md` — for clickable URL/email columns
+- `**/vc-progress.docs.md` — for percentage/progress columns
+- `**/vc-rating.docs.md` — for rating columns (read-only stars)
+- `**/vc-tooltip.docs.md` — for columns with truncated text that need hover detail
+
+**Composable docs (always read):**
 - `**/useBlade.docs.md`
 - `**/useAsync.docs.md`
 - `**/useLoading.docs.md`
@@ -50,17 +64,63 @@ Notable location: `useDataTableSort.docs.md` is under `ui/composables/`, not `co
 - `knowledge/patterns/blade-navigation.md`
 
 ### Framework docs to read (basename glob):
+
+**Core form components (always read):**
 - `**/vc-blade.docs.md`
 - `**/vc-form.docs.md`
 - `**/vc-input.docs.md`
 - `**/vc-select.docs.md`
 - `**/vc-switch.docs.md`
+
+**Extended form components (read based on field types — see Field Type → Component Mapping in details-blade-pattern.md):**
+- `**/vc-textarea.docs.md` — for `text` / `rich-text` fields
+- `**/vc-editor.docs.md` — for `rich-text` fields (WYSIWYG HTML editor)
+- `**/vc-date-picker.docs.md` — for `date-time` fields (calendar widget, preferred over VcInput type="datetime-local")
+- `**/vc-checkbox.docs.md` — for `boolean` fields (alternative to VcSwitch for "agree/accept" semantics)
+- `**/vc-checkbox-group.docs.md` — for `multi-select` fields with few static options
+- `**/vc-radio-group.docs.md` — for `enum` fields with 2-5 options
+- `**/vc-input-currency.docs.md` — for `currency` fields (formatted monetary input)
+- `**/vc-multivalue.docs.md` — for `multi-select` / `tags` fields (tag-style multi-picker)
+- `**/vc-rating.docs.md` — for `rating` fields (star rating)
+- `**/vc-slider.docs.md` — for `range` fields (numeric slider)
+- `**/vc-color-input.docs.md` — for `color` fields
+- `**/vc-file-upload.docs.md` — for `file` fields (file attachment upload)
+- `**/vc-input-group.docs.md` — for grouped inputs (prefix/suffix patterns like URL, phone)
+
+**Read-only display components (read when blade has view-only fields):**
+- `**/vc-field.docs.md` — for read-only key-value display (horizontal label:value, copyable, tooltip). Use instead of VcInput for non-editable data.
+
+**Layout & display components (read when the form has sections or read-only data):**
+- `**/vc-card.docs.md` — for grouping form sections visually (ALWAYS use for 3+ field groups)
+- `**/vc-accordion.docs.md` — for collapsible form sections
+- `**/vc-badge.docs.md` — for status indicators in form headers
+- `**/vc-banner.docs.md` — for contextual alerts at top of form (error, info, warning states)
+- `**/vc-hint.docs.md` — for field-level help text or secondary descriptions
+- `**/vc-status.docs.md` — for status display in read-only areas
+- `**/vc-button.docs.md` — for inline action buttons (e.g., inside banners)
+
+**Media components (read when entity has images/gallery/video):**
+- `**/vc-image-upload.docs.md` — for `image` fields (single image upload with preview)
+- `**/vc-gallery.docs.md` — for `gallery` / `images` fields (multi-image management)
+- `**/vc-image.docs.md` — for read-only image display
+
+**Composable docs (always read):**
 - `**/useBlade.docs.md`
 - `**/useAsync.docs.md`
 - `**/useModificationTracker.docs.md`
 - `**/useLoading.docs.md`
 - `**/validation.docs.md`
 
+**Composable docs (read when entity has related sub-entities):**
+- `**/useBladeWidgets.docs.md` — for blade sidebar widgets (icon buttons with badge counts that open child blades)
+
+### Advanced patterns to read (based on design intent):
+
+Read `knowledge/patterns/` files when the design requires these patterns:
+- `knowledge/patterns/blade-widget.md` — when entity has related sub-entities that need sidebar widget navigation
+- `knowledge/patterns/dashboard-widget.md` — when module should contribute a dashboard card
+- `knowledge/patterns/notification-template.md` — when module needs push notification rendering
+
 ---
 
 ## Module Assembler