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

package/runtime/knowledge/docs/ui/components/molecules/vc-input/vc-input.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcInput
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcInput
 
 A single-line text input component for forms in vc-shell applications. Supports multiple input types (text, number, password, email, and more), prefix/suffix decorations, inner/outer slot content, built-in clearable state, password visibility toggle, loading indicator, debounced model updates, and integration with vee-validate for validation.
 
+::storybook id="form-vcinput--default"
+
 ## When to Use
 
 | Scenario                                             | Component                                                              |
@@ -44,10 +55,14 @@ const productName = ref("");
 
 This renders a labeled text input with placeholder text. The value is two-way bound via `v-model`.
 
+::storybook id="form-vcinput--all-states" height="450"
+
 ---
 
 ## Input Types
 
+::storybook id="form-vcinput--input-types" height="500"
+
 VcInput supports the following `type` values. Each type adjusts the native `<input>` behavior and, in some cases, adds extra UI or filtering logic.
 
 | Type             | Behavior                                                                             |
@@ -298,6 +313,8 @@ Override the default error message or hint text rendering.
 
 ## Sizes
 
+::storybook id="form-vcinput--all-sizes"
+
 Two size variants are available:
 
 | Size        | Height | Use case                                   |
@@ -771,3 +788,16 @@ VcInput follows WAI-ARIA best practices for form fields:
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- The `type="date"`, `type="datetime-local"`, and `type="color"` values trigger internal delegation — the component renders `VcDatePicker` or `VcColorInput` instead of a native `<input>`. All forwarded props are passed via `v-bind="$attrs"`.
+- Debounce is implemented via a `useDebounceFn` wrapper from VueUse. The internal `temp` ref holds the raw typing value; the `modelValue` update is deferred.
+- `number` / `integer` type filtering uses `keydown` event guards — not `input` event filtering — to block `-`, `+`, `e`, and (for `integer`) `.` keys before they reach the input.
+- `type="password"` show/hide toggle is controlled by `showPassword` ref; the native `input` type toggles between `"password"` and `"text"`.
+- The `control` slot replaces the native `<input>` with an arbitrary element. The `emitValue` scope function wraps the debounce logic, so custom controls respect the `debounce` prop automatically.
+- Source file: `framework/ui/components/molecules/vc-input/vc-input.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-input-currency/vc-input-currency.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcInputCurrency
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcInputCurrency
 
 A specialized currency input that combines locale-aware number formatting (grouping separators, decimal precision) with a dropdown for selecting the currency. Built on top of [vue-currency-input](https://dm4t2.github.io/vue-currency-input/) and [VcInputDropdown](../vc-input-dropdown/).
 
+::storybook id="form-vcinputcurrency--default"
+
 ## When to Use
 
 - Entering monetary values with currency selection (e.g., product prices, order totals, shipping costs)
@@ -60,6 +71,8 @@ The dropdown portion renders the available currencies. Use `optionLabel` and `op
 
 ### Precision Control
 
+::storybook id="form-vcinputcurrency--precision-options"
+
 The `precision` prop controls the number of decimal places (0--15). The formatting engine rounds and pads the value accordingly.
 
 ```vue
@@ -146,6 +159,8 @@ const form = reactive({
 
 ### States
 
+::storybook id="form-vcinputcurrency--with-error"
+
 ```vue
 <!-- Required -->
 <VcInputCurrency v-model="price" v-model:option="currency" :options="currencies" label="Price" required />
@@ -334,3 +349,15 @@ Additionally inherits all `--input-*` CSS variables from VcInput/VcInputDropdown
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Built as a wrapper around `VcInputDropdown`. The numeric input side uses `vue-currency-input` for locale-aware formatting; the right side is `VcInputDropdown`'s built-in dropdown.
+- The minus key (`-`) and exponential notation key (`e`) are blocked at the `keydown` level, not via `input` validation.
+- `precision` is forwarded directly to `vue-currency-input`'s `CurrencyInputOptions`.
+- `currencyDisplay` maps to the `vue-currency-input` option of the same name.
+- Source file: `framework/ui/components/molecules/vc-input-currency/vc-input-currency.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-input-dropdown/vc-input-dropdown.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcInputDropdown
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcInputDropdown
 
 A composite component that combines a text input field with a dropdown option selector in a single control. The user types a value in the input while also selecting a category, unit, or format from the attached dropdown.
 
+::storybook id="form-vcinputdropdown--default"
+
 ## When to Use
 
 - Input value paired with a unit selector (e.g., "100 cm", "50 kg")
@@ -42,6 +53,8 @@ The component uses a dual `v-model` pattern: `v-model` controls the input value,
 
 ## Object Options
 
+::storybook id="form-vcinputdropdown--with-object-options"
+
 When options are objects instead of primitives, use `optionValue` and `optionLabel` to tell the component which properties to use:
 
 ```vue
