cabloy 5.1.60 → 5.1.61

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-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

@@ -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

package/.claude/skills/cabloy-zova-source-reading/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: cabloy-zova-source-reading
+description: Use this skill when the user wants to read, trace, or explain Zova frontend source code rather than scaffold new code: where a page/component/model/behavior/SSR flow is implemented, how a runtime path works internally, why a plain controller field is reactive, how Zova differs from generic Vue 3 habits, or which files to read first. Trigger for requests about Zova source reading, runtime tracing, Vue-vs-Zova explanation, controller/bean/IoC mental models, or the Zova-native way to understand frontend behavior. Do not use it for normal frontend scaffolding or backend/frontend contract regeneration.
+---
+
+# Cabloy Zova Source Reading
+
+Use this skill when the task is to understand, explain, or trace Zova frontend behavior in source code.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. classify whether the user needs a source-entry map, a runtime-flow trace, or a Vue-vs-Zova explanation
+3. start from Zova-native public docs before diving into framework source
+4. explain Zova architecture in its own terms before translating it into Vue analogies
+5. separate source-confirmed runtime behavior from interpretive comparison
+6. finish with verification guidance that matches the analysis scope
+
+## Step 1: Detect the active edition
+
+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 the repo scripts and ask before making edition-specific frontend assumptions
+
+This matters most when the analysis becomes UI-sensitive, SSR-site-sensitive, flavor-sensitive, or module-set-sensitive.
+
+## Step 2: Classify the analysis mode
+
+Before reading files deeply, decide which kind of question the user is really asking.
+
+### Mode A: source-location mode
+
+Use this mode when the user is asking questions like:
+
+- where should I start reading?
+- which files are relevant?
+- what order should I read the source in?
+- where is this implemented in Zova?
+
+### Mode B: runtime-flow mode
+
+Use this mode when the user is asking questions like:
+
+- how does this work internally?
+- why is this field reactive?
+- where does `$computed` / `$params` / `$query` come from?
+- how does page/controller/component render enter the runtime?
+
+### Mode C: Vue-vs-Zova comparison mode
+
+Use this mode when the user is asking questions like:
+
+- how should I understand this relative to Vue 3?
+- is this just Vue with classes?
+- what is the Zova way instead of the generic Vue way?
+- how do controller / bean / model / render roles map to Vue concepts?
+
+If a request spans more than one mode, answer in this order:
+
+1. source-location mode
+2. runtime-flow mode
+3. Vue-vs-Zova comparison mode
+
+That order reduces the risk of drifting into premature analogy before the source path is understood.
+
+## Step 3: Start from public Zova docs first
+
+Do not begin by forcing the problem into generic Vue terminology.
+
+Start from the public frontend reading docs in `cabloy-docs/frontend/`.
+
+### Primary reading surfaces
+
+- `cabloy-docs/frontend/reading-zova-for-vue-developers.md`
+- `cabloy-docs/frontend/zova-vs-vue3-comparison.md`
+- `cabloy-docs/frontend/zova-reactivity-under-the-hood.md`
+- `cabloy-docs/frontend/zova-source-reading-map.md`
+
+For compact procedural summaries inside the skill bundle, also use:
+
+- `references/analysis-modes.md`
+- `references/core-reading-paths.md`
+
+### Core architecture surfaces
+
+Use these when the question needs broader architectural context:
+
+- `cabloy-docs/frontend/introduction.md`
+- `cabloy-docs/frontend/foundation.md`
+- `cabloy-docs/frontend/design-principles.md`
+- `cabloy-docs/frontend/ioc-and-beans.md`
+- `cabloy-docs/frontend/page-guide.md`
+- `cabloy-docs/frontend/component-guide.md`
+- `cabloy-docs/frontend/model-architecture.md`
+- `cabloy-docs/frontend/page-route-guide.md`
+- `cabloy-docs/frontend/behavior-guide.md`
+- `cabloy-docs/frontend/ssr-architecture-overview.md`
+
+## Step 4: Choose the shortest correct source-reading path
+
+After reading the public docs, choose the smallest source path that answers the question.
+
+Use these bundled references to keep the workflow compact:
+
+- `references/analysis-modes.md`
+- `references/core-reading-paths.md`
+
+Use the public `cabloy-docs/frontend/zova-source-reading-map.md` as the fuller explanation layer, but use the bundled references first when they are enough for the current task.
+
+## Step 5: Explain Zova-native meaning first
+
+When answering, explain the Zova role first, then add Vue analogies only if they help.
+
+### Required answer posture
+
+1. identify the Zova-native role first
+   - page controller
+   - component controller
+   - render bean
+   - style bean
+   - model bean
+   - service bean
+   - behavior bean
+   - route/SSR integration layer
+
+2. explain the source-confirmed runtime path second
+
+3. only then offer Vue analogies as approximate translations
+
+Do **not** lead with statements like:
+
+- "this is basically just Vue setup with classes"
+- "this should really be a normal Vue composable"
+- "the right end state is probably `ref.value`"
+
+Those translations can erase the actual Zova architecture.
+
+For component-wrapper questions specifically, remember that `controllerRef` exposes the controller instance, not a generic DOM ref, and should not be treated as a generic Vue component-ref substitute without checking the current wrapper/controller source path.
+
+## Step 6: Distinguish source-confirmed behavior from interpretive comparison
+
+Always make the boundary explicit.
+
+### Source-confirmed behavior
+
+This includes claims you can support directly from current source files, such as:
+
+- where a controller is created
+- where a bean becomes reactive
+- where route state is refreshed
+- where render is redirected
+- which helper wraps which Vue API
+
+### Interpretive comparison
+
+This includes claims such as:
+
+- why Zova feels more object-oriented than Vue
+- how Zova growth paths differ from typical Vue growth paths
+- which analogy is the closest Vue mental model
+
+These can be useful, but they should be labeled as interpretation rather than current-source fact.
+
+## Step 7: Stay inside the right workflow boundary
+
+Use this skill for explanation and source reading.
+
+Do **not** use it as the primary workflow when the real task is:
+
+- creating or refactoring frontend structures → prefer `cabloy-frontend-scaffold`
+- diagnosing backend/frontend contract drift → prefer `cabloy-contract-loop`
+- choosing whether the work belongs to backend, frontend, fullstack, docs, or AI guidance → prefer `cabloy-workflow`
+
+## Step 8: Verification guidance
+
+Always finish with a verification path that matches the analysis task.
+
+### For source-reading answers
+
+Verify:
+
+- the cited file paths exist
+- the described runtime path is actually visible in current source
+- the answer does not contradict the public frontend docs
+
+### For Vue-vs-Zova explanation answers
+
+Verify:
+
+- the Zova-native explanation comes first
+- Vue analogies are marked as approximate, not authoritative
+- no claim quietly rewrites Zova back into generic Vue habits
+
+### For edition-sensitive frontend analysis
+
+Verify:
+
+- the active edition marker was considered
+- Basic-only or Start-only UI assumptions were not silently generalized
+- SSR, theme, and flavor-sensitive statements match the active edition context
+
+## Response pattern
+
+When helpful, structure the response around these points:
+
+1. detected edition
+2. analysis mode
+3. public docs to read first
+4. source path to inspect next
+5. Zova-native explanation
+6. optional Vue analogy
+7. verification notes or caveats
+
+Keep the response practical. The value of this skill is to help AI and users read Zova source accurately and in the right architectural order, not to flatten Zova into generic Vue prose.

