cabloy 5.1.50 → 5.1.52

package/cabloy-docs/ai/edition-consistency-checklist.md

@@ -0,0 +1,150 @@
+# Edition Consistency Checklist
+
+This checklist helps maintainers keep docs, rules, commands, and skills aligned when writing or reviewing Cabloy Basic and Cabloy Start guidance.
+
+Use it whenever you add or revise:
+
+- edition-aware docs
+- `CLAUDE.md` guidance
+- `.claude/commands/`
+- `.claude/skills/`
+- AI workflow playbooks
+
+## The baseline story that should stay consistent
+
+Before checking details, confirm that the content still tells the same baseline story:
+
+- **Cabloy Basic** is the public framework/reference edition
+- `npm create cabloy` creates the default Cabloy Basic project route
+- **Cabloy Start** is the private commercial edition
+- Cabloy Start is used by cloning the licensed private repository source directly
+- both editions share the same Cabloy fullstack core
+- both editions share a frontend engineering layer built around Zova, Vue, Vite, Quasar tooling, and related libraries
+- the editions diverge in UI layer, frontend flavors, suites/modules, SSR site baselines, project assets, and some generated outputs
+
+If a page, rule, or skill contradicts one of those points, align that content before polishing wording.
+
+## Checklist 1: edition detection is explicit
+
+Confirm that the content:
+
+- tells the reader or agent to check `__CABLOY_BASIC__` or `__CABLOY_START__`
+- treats edition detection as mandatory before UI-sensitive guidance
+- does not assume Cabloy Basic examples apply to Cabloy Start automatically
+- does not assume the project creation path is the same for both editions
+
+## Checklist 2: creation path assumptions are correct
+
+Confirm that the content states or implies the right project-entry model:
+
+- **Cabloy Basic** → `npm create cabloy`
+- **Cabloy Start** → licensed private repository clone
+
+Watch for drift such as:
+
+- implying that Cabloy Start is created through `npm create cabloy`
+- implying that both editions use the same bootstrap path
+- omitting the Start licensing/private-repo model when it matters to the workflow
+
+## Checklist 3: shared core vs edition divergence is separated cleanly
+
+Confirm that the content distinguishes:
+
+### Shared core
+
+- Vona
+- Zova
+- suite-based architecture
+- CLI-first workflows
+- shared frontend engineering direction
+
+### Edition divergence
+
+- UI layer
+- frontend flavors
+- suites/modules
+- SSR site baselines
+- project assets
+- edition-specific generated outputs or script paths where applicable
+
+Avoid collapsing the whole difference into “different UI library only.”
+
+## Checklist 4: UI language uses the right layer
+
+When the content talks about frontend differences, confirm that it uses the right level:
+
+- shared frontend engineering layer
+- edition-specific UI layer
+
+Prefer wording such as:
+
+- **Cabloy Basic**: DaisyUI + Tailwind CSS UI layer
+- **Cabloy Start**: Vuetify UI layer
+
+Avoid wording that makes Quasar sound like the edition UI component library when the intended meaning is tooling.
+
+## Checklist 5: operational examples match the active edition
+
+For scripts, flavors, paths, and examples, confirm that:
+
+- Basic examples use Basic markers and Basic flavor names
+- Start examples tell the reader to verify the Start repo directly
+- Start workflows do not silently reuse Basic script or flavor assumptions
+- SSR site baseline assumptions match the edition being discussed
+- project-asset references match the repo being discussed
+
+## Checklist 6: docs, rules, and skills play different roles
+
+Confirm that the same guidance is distributed correctly:
+
+- **docs** explain the workflow in durable prose
+- **`CLAUDE.md`** captures short repo-wide behavioral rules
+- **skills** encode procedural branching and follow-up logic
+- **commands** are used only for named operator workflows, not as the only home for conceptual guidance
+
+Avoid these drifts:
+
+- a skill contains the only explanation of an edition rule
+- `CLAUDE.md` grows into a long architectural essay
+- docs duplicate every procedural branch that belongs in a skill
+
+## Checklist 7: verification guidance matches the edition model
+
+When content ends with verification steps, confirm that it reminds the reader or agent to verify the right edition-specific surfaces when relevant:
+
+- flavor names
+- script paths
+- suites/modules
+- SSR site baselines
+- generated outputs
+- project assets
+
+For Start-sensitive workflows, confirm that verification points back to the licensed Start repository rather than pretending the current Basic repo is the direct source of truth.
+
+## Checklist 8: wording about system size stays appropriately scoped
+
+If the content talks about project fit, confirm that it keeps the intended nuance:
+
+- **Cabloy Basic** is optimized for public reference, learning, community workflows, and faster small-to-medium system development
+- **Cabloy Start** is optimized as a stronger baseline for more complex business systems
+
+Avoid overstating this into a hard claim that Basic cannot support larger systems.
+
+## Quick review questions
+
+Before you finish an edition-aware change, ask:
+
+1. Did I clearly separate shared core from edition-specific divergence?
+2. Did I preserve the correct Basic vs Start creation path?
+3. Did I avoid turning UI difference into the whole story?
+4. Did I point Start-specific operational truth back to the licensed Start repo where needed?
+5. Do docs, rules, and skills each play their proper role?
+
+## Read together with
+
+- [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start)
+- [Editions Overview](/editions/overview)
+- [Edition Detection for AI Workflows](/ai/edition-detection)
+- [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping)
+- [Rules and Config](/ai/rules-and-config)
+- [Verification](/ai/verification)

