cabloy 5.1.59 → 5.1.61

package/.claude/skills/cabloy-zova-source-reading/references/analysis-modes.md

@@ -0,0 +1,91 @@
+# Analysis Modes
+
+Use this reference to choose the shortest correct analysis posture before reading Zova source deeply.
+
+## Mode A: source-location mode
+
+Use this mode when the user is mainly asking:
+
+- where should I start reading?
+- which files matter?
+- what order should I read the source in?
+- where is this implemented?
+
+### Workflow
+
+1. detect the active edition if UI-sensitive assumptions might matter
+2. start from the public frontend docs first
+3. pick the smallest matching thread from `cabloy-docs/frontend/zova-source-reading-map.md`
+4. cite the initial source files in the recommended reading order
+5. stop before tracing deeper runtime layers unless the user also wants runtime-flow analysis
+
+### Output emphasis
+
+- reading order
+- key file paths
+- why those files are the right starting points
+
+## Mode B: runtime-flow mode
+
+Use this mode when the user is mainly asking:
+
+- how does this work internally?
+- why is this reactive?
+- where does this controller/page/component behavior come from?
+- how does render, route state, or lifecycle enter the runtime?
+
+### Workflow
+
+1. read the public Zova-native explanation docs first:
+   - `reading-zova-for-vue-developers.md`
+   - `zova-reactivity-under-the-hood.md`
+2. identify the concrete thread:
+   - page controller
+   - component controller
+   - route/state
+   - model
+   - behavior
+   - SSR
+3. trace the smallest current-source path that confirms the runtime behavior
+4. distinguish source-confirmed behavior from interpretation
+5. only after the Zova-native explanation is clear, add Vue analogy if helpful
+
+### Output emphasis
+
+- entrypoint
+- intermediate runtime files
+- what triggers the behavior
+- what is source-confirmed
+
+## Mode C: Vue-vs-Zova comparison mode
+
+Use this mode when the user is mainly asking:
+
+- how should I understand this relative to Vue 3?
+- is this just Vue with a different syntax?
+- what is the Zova way here?
+
+### Workflow
+
+1. explain the Zova-native architectural role first
+2. identify which public Zova doc best defines that role
+3. if needed, trace one representative source path to confirm the runtime grounding
+4. only then provide Vue analogies as approximate translations
+5. explicitly avoid flattening Zova back into generic Vue habits
+
+### Output emphasis
+
+- Zova-native role
+- closest Vue analogy
+- what is genuinely shared underneath
+- what changes at the authoring-model level
+
+## Combined requests
+
+If a request spans multiple modes, answer in this order:
+
+1. source-location mode
+2. runtime-flow mode
+3. Vue-vs-Zova comparison mode
+
+This keeps the explanation anchored in the real source path before analogy work begins.

package/.claude/skills/cabloy-zova-source-reading/references/core-reading-paths.md

@@ -0,0 +1,117 @@
+# Core Reading Paths
+
+Use this reference to choose the shortest source path after the analysis mode is known.
+
+## Page controller and page reactivity
+
+Read in this order:
+
+1. the concrete page controller source
+2. `zova-core/src/composables/useController.ts`
+3. `zova-core/src/bean/beanContainer.ts`
+4. `zova-core/src/bean/beanBase.ts`
+5. `zova-core/src/bean/beanControllerPageBase.ts`
+6. `zova-core/src/core/context/component.ts`
+7. router integration files such as `a-router/src/monkey.ts`
+
+Use when the question is about:
+
+- plain controller fields
+- `$computed`
+- `$params` / `$query`
+- page render flow
+
+## Component controller and wrapper path
+
+Read in this order:
+
+1. representative wrapper metadata under `src/.metadata/component/`
+2. `zova-core/src/composables/useController.ts`
+3. `zova-core/src/bean/beanControllerBase.ts`
+4. `zova-core/src/core/context/component.ts`
+5. the concrete component controller source
+
+Use when the question is about:
+
+- wrapper components
+- `controllerRef`
+- component-local controller behavior
+
+## Bean lifecycle and helper API path
+
+Read in this order:
+
+1. `zova-core/src/bean/beanBase.ts`
+2. `zova-core/src/bean/beanBaseSimple.ts`
+3. `zova-core/src/bean/beanContainer.ts`
+4. `zova-core/src/core/context/util.ts`
+
+Use when the question is about:
+
+- `__init__`
+- `__dispose__`
+- `$watch`
+- `$toRef`
+- instance scope
+
+## Route and page-shell path
+
+Read in this order:
+
+1. the local `routes.ts`
+2. `a-router/src/monkey.ts`
+3. router utility files
+4. page schema sources
+5. `BeanControllerPageBase`
+
+Use when the question is about:
+
+- route records
+- params/query parsing
+- layout shell implications
+- route-aware controller state
+
+## Model/state ownership path
+
+Read in this order:
+
+1. the relevant model bean
+2. framework model state helper files
+3. representative built-in model beans
+4. consuming page/controller/service code
+
+Use when the question is about:
+
+- model-owned state
+- cache-oriented state
+- async vs sync state ownership
+
+## Behavior path
+
+Read in this order:
+
+1. the public behavior wrapper/controller path
+2. the concrete behavior bean
+3. the behavior composer/service files
+4. host-scoped injected dependencies
+
+Use when the question is about:
+
+- render-time interception
+- behavior composition
+- Behavior vs Component vs Helper
+
+## SSR runtime path
+
+Read in this order:
+
+1. the SSR site or bundle entry
+2. SSR runtime/context files in `zova-core`
+3. relevant page/controller/model code
+4. Vona SSR handoff layer if needed
+
+Use when the question is about:
+
+- SSR entry
+- hydration handoff
+- whether the bug belongs to Vona or Zova

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

