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

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

@@ -0,0 +1,102 @@
+---
+targets:
+  - '*'
+name: tester
+description: >-
+  Tester for a downstream igaming built on @openora/*. Drives a built change
+  against the operator's local stack, checks every test case and acceptance
+  criterion, attacks it like a player, a tester and a fraudster would, and
+  returns a per-case verdict table. Adds the tests its pass exercised;
+  never fixes app code. Records the per-AC videos only when asked, once,
+  on the final commit. Use as step 3 (verify) and step 4b (evidence) of
+  ship, or to verify a branch by hand.
+claudecode:
+  model: sonnet
+  effort: high
+---
+
+You verify a built change by hand against the running stack, debug failures with Chrome DevTools, and triage bugs - OSS core vs operator overlay. After the pass you add the tests it exercised, in the same branch. You start no subagents of your own: a domain doubt or a bug goes in your reply, and the orchestrator routes it.
+
+## 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` / `password1234`. 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, start what the cases need yourself (the API, plus the player app or backoffice for a browser case) per the repo's worktree rules, and stop it when you are done. Ports held by another worktree: never kill it - the cases that need it are UNCHECKED, saying so.
+
+## Your pass: verify by hand, then add the tests
+
+A feature or fix PR carries its own tests (`docs/standards/testing.md`). Your deliverable is:
+
+1. List every test case from the plan you are handed and every acceptance criterion from the ticket (read per `docs/agents/issue-tracker.md`), numbered, before touching the app. An AC hidden in a comment or a linked page counts.
+2. Drive each AC against the running stack yourself, including the error states and the authz negatives. Assume the change is broken until the app proves otherwise - the developer's description and the videos already on the PR are claims, not evidence.
+3. **Try to break it** (below).
+4. No videos in this pass: the code can still change after review, and a clip recorded now gets thrown away. The one exception is a bug's "before" clip, recorded once when you reproduce it on the unfixed code.
+5. A **verdict table**: one row per case and AC - `case | PASS / FAIL / UNCHECKED | what happened, evidence (spec run, trace, screenshot)`. Never PASS because a screen exists - the outcome the case names must be observed, and the row names where: the test that ran it, the response, or the screenshot path. A browser case checked only through the API, or a case nothing ran, is UNCHECKED, saying why.
+6. **Mutation check** on a money, KYC, responsible-gambling or authz change (`docs/standards/testing.md`, "Tests that catch the bug"): the repo's `test:mutation` script scoped to the changed files where it has one, otherwise break each changed check by hand (flip a condition, move a boundary by one, drop an owner check, change the sign of an amount), run the tests that cover it, and restore the file with `git checkout -- <file>`. One row per break in the verdict table: `mutation <file:line> <break> | KILLED / SURVIVED / UNCHECKED | the test that failed`. A break no test catches: write the test that catches it, run the break again. Still SURVIVED, or a break you could not run, stays in the table as such.
+7. The tests that pass exercised, committed in this branch (section below), and a **"Tests"** list: one line per test, tier (unit / API E2E / browser E2E) and path - it goes into the MR description.
+8. Clean up: drop the scratch data you made (rows, a database or Redis db you created for the pass, `apps/e2e/.auth` files you regenerated) and stop what you started. Say what you could not remove.
+
+A broken flow is a FAIL row with the exact steps, expected vs actual and the file:line if you found it - the orchestrator sends it to `builder`. A failing spec you did not write: run it on the base commit too and name that run in the row; failing there as well is pre-existing, it is not this change's FAIL. Never call a spec pre-existing from reading code: unrun on the base, it is a FAIL.
+
+## Try to break it
+
+After the happy path, attack the change the way a player, a bored tester and a fraudster would. Log every attempt with its result - a list of what you tried that held is part of the report. Only the attacks that fit the change: a copy fix needs none, a new money flow needs all of them.
+
+- Input: empty, zero, negative, decimals past the currency's precision, the max and max+1, very long strings, unicode, pasted whitespace.
+- Timing: double submit, rapid repeat clicks, refresh and browser back mid-flow, the same flow in two tabs, an expired session.
+- Ownership: another player's ids in the URL or request body, a non-admin on an admin route, a logged-out call.
+- State: a limit already spent, a self-excluded or unverified player, an insufficient balance, a bonus already active.
+- Money paths: replay the request and check the ledger moved once.
+
+## Tests
+
+They live in the change's own branch and follow the `conventions` tier: 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 - delete it and cover the behaviour 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: real seeded stack by default (that run blocks merge; `USE_MOCKS` only for a state you cannot produce for real), 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.
+
+**Screenshot review on every changed screen**, part of the verify pass. Nobody reads a video back, so layout defects are caught on stills, by you. Read `.claude/skills/ui-verify/SKILL.md` and follow its "Screenshot review" yourself - do not invoke the skill, it forks a subagent: four shots per screen, `layout-check.js` in each, then read each shot. Every shot gets a verdict-table row `screen <name> <viewport> <theme> | PASS / FAIL | <png path>, what you saw`; a defect is a FAIL for `builder`. A UI change with no screenshot rows is not verified.
+
+## Evidence pass: videos, once
+
+Only when the orchestrator asks for it: after the verify pass is green and review is clean, on the final commit. Nothing is verified or attacked again here; it records what already passed.
+
+**Evidence is mandatory** before the MR: one short video per acceptance criterion (aim under 30 s, ending on the outcome the AC names; the "after" twin of a fix's "before" clip), saved under `apps/e2e/test-results/evidence/<ac>-<slug>.webm`, and the file paths listed in the report so they reach the PR description - a human confirms the change by watching it, not by reading a description.
+
+1. Specs first: run every browser spec that drives an AC, whether this branch added it or it already existed, in one command with video on (the repo's record switch where it has one, otherwise `test.use({ video: 'on' })`), and copy each `test-results/<test>/video.webm` to its evidence name. One run films every AC a spec drives, at no token cost per step.
+2. `playwright-cli` (`video-start`, `video-chapter "AC<n>: ..."`, drive it, `video-stop`) only for an AC no spec drives.
+3. A spec that fails here is a FAIL row back to the orchestrator, never a re-recorded workaround.
+
+API-only changes attach the request/response trace instead. Scale it to the change: a footer link needs one clip, a new money flow needs the whole journey. After a fix to an open MR, record again only the ACs that fix touched.
+
+## 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 -> a FAIL row for `builder`.
+- Technically consistent but violates igaming rules -> a question for `expert` in your reply.
+
+Severity: P0 blocks money/auth/game loop; P1 wrong business logic (wrong balance, bad geo-block); P2 broken UI / wrong API shape; P3 cosmetic (a row note, not a FAIL).
+
+## 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 - a test that fails on app code is a FAIL row, not a fix. The one exception is a mutation-check break, restored before you run anything else; `git status` shows no app file changed when you report.
+- Assert on user-visible outcomes, not component internals.
+- Commit only the tests you added, then run the repo's gate (`/check`) and the specs you touched once more on HEAD. Never push.
+- Videos and screenshots stay under `apps/e2e/test-results/evidence/`, never committed; the orchestrator embeds them in the MR.

package/template/__dot__rulesync/sync.json.tpl

@@ -0,0 +1,26 @@
+{
+  "vars": {
+    "name": "{{name}}",
+    "scope": "{{scope}}",
+    "trackerKey": "{{trackerKey}}",
+    "jiraSite": "{{jiraSite}}",
+    "jiraCloudId": "{{jiraCloudId}}",
+    "wikiSpace": "{{wikiSpace}}",
+    "teamChannel": "{{teamChannel}}",
+    "gitRemotePath": "{{gitRemotePath}}",
+    "ossDir": "{{ossDir}}",
+    "ossFromRoot": "{{ossFromRoot}}",
+    "mrTarget": "{{mrTarget}}"
+  },
+  "reviewPrecheck": {
+    "reactCompilerPaths": ["apps/web", "apps/backoffice"],
+    "extraSkipGlobs": [],
+    "domainPatterns": { "security": [], "compliance": [] }
+  },
+  "consumerOwned": [
+    ".rulesync/rules/overview.md",
+    ".rulesync/mcp.json",
+    ".rulesync/sync.json",
+    "docs/agents/forge.md"
+  ]
+}

package/template/apps/api/package.json.tpl

@@ -14,7 +14,7 @@
     "@openora/core": "{{coreVersion}}"
   },
   "devDependencies": {
-    "tsx": "4.22.2",
-    "typescript": "6.0.3"
+    "tsx": "{{tsxVersion}}",
+    "typescript": "{{typescriptVersion}}"
   }
 }

package/template/apps/api/src/extensions.config.ts.tpl

@@ -1,4 +1,5 @@
 import { corePlugins, type PluginEntry } from '@openora/core/server';
+import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -7,16 +8,27 @@ import { fileURLToPath } from 'node:url';
 // later registration of a DI token wins, so an adapter override must come after
 // the module it replaces. Opt a core module out with a filter, eg
 // `corePlugins().filter((p) => p.id !== 'chat')`.
+//
+// Every `path` must be absolute: the plugin host imports it from inside
+// @openora/core, where a relative path or a bare package name resolves from
+// core's location instead of this file's.
 
 // Local overlays live alongside this file, under src/extensions/<name>/.
 const LOCAL = resolve(dirname(fileURLToPath(import.meta.url)), 'extensions');
 
+// Add-on packages installed from a registry resolve from this app.
+const fromApp = createRequire(import.meta.url).resolve;
+
 export const extensions: PluginEntry[] = [
   ...corePlugins(),
 
   // Your overlays. Generate with `pnpm gen plugin` / `pnpm gen adapter`.
   // Example (loaded after `wallet` so its PAYMENT_ADAPTER binding wins):
   // { id: 'my-payment', path: `${LOCAL}/my-payment/plugin.ts` },
+
+  // An add-on package, after the modules it depends on:
+  // { id: 'igaming-poker', path: fromApp('@acme/igaming-poker/plugin') },
 ];
 
 void LOCAL;
+void fromApp;

package/template/apps/api/src/main.ts.tpl

@@ -67,18 +67,15 @@ process.env['EXTENSIONS_CONFIG'] ??= resolve(
 );
 
 async function bootstrap() {
-  const { listen, emitOpenApiSpec } = await createApp({
+  const { listen } = await createApp({
     plugins: await loadExtensions(),
     contract,
     authSchema: { user, session, account, verification, twoFactor },
     igaming,
     port: Number(process.env['PORT'] ?? 3001),
-    cors: { origins: process.env['CORS_ORIGINS']?.split(',') ?? '*' },
-    openapi: { info: { title: '{{name}} API', version: '0.1.0' } },
   });
 
   await listen();
-  await emitOpenApiSpec();
 }
 
 void bootstrap();

package/template/apps/api/src/seed.ts.tpl

@@ -10,6 +10,9 @@
  */
 import { createDrizzleDb } from '@openora/core/server';
 import { seedRoles } from '@openora/core/iam/seed';
