cabloy 5.1.72 → 5.1.74

package/.claude/skills/cabloy-backend-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cabloy-backend-scaffold
-description: Use this skill whenever the user wants the Vona backend path in this Cabloy repo: scaffold or extend modules, beans, controllers, services, models, entities, DTOs, CRUD resources, migrations, indexes, validation, OpenAPI-facing backend files, or backend tests. Trigger for questions about which npm run vona generator or CRUD command to use and what backend follow-up is required after generation, especially when the user mentions create:bean, CRUD, meta.version, field indexes, DTOs, or tests. Prefer it for backend-first requests, even if they may later require frontend contract regeneration. Do not use it for frontend-first Zova work or stale generated consumer diagnosis.
+description: This skill should be used when the user needs the Vona backend scaffold/extend path in this Cabloy repo, especially to choose the right `npm run vona` generator or CRUD command and the required backend follow-up after generation. Trigger most strongly on backend requests involving modules, beans, controllers, services, models, entities, DTOs, CRUD, meta.version, field indexes, validation, or backend tests. Do not use it for frontend-first Zova work, stale generated consumer diagnosis, workflow-routing questions, or master-detail / nested-detail aggregation workflows that belong in `cabloy-master-detail`.
 ---
 
 # Cabloy Backend Scaffold
@@ -40,6 +40,8 @@ If the user is still deciding a new business-domain boundary or suite/module nam
 
 If the task is really a broad cross-stack workflow, consider whether the root `cabloy-workflow` skill is the better primary router.
 
+If the request is not ordinary standalone backend scaffolding but a parent-owned detail aggregation workflow, such as master-detail, nested-detail, aggregate-only detail, standalone-capable detail, or `:tools:masterDetail`, prefer the dedicated `cabloy-master-detail` skill first.
+
 ## Step 2: Start from Vona CLI and repo entrypoints
 
 Inspect these surfaces before proposing implementation:

package/.claude/skills/cabloy-master-detail/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: cabloy-master-detail
+description: This skill should be used when the main Cabloy task is parent-owned detail aggregation: master-detail or nested-detail backend scaffolding, choosing aggregate-owned vs standalone-capable detail mode, running `:tools:masterDetail`, or preserving nested detail DTO naming and placement rules. Prefer it when the core problem is detail aggregation rather than ordinary standalone CRUD scaffolding or cross-stack contract drift.
+---
+
+# Cabloy Master-Detail
+
+Use this skill when the user wants to add, extend, analyze, or preserve a Cabloy master-detail or nested-detail backend workflow.
+
+Read the public [Master-Detail Workflow](../../../cabloy-docs/backend/master-detail-workflow.md) for the canonical operational explanation and [Master-Detail Source Reading Map](../../../cabloy-docs/backend/master-detail-source-reading-map.md) for the current source evidence. This skill is the thinner orchestration layer: it should classify the detail shape, choose the generator-first path, preserve the naming and placement invariants, and finish with the right verification path.
+
+## Goals
+
+1. detect whether the active repository is Cabloy Basic or Cabloy Start
+2. classify the request as first-level master-detail, recursive nested-detail, aggregate-only detail, standalone-capable detail, or docs/source-reading only
+3. prefer `npm run vona :tools:masterDetail` over manual scaffolding when the task is really generator-oriented
+4. preserve nested detail DTO naming and placement invariants
+5. keep aggregate vs standalone detail mode explicit
+6. finish with verification guidance that matches the actual detail shape
+
+## Step 1: Detect repo, edition, and task shape
+
+Check the repository root for these marker files:
+
+- `__CABLOY_BASIC__`
+- `__CABLOY_START__`
+
+Interpretation:
+
+- `__CABLOY_BASIC__` present → this is Cabloy Basic
+- `__CABLOY_START__` present → this is Cabloy Start
+- neither present → inspect nearby scripts and ask before making edition-specific assumptions
+
+Then classify the request into one of these entry shapes.
+
+### Shape A: first-level master-detail
+
+Use this shape when the user wants a master resource to own one detail collection, such as:
+
+- `student -> trainingRecords`
+- parent resource plus one nested child collection
+
+### Shape B: recursive nested-detail
+
+Use this shape when a detail resource itself becomes the immediate parent of another detail collection, such as:
+
+- `student -> trainingRecords -> trainingRecordSubjects`
+
+Treat this as the same master-detail pattern repeated one level lower, not as an unrelated mechanism.
+
+### Shape C: aggregate-only detail
+
+Use this shape when the detail should remain owned by the aggregate and should not keep a standalone controller/service/DTO resource surface in source.
+
+### Shape D: standalone-capable detail
+
+Use this shape when the detail must still participate in nested editing but also keep its own ordinary standalone resource surface.
+
+### Shape E: docs or source-reading only
+
+Use this shape when the user is not changing the scaffold but wants explanation, diagnosis, or source-reading guidance. In that case, anchor the answer in the two public master-detail docs instead of pretending the next step is generation.
+
+## Step 2: Start from shared entrypoints and the generator
+
+Inspect these surfaces before proposing implementation:
+
+- the repository `package.json`
+- `npm run vona`
+- `vona/packages-cli/cli-set-api/src/lib/command/tools.masterDetail.ts`
+- `vona/packages-cli/cli-set-api/src/lib/bean/cli.tools.masterDetail.ts`
+- the two public master-detail docs
+
+If the task is scaffold or generator oriented, prefer the generator path first.
+
+Typical command shape:
+
+- `npm run vona :tools:masterDetail resourceName -- [--module=] [--detailModule=] [--detailResourceName=] [--relationName=] [--fk=] [--detailMode=aggregate|standalone]`
+
+Important rule:
+
+- use canonical module relative names such as `training-student` and `training-record`
+- do not substitute package names for module names
+
+## Step 3: Preserve the current nested detail invariants
+
+### Nested detail DTO naming
+
+Keep nested detail DTOs on the `detail*` prefix so their role remains explicit.
+
+Representative examples:
+
+- `detailRecordBase`
+- `detailRecordMutate`
+- `detailRecordResItem`
+- `detailRecordView`
+- `detailRecordSubjectBase`
+- `detailRecordSubjectMutate`
+- `detailRecordSubjectResItem`
+- `detailRecordSubjectView`
+
+Do not rewrite these into ordinary child-resource CRUD names when the DTOs are really describing nested detail editing under a parent.
+
+### Nested detail DTO placement
+
+Keep nested detail DTOs beside the immediate parent DTOs that consume them.
+
+That means:
+
+- first-level detail DTOs live with the master DTOs
+- second-level detail DTOs live with the first-level parent DTOs
+- deeper levels repeat the same immediate-parent rule recursively
+
+Do not move nested detail DTOs into the child module just because the child may also have its own standalone resource surface.
+
+## Step 4: Distinguish aggregate vs standalone mode deliberately
+
+### Aggregate mode
+
+Use `--detailMode=aggregate` when the detail should remain aggregate-owned only.
+
+Preserve the source-backed rule:
+
+- aggregate mode removes or disallows standalone controller/service/DTO resource surfaces as appropriate
+
+### Standalone mode
+
+Use `--detailMode=standalone` when the detail must also keep its own ordinary resource surface.
+
+Preserve the source-backed rule:
+
+- standalone mode still uses nested `detail*` DTOs in the parent-owned editing flow
+- standalone child CRUD in the child module can keep its ordinary resource DTO names
+
+## Step 5: Inspect the specimen modules before manual follow-up edits
+
+Use the current specimen chain as the strongest current reference path:
+
+- `training-student`
+- `training-record`
+- `training-recordsubject`
+
+Especially inspect:
+
+- parent model relation wiring
+- parent service include lifecycle
+- parent create/update/view DTOs
+- sibling nested detail DTO files
+- child entity FK support
+- generated `.metadata/index.ts` exports
+
+Important rule:
+
+- do not start from hand-patching DTO placement or relation semantics until the generator path and specimen shape have been checked first
+
+## Step 6: Keep fullstack boundaries explicit
+
+This skill is primarily for backend detail aggregation.
+
+If the task later becomes a backend/frontend contract synchronization or stale generated consumer problem, the root `cabloy-contract-loop` skill may become the better primary workflow.
+
+Use this skill first when the core problem is still:
+
+- parent-owned detail aggregation
+- nested detail recursion
+- generator choice
+- aggregate vs standalone detail mode
+- nested detail DTO naming or placement in a scaffolding context
+
+## Step 7: Verification guidance
+
+Always finish with verification that matches the detail shape.
+
+Typical checks include:
+
+- confirm the parent model contains the expected `hasMany` relation
+- confirm parent service create/view/update/delete includes the nested detail relation
+- confirm parent create/update/view DTOs consume the nested detail DTOs
+- confirm nested detail DTO names still follow the `detail*` pattern
+- confirm nested detail DTOs are placed with the immediate parent DTOs that consume them
+- confirm the recursive immediate-parent rule still holds for deeper nesting
+- confirm the detail entity contains the FK field when expected
+- confirm detail schema/index support is present
+- confirm both modules’ `.metadata/index.ts` outputs reflect the expected nested detail DTOs
+- if standalone mode applies, confirm the detail module still exposes its standalone resource surface
+- if this workflow changes `meta.version.ts`, run `npm run test` so the test database is reinitialized and schema/data consistency issues surface early
+
+## Response pattern
+
+When helpful, structure the response around these points:
+
+1. detected edition
+2. detected detail shape
+3. recommended generator-first path
+4. aggregate vs standalone decision
+5. nested DTO naming and placement reminders
+6. verification steps
+
+Keep the response practical. The value of this skill is to route master-detail requests into the correct generator-first workflow while preserving the recursive ownership rules encoded by the current source.

package/.claude/skills/cabloy-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cabloy-workflow
-description: Use this skill first when a Cabloy request is about choosing the right path before implementation: whether the work belongs to Vona backend scaffolding, Zova frontend scaffolding, backend/frontend contract sync, or docs, .docs-internal, CLAUDE.md, commands, or skills; which Cabloy Basic or Cabloy Start assumptions apply; or where Cabloy guidance should live. Trigger on requests that ask to route, classify, choose a workflow, choose an edition-specific path, or decide between docs, rules, and skills. Do not use it once the task is already clearly a backend scaffold, frontend scaffold, or contract-loop job.
+description: This skill should be used when the main Cabloy problem is workflow routing before implementation: deciding between Vona backend scaffolding, Zova frontend scaffolding, contract-loop work, or docs/AI-enablement homes such as cabloy-docs, .docs-internal, CLAUDE.md, commands, or skills, including cases where Cabloy Basic vs Cabloy Start assumptions affect that routing. Trigger on requests to route, classify, choose a workflow, choose an edition-specific path, or decide where Cabloy guidance should live. Do not use it once the task is already clearly a backend scaffold, frontend scaffold, or contract-loop job.
 ---
 
 # Cabloy Workflow
@@ -176,6 +176,8 @@ Use `.claude/skills/` for:
 - CLI-first orchestration paths
 - future bundled references or deterministic helper scripts
 
+When the request is specifically about master-detail or nested-detail aggregate scaffolding, aggregate-owned detail resources, `:tools:masterDetail`, or nested detail DTO naming/placement in a scaffolding context, route to the dedicated `cabloy-master-detail` skill instead of treating it as generic backend scaffolding.
+
 ### Class-placement questions
 
 When the request is about whether a backend base class belongs in `src/lib`, `src/service`, or the global bean shorthand surface, apply the A / B1 / B2 rule.

package/.gitignore

@@ -72,6 +72,4 @@ vona/docker-compose.yml
 !/zova/packages-utils/quasar-app-extension-zova/dist
 
 vona/src/suite/cabloy-basic/modules/basic-siteadmin/assets/site
-vona/src/suite/cabloy-basic/modules/basic-siteadmin/zovaRest
 vona/src/suite/cabloy-basic/modules/basic-siteweb/assets/site
-vona/src/suite/cabloy-basic/modules/basic-siteweb/zovaRest

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 5.1.74
+
+### Features
+
+- Update related functionality and project components.
+
+### Bug Fixes
+
+- Alias MariaDB drivers correctly in the Vona build.
+- Reorder initialization to bootstrap Zova REST before other startup steps.
+- Seed Vona Zova REST dependencies before running the initial install.
+
+### Improvements
+
+- Align Zova REST workspace naming.
+- Streamline the Zova REST workspace flow.
+
+## 5.1.73
+
+### Features
+
+- Export the training record entity.
+- Update exposed functionality and related behavior.
+
+### Bug Fixes
+
+- Expand the `zova-core` type patch in `vona`.
+- Patch `zova-core` type augmentation in `vona`.
+- Watch `.tsx` file changes correctly in dev `nodemon`.
+
+### Improvements
+
+- Move the average score effect into the shared library.
+- Move the training record subject effect into the shared library.
+- Clarify `dtoClass` usage in DTO inference and master-detail documentation.
+- Add master-detail guidance and skill routing documentation.
+- Update tab rendering behavior.
+
 ## 5.1.72
 
 ### Features

