cabloy 5.1.111 → 5.1.113

package/cabloy-docs/frontend/navigation-guards-guide.md

@@ -16,34 +16,39 @@ Typical uses include:
 
 The `home-base` module provides a router-guard service hook where custom logic can be added.
 
+Use the pure `app.$getPagePath(...)` family to construct a guard destination. Use the imperative `app.$gotoPage(...)` family from event handlers or workflows that intentionally start navigation. Do not call `$gotoLogin()` or `$gotoAccessDenied()` from a `beforeEach` guard and then return `false`: Client-side `$goto...()` starts a nested navigation while `false` aborts the navigation currently being guarded.
+
 Representative shape:
 
 ```typescript
 class ServiceRouterGuards {
   protected onRouterGuards(router: BeanRouter) {
     router.beforeEach(async to => {
-      if (
-        !this.sys.config.ssr.cookieDisabledOnServer &&
-        to.meta.requiresAuth !== false &&
-        !this.$passport.isAuthenticated
-      ) {
-        const [_res, err] = await catchError(() => {
-          return this.$passport.ensurePassport();
-        });
+      if (to.meta.requiresAuth === false) return;
+      if (this.sys.config.ssr.cookieDisabledOnServer) return;
+
+      if (!this.$passport.isAuthenticated) {
+        const [_res, err] = await catchError(() => this.$passport.ensurePassport());
         if (err) {
           this.$errorHandler(err, 'onRouterGuards');
           return false;
         }
-        if (!this.$passport.isAuthenticated) {
-          this.app.$gotoLogin(to.fullPath);
-          return false;
+      }
+
+      if (!this.$passport.isAuthenticated) {
+        const pagePath = this.app.$getPagePathLogin(to.fullPath);
+        if (process.env.SERVER) {
+          this.app.$redirect(pagePath);
         }
+        return pagePath;
       }
     });
   }
 }
 ```
 
+`$getPagePathLogin(to.fullPath)` preserves the protected destination as `returnTo` without starting navigation. On the Client, returning that path lets Vue Router redirect the current navigation atomically. On the Server, `$redirect(...)` preserves the SSR HTTP redirect flow.
+
 ## Why route meta matters here
 
 The example makes a key architectural point: navigation guards are tightly coupled to route metadata such as `requiresAuth`.
@@ -54,6 +59,10 @@ That means route configuration and guard behavior should be read together, not a
 
 The example also references SSR-related configuration such as cookie handling on the server side.
 
+When `SSR_COOKIE=false`, `cookieDisabledOnServer` is true only during server rendering. The guard deliberately allows the protected route's neutral SSR entry, then the browser restores Passport state and applies the same admission policy after hydration. This preserves equivalent server and hydration-time initial rendering without weakening Client-side protection.
+
+For cookie-enabled SSR, a rejected request must still use `$redirect(...)` so the SSR layer returns its HTTP redirect response. On the Client, return a route path or route-location object from the guard instead of using an imperative `$goto...()` helper.
+
 So guards are not purely a client-side router concern. In Cabloy/Zova, they can also intersect with SSR behavior.
 
 ## Implementation checks for navigation-guard changes

package/cabloy-docs/frontend/route-alias-guide.md

@@ -50,6 +50,30 @@ The distinction matters:
 - use `routes.path` for normal path-based aliases
 - use `routes.name` when the route depends on params-aware naming
 
+## Generate a configured alias path
+
+When application code needs a user-facing URL for a named route, use the canonical route name with `$router.getAliasPath(...)`:
+
+```ts
+const path = this.$router.getAliasPath('demo-todo:item', {
+  params: {
+    id: '42',
+    locale: true,
+  },
+});
+const absoluteUrl = this.$router.getAliasPath(
+  'demo-todo:item',
+  { params: { id: '42', locale: true } },
+  true,
+);
+```
+
+The helper returns the configured alias path, such as `/zh-cn/todo/42`, or `undefined` when that route name has no configured alias. Pass `true` as the third argument when an absolute URL is required; it uses the same host and public-path conversion as `$router.getPagePath(..., true)`. `locale: true` uses the active locale and omits the configured default locale from an optional locale segment.
+
+Use the canonical generated route name. Do not construct `$alias:<name>` or strip `/__alias__` in application code: those are private router implementation details.
+
+Use `$router.getPagePath(...)` for a known canonical path template, `$router.getAliasPath(...)` for a configured public alias by canonical route name, and `$router.resolveName(...)` for canonical named-route resolution. Do not add alias behavior to `getPagePath(...)`, because aliases are configured against route names rather than page-path templates.
+
 ## Implementation checks for route-alias changes
 
 When changing user-facing routes, ask:

