cabloy 5.1.125 → 5.1.126

package/.cabloy-version

@@ -1 +1 @@
-5.1.125
+5.1.126

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

@@ -168,7 +168,7 @@ Then distinguish runtime lookup from a true module dependency:
 - do not add a dependency declaration merely because code looks up another module's service, model, config, locale, or other resource
 - scope lookup cannot make an absent module available; validate application/suite composition separately when the target must exist
 
-For the canonical distinction, read [Backend Foundation](../../../cabloy-docs/backend/foundation.md#scope-lookup-vs-module-dependencies) and [Package Map](../../../cabloy-docs/reference/package-map.md).
+For the canonical decision guide, read [Vona Module Dependencies](../../../cabloy-docs/backend/module-dependencies.md), with [Backend Foundation](../../../cabloy-docs/backend/foundation.md#scope-lookup-vs-module-dependencies) and [Package Map](../../../cabloy-docs/reference/package-map.md) as companions.
 
 ### Verification
 

package/.claude/skills/cabloy-backend-scaffold/evals/evals.json

@@ -24,6 +24,12 @@
       "prompt": "I changed a model relation and some entity fields in Cabloy Basic. Before you tell me anything else, I want the Cabloy backend done-checklist, not a broad explanation of ORM theory.",
       "expected_output": "Must give a concrete backend completion checklist, must include relation-aware follow-up and metadata or migration review, and must stay practical rather than drifting into generic ORM explanation.",
       "files": []
+    },
+    {
+      "id": 15,
+      "prompt": "My Vona service reads another module through this.$scope. Should I add vonaModule.dependencies? In a separate feature, my monkey.ts must extend a target module during startup. Explain the decision for both cases.",
+      "expected_output": "Must distinguish scope lookup from a module dependency edge, state that lookup alone does not require vonaModule.dependencies, and identify required availability, dependency-first ordering, or minimum compatible version as the criteria. Must recognize startup or monkey integration as a possible ordering case, verify composition separately, and reject speculative or circular edges.",
+      "files": []
     }
   ]
 }

package/.claude/skills/cabloy-backend-scaffold/references/follow-up-checklist.md

@@ -14,6 +14,12 @@ After generating or extending a backend thread, check which follow-up layers app
 - validation rules
 - OpenAPI metadata
 - inferred DTO opportunities
