chiltepin 0.47.0

package/templates/skill/reference/decks.md

@@ -0,0 +1,198 @@
+# Slide decks — `chiltepin slides`
+
+Part of the **chiltepin** skill (the hub is `SKILL.md`, one folder up). Read
+this for any slides or deck ask.
+
+## Slide decks (`chiltepin slides`)
+
+Any document renders as a deck with `chiltepin slides`. **Each top-level heading
+(`#`/`##`) starts a new slide and is its title.** Everything until the next
+heading — prose *and* every block — stays on that slide, so a slide can hold
+several blocks. (`###`+ headings stay in the slide body; to keep things on the
+same slide, just don't add a new `#`/`##`.)
+
+````md
+# Why now
+A sentence of context, then any blocks under this heading.
+
+```drivers
+items:
+  - { title: Slow, body: "p95 hit 2.4s.", icon: clock, accent: amber }
+```
+
+# The fix
+Next heading → next slide. This one stacks two blocks.
+
+```stats
+stats:
+  - { value: "800ms", label: New p95 target, trend: flat }
+```
+
+```callout
+tone: success
+body: Both blocks land on "The fix" slide.
+```
+````
+
+- This means a normal Chiltepin doc (sections under `##` headings) already
+  presents cleanly — no special markup needed. To author *for* slides, write one
+  `##` heading per slide and keep each to **one idea**. A heading plus one strong
+  visual (a diagram, `drivers`, `stats`, `pyramid`, `quadrant`, `timeline`) reads
+  better than dense prose.
+- **Vertical alignment is automatic** — light slides (one block, little prose)
+  center; heavier slides (stacked blocks or lots of prose) top-align. To force it,
+  add a marker to the heading: `## Title {top}`, `## Title {center}`, or
+  `## Title {bottom}` (the marker is stripped from the displayed title). A fourth
+  marker, `## Title {split}`, switches the slide to the consulting layout —
+  prose left, exhibit right (see *Consulting-style decks* below).
+- **Builds are automatic.** A diagram with a natural order — `sequence`,
+  `flow`, `state`, `saga`, `spans`, `steps`, `timeline` — reveals one item per
+  → press before the deck moves on; earlier items stay, the newest takes the
+  accent, and ← walks back. Add `## Title {nobuild}` to show that slide whole.
+  The page and print always show everything.
+- Every non-cover slide automatically gets a footer (deck title · page number).
+- **`chiltepin build` — and the studio's Site link — emit both views of every
+  doc**: the page plus a companion deck at `<slug>.slides.html`. A Doc | Slides
+  toggle links the two on each page, so a doc is a deck with no extra command.
+  Studio's Present mode shows the current doc's deck without even saving.
+- **Long sections paginate automatically** — each slide has a content budget
+  weighted by block item counts. A hero-scale block is one heavy enough to
+  fill a slide on its own — a big diagram, a many-card grid. It splits onto
+  its own slide with the same section title instead of sharing the stage with
+  its section's prose.
+- **Two-part slides auto-split.** Substantial prose plus a medium exhibit that
+  would overflow stacked lays out side by side automatically. Prose becomes
+  the left message column, the exhibit the right — the same layout `{split}`
+  forces. Write the section naturally; the deck picks the layout.
+- The `meta` block is the cover slide. A doc with **no headings at all** falls
+  back to one slide per block (legacy behavior).
+
+### Consulting-style decks
+
+For an executive or consulting-grade deck, hold every slide to the formula
+**assertion → exhibit → takeaway**:
+
+- **Action titles.** Each `##` is a full-sentence assertion the slide proves
+  ("Checkout latency costs us conversions"), never a topic label
+  ("Latency"). Someone flipping through only the titles should get the whole
+  argument.
+- **`{split}` layout.** `## Title {split}` puts the slide's prose in a left
+  *message* column and its blocks in a right *exhibit* column — the classic
+  consulting slide. Write 1-3 short punchy paragraphs, then exactly one strong
+  block.
+- **One exhibit per slide.** A `chart`, `scorecard`, `heatmap`, or
+  a diagram — the block *is the evidence* for the title's claim. Two exhibits
+  means two slides.
+- **Open each part with a `divider`.** A deck with 3+ parts gets an
+  interstitial per part — a `divider` alone under its own `##` heading
+  (`kicker: PART 2`, an assertion as the `title`). It renders as a clean
+  full-band break slide.
+- **The money slide is a `bignumber`.** When one metric carries the whole
+  argument ("-75% checkout p95"), give it its own `{split}` slide: message
+  left, the `bignumber` as the exhibit right. Do not use a one-item `stats` row.
+- **Close the argument with `takeaways`**: the 2-4 things the room must
+  remember, numbered; follow with a `callout` (`tone: success`) only if
+  there's a separate ask.
+- **No thin slides.** A heading floating over one small block reads empty —
+  merge it into a neighbour, or give it a message column with `{split}`.
+
+A three-part skeleton using all three:
+
+````md
+## Part 1 — checkout is bleeding conversions
+
+```divider
+kicker: PART 1
+title: Checkout is bleeding conversions
+accent: navy
+```
+
+## One number tells the story {split}
+
+The async capture change removed the 1.7s synchronous call from the
+request path. Nothing else moved.
+
+```bignumber
+value: "-75%"
+label: Checkout p95 after the change
+trend: down
+accent: green
+```
+
+## What to remember
+
+```takeaways
+items:
+  - text: The synchronous capture call was the bottleneck
+  - text: Moving it to a queue cut p95 by 75%
+  - text: Conversion recovered within two weeks
+```
+````
+
+````md
+## Checkout latency costs us conversions {split}
+
+Every 100ms of checkout latency costs ~0.6% conversion. Our p95 has drifted
+to 2.4s — the synchronous capture call is 71% of it.
+
+```chart
+kind: bar
+title: Where the 2.4s goes
+labels: [Gateway, Fraud, Capture, Persist, Render]
+series:
+  - { label: p95 ms, values: [120, 260, 1700, 180, 140] }
+```
+````
+
+
+### The design-review arc — the structural exemplar
+
+For a full design-review deck, follow this **arc**. The structure is the
+template — swap every exhibit and every title for the system at hand; nothing
+about the topic carries over.
+
+| # | Slide (always an action title) | Layout | Exhibit |
+|---|---|---|---|
+| 1 | Cover | `meta` | — |
+| 2 | PART 1 · the problem | `divider` | — |
+| 3 | *The pain, stated as a claim* | `{split}` | `chart` — the evidence |
+| 4 | *The scale is real* | — | `envelope` — the math that sets the target |
+| 5 | PART 2 · the design | `divider` | — |
+| 6 | *Who touches the system* | — | `c4` (context) |
+| 7 | *The design, stated as a claim* | `{split}` | `block` — the shape |
+| 8 | *The decision that mattered* | `{split}` | `options` — chosen vs rejected |
+| 9 | *The budget holds* | — | a waterfall `chart` against the target |
+| 10 | *One request, end to end* | — | `sequence` |
+| 11 | *When X degrades, …* | — | `swimlane` — the ops story |
+| 12 | PART 3 · the commitment | `divider` | — |
+| 13 | *What we're measured on* | — | `slo` |
+| 14 | *The number that matters* | — | `bignumber` |
+| 15 | Takeaways | — | `takeaways` — the close |
+
+What the arc encodes (keep these even when you reshape it):
+
+- **Three parts, opened by dividers**: problem → design → commitment. The
+  reader always knows where they are.
+- **Evidence before design**: slides 3-4 earn the right to propose anything —
+  a complaint chart, a metric, then the envelope math. That math turns pain
+  into a numeric target the rest of the deck answers to.
+- **One decision slide** (8): every real design had a fork; show the rejected
+  option honestly or the deck reads as a sales pitch.
+- **Slides 9-11 are chosen by YOUR bottleneck**, not by this table: a fan-out
+  system shows `sequence` + `swimlane`; a storage system might show `erd` +
+  `heatmap`; an agent system `agentloop` + `trace`. Two or three deep dives,
+  never a fixed list.
+- **The commitment close never changes**: objectives (`slo`) → the money
+  number (`bignumber`, echoing slide 4's target) → `takeaways`. The last
+  takeaway carries the ask (effort, flag, rollback).
+
+## Provenance and position
+
+`## Title {source: production traces, 14 Oct 2026}` puts a source line in the
+slide footer, where every consulting exhibit carries one. It sits in the
+footer rather than under the block on purpose. The fitter scales the exhibit,
+and a source line that shrinks with it stops being readable.
+
+A deck with two or more `divider` bands also grows a **tracker** in the slide
+header — the parts of the deck with the current one lit. The room always
+knows where it is. One divider draws nothing: a strip of one says nothing.

package/templates/skill/reference/exemplars/adr.md

@@ -0,0 +1,87 @@
+```meta
+title: ADR-014 — Sync engine for co-writing
+subtitle: Why Plotline replaced last-writer-wins with CRDT sync, and what it measurably changed.
+tag: ADR · Accepted
+```
+
+In March, 23% of active manuscripts had two or more writers in the same
+hour, and last-writer-wins overwrote 31 reported edits that month.
+"Lost my changes" became the top support tag. A ghostwriter and an editor
+routinely work the same scene at the same time, so the fix had to allow
+concurrent edits — not serialize them.
+
+## Options
+
+```options
+id: ex-adr-options
+items:
+  - kicker: Option 1
+    title: Section locking
+    how: One writer holds a scene at a time; others wait or fork.
+    pros: [No merge logic at all, Ships in two weeks]
+    cons: ["Blocks the ghostwriter + editor pair — our core workflow", Stale locks need a timeout policy]
+    verdict: "REJECTED — solves the symptom by forbidding the use case"
+    tone: rejected
+  - kicker: Option 2
+    title: OT server
+    how: A central server transforms and orders every operation.
+    pros: [Proven at scale by Google Docs, Server log makes debugging linear]
+    cons: [Every keystroke round-trips — offline writing stops working, The sequencer is a single point of failure]
+    verdict: "VIABLE — fallback if CRDT storage costs blow up"
+    tone: viable
+  - kicker: Option 3
+    title: CRDT (Yjs)
+    how: Every client merges; the server only relays and persists updates.
+    pros: [Offline edits merge on reconnect, "80 ms p50 merge in the prototype", Relay server is stateless]
+    cons: ["Stored docs grow ~1.6× from tombstones", Merge output is harder to debug than a server log]
+    verdict: "CHOSEN"
+    tone: chosen
+```
+
+## Decision
+
+```callout
+id: ex-adr-decision
+tone: note
+title: Decision
+body: "Plotline syncs manuscripts with Yjs CRDTs. The server relays and persists updates; it never resolves them."
+```
+
+## What we accepted
+
+```proscons
+id: ex-adr-consequences
+pros:
+  - Concurrent edits merge without a lock or a round-trip
+  - Writers keep working through the full offline flight test
+  - Relay servers scale horizontally — no sequencer to shard
+cons:
+  - "Stored manuscript grows ~1.6× — tombstones never leave the doc"
+  - Deletion GC needs a weekly compaction job we now own
+  - A bad merge has no single log to replay
+```
+
+The trade we made explicit: 83 KB more per manuscript is about 10 GB across
+Plotline's 120,000 manuscripts — under $1 a month at $0.02/GB. Each
+lost-edit ticket cost a churn-risk conversation. We bought
+reliability with pennies of disk.
+
+## Measured outcome
+
+```benchmark
+id: ex-adr-outcome
+metricLabel: Metric
+subjects:
+  - { label: Before, sub: last-writer-wins, tone: muted }
+  - { label: After, sub: Yjs rollout, featured: true }
+rows:
+  - { label: Lost-edit tickets / month, better: low, cells: ["31", "2"] }
+  - { label: Sync latency p50, better: low, cells: ["140 ms", "80 ms"] }
+  - { label: Doc load p95, better: low, cells: ["410 ms", "460 ms"] }
+  - { label: Storage per manuscript (median), better: low, cells: ["148 KB", "231 KB"] }
+note: "Four weeks either side of the 100% rollout, June; same manuscript cohort."
+```
+
+Load p95 and storage went the wrong way, as the options card predicted. Both
+stayed inside the budget we set before rollout (500 ms, 300 KB), so the
+decision stands without amendment.

package/templates/skill/reference/exemplars/agent-system.md

@@ -0,0 +1,113 @@
+```meta
+title: Reconciliation agent
+subtitle: How Caravel Freight's agent matches carrier invoices to shipments — the loop, the window, one real run.
+tag: Agent system · v2
+```
+
+Caravel Freight books about 9,000 ocean and air shipments a month. Carriers
+invoice 1,400 line items a week, and roughly 30% disagree with the quoted
+rate. The agent proposes a match and a verdict per line; a billing clerk
+approves every proposal. The agent has no path to the ledger.
+
+## The loop
+
+```agentloop
+id: ex-agent-system-loop
+agent:
+  name: Reconciliation agent
+  model: claude-sonnet-4-6
+  note: One invoice line per episode.
+env: Invoice queue
+tools:
+  - { name: get_shipment, desc: "Booking, lane, and quoted rate" }
+  - { name: search_rate_card, desc: Contract rate for a lane and sail date }
+  - { name: get_invoice_history, desc: "The carrier's past corrections" }
+  - { name: post_proposal, desc: Write match + verdict to the review queue }
+  - { name: escalate, desc: Send the line to a clerk with a reason }
+memory:
+  - carrier correction history
+  - verdicts on earlier lines
+stop: proposal posted or line escalated
+```
+
+Three conditions force `escalate` instead of a proposal: no booking
+reference resolves, the rate delta exceeds $400, or the invoice currency
+differs from the contract currency. Everything else — 68% of lines — ends in
+a posted proposal.
+
+## Window budget
+
+```context
+id: ex-agent-system-window
+window: 100000
+segments:
+  - { label: system prompt, tokens: 3500, accent: navy }
+  - { label: tool schemas, tokens: 4500, accent: teal }
+  - { label: invoice line + OCR text, tokens: 9000, accent: amber }
+  - { label: shipment record, tokens: 6000, accent: blue }
+  - { label: rate-card excerpt, tokens: 12000, accent: purple, desc: top-3 matching lanes only }
+  - { label: carrier history, tokens: 15000, accent: green }
+```
+
+The free 50,000 tokens are the episode's working room — tool results and
+retries append there. Carrier history is evicted first when a long episode
+fills the window. That is safe because history only tunes the verdict
+wording; the match depends on the shipment record and the rate card, which
+are never evicted.
+
+## One real run
+
+```trace
+id: ex-agent-system-run
+turns:
+  - role: user
+    text: "Invoice CMA-88231-04 · Shanghai → Rotterdam · 2 × 40HC · $4,120"
+  - role: assistant
+    thinking: The quoted rate lives on the booking. Fetch the shipment before touching the rate card.
+    text: Resolving booking CV-59107 for this line.
+  - role: tool
+    tool: get_shipment
+    args: '{ "booking": "CV-59107" }'
+    result: "2 × 40HC · lane CNSHA→NLRTM · quoted $3,890 all-in · sailed 2026-07-14"
+  - role: tool
+    tool: search_rate_card
+    args: '{ "lane": "CNSHA-NLRTM", "date": "2026-07-14" }'
+    result: "timeout after 10s"
+  - role: assistant
+    thinking: One retry is allowed on timeout; escalating on a transient error wastes a clerk's time.
+    text: Rate-card lookup timed out — retrying once.
+  - role: tool
+    tool: search_rate_card
+    args: '{ "lane": "CNSHA-NLRTM", "date": "2026-07-14" }'
+    result: "contract $3,890 per pair · valid through 2026-09-30 · no peak surcharge clause"
+  - role: assistant
+    text: "Invoice exceeds contract by $230 with no surcharge clause in force. Proposing: match to CV-59107, dispute $230."
+  - role: tool
+    tool: post_proposal
+    args: '{ "booking": "CV-59107", "verdict": "dispute", "amount": 230 }'
+    result: "queued for review · PR-20441"
+```
+
+## Eight weeks in production
+
+```stats
+id: ex-agent-system-outcomes
+stats:
+  - { value: 68%, label: Lines auto-proposed, delta: "+68pp vs manual", trend: up }
+  - { value: 45s, label: Clerk time per line, delta: "-87%", trend: down }
+  - { value: 0.4%, label: Proposals reversed after approval, trend: flat }
+  - { value: $18k, label: Disputed overcharges recovered / month, trend: up }
+```
+
+Reversals are the number to watch: each one means a clerk approved a wrong
+verdict. That makes 0.4% the agent's real error rate as the business sees
+it.
+
+## The boundary
+
+```callout
+id: ex-agent-system-boundary
+tone: danger
+title: Propose, never post
+body: "`post_proposal` writes to the review queue only. Ledger writes require a clerk's approval click, and the agent's service account holds no ledger credential — the boundary is IAM, not prompt text."
+```

package/templates/skill/reference/exemplars/api-reference.md

@@ -0,0 +1,110 @@
+```meta
+title: Skerry API
+subtitle: Render any URL to PNG, WebP, or PDF in three calls.
+tag: API · v1
+```
+
+The base URL is `https://api.skerry.dev/v1`; authenticate every call with
+`Authorization: Bearer sk_live_…`. Captures run asynchronously — a POST returns
+`202` with an id, and the file arrives seconds later via webhook or polling. A
+capture spends one credit only when it succeeds; rate limits are 10 requests
+per second with bursts to 50.
+
+## Create a capture
+
+```endpoint
+id: ex-api-create
+method: POST
+path: /captures
+auth: Bearer sk_live_…
+body:
+  - { name: url, type: string, required: true, desc: "Page to render; must be reachable from the public internet" }
+  - { name: format, type: string, desc: "png | webp | pdf — default png" }
+  - { name: width, type: integer, desc: "Viewport width in px; default 1280" }
+  - { name: full_page, type: boolean, desc: Capture the full scroll height }
+  - { name: webhook_url, type: string, desc: Receives capture.finished / capture.failed }
+responses:
+  - { status: 202, desc: Capture queued }
+  - { status: 402, desc: Credit balance is zero }
+  - { status: 422, desc: URL malformed or scheme not http(s) }
+request: |
+  { "url": "https://example.com/pricing", "format": "png", "full_page": true }
+response: |
+  { "id": "cap_8fk2", "status": "queued" }
+```
+
+## Fetch a capture
+
+```endpoint
+id: ex-api-fetch
+method: GET
+path: /captures/{id}
+description: result_url is a signed link that expires 24 hours after the capture finishes.
+params:
+  - { name: id, in: path, type: string, required: true, desc: Capture id from the create call }
+responses:
+  - { status: 200, desc: Capture in any status }
+  - { status: 404, desc: Unknown or expired id }
+response: |
+  { "id": "cap_8fk2", "status": "done",
+    "result_url": "https://files.skerry.dev/cap_8fk2.png?sig=…" }
+```
+
+## List captures
+
+```endpoint
+id: ex-api-list
+method: GET
+path: /captures
+params:
+  - { name: cursor, in: query, type: string, desc: Opaque cursor from the previous page }
+  - { name: limit, in: query, type: integer, desc: "1–100, default 25" }
+  - { name: status, in: query, type: string, desc: "Filter: queued | rendering | done | failed" }
+responses:
+  - { status: 200, desc: "Newest first, with next_cursor when more exist" }
+```
+
+## One capture, end to end
+
+```sequence
+id: ex-api-seq
+actors:
+  - { id: Client, name: Your server }
+  - { id: Skerry, name: Skerry API }
+  - { id: Hook, name: Your webhook, sub: webhook_url, external: true }
+messages:
+  - Client -> Skerry: POST /captures
+  - Skerry --> Client: 202 · cap_8fk2 queued
+  - { from: Skerry, to: Skerry, kind: note, label: "render, 2–8 s typical" }
+  - { from: Skerry, to: Hook, label: POST capture.finished, kind: async, summary: "Signed with X-Skerry-Signature; non-2xx responses are redelivered 5 times over 30 minutes." }
+  - Hook --> Skerry: 2xx ack
+  - Client -> Skerry: GET /captures/cap_8fk2
+  - Skerry --> Client: 200 · done + result_url
+foot:
+  - { label: Webhook delivery, value: at-least-once }
+  - { label: result_url TTL, value: 24 h }
+```
+
+Webhook delivery is at-least-once, so make the handler idempotent on the
+capture id. Polling is the fallback, not a race: `result_url` appears on
+`GET /captures/{id}` the moment status is `done`, whether or not any webhook
+was delivered.
+
+## Errors
+
+```table
+columns: [Status, Meaning, What to do]
+rows:
+  - [401, Missing or revoked key, "Rotate the key in the dashboard; do not retry."]
+  - [402, Credit balance is zero, "Top up; already-queued captures still finish."]
+  - [422, URL invalid or scheme not http(s), Retrying identical input fails identically.]
+  - [429, Rate limit exceeded, "Back off for Retry-After seconds, then retry."]
+  - [500, Skerry fault, "Retry with backoff; the capture id stays valid."]
+note: "A render that fails is not an HTTP error: the capture ends as status failed with a failure_reason, and spends no credit."
+```
+
+```callout
+tone: warn
+title: Verify X-Skerry-Signature
+body: "Every webhook carries an HMAC-SHA256 of the raw body, keyed with your signing secret, plus a timestamp. Reject anything unsigned or older than five minutes — an unverified handler lets anyone mark your captures done."
+```

package/templates/skill/reference/exemplars/backend-arch.md

@@ -0,0 +1,117 @@
+```meta
+title: Marram — payout engine
+subtitle: How Fenwick moves seller money from captured charge to bank account.
+tag: Backend · v2
+```
+
+Fenwick is a marketplace for used camera gear; buyers pay Fenwick, and Fenwick
+pays its sellers once a day. Marram owns that gap. It holds seller balances
+between capture and payout and splits each charge into seller net plus an 8%
+platform fee. Every afternoon it executes about 38,000 SEPA transfers.
+
+The constraint that shaped the design is auditability: a regulator can ask for
+any seller's position on any past date. So every money movement is a
+double-entry journal, and balances are derived, never stored.
+
+## Boundaries
+
+```c4
+id: ex-backend-c4
+level: container
+boundary: { label: Marram }
+nodes:
+  - { id: core, kind: external, name: marketplace-core, desc: Checkout and charge capture. }
+  - { id: settler, kind: container, family: service, name: settler, tech: Go, desc: Turns captures into ledger journals. }
+  - { id: api, kind: container, family: service, name: payout-api, tech: Go, desc: Balances and payout status. }
+  - { id: batcher, kind: container, family: service, name: batcher, tech: Go, desc: Runs the daily payout batch. }
+  - { id: ledger, kind: store, name: ledger-db, tech: Postgres 16, desc: Journals and entries. }
+  - { id: vaultic, kind: external, name: Vaultic, desc: Acquirer; executes SEPA transfers. }
+edges:
+  - { from: core, to: settler, label: publishes charge.captured, tech: Kafka, kind: dashed }
+  - { from: settler, to: ledger, label: posts capture journals, tech: SQL }
+  - { from: api, to: ledger, label: reads balances, tech: SQL }
+  - { from: batcher, to: ledger, label: posts payout journals, tech: SQL }
+  - { from: batcher, to: vaultic, label: creates transfers, tech: REST }
+  - { from: vaultic, to: api, label: transfer status webhooks, tech: HTTPS, kind: dashed }
+```
+
+Charge capture stays in marketplace-core, so a Marram outage delays payouts but
+never blocks checkout. Vaultic's webhooks land on payout-api, not the batcher —
+a batch crash therefore never loses a settlement status.
+
+## The ledger
+
+```erd
+id: ex-backend-erd
+entities:
+  - name: journals
+    columns:
+      - { name: id, type: uuid, pk: true }
+      - { name: kind, type: text }
+      - { name: created_at, type: timestamptz }
+  - name: entries
+    columns:
+      - { name: id, type: uuid, pk: true }
+      - { name: journal_id, type: uuid, fk: true }
+      - { name: account, type: text }
+      - { name: amount_cents, type: bigint }
+  - name: transfers
+    columns:
+      - { name: id, type: uuid, pk: true }
+      - { name: seller_id, type: uuid }
+      - { name: journal_id, type: uuid, fk: true }
+      - { name: status, type: text }
+relations:
+  - journals ||--o{ entries: contains
+  - journals ||--o{ transfers: funds
+```
+
+A seller's balance is `SUM(amount_cents)` over their entries — there is no
+balance column to drift. The read costs about 30 ms across the 90-day hot
+partitions, and payout-api pays that price on every balance call.
+
+## The daily payout run
+
+```sequence
+id: ex-backend-seq
+endpoint: { method: POST, path: /transfers }
+actors:
+  - { id: Batcher, name: batcher, sub: "daily 14:00 UTC" }
+  - { id: PG, name: ledger-db, sub: Postgres }
+  - { id: Vaultic, name: Vaultic, sub: acquirer, external: true }
+messages:
+  - { from: Batcher, to: PG, label: SELECT due balances, summary: "Sellers with settled balance of 10 EUR or more; about 38k rows." }
+  - { from: PG, to: Batcher, label: due sellers, kind: response }
+  - { from: Batcher, to: Batcher, kind: note, label: derive transfer_id, summary: "transfer_id = date + seller_id, so every retry names the same transfer." }
+  - { from: Batcher, to: Vaultic, label: POST /transfers, summary: "One transfer per seller, transfer_id as the external reference." }
+  - { from: Vaultic, to: Batcher, label: 504 timeout, kind: error, summary: "On timeout the batcher retries the same transfer_id; Vaultic dedupes on it." }
+  - { from: Batcher, to: Vaultic, label: retry POST /transfers }
+  - { from: Vaultic, to: Batcher, label: 201 accepted, kind: response }
+  - { from: Batcher, to: PG, label: post payout journal, summary: "The journal posts only after Vaultic accepts — the ledger never claims money that did not move." }
+foot:
+  - { label: Batch window, value: "14:00–14:40 UTC" }
+  - { label: Idempotency, value: "transfer_id, replay-safe" }
+```
+
+Retries reuse the transfer_id and Vaultic deduplicates on it, so a seller
+receives at most one transfer per day. A crashed batch is rerun whole, with
+no reconciliation step.
+
+## Who owns what
+
+```table
+columns: [Service, Responsibility, On-call]
+rows:
+  - [payout-api, "Balance reads, payout status, Vaultic webhooks", Payments Core]
+  - [settler, "charge.captured events → capture journals", Payments Core]
+  - [batcher, "Daily selection, transfer execution, payout journals", Money Movement]
+  - [ledger-db, "Journals and entries — the source of truth", Payments Core]
+```
+
+## The invariant
+
+```callout
+tone: danger
+title: Journals balance; entries never change
+body: "Every journal's entries must sum to zero — a trigger rejects the whole insert otherwise. Posted entries (#ex-backend-erd) are never updated or deleted; a correction is a new reversing journal. Any code path that edits an entry in place is a bug, whatever it fixes."
+```