package/cabloy-docs/frontend/scripts.md

@@ -20,15 +20,17 @@ For the edition-detection workflow, also see [Edition Detection](/editions/detec
 
 ## Cabloy Basic root wrappers
 
-From the current root repository:
+Cabloy Basic exposes these default Web and Admin wrappers:
 
 ```bash
 npm run dev:zova:admin
 npm run dev:zova:web
 npm run build:zova
+npm run build:zova:admin
+npm run build:zova:web
 ```
 
-These map to Basic-specific Zova flavors in this repository. Commerce follows the same aggregate-and-surface pattern:
+They map to the `cabloyBasicAdmin` and `cabloyBasicWeb` flavors. Basic also includes the Commerce aggregate-and-surface wrappers:
 
 ```bash
 # Customer Web or Operator Admin development server
@@ -41,11 +43,13 @@ npm run build:zova:commerce:web
 npm run build:zova:commerce:admin
 ```
 
+`npm run build:zova:all` sequentially runs the focused Basic and Commerce batch builds. `npm run init` uses it to prepare every shipped Cabloy Basic SSR/REST flavor before Vona is initialized. For normal frontend work, continue to use `build:zova` or `build:zova:commerce` when only that suite's artifacts changed.
+
 ## Basic SSR browser acceptance
 
-The default Basic Web and Admin sites have browser smoke commands that exercise Vona SSR dispatch at `7102`, not a standalone Zova development-server port.
+The default Basic Web and Admin sites have browser smoke commands that exercise Vona SSR dispatch at port `7102`, not a standalone Zova development-server port.
 
-Prepare current artifacts explicitly when the relevant frontend SSR output changed:
+Prepare current SSR and REST artifacts explicitly when frontend output has changed:
 
 ```bash
 # Web only
@@ -54,40 +58,77 @@ npm run build:zova:web
 # Admin only
 npm run build:zova:admin
 
-# Both default Basic sites
+# Both default Basic sites, then a managed local run
 npm run build:zova
 npm run deps:vona
-```
-
-Then use the managed clean local acceptance command:
-
-```bash
 npm run test:e2e:basic:clean
 ```
 
-It resets Vona-managed test data and the local Redis namespace, starts one development Vona worker, and runs the complete suite by default. The E2E commands consume already-built artifacts; they do not rebuild them.
+The managed clean command resets Vona-managed test data and the local Redis namespace, starts one development Vona worker, and runs the complete suite by default. Browser commands consume already-built artifacts; they do not rebuild them.
 
-The suite command family is consistent across Basic and Commerce:
+The Basic and Commerce suite families use the same command shape:
 
 ```text
 test:e2e:<suite>          complete suite
 test:e2e:<suite>:web      all @web surface scenarios
 test:e2e:<suite>:admin    all @admin surface scenarios
-test:e2e:<suite>:clean      managed clean local suite run
+test:e2e:<suite>:clean    managed clean local suite run
 ```
 
-Use Playwright tags after npm's argument delimiter for feature/category selection instead of adding one root script per scenario:
+Use Playwright tags after npm's argument delimiter for scenario selection instead of adding one root script per scenario:
 
 ```bash
 npm run test:e2e:basic:clean -- --grep @flow
 npm run test:e2e:basic -- --grep ATP-BASIC-FLOW-01
 ```
 
-For the complete tag vocabulary, managed-runner argument boundaries, and externally managed-target examples, see [Repo Scripts](/reference/repo-scripts#ssr-browser-checks). For a separately managed Basic target, set `BASIC_E2E_BASE_URL`; the equivalent Commerce commands use `COMMERCE_E2E_BASE_URL`. The caller owns external-target data, cache, and artifact freshness.
+For the complete tag vocabulary, managed-runner argument boundaries, and externally managed-target examples, see [Repo Scripts](/reference/repo-scripts#ssr-browser-checks). For a separately managed Basic target, set `BASIC_E2E_BASE_URL`; Commerce commands use `COMMERCE_E2E_BASE_URL`. The caller owns external-target data, cache, and artifact freshness.
+
+## Cabloy Start root wrappers
+
+Cabloy Start is the licensed private edition. Its default root wrappers use the `cabloyStartAdmin` and `cabloyStartWeb` flavors:
+
+```bash
+npm run dev:zova:admin
+npm run dev:zova:web
+npm run build:zova
+npm run build:zova:admin
+npm run build:zova:web
+```
+
+Cabloy Start does not expose the Basic Commerce wrapper family.
+
+## Start SSR browser acceptance
+
+The Start Web and Admin browser baseline also exercises Vona SSR dispatch at port `7102`. Prepare current SSR and REST artifacts, then use the managed local command:
+
+```bash
+npm run build:zova
+npm run deps:vona
+npm run test:e2e:start:clean
+```
+
+The Start command family is:
+
+```text
+test:e2e:start          complete suite
+test:e2e:start:web      all @web surface scenarios
+test:e2e:start:admin    all @admin surface scenarios
+test:e2e:start:clean    managed clean local suite run
+```
+
+Start scenarios currently use `@web`, `@admin`, and `@smoke`. Select a scenario or surface with Playwright arguments:
+
+```bash
+npm run test:e2e:start:clean -- --grep @web
+npm run test:e2e:start -- --grep ATP-START-FLOW-01
+```
+
+For a separately managed Start target, set `START_E2E_BASE_URL`. The target owner is responsible for data, cache, and artifact freshness.
 
 ## Zova script model
 
-The underlying Zova package still organizes scripts around app mode and flavor.
+The underlying Zova package organizes scripts around app mode and flavor.
 
 Examples from the current source include:
 
@@ -100,18 +141,18 @@ Examples from the current source include:
 - `dev:ssr:cabloyBasicAdmin`
 - `build:ssr:cabloyBasicAdmin`
 - `build:rest:cabloyBasicAdmin`
-- `dev:ssr:cabloyBasicWeb`
-- `build:ssr:cabloyBasicWeb`
-- `build:rest:cabloyBasicWeb`
+- `dev:ssr:cabloyStartAdmin`
+- `build:ssr:cabloyStartAdmin`
+- `build:rest:cabloyStartAdmin`
 
 ## Cabloy Basic
 
-The current public repository documents and scripts support Basic-specific flavors such as:
+The public repository supports Basic-specific flavors:
 
 - `cabloyBasicAdmin`
 - `cabloyBasicWeb`
 
-Representative Zova commands inside this repo include:
+Representative Zova commands are:
 
 ```bash
 cd zova && npm run dev:ssr:cabloyBasicAdmin
@@ -121,18 +162,24 @@ cd zova && npm run build:rest:cabloyBasicAdmin
 
 ## Cabloy Start
 
-The sibling `cabloy-start` repository is the private commercial edition and uses Start-specific flavors such as:
+The licensed private repository supports Start-specific flavors:
 
 - `cabloyStartAdmin`
 - `cabloyStartWeb`
 
-Those commands are not driven by the current Basic repo root wrappers, so verify the Start repo’s `package.json`, flavor names, SSR site baselines, and project assets before documenting or automating them.
+Representative Zova commands are:
+
+```bash
+cd zova && npm run dev:ssr:cabloyStartAdmin
+cd zova && npm run build:ssr:cabloyStartAdmin
+cd zova && npm run build:rest:cabloyStartAdmin
+```
 
 ## Workflow guidance
 
 When documenting or automating frontend scripts:
 
-- start from root wrappers for normal Cabloy Basic workflows
+- start from the root wrappers for the detected edition
 - detect the edition before choosing flavor-specific examples
 - verify the exact flavor before writing edition-specific examples
 - use REST/type generation commands deliberately when backend integration depends on them

package/cabloy-docs/frontend/ssr-init-data.md

@@ -44,6 +44,31 @@ Client reuse requires the model call to resolve to the same effective query key:
 
 For helper selection and the complete passport flow, read [Model State Guide](/frontend/model-state-guide). For the dehydration filter and QueryClient lifecycle, read [A-Model Under the Hood](/frontend/a-model-under-the-hood).
 
+## Hydration-equivalent initial render
+
+The server-rendered HTML and the client's hydration-time initial render must be equivalent. Compare the server response with the first client render that hydrates it, not with the browser UI after later client work completes.
+
+Choose one of these strategies for each render-driving state:
+
+### State required in SSR output
+
+Use the model-owned query on both sides, prepare it in the server-capable initialization path, and let the client reuse the transferred state through the same effective Model, selector, and logical query key. This is the normal approach for public data that must appear in the initial HTML.
+
+### State intentionally omitted from SSR
+
+For private, cookie-unavailable, or browser-only state, render the same neutral shell or placeholder on the server and during the client's hydration-time initial render. Begin the query, loading state, and private rendered branch only at an explicit client boundary, such as `onHydrated`, `ClientOnly`, completed route admission, a mounted client lifecycle, or user interaction.
+
+A `process.env.CLIENT` branch is not sufficient when it changes the first hydration tree. A state transition after hydration is valid; a different hydration-time initial tree is not.
+
+### Query helper roles
+
+- `$useStateData(...)` owns the query identity, state, cache lifecycle, and hydration reuse.
+- `disableSuspenseOnInit: true` skips only `$useStateData(...)`'s automatic first-creation `query.suspense()` kick. It does not prevent query creation, restore, mounted/no-data fetches, or later refetches.
+- `$QueryEnsureLoaded(...)` is an awaited availability gate: it waits only while `query.data === undefined`. Use it at a deliberate boundary that needs loaded data, not to suppress a query during hydration.
+- If a boundary requires domain-valid data rather than merely loaded data, choose `$QueryGetFresh(...)` or `$QueryEnsureFresh(...)` with the model's freshness rule.
+
+For the detailed state-helper semantics, read [Use State Data Best Practices](/frontend/use-state-data-best-practices). For browser-only rendering, read [SSR ClientOnly](/frontend/ssr-client-only).
+
 ## Implementation checks for SSR data-loading changes
 
 When changing SSR pages, avoid inventing parallel data-loading patterns unless there is a real reason.

package/cabloy-docs/frontend/ssr-review-checklist.md

@@ -79,6 +79,9 @@ Review these questions when the change affects route resolution, server-side dat
 
 - [ ] Is the initial server-rendered HTML still correct before hydration begins?
 - [ ] If data is involved, is it prepared through the intended SSR/model/controller flow?
+- [ ] Does the server HTML match the client's hydration-time initial render in structure, visible state, and render-driving data?
+- [ ] For SSR-required data, does the client reuse the transferred state through the same effective query key instead of producing a separate first-screen result?
+- [ ] For private, cookie-unavailable, or browser-only data intentionally omitted by SSR, does the server and hydration-time client render keep the same neutral shell or placeholder?
 - [ ] If metadata is involved, is it still produced through the intended SSR-aware meta path?
 - [ ] If the change touches SSR-only behavior, did I verify it at the server-render stage rather than only after client boot?
 
@@ -92,10 +95,12 @@ Read together:
 
 Review these questions when the change affects browser-only behavior, first paint, or client takeover after SSR.
 
-- [ ] Is the client reusing server-provided state rather than recomputing a different first-screen result?
-- [ ] If browser-only behavior is involved, should part of the UI be isolated with `ClientOnly`?
+- [ ] Is the client reusing server-provided state rather than recomputing a different hydration-time initial result?
+- [ ] If state was intentionally omitted by SSR, is its query/load/render branch deferred until an explicit post-hydration, admission, mounted, or interaction boundary?
+- [ ] If browser-only behavior is involved, should part of the UI be isolated with `ClientOnly` and a hydration-equivalent placeholder?
+- [ ] Is `disableSuspenseOnInit` being used only to skip its init-time suspense kick, rather than as an assumed no-fetch or hydration-deferral mechanism?
 - [ ] Did I separate a hydration issue from a server-render issue before changing code?
-- [ ] If the final browser state differs from the server output, is that difference expected and framework-supported?
+- [ ] If the browser UI later differs from the server output, does that change begin after hydration through an expected framework-supported boundary?
 
 Read together:
 
@@ -135,6 +140,8 @@ Flag the change for follow-up when any of these are true:
 - the change assumes one edition's theme/UI behavior applies universally
 - the change was validated only in dev even though the failure is deploy- or build-sensitive
 - the review never identified which SSR layer was actually changing
+- private or browser-only state omitted by SSR appears or starts loading during the client's hydration-time initial render
+- `disableSuspenseOnInit` is presented as proof that a query cannot fetch or affect hydration
 
 ## Reviewer template
 
@@ -156,10 +163,13 @@ Review this change with the Cabloy SSR checklist in mind.
 
 1. Identify which SSR layer the change touches: Vona SSR orchestration, frontend build output, Zova SSR server render, or client hydration.
 2. Separate server-render correctness from hydration correctness.
-3. Verify whether the change reuses the intended framework abstraction instead of adding a parallel workaround.
-4. Check whether the change needs built-mode validation rather than only dev-mode validation.
-5. Review edition-sensitive UI/theme assumptions when the change touches first paint, tokens, dark mode, or SSR env behavior.
-6. Flag any change whose review never identifies the failing or affected SSR layer.
+3. Compare server HTML with the client's hydration-time initial render, not with later post-hydration browser state.
+4. Verify whether SSR-required state reuses the intended transferred query state and whether deliberately omitted private/browser-only state remains absent until an explicit client boundary.
+5. Do not accept `disableSuspenseOnInit` as evidence that a query cannot fetch or change hydration behavior.
+6. Verify whether the change reuses the intended framework abstraction instead of adding a parallel workaround.
+7. Check whether the change needs built-mode validation rather than only dev-mode validation.
+8. Review edition-sensitive UI/theme assumptions when the change touches first paint, tokens, dark mode, or SSR env behavior.
+9. Flag any change whose review never identifies the failing or affected SSR layer.
 ```
 
 ## Read together

package/cabloy-docs/frontend/use-state-data-best-practices.md

@@ -98,6 +98,10 @@ A controller renders as though the interaction is ready, but clicking the button
 
 That is a sign that a query-state concern may have been pushed too far into imperative interaction code.
 
+### SSR exception: intentionally omitted state
+
+For state intentionally omitted from SSR, hydration equivalence takes priority over the normal render-time default. Keep the same neutral shell or placeholder in the server output and the client's hydration-time initial render, then establish or load the private/client-only branch only after an explicit client boundary. Read [SSR Init Data](/frontend/ssr-init-data) before applying this exception.
+
 ## Practical rule 3: `disableSuspenseOnInit: true` disables the init-time `query.suspense()` kick, not the query itself
 
 This point needs precise wording.

package/cabloy-docs/frontend/zova-router-under-the-hood.md

@@ -263,6 +263,8 @@ This detail is important because:
 - the runtime can still preserve named-route identity and params-aware resolution
 - alias handling remains a router concern instead of leaking into page code
 
+`$alias:<name>` and `/__alias__` are private runtime machinery. Application code should use `$router.getAliasPath('module:page', { params, query }, absolute?)`, which accepts the canonical route name and returns the configured public alias path (or `undefined` when no alias is configured). Its optional `absolute` argument uses the same origin and public-path conversion as `getPagePath(...)`.
+
 #### Layout wrapping
 
 If `meta.layout !== false`, the runtime does not register the page component alone.
@@ -289,11 +291,12 @@ This helper:
 - handles locale-specific param normalization
 - can return a relative page path or an absolute URL
 
-Zova also exposes named-route resolution through `resolveName(...)`, and both helpers preserve the module-aware naming/path model rather than asking every caller to manually build URLs.
+Zova also exposes canonical named-route resolution through `resolveName(...)` and configured public alias-path generation through `getAliasPath(...)`. Like `getPagePath(...)`, `getAliasPath(...)` can return either a relative path or an absolute URL. These helpers preserve the module-aware naming/path model rather than asking every caller to manually build URLs.
 
 That is why the recommended page-navigation surface stays framework-native:
 
 - `this.$router.getPagePath(...)`
+- `this.$router.getAliasPath(...)`
 - `this.app.$gotoPage(...)`
 - `this.app.$gotoHome(...)`
 

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

@@ -1,12 +1,12 @@
 # Comparison with Other Frameworks
 
-This page shows how **Cabloy** differs from several common framework choices, so readers can quickly see where Cabloy stands out as a Node.js fullstack framework system and which strengths come from the fullstack system as a whole versus the backend layer provided by **Vona**.
+This page shows how **Cabloy** differs from several common framework choices, focusing on its one fullstack system for AI vibe coding: bidirectional type sync, CLI-first workflows, and source-grounded docs and skills. It also distinguishes strengths of the fullstack system from those of the backend layer provided by **Vona**.
 
 ## What is being compared
 
 Cabloy is a **Node.js fullstack framework system**.
 
-That means the comparison is not only about a backend runtime or only about a frontend stack. It is about how **Vona** on the backend and **Zova** on the frontend stay aligned through shared conventions, shared scripts, SSR-aware delivery modes, and cross-stack generation workflows.
+That means the comparison is not only about a backend runtime or a frontend stack. It is about a unified system where **Vona** and **Zova** support bidirectional type sync, CLI-first workflows, and reusable docs and skills, alongside shared conventions, SSR-aware delivery modes, and cross-stack generation workflows.
 
 For the broader Cabloy model, start with these pages:
 
@@ -23,17 +23,19 @@ The sections below use the same comparison lens each time:
 - **System center** — what the framework treats as the main architectural center
 - **Backend model** — how much backend structure and infrastructure the framework provides by default
 - **Frontend and admin model** — how the UI side is expected to evolve
-- **Cross-stack workflow** — how backend/frontend contracts and generation workflows stay aligned
+- **Cross-stack workflow** — how bidirectional type sync, contracts, and generation workflows stay aligned
+- **Guidance and automation** — how CLI-first workflows, docs, and skills make repository conventions reusable
 - **Best fit** — the kind of team or project the framework fits most naturally
 
 ## Cabloy vs Next.js
 
 | Perspective              | Cabloy                                                                                         | Next.js                                                                |
 | ------------------------ | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| System center            | One framework system with Vona on the backend and Zova on the frontend                         | Frontend-centric fullstack framework                                   |
+| System center            | One fullstack system, with Vona and Zova as aligned backend and frontend layers                | Frontend-centric fullstack framework                                   |
 | Backend model            | Dedicated backend framework with its own runtime, contracts, infrastructure, and CLI workflows | Backend capabilities are typically centered around the web app runtime |
 | Frontend and admin model | Shared conventions across SSR, SPA, Web, and Admin applications                                | Strong fit for React-based web application delivery                    |
-| Cross-stack workflow     | Explicit backend OpenAPI output, frontend SDK generation, and frontend metadata feedback loops | Usually chosen per project or ecosystem tooling                        |
+| Cross-stack workflow     | Bidirectional type sync through OpenAPI, SDK generation, and metadata feedback loops           | Usually chosen per project or ecosystem tooling                        |
+| Guidance and automation  | CLI-first workflows plus source-grounded docs and skills                                       | Usually chosen per project or ecosystem tooling                        |
 | Best fit                 | Teams that want a coordinated fullstack system with a stronger dedicated backend layer         | Teams that want a React-centered fullstack web application path        |
 
 Cabloy and Next.js both target fullstack application development, but they organize the stack differently.
@@ -43,8 +45,9 @@ Cabloy keeps the backend and frontend as **separate but coordinated framework la
 Representative Cabloy strengths in this comparison include:
 
 - a clear backend/frontend collaboration model rather than a single frontend-centered runtime
-- explicit contract workflows from backend OpenAPI output to frontend SDK generation
-- frontend-generated metadata that can flow back into backend-side tooling
+- bidirectional type sync through backend OpenAPI output, frontend SDK generation, and frontend metadata feedback loops
+- CLI-first workflows for scaffolding, generation, refactors, and verification
+- source-grounded docs and skills that make repository conventions reusable for people and AI agents
 - shared delivery conventions for SSR, SPA, Web, and Admin applications
 
 If your main goal is a React-centered fullstack web app, Next.js may feel more direct. If your main goal is a **coordinated fullstack framework system** with a stronger backend layer and explicit cross-stack workflows, Cabloy is the better fit.
@@ -53,10 +56,11 @@ If your main goal is a React-centered fullstack web app, Next.js may feel more d
 
 | Perspective              | Cabloy                                                                                                | NestJS                                                                                  |
 | ------------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| System center            | Fullstack system                                                                                      | Backend framework                                                                       |
+| System center            | One fullstack system                                                                                  | Backend framework                                                                       |
 | Backend model            | Vona provides backend runtime, contracts, infrastructure, and CLI workflows                           | NestJS focuses on backend application structure                                         |
 | Frontend and admin model | Frontend collaboration is built into the broader Cabloy system through Zova and shared docs/workflows | Usually paired with a separate frontend choice                                          |
-| Cross-stack workflow     | Backend contracts can feed frontend SDK generation inside the same framework system                   | Typically assembled from separate backend and frontend tooling choices                  |
+| Cross-stack workflow     | Bidirectional type sync connects backend contracts, frontend SDKs, and metadata feedback              | Typically assembled from separate backend and frontend tooling choices                  |
+| Guidance and automation  | CLI-first workflows plus source-grounded docs and skills                                              | Usually chosen per project or ecosystem tooling                                         |
 | Best fit                 | Teams that want backend strength inside a shared fullstack system                                     | Teams that want a backend-first framework and will choose the frontend stack separately |
 
 The most important difference here is **scope**.
@@ -77,10 +81,11 @@ If a team only needs a backend framework and wants to choose the frontend stack
 
 | Perspective              | Cabloy                                                                                                                    | Django Admin                                                                             |
 | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| System center            | Typed Node.js fullstack framework system                                                                                  | Python server-centered admin framework experience                                        |
+| System center            | Typed Node.js fullstack system with aligned backend and frontend layers                                                   | Python server-centered admin framework experience                                        |
 | Backend model            | Dedicated backend runtime and infrastructure through Vona                                                                 | Django backend conventions centered on the admin stack                                   |
 | Frontend and admin model | Modern frontend layer through Zova with SSR, SPA, Web, and Admin delivery modes                                           | Admin experience is centered on server-rendered templates and built-in admin conventions |
-| Cross-stack workflow     | Backend and frontend stay aligned through generated contracts, metadata, and shared workflows                             | The default model is more tightly centered on the server-side admin stack                |
+| Cross-stack workflow     | Bidirectional type sync through generated contracts, metadata, and shared workflows                                       | The default model is more tightly centered on the server-side admin stack                |
+| Guidance and automation  | CLI-first workflows plus source-grounded docs and skills                                                                  | Usually centered on Django conventions and ecosystem tooling                             |
 | Best fit                 | Teams that want rapid admin development in Node.js without giving up typed frontend flexibility and richer UI interaction | Teams that want a fast server-centered admin path in the Python ecosystem                |
 
 This comparison is worth keeping even though the language ecosystems are different.
@@ -110,9 +115,10 @@ For Cabloy’s frontend/runtime side of this comparison, see:
 These comparisons are most useful when your decision depends on questions like:
 
 - do you want one coordinated framework system instead of stitching backend and frontend frameworks together?
+- do you need bidirectional type sync through an explicit contract loop?
+- do you want CLI-first workflows, source-grounded docs, and skills that make repository conventions reusable?
 - do you need a stronger dedicated backend layer inside a fullstack architecture?
-- do you want explicit contract-loop workflows between backend and frontend?
 - do you need shared conventions across SSR, SPA, Web, and Admin delivery modes?
 - do you want Django-Admin-like rapid admin development inside the Node.js ecosystem, but with a more modern frontend and interaction model?
 
-If those questions matter, Cabloy’s value is not just one isolated feature. It is the way **Vona**, **Zova**, shared scripts, and cross-stack workflows stay aligned as one framework system.
+If those questions matter, Cabloy’s value is not just one isolated feature. It is the way **Vona**, **Zova**, shared scripts, docs, skills, and cross-stack workflows stay aligned as one fullstack system.

package/cabloy-docs/fullstack/introduction.md

@@ -2,18 +2,18 @@
 
 Cabloy is a Node.js fullstack framework for AI vibe coding.
 
-Use one fullstack framework instead of stitching together separate backend and frontend stacks.
+**One fullstack system for AI vibe coding—bidirectional type sync, CLI-first workflows, docs, and skills.**
 
-With Vona, Zova, suite-based modules, and CLI-first workflows, Cabloy turns common scaffolding, metadata, refactors, and verification into explicit commands for faster, more accurate AI vibe coding.
+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 framework system** — build backend and frontend in one fullstack architecture
-- **Vona + Zova** — use aligned backend and frontend frameworks for code sharing, workflow reuse, and cross-stack consistency
-- **Suite-based modular system** — organize capabilities as suites and modules so services, features, metadata, and tooling evolve in composable units
-- **Multiple delivery modes** — deliver SSR, SPA, Web, and Admin applications with shared conventions across the stack
-- **CLI-first workflows for AI vibe coding** — turn common scaffolding, metadata, refactors, and verification into explicit commands for faster, more accurate AI vibe coding
-- **Monorepo-native development** — keep framework source, docs, and tooling aligned in one monorepo workflow
+- **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
+- **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
 
@@ -84,9 +84,9 @@ In earlier standalone-repo explanations, this was often described as placing the
 
 For the integration workflow and current monorepo shape, see [Vona + Zova Integration](/fullstack/vona-zova-integration) and [SSR Overview](/frontend/ssr-overview).
 
-### 2. Type information flows in both directions
+### 2. Bidirectional type sync through the contract loop
 
-Cabloy does not treat type sharing as backend-to-frontend only. The collaboration loop is bidirectional:
+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

package/cabloy-docs/fullstack/quickstart.md

@@ -114,12 +114,34 @@ In Cabloy Basic, upgrade synchronizes the framework-owned SSR browser E2E baseli
 ```text
 e2e/config/
 e2e/scripts/
-e2e/specs/a-basic/
+e2e/specs/cabloy-basic/
 e2e/specs/a-commerce/
 ```
 
 Keep project-owned browser tests outside those reserved paths, for example under `e2e/specs/my-project/`; upgrade overlays framework files without deleting project test paths. Projects whose previous upgrader predates this E2E synchronization may need to run `npm run upgrade` once more: the updated upgrader recognizes an incomplete Basic E2E baseline even when the version marker is already current.
 
+### Cabloy Start repository baseline
+
+Cabloy Start is checked out from the licensed private repository rather than created through `npm create cabloy`. Its E2E baseline is maintained in that repository:
+
+```text
+e2e/config/
+e2e/scripts/
+e2e/specs/cabloy-start/
+```
+
+The public Cabloy upgrade flow does not synchronize or repair those Start E2E files, the `test:e2e:start*` scripts, or `@playwright/test`. Keep project-owned browser scenarios outside the baseline paths, for example under `e2e/specs/my-project/`.
+
+Prepare and run the managed Start baseline locally with:
+
+```bash
+npm run build:zova
+npm run deps:vona
+npm run test:e2e:start:clean
+```
+
+The managed command requires port `7102` to be available and owns the local reset and Vona worker lifecycle. For a separately managed target, set `START_E2E_BASE_URL` and use `test:e2e:start`, `test:e2e:start:web`, or `test:e2e:start:admin`; those commands do not reset, build, start, or stop the target. Install Chromium once when needed with `npx playwright install chromium`. See [Repo Scripts](/reference/repo-scripts#ssr-browser-checks) for the complete command variants.
+
 ## 7. Next steps for framework-aware development
 
 If you are contributing to framework-aware workflows or using Cabloy CLI generation directly, prefer CLI-backed generation over manual scaffolding.

package/cabloy-docs/index.md

@@ -4,7 +4,7 @@ layout: home
 hero:
   name: 'Cabloy'
   text: 'Node.js fullstack framework for AI vibe coding'
-  tagline: Build backend and frontend with one fullstack framework. Vona, Zova, suites, and CLI-first workflows make AI vibe coding faster and more accurate.
+  tagline: One fullstack system for AI vibe coding—bidirectional type sync, CLI-first workflows, docs, and skills.
   actions:
     - theme: brand
       text: Get Started
@@ -17,25 +17,25 @@ hero:
       link: /ai/introduction
 
 features:
-  - title: One framework system
-    details: Build backend and frontend in one fullstack architecture.
+  - 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.
+  - 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.
   - title: Vona + Zova
-    details: Use aligned backend and frontend frameworks for code sharing, workflow reuse, and cross-stack consistency.
-  - title: Suite-based modular system
-    details: Organize capabilities as suites and modules so services, features, metadata, and tooling evolve in composable units.
-  - title: Multiple delivery modes
-    details: Deliver SSR, SPA, Web, and Admin applications with shared conventions across the stack.
-  - title: CLI-first workflows for AI vibe coding
-    details: Turn scaffolding, metadata, refactors, and verification into explicit commands for faster, more accurate AI vibe coding.
-  - title: Monorepo-native development
-    details: Keep framework source, docs, and tooling aligned in one monorepo workflow.
+    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.
 ---
 
 # Cabloy Documentation
 
-Cabloy is a Node.js fullstack framework for AI vibe coding. Use one fullstack framework instead of stitching together separate backend and frontend stacks. With Vona, Zova, suite-based modules, and CLI-first workflows, Cabloy turns common scaffolding, metadata, refactors, and verification into explicit commands for faster, more accurate AI vibe coding.
+Cabloy is a Node.js fullstack framework for AI vibe coding. 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 here to learn the shared Cabloy architecture, see how Vona and Zova fit together, understand how Cabloy Basic and Cabloy Start share one fullstack core but diverge by edition, and follow CLI-first workflows grounded in the current source tree.
+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. Vona, Zova, and suite-based modules provide the aligned architecture behind that workflow, while Cabloy Basic and Cabloy Start share the same fullstack core but diverge by edition.
 
 ## What you can do here