package/cabloy-docs/.vitepress/config.mjs

@@ -266,6 +266,11 @@ export default defineConfig({
             { text: 'ORM Mutation Guide', link: '/backend/orm-mutation-guide' },
             { text: 'ORM Aggregate and Group Guide', link: '/backend/orm-aggregate-group-guide' },
             { text: 'Relations Guide', link: '/backend/relations-guide' },
+            { text: 'Master-Detail Workflow', link: '/backend/master-detail-workflow' },
+            {
+              text: 'Master-Detail Source Reading Map',
+              link: '/backend/master-detail-source-reading-map',
+            },
             { text: 'Transaction Guide', link: '/backend/transaction-guide' },
           ],
         },

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

@@ -148,7 +148,7 @@ A practical split is:
 - use inferred DTOs when the contract closely follows model structure or query shape
 - wrap inferred DTOs in a named DTO class when reuse or discoverability becomes more important
 
-For the inference side, see [DTO Infer and Generation](/backend/dto-infer-generation).
+Advanced inferred DTO shaping can also stay named and reusable through helper options such as `dtoClass`, especially for relation-aware contracts and nested DTO surfaces. For the inference side, see [DTO Infer and Generation](/backend/dto-infer-generation).
 
 ## Relationship to ORM and controller contracts
 

package/cabloy-docs/backend/dto-infer-generation.md

@@ -239,6 +239,44 @@ A practical rule is:
 - keep inference inline when one action needs one contract shape only once
 - wrap the inferred DTO into a named DTO class when the same relation-aware shape becomes part of a reusable public contract
 
+## Use `dtoClass` to shape inferred fields
+
+When inferred DTOs should still follow a reusable named field surface, pass `dtoClass` to the helper options.
+
+This is useful when:
+
+- the inferred DTO should reuse a DTO class instead of exposing the full model field surface
+- a nested relation needs its own mutate/view contract class
+- a master-detail contract should stay relation-aware while the allowed fields remain curated and discoverable by name
+
+A practical rule is:
+
+- use `dtoClass` when the shaping should be reusable and named
+- use `columns` when the narrowing is simple and only needed once
+
+Representative specimen from `training-student`:
+
+```typescript
+export class DtoDetailRecordMutate extends $Dto.mutate(() => ModelRecord, {
+  dtoClass: DtoDetailRecordBase,
+  include: { trainingRecordSubjects: { dtoClass: DtoDetailRecordSubjectMutate } },
+}) {}
+```
+
+This pattern keeps model-aware and relation-aware inference, but takes the field truth from the provided DTO classes.
+
+In a master-detail flow, this usually means:
+
+- a base detail DTO such as `DtoDetailRecordBase` defines the reusable field surface for the owned detail
+- a parent contract such as `DtoStudentCreate` or `DtoStudentUpdate` includes the detail through `include: { trainingRecords: { dtoClass: DtoDetailRecordMutate } }`
+- a nested detail can repeat the same rule one level lower, such as `trainingRecordSubjects: { dtoClass: DtoDetailRecordSubjectMutate }`
+
+That separation is useful because the parent DTO keeps the aggregate relation wiring, while the detail DTO family owns which detail fields are actually exposed for create, update, or view.
+
+The nested relation case matters because `dtoClass` can also be applied inside `include`, not only at the top level.
+
+The test suite also shows the behavioral difference from a one-off `columns` selection: a relation-level `dtoClass` can act like a reusable named field subset instead of repeating inline column lists.
+
 ## Aggregate and group DTO inference
 
 Summary-oriented ORM queries often benefit from inferred DTOs because the result shape is driven by `aggrs`, `groups`, and relation configuration.

package/cabloy-docs/backend/master-detail-source-reading-map.md