@@ -21,6 +21,8 @@ concurrency:
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     steps:
       - uses: actions/checkout@v6
       - uses: pnpm/action-setup@v5

package/.github/workflows/vona-cov-pg.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest

package/.github/workflows/vona-test-crud.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest
@@ -25,11 +27,11 @@ jobs:
           version: 11.5.2
       - name: init
         run: npm run init
-      - run: npm run vona :create:module demo-student -- --suite --ci
+      - run: npm run vona :create:module demo-student2 -- --suite --ci
         working-directory: vona
       - run: npm run vona :tools:deps
         working-directory: vona
-      - run: npm run vona :tools:crud student -- --module=demo-student
+      - run: npm run vona :tools:crud student2 -- --module=demo-student2
         working-directory: vona
       - run: npm run test
         working-directory: vona

package/.github/workflows/vona-test-mysql.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest

package/.github/workflows/vona-test-pg.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest

package/.github/workflows/vona-test-sqlite3.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     services:
       redis:
         image: redis:latest

package/.github/workflows/vona-tsc.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6

package/.github/workflows/zova-ui.yml

@@ -10,6 +10,8 @@ jobs:
       matrix:
         node-version: [24]
     runs-on: ubuntu-latest
+    env:
+      PNPM_CONFIG_MINIMUM_RELEASE_AGE: 0
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v6

package/.gitignore

@@ -62,7 +62,6 @@ zova/.quasar
 **/.vitepress/cache
 **/.rollup.cache
 **/.temp-dynamic-*
-/.cabloy-version
 vona/package.json
 zova/package.json
 vona/docker-compose.yml
@@ -76,6 +75,3 @@ vona/src/suite/cabloy-basic/modules/basic-siteadmin/assets/site
 vona/src/suite/cabloy-basic/modules/basic-siteadmin/zovaRest
 vona/src/suite/cabloy-basic/modules/basic-siteweb/assets/site
 vona/src/suite/cabloy-basic/modules/basic-siteweb/zovaRest
