@xhulz/nina 0.63.0 → 0.64.0

package/releases/0.64.0/surfaces/edge-cf/tree/.claude/patterns.md

@@ -0,0 +1,17 @@
+<!-- nina:slot edge-cf.1 -->
+
+---
+
+## Secrets
+
+- **Wrangler secrets** for Workers (`{{SECRETS_PROD}} X`). Never `.env` committed.
+- **Local dev:** `{{SECRETS_LOCAL}}` (gitignored).
+
+<!-- nina:slot edge-cf.2 -->
+- `nodejs_compat` in the wrangler config's `compatibility_flags` is required for a database client that runs at the edge.
+
+<!-- nina:slot edge-cf.3 -->
+- **Miniflare** for Worker integration tests.
+
+<!-- nina:slot edge-cf.4 -->
+- **Miniflare** for Worker tests — the real Cloudflare runtime, no mocks.

package/releases/0.64.0/surfaces/edge-cf/tree/.claude/retrieval.md

@@ -0,0 +1,8 @@
+<!-- nina:slot edge-cf.1 -->
+| New Durable Object behavior | `.claude/architecture.md` § *Durable Objects*, existing `{{API_DIR}}/src/do/` | architect → implementer → reviewer + the integration gate, where there is one → qa |
+
+<!-- nina:slot edge-cf.2 -->
+| New Queue handler | `.claude/architecture.md` § *Processing pipeline*, `{{API_DIR}}/src/queues/` | architect → implementer → reviewer + the integration gate, where there is one → qa |
+
+<!-- nina:slot edge-cf.3 -->
+| Wrangler / deploy / config | `CLAUDE.md` § *Common commands*, the wrangler config (`wrangler.jsonc` or `wrangler.toml`), `.claude/patterns.md` § *Secrets* | implementer → reviewer → qa → devops |

package/releases/0.64.0/surfaces/edge-cf/tree/CLAUDE.md

@@ -0,0 +1,27 @@
+<!-- nina:slot edge-cf.1 -->
+
+### Cloudflare plugin skills — USE THEM
+
+The `cloudflare@cloudflare` plugin is installed at user scope and exposes skills that retrieve the **current** Cloudflare docs at invocation time. Pre-trained knowledge of Workers / Wrangler / DO / Queues / Cron APIs is stale — prefer the skill over recalling from memory.
+
+<!-- nina:slot edge-cf.2 -->
+| Write or review code under `{{API_DIR}}/**` (routes, services, middleware, webhook receivers, queue consumers) | `cloudflare:workers-best-practices` | catches floating promises, global-state misuse, missing `waitUntil`, streaming pitfalls |
+
+<!-- nina:slot edge-cf.3 -->
+| Touch `{{API_DIR}}/src/do/**` or any Durable Object call site | `cloudflare:durable-objects` | covers RPC, alarms, WebSocket, SQLite storage, lifecycle — DO API surface drifts fast |
+
+<!-- nina:slot edge-cf.4 -->
+| Touch `{{API_DIR}}/src/queues/**`, R2/KV usage | `cloudflare:cloudflare` | Queues, R2, KV decision tree |
+
+<!-- nina:slot edge-cf.5 -->
+| Author or modify `wrangler.toml` / `wrangler.jsonc` / run any `wrangler` CLI command | `cloudflare:wrangler` | CLI flags + config fields churn between minor versions |
+
+<!-- nina:slot edge-cf.6 -->
+| Run the **devops** deploy stage | `cloudflare:wrangler` (+ `cloudflare:cloudflare` for R2/KV/Queues/DO bindings) | deploy flags and binding config churn between versions |
+
+<!-- nina:slot edge-cf.7 -->
+
+The plugin's other skills — `cloudflare:agents-sdk`, `cloudflare:sandbox-sdk`, `cloudflare:cloudflare-email-service` — apply only where {{PROJECT}} adopts what they cover: an agent runtime, untrusted code execution, sending mail.
+
+<!-- nina:slot edge-cf.8 -->
+10. **Secrets in `{{SECRETS_LOCAL}}` for local dev, `{{SECRETS_PROD}}` for production.** Never `.env` committed. `nodejs_compat` is required in the `compatibility_flags` of the wrangler config (`wrangler.jsonc` or `wrangler.toml`) for any database client that runs at the edge.

package/releases/0.64.0/surfaces/frontend/tree/.claude/agents/architect.md

@@ -0,0 +1,20 @@
+<!-- nina:slot frontend.1 -->
+| `cloudflare:web-perf` | a page-load performance question in `{{APP_DIR}}` |
+
+<!-- nina:slot frontend.2 -->
+
+## Visual acceptance — required in any spec touching `{{APP_DIR}}/**`
+
+A frontend spec that describes only structure produces a diff that only structure can verify, and
+structure is exactly what a test renderer checks while blind to the result. So state, as a short
+checklist, what must be TRUE ON THE SCREEN at **1440** and at **375**:
+
+- what is visible, and what must not be
+- what sits beside what, and what wraps or stacks at 375
+- the empty, loading and error states, if the change can produce them
+- anything that must not overflow, clip or overlap
+
+Each line must be checkable from a screenshot by someone who did not write the code — the **reviewer**
+checks the render against this list, and rejects on a mismatch. "Follows the design system" is not a
+criterion. A spec that touches `{{APP_DIR}}/**` without this section is incomplete, and the reviewer
+rejects it back to you.

package/releases/0.64.0/surfaces/frontend/tree/.claude/agents/devops.md

@@ -0,0 +1,28 @@
+<!-- nina:slot frontend.1 -->
+- Playwright is **not** a skill — it is an MCP server, and its `browser_*` tools are granted to you
+  directly in `tools:` above. Use them; there is nothing to invoke via `Skill`.
+
+<!-- nina:slot frontend.2 -->
+- **Build-time env.** A bundler inlines the variables the app reads at build time, so one the deploy platform supplies at RUNTIME never reaches the bundle — it is not late, it is absent. Verify every variable the app reads is present in the build environment — a missing one ships a blank page, not an error.
+
+<!-- nina:slot frontend.3 -->
+
+## Render smoke — for any diff touching `{{APP_DIR}}/**`
+
+You are not the visual gate; the **reviewer** is, and it judges the render against the spec before
+the code ever reaches you. Your question is narrower and different: **did the deployed thing come up
+at all?** That is not the same failure — a build that renders perfectly on a reviewer's localhost
+still ships a blank page when the API's address was missing from the deploy build.<!-- nina:why --> That is exactly
+what happened here once.<!-- /nina:why -->
+
+So on the preview URL, not localhost: `browser_navigate`, one screenshot at 1440, and
+`browser_console_messages`. You are checking that the page renders and the console is clean — not
+whether the layout is right. A blank page or a console error is `VERDICT: BLOCKED`.
+
+<!-- nina:slot frontend.4 -->
+
+If the changed path genuinely cannot be smoked without authenticating, do NOT authenticate: say so,
+report what you could verify, and hand the authenticated check to a human.
+
+<!-- nina:slot frontend.5 -->
+, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_close

package/releases/0.64.0/surfaces/frontend/tree/.claude/agents/implementer.md

@@ -0,0 +1,25 @@
+<!-- nina:slot frontend.1 -->
+| `frontend-design:frontend-design` | new UI in `{{APP_DIR}}` — a page or component that did not exist |
+
+<!-- nina:slot frontend.2 -->
+
+## Look at the screen you built
+
+When you change anything under `{{APP_DIR}}/**`, open it in the browser before you hand off — the dev
+server or a local build, with `browser_navigate` plus a screenshot at 1440 and 375. Your test suite
+renders with no layout engine, in jsdom or to a string in Node, and cannot tell you whether the thing renders.
+
+This is a self-check, not a gate: you are the author, and an author reviewing their own work catches
+the obvious and misses the rest. **reviewer** is the gate. The point of doing it here is that the
+obvious defects are cheap to fix now and expensive after review, qa and a deploy.
+
+Report what you saw. "Rendered at both widths, matches the spec's Visual acceptance" — or what
+differed.
+
+That is also why a component test must assert content, not presence: `toHaveTextContent('4 matched')`,
+not `toBeInTheDocument()` on the badge that shows it, and never `toHaveClass` as proof that something
+looks right — it passes whether or not a pixel landed. A test that pins a removal renders the tab or
+route where the removed thing used to appear; rendering the default one proves nothing about another.
+
+<!-- nina:slot frontend.3 -->
+, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_close

package/releases/0.64.0/surfaces/frontend/tree/.claude/agents/qa.md

@@ -0,0 +1,17 @@
+<!-- nina:slot frontend.1 -->
+
+## What your green does not mean
+
+Your suite renders with **no layout engine**, in jsdom or to a string in Node. `toHaveClass('flex')` passes whether or not
+anything was laid out; nothing you run can tell you the screen is right. When you report PASS on a
+diff touching `{{APP_DIR}}/**`, say so — the rendering is checked by the **reviewer**, against the
+spec's Visual acceptance criteria. A PASS read as "the screen works" is how frontend
+defects reached staging through every gate.
+
+## When a failure arrives labelled "pre-existing"
+
+On this surface the cause is usually the test harness rather than the feature — a text query matching
+several elements at once, a missing router context for a link, a `vi.mock` hoisted above the value it
+closes over, jsdom without `showModal`, a hardcoded origin. Every one of them is fixable in the test
+without weakening the assertion, and every one of them stays invisible for exactly as long as the
+failure keeps the label.

package/releases/0.64.0/surfaces/frontend/tree/.claude/agents/reviewer.md