@@ -0,0 +1,260 @@
+# Master-Detail Source Reading Map
+
+This page is a practical source-reading companion for one narrow backend question:
+
+> if my question is no longer “how do I use the master-detail workflow?” but “which files prove the current master-detail, nested-detail, and standalone-capable detail behavior?”, where should I read first, and in what order?
+
+Use this page together with:
+
+- [Master-Detail Workflow](/backend/master-detail-workflow)
+- [Relations Guide](/backend/relations-guide)
+- [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain)
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook)
+
+> [!TIP]
+> **Master-detail reading path**
+>
+> 1. **[Master-Detail Workflow](/backend/master-detail-workflow)** — understand the public workflow and DTO rules
+> 2. **[Master-Detail Source Reading Map](/backend/master-detail-source-reading-map)** — trace the generator and specimen evidence
+>
+> **You are here:** step 2.
+
+## Why this page exists
+
+The current public docs already explain the basic master-detail workflow.
+
+What was still missing was one file-order map that proves the current implementation across:
+
+- generator behavior
+- first-level master-detail specimen
+- second-level nested-detail specimen
+- the boundary between aggregate-owned detail DTOs and standalone child-resource surfaces
+
+This page fills that gap.
+
+It is a source-order map for the current implementation, not another broad CRUD or relation concept page.
+
+## How to use this page
+
+Use this rule of thumb:
+
+1. start with the workflow page first
+2. read the generator entrypoints to understand what the scaffold promises
+3. read the specimen files in parent-to-child order
+4. stop once the behavior is clear instead of rereading the whole suite
+5. hand off to fullstack contract-loop docs only when the question becomes frontend generation or consumer drift
+
+## The shortest accurate mental model
+
+A practical master-detail implementation path looks like this:
+
+1. `:tools:masterDetail` receives the master/detail module and resource arguments
+2. the generator normalizes detail DTO names, relation names, FK names, and detail mode
+3. the generator ensures the detail module/resource shape exists
+4. it patches the detail entity/meta side
+5. it renders nested detail DTOs into the parent DTO folder
+6. it patches the master model/service/DTO/locales
+7. it refreshes metadata for both the detail module and the master module
+8. the specimen modules then demonstrate how the same pattern can repeat recursively for nested-detail
+
+That means the source-reading branch is not only “follow one CRUD module.”
+
+It starts from the generator, then confirms the shape in real specimen modules.
+
+## Generator entrypoints
+
+Start here:
+
+1. `vona/packages-cli/cli-set-api/src/lib/command/tools.masterDetail.ts`
+2. `vona/packages-cli/cli-set-api/src/lib/bean/cli.tools.masterDetail.ts`
+
+Read the command definition first when the question is:
+
+- what CLI shape is officially supported?
+- what arguments are part of the public workflow?
+
+Read `cli.tools.masterDetail.ts` first when the question is:
+
+- how are `detailMode`, relation names, FK names, and detail DTO names normalized?
+- what exactly gets scaffolded or patched?
+- how does the generator distinguish aggregate-only detail from standalone-capable detail?
+
+## What `cli.tools.masterDetail.ts` actually patches
+
+The main execution path is:
+
+1. `_prepareArgv`
+2. `_ensureDetailModule`
+3. `_ensureDetailResourceShape`
+4. `_patchDetailModule`
+5. `_renderMasterDetailDtos`
+6. `_patchMasterModule`
+7. `_refreshMetadata`
+
+A practical reading of the responsibilities is:
+
+- `_prepareArgv`
+  - defaults and validates `detailMode`
+  - derives `relationName`, `fk`, and the nested detail DTO names
+  - confirms the `detail*` naming convention comes from the generator itself
+- `_ensureDetailResourceShape`
+  - ensures the detail resource core exists
+  - branches into aggregate vs standalone handling
+- `_handleAggregateDetailMode`
+  - refuses to silently collapse an existing standalone detail surface into aggregate-only mode
+  - removes generated standalone controller/service/DTO files when aggregate-only shape is intended
+- `_handleStandaloneDetailMode`
+  - requires the standalone detail surface to remain present
+- `_patchDetailModule`
+  - adds the FK field and schema/index support on the detail side
+- `_renderMasterDetailDtos`
+  - emits `detail*` DTO files into the master module `src/dto` folder
+- `_patchMasterDto`
+  - patches `Create` / `Update` / `View` DTOs so the parent DTOs consume the sibling nested detail DTOs
+  - emits the current `include: { relationName: { dtoClass: DtoDetail... } }` wiring pattern instead of inlining long relation column lists in every parent DTO
+- `_refreshMetadata`
+  - regenerates `.metadata/index.ts` for both modules so the nested detail DTOs appear in generated contract surfaces
+
+## First-level specimen: `training-student -> training-record`
+
+Use this order:
+
+1. `vona/src/suite/a-training/modules/training-student/src/model/student.ts`
+2. `vona/src/suite/a-training/modules/training-student/src/service/student.ts`
+3. `vona/src/suite/a-training/modules/training-student/src/dto/studentCreate.tsx`
+4. `vona/src/suite/a-training/modules/training-student/src/dto/studentUpdate.tsx`
+5. `vona/src/suite/a-training/modules/training-student/src/dto/studentView.tsx`
+6. `vona/src/suite/a-training/modules/training-student/src/dto/detailRecordBase.tsx`
+7. `vona/src/suite/a-training/modules/training-student/src/dto/detailRecordMutate.tsx`
+8. `vona/src/suite/a-training/modules/training-student/src/dto/detailRecordResItem.tsx`
+9. `vona/src/suite/a-training/modules/training-student/src/dto/detailRecordView.tsx`
+10. `vona/src/suite/a-training/modules/training-student/src/.metadata/index.ts`
+11. `vona/src/suite/a-training/modules/training-record/src/entity/record.tsx`
+
+What this sequence clarifies:
+
+- `student.ts` shows the `hasMany('training-record:record', 'studentId', ...)` ownership relation
+- `service/student.ts` shows the nested include lifecycle for create/view/update/delete
+- `studentCreate.tsx`, `studentUpdate.tsx`, and `studentView.tsx` show the parent DTOs consuming sibling nested detail DTOs through `dtoClass`-based `include` wiring
+- `detailRecordBase.tsx` shows the reusable detail field surface that the mutate/view/res-item DTO family can build on
+- `detailRecordMutate.tsx` and `detailRecordView.tsx` show that first-level nested detail DTOs can also repeat the same `dtoClass` pattern for deeper nested relations
+- `detailRecord*.tsx` shows the `detail*` naming convention for first-level nested detail DTOs
+- `.metadata/index.ts` confirms those nested detail DTOs are part of the generated contract registry
+- `entity/record.tsx` shows the detail-side FK persistence field that closes the aggregate thread
+
+## Second-level specimen: `training-record -> training-recordsubject`
+
+Use this order:
+
+1. `vona/src/suite/a-training/modules/training-record/src/model/record.ts`
+2. `vona/src/suite/a-training/modules/training-record/src/service/record.ts`
+3. `vona/src/suite/a-training/modules/training-record/src/dto/recordCreate.tsx`
+4. `vona/src/suite/a-training/modules/training-record/src/dto/recordUpdate.tsx`
+5. `vona/src/suite/a-training/modules/training-record/src/dto/recordView.tsx`
+6. `vona/src/suite/a-training/modules/training-record/src/dto/detailRecordSubjectBase.tsx`
+7. `vona/src/suite/a-training/modules/training-record/src/dto/detailRecordSubjectMutate.tsx`
+8. `vona/src/suite/a-training/modules/training-record/src/dto/detailRecordSubjectResItem.tsx`
+9. `vona/src/suite/a-training/modules/training-record/src/dto/detailRecordSubjectView.tsx`
+10. `vona/src/suite/a-training/modules/training-record/src/.metadata/index.ts`
+
+What this sequence clarifies:
+
+- `record.ts` shows that `record` is itself a parent through `trainingRecordSubjects: $relation.hasMany(...)`
+- `service/record.ts` shows the include lifecycle for the second-level nested detail collection
+- `recordCreate.tsx`, `recordUpdate.tsx`, and `recordView.tsx` show the immediate parent consuming sibling `detailRecordSubject*` DTOs through the same `dtoClass`-based include pattern
+- `detailRecordSubject*.tsx` proves the recursive `detail*` naming rule
+- `.metadata/index.ts` confirms second-level nested detail DTOs are also exported into generated contract surfaces
+
+The key point is that this is not a separate mechanism.
+
+It is the same master-detail pattern repeated one level lower.
+
+## Standalone child surface vs nested detail surface
+
+This is the boundary most worth reading carefully.
+
+The `training-record` module proves that a detail can keep its own standalone resource surface while still participating as a nested detail under `student`.
+
+Read these files for the standalone-capable detail surface:
+
+- `vona/src/suite/a-training/modules/training-record/src/service/record.ts`
+- `vona/src/suite/a-training/modules/training-record/src/dto/recordCreate.tsx`
+- `vona/src/suite/a-training/modules/training-record/src/dto/recordUpdate.tsx`
+- `vona/src/suite/a-training/modules/training-record/src/dto/recordView.tsx`
+
+Then compare that with the nested detail DTOs that live in the parent module:
+
+- `vona/src/suite/a-training/modules/training-student/src/dto/detailRecordBase.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/detailRecordMutate.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/detailRecordResItem.tsx`
+- `vona/src/suite/a-training/modules/training-student/src/dto/detailRecordView.tsx`
+
+That comparison shows the intended split:
+
+- nested detail DTOs use `detail*` names in the parent module because they describe the child in its parent-owned detail role
+- standalone child CRUD uses ordinary resource DTO names in the child module because it describes the child as its own resource surface
+
+For `training-recordsubject`, the current source tree also helps prove the aggregate-only boundary.
+
+Observed source state:
+
+- `vona/src/suite/a-training/modules/training-recordsubject/src/` currently contains entity/model/meta files
+- it does **not** currently contain `src/controller/`, `src/service/`, or `src/dto/`
+- the compiled `dist/` tree still contains prior standalone declarations such as `dist/dto/subjectCreate.d.ts`
+
+A practical interpretation is:
+
+- source-level authoring for `training-recordsubject` is currently aggregate-oriented
+- nested second-level detail authoring lives in the parent `training-record` module through `detailRecordSubject*`
+- compiled artifacts alone should not be treated as the canonical source of truth when the source tree shows the current aggregate-only shape
+
+## Frontend/runtime touchpoints
+
+If your next question becomes “how does this nested detail DTO shape connect to actual detail UI/runtime behavior?”, read these areas next:
+
+- `zova/src/suite/cabloy-basic/modules/basic-details/`
+- `zova/src/suite-vendor/a-zova/modules/a-openapi/src/types/detail/`
+
+Use them to confirm:
+
+- nested detail fields are rendered through `basic-details`
+- detail lists/rows/actions have a concrete runtime contract
+- the backend DTO and metadata shape feeds a real frontend detail workflow rather than remaining only a backend convention
+
+## Suggested reading order for future source analysis
+
+Use this order when you want the shortest reliable path:
+
+1. `vona/packages-cli/cli-set-api/src/lib/command/tools.masterDetail.ts`
+2. `vona/packages-cli/cli-set-api/src/lib/bean/cli.tools.masterDetail.ts`
+3. `vona/src/suite/a-training/modules/training-student/src/model/student.ts`
+4. `vona/src/suite/a-training/modules/training-student/src/service/student.ts`
+5. `vona/src/suite/a-training/modules/training-student/src/dto/studentCreate.tsx`
+6. `vona/src/suite/a-training/modules/training-student/src/dto/studentUpdate.tsx`
+7. `vona/src/suite/a-training/modules/training-student/src/dto/studentView.tsx`
+8. `vona/src/suite/a-training/modules/training-record/src/model/record.ts`
+9. `vona/src/suite/a-training/modules/training-record/src/service/record.ts`
+10. `vona/src/suite/a-training/modules/training-record/src/dto/recordCreate.tsx`
+11. `vona/src/suite/a-training/modules/training-record/src/dto/recordUpdate.tsx`
+12. `vona/src/suite/a-training/modules/training-record/src/dto/recordView.tsx`
+13. both module `.metadata/index.ts` files
+14. frontend `basic-details` and `a-openapi` detail runtime types if the question crosses into UI/runtime behavior
+
+## Where to read next
+
+- If you need the public workflow and naming/placement rules, return to [Master-Detail Workflow](/backend/master-detail-workflow).
+- If you need broader ORM relation semantics, continue with [Relations Guide](/backend/relations-guide).
+- If you want one concrete backend module wiring page before returning to detail-specific reading, continue with [Backend Resource/Module Contract Chain](/backend/backend-resource-module-contract-chain).
+- If the next question becomes frontend consumer generation or backend/frontend drift, continue with [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## Final takeaway
+
+The cleanest way to read the current master-detail implementation is not to stay only at the workflow level and not to read every file in the suite.
+
+Start from the CLI entrypoint, confirm what the generator promises, trace the first-level specimen, then trace the recursive second-level specimen.
+
+That path is enough to prove the three current capabilities:
+
+- master-detail
+- nested-detail
+- a detail resource that can remain aggregate-owned only or also keep its own standalone resource surface