cabloy 5.1.124 → 5.1.126

package/.cabloy-version

@@ -1 +1 @@
-5.1.124
+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,26 @@
 # 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
+
+- Update payment functionality.
+
 ## 5.1.124
 
 ### Improvements

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

@@ -25,6 +25,7 @@ const aiItems = [
   { text: 'Playbook: Contract Regeneration', link: '/ai/playbook-contract-regeneration' },
   { text: 'Playbook: Module Removal', link: '/ai/playbook-module-removal' },
   { text: 'Playbook: Metadata Refresh', link: '/ai/playbook-metadata-refresh' },
+  { text: 'Playbook: Technical Blog Authoring', link: '/ai/playbook-technical-blog-authoring' },
   { text: 'CLI for Agents', link: '/ai/cli-for-agents' },
   { text: 'Rules and Config', link: '/ai/rules-and-config' },
   { text: 'Edition Detection', link: '/ai/edition-detection' },
@@ -197,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/ai/playbook-technical-blog-authoring.md

@@ -0,0 +1,158 @@
+# Playbook: Technical Blog Authoring
+
+Use this playbook when writing a technical blog about Cabloy, Vona, Zova, or an adjacent engineering problem. Its purpose is to help authors and agents turn a real reader concern into an accurate, approachable, and useful article.
+
+A blog post is not a replacement for reference documentation. Use the post to establish a mental model, explain why a design choice matters, and help readers choose a next step. Link to the relevant documentation for the complete contract and implementation detail.
+
+## Start with the reader's problem
+
+Open with a problem that readers can recognize in their existing practice, not with framework terminology or a product claim.
+
+For example, a Vue-oriented article can begin with a reader encountering growing composables, fragmented state ownership, or unclear cache invalidation. It should acknowledge that the familiar tools are useful before explaining the architectural tradeoff they do not settle by themselves.
+
+Then state one narrow thesis. A useful thesis does all of the following:
+
+- names the change in perspective;
+- limits what the article claims;
+- avoids declaring one ecosystem universally superior.
+
+For example:
+
+> Zova retains Vue 3 as its reactive foundation while giving complex application code explicit owners for state, behavior, dependencies, and lifecycle.
+
+Do not begin with claims such as “Framework X is obsolete,” “this is the only correct architecture,” or broad adoption and performance claims that the article cannot prove.
+
+## Research before drafting
+
+Use this authority order for technical claims:
+
+1. Current Cabloy documentation, source code, and tests for Cabloy, Vona, and Zova behavior.
+2. First-party upstream documentation for Vue, TypeScript, TanStack Query, React, Angular, or another external ecosystem.
+3. Carefully labelled experience, interpretation, and recommendations when a fact cannot be established from the sources above.
+
+Treat legacy documentation as input material, not unquestioned truth. If it conflicts with current source, prefer the source.
+
+Classify each meaningful statement while drafting:
+
+| Statement type               | How to write it                                                                                                      |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Verified framework fact      | State it precisely and link to current public docs or an authoritative upstream source.                              |
+| Comparison or interpretation | Explain the authoring-model difference with qualified wording such as “typically,” “can,” or “is designed to.”       |
+| Experience or recommendation | Make its situational nature visible: “consider this when…”, “can be a good fit for…”, or “in this kind of project…”. |
+
+Do not turn a representative example, a personal observation, or a framework goal into a universal ecosystem claim.
+
+## Use a problem-to-practice narrative
+
+For beginner-oriented technical posts, use this progression:
+
+1. **Reader problem** — establish empathy with a concrete, familiar situation.
+2. **Mental-model shift** — introduce one focused thesis that reframes the problem.
+3. **Progressive examples** — teach one concept and one ownership boundary at a time.
+4. **Decision aid** — use a role table or comparison table only when it helps readers choose where something belongs.
+5. **Tradeoffs** — state the learning cost, non-fit cases, and assumptions directly.
+6. **Next step** — give readers a small experiment to try and a short list of authoritative further reading.
+
+The article should answer both “what changes?” and “why should I care?” before adding advanced implementation detail.
+
+When explaining architecture, prefer ownership questions over tool-name questions:
+
+- Who owns this state or behavior?
+- Who may depend on it?
+- How long should it live?
+- Which boundary owns caching, invalidation, persistence, or rendering?
+
+This lets the article explain an architecture without becoming an API inventory.
+
+## Explain Zova in its own model first
+
+For Zova articles, begin with the controller / bean / IoC model before translating it into generic Vue terms. Vue comparisons are useful orientation aids, but they should not replace Zova's own concepts.
+
+Keep these accuracy rules in view:
+
+- Vue 3 provides Zova's reactive foundation.
+- A controller field is not reactive merely because it is a TypeScript class field; it is reactive because Zova creates the controller as a framework-managed reactive bean.
+- Controllers, beans, models, services, scopes, and TSX have distinct roles. Do not flatten them into synonyms for a composable or store.
+- A Model is not simply “Zova's Pinia.” It can own query, mutation, cache, persistence, invalidation, and SSR-related state concerns.
+- Discuss Cabloy Basic and Cabloy Start separately only when the UI layer, available suites, project assets, generated outputs, or edition-specific workflow affects the article.
+
+For factual background, start from these guides:
+
+- [Frontend Foundation](/frontend/foundation)
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers)
+- [Zova vs Vue 3 Comparison](/frontend/zova-vs-vue3-comparison)
+- [IoC and Beans](/frontend/ioc-and-beans)
+- [Model Architecture](/frontend/model-architecture)
+
+## Make examples earn their place
+
+Use short examples that demonstrate one idea each. A helpful progression is:
+
+1. page-local controller state and behavior;
+2. a controller collaborating with an injected model or service;
+3. an extraction that becomes justified as responsibility or reuse grows.
+
+Every example should make the ownership boundary easier to see. If an example requires advanced lifecycle details, data contracts, or several framework concepts to understand, defer it or split it into smaller examples.
+
+When a snippet has been simplified, say so. Do not present illustrative pseudocode as a copy-ready framework contract. Verify code, APIs, commands, and links against current sources before publishing.
+
+Comparison tables should name the dimension being compared and describe a typical or default authoring model, not imply that every project in either ecosystem has identical structure.
+
+## Keep the article balanced
+
+Strong technical writing makes the boundary of its own recommendation clear.
+
+Include the cost of the proposed approach. For example, a more structured controller/bean/model architecture may require authors to learn ownership, scope, and lifecycle rules; it may not be the most economical choice for a throwaway page or very small application.
+
+Avoid framing flexible tools as defective. Explain the problem that emerges when complexity grows and the conditions under which a more explicit structure becomes valuable.
+
+A practical article earns trust by telling readers both when to use an approach and when not to.
+
+## Package articles consistently
+
+Use a kebab-case topic directory under the local blog workspace:
+
+```text
+.assets/blogs/<topic-slug>/
+```
+
+The canonical article should begin with frontmatter that makes its purpose and distribution metadata explicit. Use the fields relevant to the publishing target:
+
+```yaml
+title:
+titleEn:
+subtitle:
+summary:
+tags:
+slug:
+date:
+```
+
+When a bilingual release is in scope, create semantic sibling articles such as `article-zh.md` and `article-en.md`. Translate the thesis, caveats, examples, and linked evidence faithfully, but adapt titles, idioms, reader framing, and platform copy to the language rather than translating word-for-word.
+
+When distribution is requested, keep publishing material separate from the canonical article. A publishing kit can contain:
+
+- recommended and alternate titles;
+- subtitle, short summary, long summary, and platform abstract;
+- tags and selected cover;
+- social or platform-specific copy;
+- editorial and accuracy notes.
+
+Treat cover copy and images as publishing deliverables, not evidence for technical claims. Use a readable 1600 × 900 cover when a social-preview image is needed.
+
+## Pre-publication checklist
+
+Before publishing, verify all of the following:
+
+- [ ] The opening names a real reader problem and does not begin as framework promotion.
+- [ ] The thesis is narrow, accurate, and non-adversarial.
+- [ ] Each factual claim has current source or first-party documentation support.
+- [ ] Interpretations and recommendations are written as interpretations and recommendations.
+- [ ] Examples are concise, current, and explicit about simplification where applicable.
+- [ ] Comparison tables describe dimensions and typical models, not universal truths.
+- [ ] Tradeoffs and non-fit situations are stated plainly.
+- [ ] Terminology, edition notes, commands, URLs, and documentation links are current.
+- [ ] Bilingual siblings and publishing assets are aligned when they are part of the requested deliverable.
+- [ ] Further reading directs readers to authoritative documentation, including [Verification](/ai/verification) when the article describes a development workflow.
+
+The goal is not merely a polished argument. It is to leave the reader with a trustworthy mental model and a safe, concrete next step.