cabloy 5.1.146 → 5.1.148

package/CLAUDE.md

@@ -17,8 +17,11 @@ Always detect the active edition before making UI-sensitive assumptions, choosin
 - `package.json` is the primary shared workflow entrypoint.
 - `vona/` contains the backend framework, backend modules, and the Vona CLI.
 - `zova/` contains the frontend framework, frontend modules, and the Zova CLI.
-- `cabloy-docs/` contains the unified public documentation.
-- `.docs-internal/` contains internal engineering notes and ADRs.
+- `repo-docs/` contains the unified public documentation.
+- `repo-docs-internal/` contains internal engineering notes and ADRs.
+- `repo-specs/` contains product and business specifications, delivery plans, and suite-local ADRs.
+- `repo-e2e/` contains the end-to-end test project.
+- `repo-observability/` contains local observability infrastructure.
 - `.claude/` contains Claude commands, skills, and settings.
 
 ## Preferred workflow
@@ -35,8 +38,9 @@ Before inventing a custom implementation path:
 
 ## Documentation boundary
 
-- Put user-facing and agent-facing guidance in `cabloy-docs/`.
-- Put maintainer rationale, architecture notes, and ADRs in `.docs-internal/`.
+- Put user-facing and agent-facing guidance in `repo-docs/`.
+- Put maintainer rationale, architecture notes, and engineering ADRs in `repo-docs-internal/`.
+- Put product and business specifications, delivery plans, acceptance records, and suite-local ADRs in `repo-specs/`.
 - Do not mix internal rationale into public how-to pages unless a trimmed user-facing explanation is genuinely needed.
 
 ## AI development rules
@@ -56,19 +60,19 @@ Before inventing a custom implementation path:
 - Treat legacy docs as input material, not as unquestioned truth. When docs conflict with source code, prefer current source code.
 - For frontend work, assume Cabloy Basic and Cabloy Start share a frontend engineering layer but may diverge in UI layer, frontend flavors, suite/module availability, SSR site baselines, project assets, and generated outputs.
 - For Zova frontend analysis, do not default to generic Vue reinterpretation first. Read the code through Zova’s controller / bean / IoC architecture before mapping it to Vue concepts.
-- For Zova source-reading or Vue-vs-Zova explanation tasks, start from the frontend reading guides and source-reading map in `cabloy-docs/frontend/` before doing framework-neutral reinterpretation.
+- For Zova source-reading or Vue-vs-Zova explanation tasks, start from the frontend reading guides and source-reading map in `repo-docs/frontend/` before doing framework-neutral reinterpretation.
 - In Zova application modules under `zova/src/module/**`, `zova/src/module-vendor/**`, `zova/src/suite/**/modules/**`, and `zova/src/suite-vendor/**/modules/**`, use emitted runtime suffixes for relative imports and exports: `.js` for `.ts` targets and `.jsx` for `.tsx` targets, including type-only imports and module tests. Preserve the deliberate `.ts`/`.tsx` convention in `zova/packages-utils/**` and `zova/packages-zova/**`; do not generalize this rule to Vona, CLI/templates, dependencies, generated output, or build artifacts.
 - In Zova page routes, any route with dynamic `params` must define `route.name`; do not rely on unnamed path-keyed routes for typed `$params`. Static routes should omit `route.name` unless a documented named-route requirement exists; use `$router.getPagePath(...)` for canonical static URL generation rather than adding a name or alias for convenience. Ordinary business routes without `locale` params should omit app-config aliases unless a documented system, compatibility, or user-facing URL exception requires one. Choose `ssrProfile` from the page's rendering contract: Web remains `public` by default, while `session` is an explicit choice for cookie-backed state, protected admission, personalized first paint, or private SSR data; the absence of a locale parameter alone does not select a profile. `requiresAuth` is independent, so anonymous routes must explicitly use `requiresAuth: false`. Regenerate page metadata after route changes.
 - For frontend async state that affects rendering or interaction across consumers, prefer model-owned `$useStateData(...)` over controller-managed fetch/cache state.
 - 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. 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.
+- 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.
 - 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.
 - Reuse existing repo terminology: Cabloy, Vona, Zova, suite, module, bean, SSR, SPA, Web, Admin.
