cabloy 5.1.59 → 5.1.61

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

@@ -0,0 +1,148 @@
+# 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.
+
+This is a downstream consumer-alignment pattern for the forward chain. It applies after contract regeneration, not instead of contract generation.
+
+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
+
+This is the forward-chain downstream rule in practice: regenerate the contract first, then keep the frontend follow-up thin and resource-owner-aware.
+
+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

@@ -1,31 +1,67 @@
 # Verification Checklist
 
-After a contract-loop change, check both sides.
+After a contract-loop change, verify the branch that actually applies.
 
-## Backend verification
+## Edition verification
+
+- Basic or Start marker confirmed
+- affected flavor confirmed
+- generation path matches the active edition
 
+## Forward chain verification
+
+- backend contract source is correct
 - controller action contract is correct
 - DTO and validation align
 - OpenAPI output reflects the intended shape
-- backend tests pass
-- `npm run test`
+- module ownership is constrained
+- regeneration commands completed successfully
+- generated SDK or schema outputs are updated
+- thin model facades and downstream consumers still align with the regenerated contract
 - `npm run tsc`
 - `npm run build`
 
-## Frontend verification
+## Reverse chain verification
 
-- regeneration commands completed successfully
-- generated SDK/schema outputs are updated
-- API/model/page/component consumers still typecheck
+- frontend-owned source is correct
+- metadata generation completed when applicable
+- the relevant flavor build completed successfully
+- `deps:vona` completed
+- backend consumers can resolve the refreshed frontend-generated handoff
+- prefer visible proof under `zova/src/**/.metadata/**` when it is available
+- this repo does not rely on a contract-loop pre-commit gate; the active safeguard is the Claude hook layer
+- if the change was a high-confidence Zova reverse-source edit through the Claude hook path, confirm whether the hook already auto-ran `npm run build:zova:admin` and `npm run deps:vona`
+- if the change was consumer-side, low-confidence, outside the Claude hook path, or in another edition branch, run the reverse sync flow manually instead of assuming it already happened
+- if the real handoff only appears in `.zova-rest`, treat the safeguard as conservative reminder/auto-sync assistance rather than strict proof
 - `npm run tsc:zova`
-- `npm run build:zova`
 - relevant flavor-specific or route-specific checks
 
-## Edition verification
+## Consumer drift verification
 
-- Basic or Start marker confirmed
-- affected flavor confirmed
-- generation path matches the active edition
+- source truth already looks correct
+- generated output already looks correct
+- the next consumer layer is the place that still looks stale
+- do not patch source or generated artifacts again until the stale consumer path is identified
+
+## 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
+- when relevant, the affected Zova flavor build already ran
+- `deps:vona` 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
 

package/.claude/skills/cabloy-frontend-scaffold/SKILL.md

@@ -134,6 +134,16 @@ Check whether the feature needs:
 - SSR init-data updates
 - OpenAPI SDK regeneration
 - schema-driven UI or `$apiSchema` review
+- reverse fullstack handoff when newly added frontend resources will later be consumed by backend metadata or backend tooling
+
+If the frontend change introduces resources such as a custom form-field renderer, table-cell renderer, or other generated metadata that backend `ZovaRender.field(...)` / `ZovaRender.cell(...)` will consume, do not treat the task as frontend-only cleanup.
+
+In that case, surface this operational sequence:
+
+1. refresh metadata when needed
+2. build the affected flavor output
+3. run `deps:vona`
+4. if backend-side shared types still look stale, escalate to the contract-loop recovery path instead of continuing source-level debugging
 
 ### Component and interaction follow-up
 
@@ -173,6 +183,7 @@ Stay frontend-first, but if the frontend task clearly depends on backend contrac
 - backend OpenAPI output may need refresh or inspection
 - backend DTO/controller response shape may be the real source of truth
 - frontend SDK or schema-driven layers should be regenerated from contract output rather than hand-patched
+- newly added frontend resources that backend metadata will consume may require a reverse handoff through frontend build output and `deps:vona`
 
 Do not turn the skill into a backend workflow. Only surface the reminder when the contract boundary is clearly involved.
 

package/.claude/skills/cabloy-frontend-scaffold/references/follow-up-checklist.md

@@ -15,6 +15,8 @@ After generating or extending a frontend thread, check which follow-up layers ap
 - SSR init-data needs
 - OpenAPI SDK or schema-driven layer impact
 - backend contract reminder if frontend depends on generated backend contract output
+- if backend metadata will consume newly added frontend render resources, run the relevant Zova build and then `deps:vona`
+- if generated `.zova-rest` output is updated but backend still sees stale shared types, rebuild `vona/node_modules` and reinstall
 
 ## Interaction and UI follow-up
 

