cabloy 5.1.161 → 5.1.162

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

@@ -1,82 +1,56 @@
-# Playbook: Plan a Cabloy Suite Specification
+# Generate a Cabloy Suite Specification
 
-Use this playbook to create or maintain the repository-native planning record for a long-lived Cabloy business suite. It explains the public workflow behind the `cabloy-spec-generation` skill without replacing the skill's detailed decision tree.
+In Claude Code, describe the business capability you want to plan:
 
-A specification establishes product intent, technical contracts, delivery structure, acceptance procedures, and decision history. It does **not** prove that implementation, generated artifacts, tests, or acceptance evidence already exist.
-
-## When to use this playbook
-
-Use `cabloy-spec-generation` when you need to:
-
-- establish a new suite's PRD, SRS, WBS, test plan, progress register, and initial ADR
-- extend an existing suite's authoritative planning records
-- turn product intent into traceable delivery and acceptance records
-- prepare an approved handoff for implementation
-
-Use a different workflow when:
-
-- provider, suite, or module identity is unresolved — use `cabloy-domain-planning`
-- the task is approved backend or frontend scaffolding — use `cabloy-backend-scaffold` or `cabloy-frontend-scaffold`
-- the task is Vona/Zova contract synchronization or generated-consumer drift — use `cabloy-contract-loop`
-- the task is one already approved, bounded WBS increment — use [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
-
-## Start with repository and edition discovery
-
-Before naming a suite, describing source topology, or recommending a site, flavor, UI, SSR, or command path:
-
-1. inspect the active repository root and edition marker
-2. inspect the root `package.json`, `CLAUDE.md`, relevant CLI entrypoints, and existing suite records
-3. separate observed source facts from confirmed user inputs, proposed targets, and `TODO(confirm from active source)` items
-
-Cabloy Basic and Cabloy Start share the planning model, but their runtime details can differ. Do not carry a Basic command, site identifier, flavor, UI assumption, or generated-output path into Start without confirming it in the active Start source.
-
-Read [Edition Detection for AI Workflows](/ai/edition-detection), [Repo Guidance](/ai/repo-guidance), [Repo Scripts](/reference/repo-scripts), and [Package Map](/reference/package-map) before making repository-specific claims.
-
-## Classify the planning request
+```text
+/cabloy-spec-generation <business description>
+```
 
-### New suite baseline
+For example:
 
-A long-lived business domain normally receives the complete planning baseline under `repo-specs/<suite>/`. The specification should be suite-first, name capability modules by business responsibility, and avoid inventing a competing persistence, identity, or authorization owner.
+```text
+/cabloy-spec-generation Plan a multi-tenant equipment-maintenance suite for technicians and operations managers, with work orders, asset history, role-based access, and an Admin dashboard.
+```
 
-### Existing suite extension
+You do not need to provide every product or technical decision in the first prompt. Cabloy AI inspects the active repository, asks focused questions, recommends boundaries where needed, and shows a confirmation summary. It generates or updates the suite specification set only after you explicitly approve that summary.
 
-Read the existing README and authority map first. Update the owning PRD, SRS, or ADR before downstream WBS, test-plan, progress, or evidence references. Preserve existing identifiers, accepted decisions, history, and evidence conventions rather than replacing them with a fresh parallel record.
+A specification set establishes product intent, technical contracts, delivery structure, acceptance procedures, and decision history. It does **not** prove that application code, generated artifacts, tests, or acceptance evidence already exist.
 
-### Proportionate planning
+This guide is the planning half of [AI Spec-Driven Development](/ai/ai-spec-driven-development). It explains the visible workflow; the `cabloy-spec-generation` Skill retains the detailed procedural checks that operate it.
 
-A disposable demo, tutorial, or isolated utility can use a smaller record only when the requester explicitly selects that scope. Do not reduce the planning baseline for a domain expected to grow merely because its first increment is small.
+## When to use it
 
-### Unresolved identity
+Run `/cabloy-spec-generation <business description>` when you want to:
 
-Stop before creating a planning directory when the provider, suite, or capability boundary is unclear. Route the identity decision to `cabloy-domain-planning` rather than creating a competing suite hierarchy.
+- establish a new long-lived business suite and its PRD, SRS, WBS, test plan, progress register, and initial ADR
+- update an existing suite's requirements, contracts, scope, delivery plan, or acceptance planning
+- turn confirmed product intent into traceable delivery and acceptance records before implementation
 
-## Keep the authority chain explicit
+Use a different path when the task is already an approved bounded WBS increment, direct backend or frontend implementation, or Vona/Zova contract synchronization. If the provider, suite, or capability identity is still unresolved, AI guides that decision before it creates a competing suite hierarchy.
 
-Repository-native traceability flows in one direction:
+## What happens after you invoke it
 
-```text
-PRD requirement → SRS contract → PDP/WBS task → ATP scenario → observed evidence
-```
+1. **AI checks the current repository.** It detects the active Cabloy edition, reads the relevant repository guidance and existing suite records, and distinguishes observed source facts from your confirmed decisions, proposals, and unresolved items.
+2. **AI identifies the planning scope.** It distinguishes a new suite, an update to an existing specification set, and a deliberately smaller planning request. Cabloy Basic and Cabloy Start share the planning model, but their runtime details can differ, so the active source remains authoritative for edition-specific facts.
+3. **AI asks focused questions.** You provide only the decisions that are needed to make the plan coherent. AI can recommend a boundary, but it identifies a recommendation as a proposal rather than treating it as confirmed input.
+4. **AI presents a confirmation summary.** The summary states what will be created or changed, what remains unresolved, and which decisions or WBS branches remain gated.
+5. **You approve or revise the summary.** No specification file is generated, replaced, or treated as approved merely because a question was asked or left unanswered. A confirmation to generate records also does not accept a durable ADR; a decision remains proposed until it is explicitly accepted.
+6. **AI generates or updates the set.** It links the planning records, preserves traceability and stable identifiers, refreshes applicable derived planning views, and reports the resulting files, unresolved decisions, and next workflow.
 
-Each record has a distinct role:
+## What you may be asked to confirm
 
-| Record                 | Authority                                                                                                 |
-| ---------------------- | --------------------------------------------------------------------------------------------------------- |
-| `README.md`            | Index, reading order, topology summary, and authority map                                                 |
-| `prd.md`               | Product outcomes, personas, scope, journeys, business rules, and launch criteria                          |
-| `srs.md`               | Technical contracts, ownership, data, tenant, authorization, lifecycle, API, and nonfunctional boundaries |
-| `pdp-wbs.md`           | Dependency order, bounded delivery tasks, completion checks, and contract-loop checkpoints                |
-| `test-plan.md`         | Formal ATP scenarios, procedures, fixtures, expected proof, and release gates                             |
-| `decisions/*.md`       | Durable suite decisions and their alternatives, consequences, and gates                                   |
-| Evidence records       | Observed, redacted proof only                                                                             |
-| `progress.md`          | Derived execution status, blockers, evidence links, and next proof                                        |
-| `implementation-*.svg` | Deterministic derived views of planning and progress records                                              |
+The initial business description can be short. During the conversation, AI may ask you to confirm:
 
-Update the upstream owner before downstream records. For example, a product or technical change belongs in the PRD, SRS, or ADR first; it is then traced into WBS tasks, ATP procedures, progress implications, and derived charts.
+- the business outcome, audiences, in-scope capabilities, exclusions, and deferred scope
+- suite identity, capability ownership, and the target `repo-specs/<suite>/` directory
+- the Web, Admin, or other site strategy that current source and confirmed requirements support
+- persistence, ownership, tenant, authorization, privacy, lifecycle, migration, and integration constraints
+- delivery, release, and verification expectations
+- unresolved durable decisions, the WBS branches they block, justified optional records, and the initial delivery status
 
-A proposed ADR is not an accepted decision. Progress cannot introduce a new requirement, contract, or durable boundary, and a chart cannot repair an authority conflict.
+This is a design confirmation, not a request to invent implementation details prematurely. When a fact must come from the active repository, AI verifies it rather than carrying assumptions across editions.
 
-## Build the planning baseline after confirmation
+## What gets generated or updated
 
 For a new long-lived suite, the normal core set is:
 
@@ -94,62 +68,56 @@ repo-specs/<suite>/
     └── 0001-*.md
 ```
 
-Add presentation contracts, staged rollout records, runbooks, additional ADRs, or an `evidence/` directory only when their scope is justified. Do not create empty evidence records to imply that testing or delivery has begun.
-
-Before creating or replacing records, explicitly confirm at least:
+| Record                     | What it provides                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------------------ |
+| `README.md`                | Index, reading order, topology summary, and authority map                                        |
+| `prd.md`                   | Product outcomes, audiences, scope, journeys, and business rules                                 |
+| `srs.md` and accepted ADRs | Technical contracts and durable decisions                                                        |
+| `pdp-wbs.md`               | Bounded delivery work, dependencies, completion checks, and applicable Contract Loop checkpoints |
+| `test-plan.md`             | Acceptance procedures, expected proof, and release gates                                         |
+| `progress.md` and charts   | Derived delivery status and planning views, not upstream authority                               |
 
-- repository, edition, suite identity, and target directory
-- intended product outcome, audiences, in-scope capabilities, and deferred scope
-- confirmed and unresolved tenant, authorization, privacy, ownership, lifecycle, migration, and integration constraints
-- site strategy at the level actually supported by current source and confirmed inputs
-- required core documents and justified optional records
-- unresolved decision gates and which WBS branches they block
-- the initial delivery-status policy
+AI adds presentation contracts, staged rollout records, runbooks, extra ADRs, or an `evidence/` directory only when the confirmed scope justifies them. It does not create empty evidence records to make testing or delivery appear to have started.
 
-Silence is not approval. Confirmation to generate records does not accept a durable ADR; retain an unaccepted decision as proposed. Initial delivery rows are normally `not-started`, `deferred`, or explicitly `blocked` unless actual prior evidence was intentionally carried forward.
+For an existing suite, the workflow updates the owning upstream authority before dependent records. It preserves existing identifiers, accepted decisions, history, and evidence conventions rather than silently overwriting them or creating a parallel planning set.
 
-## Preserve traceability and status integrity
+## Change or add requirements
 
-Use stable identifiers such as `PRD-*`, `SRS-*`, `WBS-*`, and `ATP-*`. Every referenced exact identifier must resolve to a formal definition in its owning document; a range, wildcard, or prose summary is not a substitute.
+Use the same Skill whenever an existing suite needs a changed requirement or a new capability. Describe the requested change in Claude Code:
 
-The status vocabulary is:
+```text
+/cabloy-spec-generation <changed or new business requirement>
+```
 
-- `not-started`
-- `in-progress`
-- `implementation-complete`
-- `verified`
-- `blocked`
-- `waived`
-- `deferred`
+AI reads the existing specification set, identifies the product, contract, decision, WBS, acceptance, and progress records affected by the change, then asks you to confirm the revised scope and any new boundaries. It updates the upstream PRD, SRS, or proposed/accepted ADR before it updates dependent WBS, ATP, progress, and derived-chart records.
 
-`verified` requires retained, redacted, traceable observed proof. A planning record, a planned command, a generated scaffold, a screenshot, or an unrelated broad check does not automatically provide that proof.
+If the change affects an approved or in-progress increment, return to planning first. Confirm the revised authority and delivery boundary before resuming execution; do not use an execution handoff or source workaround to redefine the requirement or contract.
 
-## Generate and check derived charts
+## How traceability and evidence work
 
-For a new or substantially revised long-lived specification set whose authoritative Markdown follows the [chart input contract](/reference/repo-scripts#chart-input-contract), refresh the two derived views after changing the README title or language, WBS, test plan, or progress register:
+Cabloy connects the specification set through **Traceable Spec Delivery**:
 
-```bash
-npm run spec:charts -- <suite>
-# Use this non-mutating check when verifying an existing chart state:
-npm run spec:charts:check -- <suite>
+```text
+PRD → SRS → WBS → ATP → Evidence
 ```
 
-The generator consumes the suite README, WBS, test plan, and progress register. It emits `implementation-gantt.svg` and `implementation-burndown.svg`; visible chart language follows the suite README. After refreshing charts, use the check when a separate freshness verification is needed, such as CI or a non-mutating review.
+A product or technical change belongs in its PRD, SRS, or accepted ADR before its WBS, acceptance, progress, evidence, and chart implications are updated. A progress entry or chart cannot introduce a requirement, resolve a contract conflict, or accept an ADR.
 
-The check validates the supported chart input contract and generated-view freshness. It does **not** implement a WBS task, run an ATP, establish evidence, prove acceptance, or replace a review of traceability and status semantics. The charts are scope/order views, not schedule forecasts or a new status authority.
+Planning records and derived charts do not establish `implementation-complete` or `verified`. `verified` requires the applicable acceptance procedure and retained, redacted observed evidence. A generated plan, planned command, scaffold, screenshot, or unrelated check is not automatically sufficient proof.
 
-This current baseline does not require unchanged legacy suite records to be migrated solely to add charts. A legacy record that does not follow the chart input contract must not be treated as chart-compatible until a deliberate record-format normalization aligns its authoritative Markdown. That normalization preserves existing planning authority and does not require an unrelated product or delivery change. Always confirm exact scripts and input expectations in the active repository before running or documenting them for another edition.
+## What happens next
 
-## Hand off work without implying implementation
+After the specification set is coherent and one bounded WBS increment is approved, execute that increment in Claude Code:
 
-Once the planning authority is coherent and implementation is approved, route the next task deliberately:
+```text
+/cabloy-spec-execution <WBS-ID>
+```
 
-- unresolved domain identity or boundary → `cabloy-domain-planning`
-- approved backend increment → `cabloy-backend-scaffold`
-- approved frontend increment → `cabloy-frontend-scaffold`
-- contract synchronization or generated-consumer drift → `cabloy-contract-loop`
-- an approved bounded WBS increment → [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+Choose one named WBS item, or an explicitly approved finite phase with a closure boundary. Do not use execution to implement an entire suite automatically or to resolve an upstream product, contract, dependency, scope, or durable-decision conflict; return to planning when those records need to change.
 
-Do not make code changes, run initialization or database-reset workflows, deploy, operate a provider, or claim implementation or verification merely because planning records now exist.
+## Further reading
 
-For the division of responsibility between public docs, skills, repository specs, and internal rationale, read [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping).
+- [AI Spec-Driven Development](/ai/ai-spec-driven-development) for the authority and evidence model
+- [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution) for bounded implementation, verification, evidence, and progress handoff
+- [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping) for the boundary between public guidance, skills, suite records, and internal rationale
+- [Repo Scripts](/reference/repo-scripts#chart-input-contract) for the derived-chart input contract and manual chart commands

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

@@ -35,7 +35,7 @@ This is more reliable than copying old file structures from examples without und
 - use `repo-docs-internal/` for supporting maintainer rationale
 - continue from public docs, rules, skills, source, and tests when a specific internal record is unavailable or irrelevant; do not create a replacement document implicitly
 
-For planning work, read the suite README, PRD, SRS, WBS, test plan, and progress records in the order appropriate to the task. `cabloy-spec-generation` maintains planning authority; `cabloy-spec-execution` acts only on a confirmed, bounded WBS increment. Both require active-source and edition discovery before topology or command claims.
+For planning work, read the suite README, PRD, SRS, WBS, test plan, and progress records in the order appropriate to the task. [AI Spec-Driven Development](/ai/ai-spec-driven-development) explains the public Traceable Spec Delivery method; the suite records retain product, technical, delivery, acceptance, and evidence authority. `cabloy-spec-generation` maintains planning authority; `cabloy-spec-execution` acts only on a confirmed, bounded WBS increment. Both require active-source and edition discovery before topology or command claims.
 
 ## 4. Treat edition detection as mandatory for UI-sensitive work
 

package/repo-docs/ai/skills.md

@@ -2,6 +2,16 @@
 
 Skills are the procedural layer of Cabloy’s AI development model.
 
+## Using a Skill in Claude Code
+
+Invoke a Cabloy Skill by typing its slash name followed by the task input. For example, describe the business capability you want to plan:
+
+```text
+/cabloy-spec-generation <business description>
+```
+
+The AI guides you through the task-specific confirmation and next steps. See [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation) for the complete planning experience.
+
 ## What a skill should do here
 
 A Cabloy skill should reduce repeated reasoning cost by encoding workflows such as:
@@ -34,20 +44,31 @@ A strong Cabloy skill usually includes:
 
 When a skill needs to apply an architectural rule such as backend class placement, prefer a branching decision tree that points back to durable docs instead of embedding the full architecture rationale inside the skill itself.
 
-For edition-aware skills, use [Edition Detection for AI Workflows](/ai/edition-detection) and [Edition Consistency Checklist](/ai/edition-consistency-checklist) as the durable review surfaces before expanding edition-specific branches.
+For edition-aware skills, use [Cabloy Editions: For AI Development](/editions/overview#for-ai-development) and [Edition Consistency Checklist](/ai/edition-consistency-checklist) as the durable review surfaces before expanding edition-specific branches.
 
-## Example workflow skills in this repo
+## Current root workflow skills
 
-Current examples include:
+The repository currently provides these cross-stack and monorepo-wide workflows in root `.claude/skills/`:
 
 - `cabloy-workflow` for choosing the correct Cabloy work path before implementation
 - `cabloy-domain-planning` for proposing and confirming providerId, suite, and initial module names before scaffolding a new business domain
-- `cabloy-spec-generation` for creating or maintaining suite-local planning authority, traceability, and derived planning views before implementation
-- `cabloy-spec-execution` for coordinating one confirmed WBS increment through specialist implementation, evidence, and derived progress updates
-- `cabloy-contract-loop` for backend/frontend contract regeneration and drift diagnosis
-- `cabloy-resource-field-update` for updating an existing backend resource field thread
-- `cabloy-module-removal` for removing a backend, frontend, or fullstack module cleanly, including generated-runtime cleanup, stale-residue recovery, and verification
-
-The specification workflows show the same boundary: [Playbook: Plan a Cabloy Suite Specification](/ai/playbook-spec-generation) and [Playbook: Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution) explain the durable public workflow, while the skills retain the branching, confirmation gates, specialist routing, and evidence protocol.
+- `cabloy-spec-generation` for creating or maintaining suite-local planning authority, traceability, and derived planning views before implementation; see [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation)
+- `cabloy-spec-execution` for coordinating one confirmed WBS increment through specialist implementation, evidence, and derived progress updates; see [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
+- `cabloy-contract-loop` for backend/frontend contract regeneration and drift diagnosis; see [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- `cabloy-resource-field-update` for updating an existing backend resource field thread; see [Existing Resource Field Update](/backend/resource-field-update)
+- `cabloy-module-removal` for removing a backend, frontend, or fullstack module cleanly, including generated-runtime cleanup, stale-residue recovery, and verification; see [Module Removal](/ai/playbook-module-removal)
+- `cabloy-backend-scaffold` for selecting the CLI-first Vona path to create or extend backend modules, beans, CRUD resources, DTOs, persistence, and tests, then checking contract, migration, metadata, and verification follow-up; see [Backend CLI](/backend/cli) and [CRUD Workflow](/backend/crud-workflow)
+- `cabloy-frontend-scaffold` for selecting the Zova CLI create, refactor, metadata, or OpenAPI path for pages, components, APIs, models, routes, and SSR-aware frontend work, then checking routing, state/contracts, hydration, UI, and verification follow-up; see [Frontend CLI](/frontend/cli) and [Page Guide](/frontend/page-guide)
+- `cabloy-master-detail` for generator-first parent-owned detail and recursive nested-detail scaffolding, including aggregate-versus-standalone choices and nested `detail*` DTO naming and placement rules; see [Master-Detail Workflow](/backend/master-detail-workflow) and [Master-Detail Source Reading Map](/backend/master-detail-source-reading-map)
+- `cabloy-worktree-environment` for explicitly invoked, confirmation-gated setup of deterministic, secret-safe Vona and Zova local environment overrides for an existing linked worktree. It does not allocate ports or isolate every external service; see [Parallel Worktree Environment](/fullstack/parallel-worktree-environment)
+- `cabloy-zova-source-reading` for Zova-native source reading and runtime tracing through controllers, beans, IoC, reactivity, routing, and SSR before offering approximate Vue comparisons; see [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers) and [Zova Source Reading Map](/frontend/zova-source-reading-map)
+
+The specification workflows show the same boundary: [AI Spec-Driven Development](/ai/ai-spec-driven-development) explains the public Traceable Spec Delivery method, while [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation) and [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution) explain its operational paths. The skills retain branching, confirmation gates, specialist routing, and evidence protocol; suite-local records remain the authority for a specific increment.
 
 The module-removal workflow is a good example of why skills belong in `.claude/skills/` instead of `CLAUDE.md`: the task needs branching, cleanup order, recovery guidance for generated runtime directories such as `vona/.vona` and `zova/.zova`, and a verification checklist that would be too large for a short repo-wide rule.
+
+## Advanced subtree-local diagnostics
+
+`detect-ssr-leak` is an advanced Skill local to the Vona workspace for investigating suspected Node.js SSR memory growth. See [Framework Performance](/fullstack/framework-performance#how-to-read-this-example) for the relevant diagnostic context.
+
+Use its instrumentation and snapshot stages only in a controlled local or nonproduction environment. Some stages create temporary diagnostic access or artifacts; remove them and restore the diagnostic environment when finished. Heap snapshots can contain sensitive in-memory application or request data, so keep them access-controlled, never commit or share them, and delete them promptly.

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

@@ -47,6 +47,7 @@ Read this guide together with:
 - [DTO Infer and Generation](/backend/dto-infer-generation)
 - [Validation Guide](/backend/validation-guide)
 - [OpenAPI Guide](/backend/openapi-guide)
+- [Semantic Presentation Contract](/fullstack/semantic-presentation-contract) for the boundary between an operation DTO and its presentation translation
 
 ## `@Api.field`
 

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

@@ -74,7 +74,7 @@ The same emitted metadata has coordinated but distinct consumers:
 
 For the form-derived scenes `form-view`, `form-create`, and `filter`, a field's base `rest` metadata is followed by the shared `rest.form` overlay and then the exact scene overlay. This lets one contract describe common form behavior while still declaring a create- or filter-specific exception.
 
-The end-to-end rule is therefore not “the frontend hides a field.” Vona uses the DTO contract to sanitize read-only request input, while Zova uses compatible metadata to render the relevant scene. See [DTO Guide](/backend/dto-guide) for declaring a DTO scene, [Validation Guide](/backend/validation-guide) for server-side readonly handling, [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood) for Zova schema loading, and [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide) for frontend form-scene flow.
+The end-to-end rule is therefore not “the frontend hides a field.” Vona uses the DTO contract to sanitize read-only request input, while Zova uses compatible metadata to render the relevant scene. See [DTO Guide](/backend/dto-guide) for declaring a DTO scene, [Semantic Presentation Contract](/fullstack/semantic-presentation-contract) for the authority boundary behind presentation translation, [Validation Guide](/backend/validation-guide) for server-side readonly handling, [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood) for Zova schema loading, and [Form Scene to Page Meta Guide](/frontend/form-scene-to-page-meta-guide) for frontend form-scene flow.
 
 ## Controllers, DTOs, entities, and examples all contribute
 

package/repo-docs/editions/overview.md

@@ -1,150 +1,81 @@
-# Editions Overview
+# Cabloy Editions
 
-This page is the editions hub for deciding which Cabloy baseline you are working with and which assumptions should follow from that choice.
+Cabloy is available through two complete project baselines: Cabloy Basic and Cabloy Start. Both use the same Cabloy fullstack direction—Vona for the backend framework and runtime layer, Zova for the frontend framework and application layer—but intentionally provide different default application baselines.
 
-Cabloy currently supports two related but distinct editions:
+## At a glance
 
-- **Cabloy Basic**
-- **Cabloy Start**
+| Edition      | Repository                                                               | License                                                         | Default path                                  | UI layer               |
+| ------------ | ------------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------- | ---------------------- |
+| Cabloy Basic | [github.com/cabloy/cabloy](https://github.com/cabloy/cabloy)             | [MIT](https://github.com/cabloy/cabloy/blob/main/LICENSE)       | `npm create cabloy`                           | DaisyUI + Tailwind CSS |
+| Cabloy Start | [github.com/cabloy/cabloy-start](https://github.com/cabloy/cabloy-start) | [MIT](https://github.com/cabloy/cabloy-start/blob/main/LICENSE) | Clone the repository, then run `npm run init` | Vuetify                |
 
-They share one Cabloy fullstack architecture, but they are composed and optimized differently.
+Both editions share Vona + Zova, suite-based modular delivery, CLI-first workflows, bidirectional type synchronization, and coordinated SSR application delivery. Their UI layer, frontend flavors, suites and modules, SSR site baselines, project assets, generated outputs, root scripts, and onboarding paths can differ.
 
-## How the names fit together
+## Comparison
 
-| Name         | Functional role                                                                   |
-| ------------ | --------------------------------------------------------------------------------- |
-| Cabloy       | The coordinated Node.js fullstack system.                                         |
-| Vona         | Cabloy's backend framework and runtime layer.                                     |
-| Zova         | Cabloy's frontend framework and application layer.                                |
-| Cabloy Basic | The public reference and community edition baseline.                              |
-| Cabloy Start | The public MIT-licensed business-system edition baseline in a sibling repository. |
+**Legend:** ✅ Included in the default edition baseline · — Not included in the default edition baseline
 
-Vona and Zova answer the architectural-layer question. Cabloy Basic and Cabloy Start answer the complete-edition-baseline question: both use the shared Cabloy architecture, but their UI, frontend flavors, modules, SSR baselines, project assets, generated outputs, root scripts, and onboarding paths can differ.
+### Included core capabilities
 
-If you need a recommendation path, start with [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start).
+| 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.                                   | ✅           | ✅           |
 
-## How to approach editions work
+### Included demonstration suites
 
-For contributor and automation workflows in this repository, prefer this order:
+| 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.                                       | —            | ✅           |
 
-1. identify the active edition before making UI-sensitive, flavor-sensitive, module-sensitive, or asset-sensitive assumptions
-2. explain the shared Cabloy architecture once before branching into edition-specific notes
-3. split documentation or workflow guidance only where the editions intentionally diverge
-4. use explicit edition markers and flavor names instead of treating the editions as interchangeable
+> “Not included” means that the suite is not part of the default edition baseline. It does not limit what can be built with Cabloy.
 
-## Editions reading paths
+## Choosing an edition
 
-Use this page as the main editions hub, then choose the path that matches your task.
+Choose **Cabloy Basic** when you want the public framework and reference edition, the default `npm create cabloy` path, and the examples and workflows provided by this repository.
 
-### Selection path
+Choose **Cabloy Start** when you want the public MIT-licensed sibling repository and its business-system-oriented baseline with Start-specific assets, SSR sites, and a Vuetify UI layer.
 
-Start here when the task is about choosing the right edition baseline or understanding their differences:
+This is a choice of default baseline, not a general capability limit. Both editions follow the same Cabloy fullstack architecture.
 
-- [Choosing Basic vs Start](/editions/choosing-between-basic-and-start)
-- [Cabloy Basic](/editions/cabloy-basic)
-- [Cabloy Start](/editions/cabloy-start)
+## Cabloy Basic
 
-### Detection and workflow path
+Cabloy Basic is the public framework and reference edition. Projects created with `npm create cabloy` follow the Basic route, and the public examples and root scripts in this repository use it as their default baseline.
 
-Use this path when the task is about repo-aware automation, flavor assumptions, or edition-safe workflow choices:
+Use the [Fullstack Quickstart](/fullstack/quickstart) to create a new Basic project. When working in this repository, verify its current scripts before choosing a flavor or implementation workflow.
 
-- [Edition Detection](/editions/detection)
-- [Fullstack Introduction](/fullstack/introduction)
-- [AI Development Introduction](/ai/introduction)
+## Cabloy Start
 
-## Shared fullstack core
+Cabloy Start is a public MIT-licensed edition maintained in its own repository. Clone [github.com/cabloy/cabloy-start](https://github.com/cabloy/cabloy-start), then run `npm run init` in that checkout.
 
-Both editions are built around the same core direction:
+Start has its own frontend flavors, suite and module composition, SSR site baselines, project assets, scripts, and generated outputs. Inspect the active Start repository before naming or relying on any of those edition-specific surfaces.
 
-- **Vona** as the backend framework and runtime layer
-- **Zova** as the frontend framework and application layer
-- suite-based modules across the stack
-- root-level `npm run vona` and `npm run zova` entrypoints
-- CLI-backed workflows for generation, refactoring, metadata, and verification
+## Working in an existing checkout
 
-This means the editions are related fullstack baselines, not unrelated products or alternatives to Vona and Zova.
+Detect the active edition before making UI-sensitive, flavor-sensitive, module-sensitive, SSR-sensitive, or asset-sensitive assumptions:
 
-## What "Basic" means
+| Repository-root markers | Result                                                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Only `__CABLOY_BASIC__` | Cabloy Basic                                                                                                              |
+| Only `__CABLOY_START__` | Cabloy Start                                                                                                              |
+| Both markers            | Invalid or ambiguous checkout; stop before making edition-specific assumptions.                                           |
+| Neither marker          | Inspect the owning `package.json` and nearby repository structure, then ask before making an edition-specific assumption. |
 
-Cabloy Basic is the public reference and community edition of Cabloy.
+## For AI Development
 
-- this public repository is marked with `__CABLOY_BASIC__`
-- projects created with `npm create cabloy` follow the Cabloy Basic route
-- the public docs and examples in this repo use Cabloy Basic as the default baseline
+AI-assisted work benefits from edition awareness whenever it depends on the UI library, frontend flavors, module availability, SSR sites, project assets, generated-output locations, or root scripts.
 
-Cabloy Basic is the open-source community edition and is optimized for public reference, learning, and fast development workflows.
+Before recommending an implementation path:
 
-## What "Start" means
+1. detect the active edition from the repository marker
+2. verify the relevant current scripts or CLI entry points
+3. branch guidance only where the editions genuinely diverge
 
-Cabloy Start is the public MIT-licensed edition maintained in its own repository.
+Keep shared Cabloy and contract-loop guidance shared. Do not project Basic-specific examples, flavors, UI assumptions, or `npm create cabloy` onboarding onto a Start checkout, or the reverse.
 
-- the public repository is marked with `__CABLOY_START__`
-- users clone the public repository source directly, then run `npm run init`
-- Start uses its own edition-specific flavors, SSR site baselines, and project assets
-
-Cabloy Start is optimized as a business-system baseline for more complex systems while staying on the same Cabloy fullstack direction.
-
-## Architecture layering
-
-Most of the frontend engineering layer is shared, while the edition-specific UI layer differs.
-
-### Shared frontend engineering layer
-
-Across editions, Zova uses the same frontend framework direction and engineering tooling, including:
-
-- Vue
-- Vite
-- Quasar tooling such as `quasar dev` and `quasar build`
-- TanStack libraries where applicable
-
-Here, Quasar is used for engineering tooling rather than as the edition UI component library.
-
-### Edition-specific UI layer
-
-The UI component strategy diverges by edition:
-
-- **Cabloy Basic**: DaisyUI + Tailwind CSS
-- **Cabloy Start**: Vuetify
-
-This difference affects not only UI code, but also module composition, frontend flavor assumptions, SSR site baselines, examples, and AI workflow guidance.
-
-## Edition-specific assets
-
-The editions intentionally diverge in several surfaces:
-
-- UI layer assumptions
-- frontend flavor names
-- suite and module composition
-- admin/web SSR site baselines
-- separate-repository structure and edition-specific project assets
-- generated outputs and root scripts
-- rules, skills, and docs used for AI vibe coding
-
-For example:
-
-- **Cabloy Basic** provides the `cabloy-basic` suites and the `cabloyBasicAdmin` / `cabloyBasicWeb` Zova flavors
-- **Cabloy Start** uses public flavors such as `cabloyStartAdmin` and `cabloyStartWeb`
-
-## Why the repo markers matter
-
-The edition markers are not just labels for humans.
-
-`__CABLOY_BASIC__` and `__CABLOY_START__` help tools, docs, and AI workflows choose the correct assumptions for:
-
-- UI component usage
-- flavor selection
-- module availability
-- SSR site expectations
-- rules, skills, and verification guidance
-
-This is why the two editions should be identified explicitly instead of being treated as interchangeable.
-
-## Documentation rule
-
-Write shared explanations once. Split or annotate only when a workflow changes because of:
-
-- UI library assumptions
-- frontend flavor names
-- different modules or assets
-- repository and initialization model
-- edition-specific scripts, generated outputs, or AI workflow guidance
+For the shared architecture and delivery model, see [Fullstack Introduction](/fullstack/introduction) and [AI Development Introduction](/ai/introduction). For front-end command selection, see [Frontend Scripts](/frontend/scripts).

package/repo-docs/frontend/environment-config-guide.md

@@ -124,7 +124,7 @@ For the theme-side contract and edition-aware checklist, see [Theme Guide](/fron
 
 ## Scripts and runtime variants
 
-Frontend scripts map directly onto the same runtime dimensions.
+Frontend scripts map directly onto the same runtime dimensions. In the Cabloy Basic default environment, `dev:ssr:*` commands use the Zova standalone SSR development listener (`DEV_SERVER_PORT=9000`), while Vona integrated SSR uses Vona's `SERVER_LISTEN_PORT=7102`. These are separate listeners; `API_BASE_URL` still points from Zova to the Vona server.
 
 Representative commands include variants such as:
 

package/repo-docs/frontend/form-layout-guide.md

@@ -9,6 +9,8 @@ This guide covers the **structural** layout contract authored in DTO metadata an
 
 ## Choose the layout from the business form
 
+Before selecting Form Layout nodes or renderers, define the scene's audience, task, meaningful information areas, and operation-specific contract boundary. See [Semantic Presentation Contract](/fullstack/semantic-presentation-contract).
+
 Start with the user's task, information hierarchy, and audience—not with the available layout node types or the number of fields. The generated CRUD layout is a valid baseline to review and refine, not a requirement to preserve unchanged.
 
 Choose the smallest structure that communicates the business form:
@@ -30,7 +32,7 @@ When the business grouping is unknown, keep the simpler layout or clarify the gr
 
 ## The layout layers are different
 
-Several APIs contain the word “layout,” but they own different concerns:
+Several APIs contain the word “layout,” but they own different concerns. Presentation metadata translates an already authorized scene contract; it does not define API membership, persistence, validation, authorization, page/state ownership, or SSR privacy:
 
 | Surface                                        | Owns                                                                                                           | Does not own                                              |
 | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
@@ -377,7 +379,7 @@ Here `formFieldLayout.inline: true` controls how each field wrapper is presented
 
 ## Authoring checklist
 
-1. Identify the audience, task, and meaningful field groupings for the operation-specific DTO before choosing a structural tree.
+1. Use the [Semantic Presentation Contract](/fullstack/semantic-presentation-contract) to identify the audience, task, scene, meaningful information areas, and operation-specific DTO boundary before choosing a structural tree.
 2. Start with DTO or resource metadata; do not hand-patch generated `.zova-rest` artifacts.
 3. Use no structural layout when schema order is sufficient. Otherwise use the smallest layout that communicates the business structure; reserve tabs for genuinely separate business domains or workflows.
 4. Use `formLayout` when the requirement is field placement, Grid or flow structure, groups, or tabs.

package/repo-docs/frontend/introduction.md

@@ -80,6 +80,7 @@ Use this path when the task is about UI composition, component contracts, form o
 
 - [Component Guide](/frontend/component-guide)
 - [Form Guide](/frontend/form-guide)
+- [Semantic Presentation Contract](/fullstack/semantic-presentation-contract)
 - [Form Layout Guide](/frontend/form-layout-guide)
 - [Image Guide](/frontend/image-guide)
 - [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
@@ -121,7 +122,7 @@ Use this path when the task is about data loading, API contracts, generated SDKs
 - [SSR Init Data](/frontend/ssr-init-data)
 - [SSR ClientOnly](/frontend/ssr-client-only)
 - [SSR SEO Meta](/frontend/ssr-seo-meta)
-- [SSR Env](/frontend/ssr-env)
+- [SSR Environment Variables](/frontend/ssr-env)
 
 ### Tooling support