@vc-shell/vc-app-skill 2.0.3 → 2.0.4

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

@@ -1,3 +1,9 @@
+---
+title: VcFileUpload
+category: components
+group: form
+---
+
 # VcFileUpload
 
 Drag-and-drop file upload zone with file type filtering, validation, loading state, and error display. Provides both drag-and-drop and click-to-browse interactions in a single drop zone.
@@ -15,6 +21,8 @@ Drag-and-drop file upload zone with file type filtering, validation, loading sta
 
 ## Quick Start
 
+::storybook id="form-vcfileupload--default"
+
 ```vue
 <template>
   <VcFileUpload
@@ -75,6 +83,9 @@ Integrate with vee-validate for file validation rules such as size limits:
 
 When validation fails, the error is displayed below the drop zone using the built-in `VcHint` component. The `upload` event is only emitted when validation passes.
 
+!!! warning "FileList is not a plain Array"
+The `upload` event emits a `FileList` object, not `File[]`. Always convert with `Array.from(files)` before calling array methods like `.map()` or `.filter()`.
+
 ## Loading State
 
 Show a loading overlay while files are being processed or uploaded:
@@ -102,6 +113,8 @@ Override the default drag-and-drop instructions and icon:
 
 The default icon is `"lucide-cloud-upload"`. The default text is pulled from the `COMPONENTS.MOLECULES.VC_FILE_UPLOAD.DRAG_HERE` and `COMPONENTS.MOLECULES.VC_FILE_UPLOAD.BROWSE` locale keys.
 
+::storybook id="form-vcfileupload--loading"
+
 ## Error Display
 
 Errors can come from three sources (by priority): the `errorMessage` prop, vee-validate `rules`, or the `error` slot for fully custom rendering.
@@ -120,6 +133,8 @@ Errors can come from three sources (by priority): the `errorMessage` prop, vee-v
 
 When any error is present, the drop zone border changes to the error color and a ring appears.
 
+::storybook id="form-vcfileupload--with-error-message"
+
 ## Disabled State
 
 Disable all interactions (drag, drop, click, keyboard):
@@ -316,6 +331,8 @@ async function onUpload(files: FileList) {
 - [VcImageTile](../vc-image-tile/) -- Image display tile used inside galleries
 - [VcHint](../../atoms/vc-hint/) -- Used internally for error message display
 
+::storybook id="form-vcfileupload--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-form/vc-form.docs.md

@@ -1,3 +1,9 @@
+---
+title: VcForm
+category: components
+group: form
+---
+
 # VcForm
 
 A lightweight `<form>` wrapper that provides consistent styling, prevents default browser submission, and serves as the standard container for validated form fields in blade detail views.
@@ -16,6 +22,8 @@ A lightweight `<form>` wrapper that provides consistent styling, prevents defaul
 
 ## Quick Start
 
+::storybook id="form-vcform--basic"
+
 ```vue
 <template>
   <VcForm @submit="handleSubmit">
@@ -50,6 +58,9 @@ function handleSubmit() {
 
 ---
 
+!!! note "Form validation is handled by vee-validate"
+VcForm itself does not validate fields — it only provides the `<form>` wrapper. Use vee-validate's `Field` component around each input that needs validation rules.
+
 ## Features
 
 ### Basic Form Layout (VcForm + VcRow + VcCol)
@@ -174,6 +185,8 @@ const bladeToolbar = ref<IBladeToolbar[]>([
 
 ---
 
+::storybook id="form-vcform--with-fieldsets" height="500"
+
 ## Recipes
 
 ### Complete CRUD Blade Form
@@ -303,6 +316,8 @@ onBeforeClose(async () => {
 </script>
 ```
 
+::storybook id="form-vcform--horizontal-layout" height="400"
+
 ### Form with Mixed Field Types
 
 Demonstrates inputs, selects, checkboxes, and switches together in a single form.

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

@@ -1,3 +1,9 @@
+---
+title: VcImageTile
+category: components
+group: data-display
+---
+
 # VcImageTile
 
 Square image tile with skeleton loading, fade-in transition, and a slide-up action tray on hover (desktop) or tap (touch devices).
@@ -10,6 +16,8 @@ Square image tile with skeleton loading, fade-in transition, and a slide-up acti
 
 ## Basic Usage
 
+::storybook id="action-vcimagetile--default"
+
 ```vue
 <template>
   <div style="width: 160px;">
@@ -73,6 +81,8 @@ interface VcImageTileActions {
 
 ## Common Patterns
 
+::storybook id="action-vcimagetile--all-actions"
+
 ### Image Grid
 
 ```vue
@@ -114,6 +124,8 @@ interface VcImageTileActions {
 </VcImageTile>
 ```
 
+::storybook id="action-vcimagetile--skeleton"
+
 ### Skeleton State
 
 When `src` is not provided or the image is still loading, a shimmer animation skeleton is displayed automatically. No additional configuration is needed.

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.