@xhulz/nina 0.28.16

package/releases/0.17.0/surfaces/db/tree/.claude/agents/reviewer.md

@@ -0,0 +1,25 @@
+<!-- nina:slot db.1 -->
+| `prisma-client-api` | a new or changed Prisma query |
+
+<!-- nina:slot db.2 -->
+- **If Prisma was touched anywhere in the diff: confirm `dba` ran and approved. If not → dispatch `dba` now, or request changes. No approval without dba sign-off on Prisma changes.**
+
+<!-- nina:slot db.3 -->
+- Check for **single-user tenant scoping** in every new Prisma query in app code: the `where` clause must include `userId` (or its model-specific FK equivalent). No "global" queries except the {{AUTH_LIB}} system tables. Missing scope = request changes.
+
+<!-- nina:slot db.4 -->
+- Check for N+1 queries when the DB layer was touched.
+
+<!-- nina:slot db.5 -->
+2. **tenant-and-privacy** — `userId` in every app query ({{AUTH_LIB}} tables are the only exemption);
+   no PII or secrets in logs; no cross-tenant read
+   or write reachable through a route, an MCP tool, a webhook, or a DO call.
+
+<!-- nina:slot db.6 -->
+- `{{DB_PKG}}/prisma/schema.prisma` touched (Prisma migration in play)
+
+<!-- nina:slot db.7 -->
+- Skip the dba check on Prisma changes "because it seems fine."
+
+<!-- nina:slot db.8 -->
+- Prisma touched but dba missed → dispatch **dba** now.

package/releases/0.17.0/surfaces/db/tree/.claude/agents/secops.md

