cabloy 5.1.194 → 5.1.196

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

@@ -69,6 +69,7 @@ const fullstackGroups = [
     text: 'Fullstack / Getting Started',
     items: [
       { text: 'Introduction', link: '/fullstack/introduction' },
+      { text: 'Development History', link: '/fullstack/development-history' },
       { text: 'Quickstart', link: '/fullstack/quickstart' },
       { text: 'Suites and Modules', link: '/fullstack/suites-and-modules' },
     ],
@@ -98,7 +99,7 @@ const fullstackGroups = [
         link: '/fullstack/tutorial-5-backend-contract-sharing',
       },
       {
-        text: 'Tutorial 6: One Contract Surface, Four Uses',
+        text: 'Tutorial 6: One Contract Model, Four Uses',
         link: '/fullstack/tutorial-6-one-contract-four-uses',
       },
     ],
@@ -115,7 +116,7 @@ const fullstackGroups = [
     ],
   },
   {
-    text: 'Architecture & Integration',
+    text: 'Architecture & Editions',
     items: [
       {
         text: 'Comparison with Other Frameworks',
@@ -123,18 +124,27 @@ const fullstackGroups = [
       },
       { text: 'Framework Performance', link: '/fullstack/framework-performance' },
       { text: 'Vona + Zova Integration', link: '/fullstack/vona-zova-integration' },
-      { text: 'SSR Site and Flavor Setup', link: '/fullstack/ssr-site-and-flavor-setup' },
-      { text: 'A-Pay Payment Suite', link: '/fullstack/a-pay-payment-suite' },
       {
-        text: 'Payment Provider Sandbox Configuration',
-        link: '/fullstack/payment-sandbox-configuration',
+        text: 'Edition Collaboration Differences',
+        link: '/fullstack/edition-collaboration-differences',
       },
+    ],
+  },
+  {
+    text: 'Contracts & Integration',
+    items: [
       { text: 'Contract Loop Playbook', link: '/fullstack/contract-loop-playbook' },
       { text: 'Semantic Presentation Contract', link: '/fullstack/semantic-presentation-contract' },
+      { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
       {
-        text: 'Admin Resource and Web Self-Service',
-        link: '/fullstack/admin-resource-and-web-self-service',
+        text: 'Frontend Metadata Back to Backend',
+        link: '/fullstack/frontend-metadata-to-backend',
       },
+    ],
+  },
+  {
+    text: 'Metadata-Driven UI',
+    items: [
       {
         text: 'Backend Metadata to Frontend Table Actions',
         link: '/fullstack/backend-metadata-to-frontend-table-actions',
@@ -151,20 +161,32 @@ const fullstackGroups = [
         text: 'Backend Metadata to Frontend Table Actions Source Reading Map',
         link: '/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map',
       },
-      { text: 'Fullstack Image Workflow', link: '/fullstack/image-workflow' },
-      { text: 'Fullstack File Workflow', link: '/fullstack/file-workflow' },
-      { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
+    ],
+  },
+  {
+    text: 'Resource & SSR Patterns',
+    items: [
+      { text: 'Vona Integrated SSR vs Zova Standalone SSR', link: '/fullstack/ssr-entry-modes' },
+      { text: 'SSR Site and Flavor Setup', link: '/fullstack/ssr-site-and-flavor-setup' },
       {
-        text: 'Frontend Metadata Back to Backend',
-        link: '/fullstack/frontend-metadata-to-backend',
+        text: 'Admin Resource and Web Self-Service',
+        link: '/fullstack/admin-resource-and-web-self-service',
       },
       {
         text: 'One-to-One Companion Resource',
         link: '/fullstack/one-to-one-companion-resource-guide',
       },
+    ],
+  },
+  {
+    text: 'Media & Payments',
+    items: [
+      { text: 'Fullstack Image Workflow', link: '/fullstack/image-workflow' },
+      { text: 'Fullstack File Workflow', link: '/fullstack/file-workflow' },
+      { text: 'A-Pay Payment Suite', link: '/fullstack/a-pay-payment-suite' },
       {
-        text: 'Edition Collaboration Differences',
-        link: '/fullstack/edition-collaboration-differences',
+        text: 'Payment Provider Sandbox Configuration',
+        link: '/fullstack/payment-sandbox-configuration',
       },
     ],
   },
@@ -194,22 +216,22 @@ const referenceGroups = [
 const GA_MEASUREMENT_ID = 'G-2NYR9RGRL4'; // process.env.GA_MEASUREMENT_ID;
 const gaHead = GA_MEASUREMENT_ID
   ? [
-      [
-        'script',
-        {
-          async: '',
-          src: `https://www.googletagmanager.com/gtag/js?id=${GA_MEASUREMENT_ID}`,
-        },
-      ],
-      [
-        'script',
-        {},
-        `window.dataLayer = window.dataLayer || [];
+    [
+      'script',
+      {
+        async: '',
+        src: `https://www.googletagmanager.com/gtag/js?id=${GA_MEASUREMENT_ID}`,
+      },
+    ],
+    [
+      'script',
+      {},
+      `window.dataLayer = window.dataLayer || [];
 function gtag(){dataLayer.push(arguments);}
 gtag('js', new Date());
 gtag('config', '${GA_MEASUREMENT_ID}');`,
-      ],
-    ]
+    ],
+  ]
   : [];
 
 export default defineConfig({
@@ -218,7 +240,10 @@ export default defineConfig({
   lang: 'en-US',
   base: '/',
   ignoreDeadLinks: [/^https?:\/\/localhost/],
-  head: gaHead,
+  head: [
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
+    ...gaHead,
+  ],
   transformPageData(pageData) {
     if (!/^blogs\/[^/]+\/index\.md$/.test(pageData.relativePath)) return;
 

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

@@ -33,7 +33,7 @@ Use [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation) instea
 
 ## Establish the execution boundary first
 
-Start by inspecting the active repository, edition marker, current revision, and working-tree state. Then build an execution dossier for the selected increment.
+Inspect the active root, current revision, working tree, and edition markers. Exactly one marker selects Basic or Start; both mean stop as invalid/ambiguous. If neither marker is present, inspect the owning package/structure and ask before edition-sensitive execution. Then build the selected increment's dossier.
 
 The dossier identifies:
 
@@ -46,7 +46,11 @@ The dossier identifies:
 - approved verification procedures, expected redacted evidence, and allowed record updates
 - blockers, unresolved `TODO(confirm)` items, excluded unsafe operations, and one next action
 
-Require explicit approval of the dossier before source changes, meaningful verification, evidence/status updates, or specialist execution. Do not reserve a task by marking it `in-progress` before approved work actually starts.
+Require explicit dossier approval before source changes, meaningful verification, evidence/status updates, or specialist execution. Generation approval, concrete design/ADR acceptance, and execution approval are separate. Do not reserve a task by marking it `in-progress` before approved work starts.
+
+Classify targets as **observed existing**, **proposed new**, or **explicitly approved new**, as in [spec generation](/ai/playbook-spec-generation#existing-facts-and-new-designs). An approved new site/flavor tuple may be created before its future source exists if framework constraints and collisions were checked, you explicitly approved the concrete design, and its governing ADR is `Accepted`. Cite accepted design authority and planned paths/manifests in the dossier. Shared integration still requires an observed owner. Controlling TODOs, unaccepted ADRs, and blocked gates remain blockers; absence of future source alone is not one.
+
+A new wrapper is a planned addition: create it within approved scope, inspect its durable manifest and paired SSR/REST outputs, then run it. Do not treat the proposed command as already runnable.
 
 ## Read authority before implementation
 
@@ -58,7 +62,9 @@ Read the suite records in this order:
 4. linked ATP procedures and release gates in `test-plan.md`
 5. `progress.md` for derived status, blockers, waivers, evidence pointers, and next proof
 6. linked evidence, runbooks, presentation records, or rollout records when they apply
-7. `implementation-gantt.svg` and `implementation-burndown.svg` as derived views to check for freshness, not authority
+7. applicable implementation charts, checking freshness only with complete supported inputs; report incomplete lightweight/legacy inputs rather than forcing new business declarations
+
+Keep planning authority audit (`npm run spec:check -- <suite>`, with `--lightweight` only for agreed limited scope), chart model/freshness, and human approval/evidence as three separate gates. Compatible catalogue tables can define legacy ATPs in their owning role; matrices and evidence cannot. A static pass does not clear a controlling TODO, accept an ADR, or prove ATP execution.
 
 When records conflict, return to [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation) before implementation. Do not resolve an authority contradiction through an execution note, a chart edit, or a source workaround.
 
@@ -111,7 +117,7 @@ A successful build, generation command, hook, manual walkthrough, screenshot, or
 
 ## Refresh derived charts last
 
-After evidence and progress are accurate, refresh the two derived views when the suite's authoritative Markdown follows the [chart input contract](/reference/repo-scripts#chart-input-contract). Refresh again when the suite README title or language changes:
+After evidence and progress are accurate, refresh both derived views only when complete supported README/WBS/ATP/progress inputs follow the [chart input contract](/reference/repo-scripts#chart-input-contract). Refresh again when README title/language changes. If legacy/lightweight inputs are incomplete, report the precise omission and route necessary authority repair through planning; never invent business definitions to force chart generation. Find progress rows by `WBS ID` and `Status` headers, not fixed column positions.
 
 ```bash
 npm run spec:charts -- <suite>

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

@@ -31,7 +31,7 @@ Use a different path when the task is already an approved bounded WBS increment,
 ## What happens after you invoke it
 
 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.
+2. **AI identifies the planning scope.** It chooses a complete new baseline, incremental maintenance of an existing set, or explicitly approved lightweight planning. An existing directory is normally the update destination, not a conflict or reset request. Basic and Start share the model, but runtime details come from the active edition. Both edition markers mean stop; if neither marker is present, inspect the owning package/structure and ask before edition-sensitive planning.
 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.
@@ -48,7 +48,19 @@ The initial business description can be short. During the conversation, AI may a
 - delivery, release, and verification expectations
 - unresolved durable decisions, the WBS branches they block, justified optional records, and the initial delivery status
 
-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.
+AI asks only for missing decisions. If the existing strategy still governs, it does not repeat a Web/Admin four-way choice; a single unresolved audience gets a focused question. Unresolved naming takes a naming-only detour through `cabloy-domain-planning`, then returns here without scaffolding.
+
+## Existing facts and new designs
+
+Targets have three distinct states:
+
+- **Observed existing**: source/configuration was inspected and cited. Shared-site integration requires an observed owner.
+- **Proposed new**: a deliberately new design, not a claim that source already exists.
+- **Explicitly approved new**: the concrete tuple passed framework-constraint and collision checks, you explicitly approved the design, and its governing ADR is `Accepted`.
+
+For a new independent SSR site, validate site ID, public path, flavor, configuration ownership, site module/registration, copied bundle, generated REST package, and paired SSR/REST commands together. The target need not exist before approval: a bounded execution task may create an explicitly approved new tuple after its own dossier approval. Unknown or unchecked values remain `TODO(confirm)`; they block only dependent work. A new wrapper is a **planned addition**, not a current command to run. See [Independent SSR Site and Flavor Setup](/fullstack/ssr-site-and-flavor-setup).
+
+Keep approval domains separate: approval to generate records does not accept a durable ADR or authorize source execution. Site-strategy selection approves only that input; design/ADR acceptance and bounded execution approval remain explicit.
 
 ## What gets generated or updated
 
@@ -77,7 +89,7 @@ repo-specs/<suite>/
 | `test-plan.md`             | Acceptance procedures, expected proof, and release gates                                         |
 | `progress.md` and charts   | Derived delivery status and planning views, not upstream authority                               |
 
-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.
+Charts are generated only after complete supported README/WBS/ATP/progress inputs exist. A deliberately lightweight set agrees on selected records and omissions instead of forcing a complete baseline or charts. AI adds presentation contracts, rollout records, runbooks, extra ADRs, or evidence only when justified; it never creates empty evidence to imply execution.
 
 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.
 
@@ -105,6 +117,31 @@ A product or technical change belongs in its PRD, SRS, or accepted ADR before it
 
 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.
 
+## Check planning without claiming implementation
+
+Use three independent gates:
+
+1. **Planning authority audit** checks formal definitions, exact references, declared PRD → SRS → WBS → ATP associations, and local links:
+
+   ```bash
+   npm run spec:check -- <suite>
+   # Only for explicitly limited planning scope:
+   npm run spec:check -- <suite> --lightweight
+   ```
+
+   Lightweight mode reports omitted owners/chain coverage; it does not permit dangling references. If progress is present, its WBS owner is still needed.
+2. **Chart model/freshness** checks supported WBS/dependency/ATP/progress consistency and generated-view freshness, only with complete supported inputs:
+
+   ```bash
+   npm run spec:charts -- <suite>
+   npm run spec:charts:check -- <suite>
+   ```
+
+   Regenerate after WBS, test-plan, progress, or README title/language changes. With incomplete lightweight/legacy inputs, report the precise chart gap; do not invent business definitions or status to make a generator pass.
+3. **Human approval/evidence review** retains ADR acceptance, controlling TODOs, bounded execution approval, and observed ATP proof as separate requirements. Neither static check approves a design or establishes `verified`.
+
+New specs use atomic `- **PRD-...**: <body>` / `- **SRS-...**: <body>` declarations, phase/task WBS headings with explicit Dependencies, Traceability, Tasks, and Acceptance checks, and `### ATP-...: <title>` scenarios under `## Acceptance Scenario Catalogue` with Setup, Procedure, Expected result, Minimum proof, and Traceability. Resolve progress columns by `WBS ID` and `Status` headers rather than fixed positions. Compatible legacy catalogue tables remain supported; matrices and evidence are not definitions. Report legacy gaps without silently rewriting business meaning. See [Repo Scripts](/reference/repo-scripts) for the active deterministic command contracts.
+
 ## What happens next
 
 After the specification set is coherent and one bounded WBS increment is approved, execute that increment in Claude Code:

package/repo-docs/ai/skills.md

@@ -51,9 +51,9 @@ For edition-aware skills, use [Cabloy Editions: For AI Development](/editions/ov
 The repository currently authors these cross-stack and monorepo-wide workflows in `repo-agent-governance/skills/` and renders them to root platform adapters; Codex and Cursor discovery remains subject to external client validation:
 
 - `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; 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-domain-planning` for confirming providerId, suite, and capability names; a naming-only detour from specification generation returns there without scaffolding
+- `cabloy-spec-generation` for complete new baselines, incremental maintenance, or explicitly lightweight planning; it separates generation approval, design/ADR acceptance, and bounded execution approval, audits authority, and refreshes charts only with complete supported inputs; see [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation)
+- `cabloy-spec-execution` for one explicitly approved WBS increment, including creation of an approved new target whose future source does not exist yet; it preserves controlling gates, specialist implementation, retained evidence, and conditional derived-view 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)

package/repo-docs/backend/controller-aop-guide.md

@@ -115,6 +115,16 @@ These shorthands still map back to the generic aspect model.
 
 The global Passport guard is the baseline for controller actions: without a local Passport decorator, an action requires an authenticated and activated user. It is not public.
 
+`@Passport.activated(...)` changes the activation requirement for an authenticated user:
+
+| Value | Requirement | Typical use |
+| --- | --- | --- |
+| `true` | The user must be activated; this is the default. | Ordinary protected actions. |
+| `false` | The user must **not** be activated. This does not mean “skip the check.” | An account-activation action. |
+| `'noCheck'` | Do not check activation state; both activated and unactivated users can proceed. | Logout, including for an unactivated account. |
+
+All three values still require authentication by default. An unauthenticated request is rejected; use `@Passport.public()` only if anonymous access is intended. A disabled account is still rejected regardless of the activation setting. The guard returns `403` when an authenticated user fails the account-status or activation check.
+
 Use a local Passport or domain guard when an action needs a policy beyond that baseline:
 
 - use `@Passport.public()` only when anonymous access is intentional

package/repo-docs/backend/field-indexes.md

@@ -60,6 +60,29 @@ class MetaIndex {}
 
 This is especially valuable for maintainability because it reduces stringly-typed drift.
 
+### Multiple indexes on one table
+
+Declare each table only once in an `indexes` object, whether using direct properties or `$tableColumns`. The helper returns one property keyed by the table name; spreading multiple calls for the same table overwrites earlier values rather than combining them. Put all specifications for that table in one array:
+
+```typescript
+@Meta({
+  indexes: {
+    ...$tableColumns('payPaymentSession', [
+      'businessReference',
+      'providerCorrelationReference',
+      'state+expiresAt',
+    ]),
+  },
+})
+class MetaIndex {}
+```
+
+Each array entry defines a separate index. In this example, the first two entries are independent single-column indexes; `state+expiresAt` defines one composite index, with `state` as its leading column. An array such as `['state', 'expiresAt']` would instead define two single-column indexes. The typed helper accepts arrays containing both single-column fields and two-column `+` specifications.
+
+### Generated names and verification
+
+The current index reconciler names an index `idx_<table>_<first-column>` and checks existing indexes by that leading column. Two intended indexes with the same leading column, such as `state+expiresAt` and `state+nextAttemptAt`, can therefore collide or leave one uncreated. Do not change column order merely to avoid a naming collision: order is part of the query access pattern. Inspect the resulting definitions, not just whether initialization succeeded.
+
 ## App-config override support
 
 Field indexes can also be configured through app config.
@@ -84,6 +107,8 @@ Also ask:
 2. should the index belong in `meta.index`?
 3. does a business key need tenant-scoped uniqueness, to be enforced in tenant-aware business logic rather than with `table.unique(...)`?
 4. is the typed style a better fit than raw string declarations?
+5. does each table have one effective declaration containing every intended index specification, without conflicting leading columns?
+6. do the resulting database indexes have the intended columns in the intended order? Check both registered metadata and physical index definitions; a passing type check or successful initialization alone does not establish this.
 
 That leads to backend changes that are more production-aware and more aligned with Vona’s module metadata model.
 

package/repo-docs/blogs/cabloy-fullstack-resource-addressing/index.md

@@ -187,7 +187,7 @@ If this field needs specialized controls instead of the default Renderer, it can
 
 That does not mean each field automatically grows a complete UI, nor that every presentation decision belongs in the backend. It means the field’s business meaning, data contract, and permitted exposure do not have to be copied into backend DTOs, frontend request types, form rules, table columns, and response post-processing—and then manually kept aligned.
 
-In this **forward contract chain**, backend Controllers, DTOs, Entities, and validation rules are the source of truth. Vona generates OpenAPI; Zova then generates or consumes SDK/Schema contract material. When a backend contract changes, the recommended path is to propagate that truth forward rather than hand-edit multiple frontend copies. [Backend OpenAPI to Frontend SDK](https://cabloy.com/fullstack/openapi-to-sdk) and [One Contract Surface, Four Uses](https://cabloy.com/fullstack/tutorial-6-one-contract-four-uses) describe the boundary of that chain.
+In this **forward contract chain**, backend Controllers, DTOs, Entities, and validation rules are the source of truth. Vona generates OpenAPI; Zova then generates or consumes SDK/Schema contract material. When a backend contract changes, the recommended path is to propagate that truth forward rather than hand-edit multiple frontend copies. [Backend OpenAPI to Frontend SDK](https://cabloy.com/fullstack/openapi-to-sdk) and [One Contract Model, Four Uses](https://cabloy.com/fullstack/tutorial-6-one-contract-four-uses) describe the boundary of that chain.
 
 ## Coordinate five: routes choose a UI scene; Resource identities choose business context
 

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

@@ -358,7 +358,7 @@ Use the tutorial series as examples of the two chains:
 - [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing) — reverse chain, built-in metadata branch
 - [Tutorial 4: Custom Form/Table Renderers for Level](/fullstack/tutorial-4-custom-level-renderers) — reverse chain, custom resource handoff branch
 - [Tutorial 5: Backend Contract Sharing](/fullstack/tutorial-5-backend-contract-sharing) — forward chain, backend-emitted contract branch
-- [Tutorial 6: One Contract Surface, Four Uses](/fullstack/tutorial-6-one-contract-four-uses) — one field story spanning multiple contract surfaces
+- [Tutorial 6: One Contract Model, Four Uses](/fullstack/tutorial-6-one-contract-four-uses) — two field examples spanning validation, OpenAPI, rendering, and serialization
 
 ## Related docs
 

package/repo-docs/fullstack/development-history.md

@@ -0,0 +1,24 @@
+# CabloyJS Development History
+
+CabloyJS has evolved from a JavaScript-based Node.js fullstack framework into a TypeScript-based system built on Vona and Zova. Three milestones explain the transition.
+
+## 2016 onward: V1–V4
+
+Development began in 2016. Across V1, V2, V3, and V4, CabloyJS refined its fullstack architecture and accumulated the conventions that led some developers to describe it as a “textbook-like framework.”
+
+Feedback also pointed toward a new direction: TypeScript support and a clearer separation between frontend and backend development. These ideas shaped the next major redesign.
+
+## 2023: The V5 redesign
+
+In 2023, work began on a redesigned V5 architecture. Rather than incrementally adapting the earlier JavaScript framework, the project adopted TypeScript and a frontend/backend separation model built around two frameworks:
+
+- **ZovaJS** provides the frontend framework. Its programming model brings together Vue 3 reactivity, TSX authoring, and inversion of control (IoC).
+- **VonaJS** provides the backend framework and fullstack integration. It connects backend contracts with frontend applications across SSR, SPA, Web, and Admin use cases.
+
+The two layers remain connected through [bidirectional contract workflows](/fullstack/contract-loop-playbook), including backend OpenAPI contracts consumed by the frontend and frontend metadata consumed by backend tooling.
+
+## April 13, 2026: V5 release
+
+ZovaJS V5 and VonaJS V5 were officially released on April 13, 2026. Built on these foundations, CabloyJS V5 continues the goal behind the “textbook-like framework” description: make fullstack architecture understandable, consistent, and productive in day-to-day development.
+
+For the current architecture and edition-specific project baselines, continue with the [Fullstack Introduction](/fullstack/introduction) and [Editions Overview](/editions/overview).

package/repo-docs/fullstack/introduction.md

@@ -1,178 +1,47 @@
 # Fullstack Introduction
 
-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, 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.
-
-## What Cabloy emphasizes
-
-- **One fullstack system** — build backend and frontend together instead of assembling separate stacks
-- **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
-
-## How to approach fullstack work
-
-For contributor and automation workflows in this repository, prefer this order:
-
-1. inspect the root `package.json` and shared monorepo scripts first
-2. inspect `npm run vona`, `npm run zova`, and the shared fullstack CLI workflow before inventing custom steps
-3. detect the active edition before making UI-sensitive or flavor-sensitive assumptions
-4. explain shared cross-stack concepts once, then isolate edition-specific notes only where the editions intentionally diverge
-
-## Fullstack reading paths
-
-Use this page as the main fullstack hub, then choose the path that matches your task.
-
-### Getting started path
-
-Start here when you want the shortest route to a working monorepo mental model:
-
-- [Quickstart](/fullstack/quickstart)
-- [Suites and Modules](/fullstack/suites-and-modules)
-- [CLI](/fullstack/cli)
-- [VS Code Extensions](/fullstack/vscode-extensions)
-
-### Architecture and integration path
-
-Use this path when the task is about how backend and frontend stay aligned inside one framework system:
-
-- [Comparison with Other Frameworks](/fullstack/comparison-with-other-frameworks)
-- [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)
-- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
-- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
-
-### Edition-aware collaboration path
-
-Use this path when the task depends on edition boundaries, UI assumptions, or cross-repo delivery differences:
-
-- [Edition Collaboration Differences](/fullstack/edition-collaboration-differences)
-- [Cabloy Editions](/editions/overview#choosing-an-edition)
+Cabloy is a Node.js fullstack framework for AI vibe coding, with AI Spec-Driven Development guiding work from confirmed specs to verifiable delivery.
 
 ## Shared architecture
 
-Cabloy coordinates its backend and frontend layers as one fullstack system:
-
-- **Vona** provides the backend framework and runtime capabilities.
-- **Zova** provides the frontend framework and application capabilities.
-- Root scripts, shared terminology, and CLI-first workflows keep the layers aligned within each edition repository.
-
-Cabloy Basic and Cabloy Start are related, complete edition baselines built on this shared architecture, not alternatives to the Vona and Zova layers. They intentionally compose UI, flavors, modules, SSR sites, and project assets differently. See [Editions Overview](/editions/overview) for the complete relationship and edition differences.
-
-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.
-
-### 1. Frontend build output participates directly in backend SSR
-
-Zova owns the frontend application, but its build output is not treated as a completely separate artifact that the backend ignores.
-
-In Cabloy’s fullstack flow:
-
-- the frontend is built from Zova source
-- the generated bundle and related SSR output are consumed by the Vona-side SSR runtime
-- backend rendering and frontend hydration stay in one coordinated SSR path rather than two unrelated systems
-
-In earlier standalone-repo explanations, this was often described as placing the frontend bundle into the backend for direct SSR rendering. In the current monorepo, the important principle stays the same while the workflow is cleaner: shared scripts and integrated repository structure let frontend build artifacts flow into the backend-side SSR process.
-
-For the integration workflow and current monorepo shape, see [Vona + Zova Integration](/fullstack/vona-zova-integration) and [SSR Overview](/frontend/ssr-overview).
-
-### 2. Bidirectional type sync through the contract loop
-
-Cabloy does not treat type sharing as backend-to-frontend only. The collaboration loop provides bidirectional type sync:
-
-- **Backend → Frontend**: Vona emits Swagger/OpenAPI contracts that Zova uses to generate frontend SDKs and related schema-aware helpers
-- **Frontend → Backend**: Zova generates structural metadata and types such as routes, components, and icons, which can be reflected back into backend-side tooling and type hints
-
-This two-way contract loop reduces duplicate declarations and lets backend and frontend evolve from generated source truth instead of hand-maintained memory.
-
-Start with the canonical [Contract Loop Playbook](/fullstack/contract-loop-playbook), then use the directional deep dives [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
-
-Use the playbook to distinguish four cases clearly:
-
-- forward chain
-- reverse chain
-- consumer drift
-- local dependency drift
-
-The contract-loop model is shared across Cabloy Basic and Cabloy Start. Detect the edition to choose concrete flavor commands and generated-output paths, not to redefine the workflow model.
-
-When the reverse direction involves newly added frontend resources that backend tooling or backend metadata will consume, treat that as an operational handoff rather than a conceptual one: refresh generated frontend output, run the relevant flavor build, then run `npm run deps:vona`, and if the generated `.zova-rest` artifacts already contain the expected changes but Vona still sees stale shared types, rebuild `vona/node_modules` and reinstall dependencies.
-
-## How the fullstack system stays connected
-
-At the repository level, shared scripts, shared terminology, and CLI-first workflows keep Vona and Zova aligned as one framework system.
+Vona provides the backend framework and runtime. Zova provides the frontend framework and application layer. Suites and modules organize capabilities across Admin, Web, SSR, and SPA applications. Root scripts and CLI workflows connect these layers within each edition repository.
 
-For the shared terminal-first workflow model, see [Fullstack CLI](/fullstack/cli).
+Cabloy Basic and Cabloy Start are complete, separate project baselines built on this architecture. They share the Vona + Zova engineering model but can differ in UI layer, frontend flavors, modules, SSR sites, and project assets. See [Editions Overview](/editions/overview) before choosing edition-specific commands or UI conventions.
 
-## Why the monorepo matters
+## How Vona and Zova connect
 
-The monorepo makes it possible to keep backend and frontend concepts, tooling, and generated outputs aligned from source rather than memory, for example:
+### Vona integrated SSR
 
-- how frontend routes and components are reflected back into backend type hints
-- how backend OpenAPI and DTO output feeds frontend SDK generation
-- how common concepts can be documented once before edition-specific notes branch out
-- how Vona and Zova CLI capabilities can be reused instead of rebuilding scaffolding by hand
+Zova builds the frontend application and SSR artifacts. In Vona integrated SSR, Vona consumes those artifacts to render the page, and the frontend hydrates it in the browser.
 
-## Technology Stack
+Zova standalone SSR is a separate development-server entry point for frontend work. Opening it directly does not verify the Vona integration path. See [Vona + Zova Integration](/fullstack/vona-zova-integration) and [SSR Overview](/frontend/ssr-overview) for the two layers in more detail.
 
-### General
+### Bidirectional contract loop
 
-| Package    | Version  |
-| ---------- | -------- |
-| TypeScript | `^5.9.3` |
-| Zod        | `^4.3.6` |
+Type information moves in both directions, with a different source of truth on each side:
 
-### Backend (Vona)
+- **Backend to frontend:** Vona emits OpenAPI contracts that Zova uses to generate SDKs and schema-aware helpers.
+- **Frontend to backend:** Zova generates metadata and types for routes, components, and icons that backend tooling and type hints can consume.
 
-| Package                          | Version   |
-| -------------------------------- | --------- |
-| Koa                              | `^3.2.0`  |
-| Knex                             | `^3.2.9`  |
-| Redis Client (`ioredis`)         | `^5.10.1` |
-| SQLite Driver (`better-sqlite3`) | `^12.9.0` |
+The [Contract Loop Playbook](/fullstack/contract-loop-playbook) explains the generation, handoff, and verification steps for each direction, including recovery when generated output or local dependencies are stale.
 
-### Frontend (Zova)
+## How spec-driven delivery fits
 
-| Package        | Version     |
-| -------------- | ----------- |
-| Vue            | `^3.5.32`   |
-| Vite           | `^8.0.14`   |
-| Quasar         | `^2.19.3`   |
-| TanStack Query | `^5.100.10` |
-| TanStack Form  | `^1.32.0`   |
-| TanStack Table | `^8.21.3`   |
+[AI Spec-Driven Development](/ai/ai-spec-driven-development) uses Traceable Spec Delivery to carry confirmed product intent into bounded work and verifiable evidence. The contract loop keeps Vona and Zova consumers aligned when that work changes a fullstack contract. Contract synchronization alone does not establish product approval or complete acceptance.
 
-### Edition-specific UI Stack
+For schema-driven UI decisions, the [Semantic Presentation Contract](/fullstack/semantic-presentation-contract) connects the approved audience and task to the appropriate renderer without changing security or ownership authority.
 
-- **Cabloy Basic**: DaisyUI + Tailwind CSS
-- **Cabloy Start**: Vuetify
+## Technology layers
 
-## Edition impact
+- **Backend:** Vona uses Koa, Knex, Redis, and database drivers.
+- **Frontend:** Zova uses Vue, Vite, Quasar tooling, and TanStack libraries. Quasar is part of the engineering toolchain, not the edition UI component library.
+- **Edition UI:** Cabloy Basic uses DaisyUI + Tailwind CSS; Cabloy Start uses Vuetify.
 
-Most framework concepts are shared across Cabloy Basic and Cabloy Start because both editions follow the same Cabloy fullstack core. The documentation prefers a common-first explanation, then adds edition-specific notes only where the editions intentionally diverge.
+For exact versions, inspect `vona/package.json` and `zova/package.json` in the active edition checkout.
 
-Across editions, the frontend engineering layer stays mostly shared through Zova, Vue, Vite, Quasar tooling, and related libraries. The edition-specific UI layer then diverges between DaisyUI + Tailwind CSS for Cabloy Basic and Vuetify for Cabloy Start.
+## Continue reading
 
-Use the [Editions Overview](/editions/overview) page whenever a task depends on UI library assumptions, flavor names, module composition, SSR site baselines, distribution boundaries, or AI workflow guidance.
+- **Explore the framework's origins:** [CabloyJS Development History](/fullstack/development-history).
+- **Start a project:** [choose an edition](/editions/overview#choosing-an-edition), then follow the [Fullstack Quickstart](/fullstack/quickstart).
+- **Build a feature:** use the [Fullstack Tutorials](/fullstack/tutorials-overview) and [Fullstack CLI](/fullstack/cli).
+- **Work with AI agents:** start with the [AI Development Introduction](/ai/introduction) for repository guidance and skills.

package/repo-docs/fullstack/quickstart.md

@@ -107,7 +107,7 @@ The two commands start different SSR entry points. Choose the one that matches t
 | **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              |
 
-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.
+Directly opening `9000` does not replace validation through Vona at `7102`. For acceptance or deployment-oriented checks, build the required SSR/REST artifacts, synchronize them with Vona, and access the site through Vona. For the request flows and guidance on choosing an entry, see [Vona Integrated SSR and Zova Standalone SSR](/fullstack/ssr-entry-modes).
 
 ## 6. Run with Docker Compose