cabloy 5.1.52 → 5.1.53

package/cabloy-docs/frontend/introduction.md

@@ -22,12 +22,80 @@ For contributor and automation workflows in this repository, prefer this order:
 3. inspect the active edition before assuming a UI stack
 4. document shared concepts once, then isolate edition-specific notes where the module set or UI library differs
 
+## Frontend reading paths
+
+Use this page as the main frontend hub, then choose the path that matches your task.
+
+### Getting started and architecture spine
+
+Start here when you need the shortest route to the frontend mental model and startup context:
+
+- [Quickstart](/frontend/quickstart)
+- [Foundation](/frontend/foundation)
+- [IoC and Beans](/frontend/ioc-and-beans)
+- [Modules and Suites](/frontend/modules-and-suites)
+- [Module Scope](/frontend/module-scope)
+- [Design Principles](/frontend/design-principles)
+- [Environment and Config Guide](/frontend/environment-config-guide)
+- [App Startup Guide](/frontend/app-startup-guide)
+- [System Startup Guide](/frontend/system-startup-guide)
+- [Frontend Directory Structure](/reference/frontend-directory-structure)
+
+### Page and routing flow
+
+Use this path when the task is page-oriented, route-oriented, or the first time you need Zod in frontend params and query work:
+
+- [Page Guide](/frontend/page-guide)
+- [Page Query Guide](/frontend/page-query-guide)
+- [Page Params Guide](/frontend/page-params-guide)
+- [Zod Guide](/frontend/zod-guide)
+- [Page Route Guide](/frontend/page-route-guide)
+- [Route Alias Guide](/frontend/route-alias-guide)
+- [Navigation Guards Guide](/frontend/navigation-guards-guide)
+
+### Components and UI flow
+
+Use this path when the task is about UI composition, component contracts, or theme work:
+
+- [Component Guide](/frontend/component-guide)
+- [Component Props Guide](/frontend/component-props-guide)
+- [Component v-model Guide](/frontend/component-v-model-guide)
+- [Generic Component Guide](/frontend/generic-component-guide)
+- [CSS-in-JS Guide](/frontend/css-in-js-guide)
+- [Theme Guide](/frontend/theme-guide)
+- [Icon Engine Guide](/frontend/icon-engine-guide)
+
+### Data, contract, and SSR flow
+
+Use this path when the task is about data loading, API contracts, generated SDKs, or SSR behavior:
+
+- [Server Data](/frontend/server-data)
+- [API Guide](/frontend/api-guide)
+- [Model Architecture](/frontend/model-architecture)
+- [Model State Guide](/frontend/model-state-guide)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [SDK Guide](/frontend/sdk-guide)
+- [SSR Overview](/frontend/ssr-overview)
+- [SSR Init Data](/frontend/ssr-init-data)
+- [SSR ClientOnly](/frontend/ssr-client-only)
+- [SSR SEO Meta](/frontend/ssr-seo-meta)
+- [SSR Env](/frontend/ssr-env)
+
+### Tooling support
+
+Use these pages when the work is about commands, scripts, or mock-driven iteration:
+
+- [CLI](/frontend/cli)
+- [Scripts](/frontend/scripts)
+- [Mock Guide](/frontend/mock-guide)
+
 ## Edition impact
 
 Frontend work is where Cabloy Basic and Cabloy Start differ most clearly.
 
 - **Shared frontend engineering layer**: both editions follow the same Zova-centered frontend direction, with Vue, Vite, Quasar tooling, and related libraries.
 - **Cabloy Basic UI layer**: current public docs and examples align with DaisyUI + Tailwind CSS.
-- **Cabloy Start UI layer**: the private commercial edition aligns with Vuetify and ships different frontend modules, SSR site baselines, and project assets.
+- **Cabloy Start UI layer**: the private commercial edition aligns with Vuetify and may use different frontend modules, SSR site baselines, and project assets.
 
 Because of this, automation and docs should always detect the active edition before recommending page-level, component-level, or UI-library-specific work.

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

