cabloy 5.1.60 → 5.1.62

package/cabloy-docs/fullstack/contract-loop-playbook.md

@@ -0,0 +1,356 @@
+# Contract Loop Playbook
+
+This page is the canonical playbook for Cabloy’s bidirectional fullstack contract loop.
+
+Use it when you need to decide:
+
+- where source truth lives for a change
+- which generated handoff should be refreshed
+- which side is actually stale
+- whether the problem is source drift, generated-output drift, consumer drift, or local dependency drift
+
+## Why this playbook exists
+
+Cabloy’s fullstack collaboration is not only backend-to-frontend.
+
+The same monorepo supports two symmetric chains:
+
+- **forward chain** — backend contract emission and frontend consumption
+- **reverse chain** — frontend metadata or resource handoff and backend consumption
+
+The core model applies to both **Cabloy Basic** and **Cabloy Start**.
+
+What changes by edition is not the model itself, but the operational branch:
+
+- flavor names
+- UI-resource examples
+- generated-output paths
+- build commands
+
+So the first question is always:
+
+1. which chain am I in?
+2. which edition is active?
+
+## Shared vocabulary
+
+Use these terms consistently:
+
+- **contract loop** — the full bidirectional Vona↔Zova collaboration model
+- **forward chain** — backend contract truth flows into generated frontend consumers
+- **reverse chain** — frontend-owned metadata or resources flow into backend consumers
+- **contract source** — the authored layer that currently owns truth
+- **generated handoff** — the generated output that carries truth to the other side
+- **consumer drift** — downstream consumers no longer match current truth
+- **local dependency drift** — generated artifacts are already correct, but installed local file dependencies are still stale
+
+## The two chains
+
+### Forward chain
+
+Use the forward chain when backend-authored contract surfaces changed.
+
+Typical contract sources:
+
+- controller request or response signatures
+- DTOs
+- entity field metadata
+- validation rules
+- OpenAPI metadata
+
+Typical handoff:
+
+- Swagger or OpenAPI output
+- generated Zova SDK or schema-aware helpers
+- flavor-built REST output when the workflow depends on it
+
+Typical consumers:
+
+- generated frontend API files
+- thin frontend model facades
+- schema-driven UI
+- custom row or page actions
+
+If your issue becomes one mixed Student row-action chain rather than a pure direction question, first continue with [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions), then [Backend Metadata to Frontend Table Actions Source Reading Map](/fullstack/backend-metadata-to-frontend-table-actions-source-reading-map).
+
+If the family root and source-reading map already match your case and the visible result is still wrong, continue with [Backend Metadata to Frontend Table Actions Debug Checklist](/fullstack/backend-metadata-to-frontend-table-actions-debug-checklist).
+
+If you have already changed that mixed chain and now want to prove it layer by layer rather than diagnose a failure, continue with [Backend Metadata to Frontend Table Actions Verify Playbook](/fullstack/backend-metadata-to-frontend-table-actions-verify-playbook).
+
+### Reverse chain
+
+Use the reverse chain when frontend-owned metadata or resources changed and backend-side tooling or metadata will consume them.
+
+Typical contract sources:
+
+- frontend routes
+- frontend components
+- frontend icons
+- custom form-field or table-cell resources
+- module metadata consumed by backend `ZovaRender.*(...)` references
+
+Typical handoff:
+
+- generated metadata
+- flavor build output
+- local file dependency sync into Vona
+
+Typical consumers:
+
+- backend metadata that references frontend resources
+- backend-side tooling and type hints
+- SSR or integration paths that depend on refreshed frontend output
+
+## Decision tree
+
+Use this decision tree before editing or regenerating anything.
+
+### 1. Did backend contract truth change?
+
+Examples:
+
+- DTO shape changed
+- controller request or response changed
+- validation changed
+- OpenAPI metadata changed
+
+Then use the **forward chain**:
+
+1. change backend truth first
+2. prove emitted contract output is correct
+3. regenerate frontend consumers
+4. keep frontend follow-up thin
+5. verify consumer alignment
+
+See [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) for the end-to-end forward-chain bridge from backend-authored contract truth to generated frontend consumers.
+
+### 2. Did frontend-owned metadata or resource truth change?
+
+Examples:
+
+- a custom table cell was added
+- a custom form field was added
+- routes, components, or icons changed
+- backend metadata now references new frontend resources
+
+Then use the **reverse chain**:
+
+1. change frontend source truth
+2. regenerate metadata when applicable
+3. build the relevant frontend flavor output
+4. run `npm run deps:vona`
+5. verify backend consumers can see the refreshed handoff
+
+See [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend) for the end-to-end reverse-chain bridge from frontend-owned truth to backend-visible shared handoff.
+
+### 3. Do generated artifacts look stale?
+
+Examples:
+
+- generated SDK still reflects an old endpoint shape
+- generated metadata is missing a new resource
+- rest output did not pick up the latest source change
+
+Then diagnose **generated-output drift**:
+
+1. confirm the source layer was changed in the right place
+2. confirm the correct generation path was used
+3. regenerate instead of hand-patching
+4. verify the generated output itself before debugging downstream code
+
+### 4. Do generated artifacts already look correct, but consumers still behave stale?
+
+Examples:
+
+- generated `.zova-rest` output already contains the new keys or types
+- generated SDK already contains the new method
+- backend or frontend still behaves as if old local file packages are installed
+
+Then suspect **local dependency drift**:
+
+1. stop editing source files
+2. prove the generated handoff is already correct
+3. rerun the normal sync flow
+4. only then repair the local install state if consumers still look stale
+
+## Forward chain playbook
+
+### Stage 1: Backend contract source
+
+Author the truth in Vona first.
+
+Typical layers:
+
+- controllers
+- DTOs
+- entities
+- validation helpers
+- OpenAPI annotations
+
+Rule:
+
+- do **not** patch generated frontend consumers first when the backend owns truth
+
+### Stage 2: Emitted contract proof
+
+Before regeneration, verify the backend output is actually correct.
+
+Typical checks:
+
+- controller contract matches intent
+- DTO and validation align
+- OpenAPI output reflects the intended shape
+
+If the emitted contract is wrong, regeneration will only spread the mistake.
+
+### Stage 3: Module ownership and generation
+
+Regenerate the frontend consumer path deliberately.
+
+Typical commands include:
+
+```bash
+npm run zova :openapi:config <module-name>
+npm run zova :openapi:generate <module-name>
+```
+
+When the target is a module-local SDK, keep ownership constrained with `operations.match` so the module only generates the API surface it actually owns.
+
+### Stage 4: Thin frontend follow-up
+
+After regeneration, keep frontend follow-up thin.
+
+That means:
+
+- prefer generated contract consumers over hand-written duplicates
+- use **thin model facades** as semantic wrappers over generated APIs
+- **reuse the existing resource-owner** when the custom API still belongs to an existing resource
+
+For resource-bound custom endpoints, prefer `rest-resource.model.resource` as the state owner. A module-local model may still exist, but it should remain a semantic facade instead of becoming a second cache owner.
+
+See the downstream pattern in `.claude/skills/cabloy-contract-loop/references/resource-custom-state-pattern.md`.
+
+### Stage 5: Consumer verification
+
+Verify that generated output and frontend consumers agree.
+
+Typical checks:
+
+- generated API contains the intended methods
+- model or schema consumers still typecheck
+- UI behavior now matches the regenerated contract
+
+## Reverse chain playbook
+
+### Stage 1: Frontend-owned source truth
+
+Start from the frontend resource or metadata that actually changed.
+
+Typical layers:
+
+- bean resources
+- components
+- metadata wrappers
+- routes
+- icons
+
+Rule:
+
+- do **not** treat a frontend-owned resource handoff as frontend-only cleanup if backend consumers depend on it
+
+### Stage 2: Generated handoff
+
+Refresh the generated metadata or build output that carries the change across the boundary.
+
+Typical commands may include:
+
+```bash
+npm run zova :tools:metadata <module-name>
+```
+
+and then the relevant build path for the active edition and flavor.
+
+### Stage 3: Vona sync handoff
+
+After the frontend-generated handoff is ready, re-sync Vona’s local file dependencies.
+
+For the current **Cabloy Basic Admin** branch, the representative sequence is:
+
+```bash
+npm run build:zova:admin
+npm run deps:vona
+```
+
+If the same resource path must also be available to Web, also refresh the Web branch.
+
+For **Cabloy Start**, use the same reverse-chain logic, but resolve the Start-specific flavor names and output paths from the active Start repo before recommending commands.
+
+### Stage 4: Consumer verification
+
+Verify that backend consumers can now resolve the refreshed frontend-generated handoff.
+
+Typical checks:
+
+- backend metadata resolves the new frontend resource names
+- generated shared types now appear in backend-side consumers
+- SSR or integration behavior sees the refreshed output
+
+## Recovery path for local dependency drift
+
+Use this branch only when all of these are already true:
+
+- source truth was edited in the right place
+- generation or build output already contains the intended change
+- the normal sync flow already ran
+- consumers still behave stale
+
+Then treat the problem as **local dependency drift**.
+
+Representative recovery path:
+
+```bash
+cd vona && rm -rf node_modules && pnpm install
+```
+
+This is a recovery step, not the first response.
+
+## Verification by branch
+
+### Forward chain
+
+- backend source truth is correct
+- emitted OpenAPI or contract output is correct
+- module ownership is constrained
+- generated frontend consumer output is refreshed
+- frontend consumers and UI behavior align
+
+### Reverse chain
+
+- frontend source truth is correct
+- metadata or build output is refreshed
+- Vona dependency sync completed
+- backend consumers resolve the updated frontend-generated handoff
+
+### Local dependency drift
+
+- generated artifacts already prove the change exists
+- sync flow already ran
+- reinstall is justified only because consumers still behave stale
+
+## Tutorial map
+
+Use the tutorial series as examples of the two chains:
+
+- [Tutorial 3: Frontend Metadata Sharing](/fullstack/tutorial-3-frontend-metadata-sharing) — reverse chain, built-in metadata branch
+- [Tutorial 4: Custom Form/Table Renderers for Level](/fullstack/tutorial-4-custom-level-renderers) — reverse chain, custom resource handoff branch
+- [Tutorial 5: Backend Contract Sharing](/fullstack/tutorial-5-backend-contract-sharing) — forward chain, backend-emitted contract branch
+- [Tutorial 6: One Contract Surface, Four Uses](/fullstack/tutorial-6-one-contract-four-uses) — one field story spanning multiple contract surfaces
+
+## Related docs
+
+- [Fullstack Introduction](/fullstack/introduction)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+- [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend)
+- [Vona + Zova Integration](/fullstack/vona-zova-integration)
+- [OpenAPI SDK Guide](/frontend/openapi-sdk-guide)
+- [API Schema Guide](/frontend/api-schema-guide)