+- treat `$Dto.get(...)` as the complete model-aware read shape by default; use `columns` or `dtoClass` only for a genuine business/query/response projection, not solely to remove `iid` or `deleted`
+- treat the top-level `$Dto.create(...)` / `$Dto.update(...)` default omissions as a write-input authorization boundary, not as a reason to mechanically narrow ordinary `$Dto.get(...)` contracts
+- when a narrowed DTO or OpenAPI schema is expected to remove physical response fields, separately shape and verify the action response; declaration narrowing alone does not guarantee runtime field stripping
+- when stable Entity, Model, relation, or query truth exists, define the DTO projection first with `$Dto.*` and, where needed, `columns`, `include`, or `dtoClass`
+- for an inferred field, use `$makeMetadata(...)` for metadata-only refinement and `$makeSchema(...)` for schema or validation refinement; use a class-body `@Api.field(...)` member only for a genuinely new field
+- when inference cannot express the contract clearly, choose an explicit DTO deliberately; see [Default-first three-layer DTO authoring](../../../../cabloy-docs/backend/dto-infer-generation.md#default-first-three-layer-dto-authoring)
 - frontend contract impact
 - `@Api.field(...)` / `$makeSchema(...)` ordering: framework guards now preserve previously attached OpenAPI metadata across schema rebuilds, but structure-shaping schemaLike is still order-sensitive
 - when an explicit zod/custom schema or other structure-defining schemaLike is present, put that structure-defining schemaLike last because `makeSchemaLikes(...)` applies arguments right-to-left and later structure changes can otherwise alter or replace the intended schema
@@ -50,10 +56,13 @@ After generating or extending a backend thread, check which follow-up layers app
 
 ## Module composition and dependency intent
 
-- target module is already composed into the application when code uses cross-module scope lookup
-- cross-module `this.$scope.<module>` or `app.scope(...)` lookup alone does not require `vonaModule.dependencies`
-- `vonaModule.dependencies` is added only for a genuine target-module availability, dependency-first ordering, or minimum-version requirement
-- do not create speculative dependency edges or circular declarations merely to document a lookup
+- confirm package, suite, or application composition already supplies a target before using cross-module lookup; lookup cannot compose an absent module
+- choose the narrowest lookup form first: `this.scope` for local resources, `this.$scope.<module>` for a fixed cross-module target, and `app.scope(...)` when an application reference or genuinely dynamic target is required
+- cross-module scope lookup, a named ORM relation, or `$Dto.get(..., { include })` alone does not require `vonaModule.dependencies`
+- add `vonaModule.dependencies` only for a genuine target-module availability, dependency-first ordering, or minimum-version requirement
+- startup, lifecycle, or `monkey.ts` integration can require dependency-first ordering, but are not the only valid dependency case
+- when adding an edge, verify package/suite composition, the target relative module name, the minimum compatible version, and that the graph remains acyclic
+- do not create speculative dependency edges or circular declarations merely to document a lookup; read [Vona Module Dependencies](../../../../cabloy-docs/backend/module-dependencies.md) for the canonical decision guide
 
 ## Verification follow-up
 

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

@@ -100,9 +100,11 @@ The reason is simple: these files are where Cabloy already encodes its real work
 
 ### Parallel worktree environment setup
 
-When a request involves a second worktree, concurrent Vona/Zova development, isolated ordinary tests, or managed clean E2E, classify it as fullstack workflow setup. Read [Parallel Worktree Environment](../../../cabloy-docs/fullstack/parallel-worktree-environment.md) for the canonical Cabloy Basic recipe.
+When a request involves a second worktree, concurrent Vona/Zova development, isolated ordinary tests, or managed clean E2E, classify it as fullstack workflow setup. Read [Parallel Worktree Environment](../../../cabloy-docs/fullstack/parallel-worktree-environment.md), the canonical shared recipe maintained in Cabloy Basic for both editions.
 
-Before applying the broad `.env.local` recipe, check for more-specific `.env.*.local` overrides. Keep Vona and Zova `APP_NAME` values aligned, use the required matching API target, and add database, Redis, external-service, mock, or SSR-preview isolation only when the work actually uses those shared resources. For Cabloy Start, inspect the active Start repository rather than reusing the Basic recipe unchanged.
+This routing skill provides read-only guidance only. Do not infer an `APP_NAME` or ports, edit local overrides, or run `npm run init` from a generic worktree request. When the user wants confirmation-gated local environment setup, ask them to explicitly invoke `/cabloy-worktree-environment`.
+
+The invoked skill detects Basic or Start to select the active root scripts and managed clean-E2E command. It uses Git worktree metadata, fixed Vona/Zova port baselines, and the worktree basename to recommend the complete standard tuple for confirmation: `APP_NAME`, `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, `DEV_SERVER_HMR_PORT`, and an `API_BASE_URL` derived from the Vona port. After confirmation, it writes both `vona/env/.env.local` and `zova/env/.env.local`; never use flavor-, mode-, app-mode-, or runtime-specific `.env.*.local` files. It does not inspect environment-file content or allocate/reserve a live port. The shared environment is Vona + Zova development: Admin and Web are alternative commands using the same configuration, and they must not run concurrently in one worktree. Concurrent use requires separately configured linked worktrees.
 
 ## Step 4: Prefer CLI-first workflows
 

package/.claude/skills/cabloy-workflow/evals/evals.json

@@ -33,8 +33,20 @@
     },
     {
       "id": 6,
-      "prompt": "I created a second Cabloy Basic worktree and need to run Vona, Zova, and test:e2e:basic:clean in parallel with the first worktree. Which environment files and exact variables should I configure without changing shared defaults?",
-      "expected_output": "Classifies this as fullstack parallel-worktree environment setup and routes to the canonical Parallel Worktree Environment guide. Checks for more-specific local overrides, uses Vona vona/env/.env.local with APP_NAME and SERVER_LISTEN_PORT, and Zova zova/env/.env.local with the same APP_NAME plus API_BASE_URL pointing to that Vona port, DEV_SERVER_PORT, and DEV_SERVER_HMR_PORT. Keeps SSR_API_BASE_URL inherited from API_BASE_URL unless a more-specific override changes it, and adds database, Redis, external-service, mock, or SSR-preview settings only when those resources are actually used.",
+      "prompt": "I created a second Cabloy Basic worktree and need to run Vona, Zova Admin, and test:e2e:basic:clean in parallel with the first worktree. Which environment files and exact variables should I configure without changing shared defaults?",
+      "expected_output": "Classifies this as fullstack parallel-worktree environment setup and routes to the canonical shared Parallel Worktree Environment guide. Explains that generic routing is read-only: it must not inspect env content, infer or write local values, or run npm run init. Directs the user to explicitly invoke /cabloy-worktree-environment for confirmation-gated setup. The invoked skill uses Git worktree metadata, the worktree basename, and fixed baseline ports to recommend APP_NAME, SERVER_LISTEN_PORT, DEV_SERVER_PORT, DEV_SERVER_HMR_PORT, and a derived API_BASE_URL, then writes only vona/env/.env.local and zova/env/.env.local after confirmation. It does not use a flavor-specific local file or reserve ports; Admin and Web are alternative non-concurrent commands using the shared tuple.",
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "I created a linked Cabloy Start worktree and need isolated Vona, Zova Web, and managed clean E2E. Which workflow should I use?",
+      "expected_output": "Routes to the canonical shared guide and explicitly invoked /cabloy-worktree-environment skill. It recognizes that the invoked skill selects the Start command npm run test:e2e:start:clean while retaining read-only generic routing, a deterministic Git-metadata recommendation, no environment-content inspection, no automatic initialization, and the universal five-setting tuple written to both permitted broad local files only after confirmation.",
+      "files": []
+    },
+    {
+      "id": 8,
+      "prompt": "I created a linked Cabloy Basic worktree and only need backend tests. What should I do for local environment isolation?",
+      "expected_output": "Keeps generic routing read-only and directs the user to the canonical guide plus explicit /cabloy-worktree-environment invocation. It explains that the invoked skill still generates the universal APP_NAME, SERVER_LISTEN_PORT, DEV_SERVER_PORT, DEV_SERVER_HMR_PORT, and derived API_BASE_URL tuple in both broad local files after confirmation; it does not provide a backend-only one-file path.",
       "files": []
     }
   ]

package/.claude/skills/cabloy-worktree-environment/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: cabloy-worktree-environment
+description: This skill must be used only when the user explicitly invokes /cabloy-worktree-environment or explicitly asks to perform the named Cabloy worktree-environment setup. It prepares a confirmation-gated, worktree-local Vona and Zova runtime environment for a linked Cabloy Basic or Cabloy Start Git worktree using Git metadata and fixed port baselines only. Do not use it merely because a request mentions worktrees, parallel work, ports, development, tests, or E2E; route those requests to cabloy-workflow for read-only guidance instead.
+---
+
+# Cabloy Worktree Environment
+
+Use this skill only for explicit, user-controlled setup of the standard local runtime environment in an already-created linked Git worktree.
+
+## Goals
+
+1. validate that the current checkout is a linked Cabloy Basic or Cabloy Start worktree before any write
+2. generate a deterministic, secret-safe core environment tuple from Git worktree metadata and fixed port baselines
+3. never read, parse, source, expand, display, log, or send `.env*` file contents to the model
+4. write only a new or empty `vona/env/.env.local` and `zova/env/.env.local` in the current worktree after explicit confirmation
+5. keep Admin and Web as alternative runtime commands that share one generated Zova configuration
+6. keep `npm run init` a separate, opt-in decision
+
+## Step 1: Validate the current checkout and edition
+
+Before proposing configuration values or writing files:
+
+1. resolve the current absolute Git top-level directory
+2. run `git worktree list --porcelain -z` and parse its NUL-delimited records without shell word splitting
+3. verify that the current root is registered
+4. compare absolute `git-dir` and `git-common-dir`; equal paths identify the primary checkout, which this skill must reject
+5. detect exactly one edition marker at the resolved root
+6. verify that `vona/env/`, `zova/env/`, and the required root scripts exist
+
+Interpretation:
+
+| Marker | Edition | Managed clean E2E command |
+| --- | --- | --- |
+| `__CABLOY_BASIC__` only | Cabloy Basic | `npm run test:e2e:basic:clean` |
+| `__CABLOY_START__` only | Cabloy Start | `npm run test:e2e:start:clean` |
+
+Stop without edits when both markers are present, neither marker is present, the checkout is primary/unregistered, required environment directories are missing, or the selected edition's required scripts are unavailable.
+
+Read [Parallel Worktree Environment](../../../cabloy-docs/fullstack/parallel-worktree-environment.md) as the canonical shared recipe. Edition detection chooses command names and labels; it does not change the two-file environment model. Never change committed defaults, including `vona/env/.env` and `zova/env/.env`.
+
+## Step 2: Generate the standard environment recommendation
+
+After validation, immediately generate the standard core tuple. Do not ask which processes the user intends to run and do not ask them to select Admin or Web.
+
+For user-facing summaries, write exactly:
+
+> 环境隔离信息：Vona 开发 + Zova 开发
+
+Admin and Web use this same Zova environment. The user may later run either frontend command, but must not run both concurrently in one worktree. Use another linked worktree for concurrent development of the other flavor. Do not create a flavor-specific local override.
+
+### Secret-safe input boundary
+
+Recommendation generation uses Git worktree metadata and the fixed constants below only. It must not inspect any `.env`, `.env.local`, `.env.*.local`, sibling worktree configuration, process environment, listener table, `lsof` output, process command line, or external service. Do not use `Read`, `cat`, `grep`, `source`, `dotenv`, `printenv`, `env`, or diagnostics that expose env-file content for this workflow.
+
+This means the proposal is deterministic convenience, not a live port reservation. If an application later reports a port collision, the user may say **“再换一批”** before setup or create another linked worktree; the actual application bind remains authoritative.
+
+### Deterministic proposal
+
+Treat the primary checkout as ordinal `0`. From the validated `git worktree list --porcelain -z` order, assign each linked worktree the next ordinal: the first linked worktree is `1`, the second is `2`, and so on. Let `batch` be `0` for the first proposal, and increase it only when the user says **“再换一批”**.
+
+Use one shared offset for every generated listener:
+
+```text
+offset = linkedWorktreeOrdinal + batch
+```
+
+Use these fixed baseline ports, which match the committed Cabloy defaults:
+
+| Setting | Baseline | Recommended value |
+| --- | ---: | --- |
+| `SERVER_LISTEN_PORT` | `7102` | `7102 + offset` |
+| `DEV_SERVER_PORT` | `9000` | `9000 + offset` |
+| `DEV_SERVER_HMR_PORT` | `24679` | `24679 + offset` |
+
+Set `APP_NAME` to the basename of the validated current worktree root. Do not inspect other worktrees’ configurations or append an env-derived suffix. Stop if that basename is empty or cannot be used as an application name without altering it; ask the user to rename/recreate the linked worktree instead.
+
+Always recommend both local files:
+
+```dotenv
+# vona/env/.env.local
+APP_NAME = <worktree-basename>
+SERVER_LISTEN_PORT = <7102 + offset>
+```
+
+```dotenv
+# zova/env/.env.local
+APP_NAME = <worktree-basename>
+API_BASE_URL = http://localhost:<recommended SERVER_LISTEN_PORT>
+DEV_SERVER_PORT = <9000 + offset>
+DEV_SERVER_HMR_PORT = <24679 + offset>
+```
+
+All generated listener ports must be integers from `1` through `65535` and distinct within the tuple. If a batch would exceed that range, stop and require a different linked-worktree arrangement.
+
+When the user says **“再换一批”**, set `batch = batch + 1`, recompute the entire tuple, and show it again. Every recommended listener advances by exactly `+1`, and `API_BASE_URL` is regenerated from the new Vona port. Do not write during a batch change. This deterministic setup does not accept user-substituted values.
+
+A unique `APP_NAME` separates ordinary framework-managed test database names and framework Redis prefixes. It does not isolate explicitly named databases, unprefixed custom Redis keys, mail, payment, webhooks, object storage, or other external services. Require a separate explicit design before claiming that any of those resources are isolated.
+
+## Step 3: Preview and confirm the write
+
+Before making any edit:
+
+1. show `环境隔离信息：Vona 开发 + Zova 开发`, the worktree ordinal, batch, and exact non-secret identity/port tuple
+2. show a file-by-file preview containing only the managed assignments that will be written to both broad local files
+3. run one independent `git check-ignore -v -- "$target"` command for each target and require each command to succeed with a matching ignore rule
+4. recheck current root, linked-worktree identity, edition, ordinal, generated port range, tuple uniqueness, and both target states
+5. ask for a final affirmative confirmation that includes the proposed identity and port tuple
+
+Do not treat silence as confirmation.
+
+## Step 4: Apply only safe broad local overrides
+
+The only files this skill may create or change are:
+
+- `vona/env/.env.local`
+- `zova/env/.env.local`
+
+To preserve the no-env-content-disclosure boundary, inspect only each target's existence and whether it is empty; do not read its contents. If either target already exists and is non-empty, stop without reading or modifying either file. Explain that this skill deliberately will not access a pre-existing local environment file because it may contain secrets; the user must manage it outside this workflow or use a fresh linked worktree.
+
+Only after final confirmation:
+
+1. immediately re-run one independent `git check-ignore -v -- "$target"` command for each target and abort unless each succeeds with a matching ignore rule
+2. confirm both targets are absent or empty without reading their content
+3. snapshot only each target's existence and empty-file state
+4. write the exact previewed Vona assignments to `vona/env/.env.local`
+5. write the exact previewed Zova assignments to `zova/env/.env.local`
+6. do not create, modify, remove, inspect, or recommend flavor-, mode-, app-mode-, or runtime-specific `.env.*.local` files
+
+Never:
+
+- edit another worktree
+- read, parse, source, expand, display, or log existing environment-file content
+- edit committed `.env` defaults
+- add mock, preview, or other runtime-specific listener settings through this workflow
+- claim that a deterministic recommendation has allocated or reserved a port
+- generate values or write configuration merely to bypass a busy shared resource
+
+If a write cannot complete, restore each already changed target to its exact prior state: remove a newly created target or restore an originally empty target to an empty file. Report only the path and operation stage; never include environment-file content in the failure output.
+
+## Step 5: Revalidate and offer initialization separately
+
+After writing, verify only the known assignments that this skill generated and wrote, without re-reading any pre-existing local content. Confirm:
+
+- the generated Vona and Zova `APP_NAME` values match
+- `API_BASE_URL` targets the generated Vona port
+- `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, and `DEV_SERVER_HMR_PORT` are distinct
+- both target paths and edition commands remain valid
+
+Report only the files changed, the generated non-secret tuple, and external resources that remain shared.
+
+Then ask exactly:
+
+> The local environment overrides are configured. Do you want to run `npm run init` now?
+
+Do not run it without an affirmative answer. Explain that `npm run init` is not an environment allocator: it installs dependencies and runs generation/build-related work. In this linked worktree, it preserves the tracked base `APP_NAME` defaults in `vona/env/.env` and `zova/env/.env`; the generated broad `.env.local` files remain the worktree-specific identity source. Primary-checkout and non-Git project initialization may still establish base `APP_NAME` from the project directory.
+
+## Verification
+
+Use focused checks appropriate to the detected edition:
+
+```bash
+git worktree list --porcelain -z
+git rev-parse --path-format=absolute --show-toplevel
+git rev-parse --path-format=absolute --git-dir
+git rev-parse --path-format=absolute --git-common-dir
+for target in vona/env/.env.local zova/env/.env.local; do
+  git check-ignore -v -- "$target" || exit 1
+done
+```
+
+Run one frontend command, not both:
+
+```bash
+npm run dev
+npm run dev:zova:admin
+# or
+npm run dev:zova:web
+npm run test
+```
+
+Run the edition-appropriate managed clean E2E command:
+
+```bash
+# Cabloy Basic
+npm run test:e2e:basic:clean
+
+# Cabloy Start
+npm run test:e2e:start:clean
+```
+
+Finish with a metadata-only status check. Do not use `git diff`, because it can print environment-file content:
+
+```bash
+git status --short
+```
+
+## Response pattern
+
+When this skill completes a stage, report:
+
+1. validated worktree root and detected edition
+2. `环境隔离信息：Vona 开发 + Zova 开发`
+3. worktree ordinal, batch, and generated non-secret identity/ports
+4. both exact broad local files proposed or changed
+5. the privacy boundary and external resources that still require separate isolation
+6. the separate `npm run init` question only after successful local setup

package/.claude/skills/cabloy-worktree-environment/evals/evals.json

@@ -0,0 +1,77 @@
+{
+  "skill_name": "cabloy-worktree-environment",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment in the first linked Cabloy Basic worktree. Configure the local environment.",
+      "expected_output": "Validates that the current checkout is a linked Cabloy Basic worktree before any write. Without asking which processes or frontend flavor will run, it uses Git worktree metadata only and recommends APP_NAME from the worktree basename, SERVER_LISTEN_PORT 7103, DEV_SERVER_PORT 9001, DEV_SERVER_HMR_PORT 24680, and API_BASE_URL http://localhost:7103. It labels the configuration as 环境隔离信息：Vona 开发 + Zova 开发, previews both vona/env/.env.local and zova/env/.env.local, waits for final confirmation before writing, and separately asks whether to run npm run init after success.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment in the second linked Cabloy Start worktree. Set up the standard local environment.",
+      "expected_output": "Detects __CABLOY_START__, selects npm run test:e2e:start:clean for later verification, and uses the shared canonical workflow. Without a process-selection question, it derives APP_NAME from the worktree basename and, for ordinal 2 batch 0, recommends SERVER_LISTEN_PORT 7104, DEV_SERVER_PORT 9002, DEV_SERVER_HMR_PORT 24681, and API_BASE_URL http://localhost:7104. It uses only the two broad local targets and waits for final confirmation before writing both.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment from the primary Cabloy Basic checkout. Set up a second local runtime here so I can avoid the port already in use.",
+      "expected_output": "Rejects the request without writing because the current checkout is the primary checkout rather than a linked worktree. It does not modify shared identity or ports merely to bypass a busy resource.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment in a linked Cabloy Basic worktree. I only plan to run ordinary backend tests.",
+      "expected_output": "Does not ask the user to select processes and still recommends the universal five-setting tuple: worktree-basename APP_NAME, SERVER_LISTEN_PORT, DEV_SERVER_PORT, DEV_SERVER_HMR_PORT, and an API_BASE_URL derived from the server port. After confirmation it writes both vona/env/.env.local and zova/env/.env.local, while explaining that external services require separate isolation decisions.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment in a linked Cabloy Basic worktree and later want to use Admin and Web frontend commands.",
+      "expected_output": "Generates the same shared standard tuple without asking for a frontend flavor and never proposes a flavor-specific .env.XXX.local file. It explains that Admin and Web use the generated Zova configuration but must not run concurrently in one worktree; another linked worktree is required for concurrent use.",
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment in a linked Cabloy Start worktree and also intend to use SSR preview later.",
+      "expected_output": "Generates only the universal five-setting Vona and Zova tuple in the two broad local files. It does not add MOCK_BUILD_PORT, SSR_PROD_PORT, SSR_API_BASE_URL, or another runtime-specific local file; those require a separately designed workflow.",
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment in a linked Cabloy Basic worktree, but zova/env/.env.local is tracked or not ignored.",
+      "expected_output": "Runs an independent git check-ignore -v -- target command for both broad targets and rejects the write before confirmation because every target must be ignored. It does not fall back to a specific local file or modify the tracked target.",
+      "files": []
+    },
+    {
+      "id": 8,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment in the first linked Cabloy Basic worktree. The initial proposal is 7103, 9001, and 24680. 再换一批。",
+      "expected_output": "Keeps the same worktree APP_NAME, increases the shared batch by one, and proposes SERVER_LISTEN_PORT 7104, DEV_SERVER_PORT 9002, DEV_SERVER_HMR_PORT 24681, and API_BASE_URL http://localhost:7104. It does not write, inspect ports, inspect environment files, or treat either batch as reserved before final confirmation.",
+      "files": []
+    },
+    {
+      "id": 9,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment for a linked Cabloy Basic worktree. My local .env.local files may contain credentials. Set up the standard local environment.",
+      "expected_output": "Uses only Git worktree metadata, fixed port baselines, and the worktree basename. It does not read, parse, source, expand, print, log, or send any .env* contents, process environment, listener table, or sibling configuration to the model. If either target broad local file exists and is non-empty at the confirmed write stage, it stops without reading or modifying either file.",
+      "files": []
+    },
+    {
+      "id": 10,
+      "prompt": "I explicitly invoke /cabloy-worktree-environment for a linked Cabloy Basic worktree. Writing zova/env/.env.local fails after vona/env/.env.local was created.",
+      "expected_output": "Uses only absent or empty permitted targets, snapshots their existence and empty-file state without reading content, removes every target newly created during the failed operation, restores any originally empty target to empty state, and reports the failure without leaving a partial configuration or exposing environment-file content.",
+      "files": []
+    },
+    {
+      "id": 11,
+      "prompt": "/cabloy-worktree-environment",
+      "expected_output": "After validating that the current checkout is a linked Cabloy worktree, immediately proposes the complete universal tuple and previews both broad local files. It does not ask the user to choose Vona, tests, E2E, Admin, or Web before the final confirmation.",
+      "files": []
+    },
+    {
+      "id": 12,
+      "prompt": "I confirm the proposed standard tuple in a valid linked worktree.",
+      "expected_output": "Rechecks ignore rules and absent-or-empty state for both permitted targets, then writes vona/env/.env.local and zova/env/.env.local together. It validates their generated assignments without reading prior content and only then asks the exact separate npm run init question.",
+      "files": []
+    }
+  ]
+}