@@ -0,0 +1,2 @@
+<!-- nina:slot db.1 -->
+- **AuthZ / tenant isolation (Hard Rule #7)** — single-user tenancy: EVERY app-code Prisma query must scope by `userId` (or its FK). Hunt for any query, route, MCP tool, or DO/queue/webhook path where another user's data could be read or mutated (IDOR). The {{AUTH_LIB}} system tables are the only allowed unscoped reads — verify nothing else is.

package/releases/0.17.0/surfaces/db/tree/.claude/agents-overview.md

@@ -0,0 +1,5 @@
+<!-- nina:slot db.1 -->
+- **DBA guardrail** → Prisma / Postgres is the surface where a bad change causes hard-to-reverse damage. Schema mistakes, missing indexes, cache on reads that feed a correctness-critical write, missing `userId` scope — all caught here.
+
+<!-- nina:slot db.2 -->
+| **dba** | Mandatory gate on Prisma changes and new queries | `.claude/agents/dba.md` |

package/releases/0.17.0/surfaces/db/tree/.claude/patterns.md

@@ -0,0 +1,30 @@
+<!-- nina:slot db.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot db.2 -->
+1. Routes must NOT import query functions (`list*`, `find*`, `get*`, `upsert*`, `delete*`) from `{{DB_PKG_NAME}}`. Only `createDbClient` and error classes.
+
+<!-- nina:slot db.3 -->
+4. `cacheStrategy` lives in `{{DB_PKG}}`. Services do not add, strip, or override cache policies.
+
+<!-- nina:slot db.4 -->
+5. **Every service query includes `userId` (tenant scope) in the `where` clause.** Missing scope = automatic CHANGES REQUESTED.
+
+<!-- nina:slot db.5 -->
+
+---
+
+## Prisma conventions (enforced by dba subagent)
+
+- Schema lives in `{{DB_PKG}}/prisma/schema.prisma`. Nowhere else.
+- **Never write raw SQL** unless justified in a code comment with perf data.
+- **Every `findUnique` / `findMany` on a hot path defines `cacheStrategy`.** No implicit cache.
+- **NEVER cache a read that feeds a write whose correctness depends on it being fresh.** A stale row contaminates the decision made from it. Hard reject in dba review.
+- **Every query in app code includes `userId` in the `where` clause** (or its model-specific equivalent FK). Tenant isolation is in the data layer. The {{AUTH_LIB}} system tables are the only exemption.
+- Migrations reviewed by **dba** for: non-blocking on large tables, index coverage for new query patterns, backward compatibility during rolling deploy.
+- N+1 queries are a bug. Use `include` / `select` deliberately.
+- Monetary columns are `BigInt`. Reject `Decimal` / `Float` / `Int` for money.
+- `Prisma Postgres` is connected only via Accelerate. Local dev uses the same Accelerate URL pointed at a dev DB; never embed a direct connection string in code.
+
+<!-- nina:slot db.6 -->
+- Real Prisma (Accelerate against a test DB). Never mock Prisma.

package/releases/0.17.0/surfaces/db/tree/.claude/pipeline.md

@@ -0,0 +1,16 @@
+<!-- nina:slot db.1 -->
+
+### 4. DBA (mandatory for Prisma)
+
+- **Trigger:** any change in `schema.prisma`, any new Prisma query, any migration.
+- **Input:** Prisma diff + application code using the queries.
+- **Output:** approve or reject with specific issues.
+- **Tools:** Read, Grep, Glob, Bash (`prisma validate`, `prisma migrate diff`, query plan checks).
+- **Checks:** schema validates; migration safe on large tables; index coverage; explicit `cacheStrategy` on hot reads; **no cache on a read that feeds a correctness-critical write**; **`userId` scope in every query**; no N+1; money columns are `BigInt`; no raw PII without encryption; secrets via Wrangler.
+- **Position:** dispatched mid-pipeline by whoever detects Prisma. Reviewer verifies dba ran.
+
+<!-- nina:slot db.2 -->
+  - **If Prisma touched → dba approved.**
+
+<!-- nina:slot db.3 -->
+- **DBA flags migration as unsafe** → architect redesigns migration strategy.

package/releases/0.17.0/surfaces/db/tree/.claude/retrieval.md

@@ -0,0 +1,5 @@
+<!-- nina:slot db.1 -->
+| Prisma schema change | `.claude/architecture.md` § *Database*, `{{DB_PKG}}/prisma/schema.prisma` | **dba** (mandatory) → reviewer → qa |
+
+<!-- nina:slot db.2 -->
+| New Prisma query in app code | `.claude/patterns.md` § *Prisma conventions* | **dba** (mandatory) → reviewer → qa |

package/releases/0.17.0/surfaces/db/tree/.claude/router.md

@@ -0,0 +1,10 @@
+<!-- nina:slot db.1 -->
+
+### 1. DBA is a guardrail, not a stage
+Invoke **dba** any time Prisma is touched — regardless of where you are in the pipeline. No Prisma change merges without dba approval. Reviewer verifies dba ran.
+
+<!-- nina:slot db.2 -->
+| any `prisma` CLI command | **`prisma-cli`** |
+
+<!-- nina:slot db.3 -->
+| a new or changed Prisma query | **`prisma-client-api`** (a caching or edge layer on top of the client is not covered — its own integration doc owns that) |

package/releases/0.17.0/surfaces/db/tree/CLAUDE.md

@@ -0,0 +1,20 @@
+<!-- nina:slot db.1 -->
+| Run any `prisma` CLI command (dba, integration-tester, devops) | `prisma-cli` | flags differ between versions; `migrate diff --shadow-database-url` against a live DB wiped dev/staging once |
+
+<!-- nina:slot db.2 -->
+| Write or audit a Prisma query (architect, implementer, dba, reviewer) | `prisma-client-api` | filters, operators, `$transaction` semantics. a caching or edge layer on top of the client is **NOT covered** — its cache strategy belongs to that layer's own integration doc |
+
+<!-- nina:slot db.3 -->
+| **ANY Prisma change (`*.prisma` or new query)** | **+ dba before reviewer** |
+
+<!-- nina:slot db.4 -->
+- **dba** → mandatory gate on Prisma schema changes, migrations, and new queries
+
+<!-- nina:slot db.5 -->
+2. **Every Prisma change goes through the dba subagent.** No exceptions. Reviewer must verify dba ran before approving.
+
+<!-- nina:slot db.6 -->
+6. **Every hot Prisma read defines a `cacheStrategy`** (Accelerate `ttl` / `swr`). Implicit cache is a bug. **Never cache a read that feeds a write whose correctness depends on it being fresh** — a stale row contaminates every decision made from it. User-scoped invalidation on every write.
+
+<!-- nina:slot db.7 -->
+7. **Tenant isolation is enforced in the data layer.** Every Prisma query in app code includes `userId` (the tenant) in the `where` clause. No "global" queries except the {{AUTH_LIB}} system tables. Reviewer rejects any query missing the scope.

package/releases/0.17.0/surfaces/edge-cf/tree/.claude/agents/architect.md

@@ -0,0 +1,14 @@
+<!-- nina:slot edge-cf.1 -->
+| `cloudflare:workers-best-practices` | `{{API_DIR}}/**` — routes, services, middleware, queue handlers |
+
+<!-- nina:slot edge-cf.2 -->
+| `cloudflare:durable-objects` | `{{API_DIR}}/src/do/**` or any DO call site |
+
+<!-- nina:slot edge-cf.3 -->
+| `cloudflare:cloudflare` | Queues, R2 or KV |
+
+<!-- nina:slot edge-cf.4 -->
+| `cloudflare:wrangler` | `wrangler.toml` or any wrangler command |
+
+<!-- nina:slot edge-cf.5 -->
+14. **Cloudflare skill flag** — if the spec touches `{{API_DIR}}/**` (Hono routes/services/queue handlers), the per-account Durable Object, Queues, R2/KV, or `wrangler` config, name which `cloudflare:*` plugin skill the implementer must consult (`cloudflare:workers-best-practices`, `cloudflare:durable-objects`, `cloudflare:cloudflare`, `cloudflare:wrangler`), or state why none applies. Retrieval beats recall — the reviewer rejects a spec that touches these surfaces without naming the skill.

package/releases/0.17.0/surfaces/edge-cf/tree/.claude/agents/dba.md

@@ -0,0 +1,2 @@
+<!-- nina:slot edge-cf.1 -->
+13. **Edge runtime compatibility.** New code paths use `@prisma/client/edge`. `compatibility_flags = ["nodejs_compat"]` is set in `wrangler.toml`.

package/releases/0.17.0/surfaces/edge-cf/tree/.claude/agents/devops.md

@@ -0,0 +1,31 @@
+<!-- nina:slot edge-cf.1 -->
+- **`cloudflare:wrangler`** — before running ANY `wrangler` command or reading `wrangler.toml`.
+  CLI flags and config fields churn between minor versions; pre-trained knowledge is stale.
+
+<!-- nina:slot edge-cf.2 -->
+- **`cloudflare:cloudflare`** — when the deploy touches R2, KV, Queues or Durable Object bindings.
+
+<!-- nina:slot edge-cf.3 -->
+2. **Both targets, or neither.** A change to the API surface needs the **staging Worker** (`wrangler deploy --env staging`) *and* **Pages** (`pnpm --filter {{PKG_SCOPE}}/app deploy`). Deploying the frontend alone against an old API is the failure that renders new fields as "—". State explicitly which targets this change requires and why.
+
+<!-- nina:slot edge-cf.4 -->
+5. **Secret and variable parity.** Everything the new code reads via `env.*` exists in the target environment (`wrangler secret list`). A missing secret fails at request time, not at deploy time.
+
+<!-- nina:slot edge-cf.5 -->
+
+## Pages: which branch, and why it matters
+
+`{{PAGES_PROJECT}}` is a **direct-upload** Pages project whose production branch is `main`. `wrangler pages
+deploy` decides production vs preview purely from `--branch`:
+
+- **Staging FE** → `--branch staging`. A preview deployment on its own URL. Production is untouched,
+  and this is the FE half of the staging pair with `{{API_STAGING}}`.
+- **Production FE** → `--branch main`. Only with an explicit go from {{OWNER}}, per the rule above.
+
+Deploying staging with `--branch=main` is a production deploy wearing a staging label — the
+permission classifier is right to stop it. Use the staging branch and the block disappears, because
+the block was correct.
+
+**`VITE_*` must be in the environment of the build command.** `[vars]` and `[env.*.vars]` in
+`{{APP_DIR}}/wrangler.toml` do NOT reach a Vite build — Vite inlines at build time, Pages vars apply at
+runtime to a project that has no server. A missing one ships a blank page with no error.

package/releases/0.17.0/surfaces/edge-cf/tree/.claude/agents/implementer.md

@@ -0,0 +1,14 @@
+<!-- nina:slot edge-cf.1 -->
+| `cloudflare:workers-best-practices` | anything under `{{API_DIR}}/**` |
+
+<!-- nina:slot edge-cf.2 -->
+| `cloudflare:durable-objects` | anything under `{{API_DIR}}/src/do/**` or a DO call site |
+
+<!-- nina:slot edge-cf.3 -->
+| `cloudflare:cloudflare` | a queue consumer, or R2 / KV access |
+
+<!-- nina:slot edge-cf.4 -->
+| `cloudflare:wrangler` | a change to `wrangler.toml` |
+
+<!-- nina:slot edge-cf.5 -->
+- Respect Workers conventions: secrets in `{{SECRETS_LOCAL}}` for local dev (never commit), `compatibility_flags = ["nodejs_compat"]` in `wrangler.toml`.

package/releases/0.17.0/surfaces/edge-cf/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,11 @@
+<!-- nina:slot edge-cf.1 -->
+| `cloudflare:durable-objects` | DO lifecycle, alarms, RPC, storage — the API surface drifts fast |
+
+<!-- nina:slot edge-cf.2 -->
+| `cloudflare:cloudflare` | Queues, R2 or KV bindings |
+
+<!-- nina:slot edge-cf.3 -->
+| `cloudflare:wrangler` | anything you run through the wrangler CLI |
+
+<!-- nina:slot edge-cf.4 -->
+- Any new Cloudflare binding read/write: R2, KV, Queues, Durable Objects — drive the binding via Miniflare and observe real I/O

package/releases/0.17.0/surfaces/edge-cf/tree/.claude/agents/qa.md

@@ -0,0 +1,3 @@
+<!-- nina:slot edge-cf.1 -->
+Here `$STRAY` is `vitest|workerd`: a Worker test boots a second runtime process alongside vitest,
+and it is the one that holds ~2 GB and survives a killed test run.

package/releases/0.17.0/surfaces/edge-cf/tree/.claude/agents/reviewer.md

@@ -0,0 +1,8 @@
+<!-- nina:slot edge-cf.1 -->
+| `cloudflare:workers-best-practices` | `{{API_DIR}}/**` |
+
+<!-- nina:slot edge-cf.2 -->
+| `cloudflare:durable-objects` | `{{API_DIR}}/src/do/**` or a DO call site |
+
+<!-- nina:slot edge-cf.3 -->
+- `{{API_DIR}}/src/do/`, a queue consumer, or a webhook receiver touched (serialization + idempotency surface)

package/releases/0.17.0/surfaces/edge-cf/tree/.claude/agents/secops.md

@@ -0,0 +1,8 @@
+<!-- nina:slot edge-cf.1 -->
+- **Secrets & config exposure** — no secrets in committed files, logs, error messages, or generated artifacts (`worker-configuration.d.ts` must contain only types, never values). `{{SECRETS_LOCAL}}`/`.env` gitignored. `wrangler secret`/`[vars]` split correct. No secret echoed in a response or thrown error.
+
+<!-- nina:slot edge-cf.2 -->
+- **Dependency & binding posture** — obviously risky dependency usage; Cloudflare binding scoping (R2 bucket names, Queue, DO) — nothing over-privileged or world-exposed; `nodejs_compat` and compatibility flags sane.
+
+<!-- nina:slot edge-cf.3 -->
+- Prefer retrieval over recall for Cloudflare/{{AUTH_LIB}} specifics: consult the `cloudflare:*` skills and the installed `node_modules` source / `.claude/integrations/*.md` rather than assuming.

package/releases/0.17.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 -->
+- `compatibility_flags = ["nodejs_compat"]` in `wrangler.toml` is required for `@prisma/client/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.17.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 → **integration-tester** → reviewer → qa |
+
+<!-- nina:slot edge-cf.2 -->
+| New Queue handler | `.claude/architecture.md` § *Processing pipeline*, `{{API_DIR}}/src/queues/` | architect → implementer → **integration-tester** → reviewer → qa |
+
+<!-- nina:slot edge-cf.3 -->
+| Wrangler / deploy / config | `CLAUDE.md` § *Common commands*, `{{API_DIR}}/wrangler.toml`, `.claude/patterns.md` § *Secrets* | reviewer (sanity check) |

package/releases/0.17.0/surfaces/edge-cf/tree/.claude/router.md

@@ -0,0 +1,21 @@
+<!-- nina:slot edge-cf.1 -->
+| `{{API_DIR}}/**` Hono routes / services / middleware / queue handlers | `cloudflare:workers-best-practices` |
+
+<!-- nina:slot edge-cf.2 -->
+| `{{API_DIR}}/src/do/**` or any DO call site | `cloudflare:durable-objects` |
+
+<!-- nina:slot edge-cf.3 -->
+| `{{API_DIR}}/src/queues/**`, R2/KV | `cloudflare:cloudflare` |
+
+<!-- nina:slot edge-cf.4 -->
+| `wrangler.toml` / `wrangler.jsonc` / any wrangler CLI | `cloudflare:wrangler` |
+
+<!-- nina:slot edge-cf.5 -->
+| **devops** running any wrangler command or deploy | **`cloudflare:wrangler`** (+ `cloudflare:cloudflare` for R2/KV/Queues/DO bindings) |
+
+<!-- nina:slot edge-cf.6 -->
+
+Irrelevant to {{PROJECT}} (do NOT invoke): `cloudflare:agents-sdk`, `cloudflare:sandbox-sdk`, `cloudflare:cloudflare-email-service`.
+
+<!-- nina:slot edge-cf.7 -->
+The `cloudflare@cloudflare` plugin (user-scope) is where this project's skills come from.

package/releases/0.17.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}}/**` (Hono 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 -->
+
+Skills NOT relevant to {{PROJECT}} (skip them): `cloudflare:agents-sdk` (no agent runtime), `cloudflare:sandbox-sdk` (no untrusted code execution), `cloudflare:cloudflare-email-service` ({{AUTH_LIB}} handles magic-link email).
+
+<!-- nina:slot edge-cf.8 -->
+10. **Secrets in `{{SECRETS_LOCAL}}` for local dev, `{{SECRETS_PROD}}` for production.** Never `.env` committed. `compatibility_flags = ["nodejs_compat"]` is required in `wrangler.toml` for any database client that runs at the edge.

package/releases/0.17.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 jsdom checks while being 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.17.0/surfaces/frontend/tree/.claude/agents/devops.md

@@ -0,0 +1,25 @@
+<!-- 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 -->
+3. **Build-time env.** Vite inlines `VITE_*` at build time, so a variable the deploy platform supplies at RUNTIME never reaches the bundle — it is not late, it is absent. Verify every `VITE_*` 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 `VITE_API_BASE_URL` was missing from the deploy build, which is exactly
+what happened here once.
+
+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.

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

@@ -0,0 +1,17 @@
+<!-- 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
+runs in jsdom, which has no layout engine 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.

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

@@ -0,0 +1,17 @@
+<!-- nina:slot frontend.1 -->
+
+## What your green does not mean
+
+Your suite runs in jsdom, which has **no layout engine**. `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.17.0/surfaces/frontend/tree/.claude/agents/reviewer.md

@@ -0,0 +1,57 @@
+<!-- nina:slot frontend.1 -->
+tools: Read, Grep, Glob, Bash, WebFetch, Skill, 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.2 -->
+- **If the diff touches `{{APP_DIR}}/**`: the spec must carry a Visual acceptance section, and you check the render against it — see *Visual gate* below.** No section → REJECT upstream to the architect.
+
+<!-- nina:slot frontend.3 -->
+- `pnpm build` 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 in
+jsdom, which has **no layout engine**: `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 — you already run `pnpm build` for frontend diffs; serve that build locally.
+   Every protected screen redirects to `/login` without a session, so a plain static server
+   screenshots the login page. Use `scripts/visual-fixture-server.mjs`, which serves the built
+   `dist` AND a canned API from ONE origin (no auth, no DB, no Worker):
+
+   ```bash
+   export PATH=/opt/homebrew/opt/node@22/bin:$PATH
+   cd {{APP_DIR}} && VITE_API_BASE_URL=http://localhost:5199 npx vite build --outDir /tmp/dist-vis
+   node ../../scripts/visual-fixture-server.mjs /tmp/dist-vis 5199
+   ```
+
+   `VITE_API_BASE_URL` must match the fixture's origin at BUILD time — Vite inlines it, and a
+   mismatch ships a screen that renders but fetches nothing. The fixture logs `UNSTUBBED: <path>`
+   for any endpoint it does not know; add a handler there rather than screenshotting a broken
+   screen. `FIXTURE_EMPTY=1` switches list endpoints to `[]` to exercise empty states, and
+   `FIXTURE_ERROR=<CODE>` fails every write with that error code so an error state is
+   reachable at all — otherwise reaching one means finding real data that collides, which
+   usually means you cannot reach it.
+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. Tabs on `/identification` and `/settings` are local
+   React state, never reflected 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.
+2b. **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 (`/dashboard`) — and, when it matters, build the
+   parent commit into a second dist 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.
+3. Check each screenshot against the spec's **Visual acceptance** list, item by item. Not "looks
+   fine" — the specific claims the spec made.
+4. `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.

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

@@ -0,0 +1,15 @@
+<!-- nina:slot frontend.1 -->
+
+---
+
+## Frontend (Vite + React) conventions
+
+- React **function components, hooks only**. No class components.
+- **TanStack Query for all server state.** Never fetch in `useEffect`.
+- **shadcn/ui + Tailwind** for styling. No CSS modules, no styled-components, no Emotion.
+- **Single-app layout:** `{{APP_DIR}}` serves all roles (`user`, `admin`) with a role-aware sidebar. Routes live in `{{APP_DIR}}/src/routes/`.
+- **Reusable UI and utilities belong in `packages/web-shared` (`{{PKG_SCOPE}}/web-shared`)** when they are stable cross-cutting primitives: `apiFetch`, {{AUTH_LIB}} client, hooks (`useAuth`, `useMe`, `useAccount`, etc.), `AuthGuard`, all shadcn `ui/*`, `formatBrl`/`parseBrl`, test helpers, the Tailwind preset.
+  - Import shadcn primitives from `{{PKG_SCOPE}}/web-shared/components/ui/<name>`.
+  - Import `formatBrl` / `parseBrl` from `{{PKG_SCOPE}}/web-shared/lib`.
+- **App-specific UI stays in `{{APP_DIR}}/src/components/`** when not consumed elsewhere.
+- No global state libs unless genuinely global (auth user, active account). Prefer URL state and TanStack Query cache.

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

@@ -0,0 +1,5 @@
+<!-- nina:slot frontend.1 -->
+| Frontend (single app — `{{APP_DIR}}`) | `.claude/architecture.md` § *Frontend*, `{{APP_DIR}}/src/routes/` | implementer → reviewer → qa |
+
+<!-- nina:slot frontend.2 -->
+| Shared frontend code (`packages/web-shared`) | `.claude/patterns.md` § *Frontend conventions*, `packages/web-shared/package.json` | architect → implementer → reviewer → qa |

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

@@ -0,0 +1,17 @@
+<!-- nina:slot frontend.1 -->
+| `{{APP_DIR}}/**` page-load perf audit (LCP/INP/CLS/bundle) | `cloudflare:web-perf` |
+
+<!-- nina:slot frontend.2 -->
+
+### 6c. Nothing before devops can see the screen
+The reviewer reads a diff. qa runs vitest in jsdom, which has **no layout engine** — `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.17.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 **reviewer builds, serves and screenshots at 1440 and 375** and rejects on a mismatch; devops smokes the deployed preview for a blank page. jsdom has no layout engine — a green suite says nothing about the screen |

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

@@ -0,0 +1,16 @@
+<!-- nina:slot integrations.1 -->
+12. **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` → `node_modules/.pnpm/<lib>@<version>/.../<file>:<line>`, from the version installed here
+    - `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, or call the service and keep the response. 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 exercise the service and keep the response. 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.17.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.17.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.17.0/surfaces/integrations/tree/.claude/agents/planner.md

@@ -0,0 +1,2 @@
+<!-- nina:slot integrations.1 -->
+5. **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.17.0/surfaces/integrations/tree/.claude/agents/reviewer.md

@@ -0,0 +1,14 @@
+<!-- nina:slot integrations.1 -->
+- **If an integration boundary was touched anywhere in the diff, or a new call into one was added: confirm `integration-tester` ran and approved.** If not → dispatch it now, or request changes. Additionally 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 -->
+- Skip the integration-tester check "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 but integration-tester missed → dispatch **integration-tester** now.
+
+<!-- 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).

package/releases/0.17.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.17.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