@xhulz/nina 0.30.0 → 0.32.0

package/releases/0.32.0/surfaces/blockchain/tree/.claude/graph.md

@@ -0,0 +1,11 @@
+<!-- nina:slot blockchain.1 -->
+- `solidity-dev` — writes contract code, which cannot be changed once it is live
+- `solidity-auditor` — gate: audits contract code as an attacker before anything deploys
+
+<!-- nina:slot blockchain.2 -->
+- `architect` → `solidity-dev` on `SPEC-READY` — the spec changes contract code
+- `solidity-dev` → `solidity-auditor` on `DIFF-READY`
+- `solidity-dev` → `architect` on `BLOCKED` — the change cannot be made safely as specified · max 2
+- `solidity-auditor` → `reviewer` on `APPROVED`
+- `solidity-auditor` → `solidity-dev` on `REJECTED` — a flaw in the contract code · max 2
+- `solidity-auditor` → `architect` on `REJECTED` — a flaw in the design · max 2

package/releases/0.32.0/surfaces/blockchain/tree/.claude/router.md

@@ -0,0 +1,6 @@
+<!-- nina:slot blockchain.1 -->
+
+### Solidity-auditor is a guardrail for contract changes
+Invoke **solidity-auditor** on any diff that touches `{{CONTRACTS_DIR}}`, a deploy script, or the version of a contracts library — regardless of where you are in the pipeline. No contract change merges without its approval, and none deploys without it. Reviewer verifies it ran; devops verifies it approved.
+
+Contract sources are written by **solidity-dev**, not the implementer. Route the work there when the spec's file list reaches `{{CONTRACTS_DIR}}`, and keep the implementer on the off-chain side of the same feature.

package/releases/0.32.0/surfaces/blockchain/tree/CLAUDE.md

@@ -0,0 +1,12 @@
+<!-- nina:slot blockchain.1 -->
+16. **Every contract change goes through the solidity-auditor gate, and deployed code is never patched in place.** A diff touching a contract source, a deploy script, or the version of a contracts library does not reach the reviewer without `VERDICT: APPROVED` from **solidity-auditor**, and does not reach any network without it. Contract sources are written by **solidity-dev**, not by the implementer — the implementer's rules assume a defect is a patch away, and here it is a redeploy or a proxy upgrade at best. Private keys, mnemonics and funded accounts never enter the repository in any form, test fixtures included.
+
+<!-- nina:slot blockchain.2 -->
+| **ANY step touching a contract, a deploy script, or a contracts library version** | **architect → solidity-dev → solidity-auditor → reviewer → qa** — the auditor is mandatory and blocks the reviewer |
+
+<!-- nina:slot blockchain.3 -->
+- **solidity-dev** → write contract sources and their adversarial tests strictly to spec; never deploys, never widens access control to make a test pass
+- **solidity-auditor** → **mandatory gate** on any contract diff; `APPROVED` required before reviewer and before any deploy
+
+<!-- nina:slot blockchain.4 -->
+- **contract code**: a contract source, a deploy script, or the version of a contracts library

package/releases/0.32.0/surfaces/db/tree/.claude/agents/architect.md

@@ -0,0 +1,5 @@
+<!-- nina:slot db.2 -->
+- **Tenant-scope impact** — state where `{{TENANT_KEY}}` is enforced. Every new query in app code filters by it, or reaches it through the model's foreign keys; only the auth library's own tables are exempt.
+
+<!-- nina:slot db.3 -->
+- **Database flag** — if the schema or a new query is touched, mark **"DBA REQUIRED"** prominently at the top of the spec, and name each new read's cache policy, or **`NO_CACHE`** for a read that feeds a write whose correctness depends on it being fresh — a stale row contaminates every decision made from it.

package/releases/0.32.0/surfaces/db/tree/.claude/agents/dba.md

@@ -0,0 +1,50 @@
+<!-- nina:slot db.3 -->
+- Any change to the schema.
+- Any new query, or change to one, anywhere in application code.
+- Any migration.
+
+<!-- nina:slot db.4 -->
+- The schema diff, and the migration SQL it generates.
+- The application code that uses the new or modified queries.
+
+<!-- nina:slot db.5 -->
+**Read `.claude/code-map.md`** when the change touches new query patterns — it lists which services consume which models, so you can spot N+1 risk and consumer-side cache implications without re-grepping. (Before there is code, fall back to `.claude/architecture.md` § *Database* for the planned schema and its cache policies.)
+
+<!-- nina:slot db.6 -->
+- **The schema validates, and you read the migration's SQL** — offline, from files, with the project's own schema tooling. A check that seems to need a database URL is one you report as impossible, not one you run.
+
+<!-- nina:slot db.8 -->
+- **Migration safety on large tables:**
+   - No `ALTER TABLE ... ADD COLUMN NOT NULL` without a safe default (causes lock + rewrite).
+   - No operations that hold long locks without an explicit batched strategy.
+   - Non-breaking for rolling deploy — old application code and new schema must coexist during the deploy window.
+
+<!-- nina:slot db.9 -->
+- **Index coverage.** Every new query pattern (`WHERE`, `ORDER BY`, `JOIN`, `aggregate`) must be backed by an index declared in the schema. Reject queries that would table-scan. The most-used compound index is `(<tenant>, <other>)` or, for models keyed by a parent entity, `(<parentId>, <other>)`; verify the leading column matches the query.
+
+<!-- nina:slot db.10 -->
+- **Tenant scope.** Every query in app code filters by `{{TENANT_KEY}}`, or by the foreign-key chain that resolves back to it. The auth library's own tables are the only exemption. Reject any app query missing the scope.
+
+<!-- nina:slot db.11 -->
+- **Cache discipline.** A cached read names its policy explicitly — **an implicit cache is a bug: reject it** — checked against the cache policies in `.claude/architecture.md` § *Database*. A read that feeds a write whose correctness depends on it being fresh is never cached.
+
+<!-- nina:slot db.12 -->
+- **N+1 patterns.** If the code fetches a list then queries per item, reject with "fetch the related rows with the list, or batch."
+
+<!-- nina:slot db.13 -->
+- **Secrets.** The database's connection string comes from `{{SECRETS_LOCAL}}` locally and `{{SECRETS_PROD}}` in production — never a committed `.env`, never a literal in code.
+
+<!-- nina:slot db.14 -->
+- **Run anything that can write to a real database.** You are a read-only gate: against a live database you run read-only queries and nothing else. If a check seems to require writing, it does not — report the limitation to the orchestrator instead.
+
+<!-- nina:slot db.15 -->
+- Approve without validating the schema and reading the migration's SQL, offline, as *You MUST check* says.
+
+<!-- nina:slot db.16 -->
+- Wave through "small" schema changes. Small changes cause the worst production incidents.
+
+<!-- nina:slot db.17 -->
+- Approve a query in app code missing its `{{TENANT_KEY}}` scope, or the foreign key that owns it.
+
+<!-- nina:slot db.18 -->
+**Final report format:** ≤300 words if approved. Sections: Schema validation result, Migration SQL preview (verbatim if non-trivial), Index analysis, Tenant-scope check, Cache verdict, Privacy check, Final verdict. If rejected, list each issue with required action — no length cap.

package/releases/0.32.0/surfaces/db/tree/.claude/agents/devops.md

@@ -0,0 +1,5 @@
+<!-- nina:slot db.2 -->
+- **Migrations, in order, against the right database.** Confirm the target is the database you intend, and that the migration is backward-compatible with the code already deployed, because the two are live together during the rollout.
+
+<!-- nina:slot db.5 -->
+- **Migrations:** applied / none, with the database they hit.

package/releases/0.32.0/surfaces/db/tree/.claude/agents/implementer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot db.2 -->
+- If you change the schema or write a new query, flag it explicitly in the diff summary: it triggers the **dba** gate.

package/releases/0.32.0/surfaces/db/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,10 @@
+<!-- nina:slot db.2 -->
+- A new query on a cached read path — verify the cache's behavior live (dba covers the schema; you cover how the cache behaves at runtime)
+
+<!-- nina:slot db.3 -->
+If a query behaves differently against a real database than the dba's static analysis suggested, escalate to **dba** — do not fix it yourself.
+
+<!-- nina:slot db.4 -->
+- **The auth library's backing store is a real database** — the development database, the same
+  connection the implementer uses from `{{SECRETS_LOCAL}}`. A suite that is green against an
+  in-memory stand-in has not exercised the library, which is the whole point of this stage.

