cabloy 5.1.149 → 5.1.151

package/.claude/skills/cabloy-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cabloy-workflow
-description: This skill should be used when the main Cabloy problem is workflow routing before implementation: deciding between Vona backend scaffolding, Zova frontend scaffolding, contract-loop work, or docs/AI-enablement homes such as repo-docs, repo-docs-internal, CLAUDE.md, commands, or skills, including cases where Cabloy Basic vs Cabloy Start assumptions affect that routing. Trigger on requests to route, classify, choose a workflow, choose an edition-specific path, or decide where Cabloy guidance should live. Do not use it once the task is already clearly a backend scaffold, frontend scaffold, or contract-loop job.
+description: This skill should be used when the main Cabloy problem is workflow routing before implementation: deciding between Vona backend scaffolding, Zova frontend scaffolding, contract-loop work, or docs/AI-enablement homes such as repo-docs, an established internal-docs home when present, CLAUDE.md, commands, or skills, including cases where Cabloy Basic vs Cabloy Start assumptions affect that routing. Trigger on requests to route, classify, choose a workflow, choose an edition-specific path, or decide where Cabloy guidance should live. Do not use it once the task is already clearly a backend scaffold, frontend scaffold, or contract-loop job.
 ---
 
 # Cabloy Workflow
@@ -24,12 +24,21 @@ Check the repository root for these marker files:
 
 Interpretation:
 
-- `__CABLOY_BASIC__` present → this is Cabloy Basic
-- `__CABLOY_START__` present → this is Cabloy Start
-- neither present → inspect the repo scripts and ask the user before making a strong edition-specific assumption
+- only `__CABLOY_BASIC__` present → this is Cabloy Basic
+- only `__CABLOY_START__` present → this is Cabloy Start
+- both markers present → treat the repository as ambiguous or invalid and stop before making edition-specific assumptions
+- neither marker present → inspect the owning package scripts and nearby repository structure, then ask before making an edition-specific assumption
 
 This matters most for frontend work, UI-layer assumptions, flavor names, suite/module availability, SSR site baselines, project assets, and edition-specific AI guidance.
 
+Repository-path availability is independent of edition detection:
+
+- inspect a documentation path before recommending or reading it
+- use `repo-docs-internal/` only when an established active-repository home exists
+- treat edition-local internal notes as optional maintainer material, never as a prerequisite for shared workflow routing
+- when an optional path is absent, continue from public docs, bundled skill references, active source, and tests
+- do not create a missing documentation home unless the user explicitly asks to establish one
+
 ## Step 2: Identify the task layer
 
 Classify the request before proposing a workflow.
@@ -70,7 +79,7 @@ Use the frontend path when the task is about:
 Use the docs/AI path when the task is about:
 
 - `repo-docs/`
-- `repo-docs-internal/`
+- an established `repo-docs-internal/` home when present
 - `CLAUDE.md`
 - `.claude/commands/`
 - `.claude/skills/`
@@ -85,7 +94,7 @@ Before inventing a workflow, inspect these shared surfaces:
 - `npm run zova`
 - root `CLAUDE.md` if present
 - `repo-docs/` for public guidance
-- `repo-docs-internal/` for maintainer rationale
+- an established `repo-docs-internal/` home for optional maintainer rationale
 
 If the request spans backend and frontend, classify it as fullstack by default unless the user clearly wants only one side.
 
@@ -158,15 +167,17 @@ Use `repo-docs/` for:
 - reusable AI-facing workflow guidance
 - edition-aware public documentation
 
-### Internal engineering docs
+### Optional internal engineering docs
 
-Use `repo-docs-internal/` for:
+When an established `repo-docs-internal/` home exists, it may be used for:
 
 - ADRs
 - architecture notes
 - maintainer rationale
 - invariants and design boundaries
 
+Its absence must not block routing or implementation, and it must not be assumed to exist in every checkout.
+
 ### Root rules and commands
 
 Use `CLAUDE.md` and `.claude/commands/` for:
@@ -197,7 +208,7 @@ When the request is about whether a backend base class belongs in `src/lib`, `sr
 For these requests:
 
 - put the durable operational explanation in `repo-docs/`
-- put rationale and invariants in `repo-docs-internal/`
+- when an established internal-docs home exists, put rationale and invariants there; otherwise preserve the public operational explanation and ask before establishing a new maintainer-rationale home
 - keep `CLAUDE.md` short and behavioral
 - do not treat `@Service()` as a business-layer naming decision only; for B2 it is a runtime-anchor placement choice
 
@@ -276,7 +287,7 @@ Verify:
 
 - referenced paths exist
 - command names still exist
-- public docs, internal docs, and rules tell a consistent story
+- public docs, optional internal rationale, and rules tell a consistent story
 - edition-specific notes point to the right repo assumptions
 
 ### For backend/frontend workflow changes

package/.claude/skills/cabloy-workflow/evals/evals.json

@@ -15,8 +15,8 @@
     },
     {
       "id": 3,
-      "prompt": "Please help me decide whether this new AI guidance belongs in public docs, repo-docs-internal, CLAUDE.md, or a skill. The guidance is about when to use npm run zova instead of hand-written scaffolding.",
-      "expected_output": "Routes the request to the right knowledge homes, prefers public docs plus Claude rules/skills as appropriate, and reinforces the CLI-first principle.",
+      "prompt": "Please help me decide whether this new AI guidance belongs in public docs, an internal-docs home when present, CLAUDE.md, or a skill. The guidance is about when to use npm run zova instead of hand-written scaffolding.",
+      "expected_output": "Routes shared operational guidance to public docs and Claude rules/skills as appropriate, treats an internal-docs home as optional maintainer material rather than an assumed requirement, and reinforces the CLI-first principle.",
       "files": []
     },
     {
@@ -48,6 +48,12 @@
       "prompt": "I created a linked Cabloy Basic worktree and only need backend tests. What should I do for local environment isolation?",
       "expected_output": "Keeps generic routing read-only and directs the user to the canonical guide plus explicit /cabloy-worktree-environment invocation. It explains that the invoked skill still generates the universal APP_NAME, SERVER_LISTEN_PORT, DEV_SERVER_PORT, DEV_SERVER_HMR_PORT, and derived API_BASE_URL tuple in both broad local files after confirmation; it does not provide a backend-only one-file path.",
       "files": []
+    },
+    {
+      "id": 9,
+      "prompt": "I am in a Cabloy checkout whose active repository currently has no repo-docs-internal directory. I need shared agent guidance and some maintainer rationale. Where should each part go?",
+      "expected_output": "Inspects the active repository path rather than making an edition-wide assumption, routes shared operational guidance to existing public docs and Claude rules or skills, and asks which established maintainer-rationale home to use rather than putting rationale into public docs automatically.",
+      "files": []
     }
   ]
 }

package/.claude/skills/cabloy-workflow/references/edition-detection.md

@@ -2,10 +2,12 @@
 
 ## Primary markers
 
-Use these root markers first:
+Interpret the root markers as exactly one of these states:
 
-- `__CABLOY_BASIC__`
-- `__CABLOY_START__`
+- only `__CABLOY_BASIC__` present → Cabloy Basic
+- only `__CABLOY_START__` present → Cabloy Start
+- both markers present → treat the checkout as invalid or ambiguous and stop before making edition-specific assumptions
+- neither marker present → inspect the owning `package.json` and nearby repository structure, then ask before making an edition-specific assumption
 
 ## Why the markers matter
 

package/.claude/skills/cabloy-zova-source-reading/SKILL.md

@@ -25,9 +25,10 @@ Check the repository root for these marker files:
 
 Interpretation:
 
-- `__CABLOY_BASIC__` present → this is Cabloy Basic
-- `__CABLOY_START__` present → this is Cabloy Start
-- neither present → inspect the repo scripts and ask before making edition-specific frontend assumptions
+- only `__CABLOY_BASIC__` present → this is Cabloy Basic
+- only `__CABLOY_START__` present → this is Cabloy Start
+- both markers present → treat the repository as ambiguous or invalid and stop before making edition-specific assumptions
+- neither marker present → inspect the owning package scripts and nearby repository structure, then ask before making an edition-specific assumption
 
 This matters most when the analysis becomes UI-sensitive, SSR-site-sensitive, flavor-sensitive, or module-set-sensitive.
 

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 5.1.151
+
+### Features
+
+- Add chart specifications and chart support.
+- Add SSR site specifications.
+- Add Cabloy specification execution.
+- Add skill creation support.
+- Add implementation burndown and gantt charts.
+
+### Bug Fixes
+
+- Fix skill specifications.
+
+### Improvements
+
+- Refactor skills and skill specification generation.
+- Update dependencies.
+
+## 5.1.150
+
+### Features
+
+- Add `bypassPersister` support.
+- Update query functionality.
+- Add runbook updates.
+- Add schema alias support.
+- Add SKU stock availability support.
+- Update related functionality and resources.
+
+### Bug Fixes
+
+- Fix end-to-end tests.
+- Correct `bypassPersister` behavior.
+- Update schema tests.
+
+### Improvements
+
+- Refactor the student model and service.
+- Improve documentation for `bypassPersister`.
+
 ## 5.1.149
 
 ### Features

package/CLAUDE.md

@@ -2,15 +2,14 @@
 
 ## Repository identity
 
-This repository is **Cabloy Basic**, the public framework/reference edition, identified by the root marker file:
+Detect the active edition from the repository-root marker before making edition-sensitive assumptions:
 
-- `__CABLOY_BASIC__`
+- exactly `__CABLOY_BASIC__` present → Cabloy Basic, the public framework/reference edition
+- exactly `__CABLOY_START__` present → Cabloy Start, the private commercial edition delivered as licensed source
+- both markers present → treat the checkout as invalid or ambiguous and stop before giving edition-specific guidance
+- neither marker present → inspect the owning `package.json` and nearby repository structure, then ask before making an edition-specific assumption
 
-A sibling repository named `cabloy-start` is the private commercial edition, delivered as a licensed separate source repository and identified by:
-
-- `__CABLOY_START__`
-
-Always detect the active edition before making UI-sensitive assumptions, choosing frontend examples, recommending module-specific workflows, or assuming the project creation path.
+Always perform this detection before making UI-sensitive assumptions, choosing frontend examples, recommending module-specific workflows, or assuming the project creation path.
 
 ## Monorepo layout
 
@@ -18,7 +17,7 @@ Always detect the active edition before making UI-sensitive assumptions, choosin
 - `vona/` contains the backend framework, backend modules, and the Vona CLI.
 - `zova/` contains the frontend framework, frontend modules, and the Zova CLI.
 - `repo-docs/` contains the unified public documentation.
-- `repo-docs-internal/` contains internal engineering notes and ADRs.
+- `repo-docs-internal/`, when present, contains edition-local maintainer notes and ADRs; treat it as optional supporting material, not as a shared-edition requirement.
 - `repo-specs/` contains product and business specifications, delivery plans, and suite-local ADRs.
 - `repo-e2e/` contains the end-to-end test project.
 - `repo-observability/` contains local observability infrastructure.
@@ -39,8 +38,9 @@ Before inventing a custom implementation path:
 ## Documentation boundary
 
 - Put user-facing and agent-facing guidance in `repo-docs/`.
-- Put maintainer rationale, architecture notes, and engineering ADRs in `repo-docs-internal/`.
-- Put product and business specifications, delivery plans, acceptance records, and suite-local ADRs in `repo-specs/`.
+- When an established `repo-docs-internal/` home exists, use it for maintainer rationale, architecture notes, and engineering ADRs. Do not infer or create that path from edition identity alone.
+- If the active repository has no established internal-documentation home, do not block the workflow or move internal rationale into public docs automatically; use existing documentation homes or ask before establishing one.
+- Put product and business specifications, delivery plans, acceptance records, and suite-local ADRs in `repo-specs/` when that repository surface exists.
 - Do not mix internal rationale into public how-to pages unless a trimmed user-facing explanation is genuinely needed.
 
 ## AI development rules
@@ -65,6 +65,7 @@ Before inventing a custom implementation path:
 - In Zova page routes, any route with dynamic `params` must define `route.name`; do not rely on unnamed path-keyed routes for typed `$params`. Static routes should omit `route.name` unless a documented named-route requirement exists; use `$router.getPagePath(...)` for canonical static URL generation rather than adding a name or alias for convenience. Ordinary business routes without `locale` params should omit app-config aliases unless a documented system, compatibility, or user-facing URL exception requires one. Choose `ssrProfile` from the page's rendering contract: Web remains `public` by default, while `session` is an explicit choice for cookie-backed state, protected admission, personalized first paint, or private SSR data; the absence of a locale parameter alone does not select a profile. `requiresAuth` is independent, so anonymous routes must explicitly use `requiresAuth: false`. Regenerate page metadata after route changes.
 - For frontend async state that affects rendering or interaction across consumers, prefer model-owned `$useStateData(...)` over controller-managed fetch/cache state.
 - Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; it does not prevent query creation, fetches, or hydration-time rendering. If strict readiness is needed later, wait explicitly at the interaction boundary.
+- For render-driving async state, read the current query-owned reactive surface (`query.data` or a model-derived projection); an awaited `query.refetch()` result is valid only for one-shot interaction or orchestration and must not become a parallel ongoing controller/render state owner.
 - In SSR, keep server HTML and the client's hydration-time initial render equivalent. When server rendering intentionally omits private, cookie-unavailable, or browser-only state, keep the same neutral shell or placeholder through hydration and defer its query/load/render branch to an explicit post-hydration, admission, mounted, or interaction boundary.
 - Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
 - Do not modify shared environment identity or ports merely to bypass a busy resource. For intentional parallel worktree setup, follow `repo-docs/fullstack/parallel-worktree-environment.md`; otherwise wait for the shared resource or ask the user. Create or change worktree-local environment overrides only through the explicitly invoked `cabloy-worktree-environment` skill and its confirmation phase, and only in `vona/env/.env.local` and `zova/env/.env.local`; never modify flavor-, mode-, app-mode-, or runtime-specific `.env.*.local` files. The skill derives the standard `APP_NAME`, `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, `DEV_SERVER_HMR_PORT`, and API-derived `API_BASE_URL` tuple only from Git worktree metadata and fixed port baselines; never read or expose `.env*` content while recommending values. Admin and Web are alternative commands using this shared tuple and must not run concurrently in one worktree; use another linked worktree for concurrent use. Detect the active edition before choosing scripts, and never run `npm run init` as an automatic follow-up.
