cabloy 5.1.52 → 5.1.53

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

@@ -156,6 +156,16 @@ Check whether the feature needs:
 - SSR or route-path verification
 - edition-specific flavor, SSR site baseline, and project-asset verification
 
+### SSR theme review reminder
+
+If the frontend change is SSR theme-sensitive, apply this short review before finishing:
+
+- detect the active edition marker and UI library before assuming SSR theme behavior
+- do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff
+- in Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth
+- keep theme-finalization logic inside the active theme handler or client boot path instead of duplicating it in page or component code
+- verify both server handoff and client hydration behavior for the active adapter
+
 ### Optional backend-contract reminder
 
 Stay frontend-first, but if the frontend task clearly depends on backend contract output, add a reminder such as:

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 5.1.53
+
+### Features
+
+- Update application functionality across core feature areas.
+- Update configuration behavior and related integration points.
+- Update theme configuration and controller handling.
+
+### Improvements
+
+- Remove the generated `$useLocale` helper.
+- Refresh project configuration files and internal implementation details.
+
+### Breaking Changes
+
+- Rename the SSR cookie-disabled server flag and update related documentation.
+
 ## 5.1.52
 
 ### Features

package/CLAUDE.md

@@ -44,6 +44,9 @@ Before inventing a custom implementation path:
 - Prefer CLI-backed workflows over manual scaffolding whenever Vona or Zova already provides a generator, refactor, metadata, or verification command.
 - Treat legacy docs as input material, not as unquestioned truth. When docs conflict with source code, prefer current source code.
 - For frontend work, assume Cabloy Basic and Cabloy Start share a frontend engineering layer but may diverge in UI layer, frontend flavors, suite/module availability, SSR site baselines, project assets, and generated outputs.
+- For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
+- In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.
+- Do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff. Verify the active theme handler and client hydration path before changing SSR theme behavior.
 - Reuse existing repo terminology: Cabloy, Vona, Zova, suite, module, bean, SSR, SPA, Web, Admin.
 - For backend base-class placement, use the A / B1 / B2 rule from `cabloy-docs/ai/class-placement-rule.md`.
 - Pure helper bases belong in `src/lib`; subclass-only bases should be evaluated case by case and often belong in `src/lib`.

package/cabloy-docs/.vitepress/config.mjs

@@ -31,12 +31,60 @@ const aiItems = [
   { text: 'Verification', link: '/ai/verification' },
 ];
 
-const referenceItems = [
-  { text: 'Repo Scripts', link: '/reference/repo-scripts' },
-  { text: 'CLI Reference', link: '/reference/cli-reference' },
-  { text: 'Package Map', link: '/reference/package-map' },
-  { text: 'Backend Directory Structure', link: '/reference/backend-directory-structure' },
-  { text: 'Glossary', link: '/reference/glossary' },
+const fullstackGroups = [
+  {
+    text: 'Fullstack / Getting Started',
+    items: [
+      { text: 'Introduction', link: '/fullstack/introduction' },
+      { text: 'Quickstart', link: '/fullstack/quickstart' },
+    ],
+  },
+  {
+    text: 'Tooling & Workflow',
+    items: [
+      { text: 'CLI', link: '/fullstack/cli' },
+      { text: 'VS Code Extensions', link: '/fullstack/vscode-extensions' },
+    ],
+  },
+  {
+    text: 'Architecture & Integration',
+    items: [
+      {
+        text: 'Comparison with Other Frameworks',
+        link: '/fullstack/comparison-with-other-frameworks',
+      },
+      { text: 'Vona + Zova Integration', link: '/fullstack/vona-zova-integration' },
+      { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
+      {
+        text: 'Frontend Metadata Back to Backend',
+        link: '/fullstack/frontend-metadata-to-backend',
+      },
+      {
+        text: 'Edition Collaboration Differences',
+        link: '/fullstack/edition-collaboration-differences',
+      },
+    ],
+  },
+];
+
+const referenceGroups = [
+  {
+    text: 'Reference / Workflow Entry',
+    items: [
+      { text: 'Introduction', link: '/reference/introduction' },
+      { text: 'Repo Scripts', link: '/reference/repo-scripts' },
+      { text: 'CLI Reference', link: '/reference/cli-reference' },
+    ],
+  },
+  {
+    text: 'Structure & Lookup',
+    items: [
+      { text: 'Package Map', link: '/reference/package-map' },
+      { text: 'Backend Directory Structure', link: '/reference/backend-directory-structure' },
+      { text: 'Frontend Directory Structure', link: '/reference/frontend-directory-structure' },
+      { text: 'Glossary', link: '/reference/glossary' },
+    ],
+  },
 ];
 
 const GA_MEASUREMENT_ID = process.env.GA_MEASUREMENT_ID;
@@ -74,46 +122,27 @@ export default defineConfig({
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Fullstack', link: '/fullstack/introduction', activeMatch: '^/fullstack/' },
-      { text: 'Backend', link: '/backend/introduction', activeMatch: '^/backend/' },
-      { text: 'Frontend', link: '/frontend/introduction', activeMatch: '^/frontend/' },
+      { text: 'Backend (Vona)', link: '/backend/introduction', activeMatch: '^/backend/' },
+      { text: 'Frontend (Zova)', link: '/frontend/introduction', activeMatch: '^/frontend/' },
       { text: 'Editions', link: '/editions/overview', activeMatch: '^/editions/' },
       { text: 'AI Development', link: '/ai/introduction', activeMatch: '^/ai/' },
-      { text: 'Reference', link: '/reference/repo-scripts', activeMatch: '^/reference/' },
+      { text: 'Reference', link: '/reference/introduction', activeMatch: '^/reference/' },
     ],
     sidebar: {
-      '/fullstack/': [
-        {
-          text: 'Fullstack',
-          items: [
-            { text: 'Introduction', link: '/fullstack/introduction' },
-            {
-              text: 'Comparison with Other Frameworks',
-              link: '/fullstack/comparison-with-other-frameworks',
-            },
-            { text: 'Quickstart', link: '/fullstack/quickstart' },
-            { text: 'CLI', link: '/fullstack/cli' },
-            { text: 'VS Code Extensions', link: '/fullstack/vscode-extensions' },
-            { text: 'Vona + Zova Integration', link: '/fullstack/vona-zova-integration' },
-            { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
-            {
-              text: 'Frontend Metadata Back to Backend',
-              link: '/fullstack/frontend-metadata-to-backend',
-            },
-            {
-              text: 'Edition Collaboration Differences',
-              link: '/fullstack/edition-collaboration-differences',
-            },
-          ],
-        },
-      ],
+      '/fullstack/': fullstackGroups,
       '/backend/': [
         {
-          text: 'Backend (Vona)',
+          text: 'Backend (Vona) / Getting Started',
           items: [
             { text: 'Introduction', link: '/backend/introduction' },
             { text: 'Foundation', link: '/backend/foundation' },
             { text: 'Backend Essentials', link: '/backend/backend-essentials' },
             { text: 'Quickstart', link: '/backend/quickstart' },
+          ],
+        },
+        {
+          text: 'Tooling & Runtime',
+          items: [
             { text: 'CLI', link: '/backend/cli' },
             { text: 'Scripts', link: '/backend/scripts' },
             { text: 'Runtime and Flavors', link: '/backend/runtime-and-flavors' },
@@ -123,18 +152,34 @@ export default defineConfig({
               text: 'Multi-Instance and Instance Resolution',
               link: '/backend/multi-instance-and-instance-resolution',
             },
+          ],
+        },
+        {
+          text: 'Security & Access',
+          items: [
             { text: 'Auth Guide', link: '/backend/auth-guide' },
             { text: 'Captcha Guide', link: '/backend/captcha-guide' },
             { text: 'User Access Guide', link: '/backend/user-access-guide' },
+            { text: 'JWT Guide', link: '/backend/jwt-guide' },
+            { text: 'Validation Guide', link: '/backend/validation-guide' },
+          ],
+        },
+        {
+          text: 'Application Basics',
+          items: [
             { text: 'Menu Guide', link: '/backend/menu-guide' },
             { text: 'I18n Guide', link: '/backend/i18n-guide' },
             { text: 'Error Guide', link: '/backend/error-guide' },
-            { text: 'JWT Guide', link: '/backend/jwt-guide' },
             { text: 'Event Guide', link: '/backend/event-guide' },
             { text: 'Logger Guide', link: '/backend/logger-guide' },
             { text: 'Upload Guide', link: '/backend/upload-guide' },
             { text: 'Mail Guide', link: '/backend/mail-guide' },
             { text: 'Serialization Guide', link: '/backend/serialization-guide' },
+          ],
+        },
+        {
+          text: 'Core Programming Model',
+          items: [
             { text: 'AOP Overview', link: '/backend/aop-overview' },
             { text: 'Controller Guide', link: '/backend/controller-guide' },
             { text: 'Controller AOP Guide', link: '/backend/controller-aop-guide' },
@@ -144,10 +189,14 @@ export default defineConfig({
             { text: 'Model Guide', link: '/backend/model-guide' },
             { text: 'Entity Guide', link: '/backend/entity-guide' },
             { text: 'DTO Guide', link: '/backend/dto-guide' },
+          ],
+        },
+        {
+          text: 'Data & CRUD',
+          items: [
             { text: 'CRUD Workflow', link: '/backend/crud-workflow' },
             { text: 'Migration and Changes', link: '/backend/migration-and-changes' },
             { text: 'Field Indexes', link: '/backend/field-indexes' },
-            { text: 'Unit Testing', link: '/backend/unit-testing' },
             { text: 'ORM Guide', link: '/backend/orm-guide' },
             { text: 'ORM Configuration Guide', link: '/backend/orm-configuration-guide' },
             { text: 'ORM Select Guide', link: '/backend/orm-select-guide' },
@@ -155,6 +204,11 @@ export default defineConfig({
             { text: 'ORM Aggregate and Group Guide', link: '/backend/orm-aggregate-group-guide' },
             { text: 'Relations Guide', link: '/backend/relations-guide' },
             { text: 'Transaction Guide', link: '/backend/transaction-guide' },
+          ],
+        },
+        {
+          text: 'Infrastructure & Distributed',
+          items: [
             { text: 'Cache Guide', link: '/backend/cache-guide' },
             {
               text: 'Multi-Database and Datasource Guide',
@@ -169,55 +223,100 @@ export default defineConfig({
             { text: 'Worker Guide', link: '/backend/worker-guide' },
             { text: 'Broadcast Guide', link: '/backend/broadcast-guide' },
             { text: 'Redlock Guide', link: '/backend/redlock-guide' },
-            { text: 'Validation Guide', link: '/backend/validation-guide' },
+          ],
+        },
+        {
+          text: 'API & Testing',
+          items: [
             { text: 'OpenAPI Guide', link: '/backend/openapi-guide' },
             { text: 'DTO Infer and Generation', link: '/backend/dto-infer-generation' },
+            { text: 'Unit Testing', link: '/backend/unit-testing' },
           ],
         },
       ],
       '/frontend/': [
         {
-          text: 'Frontend (Zova)',
+          text: 'Frontend (Zova) / Getting Started',
           items: [
             { text: 'Introduction', link: '/frontend/introduction' },
             { text: 'Quickstart', link: '/frontend/quickstart' },
             { text: 'Foundation', link: '/frontend/foundation' },
+          ],
+        },
+        {
+          text: 'Architecture & Modules',
+          items: [
             { text: 'IoC and Beans', link: '/frontend/ioc-and-beans' },
             { text: 'Modules and Suites', link: '/frontend/modules-and-suites' },
             { text: 'Module Scope', link: '/frontend/module-scope' },
+            { text: 'Design Principles', link: '/frontend/design-principles' },
+          ],
+        },
+        {
+          text: 'Environment & Startup',
+          items: [
             { text: 'Environment and Config Guide', link: '/frontend/environment-config-guide' },
             { text: 'App Startup Guide', link: '/frontend/app-startup-guide' },
             { text: 'System Startup Guide', link: '/frontend/system-startup-guide' },
+          ],
+        },
+        {
+          text: 'Tooling',
+          items: [
+            { text: 'CLI', link: '/frontend/cli' },
+            { text: 'Scripts', link: '/frontend/scripts' },
+            { text: 'Mock Guide', link: '/frontend/mock-guide' },
+          ],
+        },
+        {
+          text: 'Pages & Routing',
+          items: [
             { text: 'Page Guide', link: '/frontend/page-guide' },
             { text: 'Page Query Guide', link: '/frontend/page-query-guide' },
             { text: 'Page Params Guide', link: '/frontend/page-params-guide' },
-            { text: 'Page Route Guide', link: '/frontend/page-route-guide' },
             { text: 'Zod Guide', link: '/frontend/zod-guide' },
+            { text: 'Page Route Guide', link: '/frontend/page-route-guide' },
             { text: 'Route Alias Guide', link: '/frontend/route-alias-guide' },
             { text: 'Navigation Guards Guide', link: '/frontend/navigation-guards-guide' },
+          ],
+        },
+        {
+          text: 'Components & UI',
+          items: [
             { text: 'Component Guide', link: '/frontend/component-guide' },
             { text: 'Component Props Guide', link: '/frontend/component-props-guide' },
             { text: 'Component v-model Guide', link: '/frontend/component-v-model-guide' },
             { text: 'Generic Component Guide', link: '/frontend/generic-component-guide' },
-            { text: 'CLI', link: '/frontend/cli' },
-            { text: 'Scripts', link: '/frontend/scripts' },
-            { text: 'Mock Guide', link: '/frontend/mock-guide' },
             { text: 'CSS-in-JS Guide', link: '/frontend/css-in-js-guide' },
             { text: 'Theme Guide', link: '/frontend/theme-guide' },
             { text: 'Icon Engine Guide', link: '/frontend/icon-engine-guide' },
+          ],
+        },
+        {
+          text: 'Data & State',
+          items: [
             { text: 'Server Data', link: '/frontend/server-data' },
             { text: 'API Guide', link: '/frontend/api-guide' },
             { text: 'Model Architecture', link: '/frontend/model-architecture' },
             { text: 'Model State Guide', link: '/frontend/model-state-guide' },
+          ],
+        },
+        {
+          text: 'API Contract & SDK',
+          items: [
             { text: 'OpenAPI SDK Guide', link: '/frontend/openapi-sdk-guide' },
             { text: 'API Schema Guide', link: '/frontend/api-schema-guide' },
             { text: 'SDK Guide', link: '/frontend/sdk-guide' },
+          ],
+        },
+        {
+          text: 'SSR',
+          items: [
             { text: 'SSR Overview', link: '/frontend/ssr-overview' },
             { text: 'SSR Init Data', link: '/frontend/ssr-init-data' },
             { text: 'SSR ClientOnly', link: '/frontend/ssr-client-only' },
             { text: 'SSR SEO Meta', link: '/frontend/ssr-seo-meta' },
             { text: 'SSR Env', link: '/frontend/ssr-env' },
-            { text: 'Design Principles', link: '/frontend/design-principles' },
           ],
         },
       ],
@@ -233,12 +332,7 @@ export default defineConfig({
           items: aiItems,
         },
       ],
-      '/reference/': [
-        {
-          text: 'Reference',
-          items: referenceItems,
-        },
-      ],
+      '/reference/': referenceGroups,
     },
     socialLinks: [{ icon: 'github', link: 'https://github.com/cabloy/cabloy' }],
     search: {

package/cabloy-docs/ai/introduction.md

@@ -23,6 +23,15 @@ The goal is to make AI **reuse the repo’s existing conventions directly**, esp
 - internal architecture notes
 - shared public documentation
 
+## How to approach AI work
+
+For contributor and automation workflows in this repository, prefer this order:
+
+1. inspect the active edition and repo markers before making UI-sensitive or workflow-sensitive assumptions
+2. inspect root scripts, Vona CLI, and Zova CLI before inventing manual scaffolding or custom workflow steps
+3. use public docs for durable user-facing guidance and `.docs-internal/` for maintainer rationale
+4. encode repeatable behavior in Claude rules, commands, or skills instead of relying on unstated habits
+
 ## The knowledge layers
 
 ### Public docs
@@ -43,6 +52,41 @@ Use root `CLAUDE.md` and `.claude/commands/` for concise operational behavior an
 
 Use `.claude/skills/` for procedural workflows that benefit from reusable instructions, bundled references, or future deterministic scripts.
 
+## AI reading paths
+
+Use this page as the main AI-development hub, then choose the path that matches your task.
+
+### Repo workflow path
+
+Start here when the task is about choosing the right repo surface, docs location, or automation boundary:
+
+- [Repo Guidance](/ai/repo-guidance)
+- [Docs / Skills Mapping](/ai/docs-skills-rules-mapping)
+- [CLI to Skill Map](/ai/cli-to-skill-map)
+- [Skills](/ai/skills)
+- [Rules and Config](/ai/rules-and-config)
+
+### Framework implementation path
+
+Use this path when the task is about implementing or reviewing Cabloy code with repo-aware rules:
+
+- [Class Placement Rule](/ai/class-placement-rule)
+- [Global Bean Lookup](/ai/global-bean-lookup)
+- [Playbook: Backend Module](/ai/playbook-backend-module)
+- [Playbook: Frontend Page](/ai/playbook-frontend-page)
+- [Playbook: Contract Regeneration](/ai/playbook-contract-regeneration)
+- [Playbook: Metadata Refresh](/ai/playbook-metadata-refresh)
+
+### Verification and roadmap path
+
+Use this path when the task is about consistency checks, verification, or future workflow planning:
+
+- [Edition Detection](/ai/edition-detection)
+- [Edition Consistency Checklist](/ai/edition-consistency-checklist)
+- [Verification](/ai/verification)
+- [Future Skill Roadmap](/ai/future-skill-roadmap)
+- [CLI for Agents](/ai/cli-for-agents)
+
 ## Recommended AI lookup rules
 
 For backend shorthand lookup, prefer these surfaces in order:

package/cabloy-docs/backend/quickstart.md

@@ -87,7 +87,7 @@ Legacy Vona docs described creating projects from templates such as `cabloy-basi
 That history still matters, because it explains why the Cabloy ecosystem now supports two editions:
 
 - **Cabloy Basic**: the public framework/reference edition, including the project route created by `npm create cabloy`, with a shared frontend engineering layer and a DaisyUI + Tailwind CSS oriented UI layer in the current public examples
-- **Cabloy Start**: the private commercial edition, accessed by cloning the licensed private repository source, with Vuetify-oriented frontend modules plus Start-specific SSR site baselines and project assets
+- **Cabloy Start**: the private commercial edition, accessed by cloning the licensed private repository source, with a Vuetify-oriented UI layer plus edition-specific SSR site baselines and project assets
 
 In the current monorepo docs, do not treat these as just template names. Treat them as edition boundaries that affect frontend integration, scripts, UI assumptions, and examples.
 

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.