cabloy 5.1.151 → 5.1.153

package/.cabloy-version

@@ -1 +1 @@
-5.1.151
+5.1.153

package/.claude/skills/cabloy-module-removal/SKILL.md

@@ -129,7 +129,7 @@ Ask or confirm whether the task is:
 - code/runtime removal only
 - code/runtime removal plus docs/examples scrub
 
-If docs cleanup is in scope, update `repo-docs/` separately from the runtime cleanup. When an established `repo-docs-internal/` home exists, keep maintainer rationale there; otherwise do not create or require that path as part of module removal.
+If docs cleanup is in scope, update `repo-docs/` separately from the runtime cleanup. Keep maintainer rationale in `repo-docs-internal/`; do not require a particular internal record as part of module removal.
 
 ## Response pattern
 

package/.claude/skills/cabloy-resource-field-update/SKILL.md

@@ -217,7 +217,7 @@ Use these portable references:
 - `references/custom-renderer-demo-checklist.md`
 - [Existing Resource Field Update](../../../repo-docs/backend/resource-field-update.md)
 
-When an active repository provides `repo-docs-internal/architecture/backend-resource-field-workflow.md`, it may be consulted as optional maintainer rationale. Its absence must not block or alter this shared workflow.
+When relevant and available in the active edition, `repo-docs-internal/architecture/backend-resource-field-workflow.md` may be consulted as optional maintainer rationale. Its absence must not block or alter this shared workflow.
 
 Recommended shape:
 

package/.claude/skills/cabloy-spec-generation/SKILL.md

@@ -173,7 +173,7 @@ Optional records remain subordinate to the PRD/SRS/WBS/test-plan authority appro
 
 While drafting, preserve these principles and tailor them to confirmed scope:
 
-- `repo-specs/` is the product/business planning home; `repo-docs/` is public and agent-facing framework guidance; an established `repo-docs-internal/` home may hold cross-suite maintainer rationale; `.claude/skills/` is workflow behavior; do not assume or create an internal-docs home in an edition that lacks one;
+- `repo-specs/` is the product/business planning home; `repo-docs/` is public and agent-facing framework guidance; `repo-docs-internal/` holds supporting cross-suite maintainer rationale; `.claude/skills/` is workflow behavior; do not assume a particular internal record exists in every edition;
 - use suite-first ownership and distinguish new domain modules from reusable framework modules; do not duplicate an existing persistence or identity owner without a stated decision;
 - treat the active Vona instance as the tenant by default; do not introduce a store, organization, or merchant entity unless the confirmed domain contract requires it;
 - make identity, tenant scope, authorization, and ownership server-authoritative; menus, routes, browser filters, and UI visibility are not API authorization;

package/.claude/skills/cabloy-spec-generation/references/repo-aware-discovery.md

@@ -82,7 +82,7 @@ Hand actual implementation-time synchronization to `cabloy-contract-loop`.
 | --- | --- |
 | Product requirements, SRS contracts, WBS, ATPs, suite ADRs, delivery status | `repo-specs/<suite>/` |
 | Reusable user-facing or agent-facing framework guidance | `repo-docs/` |
-| Cross-suite maintainer architecture, rationale, and engineering ADRs | An established internal-documentation home, when present; do not create one implicitly |
+| Cross-suite maintainer architecture, rationale, and engineering ADRs | `repo-docs-internal/`; individual records may vary by edition |
 | Short durable AI operating rules | `CLAUDE.md` |
 | Reusable Claude procedure | `.claude/skills/` |
 

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, 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.
+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.
 ---
 
 # Cabloy Workflow
@@ -31,13 +31,12 @@ Interpretation:
 
 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:
+Documentation-root policy 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
+- `repo-docs-internal/` is the internal documentation home in Cabloy Basic and Cabloy Start
+- inspect a specific internal record before recommending or reading it
+- treat relevant edition-local internal records as supporting maintainer material, never as a prerequisite for shared workflow routing
+- when a specific record is unavailable or irrelevant, continue from public docs, bundled skill references, active source, and tests
 
 ## Step 2: Identify the task layer
 
@@ -79,7 +78,7 @@ Use the frontend path when the task is about:
 Use the docs/AI path when the task is about:
 
 - `repo-docs/`
-- an established `repo-docs-internal/` home when present
+- `repo-docs-internal/`
 - `CLAUDE.md`
 - `.claude/commands/`
 - `.claude/skills/`
@@ -94,7 +93,7 @@ Before inventing a workflow, inspect these shared surfaces:
 - `npm run zova`
 - root `CLAUDE.md` if present
 - `repo-docs/` for public guidance
