cabloy 5.1.49 → 5.1.51

package/cabloy-docs/ai/global-bean-lookup.md

@@ -0,0 +1,157 @@
+# Global Bean Lookup
+
+Use this page when AI or contributors need to identify which backend shorthand a bean name refers to, or decide where to continue searching after a shorthand lookup fails.
+
+## Why this lookup rule matters
+
+Backend work often starts from code such as:
+
+- `this.bean.database`
+- `ctx.bean.model`
+- `app.bean.xxx`
+
+If an agent treats every bean-like class as part of one flat container, it wastes time and often inspects the wrong scene first.
+
+The goal of this rule is to make global bean lookup fast and structurally correct:
+
+- use `IBeanRecordGlobal` for global shorthand lookup
+- use `IBeanRecordGeneral` for general full-name lookup
+- use service-scene metadata and `src/service` for runtime-anchor and service lookup
+- use class placement, not metadata exceptions, to keep these surfaces clean
+
+## The three lookup surfaces
+
+### 1. `IBeanRecordGlobal`
+
+Use `IBeanRecordGlobal` for the **global shorthand authoring surface**.
+
+This is the first static lookup surface when backend code references:
+
+- `this.bean.xxx`
+- `ctx.bean.xxx`
+- `app.bean.xxx`
+
+Typical source of truth:
+
+- module `src/.metadata/index.ts`
+- corresponding `src/bean` source file
+
+Examples:
+
+- `database`
+- `model`
+
+### 2. `IBeanRecordGeneral`
+
+Use `IBeanRecordGeneral` for the **general full-name bean surface**.
+
+This is the right lookup surface when code references a bean by full name, such as:
+
+- `bean._getBean('a-orm.service.database')`
+- generated general bean registrations
+- scene-qualified bean identities that are not global shorthand
+
+Do not use `IBeanRecordGeneral` as the first lookup step for shorthand expressions like `this.bean.xxx`.
+
+### 3. Service-scene and runtime-anchor lookup
+
+Use `src/service`, service metadata, and class-token/selector call sites for classes that are not global shorthand but still rely on container-managed behavior.
+
+This is the right path for:
+
+- runtime-anchor bases
+- selector-based services
+- class-token lookup targets
+- `src/service/*_.ts` classes that should not participate in `IBeanRecordGeneral`
+
+Examples:
+
+- `databaseDialectBase_.ts`
+- cache/summer runtime-anchor bases in `src/service`
+
+## The default lookup workflow
+
+When backend code references `this.bean.xxx`, `ctx.bean.xxx`, or `app.bean.xxx`, prefer this sequence:
+
+1. check `IBeanRecordGlobal` in the relevant module `src/.metadata/index.ts`
+2. map the shorthand name to the generated bean type
+3. jump from the generated type to the source file in `src/bean`
+4. inspect neighboring bean-scene shorthand files only if needed for context
+5. only if the shorthand is not found, re-evaluate whether the target is actually:
+   - a general full-name bean
+   - a service-scene runtime-anchor
+   - a lib/helper class
+
+This keeps shorthand lookup fast and avoids jumping into `src/service` or `src/lib` too early.
+
+## What to do when the shorthand is not found
+
+If `IBeanRecordGlobal` does not contain the target name, do not assume the metadata is incomplete.
+
+Re-check the problem category:
+
+1. **Is the code actually using a full-name bean?**
+   - then inspect `IBeanRecordGeneral`
+2. **Is the target really a service-scene runtime-anchor or selector target?**
+   - then inspect `src/service`, service metadata, and selector/class-token call sites
+3. **Is the target only a helper or superclass chain?**
+   - then inspect `src/lib`
+
+The absence of a name from `IBeanRecordGlobal` often means the target is not a global shorthand at all.
+
+## Relationship to class placement
+
+This lookup rule depends on correct backend class placement.
+
+- `src/bean` defines the global shorthand surface
+- classes that should not be global shorthand belong in `src/lib` or `src/service`
+- `@Virtual()` does not remove a bean-scene class from `IBeanRecordGlobal`
+
+That means lookup quality is improved structurally by placing classes correctly, not by adding more metadata exceptions.
+
+For placement decisions, also read [Class Placement Rule](/ai/class-placement-rule).
+
+## Practical examples
+
+### Example: `this.bean.database`
+
+1. inspect the owning module `src/.metadata/index.ts`
+2. find `database` in `IBeanRecordGlobal`
+3. map it to the generated bean type
+4. jump to the corresponding `src/bean` source file
+
+### Example: `ctx.bean.model`
+
+1. inspect `IBeanRecordGlobal`
+2. find `model`
+3. jump to the bean-scene shorthand in `src/bean/bean.model.ts`
+4. continue into `src/lib` only if deeper superclass logic is needed
+
+### Example: database dialect runtime anchor
+
+If the target is a dialect base or class-token runtime anchor and does not appear in `IBeanRecordGlobal`, that is expected.
+
+Continue with:
+
+- `src/service`
+- service metadata
+- class-token or selector call sites
+
+## Anti-patterns to avoid
+
+Avoid these mistakes:
+
+- treating `IBeanRecordGlobal` as a full container inventory
+- jumping to `src/service` first when the code clearly uses `this.bean.xxx`
+- assuming a missing shorthand means metadata is broken before checking whether the target is actually global
+- keeping non-global classes in `src/bean` and compensating with metadata patches
+- using `@Virtual()` as a shorthand-registration filter
+
+## Related guidance
+
+Read these pages together:
+
+- [Class Placement Rule](/ai/class-placement-rule)
+- [Repo Guidance](/ai/repo-guidance)
+- [Rules and Config](/ai/rules-and-config)
+- [Verification](/ai/verification)