package/releases/0.32.0/surfaces/db/tree/.claude/agents/planner.md

@@ -0,0 +1,2 @@
+<!-- nina:slot db.1 -->
+- **Database flag** — if any subtask may touch the schema or create a new query, mark **"DBA REQUIRED"** on that subtask.

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

@@ -0,0 +1,22 @@
+<!-- nina:slot db.2 -->
+- **If the schema, a migration or a query was touched anywhere in the diff: name `dba` on your Gates line.** Its approval is what a database change needs; yours does not stand in for it.
+
+<!-- nina:slot db.3 -->
+- Check for **tenant scoping** in every new query in app code: it filters by `{{TENANT_KEY}}`, or reaches it through the model's foreign keys. No "global" queries except the auth library's own tables. Missing scope = `REJECTED`.
+
+<!-- nina:slot db.4 -->
+- Check for N+1 queries when the DB layer was touched.
+
+<!-- nina:slot db.5 -->
+- **tenant-and-privacy** — `{{TENANT_KEY}}` in every app query (the auth library's own 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 an RPC between services.
+
+<!-- nina:slot db.6 -->
+- The schema touched (a migration in play)
+
+<!-- nina:slot db.7 -->
+- Leave `dba` off your Gates line on a database change "because it seems fine."
+
+<!-- nina:slot db.8 -->
+- Schema or query touched and `dba` not dispatched → name it on your Gates line; the orchestrator sends it.

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

@@ -0,0 +1,2 @@
+<!-- nina:slot db.1 -->
+- **AuthZ / tenant isolation (Hard Rule #7)** — EVERY query in app code scopes by `{{TENANT_KEY}}` (or its foreign key). Hunt for any query, route, MCP tool, or queue, webhook or background path where another tenant's data could be read or mutated (IDOR). The auth library's own tables are the only allowed unscoped reads — verify nothing else is.

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

@@ -0,0 +1,5 @@
+<!-- nina:slot db.1 -->
+- **DBA guardrail** → the database 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 tenant scope — all caught here.
+
+<!-- nina:slot db.2 -->
+| **dba** | Mandatory gate on schema changes, migrations and new queries | `.claude/agents/dba.md` |

package/releases/0.32.0/surfaces/db/tree/.claude/graph.md

@@ -0,0 +1,8 @@
+<!-- nina:slot db.1 -->
+- `dba` — gate: runs when the schema, a migration or a query is touched
+
+<!-- nina:slot db.2 -->
+- `implementer` → `dba` on `DIFF-READY` — the diff touches the schema, a migration or a query
+- `dba` → `qa` on `APPROVED` — once the reviewer, and every other gate the diff went to, approved too
+- `dba` → `implementer` on `REJECTED` — a query or schema change in the diff is unsafe · max 2
+- `dba` → `architect` on `REJECTED` — the spec's migration or data design is unsafe · max 2

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

@@ -0,0 +1,19 @@
+<!-- nina:slot db.2 -->
+- Routes must NOT import query functions (`list*`, `find*`, `get*`, `upsert*`, `delete*`) from `{{DB_PKG_NAME}}` — only its client and its error classes.
+
+<!-- nina:slot db.4 -->
+- **Every service query filters by `{{TENANT_KEY}}` (tenant scope).** Missing scope = automatic `REJECTED`.
+
+<!-- nina:slot db.5 -->
+
+---
+
+## Database conventions (enforced by the dba subagent)
+
+- **A cached read names its policy, and a read that feeds a write whose correctness depends on it being fresh is NEVER cached.** A stale row contaminates the decision made from it. Hard reject in dba review.
+- **Every query in app code filters by `{{TENANT_KEY}}`** (or reaches it through the model's foreign keys). Tenant isolation is in the data layer. The auth library's own 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.
+
+<!-- nina:slot db.6 -->
+- A real database, never a mock of its client.

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

@@ -0,0 +1,13 @@
+<!-- nina:slot db.1 -->
+
+### DBA (mandatory for the database)
+
+- **Trigger:** any schema change, any new query, any migration.
+- **Input:** the schema diff and its migration SQL + the application code using the queries.
+- **Output:** `APPROVED`, or `REJECTED` with specific issues.
+- **Tools:** Read, Grep, Glob, Bash (schema validation, an offline migration diff, query-plan checks).
+- **Checks:** schema validates; migration safe on large tables; index coverage; an explicit policy on every cached read; **no cache on a read that feeds a correctness-critical write**; **tenant scope in every query**; no N+1; no raw PII without encryption; the connection secret comes from the environment, never from code.
+- **Position:** beside the reviewer, when a diff touches the schema, a migration or a query; `qa` waits for its `APPROVED`.
+
+<!-- nina:slot db.2 -->
+  - **If the schema or a query was touched → dba approved.**

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

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

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

@@ -0,0 +1,4 @@
+<!-- nina:slot db.1 -->
+
+### DBA is a guardrail, not a stage
+Invoke **dba** any time the schema, a migration or a query is touched — regardless of where you are in the pipeline. No such change reaches qa without dba approval; the reviewer names it on its Gates line.

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

@@ -0,0 +1,17 @@
+<!-- nina:slot db.3 -->
+| **ANY schema change, migration or new query** | **+ dba beside the reviewer** |
+
+<!-- nina:slot db.4 -->
+- **dba** → mandatory gate on schema changes, migrations, and new queries
+
+<!-- nina:slot db.5 -->
+2. **Every schema change, migration and new query goes through the dba subagent.** No exceptions. It runs beside the reviewer, which names it on its Gates line, and `qa` does not go out without its `APPROVED`.
+
+<!-- nina:slot db.6 -->
+6. **A cached read names its cache policy, and a read that feeds a write whose correctness depends on it being fresh is never cached.** An implicit cache is a bug, and a stale row contaminates every decision made from it. A write invalidates what it made stale.
+
+<!-- nina:slot db.7 -->
+7. **Tenant isolation is enforced in the data layer.** Every query in app code filters by `{{TENANT_KEY}}`, or reaches it through the model's foreign keys. No "global" queries except the auth library's own tables. Reviewer rejects any query missing the scope.
+
+<!-- nina:slot db.8 -->
+- **the database**: the schema, a migration, or a query

package/releases/0.32.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 -->
+- **Cloudflare skill flag** — if the spec touches `{{API_DIR}}/**` (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.32.0/surfaces/edge-cf/tree/.claude/agents/dba.md

@@ -0,0 +1,2 @@
+<!-- nina:slot edge-cf.1 -->
+- **Edge runtime compatibility.** A database client that runs at the edge uses its edge build, and `compatibility_flags = ["nodejs_compat"]` is set in `wrangler.toml`.

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

@@ -0,0 +1,32 @@
+<!-- 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 -->
+- **Both targets, or neither.** A change to the API surface needs the **staging Worker** (`wrangler deploy --env staging`) *and*, where the project has one, the frontend's **Pages** deploy (`{{PAGES_PROJECT}}`). 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 -->
+- **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.
+
+**A variable the bundle reads must be in the environment of the build command.** `[vars]` and
+`[env.*.vars]` in `{{APP_DIR}}/wrangler.toml` do NOT reach the build — a bundler inlines them at build
+time, and 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.32.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.32.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.32.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.32.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.32.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.32.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 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.32.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*, `{{API_DIR}}/wrangler.toml`, `.claude/patterns.md` § *Secrets* | implementer → reviewer → qa → devops |

package/releases/0.32.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. `compatibility_flags = ["nodejs_compat"]` is required in `wrangler.toml` for any database client that runs at the edge.

package/releases/0.32.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.32.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, 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.
+
+<!-- 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.32.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
+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.
+
+jsdom 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.32.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.32.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 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. Every protected screen redirects to the login without a session, so a plain
+   static server screenshots the login page: this project serves the build beside a canned API, from
+   one origin, with no auth, database or backend —
+
+   ```bash
+   {{VISUAL_SERVE}}
+   ```
+
+   The API's address is fixed at build time, and one that does not match the fixture's origin ships a
+   screen that renders but fetches nothing. A request the fixture does not answer is a gap in it: add
+   the handler rather than screenshot 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.32.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.32.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.32.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 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.32.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. jsdom has no layout engine — a green suite says nothing about the screen |

package/releases/0.32.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` → `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. 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.