cabloy 5.1.204 → 5.1.205

package/.cabloy-version

@@ -1 +1 @@
-5.1.204
+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,5 +1,16 @@
 # Changelog
 
+## 5.1.205
+
+### Features
+
+- Update functionality.
+
+### Bug Fixes
+
+- Respect CLI publish boundaries.
+- Preserve test claim identities.
+
 ## 5.1.204
 
 ### Improvements

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.204",
+  "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",
@@ -47,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

@@ -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"
     },
@@ -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": "e57b3389c32379a1bdebc4ca716f1e7b21cd8bf960d5aa2c1d7b61d79c1ac556",
+      "sha256": "539fa24fc49fa8402ea0d9ab89c058762c441d5b3ed87af34a16235d1f8251a0",
       "source": "policies/repository.md",
       "target": ".cursor/rules/cabloy-governance.mdc"
     },
@@ -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": "0c22d8b0c25b20e5325ea0aa8e8272bb68e6f5752f1b14238b98814c8935fd5a",
+      "sha256": "f8172d4e80dc8b84bf99a0e926184eb78af5bd1fdfcdeebe63b02160f459afce",
       "source": "policies/repository.md",
       "target": "AGENTS.md"
     },
     {
       "adapter": "claude",
       "category": "policy",
-      "sha256": "0c22d8b0c25b20e5325ea0aa8e8272bb68e6f5752f1b14238b98814c8935fd5a",
+      "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.
@@ -95,7 +96,7 @@ Before inventing a custom implementation path:
 - 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-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/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/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.
 

package/repo-docs/blogs/ai-coding-one-prompt-crud-ssr-multitasking/index.md

@@ -57,11 +57,11 @@ It examines the project and generator commands, then uses Vona's CRUD generator
 
 The resulting book form has three fields:
 
-| Field | Purpose | Requirement |
-| --- | --- | --- |
-| Title | Book title | Required |
-| Author | Book author | Required |
-| Description | Book description | Optional |
+| Field       | Purpose          | Requirement |
+| ----------- | ---------------- | ----------- |
+| Title       | Book title       | Required    |
+| Author      | Book author      | Required    |
+| Description | Book description | Optional    |
 
 One useful part of the development experience is immediately apparent: **once the business resource is defined, the list, detail view, and forms can reuse CabloyJS's existing schema-driven CRUD pages. There is no need to build a new management interface from scratch.**
 
@@ -163,10 +163,10 @@ Don't submit this time. Leave the form as a draft.
 
 The task tabs now contain three open tasks:
 
-| Task | Content |
-| --- | --- |
-| Edit | Book One's edit form |
-| Detail | Book One's detail view |
+| Task   | Content                     |
+| ------ | --------------------------- |
+| Edit   | Book One's edit form        |
+| Detail | Book One's detail view      |
 | Create | Book Two's unsubmitted form |
 
 ### Switch Back and Continue Where You Left Off

package/repo-docs/frontend/scripts.md

@@ -51,7 +51,7 @@ The `dev:zova:*` commands start the Zova development server, which uses `9000` i
 
 ## Vona integrated SSR browser acceptance
 
-The default Basic Web and Admin sites have browser smoke commands that exercise Vona integrated SSR through Vona SSR dispatch at port `7102`, not through the Zova standalone SSR development-server port.
+The default Basic Web and Admin sites have browser smoke commands that exercise Vona integrated SSR through Vona SSR dispatch at the managed run's dynamically allocated test listener, not through the ordinary Vona development listener (`7102` by default) or the Zova standalone SSR development-server port. Vona supplies the API origin at runtime, so no Zova `.env` change or rebuild is needed solely for the test port; see [Runtime API origins in Vona integrated SSR](/fullstack/ssr-entry-modes#runtime-api-origins-in-vona-integrated-ssr).
 
 Prepare current SSR and REST artifacts explicitly when frontend output has changed:
 

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

@@ -1,10 +1,10 @@
 # Parallel Worktree Environment
 
-Use worktree-local environment overrides when two Cabloy Basic or Cabloy Start worktrees need to run ordinary local development or managed E2E checks at the same time.
+Use worktree-local environment overrides when two Cabloy Basic or Cabloy Start worktrees need to run ordinary local development at the same time. In Cabloy Basic, root `npm run test` and `npm run test:e2e` already isolate their test-mode runtime and data on every run, including alongside ordinary dev in the **same** checkout; they do not require this worktree setup for that purpose.
 
-This Cabloy Basic page is the canonical shared recipe for both editions. Detect the active edition before selecting commands, but keep the same two-file environment model.
+This Cabloy Basic page is the canonical shared recipe for both editions. Detect the active edition before selecting commands, but keep the same two-file environment model for worktree-local development.
 
-This workflow creates a standard isolated local runtime without changing committed environment defaults. It does not automatically isolate every external dependency.
+This workflow creates a standard isolated local development runtime without changing committed environment defaults. It does not automatically isolate every external dependency.
 
 ## Before creating local overrides
 
@@ -82,13 +82,13 @@ Use commands from the active repository root.
 | Cabloy Basic | `__CABLOY_BASIC__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e` |
 | Cabloy Start | `__CABLOY_START__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e` |
 
-Run one frontend command, not both, in each worktree. Both managed E2E workflows read Vona's effective local `SERVER_LISTEN_PORT` and start one fresh Vona test-mode worker; startup initializes test resources without a separate reset. Before either command, confirm exclusive ownership of the effective test database, `_local` Redis namespace, public/runtime paths, `APP_NAME`, API origin, and listener. A free port alone does not establish ownership. Do not change shared identity or ports to bypass a collision, and leave `E2E_BASE_URL` unset: externally managed targets are unsupported.
+Run one frontend command, not both, in each worktree. In Cabloy Basic, root `npm run test` and `npm run test:e2e` allocate a fresh run-specific identity, test database and Redis namespace, generated/runtime/public paths, and loopback listener independently of the worktree's development environment. Managed E2E starts a fresh Vona test-mode worker, and startup initializes test resources and module seeds without a separate dev-mode reset. This also isolates tests from a dev process in the same checkout. Cabloy Start's managed E2E uses the effective local test-mode Vona listener and its own ownership rules; inspect its root scripts before relying on Basic's isolation. Leave `E2E_BASE_URL` unset: externally managed targets are unsupported. Do not change shared identity or ports merely to bypass a busy development resource.
 
 ## What this isolates
 
-A unique `APP_NAME` separates the application identity used by ordinary framework-managed local resources, including managed test database names and Redis-related key prefixes. Worktree-local generated files, runtime files, build output, and coverage output are already separated by their worktree paths.
+A unique worktree `APP_NAME` separates the identity of ordinary development resources across worktrees, including framework-managed development database names and Redis-related key prefixes. Worktree-local generated files, runtime files, build output, and coverage output are already separated by their worktree paths. Cabloy Basic root tests use a separate run-specific identity even when invoked inside a worktree; they do not clean its ordinary development business data.
 
-The generated Vona, Zova development HTTP, and Zova HMR ports let worktrees run their ordinary local processes concurrently. The matching Zova API URL prevents the frontend in one worktree from calling the Vona process in another.
+The generated Vona, Zova development HTTP, and Zova HMR ports let worktrees run their ordinary local processes concurrently. The matching Zova API URL prevents the frontend in one worktree from calling the Vona process in another. Builds, dependency generation, and other shared preparation writes remain accepted prerequisites rather than part of test data cleanup.
 
 This is sufficient for the normal local workflows:
 

package/repo-docs/fullstack/ssr-entry-modes.md

@@ -15,6 +15,25 @@ Zova standalone SSR:    browser → Zova development server → frontend SSR →
 
 In the Cabloy Basic default environment, `SERVER_LISTEN_PORT=7102` is the Vona entry and `DEV_SERVER_PORT=9000` is the Zova development entry. These are separate listeners, not two ports for the same server. Zova's `API_BASE_URL` points to Vona, not to its own development port. Local environment overrides can change the ports; use the effective values in your checkout.
 
+## Runtime API origins in Vona integrated SSR
+
+Vona integrated SSR supplies API origins at runtime; this mechanism is not specific to an edition or frontend flavor. By default, Vona derives the origin from its effective protocol and host and passes:
+
+- `envServer.SSR_API_BASE_URL` to the built Zova server bundle during initialization.
+- `envClient.API_BASE_URL` through the SSR state to the browser during client initialization.
+
+These runtime values override Zova's build-time environment defaults used by the normal API client. They do not rewrite hard-coded URLs or arbitrary build-time substitutions in application code.
+
+For an isolated `npm run test:e2e` that enters through Vona integrated SSR, the runner's dynamic Vona origin is therefore sufficient: **do not edit Zova `.env` files or rebuild the flavor solely to match the test port**. A new listener address alone does not make the bundle stale.
+
+Artifact preparation is a separate concern. When frontend code, routes, metadata, or other build inputs change, refresh the required SSR/REST artifacts and synchronize Vona dependencies as required. Resolve commands and flavors from the active repository's scripts; do not assume every edition's E2E command builds the frontend automatically. See [SSR Build and Deploy Guide](/frontend/ssr-build-deploy-guide) and [Repo Scripts](/reference/repo-scripts).
+
+The injected origins are defaults, with these boundaries:
+
+- Vona merges the default origins first, then the `a-ssr` module's `site.default` configuration, then the individual SSR Site options. An explicit `envServer.SSR_API_BASE_URL` or `envClient.API_BASE_URL` in those site settings overrides the corresponding default; a value only in Zova's build-time `.env` does not count as a site override.
+- Generated OpenAPI clients prefer their module-specific `OPENAPI_BASE_URL_*`, then `OPENAPI_BASE_URL_DEFAULT`, before the server or browser API-origin fallback. Custom API configuration and hard-coded URLs also require separate inspection when requests reach the wrong origin.
+- Zova standalone SSR and SPA do not automatically receive this Vona integrated SSR handoff. Keep their environment setup separate from this rule, including deliberate [parallel worktree development configuration](/fullstack/parallel-worktree-environment).
+
 ## Start and use them in Cabloy Basic
 
 Start the Vona server from the repository root and visit a Vona-served site:

package/repo-docs/reference/repo-scripts.md

@@ -41,6 +41,7 @@ Cabloy Basic exposes these shared root scripts:
 - `npm run start:one`
 - `npm run test`
 - `npm run test:e2e`
+- `npm run db:reset`
 - `npm run tsc`
 - `npm run docs:dev`
 - `npm run docs:build`
@@ -48,6 +49,26 @@ Cabloy Basic exposes these shared root scripts:
 
 `npm run init` prepares all Cabloy Basic SSR and REST artifacts with `npm run build:zova:all`, which sequentially builds the Basic and Commerce flavor batches before Vona initialization. Use `build:zova` or `build:zova:commerce` for focused artifact refreshes; use `build:zova:all` only when every shipped Basic flavor must be prepared.
 
+## Test isolation and development data in Cabloy Basic
+
+Root `npm run test` delegates to Vona's `npm run test`; both it and direct `cd vona && npm run test` use the same isolated runner. Vona's `npm run cov` also uses that runner and enables coverage. Root `npm run test:e2e` retains its own isolated E2E entrypoint. Each command launches a new test-mode run, even in the same checkout as a running development server. The runner chooses a UTC `YYYYMMDDHHmmss` timestamp plus eight lowercase cryptographically random hexadecimal characters for one run ID (for example, `20261014010203-a1b2c3d4`). This ID names both owned Vona directories (`.app-test-<id>` and `.vona-test-<id>`) and the disposable database and Redis namespaces; the runner also allocates a loopback listener. The runner exclusively creates an ignored JSON claim at `vona/.vona-test-claim/<id>.json` before allocating resources. A rare claim or directory collision fails without adopting or deleting the existing paths; rerun the command. Independent checkouts sharing database or Redis services do not share these claims, so their random suffixes reduce, but cannot eliminate, cross-checkout collisions.
+
+Claims contain a versioned, nonsecret resource inventory: owned local roots, exact database allocation intents, Redis namespaces and endpoint identities, process ownership, and cleanup progress. Allocators must receive an acknowledgment that their intent is recorded before creating a database or using framework-managed Redis resources. Credentials, full environment/configuration snapshots, and readiness secrets are not stored in claims.
+
+Successful unit, coverage, and managed application E2E runs release inventoried database and Redis resources and remove their owned local roots after process shutdown is verified. Managed E2E uses a registered browser fixture to verify detached browser-group shutdown; its run-owned reports, traces, and temporary profiles are deleted on success too. The claim is deleted last. Failed or interrupted runs retain their claim and resources for inspection. Cleanup failure also makes the command fail and retains the journal for retry.
+
+Before each new invocation, the runner checks retained claims against their immutable UTC creation timestamp. Claims older than one day are eligible for cleanup; set `VONA_TEST_CLAIM_TTL_SECONDS` to a positive integer to change the default `86400` seconds. Eligibility is not permission to delete a live or unowned resource: the runner retains malformed claims, mismatched owner markers, symlinked paths, changed service endpoints, live or uncertain process identities, incomplete launch registrations, and claims with an existing cleanup lock. Inspect these warnings manually; a lock is never taken over merely because it is old. Cleanup resolves current trusted configuration without starting the application, running seeds, or opening a listener. It drops only recorded database names and scans only exact recorded Redis prefixes, never flushing Redis. Partial progress is journaled so a later eligible cleanup can retry safely. Legacy `.vona-test-claim-<id>` directories and inventory-less run roots are not automatically migrated or deleted.
+
+All three commands initialize test databases and run module `seed()` hooks; none resets the ordinary dev-mode database or deletes its business data. A narrow test selection still initializes the test environment. Raw `:bin:test` invocations bypass the public scripts and do not get the runner's isolation guarantee.
+
+Coverage reports (`vona/coverage/lcov.info` and, without `--ci`, `vona/coverage/report`) are shared checkout-level artifacts, not run-owned data. Avoid overlapping coverage runs or relying on these reports as independent per-run output.
+
+Builds, generated artifacts, dependency installation/generation, and other shared preparation writes remain accepted prerequisites when needed. Test isolation does not make those writes private or authorize an unrelated reset of development data. The run-specific identity namespaces framework-managed resources; separately configured external databases, Redis targets or unprefixed custom keys, and third-party providers still require deliberate ownership and isolation. Inspect the active edition's scripts rather than assuming Cabloy Start already uses the same root runner.
+
+For Vona integrated SSR, the allocated E2E origin is supplied to Zova at runtime as server `SSR_API_BASE_URL` and browser `API_BASE_URL`. Do not edit Zova `.env` files or rebuild solely to match the test port. The current root `npm run test:e2e` consumes prebuilt frontend artifacts; refresh affected SSR/REST output and synchronize dependencies when their inputs change. See [Runtime API origins in Vona integrated SSR](/fullstack/ssr-entry-modes#runtime-api-origins-in-vona-integrated-ssr) for configuration overrides and scope.
+
+For a deliberate **dev-mode** database recreation, `npm run db:reset` is a separate, destructive command: it drops matching disposable development databases, reruns migrations and instance initialization, then runs module `seed()` hooks. It requires `database.testDatabase: true` in the dev configuration and a connection outside the disposable database. Ordinary `npm run dev` does not seed or reset; never run `db:reset` against development data you need to retain. Upgrades no longer initialize development test data automatically. See [Migration and Changes](/backend/migration-and-changes#local-development-workflow).
+
 ## Specification planning and derived charts
 
 The current Cabloy Basic root scripts also expose:
@@ -151,7 +172,7 @@ The public-package upgrade flow does not source or reconcile the Start-owned bas
 
 ## SSR browser checks
 
-Cabloy Basic and Cabloy Start each use a single managed local `npm run test:e2e` command. In Basic, the runner checks the effective `normal/test/local` Vona listener port and starts one fresh `--workers=1 --flavor=normal --mode=test` worker. Test-mode startup initializes test resources; the runner does not invoke a separate `db:reset` or a development-mode server. Playwright does not reuse an existing process. Confirm exclusive ownership of the effective test database, `_local` Redis namespace, public/runtime paths, `APP_NAME`, API origin, and listener before starting it; port availability alone is insufficient.
+Cabloy Basic and Cabloy Start each use a managed local `npm run test:e2e` command. In Basic, the root wrapper allocates a run-specific test identity, disposable database and Redis namespaces, Vona generated/runtime/public paths, and an available loopback port, then starts a fresh `--workers=1 --flavor=normal --mode=test` worker. Test-mode startup initializes test resources and invokes module seeds without a separate dev-mode `db:reset`; Playwright does not reuse an existing process. This protects ordinary same-checkout development data and permits a Basic root E2E run alongside a dev server, subject to the shared-preparation and external-resource boundaries above. Inspect the Start repository's current scripts for its own resource-ownership rules.
 
 Both editions' browser checks target Vona integrated SSR. In the Cabloy Basic default environment, the Vona listener is `7102`; the Zova standalone SSR development server uses `9000` and is not an acceptance target.
 

package/repo-e2e/config/playwright.config.ts

@@ -4,26 +4,44 @@ import { E2E_LOCAL_BASE_URL, E2E_ROOT_DIR } from '../scripts/e2e.ts';
 
 export default defineConfig({
   testDir: `${E2E_ROOT_DIR}/repo-e2e/specs`,
+  outputDir: process.env.VONA_TEST_RUN_ID
+    ? `${E2E_ROOT_DIR}/vona/.app-test-${process.env.VONA_TEST_RUN_ID}/test-results`
+    : `${E2E_ROOT_DIR}/repo-e2e/test-results`,
   fullyParallel: false,
   workers: 1,
   forbidOnly: !!process.env.CI,
   retries: process.env.CI ? 2 : 0,
-  reporter: process.env.CI ? [['html', { open: 'never' }], ['list']] : 'list',
+  reporter: process.env.CI
+    ? [
+        [
+          'html',
+          {
+            open: 'never',
+            outputFolder: process.env.VONA_TEST_RUN_ID
+              ? `${E2E_ROOT_DIR}/vona/.app-test-${process.env.VONA_TEST_RUN_ID}/playwright-report`
+              : `${E2E_ROOT_DIR}/repo-e2e/playwright-report`,
+          },
+        ],
+        ['list'],
+      ]
+    : 'list',
   use: {
     baseURL: E2E_LOCAL_BASE_URL,
     trace: 'on-first-retry',
   },
-  webServer: {
-    command: 'node repo-e2e/scripts/startE2eVona.ts',
-    cwd: E2E_ROOT_DIR,
-    url: `${E2E_LOCAL_BASE_URL}/health/ready`,
-    timeout: 180_000,
-    reuseExistingServer: false,
-    stdout: 'pipe',
-    stderr: 'pipe',
-    gracefulShutdown: {
-      signal: 'SIGINT',
-      timeout: 10_000,
-    },
-  },
+  webServer: process.env.VONA_TEST_RUN_ID
+    ? undefined
+    : {
+        command: 'node repo-e2e/scripts/startE2eVona.ts',
+        cwd: E2E_ROOT_DIR,
+        url: `${E2E_LOCAL_BASE_URL}/health/ready`,
+        timeout: 180_000,
+        reuseExistingServer: false,
+        stdout: 'pipe',
+        stderr: 'pipe',
+        gracefulShutdown: {
+          signal: 'SIGINT',
+          timeout: 10_000,
+        },
+      },
 });

package/repo-e2e/scripts/e2e.test.ts

@@ -15,3 +15,42 @@ test('rejects a defined E2E_BASE_URL before loading local configuration', () =>
     assert.doesNotMatch(result.stderr, /SERVER_LISTEN_PORT/);
   }
 });
+
+test('isolated E2E target follows the assigned listener', () => {
+  const entrypoint = fileURLToPath(new URL('./e2e.ts', import.meta.url));
+  const result = spawnSync(
+    process.execPath,
+    [
+      '--input-type=module',
+      '-e',
+      `import { E2E_LOCAL_BASE_URL } from ${JSON.stringify(entrypoint)}; console.log(E2E_LOCAL_BASE_URL)`,
+    ],
+    {
+      env: {
+        ...process.env,
+        E2E_BASE_URL: undefined,
+        VONA_TEST_RUN_ID: '20261014010203-a1b2c3d4',
+        APP_NAME: 'cabtest20261014010203-a1b2c3d4',
+        SERVER_LISTEN_PORT: '42321',
+      },
+      encoding: 'utf8',
+    },
+  );
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout.trim(), 'http://127.0.0.1:42321');
+});
+
+test('rejects a malformed isolated E2E run ID', () => {
+  const entrypoint = fileURLToPath(new URL('./e2e.ts', import.meta.url));
+  const result = spawnSync(process.execPath, [entrypoint], {
+    env: {
+      ...process.env,
+      E2E_BASE_URL: undefined,
+      VONA_TEST_RUN_ID: '20260230010203-a1b2c3d4',
+      SERVER_LISTEN_PORT: '42321',
+    },
+    encoding: 'utf8',
+  });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /Invalid isolated test run ID/);
+});

package/repo-e2e/scripts/e2e.ts

@@ -13,7 +13,25 @@ const vonaEnv = dotenv.loadEnvs(
   resolve(E2E_ROOT_DIR, 'vona', 'env'),
   '.env',
 );
-const e2ePort = Number(vonaEnv?.SERVER_LISTEN_PORT);
+const runId = process.env.VONA_TEST_RUN_ID;
+if (runId) {
+  const match = /^(\d{14})-[a-f0-9]{8}$/.exec(runId);
+  const timestamp = match?.[1];
+  const date = timestamp
+    ? new Date(
+        `${timestamp.slice(0, 4)}-${timestamp.slice(4, 6)}-${timestamp.slice(6, 8)}T${timestamp.slice(8, 10)}:${timestamp.slice(10, 12)}:${timestamp.slice(12, 14)}Z`,
+      )
+    : undefined;
+  if (
+    !timestamp ||
+    !date ||
+    Number.isNaN(date.getTime()) ||
+    date.toISOString().slice(0, 19).replace(/[-:T]/g, '') !== timestamp
+  ) {
+    throw new Error('Invalid isolated test run ID: expected a UTC timestamp plus eight hex digits');
+  }
+}
+const e2ePort = Number(runId ? process.env.SERVER_LISTEN_PORT : vonaEnv?.SERVER_LISTEN_PORT);
 if (!Number.isInteger(e2ePort) || e2ePort <= 0 || e2ePort > 65535) {
   throw new Error('Missing or invalid SERVER_LISTEN_PORT for local E2E target');
 }