cabloy 5.1.59 → 5.1.61

package/cabloy-docs/ai/future-skill-roadmap.md

@@ -10,18 +10,21 @@ A roadmap helps convert that documented knowledge into a focused set of high-val
 
 ## What already exists
 
-Current root skill:
+Current root skills include:
 
 - `cabloy-workflow`
+- `cabloy-contract-loop`
+- `cabloy-resource-field-update`
+- `cabloy-module-removal`
 
-Its current role is broad workflow selection:
+Their current roles are:
 
-- detect Basic vs Start
-- classify backend/frontend/fullstack/docs work
-- prefer CLI-first behavior
-- suggest verification
+- `cabloy-workflow` → broad workflow selection, edition detection, CLI-first routing, and verification framing
+- `cabloy-contract-loop` → backend/frontend contract regeneration, reverse-chain handling, and drift diagnosis
+- `cabloy-resource-field-update` → existing backend resource-field changes with `fileVersion` and renderer-aware follow-up
+- `cabloy-module-removal` → backend/frontend/fullstack module deletion order, generated-runtime cleanup, and verification
 
-This is a strong foundation skill, but it is intentionally general.
+This is now a stronger foundation skill set, but it still leaves several useful workflow families for future specialization.
 
 ## Recommended next skill families
 
@@ -67,7 +70,22 @@ Primary dependencies:
 - Zova OpenAPI SDK and server-data docs
 - fullstack collaboration docs
 
-### 4. Metadata refresh skill
+### 4. Resource field update skill
+
+Purpose:
+
+- handle updates to fields on existing backend resources
+- force the right `fileVersion` decision for new persisted fields
+- branch correctly between shared renderer reuse and custom renderer demo follow-up
+- verify entity, locale, migration, test, metadata, build, and dependency-sync implications
+
+Primary dependencies:
+
+- Vona entity / migration / DTO workflow knowledge
+- Zova metadata/build flows when renderer follow-up is involved
+- the backend resource field workflow note in `.docs-internal/`
+
+### 5. Metadata refresh skill
 
 Purpose:
 
@@ -81,7 +99,7 @@ Primary dependencies:
 - CLI-to-skill mapping
 - edition detection docs
 
-### 5. Distributed backend workflow skill
+### 6. Distributed backend workflow skill
 
 Purpose:
 

package/cabloy-docs/ai/introduction.md

@@ -75,6 +75,7 @@ Use this path when the task is about implementing or reviewing Cabloy code with
 - [Playbook: Backend Module](/ai/playbook-backend-module)
 - [Playbook: Frontend Page](/ai/playbook-frontend-page)
 - [Playbook: Contract Regeneration](/ai/playbook-contract-regeneration)
+- [Playbook: Module Removal](/ai/playbook-module-removal)
 - [Playbook: Metadata Refresh](/ai/playbook-metadata-refresh)
 
 ### Verification and roadmap path

package/cabloy-docs/ai/playbook-backend-module.md

@@ -66,6 +66,12 @@ Depending on the feature, extend the generated code with the right framework-lev
 - migration and changes
 - field indexes
 
+When refining entity or DTO fields that use `@Api.field(...)`, apply this framework-specific guardrail:
+
+- if you include an explicit zod schema such as `z.number().int().min(1)`, place it as the **last argument**
+- keep helper metadata such as `v.xxx(...)` and `ZovaRender.xxx(...)` before the zod schema
+- otherwise helpers written after the zod schema may stop taking effect
+
 Relevant docs:
 
 - [Controller Guide](/backend/controller-guide)

package/cabloy-docs/ai/playbook-module-removal.md

