@openora/create 0.1.0 → 0.4.1-canary.101

package/template/__dot__rulesync/rules/conventions.md

@@ -0,0 +1,90 @@
+---
+root: false
+targets:
+  - '*'
+globs:
+  - '**/*'
+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
+
+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`.
+
+| 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)`).
+- 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.
+- Boring and consistent: match the surrounding code's idiom, naming, and density.
+
+## Never (lint-enforced unless noted)
+
+- `any` outside tests, `!` non-null assertions, `as` casts to silence the compiler (`as const` is
+  fine).
+- `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`.
+
+## 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`.
+- **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.** 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.
+- **Test at the outermost tier that reaches the behaviour:** a UI journey -> browser E2E; an API
+  route, an overlay, a vendor adapter, anything with SQL -> API E2E against real Postgres with the
+  vendor stubbed at its HTTP boundary; a pure function -> a co-located unit test in `__tests__/`.
+  Never fake a query builder and never let a spy assertion be the point of a test; always cover
+  authz negatives. Detail: `docs/standards/testing.md`.
+- **Green before review:** `pnpm verify` passes. Conventional commits, lowercase subject, one PR
+  per concern. Never push without explicit confirmation. Detail: `docs/standards/git-delivery.md`.

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

@@ -0,0 +1,48 @@
+---
+root: false
+targets:
+  - '*'
+globs:
+  - 'apps/e2e/**'
+description: Playwright E2E conventions - specs run against the real stack; mocking is a narrow, justified exception.
+---
+
+# E2E conventions (`apps/e2e`)
+
+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.
+- 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 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/oss-boundaries.md

@@ -0,0 +1,31 @@
+---
+root: false
+targets:
+  - '*'
+globs:
+  - '**/*'
+description: OSS core is read-only; enforced import/module boundaries.
+---
+
+# OSS core + import boundaries
+
+## Never modify OSS core
+
+`@openora/*` is a third-party dependency - read it for reference, never write to it.
+
+- Do NOT edit `node_modules/**` or a linked OSS checkout. Those paths are write-denied in `.claude/settings.json`; don't route around it with `sed`, redirection, or scripts. A patched dependency is lost on reinstall and diverges from the published package.
+- Extend from the OUTSIDE only: overlay plugins, adapter rebindings, UI plugins, config.
+- If something can only be fixed in core, STOP and report it upstream (problem, expected behavior, likely location).
+
+## Import boundaries (enforced)
+
+Enforced by `pnpm check:lint` (oxlint, per-edit), `pnpm check:boundaries` (dependency-cruiser, whole graph), the pre-commit hook, CI, and the agent PostToolUse hook. Fix the import, never work around a violation.
+
+- No deep OSS imports: `@openora/*/src/*` or `/dist/*` - import only the published entrypoint or subpath export.
+- No deep imports into your own shared packages - only the barrel/index entrypoint.
+- No app-to-app imports (`apps/api` <-> `apps/web` <-> `apps/backoffice`) - extract shared code to `packages/*`.
+- No cross-module imports inside an app - go through the module barrel, a query invalidation, or a domain event.
+- No overlay-to-overlay imports - couple via a command port, a domain event, or a shared contract.
+- No import cycles.
+
+`pnpm check:boundaries:graph` renders the graph (needs Graphviz).

package/template/__dot__rulesync/rules/overview.md

