@@ -145,7 +145,7 @@ else, and it never touches the corpus:
 | `decompose.mjs` | Phase 0 coordination: recipe parsing, docs-host discovery, material gathering (scrape-budget accounting via the corpus's `cacheDecision` — a cache hit is not an attempt), draft MAP writing. Contains **no judgment** — it seeds the checklist and gathers material; it never writes a status. | — |
 | `dimensions.mjs` | The universal, domain-agnostic subtopic checklist and its mechanical presence-matching (`coverageOfUniversals`). Recipes add on top of it; nothing replaces it. | — |
 | `provenance.mjs` | The tamper-evident fetch ledger: `appendFetch`, `verifyLedger`, `rebuildLedger` (the one metadata-migration path — guarded, per-entry `migrations` records, chained `op: 'migration'` boundary), and the overrides log writer. Also **the collector's exclusive section** (`withLock`), acquired with `O_EXCL` (`flag: 'wx'`) so the kernel refuses a second creator instead of letting it overwrite; staleness is judged only *after* EEXIST proves someone holds the file, and a fresh lock that names no pid — the window `O_EXCL` leaves between create and write — is waited for, never broken. Reentrant in-process, so `appendFetch` can serialize its own read-modify-write inside a run that already holds the lock, and release removes only the acquisition it made (pid + nonce). Every writer of the chain — append, tail repair, rebuild — goes through that one lock. `verifyLedger` also **classifies** a body hash that does not recompute (`isLineEndingRewrite`, `hashText`): folding CRLF back to LF either restores the recorded hash or it does not, so `body-unmodified` problems carry `kind: 'line-endings' | 'modified'` and the consumer can name the right cause instead of guessing (ADR-0020). | ADR-0003 (corpus-adjacent), ADR-0020 | **Release is ownership-positive (fixed 2026-09-21):** the lock is unlinked only when the nonce POSITIVELY matches. An unreadable lock is left alone — while a collector works its lock can be truncated, recovered as stale by a second collector and replaced by that collector's own, and unlinking then would delete a lock this process does not hold and admit a third writer to the section. Failing to release is recoverable by the staleness path; deleting someone else's is not.
-| `checks.mjs` | The **ordered contract-check registry**: discovery-contract, citations, provenance, transport-provenance, gate-integrity, unknown-closure, subtopic-coverage, capture-completeness, **evidence-supersession**, collection-attempts, hygiene, corpus-shape — twelve, in a pinned order. Every check is a pure function of the corpus snapshot + options; none reads the filesystem. **`supersededRows(corpus)`** is the one shared answer to "which rows have been replaced by a fresher capture of the same URL": `evidence-supersession` refuses an unknown still resting on a replaced row, `transport-provenance` goes quiet about a replaced row nothing relies on (but not about one still cited), and `hygiene` stops calling a refresh a duplicate while still catching two rows of one URL fetched the same day. Those last two are ADR-0026-aware: they warn about the state that ADR requires. | ADR-0004, ADR-0026 |
+| `checks.mjs` | The **ordered contract-check registry**: discovery-contract, citations, provenance, transport-provenance, gate-integrity, unknown-closure, subtopic-coverage, capture-completeness, **evidence-supersession**, collection-attempts, hygiene, corpus-shape, **corroboration** — thirteen, in a pinned order. Every check is a pure function of the corpus snapshot + options; none reads the filesystem. A check that **instructs** the reviewer owns the accuracy of the instruction, not just of the verdict: `capture-completeness/partial-render` names the EVIDENCE row and the `[render-reviewed: ...]` syntax because it used to name a `renderReview:` front-matter line, and a reviewer who obeyed it edited a hashed capture and got a blocking `provenance/body-unmodified` failure instead of a closed warning. The wording is pinned by test for that reason. **`supersededRows(corpus)`** is the one shared answer to "which rows have been replaced by a fresher capture of the same URL": `evidence-supersession` refuses an unknown still resting on a replaced row, `transport-provenance` goes quiet about a replaced row nothing relies on (but not about one still cited), and `hygiene` stops calling a refresh a duplicate while still catching two rows of one URL fetched the same day. Those last two are ADR-0026-aware: they warn about the state that ADR requires. | ADR-0004, ADR-0026 |
 | `similarity.mjs` | **Near-duplicate detection between two captured pages**, and nothing else. Word shingles (5-word, case- and punctuation-folded, URLs stripped) reduced to a 128-hash MinHash `sketch`; `similarity` estimates Jaccard, `isMirror` compares it to `MIRROR_THRESHOLD`, and `documentGroups` single-link-clusters rows into distinct DOCUMENTS. Exists because `corroboration` counted HOSTS and therefore **inverted** on a mirror: a republished copy on an unrelated host scored `independent` - the registry's best grade - while carrying one witness plus a staleness `freshness` cannot see, since that check grades when a page was FETCHED. `MIRROR_THRESHOLD = 0.25` is **chosen from measurement, not taste**: all 1081 capture pairs in this repository were compared on 2026-09-21, the known stale mirror (`nodejs.org` x `lira.epac.to`, six majors apart) scored 0.3879 and the highest-scoring genuinely different cross-host pair scored 0.0275 - a fourteen-fold gap, so the line is not delicate. `sketch` returns **null** below `MIN_SHINGLES`, and every caller must read null as "cannot tell" rather than "different", which is why two unjudgeable rows stay two documents instead of merging into an invented mirror. Hashing is seeded FNV-1a so a sketch is identical across runs and platforms - a fingerprint that decides a gate finding must grade the same corpus the same way everywhere. Judges no meaning and cannot tell a correct page from a wrong one (ADR-0013). | ADR-0036 |
 | `preflight.mjs` | **The verdict** and the **verdict context**. Assembles findings from CHECKS into pass/fail; one function, three callers (commit gate, edit gate, CLI) so they cannot disagree. Owns the verdict's input unit: `verdictContext(root)` reads the corpus, the gate state (`readGateState`), and the operator's `evidencePolicy` together — same snapshot, same verdict, by construction. | ADR-0004 |
 | `gate.mjs` | Gate policy: `isGated` (the four markers), `evaluate` (commit/edit), the GATE_OFF override recording, and the architecture-map rule (`architectureMapBreach` over `loadGateConfig` — guarded paths are project configuration, `research/kit.json`, defaults `src/lib/bin/scripts/app`). Contains no repo-specific path. **One deliberate exception to "no CLI parsing"**: the commit gate's staged-path list arrives as *data on a pipe* (`stagedPathsFromStdin` / `splitPathList`), because argv was O(n²) to build and bounded besides. It returns **null for "stdin could not be read" and `[]` for "read, and empty"** — conflating them would hand the verdict an empty staged set, which it allows, i.e. a gate that silently stops gating. `stdinIsReadable()` asks `isatty(0)` rather than inferring from the file type, which gets two cases wrong in opposite directions (a socketpair is not a FIFO; `/dev/null` is a character device but reads as immediate EOF). | ADR-0002, ADR-0007, ADR-0008, ADR-0020 | **An unreadable index BLOCKS (fixed 2026-09-21).** The commit gate judges staged bytes (ADR-0024); when `git checkout-index` fails it used to judge the working tree and note that it had. Noting is not enough — the two differ exactly when it matters, so an environmental git failure silently reinstated the defect ADR-0024 exists to prevent. It now blocks with `judged: 'nothing'` and names `--no-verify` as the recorded override. A project that is not a git repository still judges the tree: there is no index to fail to read. Index materialisation is also **chunked** (250 paths per call) rather than spreading every tracked path into one argv, which on Windows hit the ~32k command-line cap for a large corpus and produced exactly that git failure.
 
@@ -0,0 +1,10 @@
+# The corpus's line endings are integrity, not style.
+#
+# A capture's body hash is taken over the LF bytes the collector fetched. git's smudge
+# filter rewrites every text file on a default Windows checkout (core.autocrlf=true), so
+# without this file the whole corpus fails `body-unmodified` on arrival with nothing
+# actually wrong with it. This file outranks a reader's core.autocrlf. See ADR-0020.
+
+research/raw/* text eol=lf
+*.jsonl text eol=lf
+research/*.md text eol=lf
@@ -0,0 +1,27 @@
+node_modules/
+.DS_Store
+
+# Credentials never belong in a research project (AGENTS.md Rule 6). Note that
+# `firecrawl env` writes the key into .env, which is why the rule says never to run it
+# inside a repository.
+.env
+.env.*
+*.pem
+*.key
+
+# The Firecrawl CLI saves scrape output into .firecrawl/ in whatever directory it runs
+# from. That is a vendor cache, not evidence - the kit's own captures live in
+# research/raw/ with a ledger entry behind each one.
+.firecrawl/
+
+# The kit's local review logs are not evidence.
+research/raw/.usage.jsonl
+research/raw/.failures.jsonl
+research/raw/.diagnostics.jsonl
+research/raw/.fetches.lock
+
+# The chain IS evidence and must travel. The explicit negation is here so a broader
+# dotfile rule added later cannot silently exclude it - this repository lost its ledger
+# exactly that way once.
+!research/raw/.fetches.jsonl
+!research/overrides.log
@@ -0,0 +1,131 @@
+# Research-first project bootstrap
+
+Agent instructions for this project. Read this before planning, designing, or building
+anything here.
+
+## How this project works: two phases, two roles
+
+**Phase 1 - research (this kit).** Close every blocking unknown with fetched primary
+sources, then pass the gate. The output is a briefing, not code: `research/DISCOVERY.md`
+(the contract), `research/EVIDENCE.md` (claims with cached pages behind them), and
+`research/BRIEF.md` (the handoff). Phase 1 never writes product code.
+
+**Phase 2 - build (someone else's job).** A builder - another agent, a different model, or
+a human - takes `research/BRIEF.md` plus `research/` and implements. They should not need
+to re-research anything: if they do, phase 1 was incomplete, and the fix is to collect the
+missing fact rather than to let the builder guess it.
+
+The gate is the handoff point. Before it passes, phase 2 does not start.
+
+## Two machines, two roles
+
+The role is machine config - `role: "collector" | "builder"` in
+`~/.agents/research-kit.config.json`, default `collector`; declare it with
+`node ~/.agents/research-kit/bin/install-hooks.mjs --role builder`.
+
+| | **collector** (the operator's PC) | **builder** (a sandbox, a CI box, a laptop) |
+|---|---|---|
+| holds | the Firecrawl key | no key, no Firecrawl egress |
+| runs | `decompose.mjs`, `research.mjs` | `handoff.mjs`, `preflight.mjs`, the build |
+| a missing key is | a **FAIL** | **informational** |
+| must | push `research/raw/` including its dotfiles | **not collect** - the collection CLIs refuse (exit 2) |
+
+**If you are on a builder machine and there is no brief: you do not collect.** A page
+fetched by hand is not evidence in this kit, and a builder that "re-collects" a missing
+page forges a corpus instead of reporting a gap. Name the missing fact instead.
+
+A builder's first command is:
+
+```
+node ~/.agents/research-kit/bin/handoff.mjs
+```
+
+The remedy depends on the cause, and the command says which: something that did not
+travel is the collector's to push (`git add -f research/raw/`, dotfiles included);
+a corpus that travelled whole and was rewritten on checkout here is fixed **here**, with
+`.gitattributes`, and costs no credits.
+
+## Starting in the wrong place: ask which project, do not hunt for it
+
+The project is the **current working directory**. The kit takes no project argument and
+never will. If the cwd is not the project the operator means - the kit's own repo, a
+parent folder, an unrelated checkout - **ask which project**, and wait. Do not search the
+filesystem, do not infer it from a name, do not look it up on a remote. Searching a
+person's disk to guess his intent reads directories nobody authorised, and the question
+it replaces takes one line.
+
+Signals: no `AGENTS.md`, no `research/` directory, or a `research/` corpus plainly about
+something else. An existing corpus about another topic is the signal doing its job.
+
+## Resuming after an interruption: resume, do not restart
+
+The gate is a pure function of repository state, so orient from disk before touching
+anything. `doctor.mjs` and preflight answer *where this project is*; the last commit
+report and `docs/ARCHITECTURE.md` say *what was happening and why*; `git status` answers
+what is unfinished, and its uncommitted changes are the interrupted task - partial and
+unverified, work in progress, never state to trust. The corpus is already collected and
+spent credits are not spent again.
+
+## Rule 1 - research first, then build
+
+The sequence is decompose -> contract -> collect -> gate -> brief.
+
+0. **Decompose** (collector machine): `node ~/.agents/research-kit/bin/decompose.mjs --topic "<topic>"`
+   drafts `research/MAP.md` seeded with the universal checklist. The tool contains no
+   judgment. Mark every row COVERED (citing U-## rows), DISMISSED (reason required), or
+   GAP.
+1. **Write the intent** in `research/DISCOVERY.md` under `## Build intent`, and enumerate
+   the blocking unknowns FROM the map.
+2. **Collect**: `node ~/.agents/research-kit/bin/research.mjs --plan research/plan.json`. Prefer the page
+   that *owns* the fact over any write-up about it.
+3. **Rewrite** each auto-extracted `Finding` cell into a real claim, keeping the `Raw`
+   cell pointing at the cached page.
+4. **Gate**: `node ~/.agents/research-kit/bin/preflight.mjs`. **Do not start building until it prints
+   PASS.** Evidence must be *fetched*, not typed, and by a named transport.
+5. **Hand off**: write `research/BRIEF.md`.
+
+There are exactly three overrides - `git commit --no-verify`, a deliberate
+`research/GATE_OFF`, and a repository-local `core.hooksPath` - and all three are recorded
+in `research/overrides.log`. If you take one, say so in your reply.
+
+## Rule 2 - questions are for intent, never for facts
+
+At most **3** questions, once, up front, and only about things no document can answer. If
+a question's answer is in public documentation, it is a research task. **Never answer
+"insufficient info" and stop.**
+
+## Rule 3 - known unknowns are allowed, silence is not
+
+Mark a genuinely unreachable fact `KNOWN-UNKNOWN` and write the day-one verification step
+in the `Evidence` cell. An unlabeled gap is the failure mode this project exists to
+prevent.
+
+## Rule 4 - source quality
+
+`P` primary/official carries the design. `S` secondary is context. `L` lead-only is a
+hint, never proof. Never invent a citation. Flag contradictions instead of averaging them.
+
+## Rule 5 - cost discipline
+
+Every scrape spends credits. Plan the queries in `research/plan.json` first, reuse the
+cache (`--refresh-days`), and check the budget with `node ~/.agents/research-kit/bin/research.mjs --status`.
+
+## Rule 6 - secrets
+
+The key lives in the CLI config or the environment. Never write it into this repository.
+
+## The standing protocol
+
+Five rules for how work here is committed and recorded. Documentation, not enforcement:
+no check judges prose, because a gate that judges prose is a gate that will be wrong.
+
+1. **Architecture map current in the same commit.** A commit touching a declared code
+   path (`research/kit.json`) stages `docs/ARCHITECTURE.md` with it. Enforced - and a
+   prompt, not a proof: the gate checks the map was *staged*, not that it is *current*.
+2. **Commit report: five named parts** - what changed / why / what it touched / what you
+   verified / what you got wrong and fixed. The got-wrong line is not optional; if
+   nothing was gotten wrong it is written as "nothing to report".
+3. **An ADR for any choice with a rejected alternative**, dated, with the reason a future
+   explorer would need to avoid re-suggesting it.
+4. **One commit per task - the revert test.** `git revert <sha>` undoes it alone.
+5. **A red suite stops work**, reported immediately and alone, **with the cwd recorded**.
@@ -0,0 +1,75 @@
+# Start here
+
+For me, the operator. Not for the AI.
+
+---
+
+## Where things live
+
+| What | Where |
+|---|---|
+| The kit itself | `~/.agents/research-kit` - installed once, never moves |
+| Research for THIS project | `<project folder>\research\` - working files, leave alone |
+| My one pasteable file | `<project folder>\research\audits\` - named by topic + version + date |
+
+Nothing gets copied between folders. Each project keeps its own research, inside itself.
+
+---
+
+## Starting new research
+
+1. **Open the project folder** - the actual project, never the kit's own folder.
+2. **Say what I want researched.** The agent reads the skill automatically and starts.
+3. **When it's done, ask for the audit** - that's my one file:
+   ```
+   node ~/.agents/research-kit\bin\audit.mjs
+   ```
+   Written to `research\audits\` in the project folder. One attachment instead of ten
+   pastes:
+   ```
+   node ~/.agents/research-kit\bin\audit.mjs --zip
+   ```
+
+If I'm ever unsure which folder I'm in, check before starting - the agent should ask if
+it isn't sure, not go searching my disk.
+
+---
+
+## Picking up where I left off
+
+From inside the project folder:
+
+```
+node ~/.agents/research-kit\bin\doctor.mjs
+node ~/.agents/research-kit\bin\preflight.mjs
+git log --oneline -5
+git status
+```
+
+Then tell the agent to resume. Nothing committed is ever lost, and credits already spent
+are not spent again.
+
+---
+
+## If something looks broken
+
+```
+node ~/.agents/research-kit\bin\doctor.mjs
+```
+
+It names every problem and prints the exact fix. Run it, fix what it says, run it again.
+Stop at READY.
+
+---
+
+## Budget
+
+1,000 Firecrawl credits a month. Resets monthly. Stops cleanly at zero - no surprise
+charges. A research cycle is roughly 40 credits.
+
+---
+
+## The rules the AI follows
+
+Live in `AGENTS.md` inside the kit and every project it touches. I don't need to know
+them - any AI that opens the repo is bound by them.
@@ -0,0 +1,36 @@
+# ARCHITECTURE - the map of the code
+
+What each module owns, the seams between them, and which decision governs each. This is
+a map of the **code**, not of the research: `research/MAP.md` is the topic map - a
+different artifact with a different job, judged by a different check.
+
+The rule this map lives by: a commit touching a **declared code path** (declared in
+`research/kit.json`, defaulting to `src` / `lib` / `bin` / `scripts` / `app`) carries
+this file's update in the **same commit**. The commit gate refuses such commits without
+it.
+
+What the rule proves is deliberately modest: the gate checks this file was **staged**
+with the code, not that it is current - a whitespace edit satisfies it. That makes a
+stale map a deliberate act rather than mere forgetting. A prompt, not a proof.
+
+## The one picture
+
+```
+_Replace this with the shape of the thing you build: the entry points, the modules
+they reach, and the seams between them._
+```
+
+## Modules - what each one owns
+
+| Module | Owns | Governed by |
+|---|---|---|
+| _module_ | _the one concept it is responsible for_ | _ADR or decision_ |
+
+## The seams
+
+_Where modules touch, what is injectable, and why testing can stay offline._
+
+## Current shape, for the record
+
+_Counts and invariants a reader can check against the code: how many checks, how many
+adapters, which defaults._