-- an established `repo-docs-internal/` home for optional maintainer rationale
+- `repo-docs-internal/` for supporting maintainer rationale
 
 If the request spans backend and frontend, classify it as fullstack by default unless the user clearly wants only one side.
 
@@ -167,16 +166,16 @@ Use `repo-docs/` for:
 - reusable AI-facing workflow guidance
 - edition-aware public documentation
 
-### Optional internal engineering docs
+### `repo-docs-internal/`
 
-When an established `repo-docs-internal/` home exists, it may be used for:
+Use `repo-docs-internal/` 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.
+Relevant internal records support routing and implementation but do not block them: shared public guidance remains complete, and individual records may be unavailable or irrelevant in the active edition.
 
 ### Root rules and commands
 
@@ -208,7 +207,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/`
-- 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
+- put supporting rationale and invariants in `repo-docs-internal/`; preserve the public operational explanation when a particular internal record is unavailable or irrelevant
 - 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
 
@@ -287,7 +286,7 @@ Verify:
 
 - referenced paths exist
 - command names still exist
-- public docs, optional internal rationale, and rules tell a consistent story
+- public docs, `repo-docs-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, 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.",
+      "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 shared operational guidance to public docs and Claude rules/skills as appropriate, routes supporting maintainer rationale to repo-docs-internal, and reinforces the CLI-first principle without making an individual internal record a requirement.",
       "files": []
     },
     {
@@ -51,8 +51,8 @@
     },
     {
       "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.",
+      "prompt": "I am in a Cabloy checkout where repo-docs-internal exists, but the named architecture record I expected is not available in this edition. I need shared agent guidance and some maintainer rationale. Where should each part go?",
+      "expected_output": "Recognizes repo-docs-internal as the internal documentation home, routes shared operational guidance to public docs and Claude rules or skills, and treats the missing named record as non-blocking rather than inventing a replacement or moving rationale into public docs automatically.",
       "files": []
     }
   ]

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 5.1.153
+
+### Features
+
+- Add an option to disable Suspense during initialization.
+- Add support for bypassing the persister.
+
+### Improvements
+
+- Update table cell action summary handling.
+- Improve query summary Suspense documentation.
+- Update state data best-practices documentation.
+- Enhance internal repository documentation and specification-generation guidance.
+
+## 5.1.152
+
+### Improvements
+
+- Update project guidance in `CLAUDE.md`.
+
 ## 5.1.151
 
 ### Features

package/CLAUDE.md

@@ -17,7 +17,7 @@ Always perform this detection before making UI-sensitive assumptions, choosing f
 - `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/`, when present, contains edition-local maintainer notes and ADRs; treat it as optional supporting material, not as a shared-edition requirement.
+- `repo-docs-internal/` contains edition-local maintainer notes and ADRs; treat relevant records as 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.
@@ -38,8 +38,7 @@ Before inventing a custom implementation path:
 ## Documentation boundary
 
 - Put user-facing and agent-facing guidance in `repo-docs/`.
-- 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 maintainer rationale, architecture notes, and engineering ADRs in `repo-docs-internal/`. Treat relevant records as supporting material: shared workflows remain complete without any particular internal record, which may vary by edition.
 - 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.
 