@@ -0,0 +1,56 @@
+<!-- nina:slot frontend.2 -->
+- **If the diff touches `{{APP_DIR}}/**`: the spec — or the dispatch, in a chain with no architect — must carry a Visual acceptance section, and you check the render against it — see *Visual gate* below.** No section → REJECT upstream to whoever wrote it.
+
+<!-- nina:slot frontend.3 -->
+- `{{BUILD_CMD}}` for the affected frontend packages (`{{APP_DIR}}`)
+
+<!-- nina:slot frontend.4 -->
+## Visual gate — you are the stage that looks at the screen
+
+Deciding whether a screen is right is review, not operations, and it belongs here. qa runs vitest with
+**no layout engine**, in jsdom or rendering to a string: `toHaveClass('flex')` passes whether or not a single pixel
+landed anywhere. Every gate before you reads text. This is why backend work lands first time through
+this pipeline and frontend work does not — the frontend defects were never expressible as a test.
+
+For any diff touching `{{APP_DIR}}/**`:
+
+1. Build and serve it the way this project serves a build for review:
+
+   ```bash
+   {{VISUAL_SERVE}}
+   ```
+
+   Where screens sit behind a login, this command is what gets past it: a plain static server
+   screenshots the login page. Where the build reaches an API at an address fixed at build time, one
+   that does not match what the command serves ships a screen that renders but fetches nothing. A
+   request the served build does not answer is a gap in it: send it back naming the request, rather
+   than judge a broken screen. It must also reach the empty and error states the change has; a state
+   you cannot reach is a state nobody reviewed.
+2. `browser_navigate` to the changed screen. Screenshot at **1440** and at **375**
+   (`browser_resize` first — the viewport resets to a narrow default across navigations, so
+   resize AFTER navigating and confirm the width in the screenshot before you judge it).
+
+   Many screens are not reachable by URL: a tab kept in component state is never in the route, so
+   `browser_click` is the ONLY way in — a navigate-and-screenshot lands on the default tab and proves
+   nothing about the changed one.
+3. **Measure, do not squint.** `browser_evaluate` turns "looks fine" into a number, and an
+   overflow you can measure is one you can attribute. To decide whether horizontal scroll is
+   yours or pre-existing, measure `document.documentElement.scrollWidth` vs `clientWidth` on
+   the changed screen AND on an untouched one — and, when it matters, build `HEAD` into a second
+   dist from a worktree (Hard Rule #18) and measure both. Reporting a pre-existing app-wide defect
+   as a regression wastes a cycle; excusing a real one as "probably pre-existing" ships it.
+4. Check each screenshot against the spec's **Visual acceptance** list, item by item. Not "looks
+   fine" — the specific claims the spec made.
+5. `browser_console_messages`. An error there is a defect even when the page renders.
+
+A screen that contradicts the spec is `REJECTED`, with the screenshot and what is wrong in it. Say in
+your report which widths you looked at; a frontend approval that does not mention having looked is
+the failure this section exists to end.
+
+<!-- nina:slot frontend.1 -->
+, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_close
+
+<!-- nina:slot frontend.5 -->
+- **visual** — the spec's Visual acceptance section exists and the render matches it (see *Visual gate*).
+  A reviewer checking only another dimension skips it, so it is its own: owned by **patterns-and-scope**
+  when no visual reviewer is dispatched, and never nobody's.

package/releases/0.64.0/surfaces/frontend/tree/.claude/patterns.md

@@ -0,0 +1,8 @@
+<!-- nina:slot frontend.1 -->
+
+---
+
+## Frontend conventions
+
+This project's own — its framework, where server state lives, how it styles, and what it shares between
+apps — are in `.claude/frontend.md`. Read them before writing or reviewing code under `{{APP_DIR}}`.

package/releases/0.64.0/surfaces/frontend/tree/.claude/retrieval.md

@@ -0,0 +1,2 @@
+<!-- nina:slot frontend.1 -->
+| Frontend (`{{APP_DIR}}`) | `.claude/frontend.md`, `.claude/architecture.md` § *Frontend* | implementer → reviewer → qa |

package/releases/0.64.0/surfaces/frontend/tree/.claude/router.md

@@ -0,0 +1,14 @@
+<!-- nina:slot frontend.2 -->
+
+### Nothing before devops can see the screen
+The reviewer reads a diff. qa runs vitest with **no layout engine**, in jsdom or rendering to a string — `toHaveClass('flex')`
+passes whether or not a pixel landed anywhere. Every backend invariant is checkable in text, which is why
+the same pipeline lands backend work first time and lets frontend defects through every gate: they were
+never expressible as a test.
+
+So any diff touching `{{APP_DIR}}/**` carries a visual contract: the **architect** writes a *Visual acceptance*
+checklist (what must be true on screen at 1440 and 375), the **reviewer** rejects an FE spec without one, the
+**implementer** looks at its own screen before handing off, and the **reviewer** builds, serves and screenshots it,
+rejecting on a mismatch — judging the screen is review, not operations. **devops** only smokes the
+deployed preview for a blank page. Browser access is granted through the Playwright MCP `browser_*` tools in those agents'
+`tools:` lists — it is not a skill, and an agent without those tools in its list cannot see anything.

package/releases/0.64.0/surfaces/frontend/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot frontend.1 -->
+| Audit page-load perf on `{{APP_DIR}}` — LCP, INP, CLS, bundle size | `cloudflare:web-perf` | Core Web Vitals + Chrome DevTools MCP integration |
+
+<!-- nina:slot frontend.2 -->
+| **ANY diff touching `{{APP_DIR}}/**`** | architect writes a **Visual acceptance** checklist (the dispatch carries it in a chain with no architect); the **reviewer builds, serves and screenshots at 1440 and 375** and rejects on a mismatch; devops smokes the deployed preview for a blank page. A test renderer has no layout engine — a green suite says nothing about the screen |

package/releases/0.64.0/surfaces/integrations/tree/.claude/agents/architect.md

@@ -0,0 +1,16 @@
+<!-- nina:slot integrations.1 -->
+- **Integration premises (MANDATORY when an integration boundary is in scope)** — list every behavior of the dependency the implementation depends on. Each premise is a one-sentence claim followed by the evidence its kind requires:
+    - `installed-library` → `<package dir>/node_modules/<lib>/<file>:<line>`, the version installed here beside it — the package's own link, which a peer change does not rename; a dependency of a dependency, through its parent's: `<package dir>/node_modules/<parent> → <lib>@<version>/<file>:<line>`
+    - `live-api` → a contract-test case, or a response observed against the service and captured verbatim
+    - `platform-binding` → behavior observed under the local emulator, plus the platform's installed types
+    - or a `P<n>` reference into `.claude/integrations/<slug>.md`, which itself carries one of the above
+
+    A premise without a citation is an **assumption**, not a fact. The integration-tester rejects the spec if a cited line does not validate at runtime, and rejects it outright if it lists uncited premises. When in doubt: read the source. A live service you have no way to read is observed for you: report `BLOCKED` with an `ISSUES` id per premise to observe, the integration-tester records each as a `P<n>` with the response it got, and you are resumed with them. Integration regressions ship precisely when a premise is assumed instead of cited.
+
+    Also mark **"INTEGRATION-TESTER REQUIRED"** prominently at the top of the spec when this section is present.
+
+<!-- nina:slot integrations.3 -->
+- **For every integration behavior the implementation will rely on, get the evidence its kind requires** — open the installed source and cite `file:line`, or, for a live service, have it observed first (report `BLOCKED` naming what to observe). Library docs and editor autocomplete are not citations. This is the single most important rule for avoiding integration regressions.
+
+<!-- nina:slot integrations.4 -->
+- **State an integration's behavior as fact without the evidence its kind requires.** Uncited premises are assumptions, and assumptions are what ship integration bugs to prod. If you cannot find the citation, the answer is to read more source or escalate — not to write the spec anyway.

package/releases/0.64.0/surfaces/integrations/tree/.claude/agents/implementer.md

@@ -0,0 +1,12 @@
+<!-- nina:slot integrations.1 -->
+- If you change anything that touches an integration boundary, or add a call into one, flag it explicitly in the diff summary so the reviewer dispatches **integration-tester** before approving.
+
+<!-- nina:slot integrations.3 -->
+
+## Integrations
+- All access to a dependency goes through its **boundary module**, named in `.nina/profile.json`. **Never** reach it directly from a service, route, queue consumer or scheduled handler.
+- For a `live-api`, the contract-test suite is the source of truth and **both** implementations must pass it. Inject the mock in tests — and never let the mock be the only thing that ran.
+- Honor the spec's **Integration premises** verbatim. If one looks wrong while you are writing code against it, STOP and loop back to the architect. Do not work around a premise: the premise is the contract, and a contract that is wrong gets fixed, not bypassed.
+
+<!-- nina:slot integrations.4 -->
+- Reach an integration from anywhere outside its boundary module. Inject the mock in tests.

package/releases/0.64.0/surfaces/integrations/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,20 @@
+<!-- nina:slot integrations.2 -->
+2. **Live APIs.** A third-party service you reach over the network — payments, messaging, automation, mail. *Their* API is the contract; we conform to it. There IS a real service to hit, so you run the **contract-test suite** for that boundary against **BOTH** the real client and the mock, and you check each `P<n>` premise in `.claude/integrations/<slug>.md` against what the service actually returns.
+
+<!-- nina:slot integrations.3 -->
+- The boundary module of any declared integration, or a new call into one
+
+<!-- nina:slot integrations.6 -->
+- For the integration you are gating: `.claude/integrations/<slug>.md`. Read EVERY premise it lists, not a sample — the one you skip is the one the diff depends on.
+
+<!-- nina:slot integrations.7 -->
+
+## You MUST — live APIs
+
+- **Run the contract-test suite** for the boundary against **both** implementations. Every `P<n>` in the integration's doc maps to a case — verify every one the diff touches.
+- **Never accept a green mock as proof.** If only the mock run is green you have verified nothing about production. Say so, and reject.
+- **Confirm nothing reaches the service outside its boundary module.** Grep the diff and the tree for raw HTTP or client construction past the boundary. Any leak is a hard reject.
+- **Confirm the boundary validates responses** in both implementations, so drift in the service surfaces structurally rather than as a type error three layers downstream.
+
+<!-- nina:slot integrations.8 -->
+- **Update `.claude/integrations/<slug>.md` when you observe new behavior**, with the evidence that settled it: a contract case, an observed response, or a source citation.

package/releases/0.64.0/surfaces/integrations/tree/.claude/agents/planner.md

@@ -0,0 +1,2 @@
+<!-- nina:slot integrations.1 -->
+- **Integration flag** — if any subtask touches the boundary of a declared integration, or adds a call into one, mark **"INTEGRATION-TESTER REQUIRED"** on that subtask.

package/releases/0.64.0/surfaces/integrations/tree/.claude/agents/reviewer.md

@@ -0,0 +1,21 @@
+<!-- nina:slot integrations.1 -->
+- **If an integration boundary was touched anywhere in the diff, or a new call into one was added: name `integration-tester` on your Gates line.** Also verify the architect's spec carries an **Integration premises** section, each premise with the evidence its kind requires. If the section is missing or uncited, REJECT upstream — do not approve a diff against an incomplete spec.
+
+<!-- nina:slot integrations.3 -->
+- The diff touches an integration boundary — **integration-tester also required**
+
+<!-- nina:slot integrations.4 -->
+- Leave `integration-tester` off your Gates line "because the unit tests pass." Unit tests honor the spec's mock, not the real dependency — only the integration-tester catches drift.
+
+<!-- nina:slot integrations.5 -->
+- Integration boundary touched and `integration-tester` not dispatched → name it on your Gates line; the orchestrator sends it.
+
+<!-- nina:slot integrations.6 -->
+- Spec touches an integration boundary but lacks the **Integration premises** section with citations → back to **architect** for spec amendment (do NOT approve the implementer's diff against an incomplete spec).
+
+<!-- nina:slot integrations.7 -->
+- **The one exception is a `live-api` contract-test case.** Its job is to catch the real service
+  diverging from the mock, not to encode a mutation of code this project owns, so there is often no
+  change on this side that turns it red. Name the divergence it would catch instead — "the provider
+  renames a field the mock still sends" — and do not reject it for lacking a mutation: that test is
+  integration-tester's gate, and rejecting it here would remove the one check that watches the mock.

package/releases/0.64.0/surfaces/integrations/tree/.claude/agents/secops.md

@@ -0,0 +1,2 @@
+<!-- nina:slot integrations.1 -->
+- **Input validation / injection / SSRF** — validate at every trust boundary: request body, query, queue message, webhook payload, and every integration response. Parameterized queries only — never string-built SQL. Outbound HTTP to an integration: SSRF and URL-allowlist posture. Start with the unauthenticated internet-facing paths — a webhook receiver, a health route, a dev-only surface — and verify their signature or secret gate cannot be bypassed or replayed.

package/releases/0.64.0/surfaces/integrations/tree/.claude/agents-overview.md

@@ -0,0 +1,8 @@
+<!-- nina:slot integrations.1 -->
+- **Integration guardrail** → a spec describes behavior the implementer relies on, and unit tests with structural mocks honor the *spec*, not the dependency. The integration-tester runs the real thing: real flows for an installed library or a platform binding, and for a live API the contract suite against both the real client and the mock, so the two cannot diverge. Drift between assumption and reality is caught before deploy rather than after.
+
+<!-- nina:slot integrations.2 -->
+| **integration-tester** | Mandatory gate on any integration boundary; runs real flows, and for a `live-api` the contract suite against both implementations; verifies each cited premise; keeps `.claude/integrations/<slug>.md` current | `.claude/agents/integration-tester.md` |
+
+<!-- nina:slot integrations.3 -->
+- **`.claude/integrations/`** — one doc per integration, holding its verified premises

package/releases/0.64.0/surfaces/integrations/tree/.claude/graph.md

@@ -0,0 +1,10 @@
+<!-- nina:slot integrations.1 -->
+- `integration-tester` — gate: runs the real dependency when the diff touches what its spec lists
+
+<!-- nina:slot integrations.2 -->
+- `implementer` → `integration-tester` on `DIFF-READY` — the diff touches what its spec lists
+- `integration-tester` → `qa` on `APPROVED` — once the reviewer, and every other gate the diff went to, approved too
+- `integration-tester` → `architect` on `REJECTED` — a premise is wrong · max 2
+- `architect` → `integration-tester` on `BLOCKED` — a premise of a live service must be observed before the design can settle; the report goes back to the architect · max 2
+- `integration-tester` → `implementer` on `REJECTED` — the premise holds and the code does not honor it · max 2
+- `qa` → `integration-tester` on `FAIL` — the failure is the environment, not the code · max 2

package/releases/0.64.0/surfaces/integrations/tree/.claude/patterns.md

@@ -0,0 +1,38 @@
+<!-- nina:slot integrations.1 -->
+- **Queue** (`{{API_DIR}}/src/queues/<q>.ts`) / **Webhook** (`{{API_DIR}}/src/routes/<source>-webhook.ts`): same discipline — validate the input, build deps, call one service function.
+
+<!-- nina:slot integrations.2 -->
+- **Every integration is reached through its boundary module.** Services import the boundary's typed interface; they never construct an HTTP client, an SDK instance or a binding handle themselves.
+
+<!-- nina:slot integrations.3 -->
+
+---
+
+## Integrations (enforced by integration-tester + reviewer)
+
+An **integration** is a dependency whose behavior this project does not define. Each one is declared in `.nina/profile.json` with a `kind`, or a list of them, and a premise's kind decides what counts as evidence for it:
+
+| kind | what it is | a premise is settled by |
+|---|---|---|
+| `installed-library` | code on disk under `node_modules` | `<package dir>/node_modules/<lib>/<file>:<line>`, the version beside it; one no package links, through the one that depends on it: `<package dir>/node_modules/<parent> → <lib>@<version>/<file>:<line>` |
+| `live-api` | a third-party HTTP API | a contract-test case, or a response observed against the service and captured verbatim |
+| `platform-binding` | a runtime the host provides | behavior observed under the local emulator, plus the platform's installed types |
+
+- **One boundary per integration.** All access goes through the module named as its `boundary`. A service, route, queue consumer or scheduled handler that reaches the dependency directly is a hard reject: there is then no single place to mock it, retry it, log it, or fix it.
+- **A `live-api` gets two implementations behind one interface** — the real client, and a deterministic in-memory mock. One **contract-test suite** exercises the interface and **BOTH** must pass it. The mock passing alone proves nothing about production; when the two disagree, the mock is wrong, never the other way round.
+- **Validate responses at the boundary**, in both implementations, so drift in the dependency surfaces structurally instead of as a type error three layers downstream.
+- **Typed errors at the boundary.** It maps the dependency's failures to this project's own error types; callers never handle a raw HTTP status or a vendor error code.
+
+### Adding an integration
+
+Four things, and none of them is optional:
+
+1. **The doc** — `.claude/integrations/<slug>.md`, from `.claude/templates/integration.md`. It opens with a premise index, then one `## P<n>` section per premise: a one-sentence claim, and the evidence that settles it in the form its kind requires.
+2. **The boundary** — one module, named in the profile entry. For a `live-api`: the interface, both implementations, and the contract suite.
+3. **The profile entry** — `slug`, `name`, `kind`, `boundary` and `skill` in `.nina/profile.json`. This is what makes the integration visible to the gates; an integration that is not declared is not gated.
+4. **The skill binding, when one exists.** If an installed skill covers this dependency, name it in the entry's `skill` field and add its row to the *Skills you MUST consult* table of every agent that touches the surface. The table ends in a `skills` slot for exactly this: write the row in `.nina/project/tree/.claude/agents/<role>.md` under that slot's marker (`nina where .claude/agents/<role>.md` names it), with the skill in the first cell and the trigger in the second (where the section is a list or a paragraph, the skill in bold), then `nina compose`. `nina check` confirms the agent's `tools:` grants `Skill`, which is an allowlist, not a hint. **If no installed skill covers it, bind none:** an invented binding is worse than none, because it reads as retrieval while being recall.
+
+The **integration-tester** owns the doc: it creates it on first contact and appends a premise whenever it observes behavior the doc does not yet carry. The architect cites it, the implementer honors it, and the reviewer refuses a spec that touches the surface without it.
+
+<!-- nina:slot integrations.4 -->
+- **`live-api` integrations:** the contract-test suite for the boundary runs against BOTH implementations. Tests elsewhere inject the mock; the integration gate exercises the real service.

package/releases/0.64.0/surfaces/integrations/tree/.claude/pipeline.md

@@ -0,0 +1,16 @@
+<!-- nina:slot integrations.1 -->
+
+### Integration-tester (mandatory for integration boundaries)
+
+- **Trigger:** any diff touching the boundary module of a declared integration, or adding a call into one.
+- **Input:** architect spec (with its **Integration premises** section) + implementer diff + repo state.
+- **Output:** approve or reject. Approve includes a verified-premise table (premise → verdict → citation). Reject identifies which premise or contract case failed, and whether the fix is upstream (respec) or in code.
+- **Tools:** Read, Write, Edit, Glob, Grep, Bash. Edits scoped to integration/contract test dirs and `.claude/integrations/**`.
+- **Checks:**
+  - **`installed-library` / `platform-binding`:** run the real flow against the real dependency. Read `.claude/integrations/<slug>.md` and probe each premise it lists.
+  - **`live-api`:** run the **contract-test suite** for that boundary against **both** implementations. A mock that is green while the real client is not is a lie. Confirm nothing reaches the service outside its boundary module.
+  - Update `.claude/integrations/<slug>.md` when new behavior is observed.
+- **Position:** after implementer, in parallel with any other gate the diff triggered. Reviewer verifies both gates ran.
+
+<!-- nina:slot integrations.2 -->
+  - **If an integration boundary was touched → integration-tester approved.**

package/releases/0.64.0/surfaces/integrations/tree/.claude/retrieval.md

@@ -0,0 +1,16 @@
+<!-- nina:slot integrations.1 -->
+
+## Integration docs (load whenever an integration is touched)
+
+`.claude/integrations/<slug>.md` holds the verified premises for one integration. The architect MUST cite premises from it — or add new ones, carrying the evidence the integration's kind requires — in any spec that touches the boundary. The integration-tester probes each cited premise before `qa` goes out.
+
+This project's integrations:
+
+<!-- nina:slot integrations.2 -->
+
+The integration-tester owns these docs. It creates one on first contact with a dependency and appends a premise whenever it observes behavior the doc does not yet carry, written against the version actually installed here or the response actually observed — never against the vendor's documentation.
+
+Read the doc's index and the premise sections your task cites. **Not the whole file:** an integration doc for a large dependency runs to thousands of lines, and reading it end to end is one of the biggest time sinks in this pipeline.
+
+<!-- nina:slot integrations.3 -->
+| Integration boundary change | `.claude/integrations/<slug>.md`, and the boundary module named in the profile | architect (cites premises) → implementer → reviewer + **integration-tester** → qa |

package/releases/0.64.0/surfaces/integrations/tree/.claude/router.md

@@ -0,0 +1,6 @@
+<!-- nina:slot integrations.1 -->
+
+### Integration-tester is a guardrail for integration boundaries
+Invoke **integration-tester** any time the diff touches the boundary module of a declared integration, or adds a call into one. It runs the real dependency, never a mock of it; for a `live-api` it runs the **contract-test suite against BOTH implementations**, so the mock can never pass while the live path is broken. No such change merges without its approval.
+
+The architect's spec MUST carry an **Integration premises** section: every behavior the implementation relies on, each with the evidence its kind requires — `<package dir>/node_modules/<lib>/<file>:<line>` with its version for an installed library, a contract case or an observed response for a live API, the local emulator for a platform binding. Never by inference. An architect `BLOCKED` on a live service's premise gets it observed by the integration-tester, then resumes with its report.

package/releases/0.64.0/surfaces/integrations/tree/CLAUDE.md

@@ -0,0 +1,17 @@
+<!-- nina:slot integrations.1 -->
+| **ANY integration surface** (the boundary module of a declared integration, or a new call into one) | architect cites a premise, with the evidence its kind requires, for every dependency behavior the code relies on; **+ integration-tester beside the reviewer** |
+
+<!-- nina:slot integrations.3 -->
+- **integration-tester** → mandatory gate on any integration boundary; runs the real dependency rather than a mock of it, and for a `live-api` runs the contract-test suite against both implementations so they cannot diverge; verifies every cited premise; keeps `.claude/integrations/<slug>.md` current
+
+<!-- nina:slot integrations.4 -->
+11. **Every integration has one boundary and one doc.** A dependency whose behavior you do not define — an installed library, a live third-party API, a platform binding — is reached through exactly ONE module, and nothing else speaks to it: no raw HTTP, SDK instance or binding handle in a route, service, queue consumer or scheduled handler. Each is declared in `.nina/profile.json` with its `kind` — a list, where it is more than one — and `boundary`, and documented at `.claude/integrations/<slug>.md`. A `live-api` carries two implementations behind one interface — the real client and a deterministic mock — and one contract-test suite that BOTH must pass; a mock that is green while the real client is not is a lie, and a hard reject.
+
+<!-- nina:slot integrations.5 -->
+12. **A premise about an integration requires a citation, and the form depends on the kind.** The architect MAY NOT state a dependency's behavior as fact without evidence: for an `installed-library`, `<package dir>/node_modules/<lib>/<file>:<line>` with the version installed here beside it — the package's own link, not the store directory a peer change renames, and for a dependency of a dependency, which no package links, its parent's: `<package dir>/node_modules/<parent> → <lib>@<version>/<file>:<line>`; for a `live-api`, a contract-test case or a response observed against the service and captured verbatim — observed by the integration-tester, before the spec when the design depends on it; for a `platform-binding`, behavior observed under the local emulator. An integration of two kinds — a client library over a platform binding — cites each premise by the kind it is about: the library's own behavior from its source, the binding's from the emulator. Vendor docs, a README, a changelog and recall are NOT citations. An uncited premise is an assumption, and the spec is rejected by the reviewer.
+
+<!-- nina:slot integrations.6 -->
+13. **Integration boundaries require the integration-tester gate before qa.** Any diff touching a boundary module, or adding a call into one, MUST pass the integration-tester, which runs beside the reviewer, before `qa` goes out. Unit-test mocks honor the spec, not the dependency — a mock is green because we wrote it that way. Only a run against the real thing, or a contract suite both implementations pass, catches drift.
+
+<!-- nina:slot integrations.7 -->
+- **an integration boundary**: a call to an external service, or a webhook or callback from one

package/releases/0.64.0/surfaces/money/tree/.claude/agents/architect.md

@@ -0,0 +1,12 @@
+<!-- nina:slot money.1 -->
+- **Money invariants** — if the spec touches distribution, transfer generation, or a send to the payment integration, explicitly confirm the design honors:
+    - Money is integer {{MINOR_UNIT}} end to end; percentages are basis points. Never a floating-point type.
+    - A distribution may NEVER exceed the amount → **block** (reject the operation, do not clamp it).
+    - A distribution **less** than the amount → **allow**, surface the shortfall, leave the remainder **parked** — never silently distributed.
+    - Transfers are **idempotent** — never sent twice. Dedupe happens at the serialization point, via the key, before the side effect.
+    - Every legal state transition writes an audit row (who / when / from → to). Illegal transitions throw.
+
+    If the design cannot satisfy all of these, redesign before submitting the spec.
+
+<!-- nina:slot money.2 -->
+- Design a money movement that can exceed the amount it distributes, silently absorb a shortfall, or send a transfer twice. If the design needs monetary computation, that computation lives in `{{CORE_PKG}}` as a pure function — never inline in a service or route.

package/releases/0.64.0/surfaces/money/tree/.claude/agents/dba.md

@@ -0,0 +1,14 @@
+<!-- nina:slot money.1 -->
+- **No cache on a read that feeds a money write.** Anything that loads an amount or a balance before computing, approving or dispatching a transfer MUST NOT be cached. A stale amount contaminates a real money movement, and that damage is not undone by fixing the cache afterwards. **Hard reject if violated.**
+
+<!-- nina:slot money.2 -->
+- **Monetary columns are integer.** Money is stored as an integer of the currency's minor unit ({{MINOR_UNIT}}); percentages are basis points. Reject `Decimal`, `Float`, or any type that can hold a fraction of the minor unit.
+
+<!-- nina:slot money.3 -->
+- **Money-integrity constraints.** When the change touches the record of an outbound transfer, verify the **unique constraint on its idempotency key** exists (`@unique` in the schema → `UNIQUE` in the migration SQL). That constraint is what still holds when the application-level guard fails; a missing or dropped one is a **hard reject**. Verify likewise any uniqueness the ownership model depends on. Report it in its own *Money-integrity* section, before the final verdict.
+
+<!-- nina:slot money.4 -->
+- Approve a cache policy on a query that feeds a money write.
+
+<!-- nina:slot money.5 -->
+- Approve a change to an outbound-transfer record that lacks the unique constraint on its idempotency key.

package/releases/0.64.0/surfaces/money/tree/.claude/agents/implementer.md

@@ -0,0 +1,11 @@
+<!-- nina:slot money.1 -->
+
+## Money invariants you MUST honor
+- **A distribution may NEVER exceed the amount** → block. Implement the reject; never clamp and continue.
+- **A shortfall is parked, not distributed.** Surface it and leave the remainder where it is — never auto-distribute it, never absorb it quietly.
+- **Transfers are idempotent — never sent twice.** Dedupe at the serialization point via the key, *before* the side effect. A retry, a re-delivered message or a double-click must not produce a second transfer.
+- **Every state transition writes an audit row** (entity, from → to, actor). No transition without a trail.
+- The deterministic money logic lives in `{{CORE_PKG}}` — call it as a pure function; never embed the arithmetic in a service.
+
+<!-- nina:slot money.2 -->
+- Embed money arithmetic (sums, deltas, value comparisons, distribution math) inline in a service. Computation lives in `{{CORE_PKG}}`.

package/releases/0.64.0/surfaces/money/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,3 @@
+<!-- nina:slot money.1 -->
+- **Confirm idempotency holds end to end.** Two sends with the same key → one logical transfer, no double send, and the serialization point refuses the second. This is the highest-blast-radius invariant in the system — drive it explicitly against the real service; do not infer it from reading the code.
+- **Confirm money crosses the boundary as an integer of the minor unit**, and that conversion happens only in the module that owns it — never in a service, never through a floating-point type.

package/releases/0.64.0/surfaces/money/tree/.claude/agents/reviewer.md

@@ -0,0 +1,23 @@
+<!-- nina:slot money.1 -->
+- **Enforce the money invariants. Each violation is a HARD REJECT → loop back to architect:**
+  - **A distribution may NEVER exceed the amount.** It is blocked, not clamped. A retention is just another destination — same arithmetic, in integer {{MINOR_UNIT}}.
+  - **A shortfall must be parked, not silently distributed.** The remainder stays where it is, and the shortfall is surfaced to whoever is owed it.
+  - **Transfers must be idempotent — never sent twice.** Every transfer carries a key, and dedupe happens at the serialization point before the side effect. A retry, a re-delivered message or a double-click must never produce a second transfer.
+  - **Every state transition writes an audit row** (entity type, id, from, to, actor) and follows the transitions declared in `.claude/architecture.md`. An undeclared transition, or one missing its audit row, is a hard reject.
+
+<!-- nina:slot money.2 -->
+- **money-invariants** — a distribution never exceeds the amount; a shortfall is parked, never
+  distributed; transfers idempotent at the serialization point; an audit row on every transition;
+  integer {{MINOR_UNIT}} and basis points; no arithmetic outside `{{CORE_PKG}}`.
+
+<!-- nina:slot money.3 -->
+- `{{CORE_PKG}}` money logic touched (distribution and transfer generation are high-blast-radius)
+
+<!-- nina:slot money.4 -->
+- Approve a change that lets a distribution exceed the amount, silently distributes a shortfall, sends a transfer without idempotent dedupe, or skips an audit row — those are hard rejects, loop back to architect.
+
+<!-- nina:slot money.5 -->
+- **If APPROVED:** ≤300 words. Sections: Verification commands run (typecheck/lint/build only — NEVER vitest), Spec-match (✅/❌ per item), Hard-rule checks (tenant scoping ✅, integer {{MINOR_UNIT}} / bps ✅, each gate the diff triggered ✅ (`.claude/graph.md`), money invariants ✅ — distribution ≤ amount, shortfall parked, idempotent transfer, audit row on transition), QA-attention flags (list any condition from the "stricter audit" list so QA knows what to focus on), Final verdict.
+
+<!-- nina:slot money.6 -->
+- Money invariant violated (distribution exceeds the amount, shortfall silently distributed, non-idempotent transfer, missing audit row) → back to **architect** for redesign.

package/releases/0.64.0/surfaces/money/tree/.claude/agents/secops.md

@@ -0,0 +1,5 @@
+<!-- nina:slot money.1 -->
+- **Money-movement abuse (Hard Rules #3, #4, #5)** — **the money path reaches a real service; this is not a stub audit.** Is the idempotency contract actually enforced at the seam — the unique key, the serialization point, and the dedupe happening *before* the side effect? Can a replay, a double-click, a queue redelivery, or a manual reset of processed state cause a double send? Can a distribution exceed the amount, or a shortfall be silently distributed? Is whatever authorizes money OUT forgeable — a webhook without a verified signature, a callback trusted on its word? Is every state transition forced through an audit write? Flag any seam that is structurally unable to enforce its invariant, even where nothing has exploited it yet.
+
+<!-- nina:slot money.2 -->
+- **Idempotency-key & replay surface** — keys unguessable and collision-resistant where it matters; dedup enforced before the side effect, not after.

package/releases/0.64.0/surfaces/money/tree/.claude/agents/solidity-auditor.md

@@ -0,0 +1,4 @@
+<!-- nina:slot money.1 -->
+- **The conservation property, asserted rather than argued.** Find the test that proves in equals
+  out plus retained, and check it holds on the adversarial paths too, not only the intended one.
+  Rounding that always favours the same party is a finding; so is a fee path with no upper bound.

package/releases/0.64.0/surfaces/money/tree/.claude/agents/solidity-dev.md

@@ -0,0 +1,4 @@
+<!-- nina:slot money.1 -->
+- **State the conservation property and assert it in the suite.** A contract that holds or routes an
+  amount has one — what goes in equals what goes out plus what is retained — and it belongs in a
+  test, not in a comment. Rounding is part of it: say which way it goes and who it favours.

package/releases/0.64.0/surfaces/money/tree/.claude/graph.md

@@ -0,0 +1,2 @@
+<!-- nina:slot money.1 -->
+- `reviewer` → `architect` on `REJECTED` — a money invariant is broken (a distribution over the amount, a shortfall distributed, a transfer that is not idempotent, a transition with no audit row): a design question before it is a code one · max 2