cabloy 5.1.50 → 5.1.52

package/cabloy-docs/.vitepress/theme/custom.css

@@ -0,0 +1,64 @@
+:root {
+  --vp-c-brand-1: #2563eb;
+  --vp-c-brand-2: #1d4ed8;
+  --vp-c-brand-3: #1e40af;
+  --vp-sidebar-width: 320px;
+}
+
+.VPHomeHero .container .name,
+.VPHomeHero .container .text,
+.VPHomeHero .container .tagline {
+  max-width: 900px;
+}
+
+.vp-doc :not(pre, h1, h2, h3, h4, h5, h6) > code {
+  font-size: var(--vp-code-font-size);
+  color: var(--vp-code-color);
+}
+
+.cabloy-badges {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin: 1rem 0;
+}
+
+.cabloy-badge {
+  display: inline-flex;
+  align-items: center;
+  border-radius: 999px;
+  padding: 0.25rem 0.75rem;
+  font-size: 0.85rem;
+  font-weight: 600;
+  line-height: 1.25rem;
+}
+
+.cabloy-badge--common {
+  background: color-mix(in srgb, var(--vp-c-brand-1) 12%, white);
+  color: var(--vp-c-brand-3);
+}
+
+.dark .cabloy-badge--common {
+  background: color-mix(in srgb, var(--vp-c-brand-1) 20%, black);
+  color: #bfdbfe;
+}
+
+.cabloy-badge--basic {
+  background: #ecfeff;
+  color: #155e75;
+}
+
+.dark .cabloy-badge--basic {
+  background: #083344;
+  color: #a5f3fc;
+}
+
+.cabloy-badge--start {
+  background: #fff7ed;
+  color: #9a3412;
+}
+
+.dark .cabloy-badge--start {
+  background: #431407;
+  color: #fdba74;
+}

package/cabloy-docs/.vitepress/theme/edition-badges.md

@@ -0,0 +1,5 @@
+<div class="cabloy-badges">
+  <span class="cabloy-badge cabloy-badge--common">Common</span>
+  <span class="cabloy-badge cabloy-badge--basic">Basic</span>
+  <span class="cabloy-badge cabloy-badge--start">Start</span>
+</div>

package/cabloy-docs/.vitepress/theme/index.js

@@ -0,0 +1,5 @@
+import DefaultTheme from 'vitepress/theme';
+
+import './custom.css';
+
+export default DefaultTheme;

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

@@ -0,0 +1,139 @@
+# 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)
+- [Virtual Decorator Guidance](/ai/virtual-decorator-guidance)
+- [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 because the editions can diverge in UI layer, frontend flavors, suites/modules, SSR site baselines, and project assets. 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,168 @@
+# 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)
+- consistency review surface → [Edition Consistency Checklist](/ai/edition-consistency-checklist)
+- 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.