cabloy 5.1.110 → 5.1.112

package/.cabloy-version

@@ -1 +1 @@
-5.1.110
+5.1.112

package/.claude/skills/cabloy-backend-scaffold/SKILL.md

@@ -140,7 +140,35 @@ Check whether the feature needs:
 - `meta.version`
 - field indexes
 - relation definitions
-- datasource or cache considerations
+- datasource or cache considerations, including cross-Model query-cache dependencies
+
+For normal resource persistence, preserve Vona's default active-instance scope:
+
+- in the current tenancy model, a tenant corresponds to an instance and ordinary model CRUD handles the current `iid`
+- do not expose caller-controlled `iid` or tenant selection in ordinary resource DTOs or controller logic
+- treat a record absent from an ordinary scoped model lookup as absent; do not use raw cross-instance probes merely to choose between `403` and not-found behavior
+- use `disableInstance`, plain builders, or raw SQL only for an explicit global/system or otherwise authorized contract
+- model a future multi-merchant requirement as a separate boundary within an instance, with its own ownership and authorization rules
+
+For the canonical explanation, read [Multi-Instance and Instance Resolution](../../../cabloy-docs/backend/multi-instance-and-instance-resolution.md) and [Model Guide](../../../cabloy-docs/backend/model-guide.md).
+
+### Cross-module resource lookup
+
+Choose the narrowest lookup form before evaluating module dependency intent:
+
+- use `this.scope` for resources owned by the current `BeanBase` module
+- use `this.$scope.<fixedModule>` when the target module is statically known and the typed shorthand is available
+- use `app.scope('<module-name>')` in tests or standalone code with an application reference instead of BeanBase shorthands
+- use `this.app.scope(moduleName)` or `app.scope(moduleName)` when the module name is genuinely selected at runtime; do not replace a fixed module target with a dynamic string lookup merely for style
+
+Then distinguish runtime lookup from a true module dependency:
+
+- lookup resolves a resource from a module already composed into the application; it does not by itself require a `vonaModule.dependencies` entry or create a circular dependency edge
+- add `vonaModule.dependencies` only when the feature genuinely requires the target module's availability, dependency-first ordering, or minimum compatible version
+- do not add a dependency declaration merely because code looks up another module's service, model, config, locale, or other resource
+- scope lookup cannot make an absent module available; validate application/suite composition separately when the target must exist
+
+For the canonical distinction, read [Backend Foundation](../../../cabloy-docs/backend/foundation.md#scope-lookup-vs-module-dependencies) and [Package Map](../../../cabloy-docs/reference/package-map.md).
 
 ### Verification
 

package/.claude/skills/cabloy-backend-scaffold/references/follow-up-checklist.md

@@ -28,8 +28,20 @@ After generating or extending a backend thread, check which follow-up layers app
 - relations
 - datasource choice
 - cache behavior
+- cross-Model query-cache dependencies: when a source mutation can change another Model's cached query members, totals, projections, includes, or visibility, declare exactly one directed `modelsClear` / `modelsClearedBy` edge
+- keep the dependency graph acyclic and free of duplicate edges; do not declare both forms for the same edge because propagation is transitive and current runtime collection does not deduplicate targets
+- when `modelsClearedByFn` is required, treat it as replacement behavior and explicitly own the target clear and any necessary downstream propagation
+- prefer normal Model/service mutation paths so source invalidation, commit-time re-clear, and configured double-delete remain active
+- add a warm-query → mutate-source → repeat-query regression test for each new dependency path; read [Vona Cross-Model Query-Cache Dependencies](../../../../.docs-internal/architecture/vona-cross-model-query-cache-dependencies.md) for the source-backed decision rules
 - transaction behavior
 
+## Module composition and dependency intent
+
+- target module is already composed into the application when code uses cross-module scope lookup
+- cross-module `this.$scope.<module>` or `app.scope(...)` lookup alone does not require `vonaModule.dependencies`
+- `vonaModule.dependencies` is added only for a genuine target-module availability, dependency-first ordering, or minimum-version requirement
+- do not create speculative dependency edges or circular declarations merely to document a lookup
+
 ## Verification follow-up
 
 - unit tests

package/.claude/skills/cabloy-frontend-scaffold/SKILL.md

@@ -136,6 +136,8 @@ Check whether the feature needs:
 - SSR init-data updates
 - OpenAPI SDK regeneration
 - schema-driven UI or `$apiSchema` review
+- SSR hydration-equivalence review: classify state as SSR-required or intentionally deferred; keep server HTML and the hydration-time client render equivalent; defer private, cookie-unavailable, or browser-only query/load/render branches to an explicit post-hydration, admission, mounted, or interaction boundary
+- distinguish `$useStateData(...)` query ownership from readiness waits: `disableSuspenseOnInit` only skips its init-time suspense kick and does not prevent query creation or fetches; choose `$QueryEnsureLoaded(...)` or freshness helpers only at the later boundary that needs them
 - reverse fullstack handoff when newly added frontend resources will later be consumed by backend metadata or backend tooling
 
 If the frontend change introduces resources such as a custom form-field renderer, table-cell renderer, or other generated metadata that backend `ZovaRender.field(...)` / `ZovaRender.cell(...)` will consume, do not treat the task as frontend-only cleanup.
@@ -166,6 +168,7 @@ Check whether the feature needs:
 - build
 - metadata regeneration verification
 - SSR or route-path verification
+- hydration-time initial-render equivalence when SSR, private state, browser-only state, or async model state changes
 - edition-specific flavor, SSR site baseline, and project-asset verification
 
 ### SSR theme review reminder

package/.claude/skills/cabloy-frontend-scaffold/references/follow-up-checklist.md

@@ -13,6 +13,10 @@ After generating or extending a frontend thread, check which follow-up layers ap
 
 - API service or model alignment
 - SSR init-data needs
+- classify render-driving state as SSR-required or intentionally deferred; server HTML and the hydration-time client render must remain equivalent
+- for intentionally deferred private, cookie-unavailable, or browser-only state, keep the same neutral shell/placeholder through hydration and begin query/load/render work only at an explicit post-hydration, admission, mounted, or interaction boundary
+- `disableSuspenseOnInit` skips only the init-time suspense kick; do not treat it as a no-fetch or hydration-deferral mechanism
+- use `$QueryEnsureLoaded(...)` only where loaded data is explicitly required; choose freshness helpers when the boundary requires domain-valid data
 - OpenAPI SDK or schema-driven layer impact
 - backend contract reminder if frontend depends on generated backend contract output
 - if backend metadata will consume newly added frontend render resources, run the relevant Zova build first and then `npm run deps:vona`

package/.claude/skills/cabloy-master-detail/SKILL.md

@@ -152,7 +152,18 @@ Important rule:
 
 - do not start from hand-patching DTO placement or relation semantics until the generator path and specimen shape have been checked first
 
-## Step 6: Keep fullstack boundaries explicit
+## Step 6: Preserve the instance boundary across the aggregate
+
+Master-detail ownership is separate from Vona's tenant/instance boundary:
+
+- in the current tenancy model, a tenant corresponds to an instance and normal parent/detail model operations retain the active instance scope
+- relation and foreign-key checks must preserve that scope; aggregate ownership does not authorize bypassing it
+- treat a missing parent or detail from the normal scoped aggregate flow as absent; do not add unscoped existence probes merely to distinguish a foreign-instance row
+- if a future multi-merchant design is needed, model merchant ownership explicitly within the instance in addition to the aggregate relation
+
+For the canonical tenancy explanation, read [Multi-Instance and Instance Resolution](../../../cabloy-docs/backend/multi-instance-and-instance-resolution.md) and [Model Guide](../../../cabloy-docs/backend/model-guide.md).
+
+## Step 7: Keep fullstack boundaries explicit
 
 This skill is primarily for backend detail aggregation.
 
@@ -166,7 +177,7 @@ Use this skill first when the core problem is still:
 - aggregate vs standalone detail mode
 - nested detail DTO naming or placement in a scaffolding context
 
-## Step 7: Verification guidance
+## Step 8: Verification guidance
 
 Always finish with verification that matches the detail shape.
 

package/.github/workflows/playwright-e2e.yml

@@ -0,0 +1,45 @@
+name: playwright-e2e
+on:
+  push:
+    branches:
+      - main
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      DATABASE_DEFAULT_CLIENT: sqlite3
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
+    services:
+      redis:
+        image: redis:latest
+        ports:
+          - 6379:6379
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+      - uses: pnpm/action-setup@v5
+        with:
+          version: 11.5.2
+      - name: init
+        run: npm run init
+      - name: install Chromium
+        run: npx playwright install --with-deps chromium
+      - name: run Basic E2E baseline
+        run: npm run test:e2e:basic:clean
+      - name: build Commerce Zova artifacts
+        run: npm run build:zova:commerce
+      - name: synchronize Vona dependencies
+        run: npm run deps:vona
+      - name: run Commerce E2E baseline
+        run: npm run test:e2e:commerce:clean
+      - name: upload Playwright artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts
+          path: |
+            playwright-report/
+            test-results/
+          if-no-files-found: ignore

package/.gitignore

@@ -16,6 +16,7 @@ blob-report/
 
 **/.claude/settings.local.json
 **/.claude/worktrees
+**/CLAUDE.local.md
 
 **/.idea
 **/.DS_Store

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 5.1.112
+
+### Features
+
+- Add commerce member address ownership support.
+- Add commerce cart capabilities.
+- Add a commerce test seed module.
+- Add rules and catalog capabilities.
+- Add server-side rendered menu support.
+- Add commerce site administration capabilities.
+
+### Improvements
+
+- Update commerce DTOs, controllers, routing, product handling, stock balances, and upgrade flows.
+- Add Playwright end-to-end test workflow coverage.
+- Refine full-stack positioning documentation.
+
+## 5.1.111
+
+### Features
+
+- Update the application functionality.
+
 ## 5.1.110
 
 ### Features

package/CLAUDE.md

@@ -54,7 +54,8 @@ Before inventing a custom implementation path:
 - For Zova frontend analysis, do not default to generic Vue reinterpretation first. Read the code through Zova’s controller / bean / IoC architecture before mapping it to Vue concepts.
 - For Zova source-reading or Vue-vs-Zova explanation tasks, start from the frontend reading guides and source-reading map in `cabloy-docs/frontend/` before doing framework-neutral reinterpretation.
 - For frontend async state that affects rendering or interaction across consumers, prefer model-owned `$useStateData(...)` over controller-managed fetch/cache state.
-- Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; if strict readiness is needed later, wait explicitly at the interaction boundary.
+- Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; it does not prevent query creation, fetches, or hydration-time rendering. If strict readiness is needed later, wait explicitly at the interaction boundary.
+- In SSR, keep server HTML and the client's hydration-time initial render equivalent. When server rendering intentionally omits private, cookie-unavailable, or browser-only state, keep the same neutral shell or placeholder through hydration and defer its query/load/render branch to an explicit post-hydration, admission, mounted, or interaction boundary.
 - Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
 - For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
 - In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.
@@ -68,6 +69,8 @@ Before inventing a custom implementation path:
 - When backend code references `this.bean.xxx`, `ctx.bean.xxx`, or `app.bean.xxx`, use `IBeanRecordGlobal` and module `src/.metadata/index.ts` as the first static lookup surface; use `IBeanRecordGeneral` or `src/service` only when the target is not a global shorthand.
 - When adding a persisted field to an existing backend resource, ask the user whether `vonaModule.fileVersion` should be incremented before changing `meta.version.ts` or the module schema path. If yes, add a new migration version and bump `fileVersion`. If no, keep the current `fileVersion` and fold the schema change into the current version path. Do not assume the versioning strategy without confirmation.
 - In shared-database multitenancy, do not use `table.unique(...)` for business uniqueness. Keep ordinary indexes for lookup performance and enforce tenant-scoped uniqueness in the business layer.
+- In Vona, a tenant corresponds to an instance. Ordinary resource-model CRUD is automatically scoped to the active instance; treat records absent from that scope as absent, and do not use raw cross-instance probes merely to choose between `403` and not-found behavior. Model future multi-merchant boundaries explicitly inside an instance.
+- Model cross-Model query-cache dependencies as one directed, acyclic `modelsClear` / `modelsClearedBy` graph, and verify source mutations refresh warmed dependent queries; read `.docs-internal/architecture/vona-cross-model-query-cache-dependencies.md` before designing a nontrivial graph.
 - For `@Api.field(...)` and related schemaLike composition, framework guards now preserve previously attached OpenAPI metadata across schema rebuilds, but structure-shaping schemaLike is still order-sensitive. Treat `v.object(...)`, `v.array(...)`, `v.optional()`, `v.nullable()`, `v.default(...)`, and preprocess/transform wrappers as structure-shaping; keep the final structure-defining schemaLike last and verify emitted schema/OpenAPI output after such edits.
 
 ## Verification expectations

package/README.md

@@ -8,9 +8,9 @@
 
 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 provide the aligned architecture behind that workflow.
 
 [Documentation](https://docs.cabloy.com) · [npm](https://www.npmjs.com/package/cabloy) · [Web Demo](https://cabloy.com) · [Admin Demo](https://cabloy.com/admin) · [GitHub](https://github.com/cabloy/cabloy)
 
@@ -102,12 +102,12 @@ npm run upgrade
 
 ## Highlights
 
-- **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
 
 ## Technology Stack
 

package/cabloy-docs/backend/crud-workflow.md

@@ -95,6 +95,16 @@ Read this guide together with:
 - [Migration and Changes](/backend/migration-and-changes)
 - [Unit Testing](/backend/unit-testing)
 
+## Instance-scoped CRUD
+
+Generated controller, service, and model flows retain Vona's default active-instance scope. In the current tenancy model, a tenant corresponds to an instance, so ordinary resource CRUD should not accept caller-controlled `iid` or tenant selection.
+
+When a normal scoped view, update, or delete target is not found, preserve its absent/not-found semantics. Do not run an unscoped raw-table probe merely to discover whether another instance owns the same identifier and convert that result into `403`.
+
+If a future requirement introduces multiple merchants inside one instance, model that as an explicit additional business boundary with its own ownership, authorization, relations, indexes, and tests. It does not replace the existing instance scope.
+
+For the runtime tenancy boundary, see [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution). For model-level behavior and exceptional raw/builder usage, see [Model Guide](/backend/model-guide).
+
 ## Recommended workflow
 
 1. run the CRUD generator

package/cabloy-docs/backend/foundation.md

@@ -232,14 +232,39 @@ Scope groups a module’s resources behind one structured facade, including area
 - locale
 - error
 
-The key distinction is:
+Choose the narrowest lookup form that matches what is known at the call site:
 
-- `this.scope` means local module resources
-- `this.$scope.<module>` means cross-module resources
-- `app.scope(...)` means explicit app-level scope lookup outside the local class shorthand
+| Situation                                                                                                | Preferred form               | Example                                   |
+| -------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------- |
+| Resource belongs to the current `BeanBase` module                                                        | `this.scope`                 | `this.scope.model.stockBalance`           |
+| Another module is fixed in source and `$scope` is available                                              | `this.$scope.<fixedModule>`  | `this.$scope.commerceCatalog.model.sku`   |
+| Code has an application reference rather than `BeanBase` shorthands, such as a test or standalone helper | `app.scope('<module-name>')` | `app.scope('commerce-catalog').model.sku` |
+| A class uses the explicit application API or selects the module name at runtime                          | `this.app.scope(moduleName)` | `this.app.scope(moduleName)`              |
+
+Prefer `this.scope` for module-local business code and `this.$scope.<fixedModule>` for a statically known cross-module target. Use `app.scope(...)` or `this.app.scope(...)` when the shorthand is unavailable or the module name is genuinely dynamic. Do not replace a fixed typed shorthand with a string lookup merely for style, or mix equivalent fixed lookup forms in one access path.
 
 This is one of the reasons Vona backend code can stay concise without flattening everything into arbitrary imports.
 
+## Scope lookup vs module dependencies
+
+All of the lookup forms above resolve a resource from a module that is already part of the active application composition. Fixed cross-module Bean code normally uses:
+
+```typescript
+const modelSku = this.$scope.commerceCatalog.model.sku;
+```
+
+A test or standalone helper with an application reference can use:
+
+```typescript
+const modelSku = app.scope('commerce-catalog').model.sku;
+```
+
+Using `this.$scope.<fixedModule>`, `app.scope(...)`, or `this.app.scope(...)` does not by itself require adding the target module to the caller's `vonaModule.dependencies`. Lookup does not create a module dependency edge, so lookup alone cannot create a circular dependency.
+
+Scope lookup also does not compose, install, load, or order an absent module. The target must already be available through suite/application composition. Declare `vonaModule.dependencies` only when the caller has a genuine requirement for a target module's availability, dependency-first ordering, or minimum compatible version—not merely because it looks up that module's service, model, config, locale, or another resource.
+
+For the package, suite, and module dependency distinction, see [Package Map](/reference/package-map).
+
 ## Suite / module / package boundaries
 
 Vona architecture is not only about classes and beans. It is also about structural boundaries.

package/cabloy-docs/backend/introduction.md

@@ -2,7 +2,7 @@
 
 This page is the backend hub for Cabloy users, contributors, and AI vibe coding workflows that need the backend side of the framework.
 
-Vona is the backend half of Cabloy’s one-framework-system fullstack architecture.
+Vona is the backend layer of Cabloy’s one fullstack system, supporting bidirectional type sync, CLI-first workflows, and source-grounded docs and skills.
 
 ## What Vona is responsible for
 

package/cabloy-docs/backend/model-guide.md

@@ -199,23 +199,21 @@ A practical implication is:
 
 ## Instance-aware model semantics
 
-One important current-runtime distinction is that ordinary model usage is instance-aware by default.
+One important current-runtime distinction is that ordinary model usage is instance-aware by default. In Vona's current tenancy model, the active instance is the tenant boundary.
 
-A practical interpretation is:
+For normal resource models, the model layer handles the active instance `iid` as part of ordinary persistence behavior:
 
-- normal model operations participate in the current instance context
-- instance-aware filtering is part of normal model behavior unless disabled
-- request-scoped code should usually preserve that behavior instead of bypassing it casually
+- inserts receive the active instance identity
+- selects, `getById`, counts, updates, and deletes receive the active instance predicate
+- request-scoped code should preserve this behavior instead of accepting caller-controlled tenant or `iid` scope
 
-This is why `disableInstance` is a meaningful semantic choice rather than a minor ORM toggle.
+This is why `disableInstance` is a meaningful semantic choice rather than a minor ORM toggle. Use it only for a genuinely global/system model or another explicitly authorized contract that must ignore the active instance boundary.
 
-Use it only when the model truly should ignore the active instance boundary.
+A scoped miss is absent in the current tenant/instance. Do not use `disableInstance`, a plain builder, or raw SQL merely to probe another instance and choose between `403` and not-found behavior. A real authorization failure can still be `403`; the distinction is that an ordinary resource lookup should not disclose cross-instance existence.
 
-Another practical implication is:
+Lower-level builders and raw SQL need extra care when replacing ordinary model behavior. Preserve the active instance predicate when the operation is meant to remain instance-scoped, and document the authorization and audit contract when it deliberately is not.
 
-- lower-level builder or raw-SQL flows may need extra care when you are reproducing behavior that the ordinary model path would have applied automatically
-
-For the broader instance/config story, also see [Config Guide](/backend/config-guide).
+For the tenancy terminology and runtime boundary, see [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution). For generated resource flows, see [CRUD Workflow](/backend/crud-workflow). For the broader instance/config story, also see [Config Guide](/backend/config-guide).
 
 ## Datasource selection
 

package/cabloy-docs/backend/multi-instance-and-instance-resolution.md

@@ -191,6 +191,24 @@ That means:
 
 For the model-layer perspective, also see [Model Guide](/backend/model-guide).
 
+## Tenancy boundary: one Vona tenant per instance
+
+In Vona's current tenancy model, a tenant corresponds to an instance. The resolved active instance is the data-isolation boundary for ordinary resource code.
+
+For resources that inherit the normal entity base behavior:
+
+- `iid` persists the instance discriminator when instances share a datasource
+- normal model CRUD uses the active `ctx.instance.id` rather than a caller-supplied tenant or `iid`
+- isolated instances can add a separate datasource boundary through `isolateClient`, but they still remain separate instances
+
+This means a normal scoped lookup has one business result when it finds no row: that resource is absent in the current tenant/instance. Do not bypass model scope or issue an unscoped secondary lookup merely to reveal that another instance has the same identifier and change the result to `403`.
+
+This rule does not eliminate genuine authorization failures. Return `403` when the current request is not authorized to perform an operation on a resource that is available in its authorized scope. The rule only prevents ordinary scoped misses from becoming cross-instance existence disclosures.
+
+Do not use instance selection to represent a future merchant, store, organization, or similar business boundary. A multi-merchant design belongs inside one instance and needs explicit merchant ownership, authorization, relations, indexes, and tests in addition to the existing instance boundary.
+
+For the operational model rules, see [Model Guide](/backend/model-guide). For generated resource behavior, see [CRUD Workflow](/backend/crud-workflow).
+
 ## Relationship to runtime and config docs
 
 Read this guide together with:

package/cabloy-docs/backend/service-guide.md

@@ -94,7 +94,7 @@ A useful distinction is:
 - `this.scope` means local module resources
 - `this.$scope.<module>` means cross-module resources
 
-That same access model also appears for model, entity, config, locale, and other scope resources.
+That same access model also appears for model, entity, config, locale, and other scope resources. Cross-module scope lookup alone does not require a `vonaModule.dependencies` entry; see [Backend Foundation](/backend/foundation#scope-lookup-vs-module-dependencies) for the distinction between lookup and a true module dependency.
 
 ## Direct bean access
 

package/cabloy-docs/frontend/a-router-guide.md

@@ -122,7 +122,7 @@ Its main jobs are:
 - merge config-route overrides
 - synthesize alias routes when needed
 - wrap routed pages with layout routes when `meta.layout` requires it
-- expose helpers such as `getPagePath(...)`, `resolveName(...)`, and `ensureRoute(...)`
+- expose helpers such as `getPagePath(...)`, `getAliasPath(...)`, `resolveName(...)`, and `ensureRoute(...)`
 
 This is the file that most clearly shows how a module-local route record becomes operational router structure.
 

package/cabloy-docs/frontend/introduction.md

@@ -2,7 +2,7 @@
 
 This page is the frontend hub for Cabloy users, contributors, and AI vibe coding workflows that need the frontend side of the framework.
 
-Zova is the frontend half of Cabloy’s one-framework-system fullstack architecture.
+Zova is the frontend layer of Cabloy’s one fullstack system, supporting bidirectional type sync, CLI-first workflows, and source-grounded docs and skills.
 
 ## What Zova is responsible for
 

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: