cabloy 5.1.50 → 5.1.51

package/cabloy-docs/ai/class-placement-rule.md

@@ -0,0 +1,138 @@
+# Class Placement Rule
+
+Use this rule when deciding where a backend base class should live.
+
+The goal is to keep pure helpers out of the bean registry, keep runtime-anchor classes container-managed, and keep the global bean shorthand surface intentional.
+
+## The short rule
+
+- **A**: pure helper base -> `src/lib`
+- **B1**: subclass-only base -> evaluate case by case, often `src/lib`
+- **B2**: runtime-anchor base that still needs container-managed or selector/class-token behavior but should not be a global bean -> prefer `src/service` with `@Service()`
+
+## What the categories mean
+
+### A: pure helper base
+
+Use A when the class is only a reusable implementation helper.
+
+Typical signals:
+
+- no bean lifecycle requirement
+- no class-token lookup requirement
+- no selector-based resolution requirement
+- no need for bean-managed context or injection
+
+Recommended placement:
+
+- `src/lib`
+
+### B1: subclass-only base
+
+Use B1 when the class mainly exists as a superclass for concrete subclasses.
+
+Typical signals:
+
+- concrete behavior is usually reached through subclasses
+- the superclass may not need its own durable runtime identity
+- registration may be historical rather than essential
+
+Recommended placement:
+
+- evaluate case by case
+- often `src/lib`
+
+### B2: runtime-anchor base
+
+Use B2 when the class still participates in runtime bean resolution, even if it should not be treated as a public global bean.
+
+Typical signals:
+
+- used as a class token
+- used in `_getBean(...)` or `_getBeanSelector(...)`
+- participates in selector-aware resolution or instance caching
+- depends on bean lifecycle or other container-managed behavior
+- already uses `@Virtual()` for an intentional business meaning that should survive the move
+
+Recommended placement:
+
+- `src/service` with `@Service()`
+- if the original class was virtual, keep `@Virtual()` after the move
+
+## Service underscore files
+
+For service-scene classes, a trailing underscore in the file name is not only a naming style.
+
+Prefer the `src/service/*_.ts` form when a class should remain container-managed but should **not** participate in the general full-name registration surface.
+
+This usually fits classes that are:
+
+- runtime-anchor bases
+- selector or class-token anchors
+- virtual bases with real runtime meaning
+- not intended to be exposed as general full-name beans
+
+Prefer a normal `src/service/*.ts` file when the service-scene class itself should remain part of the general full-name surface.
+
+Examples:
+
+- `cacheMemBase_.ts`
+- `cacheRedisBase_.ts`
+- `summerCacheBase_.ts`
+
+Do not choose the underscore form only because a class is abstract or uses `@Virtual()`. The deciding factor is the runtime role and registration surface.
+
+## Bean-scene and global shorthand
+
+For backend classes, `src/bean` defines the global shorthand surface.
+
+A bean-scene class should be expected to participate in `IBeanRecordGlobal`, even when it uses `@Virtual()` for a real business meaning.
+
+Do not use `@Virtual()` as a reason to suppress a bean-scene class from `IBeanRecordGlobal`.
+
+If a class should not appear on the global shorthand surface, fix placement instead:
+
+- move pure helper or subclass-only bases to `src/lib`
+- move runtime-anchor bases to `src/service`, often `src/service/*_.ts`
+
+Do not keep non-global classes in `src/bean` and compensate with metadata-generation exceptions or manual type patches.
+
+## Fast classification checklist
+
+Ask these questions in order:
+
+1. Does the class still need container-managed behavior?
+   - if no, it is usually A or B1
+2. Is it mainly a runtime anchor rather than a public global bean?
+   - if yes, it is usually B2
+3. Is it mostly a superclass convenience whose logic runs through concrete subclasses?
+   - if yes, it is usually B1
+
+## Why B2 uses service-scene
+
+B2 is about runtime semantics, not business naming.
+
+The point is not that the class suddenly becomes a business-oriented service. The point is that it still needs container-managed behavior while no longer belonging on the global bean shorthand surface.
+
+That is why `src/service` with `@Service()` is usually the better fit than moving it directly to `src/lib`.
+
+If the original class already used `@Virtual()`, preserve `@Virtual()` after the move. Virtuality and service-scene placement describe different concerns and should not be conflated.
+
+## Validated B2 examples
+
+The cache and summer runtime-anchor bases validated this rule in practice.
+
+That validation also confirmed an important constraint:
+
+- if a B2 base already used `@Virtual()`, keep `@Virtual()` after moving it to `src/service`
+
+The next separate step after placement validation is naming consistency for the public base-class surface.
+
+## Related guidance
+
+Read these pages together:
+
+- [Backend Foundation](/backend/foundation)
+- [Service Guide](/backend/service-guide)
+- [Global Bean Lookup](/ai/global-bean-lookup)
+- [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping)

