cabloy 5.1.61 → 5.1.62

package/cabloy-docs/frontend/generated-contract-consumption-specimen.md

@@ -0,0 +1,203 @@
+# Generated Contract Consumption Specimen
+
+This page is a focused specimen for one narrow frontend question:
+
+> after backend-authored OpenAPI/schema contract material has already been generated into Zova, what does real frontend consumption look like?
+
+Use this page together with:
+
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [Server Data](/frontend/server-data)
+- [SDK Guide](/frontend/sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+- [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive)
+- [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+
+> [!TIP]
+> **Generated-contract reading path**
+>
+> 1. **[Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)** — understand how backend-authored truth crosses the stack boundary
+> 2. **[OpenAPI SDK Guide](/frontend/openapi-sdk-guide)** — configure and generate the frontend contract slice
+> 3. **[Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen)** — see how generated contract material is consumed in practice
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [OpenAPI SDK Guide](/frontend/openapi-sdk-guide).
+
+## Why this page exists
+
+Several existing docs already explain parts of this story well:
+
+- the fullstack bridge from backend OpenAPI to frontend generation
+- frontend OpenAPI config and module ownership
+- the conceptual roles of `$sdk`, `$apiSchema`, and server-data layers
+- the internals of `a-openapi` and `ModelResource`
+
+What was still missing was one narrow page that shows the practical consumer-side chain after generation.
+
+This page fills that gap.
+
+It is not another generation guide and not another internals page. It is a specimen page about consumption.
+
+## Shortest accurate mental model
+
+A practical generated-contract consumption path looks like this:
+
+1. backend-authored contract truth has already been generated into frontend contract material
+2. frontend accesses that material through generated API/schema surfaces such as `$api`, `$apiSchema`, and `$sdk`
+3. when the API still belongs to one resource boundary, `ModelResource` remains the stable owner
+4. list-page and entry-page shells consume that owner rather than recreating the contract ad hoc
+5. deeper runtime details still belong to the existing under-the-hood pages
+
+That means generated contract consumption is not one thing only.
+
+It usually moves through:
+
+- generated API/schema access
+- owner-level resource consumption
+- page-shell/runtime consumption
+
+## Where generated contract material comes from
+
+This page starts **after** the forward-chain bridge and generation steps.
+
+Those earlier steps are owned by:
+
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+
+Once that handoff is complete, the frontend can consume generated contract material through several surfaces:
+
+- generated API services
+- generated API schema accessors
+- `$sdk` schema/runtime helpers
+- higher-level resource owners such as `ModelResource`
+
+## Shared consumption chain
+
+A practical shared reading path is:
+
+1. `zova/src/suite/a-training/modules/training-student/src/apiSchema/trainingStudent.ts`
+2. `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+3. optional direct schema/api consumer specimen: `zova/src/suite/a-home/modules/home-passport/src/model/passport.ts`
+
+That short path already shows the shared contract-consumption layers that both list and entry pages depend on:
+
+- generated schema access
+- thin semantic model follow-up when needed
+- stable resource-owner consumption
+
+## `$sdk`, `$apiSchema`, and generated-contract surfaces in one view
+
+A practical split is:
+
+- generated API services expose callable backend operations
+- `$apiSchema` exposes schema-oriented access to those operations
+- `$sdk` is the lower-level schema/runtime bridge beneath those higher-level consumers
+
+A clear direct schema specimen exists in:
+
+- `zova/src/suite/a-training/modules/training-student/src/apiSchema/trainingStudent.ts`
+
+Representative source facts:
+
+- `@ApiSchema()` exposes a schema bean for the module
+- methods such as `select()`, `create()`, `view()`, `delete()`, `update()`, `summary()`, and `deleteForce()` call `this.$sdk.createApiSchemas(...)`
+
+A second useful specimen is:
+
+- `zova/src/suite/a-home/modules/home-passport/src/model/passport.ts`
+
+Representative source fact:
+
+- `schemaLogin` is derived from `this.apiSchemasLogin.requestBody`
+
+Together, these show the first practical boundary in the frontend contract path:
+
+> the generated contract does not jump directly from backend OpenAPI into page internals. It first becomes frontend-accessible through schema- and SDK-oriented surfaces.
+
+## `ModelResource` as the shared owner before branch split
+
+When the generated contract still belongs to one business resource, frontend consumption usually should not create a second competing owner.
+
+A strong public specimen for this pattern exists in:
+
+- `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+
+Representative source facts:
+
+- the module model is a semantic facade, not the primary resource owner
+- it resolves `rest-resource.model.resource` through selector-backed access
+- custom methods such as `summary(id)` and `deleteForce(id)` still delegate to resource-owner query and mutation helpers
+
+This is the practical contract-consumption rule that matters most:
+
+> when the API still belongs to the same resource, keep `ModelResource` as the stable owner and keep frontend follow-up thin.
+
+At this point, the generated contract consumption path splits into two practical branches:
+
+- **list branch** -> list route shell, schema row, query state, and table-facing owner surfaces
+- **entry branch** -> entry route shell, `formMeta`, `formSchema`, `formData`, and submit/page-meta owner surfaces
+
+## Choose the branch that matches your question
+
+### List branch
+
+Use this branch when your question is about:
+
+- list-page schema and data consumption
+- `schemaRow`, `schemaFilter`, and `select(query)`
+- the route shell and `basic-page:blockPage` handoff
+
+Continue with [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch).
+
+### Entry branch
+
+Use this branch when your question is about:
+
+- `formMeta`, `formSchema`, and `formData`
+- `create` / `view` / `update` schema consumption
+- the route shell and `basic-pageentry:blockPageEntry` handoff
+
+Continue with [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch).
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach in depth:
+
+- how to configure or generate OpenAPI SDK output -> see [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- the broader server-data abstraction ladder -> see [Server Data](/frontend/server-data)
+- how `$apiSchema` is positioned conceptually -> see [API Schema Guide](/frontend/api-schema-guide)
+- the lower runtime of `$sdk` and schema extraction -> see [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
+- `ModelResource` internals -> see [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- the broader `rest-resource` runtime bridge -> see [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+
+Its job is only to show the practical consumer-side handoff after generation.
+
+## Where to read next
+
+- If your next question is still on the bridge/generation side, return to [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [OpenAPI SDK Guide](/frontend/openapi-sdk-guide).
+- If your next question is about the list-page branch, continue with [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch).
+- If your next question is about the entry-page branch, continue with [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch).
+- If you now want a proof-oriented layer-by-layer consumer-side workflow, continue with [Generated Contract Consumption Verify Playbook](/frontend/generated-contract-consumption-verify-playbook).
+- If the result is already wrong and you want symptom-first diagnosis, continue with [Generated Contract Consumption Debug Checklist](/frontend/generated-contract-consumption-debug-checklist).
+- If your next question is about the conceptual server-data ladder, continue with [Server Data](/frontend/server-data), [SDK Guide](/frontend/sdk-guide), and [API Schema Guide](/frontend/api-schema-guide).
+- If your next question is about the lower runtime beneath `$sdk`, continue with [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood).
+- If your next question is about the resource-owner internals, continue with [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive).
+
+## Final takeaway
+
+The cleanest way to read generated contract consumption in Zova is not to jump straight from generated OpenAPI into deep runtime internals.
+
+Instead, read the chain like this:
+
+- generated contract surfaces
+- schema and SDK access
+- stable resource owner
+- pick the list or entry branch
+- deeper runtime internals only if you still need them
+
+That reading order keeps the consumer-side contract path visible without flattening the architecture into one giant runtime story.

package/cabloy-docs/frontend/generated-contract-consumption-verify-playbook.md

@@ -0,0 +1,189 @@
+# Generated Contract Consumption Verify Playbook
+
+This page is a proof-oriented verification companion for one narrow frontend question:
+
+> after generated contract material has already crossed into Zova, what must be true at each layer before I trust the consumer-side path?
+
+Use this page together with:
+
+- [Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen)
+- [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch)
+- [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [Server Data](/frontend/server-data)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+
+> [!TIP]
+> **Generated-contract verification path**
+>
+> 1. **[Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen)** — understand the shared consumer-side path
+> 2. **[Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch)** or **[Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch)** — pick the branch that matches your case
+> 3. **[Generated Contract Consumption Verify Playbook](/frontend/generated-contract-consumption-verify-playbook)** — prove the consumer-side path layer by layer
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen), [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch), and [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch).
+
+## Why this page exists
+
+The current frontend generated-contract family already gives you:
+
+- a conceptual hub page
+- a list-branch specimen
+- an entry-branch specimen
+
+What was still missing was one proof-oriented page that tells you what must be true at each consumer layer after a change.
+
+This page fills that gap.
+
+It is not another generation/config page and not another symptom-first debug page. It is the playbook for proving the consumer-side path is correct.
+
+## Phase 1: Scope the consumer path first
+
+Before checking any details, decide what kind of question you actually have.
+
+### Shared contract-surface question
+
+Use this when the issue is still above the branch split:
+
+- does the generated contract surface exist?
+- does the module expose the expected schema/API surface at all?
+
+### List-branch question
+
+Use this when the issue is clearly about:
+
+- list-page schema/data consumption
+- `schemaRow`, `schemaFilter`, and `select(query)`
+- the route shell and `basic-page:blockPage` handoff
+
+### Entry-branch question
+
+Use this when the issue is clearly about:
+
+- `formMeta`, `formSchema`, `formData`
+- `create` / `view` / `update` schema consumption
+- the route shell and `basic-pageentry:blockPageEntry` handoff
+
+### Deeper internals question
+
+If the issue is already below these consumer-side layers, stop here and hand off to the deeper internals pages later instead of forcing this playbook to explain everything.
+
+## Phase 2: Prove the generated contract surface
+
+Start with the smallest shared consumer-side anchors.
+
+Primary anchors:
+
+- `zova/src/suite/a-training/modules/training-student/src/apiSchema/trainingStudent.ts`
+- optional direct schema consumer: `zova/src/suite/a-home/modules/home-passport/src/model/passport.ts`
+
+What to prove:
+
+- the generated schema access surface exists where expected
+- methods such as `select()`, `create()`, `view()`, `update()`, `summary()`, and `deleteForce()` still expose the intended contract slice
+- if the module depends on direct schema-driven consumption, the expected request/response schema access still resolves correctly
+
+If this phase fails, do not debug deeper page/runtime behavior yet. The consumer path is already wrong too early.
+
+## Phase 3: Prove the stable owner boundary
+
+Once the generated surface is present, prove that the module still consumes it through the correct owner boundary.
+
+Primary anchor:
+
+- `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+
+What to prove:
+
+- the module model still keeps `ModelResource` as the stable owner when the API belongs to the same resource
+- thin semantic follow-up still delegates correctly to owner-backed query/mutation helpers
+- the module did not accidentally invent a competing second owner for the same resource contract
+
+A practical rule is:
+
+> if the generated contract still belongs to the same resource, the consumer path should still stay owner-first.
+
+## Phase 4A: Prove the list branch
+
+Only enter this phase when the problem is clearly on the list-page branch.
+
+Primary anchors:
+
+- `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx`
+
+What to prove:
+
+- the list route shell resolves the expected `resource`
+- `apiSchemasSelect.sdk` still autoloads where expected
+- `schemaRow`, `schemaFilter`, and list data flow are still exposed correctly
+- `basic-page:blockPage` still becomes the deeper list runtime owner
+
+If this phase passes, the generated contract has successfully crossed into the list branch.
+
+## Phase 4B: Prove the entry branch
+
+Only enter this phase when the problem is clearly on the entry-page branch.
+
+Primary anchors:
+
+- `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entry/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockForm/controller.tsx`
+- `zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockToolbarRow/controller.tsx`
+
+What to prove:
+
+- the entry route shell resolves `resource`, `id`, and `formScene`
+- owner-level `formMeta`, `formSchema`, and `formData` still load correctly
+- `blockForm` and `blockToolbarRow` still consume the correct host context
+- the submit and page-meta path still belongs to the deeper page-entry runtime owner rather than scattered local code
+
+If this phase passes, the generated contract has successfully crossed into the entry branch.
+
+## Phase 5: Escalate only after the proof steps pass
+
+Only after the earlier proof steps already pass should you descend into:
+
+- `a-openapi` lower runtime internals
+- `ModelResource` internals
+- deeper list runtime internals
+- deeper entry runtime internals
+
+That is the boundary that keeps this page useful instead of turning it into a full runtime deep dive.
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach:
+
+- frontend OpenAPI config/generation -> see [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- the broader server-data abstraction ladder -> see [Server Data](/frontend/server-data)
+- the conceptual role of `$apiSchema` -> see [API Schema Guide](/frontend/api-schema-guide)
+- lower `a-openapi` runtime internals -> see [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood)
+- `ModelResource` internals -> see [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- deeper list runtime -> see [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive)
+- deeper entry runtime -> see [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive)
+
+Its job is only to tell you what must be true at each consumer-side layer before you trust the generated-contract path.
+
+## Where to read next
+
+- If you need the shared consumer-side overview first, return to [Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen).
+- If you need the list or entry branch specimen first, continue with [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch) or [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch).
+- If the visible result is already wrong and you want symptom-first diagnosis, continue with [Generated Contract Consumption Debug Checklist](/frontend/generated-contract-consumption-debug-checklist).
+- If the generated surface itself is missing or stale, hand off to [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [OpenAPI SDK Guide](/frontend/openapi-sdk-guide).
+- If the issue is below the current boundary, descend into [OpenAPI Runtime Under the Hood](/frontend/a-openapi-under-the-hood), [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive), [Resource List Page Deep Dive](/frontend/resource-list-page-deep-dive), or [Resource Entry Page Deep Dive](/frontend/resource-entry-page-deep-dive).
+
+## Final takeaway
+
+The cleanest way to verify a generated-contract consumer path is not to jump straight into deep runtime debugging.
+
+First prove:
+
+- the generated contract surface
+- the stable owner boundary
+- the matching list or entry branch handoff
+
+Only then descend into deeper internals if you still need them.

package/cabloy-docs/frontend/generic-component-guide.md

@@ -13,7 +13,7 @@ This matters in large TypeScript-heavy systems because generic components help k
 Example: convert component `card` into a generic component.
 
 ```bash
-npm run zova :refactor:componentGeneric card -- --module=demo-student
+npm run zova :refactor:componentGeneric card -- --module=training-student
 ```
 
 ## Why the CLI matters here

package/cabloy-docs/frontend/introduction.md

@@ -28,18 +28,22 @@ Use this page as the main frontend hub, then choose the path that matches your t
 
 ### Getting started and architecture spine
 
-Start here when you need the shortest route to the frontend mental model and startup context:
+Start here when you need the shortest route to the frontend mental model and startup context.
+
+A practical rule is:
+
+- if you need the broadest entry page, stay on this page
+- if you need help choosing a topic cluster, continue with [Frontend Source Reading Roadmap](/frontend/frontend-source-reading-roadmap)
+- if you already know the topic and want file-order guidance, continue with [Zova Source Reading Map](/frontend/zova-source-reading-map)
+
+Recommended starting set:
 
 - [Quickstart](/frontend/quickstart)
 - [Foundation](/frontend/foundation)
 - [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
-- [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison)
-- [Zova Reactivity Under the Hood](/frontend/zova-reactivity-under-the-hood)
+- [Frontend Source Reading Roadmap](/frontend/frontend-source-reading-roadmap)
 - [Zova Source Reading Map](/frontend/zova-source-reading-map)
 - [IoC and Beans](/frontend/ioc-and-beans)
-- [Behavior Guide](/frontend/behavior-guide)
-- [Modules and Suites](/frontend/modules-and-suites)
-- [Module Scope](/frontend/module-scope)
 - [Design Principles](/frontend/design-principles)
 - [Environment and Config Guide](/frontend/environment-config-guide)
 - [App Startup Guide](/frontend/app-startup-guide)
@@ -55,17 +59,33 @@ Use this path when the task is page-oriented, route-oriented, or the first time
 - [Page Params Guide](/frontend/page-params-guide)
 - [Zod Guide](/frontend/zod-guide)
 - [Page Route Guide](/frontend/page-route-guide)
+- [A-Router Guide](/frontend/a-router-guide)
 - [Route Alias Guide](/frontend/route-alias-guide)
 - [Navigation Guards Guide](/frontend/navigation-guards-guide)
+- [Zova Router Under the Hood](/frontend/zova-router-under-the-hood)
+- [Router View Hosts Guide](/frontend/router-view-hosts-guide)
+- [Router Tabs Introduction](/frontend/router-tabs-introduction)
+- [Router Tabs Overview](/frontend/router-tabs-overview)
+- [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
+- [Page Meta Guide](/frontend/page-meta-guide)
+- [Router Tabs Layout Integration](/frontend/router-tabs-layout-integration)
+- [Router Tabs vs Stack](/frontend/router-tabs-vs-stack)
+- [Router Stack Guide](/frontend/router-stack-guide)
+- [Router Tabs Route Meta Cookbook](/frontend/router-tabs-route-meta-cookbook)
 
 ### Components and UI flow
 
-Use this path when the task is about UI composition, component contracts, form architecture, form internals, form source reading, or theme work:
+Use this path when the task is about UI composition, component contracts, form or table architecture, form or table internals, form or table source reading, or theme work:
 
 - [Component Guide](/frontend/component-guide)
 - [Form Guide](/frontend/form-guide)
 - [Zova Form Under the Hood](/frontend/zova-form-under-the-hood)
 - [Zova Form Source Reading Map](/frontend/zova-form-source-reading-map)
+- [Table Guide](/frontend/table-guide)
+- [TableCell Authoring Cookbook](/frontend/table-cell-cookbook)
+- [Table + Resource CRUD Cookbook](/frontend/table-resource-crud-cookbook)
+- [Zova Table Under the Hood](/frontend/zova-table-under-the-hood)
+- [Zova Table Source Reading Map](/frontend/zova-table-source-reading-map)
 - [Component Props Guide](/frontend/component-props-guide)
 - [Component v-model Guide](/frontend/component-v-model-guide)
 - [Generic Component Guide](/frontend/generic-component-guide)
@@ -82,6 +102,8 @@ Use this path when the task is about data loading, API contracts, generated SDKs
 - [Model Architecture](/frontend/model-architecture)
 - [Model State Guide](/frontend/model-state-guide)
 - [Model Resource Owner Pattern](/frontend/model-resource-owner-pattern)
+- [Rest Resource Under the Hood](/frontend/rest-resource-under-the-hood)
+- [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map)
 - [Using ModelResource in Your Module](/frontend/model-resource-usage-guide)
 - [Resource Model Best Practices](/frontend/model-resource-best-practices)
 - [Resource Model Cookbook](/frontend/model-resource-cookbook)

package/cabloy-docs/frontend/model-architecture.md

@@ -42,6 +42,8 @@ In practice, a model often sits above `$api` and below page rendering:
 
 Read together with [Server Data](/frontend/server-data) when deciding which abstraction layer a feature should use.
 
+If your next question is how the generic lower-level model runtime works beneath these abstractions, continue with [A-Model Under the Hood](/frontend/a-model-under-the-hood).
+
 ## Relationship to TanStack Query
 
 One current-source fact is explicit: Zova Model is built on top of TanStack Query.
@@ -73,6 +75,40 @@ At source level, `@Model()` is a bean decorator factory:
 
 That file shows that a model is registered on the `model` onion/scene rather than being a special-case standalone mechanism.
 
+### A practical thin-facade example
+
+This subsection is the first layer of a small source-reading chain around same-resource model facades.
+
+Use the three related pages in this order when your question is specifically about a same-resource custom facade:
+
+1. this page for the broader role of Zova Model
+2. [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch) for the consumer-side handoff into the owner
+3. [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive) for the owner internals that make that handoff work
+
+A current example of a model staying intentionally thin is:
+
+- `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+
+That file is useful for one specific architectural point:
+
+- `ModelResource` remains the stable resource owner
+- the module model adds resource-specific methods such as `summary(id)` and `deleteForce(id)`
+- those methods still delegate to owner-level helpers such as `queryItem(...)` and `mutationItem(...)`
+
+A compact source-reading path for this pattern is:
+
+1. `zova/src/suite/a-training/modules/training-student/src/model/student.ts`
+2. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts`
+3. `zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/entry/controller.tsx`
+
+This is a good pattern when custom frontend behavior still belongs to the same resource and should continue to participate in resource-owned query, mutation, and form semantics.
+
+For the entry-branch consumer path that uses this owner-preserving pattern, continue with [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch).
+For the deeper owner internals behind `queryItem(...)`, `mutationItem(...)`, and form-derived helpers, continue with [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive).
+
+It is not the whole story of Zova Model.
+It is a narrow example of resource-owner-preserving facade design inside the broader model architecture.
+
 ## The core architectural idea
 
 The most important current-source insight is this:
@@ -172,7 +208,7 @@ They first prefix it with the model bean identity, and when `enableSelector` is
 That means a logical user key such as:
 
 ```typescript
-['list']
+['list'];
 ```
 
 becomes model-owned cache identity rather than a globally ambiguous key.
@@ -297,4 +333,4 @@ The most important architectural insight is simple:
 
 > Zova Model is a model-bean layer built on top of TanStack Query that unifies async data, local persistence, cookie state, db persistence, and in-memory state behind one model-owned runtime.
 
-Once that clicks, the model APIs stop looking like isolated helpers and start reading as one coherent state architecture.
+Once that clicks, the model APIs stop looking like isolated helpers and start reading as one coherent state architecture.

package/cabloy-docs/frontend/model-resource-cookbook.md

@@ -69,7 +69,7 @@ Typical forward-chain case:
 ### Recommended shape
 
 ```typescript
-const StudentResource = 'demo-student:student';
+const StudentResource = 'training-student:student';
 
 @Model()
 export class ModelStudent extends BeanModelBase {
@@ -83,7 +83,7 @@ export class ModelStudent extends BeanModelBase {
       id,
       action: 'summary',
       queryFn: async () => {
-        const res = await this.scope.api.demoStudent.summary({ params: { id } });
+        const res = await this.scope.api.trainingStudent.summary({ params: { id } });
         return res ?? null;
       },
       meta: {
@@ -97,7 +97,7 @@ export class ModelStudent extends BeanModelBase {
       id,
       action: 'deleteForce',
       mutationFn: async () => {
-        await this.scope.api.demoStudent.deleteForce({ params: { id } });
+        await this.scope.api.trainingStudent.deleteForce({ params: { id } });
       },
     });
   }
@@ -116,7 +116,10 @@ export class ModelStudent extends BeanModelBase {
 A custom cell or command can consume the thin facade and trigger the semantic method:
 
 ```typescript
-const modelStudent = (await ctx.bean._getBean('demo-student.model.student', true)) as ModelStudent;
+const modelStudent = (await ctx.bean._getBean(
+  'training-student.model.student',
+  true,
+)) as ModelStudent;
 const querySummary = modelStudent.summary(id);
 const { data: summary } = await querySummary.refetch();
 ```
@@ -148,7 +151,7 @@ summary(id: TableIdentity) {
     id,
     action: 'summary',
     queryFn: async () => {
-      const res = await this.scope.api.demoStudent.summary({ params: { id } });
+      const res = await this.scope.api.trainingStudent.summary({ params: { id } });
       return res ?? null;
     },
     meta: {
@@ -221,7 +224,7 @@ deleteForce(id: TableIdentity) {
     id,
     action: 'deleteForce',
     mutationFn: async () => {
-      await this.scope.api.demoStudent.deleteForce({ params: { id } });
+      await this.scope.api.trainingStudent.deleteForce({ params: { id } });
     },
   });
 }
@@ -248,7 +251,7 @@ publish(id: TableIdentity) {
     action: 'publish',
     invalidateSelect: false,
     mutationFn: async () => {
-      await this.scope.api.demoStudent.publish({ params: { id } });
+      await this.scope.api.trainingStudent.publish({ params: { id } });
     },
     onSuccess: async () => {
       await this.$$modelResource.$invalidateQueries({ queryKey: ['select'] });
@@ -388,7 +391,7 @@ batchArchive(ids: TableIdentity[]) {
   return this.$$modelResource.$useMutationData<void, TableIdentity[]>({
     mutationKey: ['batchArchive'],
     mutationFn: async ids => {
-      await this.scope.api.demoStudent.batchArchive({ ids });
+      await this.scope.api.trainingStudent.batchArchive({ ids });
     },
     onSuccess: async () => {
       await this.$$modelResource.$invalidateQueries({ queryKey: ['select'] });