cabloy 5.1.52 → 5.1.54

package/cabloy-docs/editions/cabloy-start.md

@@ -17,9 +17,9 @@ Use Cabloy Start as the edition-aware target when work depends on:
 - direct use of the licensed private repository source
 - Vuetify-specific frontend workflows
 - Cabloy Start flavor names in frontend scripts
-- modules that exist in the private Start repository but not in Basic
-- licensed private-repo structure and Start-specific project composition
-- Start-specific SSR site baselines and project assets
+- edition-specific module composition in the licensed Start repository
+- licensed private-repo structure and edition-specific project composition
+- edition-specific SSR site baselines and project assets
 
 ## Get access and initialize
 

package/cabloy-docs/editions/choosing-between-basic-and-start.md

@@ -6,7 +6,7 @@ This guide helps you choose the right Cabloy edition before you start a new proj
 
 Choose **Cabloy Basic** when you want the public framework/reference edition, the default `npm create cabloy` project route, and a faster path for open, community-oriented, or small-to-medium system development.
 
-Choose **Cabloy Start** when you want the private commercial edition, purchase-based access to the licensed private repository source, and a stronger baseline for more complex business systems built around the Start-specific suites, SSR sites, project assets, and Vuetify UI layer.
+Choose **Cabloy Start** when you want the private commercial edition, purchase-based access to the licensed private repository source, and a stronger baseline for more complex business systems built around Start-oriented SSR sites, project assets, and a Vuetify-aligned UI layer.
 
 ## What stays the same in both editions
 
@@ -38,7 +38,7 @@ Cabloy Start is usually the better fit when you want:
 - the private commercial edition
 - purchase-based access to the licensed private repository source
 - direct cloning of the Start repository after authorization
-- Start-specific suites, flavors, SSR site baselines, and project assets
+- Start-specific flavors, SSR site baselines, and project assets
 - a UI layer aligned with Vuetify
 - a stronger starting point for more complex business systems
 - edition-specific rules, skills, and docs optimized for the Start repo assumptions
@@ -58,12 +58,12 @@ Cabloy Start is usually the better fit when you want:
 ### Repo and asset model
 
 - **Cabloy Basic**: public repository and public reference materials
-- **Cabloy Start**: private repository with Start-specific suites, SSR sites, and project assets
+- **Cabloy Start**: private repository with edition-specific SSR sites and project assets
 
 ### AI workflow assumptions
 
 - **Cabloy Basic**: use Basic-specific examples, flavors, modules, and UI assumptions
-- **Cabloy Start**: use Start-specific examples, flavors, modules, SSR site baselines, and UI assumptions
+- **Cabloy Start**: use Start-specific examples, flavors, SSR site baselines, and UI assumptions
 
 This is why edition detection matters so much for AI vibe coding.
 
@@ -72,7 +72,7 @@ This is why edition detection matters so much for AI vibe coding.
 Use this rule when you need a fast decision:
 
 1. If you want the public, default, `npm create cabloy` path, choose **Cabloy Basic**.
-2. If you want the licensed private repo with Start-specific assets, a Vuetify-based business-system baseline, and a clone-plus-`npm run init` onboarding path, choose **Cabloy Start**.
+2. If you want the licensed private repo with Start-oriented assets, a Vuetify-based business-system baseline, and a clone-plus-`npm run init` onboarding path, choose **Cabloy Start**.
 3. If AI workflow accuracy matters for UI generation, SSR site assumptions, or flavor-specific commands, confirm the edition before writing prompts, rules, skills, or docs.
 
 ## Read together with

package/cabloy-docs/editions/overview.md

@@ -1,5 +1,7 @@
 # Editions Overview
 
+This page is the editions hub for deciding which Cabloy baseline you are working with and which assumptions should follow from that choice.
+
 Cabloy currently supports two related but distinct editions:
 
 - **Cabloy Basic**
@@ -9,6 +11,35 @@ They share one Cabloy fullstack architecture, but they are distributed, composed
 
 If you need a recommendation path, start with [Choosing Between Cabloy Basic and Cabloy Start](/editions/choosing-between-basic-and-start).
 
+## How to approach editions work
+
+For contributor and automation workflows in this repository, prefer this order:
+
+1. identify the active edition before making UI-sensitive, flavor-sensitive, module-sensitive, or asset-sensitive assumptions
+2. explain the shared Cabloy architecture once before branching into edition-specific notes
+3. split documentation or workflow guidance only where the editions intentionally diverge
+4. use explicit edition markers and flavor names instead of treating the editions as interchangeable
+
+## Editions reading paths
+
+Use this page as the main editions hub, then choose the path that matches your task.
+
+### Selection path
+
+Start here when the task is about choosing the right edition baseline or understanding distribution differences:
+
+- [Choosing Basic vs Start](/editions/choosing-between-basic-and-start)
+- [Cabloy Basic](/editions/cabloy-basic)
+- [Cabloy Start](/editions/cabloy-start)
+
+### Detection and workflow path
+
+Use this path when the task is about repo-aware automation, flavor assumptions, or edition-safe workflow choices:
+
+- [Edition Detection](/editions/detection)
+- [Fullstack Introduction](/fullstack/introduction)
+- [AI Development Introduction](/ai/introduction)
+
 ## Shared fullstack core
 
 Both editions are built around the same core direction:
