agenticreplay 0.1.0 → 0.1.2

package/docs/plugins.md

@@ -1,250 +0,0 @@
-# Writing a plugin
-
-There are exactly two extension points, and they are deliberately small. A surface you can widen
-later beats one you must support forever.
-
-## Adapter — how to launch and instrument one agent
-
-```ts
-import type { Adapter, RecordContext, Launch } from '@agenticreplay/plugin-api';
-
-export const myAgent: Adapter = {
-  id: 'my-agent',
-  harnessVersions: '>=1.2.0 <2',
-
-  async detect(cwd) {
-    // Cheap check: is this agent plausibly in use here?
-    return existsSync(join(cwd, '.myagent'));
-  },
-
-  async prepare(ctx: RecordContext): Promise<Launch> {
-    return {
-      command: 'my-agent',
-      args: ctx.userArgs,
-      env: {
-        // The whole trick: point the agent at the local recording proxy.
-        OPENAI_BASE_URL: `${ctx.proxyUrl}/v1`,
-      },
-    };
-  },
-};
-```
-
-That is the entire required surface. `sessionState?()` is optional and only worth implementing if
-your harness exposes internal state a fork would otherwise lose (context compaction state, todo
-lists, memory files).
-
-**Before you write one**, check whether the agent respects a base-URL environment variable. That
-single fact decides how much work an adapter is — not, any longer, whether one is possible. There
-are three capture mechanisms, and an adapter picks whichever the harness allows:
-
-| The harness… | Capture by | Adapter looks like |
-|---|---|---|
-| reads a base-URL variable | pointing it at `ctx.proxyUrl` | one or two lines, as below |
-| is JavaScript and reads none | the fetch hook — see `node.ts` | a preload plus `NODE_OPTIONS` |
-| is neither | `--tls-intercept`, at the socket | nothing at all — see `exec.ts` |
-
-If it reads an unusual variable, the generic OpenAI adapter probably already covers you: it sets
-`OPENAI_BASE_URL`, `OPENAI_API_BASE` and `ANTHROPIC_BASE_URL` at once and takes the command from
-argv. If it reads none and is not JavaScript — a bot with its origin typed into its source, a Go
-binary, an editor that spawns the agent as a child — `agenticreplay record exec --tls-intercept -- <cmd>`
-records it with no adapter at all, and an adapter is only worth writing if you want a name for it.
-
-An adapter that relies on interception must say so with `capture: 'transport'`. It redirects
-nothing, which is otherwise indistinguishable from the broken adapter the contract's
-`redirects-model-traffic` check exists to catch; declaring it takes that one check's exemption and
-no other. See [SECURITY.md](../SECURITY.md) for what interception does and does not decrypt.
-
-### `artifacts` — when the harness's product is not the working tree
-
-Optional, and most adapters need none of it: a coding agent's output *is* the working tree, and
-the ordinary snapshot already holds it. A pipeline is the case this exists for — what it produces
-is an index or a cache, written to a path its own `.gitignore` excludes, because nobody wants a
-hundred megabytes of vectors in their repository.
-
-```ts
-artifacts: {
-  /** Snapshot these even where the workspace's .gitignore excludes them. */
-  capture: ['cache', 'vector_store', 'dataset'],
-  /** Delete these before a replay launches the harness. Whole paths, never "the valid parts". */
-  resetBeforeReplay: ['cache', 'vector_store'],
-  /** The flag `agenticreplay replay --serialize` reaches for. Declared; never applied on its own. */
-  concurrencyFlag: { flag: '--concurrency', serialValue: '1' },
-}
-```
-
-Three things worth knowing before you use it:
-
-- **`capture` cannot reach a credential.** The sensitive pathspecs are applied to the forced add
-  as well, and a pathspec exclusion is enforced by `git add` itself — no `-f` and no `.gitignore`
-  negation overrides it. An adapter declaring `.` still captures no `.env`.
-- **`capture` the inputs too, not only the outputs.** The corpus a pipeline reads is usually
-  ignored alongside the index it writes, and a replay in the recording's own directory finds it
-  anyway — which is what makes the omission easy to miss. A replay in a scratch worktree, or on
-  another machine, then starts with nothing to read and reproduces nothing.
-- **`resetBeforeReplay` deletes whole paths.** A pipeline that resumes skips by item id *including
-  items it recorded as failures*, so keeping what looks valid promotes the last run's failures to
-  completed work. AgenticReplay deletes only where it restores the tree afterwards; under `--in-place` it
-  warns and leaves them alone.
-
-### `replayArgs` — argv for a harness with no prompt
-
-`driveArgs` answers "what makes the agent ask the recorded question again", and it only applies to
-a harness with a transcript agenticreplay can read. A pipeline has neither: its argv *is* the whole
-instruction. `replayArgs(recorded)` is consulted before the transcript, so such an adapter can
-still adjust what a replay runs; return `undefined` to leave the recorded argv exactly as it was.
-
-### `RetrievalRule` — an endpoint whose answer is a function of its request
-
-Embeddings and rerank are not model exchanges and are not opaque traffic either. A rule claims the
-path, keys the call by its own body, and the recording serves it back:
-
-```ts
-const myEmbeddings: RetrievalRule = {
-  id: 'my-embeddings',
-  matches: (path) => path.endsWith('/embeddings'),
-  key: retrievalKey,                 // sha256 of the key-sorted request; override to narrow it
-  describe: (raw) => `${raw.input.length} inputs`,
-  forkable: false,                   // always — see below
-};
-```
-
-`forkable` is `false` and typed as the literal, not left off: changing an embedding model changes
-the vector space the index was built in, which is a rebuild rather than a fork. Keeping retrieval
-on the recording is precisely what makes `agenticreplay replay <run> --from N --model <other>` mean
-something — the chat model changes, the index does not.
-
-An optional `batch` handles the case where the same texts arrive in a different order on every run
-(a worker pool assembling the batch), but **only** where the endpoint's own contract guarantees
-which answer belongs to which input. OpenAI embeddings carries `data[i].index`; Cohere's embed
-does not, so it declares no `batch` rather than assuming one.
-
-See [integrations.md](integrations.md#rag-and-retrieval-frameworks) for the whole picture.
-
-## The adapter contract
-
-Adapters rot. A harness renames the variable it reads for its API origin, the adapter keeps setting
-the old one, and nothing looks wrong: the agent answers, the exit code is zero, and the trace is
-empty. `checkAdapterContract` is the guard against that, and it runs against any adapter — ours or
-yours:
-
-```ts
-import { checkAdapterContract, formatContractResult } from '@agenticreplay/adapters';
-import { myAgent } from './my-agent.js';
-
-const result = await checkAdapterContract(myAgent);
-console.log(formatContractResult(result)); // "my-agent: ok (9 checks)"
-if (!result.ok) process.exitCode = 1;
-```
-
-It never throws and it runs every check even after one fails, so one pass gives you the whole list.
-Pass `{ ctx: { userArgs: ['my-agent'] } }` if your adapter takes its command from argv.
-
-Nine checks are registered, and the count in that line is how many actually **ran**: a check that
-does not apply is skipped rather than counted as a pass. Only one skips today —
-`harness-versions`, when an adapter declares no range — so an adapter without a
-`harnessVersions` field prints `ok (8 checks)` and one with a range prints `ok (9 checks)`. The
-adapter above declares `>=1.2.0 <2`, so it gets nine.
-
-Each check is here because breaking it fails *silently*:
-
-- **`id-format`** — lowercase kebab-case. The id is what a user types after `agenticreplay record` and what
-  the trace records; mixed case and underscores turn into support questions.
-- **`detect-resolves`** — `detect()` must resolve, for a real directory and for a path that does not
-  exist. The registry reads a throwing detector as "no", so yours would silently never match, and
-  any caller that does not guard loses detection for every other adapter too.
-- **`prepare-shape`** — a non-empty `command` and an `args` array of strings. argv is a list, never
-  a pre-joined command line.
-- **`redirects-model-traffic`** — the env must set at least one of `ANTHROPIC_BASE_URL`,
-  `OPENAI_BASE_URL`, `OPENAI_API_BASE`, and *every* base-url variable it sets must point at
-  `ctx.proxyUrl`. This is the check that catches rot: point a variable the harness no longer reads
-  and capture returns nothing while everything still appears to work.
-- **`no-invented-keys`** — never fabricate a credential the incoming `ctx.env` did not have. Use
-  `passKey()` where the harness refuses to start without one — it substitutes an obviously-fake
-  placeholder — and `passThrough()` for a second provider. Harnesses pick a provider from the
-  credentials they can see, so an invented key can change which model the run calls.
-- **`no-ctx-mutation`** — `agenticreplay record` hands you `process.env` itself as `ctx.env` and the parsed
-  argv as `ctx.userArgs`. Mutating them edits the recorder's own environment and the argv written
-  into the manifest. Copy: `args: [...ctx.userArgs]`.
-- **`deterministic`** — two `prepare()` calls on the same context must agree. Replay prepares that
-  context again, so anything random or time-based reads as a divergence.
-- **`no-foreign-paths`** — no absolute path from outside `ctx.runDir` or `ctx.cwd` in the launch
-  env. Write scratch config under `ctx.runDir`, or your home directory ends up in a shared trace.
-- **`harness-versions`** — if you declare a range it has to be a semver range. `latest` says
-  nothing about what you tested.
-
-`packages/adapters/test/contract.test.ts` runs every adapter in `defaultAdapters()` through this,
-so a newly registered adapter is covered without opting in — and runs deliberately broken adapters
-through it too, so every check is proven to bite.
-
-### Start from the scaffold
-
-`scaffoldAdapter('my-agent')` returns the contents of a working adapter and its test — correct
-imports, a `detect` built on `hasBinary`, a `prepare` that redirects to `ctx.proxyUrl`, and one
-`TODO`: confirm which variable your harness actually reads. It returns data rather than writing
-files, so the generated adapter is itself run through `checkAdapterContract` in the test suite.
-
-### A PR adding an adapter includes its harness fixture
-
-`fixtures/harness/<id>.json` records the exact env-var names your adapter sets, the path each base
-url gets, the harness version range you verified against, and the date you verified it.
-`test/harness-versions.test.ts` compares that record to what `prepare()` produces now.
-
-**When a harness changes and you update an adapter, update the fixture in the same PR.** That is
-the whole point: the fixture diff is where a reviewer sees "this adapter now sets a different
-variable", and `verified_at` is the cue to ask whether you ran the harness or guessed. A fixture
-nobody has to touch only records what the adapter used to do.
-
-## Provider — a published interface with no caller yet
-
-**Read this first.** `Provider` is exported from `@agenticreplay/plugin-api` and nothing in AgenticReplay
-calls it. When a replay cursor goes live the proxy forwards the agent's own request bytes to a
-configured upstream, translating only where a fork changed the model — routing that through a
-`Provider` would mean re-serialising a request agenticreplay already holds verbatim, which loses fidelity for
-no gain. To point agenticreplay at a different model API today, use `agenticreplay setup`, or `--upstream-anthropic` /
-`--upstream-openai` per run.
-
-The repo used to ship live `Provider` clients and a registry to resolve them. They were deleted:
-about 400 lines of production code and 570 of tests that nothing invoked, kept alive only by a
-docstring claiming the live path went through them. The *interface* stays, because a format and an
-interface are cheap to publish and a wrong implementation is not.
-
-So implement this to be *ready* for a future live path, or to reuse the shape in your own tooling —
-not because registering one changes what `agenticreplay replay --model` does. It does not, yet.
-
-
-```ts
-import type { Provider, CanonicalRequest, CanonicalChunk } from '@agenticreplay/plugin-api';
-
-export class MyProvider implements Provider {
-  id = 'my-provider';
-  async models() { return [{ id: 'my-model-1' }]; }
-  async *invoke(req: CanonicalRequest): AsyncIterable<CanonicalChunk> {
-    // translate req → your wire format, stream back, yield a final `done` chunk
-  }
-  price(usage, model) { return null; }  // null means unknown — never guess a cost
-}
-```
-
-`price()` returning `null` for an unknown model is deliberate. A confidently wrong cost number is
-worse than an absent one, because it ends up in a comparison table someone makes a decision from.
-
-## The canonical IR, and why exchanges are recorded twice
-
-Every model exchange is stored in **both** forms:
-
-- the **raw provider bytes**, which is what makes exact replay exact;
-- the **canonical form** — a normalized message list, tool schema and sampling params — which is
-  what makes `--model glm-5.3-flash` possible on a run recorded against Claude.
-
-Never discard the raw bytes to save space. Blob dedup already handles size, and a lossy trace
-cannot be replayed exactly, which is the whole point of the tool.
-
-## Neutrality
-
-Plugins get no privileged API. A vendor plugin imports `@agenticreplay/plugin-api` and nothing else,
-and `scripts/check-neutrality.mjs` fails CI if that stops being true.
-
-If your plugin needs a capability the interface lacks, propose it for the public interface — with a
-second implementation showing it is not shaped around one vendor. That rule applies to the
-the maintainers' own provider plugin exactly as it applies to yours.

package/docs/proposals/action-graph-and-reasoning.md

@@ -1,354 +0,0 @@
-# Proposal: the action graph, and an export that produces a picture
-
-Status: **all four steps shipped**. Read against `d20d471`; built on
-`claude/orcaplay-action-causal-graph-jv6ekg`.
-
-| Step | State |
-|---|---|
-| 1. Observed edges, `runGraph()`, `agenticreplay graph --json` | shipped |
-| 2. `renderChainCard()` and `renderGraphCard()` — SVG | shipped |
-| 3. PNG for both cards, and `compare --share` | shipped |
-| 4. GIF of the chain resolving, one frame per hop | shipped |
-
-The rasterizer question was settled the way `docs/media/README.md` already answers it: the render
-toolchain stays out of `package.json`, is imported at the moment of use, and its absence is a
-message naming the one line that installs it. `agenticreplay doctor` reports it, and `.svg` never needs it.
-Deferred to a follow-up: the model's reasoning (section 2), and a graph pane inside the exported
-HTML viewer.
-
-Two things the build found that this plan had wrong. The inference window is one turn, not zero: a
-snapshot races the agent running the tool, so the same recording put an edit in turn 1's snapshot on
-one run and turn 2's on the next. And the fork path was a second call site of the exchange deriver
-that wrote no `causes` at all, so a forked run could be replayed and forked again but not
-explained; both now go through one shared writer.
-
-Three additions were suggested together: an action/causal graph over a run, the model's private
-chain-of-thought, and an artefact with a UI. **The scope is now the first and the third — the graph,
-and a picture export — with reasoning deferred.** Sections 1 and 3 are the plan; section 2 is kept
-for why deferring it is the right call.
-
-The two compose: the graph is what makes a picture worth taking, since a screenshot of a timeline
-list is a screenshot of a list. And the expensive half of both is already in the repository — the
-trace format already declares a causal DAG, and `scripts/` already contains a working GIF encoder.
-
-## What is already here
-
-| Piece | Where | State |
-|---|---|---|
-| `causes` — a normative causal DAG on every event | `spec/agenticreplay-trace-v0.md:40` | shipped |
-| `causalChain()` — transitive backward walk | `packages/core/src/graph.ts:117` | written, tested, **no caller** |
-| `thinking` block in the canonical IR | `packages/plugin-api/src/canonical.ts:12` | parsed, then dropped |
-| Reasoning read in all three wire dialects | `translate/anthropic.ts:140`, `openai.ts:320`, `openai-responses.ts:117` | shipped |
-| Thinking signature survives redaction so forks replay | `packages/core/src/redaction.ts:131` | shipped |
-| Single-file HTML export, zero external references | `packages/viewer/src/export.ts` | shipped, CI-asserted |
-
-A format that can express causality, and translators that can read reasoning out of three different
-protocols, are the hard parts. What is missing is the code that connects them to a reader.
-
-## 1. The action / causal graph
-
-`causes` is populated in exactly three places today: a tool result points back at its call
-(`cli/src/commands/record.ts:193`), a shell result at its exec (`:312`), and a network response at
-its request (`cli/src/tls-capture.ts:180`). That is enough to pair things up and not enough to
-answer *why did it delete my migration file* in one hop.
-
-Four edges are missing, and they are two different kinds of missing.
-
-### What the whole graph looks like
-
-Three turns of one run, every event placed by when it happened and by what kind of thing it is.
-Note what is *not* drawn: a request and its response are one exchange, not an edge, so nothing
-connects them.
-
-```
-                  TURN 1                     TURN 2               TURN 3
-MODEL     2    3 ───┐           ┌─▶ 8   9* ──┐            ┌─▶ 14   15   16
-          req  resp │           │       resp │            │   req  end  exit 0
-                    ▼           │            ▼            │
-TOOL                4 ─▶ 7 ─────┘            10* ─▶ 13 ───┘
-                    edit result              bash   result
-                    ┆                        ┆
-                    ▼                        ▼
-EFFECT              6                        11* ─▶ 12*
-                    auth.ts                  check  exit 1
-                                                    └── nothing consumes this
-
-  ─▶ written into `causes`      ┆▼ inferred, derived at read time, never written
-  *  the chain `agenticreplay graph last --to 12` returns
-```
-
-Two things this makes obvious that the timeline list does not.
-
-The run has a **motif** — request, response, call, effect, result, request — so a 400-event run is
-sixty repetitions of one shape, and anything that breaks the shape is worth looking at.
-
-And seq 12 has **no edge leaving it**. Nothing consumed the failure; turn 3 asks the model nothing
-about it and ends the run at `exit 0`. That absence is the bug, and an absence is far easier to see
-in a graph than in a list.
-
-### The same graph as data
-
-What ships first, and what an agent asking "why did this run fail" actually consumes. Every edge
-names the rule that produced it, so an inferred edge can be argued with:
-
-```console
-$ agenticreplay graph last --to 12 --json
-{
-  "runId": "run_6473f858b59e",
-  "nodes": [
-    { "seq": 9,  "type": "model.response", "attrs": { "stop_reason": "tool_use" } },
-    { "seq": 10, "type": "tool.call",      "attrs": { "name": "bash" } },
-    { "seq": 11, "type": "shell.exec",     "attrs": { "argv": ["sh","-c","node --check …"] } },
-    { "seq": 12, "type": "shell.result",   "attrs": { "exit_code": 1 } }
-  ],
-  "edges": [
-    { "from": 9,  "to": 10, "kind": "recorded", "rule": "tool_use block in the response" },
-    { "from": 10, "to": 11, "kind": "inferred", "rule": "argv matches tool input, same turn" },
-    { "from": 11, "to": 12, "kind": "recorded", "rule": "shell frame pair" }
-  ]
-}
-```
-
-`causes` points backwards in the trace, because the spec requires every entry to be less than its
-own `seq`. The graph output turns that around into `from`/`to`, since "9 caused 10" is what a reader
-wants and "10 was caused by 9" is only what the file can store. The `kind` field is the whole
-honesty mechanism: `recorded` edges came out of `causes`; `inferred` ones were derived just now by
-the named rule and are not in the trace at all.
-
-### Observed — write them into `causes`
-
-These are not inferences. A `tool_use` block is physically inside the response that emitted it, and
-a `tool_result` block is physically inside the request that carried it back. `ExchangeEventDeriver`
-holds both and simply does not record the relationship.
-
-- **`model.response` → `tool.call`.** The loop at `cli/src/exchange-events.ts:117` already iterates
-  the response's tool uses. The `persist()` loop in `record.ts:190` needs to remember the seq of the
-  `model.response` it just appended — the same seq-patch-back shape as `markPending()`, a few lines
-  away.
-- **`tool.result` → `model.request`.** Results are derived *before* the request in the same batch
-  (`exchange-events.ts:60`), so their seqs are known by the time the request event is written. The
-  edge goes on the request, naming the results.
-
-### Inferred — derive them, never write them
-
-Attributing a file change or a shell command to a *specific* tool call is guesswork. Snapshots are
-taken once per turn (`cli/src/fs-events.ts:50`), not once per tool call, and shell frames are
-drained after the agent exits and bucketed into turns by wall clock (`record.ts`, `turnAt()`).
-Matching a changed path against a tool call's `input.path`, or an argv against a Bash call's
-command, is right most of the time and wrong exactly when a run is interesting.
-
-**The rule to hold:** recorded edges go in `causes`; inferred edges are derived at read time and
-never written — the same discipline already applied to checkpoints, which spec §3 defines as derived
-and never recorded. A normative field that sometimes contains a guess is a field no third-party
-reader can trust.
-
-### Where it lands
-
-Extend `packages/core/src/graph.ts` with `runGraph(events)` returning nodes plus typed edges
-(`recorded` | `inferred`, with the inference rule named on each). Expose `agenticreplay graph <run> --json`
-alongside the other `--json` commands, add it to the MCP tool set so an agent can ask what caused
-seq N, and render it in the viewer. `causalChain()` finally gets a caller.
-
-No format change and no version bump: `causes` is already normative and already optional.
-
-## 2. The model's private reasoning — deferred
-
-Cut from the first build, and the cut buys more than it costs: reasoning is the entire privacy
-blocker in this plan, and it would land in exactly the artefact section 3 is about to make
-easier to share. Building the sharing path first means it is hardened before anything sensitive
-travels down it. Nothing is lost by waiting.
-
-It is the closest to done of the three. Reasoning is parsed into `{ type: 'thinking', text }` by
-all three translators and then never becomes an event — `derive()` collects tool uses out of the
-canonical response and nothing else. The extraction is roughly fifteen lines next to
-`collectToolUses()`: `thinking_chars` and `thinking_blocks` in `attrs`, the text to a blob, which
-the 4 KB spill rule already handles.
-
-The raw provider bytes are recorded regardless, so **every trace already on disk contains this**. It
-is a read-path feature, not a capture-path one.
-
-### What "private" honestly means, per provider
-
-| Source | What comes back | Fidelity |
-|---|---|---|
-| Anthropic extended thinking | Full thinking text plus a signature over it | verbatim |
-| Chat-completions `reasoning_content` (DeepSeek, Qwen, GLM) | Full reasoning text | verbatim |
-| OpenAI Responses `reasoning` items | Only the `summary` parts — `openai-responses.ts:117` | summary only |
-| `redacted_thinking` / encrypted reasoning | Opaque ciphertext, no canonical home | unreadable |
-
-Label this per turn in the UI. A capability row that says "private chain-of-thought: works" is the
-row that ends up being the thing that is wrong — the same reason `agenticreplay models` prints a dash rather
-than inventing a price.
-
-### The payoff
-
-The interesting artefact is not the reasoning on its own. It is the reasoning set against what the
-harness actually did and what the terminal actually showed, and agenticreplay is the only layer holding all
-three: *the model said it would verify the fix; the transcript never showed a verification; seq 12
-says the check exited 1 and the run exited 0.*
-
-### The privacy consequence
-
-Reasoning is the highest-density source region in a trace — verbatim code, real paths, and the model
-restating the task in the clear. The README already says to treat a trace as a shell history plus a
-heap dump; this raises that bar, and it lands in exactly the artefact people are encouraged to
-attach to public issues.
-
-So: capture by default (local, `0600`, no change in posture), but **strip it from `agenticreplay export` by
-default** behind `--include-thinking`, extend `agenticreplay scrub` to cover thinking blobs, and keep the
-existing behaviour where export prints exactly what it is about to write. The signature handling at
-`redaction.ts:131` is the precedent — that care has to extend to the new blob, or forks of thinking
-turns break.
-
-## 3. A picture, not just a page
-
-The export already is a self-contained artefact — one HTML file, no external reference of any kind,
-CI-asserted. That property is why it renders from a download folder, on a plane, in five years, and
-it survives all of this. What it is not is a *picture*, and a picture is what travels.
-
-### The repository has already decided this once
-
-`scripts/render-demo.mjs` renders the README hero, and its header comment answers the format
-question outright:
-
-> A GIF rather than an animated SVG because GitHub, X and HN all render a GIF the same way, and a
-> README that only animates in some places is worse than one that animates nowhere.
-
-So this is not a new decision. The encoder is about thirty lines of `gifenc` with one quantised
-palette built from the final frame, and it already uses the technique a chain animation needs —
-**one frame per state change, with the hold expressed as that frame's delay**, because 107
-near-identical PNGs made a 5.5 MB GIF and 22 self-timed frames said the same thing
-(`render-demo.mjs:97`).
-
-The constraint is stated just as plainly in `docs/media/README.md`: `playwright-core`, `pngjs` and
-`gifenc` are *deliberately* not in `package.json`, so `npm ci` stays lean for everyone not
-regenerating README art. That policy is the real design constraint here, and it should be kept.
-
-### Which format
-
-| Where it lands | SVG | PNG | GIF |
-|---|---|---|---|
-| GitHub issue / README | renders | renders | animates |
-| X | not an accepted upload | renders | animates |
-| Slack / Discord | no reliable inline preview | renders | animates |
-
-`packages/cli/src/share-card.ts` proves the cheap path works — 118 lines, no dependencies,
-monochrome, explicitly built to "survive being dropped into an issue, a README, a chat window, or a
-dark-mode client". But SVG is the one raster-free format, and the places that spread things want a
-raster.
-
-**So: SVG is the source, PNG and GIF are the shareable outputs, and the rasterizer is the only new
-dependency.** Keep SVG dependency-free so the command always works; make PNG and GIF opt-in, and
-have `agenticreplay doctor` report whether the render toolchain is present — the same way it already warns
-about a missing POSIX shell and lets you carry on with `--no-shell`.
-
-Worth doing in the same slice: `compare --share` already produces the best shareable asset in the
-project and produces it *only* as SVG, the one format X will not take. A PNG output on that existing
-flag is a handful of lines against an encoder already in the tree.
-
-### What the picture shows
-
-One chain ending at the thing that went wrong — which is exactly what `causalChain()` returns, and
-why section 1 has to land first. From the README's own bug hunt:
-
-```
-Why did this run exit 0 when its own check failed?
-run_6473f858b59e · claude-opus-5 · causal chain, 6 events
-
- seq 3   model.response   stop: tool_use
- seq 4   tool.call        edit_file auth.ts
- seq 6   fs.change        auth.ts +1 −3                    (inferred edge)
- seq 11  shell.exec       node --check nonexistent-file.ts (inferred edge)
- seq 12  shell.result     EXIT 1
- seq 13  run.end          exit 0 — the agent's code, not the check's
-
-dashed = inferred, not recorded
-```
-
-Two deliberate choices. The title states the claim as a *question*, because a card people forward
-has to carry its own context. And the legend ships on the card, because a dashed edge in a picture
-that travels without its trace launders a guess into a fact — the same discipline that makes
-`renderCompareCard` print the verify command next to the costs.
-
-### Attribution
-
-Both cards and the exported page sign themselves, from one constant so they cannot drift:
-
-```
-Recorded with AgenticReplay · github.com/askdkc/AgenticReplay
-```
-
-Shipped ahead of the rest of this plan, since `renderCompareCard` and the viewer footer both
-existed already and both carried the same literal in two packages. It now lives in
-`packages/viewer/src/credit.ts` — `viewer` is the package that already owns what an exported
-artefact says about itself, and `cli` already depends on it, so no new edge in the package graph.
-
-The card sets the two halves against opposite margins at 10px rather than one line at 11px: together
-they are 97 characters, and at 11px they leave 24px between them — a monospace fallback advancing
-0.66em rather than the usual 0.6em overlaps them by 40px. At 10px the gap is 82px.
-
-This makes the README's old "shows up in exactly one place" claim false, so that section now says
-two places and draws the line where it actually matters: a default you can overtype and a credit on
-an artefact you asked for are both opt-in, and neither is a code path or a route. Vendor neutrality
-is about where bytes go, not about a byline.
-
-**Picking the chain is the hard part**, and it *is* the feature. A defensible default: the chain
-ending at the run's most interesting event — a non-zero `shell.result`, an `error`, a `divergence`,
-else the last `fs.change` — with `--seq N` to name one outright. When nothing stands out, refuse
-rather than draw an arbitrary chain; a bad card gets screenshotted anyway.
-
-### The animation
-
-Render the card with hops revealed one at a time, screenshot once per state, carry the hold in each
-frame's delay. Roughly eight frames: title, one per hop, the failing hop held long, the full card
-held longest before it loops. A 720×322 monochrome card quantised to 32 colours lands well under a
-couple of hundred kilobytes — the existing hero GIF is a far busier scene through the same encoder.
-
-**What not to build:** a GIF of `agenticreplay ui` playing the run back. That exists as a docs asset because
-it is a scripted, hand-trimmed *demo of the product*. Generated automatically from an arbitrary
-400-event run it is a long scroll with no climax, and nobody watches a forty-second GIF in an issue
-thread.
-
-## Does this make the project spread?
-
-Two things get conflated. *Screenshot-worthy* is having something surprising to show. *Spreadable*
-is a third party opening it with nothing installed. A causal chain from a prompt to a deleted
-migration file, in five hops, is a far more compelling image than a cost table — and as a PNG or GIF
-it is finally postable where people post.
-
-This does not fully solve distribution: a card is still an image someone has to attach, not a link
-someone can click, and `agenticreplay share` remains the larger question. But it is the cheap two-thirds of
-the answer, it reuses an encoder already in the tree, and it carries no privacy decision — which is
-exactly why it is the right thing to build before reasoning.
-
-## Build order
-
-1. **The two observed edges, `runGraph()`, and `agenticreplay graph --json`.** No format change, no version
-   bump — `causes` is already normative and already optional. Gives the MCP server a "what caused
-   seq N" tool and `causalChain()` its first caller. Everything below depends on it.
-   Touches `core/graph.ts`, `cli/exchange-events.ts`, `cli/commands/record.ts`.
-2. **`renderChainCard()` — SVG, zero dependencies.** Same idiom and same file as
-   `renderCompareCard`. `agenticreplay export last --card chain.svg`. This is the artefact that has to exist;
-   everything after it is a format conversion. Touches `cli/share-card.ts`, `cli/commands/inspect.ts`.
-3. **PNG output, for both cards.** Promote the rasterizer out of `scripts/` into a real module, keep
-   it opt-in, and have `agenticreplay doctor` report whether it is present. Do `compare --share --png` in the
-   same slice.
-4. **GIF — the chain resolving, one frame per hop.** The encoder exists and the technique is proven
-   at `render-demo.mjs:97`. The smallest slice of the four, once step 3 has settled the dependency
-   question.
-
-Deferred: reasoning extraction and the viewer's graph pane. Neither blocks the above, and the first
-carries a privacy decision better made after the sharing path is hardened.
-
-## Risks
-
-- **The wrong chain.** Auto-selection is the whole feature. A card showing an arbitrary chain is
-  worse than no card, because it gets screenshotted anyway. Refuse rather than guess.
-- **Inferred edges written into `causes`,** or drawn on a card with no legend. Either launders a
-  guess into a fact, and the second does it in public.
-- **The render toolchain creeping into `package.json`.** `docs/media/README.md` is explicit that it
-  stays out so `npm ci` stays lean. Degrade to SVG and let `doctor` explain, rather than reversing
-  that quietly.
-- **Staleness with no test.** The existing note is blunt: "a GIF has no test." Generated cards are
-  per-run rather than checked in, but the *renderer* needs a snapshot test or the card drifts from
-  what the commands actually print.

package/docs/validation.md

@@ -1,52 +0,0 @@
-# What a real agent found
-
-Everything in AgenticReplay `v0` was built against fixtures. Fixtures are written by the person who
-writes the code, so they encode what that person already believed — which is why the first run
-recorded through it against a *real* harness is worth writing down rather than quietly fixing.
-
-That run was Claude Code, fixing a real bug in a real repository: recorded, replayed offline end to
-end, forked from a checkpoint, and exported. It broke four things, each of a kind no fixture can
-produce. All four are fixed; each entry says what the fix was, because "we found bugs and fixed
-them" is not information.
-
-## A sixteen-character drift scored 217,568
-
-Distance was the common prefix and suffix of the whole request body, and Claude Code carries a
-session id in its system prompt *and* another in a tool description — so all 200 KB between them
-counted as changed and nothing could reach rung 2 of the matching ladder.
-
-Distance is now summed per field, and per line within a field.
-
-## Redaction made an exact match unreachable
-
-Placeholder digests are salted per run by design, so a recorded request could never equal itself
-again.
-
-The matcher now redacts the incoming request the same way and compares the *kind* of secret rather
-than its digest — and reports that fold, because it is an approximation and a replay must not
-approximate silently.
-
-## Redaction also broke every fork
-
-`tool_use` ids and thinking-block signatures are high-entropy strings, so the sweep replaced them.
-A fork replays those turns, the agent echoes the placeholders back, and the API answers `400`.
-
-Protocol values that have to round-trip are now exempt from the entropy guess — never from the
-credential rules, which is the distinction that makes the exemption safe.
-
-## Replaying re-runs the tools
-
-AgenticReplay does not intercept tool execution, so the agent really runs `npm test` again and it really
-reprints its own durations.
-
-A request whose only difference is inside tool output is now served from the recording as a `major`
-divergence instead of halting the replay.
-
-## Where that left it
-
-The run replays offline end to end — `reused=7/7 canonical_exact=2 divergences=5 unmatched=0 exit=0` — with
-every approximation named, and a fork of it reaches the same tree the recording did.
-
-**If you have a recording agenticreplay still gets wrong, that is the single most useful thing you can
-send.** `agenticreplay export last -o bug.html` writes one self-contained file, and `agenticreplay scrub` is there for
-anything you need out of it first.