package/cabloy-docs/fullstack/edition-collaboration-differences.md

@@ -60,3 +60,9 @@ This rule prevents a common failure mode:
 - but gives the wrong operational example because it assumes the wrong edition
 
 That is exactly the kind of mistake good fullstack docs should prevent.
+
+## Where to read next
+
+- If you want the shared bidirectional model first, continue with [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+- If your current task is the forward contract bridge, continue with [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+- If your current task is the reverse metadata/resource bridge, continue with [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).

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

@@ -1,64 +1,240 @@
 # Frontend Metadata Back to Backend
 
-This page documents the reverse direction of Cabloy’s fullstack collaboration 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.
 
+> [!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:
 
-## What the frontend can generate
+- 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
 
-The current script surface shows that Zova can generate metadata and type information for areas such as:
+That means this page is the reverse-chain bridge page, not a frontend authoring cookbook and not a backend table-action runtime page.
+
+## 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
+
+This is one of the unusual strengths of the Cabloy monorepo model.
+
+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.
+
+## Backend side: Vona consumes the refreshed handoff
+
+On the backend side, Vona does not consume the raw frontend source tree directly.
+
+Instead, it consumes the refreshed handoff that the frontend generation/build path produces:
+
+- generated metadata
+- flavor build output
+- refreshed local file dependency state after `npm run deps:vona`
+
+That distinction matters.
+
+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.
+
+## Source-to-consumer reverse chain
+
+If you want the shortest accurate mental model, use this reverse chain:
+
+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
+
+That means the reverse chain is not only “build frontend and hope backend notices.”
+
+It is a deliberate handoff path with a sync step and a verification step.
+
+## Which page owns which question?
+
+Use this split to avoid reading the wrong layer too deeply.
+
+### Reverse-chain bridge and regeneration workflow
+
+Use **this page** when the real question is:
+
+- 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
+
+### Forward-chain bridge and regeneration workflow
+
+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
 
-That generated information can then be consumed by backend-side fullstack workflows and developer tooling.
+### Concrete mixed metadata/action thread
 
-## Why this is valuable
+Use [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions) when the real question is:
 
-In a separated-repo world, this information is often harder to share, easier to stale, and more annoying for AI to rediscover.
+- how backend metadata and frontend action resources cooperate in one visible table-action chain
 
-In the monorepo, the frontend-generated metadata can stay close to:
+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).
 
-- the frontend source that produced it
-- the backend workflows that consume or rely on it
-- the docs and skills that explain the collaboration path
+### Concrete implementation steps
 
-## Typical collaboration pattern
+Use these when the real question is how to author the frontend resources themselves:
 
-A practical collaboration loop often looks like this:
+- [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)
 
-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
+## 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>
+npm run build:zova:admin
+npm run deps:vona
+```
+
+If the same resource path must also be available for Web, add:
+
+```bash
+npm run build:zova:web
+npm run deps:vona
+```
+
+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
+```
+
+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 reasons about frontend-generated metadata, it should verify:
+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 or components, ask:
+When changing frontend structural resources such as routes, renderers, or shared metadata, ask:
 
 1. does metadata need regeneration?
-2. does backend-side tooling or fullstack integration rely on that metadata?
+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 and verification rather than only source edits?
+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)
 
@@ -89,7 +92,18 @@ Cabloy does not treat type sharing as backend-to-frontend only. The collaboratio
 
 This two-way contract loop reduces duplicate declarations and lets backend and frontend evolve from generated source truth instead of hand-maintained memory.
 
-For the two directions in more detail, see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
+Start with the canonical [Contract Loop Playbook](/fullstack/contract-loop-playbook), then use the directional deep dives [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk) and [Frontend Metadata Back to Backend](/fullstack/frontend-metadata-to-backend).
+
+Use the playbook to distinguish four cases clearly:
+
+- forward chain
+- reverse chain
+- consumer drift
+- local dependency drift
+
+The contract-loop model is shared across Cabloy Basic and Cabloy Start. Detect the edition to choose concrete flavor commands and generated-output paths, not to redefine the workflow model.
+
+When the reverse direction involves newly added frontend resources that backend tooling or backend metadata will consume, treat that as an operational handoff rather than a conceptual one: refresh generated frontend output, run the relevant flavor build, run `npm run deps:vona`, and if Vona still sees stale shared types, rebuild `vona/node_modules` and reinstall dependencies.
 
 ## How the fullstack system stays connected