@@ -38,7 +69,7 @@ Cabloy Start is the private commercial edition.
 - the private repository is marked with `__CABLOY_START__`
 - users first purchase a license and obtain repository access, then clone the private repository source directly
 - after cloning, the project is initialized through the Start edition workflow
-- Start provides its own suites, flavors, SSR sites, and project assets for that edition
+- Start uses its own edition-specific flavors, SSR site baselines, and project assets for that edition
 
 Cabloy Start is optimized as a commercial baseline for more complex business systems while staying on the same Cabloy fullstack direction.
 
@@ -74,13 +105,13 @@ The editions intentionally diverge in several surfaces:
 - frontend flavor names
 - suite and module composition
 - admin/web SSR site baselines
-- licensed private-repo structure and Start-specific project assets
+- licensed private-repo structure and edition-specific project assets
 - rules, skills, and docs used for AI vibe coding
 
 For example:
 
 - **Cabloy Basic** provides the `cabloy-basic` suites and the `cabloyBasicAdmin` / `cabloyBasicWeb` Zova flavors
-- **Cabloy Start** provides the `cabloy-start` suites and the `cabloyStartAdmin` / `cabloyStartWeb` Zova flavors
+- **Cabloy Start** uses public flavors such as `cabloyStartAdmin` and `cabloyStartWeb`
 
 ## Why the repo markers matter
 

package/cabloy-docs/frontend/css-in-js-guide.md

@@ -109,7 +109,7 @@ A practical rule is:
 This is especially important in Cabloy because the two editions diverge in frontend stack choices:
 
 - **Cabloy Basic** aligns with DaisyUI + TailwindCSS oriented examples
-- **Cabloy Start** aligns with Vuetify-oriented modules
+- **Cabloy Start** aligns with Vuetify-oriented frontend workflows
 
 A UI-library-independent styling layer makes it easier for the same architectural ideas to survive across both editions.
 

package/cabloy-docs/frontend/environment-config-guide.md

@@ -99,6 +99,34 @@ A representative SSR admin development stack looks like:
 
 The config side follows the same merge pattern with `config.ts`, `config.[meta].ts`, and `.local` variants.
 
+## Flavor-aware capability differences
+
+Different SSR flavors can intentionally expose different runtime capabilities rather than behaving identically.
+
+A concrete example in the current Cabloy Basic frontend setup is SSR theme resolution:
+
+- Web SSR uses a cookie-disabled path
+- Admin SSR uses a cookie-capable path
+
+That means the two flavors should not be treated as providing the same guarantee for theme-sensitive SSR output.
+
+In practice:
+
+- Web SSR is the stricter path and should treat theme-sensitive SSR reads as lower-authority
+- Admin SSR can provide a stronger server/client theme match guarantee
+
+This is exactly why flavor selection is not only a packaging choice. It can also define the supported capability boundary for runtime-sensitive behavior.
+
+A second practical rule is that flavor alone is not the full story. Contributors should combine:
+
+- flavor and `SSR_COOKIE` capability
+- edition marker
+- active UI-library adapter
+
+before assuming how SSR theme state is handed off and finalized.
+
+For the theme-side contract and edition-aware checklist, see [Theme Guide](/frontend/theme-guide). For the env-side explanation of `SSR_COOKIE`, see [SSR Environment Variables](/frontend/ssr-env).
+
 ## Scripts and runtime variants
 
 Frontend scripts map directly onto the same runtime dimensions.

package/cabloy-docs/frontend/foundation.md

@@ -28,7 +28,7 @@ That flexibility matters directly for Cabloy’s edition model:
 
 - **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-oriented frontend modules, workflows, and SSR site baselines
+- **Cabloy Start UI layer**: the private commercial edition aligns with Vuetify-oriented frontend workflows and may use different module composition and SSR site baselines
 
 So docs and skills must separate shared Zova principles from edition-specific UI assumptions.
 

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/quickstart.md

@@ -6,14 +6,14 @@ This guide explains the fastest way to start a Cabloy fullstack project.
 
 Before creating a new Cabloy project, make sure your environment has:
 
-| Name         | Version     |
-| ------------ | ----------- |
-| `pnpm`       | `>=10.19.0` |
-| `Node.js`    | `>=24.4.0`  |
-| `Redis`      | `>=7.2.6`   |
-| `SQLite3`    | `Built-in`  |
-| `MySQL`      | `>=8`       |
-| `PostgreSQL` | `>=16`      |
+| Name         | Version    |
+| ------------ | ---------- |
+| `pnpm`       | `>=11.5.2` |
+| `Node.js`    | `>=24.4.0` |
+| `Redis`      | `>=7.2.6`  |
+| `SQLite3`    | `Built-in` |
+| `MySQL`      | `>=8`      |
+| `PostgreSQL` | `>=16`     |
 
 - `Redis`: powers queue, schedule, startup, broadcast, caching, two-layer cache, and redlock
 - `SQLite3`: if you use `better-sqlite3`, set up `node-gyp` before installing dependencies

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/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: true