cabloy 5.1.145 → 5.1.147

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.145",
+  "version": "5.1.147",
   "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
 ```
 

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

@@ -112,26 +112,26 @@ 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/cabloy-start/
 ```
 
-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 Start E2E files, the `test:e2e:start*` scripts, or `@playwright/test`. Keep project-owned browser scenarios outside the baseline paths, for example under `repo-e2e/specs/my-project/`.
 
 Prepare and run the managed Start baseline locally with:
 

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

@@ -80,26 +80,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/cabloy-start/
 ```
 
-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 Start baseline, its `test:e2e:start*` scripts, or `@playwright/test`. Keep project browser tests outside the baseline paths, for example under `repo-e2e/specs/my-project/`.
 
 ## SSR browser checks
 
@@ -108,12 +108,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 +122,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 +134,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:

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');

package/{observability → repo-observability}/README.md

@@ -3,7 +3,7 @@
 Start the local OpenTelemetry Collector, Prometheus, and Grafana stack:
 
 ```bash
-docker compose -f observability/docker-compose.metrics.yml up
+docker compose -f repo-observability/docker-compose.metrics.yml up
 ```
 
 Enable the application metric exporter only for local development:

package/scripts/init.ts

@@ -18,7 +18,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = resolve(__dirname, '..');
 const VONA_DIR = resolve(ROOT_DIR, 'vona');
 const ZOVA_DIR = resolve(ROOT_DIR, 'zova');
-const CABLOY_DOCS_DIR = resolve(ROOT_DIR, 'cabloy-docs');
+const REPO_DOCS_DIR = resolve(ROOT_DIR, 'repo-docs');
 const PNPM_VERSION = '11.5.2';
 const VERSION_MARKER_FILE = '.cabloy-version';
 
@@ -284,14 +284,14 @@ function cleanupWorkspaceYaml(): void {
   }
 }
 
-// --- Step G: init:cabloy-docs ---
+// --- Step G: init:repo-docs ---
 
-function initCabloyDocs(): void {
-  const pkgPath = resolve(CABLOY_DOCS_DIR, 'package.json');
+function initRepoDocs(): void {
+  const pkgPath = resolve(REPO_DOCS_DIR, 'package.json');
   if (!existsSync(pkgPath)) return;
   // eslint-disable-next-line
-  console.log('[init] Initializing cabloy-docs...');
-  pnpmInstall(CABLOY_DOCS_DIR);
+  console.log('[init] Initializing repo-docs...');
+  pnpmInstall(REPO_DOCS_DIR);
 }
 
 // --- Main ---
@@ -305,7 +305,7 @@ cleanupWorkspaceYaml();
 initZova();
 buildSsrZovaAll();
 initVona();
-initCabloyDocs();
+initRepoDocs();
 writeVersionMarker();
 // eslint-disable-next-line
 console.log('[init] Done!');

package/scripts/upgrade.ts

@@ -28,8 +28,8 @@ const OVERWRITE_DIRS: string[] = [
   // root
   'scripts',
   '.husky',
-  'cabloy-docs',
-  'observability',
+  'repo-docs',
+  'repo-observability',
   // vona
   'vona/packages-vona',
   'vona/packages-cli',
@@ -59,28 +59,16 @@ const OVERWRITE_DIRS_CABLOY_BASIC: string[] = [
   'zova/src/suite/a-devui',
 ];
 
-const FRAMEWORK_E2E_DIRS_CABLOY_BASIC: string[] = ['e2e/config', 'e2e/scripts'];
+const FRAMEWORK_E2E_DIRS_CABLOY_BASIC: string[] = ['repo-e2e/config', 'repo-e2e/scripts'];
 
 const FRAMEWORK_E2E_FILES_CABLOY_BASIC: string[] = [
-  'e2e/specs/cabloy-basic.spec.ts',
-  'e2e/specs/account.spec.ts',
-  'e2e/specs/a-commerce.spec.ts',
+  'repo-e2e/specs/cabloy-basic.spec.ts',
+  'repo-e2e/specs/home-user-account.spec.ts',
+  'repo-e2e/specs/a-commerce.spec.ts',
 ];
 
 const FRAMEWORK_E2E_SCRIPT_NAMES_CABLOY_BASIC: string[] = ['test:e2e', 'test:e2e:fast'];
 
-const FRAMEWORK_E2E_LEGACY_SCRIPT_NAMES_CABLOY_BASIC: string[] = [
-  'test:e2e:basic',
-  'test:e2e:basic:web',
-  'test:e2e:basic:admin',
-  'test:e2e:basic:clean',
-  'test:e2e:commerce',
-  'test:e2e:commerce:web',
-  'test:e2e:commerce:admin',
-  'test:e2e:commerce:clean',
-  'test:e2e:basic:flow',
-];
-
 const FRAMEWORK_E2E_DEV_DEPENDENCY_CABLOY_BASIC = '@playwright/test';
 
 const MERGE_DIRS: string[] = [
@@ -261,12 +249,12 @@ function mergeFrameworkE2eAssets(dryRun?: boolean): void {
   }
 
   const legacyFrameworkFiles: string[] = [
-    'e2e/config/playwright.basic.config.ts',
-    'e2e/config/playwright.commerce.config.ts',
-    'e2e/config/playwright.shared.config.ts',
-    'e2e/specs/cabloy-basic/basic.spec.ts',
-    'e2e/specs/cabloy-basic/account.spec.ts',
-    'e2e/specs/a-commerce/commerce.spec.ts',
+    'repo-e2e/config/playwright.basic.config.ts',
+    'repo-e2e/config/playwright.commerce.config.ts',
+    'repo-e2e/config/playwright.shared.config.ts',
+    'repo-e2e/specs/cabloy-basic/basic.spec.ts',
+    'repo-e2e/specs/cabloy-basic/account.spec.ts',
+    'repo-e2e/specs/a-commerce/commerce.spec.ts',
   ];
   for (const file of legacyFrameworkFiles) {
     const dest = resolve(ROOT_DIR, file);
@@ -337,16 +325,6 @@ function reconcileFrameworkE2ePackageJson(dryRun?: boolean): void {
     }
   }
 
-  for (const name of FRAMEWORK_E2E_LEGACY_SCRIPT_NAMES_CABLOY_BASIC) {
-    if (!projectPackage.scripts?.[name]) continue;
-    changed = true;
-    if (dryRun) {
-      log(`  [dry-run] Remove legacy framework E2E script package.json scripts.${name}`);
-    } else {
-      delete projectPackage.scripts?.[name];
-    }
-  }
-
   if (!changed) {
     if (dryRun) log('  [dry-run] Framework E2E package entries already match');
     return;