@vc-shell/vc-app-skill 2.0.0-alpha.32 → 2.0.0-alpha.33

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [2.0.0-alpha.33](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.32...v2.0.0-alpha.33) (2026-04-14)
+
+
+### Bug Fixes
+
+* **vc-app-skill:** add VC_SHELL_MIGRATE_CLI env override for local testing ([010d2f2](https://github.com/VirtoCommerce/vc-shell/commit/010d2f2ecb29d31d9134406bcd18e46e5883208b))
+* **vc-app-skill:** resolve migrate CLI from project node_modules before npx fallback ([82a8156](https://github.com/VirtoCommerce/vc-shell/commit/82a81563f7fdb94a94a7b8a80796ecffc671a39c))
+* **vc-app-skill:** resolve migrate CLI locally in dev mode, fallback to npx ([89888a0](https://github.com/VirtoCommerce/vc-shell/commit/89888a06cc0b4a1519f46f070ee06ebb0d82fd09))
+
+
+### Features
+
+* **vc-app-skill:** add /vc-app migrate command with full migration pipeline ([35a8b11](https://github.com/VirtoCommerce/vc-shell/commit/35a8b119457b14f6f4626caf133476222afd6663))
+* **vc-app-skill:** add migration prompt knowledge base (nswag, widgets, form, blade-props, notifications) ([a0b0eb2](https://github.com/VirtoCommerce/vc-shell/commit/a0b0eb2a96521916a72bdbf787961c1c96f96f6d))
+* **vc-app-skill:** add migration-agent subagent prompt ([29ac155](https://github.com/VirtoCommerce/vc-shell/commit/29ac1550c8e3c9b71d5dbc2ade7ea86b4d40213f))
 # [2.0.0-alpha.32](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.31...v2.0.0-alpha.32) (2026-04-02)
 
 **Note:** Version bump only for package @vc-shell/vc-app-skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.0-alpha.32",
+  "version": "2.0.0-alpha.33",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [

package/runtime/VERSION

@@ -1 +1 @@
-2.0.0-alpha.32
+2.0.0-alpha.33

package/runtime/agents/migration-agent.md

@@ -0,0 +1,83 @@
+---
+name: migration-agent
+description: Performs AI-powered manual migrations on files identified by MIGRATION_REPORT.md, using transformation rules from migration prompts.
+---
+
+## Input Contract
+
+```json
+{
+  "required": {
+    "cwd": "string — absolute path to project root",
+    "reportPath": "string — path to MIGRATION_REPORT.md",
+    "topics": "array — migration topics to process, each with: { name, affectedFiles, migrationPromptPath, patternPath? }"
+  }
+}
+```
+
+## Knowledge Loading
+
+For each topic in `topics`:
+1. Read the migration prompt from `migrationPromptPath` — these contain specific transformation rules with BEFORE/AFTER examples
+2. If `patternPath` is provided, read the pattern file — this shows what correct target code looks like
+
+Do NOT read all prompts upfront. Load each topic's knowledge just before processing that topic.
+
+## Processing Strategy
+
+### Topic Order
+
+Process topics in this order (dependencies first):
+1. `notifications-migration` — may create new files and restructure directories
+2. `nswag-migration` — type-level changes that affect all other code
+3. `widgets-migration` — creates new composable files referenced by blades
+4. `blade-form-migration` — depends on correct types from nswag
+5. `blade-props-migration` — final cleanup of reusable components
+
+Skip topics not present in the `topics` input.
+
+### Per-File Strategy
+
+For each affected file in the current topic:
+
+1. **Read the file** completely
+2. **Apply transformation rules** from the loaded migration prompt — follow the BEFORE/AFTER patterns exactly
+3. **Create new files if required** by the prompt (e.g. `widgets/useXxxWidgets.ts` for widget migration)
+4. **Write the modified file**
+5. **Type-check:** Run `cd {cwd} && npx vue-tsc --noEmit 2>&1 | head -30` to check for errors
+6. **If errors in this file:** Read error messages, fix, re-check. Max 3 attempts.
+7. **If fixed or clean:** Commit: `fix(migrate): {topic name} — {filename}`
+8. **If still broken after 3 attempts:** Revert the file (`git checkout -- {filepath}`), report as "needs manual intervention", continue to next file
+
+### Important Rules
+
+1. **Only modify files listed in the topic's `affectedFiles`** — do not touch other files unless creating new files required by the migration prompt (e.g. widget composables)
+2. **Follow transformation rules exactly** — each migration prompt has specific BEFORE/AFTER patterns. Apply them mechanically.
+3. **Do not add features or refactor** — only transform existing code to the new API
+4. **Preserve all business logic** — the behavior must stay identical after migration
+5. **Commit after each successfully migrated file** — atomic commits for easy rollback
+6. **Do not modify `api_client/` directory** — generated code, not consumer code
+7. **Do not modify `node_modules/`**
+
+## Output
+
+When all topics are processed, report:
+
+```
+## Migration Agent Report
+
+### Completed
+- {topic}: {N} files migrated
+  - src/path/to/file.vue ✅
+  - src/path/to/other.ts ✅
+
+### Failed (needs manual intervention)
+- {topic}: {M} files failed
+  - src/path/to/problem.vue — {error description}
+
+### New Files Created
+- src/modules/xxx/widgets/useXxxWidgets.ts
+
+### Remaining TypeScript Errors
+{output of final vue-tsc --noEmit, if any}
+```

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit fc29b1e1b on 2026-04-02T05:22:47.427Z
+Synced from framework at commit b399787ff on 2026-04-14T15:15:27.844Z

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

@@ -54,6 +54,7 @@ const toolbar = ref<IBladeToolbar[]>([
 | Property | Type | Description |
 |----------|------|-------------|
 | `setBaseline()` | `() => void` | Snapshot current data as pristine. Call after load and after save |
+| `markReady()` | `() => void` | Mark form ready without resetting pristine snapshot. Computes modification state from current data vs setup-time snapshot |
 | `revert()` | `() => void \| Promise<void>` | Revert data to pristine (or call onRevert) |
 | `canSave` | `ComputedRef<boolean>` | `isReady && valid && modified && canSaveOverride` |
 | `isModified` | `ComputedRef<boolean>` | Data differs from pristine (false until setBaseline) |
@@ -64,9 +65,16 @@ const toolbar = ref<IBladeToolbar[]>([
 
 ## Lifecycle
 
+### Standard (edit existing entity)
 ```
 Mount → Load data → setBaseline() → User edits → Save → setBaseline()
-                                                 └→ Cancel → revert()
+                                                  └→ Cancel → revert()
+```
+
+### Pre-filled (create from template)
+```
+Mount → Pre-fill data → markReady() → canSave = true immediately
+                                       └→ Save → setBaseline()
 ```
 
 ## VcBlade Integration
@@ -102,6 +110,52 @@ const form = useBladeForm({
 });
 ```
 
+## Advanced: Pre-filled Entity (markReady)
+
+When creating a new entity that is pre-populated from a parent (e.g. new offer from a product), the form should be immediately saveable. Use `markReady()` instead of `setBaseline()`:
+
+```ts
+const form = useBladeForm({ data: item });
+
+onMounted(async () => {
+  // Populate base fields
+  item.value.sku = generateSku();
+  await addEmptyInventory();
+
+  const hasTemplate = !param.value && !!options.value?.templateId;
+
+  if (hasTemplate) {
+    // Fill from template — data diverges from the setup-time snapshot
+    await fillFromTemplate(options.value.templateId);
+    // Mark ready: compares current data to setup-time snapshot → isModified = true
+    form.markReady();
+  } else {
+    // Standard load — current state becomes the pristine baseline
+    await loadItem({ id: param.value });
+    form.setBaseline();
+  }
+});
+```
+
+### setBaseline vs markReady
+
+| | `setBaseline()` | `markReady()` |
+|--|-----------------|---------------|
+| Sets `isReady` | yes | yes |
+| Updates pristine snapshot | yes (current data → pristine) | no (keeps setup-time snapshot) |
+| `trackerIsModified` after call | `false` | computed: `data !== pristineSnapshot` |
+| Use case | Load / Save — "this is the clean state" | Pre-fill — "form is ready, changes are intentional" |
+
+### How it works
+
+At composable creation, `useBladeForm` takes a snapshot of `data` (the **setup-time snapshot**). When `markReady()` is called:
+
+1. `isReady` → `true` (gates `canSave` and the deep watcher)
+2. `trackerIsModified` = `!semanticEqual(data, setupTimeSnapshot)` — since data was mutated during `onMounted`, this evaluates to `true`
+3. Subsequent edits are tracked normally by the deep watcher
+
+After save, call `setBaseline()` as usual to capture the saved state as the new pristine snapshot.
+
 ## Constraints
 
 - **Must be called from component `setup()`** (or `<script setup>`). Do NOT call from shared data-composables.

package/runtime/knowledge/docs/shell/auth/ChangePasswordPage/change-password-page.docs.md

@@ -0,0 +1,102 @@
+# ChangePasswordPage
+
+Change password page with current, new, and confirm password fields. Supports a `forced` mode for expired passwords that displays an info banner and is triggered by post-login redirect. This full-page variant is used when the user must change their password before accessing the application (e.g., expired password policy). For voluntary password changes from within the app, the `ChangePasswordButton` in the settings menu opens a popup instead.
+
+## When to Use
+
+- When a signed-in user wants to change their password (full-page flow)
+- In `forced` mode after login when the user's password has expired
+- The standard vc-shell routing maps `/change-password` to this page
+
+## Basic Usage
+
+```vue
+<template>
+  <ChangePassword />
+</template>
+
+<!-- Forced mode (expired password) -->
+<template>
+  <ChangePassword forced />
+</template>
+```
+
+With custom branding:
+
+```vue
+<template>
+  <ChangePassword
+    forced
+    logo="/assets/my-company-logo.svg"
+    background="/assets/custom-background.jpg"
+  />
+</template>
+```
+
+## Key Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `forced` | `boolean` | `false` | Show expired-password info banner and adjusted title |
+| `logo` | `string` | - | Override logo image URL |
+| `background` | `string` | - | Custom background image URL |
+
+## Recipe: Router Configuration with Forced Mode
+
+Set up the route so the login page can redirect here when the password is expired:
+
+```ts
+import ChangePassword from "@vc-shell/framework/shared/pages/ChangePasswordPage";
+
+const routes = [
+  {
+    path: "/change-password",
+    name: "ChangePassword",
+    component: ChangePassword,
+    props: (route) => ({
+      forced: route.query.forced === "true",
+    }),
+  },
+];
+```
+
+In the login flow, redirect when the user's password has expired:
+
+```ts
+async function handleLogin() {
+  const result = await signIn(username.value, password.value);
+  if (result.passwordExpired) {
+    router.push({ name: "ChangePassword", query: { forced: "true" } });
+  } else {
+    router.push("/");
+  }
+}
+```
+
+## Features
+
+- **Real-time password policy validation**: Uses `useUserManagement().validatePassword` to check the new password against the platform's policy as the user types (minimum length, required uppercase, lowercase, digits, special characters)
+- **Equal password detection**: Shows a specific "Equal-passwords" error when the new password matches the current password, without making an API call
+- **Confirm-password mismatch detection**: Validates that the new password and confirm password fields match
+- **Forced mode banner**: When `forced` is `true`, displays an info banner explaining that the password has expired and must be changed
+- **Cancel behavior**: Cancel button signs out the user and redirects to `/login`
+- **Success redirect**: On successful password change, redirects to `/` (main application)
+
+## Details
+
+- **Auth layout**: Renders inside `VcAuthLayout`, providing the centered card design with logo and background.
+- **Password policy**: The validation rules are fetched from the platform API and include configurable requirements (minimum length, character classes, etc.). The component displays these rules as a checklist.
+- **Forced vs voluntary**: In forced mode (`forced=true`), the page title changes to reflect the expired password scenario, and an info banner explains why the change is required. The form fields and behavior are otherwise identical.
+- **Sign-out on cancel**: If the user cancels during a forced password change, they are signed out. This prevents access to the application with an expired password.
+
+## Tips
+
+- The `forced` prop is typically set via a route query parameter, not hardcoded. The login page detects expired passwords and redirects with the appropriate flag.
+- Password policy validation runs on keyup, providing immediate feedback. The submit button is disabled until all policy requirements are met and the passwords match.
+- This page is distinct from the `ChangePasswordButton` popup. The page is for full-screen flow (forced changes), while the popup is for voluntary in-app password changes.
+
+## Related Components
+
+- **VcAuthLayout** - The underlying centered card layout
+- **LoginPage** - Redirects here when `user.passwordExpired` is true
+- **ChangePasswordButton** - Settings menu popup variant for voluntary password changes

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

@@ -351,3 +351,7 @@ const validationHeader = computed(() =>
 - [VcContainer](../vc-container/) -- scrollable content wrapper without header or collapsing
 - [VcBanner](../vc-banner/) -- for alert/notification messages rather than content grouping
 - [VcCol](../vc-col/) / [VcRow](../vc-row/) -- for grid-based layout within card bodies
+
+## Skeleton / Loading State
+
+When placed inside a `VcBlade` with `loading=true`, VcCard shows a skeleton header (if the `header` prop is set) while its body content renders normally — child components self-skeletonize via their own `BladeLoadingKey` injection.

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

@@ -250,3 +250,7 @@ interface AccordionItem {
 ## Related Components
 
 - [VcAccordionItem](./_internal/vc-accordion-item/) -- individual accordion panel (used internally and available via the default slot)
+
+## 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-checkbox/vc-checkbox.docs.md

@@ -323,3 +323,8 @@ const selected = ref<string[]>([]);
 - [VcSwitch](../vc-switch/) -- toggle switch for on/off settings
 - [VcRadioButton](../vc-radio-button/) -- mutually exclusive single selection
 - [VcInputGroup](../vc-input-group/) -- semantic wrapper for grouping checkboxes or radio buttons
+
+## 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.
+

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

@@ -144,3 +144,8 @@ interface CheckboxGroupOption<V = string | number | boolean> {
 - [VcCheckbox](../vc-checkbox/) — individual checkbox component
 - [VcRadioGroup](../vc-radio-group/) — mutually exclusive option group
 - [VcInputGroup](../vc-input-group/) — generic form field group (used internally)
+
+## 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.
+

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

@@ -151,3 +151,8 @@ The native color picker does not support alpha/transparency. If you need RGBA co
 
 - [VcInput](../vc-input/) -- general-purpose input (delegates to VcColorInput for `type="color"`)
 - [VcField](../vc-field/) -- read-only field display (for showing a color value without editing)
+
+## 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-date-picker/vc-date-picker.docs.md

@@ -359,3 +359,10 @@ Uses the same `--input-*` variables as VcInput for consistent styling across all
 
 - [VcInput](../vc-input/) -- general-purpose input; delegates to VcDatePicker for `type="date"` and `type="datetime-local"`
 - [VcMultivalue](../vc-multivalue/) -- can handle multiple date values with `type="date"`
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -298,3 +298,8 @@ const content = ref("<h1>Title</h1>");
 
 - [VcTextarea](../vc-textarea/) -- plain multi-line text input (no formatting)
 - [VcInput](../vc-input/) -- single-line text input
+
+## 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-field/vc-field.docs.md

@@ -166,3 +166,8 @@ The `type` prop affects rendering, not validation. Setting `type="email"` does n
 - [VcInput](../vc-input/) -- editable text field (use instead when user input is needed)
 - [VcLabel](../../atoms/vc-label/) -- standalone label atom used internally
 - [VcCol](../../atoms/vc-col/) -- column layout atom used for aspect ratio
+
+## 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-file-upload/vc-file-upload.docs.md

@@ -322,3 +322,8 @@ async function onUpload(files: FileList) {
 - [VcGallery](../../organisms/vc-gallery/) -- Full image gallery with preview, reorder, drag-and-drop sorting, and upload
 - [VcImageTile](../vc-image-tile/) -- Image display tile used inside galleries
 - [VcHint](../../atoms/vc-hint/) -- Used internally for error message display
+
+## 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-input/vc-input.docs.md

@@ -786,3 +786,10 @@ VcInput follows WAI-ARIA best practices for form fields:
 - [VcInputGroup](../vc-input-group/) -- Groups multiple inputs with shared label, error state, and disabled state
 - [VcLabel](../../atoms/vc-label/) -- The label atom used internally by VcInput
 - [VcHint](../../atoms/vc-hint/) -- The hint/error atom used internally by VcInput
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -368,3 +368,10 @@ Additionally inherits all `--input-*` CSS variables from VcInput/VcInputDropdown
 - [VcInputDropdown](../vc-input-dropdown/) -- the underlying composite input + dropdown component
 - [VcInput](../vc-input/) -- plain input for non-currency numbers
 - [VcSelect](../vc-select/) -- standalone dropdown selection
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -305,3 +305,10 @@ Replace the default dropdown toggle with a custom element using the `button` slo
 - [VcInputCurrency](../vc-input-currency/) -- Currency-specific variant with built-in locale formatting
 - [VcInput](../vc-input/) -- Standalone text input (used internally)
 - [VcSelect](../vc-select/) -- Standalone dropdown selection (used internally)
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -345,3 +345,10 @@ The component uses `--multivalue-*` variables that fall back to `--select-*` tok
 - [VcSelect](../vc-select/) -- dropdown for single/multi selection without manual entry
 - [VcInput](../vc-input/) -- single-value text input
 - [VcInputGroup](../vc-input-group/) -- semantic wrapper for grouping form controls
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -161,3 +161,8 @@ Do not mix `binary` mode with regular `value` comparison in the same group. Bina
 - [VcSwitch](../vc-switch/) -- for on/off toggles
 - [VcInputGroup](../vc-input-group/) -- semantic wrapper with `role="radiogroup"`
 - [VcSelect](../vc-select/) -- dropdown for larger option sets
+
+## 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.
+

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

@@ -144,3 +144,8 @@ interface RadioGroupOption<V = string | number | boolean> {
 - [VcRadioButton](../vc-radio-button/) — individual radio button component
 - [VcCheckboxGroup](../vc-checkbox-group/) — multiple-selection option group
 - [VcInputGroup](../vc-input-group/) — generic form field group (used internally)
+
+## 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.
+

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

@@ -251,3 +251,8 @@ Use the `"star-and-text"` or `"text"` variant in table cell slots for a compact
 - [VcField](../vc-field/) -- Read-only field display, often used alongside ratings in detail views
 - [VcLabel](../../atoms/vc-label/) -- Label atom used internally for the label and tooltip
 - [VcIcon](../../atoms/vc-icon/) -- Renders the star icons internally
+
+## 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

@@ -682,3 +682,10 @@ Don't forget `:key` with cascading selects, otherwise the second select will ret
 - [VcInput](../vc-input/) — simple text field
 - [VcDatePicker](../vc-date-picker/) — date selection
 - [VcField](../vc-field/) — wrapper with label/error/hint (read-only display)
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -113,3 +113,8 @@ const products = [
 ## Related Components
 
 - [VcImage](../../atoms/vc-image/) -- image component often used inside slides
+
+## 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-switch/vc-switch.docs.md

@@ -298,3 +298,8 @@ const isActive = ref(true);
 - [VcCheckbox](../vc-checkbox/) -- for checkboxes and checkbox groups
 - [VcRadioButton](../vc-radio-button/) -- for mutually exclusive choices
 - [VcInputGroup](../vc-input-group/) -- semantic wrapper for grouping form controls
+
+## 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.
+

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

@@ -305,3 +305,10 @@ const description = ref<string>("");
 - [VcInput](../vc-input/) -- single-line text input
 - [VcEditor](../vc-editor/) -- rich text / Markdown editor
 - [VcInputGroup](../vc-input-group/) -- semantic wrapper for grouping form controls
+
+## Skeleton / Loading State
+
+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.
+

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

@@ -659,3 +659,33 @@ openBlade({ name: "ProductsList" });
 | `useLoading()` | Merges multiple loading refs into a single boolean. |
 | `usePopup()` | Confirmation dialogs and error messages. |
 | `useBladeWidgets()` | Register contextual widgets for the blade widget area. |
+
+## Content Skeleton Mode
+
+When `loading=true`, VcBlade provides `BladeLoadingKey` to all descendant components via Vue's provide/inject. Each framework UI component automatically renders a skeleton placeholder matching its visual footprint.
+
+### How It Works
+
+1. Set `loading` prop on VcBlade (typically bound to your data-fetching composable's loading ref)
+2. All child components (`VcInput`, `VcSelect`, `VcCard`, etc.) detect the loading state and render skeletons
+3. Layout containers (`VcContainer`, `VcRow`, `VcCol`, `VcForm`) are transparent — they preserve layout structure
+4. When loading completes, components switch to their normal rendering
+
+### What Shows During Loading
+
+- **Config-gated fields** (`v-if="config.showName"`) — config is available immediately, so these fields show skeletons
+- **Data-gated fields** (`v-if="item.productData"`) — data not yet loaded, so these fields don't appear in the skeleton
+- **Header and toolbar** — have their own dedicated skeletons (unchanged)
+
+No changes to existing blade pages are required.
+
+### Custom Components
+
+To make custom components skeleton-aware:
+
+```ts
+import { useBladeLoading } from "@vc-shell/framework";
+
+const bladeLoading = useBladeLoading();
+// bladeLoading.value === true when parent VcBlade is loading
+```

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

@@ -619,6 +619,33 @@ Customize expand/collapse icons:
 </VcDataTable>
 ```
 
+### Conditional expansion
+
+Use `isRowExpandable` to control which rows show the expand toggle. Rows that fail the predicate cannot be expanded:
+
+```vue
+<template>
+  <VcDataTable
+    :items="orders"
+    v-model:expanded-rows="expandedRows"
+    :is-row-expandable="(order) => order.lineItems.length > 0"
+  >
+    <VcColumn id="expand" :expander="true" :width="40" />
+    <VcColumn id="orderNumber" field="number" title="Order #" />
+
+    <template #expansion="{ data }">
+      <div class="tw-p-4">
+        <p v-for="item in data.lineItems" :key="item.id">{{ item.name }}</p>
+      </div>
+    </template>
+  </VcDataTable>
+</template>
+
+<script setup lang="ts">
+const expandedRows = ref<Order[]>([]);
+</script>
+```
+
 ---
 
 ## Row Grouping
@@ -1264,6 +1291,7 @@ function onRowRemove(event: { data: Product; index: number; cancel: () => void }
 | `expandedRows` | `T[]` | `[]` | Expanded rows. Use with `v-model:expandedRows`. |
 | `expandedRowIcon` | `string` | `"lucide-chevron-down"` | Icon for expanded state. |
 | `collapsedRowIcon` | `string` | `"lucide-chevron-right"` | Icon for collapsed state. |
+| `isRowExpandable` | `(data: T) => boolean` | -- | Per-row predicate to hide the expand toggle. |
 
 ### Row Grouping