@@ -0,0 +1,164 @@
+# Playbook: Remove a Cabloy Module
+
+This playbook turns Cabloy module deletion into a repeatable AI-friendly workflow.
+
+## When to use this playbook
+
+Use this playbook when the goal is to remove an existing module from the Cabloy monorepo.
+
+Typical triggers include:
+
+- delete a demo module
+- retire a backend module
+- remove a frontend module
+- remove a fullstack module that exists in both Vona and Zova
+- clean up stale generated runtime or type residues after a module was removed
+
+## Step 1: Detect the repo and scope
+
+Before deleting anything:
+
+1. detect whether the active repo is Cabloy Basic or Cabloy Start
+2. confirm whether the module is backend-only, frontend-only, or fullstack
+3. inspect the root `package.json`
+4. inspect `npm run vona` and `npm run zova`
+
+This avoids deleting the wrong surfaces or using the wrong edition-specific assumptions.
+
+## Step 2: Inventory the real module surfaces
+
+Inspect the real source and direct dependency surfaces first.
+
+Typical locations include:
+
+- `vona/src/module/<module>` or suite-based backend module roots
+- `zova/src/module/<module>` or suite-based frontend module roots
+- `vona/package.json`
+- `zova/package.json`
+- generated registries and lockfiles
+- tests that still target the module
+
+If the user asked for a public scrub, also inspect `cabloy-docs/`. Otherwise, treat docs cleanup as a separate scope decision.
+
+## Step 3: Remove source and direct references first
+
+Start by removing the real source and direct workspace package references.
+
+Typical order:
+
+1. remove backend module source if in scope
+2. remove frontend module source if in scope
+3. remove direct workspace dependency entries from the relevant `package.json` files
+4. refresh or clean generated registrations only after source removal
+
+Do not start by hand-editing generated caches while the real module source or package references still exist.
+
+## Step 4: Regenerate with the repo-owned workflow
+
+After source cleanup, use the existing root scripts to refresh generated outputs.
+
+Representative root commands in Cabloy Basic include:
+
+```bash
+npm run build:zova:admin
+npm run deps:vona
+npm run deps:zova
+npm run tsc
+npm run test
+```
+
+### Fullstack default sequence
+
+When the module exists on both the Vona and Zova sides, the usual sequence is:
+
+1. `npm run build:zova:admin`
+2. `npm run deps:vona`
+3. `npm run deps:zova`
+4. `npm run tsc`
+
+This keeps the Zova Admin JS bundle and rest output aligned before Vona consumes downstream artifacts.
+
+### Narrower branches
+
+For backend-only removal, prefer the narrowest meaningful verification first:
+
+- `npm run deps:vona`
+- `npm run tsc`
+- `npm run test` when runtime/test coupling is likely
+
+For frontend-only removal, use the relevant Zova build/deps path first, then typecheck.
+
+## Step 5: Clean generated runtime directories when residues remain stale
+
+If stale module types or runtime entries still remain after the normal cleanup and regeneration flow, treat generated runtime directories as disposable working state.
+
+In particular, the primary recovery targets for this workflow are:
+
+- `vona/.vona`
+- `zova/.zova`
+
+These are not necessarily the only generated working directories in the repo, but they are the main stale-runtime targets for normal module-removal recovery.
+
+Why this is safe:
+
+- these directories are generated by the Vona and Zova CLI flows
+- they are ignored by the repo because they are not source-of-truth files
+- they may survive when a service or build process does not stop cleanly
+
+After deleting them, rerun the normal regeneration flow and typecheck again.
+
+## Step 6: Verify that the module is really gone
+
+Search for remaining references to:
+
+- the module relative name
+- the backend workspace package name
+- the frontend workspace package name
+- route or resource names if applicable
+
+Then verify with the narrowest meaningful commands first, followed by broader checks when needed.
+
+Typical verification commands:
+
+```bash
+npm run build:zova:admin
+npm run deps:vona
+npm run deps:zova
+npm run tsc
+npm run test
+```
+
+The expected result is:
+
+- no direct workspace dependency entries remain
+- no generated registry still points at the removed module
+- no stale typecheck failures still reference the module
+- no important runtime or test surfaces still import it
+
+## Step 7: Treat docs cleanup as an explicit second scope
+
+Removing code/runtime surfaces does not automatically mean public docs should be rewritten.
+
+Make this an explicit scope decision:
+
+- code/runtime removal only
+- code/runtime removal plus docs/examples scrub
+
+If docs cleanup is in scope, update `cabloy-docs/` as a separate pass after runtime cleanup is stable.
+
+## AI rule of thumb
+
+A good Cabloy module-removal workflow is usually:
+
+1. detect edition and scope
+2. inventory real module surfaces
+3. remove source and direct references
+4. regenerate with repo entrypoints
+5. clean generated runtime dirs only when stale residues remain
+6. verify the module is really gone
+
+Not:
+
+1. delete a few generated files first
+2. guess which paths matter
+3. leave workspace dependencies or generated registrations stale

package/cabloy-docs/ai/skills.md

@@ -35,3 +35,14 @@ A strong Cabloy skill usually includes:
 When a skill needs to apply an architectural rule such as backend class placement, prefer a branching decision tree that points back to durable docs instead of embedding the full architecture rationale inside the skill itself.
 
 For edition-aware skills, use [Edition Detection for AI Workflows](/ai/edition-detection) and [Edition Consistency Checklist](/ai/edition-consistency-checklist) as the durable review surfaces before expanding edition-specific branches.