+import { seedTag } from '@openora/core/pam/tag/seed';
+import { seedAutoWithdrawalConfig } from '@openora/core/wallet/seed';
+import { seedDefaultWeightProfile } from '@openora/core/promo/seed/bonus';
 // import additional module seeders here as you enable them
 
 async function main() {
@@ -27,7 +30,11 @@ async function main() {
   const db = createDrizzleDb(databaseUrl);
 
   await seedRoles(db);
-  // await seedOtherModule(db);
+  await seedTag(db);
+  await seedAutoWithdrawalConfig(db);
+  // Without it, a bonus with no offer behind it - a gift, a rain drop, a hand-issued grant -
+  // resolves no weight profile and is refused.
+  await seedDefaultWeightProfile(db);
   console.log('Reference data seeded.');
 }
 

package/template/docker-compose.yml

@@ -17,8 +17,20 @@ services:
 
   redis:
     image: redis:7-alpine
+    command:
+      [
+        'redis-server',
+        '--maxmemory-policy',
+        'noeviction',
+        '--appendonly',
+        'yes',
+        '--appendfsync',
+        'everysec',
+      ]
     ports:
       - '6379:6379'
+    volumes:
+      - redis_data:/data
     healthcheck:
       test: ['CMD', 'redis-cli', 'ping']
       interval: 5s
@@ -27,3 +39,4 @@ services:
 
 volumes:
   postgres_data:
+  redis_data:

package/template/docs/agents/cross-repo.md.tpl

@@ -0,0 +1,37 @@
+# Working across this repo and the OSS checkout
+
+Some changes need both repos: an OSS core change plus this repo's adaptation to it. Agents and humans do those the same way, from any agent tool.
+
+## Conventions
+
+- **OSS code is changed only in a worktree**: `pnpm oss:worktree <branch>` creates or reuses `{{ossDir}}/.worktrees/<branch, / as +>` and installs its dependencies. The `guard-core` hook denies writes anywhere else in `{{ossDir}}` and in `node_modules`, in every tool rulesync renders hooks for. The main `{{ossDir}}` checkout stays on its branch: other sessions build against it.
+- **Core gets generic changes only**: before touching core, state why it cannot live here and why another operator would want it. Operator-specific behavior stays here; core gets only the seam.
+- **Any core change can be made here**, new features included, in the worktree. The `handoff` skill is for work that should run in a separate session rooted in the OSS repo.
+- **Review before push**: `pnpm -C <worktree> verify`, then the OSS repo's own review workflow and its contract checklist on the worktree diff.
+- **Same branch name in both repos** pairs the two requests. Skills find the OSS half from this repo's branch.
+- **No links between the requests**: the shared branch name is the pairing. The OSS repo is public, so its PR never names the operator; this repo's request may be read by people outside the team, so it never names or links the OSS repo.
+- **Run against the change**: `pnpm oss:worktree <branch> --link` builds the worktree and points `pnpm link:oss` at it; `pnpm link:oss` alone restores the main checkout. This repo runs core's built `dist/`, not its source, so after every core edit run `pnpm -C <worktree> build` before this repo or its e2e sees the change.
+- **Review covers both halves**: the `review` skill finds the pair, reviews the OSS diff by the OSS repo's own rules, and cross-checks the contract between them.
+- **Clean up** after both requests merge: `pnpm oss:worktree <branch> --remove`.
+
+The full procedure lives in "Changing OSS core" in the `oss-boundaries` rule.
+
+## Example asks
+
+One session covers both halves; start it here with `{{ossDir}}` added (see below).
+
+- "{{trackerKey}}-123: the withdrawal list needs a `currency` filter. Add it to the OSS contract in a worktree, then use it here."
+- "The OSS bug behind {{trackerKey}}-456: fix it in a worktree, link it, and rerun this repo's e2e against it."
+- "Review this branch and its OSS pair."
+- "Both requests merged: bump `@openora/*` and remove the worktree."
+
+## Giving each tool access to `{{ossDir}}`
+
+Grant the whole `{{ossDir}}`, not only `.worktrees/`: a worktree keeps its git metadata in `{{ossDir}}/.git`, so committing there writes to it. The hook still limits file edits to the worktree.
+
+- **Claude Code**: `permissions.additionalDirectories: ["{{ossDir}}"]` in `.claude/settings.json`, checked in. Takes effect once the workspace is trusted. That grants file access only; `claude --add-dir {{ossDir}}` (or `/add-dir {{ossDir}}`) also loads the OSS repo's skills and agents, and with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` in the `env` block of `.claude/settings.json`, checked in, its `CLAUDE.md` and `.claude/rules/`.
+- **Codex CLI**: `codex --add-dir {{ossDir}}`. `.codex/config.toml` is generated by rulesync, so a checked-in `writable_roots` entry would be overwritten. A personal alternative is `[sandbox_workspace_write] writable_roots` in `~/.codex/config.toml` with an absolute path.
+- **GitHub Copilot CLI**: `copilot --add-dir {{ossDir}}`, or `/add-dir {{ossDir}}` in the session. No project-level key exists.
+- **Gemini CLI**: `gemini --include-directories {{ossDir}}`, or `/directory add {{ossDir}}`. `.gemini/settings.json` is generated by rulesync.
+
+Each tool reads only this repo's instruction files at start. The rules therefore tell every agent to read the OSS repo's `AGENTS.md`, `.rulesync/rules/`, and `docs/standards/` from the worktree before editing or reviewing there, so no tool depends on loading a second repo's instructions.

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

@@ -0,0 +1,54 @@
+# 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>`
+- Review comments (resolved and unresolved - this endpoint has no resolved state): `gh api --paginate "repos/{{gitRemotePath}}/pulls/<n>/comments"`
+- CI: `gh pr checks <n>`; wait for it to finish with `gh pr checks <n> --watch` (GitLab: `glab ci status --live`)
+- Source to review, without switching the working tree: `git fetch origin "$(gh pr view <n> --json headRefName -q .headRefName)" && git worktree add --detach .claude/worktrees/review-<n> "$(gh pr view <n> --json headRefOid -q .headRefOid)"`
+- Last review marker (`review` skill §2a): `gh api --paginate "repos/{{gitRemotePath}}/issues/<n>/comments" --jq '[.[] | select(.body | contains("<!-- review:sha=")) | select(.author_association == "OWNER" or .author_association == "MEMBER" or .author_association == "COLLABORATOR") | select(.user.login != "<pr-author>")] | last | .body' | grep -o 'review:sha=[0-9a-f]*' | tail -1`, with `<pr-author>` from `gh pr view <n> --json author -q .author.login`. Both filters are load-bearing: anyone can post a comment containing the marker text for any SHA they like, so an outside contributor's marker and the PR author's own (a member can be both) are never trusted as a completed review. The marker only narrows an interactive review; `--ci` ignores it.
+
+## Attach evidence
+
+`gh` has no command to upload an image. Open the PR in the browser and drag each file into the description or a comment; GitHub inserts the embed markdown, keep it. If a file cannot be uploaded, say in the description that it is available from the author. Never paste a local path.
+
+## 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,42 @@
+# 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>` when it finishes the ticket, `Refs {{trackerKey}}-<n>` when it is one of several MRs for it. If your forge's tracker integration keys on `Closes`, `Refs` never moves the ticket.
+- 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.
+- The one standing exception: `/ship {{trackerKey}}-<n>` is the ask for its own writes on that ticket - the Plan, questions, blocker and MR-link comments, the test cases where the `test-plan` skill keeps them, and the transitions to In Progress and Code Review. Nothing else.
+- 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/comments.md

@@ -0,0 +1,16 @@
+# Comments
+
+Read this before writing a comment or JSDoc.
+
+- Comment WHY, never WHAT: hidden constraint, invariant, bug workaround (link it), trade-off. If a
+  block needs a comment to be understood, rename/extract instead.
+- No section-divider comments (`// ---`, `// ===`).
+- Every JSDoc is multi-line, always - `/**`, the text, and `*/` each on their own line. A
+  single-line `/** ... */` is never allowed, even for one sentence. Add one only on an independent
+  function/class (not a React component or hook) that is >~15 lines or has non-obvious params. One
+  sentence; document the surprising contract, not the name.
+- Never JSDoc a React component or hook - a genuinely surprising note goes on the specific
+  prop/param type, or an inline comment at the call site.
+- Deferred work: `// TODO:` with the concrete follow-up, never a bare TODO.
+- Placeholder/sample data and stubs: greppable `// mock:` comment so throwaway code stays
+  findable.

package/template/docs/standards/database.md

@@ -0,0 +1,77 @@
+# Database conventions (SQL / Drizzle)
+
+Read this in full before editing a schema, Drizzle query, migration config, or seed under
+`apps/api/**`. Tables live in `@openora/*` core for platform domains - never edit those; these
+rules govern the tables your overlay adds
+(`apps/api/src/extensions/<name>/src/schema/`). Import/boundary rules live in `oss-boundaries`;
+this file is SQL only.
+
+## Identifiers - snake_case everywhere
+
+Every drizzle instance sets `casing: 'snake_case'`, so the SQL name derives from the camelCase
+key. Pass an explicit name only where casing can't derive it: table names, `pgEnum` types, index
+names.
+
+```ts
+// good - key derives the column; const camelCase; explicit snake_case only for table + index
+export const playerNote = pgTable(
+  'player_note',
+  {
+    id: uuid().primaryKey().defaultRandom(),
+    playerId: uuid().notNull(), // -> player_id
+    createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [index('player_note_player_id_idx').on(t.playerId)],
+);
+
+// bad - explicit/camelCase column names, PascalCase table
+pgTable('PlayerNote', { player_id: uuid('playerId') });
+```
+
+## Timestamps - always timestamptz
+
+```ts
+createdAt: timestamp({ withTimezone: true }); // good - Postgres timestamptz, store UTC
+createdAt: timestamp(); // bad - naive, drops the zone
+```
+
+Every datetime column (`createdAt`, `updatedAt`, `expiresAt`, any `*At`) carries the zone.
+
+## Keys, references, indexes
+
+- UUID primary keys (`uuid().primaryKey().defaultRandom()`).
+- **No foreign keys across a module/overlay boundary** - store a plain ID string and resolve via
+  the oRPC client or a schema subpath. FKs only within the same add-on.
+- `NOT NULL` by default; push defaults to the DB (`.notNull().default(...)`), not app code.
+- Index every column you filter or join on; name it `<table>_<cols>_idx`.
+
+## Efficient operations
+
+```ts
+// bad - N+1
+for (const id of ids) await db.select().from(wallet).where(eq(wallet.playerId, id));
+// good - one batched query
+await db.select().from(wallet).where(inArray(wallet.playerId, ids));
+```
+
+- Select only the columns you use; don't `select(*)` wide rows to read one field.
+- **Build rows by spread + override, never hand-copy field-by-field.** When a row mostly mirrors a
+  validated input, spread it and set only the server-computed fields - `db.insert(x).values({
+...input, id, createdAt })` - never re-list `field: input.field` per key (it silently drifts the
+  moment a column is added). Keep fields explicit only for: an order-sensitive hash/signature
+  payload; a source carrying columns the row must not receive (spread then omit them); or a
+  null-vs-undefined boundary that won't coerce (`actorId: input.actorId ?? null`).
+- **Money / critical paths are transactional and idempotent** - a DB guard inside the transaction,
+  not just an `idempotencyKey` (delivery is at-least-once).
+
+```ts
+await db.transaction(async (t) => {
+  if (await ledgerExists(t, idempotencyKey)) return; // guard, not just a key
+  await insertLedger(t, { idempotencyKey, amount, currency });
+});
+```
+
+## Migrations
+
+- Never hand-edit generated migrations. Change the `pgTable`, then `pnpm db:migrate`.
+- One migration per schema change; review the generated SQL before committing.

package/template/docs/standards/enforcement.md

@@ -0,0 +1,12 @@
+# Enforcement
+
+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;
+  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.
+- Agent rules are generated from `.rulesync/` via `pnpm gen:agents` - never hand-edit a generated
+  file.

package/template/docs/standards/errors.md

@@ -0,0 +1,30 @@
+# Errors
+
+Read this before adding an error class, a catch, or a money-handling path.
+
+- Fail fast at boundaries with typed errors (`CreateOrderSchema.parse(raw)` throws early).
+- No silent catches - log with context and rethrow.
+- Typed, named error classes via the shared factories (`makeNotFoundError`/`makeOwnershipError`/
+  `makeConflictError`); the router's `mapErrors` keys off the exported class.
+- An overlay route that answers a vendor's own protocol, such as an inbound callback, throws
+  `wireErrorResponse(status, body, { cause })` from `@openora/core/server`: the reply carries that
+  status (400-599) and JSON body, not oRPC's error envelope. A 5xx reply is reported through its
+  `cause`; pass the error that caused it, or log it yourself.
+- `ORPCError.message` is an English fallback for logs, not player-facing copy - UI copy keys off
+  `.code` plus typed `.data` fields.
+- Money/critical paths are transactional AND idempotent: a DB guard inside the transaction, not
+  just an `idempotencyKey` (delivery is at-least-once).
+
+```ts
+// bad - swallows the error, no context, no rethrow
+try {
+  await chargeWallet(tx, amount);
+} catch {
+  return null;
+}
+// good - a DB guard makes the mutation idempotent under at-least-once delivery
+await db.transaction(async (t) => {
+  if (await ledgerExists(t, idempotencyKey)) return;
+  await insertLedger(t, { idempotencyKey, amount });
+});
+```

package/template/docs/standards/frontend.md

@@ -0,0 +1,60 @@
+# Frontend conventions
+
+React/UI rules for this repo's `apps/*` UI apps and shared UI package. Read this before touching
+`apps/web/**`, `apps/backoffice/**`, or `packages/ui/**`. Not applicable if this repo is
+headless/api-only - delete this file and its row in `conventions`'s routing table in that case.
+
+## Component library and styling
+
+- React Compiler is ON. Never hand-write `useMemo`/`useCallback`/`React.memo` - a compiler bail is
+  a Rules-of-React violation to fix. Exception: your shared UI package is consumed pre-built, so
+  hand-write stability there when it's part of a hook's contract (same reason `@openora/core/react`
+  does).
+- Pick ONE component library and use its classes customized via utility classes + theme tokens.
+  Don't hand-roll what the library provides.
+- Never hand-write component CSS selectors (`.btn-*{}`, `.table th{}`). A per-app `styles.css`
+  holds only the theme plus custom properties for raw values with no token; every other style is
+  a utility class on the element.
+- App-specific looks live in that app's `styles.css`; shared UI components stay visually neutral.
+- No hardcoded user-facing copy - every label goes through `t()` with a key in the module's
+  `locales/`. Pattern: `locales/index.ts` exports `export const ns = registerTranslations('<module>',
+locales)`; components use `useTranslation(ns)`. Non-`en` files mirror `en.json` keys exactly.
+- Theme tokens and CSS variables are declared once in the shared UI package - style with semantic
+  tokens (`bg-base-100`, `text-base-content`, `btn-primary`), never inline raw hex. A design color
+  with no token: add it to BOTH dark and light theme blocks. A new token without a design source:
+  ask the user first.
+- Hoist long class strings into a module-scope `const styles = { ... } as const` keyed by role -
+  never inline long strings in JSX; merge with `cn()`.
+- Extract a repeated utility-class recipe into a shared component or constant on the third
+  occurrence.
+- Import helpers like `cn()` from the shared UI package barrel - never deep-import.
+- Server state is not client state - key/cache/invalidate via the query lib, never
+  `useEffect(fetch)`, never shadowed in ad-hoc caches.
+- No label or text is allowed to overflow its container - never leave text unconstrained by
+  default. Pick per element, based on whether the full text is load-bearing: `truncate` + a
+  `title` attribute holding the full string when a single line is the right shape and hiding the
+  tail is acceptable (a table cell, a narrow badge); `line-clamp-N` + a reserved `min-h-[NlH]` when
+  several lines are the right shape or the content differs in length across siblings that must
+  stay visually aligned (a KPI tile label, a card title) - the reserved height keeps every sibling
+  the same height whether or not its text actually wraps. A tooltip/popover with the full text is
+  the fallback only when neither fits the UX.
+
+## Modular architecture (every app)
+
+- Feature modules live in `src/modules/<m>/` with the same internal folders: `pages/`,
+  `components/`, `hooks/`, `utils/`, `locales/`, and a public barrel `index.ts`.
+- App-level (non-module) code splits the same way: `src/lib/` holds stateful/integration code
+  (API clients, SDK wrappers, config); `src/utils/` holds pure stateless helpers (formatters,
+  converters).
+- No cross-module imports, ever. Cross-module communication is query invalidation or a domain
+  event, never a direct import.
+- Outer composition code (`src/app/`, `src/routes/`, `extensions.config.ts`) imports modules only
+  through their barrel; deep-importing internals is forbidden. Files inside a module use relative
+  paths to siblings only, never `../../` out of the module.
+- Components in `components/` and `pages/` are presentation-only: props in, JSX out - no
+  fetching, no side effects. Business logic, queries, and mutations live in `hooks/`, which accept
+  external dependencies (oRPC calls, API clients) as parameters.
+- Next.js client components: `'use client'` on line 1 + `.client.tsx` suffix; server components
+  are the default (no marker). All-client apps (Vite/TanStack) use no suffix.
+- One concept per file, exported name matches the kebab-case filename; split hooks and components
+  into separate files.

package/template/docs/standards/functions.md

@@ -0,0 +1,38 @@
+# Functions and modules
+
+Read this before writing or refactoring a function, service method, or module.
+
+- Pure functions with dependencies passed in as arguments; side effects only at the edges
+  (services, adapters, plugins, handlers) - never in helpers.
+- Immutability: derive new objects (`{ ...user, roles: [...] }`), don't mutate.
+- Construct objects by spread + override, never field-by-field hand-copy. Keep fields explicit
+  only for order-sensitive serialization, when the target must not receive some source fields, or
+  when null-vs-undefined matters at a boundary.
+- A `class` is only a thin dependency-holding shell at a composition root; methods delegate to
+  pure functions. No inheritance for reuse, no decorators - compose.
+- Short, single-purpose functions - if you'd write `// step 2` inside one, extract it.
+- Guard clauses first, main path last.
+- More than 3 parameters -> a single named-object param.
+- Don't annotate a return type TypeScript can infer. Annotate only when: inference can't
+  (recursion), you deliberately widen/narrow, or it's the exported public API of a shared
+  `packages/*` module - there the explicit type IS the contract. Argument types always stay
+  explicit.
+- Named exports only - no default exports (exceptions: `*.config.*` files, `plugin.ts` whose
+  loader reads `mod.default`, and Next.js App Router files; lint-enforced).
+
+```ts
+// bad - the service reaches into a global/container to hide what it depends on
+export class WalletService {
+  constructor(private readonly container: Container) {}
+  async deposit() {
+    const psp = this.container.get(PAYMENT_ADAPTER);
+  }
+}
+// good - deps are constructor params of their port type
+export class WalletService {
+  constructor(
+    private readonly db: DrizzleService,
+    private readonly payments: PaymentAdapter,
+  ) {}
+}
+```