@@ -14,10 +14,16 @@ this repo. Every per-tool instruction file (`AGENTS.md` - shared, also Codex's b
 subagent and command mirrors are generated by
 [rulesync](https://github.com/dyoshikawa/rulesync) from the single source in `.rulesync/`
 (`rules/`, `subagents/`, `commands/`, `mcp.json`). Edit the source under `.rulesync/`, then
-run `pnpm sync:agents`. Do not hand-edit the generated files.
+run `pnpm gen:agents`. Do not hand-edit the generated files.
 
 This repo is a downstream igaming operator built on the OSS platform (`@openora/*`).
 
+Sibling rules (load on demand; don't reopen settled questions):
+
+- `conventions` - the always-on code standard (naming, types, functions, package structure, errors, testing, git, frontend, DB), with a table routing each kind of change to its deep-dive file in `docs/standards/`.
+- `oss-boundaries` - OSS core is read-only; enforced import/module boundaries.
+- `e2e-conventions` - dual-mode Playwright specs, fixtures, mocks, page objects.
+
 ## HARD RULE: never modify OSS core
 
 `@openora/*` is a third-party dependency - treat it like any published npm package. You may READ it for reference, never write to it.
@@ -72,6 +78,8 @@ Delegate work to these scoped agents - the `start` / `enhance-intent` playbooks
 - `builder` - senior fullstack engineer. Implements overlays, swaps adapters, mounts UI pages.
 - `qa` - writes/runs Playwright E2E tests; triages whether a bug is in OSS core (upstream) or your overlay (local fix).
 - `debugger` - root-causes failures, build-time (Next/Turbopack, tsc, module resolution) and runtime (Chrome DevTools: console/network/DOM). Spawn it whenever something errors or behaves wrong; it finds the cause and routes the fix.
+- `quality-reviewer` - reviews a diff: boundaries, conventions, frontend rules, perf, duplication. Findings only.
+- `security-reviewer` - reviews a diff: authz, secrets/PII, money paths, input validation. Findings only.
 
 This repo consumes OSS core as linked packages - never edit `@openora/*` source. If a bug is in core, report it upstream; extend from the outside via plugins.
 
@@ -86,7 +94,6 @@ This server reads the platform CATALOG (not OSS source) - it tells you what exis
 - `list-adapters` - vendor swap seams (interface + token + status)
 - `list-routes [module]` - oRPC route namespaces
 - `list-events` - cross-module domain events you can subscribe to
-- `list-slots` - named UI slots you can fill from a UI plugin
 - `describe-module <name>` - one module's group, tables, routes
 - `schema-get <name>` - locate a Zod contract schema's file
 - `get-config-schema` - the igaming-config fields a consumer can set

package/template/__dot__rulesync/skills/add-feature/SKILL.md

@@ -4,7 +4,7 @@ name: add-feature
 description: >
   Deliver a feature end-to-end in this consumer repo. Aggregates context (Jira + Confluence + Slack +
   Google Drive + Notion + local docs + past sessions + codebase), produces an approved plan, then drives
-  delivery by calling sibling skills - create-plugin (build), code-review (review), create-pr (MR) -
+  delivery by calling sibling skills - create-plugin (build), review, create-pr (MR) -
   and create-task for ticket hygiene. Transitions Jira (no comments) and drafts a one-line Slack
   notice. Use on "add feature", "plan <KEY>-XXX", "deliver <KEY>-XXX", or /add-feature [<KEY>-XXX].
   Read-only until the plan is approved; never pushes, transitions Jira, or sends Slack without OK.
@@ -33,7 +33,7 @@ re-implement their work. The platform-core twin is the `/add-feature` skill in t
 - **Read-only until the Step 3 plan is approved.** No edits, commits, pushes, Jira writes, or Slack
   sends before sign-off.
 - Reuse sibling skills, don't reinvent: **create-task** (ticket format), **create-plugin** (build an
-  overlay), **code-review** (review), **create-pr** (MR). Delegate code to subagents.
+  overlay), **review** (review), **create-pr** (MR). Delegate code to subagents.
 
 ## Steps
 
@@ -82,7 +82,7 @@ When implementation starts, transition Jira to In Progress (Step 7 - confirm fir
 
 ### 5. Review + tests
 
-- Run **code-review** on the change set; loop `[BLOCK]`/`[WARN]` fixes back through `builder`.
+- Run **review** on the change set; loop `[BLOCK]`/`[WARN]` fixes back through `builder`.
 - Run `/check` (typecheck + lint). Don't proceed on red.
 - Derive an e2e checklist from the AC (happy path, edge cases, authz negatives, error states), then
   `qa`: write/run the E2E specs, drive `chrome-devtools` on failure.

package/template/__dot__rulesync/skills/create-plugin/SKILL.md

@@ -13,7 +13,7 @@ description: >
 
 The platform is extended from the **outside only** (overlay plugin / adapter rebind / UI page /
 config) - never by editing `@openora/*`. This skill picks the correct seam and scaffolds it.
-Domain questions go to `expert` first; review the result with `code-review`.
+Domain questions go to `expert` first; review the result with `review`.
 
 ## 1. Classify the seam (ask if unclear)
 
@@ -30,9 +30,9 @@ Hand off via the `add-feature` skill's `handoff.md`. Do not patch the linked OSS
 ## 2. Ground first
 
 - Read `.claude/rules/overview.md` (what you may and may not touch) and
-  `.claude/rules/db-conventions.md` (if the extension owns tables).
+  `docs/standards/database.md` (if the extension owns tables).
 - Inspect what already exists with the `oss` MCP: `catalog-overview`, `list-adapters` (token +
-  default binding to swap), `list-routes` (collision check), `list-slots`, `list-events`.
+  default binding to swap), `list-routes` (collision check), `list-events`.
 - For a domain rule you can't safely assume (a limit, a KYC threshold, a jurisdiction behavior),
   spawn `expert` before scaffolding.
 
@@ -54,8 +54,8 @@ plugins: [myCustomPspAdapter, walletModule];
 
 - **Boundaries**: import only package entrypoints (`@openora/core`, not `.../src` or `.../dist`).
   No imports between extensions; cross-extension data goes through the oRPC client or a schema subpath.
-- **Tables**: live in the overlay's own `src/schema/index.ts`; follow `db-conventions` (snake_case,
-  `timestamp({ withTimezone: true })`). Run `pnpm db:migrate` after.
+- **Tables**: live in the overlay's own `src/schema/index.ts`; follow `docs/standards/database.md`
+  (snake_case, `timestamp({ withTimezone: true })`). Run `pnpm db:migrate` after.
 - **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 is not done.
 - **Validate at the edge**: Zod schemas for every route input/output; no inline `fetch`/SQL in handlers.
