cabloy 5.1.61 → 5.1.62

package/cabloy-docs/fullstack/frontend-metadata-to-backend.md

@@ -1,89 +1,135 @@
 # Frontend Metadata Back to Backend
 
-This page is the **reverse chain** deep dive for Cabloy’s bidirectional contract loop: frontend-generated metadata that improves backend-side development and tooling.
+This page is the **reverse chain** deep dive for Cabloy’s bidirectional contract loop.
 
 ## Why this path matters
 
 The fullstack collaboration loop in Cabloy is not one-way.
 
-In the bidirectional [Contract Loop Playbook](/fullstack/contract-loop-playbook), this page covers the **reverse chain**.
+> [!NOTE]
+> The fullstack tutorial series intentionally uses a standalone `demo-student` sandbox so readers can experiment without colliding with the repo's real suite-owned `a-training/training-student` implementation.
+> This guide focuses on the current repo implementation as its reverse-chain specimen.
+
+In the bidirectional [Contract Loop Playbook](/fullstack/contract-loop-playbook), this page covers the **reverse chain**:
+
+1. frontend-owned truth changes first
+2. frontend metadata or flavor build output refreshes the generated handoff
+3. Vona syncs that refreshed handoff through local dependency flow
+4. backend-side metadata, tooling, or type surfaces consume the result
 
 For the forward contract-bridge direction from backend OpenAPI to frontend consumption, also see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
 