package/.github/workflows/vona-test-pg.yml

@@ -34,6 +34,9 @@ jobs:
           version: 11.5.2
       - name: init
         run: npm run init
+      - name: run A-Pay focused gate
+        run: DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
+        working-directory: vona
       - name: run Commerce stock contention gate
         run: |
           DATABASE_DEFAULT_CLIENT=pg npm run vona :bin:test -- commerce-trade/test/stockBalance.test.ts commerce-trade/test/stockReservation.test.ts commerce-trade/test/stockAudit.test.ts --flavor=normal

package/.github/workflows/vona-test-sqlite3.yml

@@ -27,6 +27,9 @@ jobs:
           version: 11.5.2
       - name: init
         run: npm run init
+      - name: run A-Pay focused gate
+        run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- test-pay/test/paymentSession.test.ts test-pay/test/payMock.test.ts test-pay/test/outbox.test.ts test-pay/test/webhook.test.ts --flavor=normal
+        working-directory: vona
       - name: run Commerce payment, shipment, and refund lifecycle gate
         run: DATABASE_DEFAULT_CLIENT=sqlite3 npm run vona :bin:test -- commerce-trade/test/paymentOutcome.test.ts commerce-trade/test/reservationExpiry.test.ts commerce-trade/test/shipment.test.ts commerce-trade/test/refundLifecycle.test.ts --flavor=normal
         working-directory: vona

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 5.1.126
+
+### Features
+
+- Add and update skills for the cabloy worktree environment.
+- Add payment capabilities and related tests.
+- Add DTO inference support.
+- Add `$Dto.get` rules.
+- Update application capabilities and workflows.
+
+### Improvements
+
+- Refactor DTO inference handling.
+- Refactor training-related modules.
+
 ## 5.1.125
 
 ### Features

