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

package/template/__dot__rulesync/skills/ship/watch-pr.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+// Watches the MR or PR of a branch and prints one line, then exits, when ship has work on it:
+//   failed | conflicts | threads <ids> | green (only with --until-green) | merged | closed | error <message>
+// A thread waits for an answer until its last comment is an "Agent:" reply from the account this runs as
+// (anyone can type the prefix); it is reported once it stayed the same for two checks, so a review with
+// ten comments is one line. Run it in the background:
+//   node watch-pr.mjs <branch> [--until-green]        WATCH_DEBUG=1 prints every check to stderr
+// --once checks one time, for a caller that polls on its own (a scheduler): threads are reported at
+// once, and `none` means nothing to do.
+import { execFileSync } from 'node:child_process';
+
+const EVERY_MS = 120_000;
+// ponytail: a repo with no CI on the last commit reads green after this; a head-SHA match on checks if it matters
+const NO_CI_MS = 10 * 60_000;
+const MAX_ERRORS = 5;
+const AGENT_REPLY = 'Agent:';
+const FAILED = [
+  'FAILURE',
+  'ERROR',
+  'CANCELLED',
+  'TIMED_OUT',
+  'ACTION_REQUIRED',
+  'STARTUP_FAILURE',
+  'failed',
+  'canceled',
+];
+
+const [branch, ...flags] = process.argv.slice(2);
+if (!branch) {
+  console.error('usage: watch-pr.mjs <branch> [--until-green | --once]');
+  process.exit(2);
+}
+const untilGreen = flags.includes('--until-green');
+const once = flags.includes('--once');
+
+const run = (cmd, args) =>
+  execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+const json = (cmd, args) => JSON.parse(run(cmd, args));
+const unansweredIds = (lastComments, me) =>
+  lastComments
+    .filter(
+      (comment) => !(comment.author === me && comment.body.trimStart().startsWith(AGENT_REPLY)),
+    )
+    .map((comment) => String(comment.id))
+    .sort();
+
+const THREADS = `query($owner: String!, $name: String!, $number: Int!, $endCursor: String) {
+  viewer { login }
+  repository(owner: $owner, name: $name) { pullRequest(number: $number) {
+    reviewThreads(first: 100, after: $endCursor) {
+      nodes { isResolved comments(last: 1) { nodes { id body author { login } } } }
+      pageInfo { hasNextPage endCursor }
+    }
+    comments(last: 1) { nodes { id body author { login } } }
+  } }
+}`;
+
+function github() {
+  const pr = json('gh', [
+    'pr',
+    'view',
+    branch,
+    '--json',
+    'number,url,state,mergeable,statusCheckRollup',
+  ]);
+  const [, owner, name] = new URL(pr.url).pathname.split('/');
+  const args = [
+    'api',
+    'graphql',
+    '--paginate',
+    '--slurp',
+    '-f',
+    `query=${THREADS}`,
+    '-f',
+    `owner=${owner}`,
+    '-f',
+    `name=${name}`,
+    '-F',
+    `number=${pr.number}`,
+  ];
+  const pages = json('gh', args).map((page) => page.data);
+  const open = pages
+    .flatMap(({ repository }) => repository.pullRequest.reviewThreads.nodes)
+    .filter((thread) => !thread.isResolved)
+    .flatMap((thread) => thread.comments.nodes)
+    .concat(pages[0].repository.pullRequest.comments.nodes)
+    .map((comment) => ({ ...comment, author: comment.author?.login }));
+  const checks = pr.statusCheckRollup ?? [];
+  const ci = !checks.length
+    ? null
+    : checks.some((check) => FAILED.includes(check.conclusion || check.state))
+      ? 'failed'
+      : checks.some((check) =>
+            check.status
+              ? check.status !== 'COMPLETED'
+              : check.state === 'PENDING' || check.state === 'EXPECTED',
+          )
+        ? 'running'
+        : 'passed';
+  return {
+    state: pr.state.toLowerCase(),
+    conflicts: pr.mergeable === 'CONFLICTING',
+    ci,
+    unanswered: unansweredIds(open, pages[0].viewer.login),
+  };
+}
+
+function gitlab() {
+  const mr = json('glab', ['mr', 'view', branch, '-F', 'json']);
+  const discussions = run('glab', [
+    'api',
+    '--paginate',
+    '--output',
+    'ndjson',
+    `projects/${mr.project_id}/merge_requests/${mr.iid}/discussions?per_page=100`,
+  ])
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+  const open = discussions
+    .map((discussion) => discussion.notes.filter((note) => !note.system))
+    .filter(
+      (notes) =>
+        notes.length &&
+        !(
+          notes.some((note) => note.resolvable) &&
+          notes.every((note) => !note.resolvable || note.resolved)
+        ),
+    )
+    .map((notes) => notes.at(-1))
+    .map((note) => ({ ...note, author: note.author?.username }));
+  const pipeline = mr.head_pipeline?.sha === mr.sha ? mr.head_pipeline.status : null;
+  const ci = !pipeline
+    ? null
+    : FAILED.includes(pipeline)
+      ? 'failed'
+      : ['success', 'skipped', 'manual'].includes(pipeline)
+        ? 'passed'
+        : 'running';
+  const state = mr.state === 'opened' ? 'open' : mr.state === 'merged' ? 'merged' : 'closed';
+  const me = json('glab', ['api', 'user']).username;
+  return { state, conflicts: mr.has_conflicts === true, ci, unanswered: unansweredIds(open, me) };
+}
+
+const say = (line) => {
+  console.log(line);
+  process.exit(0);
+};
+const status = /github\.com/.test(run('git', ['remote', 'get-url', 'origin'])) ? github : gitlab;
+const started = Date.now();
+let seen = null;
+let errors = 0;
+for (;;) {
+  try {
+    const now = status();
+    errors = 0;
+    if (process.env.WATCH_DEBUG) console.error(JSON.stringify(now));
+    if (now.state !== 'open') say(now.state);
+    if (now.conflicts) say('conflicts');
+    if (now.ci === 'failed') say('failed');
+    const ids = now.unanswered.join(' ');
+    if (ids && (once || ids === seen)) say(`threads ${ids}`);
+    seen = ids;
+    const green = now.ci === 'passed' || (now.ci === null && Date.now() - started >= NO_CI_MS);
+    if (untilGreen && green && !ids) say('green');
+    if (once) say('none');
+  } catch (reason) {
+    if (once || ++errors >= MAX_ERRORS)
+      say(`error ${reason instanceof Error ? reason.message.split('\n')[0] : reason}`);
+  }
+  await new Promise((resolve) => setTimeout(resolve, EVERY_MS));
+}

package/template/__dot__rulesync/skills/ui-verify/SKILL.md.tpl

@@ -0,0 +1,120 @@
+---
+name: ui-verify
+targets: ['*']
+description: >
+  Verify a UI change in a real browser with the global `playwright-cli`: cheap checks first,
+  then four screenshots per changed screen read for spacing, overlap, cut text and contrast,
+  then the per-AC videos for the PR. Use after any change to a page, component, style or
+  player/operator flow, on "check it looks right", "verify the UI", "does it render", "take a
+  screenshot", "record a video", and to reproduce a UI bug before fixing it.
+claudecode:
+  context: fork
+  model: sonnet
+  effort: medium
+---
+
+# ui-verify ({{name}})
+
+Global `playwright-cli` (`npm i -g @playwright/cli` if missing), never a browser MCP: it costs a
+fraction of the tokens. Do not spawn subagents. Return text only. A subagent (`tester`, `builder`) does not
+invoke this skill, which forks one of its own: it reads this file and follows it itself.
+
+## Stack
+
+- Player app :3000, backoffice :3002, API :3001, unless the repo's rules name other ports (a
+  worktree slot, say). Ports held by another checkout: never kill it, ask.
+- Accounts: the seed's (`admin@oss.dev` / `password1234` after `pnpm db:seed`). Save a login once
+  with `state-save /tmp/ui-verify/<app>.json`, `state-load` it after.
+- Theme: switch with the app's own toggle in a video; for a still, set what the toggle sets
+  (a cookie or `localStorage`) with `eval`, then reload.
+
+## Cost ladder
+
+Deterministic checks first, reading pixels last. Write each check as an assertion with an
+expected value (`[data-testid=balance]` text matches `/\d+(\.\d+)? USDT/`) and stop at the
+first rung that answers it.
+
+1. **Shell.** The route serves: `curl -s -o /dev/null -w '%{http_code}' <url>`.
+2. **Browser, one value.** `eval` for existence, text, count, computed style; `console error`
+   and `requests` grepped for `4\d\d|5\d\d`; `find "<text>"` for one node.
+3. **Structure.** `snapshot <target>` scoped to the changed component; a full-page `snapshot`
+   only with `--depth` or `--filename` + `grep`.
+4. **Pixels.** The screenshot review below.
+
+Batch commands in one bash call. Output over ~50 lines goes to `/tmp/ui-verify/` and gets
+`grep`, not read whole. One named session per run (`-s=<name>`), `close` at the end.
+
+## Screenshot review
+
+Screenshots are for you, videos for the reviewer: nobody reads a video back, so layout defects
+are caught here. Every changed screen, after the checks pass and before the videos. Four shots:
+mobile and desktop, light and dark (backoffice: desktop only).
+
+- Sizes: never shrink a shot, halving it halves every padding you judge. Mobile 390x844 at 2x
+  device pixels (780x1688), desktop 1440x900 at 1x: both under the 2000 px per-image cap a
+  session with over 20 images gets, about 1.7k tokens each.
+- Tall screens: one shot per viewport height (`eval "() => scrollTo(0, <y>)"`, then shoot),
+  never `--full-page`, which downscales a long page until its text is unreadable.
+- Before reading, run `layout-check.js` in each of the four. It lists overlapping, clipped,
+  truncated and off-screen text and a page that scrolls sideways; every line it returns is a
+  check to settle on the shot. `sh .claude/skills/ui-verify/layout-check.check.sh` is its self-test.
+- Read each shot for: spacing consistent with its neighbours, alignment, overlapping or cut text,
+  anything off-screen or out of its container, contrast in dark, and the ticket's designs. Every
+  shot gets a report line, a clean one too. A defect is a FAIL with the png path; it gets fixed
+  and shot again.
+
+```bash
+mkdir -p /tmp/ui-verify
+echo '{"browser":{"contextOptions":{"deviceScaleFactor":2}}}' > /tmp/ui-verify/2x.json
+playwright-cli -s=m open <url> --config=/tmp/ui-verify/2x.json && playwright-cli -s=m resize 390 844
+playwright-cli -s=m eval "$(cat .claude/skills/ui-verify/layout-check.js)"
+playwright-cli -s=m screenshot --hires --filename=/tmp/ui-verify/<screen>-mobile-dark.png
+# switch theme, reload, repeat as -light; desktop in its own session:
+# no --config, resize 1440 900, no --hires
+```
+
+In the PR, after the Videos section, collapsed per screen (upload as in `docs/agents/forge.md`):
+
+```markdown
+<details><summary>Screenshots: <screen></summary>
+
+|         | Light                    | Dark                    |
+| ------- | ------------------------ | ----------------------- |
+| Mobile  | ![mobile light](upload)  | ![mobile dark](upload)  |
+| Desktop | ![desktop light](upload) | ![desktop dark](upload) |
+
+</details>
+```
+
+## Video evidence
+
+Last, once, on the final commit after the tests are green and review is clean (`ship` step 4b):
+a clip taken earlier is thrown away by the next fix round. One clip per acceptance criterion
+(`docs/standards/testing.md`), recorded on the local stack. The one early clip is a fix's
+"before", taken when the bug is reproduced; its "after" twin comes here. Never read a video back.
+
+ACs a spec drives come first: every spec that drives one, new or existing, in one run with video
+on (the repo's record switch, or `test.use({ video: 'on' })`); copy each
+`test-results/<test>/video.webm` to `<ac>-<slug>-{desktop,mobile}.webm`. Only an AC no spec
+drives gets `playwright-cli`, one at mobile size (`resize 390 844`) and one at desktop
+(`resize 1440 900`), each switching theme with the app's toggle partway through:
+
+```bash
+playwright-cli -s=v video-start /tmp/ui-verify/ac1-<slug>-mobile.webm
+playwright-cli -s=v video-show-actions
+playwright-cli -s=v video-chapter "AC1: <criterion in a few words>" --duration=1500
+# drive the AC ... toggle the theme ... until its outcome is on screen
+playwright-cli -s=v video-stop
+```
+
+## Report
+
+One line per check: `PASS|FAIL - <check> - rung <n> - expected <x>, got <y> - <artifact path>`,
+plus the failure detail for each FAIL. A pixel claim neither a measurement nor the shot can
+settle is `UNSURE - <check> - <what is ambiguous> - <png path>`, never a guess. Return every shot
+and clip path.
+
+## Bugs
+
+Reproduce here first, as close to real use as possible, then fix, then rerun the same checks.
+A fix without a before and after run is unverified.

package/template/__dot__rulesync/skills/ui-verify/layout-check.check.sh

@@ -0,0 +1,58 @@
+#!/bin/sh
+# Self-check for layout-check.js: the page below plants 5 defects next to 5 look-alikes that are fine.
+set -e
+dir=$(dirname "$0")
+fixture=$(cat <<'HTML'
+<!doctype html>
+<html>
+  <body style="margin: 0; font: 16px sans-serif; width: 390px">
+    <p>
+      Clean wrapped paragraph that wraps across lines with a <a href="#">link inside</a> and more
+      text after it.
+    </p>
+    <div data-testid="overlap-card" style="position: relative; height: 40px">
+      <span>Balance</span><span style="position: absolute; left: 20px; top: 0">USDT 12.50</span>
+    </div>
+    <div data-testid="clip-box" style="height: 18px; overflow: hidden">
+      <p style="margin: 0">Line one<br />Line two cut off</p>
+    </div>
+    <div
+      data-testid="ellipsis"
+      style="width: 80px; overflow: hidden; white-space: nowrap; text-overflow: ellipsis"
+    >
+      A very long game title
+    </div>
+    <span style="position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0)"
+      >Screen reader only</span
+    >
+    <div style="overflow: hidden; width: 200px; white-space: nowrap">
+      <div style="display: inline-block; width: 200px">Slide one</div>
+      <div style="display: inline-block; width: 200px">Slide two parked</div>
+    </div>
+    <div data-testid="wide" style="white-space: nowrap">
+      This label is far too wide for a mobile viewport and runs out
+    </div>
+    <div style="overflow-x: auto; white-space: nowrap; width: 200px">
+      Scrollable chips row that is wider than its box on purpose
+    </div>
+    <p style="position: relative">Under the modal text</p>
+    <div style="position: fixed; top: 0; left: 0; width: 390px; height: 60px; background: #fff">
+      <p style="margin: 4px">Modal title over page text</p>
+    </div>
+  </body>
+</html>
+HTML
+)
+url="data:text/html;base64,$(printf '%s' "$fixture" | base64 | tr -d '\n')"
+playwright-cli -s=layout-check open "$url" >/dev/null 2>&1
+playwright-cli -s=layout-check resize 390 844 >/dev/null
+out=$(playwright-cli -s=layout-check eval "$(cat "$dir/layout-check.js")")
+playwright-cli -s=layout-check close >/dev/null
+for expected in PAGE-SCROLLS-X 'CLIPPED.*clip-box' 'TRUNCATED.*ellipsis' 'OFFSCREEN.*wide' 'OVERLAP.*overlap-card.*with.*overlap-card'; do
+  echo "$out" | grep -q "$expected" || { echo "FAIL: missing $expected"; echo "$out"; exit 1; }
+done
+# Findings never carry page text: a real screen can show player data.
+! echo "$out" | grep -qE 'Balance|USDT|Line two|game title|too wide' || { echo "FAIL: page text in findings"; echo "$out"; exit 1; }
+count=$(echo "$out" | grep -cE '^  "(PAGE|CLIPPED|TRUNCATED|OFFSCREEN|OVERLAP)')
+[ "$count" -eq 5 ] || { echo "FAIL: $count findings, expected 5"; echo "$out"; exit 1; }
+echo PASS

package/template/__dot__rulesync/skills/ui-verify/layout-check.js

@@ -0,0 +1,163 @@
+// Layout defects a screenshot read can miss: overlapping text, text cut by an
+// `overflow: hidden|clip` box, text sticking out of the viewport sideways.
+// Run: playwright-cli -s=v eval "$(cat .claude/skills/ui-verify/layout-check.js)"
+// Returns one line per finding; [] is clean. Findings are leads for the screenshot
+// review, not verdicts: a carousel peek or a deliberate ellipsis can show up here.
+// A finding names a selector and a position, never the text: a screen can show player data.
+// playwright-cli eval takes a bare function expression.
+// oxlint-disable-next-line no-unused-expressions
+() => {
+  const EDGE_PX = 1;
+  const OVERLAP_PX = 2;
+  const MAX_TEXTS = 800;
+  const MAX_FINDINGS = 40;
+
+  const describe = (el) => {
+    const tagged = el.closest('[data-testid]');
+    const testId = tagged ? `[data-testid="${tagged.getAttribute('data-testid')}"] ` : '';
+    const classes = [...el.classList]
+      .slice(0, 2)
+      .map((name) => `.${name}`)
+      .join('');
+    return `${testId}${el.tagName.toLowerCase()}${classes}`;
+  };
+  const clips = (style) => /hidden|clip/.test(style.overflowX + style.overflowY);
+  const scrolls = (style) => /auto|scroll/.test(style.overflowX + style.overflowY);
+  const overflowBy = (inner, outer) =>
+    [
+      ['top', outer.top - inner.top],
+      ['right', inner.right - outer.right],
+      ['bottom', inner.bottom - outer.bottom],
+      ['left', outer.left - inner.left],
+    ].filter(([, px]) => px > EDGE_PX);
+  const intersects = (a, b) =>
+    a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom;
+  const isOpaque = (el) => {
+    const style = getComputedStyle(el);
+    const alpha = style.backgroundColor.match(/[\d.]+/g)?.[3] ?? '1';
+    return (
+      style.backgroundImage !== 'none' ||
+      style.backdropFilter !== 'none' ||
+      (style.backgroundColor !== 'transparent' && Number(alpha) >= 0.5)
+    );
+  };
+  // A modal or sheet over the page puts an opaque layer between the two texts in the paint stack.
+  const isLayerBetween = (a, b, x, y) => {
+    const stack = document.elementsFromPoint(x, y);
+    const [upper, lower] = [stack.indexOf(a), stack.indexOf(b)].sort((p, q) => p - q);
+    if (upper < 0) {return false;}
+    const below = stack[lower];
+    return stack.slice(upper + 1, lower).some((el) => !el.contains(below) && isOpaque(el));
+  };
+
+  const findings = [];
+  const at = (r) =>
+    `at ${Math.round(r.left)},${Math.round(r.top)} ${Math.round(r.width)}x${Math.round(r.height)}`;
+  const report = (kind, el, box, detail) =>
+    findings.push(`${kind} - ${describe(el)} ${at(box)} - ${detail}`);
+
+  const texts = [];
+  const range = document.createRange();
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  for (let node = walker.nextNode(); node && texts.length < MAX_TEXTS; node = walker.nextNode()) {
+    const el = node.parentElement;
+    if (!node.textContent.trim() || !el || el.closest('script,style,noscript,template')) {continue;}
+    if (!el.checkVisibility({ opacityProperty: true, visibilityProperty: true })) {continue;}
+    range.selectNodeContents(node);
+    const lines = [...range.getClientRects()].filter((r) => r.width >= 1 && r.height >= 1);
+    if (!lines.length) {continue;}
+    const box = range.getBoundingClientRect();
+
+    let hiddenByDesign = false;
+    let clippedBy = null;
+    let insideScroller = false;
+    for (
+      let a = el, child = null;
+      a && a !== document.body && !insideScroller;
+      child = a, a = a.parentElement
+    ) {
+      const style = getComputedStyle(a);
+      const outer = a.getBoundingClientRect();
+      if (!clips(style)) {
+        insideScroller = scrolls(style);
+        continue;
+      }
+      // sr-only boxes and slides parked fully outside their track are meant to be unseen;
+      // a block only partly inside its clipper has lines cut off.
+      const shown = child ? child.getBoundingClientRect() : box;
+      if (outer.width <= 1 || outer.height <= 1 || !intersects(shown, outer)) {
+        hiddenByDesign = true;
+        break;
+      }
+      // Glyphs taller than a tight line-height poke past the box without any layout overflow.
+      const overflows =
+        a.scrollWidth > a.clientWidth + EDGE_PX || a.scrollHeight > a.clientHeight + EDGE_PX;
+      if (!clippedBy && overflows && overflowBy(box, outer).length) {clippedBy = { a, style, outer };}
+    }
+    if (hiddenByDesign) {continue;}
+
+    if (clippedBy) {
+      const edges = overflowBy(box, clippedBy.outer).map(
+        ([edge, px]) => `${edge} ${Math.round(px)}px`,
+      );
+      const isEllipsis =
+        clippedBy.style.textOverflow === 'ellipsis' || clippedBy.style.webkitLineClamp !== 'none';
+      const kind = isEllipsis ? 'TRUNCATED' : 'CLIPPED';
+      report(kind, el, box, `cut by ${describe(clippedBy.a)} at ${edges.join(', ')}`);
+    }
+    if (
+      !clippedBy &&
+      !insideScroller &&
+      (box.right > innerWidth + EDGE_PX || box.left < -EDGE_PX)
+    ) {
+      report(
+        'OFFSCREEN',
+        el,
+        box,
+        `x ${Math.round(box.left)}..${Math.round(box.right)}, viewport ${innerWidth}`,
+      );
+    }
+    // Only the part left visible can overlap anything.
+    const shownLines = clippedBy
+      ? lines
+          .map((r) => ({
+            left: Math.max(r.left, clippedBy.outer.left),
+            top: Math.max(r.top, clippedBy.outer.top),
+            right: Math.min(r.right, clippedBy.outer.right),
+            bottom: Math.min(r.bottom, clippedBy.outer.bottom),
+          }))
+          .filter((r) => r.right > r.left && r.bottom > r.top)
+      : lines;
+    texts.push({ el, box, lines: shownLines });
+  }
+
+  const overlapOf = (ra, rb) => {
+    const left = Math.max(ra.left, rb.left);
+    const top = Math.max(ra.top, rb.top);
+    const width = Math.min(ra.right, rb.right) - left;
+    const height = Math.min(ra.bottom, rb.bottom) - top;
+    return width > OVERLAP_PX && height > OVERLAP_PX
+      ? { x: left + width / 2, y: top + height / 2 }
+      : null;
+  };
+  // ponytail: O(n^2) over line boxes, fine under MAX_TEXTS; bucket by row if pages outgrow it.
+  for (let i = 0; i < texts.length; i++) {
+    for (let j = i + 1; j < texts.length; j++) {
+      const a = texts[i];
+      const b = texts[j];
+      const point = a.lines.flatMap((ra) => b.lines.map((rb) => overlapOf(ra, rb))).find(Boolean);
+      if (point && !isLayerBetween(a.el, b.el, point.x, point.y)) {
+        report('OVERLAP', a.el, a.box, `with ${describe(b.el)} ${at(b.box)}`);
+      }
+    }
+  }
+
+  const page = document.documentElement;
+  if (page.scrollWidth > page.clientWidth + EDGE_PX) {
+    findings.unshift(
+      `PAGE-SCROLLS-X - html - scrollWidth ${page.scrollWidth} > ${page.clientWidth}`,
+    );
+  }
+  const extra = findings.length - MAX_FINDINGS;
+  return extra > 0 ? [...findings.slice(0, MAX_FINDINGS), `+${extra} more`] : findings;
+}

package/template/__dot__rulesync/subagents/builder.md.tpl

@@ -0,0 +1,115 @@
+---
+targets:
+  - '*'
+name: builder
+description: >-
+  Senior fullstack engineer for a downstream igaming built on @openora/*. Configures
+  extensions.config.ts, authors overlay plugins, swaps vendor adapters (KYC,
+  PSP, notifications), and builds UI in apps/web, apps/backoffice, and packages/ui.
+  Use this agent to build or extend features in a consumer igaming repo that wraps
+  the OSS platform.
+claudecode:
+  model: sonnet
+  effort: high
+---
+
+You are a senior fullstack engineer building a downstream igaming on top of the OSS platform (`@openora/*`). You never modify OSS core - you extend it from the outside via the plugin system. The repo rule files (conventions, oss-boundaries, db-conventions) apply to everything you write.
+
+## Ground first
+
+1. `catalog-overview` (oss MCP) - what the platform already ships; don't rebuild it.
+2. `list-adapters` - which vendor seams exist to override (KYC, PSP, notifications, ...).
+3. Read `apps/api/src/extensions.config.ts` - everything active is registered there.
+4. Read `AGENTS.md` at the repo root - it is the canonical brief for this consumer repo.
+5. Library API in doubt (Next, React, Drizzle, Zod, `@openora/*`)? Check current docs via context7/web search - don't code from memory.
+
+## Local platform checkout
+
+`@openora/*` resolves to the published package by default. When the work depends on a core
+change that is not released yet, or when you are iterating against core, link the local
+checkout instead of waiting for a canary: `pnpm link:oss` (points at `{{ossDir}}`),
+`pnpm unlink:oss` to go back.
+
+Prefer linking whenever a core-side fix and a consumer-side fix are likely to bounce off each
+other. Waiting on a publish per round trip is the slow path.
+
+While linked:
+
+- The lockfile is hidden, so do NOT add, remove or change a dependency and do NOT run
+  `pnpm install`. Run `pnpm unlink:oss` first if you must.
+- Core source is not what you import - `dist` is. A core edit is invisible here until core is
+  rebuilt: `pnpm -F @openora/core build` in the checkout. For hot reload, run
+  `pnpm -F @openora/core watch` there once and leave it running.
+- Linking lets you CONSUME an unreleased core. To change core, link an OSS worktree instead
+  of the main checkout: `pnpm oss:worktree <branch> --link` (see Rules below).
+
+## Consumer repo structure
+
+```
+{{name}}/
+  apps/
+    api/                       # thin wrapper: createApp from '@openora/core/server'
+      src/extensions.config.ts # registers all plugins (OSS defaults + overrides)
+      src/extensions/          # overlay plugins
+        my-kyc/plugin.ts       # swaps KYC_ADAPTER
+        my-psp/plugin.ts       # swaps PSP_ADAPTER
+    web/                       # player app, consumes the API via @openora/core/react
+    backoffice/                # admin app
+  packages/ui/                 # {{scope}}/ui shared components
+```
+
+## Swap a vendor adapter
+
+1. `list-adapters` for the token and interface.
+2. Create `apps/api/src/extensions/<vendor>/plugin.ts`:
+
+   ```ts
+   import type { CoreTokenCatalog, Plugin } from '@openora/core/server';
+   import { KYC_ADAPTER } from '@openora/core/contracts';
+   import { MyKycAdapter } from './src/my-kyc-adapter.js';
+
+   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 - last registration of a DI token wins.
+
+## Add a feature route
+
+1. `list-routes` + `describe-module` to confirm it doesn't already exist.
+2. In a plugin: `ctx.routers.add('my-feature', myFeatureRouter)`.
+3. Zod schemas live in the plugin folder - never in `@openora/core/contracts`.
+
+## UI work
+
+The platform is headless - the frontends are this operator's own, consuming the API over HTTP via `@openora/core/react` (data hooks, auth, realtime transport, typed client). Follow the `frontend-conventions` rule (and `docs/standards/frontend.md` for the deep dive): feature modules under `src/modules/<m>/`, presentation-only components, logic in hooks, daisyUI + theme tokens, co-located `locales/`. Extend shared pages through the app's plugin layer (nav items, dashboard tiles, table columns) instead of forking them.
+
+## Escalate
+
+You start no subagents of your own. What you cannot settle yourself goes in your reply, and the orchestrator routes it:
+
+- Domain question (wagering calc, KYC threshold) -> a "Questions for expert" list; build what the answer does not change.
+- Bug or gap in OSS core -> fix it in an OSS worktree per "Changing OSS core" in the `oss-boundaries` rule; never copy core source into this repo.
+- Can't finish at all -> reply `Blocked:` on the first line and the reason.
+
+## Tests
+
+Your change ships with its tests in the same branch - never a separate test PR. You write the unit and integration tests for the plan's test cases at the tier `docs/standards/testing.md` names: pure logic gets a co-located `__tests__/` test, a route its API E2E (`apps/e2e/tests/api/<domain>/<scenario>.spec.ts`, happy + one hostile path). Never an in-process test that mocks the database or a sibling service. `tester` drives the running stack, attacks the change and adds the browser specs; you do not run a manual pass or record evidence.
+
+## Done means
+
+1. The repo's gate (`/check`: typecheck + lint + unit) passes on HEAD, and the specs you touched pass (`pnpm -F {{scope}}/e2e test <spec>`). A spec that fails: run it on the base commit too - failing there as well is pre-existing, say so; failing only here is yours to fix.
+2. Commit with the repo's commit style, staging only the files the work needs: no test output, videos, screenshots, logs, scratch scripts, unrelated formatting. `git status` is clean before you reply.
+3. Reply with what changed per plan item, the tests you added (one line each, tier and path), the gate command and the tail of its output from HEAD, then `Worktree: <absolute path>` and `Branch: <name>`. Never write "passed" without that output.
+
+## Rules
+
+- Never write to `node_modules/**` or the main linked `{{ossDir}}` checkout - the `guard-core` hook denies it; don't route around it with `sed` or shell redirection. A local patch to a published dependency is lost on reinstall and diverges from every other operator. If a change is only possible in core, make it in an OSS worktree (`pnpm oss:worktree <branch>`) under the OSS repo's own rules, per the `oss-boundaries` rule.
+- Never copy core module source into this repo - depend on the package.
+- `extensions.config.ts` is the single registry - no auto-discovery.
+- Commit on the ticket branch; never push - the orchestrator does.