cabloy 5.1.203 → 5.1.205

package/.cabloy-version

@@ -1 +1 @@
-5.1.203
+5.1.205

package/.gitignore

@@ -37,6 +37,8 @@ blob-report/
 # vona core related directories
 vona/.vona
 vona/.app
+vona/.vona-test-*
+vona/.app-test-*
 vona/.zova-rest
 
 **/.temp-dynamic-*

package/CHANGELOG.md

@@ -1,11 +1,32 @@
 # Changelog
 
+## 5.1.205
+
+### Features
+
+- Update functionality.
+
+### Bug Fixes
+
+- Respect CLI publish boundaries.
+- Preserve test claim identities.
+
+## 5.1.204
+
+### Improvements
+
+- Document model relations and transaction rules.
+- Add a blog post on using AI coding for CRUD, SSR, and multitasking.
+- Update the pnpm lockfile.
+
 ## 5.1.203
 
 ### Features
+
 - Update application features.
 
 ### Improvements
+
 - Refactor end-to-end tests.
 - Clarify managed E2E resource authorization documentation.
 - Add a video demonstrating second-level tabs for admin multitasking.

package/lint-staged.config.mjs

@@ -22,6 +22,8 @@ const OXFMT_IGNORE_PATTERNS = [
   '**/quasar.config.ts.temporary.*',
   // common directory patterns
   '**/.vona',
+  '**/.vona-test-*',
+  '**/.app-test-*',
   '**/.assets',
   '**/.app',
   '**/.zova-rest',

package/oxfmt.config.ts

@@ -24,6 +24,8 @@ export default defineConfig(
       '**/quasar.config.ts.temporary.*',
       // common directory patterns (from vona & zova, converted to **/)
       '**/.vona',
+      '**/.vona-test-*',
+      '**/.app-test-*',
       '**/.assets',
       '**/.app',
       '**/.zova-rest',

package/oxlint.config.ts

@@ -49,6 +49,8 @@ export default defineConfig(
       '**/postcss.config.cjs',
       // common directory patterns (from vona & zova, converted to **/)
       '**/.vona',
+      '**/.vona-test-*',
+      '**/.app-test-*',
       '**/.assets',
       '**/.zova',
       '**/docker-compose',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.203",
+  "version": "5.1.205",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -22,7 +22,6 @@
   "type": "module",
   "scripts": {
     "init": "node scripts/init.ts",
-    "init:test-data": "node scripts/initTestData.ts",
     "upgrade": "node scripts/upgrade.ts",
     "upgrade:dry-run": "node scripts/upgrade.ts --dry-run",
     "vona": "node ./vona/packages-cli/cli/src/bin/vona.ts --projectPath=vona",
@@ -33,8 +32,10 @@
     "dev:zova:web": "cd zova && npm run dev:ssr:cabloyBasicWeb",
     "dev:zova:commerce:web": "cd zova && npm run dev:ssr:cabloyCommerce",
     "dev:zova:commerce:admin": "cd zova && npm run dev:ssr:cabloyCommerceAdmin",
-    "build": "npm run build:zova && pnpm --dir vona run build",
-    "build:docker": "npm run build:zova && pnpm --dir vona run build:docker",
+    "build": "npm run build:zova:all && npm run build:vona",
+    "build:docker": "npm run build:zova:all && npm run build:vona:docker",
+    "build:vona": "pnpm --dir vona run build",
+    "build:vona:docker": "pnpm --dir vona run build:docker",
     "build:zova:all": "npm run build:zova && npm run build:zova:commerce",
     "build:zova": "pnpm --dir zova run build:ssr:cabloyBasicBatch",
     "build:zova:admin": "pnpm --dir zova run build:ssr:cabloyBasicAdmin && pnpm --dir zova run build:rest:cabloyBasicAdmin",
@@ -45,7 +46,7 @@
     "start": "cd vona && npm run start",
     "start:one": "cd vona && npm run start:one",
     "test": "cd vona && npm run test",
-    "test:e2e": "node repo-e2e/scripts/runE2e.ts",
+    "test:e2e": "node scripts/runIsolatedTest.ts e2e",
     "test:docs:e2e": "npm run docs:build && playwright test --config repo-e2e/docs/playwright.config.ts",
     "db:reset": "cd vona && npm run db:reset",
     "tsc": "npm run tsc:zova && pnpm --dir vona run tsc",

package/repo-agent-governance/managed-assets.json

@@ -18,7 +18,7 @@
     {
       "adapter": "codex",
       "category": "skill",
-      "sha256": "88e6ca8c60d8caeb68ab932f2a7e22810a31911400b4428fd0756d076dbc78e8",
+      "sha256": "73e068093dfc88d57dc484582e0c20b1dd5d48bdbe12e860ac6343a64883cf5e",
       "source": "skills/cabloy-backend-scaffold/references/follow-up-checklist.md",
       "target": ".agents/skills/cabloy-backend-scaffold/references/follow-up-checklist.md"
     },
@@ -277,7 +277,7 @@
     {
       "adapter": "codex",
       "category": "skill",
-      "sha256": "ff0760f6fa7c24f561fdcfa07094d9d6e8d82fcef358458a36ff0c38a30ea89e",
+      "sha256": "eccad69c3969f97e80a3766fc2149b9f3e0bf2acd0c8586ed7bed0418f6878a9",
       "source": "skills/cabloy-workflow/SKILL.md",
       "target": ".agents/skills/cabloy-workflow/SKILL.md"
     },
@@ -354,7 +354,7 @@
     {
       "adapter": "claude",
       "category": "skill",
-      "sha256": "88e6ca8c60d8caeb68ab932f2a7e22810a31911400b4428fd0756d076dbc78e8",
+      "sha256": "73e068093dfc88d57dc484582e0c20b1dd5d48bdbe12e860ac6343a64883cf5e",
       "source": "skills/cabloy-backend-scaffold/references/follow-up-checklist.md",
       "target": ".claude/skills/cabloy-backend-scaffold/references/follow-up-checklist.md"
     },
@@ -613,7 +613,7 @@
     {
       "adapter": "claude",
       "category": "skill",
-      "sha256": "ff0760f6fa7c24f561fdcfa07094d9d6e8d82fcef358458a36ff0c38a30ea89e",
+      "sha256": "eccad69c3969f97e80a3766fc2149b9f3e0bf2acd0c8586ed7bed0418f6878a9",
       "source": "skills/cabloy-workflow/SKILL.md",
       "target": ".claude/skills/cabloy-workflow/SKILL.md"
     },
@@ -683,7 +683,7 @@
     {
       "adapter": "cursor",
       "category": "policy",
-      "sha256": "db2467e225f30b74efb312c45572324f75a6a81077e19b7723ffd640a45793f9",
+      "sha256": "539fa24fc49fa8402ea0d9ab89c058762c441d5b3ed87af34a16235d1f8251a0",
       "source": "policies/repository.md",
       "target": ".cursor/rules/cabloy-governance.mdc"
     },
@@ -704,7 +704,7 @@
     {
       "adapter": "cursor",
       "category": "skill",
-      "sha256": "88e6ca8c60d8caeb68ab932f2a7e22810a31911400b4428fd0756d076dbc78e8",
+      "sha256": "73e068093dfc88d57dc484582e0c20b1dd5d48bdbe12e860ac6343a64883cf5e",
       "source": "skills/cabloy-backend-scaffold/references/follow-up-checklist.md",
       "target": ".cursor/skills/cabloy-backend-scaffold/references/follow-up-checklist.md"
     },
@@ -963,7 +963,7 @@
     {
       "adapter": "cursor",
       "category": "skill",
-      "sha256": "ff0760f6fa7c24f561fdcfa07094d9d6e8d82fcef358458a36ff0c38a30ea89e",
+      "sha256": "eccad69c3969f97e80a3766fc2149b9f3e0bf2acd0c8586ed7bed0418f6878a9",
       "source": "skills/cabloy-workflow/SKILL.md",
       "target": ".cursor/skills/cabloy-workflow/SKILL.md"
     },
@@ -1005,14 +1005,14 @@
     {
       "adapter": "codex",
       "category": "policy",
-      "sha256": "307edb0409d7d723c213c534713d2477ba000f19571e054d5498aeb9578b22bb",
+      "sha256": "f8172d4e80dc8b84bf99a0e926184eb78af5bd1fdfcdeebe63b02160f459afce",
       "source": "policies/repository.md",
       "target": "AGENTS.md"
     },
     {
       "adapter": "claude",
       "category": "policy",
-      "sha256": "307edb0409d7d723c213c534713d2477ba000f19571e054d5498aeb9578b22bb",
+      "sha256": "f8172d4e80dc8b84bf99a0e926184eb78af5bd1fdfcdeebe63b02160f459afce",
       "source": "policies/repository.md",
       "target": "CLAUDE.md"
     }

package/repo-agent-governance/policies/repository.md

@@ -71,7 +71,8 @@ Before inventing a custom implementation path:
 - Treat hooks, permissions, local settings, credentials, MCP registration, command discovery, and automatic command execution as platform-specific integrations, not portable rule or skill capabilities.
 - After implementation, do not launch broad reviews automatically; when review is needed, scope it to the current diff and report only high-confidence issues.
 - Do not modify shared environment identity or ports merely to bypass a busy resource. For intentional parallel worktree setup, follow `repo-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.
-- Before `npm run test:e2e`, verify exclusive use of the effective test-database cleanup scope, Redis cleanup namespace, public/runtime paths, and listener; a free port or separate worktree alone is insufficient. If a standing authorization covers this checkout and its resources remain exclusively assigned with no conflicting process, do not repeatedly ask to run the managed suite; if scope or ownership changes or is uncertain, wait or ask. This does not authorize manual resets, broader cleanup, or changing shared configuration. See `repo-docs/reference/repo-scripts.md`.
+- In Cabloy Basic, root `npm run test` and `npm run test:e2e` always allocate an isolated same-checkout test run: disposable run-specific database and Redis namespaces, runtime/public paths, and listener. This protects ordinary development business data, including when a dev server is active in the same checkout. Shared preparation writes (such as builds or dependency generation) are separate accepted prerequisites, not test cleanup of dev business data; do not treat the test isolation as permission to run manual resets or change shared configuration. Check the active edition's scripts before extending this guarantee to Cabloy Start. See `repo-docs/reference/repo-scripts.md`.
+- For isolated E2E through Vona integrated SSR, do not edit Zova `API_BASE_URL` environment values or rebuild solely to match the test port: Vona supplies runtime server/browser API origins. On an origin mismatch, check explicit SSR Site and module-specific API URL overrides first; follow the active repository's scripts for changed SSR/REST artifacts and dependency synchronization. Do not generalize this handoff to Zova standalone SSR or SPA. See [Runtime API origins](repo-docs/fullstack/ssr-entry-modes.md#runtime-api-origins-in-vona-integrated-ssr).
 - 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.
@@ -85,15 +86,17 @@ Before inventing a custom implementation path:
 - When adding a persisted field to an existing backend resource, ask the user whether `vonaModule.fileVersion` should be incremented before changing `meta.version.ts` or the module schema path. If yes, add a new migration version and bump `fileVersion`. If no, keep the current `fileVersion` and fold the schema change into the current version path. Do not assume the versioning strategy without confirmation.
 - In shared-database multitenancy, do not use `table.unique(...)` for business uniqueness. Keep ordinary indexes for lookup performance and enforce tenant-scoped uniqueness in the business layer.
 - In Vona, a tenant corresponds to an instance. Ordinary resource-model CRUD is automatically scoped to the active instance; treat records absent from that scope as absent, and do not use raw cross-instance probes merely to choose between `403` and not-found behavior. Model future multi-merchant boundaries explicitly inside an instance.
+- For stable, reusable Vona relationships, prefer Model relations; load declared relations with targeted ORM `include` in CRUD reads, not by default on every query. Prefer `$Dto.*` inference from Entity/Model and relation truth with deliberate read/write projections; `include` is relation loading, not a SQL join or an authorization/response-filtering boundary. Use dynamic `with`, explicit joins, or explicit DTOs when the contract requires them. See [Relations Guide](repo-docs/backend/relations-guide.md), [ORM Select Guide](repo-docs/backend/orm-select-guide.md), and [DTO Infer and Generation](repo-docs/backend/dto-infer-generation.md).
 - Model cross-Model query-cache dependencies as one directed, acyclic `modelsClear` / `modelsClearedBy` graph, and verify source mutations refresh warmed dependent queries; follow [Cross-model query-cache dependencies](repo-docs/backend/cache-guide.md#cross-model-query-cache-dependencies) before designing a nontrivial graph.
 - For `@Api.field(...)` and related schemaLike composition, framework guards now preserve previously attached OpenAPI metadata across schema rebuilds, but structure-shaping schemaLike is still order-sensitive. Treat `v.object(...)`, `v.array(...)`, `v.optional()`, `v.nullable()`, `v.default(...)`, and preprocess/transform wrappers as structure-shaping; keep the final structure-defining schemaLike last and verify emitted schema/OpenAPI output after such edits.
+- Keep ordinary, independent CRUD writes simple: do not add an explicit transaction or pessimistic update lock by default. Add a transaction when a business operation requires multiple writes to commit or roll back together; add concurrency control only for a defined invariant or contention requirement, using no more locking than that guarantee needs. A transaction alone does not prevent write races, and an update method name alone does not justify a lock. See [Transaction Guide](repo-docs/backend/transaction-guide.md).
 - `@Core.transaction(...)` defaults to `REQUIRED`: it starts a transaction only when none exists and otherwise joins the current datasource transaction without upgrading its isolation. Prefer it over manual `inTransaction` wrappers for atomic service methods; use `REQUIRES_NEW` only when an independently committed boundary is explicitly required.
 - For replay-safe transient failures, use `@Core.retryable(...)` with an explicit `errorCodes` allowlist. It retries the downstream AOP suffix, so place it closest to the method when it must wrap and retry a `@Core.transaction(...)` boundary; use `ownerOnly: true` for dual-role leaves that must not retry inside a caller-owned transaction; do not retry external side effects or infer retryability from isolation level.
 - Backend tests that use scoped Vona state must own an `app.bean.executor.mockCtx(...)` boundary; every intentionally competing operation must run in a separate `mockCtx(...)`.
 - Do not set `TEST_CONCURRENCY=false` for normal `npm run test` or CI runs: an unset value defaults to concurrent execution. For stateful `node:test` suites, declare `{ concurrency: false }` explicitly. Prove business contention by explicitly launching competing operations and asserting their combined durable outcome, never through runner parallelism or scheduling.
 - Unit tests must not temporarily mutate process-global origin or proxy configuration, including `app.config.server.serve.protocol`, `app.config.server.serve.host`, and `app.proxy`. Model request-origin cases with an explicit `req` fixture, and use the established `AppUtil` loopback fallback for requestless local URLs. Do not introduce a broad origin lock to serialize such tests; retain narrowly scoped locks only for genuinely shared domain state.
 - Unit tests must delete every test-owned persisted resource in `finally`, using precise owned identities and reverse dependency order.
-- Shared durable test or local-development fixtures must be created through the owning module's `meta.version.ts` `seed()` hook and treated as read-only by tests; the managed seed path starts from a newly recreated database rather than repeating against one database.
+- Shared durable test or local-development fixtures must be created through the owning module's `meta.version.ts` `seed()` hook and treated as read-only by tests; seeds run on isolated test-mode startup or after an explicit dev-mode `npm run db:reset` against a newly recreated disposable database, not on ordinary dev startup or repeatedly against one database.
 
 ## Verification expectations
 

package/repo-agent-governance/skills/cabloy-backend-scaffold/references/follow-up-checklist.md

@@ -44,7 +44,7 @@ When the active edition and installed modules provide `@Passport.rbac(...)` and
 - `meta.version`
 - field indexes; in shared-database multitenancy, preserve ordinary lookup indexes and enforce business uniqueness in tenant-aware business logic rather than with `table.unique(...)`
 - when editing or generating `meta.index`, consolidate each table's specifications into one declaration instead of adding another same-table `$tableColumns` spread; check for leading-column name collisions, effective metadata, and physical index definitions using the [Field Indexes guide](../../../../repo-docs/backend/field-indexes.md)
-- relations
+- relations: define stable, reusable business relationships on the Model (`hasOne`, `belongsTo`, `hasMany`, `belongsToMany`); for CRUD reads, load only the relations the endpoint needs via `include`, and align the `$Dto.*` relation projection with the ORM query. Use dynamic `with` for situational relations; when related rows determine which parents appear, filter the parent query rather than relying on `include`. See [Relations Guide](../../../../repo-docs/backend/relations-guide.md) and [ORM Select Guide](../../../../repo-docs/backend/orm-select-guide.md).
 - datasource choice
 - cache behavior
 - cross-Model query-cache dependencies: when a source mutation can change another Model's cached query members, totals, projections, includes, or visibility, declare exactly one directed `modelsClear` / `modelsClearedBy` edge
@@ -52,7 +52,7 @@ When the active edition and installed modules provide `@Passport.rbac(...)` and
 - when `modelsClearedByFn` is required, treat it as replacement behavior and explicitly own the target clear and any necessary downstream propagation
 - prefer normal Model/service mutation paths so source invalidation, commit-time re-clear, and configured double-delete remain active
 - add a warm-query → mutate-source → repeat-query regression test for each new dependency path; follow [Cross-model query-cache dependencies](../../../../repo-docs/backend/cache-guide.md#cross-model-query-cache-dependencies) for the portable decision rules
-- transaction behavior
+- transaction and concurrency requirements: leave independent CRUD writes without an explicit transaction or pessimistic lock by default; identify any multi-write atomicity or contention-sensitive invariant before choosing a transaction and the minimum necessary concurrency control. See [Transaction Guide](../../../../repo-docs/backend/transaction-guide.md).
 
 ## Test resource lifecycle follow-up
 

package/repo-agent-governance/skills/cabloy-workflow/SKILL.md

@@ -113,6 +113,8 @@ This routing skill provides read-only guidance only. Do not infer an `APP_NAME`
 
 The invoked skill detects Basic or Start to select the active root scripts and managed 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.
 
+For isolated E2E through Vona integrated SSR, use the [runtime API-origin guidance](../../../repo-docs/fullstack/ssr-entry-modes.md#runtime-api-origins-in-vona-integrated-ssr): a dynamic test port alone requires neither a Zova `.env` edit nor a frontend rebuild. This is separate from explicitly requested worktree development configuration; check the active scripts for artifact preparation and explicit API URL overrides.
+
 ## Step 4: Prefer CLI-first workflows
 
 Whenever the task maps to an existing generator, initializer, refactor, or metadata command, prefer the CLI.

package/repo-docs/backend/migration-and-changes.md

@@ -94,11 +94,11 @@ export class MetaVersion extends BeanBase {}
 
 Three migration scenarios are defined:
 
-| Scenario | Purpose                                          |
-| -------- | ------------------------------------------------ |
-| `update` | schema evolution such as tables and fields       |
-| `init`   | instance- or tenant-specific initialization data |
-| `seed`   | shared baseline data for the test environment    |
+| Scenario | Purpose                                             |
+| -------- | --------------------------------------------------- |
+| `update` | schema evolution such as tables and fields          |
+| `init`   | instance- or tenant-specific initialization data    |
+| `seed`   | baseline data for test runs and explicit dev resets |
 
 This split is one of the most important Vona migration ideas because it separates:
 
@@ -110,7 +110,7 @@ A practical generated-thread interpretation is:
 
 - `update` follows schema and entity/model evolution
 - `init` follows instance-aware initialization needs introduced by the backend feature
-- `seed` provides shared baseline data while the application starts in test mode
+- `seed` provides shared baseline data during test-mode startup or an explicit development database reset
 
 ## Update: schema migration
 
@@ -153,7 +153,7 @@ export class MetaVersion extends BeanBase implements IMetaVersionInit {
 
 The important point is that initialization can run per instance or tenant, which keeps tenant data isolated.
 
-## Seed: test-environment baseline data
+## Seed: test and reset baseline data
 
 Representative pattern:
 
@@ -171,9 +171,9 @@ export class MetaVersion extends BeanBase implements IMetaVersionSeed {
 
 This is valuable because shared baseline data becomes part of the structured version lifecycle instead of being scattered across unrelated setup code.
 
-Vona invokes `seed()` while the application starts in test mode. Use it for durable baseline fixtures shared by multiple tests, E2E tests, or the managed local-development test-data workflow. The seed path starts from a newly recreated managed database; it is not a repeatable, same-database data-import mechanism.
+Vona invokes `seed()` while the application starts in test mode (`npm run test` or managed E2E), and during an explicit `npm run db:reset` in dev mode. Ordinary development startup and framework upgrades do not seed or reset development data automatically. Use `seed()` for durable baseline fixtures shared by tests or for freshly prepared local development data. Both paths seed after instance initialization on a newly recreated disposable database; `seed()` is not a repeatable, same-database data-import mechanism.
 
-Treat shared `seed()` records as read-only in ordinary tests. A scenario that needs different state must create independent, test-owned data and clean it up in `finally`; it must not mutate or delete the shared baseline. `seed()` remains distinct from `init()`: use `init()` for instance-aware initialization data and reserve `seed()` for shared test-environment baseline data.
+Treat shared `seed()` records as read-only in ordinary tests. A scenario that needs different state must create independent, test-owned data and clean it up in `finally`; it must not mutate or delete the shared baseline. `seed()` remains distinct from `init()`: use `init()` for instance-aware initialization data and reserve `seed()` for baseline data in test runs or explicit development resets.
 
 ## Version changes across the generated backend thread
 
@@ -199,13 +199,14 @@ Representative commands:
 
 ```bash
 npm run test
-cd vona && npm run db:reset
+npm run db:reset
 ```
 
 A practical decision rule is:
 
-- use `db:reset` when you mainly need to replay migration/database setup locally
-- use `test` when you need to verify that migration, controller behavior, and the broader generated contract thread still work together
+- use `db:reset` to recreate the disposable **dev-mode** databases, rerun migrations and instance initialization, and then invoke module `seed()` hooks; it deletes existing matching development databases, so do not run it against data you need to keep
+- `db:reset` requires `database.testDatabase: true` in dev config and a connection outside the disposable database; it refuses to reset a configured non-disposable database
+- use `test` when you need **test-mode** verification of migration, controller behavior, and the broader generated contract thread; E2E also remains test-mode
 
 ## Implementation checks for migration-sensitive changes
 

package/repo-docs/backend/orm-select-guide.md

@@ -83,6 +83,12 @@ A useful distinction is:
 
 That means joins are not floating SQL trivia. They are part of a model-aware query system that can move between table-level control and relation-level convenience.
 
+For stable, reusable business relationships, declare the appropriate `hasOne`, `belongsTo`, `hasMany`, or `belongsToMany` relation on the Model and prefer `include` when a CRUD read needs its related data. Use `with` for a situational relation instead of adding every one-off lookup to Model metadata. See [Relations Guide](/backend/relations-guide#static-relations-vs-dynamic-relations). An `include` loads and attaches related records after the parent query; it is **not** automatically a SQL `JOIN` between the parent and related tables. In list reads, the ordinary relation loader batches related lookups, but this still adds queries and may load large collections. Select only the relations and fields needed by that endpoint.
+
+A relation's `where` filters the related rows that are attached; it does not remove parent rows or change a parent's `selectAndCount` total. If the presence of a matching child determines which parents belong in a list, put that condition in the parent query, for example with `_exists_` or a deliberately chosen `joins` predicate. Paginate the parent results explicitly and load bounded relation projections. A `hasMany` relation `limit` on a multi-parent list applies to the shared child query, not separately to each parent; for per-parent top-N requirements, design a query for that contract rather than assuming `include` provides it. Direct joins to collections can multiply parent rows and distort pagination or counts, so verify those semantics before using them.
+
+Match the read's selected relations to its `$Dto.*` projection when inferring an API contract; inference describes the shape, but does not trigger ORM loading or strip extra response fields by itself. See [DTO Infer and Generation](/backend/dto-infer-generation#default-first-three-layer-dto-authoring).
+
 ## Type-guided joins
 
 A key insight is that joinable tables often come from relationships already declared on the model.

package/repo-docs/backend/runtime-and-flavors.md

@@ -57,7 +57,8 @@ cd vona && npm run start:one
 In the current repo, those scripts map naturally to:
 
 - `dev` commands -> development mode
-- `test` / `cov` / `db:reset` -> test mode
+- `test` / `cov` -> test mode through the same per-run isolated runner as root `npm run test` (root `npm run test:e2e` also uses an isolated test mode); raw `:bin:test` bypasses the wrapper
+- `db:reset` -> development mode (explicitly recreates disposable development databases and runs module seeds)
 - `build` / `start` -> production mode
 
 ## Flavors

package/repo-docs/backend/transaction-guide.md

@@ -29,6 +29,18 @@ async transaction() {
 
 This matters because it makes transaction behavior explicit at the business-method level.
 
+## Choose atomicity and concurrency guarantees separately
+
+Keep ordinary, independent CRUD writes simple: do not add an explicit transaction or pessimistic update lock just because a method is named `create`, `update`, or `delete`. A Model mutation participates in an existing transaction on its datasource, but ordinary CRUD does not automatically start a transaction around the entire service method. A single Model call can also perform more than one write, so do not assume that a compound call is an all-or-nothing business operation without checking its behavior.
+
+Ask what the business operation must guarantee:
+
+- **Multiple writes must succeed or fail together:** put a transaction around the business unit of work. Parent/companion writes and all-or-nothing bulk commands are examples. A transaction gives atomicity, not automatic protection against every concurrent write race.
+- **A shared invariant depends on previously read state:** define the competing operations and required outcome, then select a concurrency strategy. Depending on the operation, that may be an atomic conditional update, optimistic version check, suitable isolation with retry, or a pessimistic row lock inside a transaction. For a read-modify-write balance or a check-then-insert path, a transaction alone may still allow a lost update or duplicate first insert.
+- **No cross-write or contention guarantee is required:** leave the CRUD operation without an additional explicit transaction or pessimistic lock. This is a decision about application-level guarantees, not a claim that the database never locks rows while executing writes.
+
+For an optional one-to-one companion, updating parent fields and companion content together can justify a transaction. If concurrent first writes must leave exactly one companion, locking an existing companion row cannot protect its first insertion: a parent-row serialization point or another deliberate strategy is needed. Once all competing writers use the same parent-row serialization point, an additional companion-row lock on that path may be redundant; verify that no writer bypasses the serialization point before removing it. Test the required combined durable outcome under competing operations. See [One-to-One Companion Resource Guide](/fullstack/one-to-one-companion-resource-guide#consistency-modes-and-concurrency) and [Unit Testing](/backend/unit-testing).
+
 ## Manual transactions
 
 Vona also supports manual transaction control using either:

package/repo-docs/backend/unit-testing.md

@@ -47,12 +47,14 @@ npm run test
 A typical Vona test flow includes:
 
 1. create one shared global `app` object for the test run
-2. clean Redis data
-3. recreate the database
-4. execute migration code
+2. clean the run's Redis namespace and run-specific public/runtime paths
+3. recreate the run's disposable test database
+4. execute migration and instance initialization code, then module `seed()` hooks
 5. run the test files
 6. close the shared application after the test run
 
+In Cabloy Basic, root `npm run test` delegates to `vona/`'s `npm run test`; both allocate an isolated test identity, database and Redis namespace, Vona generated/runtime/public paths, and loopback listener. They can run in the same checkout as an ordinary development server without resetting or mutating that server's business data. Even a targeted run performs the test-mode setup. The Vona `npm run cov` script uses the same isolation; raw `:bin:test` commands do not. Shared build/dependency preparation may still write to shared artifacts, and custom external resources need separate isolation. See [Repo Scripts](/reference/repo-scripts#test-isolation-and-development-data-in-cabloy-basic).
+
 The runner owns this application lifecycle. Test files import the shared app from `vona-mock` and must not create or close it themselves:
 
 ```typescript
@@ -61,15 +63,15 @@ import { app } from 'vona-mock';
 
 This is one of the most important distinctions from ordinary app flow: test execution rebuilds and verifies the framework lifecycle, not only the target function.
 
-## Reset database without running tests
+## Reset development database without running tests
 
-Representative command:
+From the repository root:
 
 ```bash
-cd vona && npm run db:reset
+npm run db:reset
 ```
 
-This is useful when you want to reapply migration logic without running the entire test suite.
+This is an explicit, destructive **dev-mode** command, not test isolation: it recreates matching disposable development databases, reapplies migration and instance initialization, and runs module `seed()` hooks. It requires `database.testDatabase: true` in dev configuration and a connection outside the disposable database. Ordinary dev startup does not seed; do not reset if you need to keep its existing business data. See [Migration and Changes](/backend/migration-and-changes#local-development-workflow).
 
 ## Coverage
 
@@ -79,6 +81,8 @@ Representative command:
 cd vona && npm run cov
 ```
 
+This script runs under the same isolated test environment as Vona's `npm run test`. It writes `vona/coverage/lcov.info` and, unless `--ci` is supplied, `vona/coverage/report`. These reports are shared checkout-level artifacts rather than per-run test data; do not run coverage jobs simultaneously in one checkout. Use `npm run cov -- --ci` to skip the viewer in CI.
+
 ## Runner concurrency
 
 The Vona runner uses Node's built-in test runner with one shared application and process isolation disabled. `TEST_CONCURRENCY` controls runner scheduling:
@@ -129,7 +133,7 @@ Locale-sensitive variants and additional request-context helpers are also availa
 Classify persisted test data before creating it:
 
 - use a **test-local fixture** for a single test or scenario;
-- use an owning module's `meta.version.ts` `seed()` hook only for stable baseline data shared across tests or intentionally used by the local-development test-data workflow.
+- use an owning module's `meta.version.ts` `seed()` hook only for stable baseline data shared across isolated test runs or intentionally prepared by an explicit dev-mode database reset.
 
 A test owns every persisted resource it creates. Keep the returned entity or exact ID and delete owned records from `finally`, including when an assertion or action fails. Delete dependents before their owners and use the same active tenant/instance context that created them. Do not discover cleanup targets through broad table queries, time-based prefixes, or business conditions when the test already knows the exact identity.