+
+## Example workflow skills in this repo
+
+Current examples include:
+
+- `cabloy-workflow` for choosing the correct Cabloy work path before implementation
+- `cabloy-contract-loop` for backend/frontend contract regeneration and drift diagnosis
+- `cabloy-resource-field-update` for updating an existing backend resource field thread
+- `cabloy-module-removal` for removing a backend, frontend, or fullstack module cleanly, including generated-runtime cleanup, stale-residue recovery, and verification
+
+The module-removal workflow is a good example of why skills belong in `.claude/skills/` instead of `CLAUDE.md`: the task needs branching, cleanup order, recovery guidance for generated runtime directories such as `vona/.vona` and `zova/.zova`, and a verification checklist that would be too large for a short repo-wide rule.

package/cabloy-docs/backend/bean-scene-authoring.md

@@ -0,0 +1,350 @@
+# Backend Bean Scene Authoring
+
+This guide explains the **advanced** Vona workflow for creating a **new backend bean scene**.
+
+This is not the same as creating one more bean inside an existing scene such as `service`, `model`, or `dto`.
+
+For ordinary bean creation inside an existing scene, use the existing CLI workflow documented in [Backend CLI](/backend/cli) and the scene-specific guides. This page is for framework extension work where you need to define a new scene contract.
+
+## When you need this guide
+
+Use this guide when you need to extend the backend bean system itself, for example:
+
+- define a new decorator such as `@Something()`
+- teach `:create:bean` how to scaffold that scene
+- add new scene-level metadata behavior
+- decide whether the scene should appear in module scope resources
+- decide whether the scene should contribute to the general bean registry
+
+If you only need a new service or model bean, you do **not** need this page.
+
+## Mental model
+
+For most scene-based backend beans, the scene is the middle layer inside the bean identity:
+
+- bean identifier: `{module}.{scene}.{bean}`
+- onion name: `{module}:{bean}`
+- scene name: the operational family such as `service`, `model`, `entity`, `dto`, or `startup`
+
+A practical exception is the built-in global `bean` scene, whose generated global shorthand entries use the plain bean name rather than the full `module.scene.bean` pattern.
+
+The scene is not only a naming convention. It controls several framework behaviors:
+
+- which decorator marks the class
+- where the CLI places generated files
+- whether the scene contributes to scope resources
+- whether the scene contributes to general bean typing
+- whether scene-specific metadata generation runs
+
+## The smallest built-in pattern
+
+The simplest built-in scene is a thin decorator wrapper over `createBeanDecorator(...)`.
+
+Representative pattern:
+
+```typescript
+import { createBeanDecorator } from 'vona';
+
+export function Service(): ClassDecorator {
+  return createBeanDecorator('service');
+}
+```
+
+That pattern is the first authoring surface of a new scene: give the scene a stable framework name.
+
+Some scenes use richer decorator forms with options or scene-specific post-registration behavior. A good example is `Model()`, which is implemented outside the base bean module and passes scene options through the decorator contract.
+
+## The backend authoring surfaces
+
+A new backend bean scene usually touches five surfaces.
+
+### 1. Decorator surface
+
+Define the scene decorator and export it from the owning module.
+
+Representative built-in patterns include:
+
+```typescript
+export function Bean(): ClassDecorator {
+  return createBeanDecorator('bean');
+}
+
+export function Scope(): ClassDecorator {
+  return createBeanDecorator('scope');
+}
+```
+
+A scene-specific decorator can live in the base bean module or in a more specialized module. For example, `Model()` is implemented in the ORM module rather than the base bean module.
+
+### 2. Scene typing surface
+
+Add the scene to the declaration-merging type registry.
+
+Representative pattern:
+
+```typescript
+declare module 'vona' {
+  export interface IBeanSceneRecord {
+    service: never;
+  }
+}
+```
+
+This tells the framework and generated typings that the scene exists.
+
+Some scenes also extend a scene-specific record in their owning module. For example, the built-in service scene contributes to `IServiceRecord` and then maps that into the broader onion surface.
+
+### 3. Onion metadata surface
+
+Register the scene in the owning module `package.json` under `vonaModule.onions`.
+
+Representative built-in pattern:
+
+```json
+{
+  "service": {
+    "sceneIsolate": true,
+    "scopeResource": true,
+    "beanGeneral": true,
+    "optionsGlobalInterfaceFrom": "vona-module-a-bean",
+    "boilerplate": "service/boilerplate"
+  }
+}
+```
+
+This metadata is one of the main contracts for `:create:bean` and metadata generation.
+
+### 4. CLI boilerplate surface
+
+Provide the scaffold template used by `npm run vona :create:bean sceneName beanName -- --module=...`.
+
+Representative built-in boilerplate:
+
+```typescript
+import { BeanBase } from 'vona';
+import { Bean } from 'vona-module-a-bean';
+
+@Bean()
+export class Bean<%=argv.beanNameCapitalize%> extends BeanBase {}
+```
+
+The important point is not the exact class body. The important point is that the scene owns a template and the CLI resolves it through the onion metadata.
+
+### 5. Metadata generation surface
+
+Add custom metadata generation only when the scene needs output beyond the default scene scan.
+
+Representative built-in pattern:
+
+```typescript
+export default async function (options) {
+  const { sceneName, globFiles } = options;
+  // ...build declaration-merging content...
+}
+```
+
+For example, the built-in `bean` scene adds `IBeanRecordGlobal` output through a custom metadata generator.
+
+## How `vonaModule.onions` drives scene behavior
+
+When adding a scene, the most important design step is deciding the scene flags.
+
+### `sceneIsolate`
+
+Use this when the scene should live in its own top-level folder rather than being mixed into `src/bean`.
+
+Representative example:
+
+- `service` uses `sceneIsolate: true`
+- generated files live under `src/service/`
+
+A non-isolated scene normally stays in `src/bean` using the `{scene}.{bean}` naming pattern.
+
+### `scopeResource`
+
+Use this when the scene should appear as a module scope resource such as `this.scope.service.student`.
+
+If this flag is enabled, metadata generation will create module-scope typing such as:
+
+```typescript
+export interface IModuleService {
+  student: ServiceStudent;
+}
+```
+
+Scenes without scope-resource behavior should not set this flag just for convenience.
+
+### `beanGeneral`
+
+Use this when the scene should contribute to the general bean registry.
+
+Representative generated output:
+
+```typescript
+declare module 'vona' {
+  export interface IBeanRecordGeneral {
+    'demo-student.service.student': ServiceStudent;
+  }
+}
+```
+
+This matters for container-oriented lookup and the broader typed bean surface.
+
+### `boilerplate`
+
+Use this to tell the CLI which template should be used when a bean of the scene is created.
+
+### Multiple boilerplate variants
+
+A backend scene can expose more than one named template.
+
+A practical rule is:
+
+- `boilerplate` provides the default template
+- `--boilerplate=web` maps to `boilerplateWeb`
+- more generally, `--boilerplate=name` maps to `boilerplateName`
+
+This is useful when one scene needs multiple scaffold shapes for distinct runtime targets or authoring paths.
+
+Representative built-in examples include `ssrMenu` and `ssrMenuGroup`, which expose both the default template and a `web` variant in module metadata.
+
+### `metadataCustom`
+
+Use this only when the scene needs additional generated output that is not covered by the standard metadata passes.
+
+A good rule is:
+
+- start without custom metadata if the default scene wiring is enough
+- add `metadataCustom` only when the scene has a real extra output contract
+
+## Authoring flow for a new backend scene
+
+A practical Vona scene-authoring workflow is:
+
+1. choose the owning module for the scene
+2. add the scene decorator
+3. export it from the module `src/lib/index.ts`
+4. add the scene declaration-merging type and export it from `src/types/index.ts`
+5. add the scene under `vonaModule.onions`
+6. create the scene boilerplate for `:create:bean`
+7. add custom metadata generation if the scene needs extra emitted typings
+8. run bean creation in a representative module
+9. inspect the generated `.metadata/index.ts` output
+10. only then write any additional scene-specific docs or business examples
+
+## What generated output should prove
+
+A new scene is usually correct only if the generated metadata proves the intended contract.
+
+Depending on scene flags, inspect for output such as:
+
+- declaration merging for the scene itself
+- `IBeanRecordGeneral`
+- module scope-resource interfaces such as `IModuleService`
+- bean instance helpers such as `$beanFullName` and `$onionName`
+- scope-class integration for module resource access
+
+Representative generated service output includes:
+
+```typescript
+export interface ServiceStudent {
+  get $beanFullName(): 'demo-student.service.student';
+  get $onionName(): 'demo-student:student';
+}
+```
+
+and:
+
+```typescript
+export interface IModuleService {
+  student: ServiceStudent;
+}
+```
+
+If the generated metadata does not match the scene design, fix the scene contract first rather than patching the generated output manually.
+
+## A useful split: adding a scene vs adding a bean
+
+Keep these two tasks separate.
+
+### Add a bean inside an existing scene
+
+Example:
+
+```bash
+npm run vona :create:bean service student -- --module=demo-student
+```
+
+This uses an already-defined scene.
+
+### Add a new scene
+
+This requires framework extension work:
+
+- new decorator
+- new scene type registration
+- new onion metadata entry
+- new boilerplate
+- optional metadata generation
+
+That is why this topic belongs in an advanced guide.
+
+## Design rules for new scenes
+
+Before adding a scene, ask these questions.
+
+### Should the scene be isolated?
+
+Choose an isolated scene when the scene deserves its own first-class folder and operational identity, similar to `service`.
+
+Choose a non-isolated scene when the scene is better modeled as a bean-family variant under `src/bean`.
+
+### Should the scene appear in module scope?
+
+Enable scope-resource generation only when the scene should behave like a normal module resource family.
+
+If the scene is mainly metadata, infrastructure glue, or a special registry surface, scope exposure may be the wrong contract.
+
+### Should the scene be part of the general bean registry?
+
+Enable `beanGeneral` only when typed global/general bean lookup is part of the intended developer surface.
+
+### Does the scene need custom metadata?
+
+Do not add custom generation only because it is available. Add it when the scene needs a real emitted surface beyond the default metadata pipeline.
+
+## Relationship to existing guides
+
+Read this guide together with:
+
+- [Backend Foundation](/backend/foundation)
+- [Backend CLI](/backend/cli)
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [Backend Startup Guide](/backend/startup-guide)
+
+Use the basic guides for normal bean creation. Use this page only when extending the scene system itself.
+
+## Verification checklist
+
+When authoring or documenting a new backend scene, verify in this order:
+
+1. confirm the CLI command shape still exists:
+
+   ```bash
+   npm run vona :create:bean --help
+   ```
+
+2. confirm the scene decorator, scene typing, and `vonaModule.onions` entry agree
+3. create a test bean in a representative module
+4. inspect the generated source placement
+5. inspect `src/.metadata/index.ts` in that module
+6. confirm scope resources and general bean output match the design
+7. run the narrowest meaningful type or docs verification for the change
+
+For repo-wide docs verification, also run:
+
+```bash
+npm run docs:build
+```