@@ -68,6 +67,7 @@ Before inventing a custom implementation path:
 - 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/`.
+- After implementation, do not launch broad reviews automatically; when review is needed, scope it to the current diff and report only high-confidence issues.
 - 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.
 - For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
 - In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.151",
+  "version": "5.1.153",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

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

@@ -23,6 +23,11 @@ const aiItems = [
   { text: 'Playbook: Backend Module', link: '/ai/playbook-backend-module' },
   { text: 'Playbook: Frontend Page', link: '/ai/playbook-frontend-page' },
   { text: 'Playbook: Contract Regeneration', link: '/ai/playbook-contract-regeneration' },
+  { text: 'Playbook: Plan a Suite Specification', link: '/ai/playbook-spec-generation' },
+  {
+    text: 'Playbook: Execute an Approved Specification Increment',
+    link: '/ai/playbook-spec-execution',
+  },
   { text: 'Playbook: Module Removal', link: '/ai/playbook-module-removal' },
   { text: 'Playbook: Metadata Refresh', link: '/ai/playbook-metadata-refresh' },
   { text: 'Playbook: Technical Blog Authoring', link: '/ai/playbook-technical-blog-authoring' },

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

@@ -122,6 +122,25 @@ Typical skill role:
 
 - notice when route/component/icon changes require metadata regeneration
 
+## Repository planning and derived-chart scripts
+
+Not every skill maps to a Vona or Zova generator. Repository-native suite specifications are authored under `repo-specs/`; no CLI generates the complete planning authority set.
+
+In the current Cabloy Basic repository, these root scripts refresh and check derived planning views:
+
+```bash
+npm run spec:charts -- <suite>
+npm run spec:charts:check -- <suite>
+```
+
+They generate or validate the Gantt and burndown SVGs from authoritative planning records. They do not replace PRD/SRS/WBS/ATP updates, implement a WBS task, execute an ATP, or create evidence. Confirm scripts in the active repository before using them for another edition.
+
+Typical skill roles:
+
+- `cabloy-spec-generation` creates or updates planning authority only after confirmation, then refreshes derived charts after relevant record changes
+- `cabloy-spec-execution` coordinates one approved increment, records evidence before derived progress, then refreshes and checks charts
+- source implementation remains routed to Vona, Zova, contract-loop, or other specialist workflows
+
 ## Example mappings
 
 ### Example: “Create a student CRUD backend thread”

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. Optional internal engineering docs
+### 2. Internal engineering docs
 
 Location:
 
-- an established internal-documentation home, when the active repository provides one
+- `repo-docs-internal/`
 
 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
 
-When available, internal docs answer questions like:
+Relevant internal records 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, use an established internal-documentation home when one exists; otherwise ask before establishing one
+- if it is maintainer rationale or long-lived design history, use `repo-docs-internal/`; shared guidance remains complete without any particular internal record
 - 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 → an established internal-documentation home, when available
+- maintainer rationale and invariants → `repo-docs-internal/`
 - 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 → an established internal-documentation home, when available
+- maintainer rationale and pitfalls → `repo-docs-internal/`
 - 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
 
@@ -165,6 +165,21 @@ Use this quick rule:
 - avoid putting the full branching workflow in `CLAUDE.md` because the task needs proposal, validation, confirmation, and CLI handoff
 - procedural decision workflow → `cabloy-domain-planning` skill
 
+### Example: “How should AI create or maintain a repository-native suite specification?”
+
+- public workflow explanation → [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation)
+- procedural planning, confirmation, traceability, and chart-refresh behavior → `cabloy-spec-generation`
+- suite-specific PRD, SRS, WBS, ATP, ADR, progress, and observed evidence authority → `repo-specs/<suite>/`
+- maintainer rationale → `repo-docs-internal/`
+- implementation is not implied by creating planning records
+
+### Example: “How should AI deliver an approved suite task?”
+
+- public workflow explanation → [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+- bounded-WBS coordination, readiness gates, evidence, and derived-status behavior → `cabloy-spec-execution`
+- source implementation → the relevant backend, frontend, contract-loop, or shape-specific skill
+- product, contract, dependency, scope, or durable-decision changes → return to specification or domain planning
+
 ### Example: “What `@Api.field(...)` ordering rule should AI preserve when mixing helpers and zod?”
 
 - full explanation → [Entity Guide](/backend/entity-guide) and [DTO Guide](/backend/dto-guide)

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

@@ -14,94 +14,39 @@ Current root skills include:
 
 - `cabloy-workflow`
 - `cabloy-domain-planning`
+- `cabloy-spec-generation`
+- `cabloy-spec-execution`
+- `cabloy-backend-scaffold`
+- `cabloy-frontend-scaffold`
 - `cabloy-contract-loop`
 - `cabloy-resource-field-update`
 - `cabloy-module-removal`
+- `cabloy-master-detail`
+- `cabloy-worktree-environment`
+- `cabloy-zova-source-reading`
 
 Their current roles are:
 
 - `cabloy-workflow` → broad workflow selection, edition detection, CLI-first routing, and verification framing
 - `cabloy-domain-planning` → suite-first naming proposals, providerId confirmation, module-boundary suggestions, and scaffold handoff for new business domains
+- `cabloy-spec-generation` → repository-native suite planning authority, traceability, confirmation, and derived planning views
+- `cabloy-spec-execution` → one approved WBS increment through readiness gates, specialist routing, evidence, and derived status
+- `cabloy-backend-scaffold` → Vona implementation routing and CLI-backed backend scaffolding
+- `cabloy-frontend-scaffold` → Zova implementation routing and CLI-backed frontend scaffolding
 - `cabloy-contract-loop` → backend/frontend contract regeneration, reverse-chain handling, and drift diagnosis
 - `cabloy-resource-field-update` → existing backend resource-field changes with `fileVersion` and renderer-aware follow-up
 - `cabloy-module-removal` → backend/frontend/fullstack module deletion order, generated-runtime cleanup, and verification
+- `cabloy-master-detail` → coordinated master-detail resource workflow
+- `cabloy-worktree-environment` → confirmed worktree-local environment tuple setup for intentional parallel work
+- `cabloy-zova-source-reading` → Zova-first source reading and Vue comparison workflow
 
 This is now a stronger foundation skill set, but it still leaves several useful workflow families for future specialization.
 
 ## Recommended next skill families
 
-### 1. Backend scaffold skill
+The backend scaffold, frontend scaffold, contract-loop, resource-field-update, and metadata-refresh workflow families already have implemented specialist coverage. Future work should refine those skills only when a new repository-wide branch or stable verification need emerges.
 
-Purpose:
-
-- scaffold Vona controller/service/model/entity/dto/CRUD threads
-- choose between bean creation and CRUD generation
-- verify migration/test implications
-
-Primary dependencies:
-
-- Vona `create:*`
-- Vona `tools:*`
-- backend docs in `repo-docs/backend/`
-
-### 2. Frontend scaffold skill
-
-Purpose:
-
-- scaffold Zova pages/components/API/models
-- branch correctly between Basic and Start
-- use create/refactor commands before manual edits
-
-Primary dependencies:
-
-- Zova `create:*`
-- Zova `refactor:*`
-- frontend docs in `repo-docs/frontend/`
-
-### 3. Fullstack contract loop skill
-
-Purpose:
-
-- detect backend contract changes
-- regenerate OpenAPI/SDK-related output
-- verify backend/frontend contract alignment
-
-Primary dependencies:
-
-- Vona OpenAPI and validation docs
-- Zova OpenAPI SDK and server-data docs
-- fullstack collaboration docs
-
-### 4. Resource field update skill
-
-Purpose:
-
-- handle updates to fields on existing backend resources
-- force the right `fileVersion` decision for new persisted fields
-- branch correctly between shared renderer reuse and custom renderer demo follow-up
-- verify entity, locale, migration, test, metadata, build, and dependency-sync implications
-
-Primary dependencies:
-
-- Vona entity / migration / DTO workflow knowledge
-- Zova metadata/build flows when renderer follow-up is involved
-- [Existing Resource Field Update](/backend/resource-field-update)
-
-### 5. Metadata refresh skill
-
-Purpose:
-
-- detect when route/component/icon or related changes require metadata regeneration
-- run the right metadata flow
-- verify generated artifacts belong to the active edition
-
-Primary dependencies:
-
-- Zova `tools:*`
-- CLI-to-skill mapping
-- edition detection docs
-
-### 6. Distributed backend workflow skill
+### 1. Distributed backend workflow skill
 
 Purpose:
 
@@ -148,7 +93,7 @@ The purpose is to create a small number of high-leverage skills that directly re
 
 - `repo-docs/`
 - `CLAUDE.md`
-- an established internal-documentation home, when present
+- `repo-docs-internal/`
 - `.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