-- For backend base-class placement, use the A / B1 / B2 rule from `cabloy-docs/ai/class-placement-rule.md`.
+- For backend base-class placement, use the A / B1 / B2 rule from `repo-docs/ai/class-placement-rule.md`.
 - Pure helper bases belong in `src/lib`; subclass-only bases should be evaluated case by case and often belong in `src/lib`.
 - Runtime-anchor bases that still require container-managed or selector/class-token behavior but should not be global beans should prefer `src/service` with `@Service()`.
 - Service-scene runtime-anchor bases that should not register in `IBeanRecordGeneral` should prefer the `src/service/*_.ts` form.
@@ -77,7 +81,7 @@ 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.
-- Model cross-Model query-cache dependencies as one directed, acyclic `modelsClear` / `modelsClearedBy` graph, and verify source mutations refresh warmed dependent queries; read `.docs-internal/architecture/vona-cross-model-query-cache-dependencies.md` before designing a nontrivial graph.
+- Model cross-Model query-cache dependencies as one directed, acyclic `modelsClear` / `modelsClearedBy` graph, and verify source mutations refresh warmed dependent queries; read `repo-docs-internal/architecture/vona-cross-model-query-cache-dependencies.md` 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.
 - `@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.

package/README.md

@@ -178,7 +178,8 @@ Contribution guidelines:
 
 - prefer CLI-backed workflows with `npm run vona` and `npm run zova`
 - put user-facing and agent-facing guidance in [docs.cabloy.com](https://docs.cabloy.com)
-- put maintainer rationale, architecture notes, and ADRs in [.docs-internal/](https://github.com/cabloy/cabloy/tree/main/.docs-internal)
+- put maintainer rationale, architecture notes, and engineering ADRs in [repo-docs-internal/](https://github.com/cabloy/cabloy/tree/main/repo-docs-internal)
+- put product and business specifications, delivery plans, and suite-local ADRs in [repo-specs/](https://github.com/cabloy/cabloy/tree/main/repo-specs)
 - verify framework changes with the narrowest meaningful checks first, then shared root scripts when broader confidence is needed
 
 To report bugs or propose changes, use [GitHub Issues](https://github.com/cabloy/cabloy/issues) or open a pull request in [github.com/cabloy/cabloy](https://github.com/cabloy/cabloy).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cabloy",
-  "version": "5.1.146",
+  "version": "5.1.148",
   "gitHead": "2c5c19284bab738e492856189acb6fad74b8a7b7",
   "description": "A Node.js fullstack framework",
   "keywords": [
@@ -46,8 +46,8 @@
     "start": "cd vona && npm run start",
     "start:one": "cd vona && npm run start:one",
     "test": "cd vona && npm run test",
-    "test:e2e": "node e2e/scripts/runE2e.ts --clean",
-    "test:e2e:fast": "node e2e/scripts/runE2e.ts --fast",
+    "test:e2e": "node repo-e2e/scripts/runE2e.ts --clean",
+    "test:e2e:fast": "node repo-e2e/scripts/runE2e.ts --fast",
     "db:reset": "cd vona && npm run db:reset",
     "tsc": "npm run tsc:zova && pnpm --dir vona run tsc",
     "tsc:zova": "pnpm --dir zova run tsc",
@@ -57,10 +57,10 @@
     "format:fix": "oxfmt --write",
     "lint": "oxlint --disable-nested-config",
     "lint:fix": "oxlint --disable-nested-config --fix",
-    "docs:dev": "pnpm --dir cabloy-docs docs:dev",
-    "docs:build": "pnpm --dir cabloy-docs docs:build",
-    "docs:preview": "pnpm --dir cabloy-docs docs:preview",
-    "docs:fix": "textlint --fix ./cabloy-docs/**/*.md",
+    "docs:dev": "pnpm --dir repo-docs docs:dev",
+    "docs:build": "pnpm --dir repo-docs docs:build",
+    "docs:preview": "pnpm --dir repo-docs docs:preview",
+    "docs:fix": "textlint --fix ./repo-docs/**/*.md",
     "release-patch": "node scripts/release.ts patch",
     "release-minor": "node scripts/release.ts minor",
     "release-major": "node scripts/release.ts major",

package/{cabloy-docs → repo-docs}/.vitepress/config.mjs

@@ -626,7 +626,7 @@ export default defineConfig({
       provider: 'local',
     },
     editLink: {
-      pattern: 'https://github.com/cabloy/cabloy/edit/main/cabloy-docs/:path',
+      pattern: 'https://github.com/cabloy/cabloy/edit/main/repo-docs/:path',
     },
     footer: {
       message: 'Released under the MIT License.',

package/{cabloy-docs → repo-docs}/ai/docs-skills-rules-mapping.md

@@ -22,7 +22,7 @@ The goal is to give each layer a distinct job.
 
 Location:
 
-- `cabloy-docs/`
+- `repo-docs/`
 
 Use public docs for:
 
@@ -42,7 +42,7 @@ Public docs answer questions like:
 
 Location:
 
-- `.docs-internal/`
+- `repo-docs-internal/`
 
 Use internal docs for:
 
@@ -128,7 +128,7 @@ Use this quick rule:
 ### Example: “How should a backend base class be placed?”
 
 - public operational explanation → [Class Placement Rule](/ai/class-placement-rule)
-- maintainer rationale and invariants → `.docs-internal/architecture/class-placement-a-b1-b2.md`
+- maintainer rationale and invariants → `repo-docs-internal/architecture/class-placement-a-b1-b2.md`
 - default repo-wide behavior → `CLAUDE.md`
 - procedural decision workflow → `cabloy-workflow` skill
 
@@ -153,7 +153,7 @@ Use this quick rule:
 ### Example: “How should AI remove an existing module cleanly?”
 
 - public operational explanation → [Playbook: Module Removal](/ai/playbook-module-removal)
-- maintainer rationale and pitfalls → `.docs-internal/architecture/module-removal-workflow.md`
+- maintainer rationale and pitfalls → `repo-docs-internal/architecture/module-removal-workflow.md`
 - avoid putting the full workflow in `CLAUDE.md` because the task needs branching, cleanup order, generated-runtime recovery, and verification
 - procedural decision workflow → `cabloy-module-removal` skill
 

package/{cabloy-docs → repo-docs}/ai/future-skill-roadmap.md

@@ -42,7 +42,7 @@ Primary dependencies:
 
 - Vona `create:*`
 - Vona `tools:*`
-- backend docs in `cabloy-docs/backend/`
+- backend docs in `repo-docs/backend/`
 
 ### 2. Frontend scaffold skill
 
@@ -56,7 +56,7 @@ Primary dependencies:
 
 - Zova `create:*`
 - Zova `refactor:*`
-- frontend docs in `cabloy-docs/frontend/`
+- frontend docs in `repo-docs/frontend/`
 
 ### 3. Fullstack contract loop skill
 
@@ -85,7 +85,7 @@ Primary dependencies:
 
 - Vona entity / migration / DTO workflow knowledge
 - Zova metadata/build flows when renderer follow-up is involved
-- the backend resource field workflow note in `.docs-internal/`
+- the backend resource field workflow note in `repo-docs-internal/`
 
 ### 5. Metadata refresh skill
 
@@ -146,9 +146,9 @@ The purpose of the roadmap is not to create many skills.
 
 The purpose is to create a small number of high-leverage skills that directly reuse the knowledge system now being built in:
 
-- `cabloy-docs/`
+- `repo-docs/`
 - `CLAUDE.md`
-- `.docs-internal/`
+- `repo-docs-internal/`
 - `.claude/skills/`
 - the Vona and Zova CLIs
 

package/{cabloy-docs → repo-docs}/ai/introduction.md

@@ -29,20 +29,20 @@ For contributor and automation workflows in this repository, prefer this order:
 
 1. inspect the active edition and repo markers before making UI-sensitive or workflow-sensitive assumptions
 2. inspect root scripts, Vona CLI, and Zova CLI before inventing manual scaffolding or custom workflow steps
-3. use public docs for durable user-facing guidance and `.docs-internal/` for maintainer rationale
+3. use public docs for durable user-facing guidance and `repo-docs-internal/` for maintainer rationale
 4. encode repeatable behavior in Claude rules, commands, or skills instead of relying on unstated habits
 
 ## The knowledge layers
 
 ### Public docs
 
-Use `cabloy-docs/` for user-facing and agent-facing guidance that should remain durable and source-aligned.
+Use `repo-docs/` for user-facing and agent-facing guidance that should remain durable and source-aligned.
 
 For normal project usage, prefer the user-facing entry docs such as [Fullstack Quickstart](/fullstack/quickstart). This AI section focuses on repository workflows and AI vibe coding.
 
 ### Internal engineering docs
 
-Use `.docs-internal/` for architecture notes, ADRs, and maintainership rationale that should not be mixed into public how-to documentation.
+Use `repo-docs-internal/` for architecture notes, ADRs, and maintainership rationale that should not be mixed into public how-to documentation.
 
 ### Claude rules and commands
 

package/{cabloy-docs → repo-docs}/ai/playbook-module-removal.md

@@ -38,7 +38,7 @@ Typical locations include:
 - generated registries and lockfiles
 - tests that still target the module
 
-If the user asked for a public scrub, also inspect `cabloy-docs/`. Otherwise, treat docs cleanup as a separate scope decision.
+If the user asked for a public scrub, also inspect `repo-docs/`. Otherwise, treat docs cleanup as a separate scope decision.
 
 ## Step 3: Remove source and direct references first
 
@@ -144,7 +144,7 @@ Make this an explicit scope decision:
 - code/runtime removal only
 - code/runtime removal plus docs/examples scrub
 
-If docs cleanup is in scope, update `cabloy-docs/` as a separate pass after runtime cleanup is stable.
+If docs cleanup is in scope, update `repo-docs/` as a separate pass after runtime cleanup is stable.
 
 ## AI rule of thumb
 

package/{cabloy-docs → repo-docs}/ai/repo-guidance.md

@@ -8,7 +8,7 @@ Check the root repository signals first:
 
 - `package.json`
 - edition marker files such as `__CABLOY_BASIC__` or `__CABLOY_START__`
-- `.docs-internal/README.md`
+- `repo-docs-internal/README.md`
 - root `.claude/` assets
 
 These files tell the agent which repo it is in, which scripts are canonical, and where public versus internal documentation belongs.
@@ -29,8 +29,8 @@ This is more reliable than copying old file structures from examples without und
 
 ## 3. Use docs and internal notes for different purposes
 
-- use `cabloy-docs/` to explain how people and agents should work
-- use `.docs-internal/` to explain why maintainers designed the repo a certain way
+- use `repo-docs/` to explain how people and agents should work
+- use `repo-docs-internal/` to explain why maintainers designed the repo a certain way
 
 ## 4. Treat edition detection as mandatory for UI-sensitive work
 

package/{cabloy-docs → repo-docs}/ai/rules-and-config.md

@@ -26,4 +26,4 @@ Use Claude settings for permissions and execution environment, not as the primar
 
 ## Documentation boundary
 
-If a rule is important for people and agents to understand, it probably belongs in public docs too. If it explains internal rationale rather than user-facing workflow, it belongs in `.docs-internal/`.
+If a rule is important for people and agents to understand, it probably belongs in public docs too. If it explains internal rationale rather than user-facing workflow, it belongs in `repo-docs-internal/`.

package/{cabloy-docs → repo-docs}/ai/virtual-decorator-guidance.md

@@ -203,4 +203,4 @@ Read these pages together:
 
 For maintainer-level rationale, also read:
 
-- `.docs-internal/architecture/virtual-decorator-runtime-semantics.md`
+- `repo-docs-internal/architecture/virtual-decorator-runtime-semantics.md`

package/{cabloy-docs → repo-docs}/backend/introduction.md

@@ -19,7 +19,7 @@ For contributor and automation workflows in this repository, prefer this order:
 1. inspect the root `package.json` and `npm run vona` entrypoint
 2. inspect Vona CLI command families such as `create:*`, `init:*`, `tools:*`, and `bin:*`
 3. inspect the current module or suite layout before creating new files manually
-4. use public docs for user-facing guidance and `.docs-internal/` for maintainer rationale
+4. use public docs for user-facing guidance and `repo-docs-internal/` for maintainer rationale
 
 ## Backend reading paths
 

package/{cabloy-docs → repo-docs}/backend/metrics-guide.md

@@ -66,10 +66,10 @@ The Basic Admin **Metrics** page is available only to `systemAdmin`. It shows a
 
 ## Local example
 
-A loopback-only local stack is available under the repository's `observability/README.md`:
+A loopback-only local stack is available under the repository's `repo-observability/README.md`:
 
 ```bash
-docker compose -f observability/docker-compose.metrics.yml up
+docker compose -f repo-observability/docker-compose.metrics.yml up
 ```
 
 Use it for local validation only. Production networking, TLS/mTLS, secret injection, retention, dashboards, and alert routing are operator-owned.

package/{cabloy-docs → repo-docs}/frontend/router-tabs-introduction.md

@@ -110,7 +110,7 @@ Recommended order:
 
 1. [Router Tabs Mechanism](/frontend/router-tabs-mechanism)
 2. [Router Tabs Admin and Web Comparison](/frontend/router-tabs-admin-web-comparison)
-3. `.docs-internal/architecture/router-tabs-design-boundaries.md`
+3. `repo-docs-internal/architecture/router-tabs-design-boundaries.md`
 
 ## Scope boundary
 
@@ -118,7 +118,7 @@ The public router-tabs docs explain the shared frontend mechanism and how to use
 
 For internal design boundaries, maintenance invariants, and refactor safety rules, see:
 
-- `.docs-internal/architecture/router-tabs-design-boundaries.md`
+- `repo-docs-internal/architecture/router-tabs-design-boundaries.md`
 
 ## See also
 

package/{cabloy-docs → repo-docs}/frontend/scripts.md

@@ -61,7 +61,7 @@ npm run build:zova:admin
 # Both default Basic sites, then a managed local run
 npm run build:zova
 npm run deps:vona
-npm run test:e2e cabloy-basic account
+npm run test:e2e cabloy-basic home-user-account
 ```
 
 The managed clean command resets Vona-managed test data and the local Redis namespace, starts one development Vona worker, and runs the selected specs. Browser commands consume already-built artifacts; they do not rebuild them.
@@ -73,10 +73,10 @@ npm run test:e2e                 clean local run with database reset
 npm run test:e2e:fast            fast run without automatic reset
 ```
 
-Place flat spec basenames directly after the npm script name. Use npm's `--` delimiter before Playwright options. With no names, every spec in `e2e/specs` runs. Native `--grep` and `--grep-invert` remain available, and repeatable `--tag` values require all listed tags:
+Place flat spec basenames directly after the npm script name. Use npm's `--` delimiter before Playwright options. With no names, every spec in `repo-e2e/specs` runs. Native `--grep` and `--grep-invert` remain available, and repeatable `--tag` values require all listed tags:
 
 ```bash
-npm run test:e2e cabloy-basic account -- --grep @flow
+npm run test:e2e cabloy-basic home-user-account -- --grep @flow
 npm run test:e2e:fast a-commerce -- --tag @web --tag @smoke
 ```
 
@@ -98,31 +98,31 @@ Cabloy Start does not expose the Basic Commerce wrapper family.
 
 ## Start SSR browser acceptance
 
-The Start Web and Admin browser baseline also exercises Vona SSR dispatch at port `7102`. Prepare current SSR and REST artifacts, then use the managed local command:
+The Start Web and Admin browser baseline also exercises Vona SSR dispatch at the effective local server port. Prepare current SSR and REST artifacts, then use the managed local command:
 
 ```bash
 npm run build:zova
 npm run deps:vona
-npm run test:e2e:start:clean
+npm run test:e2e
 ```
 
-The Start command family is:
+Start uses the same unified E2E command pair as Basic:
 
 ```text
-test:e2e:start          complete suite
-test:e2e:start:web      all @web surface scenarios
-test:e2e:start:admin    all @admin surface scenarios
-test:e2e:start:clean    managed clean local suite run
+npm run test:e2e       managed clean local suite run
+npm run test:e2e:fast  fast rerun without an automatic reset
 ```
 
-Start scenarios currently use `@web`, `@admin`, and `@smoke`. Select a scenario or surface with Playwright arguments:
+Select flat spec basenames and filter scenarios or surfaces with runner tags and native Playwright arguments. Current Start scenarios use tags including `@web`, `@admin`, `@smoke`, `@layout`, `@cabloy-admin`, `@account`, `@ssr`, and `@flow`:
 
 ```bash
-npm run test:e2e:start:clean -- --grep @web
-npm run test:e2e:start -- --grep ATP-START-FLOW-01
+npm run test:e2e cabloy-start
+npm run test:e2e:fast cabloy-start -- --tag @web
+npm run test:e2e:fast cabloy-admin -- --tag @admin --tag @cabloy-admin
+npm run test:e2e:fast cabloy-start -- --grep ATP-START-FLOW-01
 ```
 
-For a separately managed Start target, set `START_E2E_BASE_URL`. The target owner is responsible for data, cache, and artifact freshness.
+For a separately managed Start target, set `E2E_BASE_URL` and use `test:e2e:fast`. The target owner is responsible for data, cache, artifact freshness, and process lifecycle.
 
 ## Zova script model
 

package/{cabloy-docs → repo-docs}/fullstack/parallel-worktree-environment.md

@@ -75,10 +75,10 @@ For privacy, the skill writes only to absent or empty permitted broad local file
 
 Use commands from the active repository root.
 
-| Edition      | Marker             | Frontend command                                   | Managed clean E2E              |
-| ------------ | ------------------ | -------------------------------------------------- | ------------------------------ |
-| Cabloy Basic | `__CABLOY_BASIC__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e`             |
-| Cabloy Start | `__CABLOY_START__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e:start:clean` |
+| Edition      | Marker             | Frontend command                                   | Managed clean E2E  |
+| ------------ | ------------------ | -------------------------------------------------- | ------------------ |
+| Cabloy Basic | `__CABLOY_BASIC__` | `npm run dev:zova:admin` or `npm run dev:zova:web` | `npm run test:e2e` |
+| 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 clean E2E workflows read Vona's effective local `SERVER_LISTEN_PORT`, then reset, start, and target that local runtime.
 

package/{cabloy-docs → repo-docs}/fullstack/quickstart.md

@@ -112,36 +112,36 @@ npm run upgrade
 In Cabloy Basic, upgrade synchronizes the framework-owned SSR browser E2E baseline, the two root E2E scripts, and the `@playwright/test` development dependency. The framework owns these paths:
 
 ```text
-e2e/config/
-e2e/scripts/
-e2e/specs/cabloy-basic.spec.ts
-e2e/specs/account.spec.ts
-e2e/specs/a-commerce.spec.ts
+repo-e2e/config/
+repo-e2e/scripts/
+repo-e2e/specs/cabloy-basic.spec.ts
+repo-e2e/specs/home-user-account.spec.ts
+repo-e2e/specs/a-commerce.spec.ts
 ```
 
-Keep additional project-owned browser specs under other filenames in `e2e/specs`. The current baseline is a fresh-project contract; unsupported legacy layouts are not repaired by the upgrader.
+Keep additional project-owned browser specs under other filenames in `repo-e2e/specs`. The current baseline is a fresh-project contract; unsupported legacy layouts are not repaired by the upgrader.
 
 ### Cabloy Start repository baseline
 
 Cabloy Start is checked out from the licensed private repository rather than created through `npm create cabloy`. Its E2E baseline is maintained in that repository:
 
 ```text
-e2e/config/
-e2e/scripts/
-e2e/specs/cabloy-start/
+repo-e2e/config/
+repo-e2e/scripts/
+repo-e2e/specs/
 ```
 
-The public Cabloy upgrade flow does not synchronize or repair those Start E2E files, the `test:e2e:start*` scripts, or `@playwright/test`. Keep project-owned browser scenarios outside the baseline paths, for example under `e2e/specs/my-project/`.
+The public Cabloy upgrade flow does not synchronize or repair those private Start E2E files, its root E2E scripts, or `@playwright/test`. Keep project-owned browser scenarios in the flat `repo-e2e/specs/` directory under distinct filenames, for example `repo-e2e/specs/my-project.spec.ts`.
 
 Prepare and run the managed Start baseline locally with:
 
 ```bash
 npm run build:zova
 npm run deps:vona
-npm run test:e2e:start:clean
+npm run test:e2e
 ```
 
-The managed command requires port `7102` to be available and owns the local reset and Vona worker lifecycle. For a separately managed target, set `START_E2E_BASE_URL` and use `test:e2e:start`, `test:e2e:start:web`, or `test:e2e:start:admin`; those commands do not reset, build, start, or stop the target. Install Chromium once when needed with `npx playwright install chromium`. See [Repo Scripts](/reference/repo-scripts#ssr-browser-checks) for the complete command variants.
+The managed command checks the effective local server port and owns the local reset and Vona worker lifecycle. For a separately managed target, set `E2E_BASE_URL` and use `npm run test:e2e:fast`; this mode does not reset, build, start, or stop the target. Select surfaces with `--tag @web` or `--tag @admin`, and exact scenarios with native `--grep` arguments. Install Chromium once when needed with `npx playwright install chromium`. See [Repo Scripts](/reference/repo-scripts#ssr-browser-checks) for the complete command variants.
 
 ## 7. Next steps for framework-aware development
 

package/{cabloy-docs → repo-docs}/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "cabloy-docs",
+  "name": "repo-docs",
   "private": true,
-  "description": "Unified Cabloy monorepo docs",
+  "description": "Cabloy repository public documentation",
   "license": "MIT",
   "author": "zhennann",
   "type": "module",

package/{cabloy-docs → repo-docs}/reference/package-map.md

@@ -6,9 +6,9 @@ This monorepo is organized around a small set of stable top-level areas.
 
 - `package.json` — shared scripts and release entrypoints
 - `lerna.json` — package topology
-- `.docs-internal/` — internal engineering docs
+- `repo-docs-internal/` — internal engineering docs
 - `.claude/` — Claude commands, skills, and local settings
-- `cabloy-docs/` — unified public docs
+- `repo-docs/` — unified public docs
 
 ## Backend side
 

package/{cabloy-docs → repo-docs}/reference/repo-scripts.md

@@ -63,10 +63,8 @@ Cabloy Start exposes the equivalent Start repository surface:
 - `npm run start:one`
 - `npm run test`
 - `npm run db:reset`
-- `npm run test:e2e:start`
-- `npm run test:e2e:start:web`
-- `npm run test:e2e:start:admin`
-- `npm run test:e2e:start:clean`
+- `npm run test:e2e`
+- `npm run test:e2e:fast`
 - `npm run tsc`
 
 Cabloy Start does not expose Basic Commerce or root documentation wrappers.
@@ -80,26 +78,26 @@ Run `npm run upgrade:dry-run` before `npm run upgrade` to inspect framework file
 Basic upgrade owns these browser baseline paths:
 
 ```text
-e2e/config/
-e2e/scripts/
-e2e/specs/cabloy-basic.spec.ts
-e2e/specs/account.spec.ts
-e2e/specs/a-commerce.spec.ts
+repo-e2e/config/
+repo-e2e/scripts/
+repo-e2e/specs/cabloy-basic.spec.ts
+repo-e2e/specs/home-user-account.spec.ts
+repo-e2e/specs/a-commerce.spec.ts
 ```
 
-It also reconciles the two framework E2E scripts and the `@playwright/test` development dependency. Keep additional project browser specs under other filenames in `e2e/specs`; the upgrader updates only the listed framework files. The current fresh baseline is required and is not repaired for unsupported legacy project layouts.
+It also reconciles the two framework E2E scripts and the `@playwright/test` development dependency. Keep additional project browser specs under other filenames in `repo-e2e/specs`; the upgrader updates only the listed framework files. The current fresh baseline is required and is not repaired for unsupported legacy project layouts.
 
 ### Cabloy Start private repository
 
 The Start E2E baseline is maintained in the private repository:
 
 ```text
-e2e/config/
-e2e/scripts/
-e2e/specs/cabloy-start/
+repo-e2e/config/
+repo-e2e/scripts/
+repo-e2e/specs/
 ```
 
-The public-package upgrade flow does not source or reconcile the Start baseline, its `test:e2e:start*` scripts, or `@playwright/test`. Keep project browser tests outside the baseline paths, for example under `e2e/specs/my-project/`.
+The public-package upgrade flow does not source or reconcile the private Start baseline, its root E2E scripts, or `@playwright/test`. Keep project browser tests in the flat `repo-e2e/specs/` directory under distinct filenames, for example `repo-e2e/specs/my-project.spec.ts`.
 
 ## SSR browser checks
 
@@ -108,12 +106,12 @@ The unified runner has two modes:
 - `npm run test:e2e`: clean local run; checks the managed port, resets the database, starts one development Vona worker, and runs Playwright.
 - `npm run test:e2e:fast`: skips the reset for quick reruns and may target either the local managed server or an externally managed `E2E_BASE_URL`.
 
-Place spec basenames directly after the npm script name; use npm's `--` delimiter only before Playwright options. Multiple spec names are allowed. With no names, every spec in `e2e/specs` is discovered:
+Place spec basenames directly after the npm script name; use npm's `--` delimiter only before Playwright options. Multiple spec names are allowed. With no names, every spec in `repo-e2e/specs` is discovered:
 
 ```bash
-npm run test:e2e cabloy-basic account
+npm run test:e2e cabloy-basic home-user-account
 npm run test:e2e a-commerce
-npm run test:e2e:fast account
+npm run test:e2e:fast home-user-account
 npm run test:e2e:fast a-commerce -- --grep ATP-SSR
 npm run test:e2e:fast a-commerce -- --grep-invert @admin
 ```
@@ -122,7 +120,7 @@ Tags remain independent from filenames. Repeat `--tag` to require all tags, whil
 
 ```bash
 npm run test:e2e:fast a-commerce -- --tag @web --tag @smoke
-npm run test:e2e:fast account -- --grep @flow --tag @web
+npm run test:e2e:fast home-user-account -- --grep @flow --tag @web
 ```
 
 The existing tags include `@web`, `@admin`, `@smoke`, `@flow`, `@ssr`, `@theme`, and the business tags used by Commerce such as `@cart`, `@payment`, `@shipment`, and `@refund`. No suite tag is required. Clean runs are local-only and reject `E2E_BASE_URL`; fast runs against an external target do not reset, start, stop, or rebuild that target.
@@ -134,7 +132,7 @@ The Basic baseline exercises Web at `/` and Admin at `/admin` through Vona's SSR
 ```bash
 npm run build:zova
 npm run deps:vona
-npm run test:e2e cabloy-basic account
+npm run test:e2e cabloy-basic home-user-account
 ```
 
 Commerce browser acceptance exercises Customer Web at `/commerce` and Operator Admin routing at `/commerce-admin`. Prepare its paired artifacts explicitly:
@@ -158,24 +156,24 @@ The Start suite exercises Web at `/` and Admin at `/admin` through Vona's SSR di
 ```bash
 npm run build:zova
 npm run deps:vona
-npm run test:e2e:start:clean
+npm run test:e2e
 ```
 
 ```bash
 # Exact acceptance scenario
-npm run test:e2e:start -- --grep ATP-START-FLOW-01
+npm run test:e2e:fast cabloy-start -- --grep ATP-START-FLOW-01
 
 # Category or surface selection
-npm run test:e2e:start:clean -- --grep @smoke
-npm run test:e2e:start:clean -- --grep @admin
+npm run test:e2e:fast cabloy-start -- --tag @smoke
+npm run test:e2e:fast cabloy-admin -- --tag @admin --tag @cabloy-admin
 ```
 
-For an externally managed Start target, set `START_E2E_BASE_URL` and use matching aggregate, surface, or forwarded-tag commands. The target owner is responsible for data, cache, and artifact freshness:
+For an externally managed Start target, set `E2E_BASE_URL` and use `npm run test:e2e:fast`. The target owner is responsible for data, cache, artifact freshness, and process lifecycle:
 
 ```bash
-START_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:start
-START_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:start:admin
-START_E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:start -- --grep @web
+E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:fast
+E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:fast cabloy-admin -- --tag @admin
+E2E_BASE_URL=http://127.0.0.1:7102 npm run test:e2e:fast cabloy-start -- --tag @web
 ```
 
 Browser commands consume existing SSR and REST artifacts; they never rebuild them. Install Chromium once when needed with `npx playwright install chromium`.

package/{e2e → repo-e2e}/config/playwright.config.ts

@@ -6,7 +6,7 @@ const externalBaseURL = process.env.E2E_BASE_URL;
 const baseURL = externalBaseURL || E2E_LOCAL_BASE_URL;
 
 export default defineConfig({
-  testDir: `${E2E_ROOT_DIR}/e2e/specs`,
+  testDir: `${E2E_ROOT_DIR}/repo-e2e/specs`,
   fullyParallel: false,
   workers: 1,
   forbidOnly: !!process.env.CI,
@@ -19,7 +19,7 @@ export default defineConfig({
   webServer: externalBaseURL
     ? undefined
     : {
-        command: 'node e2e/scripts/startE2eVona.ts',
+        command: 'node repo-e2e/scripts/startE2eVona.ts',
         cwd: E2E_ROOT_DIR,
         url: `${baseURL}/`,
         timeout: 180_000,

package/{e2e → repo-e2e}/scripts/e2e.ts

@@ -16,5 +16,5 @@ if (!Number.isInteger(e2ePort) || e2ePort <= 0 || e2ePort > 65535) {
 
 export const E2E_PORT = e2ePort;
 export const E2E_LOCAL_BASE_URL = `http://127.0.0.1:${E2E_PORT}`;
-export const E2E_CONFIG_FILE = resolve(E2E_ROOT_DIR, 'e2e', 'config', 'playwright.config.ts');
-export const E2E_SPECS_DIR = resolve(E2E_ROOT_DIR, 'e2e', 'specs');
+export const E2E_CONFIG_FILE = resolve(E2E_ROOT_DIR, 'repo-e2e', 'config', 'playwright.config.ts');
+export const E2E_SPECS_DIR = resolve(E2E_ROOT_DIR, 'repo-e2e', 'specs');