package/cabloy-docs/ai/cli-for-agents.md

@@ -0,0 +1,56 @@
+# CLI for Agents
+
+The Vona and Zova CLIs are the highest-leverage automation surface in this repository.
+
+## Why CLI-first matters
+
+Using the CLI reduces both token use and framework drift.
+
+Instead of asking the model to infer every generated file or naming convention, the skill or agent can:
+
+1. discover the relevant command family
+2. execute the command
+3. inspect the output
+4. apply only the smallest necessary follow-up edits
+
+## Existing command families
+
+### Vona
+
+Vona already exposes command families such as:
+
+- `bin:*`
+- `create:*`
+- `init:*`
+- `tools:*`
+
+Typical use cases:
+
+- create suite/module/bean/test resources
+- initialize config, locale, constants, assets, or types
+- generate CRUD-related artifacts
+- refresh metadata and dependency wiring
+- run build, dev, test, typecheck, play, or database reset flows
+
+### Zova
+
+Zova already exposes command families such as:
+
+- `bin:*`
+- `create:*`
+- `init:*`
+- `refactor:*`
+- `tools:*`
+- `openapi:*`
+
+Typical use cases:
+
+- create suite/module/page/component/mock/bean resources
+- initialize app/system assets and typing helpers
+- run focused refactors for page and component patterns
+- generate OpenAPI-related outputs
+- refresh metadata and dependency wiring
+
+## Edition-aware CLI usage
+
+The command families are shared, but examples and generated targets may differ between Cabloy Basic and Cabloy Start. Detect the edition before recommending a frontend-specific example.

package/cabloy-docs/ai/cli-to-skill-map.md

