cabloy 5.1.51 → 5.1.53

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

@@ -0,0 +1,84 @@
+# Choosing Between Cabloy Basic and Cabloy Start
+
+This guide helps you choose the right Cabloy edition before you start a new project, adopt a frontend UI strategy, or prepare AI workflow guidance.
+
+## Short answer
+
+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 Start-oriented SSR sites, project assets, and a Vuetify-aligned UI layer.
+
+## What stays the same in both editions
+
+Both editions share the same Cabloy fullstack core:
+
+- **Vona** as the backend framework
+- **Zova** as the frontend framework
+- suite-based modular architecture
+- CLI-first workflows
+- shared frontend engineering direction built around Vue, Vite, Quasar tooling, and related libraries
+
+So the decision is not about choosing two unrelated products. It is about choosing the edition baseline that fits your delivery goals best.
+
+## Choose Cabloy Basic when
+
+Cabloy Basic is usually the better fit when you want:
+
+- the public framework/reference edition
+- the default project route created by `npm create cabloy`
+- open-source visibility and community-friendly workflows
+- public examples and docs that match your repo directly
+- a UI layer aligned with DaisyUI + Tailwind CSS
+- a faster path for small-to-medium system development
+
+## Choose Cabloy Start when
+
+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 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
+
+## The most practical decision factors
+
+### Project creation path
+
+- **Cabloy Basic**: create the project with `npm create cabloy`
+- **Cabloy Start**: purchase access, clone the licensed private repository source directly, then run `npm run init`
+
+### UI strategy
+
+- **Cabloy Basic**: DaisyUI + Tailwind CSS
+- **Cabloy Start**: Vuetify
+
+### Repo and asset model
+
+- **Cabloy Basic**: public repository and public reference materials
+- **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, SSR site baselines, and UI assumptions
+
+This is why edition detection matters so much for AI vibe coding.
+
+## A simple recommendation rule
+
+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-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
+
+- [Editions Overview](/editions/overview)
+- [Cabloy Basic](/editions/cabloy-basic)
+- [Cabloy Start](/editions/cabloy-start)
+- [Edition Detection](/editions/detection)
+- [Fullstack Quickstart](/fullstack/quickstart)

package/cabloy-docs/editions/overview.md

@@ -1,44 +1,138 @@
 # Editions Overview
 
-Cabloy currently needs to support two related but distinct repositories:
+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**
 - **Cabloy Start**
 
-They share the same core architectural direction, but they are not interchangeable.
+They share one Cabloy fullstack architecture, but they are distributed, composed, and optimized differently.
+
+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)
 
-## Shared core
+### Detection and workflow path
 
-Both editions use the Cabloy fullstack model built around:
+Use this path when the task is about repo-aware automation, flavor assumptions, or edition-safe workflow choices:
 