package/CLAUDE.md

@@ -58,7 +58,7 @@ Before inventing a custom implementation path:
 - Default to establishing such query state during render. Use `disableSuspenseOnInit: true` only for relatively stable query-backed state when you want to skip the init-time `query.suspense()` kick; it does not prevent query creation, fetches, or hydration-time rendering. If strict readiness is needed later, wait explicitly at the interaction boundary.
 - In SSR, keep server HTML and the client's hydration-time initial render equivalent. When server rendering intentionally omits private, cookie-unavailable, or browser-only state, keep the same neutral shell or placeholder through hydration and defer its query/load/render branch to an explicit post-hydration, admission, mounted, or interaction boundary.
 - Keep repo-wide AI rules in `CLAUDE.md` short and durable; put branching Zova analysis workflows in `.claude/skills/`.
-- Do not modify shared environment identity or ports merely to bypass a busy resource. For intentional parallel worktree setup, follow `cabloy-docs/fullstack/parallel-worktree-environment.md`; otherwise wait for the shared resource or ask the user.
+- Do not modify shared environment identity or ports merely to bypass a busy resource. For intentional parallel worktree setup, follow `cabloy-docs/fullstack/parallel-worktree-environment.md`; otherwise wait for the shared resource or ask the user. Create or change worktree-local environment overrides only through the explicitly invoked `cabloy-worktree-environment` skill and its confirmation phase, and only in `vona/env/.env.local` and `zova/env/.env.local`; never modify flavor-, mode-, app-mode-, or runtime-specific `.env.*.local` files. The skill derives the standard `APP_NAME`, `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, `DEV_SERVER_HMR_PORT`, and API-derived `API_BASE_URL` tuple only from Git worktree metadata and fixed port baselines; never read or expose `.env*` content while recommending values. Admin and Web are alternative commands using this shared tuple and must not run concurrently in one worktree; use another linked worktree for concurrent use. Detect the active edition before choosing scripts, and never run `npm run init` as an automatic follow-up.
 - For SSR theme-sensitive frontend work, detect the active edition marker and UI library before making assumptions. Cabloy Basic currently means DaisyUI + Tailwind CSS assumptions; Cabloy Start currently means Vuetify assumptions.
 - In Web SSR without cookie-backed theme resolution, do not treat server reads of `$theme.dark`, `$theme.darkMode`, or `$token` as final browser truth. Keep theme-sensitive SSR branching hydration-tolerant or defer final theme-sensitive decisions to the client.
 - Do not assume Cabloy Basic and Cabloy Start use the same adapter-level SSR theme handoff. Verify the active theme handler and client hydration path before changing SSR theme behavior.

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

@@ -198,6 +198,7 @@ export default defineConfig({
           items: [
             { text: 'Introduction', link: '/backend/introduction' },
             { text: 'Foundation', link: '/backend/foundation' },
+            { text: 'Module Dependencies', link: '/backend/module-dependencies' },
             { text: 'Backend Essentials', link: '/backend/backend-essentials' },
             { text: 'Quickstart', link: '/backend/quickstart' },
             {

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