cabloy 5.1.160 → 5.1.162

package/.cabloy-version

@@ -1 +1 @@
-5.1.160
+5.1.162

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 5.1.162
+
+### Features
+
+- Add a home prompt capability.
+- Document Vona integrated SSR and Zova standalone SSR support.
+
+### Improvements
+
+- Update AI spec-driven development, playbook specification generation, and Cabloy Editions documentation.
+- Refresh the README, quickstart guide, skills documentation, and configuration.
+- Update dependencies and the pnpm lockfile.
+
+## 5.1.161
+
+### Bug Fixes
+
+- Fix end-to-end test execution.
+
+### Improvements
+
+- Update Cabloy Basic specifications.
+
 ## 5.1.160
 
 ### Features

package/CLAUDE.md

@@ -72,7 +72,7 @@ Before inventing a custom implementation path:
 - 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.
 - Do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff. Verify the active theme handler and client hydration path before changing SSR theme behavior.
-- Reuse existing repo terminology: Cabloy, Vona, Zova, suite, module, bean, SSR, SPA, Web, Admin.
+- Reuse existing repo terminology: Cabloy, Vona, Zova, suite, module, bean, SSR, SPA, Web, Admin. For the two SSR entry modes, use Vona integrated SSR for the Vona-served path (default `7102`) and Zova standalone SSR for the direct Zova development-server path (default `9000`); do not confuse the latter with an independently deployable SSR Site/flavor.
 - For backend base-class placement, use the A / B1 / B2 rule from `repo-docs/ai/class-placement-rule.md`.
 - Pure helper bases belong in `src/lib`; subclass-only bases should be evaluated case by case and often belong in `src/lib`.
 - Runtime-anchor bases that still require container-managed or selector/class-token behavior but should not be global beans should prefer `src/service` with `@Service()`.

package/CONTRIBUTING.md

@@ -21,7 +21,7 @@ npm run init
 
 `npm run init` is more than a package install: it installs multiple workspaces, prepares generated local configuration, initializes and synchronizes Vona and Zova, and generates required frontend and backend artifacts. Run it intentionally rather than as a retry for an unrelated narrow change.
 