@@ -106,6 +119,8 @@ Supported types: `"text"`, `"password"`, `"email"`, `"tel"`, `"number"`, `"integ
 
 ## Component States
 
+::storybook id="form-vcinputdropdown--states"
+
 VcInputDropdown inherits all standard form field states:
 
 ```vue
@@ -298,3 +313,14 @@ Replace the default dropdown toggle with a custom element using the `button` slo
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Internally composed of two elements side-by-side: a `VcInput` for the text portion and a `VcSelect`-like dropdown panel for the option portion.
+- The `button` slot replaces only the dropdown toggle button element, not the entire dropdown panel.
+- The `option` slot receives `{ index, opt, selected, toggleOption }` — `toggleOption` must be called to actually select the item.
+- Source file: `framework/ui/components/molecules/vc-input-dropdown/vc-input-dropdown.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-input-group/vc-input-group.docs.md

@@ -1,7 +1,15 @@
+---
+title: VcInputGroup
+category: components
+group: form
+---
+
 # VcInputGroup
 
 A semantic `<fieldset>` wrapper that groups related form controls under a shared label, error state, and ARIA context. Propagates `disabled` and `name` to child controls via provide/inject.
 
+::storybook id="form-vcinputgroup--form-fields"
+
 ## When to Use
 
 - Grouping related form fields with a shared section label (e.g., "Billing details", "Shipping address")
@@ -56,6 +64,8 @@ const lastName = ref("");
 
 ### Radio Group
 
+::storybook id="form-vcinputgroup--radios-horizontal"
+
 ```vue
 <VcInputGroup label="Payment method" role="radiogroup" orientation="horizontal" name="payment">
   <VcRadioButton v-model="payment" value="card" label="Card" />
@@ -111,3 +121,14 @@ const lastName = ref("");
 - [VcRadioButton](../vc-radio-button/) -- radio buttons to group
 - [VcInput](../vc-input/) -- text inputs to group
 - [VcSelect](../vc-select/) -- selects to group
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `disabled` and `name` are provided via Vue's provide/inject mechanism using injection keys from `framework/injection-keys.ts`. Child form controls (`VcInput`, `VcRadioButton`, etc.) inject these to inherit group-level state automatically.
+- The `orientation` prop controls flex direction (`column` vs `row`) on the fieldset's content area.
+- Source file: `framework/ui/components/molecules/vc-input-group/vc-input-group.vue`
+- Context file: `framework/ui/components/molecules/vc-input-group/context.ts`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-menu/vc-menu.docs.md

@@ -1,7 +1,15 @@
+---
+title: VcMenu
+category: components
+group: navigation
+---
+
 # VcMenu
 
 Compositional navigation menu component for building sidebar navigation with sections, groups, nested items, badges, and loading skeletons.
 
+::storybook id="navigation-vcmenu--default"
+
 ## When to Use
 
 - Building the main navigation sidebar in admin applications
@@ -64,6 +72,8 @@ import { VcMenu, VcMenuItem, VcMenuGroup } from "@vc-shell/framework";
 
 ## Common Patterns
 
+::storybook id="navigation-vcmenu--sections"
+
 ### Section Groups with Nested Items
 
 ```vue
@@ -93,6 +103,8 @@ import { VcMenu, VcMenuItem, VcMenuGroup } from "@vc-shell/framework";
 
 ### Collapsed State
 
+::storybook id="navigation-vcmenu--collapsed"
+
 When `expanded` is `false`, the menu shows only icons and letter abbreviations. Groups show tooltips on hover. The container width should be reduced (e.g., 64px).
 
 ## CSS Variables
@@ -113,3 +125,15 @@ When `expanded` is `false`, the menu shows only icons and letter abbreviations.
 - [VcMenuItem](../vc-menu/) — individual menu item with icon, title, badge
 - [VcMenuGroup](../vc-menu/) — collapsible group container (supports `variant="section"` for top-level sections)
 - [VcDropdown](../vc-dropdown/) — contextual dropdown menus
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `VcMenuExpandedKey` is the provide/inject key (`framework/ui/components/molecules/vc-menu/constants.ts`) used by `VcMenu` to broadcast the `expanded` state down to all `VcMenuItem` and `VcMenuGroup` descendants. Components can also override it locally via their own `expanded` prop.
+- `VcMenuGroup` persists its open/closed state in `localStorage` with a key scoped to `vc_menu_<appName>_<groupId>_open`, where `appName` is derived from the first URL path segment.
+- The loading skeleton in `VcMenu` is hardcoded to mimic a realistic 2-section structure. It does not reflect actual slot content.
+- `VcMenuItem` uses a `VcTooltip` that activates only when the menu is collapsed (`!menuExpanded`), showing the item title on hover.
+- `VcMenuGroup` children animate via CSS `grid-template-rows: 0fr → 1fr` transition — no JS required.
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-multivalue/vc-multivalue.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcMultivalue
+category: components
+group: form
+---
+
+!!! note "Large reference page"
+This page is long. Use the section links in the sidebar or your browser's in-page search (Ctrl/Cmd+F) to jump to the section you need.
+
 # VcMultivalue
 
 A multi-value input component for collecting multiple entries as chips/tags. Supports two distinct modes: **free-form entry** (text, number, date, color) where users type values and press Enter, and **dictionary mode** with a searchable dropdown of predefined options.
 
+::storybook id="form-vcmultivalue--default"
+
 ## When to Use
 
 - Collecting multiple tags, keywords, or labels (e.g., product tags, email recipients)
@@ -46,6 +57,8 @@ In the default mode (`multivalue` is `false`), users type a value into the input
 
 ### Dictionary Mode (Dropdown Selection)
 
+::storybook id="form-vcmultivalue--single-value-mode"
+
 When the `multivalue` prop is `true` and `options` are provided, the component displays a searchable dropdown. Users click the field to open the dropdown, search within options, and select items. Already-selected items are automatically excluded from the dropdown.
 
 ```vue
@@ -139,6 +152,8 @@ const form = reactive({
 
 ### Custom Rendering with Slots
 
+::storybook id="form-vcmultivalue--custom-option-display"
+
 Use `#option` for dropdown items and `#selected-item` for chips:
 
 ```vue
@@ -344,3 +359,16 @@ The component uses `--multivalue-*` variables that fall back to `--select-*` tok
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- Composed of internal sub-components in `vc-multivalue/_internal/`: the chip list renderer, the dropdown panel, and the trigger input.
+- Composables are in `vc-multivalue/composables/` — chip management and dropdown open/close state are separated into composables.
+- Free-form mode: each `keydown` for Enter or comma (`','`) triggers a chip add; Backspace on empty input removes the last chip.
+- Dictionary mode: already-selected items are filtered out of the dropdown list reactively.
+- Source file: `framework/ui/components/molecules/vc-multivalue/vc-multivalue.vue`
+- Internal components: `framework/ui/components/molecules/vc-multivalue/_internal/`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-pagination/vc-pagination.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcPagination
+category: components
+group: navigation
+---
+
+!!! tip "Quick reference"
+Jump to [Props](#props) · [Events](#events) · [CSS Variables](#css-variables) · [Accessibility](#accessibility)
+
 # VcPagination
 
 Page navigation control with first/previous/next/last buttons and a sliding window of page numbers. Automatically adapts the number of visible page buttons for mobile viewports.
 
+::storybook id="navigation-vcpagination--default"
+
 ## When to Use
 
 - Navigating paginated data sets in tables, lists, or grids
@@ -39,6 +50,8 @@ function onPageChange(page: number) {
 
 ## Sliding Page Window
 
+::storybook id="navigation-vcpagination--many-pages"
+
 VcPagination displays a sliding window of page number buttons centered on the current page. The window size adapts automatically:
 
 - **Desktop:** 5 visible page buttons (default)
@@ -290,3 +303,15 @@ currentPage.value = Math.min(currentPage.value, totalPages.value);
 
 - [VcDataTable](../../organisms/vc-table) -- Data table that commonly pairs with pagination for large datasets
 - [VcSelect](../vc-select/) -- Can be used alongside pagination for a "rows per page" selector
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- `localCurrentPage` is an internal ref synced from `props.currentPage` via a watcher. This prevents the UI from jumping when the parent has not yet updated the prop after an `itemClick` event.
+- Responsive defaults: `MAX_PAGES_MOBILE = 3`, `MAX_PAGES_DESKTOP = 5`. Both are overridden by `maxPages` prop.
+- `effectiveShowFirstLast` defaults to `true` when `showFirstLast` prop is `undefined`.
+- The `setPage` function clamps clicks to valid range `[1, props.pages]` and handles both `number` and `string` inputs (supports programmatic usage).
+- The `variant` prop is defined but currently unused in the template — reserved for a future "minimal" style.
+
+<!-- internal:end -->

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

@@ -1,7 +1,18 @@
+---
+title: VcRadioButton
+category: components
+group: form
+---
+
 # VcRadioButton
 
 A radio button component for selecting a single option from a group. Supports string, number, and boolean value types.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Basic Usage](#basic-usage), [Common Patterns](#common-patterns), [Props](#key-props), [Accessibility](#accessibility).
+
+::storybook id="form-vcradiobutton--default"
+
 ## Overview
 
 Radio buttons are the standard UI pattern for selecting exactly one option from a small, visible set. Unlike dropdowns (VcSelect), radio buttons show all options simultaneously, making them ideal when there are 2-6 choices and the user benefits from seeing everything at once.
@@ -115,6 +126,8 @@ const priority = ref(2);
 
 ### Binary Mode
 
+::storybook id="form-vcradiobutton--binary"
+
 In binary mode, clicking toggles between `true` and `false` rather than comparing to a `value`. This is useful for standalone boolean options:
 
 ```vue
@@ -201,3 +214,15 @@ Do not mix `binary` mode with regular `value` comparison in the same group. Bina
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcRadioButton wraps a native `<input type="radio">` with custom CSS appearance. `checked` state is computed via `isEqual` (lodash) to support object-typed values.
+- `binary` mode: `onChange` emits `!checked.value` (a boolean toggle) instead of `props.value`. Do not mix binary and value modes within the same group.
+- The `name` attribute is critical for native keyboard group navigation — always set the same `name` across a group.
+- `useFormField` injects validation context (error, disabled, name) from a parent form provider.
+- Source file: `framework/ui/components/molecules/vc-radio-button/vc-radio-button.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-radio-group/vc-radio-group.docs.md

@@ -1,7 +1,15 @@
+---
+title: VcRadioGroup
+category: components
+group: form
+---
+
 # VcRadioGroup
 
 Accessible radio button group that wraps radio controls in a semantic fieldset with shared label, hint, error state, and layout control.
 
+::storybook id="form-vcradiogroup--default"
+
 ## When to Use
 
 - Selecting exactly one option from a set (e.g., payment method, shipping speed)
@@ -74,6 +82,8 @@ interface RadioGroupOption<V = string | number | boolean> {
 
 ### Horizontal Layout
 
+::storybook id="form-vcradiogroup--horizontal"
+
 ```vue
 <VcRadioGroup
   v-model="priority"
@@ -89,6 +99,8 @@ interface RadioGroupOption<V = string | number | boolean> {
 
 ### With Disabled Option
 
+::storybook id="form-vcradiogroup--with-disabled-option"
+
 ```vue
 <VcRadioGroup
   v-model="plan"
@@ -135,3 +147,13 @@ interface RadioGroupOption<V = string | number | boolean> {
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcRadioGroup delegates rendering to `VcInputGroup` (semantic fieldset wrapper) and renders `VcRadioButton` items from the `options` array, or passes through the default slot for custom layouts.
+- The group generates a unique `name` attribute via `useId()` when none is provided, ensuring native radio group behavior.
+- Source file: `framework/ui/components/molecules/vc-radio-group/vc-radio-group.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-rating/vc-rating.docs.md

@@ -1,3 +1,9 @@
+---
+title: VcRating
+category: components
+group: form
+---
+
 # VcRating
 
 Read-only rating display component that visualizes a numeric value as stars, a star-and-text combination, or plain text. Designed for displaying aggregate ratings in detail views, list columns, and dashboards.
@@ -15,6 +21,8 @@ Read-only rating display component that visualizes a numeric value as stars, a s
 
 ## Quick Start
 
+::storybook id="form-vcrating--stars"
+
 ```vue
 <template>
   <VcRating
@@ -29,6 +37,9 @@ import { VcRating } from "@vc-shell/framework";
 </script>
 ```
 
+!!! tip "Display-only component"
+VcRating is a read-only display component. It does not support user interaction for selecting a rating. For interactive rating input, build a custom component.
+
 ## Display Variants
 
 VcRating offers three visual modes controlled by the `variant` prop:
@@ -55,6 +66,8 @@ Shows a single filled star icon alongside a numeric fraction. Compact and precis
 
 Displays just the numeric fraction. Minimal footprint for dense layouts like table cells.
 
+::storybook id="form-vcrating--text-only"
+
 ```vue
 <VcRating :model-value="8" :max="10" variant="text" />
 <!-- Renders: 8/10 -->
@@ -74,6 +87,8 @@ The default scale is 1-5 stars. Override with the `max` prop for different scale
 
 > **Tip:** For scales larger than 5, prefer the `"star-and-text"` or `"text"` variant. Rendering 10 individual star icons can be visually crowded.
 
+::storybook id="form-vcrating--star-and-text"
+
 ## Placeholder for No Rating
 
 When `modelValue` is `0`, `null`, or `undefined`, display a placeholder message:
@@ -258,6 +273,8 @@ Use the `"star-and-text"` or `"text"` variant in table cell slots for a compact
 - [VcLabel](../../atoms/vc-label/) -- Label atom used internally for the label and tooltip
 - [VcIcon](../../atoms/vc-icon/) -- Renders the star icons internally
 
+::storybook id="form-vcrating--skeleton"
+
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.

package/runtime/knowledge/docs/ui/components/molecules/vc-select/vc-select.docs.md

@@ -1,9 +1,20 @@
+---
+title: VcSelect
+category: components
+group: form
+---
+
 # VcSelect
 
 A dropdown list component for selecting one or multiple values. Supports synchronous and asynchronous data sources, search with debounce, infinite scrolling, custom option templates, and full integration with the framework's validation system.
 
 VcSelect is one of the most widely used components in vc-shell. It covers most selection scenarios: from a simple dropdown with a static list to searching via a server API with pagination.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Data Sources](#data-sources), [Multiple Selection](#multiple-selection), [Slots](#slots), [Props](#props).
+
+::storybook id="form-vcselect--basic"
+
 ## When to Use
 
 | Scenario                                | Component                                |
@@ -82,6 +93,8 @@ In this case `optionValue` and `optionLabel` are not needed — the component us
 
 ### Async Function (Server API)
 
+::storybook id="form-vcselect--async-options" height="450"
+
 To load data from a server, pass a function instead of an array. This is the most powerful mode — it automatically provides:
 
 - Search with debounce (500ms by default)
@@ -142,6 +155,8 @@ const loadProducts = async (keyword?: string, skip?: number, ids?: string[]) =>
 
 ## Multiple Selection
 
+::storybook id="form-vcselect--multiple-selection"
+
 Add `multiple` to enable selecting several values. The model becomes an array:
 
 ```vue
@@ -178,6 +193,8 @@ Selected values are displayed as chips with a remove button. The `clearable` but
 
 ## Search and Filtering
 
+::storybook id="form-vcselect--searchable"
+
 Enable `searchable` to add a search field to the dropdown:
 
 ```vue
@@ -192,6 +209,8 @@ Enable `searchable` to add a search field to the dropdown:
 
 ## Custom Option Rendering
 
+::storybook id="form-vcselect--custom-option-slot" height="450"
+
 Use the `#option` slot for full control over how each option is rendered:
 
 ```vue
@@ -678,3 +697,16 @@ Don't forget `:key` with cascading selects, otherwise the second select will ret
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint — a label block (when the `label` prop is set) and an input-shaped block. No additional props or configuration needed.
 
 This behavior is powered by `BladeLoadingKey` via Vue's provide/inject. The component injects the loading state from the nearest `VcBlade` ancestor.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcSelect is split into three layers: `vc-select.vue` (orchestrator), `SelectTrigger.vue` (trigger button + chips), `SelectDropdown.vue` (popup list).
+- Composable split: `useSelectDataSource` (options loading, infinite scroll, search), `useSelectSelection` (model-to-option mapping, toggle, remove), `useSelectValueMapping` (optionValue/optionLabel getters), `useSelectDropdown` (Floating UI positioning), `useSelectVisibility` (IntersectionObserver for lazy open).
+- `emitValue: true` (default) means `modelValue` is always a primitive (string/number/boolean). `emitValue: false` means full option object. The `mapOptions` flag controls whether resolved objects are stored in the cache for label resolution.
+- Infinite scroll is driven by `useIntersectionObserver` on a 1px sentinel element inside the dropdown viewport.
+- Keyboard navigation is managed by `useKeyboardNavigation` (`core/composables/`) — arrow keys, Enter, Escape. The composable attaches/detaches listeners when the dropdown opens/closes.
+- Source files: `framework/ui/components/molecules/vc-select/`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-slider/vc-slider.docs.md

@@ -1,7 +1,15 @@
+---
+title: VcSlider
+category: components
+group: form
+---
+
 # VcSlider
 
 A content carousel component built on Swiper.js for displaying slides with optional navigation buttons. Renders any content via the default slot.
 
+::storybook id="form-vcslider--default"
+
 ## When to Use
 
 - Image carousels (product galleries, banners)
@@ -65,6 +73,8 @@ const products = [
 
 ### Custom Navigation Buttons
 
+::storybook id="form-vcslider--custom-navigation"
+
 ```vue
 <VcSlider :slides="items" navigation>
   <template #default="{ slide }">
@@ -123,3 +133,15 @@ const products = [
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component automatically renders a skeleton placeholder matching its visual footprint. No additional props or configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcSlider wraps the `swiper/vue` `<Swiper>` / `<SwiperSlide>` components with the `Navigation` module. Navigation buttons are custom DOM elements (`.vc-slider__prev` / `.vc-slider__next`) referenced by Swiper's `navigation.prevEl` / `nextEl` selectors.
+- `overflow` prop toggles `overflow: visible` on the swiper container, allowing slides to bleed outside bounds — useful for "peek" effects.
+- `slidesPerView="auto"` (default) lets each slide size itself from content. Pass a number for fixed-count layouts.
+- The `slides` prop accepts any array. Each item is exposed as `{ slide }` in the default scoped slot.
+- Source file: `framework/ui/components/molecules/vc-slider/vc-slider.vue`
+
+<!-- internal:end -->

package/runtime/knowledge/docs/ui/components/molecules/vc-switch/vc-switch.docs.md

@@ -1,7 +1,18 @@
+---
+title: VcSwitch
+category: components
+group: form
+---
+
 # VcSwitch
 
 A toggle switch component for binary on/off choices. Renders as a sliding track with a thumb indicator and supports labels, hints, validation, and value inversion.
 
+!!! note "Large reference"
+This page is over 200 lines. Use the section headings to jump directly to what you need: [Quick Start](#quick-start), [Features](#features), [Props](#props), [CSS Variables](#css-variables).
+
+::storybook id="form-vcswitch--default"
+
 ## When to Use
 
 - Toggling a feature or setting on/off (e.g., "Enable notifications", "Publish product")
@@ -46,6 +57,8 @@ The `label` prop renders text above the switch. Use `hint` for helper text below
 
 ### Value Inversion with trueValue / falseValue
 
+::storybook id="form-vcswitch--variants"
+
 By default, `v-model` maps `true` to the checked (on) state and `false` to unchecked (off). The `trueValue` and `falseValue` props let you invert the mapping when your data model uses opposite semantics.
 
 ```vue
@@ -294,3 +307,15 @@ const isActive = ref(true);
 ## Skeleton / Loading State
 
 When placed inside a `VcBlade` with `loading=true`, the component renders a skeleton placeholder matching its shape — a control indicator and label block. No configuration needed.
+
+<!-- internal:start -->
+
+## Architecture Notes
+
+- VcSwitch renders a hidden `<input type="checkbox">` with `role="switch"`. Visual state is driven by CSS (`:checked + .vc-switch__slider`). No JavaScript DOM manipulation needed for toggling.
+- `invertValue` handles the `trueValue`/`falseValue` mapping — both on read (for rendering) and on write (for emitting). When `trueValue` is `false`, the display is inverted.
+- The `tooltip` prop is kept for backward compatibility (legacy vc-shell code used it as hint text). A dev-mode `console.warn` nudges maintainers to migrate. The prop is mapped to `hintText` computed.
+- `useFormField` injects validation context (error, disabled, name) from a parent form provider.
+- Source file: `framework/ui/components/molecules/vc-switch/vc-switch.vue`
+
+<!-- internal:end -->