cabloy 5.1.150 → 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,24 @@
 # 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

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
@@ -82,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.150",
+  "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/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
 

package/repo-docs/backend/migration-and-changes.md

@@ -48,6 +48,31 @@ The key rule is:
 
 In the scaffolded CRUD workflow, this is not an isolated maintenance step. The generator-driven thread treats `fileVersion` as part of the same backend evolution path that also touches entity/model/controller/test resources.
 
+## Decide whether to increment fileVersion
+
+For a new persisted field or another schema-shape change on an existing resource, decide whether `vonaModule.fileVersion` should change **before** editing `meta.version.ts`, a versioned schema path, or the module `package.json`.
+
+### Increment fileVersion
+
+Choose a new migration version when the change must be applied sequentially to an existing released module:
+
+1. increment `fileVersion`;
+2. add a new migration branch;
+3. preserve older branches as historical snapshots;
+4. introduce the schema change in the new branch.
+
+Do not introduce the same column in an older create path and again in a later migration branch. A fresh installation can execute version branches sequentially and fail on a duplicate column.
+
+### Keep the current fileVersion
+
+When the change belongs in the current version path rather than new migration history:
+
+1. keep the existing `fileVersion`;
+2. fold the schema change into the current version path;
+3. do not create a new migration branch.
+
+Ask before choosing this strategy; do not infer migration history from the field change alone. Any change to `meta.version.ts` requires `npm run test` so the test database is recreated and schema/data consistency is exercised.
+
 ## `meta.version`
 
 Vona uses a bean named `meta.version` to organize migration code for a module.
@@ -156,9 +181,9 @@ When the generated CRUD thread evolves, migration should evolve with it.
 
 A practical sequence is:
 
-1. increment `fileVersion`
+1. decide whether to increment `fileVersion`
 2. add or adjust entity/model structure
-3. update `meta.version` logic
+3. update the current or new `meta.version` path to match that decision
 4. rerun migration locally
 5. verify the contract through tests and controller actions
 

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

@@ -254,7 +254,7 @@ A practical distinction is:
 
 That means model behavior affects performance and consistency semantics, not only data retrieval.
 
-For the broader cache story, also see [Cache Guide](/backend/cache-guide).
+For the broader cache story, also see [Cache Guide](/backend/cache-guide). For dependencies between Models, see [Cross-model query-cache dependencies](/backend/cache-guide#cross-model-query-cache-dependencies).
 
 ## Relationship to the backend contract loop