cabloy 5.1.61 → 5.1.62

package/cabloy-docs/backend/backend-source-reading-verify-playbook.md

@@ -0,0 +1,166 @@
+# Backend Source Reading Verify Playbook
+
+This page is a proof-oriented verification companion for one narrow backend question:
+
+> after I have chosen a backend source-reading path, what must be true at each backend layer before I trust it?
+
+Use this page together with:
+
+- [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen)
+- [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map)
+- [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection)
+- [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+> [!TIP]
+> **Backend source-reading verification path**
+>
+> 1. **[Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)** — choose the backend source-reading branch
+> 2. **[Vona Source Reading Map](/backend/vona-source-reading-map)**, **[Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)**, or the emission family — inspect the relevant branch/specimen first
+> 3. **[Backend Source Reading Verify Playbook](/backend/backend-source-reading-verify-playbook)** — prove the backend-side path layer by layer
+>
+> **You are here:** step 3.
+> **Previous recommended pages:** [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap) and [Vona Source Reading Map](/backend/vona-source-reading-map).
+
+## Why this page exists
+
+The current backend source-reading family already gives you:
+
+- a chooser page
+- a broad file-order map
+- a module-wiring specimen
+- an emission specimen/map/inspection family
+
+What was still missing was one proof-oriented page that tells you what must be true at each backend layer before you trust the path.
+
+This page fills that gap.
+
+It is not another concept page and not another file-order map. It is the verification playbook for backend source-reading.
+
+## Phase 1: Scope the backend branch first
+
+Before checking details, decide which backend branch you are actually in.
+
+### Module-wiring branch
+
+Use this branch when the question is about:
+
+- how controller, service, model, entity, and DTO layers still connect
+- whether generated metadata still reflects the intended module/resource shape
+- whether the current module-wiring specimen still matches the real code path
+
+### Contract-emission branch
+
+Use this branch when the question is about:
+
+- whether controller + DTO + entity metadata still shape the emitted backend contract correctly
+- whether generated metadata records and emitted OpenAPI output still agree
+- whether the backend side is ready to hand off into the forward bridge
+
+### Emitted-output inspection only
+
+Use this branch when the input-side source path already looks correct and you only need to verify the emitted output surface itself.
+
+## Phase 2: Prove the shared generated/module anchor surfaces
+
+Start with the smallest shared backend anchors.
+
+Primary anchors:
+
+- `vona/src/suite/a-training/modules/training-student/src/index.ts`
+- `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+
+What to prove:
+
+- the module entry still re-exports the generated surfaces where expected
+- the generated registration surface still exposes the expected controller/model/service/entity/DTO path
+- the current source-reading/specimen docs still line up with the actual generated module surface
+
+If this phase fails, do not continue into either branch. The backend source-reading path is already wrong too early.
+
+## Phase 3A: Prove the module-wiring branch
+
+Only enter this phase when the question is clearly about module wiring.
+
+Primary anchors:
+
+- `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/service/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/model/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/entity/student.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/*.tsx`
+
+What to prove:
+
+- controller, service, model, entity, and DTO layers still connect as expected
+- the generated metadata still reflects the intended module/resource chain
+- the current specimen path still matches the actual backend code path
+
+If this phase passes, the backend source-reading path is correct enough to trust the module-wiring branch.
+
+## Phase 3B: Prove the contract-emission branch
+
+Only enter this phase when the question is clearly about emitted backend contract truth.
+
+Primary anchors:
+
+- `vona/src/suite/a-training/modules/training-student/src/controller/student.ts`
+- `vona/src/suite/a-training/modules/training-student/src/dto/studentSummary.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+- emitted output surface already used in docs:
+  - `http://localhost:7102/swagger/json?version=V31`
+
+What to prove:
+
+- the controller action still declares the intended emitted path and response contract
+- the named DTO still matches the intended emitted response shape
+- generated metadata records still line up with emitted route/DTO presence
+- the emitted output surface itself still reflects those backend inputs
+
+If this phase passes, the backend emission branch is correct enough to hand off to the forward bridge.
+
+## Phase 4: Escalate only after the backend proof steps pass
+
+Only after the earlier proof steps pass should you descend into:
+
+- fullstack forward-bridge docs
+- frontend generation/consumption docs
+- deeper consumer-side verification
+
+That is the boundary that keeps this page backend-side and source-reading focused.
+
+## What this page does not re-explain
+
+This page deliberately does **not** re-teach:
+
+- the conceptual backend overview -> see [Backend (Vona)](/backend/introduction)
+- controller/service/model/entity/DTO concept guides
+- the broad chooser and broad file-order map -> see [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap) and [Vona Source Reading Map](/backend/vona-source-reading-map)
+- the module-wiring specimen -> see [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- the emission family pages -> see [OpenAPI Guide](/backend/openapi-guide), [Backend Contract Emission Specimen](/backend/backend-contract-emission-specimen), [Backend Contract Emission Source Reading Map](/backend/backend-contract-emission-source-reading-map), and [Backend Contract Emission Output Inspection](/backend/backend-contract-emission-output-inspection)
+- the fullstack forward bridge -> see [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk)
+
+Its job is only to tell you what must be true at each backend layer before you trust the source-reading path.
+
+## Where to read next
+
+- If you need the chooser page first, return to [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap).
+- If you need the broad file-order map first, continue with [Vona Source Reading Map](/backend/vona-source-reading-map).
+- If the backend result already looks wrong and you want symptom-first diagnosis, continue with [Backend Source Reading Debug Checklist](/backend/backend-source-reading-debug-checklist).
+- If the backend path is now proven and you want the downstream bridge, hand off to [Backend OpenAPI to Frontend SDK](/fullstack/openapi-to-sdk).
+- If the backend truth is proven but the real problem is one mixed Student row-action chain, hand off to [Backend Metadata to Frontend Table Actions](/fullstack/backend-metadata-to-frontend-table-actions).
+- If you are still unsure which contract direction or drift type actually applies, return to [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## Final takeaway
+
+The cleanest way to verify a backend source-reading path is not to jump straight into downstream frontend generation or the broadest concept docs.
+
+First prove:
+
+- the shared generated/module surface
+- the relevant module-wiring or emission branch
+- the emitted output surface when needed
+
+Only then hand off to the fullstack bridge if you still need the downstream path.

package/cabloy-docs/backend/bean-scene-authoring.md

@@ -183,7 +183,7 @@ Representative generated output:
 ```typescript
 declare module 'vona' {
   export interface IBeanRecordGeneral {
-    'demo-student.service.student': ServiceStudent;
+    'training-student.service.student': ServiceStudent;
   }
 }
 ```
@@ -248,8 +248,8 @@ Representative generated service output includes:
 
 ```typescript
 export interface ServiceStudent {
-  get $beanFullName(): 'demo-student.service.student';
-  get $onionName(): 'demo-student:student';
+  get $beanFullName(): 'training-student.service.student';
+  get $onionName(): 'training-student:student';
 }
 ```
 
@@ -272,7 +272,7 @@ Keep these two tasks separate.
 Example:
 
 ```bash
-npm run vona :create:bean service student -- --module=demo-student
+npm run vona :create:bean service student -- --module=training-student
 ```
 
 This uses an already-defined scene.

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

@@ -10,10 +10,10 @@ This is important because some business logic is not point-to-point background w
 
 ## Create a broadcast
 
-Example: create a broadcast named `echo` in module `demo-student`.
+Example: create a broadcast named `echo` in module `training-student`.
 
 ```bash
-npm run vona :create:bean broadcast echo -- --module=demo-student
+npm run vona :create:bean broadcast echo -- --module=training-student
 ```
 
 ## Broadcast definition
@@ -78,7 +78,7 @@ Representative pattern:
 ```typescript
 config.onions = {
   broadcast: {
-    'demo-student:echo': {
+    'training-student:echo': {
       instance: true,
       transaction: true,
     },

package/cabloy-docs/backend/cli.md

@@ -87,31 +87,31 @@ npm run vona :create:module moduleName -- [--suite=]
 ### Create a service bean
 
 ```bash
-npm run vona :create:bean service student -- --module=demo-student
+npm run vona :create:bean service student -- --module=training-student
 ```
 
 ### Create a model bean
 
 ```bash
-npm run vona :create:bean model student -- --module=demo-student
+npm run vona :create:bean model student -- --module=training-student
 ```
 
 ### Create an entity bean
 
 ```bash
-npm run vona :create:bean entity student -- --module=demo-student
+npm run vona :create:bean entity student -- --module=training-student
 ```
 
 ### Create a DTO bean
 
 ```bash
-npm run vona :create:bean dto studentCreate -- --module=demo-student
+npm run vona :create:bean dto studentCreate -- --module=training-student
 ```
 
 ### Create a startup bean
 
 ```bash
-npm run vona :create:bean startup log -- --module=demo-student
+npm run vona :create:bean startup log -- --module=training-student
 ```
 
 These examples show that the CLI is tightly connected to module boundaries and bean scenes such as service, model, entity, DTO, and startup.
@@ -129,7 +129,7 @@ Some backend bean scenes expose more than one scaffold template.
 In those cases, use `--boilerplate=...` to select a named variant:
 
 ```bash
-npm run vona :create:bean ssrMenu menuTest -- --module=demo-student --boilerplate=web
+npm run vona :create:bean ssrMenu menuTest -- --module=training-student --boilerplate=web
 ```
 
 A practical rule is:
@@ -147,10 +147,10 @@ Not every backend resource is created through bean scenes.
 Representative initializer commands include:
 
 ```bash
-npm run vona :init:constant demo-student
-npm run vona :init:types demo-student
-npm run vona :init:lib demo-student
-npm run vona :init:asset static -- --module=demo-student
+npm run vona :init:constant training-student
+npm run vona :init:types training-student
+npm run vona :init:lib training-student
+npm run vona :init:asset static -- --module=training-student
 ```
 
 A practical distinction is:
@@ -160,7 +160,7 @@ A practical distinction is:
 
 A practical helper-placement rule is:
 
-- if a backend module needs reusable pure helper functions, initialize `src/lib` with `npm run vona :init:lib demo-student`
+- if a backend module needs reusable pure helper functions, initialize `src/lib` with `npm run vona :init:lib training-student`
 - place those shared helpers under `src/lib` and export shared entrypoints from `src/lib/index.ts`
 - if the logic needs container-managed runtime behavior, do not force it into `src/lib`; re-evaluate `src/service` or another bean scene instead
 
@@ -196,3 +196,12 @@ When creating backend code:
 4. only then make minimal follow-up edits
 
 This reduces unnecessary manual scaffolding and keeps the implementation aligned with Vona conventions.
+
+## Where to read next
+
+If your next question is no longer only which command to run, but which backend source files to inspect after the CLI step, continue with:
+
+- [Backend Scripts](/backend/scripts)
+- [Backend Source Reading Roadmap](/backend/backend-source-reading-roadmap)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)

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

@@ -12,10 +12,10 @@ That matters because backend capabilities often need both:
 
 ## Initialize the config skeleton
 
-Example: initialize config for module `demo-student`.
+Example: initialize config for module `training-student`.
 
 ```bash
-npm run vona :init:config demo-student
+npm run vona :init:config training-student
 ```
 
 This gives the module its own config file under the module’s config area.
@@ -53,7 +53,7 @@ Cross-module config access uses the cross-module scope surface.
 Representative pattern:
 
 ```typescript
-console.log(this.$scope.demoStudent.config.title);
+console.log(this.$scope.trainingStudent.config.title);
 ```
 
 A practical distinction is:
@@ -122,7 +122,7 @@ Representative pattern:
 
 ```typescript
 config.modules = {
-  'demo-student': {
+  'training-student': {
     title: 'Hello World!!',
   },
 };

package/cabloy-docs/backend/controller-aop-guide.md

@@ -23,9 +23,9 @@ Middleware is used for request-path behavior that wraps execution before and aft
 Representative CLI generation patterns from the legacy workflow include:
 
 ```bash
-npm run vona :create:bean middlewareSystem logger -- --module=demo-student
-npm run vona :create:bean middleware logger -- --module=demo-student --boilerplate=global
-npm run vona :create:bean middleware logger -- --module=demo-student
+npm run vona :create:bean middlewareSystem logger -- --module=training-student
+npm run vona :create:bean middleware logger -- --module=training-student --boilerplate=global
+npm run vona :create:bean middleware logger -- --module=training-student
 ```
 
 These commands all go through the shared `:create:bean` entrypoint, but they target different middleware scopes and boilerplates.
@@ -45,13 +45,13 @@ This is where Vona places concerns such as not-found handling, request override
 ### Representative local usage
 
 ```typescript
-@Aspect.middleware('demo-student:logger')
+@Aspect.middleware('training-student:logger')
 ```
 
 ### Representative global usage
 
 ```typescript
-@Aspect.middlewareGlobal('demo-student:logger', { prefix: 'elapsed' })
+@Aspect.middlewareGlobal('training-student:logger', { prefix: 'elapsed' })
 ```
 
 ### Representative built-in usage
@@ -85,7 +85,7 @@ Typical jobs include:
 ### Representative local usage
 
 ```typescript
-@Aspect.guard('demo-student:admin')
+@Aspect.guard('training-student:admin')
 ```
 
 ### Representative built-in usage
@@ -120,7 +120,7 @@ Typical jobs include:
 ### Representative local usage
 
 ```typescript
-@Aspect.interceptor('demo-student:logger')
+@Aspect.interceptor('training-student:logger')
 ```
 
 ### Representative built-in usage
@@ -140,7 +140,7 @@ Pipes transform or validate request values before they reach controller logic.
 ### Representative local pipe usage
 
 ```typescript
-@Aspect.pipe('demo-student:number')
+@Aspect.pipe('training-student:number')
 ```
 
 ### Argument pipe pattern
@@ -150,7 +150,7 @@ Argument pipes are usually created from a local pipe:
 ```typescript
 import { createArgumentPipe } from 'vona-module-a-aspect';
 
-export const ArgNumber = createArgumentPipe('demo-student:number');
+export const ArgNumber = createArgumentPipe('training-student:number');
 ```
 
 Used on a controller parameter:
@@ -191,7 +191,7 @@ This is where request-path error customization becomes explicit.
 ### Representative local usage
 
 ```typescript
-@Aspect.filter('demo-student:test')
+@Aspect.filter('training-student:test')
 ```
 
 ### Built-in filter

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

@@ -18,12 +18,12 @@ A useful contract-loop mental model is:
 
 ## Create a controller
 
-Example: create a controller named `student` in module `demo-student`.
+Example: create a controller named `student` in module `training-student`.
 
 ### CLI command
 
 ```bash
-npm run vona :create:bean controller student -- --module=demo-student
+npm run vona :create:bean controller student -- --module=training-student
 ```
 
 ## Controller definition
@@ -345,3 +345,13 @@ The safest workflow is:
 3. add `@Web`, `@Arg`, validation, and OpenAPI metadata in the same style
 4. choose deliberately whether response wrapper defaults should stay in place
 5. verify the resulting routes and response conventions
+
+## Where to read next
+
+If your next question is how the HTTP-facing controller layer connects to the rest of one real backend module, continue with:
+
+- [Service Guide](/backend/service-guide)
+- [DTO Guide](/backend/dto-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)

package/cabloy-docs/backend/crud-workflow.md

@@ -8,18 +8,22 @@ CRUD is one of the clearest places where Cabloy’s CLI-first philosophy pays of
 
 Instead of creating controller, service, model, entity, DTO, metadata, locale, and test files by hand, Vona already provides generators that create the initial backend thread.
 
+> [!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, by contrast, uses the current repo implementation as its compact specimen.
+
 ## Generate a CRUD skeleton
 
-Example: generate a CRUD workflow for `student` in module `demo-student`.
+Example: generate a CRUD workflow for `student` in module `training-student`.
 
 ```bash
-npm run vona :tools:crud student -- --module=demo-student
+npm run vona :tools:crud student -- --module=training-student
 ```
 
 A lighter variant also exists:
 
 ```bash
-npm run vona :tools:crudBasic student -- --module=demo-student
+npm run vona :tools:crudBasic student -- --module=training-student
 ```
 
 This is important because the repo already encodes both the full CRUD thread and a lighter CRUD-basic workflow in the CLI surface.

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

@@ -16,10 +16,10 @@ That is why DTO design should be treated as a framework concern instead of only
 
 ## Create a DTO
 
-Example: create a DTO named `studentCreate` in module `demo-student`.
+Example: create a DTO named `studentCreate` in module `training-student`.
 
 ```bash
-npm run vona :create:bean dto studentCreate -- --module=demo-student
+npm run vona :create:bean dto studentCreate -- --module=training-student
 ```
 
 ## DTO definition
@@ -172,3 +172,13 @@ When creating DTOs:
 4. avoid re-declaring fields manually if Vona’s DTO-generation or class-derivation tools already solve the problem
 5. treat DTO design as part of the contract between backend handlers, models, and frontend integration
 6. choose explicit DTOs when named long-lived contracts matter, and inferred DTOs when the model/query shape already expresses the contract clearly
+
+## Where to read next
+
+If your next question is how named DTO artifacts fit into one complete backend module specimen, continue with:
+
+- [DTO Infer and Generation](/backend/dto-infer-generation)
+- [Controller Guide](/backend/controller-guide)
+- [OpenAPI Guide](/backend/openapi-guide)
+- [Vona Source Reading Map](/backend/vona-source-reading-map)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)