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

package/runtime/agents/details-blade-generator.md

@@ -10,13 +10,13 @@ description: Generates a details blade Vue component and its singular composable
   "required": {
     "moduleName": "string — kebab-case module name (e.g., 'team', 'catalog-items')",
     "entityName": "string — PascalCase entity name (e.g., 'TeamMember', 'Order')",
-    "entityTypePath": "string — import path for entity types (e.g., '../../api_client/virtocommerce.marketplace')",
-    "clientClass": "string — NSwag client class name (e.g., 'VcmpSellerSecurityClient')",
+    "entityTypePath": "string — import path for entity types (e.g., '../../api_client/virtocommerce.mymodule')",
+    "clientClass": "string — NSwag client class name (e.g., 'MyEntityClient')",
     "crudMethods": {
-      "get": "string? — camelCase get method on client (e.g., 'getSellerUser')",
-      "create": "string? — camelCase create method (e.g., 'createSellerUser')",
-      "update": "string? — camelCase update method (e.g., 'updateSellerUser')",
-      "delete": "string? — camelCase delete method (e.g., 'deleteSellerUsers')"
+      "get": "string? — camelCase get method on client (e.g., 'getUser')",
+      "create": "string? — camelCase create method (e.g., 'createUser')",
+      "update": "string? — camelCase update method (e.g., 'updateUser')",
+      "delete": "string? — camelCase delete method (e.g., 'deleteUsers')"
     },
     "fields": [
       {
@@ -56,6 +56,7 @@ Before generating, Read these files in order:
 3. `{knowledgeBase}/index.md` — to find relevant component docs
 
 From `index.md`, identify and Read docs from `{docsRoot}/` for:
+
 - **Always:** `VcBlade`, `VcForm`, `VcInput`, `VcSelect`, `VcSwitch`
 - **Based on field types present:** Read docs for each component that appears in the field type mapping below (e.g., if any field has type `text` → read `VcTextarea` docs; if `rich-text` → read `VcEditor` docs; if `currency` → read `VcInputCurrency` docs; etc.)
 - **Layout:** If 5+ fields → read `VcCard` docs; if 8+ fields → read `VcAccordion` docs
@@ -65,6 +66,7 @@ From `index.md`, identify and Read docs from `{docsRoot}/` for:
 ### Step 1: Derive naming variables
 
 From inputs compute:
+
 - `composableName` = `use` + `entityName` (e.g., `useTeamMember`)
 - `entityNameLower` = camelCase of `entityName` (e.g., `teamMember`)
 - `bladeComponentName` = PascalCase of `moduleName` + `Details` (e.g., `TeamDetails`)
@@ -73,15 +75,18 @@ From inputs compute:
 - `updateCommandClass` = `Update` + `entityName` + `Command` (if `crudMethods.update` provided)
 
 For standalone blades:
+
 - `url` = `"/" + moduleName + "-details"`
 
 ### Existing Module Context
 
 When `existingModule` is provided:
+
 - Use the same `localePrefix` convention from `existingModule.localePrefix` instead of deriving a new one. This ensures i18n keys are consistent across all blades in the module.
 - Reference `existingModule.blades` to avoid naming collisions with existing blade component names.
 
 When `linkTo` is provided:
+
 - After generating the new details blade, open the source blade file specified by `linkTo.blade` (resolve from `existingModule.indexPath` parent directory + `pages/`).
 - Add an `openBlade` call to the source blade based on `linkTo.trigger`:
   - `"button"` — add a toolbar button with `linkTo.label` that calls `openBlade({ blade: {bladeComponentName} })`
@@ -93,30 +98,31 @@ When `linkTo` is provided:
 
 For each field in `fields`, determine the component using this table. If the field already has a `component` property (from `/vc-app design`), use that directly. Otherwise, map from `type`:
 
-| Field type | Component | Validation rules | Notes |
-|------------|-----------|------------------|-------|
-| `string` | `VcInput` | `required` (if required) | Default for short text. Use `rules="email"` if name contains "email", `type="tel"` if phone, `type="url"` if url/website |
-| `text` | `VcTextarea` | `required` (if required) | Long text: description, notes, comments, bio, summary |
-| `rich-text` | `VcEditor` | `required` (if required) | HTML/WYSIWYG: body, content, article, template |
-| `boolean` | `VcSwitch` | none | No `Field` wrapper. Default for toggles (isActive, isEnabled) |
-| `boolean` | `VcCheckbox` | none | No `Field` wrapper. Use for consent/accept semantics (agreeTerms) |
-| `number` | `VcInput type="number"` | `required\|bigint\|min_value:0` | Plain numbers: quantity, count, age |
-| `currency` | `VcInputCurrency` | `required\|min_value:0` | Money: price, cost, amount, salary. Set `currency="USD"` (or infer from context) |
-| `date-time` | `VcDatePicker` | `required` (if required) | Preferred over `VcInput type="datetime-local"`. Calendar picker widget |
-| `Date` | `VcDatePicker` | `required` (if required) | Legacy alias — same as `date-time` |
-| `enum` | `VcSelect` | `required` (if required) | For 6+ options or dynamic options. Needs `{field}Options` computed |
-| `enum` (2-5 options) | `VcRadioGroup` | `required` (if required) | More visual for small static sets. Needs `{field}Options` array |
-| `multi-select` | `VcMultivalue` | none | Tags/multi-pick: tags, categories, roles. No `Field` wrapper needed |
-| `multi-select` (static) | `VcCheckboxGroup` | none | Few static checkboxes. Needs `{field}Options` array |
-| `rating` | `VcRating` | none | Star rating 1-5. No `Field` wrapper needed |
-| `range` | `VcSlider` | none | Numeric slider: discount, percentage. Set `:min` / `:max` |
-| `color` | `VcColorInput` | none | Color picker with hex. No `Field` wrapper needed |
-| `image` | `VcImageUpload` | none | Single image upload with preview |
-| `gallery` | `VcGallery` | none | Multi-image management grid |
-| `file` | `VcFileUpload` | none | File attachment. Set `:accept` filter for allowed extensions |
-| `array` | `VcDataTable` (inline) | none | Read-only nested table |
+| Field type              | Component               | Validation rules                | Notes                                                                                                                    |
+| ----------------------- | ----------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `string`                | `VcInput`               | `required` (if required)        | Default for short text. Use `rules="email"` if name contains "email", `type="tel"` if phone, `type="url"` if url/website |
+| `text`                  | `VcTextarea`            | `required` (if required)        | Long text: description, notes, comments, bio, summary                                                                    |
+| `rich-text`             | `VcEditor`              | `required` (if required)        | HTML/WYSIWYG: body, content, article, template                                                                           |
+| `boolean`               | `VcSwitch`              | none                            | No `Field` wrapper. Default for toggles (isActive, isEnabled)                                                            |
+| `boolean`               | `VcCheckbox`            | none                            | No `Field` wrapper. Use for consent/accept semantics (agreeTerms)                                                        |
+| `number`                | `VcInput type="number"` | `required\|bigint\|min_value:0` | Plain numbers: quantity, count, age                                                                                      |
+| `currency`              | `VcInputCurrency`       | `required\|min_value:0`         | Money: price, cost, amount, salary. Set `currency="USD"` (or infer from context)                                         |
+| `date-time`             | `VcDatePicker`          | `required` (if required)        | Preferred over `VcInput type="datetime-local"`. Calendar picker widget                                                   |
+| `Date`                  | `VcDatePicker`          | `required` (if required)        | Legacy alias — same as `date-time`                                                                                       |
+| `enum`                  | `VcSelect`              | `required` (if required)        | For 6+ options or dynamic options. Needs `{field}Options` computed                                                       |
+| `enum` (2-5 options)    | `VcRadioGroup`          | `required` (if required)        | More visual for small static sets. Needs `{field}Options` array                                                          |
+| `multi-select`          | `VcMultivalue`          | none                            | Tags/multi-pick: tags, categories, roles. No `Field` wrapper needed                                                      |
+| `multi-select` (static) | `VcCheckboxGroup`       | none                            | Few static checkboxes. Needs `{field}Options` array                                                                      |
+| `rating`                | `VcRating`              | none                            | Star rating 1-5. No `Field` wrapper needed                                                                               |
+| `range`                 | `VcSlider`              | none                            | Numeric slider: discount, percentage. Set `:min` / `:max`                                                                |
+| `color`                 | `VcColorInput`          | none                            | Color picker with hex. No `Field` wrapper needed                                                                         |
+| `image`                 | `VcImageUpload`         | none                            | Single image upload with preview                                                                                         |
+| `gallery`               | `VcGallery`             | none                            | Multi-image management grid                                                                                              |
+| `file`                  | `VcFileUpload`          | none                            | File attachment. Set `:accept` filter for allowed extensions                                                             |
+| `array`                 | `VcDataTable` (inline)  | none                            | Read-only nested table                                                                                                   |
 
 **Field name heuristics:** When field type is plain `"string"`, upgrade based on the field name:
+
 - `description`, `notes`, `comment`, `bio`, `summary`, `about` → `text` (VcTextarea)
 - `body`, `content`, `html`, `article`, `template` → `rich-text` (VcEditor)
 - `price`, `cost`, `amount`, `total`, `salary`, `budget`, `fee` → `currency` (VcInputCurrency)
@@ -132,6 +138,7 @@ Refer to `details-blade-pattern.md` → "Field Type → Component Mapping" secti
 Write to: `{targetDir}/composables/use{EntityName}/index.ts`
 
 Follow `composable-details.md` skeleton exactly:
+
 - Import `useModificationTracker`, `useApiClient`, `useAsync`, `useLoading`, `AsyncAction` from `@vc-shell/framework`
 - Import entity types and command classes from `entityTypePath`
 - Define `IUse{EntityName}` interface — include only methods present in `crudMethods`
@@ -155,9 +162,7 @@ Instead of the normal composable that imports API client classes, generate this
 
 ```ts
 // vc-app:mock-start
-const mockData: Record<string, unknown>[] = [
-  { id: "1", name: "Item 1", status: "active", createdDate: new Date().toISOString() },
-];
+const mockData: Record<string, unknown>[] = [{ id: "1", name: "Item 1", status: "active", createdDate: new Date().toISOString() }];
 
 const fetchItem = async (id: string) => {
   return mockData.find((item) => item.id === id) ?? {};
@@ -185,6 +190,7 @@ Write to: `{targetDir}/pages/{moduleName}-details.vue`
 Follow `details-blade-pattern.md` template exactly:
 
 **Script setup:**
+
 - `defineBlade({ name: "{bladeComponentName}" })` — no url/isWorkspace for child blades
 - If `isStandalone: true`: `defineBlade({ name: "{bladeComponentName}", url: "{url}", isWorkspace: true, menuItem: { title: "{menuConfig.title}", icon: "{menuConfig.icon}", priority: {menuConfig.priority} } })` — standalone details blades that serve as the module entry point need a menu item to be accessible from navigation
 - `const { onBeforeClose, param, options, callParent, closeSelf } = useBlade()`
@@ -194,6 +200,7 @@ Follow `details-blade-pattern.md` template exactly:
 - `isDisabled` computed: `!meta.value.dirty || !meta.value.valid`
 
 **Toolbar items (include only for methods present in `crudMethods`):**
+
 - `save` button: `isVisible: !!param.value`, calls `updateXxx` then `callParent("reload"); closeSelf()`
 - `create` button: `isVisible: !param.value`, calls `createXxx` then `callParent("reload"); closeSelf()`
 - `reset` button: `isVisible: !!param.value`, calls `resetEntries()`
@@ -203,15 +210,18 @@ Follow `details-blade-pattern.md` template exactly:
 - If `crudMethods.delete` is null: omit delete button
 
 **Template:**
+
 - `<VcBlade :loading="loading" :modified="modified" :title="title" :toolbar-items="bladeToolbar" width="50%">`
 - `<VcContainer>`
 
 **Banners (contextual alerts):**
+
 - Add `<VcBanner>` at the top of the form (before `<VcForm>`) for state-dependent alerts. See `details-blade-pattern.md` → "Contextual Banners Pattern".
 - Use `variant="info"` for creation hints, `variant="danger"` for errors, `variant="warning"` for missing data.
 - Example: `<VcBanner v-if="!entity.id" variant="info" icon="lucide-lightbulb" icon-size="l">{{ $t("...CREATE_HINT") }}</VcBanner>`
 
 **Form fields:**
+
 - `<VcForm>` wraps all editable fields
 - Use the component determined in Step 2 for each field. Refer to `details-blade-pattern.md` for full template examples of each component type.
 - Components that need `<Field>` wrapper (for validation): `VcInput`, `VcTextarea`, `VcEditor`, `VcDatePicker`, `VcSelect`, `VcRadioGroup`, `VcInputCurrency`, `VcFileUpload`
@@ -220,6 +230,7 @@ Follow `details-blade-pattern.md` template exactly:
 - Use i18n keys: `{i18nPrefix}.FIELDS.{FIELD_NAME_UPPER}.LABEL` and `.PLACEHOLDER`
 
 **Read-only fields (VcField):**
+
 - For fields that should display data without editing (computed values, IDs, timestamps on existing entities), use `<VcField>` instead of `<VcInput>`:
   ```vue
   <VcField :label="$t('...')" :model-value="entity.number" orientation="horizontal" :aspect-ratio="[1, 2]" copyable type="text" />
@@ -228,12 +239,14 @@ Follow `details-blade-pattern.md` template exactly:
 - Use `VcField` when: the blade is view-only, or for specific non-editable fields within an editable form (order number, creation date).
 
 **Layout — ALWAYS use VcCard sections:**
+
 - Group related fields in `<VcCard :header="$t('...')">` sections. This is how real vc-shell apps are built — flat forms without cards look unfinished.
 - If 3+ fields → at minimum 1 card. If 5+ fields → 2+ cards grouped by topic.
 - If 8+ fields → consider `<VcAccordion>` for secondary/advanced fields.
 - **Grid:** Use `<VcRow><VcCol>` to arrange short fields in 2 columns. Wide fields (`VcTextarea`, `VcEditor`, `VcGallery`, `VcDataTable`) span full width.
 
 **Close guard:**
+
 ```ts
 onBeforeClose(async () => {
   if (modified.value) {
@@ -248,6 +261,7 @@ onBeforeClose(async () => {
 Write to: `{targetDir}/composables/index.ts`
 
 Append (or create):
+
 ```ts
 export { default as use{EntityName} } from "./use{EntityName}";
 ```
@@ -255,6 +269,7 @@ export { default as use{EntityName} } from "./use{EntityName}";
 ## Output Contract
 
 Files written to disk:
+
 1. `{targetDir}/composables/use{EntityName}/index.ts`
 2. `{targetDir}/pages/{moduleName}-details.vue`
 3. `{targetDir}/composables/index.ts` (created or appended)
@@ -264,6 +279,7 @@ Returns a summary of generated files and any field type assumptions made.
 ## Self-Check
 
 Before completing, verify:
+
 - [ ] `defineBlade` is at module scope, not inside a function
 - [ ] `useForm({ validateOnMount: false })` is called
 - [ ] `onBeforeClose` guard is present if `modified` is used

package/runtime/agents/list-blade-generator.md

@@ -10,9 +10,9 @@ description: Generates a list blade Vue component and its plural composable for
   "required": {
     "moduleName": "string — kebab-case module name (e.g., 'team', 'catalog-items')",
     "entityName": "string — PascalCase entity name (e.g., 'TeamMember', 'Order')",
-    "entityTypePath": "string — import path for entity types (e.g., '../../api_client/virtocommerce.marketplace')",
-    "clientClass": "string — NSwag client class name (e.g., 'VcmpSellerSecurityClient')",
-    "searchMethod": "string — camelCase search method on client (e.g., 'searchSellerUsers')",
+    "entityTypePath": "string — import path for entity types (e.g., '../../api_client/virtocommerce.mymodule')",
+    "clientClass": "string — NSwag client class name (e.g., 'UserSecurityClient')",
+    "searchMethod": "string — camelCase search method on client (e.g., 'searchUsers')",
     "columns": [
       {
         "name": "string — field name (camelCase)",
@@ -61,6 +61,7 @@ From `index.md`, identify any `.docs.md` files for `VcBlade`, `VcDataTable`, `Vc
 ### Step 1: Derive naming variables
 
 From inputs compute:
+
 - `entityNamePlural` = `entityName` + "s" (e.g., `TeamMembers`, `Orders`)
 - `entityNameLower` = camelCase of `entityName` (e.g., `teamMember`, `order`)
 - `entityNamePluralLower` = camelCase of `entityNamePlural` (e.g., `teamMembers`, `orders`)
@@ -76,10 +77,12 @@ From inputs compute:
 ### Existing Module Context
 
 When `existingModule` is provided:
+
 - Use the same `localePrefix` convention from `existingModule.localePrefix` instead of deriving a new one. This ensures i18n keys are consistent across all blades in the module.
 - Reference `existingModule.blades` to avoid naming collisions with existing blade component names.
 
 When `linkTo` is provided:
+
 - After generating the new list blade, open the source blade file specified by `linkTo.blade` (resolve from `existingModule.indexPath` parent directory + `pages/`).
 - Add an `openBlade` call to the source blade based on `linkTo.trigger`:
   - `"button"` — add a toolbar button with `linkTo.label` that calls `openBlade({ blade: {bladeComponentName} })`
@@ -92,6 +95,7 @@ When `linkTo` is provided:
 Write to: `{targetDir}/composables/use{EntityNamePlural}/index.ts`
 
 Follow the skeleton from `composable-list.md` exactly:
+
 - Import `useApiClient`, `useAsync`, `useLoading` from `@vc-shell/framework`
 - Import `Search{EntityName}Query`, `Search{EntityName}Result`, `{EntityName}`, `{ClientClass}` from `entityTypePath`
 - Import type alias: `import type { Search{EntityName}Query as ISearch{EntityName}Query }`
@@ -100,13 +104,14 @@ Follow the skeleton from `composable-list.md` exactly:
 - Use `useAsync<ISearch{EntityName}Query>` for the `{getFnName}` action
 - Return `loading`, `{listVarName}`, `totalCount`, `currentPage`, `pages`, `searchQuery`, `{getFnName}`
 
-If the `searchMethod` uses a non-standard pluralization (e.g., `searchSellerUsers` for `SellerUser`), match the client method name exactly.
+If the `searchMethod` uses a non-standard pluralization (e.g., `searchUsers` for `User`), match the client method name exactly.
 
 ### Step 3: Classify columns and assign VcColumn attributes
 
 For each column in `columns`, determine the VcColumn attributes using these rules:
 
 **Column type mapping** (based on field name and data type):
+
 - Field name contains "status" or "state" OR `isEnum: true` → `type="status"`, add `#body` slot with `VcStatus`
 - Field name starts with "is", "has", "can" (boolean) → `type="status-icon"`
 - Field name contains "date", "created", "modified", "updated" (Date type) → `type="date-ago"`
@@ -116,6 +121,7 @@ For each column in `columns`, determine the VcColumn attributes using these rule
 - Everything else → no type (plain text)
 
 **Mobile layout assignment** (assign to the first matching column):
+
 - First image column → `mobile-role="image"`, `:always-visible="true"`
 - First identifier column (name, number, title) → `mobile-position="top-left"`, `:always-visible="true"`
 - First status column → `mobile-role="status"`, `:always-visible="true"`
@@ -132,50 +138,28 @@ Follow the template from `list-blade-pattern.md` exactly.
 **CRITICAL: Template section — explicit VcColumn declarations (NO v-for):**
 
 Each column must be declared as a separate `<VcColumn>` element in the template. Do NOT use `v-for` with a computed array. This enables:
+
 - `#body` slots for status badges, images, and custom rendering
 - Per-column `mobile-role` / `mobile-position` attributes
 - Better readability and maintainability
 
 Example of correct column declarations:
+
 ```vue
-<VcColumn
-  id="number"
-  :title="t('ORDERS.PAGES.LIST.TABLE.HEADER.NUMBER')"
-  :always-visible="true"
-  :sortable="true"
-  mobile-position="top-left"
-/>
-<VcColumn
-  id="status"
-  :title="t('ORDERS.PAGES.LIST.TABLE.HEADER.STATUS')"
-  :always-visible="true"
-  :sortable="true"
-  type="status"
-  mobile-role="status"
->
+<VcColumn id="number" :title="t('ORDERS.PAGES.LIST.TABLE.HEADER.NUMBER')" :always-visible="true" :sortable="true" mobile-position="top-left" />
+<VcColumn id="status" :title="t('ORDERS.PAGES.LIST.TABLE.HEADER.STATUS')" :always-visible="true" :sortable="true" type="status" mobile-role="status">
   <template #body="{ data }">
     <VcStatus :variant="statusVariant(data.status)">
       {{ data.status }}
     </VcStatus>
   </template>
 </VcColumn>
-<VcColumn
-  id="total"
-  :title="t('ORDERS.PAGES.LIST.TABLE.HEADER.TOTAL')"
-  :sortable="true"
-  type="money"
-  mobile-position="top-right"
-/>
-<VcColumn
-  id="createdDate"
-  :title="t('ORDERS.PAGES.LIST.TABLE.HEADER.CREATED_DATE')"
-  :sortable="true"
-  type="date-ago"
-  mobile-position="bottom-right"
-/>
+<VcColumn id="total" :title="t('ORDERS.PAGES.LIST.TABLE.HEADER.TOTAL')" :sortable="true" type="money" mobile-position="top-right" />
+<VcColumn id="createdDate" :title="t('ORDERS.PAGES.LIST.TABLE.HEADER.CREATED_DATE')" :sortable="true" type="date-ago" mobile-position="bottom-right" />
 ```
 
 **Script setup section:**
+
 - `defineBlade({ name: "{bladeComponentName}", url: "{url}", isWorkspace: true, permissions: ["{i18nPrefix_lower}:manage"], menuItem: { title: "{menuConfig.title}", icon: "{menuConfig.icon}", priority: {menuConfig.priority} } })`
 - Import and destructure `{composableName}` with correct variable names
 - `useDataTableSort({ initialField: "createdDate", initialDirection: "DESC" })`
@@ -196,9 +180,7 @@ Instead of the normal composable that imports API client classes, generate this
 
 ```ts
 // vc-app:mock-start
-const mockData: Record<string, unknown>[] = [
-  { id: "1", name: "Item 1", status: "active", createdDate: new Date().toISOString() },
-];
+const mockData: Record<string, unknown>[] = [{ id: "1", name: "Item 1", status: "active", createdDate: new Date().toISOString() }];
 
 const fetchItems = async (query?: Record<string, unknown>) => {
   return { results: mockData, totalCount: mockData.length };
@@ -236,6 +218,7 @@ If the file already exists, append the export line (do not overwrite).
 ## Output Contract
 
 Files written to disk:
+
 1. `{targetDir}/composables/use{EntityNamePlural}/index.ts`
 2. `{targetDir}/pages/{moduleName}-list.vue`
 3. `{targetDir}/composables/index.ts` (created or appended)
@@ -245,6 +228,7 @@ Returns a summary of generated files and any assumptions made.
 ## Self-Check
 
 Before completing, verify:
+
 - [ ] `defineBlade` is at module scope (top-level of `<script setup>`), not inside any function
 - [ ] `state-key` is snake_case and unique (based on `moduleName`)
 - [ ] `useDataTableSort` destructures `sortField`, `sortOrder`, `sortExpression` — all three used
@@ -256,7 +240,7 @@ Before completing, verify:
 - [ ] **Each VcColumn is declared explicitly in the template — NO v-for with computed array**
 - [ ] Date columns use `type="date-ago"` (NOT `"date-time"`)
 - [ ] Status/state columns use `type="status"` with `#body` slot containing `VcStatus` component
-- [ ] Boolean columns (is*, has*, can*) use `type="status-icon"`
+- [ ] Boolean columns (is*, has*, can\*) use `type="status-icon"`
 - [ ] Monetary columns use `type="money"`
 - [ ] Mobile layout attributes (`mobile-position`, `mobile-role`) are assigned to key columns
 - [ ] If status column exists, `statusVariant()` function is defined in script setup

package/runtime/agents/locales-generator.md

@@ -61,6 +61,7 @@ For each key, derive its English value using this algorithm:
 For unknown suffixes: split by `_`, convert each word to Title Case, join with space.
 
 Examples:
+
 - `TEAM.MENU.TITLE` → `"Team"`
 - `TEAM.PAGES.LIST.TITLE` → `"Team"`
 - `TEAM.PAGES.LIST.TOOLBAR.ADD` → `"Add"`
@@ -112,6 +113,7 @@ export { en };
 ## Output Contract
 
 Files written to disk:
+
 1. `{targetDir}/locales/en.json`
 2. `{targetDir}/locales/index.ts`
 
@@ -120,6 +122,7 @@ Returns a summary listing number of keys extracted and any keys with uncertain v
 ## Self-Check
 
 Before completing, verify:
+
 - [ ] All files in `generatedFiles` were read (not just the first)
 - [ ] Both `$t('...')` and `t('...')` patterns were captured
 - [ ] Keys with template literal interpolation (`${...}`) were excluded

package/runtime/agents/migration-agent.md

@@ -0,0 +1,94 @@
+---
+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. `notification-migration` — may create new files and restructure directories
+2. `nswag-class-to-interface` — type-level changes that affect all other code
+3. `use-assets-migration` — rewires assets handlers and may add manager wiring used by blades/widgets
+4. `widgets-migration` — creates new composable files referenced by blades
+5. `use-blade-form` — depends on correct types from nswag
+6. `blade-props-simplification` — final cleanup of reusable components
+7. `vctable-audit` — VcTable → VcDataTable component and API rewrite
+8. `icon-audit` — replace all non-lucide icons with lucide equivalents (last among mechanical manual edits)
+9. `manual-migration-audit` — catch-all manual refactors (run last to avoid overlap)
+
+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` and `widgets/useXxxCount.ts` for widget migration — new files go in the `widgets/` directory at the module level, NOT in `composables/`)
+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:** Restore from backup copy (`cp {filepath}.bak {filepath}`), delete backup (`rm -f {filepath}.bak`), keep the failure in the report as "needs manual intervention", continue to next file
+
+Before step 4, always create a backup:
+
+- `cp {filepath} {filepath}.bak`
+- Delete the backup after a successful commit for that 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/agents/module-analyzer.md

@@ -26,6 +26,7 @@ This agent does NOT write files. It reads the module source tree and produces a
 Read `{targetDir}/index.ts` (or `{targetDir}/index.js` if TypeScript variant is absent).
 
 Extract:
+
 - **Module name** — from the `defineAppModule` call's first argument or the `id` / `name` field in the object argument
 - **Blade registrations** — from the `blades` key in `defineAppModule`. Each entry maps a blade component import to its registration. Collect the import paths to locate blade files.
 - **All imports** — record import paths and specifiers for cross-referencing
@@ -140,6 +141,7 @@ Combine all extracted data into the output contract structure.
 ## Self-Check
 
 Before completing, verify:
+
 - [ ] All `.vue` files in `pages/` have been discovered and typed correctly as `list`, `details`, or `custom`
 - [ ] All composables in `composables/` (including nested index.ts patterns) have been discovered with their exports listed
 - [ ] API connection status is accurate — reflects actual `useApiClient` usage, not just the presence of import paths

package/runtime/agents/module-assembler.md

@@ -37,6 +37,7 @@ When `mode: "append"`:
 5. Use the Edit tool (not Write tool) for all file modifications in append mode
 
 Specifically in append mode:
+
 - `pages/index.ts` — append new `export { default as NewBlade } from "./new-blade.vue"` lines
 - `composables/index.ts` — append new composable export lines
 - `{targetDir}/index.ts` — no changes needed (namespace import `* as pages` picks up new pages automatically)
@@ -45,6 +46,7 @@ Specifically in append mode:
 ### Step 1: Derive naming variables
 
 From `moduleName` compute:
+
 - `moduleClassName` = PascalCase of `moduleName` (e.g., `Team`, `CatalogItems`)
 - `targetDir` = directory containing the generated files (parent of `pages/`, `composables/`, `locales/`)
 
@@ -53,10 +55,12 @@ To find `targetDir`: take the directory of the first file in `generatedFiles` th
 ### Step 2: Identify generated pages and composables
 
 From `generatedFiles`, classify each file:
+
 - Files under `*/pages/*.vue` → page components
 - Files under `*/composables/**/*.ts` but NOT `*/composables/index.ts` → composable implementations
 
 For each page file, derive its export name:
+
 - `team-list.vue` → `TeamList`
 - `team-details.vue` → `TeamDetails`
 - `{moduleName}-list.vue` → PascalCase(`moduleName`) + `List`
@@ -69,6 +73,7 @@ For each composable directory (e.g., `useTeamMembers/`), derive its export name
 Write to: `{targetDir}/pages/index.ts`
 
 Export each page component as a named export:
+
 ```ts
 export { default as TeamList } from "./team-list.vue";
 export { default as TeamDetails } from "./team-details.vue";
@@ -83,6 +88,7 @@ Write to: `{targetDir}/composables/index.ts`
 If the file was already created by a generator agent (list-blade-generator or details-blade-generator), read it and ensure all composables have an export. Otherwise create it with all discovered composables.
 
 Format:
+
 ```ts
 export { default as useTeamMembers } from "./useTeamMembers";
 export { default as useTeamMember } from "./useTeamMember";
@@ -93,6 +99,7 @@ export { default as useTeamMember } from "./useTeamMember";
 Write to: `{targetDir}/index.ts`
 
 Follow `module-structure.md` exactly:
+
 ```ts
 import * as pages from "./pages";
 import * as locales from "./locales";
@@ -111,14 +118,17 @@ Do NOT re-export locales. Do NOT use a default export for locales.
 Read `appModulesRegistryPath` (e.g., `src/modules/index.ts`).
 
 Parse existing exports to detect if the module is already registered:
+
 - Check for `export { default as {moduleClassName} }` or `export * from "./{moduleName}"`
 
 If NOT already registered, append:
+
 ```ts
 export { default as {moduleClassName} } from "./{moduleName}";
 ```
 
 **Critical rules for registry update:**
+
 - Read the existing file first — NEVER overwrite it from scratch
 - Append the new export at the end of the file
 - Preserve all existing export lines exactly
@@ -130,12 +140,14 @@ export { default as {moduleClassName} } from "./{moduleName}";
 Find the app entry point: look for `src/main.ts` relative to the project root (the parent of `src/modules/`).
 
 Read `main.ts` and check if `{moduleClassName}` is already imported and used:
+
 - Check for `import { ... {moduleClassName} ... } from "./modules"` (or `from "@/modules"`)
 - Check for `app.use({moduleClassName})`
 
 If NOT already registered:
 
 1. **Update the modules import.** Find the existing `import { ... } from "./modules"` line. Add `{moduleClassName}` to its named imports. If no such import exists, add:
+
    ```ts
    import { {moduleClassName} } from "./modules";
    ```
@@ -146,6 +158,7 @@ If NOT already registered:
    - BEFORE `app.use(router)` (router must come after all modules)
 
 **Critical rules:**
+
 - Read the file first — NEVER overwrite from scratch
 - Use Edit tool for surgical changes
 - Preserve all existing imports and app.use() calls
@@ -155,6 +168,7 @@ If NOT already registered:
 ## Output Contract
 
 Files written to disk:
+
 1. `{targetDir}/pages/index.ts` (created or updated)
 2. `{targetDir}/composables/index.ts` (created or updated)
 3. `{targetDir}/index.ts` (created)
@@ -166,6 +180,7 @@ Returns a summary of all files created/modified and confirmation of registry reg
 ## Self-Check
 
 Before completing, verify:
+
 - [ ] `defineAppModule({ blades: pages, locales })` — both `pages` and `locales` are passed
 - [ ] `export * from "./pages"` and `export * from "./composables"` are in module `index.ts`
 - [ ] `locales` is NOT re-exported (no `export * from "./locales"`)