cabloy 5.1.58 → 5.1.60

package/.claude/skills/cabloy-contract-loop/SKILL.md

@@ -7,6 +7,17 @@ description: Use this skill whenever a Cabloy task crosses the Vona-to-Zova cont
 
 Use this skill when a backend contract change needs to be reflected in frontend consumers, or when frontend consumers appear stale and you need to diagnose whether the backend contract loop is the real source of drift.
 
+## Important recovery note for stale local file consumers
+
+When generated `.zova-rest` output or other generated consumer artifacts already contain the expected new keys or types but Vona still behaves as if old consumer types are installed, treat that first as a local file-dependency installation problem rather than a source-editing problem.
+
+In that situation:
+
+1. run the normal sync or regeneration flow first
+2. if stale behavior remains after `deps:vona`, rebuild `vona/node_modules` and reinstall dependencies
+
+Do not keep debugging source-level contract or renderer changes until the local file-package installation state is known to be healthy.
+
 ## Goals
 
 1. detect whether the active repository is Cabloy Basic or Cabloy Start
@@ -71,6 +82,7 @@ For deeper reference material, read:
 
 - `references/contract-loop-map.md`
 - `references/verification-checklist.md`
+- `references/resource-custom-state-pattern.md`
 
 ## Step 3: Identify the contract source of truth deliberately
 
@@ -130,6 +142,8 @@ Typical Zova commands include:
 - `npm run zova :openapi:config ...`
 - `npm run zova :openapi:generate ...`
 
+When the target is a module-local SDK, constrain `openapi.config.ts` with `operations.match` unless the module intentionally owns a broad API surface. This prevents unrelated APIs from being generated into the module.
+
 ### Path B: REST/type generation by flavor
 
 Use the edition-specific Zova REST/type build path when the workflow depends on the built flavor outputs.
@@ -150,6 +164,8 @@ After generation, inspect whether the frontend still needs follow-up in:
 - schema-driven UI
 - page or component assumptions
 
+If a custom endpoint still belongs to an existing resource, prefer one resource-state owner instead of letting a module-local model create a second cache tree. Reuse the resource-owned custom state pattern in `references/resource-custom-state-pattern.md`.
+
 ## Step 6: Keep edition-aware differences explicit
 
 The collaboration model is shared across Basic and Start, but the operational details may differ.

package/.claude/skills/cabloy-contract-loop/references/contract-loop-map.md

@@ -32,6 +32,32 @@ Likely next step:
 - confirm whether backend contract really changed
 - regenerate instead of hand-patching
 
+## Module-local OpenAPI generation boundary
+
+When generating a module-local OpenAPI SDK, do not leave the module config effectively unconstrained if the module should only own a narrow resource surface.
+
+Preferred rule:
+
+- set `operations.match` in `openapi.config.ts` so the module generates only the intended API operations
+
+Reason:
+
+- an unconstrained or overly broad generation pass can pull unrelated APIs into the module
+- that expands generated SDK files, metadata exports, and downstream type surfaces far beyond the module’s real ownership boundary
+- the result may still compile, but it weakens module boundaries and makes maintenance harder
+
+Representative example:
+
+- a module-level OpenAPI config such as `zova/src/module/demo-student/cli/openapi.config.ts`
+- narrow the generated surface with a module-specific matcher such as `operations.match: [/^DemoStudent_*/]`
+
+Treat that module path as an example, not as a durable dependency of the rule. The durable rule is to align `operations.match` with the module’s true API ownership boundary.
+
+Practical check after generation:
+
+- confirm the generated API files only contain the intended resource operations
+- confirm the module metadata and exports were not polluted by unrelated APIs
+
 ## Shared rule
 
 The sequence is usually:

package/.claude/skills/cabloy-contract-loop/references/resource-custom-state-pattern.md

@@ -0,0 +1,144 @@
+# Resource Custom State Pattern
+
+Use this reference when a contract-loop task adds or refactors a custom API that still belongs to an existing resource.
+
+Typical examples:
+
+- `summary/:id`
+- `restore/:id`
+- `deleteForce/:id`
+- `history/:id`
+- any other row-scoped endpoint that should stay synchronized with standard resource list or entry flows
+
+## The ownership rule
+
+Prefer one owner for all resource-bound server state.
+
+In this codebase, the preferred owner is:
+
+- `rest-resource.model.resource`
+
+Do not let a module-local model become a second state owner for the same resource rows unless the boundary is explicitly intentional.
+
+## The split to avoid
+
+Avoid this pattern:
+
+1. standard resource list and entry pages consume `rest-resource.model.resource`
+2. a module-local model introduces separate query or mutation state for the same rows
+3. custom mutation success invalidates only the local model keys
+4. the generic resource pages keep reading stale row or list state
+
+This usually happens when a task starts with a module-local generated SDK wrapper and stops there. The pattern is generic and should not depend on any one demo module continuing to exist.
+
+## Preferred pattern
+
+Use this shape instead:
+
+1. keep `ModelResource` as the single owner of resource-bound server state
+2. add reusable resource-owned helpers for custom query and mutation state
+3. keep module-local models only as thin semantic facades when the task still benefits from a business-local API surface
+
+A good semantic facade may still expose methods such as:
+
+- `summary(id)`
+- `deleteForce(id)`
+
+But those methods should delegate to `ModelResource`, not create a competing cache owner.
+
+## Cache-key convention
+
+For row-scoped state, group keys under the item identity.
+
+Preferred structure:
+
+- row root:
+  - `['item', id]`
+- row query scenes:
+  - `['item', id, 'get']`
+  - `['item', id, 'summary']`
+  - `['item', id, 'history']`
+- row mutation scenes may extend the same structure, for example:
+  - `['item', id, 'deleteForce', 'mutation']`
+
+For list-scoped resource queries, keep the select-style grouping, for example:
+
+- `['select', actionPath ?? '', hashkey(query)]`
+
+## Invalidation rule
+
+For a row-affecting mutation:
+
+- invalidate `['item', id]`
+
+For a list-affecting mutation:
+
+- invalidate `['select']`
+
+If both are affected:
+
+- invalidate both
+
+This is the key benefit of the grouped row-root convention: one invalidation clears all row-specific query scenes for the same item.
+
+## Helper naming guidance
+
+When adding reusable row-scoped helper options, prefer `action` over `scene` or `handler`.
+
+Reason:
+
+- `action` matches resource semantics such as `get`, `summary`, `deleteForce`
+- `scene` already has stronger UI and form-scene meaning elsewhere in the codebase
+- `handler` describes implementation shape rather than resource meaning
+
+Preferred examples:
+
+- `queryItem({ id, action: 'summary', ... })`
+- `mutationItem({ id, action: 'deleteForce', ... })`
+
+## Typed SDK guidance
+
+Keep generated SDK calls typed and module-local.
+
+Preferred split:
+
+- module-local facade keeps the generated SDK call
+- `ModelResource` owns the query or mutation state and invalidation policy
+
+That means the facade passes typed closures into the generic helpers, conceptually like:
+
+- `queryItem({ id, action: 'summary', queryFn: () => api.summary(...) })`
+- `mutationItem({ id, action: 'deleteForce', mutationFn: () => api.deleteForce(...) })`
+
+This preserves strong typing without duplicating state ownership.
+
+## When to reuse this pattern
+
+Reuse it when all of the following are true:
+
+- the endpoint still belongs logically to an existing resource
+- standard resource list or entry pages already consume that resource through `rest-resource.model.resource`
+- stale row or list state would matter after the mutation or fetch
+- the task needs a custom API shape beyond standard CRUD, but not a separate application-state subsystem
+
+## When a separate owner may still be acceptable
+
+A separate owner may still be fine when the data is not really part of the resource state surface, for example:
+
+- unrelated dashboard data
+- global application state
+- purely local UI state
+- intentionally unsynchronized auxiliary data
+
+Even then, be explicit about the boundary.
+
+## Quick checklist
+
+1. confirm whether the resource pages already use `rest-resource.model.resource`
+2. decide whether the custom endpoint is row-scoped or list-scoped
+3. reuse or extend the generic resource helpers instead of creating a second owner
+4. group row keys under `['item', id, action]`
+5. invalidate `['item', id]` for row-affecting mutations
+6. invalidate `['select']` for list-affecting mutations
+7. keep module-local models semantic-only when possible
+8. verify both standard resource flows and the new custom action flow

package/.claude/skills/cabloy-contract-loop/references/verification-checklist.md

@@ -27,6 +27,24 @@ After a contract-loop change, check both sides.
 - affected flavor confirmed
 - generation path matches the active edition
 
+## Recovery rule for stale local file consumers
+
+If all of these are true:
+
+- generated `.zova-rest` or related generated consumer artifacts already contain the expected new keys or types
+- the normal regeneration or sync flow already ran
+- Vona still behaves as if old consumer types are installed
+
+Then suspect a stale or unhealthy local installation state in `vona/node_modules`.
+
+Recovery action:
+
+```bash
+cd vona && rm -rf node_modules && pnpm install
+```
+
+Use this as a recovery path when normal sync steps did not restore the local file-package installation state cleanly.
+
 ## Done rule
 
 A contract-loop task is not done when only the backend compiles or only the frontend builds. It is done when the contract source and the generated consumer path agree.

package/.claude/skills/cabloy-resource-field-update/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: cabloy-resource-field-update
+description: Use this skill whenever the user wants to update a field on an existing Cabloy backend resource: add a new persisted field, refine validation, add enum-like constraints, attach or change ZovaRender.field / ZovaRender.cell metadata, decide whether vonaModule.fileVersion should change, or demonstrate a custom frontend renderer for a backend field. Trigger when the request is specifically about modifying an existing resource field thread rather than creating a new CRUD/resource thread. Prefer it for backend-first field-update work that may branch into renderer-aware frontend follow-up. Do not use it for initial backend scaffolding, generic frontend scaffolding, or stale generated contract diagnosis.
+---
+
+# Cabloy Resource Field Update
+
+Use this skill when the user wants to change a field on an existing Vona backend resource.
+
+## Important recovery note for stale generated consumers
+
+When generated `.zova-rest` output already contains the expected new keys or types but Vona still behaves as if old consumer types are installed, treat that first as a local file-dependency installation problem rather than a source-editing problem.
+
+In that situation:
+
+1. run the normal sync flow such as `deps:vona`
+2. if the stale behavior remains, rebuild `vona/node_modules` and reinstall dependencies
+
+Keep this recovery rule visible during renderer-aware or contract-loop follow-up work. Do not keep debugging source-level renderer registrations until the local file-package installation state is known to be healthy.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. classify the task as a new persisted field or a metadata-only field refinement
+3. force the correct `fileVersion` decision before persistence edits
+4. keep the workflow entity-first and inferred-DTO-first
+5. prefer shared renderer reuse unless the task explicitly asks for a custom renderer demo
+6. finish with verification guidance that matches backend and renderer follow-up scope
+
+## Step 1: Detect repo and confirm existing-resource scope
+
+Check the repository root for these marker files:
+
+- `__CABLOY_BASIC__`
+- `__CABLOY_START__`
+
+Interpretation:
+
+- `__CABLOY_BASIC__` present → this is Cabloy Basic
+- `__CABLOY_START__` present → this is Cabloy Start
+- neither present → inspect nearby scripts and ask before making edition-specific assumptions
+
+Then confirm the request is about an **existing** resource field.
+
+Use this skill for requests such as:
+
+- add a field to an existing resource
+- tighten validation for an existing field
+- add enum-like constraints to an existing field
+- add or change `ZovaRender.field(...)` / `ZovaRender.cell(...)`
+- decide whether a persisted field change needs a new `fileVersion`
+- demonstrate a custom renderer workflow for a backend field
+
+Do **not** use this skill when the user is really asking to create a new module, bean, CRUD thread, page thread, or stale consumer diagnosis flow.
+
+If the request is really about initial backend thread creation, prefer `cabloy-backend-scaffold`.
+If the request is really about stale generated frontend/backend consumers, prefer `cabloy-contract-loop`.
+If the request is mainly about choosing a workflow, prefer `cabloy-workflow`.
+
+## Step 2: Classify the field change before editing
+
+Branch the request into one of two cases.
+
+### Case A: new persisted field
+
+Examples:
+
+- add `level: number`
+- add `status: string`
+- add a new stored relation key
+
+This case affects persistence and versioning.
+
+### Case B: metadata-only or validation/render-only refinement
+
+Examples:
+
+- add enum validation to an existing field
+- add or change `ZovaRender.field(...)`
+- add or change `ZovaRender.cell(...)`
+- refine locale labels
+- tighten validation without changing storage shape
+
+This case usually does **not** require a `fileVersion` bump, because the persisted field already exists.
+
+## Step 3: Force the `fileVersion` decision for new persisted fields
+
+If the task is a new persisted field on an existing resource, ask whether `vonaModule.fileVersion` should be incremented **before** changing:
+
+- `meta.version.ts`
+- the module schema version path
+- the module `package.json` `fileVersion`
+
+### If the user says yes
+
+Then:
+
+1. bump `vonaModule.fileVersion`
+2. add a new migration branch in `meta.version.ts`
+3. preserve older version branches as historical snapshots
+4. introduce the new persisted field in the new version branch
+
+Important warning:
+
+- do not add the same new column to an older create path and again to a new migration branch
+- fresh install may run version branches sequentially
+- that pattern can produce duplicate-column failures
+
+### If the user says no
+
+Then:
+
+1. keep the current `fileVersion`
+2. fold the schema change into the current version path
+3. do not create a new migration branch
+
+## Step 4: Inspect the current backend thread first
+
+Before proposing or making edits, inspect the existing thread:
+
+- entity
+- model
+- DTOs
+- controller
+- service
+- `meta.version.ts`
+- module `package.json`
+- locale files
+- tests
+
+Also inspect the shared entrypoints first:
+
+- root `package.json`
+- `npm run vona`
+- `npm run zova`
+
+Use these references for compact support material:
+
+- `references/field-update-decision-tree.md`
+- `references/follow-up-checklist.md`
+- `references/verification-checklist.md`
+
+## Step 5: Update the entity first and reuse inferred DTO flow
+
+Treat the entity as the primary field-definition surface.
+
+Typical field-update changes belong here first:
+
+- `@Api.field(...)`
+- `v.required()` / `v.optional()`
+- `v.title($locale(...))`
+- `ZovaRender.order(...)`
+- explicit zod schema for constrained values
+
+For enum-like numeric or string values, prefer an explicit constrained schema such as:
+
+- `z.union([z.literal(1), z.literal(2), z.literal(3)])`
+
+Then check whether DTOs are already inferred through patterns such as:
+
+- `$Dto.create(...)`
+- `$Dto.update(...)`
+- `$Dto.get(...)`
+
+If the DTOs are inferred from the entity/model chain, let the entity change propagate. Do not hand-edit DTO field lists unless the source clearly requires it.
+
+## Step 6: Apply the renderer branch deliberately
+
+### Default rule: prefer shared renderer reuse
+
+If the field needs form or table rendering metadata, inspect shared renderers first.
+
+Default preference order:
+
+1. reuse an existing shared renderer
+2. configure it with field-level options
+3. only create a new custom renderer if the shared surface cannot express the needed behavior
+
+For enum-like values, apply an edition-aware default.
+
+In Cabloy Basic, the usual default is:
+
+- `ZovaRender.field('basic-select:formFieldSelect', { items, placeholder })`
+- `ZovaRender.cell('basic-select:select', { items })`
+
+In Cabloy Start:
+
+- do not assume the same renderer keys or placeholder behavior from Basic
+- inspect the `start-select` wrapper and its underlying component semantics before choosing renderer keys or copying Basic-specific select logic
+
+When using a field-rendering select component, default to providing a user-visible `placeholder` unless the UX clearly requires an always-preselected value.
+
+In Cabloy Basic, prefer `placeholder` over artificial empty-item injection when the goal is to keep the select initially unchosen.
+
+### Custom renderer demo rule
+
+If the user explicitly wants to **demonstrate** the custom renderer workflow, branch into a frontend follow-up path.
+
+Use these references:
+
+- `references/custom-renderer-demo-checklist.md`
+- `.docs-internal/architecture/backend-resource-field-workflow.md`
+
+Recommended shape:
+
+- module-local FormField component for backend field rendering
+- module-local `@TableCell(...)` bean for backend table-cell rendering
+- metadata regeneration
+- frontend build
+- `deps:vona`
+- Vona-side typecheck and targeted backend test
+
+Important warning:
+
+- a plain frontend component alone is not enough for backend `ZovaRender.cell(...)`
+- the backend table-cell render key should be backed by a registered `@TableCell(...)` bean
+
+## Step 7: Always close the remaining layers
+
+### Locale
+
+If titles, enum labels, or helper text are user-visible, update locale files in the same task.
+
+Typical additions:
+
+- field title like `Level`
+- enum labels like `LevelBeginner`, `LevelIntermediate`, `LevelAdvanced`
+- custom renderer helper text when applicable
+
+### Tests
+
+Minimum expected backend coverage usually includes:
+
+- create with the field
+- select/list still works
+- update persists the field
+- get-by-id/view returns the field
+- delete flow still works if relevant
+
+For constrained enum-like fields, add a negative test such as:
+
+- invalid value is rejected
+
+### Verification
+
+Always end with a verification path matched to the scope.
+
+Typical checks include:
+
+- `npm run test`
+- `npm run tsc`
+- `npm run build`
+- narrow resource test runs
+- renderer/build/deps synchronization when custom frontend renderers are involved
+
+## Response pattern
+
+When helpful, structure the response around these points:
+
+1. detected edition
+2. persisted-field vs metadata-only classification
+3. `fileVersion` decision if needed
+4. backend thread surfaces to inspect or modify
+5. shared-renderer reuse vs custom-renderer branch
+6. verification steps
+
+Keep the response practical. The value of this skill is turning existing-resource field updates into the correct Cabloy decision tree with the right backend and renderer follow-up, not writing a broad architecture essay.

package/.claude/skills/cabloy-resource-field-update/evals/evals.json

@@ -0,0 +1,53 @@
+{
+  "skill_name": "cabloy-resource-field-update",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Please add a new persisted level field to the existing student resource in Cabloy Basic. Before doing anything else, tell me whether fileVersion needs a decision and what layers must be updated.",
+      "expected_output": "Must classify the task as a new persisted field on an existing resource, must require a fileVersion decision before migration edits, and must mention entity, meta.version, package.json, locale, and tests as relevant follow-up layers.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I want to add a new persisted field to an existing Cabloy resource, but do not bump fileVersion — fold it into the current version path. What workflow should Claude follow?",
+      "expected_output": "Must recognize the no-bump branch, keep the current fileVersion, avoid creating a new migration version branch, and still mention schema-path, entity, locale, and tests as required follow-up surfaces.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "The level field already exists in storage. I only want to tighten it to an enum-like 1/2/3 field and attach select-style render metadata. Keep this as a field refinement workflow, not a migration plan.",
+      "expected_output": "Must classify the task as metadata-only or validation/render-only refinement, must avoid unnecessary fileVersion escalation, and must mention explicit validation, renderer metadata, locale, and invalid-value testing.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "In Cabloy Basic, please update the existing student resource field so it uses the best existing shared renderer first. I want the Cabloy way, not a custom component unless it is really needed.",
+      "expected_output": "Must prefer shared renderer reuse first, should mention basic-select as the default Cabloy Basic select-style baseline for enum-like fields, and should not jump straight into custom renderer creation.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "I know the shared renderer would work, but I explicitly want a custom renderer demo for this existing backend field so future AI can learn the workflow. What should Claude do?",
+      "expected_output": "Must branch into the custom renderer demo workflow, must mention a module-local FormField component plus a module-local @TableCell bean, and must include metadata generation, frontend build, deps:vona, and Vona verification steps.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Create a brand new CRUD resource for courses in Cabloy and tell me the best generation path.",
+      "expected_output": "Must not treat this as an existing-resource field-update workflow. It should indicate that initial CRUD/resource creation belongs to the backend scaffold or a broader workflow, not this skill.",
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "In Cabloy Basic, the level field already exists and I want select-style field rendering for it. Claude should use the shared renderer path, and unless the UX truly requires a preselected value, I want the field to start unchosen with a visible hint. What guidance should Claude follow?",
+      "expected_output": "Must classify this as an existing-field refinement, prefer the shared Cabloy Basic select renderer path, default to providing a user-visible placeholder for the field-rendering select component unless the UX clearly requires a preselected value, and prefer placeholder over artificial empty-item injection for Cabloy Basic rather than assuming the same behavior in Cabloy Start.",
+      "files": []
+    },
+    {
+      "id": 8,
+      "prompt": "In Cabloy Start, the level field already exists and now needs select-style field rendering. I want Claude to reuse the right shared renderer path if possible, and I also care about how an initially unchosen state should work. What guidance should Claude follow?",
+      "expected_output": "Must classify this as an existing-field refinement, must detect that this is Cabloy Start, must still prefer shared renderer reuse first rather than jumping straight to a custom renderer, must not jump straight to Cabloy Basic renderer keys such as basic-select, and must say to inspect the Start-side select wrapper and underlying component semantics before deciding renderer keys or copying Cabloy Basic placeholder or empty-item behavior.",
+      "files": []
+    }
+  ]
+}

