docs: check in CLAUDE.md, refreshed against the current tree

[stormer78]

CLAUDE.md was untracked — every contributor had their own copy, or none. This checks it in and corrects what had gone stale.

Why it needed correcting

Its named defects are the parts most likely to be trusted verbatim, and all three had been fixed:

Rule	Said	Reality
R3.7	consentRequiredFrom matches a code the VTA never emits	Fixed — matches details.reason
R1.5	inbound session schedules one 2s retry from onClose	Fixed on the worker path (#88) and the approver inbox (#97)
R1.2	handleApiGet/handleApiPost hangs the page for minutes	Fixed in #88; it is now the compliant reference

A doc that points at already-fixed bugs sends the next person hunting for them, and — worse — implies the remaining problems are covered.

Each stale example is replaced with the invariant that actually bites now:

• R3.7 — a Response body reads once; an already-parsed body must use errorFromBody, never a re-read of the spent Response (that throws into a swallowing catch and degrades to a status-only guess) — fix: parse error bodies before throwing on status (R3.7) #99
• R1.5 — cap the delay, never the attempt count; re-arm on every failure including first-connect, since onClose cannot fire for a session that never opened; use ReconnectScheduler — fix: re-arm the approver inbox with exponential backoff (R1.5) #97
• R1.2 — apply the timeout where fetch is injected, because a literal grep "fetch(" finds almost nothing here — fix: bound every outbound fetch with a timeout (R1.2) #98

The one genuinely open defect

Promoted R1.6 persist-before-ack to its own section, since it is the only live one and is not fixable from this repo: vti-didcomm-js acks before dispatching to onMessage, and the wallet persists only the message id — so an offscreen teardown mid-prompt loses a task-consent/request permanently. Needs a library change or disabling auto-ack, and affects pnm-relay too (R4.1).

New: repo mechanics

The traps that actually cost time this week, so they cost the next person nothing:

• build core before typechecking dependents — each workspace typechecks against gitignored dist, and a stale one produces phantom errors in correct source
• lint is tsc -b, never tsc -b --noEmit (TS6310 when a referenced composite project must emit)
• no cross-workspace import without the matching references entry
• what CI asserts, including the MV3 single-bundle / no-import() invariant
• stub with real Response objects, not { ok, json } literals
• Node unrefs the AbortSignal.timeout timer — passes locally, fails in CI as "Promise resolution is still pending"

Verification

Docs only — no code changed. CI runs anyway; lint/build/test are unaffected.

Worth a read rather than a rubber-stamp: it now asserts things about the codebase, and I'd rather you catch anything I've overstated.