cabloy 5.1.194 → 5.1.196

package/repo-docs/fullstack/ssr-entry-modes.md

@@ -0,0 +1,52 @@
+# Vona Integrated SSR and Zova Standalone SSR
+
+Cabloy has two ways to enter the same frontend SSR application during development. The difference is **which server receives the browser request and owns the response**, not whether the page uses SSR. Choose an entry based on the boundary you need to develop or verify.
+
+## The two entry modes
+
+**Vona integrated SSR** starts at the Vona server. Vona handles the incoming HTTP request, matches an SSR site, and uses the built frontend assets and Zova SSR runtime to render the response. The browser enters through Vona, so this is the path to check site dispatch and the fullstack HTTP boundary.
+
+**Zova standalone SSR** starts at the Zova development server. It renders the selected frontend flavor directly for fast page, route, and hydration iteration with hot reload. Backend APIs still belong to Vona; opening the Zova server directly does not exercise Vona's SSR site dispatch or built-artifact handoff.
+
+```text
+Vona integrated SSR:    browser → Vona → SSR site → built Zova SSR output → browser
+Zova standalone SSR:    browser → Zova development server → frontend SSR → browser
+```
+
+In the Cabloy Basic default environment, `SERVER_LISTEN_PORT=7102` is the Vona entry and `DEV_SERVER_PORT=9000` is the Zova development entry. These are separate listeners, not two ports for the same server. Zova's `API_BASE_URL` points to Vona, not to its own development port. Local environment overrides can change the ports; use the effective values in your checkout.
+
+## Start and use them in Cabloy Basic
+
+Start the Vona server from the repository root and visit a Vona-served site:
+
+```bash
+npm run dev
+# Web:   http://localhost:7102/
+# Admin: http://localhost:7102/admin/
+```
+
+For frontend iteration, start **one** Zova flavor in another terminal and open its development entry directly:
+
+```bash
+npm run dev:zova:web    # http://localhost:9000/
+# or
+npm run dev:zova:admin  # http://localhost:9000/admin/
+```
+
+For the other Cabloy Basic site URLs and the quick command comparison, see [Fullstack Quickstart](/fullstack/quickstart#3-start-vona-integrated-ssr). For Cabloy Start, keep the same entry-mode distinction but use the scripts, flavors, sites, and effective ports in the active Start checkout; do not copy Basic-specific flavor names or site paths blindly.
+
+## Which entry should you use?
+
+| Task                                                                  | Use                                                                           | What the result tells you                                                                     |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Iterate on a page, route, SSR render, or hydration                    | Zova standalone SSR (`9000` by default)                                       | The selected frontend flavor works through the Zova development entry.                        |
+| Check Vona site matching, backend-owned routing, or the HTTP response | Vona integrated SSR (`7102` by default)                                       | The request enters through Vona and exercises the integrated HTTP response path.              |
+| Verify release output or integrated browser acceptance                | Built SSR/REST artifacts, synchronized Vona dependencies, then the Vona entry | The intended built fullstack path is exercised, rather than just the Zova development server. |
+
+Direct access to `9000` cannot replace validation at `7102`. Before acceptance or deployment checks, build the required SSR/REST artifacts and synchronize them with Vona. For build and deployment steps, follow [SSR Build and Deploy Guide](/frontend/ssr-build-deploy-guide); for the Basic browser acceptance workflow, see [Frontend Scripts](/frontend/scripts#vona-integrated-ssr-browser-acceptance).
+
+## Do not confuse an entry mode with an SSR site
+
+“Standalone” here describes **direct access to the Zova development server**. It does not mean an independently deployable SSR application. An **SSR Site/flavor** identifies an application surface that Vona can mount and serve, such as Web or Admin. Adding a new deployable site requires its own aligned flavor, SSR/REST output, and Vona registration; it is not accomplished by starting another standalone development listener. See [Independent SSR Site and Flavor Setup](/fullstack/ssr-site-and-flavor-setup).
+
+For the cross-layer request flow, read [SSR Architecture Overview](/frontend/ssr-architecture-overview). For concise definitions, see the [Glossary](/reference/glossary#vona-integrated-ssr).

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

@@ -42,7 +42,9 @@ A new site is an ownership decision, not a convenient alias for an existing Admi
 
 ## Define the identity tuple
 
-Choose these values before editing source. Keep their spelling and ownership consistent:
+Choose these values before editing source. Classify the tuple as **observed existing**, **proposed new**, or **explicitly approved new**. A new tuple need not already exist: validate framework constraints and collisions against active source, obtain explicit approval of the concrete design and an `Accepted` governing ADR, then create it through a separately approved bounded execution task. Strategy selection or approval to generate planning records alone is insufficient. Keep unchecked values and controlling `TODO(confirm)` gates explicit.
+
+Label a new root wrapper as a **planned addition**, not a currently runnable command. Its execution task must create the durable manifest entry and inspect the resulting SSR/REST pair before running it. Keep tuple spelling and ownership consistent:
 
 | Identity               | Role                                                                                                            |
 | ---------------------- | --------------------------------------------------------------------------------------------------------------- |

package/repo-docs/fullstack/tutorial-5-backend-contract-sharing.md

@@ -47,6 +47,17 @@ Inspect the relevant command surfaces first:
 
 ```bash
 npm run zova :openapi
+```
+
+After updating the backend controller and DTOs, start Vona in a separate terminal and keep it running so the generator can read the current Swagger output:
+
+```bash
+npm run dev
+```
+
+Then configure the module's OpenAPI ownership if needed and regenerate its frontend consumers:
+
+```bash
 npm run zova :openapi:config demo-student
 npm run zova :openapi:generate demo-student
 ```
@@ -118,12 +129,7 @@ That is the practical forward chain: backend controller and DTO truth flows into
 
 ## Verification
 
-1. make sure the local dev workflow is running:
-
-```bash
-npm run dev
-```
-
+1. confirm that Vona, started before OpenAPI generation, is still running
 2. open `http://localhost:7102/admin/`
 3. enter the **Student** list page
 4. trigger the **Summary** row action and verify that it uses the regenerated frontend API and returns the expected Student summary data
@@ -148,4 +154,4 @@ npm run dev
 
 ## Next step
 
-Continue to [Tutorial 6: One Contract Surface, Four Uses](/fullstack/tutorial-6-one-contract-four-uses).
+Continue to [Tutorial 6: One Contract Model, Four Uses](/fullstack/tutorial-6-one-contract-four-uses).

package/repo-docs/fullstack/tutorial-6-one-contract-four-uses.md

@@ -1,8 +1,8 @@
-# Tutorial 6: One Contract Surface, Four Uses
+# Tutorial 6: One Contract Model, Four Uses
 
 <Badge type="info" text="Basic" />
 
-In this tutorial, one prompt lets AI close the series by showing Cabloy’s core fullstack idea: one field-oriented contract surface can drive several behaviors across backend and frontend.
+In this tutorial, one prompt lets AI close the series by showing how Cabloy's field-oriented contract model supports several behaviors across backend and frontend.
 
 This capstone sits on top of both the forward chain and the reverse chain rather than replacing either one.
 
@@ -14,7 +14,7 @@ This time the main teaching field is `mobile`, while `level` stays as the suppor
 
 ## Goal
 
-By the end of this tutorial, you will understand how one business field thread can participate in:
+By the end of this tutorial, you will understand how the field-oriented contract model supports:
 
 1. validation
 2. OpenAPI generation
@@ -44,13 +44,16 @@ Cabloy tries to reduce that duplication through a field-oriented contract and me
 
 ## CLI commands to inspect/use
 
-This tutorial is mainly a source-inspection and verification capstone.
+This tutorial is mainly a source-inspection and verification capstone. After updating the backend field and DTO contracts, start Vona in a separate terminal and keep it running so OpenAPI generation reads the current Swagger output:
 
-Useful commands include:
+```bash
+npm run dev
+```
+
+Then regenerate the frontend contract using the module configuration established in Tutorial 5:
 
 ```bash
 npm run zova :openapi:generate demo-student
-npm run dev
 ```
 
 Usage notes:
@@ -94,9 +97,7 @@ The supporting render example remains:
 
 ## What those files mean in the business thread
 
-This tutorial works best when you read `mobile` as one continuous contract thread.
-
-That is why `mobile` is the main capstone field, while `level` remains the supporting rendering field.
+Read `mobile` as the validation, OpenAPI, and serialization example, and `level` as the table and form rendering example. Together they show four uses of the same field-oriented contract model.
 
 ### Use 1: Validation
 
@@ -140,12 +141,7 @@ That keeps the masking rule close to the field contract ecosystem instead of sca
 
 ## Verification
 
-1. make sure the local dev workflow is running:
-
-```bash
-npm run dev
-```
-
+1. confirm that Vona, started before OpenAPI generation, is still running
 2. open `http://localhost:7102/admin/`
 3. enter the relevant **Student** page
 4. verify that `level` still shows the expected render-driven behavior

package/repo-docs/fullstack/tutorials-overview.md

@@ -84,9 +84,9 @@ See [Contract Loop Playbook](/fullstack/contract-loop-playbook) and [Frontend Me
 
 This phase teaches the **forward chain** of the contract loop: backend contract truth changes first, generated frontend consumers are refreshed second, and frontend follow-up stays thin and resource-owner-aware.
 
-### Phase 4: One field story across multiple contract surfaces
+### Phase 4: One field-oriented contract model across four uses
 
-- [Tutorial 6: One Contract Surface, Four Uses](/fullstack/tutorial-6-one-contract-four-uses)
+- [Tutorial 6: One Contract Model, Four Uses](/fullstack/tutorial-6-one-contract-four-uses)
 
 ## The standard tutorial structure
 

package/repo-docs/index.md

@@ -4,7 +4,7 @@ layout: home
 hero:
   name: 'Cabloy'
   text: 'Node.js fullstack framework for AI vibe coding'
-  tagline: One fullstack system for AI vibe coding—bidirectional type sync, CLI-first workflows, and Traceable Spec Delivery from product intent to verifiable evidence.
+  tagline: Vona and Zova stay connected through bidirectional type sync; AI Spec-Driven Development guides work from confirmed specs to verifiable delivery.
   actions:
     - theme: brand
       text: Get Started
@@ -20,65 +20,43 @@ hero:
       link: /ai/ai-spec-driven-development
 
 features:
-  - title: One fullstack system
-    details: Build backend and frontend together instead of assembling separate stacks.
   - title: Bidirectional type sync
-    details: Keep backend contracts and frontend metadata aligned through a two-way contract loop.
+    details: Generate Zova SDKs from Vona OpenAPI contracts and feed Zova metadata back to backend tooling.
   - title: CLI-first workflows
-    details: Use explicit commands for scaffolding, generation, refactors, and verification.
-  - title: Docs and skills
-    details: Give people and AI agents reusable, source-grounded guidance for the current repository.
+    details: Scaffold, regenerate, refactor, and verify through Vona and Zova commands.
   - title: AI Spec-Driven Development
-    details: Connect confirmed product intent to contracts, bounded delivery, acceptance procedures, and verifiable evidence.
-  - title: Vona + Zova
-    details: Use aligned backend and frontend layers for code sharing and cross-stack consistency.
-  - title: Modular delivery
-    details: Organize capabilities as suites and modules, then deliver SSR, SPA, Web, and Admin applications with shared conventions.
-  - title: Semantic presentation
-    details: Translate confirmed audience, task, scene, and DTO contracts into schema-driven UI without changing security or ownership authority.
+    details: Turn confirmed product intent into bounded work, acceptance procedures, and verifiable evidence.
+  - title: Suites and modules
+    details: Organize capabilities for SSR, SPA, Web, and Admin applications with shared conventions.
 ---
 
-# Cabloy Documentation
+## Choose a reading path
 
-Cabloy is a Node.js fullstack framework for AI vibe coding, with AI Spec-Driven Development for traceable, evidence-backed delivery. It brings backend and frontend work into one system, with bidirectional type sync, CLI-first workflows, and source-grounded docs and skills for people and AI agents.
+### Start a project
 
-[AI Spec-Driven Development](/ai/ai-spec-driven-development) adds Cabloy's disciplined delivery path: **Traceable Spec Delivery** connects confirmed product intent to contracts, bounded work, acceptance procedures, and verifiable evidence. Start with the [Contract Loop Playbook](/fullstack/contract-loop-playbook) to understand bidirectional type sync, then use the [Fullstack CLI](/fullstack/cli) and [AI Development](/ai/introduction) guides to follow the current repository. Cabloy coordinates Vona and Zova as its backend and frontend layers, while Cabloy Basic and Cabloy Start are related, complete edition baselines built on that shared architecture. See [Editions Overview](/editions/overview) for the relationship and deliberate edition differences.
+1. [Choose an edition](/editions/overview#choosing-an-edition)
+2. [Fullstack Quickstart](/fullstack/quickstart)
+3. [Fullstack Quick Start Tutorials](/fullstack/tutorials-overview)
 
-## What you can do here
+### Develop across Vona and Zova
 
-- **Get started quickly** with the fullstack quickstart and core Cabloy concepts
-- **Learn the shared fullstack architecture** across Cabloy, Vona, and Zova
-- **Explore backend and frontend workflows** without losing the cross-stack picture
-- **Understand Cabloy’s performance philosophy and runtime stability story** with [Framework Performance](/fullstack/framework-performance)
-- **See how Cabloy Basic and Cabloy Start differ by edition** when UI assumptions, flavors, modules, SSR sites, or AI workflow guidance matter
-- **Follow AI Spec-Driven Development** from confirmed product intent to evidence-backed verification
-- **Use source-grounded AI vibe coding guidance** for prompting, workflow selection, and verification
+Use the contract loop when generated contracts or metadata cross the Vona-Zova boundary.
 
-## First reading path
-
-### For getting started
+1. [Fullstack Introduction](/fullstack/introduction)
+2. [Fullstack CLI](/fullstack/cli)
+3. [Contract Loop Playbook](/fullstack/contract-loop-playbook)
 
-1. [Fullstack Quickstart](/fullstack/quickstart)
-2. [Fullstack Quick Start Tutorials](/fullstack/tutorials-overview)
-3. [Cabloy Editions](/editions/overview#choosing-an-edition)
-4. [Fullstack Introduction](/fullstack/introduction)
+### Deliver from confirmed specs
 
-### For contributors and AI vibe coding workflows
+Use AI Spec-Driven Development to connect product intent, bounded work, and acceptance evidence.
 
-1. [Fullstack Introduction](/fullstack/introduction)
-2. [Fullstack CLI](/fullstack/cli)
-3. [VS Code Extensions](/fullstack/vscode-extensions)
-4. [AI Development Introduction](/ai/introduction)
-5. [AI Spec-Driven Development](/ai/ai-spec-driven-development)
-6. [Reference Introduction](/reference/introduction)
-7. [Editions Overview](/editions/overview)
+1. [AI Spec-Driven Development](/ai/ai-spec-driven-development)
+2. [AI Development Introduction](/ai/introduction)
 
-### For performance-oriented reading
+### Explore performance
 
-1. [Fullstack Introduction](/fullstack/introduction)
-2. [Framework Performance](/fullstack/framework-performance)
-3. [Cache Guide](/backend/cache-guide)
-4. [Vona + Zova Integration](/fullstack/vona-zova-integration)
+1. [Framework Performance](/fullstack/framework-performance)
+2. [Cache Guide](/backend/cache-guide)
 
 ## Documentation scope labels
 

package/repo-docs/public/cabloy.svg

@@ -0,0 +1,3 @@
+<svg width="32" height="32" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M14.1094 0C14.7552 0 15.1979 0.0729167 15.4375 0.21875C15.6771 0.364583 15.7969 0.619792 15.7969 0.984375V6.98438C15.7969 7.33854 15.6354 7.59375 15.3125 7.75C15 7.89583 14.474 7.96875 13.7344 7.96875C13.2448 7.96875 12.8646 7.9375 12.5938 7.875C12.3333 7.80208 12.151 7.69792 12.0469 7.5625C11.9427 7.42708 11.8906 7.23438 11.8906 6.98438C11.8906 5.94271 11.6042 5.10938 11.0312 4.48438C10.4688 3.85938 9.66146 3.54688 8.60938 3.54688C7.16146 3.54688 6.0625 4.06771 5.3125 5.10938C4.5625 6.15104 4.1875 7.65104 4.1875 9.60938C4.1875 11.5469 4.58333 13.0469 5.375 14.1094C6.17708 15.1615 7.30729 15.6875 8.76562 15.6875C9.67188 15.6875 10.5417 15.5677 11.375 15.3281C12.2083 15.0781 13.1146 14.7031 14.0938 14.2031C14.2604 14.1198 14.4167 14.0781 14.5625 14.0781C15.0521 14.0781 15.4583 14.5104 15.7812 15.375C15.9271 15.7708 16 16.125 16 16.4375C16 16.9688 15.7604 17.349 15.2812 17.5781C13.0521 18.6823 10.8281 19.2344 8.60938 19.2344C6.90104 19.2344 5.39583 18.8438 4.09375 18.0625C2.79167 17.2812 1.78125 16.1667 1.0625 14.7188C0.354167 13.2604 0 11.5573 0 9.60938C0 7.67188 0.348958 5.97917 1.04688 4.53125C1.74479 3.07292 2.70833 1.95312 3.9375 1.17188C5.17708 0.390625 6.57812 0 8.14062 0C9.96354 0 11.3177 0.65625 12.2031 1.96875V0.984375C12.2031 0.630208 12.3542 0.380208 12.6562 0.234375C12.9583 0.078125 13.4427 0 14.1094 0Z" fill="#FF9300"/>
+</svg>

package/repo-docs/public/favicon.svg

@@ -0,0 +1,3 @@
+<svg width="32" height="32" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M14.1094 0C14.7552 0 15.1979 0.0729167 15.4375 0.21875C15.6771 0.364583 15.7969 0.619792 15.7969 0.984375V6.98438C15.7969 7.33854 15.6354 7.59375 15.3125 7.75C15 7.89583 14.474 7.96875 13.7344 7.96875C13.2448 7.96875 12.8646 7.9375 12.5938 7.875C12.3333 7.80208 12.151 7.69792 12.0469 7.5625C11.9427 7.42708 11.8906 7.23438 11.8906 6.98438C11.8906 5.94271 11.6042 5.10938 11.0312 4.48438C10.4688 3.85938 9.66146 3.54688 8.60938 3.54688C7.16146 3.54688 6.0625 4.06771 5.3125 5.10938C4.5625 6.15104 4.1875 7.65104 4.1875 9.60938C4.1875 11.5469 4.58333 13.0469 5.375 14.1094C6.17708 15.1615 7.30729 15.6875 8.76562 15.6875C9.67188 15.6875 10.5417 15.5677 11.375 15.3281C12.2083 15.0781 13.1146 14.7031 14.0938 14.2031C14.2604 14.1198 14.4167 14.0781 14.5625 14.0781C15.0521 14.0781 15.4583 14.5104 15.7812 15.375C15.9271 15.7708 16 16.125 16 16.4375C16 16.9688 15.7604 17.349 15.2812 17.5781C13.0521 18.6823 10.8281 19.2344 8.60938 19.2344C6.90104 19.2344 5.39583 18.8438 4.09375 18.0625C2.79167 17.2812 1.78125 16.1667 1.0625 14.7188C0.354167 13.2604 0 11.5573 0 9.60938C0 7.67188 0.348958 5.97917 1.04688 4.53125C1.74479 3.07292 2.70833 1.95312 3.9375 1.17188C5.17708 0.390625 6.57812 0 8.14062 0C9.96354 0 11.3177 0.65625 12.2031 1.96875V0.984375C12.2031 0.630208 12.3542 0.380208 12.6562 0.234375C12.9583 0.078125 13.4427 0 14.1094 0Z" fill="#FF9300"/>
+</svg>

package/repo-docs/reference/repo-scripts.md

@@ -55,11 +55,15 @@ Cabloy Basic exposes these shared root scripts:
 The current Cabloy Basic root scripts also expose:
 
 ```bash
+npm run spec:check -- <suite>
+npm run spec:check -- <suite> --lightweight --format json
 npm run test:spec-charts
 npm run spec:charts -- <suite>
 npm run spec:charts:check -- <suite>
 ```
 
+`spec:check` is a read-only planning-authority structure audit: complete mode checks core records, formal definitions, exact references and traceability, WBS/progress consistency, and supported local Markdown links. `--lightweight` checks the present authority and references without requiring a full baseline or charts; `--format json` emits deterministic diagnostics. Audit regressions run under `test:agent-governance`. A structural pass does not authenticate approval, business completeness, implementation, or acceptance evidence; existing legacy gaps should be reported rather than filled with invented requirements.
+
 `spec:charts` refreshes the generated Gantt and burndown SVG views for a chart-compatible `repo-specs/<suite>/` record. `spec:charts:check` validates the supported input contract and detects stale generated views; `test:spec-charts` runs the chart-tool test suite. The deterministic implementation lives in `repo-agent-governance/tools/spec-charts/`, not inside a provider-specific skill discovery directory.
 
 ### Chart input contract
@@ -68,7 +72,8 @@ The generator consumes `README.md`, `pdp-wbs.md`, `test-plan.md`, and `progress.
 
 - formal `### Phase <number>:` and `#### WBS-...:` headings in the WBS, with supported dependency labels
 - formally defined `ATP-*` scenarios in the test plan for every ATP reference used by a WBS task
-- one progress row for each WBS item, with the WBS ID in the first cell and its supported status in the second cell
+- exactly one progress row for each WBS item, with columns identified by the `WBS ID` and `Status` headers, regardless of their order; explicit WBS status must agree
+- unique formal definitions and an acyclic dependency graph; both `Dependency:` and `Dependencies:` are supported, phase defaults apply only before the first task, and explicit task dependencies override them
 - a README whose current title and language should be reflected by regenerated chart output
 
 A legacy suite with a different WBS or progress-table layout is not chart-compatible until a deliberate record-format normalization aligns its authoritative Markdown with this input contract. Format normalization must preserve the existing planning authority; it does not require an unrelated product or delivery change.