package/cabloy-docs/ai/introduction.md

@@ -0,0 +1,62 @@
+# AI Development Introduction
+
+This page is the entrypoint for contributors who are designing, reviewing, or maintaining AI-assisted workflows in the Cabloy repository.
+
+The Cabloy monorepo is a good fit for AI-assisted development because the source tree already contains most of the framework knowledge an agent needs:
+
+- root scripts for shared workflows
+- Vona CLI source and command groups
+- Zova CLI source and command groups
+- archived docs that still capture valuable concepts
+- internal engineering docs for maintainers
+- Claude commands and skills
+
+## The main design goal
+
+The goal is not to make AI guess Cabloy conventions more effectively.
+
+The goal is to make AI **reuse the repo’s existing conventions directly**, especially through:
+
+- CLI commands
+- root scripts
+- repo markers
+- internal architecture notes
+- shared public documentation
+
+## The knowledge layers
+
+### Public docs
+
+Use `cabloy-docs/` for user-facing and agent-facing guidance that should remain durable and source-aligned.
+
+For normal project usage, prefer the user-facing entry docs such as [Fullstack Quickstart](/fullstack/quickstart). This AI section focuses on repository workflows and AI-assisted development.
+
+### Internal engineering docs
+
+Use `.docs-internal/` for architecture notes, ADRs, and maintainership rationale that should not be mixed into public how-to documentation.
+
+### Claude rules and commands
+
+Use root `CLAUDE.md` and `.claude/commands/` for concise operational behavior and repeatable workflows.
+
+### Skills
+
+Use `.claude/skills/` for procedural workflows that benefit from reusable instructions, bundled references, or future deterministic scripts.
+
+## Recommended AI lookup rules
+
+For backend shorthand lookup, prefer these surfaces in order:
+
+1. `IBeanRecordGlobal` for `this.bean.xxx`, `ctx.bean.xxx`, and `app.bean.xxx`
+2. module `src/.metadata/index.ts` to map shorthand names to generated bean types
+3. `src/bean` for the shorthand source file itself
+4. only then re-evaluate whether the target is really a general full-name bean, a service-scene runtime-anchor, or a lib/helper class
+
+For the full lookup workflow, read [Global Bean Lookup](/ai/global-bean-lookup).
+
+## Common AI mistakes to avoid
+
+- assuming Cabloy Basic and Cabloy Start are identical
+- creating framework files manually when a CLI command already exists
+- trusting stale legacy repo paths instead of current source
+- mixing public documentation and internal rationale into one document set

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

@@ -0,0 +1,111 @@
+# Playbook: Add a Backend Module
+
+This playbook turns the Cabloy backend documentation into a repeatable AI-friendly workflow.
+
+## When to use this playbook
+
+Use this playbook when the goal is to add a new backend feature thread in Vona, such as:
+
+- a new module
+- a new controller/service/model/entity/dto thread
+- a new CRUD-oriented backend feature
+
+## Step 1: Detect the repo and scope
+
+Before generating anything:
+
+1. confirm the active repo marker
+2. confirm whether the task is backend-only or fullstack
+3. inspect the root `package.json`
+4. inspect `npm run vona` command families
+
+This avoids solving the wrong problem or choosing the wrong edition assumptions.
+
+## Step 2: Prefer the Vona CLI first
+
+Choose the smallest matching Vona command family.
+
+Typical options include:
+
+- `create:*` for module/bean/test scaffolding
+- `tools:*` for CRUD generation
+- `init:*` for config/locale/constant/type helpers
+
+Example paths:
+
+```bash
+npm run vona :create:module ...
+npm run vona :create:bean ...
+npm run vona :tools:crud ...
+```
+
+Do not start by hand-writing the whole thread if the generator already exists.
+
+## Step 3: Inspect the generated thread
+
+After generation, inspect the resulting backend layers:
+
+- controller
+- service
+- model
+- entity
+- dto
+- migration/meta files if applicable
+- locale and test files if applicable
+
+Use the generated structure as the baseline rather than replacing it.
+
+## Step 4: Add contract and persistence details
+
+Depending on the feature, extend the generated code with the right framework-level concerns:
+
+- validation
+- OpenAPI metadata
+- DTO inference or explicit DTOs
+- model relations
+- migration and changes
+- field indexes
+
+Relevant docs:
+
+- [Controller Guide](/backend/controller-guide)
+- [Service Guide](/backend/service-guide)
+- [Model Guide](/backend/model-guide)
+- [Entity Guide](/backend/entity-guide)
+- [DTO Guide](/backend/dto-guide)
+- [Migration and Changes](/backend/migration-and-changes)
+
+## Step 5: Verify the backend path
+
+Choose verification based on scope.
+
+Typical checks include:
+
+```bash
+npm run test
+npm run tsc
+npm run build
+```
+
+Or narrower checks such as:
+
+- module tests
+- migration reset flow
+- controller action testing
+
+## AI rule of thumb
+
+A good AI backend workflow in Cabloy is usually:
+
+1. detect
+2. choose CLI
+3. generate
+4. inspect
+5. refine
+6. verify
+
+Not:
+
+1. imagine the file structure
+2. write everything manually
+3. hope it matches framework conventions

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 library usage
+- frontend flavor scripts
+- edition-specific modules or 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
+
+## `.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/`.