@openora/create 0.4.1-canary.35 → 0.4.1-canary.351

package/template/__dot__rulesync/rules/conventions.md

@@ -3,132 +3,112 @@ root: false
 targets:
   - '*'
 globs:
-  - '**/*'
-description: Engineering code conventions (TS, frontend, testing, git) - apply all of these to every change.
+  - 'apps/**'
+  - 'packages/**'
+  - 'tools/**'
+  - '*.config.*'
+  - 'package.json'
+description: Engineering code conventions (TS, DB, frontend, testing, git) - the always-on core, with a routing table to full detail in docs/standards/.
 ---
 
 # Engineering conventions
 
-Portable code standard for this repo.
-The enforced import graph lives in `oss-boundaries`; SQL rules in `db-conventions`; Playwright rules in `e2e-conventions`.
+The always-on core of the code standard: what you must obey while typing. Detail, examples, and
+rationale live in `docs/standards/` - read the one file that matches the change instead of
+carrying all of it. The enforced import graph lives in `oss-boundaries`; Playwright rules in
+`e2e-conventions`; the always-on UI and SQL cores in `frontend-conventions` and `db-conventions`.
+
+| Change you are making                 | Read first                           |
+| ------------------------------------- | ------------------------------------ |
+| schema, type, enum-like value set     | `docs/standards/types.md`            |
+| function, service method, constructor | `docs/standards/functions.md`        |
+| new package, overlay, module layout   | `docs/standards/module-structure.md` |
+| a comment or JSDoc                    | `docs/standards/comments.md`         |
+| error class, catch, money path        | `docs/standards/errors.md`           |
+| a test                                | `docs/standards/testing.md`          |
+| commit, PR                            | `docs/standards/git-delivery.md`     |
+| a failing gate, a new lint rule       | `docs/standards/enforcement.md`      |
+| React/UI component, page, styling     | `docs/standards/frontend.md`         |
+| SQL, Drizzle, migration, seed         | `docs/standards/database.md`         |
+
+`docs/standards/frontend.md` doesn't apply to a headless/api-only repo - delete it (and its row
+above) if this repo has no UI apps.
 
 ## Philosophy
 
-- Functional and declarative: pure functions, immutable data, composition. No stateful classes, no imperative accumulation loops.
-- Explicit over magic: no decorators, no auto-discovery, no reflection. Every wiring point is a greppable typed call (`ctx.provide(TOKEN, factory)`).
+- Functional and declarative: pure functions, immutable data, composition. No stateful classes, no
+  imperative accumulation loops.
+- Explicit over magic: no decorators, no auto-discovery, no reflection. Every wiring point is a
+  greppable typed call (`ctx.provide(TOKEN, factory)`).
 - Self-documenting: clear names beat comments (`percentChange`, not `d` + a comment).
-- YAGNI then DRY: don't build for imagined futures; abstract on the third occurrence, not the first.
+- YAGNI then DRY: don't build for imagined futures; abstract on the third occurrence, not the
+  first.
 - Boring and consistent: match the surrounding code's idiom, naming, and density.
 
-## Naming
-
-- Files `kebab-case.ts`, one concept per file, filename names the concept (`wallet.service.ts`; never `helpers.ts`, `utils2.ts`).
-- Types `PascalCase`; values/functions `camelCase`; true global constants `SCREAMING_SNAKE_CASE`.
-- Zod schemas `<Name>Schema`; the inferred type is the bare `<Name>`.
-- Booleans read as predicates (`isActive`, `canEdit`); IO functions as verbs (`fetchInvoice`); names carry units/intent (`delayMs`, `maxRetries`).
-- Money is a decimal string plus a `currency` field alongside it - `amount`, `balance`, `threshold`, never `amountCents`.
-
-## Types
-
-- One source of truth per shape - infer, never hand-write a type that already exists: `z.infer<typeof UserSchema>`, `typeof users.$inferSelect`, `Omit<User, 'id'>`.
-- Schema-first at every boundary (HTTP, config, env, messages, events): validate once at the edge, trust the type after. oRPC + Zod does this for routes; do the same elsewhere.
-- Never re-infer a schema you imported - the owning contract exports the type once; import it.
-- No `any` outside tests - `unknown` + narrowing.
-- No `as` casts to silence the compiler - fix the root cause (`as const` is fine).
-- Never `!` non-null assertions - narrow explicitly, or restructure so the value is provably present (carry it on the object instead of re-looking it up).
-- Under `noUncheckedIndexedAccess`: `.at()`, destructure-with-default (`const [first = ''] = parts`), or an explicit guard - never `arr[i]!`.
-- `type` over `interface` (lint-enforced).
-- Type entity ids through their owning type (`playerId: Player['id']`), never a bare `string`.
-- Derive related schemas with `.pick()/.omit()/.partial()/.extend()/.merge()` - never re-type fields.
-- Enum-like value sets are a values + schema + type triple declared once on the contract surface: `X_STATUSES = [...] as const` -> `XStatusSchema = z.enum(X_STATUSES)` -> inferred `XStatus`. Never a TS `enum`, never a second hand-typed copy - import the one from `@openora/*`.
-- Make illegal states unrepresentable - discriminated unions (`{ status: 'ok'; data } | { status: 'error'; error }`) over optional-flag soup.
-
-## Functions and modules
-
-- Pure functions with dependencies passed in as arguments; side effects only at the edges (services, adapters, plugins, handlers) - never in helpers.
-- Immutability: derive new objects (`{ ...user, roles: [...] }`), don't mutate.
-- Construct objects by spread + override, never field-by-field hand-copy. Keep fields explicit only for order-sensitive serialization, when the target must not receive some source fields, or when null-vs-undefined matters at a boundary.
-- A `class` is only a thin dependency-holding shell at a composition root; methods delegate to pure functions. No inheritance for reuse, no decorators - compose.
-- Short, single-purpose functions - if you'd write `// step 2` inside one, extract it.
-- Guard clauses first, main path last.
-- More than 3 parameters -> a single named-object param.
-- Don't annotate a return type TypeScript can infer. Annotate only when: inference can't (recursion), you deliberately widen/narrow, or it's the exported public API of a shared `packages/*` module - there the explicit type IS the contract. Argument types always stay explicit.
-- Named exports only - no default exports (exceptions: `*.config.*` files, `plugin.ts` whose loader reads `mod.default`, and Next.js App Router files; lint-enforced).
-
-## Comments
-
-- Comment WHY, never WHAT: hidden constraint, invariant, bug workaround (link it), trade-off. If a block needs a comment to be understood, rename/extract instead.
-- No section-divider comments (`// ---`, `// ===`).
-- Every JSDoc is multi-line, always - `/**`, the text, and `*/` each on their own line. A single-line `/** ... */` is never allowed, even for one sentence. Add one only on an independent function/class (not a React component or hook) that is >~15 lines or has non-obvious params. One sentence; document the surprising contract, not the name.
-- Never JSDoc a React component or hook - a genuinely surprising note goes on the specific prop/param type, or an inline comment at the call site.
-- Deferred work: `// TODO:` with the concrete follow-up, never a bare TODO.
-- Placeholder/sample data and stubs: greppable `// mock:` comment so throwaway code stays findable.
-
-## Frontend (any `apps/*` UI app and your shared UI package)
-
-Applies when this repo hosts UI apps; a headless api-only consumer can skip this section.
-
-- React Compiler is ON. Never hand-write `useMemo`/`useCallback`/`React.memo` - a compiler bail is a Rules-of-React violation to fix. Exception: your shared UI package is consumed pre-built, so hand-write stability there when it's part of a hook's contract (same reason `@openora/core/react` does).
-- Pick ONE component library and use its classes customized via utility classes + theme tokens. Don't hand-roll what the library provides.
-- Never hand-write component CSS selectors (`.btn-*{}`, `.table th{}`). A per-app `styles.css` holds only the theme plus custom properties for raw values with no token; every other style is a utility class on the element.
-- App-specific looks live in that app's `styles.css`; shared UI components stay visually neutral.
-- No hardcoded user-facing copy - every label goes through `t()` with a key in the module's `locales/`. Pattern: `locales/index.ts` exports `export const ns = registerTranslations('<module>', locales)`; components use `useTranslation(ns)`. Non-`en` files mirror `en.json` keys exactly.
-- Theme tokens and CSS variables are declared once in the shared UI package - style with semantic tokens (`bg-base-100`, `text-base-content`, `btn-primary`), never inline raw hex. A design color with no token: add it to BOTH dark and light theme blocks. A new token without a design source: ask the user first.
-- Hoist long class strings into a module-scope `const styles = { ... } as const` keyed by role - never inline long strings in JSX; merge with `cn()`.
-- Extract a repeated utility-class recipe into a shared component or constant on the third occurrence.
-- Import helpers like `cn()` from the shared UI package barrel - never deep-import.
-- Server state is not client state - key/cache/invalidate via the query lib, never `useEffect(fetch)`, never shadowed in ad-hoc caches.
-
-## Modular architecture (every app)
-
-- Feature modules live in `src/modules/<m>/` with the same internal folders: `pages/`, `components/`, `hooks/`, `utils/`, `locales/`, and a public barrel `index.ts`.
-- App-level (non-module) code splits the same way: `src/lib/` holds stateful/integration code (API clients, SDK wrappers, config); `src/utils/` holds pure stateless helpers (formatters, converters).
-- No cross-module imports, ever. Cross-module communication is query invalidation or a domain event, never a direct import.
-- Outer composition code (`src/app/`, `src/routes/`, `extensions.config.ts`) imports modules only through their barrel; deep-importing internals is forbidden. Files inside a module use relative paths to siblings only, never `../../` out of the module.
-- Components in `components/` and `pages/` are presentation-only: props in, JSX out - no fetching, no side effects. Business logic, queries, and mutations live in `hooks/`, which accept external dependencies (oRPC calls, API clients) as parameters.
-- Next.js client components: `'use client'` on line 1 + `.client.tsx` suffix; server components are the default (no marker). All-client apps (Vite/TanStack) use no suffix.
-- One concept per file, exported name matches the kebab-case filename; split hooks and components into separate files.
-
-## Package structure (`packages/*` and overlay packages)
-
-- One package = one concern, named `@<scope>/<kebab>`, with an explicit `exports` map. The entrypoint IS the public API; everything else is internal and off-limits to consumers (`oss-boundaries`).
-- Overlay/add-on packages mirror the platform module shape: `contract/`, `schema/`, `service/`, `router/`, `adapters/`, `__tests__/`, plus `plugin.ts` at the root as the single wiring point.
-- Each overlay owns its `drizzle.config.ts` and its own migration history - never share one migration folder across packages.
-- Pin exact dependency versions in every package; a package never depends on an app.
-
-## Errors
-
-- Fail fast at boundaries with typed errors (`CreateOrderSchema.parse(raw)` throws early).
-- No silent catches - log with context and rethrow.
-- Typed, named error classes via the shared factories (`makeNotFoundError`/`makeOwnershipError`/`makeConflictError`); the router's `mapErrors` keys off the exported class.
-- `ORPCError.message` is an English fallback for logs, not player-facing copy - UI copy keys off `.code` plus typed `.data` fields.
-- Money/critical paths are transactional AND idempotent: a DB guard inside the transaction, not just an `idempotencyKey` (delivery is at-least-once).
-
-## Testing
-
-- Co-locate as `src/__tests__/<name>.test.ts` (Vitest); service tests use a vi-mocked Drizzle.
-- Test behavior, not implementation - tests must survive a safe refactor (assert outputs, not private caches).
-- Cover new logic as part of the same change: unit tests for pure functions, authz negatives included.
-- Deterministic and isolated: no shared mutable state, no real network, seedable data.
-
-## Dependencies
-
-- Pin exact versions - no `^`/`~`.
-- No inline `fetch`/`axios` in module code - third-party integrations are ports + adapters bound at the composition root (`ctx.provide(KYC_ADAPTER, ...)`).
-- Add a dependency deliberately - std lib or a few lines often beat a tree.
-
-## Git and delivery
-
-- Conventional commits, enforced by commitlint (husky + CI): `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `ci`, `perf`. E.g. `feat(wallet): atomic debit command port`.
-- Subject starts lowercase, acronyms included (`feat(pam): kyc status filter`). This applies to the PR title too - squash merges derive the commit message from it.
-- One PR = one concern. Stage files explicitly; never `git add -A` when foreign changes are in the tree.
-- Green before review: typecheck + lint + unit tests pass; `pnpm verify` is the full gate (adds format:check + boundaries + build).
-- Branch off `dev`; never commit directly to a shared branch; never push without an explicit per-action "yes push".
-- PR description carries intent: what / why / acceptance criteria / ticket link. No secrets, internal hostnames, or PII - it is the public record.
-
-## Enforcement
-
-- `pnpm check:types` + `pnpm check:lint` (oxlint) + `pnpm test:unit` is the fast gate; `pnpm check:boundaries` (dependency-cruiser) is the whole-graph boundary/cycle check, also run by the pre-commit hook and CI.
-- oxlint extends the platform's shared config (`./node_modules/@openora/core/oxlint/oxlintrc.json`) - add local rules on top, never fork it.
-- Don't work around a lint/boundary violation - fix the import.
-- Agent rules are generated from `.rulesync/` via `pnpm gen:agents` - never hand-edit a generated file.
+## Never (lint-enforced unless noted)
+
+- `any` outside tests, `!` non-null assertions, `as` casts to silence the compiler (`as const` is
+  fine). Two sanctioned casts: test doubles through one `mock<T>()` helper (never inline in a
+  test), and a third-party inference boundary a library gives no honest way to satisfy (one cast,
+  one-line `// Library boundary:` note).
+- `interface`, TS `enum`, decorators, inheritance for reuse, default exports (exceptions:
+  `*.config.*`, `plugin.ts`, Next.js App Router files).
+- Hand-written duplicates of an inferrable type, re-inferring an imported schema, re-typing
+  derived schema fields, ad-hoc/duplicated Zod schemas outside a module's `contract/`.
+- Re-exporting types "to be nice" - import from where defined.
+- Inline `fetch`/`axios` in module code - third-party access is a port + adapter bound at the
+  composition root.
+- Deep (`../../`+) relative imports that leave your module/zone, imports of another module's
+  internals, import cycles, deep `dist/`/`src/` paths into another package.
+- SQL anti-patterns (bare `timestamp()`, CamelCase identifiers, hand-edited migrations) - detail
+  in `docs/standards/database.md`.
+- Silent catches - log with context and rethrow. `ORPCError.message` rendered to a player - UI copy
+  keys off `.code` + typed `.data` through `t()`.
+- Comments, unless one states a fact the code cannot contain (an external system's behaviour, a
+  spec constraint); a reason goes in the commit or PR, never inline. Never in tests. Detail:
+  `docs/standards/comments.md`.
+- An in-process test that mocks the database, a repository, or a sibling service - found one in
+  the diff, delete it and replace it with the API E2E; never add to it.
+
+## Always
+
+- **Naming:** files `kebab-case.ts`, one concept per file, filename names the concept
+  (`wallet.service.ts`, never `helpers.ts`); types `PascalCase`; values/functions `camelCase`;
+  true global constants `SCREAMING_SNAKE_CASE`; Zod schemas `<Name>Schema` with inferred type
+  `<Name>`; booleans read as predicates (`isActive`, `canEdit`); money is a decimal string plus a
+  `currency` field alongside it, never `amountCents`; IO functions are verbs (`fetchInvoice`); names
+  carry units and intent (`delayMs`, `maxRetries`).
+- **One source of truth per shape** - infer, never hand-write: `z.infer<typeof XSchema>`,
+  `typeof x.$inferSelect`. Full detail: `docs/standards/types.md`.
+- **Literal config arrays/objects (option lists, key sets) use `as const`**, not an explicit union
+  type annotation - let TypeScript infer the literal types.
+- **Schema-first at every boundary** (HTTP, config, env, events); validate once at the edge, trust
+  the type after.
+- **Entity ids typed through their owning type** (`playerId: Player['id']`), never a bare
+  `string`.
+- **Guard clauses first, main path last; more than 3 params -> one named object** (a leading
+  `tx` handle may stay positional). Always brace control statements, even one-liners (lint:
+  `curly`). Detail: `docs/standards/functions.md`.
+- **Construct objects by spread + override**, never a hand-copied field list.
+- **Side effects at the edges**; money paths are transactional AND idempotent (a DB guard inside
+  the transaction, not just an idempotency key). Detail: `docs/standards/errors.md`.
+- **Typed, named error classes** from the shared factories, mapped to transport in the router's
+  `mapErrors`.
+- **Pin exact dependency versions** (no `^`/`~`); add a dependency deliberately - std lib or a few
+  lines often beat a tree.
+- **A feature or fix PR ships its own tests** - no separate test PR. It ships the change, the
+  manual verification pass that proves it (drive the running stack by hand, attach a short video
+  per acceptance criterion, or the request/response trace for an API-only change, to the PR
+  description), and the tests that pass exercised, listed in the description's "Tests" list.
+  Which tier each one belongs to, and how to run the manual pass: `docs/standards/testing.md`.
+- **Green before review:** `/check` (typecheck + lint + unit tests) while iterating, `pnpm verify`
+  on the committed tree before the PR (the `guard-mr` hook refuses to open one until it passed on
+  HEAD). Conventional commits, lowercase subject (PR
+  title too - a squash merge turns it into the commit), one PR per concern. Never push without
+  explicit confirmation. The description carries what / why / acceptance criteria / bare ticket
+  key, the manual-verification evidence (a short video per acceptance criterion, before and after on
+  a fix) and the "Tests" list - but no CI checklist the pipeline already shows, no URLs,
+  hostnames, secrets, or PII. Detail: `docs/standards/git-delivery.md`.
+- **Fix the import, never work around a lint or boundary violation.** Agent rules are generated
+  from `.rulesync/` via `pnpm gen:agents` - never hand-edit a generated file. Detail:
+  `docs/standards/enforcement.md`.

package/template/__dot__rulesync/rules/db-conventions.md

@@ -4,80 +4,14 @@ targets:
   - '*'
 globs:
   - 'apps/api/**'
-description: SQL / Drizzle conventions for tables an overlay or local add-on owns.
+description: SQL / Drizzle conventions for tables an overlay or local add-on owns - the always-on core; full detail in docs/standards/database.md.
 ---
 
 # Database conventions (SQL / Drizzle)
 
-Applies to every table an overlay or local add-on owns (`apps/api/src/extensions/<name>/src/schema/`).
-Tables live in `@openora/*` core for platform domains - never edit those; these rules govern the
-tables you add. Boundary/import rules live in `oss-boundaries`; this file is SQL only.
+Applies to every table an overlay or local add-on owns (`apps/api/src/extensions/<name>/src/schema/`). Platform-domain tables live in `@openora/*` core - never edit those. Identifiers, timestamps, keys, indexes, N+1, idempotency and migrations are specified in `docs/standards/database.md` - read it before touching a schema, query, migration, or seed. The rules below are the ones that file does not state.
 
-## Identifiers - snake_case everywhere
-
-Every drizzle instance sets `casing: 'snake_case'`, so the SQL name derives from the camelCase key.
-Pass an explicit name only where casing can't derive it: table names, `pgEnum` types, index names.
-
-```ts
-// good - key derives the column; const camelCase; explicit snake_case only for table + index
-export const playerNote = pgTable(
-  'player_note',
-  {
-    id: uuid().primaryKey().defaultRandom(),
-    playerId: uuid().notNull(), // -> player_id
-    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
-  },
-  (t) => [index('player_note_player_id_idx').on(t.playerId)],
-);
-
-// bad - explicit/camelCase column names, PascalCase table
-pgTable('PlayerNote', { player_id: uuid('playerId') });
-```
-
-## Timestamps - always timestamptz
-
-```ts
-createdAt: timestamp({ withTimezone: true }); // good - Postgres timestamptz, store UTC
-createdAt: timestamp(); // bad - naive, drops the zone
-```
-
-Every datetime column (`createdAt`, `updatedAt`, `expiresAt`, any `*At`) carries the zone.
-
-## Keys, references, indexes
-
-- UUID primary keys (`uuid().primaryKey().defaultRandom()`).
-- **No foreign keys across a module/overlay boundary** - store a plain ID string and resolve via the
-  oRPC client or a schema subpath. FKs only within the same add-on.
-- `NOT NULL` by default; push defaults to the DB (`.notNull().default(...)`), not app code.
-- Index every column you filter or join on; name it `<table>_<cols>_idx`.
-
-## Efficient operations
-
-```ts
-// bad - N+1
-for (const id of ids) await db.select().from(wallet).where(eq(wallet.playerId, id));
-// good - one batched query
-await db.select().from(wallet).where(inArray(wallet.playerId, ids));
-```
-
-- Select only the columns you use; don't `select(*)` wide rows to read one field.
-- **Build rows by spread + override, never hand-copy field-by-field.** When a row mostly mirrors a
-  validated input, spread it and set only the server-computed fields - `db.insert(x).values({ ...input,
-id, createdAt })` - never re-list `field: input.field` per key (it silently drifts the moment a
-  column is added). Keep fields explicit only for: an order-sensitive hash/signature payload; a source
-  carrying columns the row must not receive (spread then omit them); or a null-vs-undefined boundary
-  that won't coerce (`actorId: input.actorId ?? null`).
-- **Money / critical paths are transactional and idempotent** - a DB guard inside the transaction,
-  not just an `idempotencyKey` (delivery is at-least-once).
-
-```ts
-await db.transaction(async (t) => {
-  if (await ledgerExists(t, idempotencyKey)) return; // guard, not just a key
-  await insertLedger(t, { idempotencyKey, amountCents });
-});
-```
-
-## Migrations
-
-- Never hand-edit generated migrations. Change the `pgTable`, then `pnpm db:migrate`.
-- One migration per schema change; review the generated SQL before committing.
+- Money: exact decimal, never float, never a scaled integer. Every money column is `decimal()` (Postgres `NUMERIC`) - never `real`/`float`, never an `integer` "cents" column. Pair it with a `currency` column; on the wire use `MoneyAmountSchema` (decimal string) + `currency`, never `z.number()`. Balance math runs in SQL, never JS float arithmetic.
+- `pgEnum` derives from a values + schema + type triple declared once (never an inline value array): `X_STATUSES = [...] as const` -> `XStatusSchema = z.enum(X_STATUSES)` -> `pgEnum('x_status', X_STATUSES)`.
+- Bound the fan-out: never `Promise.all(rows.map(fn))` when `rows` is a query result and `fn` calls out per row (a vendor adapter, another service) - it opens unbounded concurrent connections/requests and starves everything else at scale. Use `mapConcurrent(items, limit, fn)` (`@openora/core/server`).
+- Audit every mutation: each state-changing action emits a domain event the `audit` add-on subscribes to, or resolves `AUDIT_WRITER` and calls `record(...)`. A mutation with no audit trail is not done.

package/template/__dot__rulesync/rules/e2e-conventions.md

@@ -4,23 +4,49 @@ targets:
   - '*'
 globs:
   - 'apps/e2e/**'
-description: Playwright E2E conventions - dual-mode (USE_MOCKS) specs, fixtures, mocks, page objects.
+description: Playwright E2E conventions - specs run against the real stack; mocking is a narrow, justified exception.
 ---
 
 # E2E conventions (`apps/e2e`)
 
-Every spec is written ONCE and runs in two modes, switched by `USE_MOCKS`:
+Applies once this repo has an `apps/e2e` Playwright suite; a repo without one is not covered by this rule, and adding the suite is what turns it on.
 
-- `USE_MOCKS=true` - CI / pull request: requests fulfilled from `mocks/`, no stack needed, blocks merge.
-- unset - scheduled/local run against the real seeded API (`pnpm dev` stack must be up); failures alert, don't block.
+This file governs **how** a spec is written. A feature or fix PR ships its specs in the same branch as the change, after the manual verification pass (`docs/standards/testing.md`).
+
+Two kinds of spec live here:
+
+- **Browser specs** (`tests/<app>/**`) - a player or admin journey through the UI.
+- **API specs** (`tests/api/**`) - the `api` Playwright project: no browser, no `page`. Drives the real API over HTTP against real Postgres, with each external vendor replaced by a stub HTTP server the API is pointed at by env. This is the tier that proves an overlay end to end: request -> route -> service -> rows -> webhook -> resulting state. `USE_MOCKS` does not apply here at all.
+
+## Real stack by default
+
+Every spec runs against the real seeded stack - API, Postgres, and the apps under test - and that
+run is what blocks merge. A test that never executes the backend cannot tell you the backend works.
+
+`USE_MOCKS=true` intercepts responses in the browser and exists only for a state you cannot produce
+for real: a third-party widget or redirect you are not allowed to run in CI. It is an exception you
+justify per spec, never the mode a suite is written for. Anything reachable by seeding data or by
+scripting a vendor stub is NOT such a state - script the stub instead, and prefer the API tier when
+the behaviour under test is the backend's.
+
+Existing mocked specs are converted as they are touched; delete the fixture with the last spec that
+used it.
 
 ## Rules
 
 - Import `test`/`expect` from `fixtures.ts`, NEVER from `@playwright/test` - fixtures add `cleanup()` and shared setup.
-- `mockApi(page, routes)` (from `lib/mocks.ts`) registers interceptions only under `USE_MOCKS`; in real mode it's a no-op, so the same assertions exercise the live backend. Never branch test logic on the mode.
-- Mocks are typed: fixture shapes in `mocks/<domain>.ts` mirror the response contract - type platform-endpoint fixtures with the `z.infer` contract type from `@openora/*` so a contract change fails typecheck. No loose hand-written JSON.
+- Set up state through the product: seed data or drive the API, so the spec exercises the same path a player would. `mockApi(page, routes)` (from `lib/mocks.ts`) is the escape hatch above - reach for it only after the real setup is genuinely impossible, and never branch test logic on the mode.
+- A mock that stays is typed: fixture shapes in `mocks/<domain>.ts` mirror the response contract - type platform-endpoint fixtures with the `z.infer` contract type from `@openora/*` so a contract change fails typecheck. No loose hand-written JSON.
 - Selectors use `data-testid` - kebab-case, domain-prefixed (`chat-message`, `chat-input`). Never assert on CSS classes or component-library structure; shared UI components spread props so `data-testid` passes through.
 - Page objects in `pages/<name>.page.ts` are functional factories - no classes, no `this`; locators + actions returned as a plain object.
 - Test names are behavioural: "shows masked standings", not "table renders".
-- `cleanup(fn)` reverses any real data a test creates (runs in reverse order; no-op under mocks).
+- `cleanup(fn)` reverses any data a test creates (runs in reverse order) - the suite shares one database, so a spec that leaks rows breaks the next one.
 - Layout: `tests/<app>/<domain>/<scenario>.spec.ts` (one Playwright project per app, sharing fixtures/mocks/pages; run one with `--project=<app>`), `mocks/<domain>.ts`, `pages/<name>.page.ts`.
+
+## API specs (`tests/api/**`)
+
+- Use `request` (Playwright's APIRequestContext), never `page`. Assert status, body, and the state a follow-up request reports - not internals.
+- A vendor stub is a plain `node:http` server under `apps/e2e/`, modelled on `mock-identity-server.mjs`: it answers only the vendor endpoints the flow reaches and records the calls a spec asserts on. Point the API at it with the vendor's base-URL env var; every vendor adapter must accept one.
+- Drive the vendor's inbound side the way the vendor does - post the real webhook shape to the real route with a signature the stub's key material produces. Never call the adapter directly.
+- Own your data: create the player the spec needs and reverse it with `cleanup(fn)`. The suite shares one database.
+- Layout: `tests/api/<domain>/<scenario>.spec.ts`.

package/template/__dot__rulesync/rules/frontend-conventions.md.tpl

@@ -0,0 +1,35 @@
+---
+root: false
+targets:
+  - '*'
+globs:
+  - 'apps/web/**'
+  - 'apps/backoffice/**'
+  - 'packages/ui/**'
+description: React/UI conventions (component library, theming, i18n, permission gating, modular architecture) for apps/web, apps/backoffice, packages/ui - applies once those apps exist; full detail in docs/standards/frontend.md.
+---
+
+# Frontend conventions
+
+Applies once this repo has UI apps (`apps/web`, `apps/backoffice`, `packages/ui`); an api-only repo has none of those paths and this rule is inert there.
+
+UI-specific rules for `apps/web`, `apps/backoffice`, and `packages/ui`. Stack-agnostic rules (naming, types, functions, comments, errors, testing, git) live in `conventions`. Styling, i18n, and the modular architecture are specified in `docs/standards/frontend.md` - read it before touching a component, page, or module. The rules below are the ones that file does not state.
+
+## Component library
+
+- `{{scope}}/ui` is the component library: compose from its primitives (`Button`, `Dialog`, `Select`, `Switch`, `Tabs`, `Badge`, ...) plus utility classes on the theme tokens. Don't hand-roll what a primitive already provides; a genuinely missing one is added to `packages/ui/src/primitives/`.
+- Theme tokens and CSS variables are declared once in `packages/ui/themes.css`; `cn()` and `registerTranslations()` come from the `{{scope}}/ui` barrel - never deep-import.
+- `{{scope}}/ui` is consumed pre-built, so the React Compiler exception in `docs/standards/frontend.md` applies to it.
+
+## Permission-gated UI
+
+A page, nav item, tab, panel, or write action gated on a permission must check the exact resource/level the backend route actually asserts (`adminGuard.assert(resource, action)`) - never a looser, unrelated, or merely-plausible resource, and never a coarse "is admin" shortcut. Confirm the check against the route/service being called, not against what reads correctly at a glance.
+
+- Gate at every layer the feature touches, and keep them in agreement: the nav entry, the route guard, the data-fetching hook's `enabled`, and the rendered branch. A mismatch between any two of these reopens the exact bug class this guards against - a request that fires (and 403s) before the UI hides itself, a control shown that fails on click, or a section rendering an empty/failed state instead of disappearing.
+- Thread the permission into the query hook itself (`enabled: Boolean(id) && useHasPermission(resource, level)`), not only into the component that renders it - a hook with no grant check still fires for any caller that forgets the wrapper, including ones added later.
+- A missing or denied permission hides the section outright - never a failed-to-load screen, an empty state standing in for "no access," or a disabled-but-visible control. See `conventions` > Testing: cover the authz-negative for every new gate as part of the same change.
+
+## Modular architecture
+
+- Outer composition code (`src/app/`, `src/routes/`) imports a module only as `@/modules/<name>`; files inside a module use relative paths to siblings.
+- Cross-module communication is query invalidation, never a direct import.

package/template/__dot__rulesync/rules/oss-boundaries.md.tpl

@@ -0,0 +1,78 @@
+---
+root: false
+targets:
+  - '*'
+globs:
+  - 'apps/**'
+  - 'packages/**'
+  - 'package.json'
+  - 'pnpm-workspace.yaml'
+description: OSS core is read-only except in an OSS worktree (paired changes); enforced import/module boundaries.
+---
+
+# OSS core + import boundaries
+
+## Never patch OSS core in place
+
+`@openora/*` is a dependency - read it for reference, never patch it where it is installed.
+
+- Do NOT edit `node_modules/**` or the main linked OSS checkout (`{{ossDir}}`). The `guard-core` hook denies those writes in every agent tool; don't route around it with `sed`, redirection, or scripts. A patched dependency is lost on reinstall and diverges from the published package, and other sessions build against the main checkout.
+- Extend from the OUTSIDE first: overlay plugins, adapter rebindings, UI plugins, config.
+
+## Changing OSS core (paired change)
+
+When a fix can only live in core, change it in core - in a git worktree of `{{ossDir}}`, the one OSS path the hook lets you write. Works the same from any agent tool; `docs/agents/cross-repo.md` lists how each tool is granted access to `{{ossDir}}`.
+
+**Scope.** Any core change can be made here, in the worktree: a bug, a missing export or field, a contract alignment, or a new feature or module. Use the `handoff` skill only when the work should run in a separate session rooted in the OSS repo.
+
+**Genericity test - before the first edit.** Core serves every operator, and this session carries this operator's requirements. Write down, for the OSS PR's Why section: why it cannot be an overlay, adapter, or config here, and why another operator would want the same change. If only this operator needs it, core gets only the seam (an adapter token, an event, a config field, a hook) and the behavior stays in this repo. Jurisdiction rules, vendor specifics, and limits or flows only this operator uses never go into core.
+
+1. `pnpm oss:worktree <branch>`, with this repo's branch name: the same name in both repos is how skills pair the two requests. It creates or reuses `{{ossDir}}/.worktrees/<branch, / as +>` and installs its dependencies. `--link` also builds it and points `pnpm link:oss` at it, so this repo runs against the change; rebuild with `pnpm -C <worktree> build` after each core edit.
+2. Before the first edit there, read `<worktree>/AGENTS.md`, every `<worktree>/.rulesync/rules/*.md`, and the `<worktree>/docs/standards/` file for the kind of change. Files in the worktree follow the OSS rules; files in this repo follow this repo's rules. On conflict, the file's location decides.
+3. Review before any push. The OSS repo's own edit hooks (format, lint, typecheck) and its reviewer agents do not run from this session, so do their work yourself: run `pnpm -C <worktree> verify`, then review the worktree diff by `<worktree>/docs/standards/skills/review.md`, applying the checklists in `<worktree>/.rulesync/subagents/contract-reviewer.md` and, for money, auth, KYC, or RG paths, `security-reviewer.md`. Fix every BLOCK, and re-check the genericity test against the final diff.
+4. Commit and open the OSS pull request from the worktree, per `<worktree>/docs/standards/skills/delivery.md`, with its own explicit push confirmation. The OSS repo is public: its commits and PR carry the bare ticket key at most - no operator name, no internal URL, no link to this repo's request, and no ticket text or operator-specific domain detail. Describe the change in generic terms.
+5. Do not link the two requests - the shared branch name pairs them. This repo's request may be read by people outside the team, so it never names or links the OSS repo.
+6. Never `git checkout` a branch in the main `{{ossDir}}` checkout. Remove the worktree with `pnpm oss:worktree <branch> --remove` once both requests have merged.
+
+
+## Import boundaries (enforced)
+
+Enforced by `pnpm check:lint` (oxlint, per-edit), the pre-commit hook, CI, and the agent PostToolUse hook - plus `pnpm check:boundaries` (dependency-cruiser, one graph per app/package via turbo) and `pnpm check:shape` in repos that ship them. Fix the import, never work around a violation.
+
+### Across packages
+
+- No deep OSS imports: `@openora/*/src/*` or `/dist/*` - import only the package entrypoint (oxlint owns this one; every published entrypoint resolves into `dist/`, so the boundary graph cannot tell the two apart).
+- No deep `{{scope}}/ui` imports - only the barrel.
+- No app-to-app imports (`apps/web` <-> `apps/backoffice` <-> `apps/api`) - extract shared code to `packages/*`. Never reach across with a relative `../../apps/` path either.
+- No deep workspace-package imports - only the index entrypoint.
+- No import cycles.
+- A shared package (`packages/*`) must not import from an app.
+- `{{scope}}/ui` is renderer- and router-agnostic: no `next`, no router package. Take the capability through an injected adapter (see `navigation.tsx`).
+- No Node builtins in browser code (the Next instrumentation/proxy entries and `src/lib/api-server.*` are the declared exceptions).
+
+### Inside an app (ADR-0001)
+
+- No cross-module imports; a module is reached only through its barrel `index.ts`.
+- Layering inside a module: `pages/` is the leaf - `components/`, `hooks/`, `utils/` must not import it; `utils/` must not import `components/`, `hooks/` or `pages/`.
+- A file inside a module must not import its own barrel.
+- The shared kernel (`src/lib`, `src/hooks`, `src/utils`, `src/components`) must not import a feature module - dependencies point inwards.
+- Routes are leaves: nothing may import `src/app/**` (web) or `src/routes/**` / `routeTree.gen.ts` (backoffice, except `main.tsx`).
+- Transport clients (`@orpc/client`, `@orpc/openapi-client`, `@orpc/tanstack-query`) are constructed in `src/lib/` only.
+- A `'use client'` file must not import server-only code (`next/headers`, `src/lib/api-server.*`, `*.server.ts`).
+
+### Dependency manifest hygiene
+
+- Every import resolves; every npm package used is declared in that package's own `package.json`; no package sits in two dependency sections (a library's devDependency + peerDependency pair is the exception).
+- Production code imports no devDependency and no test/mock/fixture file.
+
+### Structure checks (`pnpm check:shape`, in repos that ship it)
+
+Runs the checks a dependency graph cannot make, because they are about files that do not exist or edges that do not exist:
+
+- Every module has `index.ts`. An `AGENTS.md` is optional - only for knowledge local to the module that the rules and the code do not show. A `check:shape` that still requires one drops that assertion with this rule, or the gate contradicts it.
+- The barrel re-exports only; the single side effect it may carry is `import './locales'`.
+- Every file under a module's `pages|components|hooks|utils` is reachable from the barrel, and every `packages/ui/src` file from the `{{scope}}/ui` barrel - otherwise it is dead code.
+
+Each app/package owns its own `.dependency-cruiser.cjs` (its own tsconfig for `@/*` alias resolution) built on the shared rule/option helpers in `.dependency-cruiser.shared.cjs`. Where the repo ships `pnpm gen:boundaries-graph`, it renders each package's graph (needs Graphviz).
+
+The shared options keep npm packages in the graph on purpose - a dependency-type rule can only judge a package that is a node - so build output is excluded per workspace path, never as a bare `/dist/`.