@@ -0,0 +1,165 @@
+# CLI to Skill Map
+
+This page explains how Cabloy skills should map onto Vona and Zova CLI capabilities.
+
+## Why this mapping matters
+
+The CLI is the most efficient automation surface in the repo.
+
+Skills should normally orchestrate CLI capabilities rather than replacing them.
+
+That is how Cabloy reduces token use and keeps AI output aligned with framework conventions.
+
+## The general rule
+
+When a task matches an existing generator, refactor, metadata, or execution command:
+
+1. detect the active edition
+2. identify the relevant framework side
+3. choose the correct CLI family
+4. run or recommend the CLI command
+5. inspect output
+6. apply minimal follow-up edits
+7. verify
+
+## Vona CLI families and likely skill roles
+
+### `create:*`
+
+Typical use cases:
+
+- suite/module/bean/test generation
+- controller/service/model/entity/dto creation
+
+Typical skill role:
+
+- choose the right bean or module workflow
+- branch on context
+- then delegate creation to Vona CLI
+
+### `init:*`
+
+Typical use cases:
+
+- config / locale / constant / asset / types initialization
+
+Typical skill role:
+
+- decide whether the task belongs to module setup or later feature work
+- then delegate initialization to Vona CLI
+
+### `tools:*`
+
+Typical use cases:
+
+- CRUD generation
+- metadata and dependency refresh
+
+Typical skill role:
+
+- recognize when a task is “scaffold a thread” rather than “hand-build layers”
+- choose the right generator
+- then inspect and refine output
+
+### `bin:*`
+
+Typical use cases:
+
+- dev / test / tsc / play / db-reset / build
+
+Typical skill role:
+
+- pick the right verification or execution path after changes
+
+## Zova CLI families and likely skill roles
+
+### `create:*`
+
+Typical use cases:
+
+- page / component / module / mock / bean generation
+
+Typical skill role:
+
+- detect whether the task is page/component/API/model-oriented
+- then delegate generation to Zova CLI
+
+### `refactor:*`
+
+Typical use cases:
+
+- page query
+- page params
+- component props
+- generic component
+- v-model
+
+Typical skill role:
+
+- recognize when a task is “add a framework feature to an existing page/component”
+- then delegate the structural transform to Zova CLI
+
+### `openapi:*`
+
+Typical use cases:
+
+- config generation
+- SDK generation
+
+Typical skill role:
+
+- connect backend contract changes to frontend regeneration
+- then delegate to Zova OpenAPI commands
+
+### `tools:*`
+
+Typical use cases:
+
+- metadata regeneration
+- dependency refresh
+
+Typical skill role:
+
+- notice when route/component/icon changes require metadata regeneration
+
+## Example mappings
+
+### Example: “Create a student CRUD backend thread”
+
+- skill decides this is a backend CRUD task
+- skill chooses Vona `tools:*`
+- likely CLI path: `npm run vona :tools:crud ...`
+- skill then verifies the generated layers and suggests follow-up edits
+
+### Example: “Add page params to an existing Zova page”
+
+- skill decides this is a frontend page refactor task
+- skill chooses Zova `refactor:*`
+- likely CLI path: `npm run zova :refactor:pageParams ...`
+- skill then reminds the user to regenerate metadata and verify route behavior
+
+### Example: “Backend contract changed, frontend needs refresh”
+
+- skill decides this is a fullstack contract loop task
+- skill uses docs + edition detection
+- likely CLI path: Zova `openapi:*` or REST build flows
+- skill then verifies the right edition-specific flavor path
+
+## Anti-patterns
+
+Avoid these mistakes in skills:
+
+- hand-writing all generated files when a CLI command exists
+- editing page/component/model structure manually before checking `refactor:*`
+- ignoring metadata regeneration after route/component/icon changes
+- using Basic-specific examples in Start without edition detection
+
+## Current root skill example
+
+The root-level skill:
+
+- `.claude/skills/cabloy-workflow/SKILL.md`
+
+already follows this philosophy: detect edition, classify layer, prefer CLI, then verify.
+
+Future skills should follow the same mapping pattern.

package/cabloy-docs/ai/docs-skills-rules-mapping.md