@@ -64,7 +64,7 @@ plugins: [myCustomPspAdapter, walletModule];
 
 - `/check` (typecheck + lint) green.
 - Plugin boots (API health check / `pnpm dev`).
-- Hand to `code-review` before opening an MR.
+- Hand to `review` before opening an MR.
 
 ## Rules
 

package/template/__dot__rulesync/skills/create-pr/SKILL.md

@@ -31,7 +31,7 @@ If the current branch isn't in the table, target `dev`.
 3. **Commit.** Conventional-commit message (`feat:`, `fix:`, `docs:`, `refactor:`,
    `chore:`); for ticket work prefix the ticket key (e.g. `feat(<KEY>-123): ...`).
 4. **Verify before pushing** (cheap insurance): run the repo's check (e.g.
-   `pnpm typecheck && pnpm lint`). Don't push a red tree.
+   `pnpm check:types && pnpm check:lint`). Don't push a red tree.
 5. **Push** the current branch - but STOP and get an explicit per-action "yes push"
    from the user FIRST. Report the commit SHA, then ask. Invoking this skill is NOT
    push authorization. Pushing to a shared/env branch (`dev`, `stage`, `prod`)

package/template/__dot__rulesync/skills/create-ui-module/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: create-ui-module
+targets: ['*']
+description: >
+  Create a frontend feature module in apps/backoffice or apps/web following ADR-0001's
+  modular architecture: standard folder shape, co-located locales, DI hooks, pure
+  components, barrel entry, route wiring. Use on "create module", "new feature module",
+  "add a backoffice/web module", "/create-ui-module <app> <name>".
+---
+
+# create-ui-module (consumer)
+
+Scaffold a feature module under `src/modules/<name>/` per ADR-0001 (`docs/adr/0001-modular-architecture.md`). The shape is lint-enforced (`tools/oxlint-module-structure.mjs`: folder structure, `use-` hook naming, kebab-case files, client-component naming). Copy an existing module as the reference - `apps/backoffice/src/modules/roles/` is canonical.
+
+## 1. Resolve input
+
+`<app> <name>` from `$ARGUMENTS` (`backoffice` | `web`, kebab-case name). Ask if missing. Confirm the module doesn't exist and the concern isn't already owned by another module.
+
+## 2. Create the shape
+
+```
+src/modules/<name>/
+  pages/<name>-page.tsx        page entrypoint(s)
+  components/                  presentational only - props in, JSX out
+  hooks/use-<x>.ts             ALL logic/queries/mutations; deps passed as parameters
+  utils/                       local helpers (only if needed)
+  locales/en.json              translation keys
+  locales/index.ts             registration (below)
+  index.ts                     public barrel - the ONLY entry other code may import
+```
+
+`locales/index.ts` pattern (exact):
+
+```ts
+import { registerTranslations } from '@<scope>/ui';
+import en from './en.json';
+
+export const locales = { en };
+export const ns = registerTranslations('<name>', locales);
+```
+
+Components use `useTranslation(ns)`; no hardcoded copy. Non-`en` files mirror `en.json` keys exactly.
+
+## 3. Wire the route
+
+- backoffice: `src/routes/_authed/<name>.tsx` -> `createFileRoute` with `component` imported from `@/modules/<name>` (see `src/routes/_authed/roles.tsx`).
+- web: the App Router page under `app/(shell)/<name>/` imports from `@/modules/<name>`; client components get `'use client'` line 1 + `.client.tsx` suffix.
+
+## 4. Non-negotiables
+
+- No cross-module imports - cross-module effects go through query cache invalidation, never a direct import.
+- Outside code imports ONLY the barrel via `@/modules/<name>`; inside the module use relative paths.
+- Hooks take their clients (oRPC/API) as parameters (see `roles/hooks/use-iam-client-deps.ts`) so they're testable without global mocks.
+- Follow `docs/standards/frontend.md` (daisyUI, theme tokens, hoisted `styles` const, React Compiler - no manual memo).
+
+## 5. Verify
+
+`/check` green (the structure lint runs inside `pnpm check:lint`); route renders (`pnpm dev`). Hand to `review` before an MR.

package/template/__dot__rulesync/skills/handoff/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: handoff
+description: >
+  Package the current task into a self-contained prompt another agent (a
+  teammate, or a fresh Claude session in another repo) can execute without this
+  conversation. Gathers context from the chat so far plus live repo/environment
+  state, then emits a copy-pasteable handoff. Use on "hand this off", "prompt for
+  another agent", "write a handoff", when routing an OSS-core change into the
+  platform repo, or /handoff [what to hand off | target agent/repo]. Produces a
+  copy-pasteable prompt and may use any tool to gather context; the one hard line
+  is never force-push.
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+  - Edit
+  - Bash
+disallowed-tools:
+  - Bash(git push --force:*)
+  - Bash(git push -f:*)
+  - Bash(git push --force-with-lease:*)
+  - Bash(git push --force-with-lease)
+  - Bash(git push -f)
+---
+
+# handoff - write a self-contained prompt for another agent
+
+Turn "what we're doing" into a prompt a _stranger_ agent can act on with zero access to this
+chat. The receiver has none of our context, so the prompt must carry all of it.
+
+Common use here: an OSS-core change this consumer can't make itself. The receiver is a teammate
+(agent teams on) or a new Claude session rooted in the platform checkout (agent teams off) - see
+the "Fixing something in OSS core" rule. Either way it needs a standalone brief.
+
+Optional argument = what to hand off / who to (e.g. `the OSS core publish fix`, `to a teammate in
+the platform repo`, a repo path, an issue/MR#). No argument -> hand off the current in-flight task.
+
+## Rules
+
+- **One hard line: never force-push** (`git push --force` / `-f` / `--force-with-lease`), in any
+  repo, ever - it rewrites shared history. Every other tool is fair game. The skill's main output
+  is still the prompt; take further action (commit, push, spawn, launch) only on explicit confirmation.
+- **Self-contained.** The receiver can't see this conversation. Inline every fact they need:
+  exact paths, branch/remote names, IDs (MR/PR/ticket), commands, versions, error strings.
+  No "as discussed", no "the file we changed", no unresolved pronouns.
+- **Facts over memory.** Verify the moving parts against live state (git, files, CLIs) before
+  writing them - don't trust half-remembered branch names or versions.
+- **No secrets.** Never inline tokens, passwords, or `.env` values. Reference the env var name.
+- **Scope, don't dump.** Include what's load-bearing for the task; link/name the rest.
+
+## Step 1 - Resolve scope
+
+From the argument + the conversation, state in one line: the goal, the target repo/dir, and (if
+known) the agent type or persona best suited. If genuinely ambiguous, ask one clarifying question;
+otherwise proceed with the obvious reading and note the assumption.
+
+## Step 2 - Gather live context
+
+Pull only what the task touches (skip irrelevant ones):
+
+- Repo/env: `pwd`; `git -C <dir> remote -v`; `git -C <dir> branch --show-current`;
+  `git -C <dir> status --short`; recent `git log --oneline -5`. Note default/target branch.
+- Work state: relevant file paths (verify they exist), functions/symbols, versions/pins,
+  exact error messages or failing job names, IDs (MR/PR/ticket/pipeline).
+- Conventions the receiver must follow: point at the repo's rules (`CLAUDE.md`,
+  `.rulesync/`, `AGENTS.md`) rather than restating them; call out any that bit us.
+- What's already done vs. what remains (so they don't redo or undo work).
+
+## Step 3 - Emit the handoff
+
+Output one fenced markdown block (so it copy-pastes cleanly), using these headings - drop any
+that don't apply, never pad:
+
+- **Task** - one imperative sentence: the outcome wanted.
+- **Environment** - repo(s), absolute path(s), remote(s), current + target branch, sibling deps.
+- **Background** - the why + current state + root cause/findings already established. This is
+  where prior investigation goes so it isn't repeated.
+- **Do this** - ordered, concrete steps. Name files/symbols/commands. Mark decisions that need
+  a human ("report the plan first, don't push").
+- **Verify** - the exact commands/gates that must pass, and the expected green result.
+- **Constraints** - boundaries (read-only zones, "never push without explicit yes", conventional
+  commits, branch-off-target, don't touch X). Inherit the repo's rules; restate only the sharp edges.
+
+After the block, in <=2 lines: state the key assumption you made, and offer to (a) tweak the
+prompt, (b) save it to a file, or (c) launch it now (spawn a teammate with a suitable agent type,
+or hand it to the operator to paste into a session rooted in the target repo). Only save or launch
+on explicit confirmation.
+
+## Quality bar
+
+A good handoff passes this test: **hand it to someone who has never seen this repo or chat, and
+they can start in under a minute and finish without asking you anything.** If a step assumes
+context the block doesn't contain, fix the block.

package/template/__dot__rulesync/skills/review/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: review
+targets: ['*']
+description: Multi-agent code review of the working branch against this repo's conventions, OSS-core boundaries, frontend rules, security, and operator-domain fit. Fans out a configurable number of parallel reviewers, each grounded in the rule docs, then synthesizes one verdict. Use on "review this", "code review", "/review", optionally "--agents N", "--base <ref>", "--fix", "--post" (publish findings to the MR as inline comments + a summary verdict), "--yes" (post without confirming), a GitLab MR number, or paths.
+---
+
+# review
+
+You are the orchestrator: scope the diff, fan out N reviewers across dimensions, dedup findings, report ONE verdict. Report-only unless `--fix`.
+
+Checklist - tick as you go:
+
+```
+- [ ] 1. Parse args (--agents / --base / MR# / paths / --fix / --post / --yes)
+- [ ] 2. Scope the diff; if empty, ask
+- [ ] 3. Collect task context (ticket AC + MR discussion)
+- [ ] 4. Pick applicable dimensions; small diff -> review inline, else spawn reviewers in ONE message
+- [ ] 5. Dedup + apply the evidence gate
+- [ ] 6. Report one verdict (+ apply fixes only if --fix)
+- [ ] 7. Post to the MR as inline comments + summary (only if --post)
+```
+
+## 1. Parse `$ARGUMENTS`
+
+- `--agents N` - parallel reviewers (1-5); default one per applicable dimension.
+- `--base <ref>` - diff base; default `dev`.
+- `<number>` - a GitLab MR: `glab mr diff <n>` for the patch, `glab mr view <n>` for intent.
+- paths - restrict review to those files/dirs.
+- `--fix` - apply BLOCK/WARN fixes after the review; default report-only.
+- `--post` - publish findings to the GitLab MR as inline diff-line comments + a one-line summary verdict (§8). Requires an MR number. Draft-and-confirm by default.
+- `--yes` - with `--post`, skip the confirmation and publish straight away.
+
+## 2. Scope the diff
+
+`git diff <base>...HEAD --name-only`; if empty, fall back to `git status -s`; if still empty, ask. Group changed files by app/package so reviewers and any file-split share the same map. Note the total changed-line count - it picks the mode in §4.
+
+## 2b. Collect task context
+
+Distill everything here into ONE context block of at most ~30 lines; it is the only task context reviewers receive.
+
+- **Ticket.** Extract the BF key from the branch name / MR title. Fetch it (Atlassian MCP or REST) and distill: goal in one line + acceptance criteria as bullets. No key or no access: skip silently.
+- **MR discussion.** If reviewing an MR: `glab mr view <n>` + unresolved discussion threads. Distill to stated intent + open reviewer asks, so the review doesn't repeat or contradict them. No MR: use branch commit subjects as intent.
+- The AC bullets feed the verdict (§7) - a finding "AC not met" needs a specific bullet.
+
+## 3. Ground every reviewer (mandatory)
+
+Each reviewer MUST read the changed code AND the rule docs owning its dimension before judging - never infer behavior from a diff hunk; if a finding depends on a called function, open it. Cite the docs in findings:
+
+- `.claude/rules/conventions.md` - the always-on code standard, with a table routing to the deep-dive file in `docs/standards/`.
+- `docs/standards/frontend.md` - React/UI rules (React Compiler, daisyUI, module isolation) when the diff touches a UI app or the shared UI package.
+- `.claude/rules/oss-boundaries.md` - OSS core read-only; enforced import boundaries.
+- `docs/standards/database.md` - SQL/Drizzle rules for overlay tables.
+- `.claude/rules/workflow.md` + `.claude/rules/overview.md` - how this repo operates.
+
+## 4. Dimensions
+
+Dimensions and the roster agent that owns each - never `general-purpose`:
+
+1. **Boundaries, conventions, frontend, perf, duplication** - `quality-reviewer` (its prompt carries the full lens checklists; always applicable).
+2. **Security & secrets** - `security-reviewer`; only if overlay routes, adapters, auth/session, env/config, or money-adjacent code changed.
+3. **Operator/domain fit** - `expert`; only if business logic changed AND AC exists to judge against.
+
+**Small-diff fast path (<= 150 changed lines): no subagents.** Read the changed files in the main thread and apply the applicable agents' checklists yourself (they live in `.claude/agents/<name>.md` - skim, don't spawn). This is the common case and costs a fraction of a fan-out.
+
+## 5. Allocate to `--agents N` (large diffs only)
+
+- N unset: one reviewer per applicable dimension.
+- N > dimensions: extras are additional `quality-reviewer` instances split by file group (state the split; never silently drop files).
+- N < dimensions: drop `expert` first, then merge security into quality (say so in the report).
+
+Spawn all reviewers in a SINGLE message (parallel). Pass each: the changed-file list for its dimension (pre-grouped - reviewers never re-scope), the base ref, the §2b context block, and hard caps: read only changed files + immediate callees; max 10 findings; compact `[SEV] file:line - finding - evidence - fix` lines, no prose; do NOT run `/check`/tests.
+
+## 6. Evidence gate (cut false positives)
+
+Every reviewer applies this before returning; re-apply it yourself when synthesizing:
+
+- Every `[BLOCK]`/`[WARN]` cites a concrete `file:line` AND the rule doc violated - otherwise downgrade to `[INFO]` or drop.
+- High-confidence findings only; unsure = downgrade or omit. Few actionable findings beat flooding.
+- No invented runtime failures - state the trigger path or don't raise it.
+- Don't duplicate what tooling enforces (oxlint, the `/check` gate); for a suspected lint/boundary issue say "confirm with `pnpm check:lint`" - flag only what the gates miss.
+
+## 7. Synthesize
+
+Dedup by `file:line`, group by dimension, order BLOCK -> WARN -> INFO. Each line: `[SEV] file:line - finding - evidence - rule cited - fix`. Lead with a one-line summary (counts per severity + verdict); end with **APPROVED** / **CHANGES REQUESTED** + the single most critical finding.
+
+Severities: `[BLOCK]` must fix before merge (core edit, boundary break, authz/secret/PII risk, broken extension wiring); `[WARN]` should fix (convention violation, missing test, weak validation); `[INFO]` FYI / hardening.
+
+If `--fix`: apply BLOCK + WARN fixes in the working tree (smallest diff satisfying the cited rule), run `/check`, report green/red. Leave INFO untouched. Never commit or push.
+
+## 8. Post to the MR (`--post`)
+
+Only when `--post` is set and the target is an MR number. Turns findings into terse review comments: one line each, brief why, backtick every identifier.
+
+Post BLOCK + WARN as inline threads; include INFO only if it maps to a concrete `file:line`. One comment per finding, one line each.
+
+1. **Draft.** Rewrite each finding as a terse comment keyed to its `file:line`. Compose the summary as ONE sentence stating whether the changes block prod/push, e.g. `Not a blocker for push - a few cleanups worth doing.` or `Blocker: BLOCK finding in `x.ts` must be fixed before we push.`
+2. **Confirm.** Show all drafted comments + the summary and stop for approval - UNLESS `--yes`, then skip straight to posting.
+3. **Post inline comments** as positional discussions on the diff. Mechanics + gotchas are in the Notion memory `glab MR inline diff-line comments (positional discussions)` (query the Memories DB) - the short of it:
+   - Diff SHAs from `glab api "projects/consumer%2Fconsumer/merge_requests/<n>" | jq .diff_refs`.
+   - Anchor on the NEW-file line of an added (`+`) line (`git show <src-branch>:<file> | grep -n`).
+   - POST JSON (build with Python `json.dumps` to dodge quoting) to `.../merge_requests/<n>/discussions` with a `position` object; `glab api -H "Content-Type: application/json" ... --input -`. Do NOT use `-f "position[...]"` - nested params silently drop the position.
+   - Verify each response's `.notes[0].position.new_line`; if null it fell back to a general note - delete (`glab api -X DELETE .../notes/<id>`) and retry.
+4. **Post the summary** as one general MR note (`glab mr note <n> -m "<one sentence>"`).
+5. Report back the count posted + the summary verdict. Never resolve threads; never push.
+
+## Constraints
+
+- Reviewers report; only the orchestrator edits, and only under `--fix` (working tree only - no commit, no push).
+- NEVER edit `@openora/*` core or `node_modules`.
+- Every finding cites a rule doc - no ungrounded opinions.
+- Cap at 5 parallel reviewers.