-
-/vona/src/module/demo-student
-/zova/src/module/demo-student

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 5.1.61
+
+### Features
+
+- Enforce explicit OpenAPI operation filters.
+- Remove the demo-student module and document the module-removal workflow.
+- Add a mobile field to students and document serializer guidance.
+
+### Bug Fixes
+
+- Decouple test data initialization from application initialization.
+- Refresh the student summary after updates.
+
+### Improvements
+
+- Migrate the contract-loop hook to TypeScript.
+- Harden and simplify contract-loop guidance and gate behavior.
+- Add Zova Form documentation and navigation.
+- Refine ModelResource guidance and examples.
+- Add Zova command scene, fetch interceptor, frontend reading, and Status architecture guides.
+- Update backend contract-sharing tutorial and related skill documentation.
+
+## 5.1.60
+
+### Features
+
+- Add a mobile field to the demo-student example.
+- Add demo-student summary and force-delete flows.
+- Add a level renderer workflow to the demo-student example.
+- Initialize test data automatically after setup.
+- Refine router tab insertion order.
+
+### Improvements
+
+- Add SSR architecture and workflow guides.
+- Add a Web Socket documentation set.
+- Add a Zova Behavior guide.
+- Add router tabs documentation.
+- Add advanced bean scene authoring guides and document boilerplate variants.
+- Add a fullstack quick start tutorial series and document core fullstack principles.
+- Refactor the fullstack AI tutorial series and streamline quick start guidance.
+- Clarify helper placement and strengthen contract loop examples with reusable patterns.
+- Simplify and polish tutorial prompts, verification steps, and user workflow guidance.
+- Unify resource-owned custom item state handling.
+- Update `tmp` to `0.2.7` and `tar` to `7.5.16`.
+- Disable `pnpm` `minimumReleaseAge` in CI workflows.
+
+### Bug Fixes
+
+- Make contract loop examples more resilient.
+- Refine select placeholder guidance.
+
 ## 5.1.59
 
 ### Features

package/CLAUDE.md

@@ -42,8 +42,18 @@ Before inventing a custom implementation path:
 ## AI development rules
 
 - Prefer CLI-backed workflows over manual scaffolding whenever Vona or Zova already provides a generator, refactor, metadata, or verification command.
+- The Cabloy contract-loop model applies to both Cabloy Basic and Cabloy Start; detect the edition to choose commands and output paths, not to redefine the workflow model.
+- Treat contract-loop work as one of four branches: forward chain, reverse chain, consumer drift, or local dependency drift.
+- For the forward chain, change backend contract truth first and regenerate frontend consumers rather than hand-patching them.
+- After forward regeneration, keep frontend follow-up thin: prefer semantic model facades and reuse the existing resource-owner when the custom API still belongs to the same resource.
+- For the reverse chain, when Vona consumes newly added or changed Zova Admin render/action/metadata, always run `npm run build:zova:admin` before `npm run deps:vona`. Do not treat `build:rest:cabloyBasicAdmin` alone as sufficient, because the Admin JS bundle and rest output must move together.
+- If generated artifacts already contain the expected changes but consumers still behave stale, suspect local dependency drift before making more source edits.
+- For Cabloy Start, apply the same reverse-chain logic but resolve the Start-specific flavor names and generated-output paths from the active Start repo before recommending commands.
 - 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 Zova frontend analysis, do not default to generic Vue reinterpretation first. Read the code through Zova’s controller / bean / IoC architecture before mapping it to Vue concepts.
+- For Zova source-reading or Vue-vs-Zova explanation tasks, start from the frontend reading guides and source-reading map in `cabloy-docs/frontend/` before doing framework-neutral reinterpretation.
+- Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
 - 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.
@@ -54,9 +64,11 @@ Before inventing a custom implementation path:
 - Service-scene runtime-anchor bases that should not register in `IBeanRecordGeneral` should prefer the `src/service/*_.ts` form.
 - `src/bean` defines the global shorthand surface; classes that should not appear in `IBeanRecordGlobal` should move to `src/lib` or `src/service` rather than being filtered by `@Virtual()`.
 - When backend code references `this.bean.xxx`, `ctx.bean.xxx`, or `app.bean.xxx`, use `IBeanRecordGlobal` and module `src/.metadata/index.ts` as the first static lookup surface; use `IBeanRecordGeneral` or `src/service` only when the target is not a global shorthand.
+- When adding a persisted field to an existing backend resource, ask the user whether `vonaModule.fileVersion` should be incremented before changing `meta.version.ts` or the module schema path. If yes, add a new migration version and bump `fileVersion`. If no, keep the current `fileVersion` and fold the schema change into the current version path. Do not assume the versioning strategy without confirmation.
 
 ## Verification expectations
 
 - For docs changes: run the docs build and verify links/navigation where practical.
 - For code-generation or workflow guidance changes: verify that the referenced scripts and command families still exist.
 - For code changes: prefer the narrowest meaningful verification first, then use shared root scripts when broader confidence is needed.
+- Any change to `meta.version.ts` requires running `npm run test` so the test database is reinitialized and schema/data consistency issues surface early.

package/README.md

@@ -14,6 +14,21 @@ With Vona, Zova, suite-based modules, and CLI-first workflows, Cabloy turns comm
 
 [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)
 