@@ -81,7 +82,7 @@ Before inventing a custom implementation path:
 - When adding a persisted field to an existing backend resource, ask the user whether `vonaModule.fileVersion` should be incremented before changing `meta.version.ts` or the module schema path. If yes, add a new migration version and bump `fileVersion`. If no, keep the current `fileVersion` and fold the schema change into the current version path. Do not assume the versioning strategy without confirmation.
 - In shared-database multitenancy, do not use `table.unique(...)` for business uniqueness. Keep ordinary indexes for lookup performance and enforce tenant-scoped uniqueness in the business layer.
 - In Vona, a tenant corresponds to an instance. Ordinary resource-model CRUD is automatically scoped to the active instance; treat records absent from that scope as absent, and do not use raw cross-instance probes merely to choose between `403` and not-found behavior. Model future multi-merchant boundaries explicitly inside an instance.
-- Model cross-Model query-cache dependencies as one directed, acyclic `modelsClear` / `modelsClearedBy` graph, and verify source mutations refresh warmed dependent queries; read `repo-docs-internal/architecture/vona-cross-model-query-cache-dependencies.md` before designing a nontrivial graph.
+- Model cross-Model query-cache dependencies as one directed, acyclic `modelsClear` / `modelsClearedBy` graph, and verify source mutations refresh warmed dependent queries; follow [Cross-model query-cache dependencies](repo-docs/backend/cache-guide.md#cross-model-query-cache-dependencies) before designing a nontrivial graph.
 - For `@Api.field(...)` and related schemaLike composition, framework guards now preserve previously attached OpenAPI metadata across schema rebuilds, but structure-shaping schemaLike is still order-sensitive. Treat `v.object(...)`, `v.array(...)`, `v.optional()`, `v.nullable()`, `v.default(...)`, and preprocess/transform wrappers as structure-shaping; keep the final structure-defining schemaLike last and verify emitted schema/OpenAPI output after such edits.
 - `@Core.transaction(...)` defaults to `REQUIRED`: it starts a transaction only when none exists and otherwise joins the current datasource transaction without upgrading its isolation. Prefer it over manual `inTransaction` wrappers for atomic service methods; use `REQUIRES_NEW` only when an independently committed boundary is explicitly required.
 - For replay-safe transient failures, use `@Core.retryable(...)` with an explicit `errorCodes` allowlist. It retries the downstream AOP suffix, so place it closest to the method when it must wrap and retry a `@Core.transaction(...)` boundary; use `ownerOnly: true` for dual-role leaves that must not retry inside a caller-owned transaction; do not retry external side effects or infer retryability from isolation level.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.149",
+  "version": "5.1.151",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -23,7 +23,6 @@
   "scripts": {
     "init": "node scripts/init.ts",
     "init:test-data": "node scripts/initTestData.ts",
-    "test:scripts": "node --test scripts/initAppName.test.ts",
     "upgrade": "node scripts/upgrade.ts",
     "upgrade:dry-run": "node scripts/upgrade.ts --dry-run",
     "vona": "node ./vona/packages-cli/cli/src/bin/vona.ts --projectPath=vona",
@@ -57,6 +56,9 @@
     "format:fix": "oxfmt --write",
     "lint": "oxlint --disable-nested-config",
     "lint:fix": "oxlint --disable-nested-config --fix",
+    "test:spec-charts": "node --test .claude/skills/cabloy-spec-generation/scripts/generate-implementation-charts.test.mjs",
+    "spec:charts": "node ./.claude/skills/cabloy-spec-generation/scripts/generate-implementation-charts.mjs",
+    "spec:charts:check": "node ./.claude/skills/cabloy-spec-generation/scripts/generate-implementation-charts.mjs --check",
     "docs:dev": "pnpm --dir repo-docs docs:dev",
     "docs:build": "pnpm --dir repo-docs docs:build",
     "docs:preview": "pnpm --dir repo-docs docs:preview",

package/repo-docs/.vitepress/config.mjs

@@ -292,6 +292,10 @@ export default defineConfig({
           text: 'Data & CRUD',
           items: [
             { text: 'CRUD Workflow', link: '/backend/crud-workflow' },
+            {
+              text: 'Existing Resource Field Update',
+              link: '/backend/resource-field-update',
+            },
             { text: 'Migration and Changes', link: '/backend/migration-and-changes' },
             { text: 'Field Indexes', link: '/backend/field-indexes' },
             { text: 'ORM Guide', link: '/backend/orm-guide' },

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

@@ -38,11 +38,11 @@ Public docs answer questions like:
 - how does Zova page or model architecture work?
 - what is different between Cabloy Basic and Cabloy Start?
 
-### 2. Internal engineering docs
+### 2. Optional internal engineering docs
 
 Location:
 
-- `repo-docs-internal/`
+- an established internal-documentation home, when the active repository provides one
 
 Use internal docs for:
 
@@ -51,7 +51,7 @@ Use internal docs for:
 - maintenance boundaries
 - “why this design exists” notes that do not belong in public user docs
 
-Internal docs answer questions like:
+When available, internal docs answer questions like:
 
 - why were docs and internal notes separated?
 - why is AI enablement structured this way?
@@ -105,7 +105,7 @@ Skills answer questions like:
 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 maintainer rationale or long-lived design history, use an established internal-documentation home when one exists; otherwise ask before establishing one
 - 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**
@@ -128,7 +128,7 @@ Use this quick rule:
 ### Example: “How should a backend base class be placed?”
 
 - public operational explanation → [Class Placement Rule](/ai/class-placement-rule)
-- maintainer rationale and invariants → `repo-docs-internal/architecture/class-placement-a-b1-b2.md`
+- maintainer rationale and invariants → an established internal-documentation home, when available
 - default repo-wide behavior → `CLAUDE.md`
 - procedural decision workflow → `cabloy-workflow` skill
 
@@ -153,7 +153,7 @@ Use this quick rule:
 ### Example: “How should AI remove an existing module cleanly?”
 
 - public operational explanation → [Playbook: Module Removal](/ai/playbook-module-removal)
-- maintainer rationale and pitfalls → `repo-docs-internal/architecture/module-removal-workflow.md`
+- maintainer rationale and pitfalls → an established internal-documentation home, when available
 - avoid putting the full workflow in `CLAUDE.md` because the task needs branching, cleanup order, generated-runtime recovery, and verification
 - procedural decision workflow → `cabloy-module-removal` skill
 

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

@@ -85,7 +85,7 @@ Primary dependencies:
 
 - Vona entity / migration / DTO workflow knowledge
 - Zova metadata/build flows when renderer follow-up is involved
-- the backend resource field workflow note in `repo-docs-internal/`
+- [Existing Resource Field Update](/backend/resource-field-update)
 
 ### 5. Metadata refresh skill
 
@@ -148,7 +148,7 @@ The purpose is to create a small number of high-leverage skills that directly re
 
 - `repo-docs/`
 - `CLAUDE.md`
-- `repo-docs-internal/`
+- an established internal-documentation home, when present
 - `.claude/skills/`
 - the Vona and Zova CLIs
 

package/repo-docs/ai/introduction.md

@@ -8,7 +8,7 @@ The Cabloy monorepo is a good fit for AI vibe coding because the source tree alr
 - Vona CLI source and command groups
 - Zova CLI source and command groups
 - archived docs that still capture valuable concepts
-- internal engineering docs for maintainers
+- optional internal engineering docs for maintainers when the active repository provides them
 - Claude commands and skills
 
 ## The main design goal
@@ -20,7 +20,7 @@ The goal is to make AI **reuse the repo’s existing conventions directly**, esp
 - CLI commands
 - root scripts
 - repo markers
-- internal architecture notes
+- optional internal architecture notes when the active repository provides them
 - shared public documentation
 
 ## How to approach AI work
@@ -29,7 +29,7 @@ For contributor and automation workflows in this repository, prefer this order:
 
 1. inspect the active edition and repo markers before making UI-sensitive or workflow-sensitive assumptions
 2. inspect root scripts, Vona CLI, and Zova CLI before inventing manual scaffolding or custom workflow steps
-3. use public docs for durable user-facing guidance and `repo-docs-internal/` for maintainer rationale
+3. use public docs for durable user-facing and agent-facing guidance; consult an established internal-documentation home only when the active repository provides one for maintainer rationale
 4. encode repeatable behavior in Claude rules, commands, or skills instead of relying on unstated habits
 
 ## The knowledge layers
@@ -40,9 +40,9 @@ Use `repo-docs/` for user-facing and agent-facing guidance that should remain du
 
 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
+### Optional internal engineering docs
 
-Use `repo-docs-internal/` for architecture notes, ADRs, and maintainership rationale that should not be mixed into public how-to documentation.
+When an established internal-documentation home exists, use it for architecture notes, ADRs, and maintainer rationale that should not be mixed into public how-to documentation. Its absence must not block a shared workflow or cause internal rationale to be moved into public how-to documentation automatically.
 
 ### Claude rules and commands
 

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

@@ -52,17 +52,11 @@ Before regenerating frontend artifacts:
 
 ## Step 4: Regenerate the frontend-side contract artifacts
 
-Use the Zova OpenAPI and REST-generation path rather than manually updating request code first.
+Use the Zova OpenAPI and REST-generation path rather than manually updating request code first. Follow the canonical [Contract Loop Playbook](/fullstack/contract-loop-playbook#forward-chain-playbook) for the active edition’s complete generation and verification sequence.
 
-Representative commands may include:
+Do not treat `build:rest:*` as a standalone current command recipe. Resolve the active edition’s full build path from the canonical playbook and current root scripts so SSR bundle and REST output stay synchronized.
 
-```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.
+For Start, resolve Start-specific flavor paths from that repository.
 
 ## Step 5: Inspect affected frontend layers
 

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

@@ -8,10 +8,10 @@ Check the root repository signals first:
 
 - `package.json`
 - edition marker files such as `__CABLOY_BASIC__` or `__CABLOY_START__`
-- `repo-docs-internal/README.md`
+- an established internal-documentation home, when present
 - root `.claude/` assets
 
-These files tell the agent which repo it is in, which scripts are canonical, and where public versus internal documentation belongs.
+These surfaces tell the agent which repo it is in and which scripts are canonical. Inspect an internal-documentation home only when the active repository actually provides one.
 
 ## 2. Prefer framework entrypoints over scattered examples
 
@@ -27,10 +27,11 @@ For frontend workflows:
 
 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
+## 3. Use public docs and optional internal notes for different purposes
 
 - use `repo-docs/` to explain how people and agents should work
-- use `repo-docs-internal/` to explain why maintainers designed the repo a certain way
+- when an established internal-documentation home exists, use it for maintainer rationale
+- when it does not exist, continue from public docs, rules, skills, source, and tests; do not create a new documentation home implicitly
 
 ## 4. Treat edition detection as mandatory for UI-sensitive work
 

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

@@ -8,7 +8,7 @@ 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
+- whether an established internal-documentation home is available
 - which command entrypoints are preferred
 - why edition detection is mandatory before UI-sensitive guidance or project-creation assumptions
 
@@ -26,4 +26,4 @@ Use Claude settings for permissions and execution environment, not as the primar
 
 ## 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 `repo-docs-internal/`.
+If a rule is important for people and agents to understand, it probably belongs in public docs too. When an established internal-documentation home exists, it may hold maintainer rationale rather than user-facing workflow. Do not infer or create such a home from edition identity alone.

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

@@ -201,6 +201,4 @@ Read these pages together:
 - [Global Bean Lookup](/ai/global-bean-lookup)
 - [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping)
 
-For maintainer-level rationale, also read:
-
-- `repo-docs-internal/architecture/virtual-decorator-runtime-semantics.md`
+For maintainer-level rationale, consult an established internal-documentation home when the active repository provides one. The public guidance above is the complete shared operational rule.

package/repo-docs/backend/cache-guide.md

@@ -52,6 +52,42 @@ Representative areas include:
 - related-model cache clearing
 - custom cache-clearing logic
 
+## Cross-model query-cache dependencies
+
+When a mutation in one Model changes the members, totals, projections, includes, or visibility of a query cached by another Model, declare an explicit cross-model dependency. Decide this from **query-result semantics**, not merely from a relation or foreign key.
+
+### Choose one directed declaration
+
+Express each dependency as one source-to-target edge:
+
+- `modelsClear` declares targets from the source Model;
+- `modelsClearedBy` declares sources from the target Model.
+
+They normalize to the same direction. Choose the form that makes local ownership clearest, but never declare both forms for the same edge.
+
+### Keep the graph acyclic
+
+Keep the dependency graph directed, acyclic, and free of duplicate edges. A normal target clear can propagate transitively to its own dependent query caches, so reverse or duplicate declarations are not a way to increase reliability.
+
+The default behavior clears affected **query caches**. It does not make a cross-Model entity cache relationship, replace a lock, enforce uniqueness, or create a transaction boundary.
+
+### Use custom clearing deliberately
+
+`modelsClearedByFn` replaces the normal target-clear behavior for that dependency. When using it, explicitly own the target clear and any required downstream propagation. Do not add it as if it were an additional callback around the normal path.
+
+Prefer normal Model or service mutation paths so source invalidation, transaction-aware re-clearing, and configured cache behavior remain active.
+
+### Verify a warmed dependent query
+
+For every new dependency path, add a regression test that:
+
+1. warms the dependent Model query;
+2. mutates the source through the normal Model or service path;
+3. repeats the dependent query;
+4. proves that the result now reflects the mutation.
+
+This test demonstrates business invalidation rather than relying on test-runner scheduling or cache implementation assumptions.
+
 ## Consistency strategy
 
 Vona also clears or compensates cache automatically when model mutation occurs.

package/repo-docs/backend/dto-guide.md

@@ -183,7 +183,7 @@ A practical split is:
 - use inferred DTOs when the contract closely follows model structure or query shape
 - wrap inferred DTOs in a named DTO class when reuse or discoverability becomes more important
 
-When stable Entity, Model, relation, or query truth already exists, prefer inference first: use `$Dto.*` with `columns`, `include`, or `dtoClass` to define the projection; use `@Dto({ fields })` with `$makeMetadata(...)` for metadata-only differences or `$makeSchema(...)` for schema and validation differences; add an `@Api.field(...)` member only for a genuinely new field absent from the inferred contract. Keep an explicit DTO as a deliberate fallback when no suitable upstream truth exists or the inferred composition is less clear.
+When stable Entity, Model, relation, or query truth already exists, prefer inference first: use `$Dto.*` with `columns`, `include`, or `dtoClass` to define the projection; use `@Dto({ fields })` with `$makeMetadata(...)` only for metadata-only differences on an existing inferred/projected field, or `$makeSchema(...)` for schema and validation differences. A true virtual `fields` key absent from that projection must use `$makeSchema(...)` with a final concrete `z.<type>()` schema; `fieldSource(...)` maps its binding but supplies no type. Add an `@Api.field(...)` member only for a genuinely new declared DTO property. See [Virtual fields in the DTO fields map](/backend/dto-infer-generation#virtual-fields-in-the-dto-fields-map) for the full decision rule. Keep an explicit DTO as a deliberate fallback when no suitable upstream truth exists or the inferred composition is less clear.
 
 Advanced inferred DTO shaping can also stay named and reusable through helper options such as `dtoClass`, especially for relation-aware contracts and nested DTO surfaces. `$Dto.get(...)` otherwise keeps the complete model-aware read shape by default; use `columns` or `dtoClass` for a genuine business projection, not merely to remove `iid` or `deleted`. For the canonical authoring sequence, see [Default-first three-layer DTO authoring](/backend/dto-infer-generation#default-first-three-layer-dto-authoring) and [Default read shape versus a public projection](/backend/dto-infer-generation#default-read-shape-versus-a-public-projection).
 
@@ -205,11 +205,12 @@ When creating DTOs:
 
 1. check whether an Entity, Model, relation, or query shape already provides suitable upstream contract truth
 2. define the inferred projection before redeclaring fields: choose the `$Dto.*` helper and, where needed, `columns`, `include`, or `dtoClass`
-3. use `$makeMetadata(...)` for metadata-only refinement and `$makeSchema(...)` for schema or validation refinement of an inferred field
-4. use `@Api.field(...)` for a genuinely new field, not as a second declaration of an inferred field
-5. keep DTO validation and OpenAPI concerns aligned, and keep the final structure-defining schema last when using schema-like composition
-6. decide whether the contract should remain inferred, be wrapped in a named inferred DTO, or deliberately fall back to an explicit DTO
-7. treat DTO design as part of the contract between backend handlers, models, and frontend integration
+3. use `$makeMetadata(...)` for metadata-only refinement and `$makeSchema(...)` for schema or validation refinement of an inferred/projected field
+4. for a true virtual key added only through `@Dto({ fields })`, use `$makeSchema(...)` with a final concrete `z.<type>()` schema; `fieldSource(...)` supplies no missing type
+5. use `@Api.field(...)` for a genuinely new declared DTO property, not as a second declaration of an inferred field
+6. keep DTO validation and OpenAPI concerns aligned, and keep the final structure-defining schema last when using schema-like composition
+7. decide whether the contract should remain inferred, be wrapped in a named inferred DTO, or deliberately fall back to an explicit DTO
+8. treat DTO design as part of the contract between backend handlers, models, and frontend integration
 
 ## Where to read next
 

package/repo-docs/backend/dto-infer-generation.md

@@ -193,6 +193,25 @@ export class DtoStudentSelectReq extends $Dto.queryPage(EntityStudent, [
 
 Framework DTO composition preserves inherited OpenAPI metadata when a field schema is refined. That includes metadata such as titles, render information, and scene identity. It does **not** make structure-shaping schema-like arguments order-independent: keep the final structure-defining argument last and verify the effective schema rather than assuming a metadata merge can repair a reordered schema.
 
+#### Virtual fields in the DTO fields map
+
+The Layer 2 `$makeMetadata(...)` rule has a precondition: the field key must already be supplied by the inferred projection, whether through the `$Dto.*` base, `columns`, `include`, or `dtoClass`. It overlays metadata on that existing runtime schema.
+
+A **true virtual DTO field** is a key added only through `@Dto({ fields })` and absent from that inherited projection. Define such a key with `$makeSchema(...)` and a final concrete Zod schema, even when its purpose is only to map a renderer to a nested source:
+
+```typescript
+const descriptionMarkdownField = $makeSchema(
+  ZovaRender.fieldSource('content.descriptionMarkdown'),
+  ZovaRender.field('basic-markdown:formFieldMarkdown'),
+  v.optional(),
+  z.string(),
+);
+```
+
+`z.string()` establishes the virtual key's validation and emitted OpenAPI type. `fieldSource(...)` only maps the DTO-facing key to the canonical source path used by downstream schema-driven UI; it does not supply a type. `$makeMetadata(...)` alone has no inherited schema to overlay for a true virtual key, so its metadata is attached to an unconstrained fallback rather than a meaningful field schema.
+
+Use a class-body `@Api.field(...)` member instead when the new field should be a declared, statically typed DTO property rather than a contract-only `fields`-map key.
+
 `@Dto({ fields })` changes the runtime contract and metadata. It does not rewrite the TypeScript property type inferred from the `$Dto.*` base class. Do not add a duplicate `declare` field or a second field decorator solely to mirror a runtime schema restriction unless a separate static contract is genuinely required and is type-compatible with the inferred base.
 
 ### Layer 3: add contract-only fields
@@ -507,10 +526,11 @@ When evaluating a return shape or input contract that closely follows model stru
 2. is the contract get/list/query/create/update/aggregate/group oriented, and which `$Dto.*` helper matches it?
 3. should `columns`, `include`, `with`, or `dtoClass` define the projection boundary?
 4. should the inferred DTO stay inline or be wrapped in a named DTO class?
-5. for every local difference, is it metadata-only (`$makeMetadata(...)`) or schema-affecting (`$makeSchema(...)`)?
-6. is every `@Api.field(...)` member genuinely new instead of a redeclared inferred field?
-7. if `$makeSchema(...)` is used, is the structure-defining schema last and is emitted schema/OpenAPI verification planned?
-8. does the resulting DTO also affect OpenAPI and frontend generation paths?
-9. is CRUD generation already giving enough contract structure that another handwritten DTO would be redundant, or is an explicit DTO clearer?
+5. for every local difference, does the `fields` key already have an inferred/projected schema, or is it a true virtual key?
+6. use `$makeMetadata(...)` only for metadata-only refinement of an inferred/projected field; define every true virtual key with `$makeSchema(...)` and a final concrete `z.<type>()` schema
+7. is every `@Api.field(...)` member genuinely new instead of a redeclared inferred field?
+8. if `$makeSchema(...)` is used, is the structure-defining schema last and is emitted schema/OpenAPI verification planned?
+9. does the resulting DTO also affect OpenAPI and frontend generation paths?
+10. is CRUD generation already giving enough contract structure that another handwritten DTO would be redundant, or is an explicit DTO clearer?
 
 That helps reduce redundant type work and keeps contracts closer to the model truth.

package/repo-docs/backend/introduction.md

@@ -19,7 +19,7 @@ For contributor and automation workflows in this repository, prefer this order:
 1. inspect the root `package.json` and `npm run vona` entrypoint
 2. inspect Vona CLI command families such as `create:*`, `init:*`, `tools:*`, and `bin:*`
 3. inspect the current module or suite layout before creating new files manually
-4. use public docs for user-facing guidance and `repo-docs-internal/` for maintainer rationale
+4. use public docs for user-facing and agent-facing guidance; consult an established internal-documentation home only when the active repository provides one for maintainer rationale
 
 ## Backend reading paths