@xhulz/nina 0.28.20 → 0.28.21

package/releases/0.28.21/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.28.21/surfaces/db/tree/.claude/agents/architect.md

@@ -0,0 +1,8 @@
+<!-- nina:slot db.1 -->
+| `prisma-client-api` | a new or changed Prisma query |
+
+<!-- nina:slot db.2 -->
+- **Tenant-scope impact** — explicitly state where `userId` is enforced. Every new Prisma query in app code includes `userId` (or its model-specific FK equivalent) in the `where` clause. The only exempt tables are the {{AUTH_LIB}} system tables.
+
+<!-- nina:slot db.3 -->
+- **Prisma flag** — if `schema.prisma` or a new Prisma query is touched, mark **"DBA REQUIRED"** prominently at the top of the spec. Specify the proposed `cacheStrategy`, or **`NO_CACHE`** for any read that feeds a write whose correctness depends on it being fresh — a stale row contaminates every decision made from it.

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

@@ -0,0 +1,84 @@
+<!-- nina:slot db.1 -->
+| `prisma-cli` | **before ANY `prisma` CLI command** — `validate`, `format`, `migrate dev`, `migrate diff`, `migrate deploy`. Flags differ between versions, and one of them (`migrate diff --shadow-database-url` against a live database) destroys the database it points at |
+| `prisma-client-api` | auditing a new or changed query — filters, operators, `$transaction` semantics |
+
+<!-- nina:slot db.2 -->
+Neither skill covers a **caching or edge layer sitting on top of the client** — cache strategy,
+edge-client behaviour and the rule about never caching a read that authorizes a write belong to that
+layer's own integration doc, declared like any other integration. A skill does not replace it.
+
+<!-- nina:slot db.3 -->
+- Any change to `{{DB_PKG}}/prisma/schema.prisma`.
+- Any new Prisma query (`findUnique`, `findMany`, `create`, `update`, `delete`, `aggregate`, `$queryRaw`, etc.) anywhere in application code.
+- Any migration generated via `prisma migrate`.
+
+<!-- nina:slot db.4 -->
+- The Prisma diff (schema changes + generated migration SQL).
+- 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 Prisma models, so you can spot N+1 risk and consumer-side cache implications without re-grepping. (Greenfield phase: fall back to `.claude/architecture.md` § *Database* for the planned schema — the model table, monetary conventions, and the Accelerate cache-policy table are canonical there.)
+
+<!-- nina:slot db.6 -->
+- **Schema validates.** Run `pnpm --filter {{DB_PKG_NAME}} exec prisma validate`. Must pass.
+
+<!-- nina:slot db.7 -->
+- **Migration diff.** Run `prisma migrate diff` in its **offline, file-only form** and read the generated SQL, not just the Prisma delta:
+
+   ```
+   # Compare the PREVIOUS schema against the working one — pure file-to-file, no database.
+   git show HEAD:{{DB_PKG}}/prisma/schema.prisma > /tmp/schema-head.prisma
+   pnpm --filter {{DB_PKG_NAME}} exec prisma migrate diff \
+     --from-schema-datamodel /tmp/schema-head.prisma \
+     --to-schema-datamodel prisma/schema.prisma \
+     --script
+   ```
+
+   ⚠️ **Do NOT reach for `--from-migrations`.** It looks like the natural choice and it is a trap:
+   Prisma refuses it without `--shadow-database-url`, which pushes you toward supplying a database
+   URL — the exact move that destroys databases (below). The two-datamodel form above answers the
+   same question with no database involved. Compare its output against the hand-written
+   `migration.sql` to confirm the declarative parts match.
+
+   ⛔ **NEVER pass `--shadow-database-url`, `--from-url`, `--to-url`, or `--from-schema-datasource` pointing at a real database — most of all not `DATABASE_URL` from `{{API_DIR}}/{{SECRETS_LOCAL}}`.** Prisma **executes** the entire migration history against whatever database those flags name, which **DESTROYS ALL DATA** in it. A shadow database must be a disposable, empty database and nothing else. This is not hypothetical, and it does not announce itself: the command completes with a reassuring "empty migration" result and no error, having already destroyed everything in the database it was pointed at. If the offline form above cannot answer your question, **STOP and report that to the orchestrator** instead of reaching for a database URL.
+
+<!-- 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. Use `@@index` in 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 -->
+- **userId scope.** Every query in app code must include `userId` in `where` (or the model's equivalent FK chain — `accountId`/`entryId`/`ruleId` resolving back to the owning user). The {{AUTH_LIB}} system tables are the only exemption. Reject any app query missing the scope.
+
+<!-- nina:slot db.11 -->
+- **Cache strategy.** Every `findUnique` / `findMany` on a hot read path has an explicit `cacheStrategy` (Accelerate `ttl` / `swr`). **Implicit cache is a bug — reject.** Cross-check the policy against the cache-policy table in `.claude/architecture.md` § *Database*.
+
+<!-- nina:slot db.12 -->
+- **N+1 patterns.** If the code fetches a list then queries per item, reject with "use `include` / `select` or batch."
+
+<!-- nina:slot db.13 -->
+- **Secrets.** `DATABASE_URL` (Prisma Postgres / Accelerate URL) must come from `{{SECRETS_LOCAL}}` locally and `{{SECRETS_PROD}}` in production — never `.env` committed.
+
+<!-- nina:slot db.14 -->
+- **Run ANY command that can write to a real database.** You are a read-only gate. Against a live
+  `DATABASE_URL` you may run `SELECT`-only queries and nothing else. Explicitly forbidden, no
+  exceptions: `prisma migrate dev`, `migrate deploy`, `migrate reset`, `migrate resolve`,
+  `db push`, `db execute`, `$executeRaw*`, and **any `prisma migrate diff` variant carrying a
+  database URL** (see the *Migration diff* check — that one silently wipes the database it points at). If a check
+  seems to require writing, it does not: report the limitation to the orchestrator instead.
+
+<!-- nina:slot db.15 -->
+- Approve without actually running `prisma validate` and the offline `prisma migrate diff` of the *Migration diff* check.
+
+<!-- nina:slot db.16 -->
+- Wave through "small" schema changes. Small changes cause the worst production incidents.
+
+<!-- nina:slot db.17 -->
+- Approve a query missing `userId` scope (or its equivalent owning FK) in app code.
+
+<!-- nina:slot db.18 -->
+**Final report format:** ≤300 words if approved. Sections: Schema validation result, Migration SQL preview (verbatim if non-trivial), Index analysis, userId-scope check, Cache strategy verdict, Privacy check, Final verdict. If rejected, list each issue with required action — no length cap.

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

@@ -0,0 +1,14 @@
+<!-- nina:slot db.1 -->
+- **`prisma-cli`** — before `migrate deploy` or any other Prisma CLI command against a real database.
+
+<!-- nina:slot db.2 -->
+- **Migrations, in order, against the right database.** Apply with `prisma migrate deploy`. Confirm the target `DATABASE_URL` is the one you intend. Verify the migration is backward-compatible with the currently-deployed code, because the two are live together during the rollout.
+
+<!-- nina:slot db.3 -->
+- Run `prisma migrate diff --shadow-database-url <url>` against any live database. It **executes** the migration history against that database, destroying everything in it, and reports success. Use a disposable shadow database or don't run it.
+
+<!-- nina:slot db.4 -->
+- Run `prisma migrate reset` against a shared database, ever.
+
+<!-- nina:slot db.5 -->
+- **Migrations:** applied / none, with the database they hit.

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

@@ -0,0 +1,5 @@
+<!-- nina:slot db.1 -->
+| `prisma-client-api` | a new or changed Prisma query |
+
+<!-- nina:slot db.2 -->
+- If you change `schema.prisma` or write a new Prisma query, flag it explicitly in the diff summary so the reviewer dispatches **dba** before approving.

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

@@ -0,0 +1,13 @@
+<!-- nina:slot db.1 -->
+| `prisma-cli` | a Prisma CLI command |
+
+<!-- nina:slot db.2 -->
+- Any new Prisma query against an Accelerate-cached read path — verify cache hit/`cacheStrategy` behavior live (dba covers schema; you cover runtime cache behavior)
+
+<!-- nina:slot db.3 -->
+If you find a Prisma issue mid-run (a query behaves differently against a real DB than the dba's static analysis suggested) — escalate to **dba**, do not fix yourself.
+
+<!-- nina:slot db.4 -->
+- **{{AUTH_LIB}}'s backing store is a real Postgres** — the dev DB Accelerate branch, the same
+  `DATABASE_URL` the implementer uses in `{{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.28.21/surfaces/db/tree/.claude/agents/planner.md

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

package/releases/0.28.21/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 -->
+- **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 an RPC between services.
+
+<!-- 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.28.21/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.28.21/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.28.21/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` → `reviewer` on `APPROVED`
+- `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.28.21/surfaces/db/tree/.claude/patterns.md

@@ -0,0 +1,29 @@
+<!-- nina:slot db.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot db.2 -->
+- Routes must NOT import query functions (`list*`, `find*`, `get*`, `upsert*`, `delete*`) from `{{DB_PKG_NAME}}`. Only `createDbClient` and error classes.
+
+<!-- nina:slot db.3 -->
+- `cacheStrategy` lives in `{{DB_PKG}}`. Services do not add, strip, or override cache policies.
+
+<!-- nina:slot db.4 -->
+- **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.
+- `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.28.21/surfaces/db/tree/.claude/pipeline.md

@@ -0,0 +1,13 @@
+<!-- nina:slot db.1 -->
+
+### 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; no raw PII without encryption; the connection secret comes from the environment, never from code.
+- **Position:** dispatched mid-pipeline by whoever detects Prisma. Reviewer verifies dba ran.
+
+<!-- nina:slot db.2 -->
+  - **If Prisma touched → dba approved.**

package/releases/0.28.21/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.28.21/surfaces/db/tree/.claude/router.md

@@ -0,0 +1,10 @@
+<!-- nina:slot db.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.28.21/surfaces/db/tree/CLAUDE.md

@@ -0,0 +1,23 @@
+<!-- nina:slot db.1 -->
+| Run any `prisma` CLI command (dba, devops, and the integration gate where there is one) | `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.
+
+<!-- nina:slot db.8 -->
+- **the database**: the schema, a migration, or a query

package/releases/0.28.21/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}}/**` (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.28.21/surfaces/edge-cf/tree/.claude/agents/dba.md

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

package/releases/0.28.21/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 -->
+- **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 -->
+- **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.28.21/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.28.21/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.28.21/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.28.21/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.28.21/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.28.21/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.28.21/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 → the integration gate, where there is one → reviewer → qa |
+
+<!-- nina:slot edge-cf.2 -->
+| New Queue handler | `.claude/architecture.md` § *Processing pipeline*, `{{API_DIR}}/src/queues/` | architect → implementer → the integration gate, where there is one → 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.28.21/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.28.21/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.28.21/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.28.21/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.** 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.
+
+<!-- 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.28.21/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.28.21/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.