package/template/__dot__rulesync/subagents/builder.md

@@ -46,17 +46,17 @@ my-igaming/
 2. Create `apps/api/src/extensions/<vendor>/plugin.ts`:
 
    ```ts
-   import { definePlugin } from '@openora/plugin-host';
+   import type { CoreTokenCatalog, Plugin } from '@openora/core/server';
    import { KYC_ADAPTER } from '@openora/adapters';
    import { MyKycAdapter } from './src/my-kyc-adapter.js';
 
-   export default definePlugin({
+   export default {
      id: 'my-kyc',
      dependsOn: ['identity'], // always load after the default-binding module
      register(ctx) {
        ctx.provide(KYC_ADAPTER, () => new MyKycAdapter());
      },
-   });
+   } as const satisfies Plugin<CoreTokenCatalog>;
    ```
 
 3. Register it in `extensions.config.ts` AFTER the module that owns the default binding.

package/template/__dot__rulesync/subagents/debugger.md

@@ -26,7 +26,7 @@ Reproduce deterministically with a build, not the dev server (dev caches aggress
 
 ```bash
 pnpm -C apps/web exec next build   # or apps/backoffice
-pnpm typecheck
+pnpm check:types
 ```
 
 Common consumer-side causes (this stack links `@openora/*` from a sibling checkout):
@@ -35,7 +35,6 @@ Common consumer-side causes (this stack links `@openora/*` from a sibling checko
 | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Module not found: Can't resolve '@openora/...'` but `node -e "require.resolve(...)"` works | A bundler won't compile across the link: boundary (packages live outside the project root) | point the bundler's project root at the common ancestor of your frontend repo and the OSS checkout, and allow imports from outside the root (eg Next.js `turbopack.root` + `experimental.externalDir: true`). |
 | `extends "@openora/tsconfig/..." doesn't resolve`                                           | An `extends` chain through a symlinked tsconfig                                            | the `@openora/tsconfig` configs must be self-contained (no `extends`)                                                                                                                                         |
-| Resolves but won't import                                                                   | `@openora/*` not built                                                                     | run `pnpm build:oss`                                                                                                                                                                                          |
 | Stale error after a fix                                                                     | Turbopack cache                                                                            | `rm -rf apps/*/.next` and rebuild                                                                                                                                                                             |
 
 To confirm a resolution issue is the bundler (not a missing dep):

package/template/__dot__rulesync/subagents/qa.md

@@ -23,7 +23,7 @@ The OSS platform is headless (API + modules only) - the player app and backoffic
 | Player app | http://localhost:3000 | operator                              |
 | Backoffice | http://localhost:3002 | operator                              |
 
-Seed credentials (after `pnpm seed`): `admin@oss.dev` / `password123`
+Seed credentials (after `pnpm db:seed`): `admin@oss.dev` / `password123`
 
 Confirm actual ports and which UIs exist with the operator - they may have only an API, or a single combined app.