cabloy 5.1.60 → 5.1.62

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

@@ -2,6 +2,8 @@
 
 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`
@@ -39,6 +41,8 @@ Use this shape instead:
 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)`

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

@@ -1,31 +1,47 @@
 # 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
-
-- regeneration commands completed successfully
-- generated SDK/schema outputs are updated
-- API/model/page/component consumers still typecheck
+## Reverse chain verification
+
+- 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
 
@@ -33,6 +49,8 @@ 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`.

package/.claude/skills/cabloy-domain-planning/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: cabloy-domain-planning
+description: Use this skill whenever the user wants to plan a new business domain in this Cabloy repo, such as CRM, OA, training, ERP, or a similar long-lived domain. Trigger when the request is about deciding suite-first structure, proposing or validating providerId, suite, and module names, comparing naming options, confirming names before scaffolding, or keeping a custom naming path open. Prefer it before backend or frontend scaffolding when the main question is domain naming and structure rather than immediate file generation.
+---
+
+# Cabloy Domain Planning
+
+Use this skill when the user is still deciding how to name and structure a new business domain.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. classify the request as domain planning rather than immediate scaffolding
+3. default to suite-first planning for real business domains
+4. propose valid `providerId`, suite, and module names before any generation happens
+5. require explicit confirmation before handing off to scaffold commands
+6. always keep a custom naming path available for the user
+7. finish with the CLI-first next step and matching verification guidance
+
+## Step 1: Detect edition first
+
+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
+
+This matters most when examples, frontend flavors, or suite/module availability may differ between editions.
+
+## Step 2: Confirm that this is a planning request
+
+Use this skill when the user is asking things such as:
+
+- how to plan a new CRM, OA, training, ERP, or similar business area
+- whether the work should start as a suite or only a module
+- how to choose `providerId`, `suiteName`, or first module names
+- whether a proposed name is valid
+- which naming option should be preferred before scaffolding
+
+Do not use this skill once naming is already confirmed and the request is clearly about backend or frontend scaffolding. In that case, route to the appropriate scaffold skill.
+
+## Step 3: Default to suite-first planning
+
+For real business work, prefer the suite-first path described in:
+
+- `cabloy-docs/fullstack/suites-and-modules.md`
+
+Use this practical rule:
+
+- prefer a **suite** for the business domain boundary
+- prefer **modules** for the capabilities inside that domain
+- treat a standalone module as the exception for very small, disposable, or tutorial-only work
+
+Do not jump into `:create:module` first when the real question is still the domain boundary.
+
+## Step 4: Collect or infer the planning inputs
+
+Before proposing names, determine these inputs:
+
+1. the business domain term
+   - examples: crm, oa, training
+2. whether the user already has a required namespace or provider prefix
+   - examples: `demo`, `biz`, `mycorp`
+3. whether the work is backend-only, frontend-only, or fullstack
+4. whether the user wants a conservative functional naming style or a custom/branded naming style
+
+If the user already provides names, validate them instead of replacing them silently.
+
+## Step 5: Validate the naming rules
+
+Reuse the durable naming rules from:
+
+- `cabloy-docs/fullstack/suites-and-modules.md`
+- `cabloy-docs/frontend/modules-and-suites.md`
+
+### Suite short name rule
+
+A suite short name follows:
+
+```text
+{providerId}-{suiteName}
+```
+
+In this repository:
+
+- `suiteName` must use lowercase English letters only
+- `suiteName` must not contain another `-`
+
+So a name such as `crm-core` is not valid as the `suiteName` segment.
+
+When a proposed name is invalid:
+
+- explain whether the invalid part is `providerId`, `suiteName`, or the combined short name
+- do not collapse those layers into one vague error
+- provide the nearest valid alternatives when possible
+
+For example:
+
+- `crm-core` is invalid as a `suiteName`
+- `crm-core` can still be a valid suite short name if it is interpreted as:
+  - `providerId = crm`
+  - `suiteName = core`
+
+### Module planning rule
+
+Module names should represent capability ownership inside the suite.
+
+Prefer names that:
+
+- map cleanly to a business capability
+- remain natural when they become resource owners, controller names, API paths, or menu/page anchors
+- avoid technical placeholder words such as `base`, `core`, or `common` unless the module is truly a shared technical layer
+
+If more detail is needed, prefer expressing it in the module name rather than by making the suite name longer.
+
+## Step 6: Propose names in a compact planning table
+
+When the user has not finalized naming, propose:
+
+1. one **recommended** option
+2. one or two **alternatives** if there is a meaningful trade-off
+3. one **custom naming** path
+
+The proposal should be compact and practical. Include:
+
+- `providerId`
+- suite short name
+- Vona suite full name
+- Zova suite full name
+- 3-6 likely first module names
+- which module should be scaffolded first
+
+Use examples such as:
+
+- suite: `demo-training`
+- modules: `training-student`, `training-course`, `training-record`
+
+When helpful, explain why the recommendation is better than obvious alternatives.
+
+## Step 7: Require confirmation before scaffolding
+
+Before suggesting any scaffold execution, explicitly confirm:
+
+- `providerId`
+- suite short name
+- first module names
+- whether the user wants backend-only, frontend-only, or fullstack scaffolding
+
+Do not treat silence as confirmation.
+
+Always leave a custom path available, for example:
+
+- “If you want a different `providerId`, suite short name, or first module set, give the custom names and I will validate them against the repo rules.”
+
+## Step 8: Hand off to CLI-first scaffolding only after confirmation
+
+Once naming is confirmed, route to the real generators rather than hand-authoring structure.
+
+Typical commands are:
+
+```bash
+npm run vona :create:suite <suiteShortName>
+npm run zova :create:suite <suiteShortName>
+npm run vona :create:module <moduleName> -- --suite=<suiteShortName>
+npm run zova :create:module <moduleName> -- --suite=<suiteShortName>
+```
+
+Then route to:
+
+- `cabloy-backend-scaffold` for backend generation and follow-up
+- `cabloy-frontend-scaffold` for frontend generation and follow-up
+- `cabloy-workflow` if the task becomes a broader cross-stack routing problem
+
+## Step 9: Verification
+
+Always finish with a verification path that matches the scope.
+
+Before generation, verify:
+
+- the proposed suite name follows the naming rule
+- the proposed module names are natural business capability owners
+- the command family still exists through `npm run vona` / `npm run zova`
+
+After generation, verify with the narrowest useful checks first:
+
+- `npm run vona :`
+- `npm run zova :`
+- `npm run deps:vona`
+- `npm run deps:zova`
+- `npm run tsc`
+
+For docs or AI-asset changes that accompany this workflow, also verify that referenced public docs and skill descriptions still tell a consistent story.
+
+## Response pattern
+
+When helpful, structure the response around these points:
+
+1. detected edition
+2. suite-first recommendation
+3. recommended naming table
+4. alternatives and trade-offs
+5. custom naming path
+6. confirmation gate before scaffolding
+7. next CLI commands after confirmation
+8. verification steps
+
+Keep the response practical. The value of this skill is to turn vague new-domain requests into a confirmed, valid, and CLI-ready naming plan before any scaffolding starts.

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

@@ -36,6 +36,8 @@ Then classify the request:
 
 Default to frontend-first. Only escalate mentally to a broader fullstack workflow when the frontend task obviously crosses the contract boundary.
 
+If the user is still deciding a new business-domain boundary or suite/module naming, use the root `cabloy-domain-planning` skill before scaffolding.
+
 If the task is really a broad cross-stack workflow, consider whether the root `cabloy-workflow` skill is the better primary router.
 
 ## Step 2: Start from Zova CLI and repo entrypoints
@@ -134,6 +136,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 +185,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

@@ -164,6 +164,12 @@ Then check whether DTOs are already inferred through patterns such as:
 
 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
@@ -251,6 +257,7 @@ Typical checks include:
 - `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