-Current CI workflows run on Ubuntu with Node.js 24 after pushes to `main`; do not assume that every pull request is automatically validated. For maintained onboarding guidance, see [Cabloy Basic](https://cabloy.com/editions/cabloy-basic).
+Current CI workflows run on Ubuntu with Node.js 24 after pushes to `main`; do not assume that every pull request is automatically validated. For maintained edition and onboarding guidance, see [Cabloy Editions](https://cabloy.com/editions/overview#cabloy-basic).
 
 ## Develop and validate
 

package/README.md

@@ -6,11 +6,11 @@
 [![Docs](https://img.shields.io/badge/docs-cabloy-4f46e5.svg?style=flat-square)](https://cabloy.com)
 [![Demo](https://img.shields.io/badge/demo-cabloy.com-059669.svg?style=flat-square)](https://cabloy.com)
 
-Cabloy is a Node.js fullstack framework for AI vibe coding.
+Cabloy is a Node.js fullstack framework for AI vibe coding, with AI Spec-Driven Development for traceable, evidence-backed delivery.
 
-**One fullstack system for AI vibe coding—bidirectional type sync, CLI-first workflows, docs, and skills.**
+**One fullstack system for AI vibe coding—bidirectional type sync, CLI-first workflows, docs, skills, and traceable delivery from product intent to verifiable evidence.**
 
-Instead of stitching separate backend and frontend stacks together, Cabloy keeps their contracts, tooling, and guidance connected in one repository. Vona is its backend framework and runtime layer, and Zova is its frontend framework and application layer. Cabloy Basic and Cabloy Start are related, complete edition baselines built on that shared architecture; see [Editions Overview](https://cabloy.com/editions/overview) for their deliberate differences.
+Instead of stitching separate backend and frontend stacks together, Cabloy keeps their contracts, tooling, and guidance connected in one repository. [AI Spec-Driven Development](https://cabloy.com/ai/ai-spec-driven-development) provides the disciplined path from confirmed Specs to evidence-backed delivery; its precise engineering method is Traceable Spec Delivery. Vona is its backend framework and runtime layer, and Zova is its frontend framework and application layer. Cabloy Basic and Cabloy Start are related, complete edition baselines built on that shared architecture; see [Editions Overview](https://cabloy.com/editions/overview) for their deliberate differences.
 
 [Documentation](https://cabloy.com) · [npm](https://www.npmjs.com/package/cabloy) · [Web Demo](https://cabloy.com) · [Admin Demo](https://cabloy.com/admin) · [GitHub](https://github.com/cabloy/cabloy)
 
@@ -31,74 +31,50 @@ For the complete explanation, see [Fullstack Introduction](https://cabloy.com/fu
 
 ## Get Started
 
-### Prerequisites
+See the [Fullstack Quickstart](https://cabloy.com/fullstack/quickstart).
 
-Before creating a new Cabloy project, make sure your environment has:
+## AI Spec-Driven Development
 
-| Name       | Version    |
-| ---------- | ---------- |
-| pnpm       | `>=11.5.2` |
-| Node.js    | `>=24.4.0` |
-| Redis      | `>=7.2.6`  |
-| SQLite3    | `Built-in` |
-| MySQL      | `>=8`      |
-| PostgreSQL | `>=16`     |
+See the [AI Spec-Driven Development](https://cabloy.com/ai/ai-spec-driven-development).
 
-- `Redis`: powers queue, schedule, startup, broadcast, caching, two-layer cache, and redlock
-- `SQLite3`: if you use `better-sqlite3`, set up `node-gyp` before installing dependencies
+## Editions
 
-Create a new Cabloy project:
+Cabloy is available through two complete project baselines, each maintained in its own repository:
 
-```bash
-npm create cabloy
-```
-
-The generated project already includes `CLAUDE.md` and the `.claude/` workspace assets. This path creates a Cabloy Basic project baseline. Open this project in Claude Code and start coding immediately with project-specific guidance.
-
-#### pnpm 11 supply-chain protection note
-
-`pnpm` 11 enables the `minimumReleaseAge` supply-chain protection by default. Newly published packages may be blocked for a short time window before `pnpm` allows installation.
-
-This matters for `npm create cabloy` because the command downloads Cabloy from npm and then automatically runs `npm run init`. If your environment blocks newly published packages during that flow, temporarily set `pnpm_config_minimum_release_age=0` for the current shell session and rerun the command.
-
-**Windows PowerShell**
+- **[Cabloy Basic](https://github.com/cabloy/cabloy)** — the public framework and reference edition, licensed under [MIT](https://github.com/cabloy/cabloy/blob/main/LICENSE), with a DaisyUI + Tailwind CSS UI layer and an e-commerce-oriented demonstration suite.
+- **[Cabloy Start](https://github.com/cabloy/cabloy-start)** — a public starter edition, licensed under [MIT](https://github.com/cabloy/cabloy-start/blob/main/LICENSE), with a Vuetify UI layer and built-in system-management and authorization demonstrations.
 
-```powershell
-$env:pnpm_config_minimum_release_age = "0"
-npm create cabloy
-```
+Both editions share Cabloy’s Vona + Zova architecture, CLI-first workflows, bidirectional type synchronization, and AI Spec-Driven Development model. They differ primarily in their default UI layer, included demonstration suites, and out-of-the-box application baseline.
 
-**Windows Command Prompt**
+For fuller guidance on choosing an edition and working in an existing checkout, see [Cabloy Editions](https://cabloy.com/editions/overview).
 
-```cmd
-set pnpm_config_minimum_release_age=0 && npm create cabloy
-```
+**Legend:** ✅ Included in the default edition baseline · — Not included in the default edition baseline
 
-**macOS / Linux**
+### Default UI Layer
 
-```bash
-pnpm_config_minimum_release_age=0 npm create cabloy
-```
+| Area       | Cabloy Basic           | Cabloy Start |
+| ---------- | ---------------------- | ------------ |
+| UI library | DaisyUI + Tailwind CSS | Vuetify      |
 
-If you already created the project directory and only need to rerun initialization, use the same environment variable with `npm run init`.
+### Included Core Capabilities
 
-For **Cabloy Start**, clone the public MIT-licensed repository at `https://github.com/cabloy/cabloy-start`, then run `npm run init`. For the complete Start onboarding flow, read the [Cabloy Start](https://cabloy.com/editions/cabloy-start) page.
+| Capability           | Description                                                                       | Cabloy Basic | Cabloy Start |
+| -------------------- | --------------------------------------------------------------------------------- | ------------ | ------------ |
+| Master–detail forms  | Supports nested master–detail forms, including multiple levels of detail records. | ✅           | ✅           |
+| Image uploads        | Supports local storage and Cloudflare storage backends.                           | ✅           | ✅           |
+| File uploads         | Supports local storage and Cloudflare storage backends.                           | ✅           | ✅           |
+| Payment integrations | Demonstrates simulated payments, PayPal, and Stripe integrations.                 | ✅           | ✅           |
+| Markdown editor      | Includes image uploads and syntax highlighting.                                   | ✅           | ✅           |
 
-Then continue with the framework docs:
+### Included Demonstration Suites
 
-- [Fullstack Quickstart](https://cabloy.com/fullstack/quickstart)
-- [Documentation](https://cabloy.com)
-- [Fullstack Introduction](https://cabloy.com/fullstack/introduction)
-- [Backend Introduction](https://cabloy.com/backend/introduction)
-- [Frontend Introduction](https://cabloy.com/frontend/introduction)
-- [Editions Overview](https://cabloy.com/editions/overview)
-- [Choosing Between Cabloy Basic and Cabloy Start](https://cabloy.com/editions/choosing-between-basic-and-start)
+| Suite                       | What it demonstrates                                                                                                                       | Cabloy Basic | Cabloy Start |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | ------------ |
+| Student Training Management | Master–detail forms, nested detail records, image uploads, and file uploads. Cabloy Start additionally demonstrates data-scope-based RBAC. | ✅           | ✅           |
+| E-commerce                  | A complete Admin site, Web site, personal center, payment flows, Markdown editing, and related capabilities.                               | ✅           | —            |
+| System Management           | User management, role management, department management, RBAC authorization, and menu authorization.                                       | —            | ✅           |
 
-To upgrade an existing Cabloy project:
-
-```bash
-npm run upgrade
-```
+> “Not included” means that the suite is not part of the default edition baseline. It does not limit what can be built with Cabloy.
 
 ## Highlights
 
@@ -106,6 +82,7 @@ npm run upgrade
 - **Bidirectional type sync** — use the contract loop to keep backend contracts and frontend metadata aligned in both directions
 - **CLI-first workflows** — use explicit commands for scaffolding, generation, refactors, and verification
 - **Docs and skills** — give people and AI agents reusable, source-grounded guidance for the current repository
+- **AI Spec-Driven Development** — use Traceable Spec Delivery to connect product intent, contracts, bounded work, acceptance procedures, and verifiable evidence
 - **Vona + Zova** — use aligned backend and frontend layers for code sharing and cross-stack consistency
 - **Modular delivery** — organize capabilities as suites and modules, then deliver SSR, SPA, Web, and Admin applications with shared conventions
 
@@ -168,8 +145,7 @@ npm run build
 
 For more details, see:
 
-- [Editions Overview](https://cabloy.com/editions/overview)
-- [Choosing Between Cabloy Basic and Cabloy Start](https://cabloy.com/editions/choosing-between-basic-and-start)
+- [Cabloy Editions](https://cabloy.com/editions/overview)
 - [Repo Scripts](https://cabloy.com/reference/repo-scripts)
 - [Package Map](https://cabloy.com/reference/package-map)
 - [AI Development Introduction](https://cabloy.com/ai/introduction)

package/package.json

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

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

@@ -1,41 +1,66 @@
 import { defineConfig } from 'vitepress';
 
-const editionsItems = [
-  { text: 'Overview', link: '/editions/overview' },
-  {
-    text: 'Choosing Basic vs Start',
-    link: '/editions/choosing-between-basic-and-start',
-  },
-  { text: 'Cabloy Basic', link: '/editions/cabloy-basic' },
-  { text: 'Cabloy Start', link: '/editions/cabloy-start' },
-  { text: 'Edition Detection', link: '/editions/detection' },
-];
+const editionsItems = [{ text: 'Overview', link: '/editions/overview' }];
 
 const aiItems = [
   { text: 'Introduction', link: '/ai/introduction' },
-  { text: 'Repo Guidance', link: '/ai/repo-guidance' },
-  { text: 'Skills', link: '/ai/skills' },
-  { text: 'Class Placement Rule', link: '/ai/class-placement-rule' },
-  { text: 'Global Bean Lookup', link: '/ai/global-bean-lookup' },
-  { text: 'Docs / Skills Mapping', link: '/ai/docs-skills-rules-mapping' },
-  { text: 'CLI to Skill Map', link: '/ai/cli-to-skill-map' },
-  { text: 'Future Skill Roadmap', link: '/ai/future-skill-roadmap' },
-  { 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: 'AI Spec-Driven Development',
+    collapsed: false,
+    items: [
+      { text: 'Overview', link: '/ai/ai-spec-driven-development' },
+      { text: 'Generate a Cabloy Suite Specification', link: '/ai/playbook-spec-generation' },
+      {
+        text: 'Execute an Approved Cabloy Specification Increment',
+        link: '/ai/playbook-spec-execution',
+      },
+    ],
+  },
+  {
+    text: 'Repository Guidance & Skills',
+    collapsed: true,
+    items: [
+      { text: 'Repo Guidance', link: '/ai/repo-guidance' },
+      { text: 'Skills', link: '/ai/skills' },
+      { text: 'Docs / Skills Mapping', link: '/ai/docs-skills-rules-mapping' },
+      { text: 'CLI to Skill Map', link: '/ai/cli-to-skill-map' },
+      { text: 'Future Skill Roadmap', link: '/ai/future-skill-roadmap' },
+      { text: 'CLI for Agents', link: '/ai/cli-for-agents' },
+      { text: 'Rules and Config', link: '/ai/rules-and-config' },
+    ],
+  },
+  {
+    text: 'Implementation Playbooks',
+    collapsed: true,
+    items: [
+      { text: 'Backend Module', link: '/ai/playbook-backend-module' },
+      { text: 'Frontend Page', link: '/ai/playbook-frontend-page' },
+      { text: 'Contract Regeneration', link: '/ai/playbook-contract-regeneration' },
+      { text: 'Module Removal', link: '/ai/playbook-module-removal' },
+      { text: 'Metadata Refresh', link: '/ai/playbook-metadata-refresh' },
+    ],
+  },
+  {
+    text: 'Architecture Rules',
+    collapsed: true,
+    items: [
+      { text: 'Class Placement Rule', link: '/ai/class-placement-rule' },
+      { text: 'Global Bean Lookup', link: '/ai/global-bean-lookup' },
+    ],
+  },
+  {
+    text: 'Edition & Verification',
+    collapsed: true,
+    items: [
+      { text: 'Edition Consistency Checklist', link: '/ai/edition-consistency-checklist' },
+      { text: 'Verification', link: '/ai/verification' },
+    ],
+  },
+  {
+    text: 'Authoring',
+    collapsed: true,
+    items: [{ text: 'Technical Blog Authoring', link: '/ai/playbook-technical-blog-authoring' }],
   },
-  { 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' },
-  { text: 'CLI for Agents', link: '/ai/cli-for-agents' },
-  { text: 'Rules and Config', link: '/ai/rules-and-config' },
-  { text: 'Edition Detection', link: '/ai/edition-detection' },
-  { text: 'Edition Consistency Checklist', link: '/ai/edition-consistency-checklist' },
-  { text: 'Verification', link: '/ai/verification' },
 ];
 
 const fullstackGroups = [
@@ -104,6 +129,7 @@ const fullstackGroups = [
         link: '/fullstack/payment-sandbox-configuration',
       },
       { text: 'Contract Loop Playbook', link: '/fullstack/contract-loop-playbook' },
+      { text: 'Semantic Presentation Contract', link: '/fullstack/semantic-presentation-contract' },
       {
         text: 'Admin Resource and Web Self-Service',
         link: '/fullstack/admin-resource-and-web-self-service',
@@ -658,7 +684,7 @@ export default defineConfig({
             { text: 'SSR Init Data', link: '/frontend/ssr-init-data' },
             { text: 'SSR ClientOnly', link: '/frontend/ssr-client-only' },
             { text: 'SSR SEO Meta', link: '/frontend/ssr-seo-meta' },
-            { text: 'SSR Env', link: '/frontend/ssr-env' },
+            { text: 'SSR Environment Variables', link: '/frontend/ssr-env' },
           ],
         },
       ],

package/repo-docs/ai/ai-spec-driven-development.md

@@ -0,0 +1,99 @@
+# AI Spec-Driven Development
+
+**AI Spec-Driven Development** is Cabloy's approach to using AI from confirmed product intent through verifiable delivery evidence. It gives people and AI agents a shared, repository-native way to decide what to build, which contract owns a change, and what proof is required before an increment is called verified.
+
+It is a disciplined path within the broader [AI Development](/ai/introduction) area, not a promise of unconstrained prompt-to-code automation.
+
+## From intent to evidence
+
+Cabloy implements AI Spec-Driven Development through **Traceable Spec Delivery**, also described as **Spec-to-Evidence Delivery**:
+
+```text
+PRD → SRS → WBS → ATP → Evidence
+```
+
+This is a traceability chain rather than a literal list of every implementation activity:
+
+- **PRD** defines product outcomes, scope, audiences, journeys, and business rules.
+- **SRS** defines technical contracts, ownership, data, authorization, lifecycle, API, and nonfunctional boundaries.
+- **WBS** defines bounded delivery work, dependencies, completion checks, and applicable Contract Loop checkpoints. In a suite record, this is commonly maintained in `pdp-wbs.md`.
+- **ATP** defines formal acceptance procedures, expected proof, and release gates.
+- **Evidence** is observed, retained, redacted proof for the applicable authority and revision.
+
+Implementation and, when applicable, fullstack contract synchronization happen between the approved WBS increment and the resulting ATP evidence.
+
+## AI Skills
+
+To support this workflow, Cabloy provides two complementary AI Skills:
+
+- `cabloy-spec-generation` creates or maintains suite-local planning authority and traceability before implementation.
+- `cabloy-spec-execution` coordinates one confirmed, bounded WBS increment through the appropriate specialist workflow, scoped verification, retained evidence, and derived progress updates.
+
+Use the skills in Claude Code when the task matches their boundary. Start planning with `/cabloy-spec-generation <business description>`; after one bounded increment is approved, use `/cabloy-spec-execution <WBS-ID>`. They provide procedural routing, readiness and confirmation gates, and evidence discipline; they do not replace the suite records that own product, technical, delivery, acceptance, or evidence authority. For the detailed public workflow, read [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation) and [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution).
+
+## Repository-native, domain-scoped authority
+
+Traceable Spec Delivery does not create a second planning hierarchy or reduce the project to one document. It keeps authority at the record and domain that own it.
+
+| Record                                  | Role                                                        |
+| --------------------------------------- | ----------------------------------------------------------- |
+| Suite `README.md`                       | Index, reading order, topology summary, and authority map   |
+| `prd.md`                                | Product authority                                           |
+| `srs.md` and accepted ADRs              | Technical contracts and durable decisions                   |
+| `pdp-wbs.md`                            | Delivery decomposition, dependencies, and completion checks |
+| `test-plan.md`                          | ATP procedures and release gates                            |
+| Evidence records                        | Observed proof only                                         |
+| `progress.md` and implementation charts | Derived status and views, not upstream authority            |
+
+Update upstream authority before downstream records. For example, a changed product or technical boundary belongs in the PRD, SRS, or an accepted decision first; its WBS, ATP, progress, evidence, and derived-chart implications follow from that change. Evidence can reveal a mismatch, but it cannot rewrite a requirement or contract.
+
+For the detailed authority table, identifiers, and chart boundary, see [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation).
+
+## Evidence-gated delivery
+
+**Evidence-gated delivery** means delivery status stays precise about what is known and what has been proven.
+
+- `implementation-complete` means the source work is complete, while required ATP or release proof remains.
+- `verified` means all applicable WBS checks and ATPs have durable, linked, redacted observed evidence.
+
+A successful build, generation command, chart-freshness check, planning record, screenshot, manual walkthrough, or unrelated test run is not automatically verification. It is verification only when the authoritative test plan defines it as sufficient retained proof for the named increment.
+
+Readiness gates, evidence gates, and release gates are also distinct:
+
+- **Readiness gates** determine whether an increment may start.
+- **Evidence gates** determine whether a verification or closure claim is justified.
+- **Release gates** are the test-plan-defined conditions for release-level acceptance.
+
+## Deliver bounded, verified vertical increments
+
+The controlled execution unit is one named WBS item or an explicitly approved finite phase with a defined closure boundary—not an open-ended request to finish a suite or continue automatically.
+
+Before source work begins, an **execution dossier** makes the unit explicit: target and revision, linked authority, dependencies, scope and exclusions, safety and ownership constraints, permitted verification, expected evidence, allowed record updates, blockers, and one next action. After work, a **resumable handoff** records the implemented scope, procedures actually run, resulting evidence and status, any gap or blocker, and exactly one next action.
+
+This structure lets a team pause, review, or transfer work without treating an unfinished implementation as verified. See [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution) for the readiness gates, routing rules, evidence protocol, and handoff format.
+
+## Contract Loop is complementary
+
+[Contract Loop](/fullstack/contract-loop-playbook) is Cabloy's bidirectional Vona↔Zova synchronization model. It determines where fullstack contract truth lives, which generated handoff must be refreshed, and how to recover from forward-chain, reverse-chain, consumer, or local-dependency drift.
+
+Traceable Spec Delivery and Contract Loop answer different questions:
+
+| Concern                                                                                     | Primary model           |
+| ------------------------------------------------------------------------------------------- | ----------------------- |
+| What should be built, under which authority, and what proves it?                            | Traceable Spec Delivery |
+| How do Vona and Zova contract sources, generated handoffs, and consumers stay synchronized? | Contract Loop           |
+
+A WBS increment can require a Contract Loop checkpoint, but synchronization alone does not establish product authority or close its ATP evidence.
+
+## When presentation semantics are in scope
+
+For schema-driven UI, establish the audience, task, scene, meaningful business information areas, and operation-specific DTO boundary before selecting layout mechanics or a renderer. The [Semantic Presentation Contract](/fullstack/semantic-presentation-contract) explains how confirmed product and technical contracts translate into presentation metadata without changing API authority, persistence, validation, authorization, state ownership, or SSR privacy.
+
+## Continue reading
+
+- [AI Development Introduction](/ai/introduction)
+- [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation)
+- [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Semantic Presentation Contract](/fullstack/semantic-presentation-contract)
+- [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping)

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

@@ -2,7 +2,7 @@
 
 This page is for docs, skills, and workflow authors who need to decide where Cabloy AI guidance should live.
 
-This page explains how the Cabloy AI knowledge system is divided across public docs, skills, rules, and CLI capabilities.
+This page explains how the Cabloy AI knowledge system is divided across public docs, suite-local authority records, skills, rules, and CLI capabilities.
 
 ## Why this mapping matters
 
@@ -16,7 +16,7 @@ Without a clear mapping, AI systems and contributors repeat the same mistakes:
 
 The goal is to give each layer a distinct job.
 
-## The four main layers
+## The five main layers
 
 ### 1. Public docs
 
@@ -38,7 +38,21 @@ 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. Suite-local authority records
+
+Location:
+
+- `repo-specs/<suite>/`
+
+Use suite records for the authority that governs one business suite:
+
+- product requirements and system requirements
+- WBS delivery boundaries and ATP procedures
+- accepted decisions, observed evidence, and derived progress
+
+[AI Spec-Driven Development](/ai/ai-spec-driven-development) explains how these domain-scoped records form Traceable Spec Delivery. Public docs explain the method; they do not replace suite authority.
+
+### 3. Internal engineering docs
 
 Location:
 
@@ -57,7 +71,7 @@ Relevant internal records answer questions like:
 - why is AI enablement structured this way?
 - what invariants should future contributors preserve?
 
-### 3. Rules and commands
+### 4. Rules and commands
 
 Locations:
 
@@ -81,7 +95,7 @@ These layers answer questions like:
 - when should CLI be preferred over manual scaffolding?
 - what recurring workflow deserves a named command?
 
-### 4. Skills
+### 5. Skills
 
 Location:
 
@@ -105,6 +119,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 product, contract, delivery, ATP, decision, or observed-evidence authority for one suite, use `repo-specs/<suite>/`
 - 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**
@@ -114,7 +129,7 @@ Use this quick rule:
 
 ### Example: “Always detect Basic vs Start before giving UI-sensitive advice”
 
-- public explanation → [AI Edition Detection](/ai/edition-detection)
+- public explanation → [Cabloy Editions: For AI Development](/editions/overview#for-ai-development)
 - consistency review surface → [Edition Consistency Checklist](/ai/edition-consistency-checklist)
 - repo-wide behavior rule → `CLAUDE.md`
 - procedural enforcement → `cabloy-workflow` skill
@@ -167,7 +182,8 @@ Use this quick rule:
 
 ### 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)
+- public method overview → [AI Spec-Driven Development](/ai/ai-spec-driven-development)
+- public workflow explanation → [Generate 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/`
@@ -175,7 +191,8 @@ Use this quick rule:
 
 ### Example: “How should AI deliver an approved suite task?”
 
-- public workflow explanation → [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+- public method overview → [AI Spec-Driven Development](/ai/ai-spec-driven-development)
+- public workflow explanation → [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

package/repo-docs/ai/edition-consistency-checklist.md

@@ -142,9 +142,8 @@ Before you finish an edition-aware change, ask:
 
 ## Read together with
 
-- [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start)
-- [Editions Overview](/editions/overview)
-- [Edition Detection for AI Workflows](/ai/edition-detection)
+- [Cabloy Editions: Choosing an Edition](/editions/overview#choosing-an-edition)
+- [Cabloy Editions: For AI Development](/editions/overview#for-ai-development)
 - [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping)
 - [Rules and Config](/ai/rules-and-config)
 - [Verification](/ai/verification)

package/repo-docs/ai/introduction.md

@@ -2,6 +2,8 @@
 
 This page is the entrypoint for contributors who are designing, reviewing, or maintaining AI vibe coding workflows in the Cabloy repository.
 
+For work that must move from confirmed product intent to evidence-backed verification, use [AI Spec-Driven Development](/ai/ai-spec-driven-development). It is a disciplined specification-delivery path within AI Development, not a synonym for every AI vibe coding workflow.
+
 The Cabloy monorepo is a good fit for AI vibe coding because the source tree already contains most of the framework knowledge an agent needs:
 
 - root scripts for shared workflows
@@ -68,10 +70,11 @@ Start here when the task is about choosing the right repo surface, docs location
 
 ### 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:
+Use this path to understand [AI Spec-Driven Development](/ai/ai-spec-driven-development), 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)
+- [AI Spec-Driven Development](/ai/ai-spec-driven-development)
+- [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation)
+- [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
 - [Skills](/ai/skills)
 - [Repo Scripts](/reference/repo-scripts)
 - [Verification](/ai/verification)
@@ -92,7 +95,7 @@ Use this path when the task is about implementing or reviewing Cabloy code with
 
 Use this path when the task is about consistency checks, verification, or future workflow planning:
 
-- [Edition Detection](/ai/edition-detection)
+- [Cabloy Editions: For AI Development](/editions/overview#for-ai-development)
 - [Edition Consistency Checklist](/ai/edition-consistency-checklist)
 - [Verification](/ai/verification)
 - [Future Skill Roadmap](/ai/future-skill-roadmap)

package/repo-docs/ai/playbook-spec-execution.md

@@ -1,21 +1,35 @@
-# Playbook: Execute an Approved Cabloy Specification Increment
+# Execute an Approved Cabloy Specification Increment
 
 Use this playbook to deliver one approved Cabloy specification increment from a bounded WBS item through implementation, scoped verification, retained evidence, and an accurate progress handoff.
 
 The `cabloy-spec-execution` skill is a control plane. It coordinates an approved increment and its specialist workflow; it is not a second product authority, architecture authority, or code generator.
 
-## When to use this playbook
+This playbook is the execution half of [AI Spec-Driven Development](/ai/ai-spec-driven-development). It operationalizes Traceable Spec Delivery for one bounded increment; it does not redefine upstream authority or make Contract Loop synchronization sufficient evidence of verification.
+
+## Start a bounded execution increment
+
+In Claude Code, use either of these entry points:
+
+```text
+/cabloy-spec-execution <WBS-ID>
+/cabloy-spec-execution Execute the next task for <Suite Name>
+```
+
+An explicit `WBS-ID` is the most direct and precise request: it identifies the bounded increment that you want to execute.
+
+If you do not know the next `WBS-ID`, use the suite-level request instead. AI reads the suite's WBS, dependencies, current progress, blockers, and acceptance requirements, then proposes the next ready bounded increment or a finite candidate set. Review and explicitly approve the proposed WBS target and execution dossier before any implementation begins. The suite-level request authorizes exploration and recommendation; it does **not** authorize AI to choose or execute adjacent work automatically.
 
 Use `cabloy-spec-execution` when you need to:
 
 - implement one named `WBS-*` item
+- explore an existing suite and recommend its next ready bounded increment
 - execute an explicitly named, finite, approved phase with a defined closure boundary
 - verify or close a named ATP or release-gate task
 - turn one existing suite-plan increment into implementation and observed proof
 
 Requests such as “implement the suite,” “finish all specs,” or “do the next phase” are not bounded enough. Select one WBS task, or explicitly approve a finite task list and its closure boundary, before implementation begins.
 
-Use [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation) instead when the task changes a requirement, contract, dependency, scope boundary, or durable decision.
+Use [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation) instead when the task changes a requirement, contract, dependency, scope boundary, or durable decision.
 
 ## Establish the execution boundary first
 
@@ -46,7 +60,7 @@ Read the suite records in this order:
 6. linked evidence, runbooks, presentation records, or rollout records when they apply
 7. `implementation-gantt.svg` and `implementation-burndown.svg` as derived views to check for freshness, not authority
 
-When records conflict, return to [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation) before implementation. Do not resolve an authority contradiction through an execution note, a chart edit, or a source workaround.
+When records conflict, return to [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation) before implementation. Do not resolve an authority contradiction through an execution note, a chart edit, or a source workaround.
 
 ## Stop at readiness gates
 
@@ -139,6 +153,6 @@ Finish the increment with a concise record of:
 6. remaining blocker or evidence gap
 7. exactly one next action
 
-A next action is a handoff, not authorization to execute another task. If it requires an authority change, return to [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation).
+A next action is a handoff, not authorization to execute another task. If it requires an authority change, return to [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation).
 
 For the public boundaries between docs, skills, suite authority, and CLI workflows, read [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping) and [CLI to Skill Map](/ai/cli-to-skill-map).