package/.claude/skills/cabloy-resource-field-update/references/custom-renderer-demo-checklist.md

@@ -0,0 +1,102 @@
+# Custom Renderer Demo Checklist
+
+Use this checklist when the user explicitly wants to demonstrate how a backend resource field can switch from a shared renderer to a custom module-local renderer.
+
+## Goal
+
+Preserve the field’s backend business semantics while deliberately exercising the full frontend renderer registration path.
+
+## 1. Confirm the task is really instructional
+
+Use this branch when the user wants to show:
+
+- how to build a custom FormField component
+- how to build a custom backend-usable TableCell renderer
+- how to connect them back to `ZovaRender.field(...)` / `ZovaRender.cell(...)`
+
+If the user only wants the simplest production implementation, prefer shared renderer reuse instead.
+
+## 2. Keep business semantics unchanged if possible
+
+Do not rework field meaning unless the request also asks for it.
+
+Preserve existing semantics such as:
+
+- allowed values
+- locale labels
+- `items`, `itemValue`, `itemTitle`
+- backend field name and DTO flow
+
+## 3. Build the correct frontend pair
+
+### FormField
+
+Add a module-local FormField component such as:
+
+- `src/component/formFieldX/controller.tsx`
+
+Best practice:
+
+- reuse the option shape of the closest shared renderer
+- copy the data flow from the shared baseline first
+- default to providing a user-visible `placeholder` for field-rendering select components unless the UX clearly requires an always-preselected value
+- in Cabloy Basic, keep placeholder handling aligned with `basic-select` semantics instead of adding artificial empty items by default
+- in Cabloy Start, verify the `start-select` wrapper behavior before copying Basic-specific placeholder or empty-item logic
+- keep customizations minimal and clearly demo-oriented
+
+### TableCell
+
+Add a module-local `@TableCell(...)` bean such as:
+
+- `src/bean/tableCell.x.tsx`
+
+Important:
+
+- backend `ZovaRender.cell(...)` should point to a registered table-cell key
+- a plain frontend component is not enough for this role
+
+## 4. Use the best existing baseline
+
+For select-like enum fields, start from an edition-correct baseline.
+
+In Cabloy Basic, start from:
+
+- `basic-select` FormField behavior
+- `basic-select` table-cell bean behavior
+
+In Cabloy Start:
+
+- identify the Start-side select baseline first rather than reusing Basic components by name
+- verify placeholder and empty-state behavior before copying Basic-specific logic
+
+The goal is to demonstrate module-local customization, not to reinvent field-state handling.
+
+## 5. Regenerate and synchronize in the right order
+
+Recommended order:
+
+1. create or update renderer source files
+2. regenerate frontend metadata
+3. run the relevant frontend build so both bundle output and type surface update
+4. run `deps:vona`
+5. run Vona typecheck
+6. run the narrow backend resource test
+
+For Cabloy Basic admin, the representative flow is:
+
+```bash
+npm run zova :tools:metadata <module-name>
+npm run build:zova:admin
+npm run deps:vona
+cd vona && npm run tsc
+cd vona && npm test -- <resource-test>.test.ts
+```
+
+## 6. Recovery rule when generated keys still look stale
+
+If the generated `.zova-rest` files already contain the new renderer keys but Vona still behaves as if old types are installed:
+
+- suspect a stale or unhealthy `vona/node_modules` installation state
+- after normal `deps:vona`, rebuild `vona/node_modules` and reinstall dependencies if needed
+
+This is an installation-state recovery step, not the normal first move.