@@ -0,0 +1,167 @@
+# Docs, Skills, Rules, and CLI Mapping
+
+This page is for docs, skills, and workflow authors who need to decide where Cabloy AI guidance should live.
+
+This page explains how the Cabloy AI knowledge system is divided across public docs, skills, rules, and CLI capabilities.
+
+## Why this mapping matters
+
+Without a clear mapping, AI systems and contributors repeat the same mistakes:
+
+- knowledge is stored in the wrong place
+- CLI capabilities are documented but not reused in skills
+- skills explain things that should live in docs
+- rules become too large because they try to teach everything
+- the same guidance drifts across multiple files
+
+The goal is to give each layer a distinct job.
+
+## The four main layers
+
+### 1. Public docs
+
+Location:
+
+- `cabloy-docs/`
+
+Use public docs for:
+
+- durable user-facing guidance
+- durable agent-facing workflow guidance
+- architecture explanations that people and agents should both understand
+- edition-aware usage notes that need to be reviewed in prose
+
+Public docs answer questions like:
+
+- how does the fullstack collaboration loop work?
+- how should Vona ORM and OpenAPI be understood?
+- how does Zova page or model architecture work?
+- what is different between Cabloy Basic and Cabloy Start?
+
+### 2. Internal engineering docs
+
+Location:
+
+- `.docs-internal/`
+
+Use internal docs for:
+
+- ADRs
+- architecture rationale
+- maintenance boundaries
+- “why this design exists” notes that do not belong in public user docs
+
+Internal docs answer questions like:
+
+- why were docs and internal notes separated?
+- why is AI enablement structured this way?
+- what invariants should future contributors preserve?
+
+### 3. Rules and commands
+
+Locations:
+
+- `CLAUDE.md`
+- `.claude/commands/`
+
+Use rules for:
+
+- concise repo-wide operational guidance
+- default behavior Claude should follow in this repo
+- short durable constraints such as edition detection and CLI-first preference
+
+Use commands for:
+
+- named recurring operator workflows
+- shorter, explicit actions such as release or future migration helpers
+
+These layers answer questions like:
+
+- what should Claude check first in this repo?
+- when should CLI be preferred over manual scaffolding?
+- what recurring workflow deserves a named command?
+
+### 4. Skills
+
+Location:
+
+- `.claude/skills/`
+
+Use skills for:
+
+- procedural decision trees
+- reusable workflows with branching logic
+- tasks that benefit from bundled references, evals, or future deterministic helpers
+- repo-specific orchestration over CLI and source inspection
+
+Skills answer questions like:
+
+- how should Claude choose the right Cabloy workflow?
+- when should it branch between Basic and Start?
+- what is the right verification path after generation or refactor work?
+
+## Decision rule for authors: where should a new piece of knowledge go?
+
+Use this quick rule:
+
+- if people and agents both need to read and understand it, put it in **public docs**
+- if it is maintainer rationale or long-lived design history, put it in **internal docs**
+- if it is short repo-wide behavioral guidance, put it in **CLAUDE.md**
+- if it is a named repeatable operator action, put it in a **command**
+- if it is a reusable procedural workflow with branching, put it in a **skill**
+
+## Example mappings
+
+### Example: “Always detect Basic vs Start before giving UI-sensitive advice”
+
+- public explanation → [AI Edition Detection](/ai/edition-detection)
+- repo-wide behavior rule → `CLAUDE.md`
+- procedural enforcement → `cabloy-workflow` skill
+
+### Example: “Use Zova CLI refactors before hand-editing page params/query/component props”
+
+- conceptual explanation → public docs in frontend and AI sections
+- default agent behavior → `CLAUDE.md`
+- step-by-step orchestration → `cabloy-workflow` skill or future specialized skills
+
+### Example: “How should a backend base class be placed?”
+
+- public operational explanation → [Class Placement Rule](/ai/class-placement-rule)
+- maintainer rationale and invariants → `.docs-internal/architecture/class-placement-a-b1-b2.md`
+- default repo-wide behavior → `CLAUDE.md`
+- procedural decision workflow → `cabloy-workflow` skill
+
+### Example: “How should AI look up a backend global bean?”
+
+- public lookup explanation → [Global Bean Lookup](/ai/global-bean-lookup)
+- default repo-wide behavior → `CLAUDE.md`
+- procedural lookup sequence → `cabloy-workflow` skill
+
+### Example: “How backend OpenAPI becomes frontend SDK”
+
+- full explanation → [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- workflow steering → skill and rules can point to the docs and choose the right CLI path
+
+## Anti-patterns to avoid
+
+Avoid these mistakes:
+
+- putting large conceptual explanations in `CLAUDE.md`
+- using a skill as the only place where an important architectural rule is explained
+- duplicating the same workflow prose across docs and skills without giving each a distinct role
+- creating a command for something that actually needs a branching decision tree
+- creating a skill that re-implements an existing CLI generator manually
+
+## Why this matters for AI workflows
+
+This mapping reduces token waste and drift.
+
+If each layer does the right job:
+
+- docs hold durable explanations
+- rules hold short repo behavior
+- commands hold named actions
+- skills orchestrate real workflows
+- CLI executes framework-native generation and refactor behavior
+
+That is the AI-development model Cabloy is optimizing for.

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 assumptions
+- suggest the wrong frontend flavors
+- cite modules that do not exist in the active repo
+- generate docs or skills that accidentally hardcode Basic-only behavior 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.