cabloy 5.1.161 → 5.1.162

package/repo-docs/frontend/quickstart.md

@@ -33,11 +33,7 @@ That matters because edition choice affects:
 - project assets and examples
 - which examples in the docs match the current repo directly
 
-Read together with:
-
-- [Edition Detection](/editions/detection)
-- [Cabloy Basic](/editions/cabloy-basic)
-- [Cabloy Start](/editions/cabloy-start)
+Read together with [Cabloy Editions](/editions/overview#working-in-an-existing-checkout).
 
 ## Step 2: start from root scripts
 
@@ -203,9 +199,7 @@ Read next:
 
 ### I need edition-sensitive guidance
 
-- [Edition Detection](/editions/detection)
-- [Cabloy Basic](/editions/cabloy-basic)
-- [Cabloy Start](/editions/cabloy-start)
+- [Cabloy Editions](/editions/overview#working-in-an-existing-checkout)
 - [Frontend Scripts](/frontend/scripts)
 
 ### I want the broader frontend architecture story

package/repo-docs/frontend/scripts.md

@@ -16,7 +16,7 @@ A practical rule is:
 2. then choose the correct script, flavor, and appMode path
 3. only then document or automate edition-specific frontend examples
 
-For the edition-detection workflow, also see [Edition Detection](/editions/detection).
+For the edition-detection workflow, see [Cabloy Editions: For AI Development](/editions/overview#for-ai-development).
 
 ## Cabloy Basic root wrappers
 
@@ -45,9 +45,13 @@ npm run build:zova:commerce:admin
 
 `npm run build:zova:all` sequentially runs the focused Basic and Commerce batch builds. `npm run init` uses it to prepare every shipped Cabloy Basic SSR/REST flavor before Vona is initialized. For normal frontend work, continue to use `build:zova` or `build:zova:commerce` when only that suite's artifacts changed.
 
-## Basic SSR browser acceptance
+## Zova standalone SSR development
 
-The default Basic Web and Admin sites have browser smoke commands that exercise Vona SSR dispatch at port `7102`, not a standalone Zova development-server port.
+The `dev:zova:*` commands start the Zova development server, which uses `9000` in the Cabloy Basic default environment. Use this Zova standalone SSR entry for page, route, and hydration iteration. It may be used as Vona's development proxy target, but direct access to `9000` does not prove the Vona request boundary or integrated acceptance.
+
+## Vona integrated SSR browser acceptance
+
+The default Basic Web and Admin sites have browser smoke commands that exercise Vona integrated SSR through Vona SSR dispatch at port `7102`, not through the Zova standalone SSR development-server port.
 
 Prepare current SSR and REST artifacts explicitly when frontend output has changed:
 

package/repo-docs/frontend/ssr-architecture-overview.md

@@ -200,7 +200,7 @@ Use this order when you need the shortest path from mental model to implementati
 3. [SSR Init Data](/frontend/ssr-init-data)
 4. [SSR ClientOnly](/frontend/ssr-client-only)
 5. [SSR SEO Meta](/frontend/ssr-seo-meta)
-6. [SSR Env](/frontend/ssr-env)
+6. [SSR Environment Variables](/frontend/ssr-env)
 7. [Fullstack Vona + Zova Integration](/fullstack/vona-zova-integration)
 
 ## Implementation checks for architecture-sensitive SSR changes

package/repo-docs/frontend/ssr-build-deploy-guide.md

@@ -77,7 +77,7 @@ npm run build
 
 Practical interpretation:
 
-- `dev:zova:*` is for normal frontend SSR development entry
+- `dev:zova:*` starts the Zova standalone SSR development entry (the default `9000` listener)
 - `build:zova` builds frontend SSR output in batch mode
 - `build:zova:admin` and `build:zova:web` are explicit root-wrapper paths for flavor-specific SSR output plus related REST generation
 - `build` is the fullstack alignment path when frontend and backend output should move together
@@ -117,13 +117,15 @@ or:
 npm run dev:zova:web
 ```
 
-Use this when the task is:
+Use this Zova standalone SSR entry when the task is:
 
 - page development
 - route debugging
 - SSR UI iteration
 - hydration behavior review
 
+When the task requires the Vona HTTP boundary, built artifact handoff, or acceptance evidence, verify through Vona integrated SSR on the effective Vona server port (the Cabloy Basic default is `7102`), rather than directly through the Zova development server.
+
 If you need deeper script control or need to verify the exact Zova flavor path, inspect the flavor-specific scripts described in [Frontend Scripts](/frontend/scripts).
 
 ## Build workflow

package/repo-docs/fullstack/comparison-with-other-frameworks.md

@@ -1,6 +1,6 @@
 # Comparison with Other Frameworks
 
-This page shows how **Cabloy** differs from several common framework choices, focusing on its one fullstack system for AI vibe coding: bidirectional type sync, CLI-first workflows, and source-grounded docs and skills. It also distinguishes strengths of the fullstack system from those of the backend layer provided by **Vona**.
+This page shows how **Cabloy** differs from several common framework choices, focusing on its one fullstack system for AI vibe coding: bidirectional type sync, CLI-first workflows, source-grounded docs and skills, and AI Spec-Driven Development. It also distinguishes strengths of the fullstack system from those of the backend layer provided by **Vona**.
 
 ## What is being compared
 
@@ -15,6 +15,7 @@ For the broader Cabloy model, start with these pages:
 - [Vona + Zova Integration](/fullstack/vona-zova-integration)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+- [AI Spec-Driven Development](/ai/ai-spec-driven-development)
 
 ## Comparison lens
 
@@ -25,6 +26,7 @@ The sections below use the same comparison lens each time:
 - **Frontend and admin model** — how the UI side is expected to evolve
 - **Cross-stack workflow** — how bidirectional type sync, contracts, and generation workflows stay aligned
 - **Guidance and automation** — how CLI-first workflows, docs, and skills make repository conventions reusable
+- **Traceable delivery** — how a repository can connect requirements, contracts, bounded work, acceptance procedures, and evidence
 - **Best fit** — the kind of team or project the framework fits most naturally
 
 ## Cabloy vs Next.js
@@ -35,7 +37,7 @@ The sections below use the same comparison lens each time:
 | Backend model            | Dedicated backend framework with its own runtime, contracts, infrastructure, and CLI workflows | Backend capabilities are typically centered around the web app runtime |
 | Frontend and admin model | Shared conventions across SSR, SPA, Web, and Admin applications                                | Strong fit for React-based web application delivery                    |
 | Cross-stack workflow     | Bidirectional type sync through OpenAPI, SDK generation, and metadata feedback loops           | Usually chosen per project or ecosystem tooling                        |
-| Guidance and automation  | CLI-first workflows plus source-grounded docs and skills                                       | Usually chosen per project or ecosystem tooling                        |
+| Guidance and automation  | CLI-first workflows, source-grounded docs and skills, and Traceable Spec Delivery              | Usually chosen per project or ecosystem tooling                        |
 | Best fit                 | Teams that want a coordinated fullstack system with a stronger dedicated backend layer         | Teams that want a React-centered fullstack web application path        |
 
 Cabloy and Next.js both target fullstack application development, but they organize the stack differently.
@@ -48,6 +50,7 @@ Representative Cabloy strengths in this comparison include:
 - bidirectional type sync through backend OpenAPI output, frontend SDK generation, and frontend metadata feedback loops
 - CLI-first workflows for scaffolding, generation, refactors, and verification
 - source-grounded docs and skills that make repository conventions reusable for people and AI agents
+- AI Spec-Driven Development: a repository-native Traceable Spec Delivery model that connects requirements, contracts, bounded work, acceptance procedures, and observed evidence
 - shared delivery conventions for SSR, SPA, Web, and Admin applications
 
 If your main goal is a React-centered fullstack web app, Next.js may feel more direct. If your main goal is a **coordinated fullstack framework system** with a stronger backend layer and explicit cross-stack workflows, Cabloy is the better fit.
@@ -117,6 +120,7 @@ These comparisons are most useful when your decision depends on questions like:
 - do you want one coordinated framework system instead of stitching backend and frontend frameworks together?
 - do you need bidirectional type sync through an explicit contract loop?
 - do you want CLI-first workflows, source-grounded docs, and skills that make repository conventions reusable?
+- do you want a disciplined, evidence-aware specification-delivery model in the repository?
 - do you need a stronger dedicated backend layer inside a fullstack architecture?
 - do you need shared conventions across SSR, SPA, Web, and Admin delivery modes?
 - do you want Django-Admin-like rapid admin development inside the Node.js ecosystem, but with a more modern frontend and interaction model?

package/repo-docs/fullstack/contract-loop-playbook.md

@@ -2,6 +2,8 @@
 
 This page is the canonical playbook for Cabloy’s bidirectional fullstack contract loop.
 
+[AI Spec-Driven Development](/ai/ai-spec-driven-development) defines what an approved increment should build and how it is proven. Contract Loop is its complementary synchronization mechanism: it aligns Vona↔Zova contract sources, generated handoffs, and consumers, but does not create suite authority or establish ATP evidence.
+
 Use it when you need to decide:
 
 - where source truth lives for a change
@@ -361,6 +363,8 @@ Use the tutorial series as examples of the two chains:
 ## Related docs
 
 - [Fullstack Introduction](/fullstack/introduction)
+- [AI Spec-Driven Development](/ai/ai-spec-driven-development)
+- [Semantic Presentation Contract](/fullstack/semantic-presentation-contract)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - [Existing Resource Field Update](/backend/resource-field-update)
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)

package/repo-docs/fullstack/introduction.md

@@ -1,8 +1,8 @@
 # Fullstack Introduction
 
-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, Zova, and suite-based modules are the aligned architecture behind that workflow.
 
@@ -12,6 +12,7 @@ Instead of stitching separate backend and frontend stacks together, Cabloy keeps
 - **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
 
@@ -45,6 +46,7 @@ Use this path when the task is about how backend and frontend stay aligned insid
 - [Framework Performance](/fullstack/framework-performance)
 - [Vona + Zova Integration](/fullstack/vona-zova-integration)
 - [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Semantic Presentation Contract](/fullstack/semantic-presentation-contract)
 - [Admin Resource and Web Self-Service](/fullstack/admin-resource-and-web-self-service)
 - [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
 - [Fullstack Image Workflow](/fullstack/image-workflow)
@@ -56,8 +58,7 @@ Use this path when the task is about how backend and frontend stay aligned insid
 Use this path when the task depends on edition boundaries, UI assumptions, or cross-repo delivery differences:
 
 - [Edition Collaboration Differences](/fullstack/edition-collaboration-differences)
-- [Editions Overview](/editions/overview)
-- [Choosing Basic vs Start](/editions/choosing-between-basic-and-start)
+- [Cabloy Editions](/editions/overview#choosing-an-edition)
 
 ## Shared architecture
 
@@ -71,6 +72,14 @@ Cabloy Basic and Cabloy Start are related, complete edition baselines built on t
 
 This combination keeps backend and frontend development close enough for code sharing, workflow reuse, and AI vibe coding workflows.
 
+## Traceable delivery and contract synchronization
+
+[AI Spec-Driven Development](/ai/ai-spec-driven-development) governs how confirmed product intent becomes contracts, bounded WBS work, acceptance procedures, and evidence-backed status. Its precise engineering method is Traceable Spec Delivery.
+
+The [Contract Loop](/fullstack/contract-loop-playbook) is complementary rather than interchangeable: it synchronizes Vona↔Zova contract sources, generated handoffs, and consumers when an approved increment crosses the fullstack contract boundary. A completed synchronization does not establish product authority or close ATP evidence.
+
+When an approved scene needs schema-driven presentation, use the [Semantic Presentation Contract](/fullstack/semantic-presentation-contract) to translate audience, task, scene, and DTO boundaries into renderer decisions without changing security or ownership authority.
+
 ## Cabloy fullstack framework principles
 
 Cabloy’s fullstack model can be understood through two core principles.

package/repo-docs/fullstack/parallel-worktree-environment.md

@@ -30,6 +30,8 @@ The recommendation uses only Git worktree metadata and the fixed defaults below.
 | `DEV_SERVER_PORT`     |   `9000` | `9000 + linked-worktree ordinal`  |
 | `DEV_SERVER_HMR_PORT` |  `24679` | `24679 + linked-worktree ordinal` |
 
+These listeners have different responsibilities: `SERVER_LISTEN_PORT` is the Vona server and Vona integrated SSR entry, `DEV_SERVER_PORT` is the Zova standalone SSR development server, and `DEV_SERVER_HMR_PORT` is its HMR listener. `API_BASE_URL` must point to the Vona port, not the Zova development port.
+
 `APP_NAME` is the current linked worktree directory name. `API_BASE_URL` is regenerated as `http://localhost:<SERVER_LISTEN_PORT>`.
 
 Every valid explicit setup proposes the same complete tuple and both local files:

package/repo-docs/fullstack/quickstart.md

@@ -26,6 +26,16 @@ 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.
 
+`npm create cabloy` automatically runs `npm run init` after creating the project. If you later need to reinstall the project's frontend and backend dependencies, you can run `npm run init` directly.
+
+### Cabloy Start
+
+Cabloy Start is the public MIT-licensed edition maintained in its own repository. Instead of `npm create cabloy`, clone its public repository directly and run `npm run init`. Then use the frontend commands provided by that edition. Do not assume the Cabloy Basic flavor names apply to Cabloy Start.
+
+For the Start onboarding distinction, read [Cabloy Editions: Cabloy Start](/editions/overview#cabloy-start).
+
+If you are not sure which edition you are using or which one to choose, read [Cabloy Editions](/editions/overview).
+
 ### 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.
@@ -51,40 +61,55 @@ set pnpm_config_minimum_release_age=0 && npm create cabloy
 pnpm_config_minimum_release_age=0 npm create cabloy
 ```
 
-If you already created the project directory and only need to rerun initialization, use the same environment variable with `npm run init`.
+## 3. Start Vona integrated SSR
 
-## 3. Start the backend
+Run the root CLI command to start the Vona server:
 
 ```bash
 npm run dev
 ```
 
-- Web: http://localhost:7102/
-- Admin: http://localhost:7102/admin/
+In the Cabloy Basic default environment, Vona listens on `7102` and serves the following SSR sites:
+
+| SSR Site       | URL                                   |
+| -------------- | ------------------------------------- |
+| Web            | http://localhost:7102/                |
+| Admin          | http://localhost:7102/admin/          |
+| Commerce-Web   | http://localhost:7102/commerce/       |
+| Commerce-Admin | http://localhost:7102/commerce-admin/ |
 
-## 4. Start the frontend for your edition
+## 4. Start Zova standalone SSR
 
-### Cabloy Basic
+Run one of the root CLI commands below to start the Zova development server. Zova standalone SSR is typically used for frontend development, hot reload, and isolated debugging:
 
 ```bash
-npm run dev:zova:admin # http://localhost:9000/admin/
-npm run dev:zova:web   # http://localhost:9000/
+npm run dev:zova:web             # http://localhost:9000/
+npm run dev:zova:admin           # http://localhost:9000/admin/
+npm run dev:zova:commerce:web    # http://localhost:9000/commerce/
+npm run dev:zova:commerce:admin  # http://localhost:9000/commerce-admin/
 ```
 
-### Cabloy Start
+In the Cabloy Basic default environment, the Zova development server listens on `9000`:
 
-Cabloy Start is the public MIT-licensed edition maintained in its own repository. Instead of `npm create cabloy`, clone its public repository directly and run `npm run init`. Then use the frontend commands provided by that edition. Do not assume the Cabloy Basic flavor names apply to Cabloy Start.
+| SSR Site       | URL                                   |
+| -------------- | ------------------------------------- |
+| Web            | http://localhost:9000/                |
+| Admin          | http://localhost:9000/admin/          |
+| Commerce-Web   | http://localhost:9000/commerce/       |
+| Commerce-Admin | http://localhost:9000/commerce-admin/ |
 
-For the full Start onboarding and initialization flow, read [Cabloy Start](/editions/cabloy-start).
+## 5. Vona integrated SSR and Zova standalone SSR
 
-If you are not sure which edition you are using or which one to choose, read:
+The two commands start different SSR entry points. Choose the one that matches the task:
 
-- [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start)
-- [Edition Detection](/editions/detection)
-- [Cabloy Basic](/editions/cabloy-basic)
-- [Cabloy Start](/editions/cabloy-start)
+| SSR entry               | Default port | Best for                                                                                 | What it validates                                                                                   |
+| ----------------------- | ------------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| **Vona integrated SSR** | `7102`       | Fullstack development, site access, and browser acceptance                               | Vona API handling, SSR site matching, built artifact handoff, and the integrated HTTP response path |
+| **Zova standalone SSR** | `9000`       | Frontend development, hot reload, isolated debugging, and page/route/hydration iteration | Zova SSR rendering and frontend behavior without proving the Vona integration boundary              |
 
-## 5. Run with Docker Compose
+The Zova standalone SSR server can also be used as Vona's development proxy target. However, directly opening `9000` does not replace validation through Vona integrated SSR at `7102`. For acceptance or deployment-oriented checks, build the required SSR/REST artifacts, synchronize them with Vona, and access the site through Vona.
+
+## 6. Run with Docker Compose
 
 Both Cabloy Basic and Cabloy Start support the same Docker Compose command flow. Run these commands from the repository for the edition you are using:
 
@@ -95,81 +120,47 @@ sudo COMPOSE_BAKE=true docker-compose build
 sudo docker-compose up
 ```
 
-- Web: http://localhost/
-- Admin: http://localhost/admin/
-
-These commands build the edition-specific frontend flavors from the repository you are using.
-
-## 6. Upgrade an existing project
+| SSR Site       | Url                              |
+| -------------- | -------------------------------- |
+| Web            | http://localhost/                |
+| Admin          | http://localhost/admin/          |
+| Commerce-Web   | http://localhost/commerce/       |
+| Commerce-Admin | http://localhost/commerce-admin/ |
 
-Inspect the planned framework changes before applying them:
+## 7. Upgrade an existing project
 
 ```bash
-npm run upgrade:dry-run
 npm run upgrade
 ```
 
-In Cabloy Basic, upgrade synchronizes the framework-owned SSR browser E2E baseline, the two root E2E scripts, and the `@playwright/test` development dependency. The framework owns these paths:
+## 8. Next step: follow the quick start tutorials
 
-```text
-repo-e2e/config/
-repo-e2e/scripts/
-repo-e2e/specs/cabloy-basic.spec.ts
-repo-e2e/specs/home-user-account.spec.ts
-repo-e2e/specs/a-commerce.spec.ts
-```
+If you want a beginner-friendly path that connects modules, CRUD, bidirectional contract sharing, and schema-driven workflows into one story, continue with:
+
+- [Fullstack Quick Start Tutorials](/fullstack/tutorials-overview)
 
-Keep additional project-owned browser specs under other filenames in `repo-e2e/specs`. The current baseline is a fresh-project contract; unsupported legacy layouts are not repaired by the upgrader.
+## 9. AI Spec-Driven Development
 
-### Cabloy Start repository baseline
+After the project is running, use **AI Spec-Driven Development** when AI-assisted work must move from confirmed product intent to traceable, evidence-backed delivery.
 
-Cabloy Start is cloned from its separate public repository rather than created through `npm create cabloy`. Its E2E baseline is maintained in that repository:
+Cabloy implements this approach through **Traceable Spec Delivery**:
 
 ```text
-repo-e2e/config/
-repo-e2e/scripts/
-repo-e2e/specs/
+PRD → SRS → WBS → ATP → Evidence
 ```
 
-The public Cabloy upgrade flow does not synchronize or repair those Start-owned E2E files, its root E2E scripts, or `@playwright/test`. Keep project-owned browser scenarios in the flat `repo-e2e/specs/` directory under distinct filenames, for example `repo-e2e/specs/my-project.spec.ts`.
+For suite-level work, describe the business capability you want to plan in Claude Code:
 
-Prepare and run the managed Start baseline locally with:
-
-```bash
-npm run build:zova
-npm run deps:vona
-npm run test:e2e
+```text
+/cabloy-spec-generation <business description>
 ```
 
-The managed command checks the effective local server port and owns the local reset and Vona worker lifecycle. For a separately managed target, set `E2E_BASE_URL` and use `npm run test:e2e:fast`; this mode does not reset, build, start, or stop the target. Select surfaces with `--tag @web` or `--tag @admin`, and exact scenarios with native `--grep` arguments. Install Chromium once when needed with `npx playwright install chromium`. See [Repo Scripts](/reference/repo-scripts#ssr-browser-checks) for the complete command variants.
-
-## 7. Next steps for framework-aware development
-
-If you are contributing to framework-aware workflows or using Cabloy CLI generation directly, prefer CLI-backed generation over manual scaffolding.
+Once a bounded WBS increment is approved, execute it with:
 
-Read [Fullstack CLI](/fullstack/cli) for the shared cross-stack workflow model, then start with:
-
-```bash
-npm run vona :create
-npm run zova :create
+```text
+/cabloy-spec-execution <WBS-ID>
 ```
 
-Then narrow into the specific command family you need.
-
-## 8. Next step: follow the quick start tutorials
-
-If you want a beginner-friendly path that connects modules, CRUD, bidirectional contract sharing, and schema-driven workflows into one story, continue with:
-
-- [Fullstack Quick Start Tutorials](/fullstack/tutorials-overview)
-
-## 9. Shared verification commands for deeper workflow checks
-
-If you are validating framework-aware changes or a broader workflow, use the shared project scripts before declaring a workflow correct:
-
-```bash
-npm run tsc
-npm run test
-npm run build
-```
+These Skills guide planning, specialist implementation, verification, evidence, and progress handoff; they do not replace the suite records that own product, technical, delivery, acceptance, and evidence authority.
 
-Choose more targeted checks when only one area is affected, but treat these scripts as the shared reference surface.
+Start with [AI Spec-Driven Development](/ai/ai-spec-driven-development), then continue with [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation) and [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution).

package/repo-docs/fullstack/semantic-presentation-contract.md

@@ -0,0 +1,121 @@
+# Semantic Presentation Contract
+
+<Badge type="tip" text="Common" />
+
+A **semantic presentation contract** defines what an audience needs to accomplish in a scene before a project chooses visual structure or a renderer. It connects confirmed product intent and operation-specific contracts to runtime presentation without making presentation metadata authoritative.
+
+The semantic model applies across Cabloy editions. UI libraries, renderer identities, supported layout grammar, flavor commands, and generated-output paths remain edition-specific facts that must be verified in the active repository.
+
+## What this contract solves
+
+Use a semantic presentation contract to avoid:
+
+- treating layout syntax or a renderer choice as product or API authority
+- forcing Create, Update, View, list, and filter work through one universal DTO or visual tree
+- duplicating DTO and schema truth in frontend-local field definitions
+- treating visual hiding, route admission, or action visibility as authorization or privacy
+- collapsing distinct audiences, API projections, state owners, or pages into groups or tabs
+
+## Start with scene meaning, not a renderer
+
+Design the scene in this order:
+
+```text
+audience → task → scene → meaningful business information areas
+→ operation-specific DTO boundary → presentation translation → renderer choice
+```
+
+- **Audience** is whose work and authority context the scene serves.
+- **Task** is whether that audience is finding, comparing, supplying permitted input, reviewing, or acting.
+- **Scene** is the operation-specific list/filter, Create, Update, View, or purpose-built page context.
+- **Information areas** organize facts by business meaning, such as identity, lifecycle, amount, availability, time, relationships, or immutable snapshots.
+- **Presentation translation** applies order, in-scene visibility, grouping, local placement, and renderer choice to an already authorized contract.
+
+Lists support finding and comparison. Create and Update scenes expose only permitted input. View scenes expose complete, audience-appropriate facts. List/filter and entry presentation are independently designed rather than being smaller or larger versions of one another.
+
+## Keep authority at the right layer
+
+| Layer                                  | Owns                     | May define                                                                                          | Must not redefine                                                                           |
+| -------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| Product requirements                   | Business outcome         | Audience, task, and meaningful information areas                                                    | DTO syntax or component structure                                                           |
+| System requirements and operation DTOs | Scene contract           | API membership; editable, readonly, derived, hidden, and snapshot boundaries; ownership constraints | Product scope                                                                               |
+| DTO render metadata                    | Presentation translation | Order, groups, sections, tabs, supported placement, visible presentation, and renderer identity     | API authority, persistence, validation, authorization, state/page ownership, or SSR privacy |
+| Renderer/runtime implementation        | Runtime presentation     | UI-library-specific markup, input conversion, and interaction                                       | Business and security boundaries                                                            |
+
+Suites that use PRD and SRS records should preserve that upstream authority chain. Metadata translates a confirmed contract; it does not create one.
+
+## Design each scene as an explicit contract
+
+Before authoring presentation metadata, make the scene answer these questions:
+
+| Record                      | Questions to answer                                                                                   |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Audience and task           | Who is doing what, and under which authority?                                                         |
+| Scene                       | Is this list/filter, Create, Update, View, or a purpose-built experience?                             |
+| Information areas           | Which business facts are needed, and in what input or reading order?                                  |
+| Operation DTO boundary      | Which facts are editable, readonly, derived, hidden, live, or immutable snapshots?                    |
+| Presentation strategy       | Is default rendering sufficient, is a shared renderer appropriate, or is a custom renderer justified? |
+| Non-presentation boundaries | Which API, authorization, model/page ownership, scope, and SSR constraints remain unchanged?          |
+| Evidence                    | Which emitted-contract and focused runtime or browser proof demonstrates the translation?             |
+
+Different tasks can justify different DTO membership and layouts. Absence from an operation DTO is stronger and clearer than visual hiding. A separate audience, API contract, model owner, or page remains separate even when some business facts overlap.
+
+## Translate an eligible scene contract into presentation
+
+Vona DTO render metadata is the normal translation surface for Cabloy's schema-driven paths. It can express order, semantic groups, sections or tabs where supported, placement, presentation visibility within the resolved scene, and renderer identity or options.
+
+It cannot add request or response membership, relax validation, change persistence, authorize browser input, or create server authority. Consume the operation-specific DTO rather than copying fields into a frontend-local schema. If a presentation needs a label or summary relation, make an explicit response-projection decision; presentation convenience does not justify broadening a mutation DTO or API.
+
+Cabloy Basic's concrete `formLayout` grammar, block names, and DaisyUI/Tailwind implementation are details of that edition, not cross-edition guarantees. Cabloy Start readers should inspect the active Start repository before relying on a Basic renderer, UI resource, supported layout behavior, or command.
+
+## Preserve boundaries that presentation cannot own
+
+Presentation does not authorize.
+
+- **API membership:** only operation DTOs and endpoint contracts decide what enters or leaves an operation.
+- **Persistence and validation:** metadata cannot add fields, alter stored meaning, or bypass server validation.
+- **Authorization and scope:** action visibility, menus, route admission, and visual hiding are not server authorization, tenant isolation, or owner filtering.
+- **Audience/API separation:** Admin operational projections and Web self-service projections remain distinct when authority, scope, or experience differs.
+- **Model and page ownership:** a visual group cannot merge separate state owners or page architectures.
+- **SSR privacy:** render metadata and hydration flags do not decide whether private data may appear in server HTML.
+
+For the related architecture boundaries, read [Admin Resource and Web Self-Service](/fullstack/admin-resource-and-web-self-service), [Navigation Guards Guide](/frontend/navigation-guards-guide), and [SSR Review Checklist](/frontend/ssr-review-checklist).
+
+## Choose the renderer after the meaning is clear
+
+Use this order:
+
+1. Use the default renderer when it preserves the documented business meaning.
+2. Reuse a shared renderer for recurring semantic needs, such as date/time, localized state labels, monetary values, resource identity, or structured details.
+3. Introduce a custom renderer only when shared resources cannot accurately express the required meaning or interaction.
+
+A Vona DTO or render-metadata change normally follows the [forward chain](/fullstack/contract-loop-playbook#forward-chain). A new frontend-owned renderer or resource is a [reverse-chain](/fullstack/contract-loop-playbook#reverse-chain) prerequisite before backend metadata references its identity. A mixed change respects both boundaries: establish the frontend resource handoff first when a new renderer will be referenced, then author and verify the backend translation and regenerate consumers.
+
+For operational procedures, use the [Contract Loop Playbook](/fullstack/contract-loop-playbook), [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk), and [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend). [Tutorial 4: Custom Form/Table Renderers for Level](/fullstack/tutorial-4-custom-level-renderers) is a Cabloy Basic implementation specimen.
+
+## Use Form Layout for structural translation
+
+A semantic group represents a meaningful business information area. A section solves local Grid or flow placement. Tabs are for genuinely independent business domains or workflows. Field renderer and field-wrapper behavior remain separate from multi-field structure.
+
+[Form Layout Guide](/frontend/form-layout-guide) explains Cabloy Basic's structural grammar and runtime behavior. It does not replace DTO membership, validation, action behavior, or authorization. Read [Form Guide](/frontend/form-guide) for field rendering, validation, and manual or mixed forms.
+
+## Review checklist
+
+- [ ] Audience, task, scene, and information areas were established before renderer or layout mechanics.
+- [ ] Operation DTO membership establishes editable, readonly, derived, hidden, and snapshot boundaries.
+- [ ] List/filter and entry/detail scenes were considered independently.
+- [ ] Renderer choice preserves business meaning without broadening a DTO or API.
+- [ ] Visual visibility is not being used for authorization, scope, or SSR privacy.
+- [ ] Distinct audience contracts retain their API, state, and page boundaries when required.
+- [ ] New frontend resources complete their reverse contract-loop handoff before backend metadata references them.
+- [ ] Backend-owned contract changes include emitted-contract proof and forward regeneration.
+- [ ] Edition-specific UI, renderer, flavor, and generated-output claims were verified against the active edition.
+
+## Related reading
+
+- [AI Spec-Driven Development](/ai/ai-spec-driven-development)
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [DTO Guide](/backend/dto-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Form Layout Guide](/frontend/form-layout-guide)
+- [Edition Consistency Checklist](/ai/edition-consistency-checklist)

package/repo-docs/fullstack/ssr-site-and-flavor-setup.md

@@ -28,7 +28,7 @@ Read the repository marker first:
 - `__CABLOY_START__` → inspect the active Start repository before naming a flavor, wrapper, generated package, or site module.
 - both markers → stop: the checkout is ambiguous.
 
-The framework model is shared, but the exact flavor names, site baselines, UI layer, assets, scripts, and generated output paths can differ by edition. See [Edition Detection](/editions/detection) and [Edition Collaboration Differences](/fullstack/edition-collaboration-differences).
+The framework model is shared, but the exact flavor names, site baselines, UI layer, assets, scripts, and generated output paths can differ by edition. See [Cabloy Editions: Working in an Existing Checkout](/editions/overview#working-in-an-existing-checkout) and [Edition Collaboration Differences](/fullstack/edition-collaboration-differences).
 
 ### Confirm that a new site is needed
 
@@ -174,7 +174,7 @@ If the generated artifacts are correct and `npm run deps:vona` completed but Von
 
 ## Verify through the Vona boundary
 
-A standalone Zova development server can help with page iteration, but it does not prove copied artifacts, Vona site matching, generated type handoff, or production-like hydration.
+A Zova standalone SSR development server (the default `9000` entry) can help with page iteration, but it does not prove copied artifacts, Vona site matching, generated type handoff, or production-like hydration. An independent SSR Site/flavor remains a separately deployable application boundary; it is not another name for Zova standalone SSR.
 
 Run the narrowest meaningful checks first: