@openora/create 0.4.1-canary.108 → 0.4.1-canary.110

package/template/__dot__rulesync/subagents/expert.md

@@ -2,52 +2,46 @@
 targets:
   - '*'
 name: expert
-description: iGaming domain expert scoped to a downstream igaming operator. Turns fuzzy product asks into concrete requirements and acceptance criteria for features specific to that igaming (promotions, VIP, jurisdiction rules, custom game feeds). Advisory only - no code. Escalate domain questions here before builder implements anything non-obvious.
+description: >-
+  iGaming domain expert scoped to a downstream igaming operator. Turns fuzzy
+  product asks into concrete requirements and acceptance criteria for features
+  specific to that igaming (promotions, VIP, jurisdiction rules, custom game
+  feeds). Advisory only - no code. Escalate domain questions here before
+  builder implements anything non-obvious.
 claudecode:
-  tools:
-    - Read
-    - Bash
-    - WebSearch
-    - WebFetch
-    - Agent
+  model: opus
 ---
 
-You are a senior iGaming product and domain expert advising a specific online igaming operator built on the OSS igaming platform. You know the industry end to end: player journeys, game mechanics, RGS, payments (PSP + crypto), KYC/AML, responsible gaming, licensing per jurisdiction, bonus/wagering mechanics, affiliates, and retention.
+You are a senior iGaming product and domain expert advising this operator: player journeys, game mechanics, RGS, payments (PSP + crypto), KYC/AML, responsible gaming, licensing per jurisdiction, bonus/wagering mechanics, affiliates, retention.
 
-You do NOT write code. You define what must be built, why, and how it must behave - then `builder` implements it.
+You do NOT write code. You define what must be built, why, and how it must behave; `builder` implements.
 
-## Grounding (do this first)
+## Ground first
 
-1. Run `catalog-overview` (MCP) to understand what the OSS platform already provides. Don't spec features that already exist.
-2. Run `list-adapters` to see which vendor ports exist. When a feature needs a third party, frame it as a swappable adapter, not a named vendor.
-3. Ask the operator (via the conversation) for their target jurisdiction(s) and license type before speccing anything compliance-related. Rules differ materially between MGA, UKGC, Curacao, and others.
+1. `catalog-overview` (oss MCP) - don't spec what the platform already provides.
+2. `list-adapters` - existing vendor ports; frame third-party needs as swappable adapters, never a named vendor in core logic.
+3. Ask the operator for target jurisdiction(s) and license type before speccing anything compliance-related - MGA, UKGC, Curacao and others differ materially.
 
 ## How you work
 
-- Translate asks into **requirements with explicit acceptance criteria** - user story + what "done" looks like in observable terms.
-- Always flag the **regulatory angle**: deposit/loss/wager limits, self-exclusion, KYC thresholds for withdrawals, geo-blocking, RTP/fairness disclosure, cooling-off periods. Easy for engineers to miss, expensive to retrofit.
-- When a claim depends on current regulation, verify with web search and cite the source. Do not rely on memory for compliance specifics.
-- Express every third-party need as a **swappable adapter behind a generic port**. Different operators use different vendors - never spec a named vendor into core logic.
-- Flag what is **operator-specific** (should live in their overlay plugin) vs what should be contributed back to OSS core as reusable.
+- Translate asks into requirements with explicit, observable acceptance criteria - user story + what "done" looks like.
+- Always flag the regulatory angle: deposit/loss/wager limits, self-exclusion, KYC thresholds for withdrawals, geo-blocking, RTP/fairness disclosure, cooling-off. Cheap to design in, expensive to retrofit.
+- When a claim depends on current regulation, verify with web search and cite the source - never from memory.
+- Express every third-party need as a swappable adapter behind a generic port - different operators use different vendors.
+- Flag what is operator-specific (their overlay) vs reusable (contribute upstream to OSS core).
 
-## Output format
+## Output per feature request
 
-For each feature request:
-
-1. **Scope** - operator-specific overlay vs. OSS core contribution. Justify.
-2. **Requirements** - user stories by domain, each with observable acceptance criteria.
-3. **Provider seams** - which adapter ports are involved; what the interface must cover.
-4. **Regulatory flags** - jurisdiction-specific constraints the engineer must not miss.
-5. **Handoff brief** - tight implementation-ready summary for `builder`, plus open product decisions that need operator input before building.
-
-## Escalation
-
-- Implementation question -> defer to `builder`.
-- Platform capability gap (feature doesn't exist at all in OSS) -> note it as a gap; recommend either building it as a plugin or contributing it upstream.
+1. **Scope** - overlay vs OSS-core contribution, justified.
+2. **Requirements** - user stories with observable acceptance criteria.
+3. **Provider seams** - adapter ports involved; what the interface must cover.
+4. **Regulatory flags** - jurisdiction-specific constraints.
+5. **Handoff brief** - implementation-ready summary for `builder` + open product decisions needing operator input.
 
 ## Rules
 
-- No code, no file edits. Specs and findings only.
-- Be igaming-specific. Generic SaaS advice is not useful here.
+- No code, no file edits - specs and findings only.
+- Be igaming-specific; generic SaaS advice is useless here.
 - Cite regulatory sources when compliance is in scope.
-- Ask the operator clarifying questions rather than assuming jurisdiction, player demographics, or business model.
+- Ask rather than assume jurisdiction, demographics, or business model.
+- Implementation questions defer to `builder`; platform capability gaps are noted as plugin-vs-upstream recommendations.

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

@@ -0,0 +1,61 @@
+---
+targets:
+  - '*'
+name: qa
+description: >-
+  QA engineer for a downstream igaming built on @openora/*. Writes and runs
+  Playwright E2E tests against the operator's local stack. Uses Chrome DevTools
+  MCP for network/console/DOM inspection. Escalates domain questions to expert
+  and confirmed bugs to builder. Distinguishes bugs in OSS core (upstream issue)
+  from bugs in operator overlays (local fix).
+claudecode:
+  model: sonnet
+---
+
+You write Playwright E2E tests, debug failures with Chrome DevTools, and triage bugs - OSS core (report upstream) vs operator overlay (fix locally).
+
+## Ground first
+
+1. `list-routes` (oss MCP) - full API surface (platform + operator routes).
+2. `catalog-overview` - active modules and expected behavior.
+3. `apps/api/src/extensions.config.ts` - active overlays and adapters.
+
+## Local stack
+
+The platform is headless (API + modules); the player app and backoffice are this operator's own frontends. API :3001, player app :3000, backoffice :3002. Seed credentials (after `pnpm db:seed`): `admin@oss.dev` / `password123`. Confirm ports and which UIs exist with the operator if they differ - an api-only consumer has no browser specs. If the stack isn't running, say so with the start command.
+
+## Tests
+
+Tier per `conventions`: a route -> API E2E in `apps/e2e/tests/api/**` (happy + one hostile path); a screen -> browser spec; pure logic -> unit. An in-process test that mocks the database or a service is a defect - replace it with the API E2E.
+
+E2E specs live in `apps/e2e/tests/<app>/<domain>/<scenario>.spec.ts` (Playwright projects `api`, `web` and `backoffice`) and follow the `e2e-conventions` rule: dual-mode via `USE_MOCKS` (mocked run blocks merge; real run needs the stack up), import `test`/`expect` from `fixtures.ts` (never `@playwright/test`), typed fixtures in `mocks/`, `data-testid` selectors, functional page objects. If `apps/e2e` is missing, scaffold it: `mkdir -p apps/e2e && cd apps/e2e && pnpm init && pnpm add -D @playwright/test && npx playwright install chromium`.
+
+Debug and verify with the **Playwright CLI** first (`pnpm -F {{scope}}/e2e test <spec>`, `npx playwright screenshot <url> <file>`, or a throwaway spec with `page.screenshot`) - it costs a fraction of the tokens a browser MCP does. Reach for the **chrome-devtools** MCP only for a live console or network read the CLI cannot give you: navigate, reproduce the action, read console messages (JS errors, unhandled rejections), inspect network requests (status codes, response shapes), evaluate a script for DOM state, screenshot the failure.
+
+**Evidence is mandatory.** Every pass ends with a screenshot per changed or broken screen, saved under `apps/e2e/test-results/evidence/<scenario>.png`, and the file paths listed in the report - a human confirms the change by looking, not by reading a description. API-only changes attach the request/response trace instead.
+
+## Triage - the key question
+
+Is the bug in OSS core or the operator's overlay?
+
+- Fails in a fresh consumer scaffold / with no overlays active -> OSS core -> report upstream.
+- Fails only with this operator's plugins/adapters -> `builder`.
+- Technically consistent but violates igaming rules -> `expert`.
+
+Severity: P0 blocks money/auth/game loop (immediate -> `builder`); P1 wrong business logic (wrong balance, bad geo-block - confirm via `expert`, then `builder`); P2 broken UI / wrong API shape (escalate if blocking); P3 cosmetic (document, don't block).
+
+## Core flows (priority order)
+
+1. Auth: register, login, logout, bad credentials.
+2. Wallet: balance, deposit, withdraw, history.
+3. Gaming: catalogue, start/end round, balance deduction.
+4. Bonus: claim, wagering progress.
+5. Compliance: deposit limits, geo-block.
+6. Backoffice: admin login, player list, KYC status.
+7. Each active operator overlay.
+
+## Rules
+
+- Never modify platform or overlay code to make a test pass - report and escalate.
+- Assert on user-visible outcomes, not component internals.
+- Don't commit unless asked.

package/template/__dot__rulesync/subagents/{quality-reviewer.md → quality-reviewer.md.tpl}

@@ -12,19 +12,31 @@ claudecode:
 
 You are a senior code-quality reviewer for this consumer igaming repo (built on `@openora/*` OSS core). One pass over the changed files, several lenses. You are NOT the implementer - findings only, no changes.
 
+Stance: assume the change is BROKEN until you trace it working - review to falsify, not to confirm. Green gates, comments, and commit messages prove nothing.
+
 ## Grounding
 
-- Read `.claude/rules/conventions.md` IN FULL, and `docs/standards/frontend.md` IN FULL when the diff touches a UI app or the shared UI package (skip if this repo deleted that file as headless) - enforce all of it, the lenses below are high-signal reminders, not the boundary of the review.
-- For import/extension questions, `.claude/rules/oss-boundaries.md`; for overlay tables, `docs/standards/database.md`.
+- Read `.claude/rules/conventions.md` IN FULL, and `.claude/rules/frontend-conventions.md` IN FULL (and `docs/standards/frontend.md` for the deep dive) when the diff touches `apps/web`, `apps/backoffice`, or `packages/ui` (skip if this repo deleted those as headless) - enforce all of it, the lenses below are high-signal reminders, not the boundary of the review.
+- For import/extension questions, `.claude/rules/oss-boundaries.md`; for overlay tables, `.claude/rules/db-conventions.md` and `docs/standards/database.md` for the deep dive.
 - Where no repo rule covers a problem, judge by established industry practice (algorithmic complexity, DB query patterns, transaction scope, React render behavior, error-handling hygiene) and name the principle in the finding.
 - Library API in doubt (Next, React, Drizzle, Zod, `@openora/*`)? Check current docs via context7/web search - never claim from memory.
 
 ## Scope
 
-The orchestrator passes you the base ref and changed-file list - do not re-scope the diff. Read only the changed files plus the immediate callees a finding depends on. If no file list was passed: `git diff origin/dev...HEAD --name-only`.
+The orchestrator passes you the base ref and changed-file list - do not re-scope the diff. Read the changed files, the immediate callees a finding depends on, and every caller `git grep -w` finds for a changed symbol or table. If no file list was passed: `git diff origin/{{mrTarget}}...HEAD --name-only`.
+
+## Request trace
+
+Follow §3c of the `review` skill: walk the seven hops for each changed entry point, and check the blast radius: `git grep -w` each changed export, table symbol, and SQL table name across `*.ts`, `*.tsx`, `*.sql`, and open every caller found, not only the immediate callee; a caller that no longer holds is a `[BLOCK]`. Report one `TRACE:` line per entry point before the findings.
 
 ## Lenses
 
+### Correctness (first - the change must actually work)
+
+- [ ] Trace each changed behavior end-to-end with concrete inputs - happy path plus at least one hostile one (empty/`''`/`0`, error, unauthorized, repeat call) - and confirm the outcome matches the stated intent/AC.
+- [ ] Called APIs behave as the code assumes - open the callee or check current docs; watch falsy-vs-nullish coercions, off-by-default options, unawaited promises, swallowed rejections.
+- [ ] Failure mid-flow leaves consistent state (throw between two writes, partial batch); cache/query invalidation matches every mutation the change introduces.
+
 ### OSS boundaries & extension
 
 - [ ] No edits to `@openora/*` core or `node_modules`; extension only via `extensions.config.ts`, overlay plugins, adapters.

package/template/__dot__rulesync/subagents/{security-reviewer.md → security-reviewer.md.tpl}

@@ -12,9 +12,15 @@ claudecode:
 
 You are a security reviewer for a real-money igaming consumer repo built on `@openora/*`. Core money/auth logic lives upstream in the platform; you review what the OVERLAY adds: custom routes, adapter swaps, config, and the frontend. Findings only, no changes.
 
+Stance: assume every protection in the diff is broken or bypassable until you trace the path that stops the attack - review to falsify, not to confirm the author's intent.
+
 ## Grounding
 
-If the orchestrator passed a base ref + changed-file list, use them - do not re-scope the diff. Otherwise: `git diff origin/dev...HEAD --name-only`. Read each changed file plus the immediate callees a finding depends on. Prioritize overlay plugins/routes, adapter implementations (KYC, PSP, notifications), auth/session touchpoints, and anything reading env/secrets.
+If the orchestrator passed a base ref + changed-file list, use them - do not re-scope the diff. Otherwise: `git diff origin/{{mrTarget}}...HEAD --name-only`. Read each changed file, the immediate callees a finding depends on, and every caller `git grep -w` finds for a changed symbol or table. Prioritize overlay plugins/routes, adapter implementations (KYC, PSP, notifications), auth/session touchpoints, and anything reading env/secrets.
+
+## Request trace
+
+Follow §3c of the `review` skill: walk the seven hops for each changed entry point, and check the blast radius: `git grep -w` each changed export, table symbol, and SQL table name across `*.ts`, `*.tsx`, `*.sql`, and open every caller found, not only the immediate callee; a caller that no longer holds is a `[BLOCK]`. Report one `TRACE:` line per entry point before the findings.
 
 ## Checklist
 

package/template/__dot__rulesync/sync.json.tpl

@@ -0,0 +1,21 @@
+{
+  "vars": {
+    "name": "{{name}}",
+    "scope": "{{scope}}",
+    "trackerKey": "{{trackerKey}}",
+    "jiraSite": "{{jiraSite}}",
+    "jiraCloudId": "{{jiraCloudId}}",
+    "wikiSpace": "{{wikiSpace}}",
+    "teamChannel": "{{teamChannel}}",
+    "gitRemotePath": "{{gitRemotePath}}",
+    "ossDir": "{{ossDir}}",
+    "ossFromRoot": "{{ossFromRoot}}",
+    "mrTarget": "{{mrTarget}}"
+  },
+  "consumerOwned": [
+    ".rulesync/rules/overview.md",
+    ".rulesync/mcp.json",
+    ".rulesync/sync.json",
+    "docs/agents/forge.md"
+  ]
+}

package/template/docs/agents/forge.md.tpl

@@ -0,0 +1,48 @@
+# Code forge: GitHub
+
+Code review for `{{gitRemotePath}}` happens on GitHub pull requests, driven by the [`gh`](https://cli.github.com) CLI. Every skill that opens, reads, or comments on a pull request reads this file instead of hardcoding commands, so a repo on a different forge rewrites this one file and the skills keep working.
+
+Swapping forge: keep the headings below and replace the commands. For GitLab that is `glab`, "merge request" for "pull request", `glab mr create/view/diff/note`, and `glab api "projects/<path-with-%2F>/merge_requests/<n>/discussions"` with a `position` object for inline comments.
+
+## Coordinates
+
+- Repo: `{{gitRemotePath}}`. CLI: `gh` (authenticate once with `gh auth login`).
+- Noun: pull request, "PR" for short. The default target branch is `{{mrTarget}}`.
+
+## Where a change lands
+
+- Topic branch (`feat/*`, `fix/*`, `{{trackerKey}}-*`) -> `{{mrTarget}}`.
+- A repo that promotes through environment branches adds them here (for example `{{mrTarget}}` -> `stage` -> `prod`) and never opens a PR straight from a topic branch to the last one.
+- If the current branch is not listed, target `{{mrTarget}}`.
+
+## Open a pull request
+
+```
+gh pr create --base <target> --head <current> --title "<type>: <summary>" --body "<body>"
+```
+
+Reuse an open PR for the same head -> base instead of opening a duplicate: `gh pr list --head <current> --base <target>`. Never delete a long-lived branch on merge.
+
+## Read a pull request
+
+- Intent and discussion: `gh pr view <n> --comments`
+- Patch: `gh pr diff <n>`
+- Unresolved threads: `gh api "repos/{{gitRemotePath}}/pulls/<n>/comments"`
+- CI: `gh pr checks <n>`
+
+## Inline review comments
+
+Anchor each comment to a line of the diff on the head commit:
+
+```
+gh api "repos/{{gitRemotePath}}/pulls/<n>/comments" \
+  -f body="<comment>" -f commit_id="<head-sha>" -f path="<file>" -F line=<new-line> -f side=RIGHT
+```
+
+Take `<head-sha>` from `gh pr view <n> --json headRefOid`. Anchor on the NEW-file line of an added line. Verify the response carries a non-null `line`; if it came back as a plain issue comment, delete it and retry rather than leaving an unanchored note. Post the verdict itself as one summary comment: `gh pr comment <n> --body "<one sentence>"`.
+
+## Rules
+
+- Never push without an explicit per-action confirmation from the user.
+- Never merge a pull request unless the user asks for that exact action.
+- Never resolve someone else's review thread.

package/template/docs/agents/issue-tracker.md.tpl

@@ -0,0 +1,41 @@
+# Issue tracker: Jira (project `{{trackerKey}}`) + Confluence + Slack
+
+Work for this operator is tracked in Jira project `{{trackerKey}}` on `{{jiraSite}}`. Requirements and reasoning live in Confluence space `{{wikiSpace}}`. Decisions that never made it into a ticket live in Slack `{{teamChannel}}`. Code review happens on `{{gitRemotePath}}` - see `docs/agents/forge.md`.
+
+Every skill that says "fetch the relevant ticket" reads this file.
+
+## Keys and where they appear
+
+- Ticket key: `{{trackerKey}}-<n>`. `{{trackerKey}}-0` means "no ticket" (chores).
+- Branch: `<type>/{{trackerKey}}-<n>/<slug>`. MR title: conventional commit subject; MR description ends with `Closes {{trackerKey}}-<n>`.
+- Resolve the key from, in order: the argument the user gave, the MR description, the MR title, the branch name, commit subjects.
+
+## What "read the ticket" means
+
+A ticket is read when ALL of this has been seen - never from the description alone:
+
+1. Description and acceptance criteria (task items render as `- [ ]` / `- [x]`).
+2. Every comment, with author and date - decisions and scope changes hide there.
+3. Every attachment and every inline image, downloaded and viewed as pixels. Filenames, thumbnails, `blob:` links and metadata prove nothing.
+4. Parent epic and linked issues named by the AC.
+5. Every Confluence page the ticket links - its body, its images, its inline and footer comments. The AC are the spec; the page behind them is the reasoning.
+6. A Slack thread, only when the ticket or MR says the design or decision lives there ("shared in chat", a Slack link). Optional otherwise.
+
+How:
+
+- With the `atlassian-read` skill installed: `python3 ~/.claude/skills/atlassian-read/scripts/read.py issue {{trackerKey}}-<n>` then `page <id>` for each linked page. It downloads everything and prints a manifest mapping each image to the comment it came from.
+- Without it, REST with an Atlassian API token: Jira `GET /rest/api/3/issue/{{trackerKey}}-<n>?fields=summary,status,description,attachment,comment,issuelinks,parent`, attachments `GET /rest/api/3/attachment/content/<id>`; Confluence `GET /wiki/api/v2/pages/<id>?body-format=atlas_doc_format`, `/attachments`, `/footer-comments`, `/inline-comments`, download `/wiki<downloadLink>`. Bodies are ADF: walk `text` nodes for prose and `media`/`mediaInline` nodes for images (`attrs.alt` is the Jira attachment filename; on Confluence `attrs.id` is the attachment `fileId`).
+- The Atlassian MCP is fine for search, text and writes, but it returns no image bytes - it is never sufficient on its own when attachments exist.
+- Slack: the `slack-reader` agent when available, else the Slack MCP, scoped to the channel and thread named.
+
+Credentials are personal: `CONFLUENCE_EMAIL` / `CONFLUENCE_TOKEN` (an Atlassian API token) from a local, untracked env file. Never commit them, never echo them, never store curl flags holding them in a shell variable.
+
+## When a skill says "fetch the relevant ticket"
+
+Run the protocol above and distill: goal in one line, AC quoted as bullets, decisions from comments (who, when), design references (which screenshot shows what), out-of-scope lines. Report "no ticket" when no key resolves and "no access" when a fetch fails - never fall back silently, never invent AC.
+
+## Writing
+
+- Never comment on, transition, or edit a Jira issue or Confluence page unless the user asks for that exact write. Reading authorizes nothing.
+- Review comments go through `review --post`, draft-and-confirm, using the commands in `docs/agents/forge.md`.
+- Slack: draft only, never send.

package/template/docs/standards/database.md

@@ -67,7 +67,7 @@ await db.select().from(wallet).where(inArray(wallet.playerId, ids));
 ```ts
 await db.transaction(async (t) => {
   if (await ledgerExists(t, idempotencyKey)) return; // guard, not just a key
-  await insertLedger(t, { idempotencyKey, amountCents });
+  await insertLedger(t, { idempotencyKey, amount, currency });
 });
 ```
 

package/template/docs/standards/enforcement.md

@@ -3,8 +3,8 @@
 Read this before working around a failing gate or adding a lint rule.
 
 - `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.
+  In repos that ship `pnpm check:boundaries` (dependency-cruiser), that 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.

package/template/package.json.tpl

@@ -8,13 +8,17 @@
     "build": "turbo run build",
     "check:types": "turbo run check:types",
     "check:lint": "oxlint .",
+    "test:unit": "turbo run test:unit",
+    "verify": "turbo run check:types check:lint test:unit",
     "gen:agents": "rulesync generate",
-    "prepare": "rulesync generate",
+    "sync:agents": "node tools/sync-agents.mjs",
+    "prepare": "node tools/sync-agents.mjs && rulesync generate",
     "db:migrate": "pnpm -F @{{name}}/api exec openora-migrate",
     "db:seed": "pnpm -F @{{name}}/api db:seed",
     "gen": "turbo gen"
   },
   "devDependencies": {
+    "@openora/create": "{{coreVersion}}",
     "@openora/mcp": "latest",
     "@turbo/gen": "2.9.14",
     "@types/node": "25.9.0",

package/template/tools/sync-agents.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// Render the template-owned agent files from `@openora/create`'s consumer template.
+//
+// Source of truth: node_modules/@openora/create/template at the pinned @openora/* version
+// (with `pnpm link:oss`, ../openora/packages/create-openora's own tools/templates/consumer).
+// Runs on `pnpm install` via `prepare`, so these files are generated artifacts: they are
+// listed in the managed .gitignore block below and never committed. Only this repo's own
+// rules and skills - and the `consumerOwned` overrides in .rulesync/sync.json - are tracked.
+//
+// To change a synced file, edit openora's tools/templates/consumer and take the next bump.
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, sep } from 'node:path';
+
+const ROOT = process.cwd();
+const SYNCED_ROOTS = ['.rulesync/', 'docs/standards/', 'docs/agents/', 'tools/sync-agents.mjs'];
+// This script bootstraps `prepare`, so it must stay tracked: ignoring it would leave a
+// fresh clone with no way to run the install that would have rendered it.
+// Tracked on purpose: `prepare` runs the script, and the Claude hooks in .claude/settings.json
+// import _shared.mjs, so both must exist in a fresh clone before the first install.
+const NEVER_IGNORED = new Set(['tools/sync-agents.mjs', '.rulesync/hooks/_shared.mjs']);
+const SKIPPED_BASENAMES = new Set();
+
+const die = (message) => {
+  console.error(`sync:agents - ${message}`);
+  process.exit(1);
+};
+
+const config = (() => {
+  const path = join(ROOT, '.rulesync/sync.json');
+  if (!existsSync(path)) {
+    die(`${path} is missing - it holds this repo's template variables and consumerOwned list.`);
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (err) {
+    return die(`${path} is not valid JSON: ${err.message}`);
+  }
+})();
+const vars = config.vars ?? {};
+const consumerOwned = new Set(config.consumerOwned ?? []);
+
+// The published package ships `template/`; a linked source checkout (pnpm link:oss, CI's
+// unbuilt clone) only has the source at tools/templates/consumer - read that directly.
+const templateRoot = (() => {
+  let pkgDir;
+  try {
+    pkgDir = dirname(createRequire(join(ROOT, '/')).resolve('@openora/create/package.json'));
+  } catch {
+    return die('@openora/create is not installed - add it as a devDependency and reinstall.');
+  }
+  const candidates = [
+    join(pkgDir, 'template'),
+    join(pkgDir, '..', '..', 'tools', 'templates', 'consumer'),
+  ];
+  const found = candidates.find((dir) => existsSync(dir));
+  if (!found) {
+    return die(`consumer template not found at ${candidates.join(' or ')}`);
+  }
+  return found;
+})();
+
+const walk = (dir) =>
+  readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry);
+    return statSync(full).isDirectory() ? walk(full) : [full];
+  });
+
+const undot = (segment) => (segment.startsWith('__dot__') ? `.${segment.slice(7)}` : segment);
+
+const gitTracked = (paths) => {
+  try {
+    return execFileSync('git', ['ls-files', '-z', '--', ...paths], {
+      cwd: ROOT,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+      .split('\0')
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+};
+
+const substitute = (content) =>
+  content.replace(/\{\{(\w+)\}\}/g, (match, key) => vars[key] ?? match);
+
+const render = (file) => {
+  const rel = relative(templateRoot, file).split(sep).map(undot).join('/');
+  const isTpl = rel.endsWith('.tpl');
+  const raw = readFileSync(file, 'utf8');
+  return { path: isTpl ? rel.slice(0, -4) : rel, content: isTpl ? substitute(raw) : raw };
+};
+
+const rendered = walk(templateRoot)
+  .filter((file) => !SKIPPED_BASENAMES.has(file.split(sep).at(-1)))
+  .map(render)
+  .filter(({ path }) => SYNCED_ROOTS.some((root) => path.startsWith(root)))
+  .filter(({ path }) => !consumerOwned.has(path));
+
+// A new template variable must not brick `pnpm install` (which is also how the bump MR that
+// would add it gets built) - leave the placeholder in place and say what to add.
+const unresolved = rendered.filter(({ content }) => /\{\{\w+\}\}/.test(content));
+if (unresolved.length > 0) {
+  console.warn(
+    'sync:agents - unresolved template variables, add them to .rulesync/sync.json vars:',
+  );
+  for (const { path, content } of unresolved) {
+    console.warn(`  ${path}: ${[...new Set(content.match(/\{\{\w+\}\}/g))].join(' ')}`);
+  }
+}
+
+// Tracking a path is how this repo says "mine": .gitignore does not apply to it, so writing
+// would replace the committed content and leave a permanently dirty file. Skip those and
+// name them - opting one into being generated is a deliberate `git rm --cached`.
+const trackedPaths = new Set(gitTracked(rendered.map(({ path }) => path)));
+const owned = rendered.filter(({ path }) => trackedPaths.has(path) && !NEVER_IGNORED.has(path));
+
+for (const { path, content } of rendered) {
+  if (trackedPaths.has(path) && !NEVER_IGNORED.has(path)) {
+    continue;
+  }
+  const target = join(ROOT, path);
+  mkdirSync(dirname(target), { recursive: true });
+  if (!existsSync(target) || readFileSync(target, 'utf8') !== content) {
+    writeFileSync(target, content);
+  }
+}
+
+// Git must ignore exactly what this script writes, so a template that gains or loses a
+// file cannot leave an untracked stray behind. The block is rewritten in place; anything
+// outside the markers is left alone.
+const BEGIN = '# BEGIN synced-agents (generated by tools/sync-agents.mjs - do not edit)';
+const END = '# END synced-agents';
+const gitignore = join(ROOT, '.gitignore');
+// A tracked path is never ignored by git anyway - listing it would only mislead.
+const ignored = rendered.filter(({ path }) => !NEVER_IGNORED.has(path) && !trackedPaths.has(path));
+const block = [BEGIN, ...ignored.map(({ path }) => `/${path}`).sort(), END].join('\n');
+const current = existsSync(gitignore) ? readFileSync(gitignore, 'utf8') : '';
+const start = current.indexOf(BEGIN);
+// Search for END after BEGIN: a stray END earlier in the file (hand-edit, bad merge) would
+// otherwise splice at a negative offset and duplicate the whole block.
+const end = start === -1 ? -1 : current.indexOf(END, start + BEGIN.length);
+if (start !== -1 && end === -1) {
+  die(`${gitignore} has a ${BEGIN} marker with no matching ${END} - repair or delete the block.`);
+}
+const updated =
+  start === -1
+    ? `${current.trimEnd()}\n\n${block}\n`.trimStart()
+    : current.slice(0, start) + block + current.slice(end + END.length);
+if (updated !== current) {
+  writeFileSync(gitignore, updated);
+}
+
+console.log(`sync:agents - ${rendered.length - owned.length} template-owned file(s) rendered.`);
+if (owned.length > 0) {
+  console.warn(
+    `  ${owned.length} kept as-is because this repo tracks them: ${owned.map(({ path }) => path).join(', ')}\n` +
+      `  To let the template own one, untrack it: git rm --cached <path>`,
+  );
+}

package/template/__dot__rulesync/commands/doctor.md

@@ -1,16 +0,0 @@
----
-targets:
-  - '*'
-description: Diagnose the local dev environment - linked ../oss, node, postgres, ports, caches. Read-only; reports findings + the fix command for each.
----
-
-Run these checks and report a pass/fail line per item with the fix command for failures. Read-only - never apply fixes without being asked.
-
-1. **Node version**: `node -v` matches `.nvmrc` (26). Fix: `nvm use`.
-2. **Core resolves**: `node --input-type=module -e "import {createRequire} from 'node:module'; console.log(createRequire(process.cwd()+'/').resolve('@openora/core/react'))"` prints a path. Fix: `pnpm install`.
-3. **Database**: postgres reachable on :5432 (`nc -z localhost 5432`). Fix: `dev:infra` MCP tool (server `oss`) or the compose stack.
-4. **Services**: ports 3001 (api), 3000 (web), 3002 (backoffice) - report which are up. Fix: `pnpm dev`.
-5. **Stale bundler cache**: if a build error persists after a fix, `rm -rf apps/*/.next` and rebuild (Turbopack caches across the link boundary).
-6. **Generated agent files**: `pnpm gen:agents` runs clean (regenerates from `.rulesync/`).
-
-If everything passes but a build still fails, hand off to the `debugger` agent with the verbatim error - it owns the deeper resolution table (turbopack.root, symlinked tsconfig, externalDir).

package/template/__dot__rulesync/hooks/post-edit.mjs

@@ -1,57 +0,0 @@
-#!/usr/bin/env node
-import { execSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { join, isAbsolute, relative } from 'node:path';
-import { extractFilePath, readPayload } from './_shared.mjs';
-
-const CAP_LINES = 40;
-const CAP_CHARS = 2000;
-
-const filePath = extractFilePath(readPayload());
-if (!filePath) process.exit(0);
-if (!/\.(ts|tsx)$/.test(filePath) || /\.d\.ts$/.test(filePath)) process.exit(0);
-if (filePath.includes('/templates/') || filePath.includes('/generated/')) process.exit(0);
-
-// Lint-fix (best effort - never block on the linter).
-try {
-  execSync(`pnpm exec oxlint --fix "${filePath}"`, { stdio: 'pipe' });
-} catch {
-  /* oxlint unavailable or errored - fall through to typecheck */
-}
-
-function packageNameFor(fp) {
-  const m = fp.match(/(.*?\/(?:apps\/[^/]+|packages\/[^/]+\/[^/]+))\//);
-  if (!m) return null;
-  try {
-    const pkg = JSON.parse(readFileSync(join(m[1], 'package.json'), 'utf8'));
-    if (!pkg.name || !pkg.scripts?.typecheck) return null;
-    return pkg.name;
-  } catch {
-    return null;
-  }
-}
-
-const abs = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
-const owner = packageNameFor(abs);
-if (!owner) process.exit(0);
-
-function cap(text) {
-  const out = text.split('\n').slice(0, CAP_LINES).join('\n').slice(0, CAP_CHARS);
-  return out.length < text.length ? `${out}\n... (truncated)` : out;
-}
-
-try {
-  execSync(`pnpm --filter "${owner}" typecheck`, { stdio: 'pipe' });
-  process.exit(0);
-} catch (e) {
-  const output = (e.stdout?.toString() ?? '') + (e.stderr?.toString() ?? '');
-  const basename =
-    (isAbsolute(filePath) ? relative(process.cwd(), filePath) : filePath).split('/').pop() ?? '';
-  if (basename && output.includes(basename)) {
-    process.stderr.write(
-      `Typecheck failed for ${owner} after editing ${basename}:\n${cap(output)}`,
-    );
-    process.exit(2);
-  }
-  process.exit(0);
-}

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

@@ -1,31 +0,0 @@
----
-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).