-The backend does not only feed the frontend through OpenAPI. The frontend also generates information that can improve backend-side type hints and integration confidence.
+If your real question is the full row-action chain from backend metadata to visible frontend table actions, including when forward-generated API consumers and reverse-shared render resources cooperate, also see [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
 
-This is one of the unusual strengths of the Cabloy monorepo model.
+## This page’s role in the contract loop
+
+A practical split is:
+
+- fullstack docs classify which direction the contract loop is moving
+- this page explains the **reverse bridge** from frontend-owned truth to backend-visible handoff
+- frontend docs explain how to author the relevant frontend resources
+- tutorials show concrete implementation flows for specific cases
 
-## What the frontend can generate
+That means this page is the reverse-chain bridge page, not a frontend authoring cookbook and not a backend table-action runtime page.
 
-The current script surface shows that Zova can generate metadata and type information for areas such as:
+## Frontend side: Zova owns the source truth
+
+The reverse chain starts when the source of truth lives on the frontend side.
+
+Typical frontend-owned truth includes:
 
 - routes
 - components
 - icons
-- REST-related generated output
+- custom form-field renderers
+- custom table-cell renderers
+- generated frontend metadata that backend `ZovaRender.*(...)` references rely on
 
-That generated information can then be consumed by backend-side fullstack workflows and developer tooling.
+This is one of the unusual strengths of the Cabloy monorepo model.
 
-## Why this is valuable
+The frontend does not only consume backend contract truth through OpenAPI. It can also generate metadata and build output that improves backend-side development, tooling, and integration confidence.
 
-In a separated-repo world, this information is often harder to share, easier to stale, and more annoying for AI to rediscover.
+## Backend side: Vona consumes the refreshed handoff
 
-In the monorepo, the frontend-generated metadata can stay close to:
+On the backend side, Vona does not consume the raw frontend source tree directly.
 
-- the frontend source that produced it
-- the backend workflows that consume or rely on it
-- the docs and skills that explain the collaboration path
+Instead, it consumes the refreshed handoff that the frontend generation/build path produces:
 
-## Typical collaboration pattern
+- generated metadata
+- flavor build output
+- refreshed local file dependency state after `npm run deps:vona`
 
-A practical collaboration loop often looks like this:
+That distinction matters.
 
-1. define or update frontend routes/components/icons
-2. regenerate the relevant frontend metadata or REST/type output
-3. let backend-side workflows, docs, or fullstack integration logic consume the generated information
-4. verify the collaboration path still matches the active edition
+The reverse chain is not complete when the frontend source file is saved.
+It is complete only when the generated/shared handoff is refreshed and the backend side can actually see it.
 
-## Edition awareness
+## Source-to-consumer reverse chain
 
-The reverse-chain mental model applies to both Cabloy Basic and Cabloy Start.
+If you want the shortest accurate mental model, use this reverse chain:
 
-This path is especially sensitive to edition differences because Basic and Start do not expose the same frontend module and UI shape.
+1. frontend-owned truth changes in resources such as table cells, form fields, routes, or related metadata
+2. frontend metadata or flavor build output refreshes the generated handoff
+3. `npm run deps:vona` refreshes the Vona-side local dependency view
+4. backend-side metadata, tooling, and type surfaces consume the refreshed handoff
+5. if generated output already looks correct but backend consumers still behave stale, suspect **local dependency drift** rather than source-truth drift
 
-So when AI reasons about frontend-generated metadata, it should verify:
+That means the reverse chain is not only “build frontend and hope backend notices.”
 
-- which repo is active
-- which flavor is active
-- which generated output belongs to that edition
-- which concrete build and sync commands belong to that edition
+It is a deliberate handoff path with a sync step and a verification step.
 
-## Implementation checks for frontend-metadata changes
+## Which page owns which question?
 
-When changing frontend structural resources such as routes or components, ask:
+Use this split to avoid reading the wrong layer too deeply.
 
-1. does metadata need regeneration?
-2. does backend-side tooling or fullstack integration rely on that metadata?
-3. is this a Basic-specific or Start-specific workflow?
-4. should the next action be generation and verification rather than only source edits?
+### Reverse-chain bridge and regeneration workflow
 
-That keeps the reverse contract loop visible instead of accidental.
+Use **this page** when the real question is:
 
-## When backend consumes newly added frontend resources
+- how frontend-owned truth crosses into backend-visible shared output
+- which generation/build/sync steps belong to the reverse chain
+- how to diagnose generated-output drift vs local dependency drift
 
-This reverse handoff matters most when you create or change frontend resources that backend-side workflows will later consume, such as:
+### Forward-chain bridge and regeneration workflow
 
-- custom form-field renderers
-- custom table-cell renderers
-- other generated frontend metadata that backend `ZovaRender.*(...)` references depend on
+Use [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) when the real question is:
+
+- how backend-authored truth becomes generated frontend contract material
+- which OpenAPI generation and rest-build steps belong to that path
+
+### Full chain classification and drift diagnosis
+
+Use [Contract Loop Playbook](/fullstack/contract-loop-playbook) when the real question is:
+
+- which direction the contract loop is moving
+- whether the problem is source drift, generated-output drift, consumer drift, or local dependency drift
+
+### Concrete mixed metadata/action thread
+
+Use [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions) when the real question is:
+
+- how backend metadata and frontend action resources cooperate in one visible table-action chain
 
-In that case, do not stop after source edits alone. Use this representative sequence:
+If you then want the shortest file-order path through that same Student row-action thread across both sides, continue with [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map).
 
-1. regenerate frontend metadata when applicable
-2. build the relevant frontend flavor output so the shared REST/type surface is refreshed
-3. run `npm run deps:vona` so Vona re-syncs its local file dependencies
-4. if generated `.zova-rest` output already contains the expected new keys or types but backend-side consumers still look stale, rebuild `vona/node_modules` and reinstall dependencies
+### Concrete implementation steps
 
-For the current Cabloy Basic admin flow, the representative commands are:
+Use these when the real question is how to author the frontend resources themselves:
+
+- [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing)
+- [Tutorial 4: Custom Form/Table Renderers for Level](/fullstack/tutorial-4-custom-level-renderers)
+
+## Cabloy Basic workflow
+
+For Cabloy Basic, the representative reverse-chain path is:
+
+1. change the frontend-owned truth
+2. regenerate frontend metadata when applicable
+3. build the relevant frontend flavor output so the shared handoff is refreshed
+4. run `npm run deps:vona`
+5. verify backend-side consumers can now see the refreshed handoff
+
+Representative commands for the current Basic admin path are:
 
 ```bash
 npm run zova :tools:metadata <module-name>
@@ -98,10 +144,97 @@ npm run build:zova:web
 npm run deps:vona
 ```
 
-If Vona still cannot see the refreshed shared types after the normal sync flow, use this recovery path:
+A practical rule is:
+
+- treat metadata generation, flavor build, and `deps:vona` as one reverse-chain handoff
+- do not stop after the frontend source edit alone
+
+## `training-student` as a compact reverse-chain specimen
+
+A compact specimen helps make the reverse chain concrete without replaying the full tutorials.
+
+A practical example thread looks like this:
+
+1. frontend-owned truth lives in module resources such as:
+   - `zova/src/suite/a-training/modules/training-student/src/bean/tableCell.level.tsx`
+   - `zova/src/suite/a-training/modules/training-student/src/component/formFieldLevel/controller.tsx`
+2. frontend-generated metadata is refreshed and the relevant flavor build output is rebuilt
+3. `npm run deps:vona` refreshes what Vona can see from the frontend side
+4. backend-side metadata such as `vona/src/suite/a-training/modules/training-student/src/entity/student.tsx` can safely reference the refreshed frontend resource identities through `ZovaRender.*(...)`
+5. if the generated/shared output already contains the right resource keys but Vona still behaves stale, the next suspect is local dependency drift instead of missing source edits
+
+The key point is simple:
+
+> frontend-owned renderer and metadata resources become backend-visible only after the reverse-chain handoff is refreshed.
+
+## Generated-output drift vs local dependency drift
+
+A useful distinction is:
+
+### Generated-output drift
+
+This is the problem when:
+
+- the correct frontend source changed
+- but the generated metadata or flavor build output was never refreshed
+
+Typical fix:
+
+1. regenerate metadata when applicable
+2. rebuild the relevant frontend flavor output
+3. verify the generated/shared output itself before debugging Vona consumers
+
+### Local dependency drift
+
+This is the problem when:
+
+- generated `.zova-rest` or related shared output already contains the expected keys or types
+- but backend-side consumers still behave as if the old handoff is installed
+
+Typical fix:
+
+1. stop editing source files
+2. run the normal sync flow with `npm run deps:vona`
+3. if needed, rebuild `vona/node_modules` and reinstall dependencies
+
+Representative recovery path:
 
 ```bash
 cd vona && rm -rf node_modules && pnpm install
 ```
 
-The key rule is simple: if frontend-generated resources are later consumed by backend tooling or backend metadata, treat the work as a reverse fullstack handoff, not as frontend-only cleanup.
+This distinction is one of the most important practical diagnostics in the reverse chain.
+
+## Edition awareness
+
+The reverse-chain mental model applies to both Cabloy Basic and Cabloy Start.
+
+This path is especially sensitive to edition differences because Basic and Start do not expose the same frontend module and UI shape.
+
+So when AI or contributors reason about frontend-generated metadata, they should verify:
+
+- which repo is active
+- which flavor is active
+- which generated output belongs to that edition
+- which concrete build and sync commands belong to that edition
+
+For this public repo, use Cabloy Basic examples as the default operational path.
+
+## Where to read next
+
+- If your next question is about classifying the contract direction first, return to [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+- If your next question is the opposite direction, continue with [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+- If your next question is about concrete mixed metadata/action collaboration, continue with [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
+- If your next question is about the concrete frontend authoring flows behind this handoff, continue with [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing) and [Tutorial 4: Custom Form/Table Renderers for Level](/fullstack/tutorial-4-custom-level-renderers).
+
+## Implementation checks for frontend-metadata changes
+
+When changing frontend structural resources such as routes, renderers, or shared metadata, ask:
+
+1. does metadata need regeneration?
+2. does backend-side tooling or backend metadata rely on that handoff?
+3. is this a Basic-specific or Start-specific workflow?
+4. should the next action be generation, flavor build, and `deps:vona` rather than only source edits?
+5. if backend still looks stale, is the problem generated-output drift or local dependency drift?
+
+That keeps the reverse contract loop visible instead of accidental.

package/cabloy-docs/fullstack/introduction.md

@@ -33,6 +33,7 @@ Use this page as the main fullstack hub, then choose the path that matches your
 Start here when you want the shortest route to a working monorepo mental model:
 
 - [Quickstart](/fullstack/quickstart)
+- [Suites and Modules](/fullstack/suites-and-modules)
 - [CLI](/fullstack/cli)
 - [VS Code Extensions](/fullstack/vscode-extensions)
 
@@ -43,6 +44,8 @@ Use this path when the task is about how backend and frontend stay aligned insid
 - [Comparison with Other Frameworks](/fullstack/comparison-with-other-frameworks)
 - [Framework Performance](/fullstack/framework-performance)
 - [Vona + Zova Integration](/fullstack/vona-zova-integration)
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+- [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions)
 - [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
 - [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
 

package/cabloy-docs/fullstack/openapi-to-sdk.md

@@ -6,6 +6,10 @@ This page is the **forward chain** deep dive for Cabloy’s bidirectional contra
 
 In the bidirectional [Contract Loop Playbook](/fullstack/contract-loop-playbook), this page covers the **forward chain**:
 
+> [!NOTE]
+> The fullstack tutorial series intentionally uses a standalone `demo-student` sandbox so readers can experiment without colliding with the repo's real suite-owned `a-training/training-student` implementation.
+> This guide focuses on the current repo implementation as its forward-chain specimen.
+
 1. Vona emits backend API metadata through Swagger/OpenAPI
 2. Zova consumes that metadata to generate frontend SDKs and schema-aware helpers
 3. frontend pages, models, and services build on those generated contracts instead of re-declaring everything manually
@@ -24,6 +28,8 @@ That means this page is the forward-chain bridge page, not the backend authoring
 
 If the changed source is actually a frontend-owned resource that backend consumers later depend on, switch to the reverse-chain guide: [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
 
+If your real question is how one backend-owned row action becomes a visible frontend table action through metadata, page blocks, `tableCell` resources, and optionally generated API/model layers, continue with [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
+
 ## Backend side: Vona emits the contract
 
 On the backend side, OpenAPI metadata is driven by:
@@ -39,6 +45,7 @@ For the deeper backend perspective, see:
 - [OpenAPI Guide](/backend/openapi-guide)
 - [Validation Guide](/backend/validation-guide)
 - [DTO Infer and Generation](/backend/dto-infer-generation)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
 
 ## Frontend side: Zova consumes the contract
 
@@ -56,6 +63,65 @@ For the deeper frontend perspective, see:
 - [API Schema Guide](/frontend/api-schema-guide)
 - [SDK Guide](/frontend/sdk-guide)
 
+## Source-to-consumer chain
+
+If you want the shortest accurate mental model, use this forward chain:
+
+1. backend controller signatures define request and response entry surfaces
+2. backend DTO and entity fields shape named and shared contract structure
+3. validation rules and `v` helpers refine the machine-readable contract
+4. Vona emits OpenAPI output from those backend declarations
+5. Zova OpenAPI config decides which generated contract slice belongs to which frontend module
+6. frontend generation produces SDK and rest/schema-related contract output
+7. frontend code consumes the generated contract through:
+   - generated SDK methods
+   - schema-driven helpers
+   - `$sdk` and `$apiSchema`-adjacent runtime surfaces
+   - thin model facades and existing resource-owner consumers when the API belongs to an existing resource
+
+That means this bridge is not only “generate the SDK.”
+
+It is the whole path that moves backend-authored truth into frontend-usable contract material.
+
+## Which page owns which question?
+
+Use this split to avoid reading the wrong layer too deeply.
+
+### Backend authoring semantics
+
+Use these when the real question is how the backend contract is authored:
+
+- [Controller Guide](/backend/controller-guide)
+- [DTO Guide](/backend/dto-guide)
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+
+### Forward-chain bridge and regeneration workflow
+
+Use **this page** when the real question is:
+
+- how backend-authored truth crosses the stack boundary
+- which generation steps to run
+- where module ownership and regeneration decisions belong
+- how to keep frontend follow-up thin after regeneration
+
+### Frontend generation and usage setup
+
+Use these when the generated contract has already crossed the boundary and you are configuring or consuming it in Zova:
+
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)
+- [SDK Guide](/frontend/sdk-guide)
+
+### Frontend runtime and deeper consumption internals
+
+Use these when the real question is how generated contract material is consumed inside Zova runtime layers:
+
+- [A-OpenAPI Under the Hood](/frontend/a-openapi-under-the-hood)
+- [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive)
+- [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map)
+
 ## Cabloy Basic workflow
 
 In the current public monorepo, Basic-specific Zova flavors include:
@@ -66,8 +132,8 @@ In the current public monorepo, Basic-specific Zova flavors include:
 Representative frontend-side contract-generation commands include:
 
 ```bash
-npm run zova :openapi:config demo-student
-npm run zova :openapi:generate demo-student
+npm run zova :openapi:config training-student
+npm run zova :openapi:generate training-student
 cd zova && npm run build:rest:cabloyBasicAdmin
 cd zova && npm run build:rest:cabloyBasicWeb
 ```
@@ -98,6 +164,43 @@ A practical regeneration rule is:
 - if `npm run zova :openapi:generate ...` fails because the local Swagger source is unavailable, first start the backend service and confirm `http://localhost:7102/swagger/json?version=V31` is reachable before treating generation as broken
 - if the generated consumer path is already correct, but frontend behavior still looks stale, stop patching generated files and diagnose consumer drift or local dependency drift instead
 
+## `training-student` as a compact forward-chain specimen
+
+A compact specimen helps make the bridge more concrete.
+
+A practical `training-student` forward chain looks like this:
+
+1. backend contract truth changes in places such as:
+   - `controller/student.ts`
+   - `entity/student.tsx`
+   - `dto/studentCreate.tsx`
+   - `dto/studentUpdate.tsx`
+   - `dto/studentView.tsx`
+   - `dto/studentSelectReq.tsx`
+2. backend OpenAPI output changes because those controller/DTO/entity/validation surfaces changed
+3. frontend OpenAPI generation refreshes the module-owned consumer slice
+4. flavor-specific rest output is rebuilt when the workflow depends on generated rest output
+5. frontend code consumes the generated result through module-owned SDK/schema surfaces, then keeps follow-up thin with semantic wrappers or existing resource owners
+
+This is the main point of the forward chain:
+
+> backend contract truth moves first, generated handoff moves second, frontend consumers stay thin and downstream.
+
+## Thin frontend follow-up after generation
+
+After the generated contract crosses the boundary, the best frontend move is usually **not** to recreate the contract by hand.
+
+A practical split is:
+
+- use generated SDKs when the module already follows the OpenAPI-generated API-service path
+- use schema-driven helpers when the workflow is contract/schema oriented
+- use thin model facades when the UI needs business semantics over generated APIs
+- reuse the existing resource-owner when the custom API still belongs to the same resource
+
+That last point matters especially for resource-driven pages.
+
+If the endpoint still belongs to an existing business resource, prefer keeping `ModelResource` or the existing resource-owner story as the stable state owner rather than introducing a competing second owner.
+
 ## Cabloy Start workflow
 
 In the sibling private Start repo, the same collaboration idea applies, but the frontend flavor names differ.
@@ -113,6 +216,17 @@ Before documenting or automating this path for Start, confirm:
 2. the Start repo’s `package.json`
 3. the exact frontend flavor names and generated output paths
 
+## Where to read next
+
+- If your next question is still on the backend authoring side, continue with [OpenAPI Guide](/backend/openapi-guide), [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen), [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection), [DTO Guide](/backend/dto-guide), [DTO Infer and Generation](/backend/dto-infer-generation), and [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain).
+- If your next question is about frontend SDK setup and module ownership, continue with [OpenAPI SDK Guide](/frontend/openapi-sdk-guide).
+- If your next question is about what generated contract consumption looks like in one practical frontend path, continue with [Generated Contract Consumption Specimen](/frontend/generated-contract-consumption-specimen), then choose [Generated Contract Consumption: List Branch](/frontend/generated-contract-consumption-list-branch) or [Generated Contract Consumption: Entry Branch](/frontend/generated-contract-consumption-entry-branch) as needed.
+- If your next question becomes one mixed Student row-action thread spanning backend metadata, generated contract follow-up, and frontend action resources, continue with [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map).
+- If your next question is about schema-driven frontend consumption, continue with [API Schema Guide](/frontend/api-schema-guide).
+- If your next question is about the lower-level frontend runtime under generated OpenAPI/schema usage, continue with [A-OpenAPI Under the Hood](/frontend/a-openapi-under-the-hood).
+- If your next question is about resource-owner or model-level consumption after regeneration, continue with [ModelResource Internals Deep Dive](/frontend/model-resource-internals-deep-dive) and [Rest Resource Source Reading Map](/frontend/rest-resource-source-reading-map).
+- If the problem is actually about deciding which direction the contract loop is moving, return to [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
 ## Implementation checks for backend-to-frontend contract changes
 
 When changing a backend API contract, ask: