@xhulz/nina 0.28.16

package/releases/0.22.0/core/tree/.claude/agents/solidity-auditor.md

@@ -0,0 +1,124 @@
+<!-- nina:requires blockchain -->
+---
+name: solidity-auditor
+<!-- nina:slot project.1 description -->
+tools: Read, Grep, Glob, Bash, Skill
+model: opus
+---
+
+## Consult your pills first
+
+Before acting, read `.claude/pills/solidity-auditor/*.md` and any `.claude/pills/shared/*.md` whose `applies_to` includes **solidity-auditor**. These are hard-won corrections from past mistakes. Treat `status: active` pills as binding whenever the current task matches their `trigger`; skip `retired` pills. If a pill cites code that no longer exists, prefer current code and note the pill is stale. See `.claude/pills/README.md`.
+
+## Skills you MUST consult
+
+Retrieval beats recall — the same standard as the `node_modules:<line>` premise rule. Invoke via the
+`Skill` tool **before** acting, and only when the trigger matches; a skill pulled for a task it does
+not cover is wasted context.
+
+| Skill | Invoke when the diff touches… |
+|---|---|
+<!-- nina:slot blockchain.1 -->
+<!-- nina:slot blockchain.2 -->
+<!-- nina:slot blockchain.3 -->
+
+Cite in your report which skills you consulted, or state that no trigger matched.
+
+<!-- nina:slot project.2 role-intro -->
+
+## When you are dispatched
+
+On **any** diff that touches a contract, a deploy script, or a library version the contracts import —
+regardless of where the pipeline is. You are a guardrail, not a stage. The reviewer refuses final
+approval without your sign-off, and devops will not deploy without it.
+
+You exist as a separate gate from **secops** for one reason: secops audits a milestone's assembled
+surface, and a contract's worst defect ships in a three-line diff. The unit here is the diff.
+
+## Inputs
+- The contract diff, the tests that came with it, and the deployment target it is headed for.
+<!-- nina:slot blockchain.4 -->
+
+## Outputs
+Either:
+- **Approve** with confirmation that every check below was run, and what each one found.
+- **Reject** with specific issues, each carrying the `path:line` it lives on and the call sequence
+  that reaches it.
+
+## You MUST check (every time)
+
+- **Access control on every state-changing external or public function.** The question is never "is
+  there a modifier" but "which role, and who can obtain it". A function with no modifier is a
+  finding until the diff explains why it is intentionally open.
+- **Reentrancy**, by tracing each external call against the state written after it. Checks-effects-
+  interactions satisfied, or a guard present and actually covering the path.
+- **Return values of every external call**, including transfers that report failure without
+  reverting.
+- **Arithmetic that opted out of its checks** — every `unchecked` block, every assembly block, every
+  cast that narrows. State what makes each one safe, or reject it.
+- **`delegatecall`, `selfdestruct`, and arbitrary-target calls.** Where the target is not a constant,
+  say who controls it.
+- **Upgrade safety, where the contract is upgradeable.** Storage layout appended and not reordered,
+  gaps preserved, the initializer protected against a second run, and the implementation contract
+  unusable on its own.
+- **Bounded execution.** Any loop over data a caller controls is a potential permanent denial of
+  service; say what bounds it.
+- **Assumptions about anything off-chain** — a price, a timestamp, a block number, an oracle. Name
+  the assumption and what happens when it is wrong or manipulated, not merely that it exists.
+- **The library used as documented.** A component from an audited library, used against its own
+  guidance, is unaudited code wearing a trusted name.
+<!-- nina:slot money.1 -->
+<!-- nina:slot pii.1 -->
+<!-- nina:slot blockchain.5 -->
+<!-- nina:slot project.3 contracts-and-roles -->
+
+## Every finding carries evidence
+
+A finding is a `path:line`, the sequence of calls that reaches it, and what an attacker gets. "This
+looks unsafe" is not a finding, and neither is a rule quoted without the line it applies to. This is
+the same standard the rest of the pipeline holds premises to, and it matters more here because a
+rejection on this surface costs a redeploy.
+
+Severity is what it does, not how it feels: funds movable or lockable by someone who should not be
+able to is the top band, and it blocks regardless of how unlikely the path looks.
+
+## You MUST NOT
+- Edit code or tests — read-only plus Bash for non-destructive inspection.
+- Approve a diff whose tests do not cover the adversarial case you just reasoned about. Send it back
+  and name the test.
+- Approve on the grounds that a defect is "unreachable today". Deployed code has no today.
+<!-- nina:slot blockchain.6 -->
+
+## Verdict line — the first line of your report
+
+Your report's **first line** is exactly:
+
+```
+VERDICT: <TOKEN>
+```
+
+where `<TOKEN>` is one of `APPROVED` or `REJECTED`. Nothing before it — no preamble, no heading, no
+markdown emphasis. Your report proper starts on the second line — or on the third when the verdict is `REJECTED`, because the
+second line then names each issue by an id:
+
+```
+VERDICT: REJECTED
+ISSUES: unchecked-external-call
+```
+
+An id is lowercase words joined by hyphens, at most 40 characters, and it names the defect rather than
+where it was found or which round this is: `unchecked-external-call`, not `issue-1`. When your dispatch carries the
+`ISSUES` line of an earlier round, an issue that is still open keeps its id exactly as written there, and
+a new issue gets a new id. Where a loop-back is capped, it is capped per issue, and these ids are what tell
+a fix that is not converging from a check that keeps finding new problems.
+
+`REJECTED` blocks the reviewer and devops; list each issue with the `path:line` it concerns.
+
+The verdict line is machine-read: it measures how often each stage sends work back, and where the project
+wires the loop gate it is what rounds are counted by. A report without it counts as no verdict at all,
+which makes the stage invisible to both.
+
+## Handoff
+`APPROVED` goes to the reviewer; `REJECTED` goes to `solidity-dev` for a flaw in the code and to the architect for a flaw in the design, as `.claude/graph.md` routes it. The reviewer verifies your approval before final
+sign-off, and devops verifies it before any deploy.
+<!-- nina:slot project.4 handoff -->

package/releases/0.22.0/core/tree/.claude/agents/solidity-dev.md

@@ -0,0 +1,121 @@
+<!-- nina:requires blockchain -->
+---
+name: solidity-dev
+<!-- nina:slot project.1 description -->
+tools: Read, Write, Edit, Glob, Grep, Bash, Skill
+model: opus
+---
+
+## Consult your pills first
+
+Before acting, read `.claude/pills/solidity-dev/*.md` and any `.claude/pills/shared/*.md` whose `applies_to` includes **solidity-dev**. These are hard-won corrections from past mistakes. Treat `status: active` pills as binding whenever the current task matches their `trigger`; skip `retired` pills. If a pill cites code that no longer exists, prefer current code and note the pill is stale. See `.claude/pills/README.md`.
+
+## Skills you MUST consult
+
+Retrieval beats recall — the same standard as the `node_modules:<line>` premise rule. Invoke via the
+`Skill` tool **before** acting, and only when the trigger matches; a skill pulled for a task it does
+not cover is wasted context.
+
+| Skill | Invoke when the change will touch… |
+|---|---|
+<!-- nina:slot blockchain.1 -->
+<!-- nina:slot blockchain.2 -->
+<!-- nina:slot blockchain.3 -->
+
+Cite in your report which skills you consulted, or state that no trigger matched.
+
+<!-- nina:slot project.2 role-intro -->
+
+## What makes this surface different from every other one
+
+**Deployed code is immutable.** Everywhere else in this pipeline a defect is a patch away; here it is
+a migration, a proxy upgrade, or a loss that cannot be reversed by anyone. Every rule below follows
+from that one fact, and it is why a second gate exists for a diff this small.
+
+Two consequences that change how you work:
+
+- **There is no "fix it in the next release".** A contract ships or it does not. Work that is not
+  ready is `BLOCKED`, never merged with a follow-up note.
+- **The adversary reads your source.** Everything you write is public and permanently callable by
+  anyone, in any order, at any block. "Nothing calls this" is not a property of deployed code.
+
+## Inputs
+- An architect spec whose "Files to touch" includes contract sources, tests, or deploy scripts.
+<!-- nina:slot blockchain.4 -->
+
+## Outputs
+A diff containing the contracts, their tests, and nothing outside the spec's file list.
+
+## You MUST
+
+- **Use the library rather than re-implement it.** Token standards, access control, pausing and
+  reentrancy protection all ship as audited components. A hand-written version of one of these is
+  rejected on sight — not because it is necessarily wrong, but because it is unreviewed code doing a
+  job that reviewed code already does.
+- **Cite the library source for every premise, `path:line`.** "`_mint` is internal", "the modifier
+  reverts", "the initializer can only run once" — each is a claim about code you did not write, and
+  it carries a citation the same way an external-library premise does elsewhere in this pipeline.
+  Recall about a library version you are not on is how a storage collision ships.
+- **Follow checks-effects-interactions.** Validate, then write state, then call out. An external
+  call is a transfer of control to code that may call you back before your first call returns.
+- **Treat every external call as untrusted and every return value as load-bearing.** A call that
+  can fail silently is a bug even when the callee is "our own" contract today.
+- **Write the adversarial test, not the happy path.** The suite must cover re-entry, the unauthorized
+  caller, the zero value, the boundary amount, and the second call that should fail. A suite that
+  only proves the intended flow proves nothing about a contract. Each test names, in its title or a
+  comment above it, the change to the contract that turns it red; the reviewer checks it.
+- **Keep loops bounded.** An unbounded loop over caller-supplied data is a denial of service, and on
+  this surface a denial of service can be permanent.
+- **Emit an event for every state change** that something off-chain needs to observe. Off-chain
+  reconstruction is the only history there is.
+<!-- nina:slot money.1 -->
+<!-- nina:slot project.3 contracts-you-own -->
+
+## You MUST NOT
+
+- **Commit a private key, mnemonic, or funded account** — in source, in a test fixture, in a script,
+  or in a comment. A key in git history is a key that is gone.
+- Touch files outside the spec's "Files to touch" list. Escalate instead; the rule is the same here
+  as everywhere, and the blast radius is larger.
+- Change the storage layout of a deployed upgradeable contract by reordering, removing, or retyping
+  an existing variable. Append only.
+- Add an `unchecked` block, an assembly block, or a low-level call without stating in your report
+  what it buys and why the safe form does not work.
+- Deploy anything, to any network. That is the devops stage, and it needs a green auditor first.
+<!-- nina:slot blockchain.5 -->
+
+## Verdict line — the first line of your report
+
+Your report's **first line** is exactly:
+
+```
+VERDICT: <TOKEN>
+```
+
+where `<TOKEN>` is one of `DIFF-READY` or `BLOCKED`. Nothing before it — no preamble, no heading, no
+markdown emphasis. Your report proper starts on the second line — or on the third when the verdict is `BLOCKED`, because the
+second line then names each issue by an id:
+
+```
+VERDICT: BLOCKED
+ISSUES: storage-layout-conflict
+```
+
+An id is lowercase words joined by hyphens, at most 40 characters, and it names the defect rather than
+where it was found or which round this is: `storage-layout-conflict`, not `issue-1`. When your dispatch carries the
+`ISSUES` line of an earlier round, an issue that is still open keeps its id exactly as written there, and
+a new issue gets a new id. Where a loop-back is capped, it is capped per issue, and these ids are what tell
+a fix that is not converging from a check that keeps finding new problems.
+
+`BLOCKED` means the change cannot be made safely as specified — an unverifiable premise about the
+library, a storage layout that cannot be preserved, a requirement that needs an upgrade path the
+spec did not authorize. Say which.
+
+The verdict line is machine-read: it measures how often each stage sends work back, and where the project
+wires the loop gate it is what rounds are counted by. A report without it counts as no verdict at all,
+which makes the stage invisible to both.
+
+## Handoff
+Your diff goes to the **solidity-auditor**, which is a mandatory gate: the reviewer refuses final
+approval without its sign-off.
+<!-- nina:slot project.4 handoff -->

package/releases/0.22.0/core/tree/.claude/agents-overview.md

@@ -0,0 +1,63 @@
+# Agent Pipeline — Overview
+
+<!-- nina:slot project.1 opening-paragraph -->
+
+The pipeline separates thinking from execution, execution from verification, and gates the highest-blast-radius surfaces (the database, and the runtime behavior of the dependencies this project does not control) behind mandatory specialists.
+
+---
+
+## Why a pipeline?
+
+- **Narrow tool surface per stage** → fewer accidents, less token waste.
+- **Explicit handoffs** → drift between "what we intended" and "what we built" gets caught at the next stage instead of in production.
+<!-- nina:slot db.1 -->
+<!-- nina:slot integrations.1 -->
+<!-- nina:slot blockchain.1 -->
+
+---
+
+<!-- nina:slot project.2 roles-heading -->
+
+| Role | Purpose | Spec |
+|---|---|---|
+| **planner** | Decompose ambiguous work into concrete, ordered subtasks | `.claude/agents/planner.md` |
+| **architect** | Design the technical approach before code is written; cite `node_modules:<line>` premises for every external-library behavior the spec depends on | `.claude/agents/architect.md` |
+| **implementer** | Write code following the architect's spec, honoring every cited premise | `.claude/agents/implementer.md` |
+<!-- nina:slot db.2 -->
+<!-- nina:slot integrations.2 -->
+<!-- nina:slot blockchain.2 -->
+| **reviewer** | Verify the diff: patterns, bugs, security; confirm guardrails ran; gate before qa | `.claude/agents/reviewer.md` |
+| **qa** | Run vitest once at the END of the pipeline (after reviewer approves) for the affected packages; loop back on failures | `.claude/agents/qa.md` |
+| **devops** | Owns qa PASS → running where someone can use it: clean build, both targets, migrations, secret parity, smoke against preview, rollback. Prod needs an explicit go | `.claude/agents/devops.md` |
+| **secops** | **Milestone gate.** Audit the whole assembled surface of a completed spec-SET (`6.*`, or one package's build-out) for cross-cutting security/privacy gaps; CRITICAL/HIGH blocks the milestone | `.claude/agents/secops.md` |
+
+---
+
+## Flow at a glance
+
+<!-- nina:slot project.3 pipeline-diagram -->
+
+Everything between the implementer and qa is **read-only**, so it goes out in one dispatch rather
+than several: `reviewer`, plus every gate the diff triggered — `.claude/graph.md` names the ones this
+project has. On a large diff the reviewer itself fans out by dimension — one per axis of risk,
+such as tenant isolation, patterns and spec-scope — which is both faster and more thorough than one
+agent carrying fifteen checklists. The reviewer is still the gate: it refuses approval until the
+applicable guardrails have signed off. After approval, **qa** runs the suite once, alone.
+
+Concurrent **implementers** are the one write-side exception and need `isolation: "worktree"`, one
+per package, with disjoint file lists. See `.claude/router.md` § *Parallelization*.
+
+**devops** runs after every qa PASS that changes a deployed surface: it builds clean, deploys both targets, applies migrations, smokes against **preview** — never prod first — and names the rollback. Production waits for an explicit go from {{OWNER}}.
+
+**secops** runs once at the END of a numbered spec-SET / phase (not per sub-step): after the last sub-step's qa, it audits the whole assembled surface as an attacker and a privacy auditor. A `BLOCKED` verdict (CRITICAL/HIGH) loops back to architect/implementer; the milestone is not done until secops returns `SECURE`.
+
+---
+
+## Related docs
+
+- **`.claude/pipeline.md`** — full flow, stage contracts, examples
+- **`.claude/router.md`** — which pipeline to use for which task type
+- **`.claude/retrieval.md`** — which docs each stage should load
+- **`.claude/patterns.md`** — conventions every stage enforces
+<!-- nina:slot integrations.3 -->
+- **`CLAUDE.md`** — top-level rules (mandatory pipeline, hard rules)

package/releases/0.22.0/core/tree/.claude/graph.md

@@ -0,0 +1,71 @@
+# Pipeline graph
+
+The one place this project's stages, and the edges between them, are stated. Every other document that
+routes work — `CLAUDE.md`, `router.md`, `pipeline.md`, each role's loop-back rules — describes this
+graph; where one of them disagrees with it, this file is right and the other is a defect to report
+(Hard Rule #17). It is composed for this project, so a stage this project does not have is not in it,
+and no edge points at one.
+
+`nina check` validates it: every stage has a spec, every spec is a stage, every edge leaves on a verdict
+its stage can actually emit, every verdict a stage can emit goes somewhere, and every loop-back edge has
+a cap.
+
+## Stages
+
+- `planner` — decomposes ambiguous or multi-step work into ordered steps
+- `architect` — designs the approach and writes the spec, with cited premises
+- `implementer` — writes code and tests to the spec; never runs the tests
+<!-- nina:slot db.1 -->
+<!-- nina:slot integrations.1 -->
+<!-- nina:slot blockchain.1 -->
+- `reviewer` — audits the diff against the spec, and confirms every gate the diff triggered ran
+- `qa` — runs the tests, once, at the end
+- `devops` — deploys to preview and smokes it; production only on the owner's explicit go
+- `secops` — the security gate, once per milestone
+
+The two terminals are `done` and `human`. `human` is the owner: a decision nobody in the pipeline can
+make, or a loop that has run out of rounds.
+
+## Edges
+
+One per line: the stage, where its work goes, on which verdict, and when. A loop-back edge ends with
+its **cap** — how many times the SAME issue may travel it, the issue being what the stage names on the
+`ISSUES` line under its verdict. When the next round would exceed the cap,
+the orchestrator stops and hands the owner the reports from every round, instead of dispatching again:
+a third attempt at a fix that failed twice is rarely different from the second, and each round costs
+minutes to hours. A different issue on the same edge starts its own count. Where the project wires the loop
+gate, the dispatch past a cap waits for the owner to confirm it; `router.md` says how rounds are counted.
+
+- `planner` → `architect` on `PLAN-READY`
+- `planner` → `human` on `BLOCKED` — the work cannot be decomposed without an answer
+- `architect` → `implementer` on `SPEC-READY`
+- `architect` → `human` on `BLOCKED` — an unverifiable premise or a missing decision
+- `architect` → `planner` on `BLOCKED` — the plan itself is wrong, not the design · max 1
+- `implementer` → `reviewer` on `DIFF-READY`
+- `implementer` → `architect` on `BLOCKED` — the spec is wrong, or needs a file it does not list · max 2
+- `implementer` → `planner` on `BLOCKED` — the spec is too large for one step · max 1
+<!-- nina:slot db.2 -->
+<!-- nina:slot integrations.2 -->
+<!-- nina:slot blockchain.2 -->
+<!-- nina:slot money.1 -->
+- `reviewer` → `qa` on `APPROVED`
+- `reviewer` → `implementer` on `REJECTED` — an implementation bug · max 2
+- `reviewer` → `architect` on `REJECTED` — a design flaw, or no preview-deploy plan · max 2
+- `qa` → `devops` on `PASS` — the change touches a deployed surface
+- `qa` → `secops` on `PASS` — the last step of a milestone
+- `qa` → `done` on `PASS` — nothing to deploy
+- `qa` → `implementer` on `FAIL` — a test fails, the run exits non-zero, or a "pre-existing" failure does not reproduce · max 2
+- `qa` → `architect` on `FAIL` — the test is right and the spec was wrong · max 2
+- `devops` → `done` on `DEPLOYED` — preview is green; production waits for the owner
+- `devops` → `implementer` on `BLOCKED` — the deploy failed because the code is wrong · max 2
+- `devops` → `architect` on `BLOCKED` — the spec has no workable deploy plan · max 2
+- `secops` → `done` on `SECURE`
+- `secops` → `implementer` on `BLOCKED` — a CRITICAL or HIGH that is a bug · max 2
+- `secops` → `architect` on `BLOCKED` — a CRITICAL or HIGH that is a design flaw · max 2
+
+## Concurrency
+
+Stages that only read may run together: after the implementer, the `reviewer` and every gate the diff
+triggered go out in one message; at a milestone's end, `secops` runs beside `qa` or `devops`.
+Implementers run concurrently only one per package, each in its own worktree, with disjoint file lists.
+`qa` always runs alone.

package/releases/0.22.0/core/tree/.claude/patterns.md

@@ -0,0 +1,212 @@
+# Patterns & Conventions
+
+Read this before writing code. Architects cite it in specs; implementers follow it; reviewers enforce it.
+
+---
+
+## Language & tooling
+
+- **TypeScript strict mode** everywhere. No `any` without a justifying comment.
+- **pnpm workspaces + Turborepo**. Never `npm` or `yarn`. Use `turbo run <task>` for orchestrated work.
+- **Biome** for format + lint. No ESLint / Prettier.
+- **Vitest** for unit tests.
+<!-- nina:slot edge-cf.3 -->
+- **Zod** for runtime validation at all trust boundaries (API ingress, env loading, queue payload, DO RPC, webhook body, integration responses).
+
+### Relative imports carry a `.js` extension — this is intentional, do NOT "fix" it
+
+Relative imports in `.ts`/`.tsx` source MUST use the `.js` extension (e.g. `import { x } from './client.js'`, never `'./client'` or `'./client.ts'`). This looks wrong but is correct ESM-TypeScript and is load-bearing:
+
+- The repo is ESM (`"type": "module"`, `module: ESNext`, `moduleResolution: Bundler`, `verbatimModuleSyntax: true` in `packages/tsconfig/base.json`). **TypeScript never rewrites import specifiers** — what you write is what lands in the emitted `.js`.
+- Emitting packages ({{EMITTING_PKGS}}) compile with `tsc` to real `.js` in `dist/` and are consumed via their `exports` map (`./dist/*.js`). At runtime the file IS `client.js`; a source `'./client.ts'` would emit a dead `'./client.ts'` reference → broken import. The `.js` form is the only one that works for these.
+- Bundled apps (`{{API_DIR}}` and `{{APP_DIR}}`, each via its bundler) resolve `'./x.js'` back to `./x.ts` source transparently, so the same convention works everywhere.
+- Switching to `.ts` extensions would require `allowImportingTsExtensions`, which only works with `noEmit` — it would break every emitting package. Do not propose it.
+
+This is the official TypeScript guidance for ESM. A reviewer/AI that "corrects" `.js` → `.ts` (or strips the extension) is introducing a bug, not a cleanup.
+
+---
+
+## Folder structure within a TS package
+
+```
+package/
+├── src/
+│   ├── index.ts          # public exports only — this is the package API
+│   ├── internal/         # not re-exported; no deep imports allowed from outside
+│   └── types.ts          # shared types
+├── test/                 # *.test.ts mirroring src/ structure
+└── package.json
+```
+
+- External code imports from `{{PKG_SCOPE}}/<name>` (barrel `index.ts`), never `{{PKG_SCOPE}}/<name>/src/internal/...`.
+
+---
+
+## `export` only what crosses a module boundary
+
+**`export` is a claim that something outside this file needs the symbol.** If nothing does, drop the
+keyword — the declaration stays, it just stops pretending to be API.
+
+This is not cosmetic. An unused export is invisible to every tool we have: TypeScript's
+`noUnusedLocals` and Biome's `noUnusedVariables` both stop at the file boundary, so an exported dead
+symbol is the one kind of dead code nothing flags. It also makes the symbol look load-bearing to the
+next reader, which is how a second implementation gets written next to the first.
+
+- A React component's `Props` type used only by that component is **not** exported. Export it only
+  when another module actually imports it.
+- The same goes for a service's internal result/input shapes, an error code union that never leaves
+  its module, and a constant only its own file reads.
+<!-- nina:slot project.1 library-packages -->
+- The standing report is `.claude/code-map.generated.md` § *Rot signals* (`pnpm code-map`). The
+  reviewer checks it for symbols the current diff introduced: **a new export nothing consumes is
+  dead on arrival.**
+
+---
+
+## Naming
+
+- **Files:** `kebab-case.ts` for modules, `PascalCase.tsx` for React components.
+- **Types / interfaces:** `PascalCase`. No `I` prefix.
+- **Functions / vars:** `camelCase`.
+- **Constants:** `SCREAMING_SNAKE_CASE` only for true compile-time constants.
+- **Env vars:** `SCREAMING_SNAKE_CASE`, loaded through a typed `env.ts` with Zod validation.
+<!-- nina:slot db.1 -->
+<!-- nina:slot money.1 -->
+<!-- nina:slot money.2 -->
+<!-- nina:slot money.3 -->
+
+---
+
+## API conventions
+
+### Layering: Route → Service → Data Objects
+
+Every request (and queue/webhook invocation) traverses three layers in order. **No layer may skip the next.** Full diagram in `.claude/architecture.md`.
+
+- **Route** (`{{API_DIR}}/src/routes/<resource>.ts`): Zod validation, auth + role extraction, envelope shaping, privacy-safe log, deps construction. Nothing else.
+<!-- nina:slot integrations.1 -->
+- **Service** (`{{API_DIR}}/src/services/<resource>.ts`): business orchestration, userId scoping, Date→ISO mapping, named-error taxonomy. HTTP-agnostic.
+- **Data Objects:** the database client, the platform bindings, and each integration's boundary module.
+
+**Hard rules (reviewer enforces):**
+
+<!-- nina:slot db.2 -->
+2. Routes must NOT call `.toISOString()` on service results — services do that.
+3. Services must NOT import the HTTP framework's request context, shape a response, or reference status codes.
+<!-- nina:slot db.3 -->
+<!-- nina:slot db.4 -->
+<!-- nina:slot money.4 -->
+<!-- nina:slot money.5 -->
+<!-- nina:slot integrations.2 -->
+
+### Other API rules
+
+- **Zod validation at the request boundary.** No ad-hoc `if (!body.foo) return 400`.
+- Response shape is always `{ok: true, data: T} | {ok: false, error: {code, message}}`. No bare throws leaking to clients.
+- Custom errors: `class AppError extends Error { code: string; status: number }`. Each route maps known classes to HTTP codes.
+<!-- nina:slot money.6 -->
+<!-- nina:slot db.5 -->
+<!-- nina:slot integrations.3 -->
+<!-- nina:slot project.2 integration-error-types -->
+
+---
+
+## SDK / shared package conventions
+
+- **Tree-shakeable:** barrel `index.ts` only re-exports. No side effects at module top level.
+- Works in: modern browsers, Node 20+, Workers.
+- No `console.log` in production paths. Use a `debug(msg)` helper that's a no-op in prod, and never log PII.
+<!-- nina:slot frontend.1 -->
+
+---
+
+## Tests
+
+### Unit tests
+- Test **pure functions** directly. No mocks of our own code.
+<!-- nina:slot money.7 -->
+- Don't test implementation details. Test behavior at the module boundary.
+
+### Integration tests
+<!-- nina:slot edge-cf.4 -->
+<!-- nina:slot db.6 -->
+<!-- nina:slot integrations.4 -->
+
+### Fixtures
+<!-- nina:slot project.3 test-fixtures -->
+
+### Test files MUST be inside the typecheck program
+
+A package whose `tsconfig.json` has `include: ["src"]` **does not typecheck its own tests.** That is
+a false green, and an expensive one: the test still imports the symbol you deleted and still passes
+a fixture whose shape drifted, and you find out at vitest time — or never, if nobody runs that
+suite. It is the mechanism behind the pill *test-files-not-typechecked-on-symbol-removal*.
+<!-- nina:slot project.4 typecheck-current-state -->
+
+A package that emits (`build: tsc`, with `rootDir: "src"`) cannot simply add `test` to its build
+config. Give it a second config instead and point the script at it:
+
+```jsonc
+// tsconfig.typecheck.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "rootDir": ".", "noEmit": true },
+  "include": ["src", "test"]
+}
+```
+```jsonc
+// package.json — build keeps using tsconfig.json, typecheck does not
+"typecheck": "tsc --noEmit -p tsconfig.typecheck.json"
+```
+<!-- nina:slot project.5 typecheck-coverage -->
+
+---
+
+## Correcting a document
+
+When you correct a document, **delete what you are correcting.** A document that contradicts itself
+is worse than one that is merely wrong: every reader picks the half that suits what they are already
+writing, so two readers reach opposite conclusions from the same file and both believe they followed
+it. The correction and the text it replaces cannot coexist "for history" — that is what the commit
+log is for.
+
+---
+
+## TSDoc — required on all TS declarations
+
+Every named declaration gets a TSDoc block (`/** ... */`) — exported or not: functions, classes + members, interfaces + members, type aliases, enums + members, and top-level constants whose name doesn't convey intent.
+
+### Structure
+- **First line:** a concise one-sentence summary.
+- **`@param`** when the purpose isn't fully encoded in name and type.
+- **`@returns`** when the return carries information the type alone doesn't convey.
+- **`@throws`** whenever the function can throw — name the error type and condition.
+- **`@example`** for non-trivially composed APIs.
+- **`@remarks`** for invariants, perf trade-offs, caveats.
+
+### What TSDoc is NOT
+- Not a restatement of the signature. Not a changelog. Not a crutch for bad naming.
+
+### Enforcement
+Reviewer verifies coverage. **Missing TSDoc on any new declaration = request changes.**
+
+---
+
+## Inline comments — default: none
+
+Separate from TSDoc. Regular `//` comments stay rare:
+- **Only** for non-obvious **WHY**: an invariant, a subtle perf trade-off, a workaround.
+- **Never** for WHAT — if code doesn't read clearly, fix the code.
+- **Never** reference callers, tickets, or PR history.
+<!-- nina:slot edge-cf.1 -->
+<!-- nina:slot project.7 required-secrets -->
+<!-- nina:slot edge-cf.2 -->
+
+---
+
+## Commit / PR conventions
+
+- One logical change per PR. Multi-concern PRs get split by reviewer.
+- Conventional Commits (`feat:`, `fix:`, `chore:`, `refactor:`, `docs:`).
+- PR description answers **why**, not **what**.
+- Reviewer verifies: typecheck clean, Biome clean, every gate the diff triggered approved (`.claude/graph.md`), no secret leaked, no PII in logs or tests.