cabloy 5.1.124 → 5.1.126

package/cabloy-docs/backend/backend-contract-emission-specimen.md

@@ -101,8 +101,8 @@ The next source to read is:
 Representative source facts:
 
 - `@Dto<IDtoOptionsStudentSummary>()`
-- fields such as `id`, `name`, `mobile`, `level`, `levelTitle`, `description`, `descriptionLength`, and `summaryText`
-- `@Api.field(...)` metadata on each field
+- the `ModelStudent` projection supplies `id`, `name`, `mobile`, `level`, and `description`
+- direct `@Api.field(...)` metadata declares the computed `levelTitle`, `descriptionLength`, and `summaryText` fields
 
 This file answers the second emission question:
 

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

@@ -148,7 +148,9 @@ 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
 
-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).
+When stable Entity, Model, relation, or query truth already exists, prefer inference first: use `$Dto.*` with `columns`, `include`, or `dtoClass` to define the projection; use `@Dto({ fields })` with `$makeMetadata(...)` for metadata-only differences or `$makeSchema(...)` for schema and validation differences; add an `@Api.field(...)` member only for a genuinely new field absent from the inferred contract. Keep an explicit DTO as a deliberate fallback when no suitable upstream truth exists or the inferred composition is less clear.
+
+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. `$Dto.get(...)` otherwise keeps the complete model-aware read shape by default; use `columns` or `dtoClass` for a genuine business projection, not merely to remove `iid` or `deleted`. For the canonical authoring sequence, see [Default-first three-layer DTO authoring](/backend/dto-infer-generation#default-first-three-layer-dto-authoring) and [Default read shape versus a public projection](/backend/dto-infer-generation#default-read-shape-versus-a-public-projection).
 
 ## Relationship to ORM and controller contracts
 
@@ -166,12 +168,13 @@ That means DTO design should often be read together with:
 
 When creating DTOs:
 
-1. prefer reuse through mapped-class helpers when the shape is derived from existing classes
-2. keep DTO validation and OpenAPI concerns aligned through `@Api.field`
-3. decide whether the contract should be an explicit DTO class or an inferred DTO
-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
+1. check whether an Entity, Model, relation, or query shape already provides suitable upstream contract truth
+2. define the inferred projection before redeclaring fields: choose the `$Dto.*` helper and, where needed, `columns`, `include`, or `dtoClass`
+3. use `$makeMetadata(...)` for metadata-only refinement and `$makeSchema(...)` for schema or validation refinement of an inferred field
+4. use `@Api.field(...)` for a genuinely new field, not as a second declaration of an inferred field
+5. keep DTO validation and OpenAPI concerns aligned, and keep the final structure-defining schema last when using schema-like composition
+6. decide whether the contract should remain inferred, be wrapped in a named inferred DTO, or deliberately fall back to an explicit DTO
+7. treat DTO design as part of the contract between backend handlers, models, and frontend integration
 
 ## Where to read next
 

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

@@ -94,6 +94,16 @@ A practical mental model is:
 
 This matters because different ORM operations naturally produce different API contracts.
 
+## Default read shape versus a public projection
+
+`$Dto.get(() => ModelX)` defaults to the complete model-aware Entity read shape, including inherited framework fields such as `iid` and `deleted` when the Entity defines them. This is the ordinary read baseline, not an automatic public-payload minimization policy.
+
+Use `columns` when an endpoint genuinely needs a smaller one-off business, query, or response projection. Use `dtoClass` when that curated read surface is named and reusable, especially for nested relation contracts. Do not add either solely to remove `iid` or `deleted` from an otherwise complete `$Dto.get(...)` shape.
+
+This differs from top-level `$Dto.create(...)` and `$Dto.update(...)`. Their default omission of identity, active-instance, soft-deletion, and lifecycle fields establishes a write-input authorization boundary: callers must not supply those framework-owned values. That write policy does not imply that ordinary read DTOs need the same narrowing.
+
+A narrowed DTO or emitted OpenAPI schema declares the supported contract, but does not by itself prove that an already-built HTTP response object is projected or stripped at runtime. When actual payload minimization is required, deliberately shape the returned data or apply a verified response-output policy, then verify the action response. See [Serialization Guide](/backend/serialization-guide) for response transformation behavior.
+
 ## When inference should replace handwritten DTOs
 
 A practical rule is:
@@ -106,12 +116,117 @@ A practical reading takeaway is:
 
 > the best default is often not “handwritten DTO or no DTO.” It is “named DTO class backed by the right inferred helper.”
 
+## Default-first three-layer DTO authoring
+
+The three DTO shapes above classify the public artifact: explicit named DTO, inline inference, or a named class that wraps inference. They do not describe how to author an inferred contract.
+
+When an Entity, Model, relation, or query shape already owns stable contract truth, start from that truth instead of redeclaring its fields. Define the DTO projection first, then add only the smallest DTO-local difference. This preserves inherited validation, titles, OpenAPI metadata, and render metadata wherever they still apply.
+
+### Layer 1: project upstream truth
+
+Use the operation-appropriate `$Dto.*` helper to establish the baseline contract. Then choose the narrowest projection mechanism:
+
+- use the default inferred shape when all relevant model-aware fields belong in the DTO
+- use `columns` for a simple local field subset, including the exclusion of server-owned fields
+- use `include` to bring a relation-aware shape into the DTO
+- use `dtoClass` when a top-level or nested relation needs a reusable, named field surface
+
+For example, `DtoStudentSelectReq` starts from an Entity-backed query projection:
+
+```typescript
+export class DtoStudentSelectReq extends $Dto.queryPage(EntityStudent, [
+  'name',
+  'level',
+  'createdAt',
+]) {}
+```
+
+A relation-aware DTO can use `columns` and `include` to curate its baseline without restating each field decorator:
+
+```typescript
+export class DtoDetailRecordBase extends $Dto.get(() => ModelRecord, {
+  columns: ['id', 'name', 'subjectCount', 'totalScore', 'averageScore'],
+  include: { trainingRecordSubjects: true },
+}) {}
+```
+
+Use `dtoClass` when that curated surface is itself reusable. For example, a detail mutate DTO can take its field surface from `DtoDetailRecordBase`, and a parent create DTO can include that named detail contract:
+
+```typescript
+export class DtoDetailRecordMutate extends $Dto.mutate(() => ModelRecord, {
+  dtoClass: DtoDetailRecordBase,
+  include: { trainingRecordSubjects: { dtoClass: DtoDetailRecordSubjectMutate } },
+}) {}
+
+export class DtoStudentCreate extends $Dto.create(() => ModelStudent, {
+  include: { trainingRecords: { dtoClass: DtoDetailRecordMutate } },
+}) {}
+```
+
+When a field genuinely does not belong to an API's business read or write contract, exclude it through the projection; do not rely on visibility metadata to hide a field that the API must not accept or return. Do not add a projection solely to remove framework read fields such as `iid` or `deleted` from an otherwise complete `$Dto.get(...)` shape; see [Default read shape versus a public projection](#default-read-shape-versus-a-public-projection).
+
+### Layer 2: overlay metadata or refine the schema
+
+For a field already supplied by the projection, use the `fields` map on `@Dto(...)` rather than redeclaring the property:
+
+- use `$makeMetadata(...)` when only field metadata changes, such as title, order, visibility, serialization, or render behavior; the inherited schema and validation remain authoritative
+- use `$makeSchema(...)` when optionality, validation, enum members, preprocess/transform behavior, or another schema structure must change; it replaces or refines the runtime field schema while preserving the framework's inherited OpenAPI metadata merge
+
+`DtoStudentSelectReq` demonstrates schema refinement for query input:
+
+```typescript
+@Dto({
+  fields: {
+    name: $makeSchema(v.optional(), z.string()),
+    level: $makeSchema(v.optional(), z.number()),
+    createdAt: $makeSchema(v.filterTransform('a-web:dateRange'), v.optional(), z.string()),
+  },
+})
+export class DtoStudentSelectReq extends $Dto.queryPage(EntityStudent, [
+  'name',
+  'level',
+  'createdAt',
+]) {}
+```
+
+`$makeSchema(...)` applies schema-like arguments right-to-left. Keep the final structure-defining schema, such as `z.string()`, `z.number()`, `v.object(...)`, or `v.array(...)`, last in authoring order. Treat optionality, nullability, defaults, preprocess/transform wrappers, objects, and arrays as structure-shaping rather than metadata-only, and verify emitted schema/OpenAPI output after changing them.
+
+`@Dto({ fields })` changes the runtime contract and metadata. It does not rewrite the TypeScript property type inferred from the `$Dto.*` base class. Do not add a duplicate `declare` field or a second field decorator solely to mirror a runtime schema restriction unless a separate static contract is genuinely required and is type-compatible with the inferred base.
+
+### Layer 3: add contract-only fields
+
+Declare a class member with `@Api.field(...)` only when the field is absent from the inferred projection. Typical examples are serializer-produced response fields, operation-local helper fields, or a separate nested representation.
+
+```typescript
+export class DtoStudentCreate extends $Dto.create(() => ModelStudent, {
+  include: { trainingRecords: { dtoClass: DtoDetailRecordMutate } },
+}) {
+  @Api.field(v.optional(), v.array(DtoDetailRecordResItem))
+  _trainingRecords?: DtoDetailRecordResItem[];
+}
+```
+
+Do not manually redeclare an inferred field merely to adjust its title, renderer, validation, or schema. Use Layer 2 instead.
+
+### When to use an explicit DTO from scratch
+
+Inference first is a default strategy, not a requirement to force every DTO through `$Dto.*`. Use an explicit DTO deliberately when no stable upstream Entity, Model, relation, or query shape is suitable, for example:
+
+- authentication, captcha, or behavior-focused commands
+- webhook and third-party protocol payloads
+- aggregate commands assembled from unrelated resources
+- a public contract that must stay intentionally decoupled from persistence structure
+
+If the inferred baseline would require pervasive exceptions or no longer makes the contract clearer, an explicit DTO is the better design.
+
 ## `training-student` as the decision specimen
 
 The current `training-student` module is a strong specimen because it shows several different DTO choices in one compact family.
 
 Relevant source files include:
 
+- `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/studentCreate.tsx`
 - `vona/src/suite/a-training/modules/training-student/src/dto/studentUpdate.tsx`
 - `vona/src/suite/a-training/modules/training-student/src/dto/studentView.tsx`
@@ -163,10 +278,12 @@ Representative source facts:
 
 This makes it a strong specimen of a **query DTO that still wraps inference, but adds operation-specific shaping**.
 
+Its `fields` entries use `$makeSchema(...)` because the query contract changes the projected fields' runtime schema: query values become optional, `level` is normalized before validation, and `createdAt` accepts the date-range filter representation. Keep the final structure-defining schema last in each `$makeSchema(...)` call, then verify the emitted schema/OpenAPI result after a structure-shaping change.
+
 A practical reading takeaway is:
 
 - inference gives the structural baseline
-- explicit field metadata adds the operation-specific contract behavior
+- `$makeSchema(...)` refines projected fields when their query contract behavior differs
 
 ### Row-item response DTO
 
@@ -241,7 +358,7 @@ A practical rule is:
 
 ## Use `dtoClass` to shape inferred fields
 
-When inferred DTOs should still follow a reusable named field surface, pass `dtoClass` to the helper options.
+When inferred DTOs should still follow a reusable named field surface, pass `dtoClass` to the helper options. This is the reusable projection choice from [Layer 1: project upstream truth](#layer-1-project-upstream-truth).
 
 This is useful when:
 
@@ -357,11 +474,14 @@ For the bridge step that carries this backend-authored contract across the stack
 
 When evaluating a return shape or input contract that closely follows model structure, ask:
 
-1. should this DTO be inferred instead of handwritten?
-2. does model relationship structure already contain enough information?
-3. is the contract get/list/query/create/update/aggregate/group oriented?
+1. does an Entity, Model, relation, or query shape already provide stable upstream contract truth?
+2. is the contract get/list/query/create/update/aggregate/group oriented, and which `$Dto.*` helper matches it?
+3. should `columns`, `include`, `with`, or `dtoClass` define the projection boundary?
 4. should the inferred DTO stay inline or be wrapped in a named DTO class?
-5. does the resulting DTO also affect OpenAPI and frontend generation paths?
-6. is CRUD generation already giving enough contract structure that another handwritten DTO would be redundant?
+5. for every local difference, is it metadata-only (`$makeMetadata(...)`) or schema-affecting (`$makeSchema(...)`)?
+6. is every `@Api.field(...)` member genuinely new instead of a redeclared inferred field?
+7. if `$makeSchema(...)` is used, is the structure-defining schema last and is emitted schema/OpenAPI verification planned?
+8. does the resulting DTO also affect OpenAPI and frontend generation paths?
+9. is CRUD generation already giving enough contract structure that another handwritten DTO would be redundant, or is an explicit DTO clearer?
 
 That helps reduce redundant type work and keeps contracts closer to the model truth.

package/cabloy-docs/backend/foundation.md

@@ -263,7 +263,7 @@ Using `this.$scope.<fixedModule>`, `app.scope(...)`, or `this.app.scope(...)` do
 
 Scope lookup also does not compose, install, load, or order an absent module. The target must already be available through suite/application composition. Declare `vonaModule.dependencies` only when the caller has a genuine requirement for a target module's availability, dependency-first ordering, or minimum compatible version—not merely because it looks up that module's service, model, config, locale, or another resource.
 
-For the package, suite, and module dependency distinction, see [Package Map](/reference/package-map).
+For the canonical availability, ordering, and version decision guide, see [Vona Module Dependencies](/backend/module-dependencies). For the package, suite, and module topology distinction, see [Package Map](/reference/package-map).
 
 ## Suite / module / package boundaries
 

package/cabloy-docs/backend/introduction.md

@@ -30,6 +30,7 @@ Use this page as the main backend hub, then choose the family that matches your
 Start here when you need the core backend mental model first:
 
 - [Backend Foundation](/backend/foundation)
+- [Vona Module Dependencies](/backend/module-dependencies)
 - [Backend Essentials](/backend/backend-essentials)
 - [Backend CLI](/backend/cli)
 - [Service Guide](/backend/service-guide)

package/cabloy-docs/backend/module-dependencies.md

@@ -0,0 +1,104 @@
+# Vona Module Dependencies
+
+Use `vonaModule.dependencies` when one Vona module has a real requirement for another module's availability, dependency-first ordering, or minimum compatible version.
+
+It is not a general declaration for every cross-module reference.
+
+## What a module dependency means
+
+A dependency in a module package manifest expresses all of these conditions:
+
+- the target module must be present and enabled
+- the target module is ordered before the dependent module
+- the declared version is the minimum compatible target version
+
+For example:
+
+```json
+{
+  "vonaModule": {
+    "dependencies": {
+      "a-vona": "5.0.0",
+      "a-telemetry": "5.0.0"
+    }
+  }
+}
+```
+
+This is a module lifecycle contract. It is stronger than an import or a resource lookup.
+
+## Four different relationships
+
+Keep these concerns separate.
+
+| Relationship                     | Purpose                                                                | Typical surface                    |
+| -------------------------------- | ---------------------------------------------------------------------- | ---------------------------------- |
+| Package dependency               | Makes a package available to package tooling                           | `package.json` `dependencies`      |
+| Suite or application composition | Includes module packages in the application composition                | suite/application package metadata |
+| Module dependency                | Requires a target module's availability, order, and compatible version | `vonaModule.dependencies`          |
+| Runtime resource lookup          | Resolves a resource from an already composed module                    | `this.$scope`, `app.scope(...)`    |
+
+A module dependency does not install a package or compose an otherwise absent module. Ensure package and suite/application composition separately.
+
+## Lookup is not a dependency edge
+
+The following forms look up resources from modules that are already composed into the active application:
+
+```ts
+this.scope.model.order;
+this.$scope.commerceCatalog.model.product;
+app.scope('commerce-catalog').model.product;
+```
+
+Lookup alone does not require adding the target to `vonaModule.dependencies`. That includes lookup of another module's service, model, config, locale, entity, or other scoped resource.
+
+The same distinction applies to a named ORM relation or a relation included by an inferred DTO. A relation such as:
+
+```ts
+$relation.belongsTo('commerce-trade:order', 'commerce-member:user', 'userId');
+```
+
+is not, by itself, a reason to add a module dependency edge.
+
+## Decision guide
+
+| Question                                                                                     | Decision                                                                           |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Does the code only look up a resource from an already composed module?                       | Do not add an edge solely for the lookup.                                          |
+| Can the feature operate when the target module is absent?                                    | Do not add a required dependency; make optional behavior explicit.                 |
+| Must the target module be present and enabled for the feature to work?                       | Add a module dependency and verify composition separately.                         |
+| Must the target initialize before the dependent module?                                      | Add a module dependency.                                                           |
+| Does startup, lifecycle, or `monkey.ts` integration depend on deterministic target ordering? | Add a module dependency.                                                           |
+| Does the feature require a minimum compatible target-module version?                         | Add a module dependency with that minimum version.                                 |
+| Would the proposed edge create a cycle?                                                      | Revisit module ownership or composition instead of encoding a circular dependency. |
+
+`monkey.ts` and lifecycle integration are common reasons to require ordering, but they are not the only valid reason. The decisive question is whether the target module is a required availability, ordering, or version contract.
+
+## Avoid speculative edges
+
+Do not add `vonaModule.dependencies` merely to:
+
+- document an import
+- document a scope lookup
+- make a named ORM relation appear explicit
+- compensate for an assumed circular lookup
+- encode a transient implementation detail that should remain inside the framework
+
+A speculative edge can make a module unavailable when its target is disabled, impose an unnecessary ordering constraint, and turn a manageable design issue into a cycle.
+
+## Verification
+
+When adding or changing a module dependency:
+
+1. verify that package and suite/application composition makes the target available
+2. verify the target module's relative name and minimum compatible version
+3. confirm that the dependency graph remains acyclic
+4. run the relevant Vona metadata, build, or startup path that consumes module metadata
+5. run the narrowest meaningful tests and type checks for the affected feature
+
+## Related guides
+
+- [Backend Foundation](/backend/foundation#scope-lookup-vs-module-dependencies)
+- [Package Map](/reference/package-map)
+- [Backend Startup Guide](/backend/startup-guide)
+- [Backend CLI](/backend/cli)

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

@@ -51,6 +51,12 @@ A practical debugging rule is:
 
 - if a field-level serializer appears correct but the response still returns the raw value, first check whether the controller action uses `@Core.serializer()`
 
+### Declared response shape versus physical output fields
+
+A DTO or `@Api.body(...)` schema declares the response contract and emitted OpenAPI shape. It is not, by itself, an unknown-field stripping pass over an object that a controller action has already returned.
+
+When an API must physically omit fields from its payload, deliberately return the intended projection or apply a verified response-output policy, then verify the action response. Field-level serializer metadata is part of such output behavior only when the action enables `@Core.serializer()`; do not assume a narrower DTO declaration alone sanitizes a response. For deciding whether a read DTO itself needs a narrower business projection, see [Default read shape versus a public projection](/backend/dto-infer-generation#default-read-shape-versus-a-public-projection).
+
 ## Serializer transforms
 
 Vona supports custom serializer transforms through `@SerializerTransform(...)`.

package/cabloy-docs/fullstack/parallel-worktree-environment.md

@@ -1,81 +1,119 @@
 # Parallel Worktree Environment
 
-Use worktree-local environment overrides when two Cabloy Basic worktrees need to run ordinary local development or managed E2E checks at the same time.
+Use worktree-local environment overrides when two Cabloy Basic or Cabloy Start worktrees need to run ordinary local development or managed E2E checks at the same time.
 
-This workflow creates an isolated local runtime without changing committed environment defaults. It covers normal Vona and Zova development, `npm run test`, and `npm run test:e2e:XXX:clean`. It does not automatically isolate every external dependency.
+This Cabloy Basic page is the canonical shared recipe for both editions. Detect the active edition before selecting commands, but keep the same two-file environment model.
+
+This workflow creates a standard isolated local runtime without changing committed environment defaults. It does not automatically isolate every external dependency.
 
 ## Before creating local overrides
 
-1. Confirm that the checkout is a separate worktree.
-2. Check `vona/env/` and `zova/env/` for applicable, more-specific `.env.*.local` files. A more-specific local override can take precedence over `.env.local`.
-3. Choose one unique worktree name and unused Vona, Zova, and HMR ports.
+1. Create and enter a separate linked worktree.
+2. Explicitly invoke `/cabloy-worktree-environment` to receive a deterministic environment proposal and confirm it before any local file is written.
 
-The repository ignores `**/env/.env*.local`, so these files remain local to the worktree and must not be committed.
+The repository ignores `**/env/.env*.local`, but this workflow may create or change only these broad files:
 
-## Minimum configuration
+- `vona/env/.env.local`
+- `zova/env/.env.local`
 
-Create these files in the new worktree.
+Do not create or modify flavor-, mode-, app-mode-, or runtime-specific `.env.*.local` files for worktree isolation.
 
-### Vona
+## Deterministic, secret-safe recommendations
 
-`vona/env/.env.local`
+The explicit setup skill does not inspect `.env`, `.env.local`, `.env.*.local`, sibling configuration, process environment, listening processes, or external services while recommending values. Therefore secrets in local environment files are not supplied to the AI/model, printed to the console, or included in this workflow’s diagnostic output.
 
-```dotenv
-APP_NAME = cabloy-basic-my-worktree
-SERVER_LISTEN_PORT = 7113
-```
+The recommendation uses only Git worktree metadata and the fixed defaults below. The primary checkout has ordinal `0`; the first linked worktree has ordinal `1`, the second has ordinal `2`, and so on. For the first proposal, add the linked-worktree ordinal to each baseline port.
+
+| Setting               | Baseline | First-proposal rule               |
+| --------------------- | -------: | --------------------------------- |
+| `SERVER_LISTEN_PORT`  |   `7102` | `7102 + linked-worktree ordinal`  |
+| `DEV_SERVER_PORT`     |   `9000` | `9000 + linked-worktree ordinal`  |
+| `DEV_SERVER_HMR_PORT` |  `24679` | `24679 + linked-worktree ordinal` |
+
+`APP_NAME` is the current linked worktree directory name. `API_BASE_URL` is regenerated as `http://localhost:<SERVER_LISTEN_PORT>`.
 
-### Zova
+Every valid explicit setup proposes the same complete tuple and both local files:
 
-`zova/env/.env.local`
+```dotenv
+# vona/env/.env.local
+APP_NAME = cabloy-worktree-name
+SERVER_LISTEN_PORT = 7103
+```
 
 ```dotenv
-APP_NAME = cabloy-basic-my-worktree
-API_BASE_URL = http://localhost:7113
-DEV_SERVER_PORT = 9013
-DEV_SERVER_HMR_PORT = 24693
+# zova/env/.env.local
+APP_NAME = cabloy-worktree-name
+API_BASE_URL = http://localhost:7103
+DEV_SERVER_PORT = 9001
+DEV_SERVER_HMR_PORT = 24680
 ```
 
-Keep these invariants:
+The user-facing summary is:
+
+> 环境隔离信息：Vona 开发 + Zova 开发
+
+If the proposal is unsuitable, say **“再换一批”**. The skill increases every listener port by exactly `+1`, regenerates `API_BASE_URL` from the new Vona port, and presents the next tuple for confirmation. It never writes during this step.
+
+This deterministic scheme is not a port reservation or a live collision check. If an application later reports that a port is occupied, request another batch before setup or create another linked worktree; successful application startup remains the final authority.
+
+## Configuration boundaries
+
+After final confirmation, the skill always writes the two shown files. Keep these invariants:
 
 - Vona and Zova use the same unique `APP_NAME`.
-- `API_BASE_URL` points to the selected Vona `SERVER_LISTEN_PORT`.
-- `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, and `DEV_SERVER_HMR_PORT` are unique among concurrently running worktrees.
+- `API_BASE_URL` points to the generated Vona `SERVER_LISTEN_PORT`.
+- `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, and `DEV_SERVER_HMR_PORT` are unique within the generated worktree tuple.
+- The skill writes no settings beyond the five shown assignments and creates no flavor-specific local file.
+
+Admin and Web are alternative commands that share the generated Zova environment. Do not run both frontend development commands concurrently in one worktree. Configure another linked worktree for concurrent development of the other flavor.
+
+The enabled Zova Quasar extension maps `DEV_SERVER_HMR_PORT` to Vite's client HMR/WebSocket listener. It is a separate listener when it differs from `DEV_SERVER_PORT`, so every concurrently running Zova development worktree needs its own unique HMR port.
+
+For privacy, the skill writes only to absent or empty permitted broad local files. If either target already contains content, it stops without reading or changing either file; manage the existing local configuration outside this workflow or use a fresh linked worktree.
 
-The base Zova environment defines `SSR_API_BASE_URL = $API_BASE_URL`, so SSR uses the same Vona target in the normal baseline. Add an explicit local `SSR_API_BASE_URL` only if an applicable, more-specific environment file changes that relationship.
+## Edition-aware commands
+
+Use commands from the active repository root.
+
+| Edition      | Marker             | Frontend command                                   | Managed clean E2E              |
+| ------------ | ------------------ | -------------------------------------------------- | ------------------------------ |
+| Cabloy Basic | `__CABLOY_BASIC__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e:basic:clean` |
+| Cabloy Start | `__CABLOY_START__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e:start:clean` |
+
+Run one frontend command, not both, in each worktree. Both managed clean E2E workflows read Vona's effective local `SERVER_LISTEN_PORT`, then reset, start, and target that local runtime.
 
 ## What this isolates
 
 A unique `APP_NAME` separates the application identity used by ordinary framework-managed local resources, including managed test database names and Redis-related key prefixes. Worktree-local generated files, runtime files, build output, and coverage output are already separated by their worktree paths.
 
-The selected Vona, Zova, and HMR ports let the worktrees run their ordinary local processes concurrently. The matching Zova API URL prevents the frontend in one worktree from calling the Vona process in another.
+The generated Vona, Zova development HTTP, and Zova HMR ports let worktrees run their ordinary local processes concurrently. The matching Zova API URL prevents the frontend in one worktree from calling the Vona process in another.
 
 This is sufficient for the normal local workflows:
 
 ```bash
 npm run dev
+# Run one frontend process in this worktree:
 npm run dev:zova:admin
+# or
 npm run dev:zova:web
 npm run test
-npm run test:e2e:basic:clean
 ```
 
-The managed clean E2E workflow reads Vona's effective local `SERVER_LISTEN_PORT`, then resets, starts, and targets that local runtime.
+## Resources requiring separate design
 
-## Add configuration only when the work uses it
-
-Do not add isolation settings preemptively. Extend the local overrides only when the selected workflow actually shares one of these resources:
+Do not extend this universal five-value setup with additional listener or provider settings. An explicit separate design is required for:
 
 - an explicitly named database or a separately configured Redis target
 - mail, payment, webhook, object-storage, or other external providers
-- a standalone mock-build process, using `MOCK_BUILD_PORT`
-- an SSR preview or production process, using `SSR_PROD_PORT`
+- standalone mock-build, SSR preview, or production listeners
 
 For example, `APP_NAME` namespaces ordinary framework Redis keys, but it does not create a separate Redis server or automatically isolate custom, unprefixed keys. Likewise, an explicitly configured external database remains shared until it is configured separately.
 
-## Edition-aware note
+## Guided setup and initialization
+
+For confirmation-gated setup, explicitly invoke `/cabloy-worktree-environment`. The skill validates the linked worktree and edition, derives a secret-safe proposal from Git metadata and fixed port baselines, and writes both allowed broad local files after final confirmation.
 
-This page describes the current Cabloy Basic workflow. For Cabloy Start, detect the active edition first and inspect the Start repository's current scripts, flavors, environment files, and generated-output paths before applying this recipe.
+After local overrides are validated, decide separately whether to run `npm run init`. It is not an environment allocator: it installs dependencies and runs generation/build-related work. When it runs from a linked Git worktree rooted at the project, it preserves the tracked base `APP_NAME` defaults in `vona/env/.env` and `zova/env/.env`; the generated broad `.env.local` files supply the worktree-specific identity. Primary-checkout and non-Git project initialization may still establish base `APP_NAME` from the project directory.
 
 ## Read together with
 

package/cabloy-docs/fullstack/suites-and-modules.md

@@ -297,6 +297,7 @@ For most real business scenarios, the correct answer is to create the suite firs
 This guide should be read together with:
 
 - [Package Map](/reference/package-map)
+- [Vona Module Dependencies](/backend/module-dependencies)
 - [Backend Directory Structure](/reference/backend-directory-structure)
 - [Frontend Directory Structure](/reference/frontend-directory-structure)
 - [Backend CLI](/backend/cli)

package/cabloy-docs/reference/package-map.md

@@ -81,6 +81,7 @@ Use this package map together with:
 - [Suites and Modules](/fullstack/suites-and-modules)
 - [Backend Essentials](/backend/backend-essentials)
 - [Backend Foundation](/backend/foundation)
+- [Vona Module Dependencies](/backend/module-dependencies)
 - [Backend CLI](/backend/cli)
 - [Backend Scripts](/backend/scripts)
 - [Backend Directory Structure](/reference/backend-directory-structure)

package/e2e/specs/a-commerce/commerce.spec.ts

@@ -796,6 +796,95 @@ test(
   },
 );
 
+test(
+  'ATP-SPC-01: Coupon Template renders semantic Admin field controls',
+  { tag: ['@admin', '@flow', '@fia'] },
+  async ({ browser }) => {
+    test.setTimeout(60_000);
+    const adminContext = await browser.newContext();
+    const adminPage = await adminContext.newPage();
+    const adminPageErrors = collectPageErrors(adminPage);
+    try {
+      await adminPage.setViewportSize({ width: 1440, height: 900 });
+      await login(adminPage, '/commerce-admin/', 'admin', '123456', 'commerceAdmin');
+      await adminPage.goto(
+        '/commerce-admin/rest/resource/commerce-promotion%3AcouponTemplate/create',
+        {
+          waitUntil: 'load',
+        },
+      );
+      await expect(adminPage).toHaveURL(
+        /\/commerce-admin\/rest\/resource\/commerce-promotion(?:%3A|:|%253A)couponTemplate\/create(?:[/?#]|$)/,
+      );
+
+      for (const groupName of [
+        'Basic Information',
+        'Discount Policy',
+        'Validity Window',
+        'Usage Limits',
+      ]) {
+        await expect(adminPage.getByRole('group', { name: groupName })).toBeVisible();
+      }
+
+      const state = adminPage
+        .getByRole('group', { name: 'Template State *' })
+        .getByRole('combobox');
+      await expect(state).toBeVisible();
+      await state.selectOption({ label: 'Active' });
+      await expect(state).toHaveValue('active');
+
+      const discountInput = adminPage
+        .getByRole('group', { name: 'Fixed Discount *' })
+        .getByRole('textbox');
+      const minSpendInput = adminPage
+        .getByRole('group', { name: 'Minimum Spend *' })
+        .getByRole('textbox');
+      await discountInput.fill('12.34');
+      await minSpendInput.fill('45.67');
+      await expect(discountInput).toHaveValue('12.34');
+      await expect(minSpendInput).toHaveValue('45.67');
+      await expect(
+        adminPage.getByRole('group', { name: 'Valid From *' }).locator('input[type="date"]'),
+      ).toBeVisible();
+      await expect(
+        adminPage.getByRole('group', { name: 'Valid Until *' }).locator('input[type="date"]'),
+      ).toBeVisible();
+
+      await adminPage
+        .getByRole('group', { name: 'Name *' })
+        .getByRole('textbox')
+        .fill('E2E Coupon Template');
+      await adminPage.getByRole('group', { name: 'Currency *' }).getByRole('textbox').fill('USD');
+      await adminPage
+        .getByRole('group', { name: 'Valid From *' })
+        .getByRole('textbox')
+        .fill('2026-08-04');
+      await adminPage
+        .getByRole('group', { name: 'Valid Until *' })
+        .getByRole('textbox')
+        .fill('2026-12-31');
+      await adminPage
+        .getByRole('group', { name: 'Total Issue Limit' })
+        .getByRole('textbox')
+        .fill('10');
+      await adminPage
+        .getByRole('group', { name: 'Total Usage Limit' })
+        .getByRole('textbox')
+        .fill('10');
+      await adminPage
+        .getByRole('group', { name: 'Per-customer Issue Limit' })
+        .getByRole('textbox')
+        .fill('1');
+
+      await expect(adminPage.getByRole('button', { name: 'Submit', exact: true })).toBeVisible();
+      await expect(adminPage.getByRole('button', { name: 'Back', exact: true })).toBeVisible();
+      expect(adminPageErrors).toEqual([]);
+    } finally {
+      await adminContext.close().catch(() => {});
+    }
+  },
+);
+
 test(
   'Commerce Cart: anonymous browser is redirected to login',
   { tag: ['@web', '@cart'] },