package/.claude/skills/cabloy-zova-source-reading/references/analysis-modes.md

@@ -0,0 +1,91 @@
+# Analysis Modes
+
+Use this reference to choose the shortest correct analysis posture before reading Zova source deeply.
+
+## Mode A: source-location mode
+
+Use this mode when the user is mainly asking:
+
+- where should I start reading?
+- which files matter?
+- what order should I read the source in?
+- where is this implemented?
+
+### Workflow
+
+1. detect the active edition if UI-sensitive assumptions might matter
+2. start from the public frontend docs first
+3. pick the smallest matching thread from `cabloy-docs/frontend/zova-source-reading-map.md`
+4. cite the initial source files in the recommended reading order
+5. stop before tracing deeper runtime layers unless the user also wants runtime-flow analysis
+
+### Output emphasis
+
+- reading order
+- key file paths
+- why those files are the right starting points
+
+## Mode B: runtime-flow mode
+
+Use this mode when the user is mainly asking:
+
+- how does this work internally?
+- why is this reactive?
+- where does this controller/page/component behavior come from?
+- how does render, route state, or lifecycle enter the runtime?
+
+### Workflow
+
+1. read the public Zova-native explanation docs first:
+   - `reading-zova-for-vue-developers.md`
+   - `zova-reactivity-under-the-hood.md`
+2. identify the concrete thread:
+   - page controller
+   - component controller
+   - route/state
+   - model
+   - behavior
+   - SSR
+3. trace the smallest current-source path that confirms the runtime behavior
+4. distinguish source-confirmed behavior from interpretation
+5. only after the Zova-native explanation is clear, add Vue analogy if helpful
+
+### Output emphasis
+
+- entrypoint
+- intermediate runtime files
+- what triggers the behavior
+- what is source-confirmed
+
+## Mode C: Vue-vs-Zova comparison mode
+
+Use this mode when the user is mainly asking:
+
+- how should I understand this relative to Vue 3?
+- is this just Vue with a different syntax?
+- what is the Zova way here?
+
+### Workflow
+
+1. explain the Zova-native architectural role first
+2. identify which public Zova doc best defines that role
+3. if needed, trace one representative source path to confirm the runtime grounding
+4. only then provide Vue analogies as approximate translations
+5. explicitly avoid flattening Zova back into generic Vue habits
+
+### Output emphasis
+
+- Zova-native role
+- closest Vue analogy
+- what is genuinely shared underneath
+- what changes at the authoring-model level
+
+## Combined requests
+
+If a request spans multiple modes, answer in this order:
+
+1. source-location mode
+2. runtime-flow mode
+3. Vue-vs-Zova comparison mode
+
+This keeps the explanation anchored in the real source path before analogy work begins.