-- Vona as the backend framework
-- Zova as the frontend framework
+- [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:
+
+- **Vona** as the backend framework
+- **Zova** as the frontend framework
+- suite-based modules across the stack
 - root-level `npm run vona` and `npm run zova` entrypoints
 - CLI-backed workflows for generation, refactoring, metadata, and verification
 
-## Why the editions differ
+This means the editions are related fullstack baselines, not unrelated products.
+
+## What "Basic" means
+
+Cabloy Basic is the public framework/reference edition.
+
+- this public repository is marked with `__CABLOY_BASIC__`
+- projects created with `npm create cabloy` follow the Cabloy Basic route
+- the public docs and examples in this repo use Cabloy Basic as the default baseline
+
+Cabloy Basic is the open-source community edition and is optimized for public reference, learning, and fast development workflows.
+
+## What "Start" means
+
+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 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.
+
+## Architecture layering
+
+Most of the frontend engineering layer is shared, while the edition-specific UI layer differs.
+
+### Shared frontend engineering layer
+
+Across editions, Zova uses the same frontend framework direction and engineering tooling, including:
+
+- Vue
+- Vite
+- Quasar tooling such as `quasar dev` and `quasar build`
+- TanStack libraries where applicable
+
+Here, Quasar is used for engineering tooling rather than as the edition UI component library.
+
+### Edition-specific UI layer
+
+The UI component strategy diverges by edition:
+
+- **Cabloy Basic**: DaisyUI + Tailwind CSS
+- **Cabloy Start**: Vuetify
+
+This difference affects not only UI code, but also module composition, frontend flavor assumptions, SSR site baselines, examples, and AI workflow guidance.
+
+## Edition-specific assets
+
+The editions intentionally diverge in several surfaces:
+
+- UI layer assumptions
+- frontend flavor names
+- suite and module composition
+- admin/web SSR site baselines
+- 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** uses public flavors such as `cabloyStartAdmin` and `cabloyStartWeb`
 
-The editions exist to support different product and distribution goals.
+## Why the repo markers matter
 
-### Cabloy Basic
+The edition markers are not just labels for humans.
 
-- public repository
-- baseline fullstack reference implementation
-- current default examples in this public monorepo
+`__CABLOY_BASIC__` and `__CABLOY_START__` help tools, docs, and AI workflows choose the correct assumptions for:
 
-### Cabloy Start
+- UI component usage
+- flavor selection
+- module availability
+- SSR site expectations
+- rules, skills, and verification guidance
 
-- sibling private repository
-- created from `npm create cabloy`
-- uses a different UI strategy centered on Vuetify
-- contains different Vona/Zova modules and value-add project structure
+This is why the two editions should be identified explicitly instead of being treated as interchangeable.
 
 ## Documentation rule
 
-Write shared explanations once. Only split or annotate when a workflow changes because of:
+Write shared explanations once. Split or annotate only when a workflow changes because of:
 
 - UI library assumptions
 - frontend flavor names
 - different modules or assets
-- private-value product boundaries
-- edition-specific scripts or generated outputs
+- distribution and authorization model
+- edition-specific scripts, generated outputs, or AI workflow guidance

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

@@ -26,8 +26,9 @@ Zova is not tied to one UI library.
 
 That flexibility matters directly for Cabloy’s edition model:
 
-- **Cabloy Basic** currently aligns with DaisyUI + TailwindCSS oriented examples
-- **Cabloy Start** aligns with Vuetify-oriented frontend modules and workflows
+- **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 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

@@ -1,8 +1,8 @@
 # Frontend (Zova)
 
-This page is the frontend hub for contributors who are documenting, designing, or extending frontend work in the Cabloy repository.
+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 the Cabloy fullstack architecture.
+Zova is the frontend half of Cabloy’s one-framework-system fullstack architecture.
 
 ## What Zova is responsible for
 
@@ -22,11 +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.
 
-- **Cabloy Basic** uses a frontend stack centered on DaisyUI and TailwindCSS in the current docs and examples.
-- **Cabloy Start** uses Vuetify and ships different frontend modules as a private value-add project.
+- **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 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

@@ -28,8 +28,9 @@ When working in this framework repository, the active edition is **Cabloy Basic*
 That matters because edition choice affects:
 
 - frontend flavor names
-- UI-library assumptions
-- available modules and layouts
+- UI-layer assumptions
+- available modules, layouts, and SSR site baselines
+- project assets and examples
 - which examples in the docs match the current repo directly
 
 Read together with:
@@ -72,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

@@ -66,12 +66,12 @@ cd zova && npm run build:rest:cabloyBasicAdmin
 
 ## Cabloy Start
 
-The sibling `cabloy-start` repository uses Start-specific flavors such as:
+The sibling `cabloy-start` repository is the private commercial edition and uses Start-specific flavors such as:
 
 - `cabloyStartAdmin`
 - `cabloyStartWeb`
 
-Those commands are not driven by the current Basic repo root wrappers, so verify the Start repo’s `package.json` 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.