cabloy 5.1.51 → 5.1.53

package/.claude/skills/cabloy-contract-loop/SKILL.md

@@ -139,7 +139,7 @@ Typical examples in Cabloy Basic include:
 - `cd zova && npm run build:rest:cabloyBasicAdmin`
 - `cd zova && npm run build:rest:cabloyBasicWeb`
 
-For Cabloy Start, verify the exact Start-specific flavor names and paths in the Start repo.
+For Cabloy Start, verify the exact Start-specific flavor names, paths, SSR site baselines, and project assets in the licensed Start repo.
 
 ### Path C: Downstream frontend alignment
 

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

@@ -154,7 +154,17 @@ Check whether the feature needs:
 - build
 - metadata regeneration verification
 - SSR or route-path verification
-- edition-specific flavor 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
 

package/.claude/skills/cabloy-workflow/SKILL.md

@@ -28,7 +28,7 @@ Interpretation:
 - `__CABLOY_START__` present → this is Cabloy Start
 - neither present → inspect the repo scripts and ask the user before making a strong edition-specific assumption
 
-This matters most for frontend work, UI-library assumptions, flavor names, and edition-specific modules.
+This matters most for frontend work, UI-layer assumptions, flavor names, suite/module availability, SSR site baselines, project assets, and edition-specific AI guidance.
 
 ## Step 2: Identify the task layer
 
@@ -61,7 +61,7 @@ Use the frontend path when the task is about:
 
 - page, component, mock, bean
 - SSR, Web, Admin, SPA
-- UI-library-sensitive work
+- UI-layer-sensitive work
 - OpenAPI SDK generation
 - frontend refactors such as page params, page query, component props, or model helpers
 
@@ -236,19 +236,23 @@ When the task is frontend-sensitive or examples differ between editions, branch
 
 Bias toward:
 
+- the public framework/reference edition
 - current public monorepo source
+- the default `npm create cabloy` project route
 - public docs examples
 - the Basic repo marker
-- current Basic frontend flavors and module layout
+- current Basic frontend flavors, module layout, and DaisyUI + Tailwind CSS UI assumptions
 
 ### Cabloy Start
 
 Bias toward:
 
+- the private commercial edition
 - the Start repo marker
+- the licensed private repository source
 - Vuetify-sensitive examples
 - Start-specific frontend flavor names
-- Start-specific modules and private-value repo structure
+- Start-specific suites/modules, SSR site baselines, project assets, and licensed private-repo structure
 
 Do not silently reuse Basic examples when Start-specific assumptions matter.
 

package/.claude/skills/cabloy-workflow/references/edition-detection.md

@@ -13,10 +13,11 @@ They prevent the most common category error in Cabloy AI work: assuming Cabloy B
 
 That assumption is especially dangerous for:
 
-- UI-library-sensitive examples
+- UI-layer-sensitive examples
 - frontend flavor names
 - page/component workflows
-- module availability
+- suite/module availability
+- SSR site baselines and project assets
 - docs and skills that try to support both repos
 
 ## Secondary checks

package/.github/workflows/docs-pages.yml

@@ -34,6 +34,8 @@ jobs:
       - name: install docs dependencies
         run: pnpm --dir cabloy-docs install --frozen-lockfile
       - name: build docs
+        env:
+          GA_MEASUREMENT_ID: ${{ vars.GA_MEASUREMENT_ID }}
         run: pnpm --dir cabloy-docs docs:build
       - name: setup pages
         uses: actions/configure-pages@v5

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # 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
+
+- Add SSR memory diagnostic endpoints.
+- Expand framework capabilities across SSR, controller, module, component, utility, and runtime integration areas.
+- Add virtual decorator guidance to the AI documentation.
+
+### Bug Fixes
+
+- Correct runtime home paths in the documentation.
+- Fix homepage scope badge layout in the documentation.
+
+### Improvements
+
+- Refine SSR internals and metadata handling.
+- Polish controller and page base implementation details.
+- Update monkey patching and runtime support code.
+- Improve package metadata and lockfile consistency.
+- Pass the GA measurement ID into the docs build pipeline.
+- Add GA4 tracking support for the documentation site.
+- Improve CLI, index, glossary, skill, and README documentation.
+- Add and refine the Cabloy framework comparison and fullstack introduction content.
+- Polish branding, wording, and AI vibe coding terminology across the docs.
+
 ## 5.1.51
 
 ### Features

package/CLAUDE.md

@@ -2,15 +2,15 @@
 
 ## Repository identity
 
-This repository is **Cabloy Basic**, identified by the root marker file:
+This repository is **Cabloy Basic**, the public framework/reference edition, identified by the root marker file:
 
 - `__CABLOY_BASIC__`
 
-A sibling repository named `cabloy-start` is a separate source repository and is identified by:
+A sibling repository named `cabloy-start` is the private commercial edition, delivered as a licensed separate source repository and identified by:
 
 - `__CABLOY_START__`
 
-Always detect the active edition before making UI-sensitive assumptions, choosing frontend examples, or recommending module-specific workflows.
+Always detect the active edition before making UI-sensitive assumptions, choosing frontend examples, recommending module-specific workflows, or assuming the project creation path.
 
 ## Monorepo layout
 
@@ -43,7 +43,10 @@ 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 may diverge in UI library, frontend flavors, module availability, and generated outputs.
+- 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/README.md

@@ -3,16 +3,16 @@
 [![License MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/cabloy/cabloy/blob/main/LICENSE)
 [![npm version](https://img.shields.io/npm/v/cabloy.svg?style=flat-square&label=cabloy)](https://www.npmjs.com/package/cabloy)
 [![npm downloads](https://img.shields.io/npm/dm/cabloy?color=orange&label=downloads)](https://www.npmjs.com/package/cabloy)
-[![Docs](https://img.shields.io/badge/docs-cabloy-4f46e5.svg?style=flat-square)](https://github.com/cabloy/cabloy/tree/main/cabloy-docs)
+[![Docs](https://img.shields.io/badge/docs-cabloy-4f46e5.svg?style=flat-square)](https://docs.cabloy.com)
 [![Demo](https://img.shields.io/badge/demo-cabloy.com-059669.svg?style=flat-square)](https://cabloy.com)
 
 Cabloy is a Node.js fullstack framework for AI vibe coding.
 
-Use one framework system instead of stitching together separate backend and frontend stacks.
+Use one fullstack framework instead of stitching together separate backend and frontend stacks.
 
-With **Vona** on the backend, **Zova** on the frontend, and CLI-first workflows across the stack, Cabloy turns common scaffolding and verification into explicit commands so AI coding can stay more accurate, use fewer tokens, and move faster.
+With Vona, Zova, suite-based modules, and CLI-first workflows, Cabloy turns common scaffolding, metadata, refactors, and verification into explicit commands for faster, more accurate AI vibe coding.
 
-[Documentation](https://github.com/cabloy/cabloy/tree/main/cabloy-docs) · [npm](https://www.npmjs.com/package/cabloy) · [Web Demo](https://cabloy.com) · [Admin Demo](https://cabloy.com/admin) · [GitHub](https://github.com/cabloy/cabloy)
+[Documentation](https://docs.cabloy.com) · [npm](https://www.npmjs.com/package/cabloy) · [Web Demo](https://cabloy.com) · [Admin Demo](https://cabloy.com/admin) · [GitHub](https://github.com/cabloy/cabloy)
 
 ## Get Started
 
@@ -38,16 +38,19 @@ Create a new Cabloy project:
 npm create cabloy
 ```
 
-The generated project already includes `CLAUDE.md` and the `.claude/` workspace assets. Open this project in Claude Code and start coding immediately with project-specific guidance.
+The generated project already includes `CLAUDE.md` and the `.claude/` workspace assets. This path creates a Cabloy Basic project baseline. Open this project in Claude Code and start coding immediately with project-specific guidance.
+
+For **Cabloy Start**, purchase access to the licensed private repository, clone `git@github.com:cabloy/cabloy-start.git`, and run `npm run init`. For the complete Start onboarding flow, read the [Cabloy Start](https://docs.cabloy.com/editions/cabloy-start) page.
 
 Then continue with the framework docs:
 
-- [Fullstack Quickstart](https://github.com/cabloy/cabloy/blob/main/cabloy-docs/fullstack/quickstart.md)
-- [Documentation](https://github.com/cabloy/cabloy/tree/main/cabloy-docs)
-- [Fullstack Introduction](https://github.com/cabloy/cabloy/blob/main/cabloy-docs/fullstack/introduction.md)
-- [Backend Introduction](https://github.com/cabloy/cabloy/blob/main/cabloy-docs/backend/introduction.md)
-- [Frontend Introduction](https://github.com/cabloy/cabloy/blob/main/cabloy-docs/frontend/introduction.md)
-- [Editions Overview](https://github.com/cabloy/cabloy/blob/main/cabloy-docs/editions/overview.md)
+- [Fullstack Quickstart](https://docs.cabloy.com/fullstack/quickstart)
+- [Documentation](https://docs.cabloy.com)
+- [Fullstack Introduction](https://docs.cabloy.com/fullstack/introduction)
+- [Backend Introduction](https://docs.cabloy.com/backend/introduction)
+- [Frontend Introduction](https://docs.cabloy.com/frontend/introduction)
+- [Editions Overview](https://docs.cabloy.com/editions/overview)
+- [Choosing Between Cabloy Basic and Cabloy Start](https://docs.cabloy.com/editions/choosing-between-basic-and-start)
 
 To upgrade an existing Cabloy project:
 
@@ -57,11 +60,12 @@ npm run upgrade
 
 ## Highlights
 
-- **One framework system** — build backend and frontend in one Node.js fullstack architecture
-- **Vona + Zova** — use aligned backend and frontend frameworks instead of stitching together separate stacks
-- **Multiple delivery modes** — support SSR, SPA, Web, and Admin applications with shared conventions
-- **CLI-first workflows for AI coding** — turn scaffolding, metadata, refactors, and verification into explicit commands so AI can stay more accurate, use fewer tokens, and move faster
-- **Monorepo-native development** — keep framework source, docs, and tooling aligned in one repository model
+- **One framework system** — build backend and frontend in one fullstack architecture
+- **Vona + Zova** — use aligned backend and frontend frameworks for code sharing, workflow reuse, and cross-stack consistency
+- **Suite-based modular system** — organize capabilities as suites and modules so services, features, metadata, and tooling evolve in composable units
+- **Multiple delivery modes** — deliver SSR, SPA, Web, and Admin applications with shared conventions across the stack
+- **CLI-first workflows for AI vibe coding** — turn common scaffolding, metadata, refactors, and verification into explicit commands for faster, more accurate AI vibe coding
+- **Monorepo-native development** — keep framework source, docs, and tooling aligned in one monorepo workflow
 
 ## Technology Stack
 
@@ -92,7 +96,16 @@ npm run upgrade
 | TanStack Form  | `^1.32.0`   |
 | TanStack Table | `^8.21.3`   |
 
-### Edition-specific UI Stack
+### Shared Frontend Engineering Layer
+
+- Vue
+- Vite
+- Quasar tooling such as `quasar dev` and `quasar build`
+- TanStack libraries where applicable
+
+Quasar is used here for engineering tooling rather than as the edition UI component library.
+
+### Edition-specific UI Layer
 
 - **Cabloy Basic**: DaisyUI + Tailwind CSS
 - **Cabloy Start**: Vuetify
@@ -113,14 +126,16 @@ npm run build
 
 For more details, see:
 
-- [Repo Scripts](https://github.com/cabloy/cabloy/blob/main/cabloy-docs/reference/repo-scripts.md)
-- [Package Map](https://github.com/cabloy/cabloy/blob/main/cabloy-docs/reference/package-map.md)
-- [AI Development Introduction](https://github.com/cabloy/cabloy/blob/main/cabloy-docs/ai/introduction.md)
+- [Editions Overview](https://docs.cabloy.com/editions/overview)
+- [Choosing Between Cabloy Basic and Cabloy Start](https://docs.cabloy.com/editions/choosing-between-basic-and-start)
+- [Repo Scripts](https://docs.cabloy.com/reference/repo-scripts)
+- [Package Map](https://docs.cabloy.com/reference/package-map)
+- [AI Development Introduction](https://docs.cabloy.com/ai/introduction)
 
 Contribution guidelines:
 
 - prefer CLI-backed workflows with `npm run vona` and `npm run zova`
-- put user-facing and agent-facing guidance in [cabloy-docs/](https://github.com/cabloy/cabloy/tree/main/cabloy-docs)
+- put user-facing and agent-facing guidance in [docs.cabloy.com](https://docs.cabloy.com)
 - put maintainer rationale, architecture notes, and ADRs in [.docs-internal/](https://github.com/cabloy/cabloy/tree/main/.docs-internal)
 - verify framework changes with the narrowest meaningful checks first, then shared root scripts when broader confidence is needed
 

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

@@ -2,6 +2,10 @@ import { defineConfig } from 'vitepress';
 
 const editionsItems = [
   { text: 'Overview', link: '/editions/overview' },
+  {
+    text: 'Choosing Basic vs Start',
+    link: '/editions/choosing-between-basic-and-start',
+  },
   { text: 'Cabloy Basic', link: '/editions/cabloy-basic' },
   { text: 'Cabloy Start', link: '/editions/cabloy-start' },
   { text: 'Edition Detection', link: '/editions/detection' },
@@ -23,23 +27,94 @@ const aiItems = [
   { text: 'CLI for Agents', link: '/ai/cli-for-agents' },
   { text: 'Rules and Config', link: '/ai/rules-and-config' },
   { text: 'Edition Detection', link: '/ai/edition-detection' },
+  { text: 'Edition Consistency Checklist', link: '/ai/edition-consistency-checklist' },
   { 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;
+const gaHead = GA_MEASUREMENT_ID
+  ? [
+      [
+        'script',
+        {
+          async: '',
+          src: `https://www.googletagmanager.com/gtag/js?id=${GA_MEASUREMENT_ID}`,
+        },
+      ],
+      [
+        'script',
+        {},
+        `window.dataLayer = window.dataLayer || [];
+function gtag(){dataLayer.push(arguments);}
+gtag('js', new Date());
+gtag('config', '${GA_MEASUREMENT_ID}');`,
+      ],
+    ]
+  : [];
+
 export default defineConfig({
   title: 'Cabloy',
   description: 'Unified fullstack and AI-development documentation for the Cabloy monorepo',
   lang: 'en-US',
   base: '/',
   ignoreDeadLinks: [/^https?:\/\/localhost/],
+  head: gaHead,
   markdown: {
     lineNumbers: true,
   },
@@ -47,40 +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: 'Quickstart', link: '/fullstack/quickstart' },
-            { 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' },
@@ -90,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' },
@@ -111,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' },
@@ -122,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',
@@ -136,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' },
           ],
         },
       ],
@@ -200,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/class-placement-rule.md

@@ -135,4 +135,5 @@ Read these pages together:
 - [Backend Foundation](/backend/foundation)
 - [Service Guide](/backend/service-guide)
 - [Global Bean Lookup](/ai/global-bean-lookup)
+- [Virtual Decorator Guidance](/ai/virtual-decorator-guidance)
 - [Docs, Skills, Rules, and CLI Mapping](/ai/docs-skills-rules-mapping)

package/cabloy-docs/ai/cli-for-agents.md

@@ -53,4 +53,4 @@ Typical use cases:
 
 ## Edition-aware CLI usage
 
-The command families are shared, but examples and generated targets may differ between Cabloy Basic and Cabloy Start. Detect the edition before recommending a frontend-specific example.
+The command families are shared, but examples and generated targets may differ between Cabloy Basic and Cabloy Start because the editions can diverge in UI layer, frontend flavors, suites/modules, SSR site baselines, and project assets. Detect the edition before recommending a frontend-specific example.