# Building a recorder extension: what we learned

Four guides, written from five weeks of a human and an agent building a Manifest V3 browser
extension that records a web application's own network traffic, against an undocumented target
that changed its entire API stack mid-project.

**These are deliberately generic.** The original target is never named; it appears as "the
target" and "the API". What transfers is the method, the architecture and the failure modes —
not the parsers.

## The guides

| | | Read it for |
|---|---|---|
| **01** | [The method](01-method.md) | How the human and the agent divided the work, the capture loop, evidence discipline, why corrections stay where the mistake was, and the failure modes to expect. **Read this one first.** |
| **02** | [The extension](02-extension.md) | MV3 architecture: MAIN vs ISOLATED world, intercepting without disturbing, capture modes, storage design, the circuit breaker, build provenance, and the boundary that only fails once the data gets big. |
| **03** | [Reading payloads nobody documented](03-payloads.md) | Probing envelopes, deriving timestamps from identifiers and proving them, reading markup rather than English, reassembling a document-shaped payload, failing closed, and two sampling mistakes to expect. |
| **04** | [Vaults, handover, and surviving your own death](04-vaults.md) | The code/data store split, the regenerable-derivation contract, the four documents that make a stranger productive, per-entity records with history, and what to do when the container resets mid-task. |

## The five sentences

If you read nothing else:

1. **Build a deliberately stupid recorder first.** No parsers, no domain model — just keep the
   bodies. Every parser you write afterwards is written against evidence instead of a guess, and
   being wrong costs a re-run instead of a re-capture.

2. **Verify every derived fact against an artefact the system itself produced.** Every claim
   that survived this project was checked against something the target emitted independently;
   every claim that collapsed was plausible and unchecked.

3. **The expensive bugs do not throw.** Running an old build, a size cap that excludes exactly
   the evidence you are testing for, `res || {}` turning "no answer" into "an empty answer",
   `new Blob([undefined])` writing the word "undefined" into a file. Each looked like success
   for days or weeks.

4. **Missing is `null`, and `null` never becomes `0`, `''` or `{}`.** Report coverage next to
   results, so "there is no edge here" and "we never looked here" stay different sentences.

5. **Leave the corrections in.** A doc with visible errata is one you can trust the rest of.

## Provenance

Written 2026-09-08, from a project at version 0.16.0: ~3,400 lines of extension source, 176
tests, 33 numbered lessons, 12 capture runs. Every incident described here happened, and the
numbers quoted are measured rather than illustrative.