package/.claude/skills/cabloy-module-removal/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: cabloy-module-removal
+description: Use this skill whenever the user wants to remove or delete an existing Cabloy module, retire a demo module, or cleanly take a backend, frontend, or fullstack module out of the monorepo. Trigger for requests such as remove module, delete module, retire module, remove demo module, or remove fullstack module, including equivalent requests in other languages. Prefer it when the task is about deletion order, generated-runtime cleanup, and verification rather than scaffolding or contract evolution.
+---
+
+# Cabloy Module Removal
+
+Use this skill when the user wants to remove an existing module from the Cabloy monorepo.
+
+Read the public [Module Removal Playbook](../../../cabloy-docs/ai/playbook-module-removal.md) for the canonical user/agent-facing workflow. This skill is the thinner orchestration layer: it should classify the removal path, choose the right cleanup branch, and point back to the playbook for the shared operational sequence.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. classify the removal scope as backend-only, frontend-only, or fullstack
+3. keep the workflow source-first instead of debugging generated artifacts too early
+4. make the stale-generated-runtime recovery branch explicit when needed
+5. finish with verification guidance that proves the module is gone from the runtime/code graph
+
+## Step 1: Detect repo and classify the removal branch
+
+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 classify the request into one of three branches:
+
+### Branch A: backend-only removal
+
+Use this branch when the user is removing only Vona-side code such as:
+
+- `vona/src/module/<module>`
+- backend package references
+- backend tests or metadata tied only to Vona
+
+### Branch B: frontend-only removal
+
+Use this branch when the user is removing only Zova-side code such as:
+
+- `zova/src/module/<module>`
+- frontend package references
+- Zova-only API/model/component assets
+
+### Branch C: fullstack removal
+
+Use this branch when the module exists on both sides or the request affects both Vona and Zova.
+
+This is the default branch for demo modules and shared business threads.
+
+## Step 2: Inventory real source and direct references first
+
+Before proposing or making cleanup steps, inspect the real module surfaces first:
+
+- backend and frontend module roots
+- `vona/package.json`
+- `zova/package.json`
+- generated registries or lockfiles that may need refresh
+- tests tied to the module
+- optional docs/examples only if the user explicitly wants a public scrub
+
+Start from the shared root scripts first:
+
+- `package.json`
+- `npm run vona`
+- `npm run zova`
+
+Do not assume a module lives only in one path family until the actual repo layout has been inspected.
+
+## Step 3: Keep the normal execution order source-first
+
+Point the user or the main workflow to this order:
+
+1. remove backend source if in scope
+2. remove frontend source if in scope
+3. remove direct workspace dependency references
+4. run the repo-owned regeneration flow
+5. verify no references remain
+
+Important rule:
+
+- do not start by hand-editing generated caches or type surfaces while the real source and dependency references still exist
+
+Use the playbook for the full operational sequence and representative commands.
+
+## Step 4: Use generated-runtime cleanup only as a recovery branch
+
+When a module has already been removed from source and direct dependency references, but stale generated types or runtime entries still remain, treat generated runtime directories as disposable working state rather than source-of-truth files.
+
+Primary recovery targets for this workflow are:
+
+- `vona/.vona`
+- `zova/.zova`
+
+These directories are auto-generated by the Vona and Zova CLI flows and may survive when a service or build process does not stop cleanly.
+
+This is a recovery branch, not the default first step.
+
+After cleanup, rerun the normal build/deps/typecheck flow from the playbook.
+
+## Step 5: Finish with branch-aware verification
+
+Use the verification path that matches the branch:
+
+- backend-only → backend deps/typecheck/tests as needed
+- frontend-only → relevant Zova build/deps/typecheck path
+- fullstack → fullstack regeneration order plus typecheck and targeted tests
+
+Verification should prove:
+
+- no direct workspace dependency entries remain
+- no stale generated registrations remain
+- no typecheck failures still point at the removed module
+- no important runtime or test surfaces still import the removed module
+
+## Step 6: Treat docs cleanup as a separate scope decision
+
+Do not assume module deletion automatically means public docs cleanup.
+
+Ask or confirm whether the task is:
+
+- code/runtime removal only
+- code/runtime removal plus docs/examples scrub
+
+If docs cleanup is in scope, update `cabloy-docs/` separately from the runtime cleanup and keep maintainer rationale in `.docs-internal/`.
+
+## Response pattern
+
+When using this skill, structure the response around these points when helpful:
+
+1. detected edition
+2. detected removal scope
+3. real module surfaces involved
+4. recommended cleanup/regeneration branch
+5. stale-generated-runtime recovery branch if needed
+6. verification steps
+
+Keep the response practical. The value of this skill is to choose the right removal branch quickly and keep generated working state in the correct role.

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

@@ -0,0 +1,274 @@
+---
+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.
+
+Important serialization reminder:
+
+- if the returned field behavior depends on `v.serializerTransform(...)`, `v.serializerExclude()`, `v.serializerReplace(...)`, `v.serializerGetter(...)`, or `v.serializerCustom(...)`, do not assume those transforms run by default
+- for performance reasons, Vona response serialization is opt-in per API action
+- verify that the target controller action explicitly uses `@Core.serializer()` before concluding that serializer metadata is broken
+
+## 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
+- when returned-field masking or exclusion uses `v.serializer*`, verify the action-level `@Core.serializer()` path with an API test, not only static field metadata inspection
+- 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.