cabloy 5.1.50 → 5.1.52

package/cabloy-docs/ai/playbook-contract-regeneration.md

@@ -0,0 +1,100 @@
+# Playbook: Update a Backend Contract and Regenerate the Frontend
+
+This playbook documents one of the highest-value fullstack AI workflows in Cabloy.
+
+## When to use this playbook
+
+Use this playbook when a backend API contract changes and the frontend should be brought back into sync.
+
+Typical triggers include:
+
+- DTO field changes
+- controller parameter or response changes
+- validation changes
+- OpenAPI metadata changes
+- relation or DTO inference changes that affect API shape
+
+## Step 1: Update the backend contract at the correct layer
+
+Inspect which backend layer actually owns the change:
+
+- controller
+- dto
+- entity
+- validation rule
+- inferred DTO path
+- OpenAPI configuration
+
+Relevant docs:
+
+- [Validation Guide](/backend/validation-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [DTO Guide](/backend/dto-guide)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+
+## Step 2: Verify the backend contract output
+
+Before touching the frontend, verify that the backend-side contract change is really reflected in the generated OpenAPI output.
+
+That may include:
+
+- rebuilding or running the backend
+- checking Swagger / OpenAPI JSON
+- confirming the contract shape matches intent
+
+## Step 3: Detect the edition and frontend target
+
+Before regenerating frontend artifacts:
+
+1. detect Basic vs Start
+2. verify the relevant frontend flavor
+3. confirm whether the change affects Admin, Web, or both
+
+## Step 4: Regenerate the frontend-side contract artifacts
+
+Use the Zova OpenAPI and REST-generation path rather than manually updating request code first.
+
+Representative commands may include:
+
+```bash
+npm run zova :openapi:generate ...
+cd zova && npm run build:rest:cabloyBasicAdmin
+cd zova && npm run build:rest:cabloyBasicWeb
+```
+
+For Start, use the Start-specific flavor paths from that repo.
+
+## Step 5: Inspect affected frontend layers
+
+After regeneration, inspect which frontend layers need follow-up changes:
+
+- API services
+- generated SDK
+- model-managed data access
+- schema-driven UI
+- page or component assumptions
+
+## Step 6: Verify the end-to-end loop
+
+Use a verification path that checks both sides:
+
+- backend contract correctness
+- regenerated frontend artifacts
+- typecheck/build for the affected frontend edition or flavor
+
+## AI rule of thumb
+
+A good fullstack contract update workflow is usually:
+
+1. change backend contract
+2. verify OpenAPI output
+3. detect edition and target flavor
+4. regenerate frontend contract artifacts
+5. inspect downstream breakage
+6. verify end to end
+
+Not:
+
+1. change backend DTO
+2. hand-edit a few frontend request types
+3. leave the contract loop out of sync

package/cabloy-docs/ai/playbook-frontend-page.md

@@ -0,0 +1,99 @@
+# Playbook: Add a Frontend Page
+
+This playbook turns the Zova frontend docs into a repeatable AI-friendly workflow.
+
+## When to use this playbook
+
+Use this playbook when the goal is to add or extend a frontend page, especially when the work may involve:
+
+- page creation
+- route and params/query setup
+- component integration
+- model or API integration
+- edition-sensitive UI assumptions
+
+## Step 1: Detect the edition first
+
+Before generating or editing anything:
+
+1. check `__CABLOY_BASIC__` or `__CABLOY_START__`
+2. confirm the active frontend flavor assumptions
+3. inspect root `package.json` and `npm run zova`
+
+This matters because frontend examples can differ between Basic and Start.
+
+## Step 2: Use the page generator first
+
+Start from the Zova generator instead of creating the page structure manually.
+
+Representative command:
+
+```bash
+npm run zova :create:page ...
+```
+
+## Step 3: Add page capabilities with refactor commands
+
+If the page needs additional framework features, prefer the dedicated refactor commands.
+
+Representative examples:
+
+```bash
+npm run zova :refactor:pageQuery ...
+npm run zova :refactor:pageParams ...
+```
+
+That is better than manually recreating the framework structure because the refactor commands preserve Zova conventions.
+
+## Step 4: Connect data and components the Zova way
+
+Depending on the page, extend it through the right abstraction layer:
+
+- API service
+- model-managed remote state
+- component wrappers
+- SSR init data
+- navigation guards or route metadata
+
+Relevant docs:
+
+- [Page Guide](/frontend/page-guide)
+- [Page Query Guide](/frontend/page-query-guide)
+- [Page Params Guide](/frontend/page-params-guide)
+- [API Guide](/frontend/api-guide)
+- [Model State Guide](/frontend/model-state-guide)
+- [SSR Init Data](/frontend/ssr-init-data)
+
+## Step 5: Regenerate metadata when needed
+
+If the page changes affect route structure or typed metadata, regenerate the relevant metadata through the Zova tool path.
+
+Representative command family:
+
+```bash
+npm run zova :tools:metadata ...
+```
+
+## Step 6: Verify the active edition workflow
+
+Use the right verification path for the active repo and flavor.
+
+Typical checks include:
+
+```bash
+npm run tsc
+npm run build:zova
+```
+
+And if needed, the relevant `zova/` flavor-specific build or REST generation paths.
+
+## AI rule of thumb
+
+A good AI frontend-page workflow in Cabloy is usually:
+
+1. detect edition
+2. choose generator or refactor command
+3. generate or transform
+4. connect API/model/SSR pieces
+5. regenerate metadata if needed
+6. verify

package/cabloy-docs/ai/playbook-metadata-refresh.md

@@ -0,0 +1,67 @@
+# Playbook: Metadata Refresh Workflow
+
+This playbook documents when and how Cabloy contributors and AI systems should refresh generated metadata.
+
+## Why this workflow matters
+
+In Cabloy, some framework behavior depends on generated metadata rather than only handwritten source files.
+
+That means certain structural changes are incomplete until metadata is regenerated.
+
+## Common triggers
+
+Typical triggers include:
+
+- route changes
+- page params/query structure changes
+- component wrapper-related changes
+- icon additions or module-level icon changes
+- relation or type-surface changes that affect typed framework artifacts
+
+## Step 1: Recognize that the change is structural
+
+Before editing more code, ask whether the change affects framework-generated structure rather than only business logic.
+
+This is the key AI checkpoint.
+
+## Step 2: Choose the right metadata generation path
+
+For frontend-side metadata work, the common path is the Zova tools family.
+
+Representative command family:
+
+```bash
+npm run zova :tools:metadata ...
+```
+
+For icon changes or other generation-sensitive areas, the metadata refresh may be part of the same broader workflow.
+
+## Step 3: Detect edition before verifying downstream effects
+
+If the generated metadata influences frontend build or runtime behavior, detect whether the active repo is Basic or Start before choosing verification examples.
+
+## Step 4: Re-run the dependent workflow
+
+After metadata regeneration, re-run the relevant dependent flow, such as:
+
+- typecheck
+- page route verification
+- component usage verification
+- icon usage verification
+- frontend build or REST generation
+
+## Step 5: Treat metadata generation as part of the change, not cleanup
+
+Metadata regeneration should not be treated as an optional final polish step.
+
+In Cabloy it is often part of the actual correctness path.
+
+## AI rule of thumb
+
+If a change alters framework structure, ask immediately:
+
+- does metadata need regeneration?
+- which command family owns that regeneration?
+- what downstream build or typecheck should confirm it worked?
+
+That prevents a large class of false-positive “done” states.

package/cabloy-docs/ai/repo-guidance.md

@@ -0,0 +1,58 @@
+# Repo Guidance for Agents
+
+When an AI agent works in Cabloy, it should navigate the repo with deliberate layers of trust.
+
+## 1. Start from the root
+
+Check the root repository signals first:
+
+- `package.json`
+- edition marker files such as `__CABLOY_BASIC__` or `__CABLOY_START__`
+- `.docs-internal/README.md`
+- root `.claude/` assets
+
+These files tell the agent which repo it is in, which scripts are canonical, and where public versus internal documentation belongs.
+
+## 2. Prefer framework entrypoints over scattered examples
+
+For backend workflows:
+
+- start from `npm run vona`
+- inspect Vona CLI command families
+
+For frontend workflows:
+
+- start from `npm run zova`
+- inspect Zova CLI command families
+
+This is more reliable than copying old file structures from examples without understanding the command surface that created them.
+
+## 3. Use docs and internal notes for different purposes
+
+- use `cabloy-docs/` to explain how people and agents should work
+- use `.docs-internal/` to explain why maintainers designed the repo a certain way
+
+## 4. Treat edition detection as mandatory for UI-sensitive work
+
+Edition detection is especially important when the work touches:
+
+- page creation
+- component generation
+- UI-layer usage
+- frontend flavor scripts
+- edition-specific suites, modules, SSR site baselines, or project assets
+
+## 5. Use the right lookup surface before searching broadly
+
+For backend lookup work, choose the surface before choosing the files:
+
+- if code references `this.bean.xxx`, `ctx.bean.xxx`, or `app.bean.xxx`, start from `IBeanRecordGlobal` and module `src/.metadata/index.ts`
+- if code references a full bean name, inspect `IBeanRecordGeneral`
+- if the target is a runtime-anchor or selector/class-token service, inspect `src/service` and service metadata
+- if the target is only a helper or superclass chain, inspect `src/lib`
+
+This reduces wasted search and keeps bean lookup aligned with class placement.
+
+## 6. Verify before claiming success
+
+Whenever a workflow recommendation is made, verify it against current scripts or command definitions before presenting it as guidance.

package/cabloy-docs/ai/rules-and-config.md

@@ -0,0 +1,29 @@
+# Rules and Config
+
+Cabloy’s AI behavior should be organized into a few clear layers instead of one oversized instruction file.
+
+## Root `CLAUDE.md`
+
+Use the root `CLAUDE.md` for concise, durable operational guidance such as:
+
+- how the monorepo is organized
+- where public docs live
+- where internal docs live
+- which command entrypoints are preferred
+- why edition detection is mandatory before UI-sensitive guidance or project-creation assumptions
+
+## `.claude/commands/`
+
+Use commands for reusable operator workflows that are naturally invoked as a named action, such as release or future docs migration helpers.
+
+## `.claude/skills/`
+
+Use skills for workflows that need more procedural context, bundled references, or iterative selection logic.
+
+## `settings.json` and `settings.local.json`
+
+Use Claude settings for permissions and execution environment, not as the primary place to explain framework concepts.
+
+## Documentation boundary
+
+If a rule is important for people and agents to understand, it probably belongs in public docs too. If it explains internal rationale rather than user-facing workflow, it belongs in `.docs-internal/`.

package/cabloy-docs/ai/skills.md

@@ -0,0 +1,37 @@
+# Skills
+
+Skills are the procedural layer of Cabloy’s AI development model.
+
+## What a skill should do here
+
+A Cabloy skill should reduce repeated reasoning cost by encoding workflows such as:
+
+- choosing the correct backend or frontend entrypoint
+- detecting the active edition
+- selecting the right CLI command family
+- deciding what to verify after generation or refactor work
+
+## What a skill should not do by default
+
+A skill should not re-implement framework scaffolding manually when the Vona or Zova CLI already provides that behavior.
+
+If a generator or refactor command exists, the skill should orchestrate it instead of replacing it.
+
+## Skill placement
+
+- Use root `.claude/skills/` for cross-stack, monorepo-wide workflows.
+- Use subtree-local `.claude/skills/` only when a workflow is truly specific to one framework area.
+
+## Skill structure recommendation
+
+A strong Cabloy skill usually includes:
+
+1. repo and edition detection
+2. CLI-first workflow selection
+3. minimal manual fallback guidance
+4. verification guidance
+5. references to durable source-of-truth files
+
+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.

package/cabloy-docs/ai/verification.md

@@ -0,0 +1,31 @@
+# Verification
+
+AI-assisted work should finish with checks that match the scope of the change.
+
+## Documentation verification
+
+For public docs changes, verify at minimum:
+
+- VitePress dev/build commands work
+- navigation links resolve
+- examples match current scripts and command names
+- edition labels and notes are consistent
+
+## Skill and rule verification
+
+For skills and repo guidance:
+
+- confirm the workflow still points to real command entrypoints
+- confirm edition branches match the active repo markers and scripts
+- confirm public docs, skills, and root `CLAUDE.md` tell the same story
+- review edition-aware changes against [Edition Consistency Checklist](/ai/edition-consistency-checklist)
+
+## Code-generation verification
+
+When a skill triggers code generation or refactor behavior:
+
+- inspect generated output
+- run targeted typecheck, tests, or build commands
+- prefer existing root scripts when a full verification pass is needed
+
+Verification is part of the workflow, not an optional afterthought.

package/cabloy-docs/ai/virtual-decorator-guidance.md

@@ -0,0 +1,206 @@
+# Virtual Decorator Guidance
+
+Use this page when deciding whether a backend class should use `@Virtual()`, or when AI needs to understand what `@Virtual()` changes in Vona bean behavior.
+
+The goal is to preserve real runtime semantics, keep class placement intentional, and prevent `@Virtual()` from being reused as a shorthand or registration filter.
+
+## Short definition
+
+`@Virtual()` marks a container-managed class as a virtual inherited runtime node.
+
+Its core effect is to make bean registration inherit `moduleBelong` from the parent bean chain instead of treating the current class as a new independent runtime ownership center.
+
+## What `@Virtual()` does not mean
+
+`@Virtual()` does **not** mean any of the following:
+
+- suppress bean registration
+- remove a bean-scene class from `IBeanRecordGlobal`
+- act as a shorthand-registration filter
+- compensate for incorrect class placement
+- mean only that a class is abstract or internal
+
+If a class should not appear on the global shorthand surface, fix placement instead.
+
+For related guidance, also read:
+
+- [Class Placement Rule](/ai/class-placement-rule)
+- [Global Bean Lookup](/ai/global-bean-lookup)
+
+## Runtime effect
+
+`@Virtual()` matters at registration time and then keeps affecting runtime scope resolution.
+
+### 1. Decorator stage
+
+The decorator writes virtual metadata on the class.
+
+Conceptually:
+
+```text
+@Virtual()
+ -> metadata(SymbolDecoratorVirtual = true)
+```
+
+### 2. Registration stage
+
+When the bean is registered, Vona reads that metadata and computes `moduleBelong`.
+
+- non-virtual bean -> `moduleBelong` stays equal to the current module
+- virtual bean -> `moduleBelong` is inherited from the nearest parent bean that already has one
+
+Conceptually:
+
+```text
+@Virtual()
+ -> addBean()
+ -> _parseModuleBelong()
+ -> inherited moduleBelong
+```
+
+### 3. Runtime stage
+
+Bean instances then resolve runtime scope resources from that inherited `moduleBelong`.
+
+This directly affects access to:
+
+- `this.scope`
+- `this.module`
+- `this.config`
+- `this.constant`
+- `this.error`
+- `this.locale`
+- `this.util`
+- `this.model`
+- `this.entity`
+- module meta and scene resources
+
+Short version:
+
+> `@Virtual()` changes runtime ownership resolution, not registration existence.
+
+## Relationship to `@Bean()` and `@Service()`
+
+These decorators solve different problems.
+
+- `@Bean()` / `@Service()` / `@Controller()` decide which scene the class registers into
+- `@Virtual()` decides how runtime ownership is resolved
+
+They are orthogonal.
+
+Examples:
+
+- `@Service() + @Virtual()`
+  - service-scene bean
+  - runtime ownership follows the parent bean chain
+- `@Bean() + @Virtual()`
+  - bean-scene bean
+  - still a virtual bridge node rather than a new independent ownership center
+
+## When to use `@Virtual()`
+
+Use `@Virtual()` when a class is still container-managed, but is not intended to become a new independent runtime ownership center.
+
+Typical cases:
+
+### 1. Runtime-anchor bases
+
+These classes still need bean lifecycle, class-token lookup, selector-aware behavior, or framework-managed context.
+
+Representative examples:
+
+- `vona/src/suite-vendor/a-vona/modules/a-orm/src/service/databaseDialectBase_.ts`
+- `vona/src/suite-vendor/a-vona/modules/a-cache/src/service/cacheMemBase_.ts`
+- `vona/src/suite-vendor/a-vona/modules/a-cache/src/service/cacheRedisBase_.ts`
+- `vona/src/suite-vendor/a-vona/modules/a-summer/src/service/summerCacheBase_.ts`
+
+### 2. Bean facade or bridge nodes
+
+These classes remain intentionally visible on the bean-scene shorthand surface, but still behave as inherited bridge nodes rather than independent runtime ownership centers.
+
+Representative example:
+
+- `vona/src/suite-vendor/a-vona/modules/a-orm/src/bean/bean.model.ts`
+
+### 3. Compatibility or variant nodes
+
+These classes extend an existing bean hierarchy and should keep runtime ownership aligned with the parent chain.
+
+Representative example:
+
+- `vona/src/suite-vendor/a-vona/modules/a-ormdialect/src/bean/databaseDialect.mysql3.ts`
+
+## When not to use `@Virtual()`
+
+Do **not** use `@Virtual()` for these cases.
+
+### 1. Independent business services
+
+If a class is the real business owner of its own runtime boundary, it should usually keep its own `moduleBelong` and should not be virtual.
+
+### 2. Misplaced bean-scene classes
+
+Do not keep a class in `src/bean` and try to hide it with `@Virtual()`.
+
+If it should not be a global shorthand bean, move it instead:
+
+- pure helper or subclass-only base -> `src/lib`
+- runtime-anchor base -> `src/service`, often `src/service/*_.ts`
+
+### 3. Pure helpers or superclass convenience classes
+
+If a class does not need container-managed behavior, it usually belongs in `src/lib` and should not use `@Virtual()`.
+
+## Decision table
+
+| Scenario | Use `@Virtual()` | Recommended placement | Reason |
+| --- | --- | --- | --- |
+| independent business service | No | `src/service` | it should own its own runtime resource boundary |
+| runtime-anchor base with container behavior | Yes | `src/service` or `src/service/*_.ts` | it is container-managed but belongs logically to the parent bean system |
+| bean-scene facade that intentionally stays on shorthand surface | Yes, if it is a bridge node | `src/bean` | it participates in shorthand lookup but is not a new ownership center |
+| compatibility / dialect / variant node built on a parent bean | Yes | same scene as the concrete variant type | runtime ownership should inherit from the parent chain |
+| pure helper or superclass convenience class | No | `src/lib` | no bean ownership semantics are needed |
+| class kept in `src/bean` only to expose shortcut lookup | Usually no | re-evaluate placement | `@Virtual()` is not a shorthand filter |
+| misplaced bean-scene class that should not be globally visible | No | move to `src/lib` or `src/service` | fix placement, not metadata |
+
+## Worked examples
+
+### Example: runtime-anchor dialect base
+
+`databaseDialectBase_.ts` is virtual because it remains container-managed and is used as the runtime base for dialect resolution, but it is not meant to become a separate public shorthand ownership center.
+
+### Example: bean-scene bridge node
+
+`bean.model.ts` is still in bean-scene because it intentionally participates in the global shorthand surface, but `@Virtual()` preserves its bridge-node semantics.
+
+### Example: derived dialect variant
+
+`databaseDialect.mysql3.ts` combines `$Class.extend(...)` and `@Virtual()` because those two features solve different problems:
+
+- `$Class.extend(...)` expresses a framework-managed derived-class relationship
+- `@Virtual()` preserves inherited runtime ownership semantics
+
+## Quick checklist
+
+Ask these questions in order:
+
+1. Does the class still need container-managed behavior?
+   - if no, do not use `@Virtual()`
+2. Is it a runtime extension of a parent bean system rather than a new business ownership center?
+   - if yes, `@Virtual()` may be appropriate
+3. Are you using `@Virtual()` only to hide the class from shorthand or metadata surfaces?
+   - if yes, do not use it; fix placement instead
+4. Will inherited `moduleBelong` produce the correct `scope` / `config` / `model` / `entity` behavior at runtime?
+   - if no, do not use `@Virtual()`
+
+## Related guidance
+
+Read these pages together:
+
+- [Class Placement Rule](/ai/class-placement-rule)
+- [Global Bean Lookup](/ai/global-bean-lookup)
+- [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping)
+
+For maintainer-level rationale, also read:
+
+- `.docs-internal/architecture/virtual-decorator-runtime-semantics.md`