-- optional internal engineering docs for maintainers when the active repository provides them
+- `repo-docs-internal/` engineering docs for maintainers
 - 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
-- optional internal architecture notes when the active repository provides them
+- relevant `repo-docs-internal/` architecture notes
 - 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 and agent-facing guidance; consult an established internal-documentation home only when the active repository provides one for maintainer rationale
+3. use public docs for durable user-facing and agent-facing guidance; consult relevant `repo-docs-internal/` records for supporting 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.
 
-### Optional internal engineering docs
+### `repo-docs-internal/` engineering docs
 
-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.
+Use `repo-docs-internal/` for architecture notes, ADRs, and maintainer rationale that should not be mixed into public how-to documentation. Relevant records support a shared workflow without being prerequisites; an unavailable or irrelevant individual record must not cause its rationale to be moved into public how-to documentation automatically.
 
 ### Claude rules and commands
 
@@ -66,6 +66,16 @@ Start here when the task is about choosing the right repo surface, docs location
 - [Skills](/ai/skills)
 - [Rules and Config](/ai/rules-and-config)
 
+### Specification planning and delivery path
+
+Use this path to establish suite authority before implementation, then deliver one approved, bounded WBS increment with evidence-backed status:
+
+- [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation)
+- [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+- [Skills](/ai/skills)
+- [Repo Scripts](/reference/repo-scripts)
+- [Verification](/ai/verification)
+
 ### Framework implementation path
 
 Use this path when the task is about implementing or reviewing Cabloy code with repo-aware rules: