cabloy 5.1.60 → 5.1.61

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

@@ -1,5 +1,27 @@
 # 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

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.

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' },
@@ -50,12 +51,16 @@ const fullstackGroups = [
         link: '/fullstack/tutorial-3-frontend-metadata-sharing',
       },
       {
-        text: 'Tutorial 4: Backend Contract Sharing',
-        link: '/fullstack/tutorial-4-backend-contract-sharing',
+        text: 'Tutorial 4: Custom Form/Table Renderers for Level',
+        link: '/fullstack/tutorial-4-custom-level-renderers',
       },
       {
-        text: 'Tutorial 5: One Contract Surface, Four Uses',
-        link: '/fullstack/tutorial-5-one-contract-four-uses',
+        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',
       },
     ],
   },
@@ -75,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',
@@ -243,6 +249,7 @@ 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' },
@@ -268,6 +275,22 @@ 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',
+            },
           ],
         },
         {
@@ -324,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' },
@@ -336,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',
+            },
           ],
         },
         {

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

@@ -152,6 +152,13 @@ Typical skill role:
 - 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:

package/cabloy-docs/ai/future-skill-roadmap.md

@@ -10,18 +10,21 @@ A roadmap helps convert that documented knowledge into a focused set of high-val
 
 ## What already exists
 
-Current root skill:
+Current root skills include:
 
 - `cabloy-workflow`
+- `cabloy-contract-loop`
+- `cabloy-resource-field-update`
+- `cabloy-module-removal`
 
-Its current role is broad workflow selection:
+Their current roles are:
 
-- detect Basic vs Start
-- classify backend/frontend/fullstack/docs work
-- prefer CLI-first behavior
-- suggest verification
+- `cabloy-workflow` → broad workflow selection, edition detection, CLI-first routing, and verification framing
+- `cabloy-contract-loop` → backend/frontend contract regeneration, reverse-chain handling, and drift diagnosis
+- `cabloy-resource-field-update` → existing backend resource-field changes with `fileVersion` and renderer-aware follow-up
+- `cabloy-module-removal` → backend/frontend/fullstack module deletion order, generated-runtime cleanup, and verification
 
-This is a strong foundation skill, but it is intentionally general.
+This is now a stronger foundation skill set, but it still leaves several useful workflow families for future specialization.
 
 ## Recommended next skill families
 

package/cabloy-docs/ai/introduction.md

@@ -75,6 +75,7 @@ Use this path when the task is about implementing or reviewing Cabloy code with
 - [Playbook: Backend Module](/ai/playbook-backend-module)
 - [Playbook: Frontend Page](/ai/playbook-frontend-page)
 - [Playbook: Contract Regeneration](/ai/playbook-contract-regeneration)
+- [Playbook: Module Removal](/ai/playbook-module-removal)
 - [Playbook: Metadata Refresh](/ai/playbook-metadata-refresh)
 
 ### Verification and roadmap path

package/cabloy-docs/ai/playbook-backend-module.md

@@ -66,6 +66,12 @@ Depending on the feature, extend the generated code with the right framework-lev
 - migration and changes
 - field indexes
 
+When refining entity or DTO fields that use `@Api.field(...)`, apply this framework-specific guardrail:
+
+- if you include an explicit zod schema such as `z.number().int().min(1)`, place it as the **last argument**
+- keep helper metadata such as `v.xxx(...)` and `ZovaRender.xxx(...)` before the zod schema
+- otherwise helpers written after the zod schema may stop taking effect
+
 Relevant docs:
 
 - [Controller Guide](/backend/controller-guide)

package/cabloy-docs/ai/playbook-module-removal.md

@@ -0,0 +1,164 @@
+# Playbook: Remove a Cabloy Module
+
+This playbook turns Cabloy module deletion into a repeatable AI-friendly workflow.
+
+## When to use this playbook
+
+Use this playbook when the goal is to remove an existing module from the Cabloy monorepo.
+
+Typical triggers include:
+
+- delete a demo module
+- retire a backend module
+- remove a frontend module
+- remove a fullstack module that exists in both Vona and Zova
+- clean up stale generated runtime or type residues after a module was removed
+
+## Step 1: Detect the repo and scope
+
+Before deleting anything:
+
+1. detect whether the active repo is Cabloy Basic or Cabloy Start
+2. confirm whether the module is backend-only, frontend-only, or fullstack
+3. inspect the root `package.json`
+4. inspect `npm run vona` and `npm run zova`
+
+This avoids deleting the wrong surfaces or using the wrong edition-specific assumptions.
+
+## Step 2: Inventory the real module surfaces
+
+Inspect the real source and direct dependency surfaces first.
+
+Typical locations include:
+
+- `vona/src/module/<module>` or suite-based backend module roots
+- `zova/src/module/<module>` or suite-based frontend module roots
+- `vona/package.json`
+- `zova/package.json`
+- generated registries and lockfiles
+- tests that still target the module
+
+If the user asked for a public scrub, also inspect `cabloy-docs/`. Otherwise, treat docs cleanup as a separate scope decision.
+
+## Step 3: Remove source and direct references first
+
+Start by removing the real source and direct workspace package references.
+
+Typical order:
+
+1. remove backend module source if in scope
+2. remove frontend module source if in scope
+3. remove direct workspace dependency entries from the relevant `package.json` files
+4. refresh or clean generated registrations only after source removal
+
+Do not start by hand-editing generated caches while the real module source or package references still exist.
+
+## Step 4: Regenerate with the repo-owned workflow
+
+After source cleanup, use the existing root scripts to refresh generated outputs.
+
+Representative root commands in Cabloy Basic include:
+
+```bash
+npm run build:zova:admin
+npm run deps:vona
+npm run deps:zova
+npm run tsc
+npm run test
+```
+
+### Fullstack default sequence
+
+When the module exists on both the Vona and Zova sides, the usual sequence is:
+
+1. `npm run build:zova:admin`
+2. `npm run deps:vona`
+3. `npm run deps:zova`
+4. `npm run tsc`
+
+This keeps the Zova Admin JS bundle and rest output aligned before Vona consumes downstream artifacts.
+
+### Narrower branches
+
+For backend-only removal, prefer the narrowest meaningful verification first:
+
+- `npm run deps:vona`
+- `npm run tsc`
+- `npm run test` when runtime/test coupling is likely
+
+For frontend-only removal, use the relevant Zova build/deps path first, then typecheck.
+
+## Step 5: Clean generated runtime directories when residues remain stale
+
+If stale module types or runtime entries still remain after the normal cleanup and regeneration flow, treat generated runtime directories as disposable working state.
+
+In particular, the primary recovery targets for this workflow are:
+
+- `vona/.vona`
+- `zova/.zova`
+
+These are not necessarily the only generated working directories in the repo, but they are the main stale-runtime targets for normal module-removal recovery.
+
+Why this is safe:
+
+- these directories are generated by the Vona and Zova CLI flows
+- they are ignored by the repo because they are not source-of-truth files
+- they may survive when a service or build process does not stop cleanly
+
+After deleting them, rerun the normal regeneration flow and typecheck again.
+
+## Step 6: Verify that the module is really gone
+
+Search for remaining references to:
+
+- the module relative name
+- the backend workspace package name
+- the frontend workspace package name
+- route or resource names if applicable
+
+Then verify with the narrowest meaningful commands first, followed by broader checks when needed.
+
+Typical verification commands:
+
+```bash
+npm run build:zova:admin
+npm run deps:vona
+npm run deps:zova
+npm run tsc
+npm run test
+```
+
+The expected result is:
+
+- no direct workspace dependency entries remain
+- no generated registry still points at the removed module
+- no stale typecheck failures still reference the module
+- no important runtime or test surfaces still import it
+
+## Step 7: Treat docs cleanup as an explicit second scope
+
+Removing code/runtime surfaces does not automatically mean public docs should be rewritten.
+
+Make this an explicit scope decision:
+
+- code/runtime removal only
+- code/runtime removal plus docs/examples scrub
+
+If docs cleanup is in scope, update `cabloy-docs/` as a separate pass after runtime cleanup is stable.
+
+## AI rule of thumb
+
+A good Cabloy module-removal workflow is usually:
+
+1. detect edition and scope
+2. inventory real module surfaces
+3. remove source and direct references
+4. regenerate with repo entrypoints
+5. clean generated runtime dirs only when stale residues remain
+6. verify the module is really gone
+
+Not:
+
+1. delete a few generated files first
+2. guess which paths matter
+3. leave workspace dependencies or generated registrations stale

package/cabloy-docs/ai/skills.md

@@ -35,3 +35,14 @@ A strong Cabloy skill usually includes:
 When a skill needs to apply an architectural rule such as backend class placement, prefer a branching decision tree that points back to durable docs instead of embedding the full architecture rationale inside the skill itself.
 
 For edition-aware skills, use [Edition Detection for AI Workflows](/ai/edition-detection) and [Edition Consistency Checklist](/ai/edition-consistency-checklist) as the durable review surfaces before expanding edition-specific branches.
+
+## Example workflow skills in this repo
+
+Current examples include:
+
+- `cabloy-workflow` for choosing the correct Cabloy work path before implementation
+- `cabloy-contract-loop` for backend/frontend contract regeneration and drift diagnosis
+- `cabloy-resource-field-update` for updating an existing backend resource field thread
+- `cabloy-module-removal` for removing a backend, frontend, or fullstack module cleanly, including generated-runtime cleanup, stale-residue recovery, and verification
+
+The module-removal workflow is a good example of why skills belong in `.claude/skills/` instead of `CLAUDE.md`: the task needs branching, cleanup order, recovery guidance for generated runtime directories such as `vona/.vona` and `zova/.zova`, and a verification checklist that would be too large for a short repo-wide rule.

package/cabloy-docs/backend/dto-guide.md

@@ -73,6 +73,12 @@ class DtoStudentCreate {
 }
 ```
 
+When mixing helper metadata and an explicit zod schema in `@Api.field(...)`, apply the same ordering rule used by entities:
+
+- place `z.xxx(...)` as the **last argument** because it returns the zod schema instance
+- keep helper metadata such as `v.xxx(...)` and `ZovaRender.xxx(...)` before the zod schema
+- otherwise helpers written after the zod schema may stop taking effect
+
 For query-oriented DTOs, another important distinction is optional vs nullable:
 
 - `v.optional()` means the field may be omitted

package/cabloy-docs/backend/entity-guide.md

@@ -103,6 +103,24 @@ Representative examples include:
 - helpers such as `v.default`, `v.optional`, `v.array`
 - OpenAPI metadata such as `v.title`, `v.description`, `v.example`, `v.openapi`
 
+When mixing helper metadata and an explicit zod schema in `@Api.field(...)`, keep a small but important ordering rule:
+
+- `z.xxx(...)` returns the zod schema instance, so place it as the **last argument**
+- put helper metadata such as `v.xxx(...)` and `ZovaRender.xxx(...)` before the zod schema
+- otherwise helpers written after the zod schema may stop taking effect
+
+Representative pattern:
+
+```typescript
+@Api.field(
+  v.title($locale('Level')),
+  ZovaRender.order(3),
+  ZovaRender.field('basic-select:formFieldSelect', { items: levelItems }),
+  z.number().int().min(1).max(3),
+)
+level: number;
+```
+
 A practical rule is:
 
 - use inference for straightforward fields

package/cabloy-docs/backend/introduction.md

@@ -60,6 +60,7 @@ Use this path when the task is about runtime shape, startup, instances, workers,
 - [Worker Guide](/backend/worker-guide)
 - [Election Guide](/backend/election-guide)
 - [Queue Guide](/backend/queue-guide)
+- [Status Guide](/backend/status-guide)
 - [Broadcast Guide](/backend/broadcast-guide)
 - [Web Socket Guide](/backend/websocket-guide)
 - [Web Socket Usage Guide](/backend/websocket-usage-guide)
@@ -94,6 +95,7 @@ If your task is already inside the runtime and distributed family, read these gu
 - [Worker Guide](/backend/worker-guide)
 - [Election Guide](/backend/election-guide)
 - [Queue Guide](/backend/queue-guide)
+- [Status Guide](/backend/status-guide)
 - [Broadcast Guide](/backend/broadcast-guide)
 - [Web Socket Guide](/backend/websocket-guide)
 - [Web Socket Usage Guide](/backend/websocket-usage-guide)

package/cabloy-docs/backend/serialization-guide.md

@@ -41,6 +41,16 @@ async findOne(id) {
 
 This makes serialization an explicit request-path capability rather than an invisible response-side convention.
 
+Important operational rule:
+
+- for performance reasons, serialization is **not enabled by default**
+- `v.serializerTransform(...)`, `v.serializerExclude()`, `v.serializerReplace(...)`, `v.serializerGetter(...)`, and `v.serializerCustom(...)` only declare field-level transform metadata
+- those transforms do **not** run unless the target API explicitly enables serialization with `@Core.serializer()`
+
+A practical debugging rule is:
+
+- if a field-level serializer appears correct but the response still returns the raw value, first check whether the controller action uses `@Core.serializer()`
+
 ## Serializer transforms
 
 Vona supports custom serializer transforms through `@SerializerTransform(...)`.