+## Fullstack Principles
+
+Cabloy’s fullstack model is built around two core principles:
+
+1. **Frontend build output participates directly in backend SSR**
+   - Zova owns the frontend application source
+   - the generated frontend bundle and SSR-related artifacts are consumed by the Vona-side SSR flow
+   - backend rendering and frontend hydration stay on one coordinated delivery path
+
+2. **Type information flows in both directions**
+   - **Backend -> Frontend**: Vona emits Swagger/OpenAPI contracts that Zova can use to generate SDKs and related schema-aware helpers
+   - **Frontend -> Backend**: Zova generates structural metadata and typing surfaces such as routes, components, and icons that can improve backend-side tooling and type hints
+
+For the complete explanation, see [Fullstack Introduction](https://docs.cabloy.com/fullstack/introduction), [Vona + Zova Integration](https://docs.cabloy.com/fullstack/vona-zova-integration), [Backend OpenAPI to Frontend SDK](https://docs.cabloy.com/fullstack/openapi-to-sdk), and [Frontend Metadata Back to Backend](https://docs.cabloy.com/fullstack/frontend-metadata-to-backend).
+
 ## Get Started
 
 ### Prerequisites

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

@@ -23,6 +23,7 @@ const aiItems = [
   { text: 'Playbook: Backend Module', link: '/ai/playbook-backend-module' },
   { text: 'Playbook: Frontend Page', link: '/ai/playbook-frontend-page' },
   { text: 'Playbook: Contract Regeneration', link: '/ai/playbook-contract-regeneration' },
+  { text: 'Playbook: Module Removal', link: '/ai/playbook-module-removal' },
   { text: 'Playbook: Metadata Refresh', link: '/ai/playbook-metadata-refresh' },
   { text: 'CLI for Agents', link: '/ai/cli-for-agents' },
   { text: 'Rules and Config', link: '/ai/rules-and-config' },
@@ -39,6 +40,30 @@ const fullstackGroups = [
       { text: 'Quickstart', link: '/fullstack/quickstart' },
     ],
   },
+  {
+    text: 'Fullstack / Tutorials',
+    items: [
+      { text: 'Tutorials Overview', link: '/fullstack/tutorials-overview' },
+      { text: 'Tutorial 1: First Module', link: '/fullstack/tutorial-1-first-module' },
+      { text: 'Tutorial 2: First CRUD', link: '/fullstack/tutorial-2-first-crud' },
+      {
+        text: 'Tutorial 3: Frontend Metadata Sharing',
+        link: '/fullstack/tutorial-3-frontend-metadata-sharing',
+      },
+      {
+        text: 'Tutorial 4: Custom Form/Table Renderers for Level',
+        link: '/fullstack/tutorial-4-custom-level-renderers',
+      },
+      {
+        text: 'Tutorial 5: Backend Contract Sharing',
+        link: '/fullstack/tutorial-5-backend-contract-sharing',
+      },
+      {
+        text: 'Tutorial 6: One Contract Surface, Four Uses',
+        link: '/fullstack/tutorial-6-one-contract-four-uses',
+      },
+    ],
+  },
   {
     text: 'Tooling & Workflow',
     items: [
@@ -55,6 +80,7 @@ const fullstackGroups = [
       },
       { text: 'Framework Performance', link: '/fullstack/framework-performance' },
       { text: 'Vona + Zova Integration', link: '/fullstack/vona-zova-integration' },
+      { text: 'Contract Loop Playbook', link: '/fullstack/contract-loop-playbook' },
       { text: 'Backend OpenAPI to Frontend SDK', link: '/fullstack/openapi-to-sdk' },
       {
         text: 'Frontend Metadata Back to Backend',
@@ -75,6 +101,7 @@ const referenceGroups = [
       { text: 'Introduction', link: '/reference/introduction' },
       { text: 'Repo Scripts', link: '/reference/repo-scripts' },
       { text: 'CLI Reference', link: '/reference/cli-reference' },
+      { text: 'Bean Scene Boilerplate Variants', link: '/reference/bean-scene-boilerplates' },
     ],
   },
   {
@@ -182,6 +209,7 @@ export default defineConfig({
           text: 'Core Programming Model',
           items: [
             { text: 'AOP Overview', link: '/backend/aop-overview' },
+            { text: 'Bean Scene Authoring', link: '/backend/bean-scene-authoring' },
             { text: 'Controller Guide', link: '/backend/controller-guide' },
             { text: 'Controller AOP Guide', link: '/backend/controller-aop-guide' },
             { text: 'Internal AOP Guide', link: '/backend/internal-aop-guide' },
@@ -221,8 +249,13 @@ export default defineConfig({
             { text: 'Queue Guide', link: '/backend/queue-guide' },
             { text: 'Election Guide', link: '/backend/election-guide' },
             { text: 'Schedule Guide', link: '/backend/schedule-guide' },
+            { text: 'Status Guide', link: '/backend/status-guide' },
             { text: 'Worker Guide', link: '/backend/worker-guide' },
             { text: 'Broadcast Guide', link: '/backend/broadcast-guide' },
+            { text: 'Web Socket Guide', link: '/backend/websocket-guide' },
+            { text: 'Web Socket Usage Guide', link: '/backend/websocket-usage-guide' },
+            { text: 'Web Socket Protocol Guide', link: '/backend/websocket-protocol-guide' },
+            { text: 'Web Socket Call Flow', link: '/backend/websocket-call-flow' },
             { text: 'Redlock Guide', link: '/backend/redlock-guide' },
           ],
         },
@@ -242,12 +275,30 @@ export default defineConfig({
             { text: 'Introduction', link: '/frontend/introduction' },
             { text: 'Quickstart', link: '/frontend/quickstart' },
             { text: 'Foundation', link: '/frontend/foundation' },
+            {
+              text: 'Reading Zova for Vue Developers',
+              link: '/frontend/reading-zova-for-vue-developers',
+            },
+            {
+              text: 'Zova vs Vue 3 Comparison',
+              link: '/frontend/zova-vs-vue3-comparison',
+            },
+            {
+              text: 'Zova Reactivity Under the Hood',
+              link: '/frontend/zova-reactivity-under-the-hood',
+            },
+            {
+              text: 'Zova Source Reading Map',
+              link: '/frontend/zova-source-reading-map',
+            },
           ],
         },
         {
           text: 'Architecture & Modules',
           items: [
             { text: 'IoC and Beans', link: '/frontend/ioc-and-beans' },
+            { text: 'Bean Scene Authoring', link: '/frontend/bean-scene-authoring' },
+            { text: 'Behavior Guide', link: '/frontend/behavior-guide' },
             { text: 'Modules and Suites', link: '/frontend/modules-and-suites' },
             { text: 'Module Scope', link: '/frontend/module-scope' },
             { text: 'Design Principles', link: '/frontend/design-principles' },
@@ -277,6 +328,17 @@ export default defineConfig({
             { text: 'Page Params Guide', link: '/frontend/page-params-guide' },
             { text: 'Zod Guide', link: '/frontend/zod-guide' },
             { text: 'Page Route Guide', link: '/frontend/page-route-guide' },
+            { text: 'Router Tabs Introduction', link: '/frontend/router-tabs-introduction' },
+            { text: 'Router Tabs Overview', link: '/frontend/router-tabs-overview' },
+            { text: 'Router Tabs Mechanism', link: '/frontend/router-tabs-mechanism' },
+            {
+              text: 'Router Tabs Route Meta Cookbook',
+              link: '/frontend/router-tabs-route-meta-cookbook',
+            },
+            {
+              text: 'Router Tabs Admin and Web Comparison',
+              link: '/frontend/router-tabs-admin-web-comparison',
+            },
             { text: 'Route Alias Guide', link: '/frontend/route-alias-guide' },
             { text: 'Navigation Guards Guide', link: '/frontend/navigation-guards-guide' },
           ],
@@ -285,6 +347,15 @@ export default defineConfig({
           text: 'Components & UI',
           items: [
             { text: 'Component Guide', link: '/frontend/component-guide' },
+            { text: 'Form Guide', link: '/frontend/form-guide' },
+            {
+              text: 'Zova Form Under the Hood',
+              link: '/frontend/zova-form-under-the-hood',
+            },
+            {
+              text: 'Zova Form Source Reading Map',
+              link: '/frontend/zova-form-source-reading-map',
+            },
             { 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' },
@@ -297,9 +368,23 @@ export default defineConfig({
           text: 'Data & State',
           items: [
             { text: 'Server Data', link: '/frontend/server-data' },
+            { text: 'Fetch Interceptor Guide', link: '/frontend/fetch-interceptor-guide' },
             { text: 'API Guide', link: '/frontend/api-guide' },
             { text: 'Model Architecture', link: '/frontend/model-architecture' },
             { text: 'Model State Guide', link: '/frontend/model-state-guide' },
+            { text: 'Model Resource Owner Pattern', link: '/frontend/model-resource-owner-pattern' },
+            {
+              text: 'Using ModelResource in Your Module',
+              link: '/frontend/model-resource-usage-guide',
+            },
+            {
+              text: 'Resource Model Best Practices',
+              link: '/frontend/model-resource-best-practices',
+            },
+            {
+              text: 'Resource Model Cookbook',
+              link: '/frontend/model-resource-cookbook',
+            },
           ],
         },
         {
@@ -313,6 +398,10 @@ export default defineConfig({
         {
           text: 'SSR',
           items: [
+            { text: 'SSR Architecture Overview', link: '/frontend/ssr-architecture-overview' },
+            { text: 'SSR Build and Deploy Guide', link: '/frontend/ssr-build-deploy-guide' },
+            { text: 'SSR Troubleshooting Guide', link: '/frontend/ssr-troubleshooting-guide' },
+            { text: 'SSR Review Checklist', link: '/frontend/ssr-review-checklist' },
             { text: 'SSR Overview', link: '/frontend/ssr-overview' },
             { text: 'SSR Init Data', link: '/frontend/ssr-init-data' },
             { text: 'SSR ClientOnly', link: '/frontend/ssr-client-only' },

package/cabloy-docs/ai/class-placement-rule.md

@@ -27,6 +27,8 @@ Recommended placement:
 
 - `src/lib`
 
+For reusable module-local helper functions that are not classes, follow the same structural idea: initialize the module `src/lib` directory and place shared pure helper functions there. For the fuller backend placement context around module-local helpers, also see [Backend Foundation](/backend/foundation).
+
 ### B1: subclass-only base
 
 Use B1 when the class mainly exists as a superclass for concrete subclasses.

package/cabloy-docs/ai/cli-to-skill-map.md

@@ -145,6 +145,20 @@ Typical skill role:
 - likely CLI path: Zova `openapi:*` or REST build flows
 - skill then verifies the right edition-specific flavor path
 
+### Example: “Update a field on an existing backend resource”
+
+- skill decides this is an existing-resource field-update task
+- skill classifies persisted-field vs metadata-only refinement
+- likely CLI path: Vona persistence verification plus Zova metadata/build flows only if renderer follow-up is required
+- skill then verifies entity, locale, tests, `fileVersion` logic, and renderer/build/deps follow-up when applicable
+
+### Example: “Remove an existing module cleanly”
+
+- skill decides this is a module-removal workflow rather than scaffolding or contract evolution
+- skill classifies backend-only vs frontend-only vs fullstack removal
+- likely CLI path: root build/deps/typecheck scripts such as `npm run build:zova:admin`, `npm run deps:vona`, `npm run deps:zova`, and `npm run tsc`
+- skill then verifies that source, package references, generated registrations, and stale runtime directories are handled in the correct order
+
 ## Anti-patterns
 
 Avoid these mistakes in skills:

package/cabloy-docs/ai/docs-skills-rules-mapping.md

@@ -143,6 +143,20 @@ Use this quick rule:
 - full explanation → [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - workflow steering → skill and rules can point to the docs and choose the right CLI path
 
+### Example: “How should AI remove an existing module cleanly?”
+
+- public operational explanation → [Playbook: Module Removal](/ai/playbook-module-removal)
+- maintainer rationale and pitfalls → `.docs-internal/architecture/module-removal-workflow.md`
+- avoid putting the full workflow in `CLAUDE.md` because the task needs branching, cleanup order, generated-runtime recovery, and verification
+- procedural decision workflow → `cabloy-module-removal` skill
+
+### Example: “What `@Api.field(...)` ordering rule should AI preserve when mixing helpers and zod?”
+
+- full explanation → [Entity Guide](/backend/entity-guide) and [DTO Guide](/backend/dto-guide)
+- AI workflow reminder → [Playbook: Add a Backend Module](/ai/playbook-backend-module)
+- procedural checklist reminder → backend scaffold skill references
+- avoid putting the full explanation only in `CLAUDE.md` because this is a framework-specific authoring rule, not a short global behavior rule
+
 ## Anti-patterns to avoid
 
 Avoid these mistakes: