@xhulz/nina 0.83.0 → 0.85.0

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/releases/0.85.0/surfaces/money/tree/.claude/patterns.md

@@ -0,0 +1,49 @@
+<!-- nina:slot money.1 -->
+
+---
+
+## Monetary values & percentages
+
+- **Money is an integer of the currency's minor unit**, end to end — {{MINOR_UNIT}}, never a float, never a type that can hold a fraction of one. Source of precision: `{{MONEY_MODULE}}`.
+- **Percentages are basis points** (`40% → 4000`, `100% → 10000`) so a distribution is exact without floating point.
+- **Parsing, formatting and percentage arithmetic live in one module and nowhere else.** A second place that turns a string into money is a second rounding rule, and the two will disagree on a value somebody is owed.
+- **Never** convert to a floating-point type before formatting, and never let a display format round a stored value.
+- Monetary database columns are integer. JSON responses serialize them as **strings**, not numbers, so no client parses them into a float. The service owns the conversion.
+
+<!-- nina:slot money.2 -->
+
+---
+
+## Distribution invariants (enforced by reviewer + unit tests)
+
+The distribution engine lives in `{{CORE_PKG}}`. It is pure and total over integer {{MINOR_UNIT}}:
+
+- A destination is either a percentage (basis points of the amount) or a fixed value.
+- `total = Σ destinations`, computed in {{MINOR_UNIT}}.
+- `total > amount` → **reject.** Never clamp, never distribute what is not there.
+- `total < amount` → **allow**, surface the shortfall, and leave the remainder **parked**. Silence is the defect here: an unexplained remainder is indistinguishable from a bug.
+- `total = amount` → OK.
+- A retention is just another destination — the same arithmetic applies to it, with no special case.
+
+<!-- nina:slot money.3 -->
+
+---
+
+## State machines & idempotency (enforced by reviewer)
+
+- **Every money-moving entity is a state machine.** Its states and legal transitions are declared in `.claude/architecture.md`; the code follows the declaration, not the other way round. Illegal transitions throw; they are never silently coerced.
+- **Every transition writes an audit row** (entity type, entity id, from, to, actor). No transition without a trail — the trail is what makes a money bug diagnosable after the money has moved.
+- **Outbound transfers are idempotent.** Each carries a unique key, and dedupe happens before the side effect, at the serialization point.
+- **One serialization point per balance.** Whatever computes and dispatches against a single balance never runs concurrently with itself. Two concurrent runs over one balance is how a double send happens even when every individual write is correct.
+
+<!-- nina:slot money.4 -->
+- **Money computation and dispatch go through the serialization point.** Routes, queue consumers and tools never run a distribution or a transfer synchronously in the request path.
+
+<!-- nina:slot money.5 -->
+- **The distribution engine lives in `{{CORE_PKG}}`.** Services call it as a pure function; they do not embed money logic inline.
+
+<!-- nina:slot money.6 -->
+- Idempotency on money-moving writes: the record carries an idempotency key, and the serialization point refuses the second attempt *before* the side effect.
+
+<!-- nina:slot money.7 -->
+- `{{CORE_PKG}}` is the most-tested package — pure functions over fixtures. Cover the distribution invariants exhaustively: over, under, exact, mixed percentage and fixed, and rounding.

package/releases/0.85.0/surfaces/money/tree/.claude/pipeline.md

@@ -0,0 +1,2 @@
+<!-- nina:slot money.1 -->
+  - **Money invariants respected** — a distribution never exceeds the amount; a shortfall is parked, not distributed; transfers idempotent; every transition audited.

package/releases/0.85.0/surfaces/money/tree/.claude/retrieval.md

@@ -0,0 +1,2 @@
+<!-- nina:slot money.1 -->
+| New distribution / transfer logic | `.claude/architecture.md` § *Money*, `.claude/patterns.md` § *Distribution invariants*, `{{CORE_PKG}}/` | architect → implementer → reviewer → qa |

package/releases/0.85.0/surfaces/money/tree/CLAUDE.md

@@ -0,0 +1,11 @@
+<!-- nina:slot money.1 -->
+3. **An outbound transfer is idempotent — it is NEVER sent twice.** Every transfer carries an idempotency key, and deduplication happens at a single serialization point **before** the side effect, never after it. A retry, a re-delivered queue message, a double-click and a replayed webhook must all collapse to one transfer. This is the highest-blast-radius invariant in the system: almost everything else can be corrected afterwards, and a duplicated transfer cannot.
+
+<!-- nina:slot money.2 -->
+4. **Conservation — what comes in equals what goes out plus what is retained.** A distribution may NEVER exceed the amount it distributes → **block**. If it is **less**, **alert** and leave the remainder **parked** and visible — never silently distributed, never silently absorbed. All arithmetic is integer {{MINOR_UNIT}}; percentages are basis points. The LLM never computes a monetary value.
+
+<!-- nina:slot money.3 -->
+5. **State-machine integrity.** Every money-moving entity has an explicit set of states and legal transitions, declared in `.claude/architecture.md` § *State machines* — not inferred from whatever code happens to exist. Only declared transitions are legal; an illegal one throws and is never silently coerced. **Every transition writes an audit row** (entity, id, from → to, actor, when). Skipping a state, inventing one, or landing a transition with no audit row is a hard reject.
+
+<!-- nina:slot money.4 -->
+- **money movement**: anything that creates, moves, settles or records a balance

package/releases/0.85.0/surfaces/pii/tree/.claude/agents/dba.md

@@ -0,0 +1,2 @@
+<!-- nina:slot pii.1 -->
+- **Privacy.** No sensitive value in clear text where it must not be. The categories are declared in `.claude/architecture.md` § *Privacy* — they are not decided per query, and not decided by you. **Document bytes live only in the object store, referenced by key: the column holds the key, never the bytes.** Any column the architect's spec flagged for masking must be encrypted at rest. Reject a schema that widens what is stored in the clear.

package/releases/0.85.0/surfaces/pii/tree/.claude/agents/devops.md

@@ -0,0 +1,8 @@
+<!-- nina:slot pii.1 -->
+
+**Point it at an UNAUTHENTICATED route — a sign-in page is the right one.** Never sign in, and never
+screenshot a signed-in page. Accounts on deployed environments hold real personal data, and a
+screenshot or a console dump pulls it into agent transcripts and logs, where it persists and nobody
+ever looks for it again. That is a privacy leak with no upside here: the sign-in page proves
+everything this check is for. It renders from the same bundle, it exercises the same build-time env
+inlining (a missing variable blanks it identically), and it needs no session.

package/releases/0.85.0/surfaces/pii/tree/.claude/agents/reviewer.md

@@ -0,0 +1,8 @@
+<!-- nina:slot pii.1 -->
+- Check for privacy regressions: **no sensitive value in a log, an error message — a library's own included — a URL or a test fixture**, per the categories in `.claude/architecture.md` § *Privacy*; document bytes only in the object store, never plaintext in the database; no leaked secret.
+
+<!-- nina:slot pii.2 -->
+- **privacy** — the privacy check above, in full: no sensitive value in a log, an error message, a
+  URL or a test fixture; document bytes only in the object store; no leaked secret. Where
+  **tenant-and-privacy** is dispatched, its reviewer owns this too and there is no separate one; where
+  it is not, this is a dimension of its own. Either way it is never nobody's.

package/releases/0.85.0/surfaces/pii/tree/.claude/agents/secops.md

@@ -0,0 +1,2 @@
+<!-- nina:slot pii.1 -->
+- **Privacy (Hard Rule #8)** — the categories declared in `.claude/architecture.md` § *Privacy* must never appear in logs, in responses that do not need them, in error paths, or in the database in clear text. Check every endpoint that returns a person's record for fields it includes by accident: a `select` that quietly grew a column is the usual way this leaks. Check the error paths too — they are written last and reviewed least — and what the libraries on them print or carry in their own errors, bound values included.

package/releases/0.85.0/surfaces/pii/tree/.claude/agents/solidity-auditor.md

@@ -0,0 +1,5 @@
+<!-- nina:slot pii.1 -->
+- **Nothing personal reaches the chain.** What is written on-chain is public, permanent, and beyond
+  deletion by anyone — including by you, and including after a subject asks. A hash of a personal
+  identifier is not a protection: it is a lookup table for whoever holds the input set. Reject a
+  personal datum stored in state, emitted in an event, or passed as calldata.

package/releases/0.85.0/surfaces/pii/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot pii.1 -->
+8. **Sensitive personal data is classified, and the classification is enforced.** What counts as sensitive here — identity documents, financial identifiers, anything a person would not expect to be readable by whoever can read a log — is declared in `.claude/architecture.md` § *Privacy*, along with the regime that governs it ({{PRIVACY_REGIME}}). Encrypted at rest. **No sensitive value in a log, an error message, a URL, an analytics event, or an agent transcript** — the places nobody thinks about are exactly the ones that persist. That includes what a library puts in its own errors and prints itself: a database client's error can carry the query and every bound value, and a framework can log a whole error past the logger it was given. A database error is mapped at the data layer to a typed error from a closed list before anything logs or returns it, and a test proves that a bound value it writes reaches no thrown error. **A value absent from an error that never held it proves nothing:** each test that shows a mapper or a sanitizer keeps a value out drives a failure whose raw error carries it — the spec names that failure class and cites where it renders bound values, an error that prints the call or a violation that echoes the input, never one that names only its constraint — and asserts first that the raw, unmapped error of the same operation contains the value, a control kept in memory and never printed; the mutant that copies the raw error's `message`, `cause` or details across turns it red.<!-- nina:why --> In one project a spec proved its error mapper on a foreign-key failure, whose message and details name only the constraint, so no mapper that copied them could turn the test red.<!-- /nina:why --> **A test that proves a value stays out matches by containment** (`String(v).includes(value)`), never by equality: a leak arrives inside an id, a message or a key. It gives each log call in the source a run, counts the console's calls by method and asserts each method the path must not use at zero, and reads at least what the console prints of each entry and each error the runs produce, recursively: every own key, symbols and non-enumerable ones too (`Reflect.ownKeys`), and the entries of every `Map`, `Set`, `Headers` and `URLSearchParams`, unless the spec rules one out in writing. Its controls put their value where the real emitter puts its own, past a call's first argument and among several, and the spec names the window its spy covers and why nothing logs after it. Its forbidden values are the run's own that § *Privacy* keeps out — where it lists what may be logged, every other value the run carries — each with a control that embeds it in a longer string under an allowed key and must fail the check — the values one run adds as much as a shared list's, since a check that folds accents passes every control written in ASCII — and no fixture value inside another's.<!-- nina:why --> In one project an allowlist check that refused only equal values passed a mutant logging `${id}:${amount}`; the next read `Object.keys` and missed an amount on a non-enumerable property and an info log no row inspected; the one after left out a class and four log paths.<!-- /nina:why --> Where what it claims to keep out names a class — an attribute, an amount — it covers every member: a surface with open-ended slots is read whole, never through a list of them — every attribute of every element a rendered page carries, just as every property of an error is — and a sweep that read nothing fails; each forbidden value is looked for in every form the code can give it, formatted and raw; and each state that shows, hides or replaces a value is swept on its own, the one built to withhold it most of all. One mutant puts the value in a slot the check does not name — `data-x` on a page; on an object or an error, a non-enumerable key, a symbol key, a nested object, a `Map` entry, `cause`, the end of `message` or `stack` — and one per field puts that field's raw value in each such slot, on every error the code throws, not only one it builds: one left green is a slot or a form the check misses. The implementer runs them on its mirror, as one block it reuses, before `DIFF-READY`, whatever the step lists, and reports one left green as the row the spec lacks (Hard Rule #17), adding it only in a file the step authorizes.<!-- nina:why --> In one project a walk of own keys missed a `Map`, a symbol key and a nested object, and every control put its value in a call's first argument, where the runtime's loggers put theirs second; then three steps in two days went back from review for a slot no listed mutant tried — an error's `cause`, its `stack`, a hidden key.<!-- /nina:why --><!-- nina:why --> In one project a sweep of `data-testid`, `aria-label` and `title`, proven by mutants in those three, stayed green with the label in a `data-label`; the next swept every attribute for the formatted amounts and missed their raw centavos; the one after swept only the state that shows the figure, and the row built to show none carried it in a `title`.<!-- /nina:why --> Document bytes live only in the object store, referenced by key, never in the database in clear text.
+
+<!-- nina:slot pii.2 -->
+- **personal data**: where it is collected, stored, logged or sent

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/architect.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/dba.md

@@ -0,0 +1,42 @@
+<!-- nina:slot prisma.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. Through a driver adapter, cite the adapter's installed source for what a transaction does: the skill describes the default engine, and an adapter can roll back less |
+
+<!-- nina:slot prisma.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 prisma.3 -->
+- **With Prisma, both offline.** Run `pnpm --filter {{DB_PKG_NAME}} exec prisma validate`; it must pass. Then run `prisma migrate diff` in its **offline, file-only form** and read the generated SQL, not just the Prisma delta. Its flags changed in Prisma 7, so read the installed major (`prisma --version`) before writing the command:
+
+   ```
+   # Prisma 6. 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
+   ```
+
+   From Prisma 7 the two flags are `--from-schema` and `--to-schema`, and the schema engine starts from the
+   datasource in `prisma.config.ts` even for this diff: with none there, it prints nothing and exits 0. For
+   SQLite a placeholder the diff never opens is enough, a `file:` URL under a gitignored directory; for any
+   other provider, find out what the diff opens before you give it one. Never a real database's URL. A first schema has nothing at `HEAD`: diff it `--from-empty`. Compare the output against the
+   hand-written `migration.sql` to confirm the declarative parts match.
+
+   ⚠️ **Do NOT reach for `--from-migrations`.** It looks like the natural choice and it is a trap:
+   Prisma refuses it without a shadow database (`--shadow-database-url`, or from Prisma 7 a
+   `shadowDatabaseUrl` in `prisma.config.ts`), which pushes you toward supplying a database URL — the exact move that destroys databases (below). The file-to-file form above answers the
+   same question with no database involved.
+
+   ⛔ **NEVER point `--shadow-database-url`, `--from-url`, `--to-url`, `--from-schema-datasource` — or, from Prisma 7, a `shadowDatabaseUrl` or the config datasource behind `--from-config-datasource` — at a real database, most of all not the one `{{SECRETS_LOCAL}}` names.** 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. 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 prisma.4 -->
+- **Where reads are cached through Prisma Accelerate,** every `findUnique` / `findMany` on a hot read path names its `cacheStrategy` (`ttl` / `swr`), and one that feeds a correctness-critical write names none.
+
+<!-- nina:slot prisma.5 -->
+- **On an edge runtime,** new Prisma code paths use the edge client of the installed major: `@prisma/client/edge` up to Prisma 6; from 7, the client the `prisma-client` generator writes with the platform's `runtime` set, imported from where it is generated — `@prisma/client/edge` fails there with `MODULE_NOT_FOUND`.
+
+<!-- nina:slot prisma.6 -->
+- Run a Prisma command that writes to a real database — `prisma migrate dev`, `migrate deploy`, `migrate reset`, `migrate resolve`, `db push`, `db execute`, `$executeRaw*` — or **any `prisma migrate diff` variant carrying a database URL**, which silently wipes the database it points at.

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/devops.md

@@ -0,0 +1,11 @@
+<!-- nina:slot prisma.1 -->
+- **`prisma-cli`** — before `migrate deploy` or any other Prisma CLI command against a real database.
+
+<!-- nina:slot prisma.2 -->
+- **Prisma migrations go out with `prisma migrate deploy`**, and nothing else changes a shared database's schema.
+
+<!-- nina:slot prisma.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 prisma.4 -->
+- Run `prisma migrate reset` against a shared database, ever.

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/implementer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/integration-tester.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-cli` | a Prisma CLI command |

package/releases/0.85.0/surfaces/prisma/tree/.claude/agents/reviewer.md

@@ -0,0 +1,2 @@
+<!-- nina:slot prisma.1 -->
+| `prisma-client-api` | a new or changed Prisma query |

package/releases/0.85.0/surfaces/prisma/tree/.claude/patterns.md

@@ -0,0 +1,15 @@
+<!-- nina:slot prisma.1 -->
+- **Database table/column names** (Prisma `@map` / `@@map`): `snake_case` in SQL, `camelCase` in TS.
+
+<!-- nina:slot prisma.2 -->
+- Where Prisma reads are cached through Accelerate, `cacheStrategy` lives in `{{DB_PKG}}`: services do not add, strip, or override cache policies.
+
+<!-- nina:slot prisma.3 -->
+
+### Prisma
+
+- Schema lives in `{{DB_PKG}}/prisma/schema.prisma`. Nowhere else.
+- **Never write raw SQL** unless justified in a code comment with perf data.
+- N+1 is solved with `include` / `select`, chosen deliberately.
+- Where reads are cached through Accelerate, every `findUnique` / `findMany` on a hot path defines its `cacheStrategy`, and no direct connection string is embedded in code.
+- Tests run a real Prisma client against a real database; the client is never mocked.

package/releases/0.85.0/surfaces/prisma/tree/CLAUDE.md

@@ -0,0 +1,5 @@
+<!-- nina:slot prisma.1 -->
+| Run any `prisma` CLI command (the database gate, 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 prisma.2 -->
+| Write or audit a Prisma query (architect, implementer, the database gate, 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 |

package/src/commands/dashboard.mjs

@@ -3,12 +3,14 @@
  * this machine, its address printed for a click (src/dashboard.mjs).
  *
  *   nina dashboard [--project <dir>] [--port <n>] [--open]
+ *   nina dashboard --demo [--port <n>] [--open]      an invented project, anywhere, its office playing in a loop
  */
 
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { HARNESS } from '../paths.mjs';
 import { viewDashboard } from '../dashboard.mjs';
+import { makeDemo } from '../demo.mjs';
 
 /**
  * Runs the command.
@@ -19,15 +21,38 @@ import { viewDashboard } from '../dashboard.mjs';
  */
 export async function dashboard(argv, ctx) {
   const arg = (flag) => (argv.includes(flag) ? argv[argv.indexOf(flag) + 1] ?? '' : null);
-  const target = resolve(arg('--project') ?? '.');
-  if (!existsSync(join(target, HARNESS, 'profile.json'))) {
-    console.error(`  no ${HARNESS}/profile.json under ${target} — run it inside a project, or name one with --project\n`);
-    return 1;
-  }
   const port = arg('--port');
   if (port !== null && !(/^\d+$/.test(port) && Number(port) <= 65535)) {
     console.error(`  --port takes a port number, 0 to 65535, and was given ${port}\n`);
     return 2;
   }
-  return viewDashboard({ target, ctx, port: port === null ? undefined : Number(port), open: argv.includes('--open') });
+  const options = { ctx, port: port === null ? undefined : Number(port), open: argv.includes('--open') };
+  if (argv.includes('--demo')) {
+    if (arg('--project') !== null) {
+      console.error('  --demo shows an invented project, so it takes no --project: give one or the other\n');
+      return 2;
+    }
+    let demo;
+    try {
+      demo = await makeDemo(ctx);
+    } catch (error) {
+      console.error(`  the demo could not be made — ${error?.message ?? error}\n`);
+      return 1;
+    }
+    // Removed however the process ends; on Ctrl+C, once the dashboard has closed. A terminal closed under it hangs it up,
+    // which ends the process with no `exit` event unless something listens.
+    process.once('exit', demo.remove);
+    process.once('SIGHUP', () => process.exit(129));
+    try {
+      return await viewDashboard({ ...options, target: demo.project, demo: true });
+    } finally {
+      demo.remove();
+    }
+  }
+  const target = resolve(arg('--project') ?? '.');
+  if (!existsSync(join(target, HARNESS, 'profile.json'))) {
+    console.error(`  no ${HARNESS}/profile.json under ${target} — run it inside a project, or name one with --project, or see one with --demo\n`);
+    return 1;
+  }
+  return viewDashboard({ ...options, target });
 }

package/src/dashboard.mjs

@@ -16,6 +16,7 @@ import { fileURLToPath } from 'node:url';
 import { readProfile } from './paths.mjs';
 import { projectRecords } from './store.mjs';
 import { officeRoutes } from './office.mjs';
+import { DEMO_OFFICE } from './demo.mjs';
 import { listenHere, openInBrowser, refuseElsewhere, untilStopped } from './serve.mjs';
 import { layerRootFor } from './commands/compose.mjs';
 import { taskList } from './commands/runs.mjs';
@@ -100,18 +101,19 @@ export function dashboardTabs(target, ctx) {
 /**
  * Serves the dashboard: the page at `/`, each tab's data at `/api/<tab>`, and the office at `/office/`.
  *
- * @param {{target: string, ctx: {root: string}, port?: number, tell?: (line: string) => void}} options - `tell` is where
- *   a failure is said: the terminal by default.
+ * @param {{target: string, ctx: {root: string}, port?: number, tell?: (line: string) => void, replay?: boolean, loop?: boolean, rest?: number, scale?: number}} options -
+ *   `tell` is where a failure is said: the terminal by default. `replay`, `loop`, `rest` and `scale` are the office's
+ *   (`officeRoutes`): the demo's plays its one session over and over (`DEMO_OFFICE`).
  * @returns {Promise<{url: string, close: () => Promise<void>}>}
  */
-export async function serveDashboard({ target, ctx, port = DASHBOARD_PORT, tell = console.error }) {
+export async function serveDashboard({ target, ctx, port = DASHBOARD_PORT, tell = console.error, replay = false, loop = false, rest, scale }) {
   const tabs = dashboardTabs(target, ctx);
   const room = JSON.stringify({ project: basename(target) }).replace(/</g, '\\u003c');
   const page = readFileSync(PAGE, 'utf8').replace('/*NINA_DASHBOARD*/null', () => room);
   // The office polls its ledger while anyone watches it: made when its tab is first opened, not before.
   let office = null;
   const officeFor = () => {
-    if (!office) office = officeRoutes({ target });
+    if (!office) office = officeRoutes({ target, replay, loop, scale, ...(rest === undefined ? {} : { rest }) });
     return office;
   };
   // What failed is said in the terminal that runs the dashboard, and never in the response: an error's message carries
@@ -172,13 +174,14 @@ export async function serveDashboard({ target, ctx, port = DASHBOARD_PORT, tell
 /**
  * Runs the dashboard until Ctrl+C: serves it, says where for a click, and opens it in the system's browser when asked.
  *
- * @param {{target: string, ctx: {root: string}, port?: number, open?: boolean}} options
+ * @param {{target: string, ctx: {root: string}, port?: number, open?: boolean, demo?: boolean}} options - `demo`: the
+ *   project is the demo's, its office a replay in a loop, and the terminal says the data is invented.
  * @returns {Promise<number>} Process exit code.
  */
-export async function viewDashboard({ target, ctx, port = DASHBOARD_PORT, open = false }) {
+export async function viewDashboard({ target, ctx, port = DASHBOARD_PORT, open = false, demo = false }) {
   let dashboard;
   try {
-    dashboard = await serveDashboard({ target, ctx, port });
+    dashboard = await serveDashboard({ target, ctx, port, ...(demo ? DEMO_OFFICE : {}) });
   } catch (error) {
     console.error(`  the dashboard could not open a port — ${error?.message ?? error}\n`);
     return 1;
@@ -186,7 +189,7 @@ export async function viewDashboard({ target, ctx, port = DASHBOARD_PORT, open =
   const stopped = untilStopped();
   const opened = open ? await openInBrowser(dashboard.url) : false;
   // The address ends its line, with nothing after it, so a terminal makes it a link.
-  console.log(`  the dashboard · ${basename(target)}`);
+  console.log(demo ? '  the dashboard · a demo: an invented notes app, three weeks of made-up work, no real project' : `  the dashboard · ${basename(target)}`);
   if (open && !opened) console.log('  No browser could be opened from here.');
   console.log(`  ${opened ? 'Opened in your browser' : 'Click to open it'}: ${dashboard.url}`);
   console.log('  Ctrl+C closes the dashboard.\n');