package/cabloy-docs/ai/edition-detection.md

@@ -0,0 +1,30 @@
+# Edition Detection for AI Workflows
+
+This page applies the general detection rule from [Editions / Detection](/editions/detection) to AI-assisted development specifically.
+
+Edition detection should happen before any AI workflow that assumes a frontend stack, module set, or example path.
+
+## AI-specific consequence
+
+If an agent skips edition detection, it can:
+
+- scaffold against the wrong UI-layer assumptions
+- suggest the wrong frontend flavors
+- cite suites, modules, SSR site baselines, or project assets that do not exist in the active repo
+- generate docs or skills that accidentally hardcode Basic-only behavior or `npm create cabloy` assumptions into Start workflows
+
+## Operational rule
+
+Before an AI workflow recommends implementation steps:
+
+1. check the edition marker
+2. verify the relevant package scripts or CLI entrypoints
+3. branch the guidance only where the editions truly diverge
+
+## Where this rule should live
+
+Keep the same rule in three places on purpose:
+
+- **public docs** so people can review it
+- **skills** so agents execute it consistently
+- **`CLAUDE.md`** so repo-wide Claude behavior stays aligned

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

@@ -0,0 +1,135 @@
+# Future Skill Roadmap
+
+This page turns the current documentation work into a practical roadmap for future Cabloy skills.
+
+## Why a roadmap helps
+
+The docs now describe a large portion of the Cabloy backend, frontend, fullstack, and edition-aware workflow surface.
+
+A roadmap helps convert that documented knowledge into a focused set of high-value skills rather than a random collection of prompts.
+
+## What already exists
+
+Current root skill:
+
+- `cabloy-workflow`
+
+Its current role is broad workflow selection:
+
+- detect Basic vs Start
+- classify backend/frontend/fullstack/docs work
+- prefer CLI-first behavior
+- suggest verification
+
+This is a strong foundation skill, but it is intentionally general.
+
+## Recommended next skill families
+
+### 1. Backend scaffold skill
+
+Purpose:
+
+- scaffold Vona controller/service/model/entity/dto/CRUD threads
+- choose between bean creation and CRUD generation
+- verify migration/test implications
+
+Primary dependencies:
+
+- Vona `create:*`
+- Vona `tools:*`
+- backend docs in `cabloy-docs/backend/`
+
+### 2. Frontend scaffold skill
+
+Purpose:
+
+- scaffold Zova pages/components/API/models
+- branch correctly between Basic and Start
+- use create/refactor commands before manual edits
+
+Primary dependencies:
+
+- Zova `create:*`
+- Zova `refactor:*`
+- frontend docs in `cabloy-docs/frontend/`
+
+### 3. Fullstack contract loop skill
+
+Purpose:
+
+- detect backend contract changes
+- regenerate OpenAPI/SDK-related output
+- verify backend/frontend contract alignment
+
+Primary dependencies:
+
+- Vona OpenAPI and validation docs
+- Zova OpenAPI SDK and server-data docs
+- fullstack collaboration docs
+
+### 4. Metadata refresh skill
+
+Purpose:
+
+- detect when route/component/icon or related changes require metadata regeneration
+- run the right metadata flow
+- verify generated artifacts belong to the active edition
+
+Primary dependencies:
+
+- Zova `tools:*`
+- CLI-to-skill mapping
+- edition detection docs
+
+### 5. Distributed backend workflow skill
+
+Purpose:
+
+- route tasks into queue / schedule / broadcast / redlock / worker logic
+- help choose the right distributed abstraction
+- verify mode/flavor and transaction/cache implications
+
+Primary dependencies:
+
+- backend distributed docs
+- Redis / queue / schedule / worker / broadcast / redlock pages
+
+## What should stay in docs rather than becoming a skill
+
+Not every good doc topic should become a skill.
+
+Keep something in docs only when:
+
+- it is mostly conceptual
+- it has no procedural branching worth automating
+- it primarily teaches architecture rather than driving action
+
+Examples:
+
+- high-level architecture foundations
+- broad conceptual comparisons
+- maintainership rationale
+
+## Skill design rules for future Cabloy skills
+
+Future skills should generally:
+
+1. detect edition first when relevant
+2. classify backend/frontend/fullstack/docs/distributed layer
+3. prefer CLI/refactor/generator paths
+4. read docs only where the explanation adds value
+5. verify the result using the smallest correct command set
+
+## Why this roadmap matters for AI workflows
+
+The purpose of the roadmap is not to create many skills.
+
+The purpose is to create a small number of high-leverage skills that directly reuse the knowledge system now being built in:
+
+- `cabloy-docs/`
+- `CLAUDE.md`
+- `.docs-internal/`
+- `.claude/skills/`
+- the Vona and Zova CLIs
+
+That is how Cabloy gets long-term value from the documentation work.

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

@@ -0,0 +1,158 @@
+# 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)
+- [Virtual Decorator Guidance](/ai/virtual-decorator-guidance)
+- [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 vibe coding workflows in the Cabloy repository.
+
+The Cabloy monorepo is a good fit for AI vibe coding 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 vibe coding.
+
+### 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