@@ -23,7 +23,7 @@ class ServiceRouterGuards {
   protected onRouterGuards(router: BeanRouter) {
     router.beforeEach(async to => {
       if (
-        !this.sys.config.ssr.ignoreCookieOnServer &&
+        !this.sys.config.ssr.cookieDisabledOnServer &&
         to.meta.requiresAuth !== false &&
         !this.$passport.isAuthenticated
       ) {

package/cabloy-docs/frontend/quickstart.md

@@ -73,6 +73,7 @@ Use the root wrappers as the normal entrypoint for this framework repository, th
 
 Read together with:
 
+- [Reference Introduction](/reference/introduction)
 - [Repo Scripts](/reference/repo-scripts)
 - [Frontend Scripts](/frontend/scripts)
 

package/cabloy-docs/frontend/scripts.md

@@ -71,7 +71,7 @@ The sibling `cabloy-start` repository is the private commercial edition and uses
 - `cabloyStartAdmin`
 - `cabloyStartWeb`
 
-Those commands are not driven by the current Basic repo root wrappers, so verify the Start repo’s `package.json`, suites, SSR site baselines, and project assets before documenting or automating them.
+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.
 
 ## Workflow guidance
 

package/cabloy-docs/frontend/ssr-env.md

@@ -20,6 +20,29 @@ Representative variables include:
 
 These affect areas such as cookie-driven SSR behavior, theme defaults, body-load observation, server-side API targeting, and SSR production port behavior.
 
+## Theme implications of `SSR_COOKIE`
+
+`SSR_COOKIE` is not only a storage choice. It also changes what SSR can guarantee about theme-sensitive output.
+
+A practical split is:
+
+- `SSR_COOKIE=true`: the server can resolve theme state from cookies during SSR
+- `SSR_COOKIE=false`: the server cannot guarantee that theme-sensitive SSR reads match the browser's eventual selected theme
+
+In practice, this means Web SSR and Admin SSR can intentionally expose different theme capabilities.
+
+- In a cookie-capable SSR path, theme-sensitive server rendering can rely on a stronger server/client match guarantee.
+- In a cookie-disabled SSR path, SSR should treat theme-sensitive reads as non-authoritative for the browser's final theme and prefer hydration-tolerant or client-finalized decisions when exact matching matters.
+
+A practical development rule is:
+
+- use `SSR_COOKIE` to determine the capability level
+- use the active edition and UI library to determine how that capability is implemented
+
+That matters because Cabloy Basic and Cabloy Start share the same theme architecture but do not use the same adapter-level SSR handoff strategy.
+
+For the broader theme usage contract and edition-aware checklist, see [Theme Guide](/frontend/theme-guide). For the runtime/flavor selection model behind these env choices, see [Environment and Config Guide](/frontend/environment-config-guide).
+
 ## Dynamic environment variables
 
 The runtime also exposes environment variables that describe the current execution context, such as:

package/cabloy-docs/frontend/theme-guide.md

@@ -127,6 +127,19 @@ A useful distinction is:
 - brand-theme switching changes which named theme provides the token set
 - both still work through the same `$theme` and token architecture
 
+## Edition and UI-library decision gate
+
+Before applying SSR theme rules, identify the active edition and UI library first.
+
+In the current Cabloy monorepo context:
+
+- Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions
+- Cabloy Start currently means Vuetify assumptions
+
+The shared Zova theme architecture stays the same, but token shape, SSR output strategy, and hydration integration can vary by adapter.
+
+That means a rule that is safe for one edition or UI library is not automatically portable to another.
+
 ## What stays shared across editions
 
 Across Cabloy Basic and Cabloy Start, the core theme architecture remains shared:
@@ -140,15 +153,135 @@ What may still vary by edition or UI library is:
 
 - the exact token shape
 - concrete default token values
+- SSR server output strategy
+- client hydration and theme-finalization behavior
 - integration details for a specific component library or visual system
 
-## Implementation checks for theme-related changes
+## SSR flavor capability gate
+
+After identifying the edition and UI library, identify the SSR flavor capability level.
+
+A practical split is:
+
+- Web SSR is usually the lower-authority path for final browser theme when cookie-backed SSR resolution is unavailable
+- Admin SSR is the stronger path for SSR-stable theme-sensitive rendering when cookie-backed SSR resolution is available
+
+In practice, always check `SSR_COOKIE` and the active adapter behavior before assuming that server-rendered theme-sensitive output can exactly match the hydrated client state.
+
+With `SSR_COOKIE=false`, server reads of `$theme.dark`, `$theme.darkMode`, and `$token` should be treated as non-authoritative for the browser's final theme unless the active adapter explicitly documents a stronger guarantee.
+
+With `SSR_COOKIE=true`, SSR theme-sensitive branching can rely on a stronger server/client match guarantee, but should still stay inside the established theme handler and hydration pipeline.
+
+For the env-side explanation of `SSR_COOKIE`, see [SSR Environment Variables](/frontend/ssr-env). For the flavor/runtime selection model, see [Environment and Config Guide](/frontend/environment-config-guide).
+
+## Shared development rules
+
+Apply these rules before writing adapter-specific logic:
+
+1. keep concrete theme values in theme beans instead of scattering them across pages or components
+2. use `$token` when code consumes theme-defined design values
+3. use `$theme` when code needs to inspect or switch theme state itself
+4. keep adapter-specific DOM/theme application inside the active theme handler or client boot path rather than duplicating it in feature code
+5. do not assume token fields are portable across UI libraries without checking the active adapter contract
+
+## Cabloy Basic checklist: DaisyUI + Tailwind CSS
+
+In the current `__CABLOY_BASIC__` frontend setup:
+
+- DaisyUI + Tailwind CSS is the active UI layer
+- theme beans and `$token` remain the shared architectural contract
+- Web SSR emits dual dark/light SSR markers and the browser selects the final theme during bootstrap
+- the active theme handler owns `data-theme` and CSS variable application
+
+Apply these rules:
+
+- In Web SSR, treat server-rendered reads of `$theme.dark`, `$theme.darkMode`, and theme-derived `$token` values as non-authoritative for the browser's final theme.
+- Keep theme-sensitive SSR output fallback-safe or hydration-tolerant when exact browser theme matching matters.
+- Defer final theme-sensitive decisions to the client when an exact browser theme match is required.
+- Let the theme handler own `data-theme` and CSS variable application instead of duplicating that logic in pages or components.
+- In Admin SSR, cookie-backed theme resolution is the stronger path for SSR-stable theme-sensitive branching.
+
+## Cabloy Start comparison checklist: Vuetify
+
+In `__CABLOY_START__`, the theme architecture is still shared, but the adapter behavior is deeper:
+
+- Vuetify-oriented token payloads are part of the active theme contract
+- the SSR adapter writes theme name, dark-variant theme data, and token payloads for hydration
+- client boot reconstructs the active Vuetify theme from SSR state
+
+Apply these comparison rules:
+
+- Do not collapse Cabloy Start behavior into the simpler Cabloy Basic `data-theme` mental model.
+- Treat Vuetify adapter state handoff and client boot hydration as part of the theme contract.
+- When documenting or changing SSR theme rules, verify both the server handoff payload and the client reconstruction path.
+- Web SSR still needs lower-authority assumptions when cookie-backed SSR resolution is unavailable, even though the adapter handoff is richer than in Cabloy Basic.
+
+## Quick comparison table
+
+| Edition      | UI library             | SSR server handoff                                                                   | Client hydration/finalization                                       | Safe Web SSR rule                                                                                                                     |
+| ------------ | ---------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| Cabloy Basic | DaisyUI + Tailwind CSS | Dual dark/light SSR markers plus handler-owned DOM theme output                      | Browser bootstrap resolves the final theme and applies `data-theme` | Do not treat server theme-sensitive reads as final browser truth                                                                      |
+| Cabloy Start | Vuetify                | Adapter-driven SSR state including theme name, dark variant data, and token payloads | Client boot reconstructs the active Vuetify theme from SSR state    | Do not reduce Start to a Basic-style `data-theme`-only model; still treat Web SSR as lower-authority without cookie-backed resolution |
+
+## SSR theme review checklist
+
+Use this short review checklist when editing SSR theme behavior or reviewing AI-generated changes.
+
+Do:
+
+- identify the active edition marker before applying SSR theme rules
+- identify the active UI library before assuming token shape or hydration behavior
+- keep concrete theme values in theme beans and consume them through `$token`
+- use `$theme` for theme-state control and `$token` for theme-value consumption
+- verify whether the active flavor provides cookie-backed SSR theme resolution before trusting server theme reads
+- keep adapter-specific theme finalization inside the existing theme handler or client boot path
+- verify both server handoff and client hydration behavior when documenting or changing adapter-specific SSR theme logic
+- treat Web SSR as the stricter path unless the active adapter and cookie capability clearly provide a stronger guarantee
+
+Don't:
+
+- do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff
+- do not assume a Basic `data-theme` pattern fully describes Vuetify-based Start behavior
+- do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth in cookie-disabled Web SSR
+- do not duplicate theme-finalization logic in pages or components when the active adapter already owns that responsibility
+
+## Reviewer template
+
+Use this short template in PR review, code review, or AI review when a change touches SSR theme behavior.
+
+- [ ] I identified the active edition marker before reviewing SSR theme behavior.
+- [ ] I identified the active UI library before assuming token shape or hydration behavior.
+- [ ] I verified whether the active flavor provides cookie-backed SSR theme resolution.
+- [ ] I checked whether the change treats server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as lower-authority in cookie-disabled Web SSR.
+- [ ] I verified that adapter-specific theme finalization stays inside the existing theme handler or client boot path.
+- [ ] I checked whether the rule or behavior is shared across editions or adapter-specific.
+- [ ] For Cabloy Basic, I verified the change does not over-assume a final browser theme from server-side theme-sensitive reads.
+- [ ] For Cabloy Start, I verified the change respects Vuetify SSR state handoff and client reconstruction rather than reducing it to a Basic-style `data-theme`-only model.
+- [ ] I verified both server handoff and client hydration behavior for the active adapter.
+
+## Prompt-ready reviewer snippet
+
+Use this block directly in a reviewer-agent or code-review prompt when a change touches SSR theme behavior:
+
+```text
+Review this change with the Cabloy SSR theme rules in mind.
+
+1. Detect the active edition marker and UI library before assuming SSR theme behavior.
+2. Do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff.
+3. In cookie-disabled Web SSR, do not treat server reads of $theme.dark, $theme.darkMode, or $token as final browser truth.
+4. Verify that adapter-specific theme finalization stays inside the existing theme handler or client boot path.
+5. Verify both server handoff and client hydration behavior for the active adapter.
+6. Flag any change that collapses Vuetify-based Start behavior into a Basic-style data-theme-only mental model.
+```
+
+## Verification checklist
 
-When changing theme behavior, ask:
+When changing theme behavior or writing theme-sensitive SSR code, ask:
 
-1. should this change live in a theme bean instead of inlining colors into components?
-2. is the change about dark mode, brand style, or both?
-3. should the change be token-driven instead of component-specific?
-4. does the active edition change the UI component library while preserving the same theme architecture?
+1. which edition marker is active, and which UI library contract does that imply?
+2. is the change about token design, theme state control, SSR output, or client hydration?
+3. does the active flavor provide cookie-backed SSR theme resolution?
+4. is this rule shared across editions, or adapter-specific?
+5. does the implementation follow the existing handler and hydration path for the active UI library?
 
-That helps keep theme work scalable and edition-aware.
+That keeps theme work scalable, edition-aware, and aligned with the real SSR capability boundary.

package/cabloy-docs/fullstack/cli.md

@@ -34,7 +34,7 @@ Use this distinction consistently:
 - use the CLI when you are discovering commands, generating framework resources, running framework-specific tooling, or inspecting workflow families
 - use root scripts when you are running broader repository workflows such as development, builds, or verification
 
-For the compact root-script lookup surface, see [Repo Scripts](/reference/repo-scripts).
+For the broader Reference landing page, see [Reference Introduction](/reference/introduction). For the compact root-script lookup surface, see [Repo Scripts](/reference/repo-scripts).
 
 ## Shared discovery pattern
 
@@ -87,11 +87,11 @@ For side-specific depth, see:
 
 Use these three surfaces for different jobs:
 
-| Surface | Best for | Typical examples |
-| --- | --- | --- |
-| Root scripts | Repo-wide development, build, and verification workflows | `npm run dev`, `npm run build`, `npm run test` |
-| CLI | Framework-aware generation, refactors, initialization, and tooling | `npm run vona :create`, `npm run zova :refactor`, `npm run zova :openapi` |
-| VS Code extensions | In-editor discovery of the same framework workflow families | Explorer right-click menus for `Create`, `Init`, `Refactor`, `Tools`, and related groups |
+| Surface            | Best for                                                           | Typical examples                                                                         |
+| ------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| Root scripts       | Repo-wide development, build, and verification workflows           | `npm run dev`, `npm run build`, `npm run test`                                           |
+| CLI                | Framework-aware generation, refactors, initialization, and tooling | `npm run vona :create`, `npm run zova :refactor`, `npm run zova :openapi`                |
+| VS Code extensions | In-editor discovery of the same framework workflow families        | Explorer right-click menus for `Create`, `Init`, `Refactor`, `Tools`, and related groups |
 
 ## CLI and VS Code extensions
 

package/cabloy-docs/fullstack/edition-collaboration-differences.md

@@ -26,7 +26,7 @@ The most important differences show up in:
 - frontend flavor names
 - frontend module composition
 - admin/web SSR site baselines
-- private value-add content and project assets in Cabloy Start
+- edition-specific private value-add content and project assets in Cabloy Start
 - potentially different generated output paths or integration details
 
 ## Cabloy Basic

package/cabloy-docs/fullstack/introduction.md

@@ -15,6 +15,44 @@ With Vona, Zova, suite-based modules, and CLI-first workflows, Cabloy turns comm
 - **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
 
+## 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)
+- [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)
+- [Vona + Zova Integration](/fullstack/vona-zova-integration)
+- [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)
+- [Editions Overview](/editions/overview)
+- [Choosing Basic vs Start](/editions/choosing-between-basic-and-start)
+
 ## Shared architecture
 
 - **Vona** provides the backend framework capabilities.
@@ -72,7 +110,7 @@ The monorepo makes it possible to keep backend and frontend concepts, tooling, a
 - **Cabloy Basic**: DaisyUI + Tailwind CSS
 - **Cabloy Start**: Vuetify
 
-## Common-first, edition-aware
+## Edition impact
 
 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.
 

package/cabloy-docs/fullstack/vona-zova-integration.md

@@ -56,7 +56,7 @@ Its root script surface uses Start-specific flavors such as:
 - `cabloyStartAdmin`
 - `cabloyStartWeb`
 
-Because Start differs in UI layer, module composition, SSR site baselines, and project assets, do not reuse Basic integration examples without first confirming:
+Because Start can differ in UI layer, module composition, SSR site baselines, and project assets, do not reuse Basic integration examples without first confirming:
 
 1. the `__CABLOY_START__` marker
 2. the Start repo’s `package.json`

package/cabloy-docs/index.md

@@ -60,7 +60,7 @@ Start here to learn the shared Cabloy architecture, see how Vona and Zova fit to
 2. [Fullstack CLI](/fullstack/cli)
 3. [VS Code Extensions](/fullstack/vscode-extensions)
 4. [AI Development Introduction](/ai/introduction)
-5. [Repo Scripts Reference](/reference/repo-scripts)
+5. [Reference Introduction](/reference/introduction)
 6. [Editions Overview](/editions/overview)
 
 ## Documentation scope labels

package/cabloy-docs/reference/frontend-directory-structure.md

@@ -0,0 +1,125 @@
+# Frontend Directory Structure
+
+This page gives a compact reference view of the frontend tree under `zova/`.
+
+## Why this page exists
+
+The package map explains the architectural meaning of package, module, and suite boundaries.
+
+This page complements that by showing the practical frontend tree layout used in the Cabloy repository.
+
+## Simplified frontend tree
+
+Representative frontend structure:
+
+```text
+zova/
+├── packages-cli/
+├── packages-utils/
+├── packages-zova/
+├── env/
+├── public/
+├── src-ssr/
+└── src/
+   ├── boot/
+   ├── css/
+   ├── front/
+   │  ├── config/
+   │  └── typing/
+   ├── module/
+   ├── module-vendor/
+   ├── suite/
+   └── suite-vendor/
+```
+
+## Meaning of the main directories
+
+| Path                      | Meaning                                        |
+| ------------------------- | ---------------------------------------------- |
+| `zova/packages-cli/`      | Zova CLI entrypoints and command sets          |
+| `zova/packages-utils/`    | shared frontend-side utilities                 |
+| `zova/packages-zova/`     | framework packages                             |
+| `zova/env/`               | frontend env files and runtime/build inputs    |
+| `zova/public/`            | public static assets                           |
+| `zova/src-ssr/`           | SSR entrypoints and SSR-related project source |
+| `zova/src/boot/`          | app bootstrapping and startup registration     |
+| `zova/src/css/`           | project-level CSS and theme entry assets       |
+| `zova/src/front/config/`  | project-level frontend config overrides        |
+| `zova/src/front/typing/`  | project-level frontend type definitions        |
+| `zova/src/module/`        | first-party standalone frontend modules        |
+| `zova/src/module-vendor/` | vendor-provided standalone frontend modules    |
+| `zova/src/suite/`         | first-party frontend suites and their modules  |
+| `zova/src/suite-vendor/`  | vendor-provided frontend suites and modules    |
+
+## Project-level frontend areas
+
+Within the frontend application layer, contributors should also know these practical areas:
+
+| Path                     | Meaning                                            |
+| ------------------------ | -------------------------------------------------- |
+| `zova/env/`              | frontend env files and runtime/build inputs        |
+| `zova/public/`           | project-level public static assets                 |
+| `zova/src-ssr/`          | project-level SSR entry and SSR middleware wiring  |
+| `zova/src/boot/`         | project-level boot registration and startup hooks  |
+| `zova/src/css/`          | project-level CSS, theme, and style entry assets   |
+| `zova/src/front/config/` | project-level frontend config and override surface |
+| `zova/src/front/typing/` | project-level frontend typing definitions          |
+
+## Edition note
+
+The high-level Zova tree above is intentionally stable across Cabloy Basic and Cabloy Start.
+
+A practical rule is:
+
+- use the shared tree as the structural reference
+- treat suite names and UI-layer examples as edition-sensitive details
+- in Cabloy Basic, public examples may include suites such as `cabloy-basic` and `a-devui`
+- in Cabloy Start, examples may include suites such as `cabloy-start` and `a-vuetify`
+
+Cabloy Start is a sibling repository, not a subdirectory of this monorepo.
+
+## Practical development reading of the tree
+
+A useful rule is:
+
+- start in `zova/src/module/` when the work belongs to a standalone frontend module
+- start in `zova/src/suite/` when the work belongs to a suite-composed business area
+- inspect `zova/packages-cli/` when the task is about command discovery, generation behavior, or refactor behavior
+- inspect `zova/src/front/config/` when the task is about project-level frontend config overrides rather than module-local defaults
+- inspect `zova/src/boot/` or `zova/src-ssr/` when the task is about startup flow or SSR behavior
+- inspect `zova/src/css/` and `zova/public/` when the task is about project-level styling or static assets
+
+A practical generator-oriented reading is:
+
+- `create:*` commands choose the structural target before placing frontend resources
+- `init:*` commands create project-level or module-level support assets
+- `refactor:*` commands reshape existing frontend patterns without requiring manual rework from scratch
+- `openapi:*` commands affect generated SDK-related frontend surfaces
+
+## Relationship to other reference pages
+
+Read this page together with:
+
+- [Package Map](/reference/package-map)
+- [Frontend (Zova)](/frontend/introduction)
+- [Modules and Suites](/frontend/modules-and-suites)
+- [Environment and Config Guide](/frontend/environment-config-guide)
+- [App Startup Guide](/frontend/app-startup-guide)
+- [System Startup Guide](/frontend/system-startup-guide)
+- [Frontend CLI](/frontend/cli)
+
+A practical split is:
+
+- [Frontend (Zova)](/frontend/introduction) is the broader frontend hub
+- [Package Map](/reference/package-map) explains architecture boundaries and package metadata
+- this page explains the practical directory tree contributors navigate
+
+## Implementation checks for frontend file-location changes
+
+When changing frontend code, ask:
+
+1. does this change belong to a standalone module, a suite-contained module, or a project-level frontend area?
+2. is the task about generation behavior under `packages-cli/`, startup behavior under `src/boot` or `src-ssr`, or feature code under `src/`?
+3. should the example use a shared structural path, a Cabloy Basic example, or a public Cabloy Start example note?
+
+That helps keep frontend file references aligned with the actual monorepo layout.

package/cabloy-docs/reference/introduction.md

@@ -0,0 +1,47 @@
+# Reference
+
+This page is the reference hub for shared monorepo commands, package lookup, directory lookup, and shared terminology.
+
+## What Reference is responsible for
+
+- shared monorepo command entrypoints
+- CLI lookup and command-surface discovery
+- package lookup across the repository
+- backend and frontend directory lookup
+- shared terminology and glossary support
+
+## How to approach reference work
+
+For contributor and automation workflows in this repository, prefer this order:
+
+1. inspect the root `package.json` when you need the shared workflow entrypoints
+2. inspect the CLI reference before inferring command families from memory
+3. use package and directory lookup pages when the task is about locating code, modules, or shared terms
+4. pair Reference pages with Backend, Frontend, or Fullstack guides when lookup alone is not enough
+
+## Reference reading paths
+
+Use Reference as the lookup area for shared commands, package discovery, directory lookup, and shared terminology.
+
+### Workflow entry path
+
+Start here when you first need the shared monorepo command surface:
+
+- [Repo Scripts](/reference/repo-scripts)
+- [CLI Reference](/reference/cli-reference)
+- [Fullstack CLI](/fullstack/cli)
+
+### Structure and lookup path
+
+Use this path when you need to find where packages, backend directories, frontend directories, or shared terms live:
+
+- [Package Map](/reference/package-map)
+- [Backend Directory Structure](/reference/backend-directory-structure)
+- [Frontend Directory Structure](/reference/frontend-directory-structure)
+- [Glossary](/reference/glossary)
+
+## Edition impact
+
+Cabloy Start keeps the same high-level workflow pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own SSR site baselines and project assets in the licensed private repository.
+
+When documenting or automating flavor-specific commands, always confirm the active repo first.

package/cabloy-docs/reference/package-map.md

@@ -96,6 +96,8 @@ For the broader backend entry path, also see [Backend (Vona)](/backend/introduct
 
 For the frontend architectural meaning of modules, suites, scope-driven resources, and runtime/startup structure, see `/frontend/modules-and-suites`, `/frontend/module-scope`, `/frontend/ioc-and-beans`, `/frontend/environment-config-guide`, `/frontend/app-startup-guide`, and `/frontend/system-startup-guide`.
 
+For the practical frontend directory tree contributors navigate, also see [Frontend Directory Structure](/reference/frontend-directory-structure).
+
 ## Sibling edition
 
 - `cabloy-start` is a separate sibling repository, not a subdirectory of this monorepo.

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

@@ -1,5 +1,9 @@
 # Repo Scripts
 
+Use this page when you need the compact lookup surface for the shared root scripts exposed by the Cabloy Basic monorepo.
+
+For the broader Reference landing page, see [Reference Introduction](/reference/introduction).
+
 The root `package.json` is the first reference point for shared monorepo workflows.
 
 ## Current shared entrypoints in Cabloy Basic
@@ -21,9 +25,7 @@ The root `package.json` is the first reference point for shared monorepo workflo
 
 ## Edition-sensitive note
 
-Cabloy Start keeps the same high-level pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own Start-specific suites, SSR site baselines, and project assets in the licensed private repository.
-
-### Documentation and automation guidance
+Cabloy Start keeps the same high-level pattern while using different frontend flavors such as `cabloyStartAdmin` and `cabloyStartWeb`, plus its own SSR site baselines and project assets in the licensed private repository.
 
 When documenting or automating flavor-specific commands, always confirm the active repo first.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.52",
+  "version": "5.1.53",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [

package/zova/package.original.json

@@ -94,7 +94,7 @@
       "@quasar/app-vite": "npm:@cabloy/quasar-app-vite@^2.5.10",
       "@vue/babel-plugin-jsx": "npm:@cabloy/vue-babel-plugin-jsx@^2.0.1",
       "@vue/compiler-sfc": "npm:@cabloy/vue-compiler-sfc@^3.5.14",
-      "@vue/runtime-core": "npm:@cabloy/vue-runtime-core@^3.5.56",
+      "@vue/runtime-core": "npm:@cabloy/vue-runtime-core@^3.5.57",
       "@vue/runtime-dom": "npm:@cabloy/vue-runtime-dom@^3.5.13",
       "@vue/reactivity": "npm:@cabloy/vue-reactivity@^3.5.16",
       "@vue/server-renderer": "npm:@cabloy/vue-server-renderer@^3.5.18",