package/cabloy-docs/backend/cli.md

@@ -122,6 +122,24 @@ A practical bean-scene reading is:
 - `:create:bean sceneName beanName -- --module=...` uses `sceneName` as the operational family slot inside the bean identifier
 - this is why generated bean names later appear in forms such as `module.scene.bean`
 
+## Bean boilerplate variants
+
+Some backend bean scenes expose more than one scaffold template.
+
+In those cases, use `--boilerplate=...` to select a named variant:
+
+```bash
+npm run vona :create:bean ssrMenu menuTest -- --module=demo-student --boilerplate=web
+```
+
+A practical rule is:
+
+- the default scene template comes from the scene metadata `boilerplate`
+- a named variant such as `--boilerplate=web` maps to a metadata key such as `boilerplateWeb`
+- supported variants are scene-defined, so do not assume every scene exposes them
+
+For the current cross-stack lookup table, see [Bean Scene Boilerplate Variants](/reference/bean-scene-boilerplates).
+
 ## Initializer-family examples
 
 Not every backend resource is created through bean scenes.
@@ -131,13 +149,20 @@ Representative initializer commands include:
 ```bash
 npm run vona :init:constant demo-student
 npm run vona :init:types demo-student
+npm run vona :init:lib demo-student
 npm run vona :init:asset static -- --module=demo-student
 ```
 
 A practical distinction is:
 
 - `:create:bean` creates scene-based backend beans
-- `:init:*` commands create module-scope resources such as constants, typings, or asset-resource structure
+- `:init:*` commands create module-scope resources such as constants, typings, helper directories, or asset-resource structure
+
+A practical helper-placement rule is:
+
+- if a backend module needs reusable pure helper functions, initialize `src/lib` with `npm run vona :init:lib demo-student`
+- place those shared helpers under `src/lib` and export shared entrypoints from `src/lib/index.ts`
+- if the logic needs container-managed runtime behavior, do not force it into `src/lib`; re-evaluate `src/service` or another bean scene instead
 
 ## Relationship to modules, suites, and package metadata
 

package/cabloy-docs/backend/dto-guide.md

@@ -73,6 +73,12 @@ class DtoStudentCreate {
 }
 ```
 
+When mixing helper metadata and an explicit zod schema in `@Api.field(...)`, apply the same ordering rule used by entities:
+
+- place `z.xxx(...)` as the **last argument** because it returns the zod schema instance
+- keep helper metadata such as `v.xxx(...)` and `ZovaRender.xxx(...)` before the zod schema
+- otherwise helpers written after the zod schema may stop taking effect
+
 For query-oriented DTOs, another important distinction is optional vs nullable:
 
 - `v.optional()` means the field may be omitted