backdraft 0.7.0__tar.gz → 0.9.0__tar.gz

{backdraft-0.7.0 → backdraft-0.9.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "backdraft",
   "displayName": "Backdraft",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Drop-in provenance for factual claims: one click from any claim to the evidence behind it. Ships the backdraft writing, backfill, and artifact-reading skills; the CLI installs separately (uv tool install backdraft).",
   "author": {
     "name": "Spencer Braun",

{backdraft-0.7.0 → backdraft-0.9.0}/DESIGN.md

@@ -29,7 +29,7 @@ Four verbs:
 - **`ingest`** — deterministically anchor source documents (PDF/xlsx/md/…) into the registry: extract, locate, snapshot snippets, hash.
 - **`read` / `search`** — the gate. Emit token-marked context for a model. Search results are themselves mintable evidence (search that returns nothing citable forces a page read purely to obtain an anchor).
 - **`bind`** — postprocess a written document: resolve tokens, run enabled verification switches, backfill surface forms (doc names, pages, quotes), emit sidecar claims file + binding report.
-- **`render`** — produce the clickable artifact.
+- **`render`** — produce the clickable artifact. Its reader half is `verify`: an artifact carries the checks it wants run in its own legend, so the tool that writes them ships the command that runs them.
 
 ### 3. Substrates (sequenced)
 1. **Skill + CLI, together** (first release). The CLI is the system; the skill is ~a page instructing an agent to use it. Ships both the agent-native wedge and the zero-integration backfill demo.
@@ -143,6 +143,14 @@ Self-contained HTML (plus the machine-readable sidecar): **quotes + receipts + e
 | 2026-08-11 | **An extractor declares the `--config` keys it reads, and an undeclared key is an error.** `--config dpy=300` used to exit 0, ingest, and change nothing: the config boundary was the one place this repo's "failures are data, never warn-and-drop" rule did not hold, and nothing — help, docs, `llms.txt` — said which keys existed, so learning them meant reading `extract/vlm.py` and `extract/snapshots.py`. The `Extractor` protocol gains an optional `config_keys: Mapping[str, str]` (key → one-line meaning) and `check_config` validates against it. Validation happens **after selection and inside `Registry.ingest`**, not in the CLI: `auto` picks per file, so only the chosen extractor can say whether `dpi` is a render setting or a typo, and putting it at the registry means every substrate is covered rather than only the one with a `--config` flag. It raises `ExtractionError` rather than the `UsageError` a CLI-side check would have used — `cli_context` imports the registry, so the registry cannot import `UsageError` back — and both are `BackdraftError`, so the guard maps either to exit 1 and the user sees the same line. Each key is declared once by the module that already owns its default and reads it: the page-render budget (`dpi`, `snapshot_quality`, `snapshot_max_height`) in `extract/snapshots.py`, the provider surface (`api_key`, `base_url`, `model`, `timeout`, `retries`) in `extract/vlm_settings.py`, and the extractors compose those by reference. `pdf-text` declares the page-render keys despite reading none of them itself — the snapshot capture that runs beside it at ingest does, and a user passing `dpi` to a text-layer ingest means the images; declaring by *what one flag on one ingest affects* beats declaring by which function happens to call `config.get`. Tradeoff accepted: declaring nothing means accepting nothing, so an out-of-tree extractor that reads config without declaring it starts rejecting keys it used to receive. That is the intended direction — a silently ignored key is the failure being fixed — and the fix is one attribute. The help text that lists the keys is pinned by a test against the declarations, so a new key cannot be added in code and left undocumented. |
 | 2026-08-12 | **`show` is a gate verb, not a lookup tool.** `backdraft show <token>` answers what a token says — the inverse of minting, for a token that arrived out of an artifact, a draft, or somebody's message, which nothing in the tool could answer before without rebuilding the slug and selector by hand and re-reading a whole page. It therefore *mints what it shows*, exactly as `read` and `search` do: an agent that has seen a snippet through the gate has genuinely read it, so recording it is honest rather than a loophole, and `not_shown` stays true by construction — a status `show` can never produce. That makes a token laundering into a citable one by being looked at, which is the intended behavior and the reason this is in `gate/` and not somewhere neutral. Resolution is bind's path rather than a second reading of what a token means: `kernel.claims.parse_citation` decides `malformed` (so the reserved `bd:calc(...)` form lands identically in both) and `Registry.resolve` decides the rest, which is what makes a status printed here the status bind would print. Two smaller calls. `drifted` prints both snippets *and* mints the anchor standing at the locator now, since that anchor's token is the one worth citing and printing it unrecorded would be the under-minting the gate must never do. And drift does **not** fail the exit code: exit 1 covers `unresolved` and `malformed`, the two statuses where there was nothing to show, because whether a changed source still supports a sentence is bind's question about a document, not a lookup's about a token. Tradeoff accepted: auditing someone else's artifact against a registry now writes ledger rows into the auditor's session, so `skills/backdraft-artifact/SKILL.md` says so and keeps that check reported separately from the artifact's self-checks. |
 | 2026-08-13 | **`ingest` finishes its list; an unreadable source is data, not the end of the run.** `backdraft ingest a.md broken.pdf c.md` used to ingest `a.md`, raise on `broken.pdf`, and never attempt `c.md` — leaving a half-built registry, a message naming only the first failure, and no way to tell which sources landed from which were never tried, so ingesting a folder meant re-running and inferring the state. The loop now catches `BackdraftError` per source and records `(source, reason)`, so every source is attempted, and prints one `!` line per failure under a count (`2 of 3 sources ingested; 1 failed`) whose two numbers add to the whole list — which is precisely the fact the old behavior could not state. This is principle 4 ("failures are data, never warn-and-drop") applied at the boundary it had not reached, and the same shape the page-snapshot note already uses one level down. Grouping differs deliberately: the snapshot note groups by *reason* because one missing poppler explains every document at once, while this lists by *source*, because the source is what the caller has to go fix. The exit code is unchanged at 1 and `guard` remains the only place a `BackdraftError` becomes one — nothing caught per source is re-raised, and the report exits through `fail` like any other error line, on stderr, so a clean run's stdout is byte-identical to before and that is pinned by a test. Tradeoff accepted: a run that fails partway now leaves *more* in the registry than it used to, so "the command failed" no longer implies "nothing happened". The closing line of the report answers that directly — re-running the same list is safe, because a source already ingested with unchanged bytes, extractor and config is a no-op — which is cheaper for a caller than reconstructing the failed half by diffing `ls` against its own arguments. |
+| 2026-08-17 | **The demo cites a web page at a fixed revision, so the capability is visible and stays `resolved`.** URL sources shipped whole — fetch, snapshot, `url`/`fetched_at`, the artifact's live dated link — and none of it appeared at backdraft.dev/demo.html, because both demo sources were local files and the byte-identity test that proved the artifact change safe was the same fact that kept it invisible. The demo gains a third source: the Wikipedia article for Franklin County, Ohio — the county the fictional property sits in and the one its tax appeal is already pending before — cited for two market figures a T12 cannot supply, the county's population and its renter-occupied share. It is ingested at Wikipedia's **permanent link** (`?oldid=<rev>`) rather than the bare article URL. What that gives up is named: the demo no longer shows a live page changing under a citation, which is the better story and belongs in a `drifted` walkthrough rather than the shop window. What it buys is that the front page does not permanently display `drifted` within days of the next edit — a demo that always shows drift teaches that the tool is broken rather than that the source moved — and an immutable revision plus the rendered "as of" date is what a careful analyst cites anyway. The same reasoning is now advice rather than a one-off: the docs, `llms.txt` and the writing skill tell an agent to prefer a fixed-revision address (`?oldid=`, a DOI, an archived snapshot) and to pass `--slug` with it. `--slug` is load-bearing here, not decoration: a permanent link is served from `/w/index.php`, so the default stem would be `index` and every token in the memo would carry it. That is the queued slug-assignment item's problem and is fixed at the fetch layer there, not worked around here. One renderer change came with it. `source_title` took a source's display name from its filename's stem, which for a fetched page is the staging name `fetch.filename_for` invented — so the article titled itself "Index". Where a document carries a URL the slug is the name instead, which is the 2026-08-06 row's rule ("showing both would let the fictional one look authoritative") applied to the one surface that had kept the invented name. It changes nothing for a page ingested without `--slug`, since the slug is derived from that same stem; it defers to whoever named the document when someone did. |
+| 2026-08-18 | **One rule names a source, and every surface that names one uses it.** A fetched page's `filename` is the temporary file `fetch.filename_for` staged the bytes in — `index.html` for a permanent link, a name on nobody's disk — and the 2026-08-06 row settled what to do about it ("showing both would give a reader two names for one thing and let the fictional one look authoritative") for the artifact alone. The four CLI surfaces that name a document kept the fiction: `ingest`'s line, the gate's document list, its table-of-contents headline, and `ls` — which showed *both*, filename in column two and URL in a fifth field, the exact shape that row rejected. `gate.source_name` is now the single owner, exported the way `gate.unit` is and imported downward by `cli.py`, so a writing agent learns a source's provenance from the surface it already lives on instead of being sent to `ls` by the skill. Display only: the slug, the token and everything a citation resolves through are untouched, which is the 2026-08-05 "provenance, never identity" rule. Two consequences named rather than discovered. `ls` loses a field — a fetched row is four columns, not five — so anything parsing column five stops seeing one; that is the point, since column two was a lie and one true name beats two names of which one is fictional. And in the gate's aligned list a URL *overflows* the name column rather than widening it: the column is sized on filenames alone, so one 80-character address pushes its own row's later columns right instead of pushing every row's past column 100. The cost is a ragged right on fetched rows, accepted because the file rows a mostly-file registry is made of stay byte-identical to what they printed before — pinned by a test, the way the artifact's byte-identity is. `bind`'s unmatched-claim report still names a source by filename: the fix cannot be shared into it without a sideways `bind` → `gate` import, which SPEC § Dependency rule forbids, and duplicating the rule there is the reinvention this row exists to end. |
+| 2026-08-19 | **A slug is assigned by a rule, and the rule is written down.** The Open list carried "slug assignment/collision rules" from the first field trial, and URL sources sharpened it into a live failure: `fetch.filename_for` took the stem from a URL's last path segment, so `https://a.example/reports/2025/index.html` and `https://b.example/docs/index.html` both staged as `index.html` and became `index` and `index-2` — two handles that say which is which to nobody, carried by every token in every document written against them, permanently, since a slug is stable once assigned. The rule now has two clauses and they are stated together for files and URLs. A **file** is named by its filename's stem, kebabed and cut to 32 characters, which is unchanged and was never the problem. A **URL** is named by its last path segment, *except* when that segment names the site's plumbing rather than its page — a directory index or generic handler (`_GENERIC_STEMS`: `index`, `view`, `page`, `show`, and a dozen more), an all-digit id, or no segment at all — in which case the host goes in front of it, minus `www.` and minus the port, so the two pages above become `a-example-index` and `b-example-index`. The common case is deliberately untouched: `https://example.com/reports/q4-2025` is still `q4-2025`, because a rule that made every good name uglier to fix the bad ones would be the wrong trade. `_dedupe`'s `-2` stays, demoted from the normal outcome to the backstop it was meant to be — the host is a *better* stem, not a unique one, and two `index.html` pages on one site still collide. Truncation is trimmed on both cuts now (`slug_for` and `_dedupe`), which is the other half of the Open line: a 32-character cut lands on a hyphen often enough that `q4-report-` was a slug this repo could produce, legal in the grammar and reading like a bug. The compatibility statement, said out loud because nothing else will say it: two registries built on either side of this change disagree about a fetched page's slug, and an artifact's tokens are not portable between them. Existing registries are unaffected, and that is not luck — `_find_document` matches a re-fetch on the URL, never the slug, so re-ingesting a page keeps the slug it already has. `--slug` remains the way to overrule all of this and is still the advice for a fetched page worth citing, because `a-example-index` names a site rather than nothing, which is better and is not good. |
+| 2026-08-20 | **`ingest` says which of its three outcomes happened, and how much text came out.** One line served three different events — a document created, a *new generation* of one whose bytes moved, and a no-op that wrote nothing — so an agent re-ingesting after a fix could not tell whether anything had changed, at exactly the moment it most needed to: a new generation is when citations into the previous snapshot begin resolving to a superseded one and `bind` starts calling them `drifted`. The registry already distinguished all three internally (`_find_document`, `_is_noop`, `_upsert_document`) and threw the answer away, so `ingest` now returns an `Ingested` — a `Document` subclass carrying `outcome`, the shape `SearchResults` established for `search`: Addendum A's pinned `-> Document` still holds, every `.slug` caller and every fake is untouched, and the one consumer that cares reads the extra field. Re-deriving the outcome in the CLI was the alternative and would have meant a second implementation of `_is_noop` living away from the first. The wart is named rather than papered over: a dataclass compares by class, so an `Ingested` never equals the plain `Document` the read side returns for the same row, and the two tests that compared them now compare what persists. The second half is a number: the extracted character count, beside the page count on every line. A scanned PDF with no text layer and a page behind a login both ingest cleanly, exit 0 and print a page count like any success, which is how a shell of a source gets cited — and the writing skill's instruction to notice "thin or empty" gave the agent nothing to notice it with. Under `THIN_SOURCE_CHARS` (200) a note names the likely cause by media type and what to do about it. That threshold is a heuristic, which this repo refuses elsewhere on purpose — the `html` extractor is a parse and not a readability guess, because a heuristic that changes its mind moves anchors. This one is admissible for the reason those are not: it is display only, at exit 0, and no token, anchor, status or byte of the artifact derives from it, so being wrong costs one line of advice and never a citation. `chars` counts sheets too, where `read`'s window unit is rows: this is the extraction's volume, not a window into it. Grouping follows the 2026-08-13 rule — thin sources group by cause, since one missing text layer explains every scan at once and each document's own count is already on its own line, while the failure report still lists by source. |
+| 2026-08-24 | **`backdraft verify` — the recipient's check, and the drift bug it found in the spec.** The artifact's whole promise is that someone holding only the file can check it, and until now the instructions for doing so were prose: `skills/backdraft-artifact/SKILL.md` walked an agent through recomputing hashes by hand, which is a deterministic procedure re-implemented per reading — the way a recipient's audit ends up weaker than the producer's. It is now a command, in `render/cli.py` because that module already holds the format's reader half (`render.sidecar`), taking either the `.backdraft.html` or the `.backdraft.json`. Two tiers, and the output names which ran: the record against itself, which needs nothing but the file, and — only where a `.backdraft/` is discoverable — every token re-resolved against the sources. Discovery is from **cwd**, not from the artifact's own directory as `bind` does it from the document's: an artifact is a file people forward, so the folder it landed in is evidence about the recipient's machine and not about which registry produced it. Exit 2 joins `bind`'s, which was documented as "`bind`'s alone"; the shared meaning is "the run completed and the document is not clean", which is exactly what a Stop hook gates on, so a hook written for one now catches the other — the gate's `show` stays at 1, because a lookup answering "that token names nothing" is not a document failing. Read-only and minting nothing, which is the line between it and `show`: showing is minting, and an audit that made its own subject citable would manufacture the evidence it was sent to inspect. A record faithfully carrying an `unresolved` citation still passes tier one — a kept failure is the record working, so the same bytes exit 0 in an inbox and 2 in the project, answering different questions. Two consolidations came with it rather than a third copy of each: `registry.citation_for` is the token-to-status walk `bind` and `verify` both need and the dependency rule forbids either importing from the other, so it sits beside `current_at` for the same reason, with `not_shown` deliberately left out as a fact about a session the caller holds; and `cli_context.claim_words` is the line-item shape, since two commands reporting on the same claims must not print two layouts. The real find was in the spec. `spec/artifact.md` § Checking an artifact and the legend's `verify_this_record` both said the token's hash must prefix `anchor.snippet_sha256` — false for every `drifted` citation by construction, since the token names `drifted_from` (what the author cited) while `anchor` carries what stands there now, and the two differing *is* what drift means. Implemented as written, `verify` would have called every drifted artifact forged: the one status the format exists to carry honestly. Both statements are corrected, which moves the legend and therefore every artifact's bytes — goldens and the demo regenerated — and is worth the churn, because a known-wrong normative instruction shipped inside every artifact is a worse cost than a diff. |
+| 2026-08-24 | **Math is rendered, not forbidden, and MathML is why that is affordable.** An agent writing a memo about coverage writes `$\mathrm{DSCR} = \frac{NOI}{D}$`, and the renderer handed the reader raw TeX — or worse, corrupted TeX, since `$x_1$ and $x_2$` paired its subscripts into emphasis and `\(a^2\)` lost its delimiters to the backslash-escape pass. The alternative on the table was to forbid math in the writing skill, and it was rejected twice over: this product's documents are exactly the finance and science memos that contain formulas, and a skill instruction cannot be enforced against an agent that did not read it carefully, so the corruption would have arrived anyway. Shipping *unrendered* TeX was rejected too — nobody wants to read `\frac{NOI}{D}`, and a document a reader cannot read is not a lesser artifact but a broken one. The target is MathML via `latex2mathml`, behind a `[math]` extra: it is static markup the browser lays out itself, so rules 1 and 2 of § The HTML artifact hold *by construction* rather than by care — no script, no font file, no request — where inlining KaTeX would have cost roughly a megabyte of fonts as `data:` URIs on every artifact, math or not. The tradeoff, stated because it is the one place the format's fixed-at-render promise is soft: MathML leans on whatever math font the reader's system has, so two readers of one artifact may see different glyph quality. That is a smaller and more honest cost than the alternative, and it is bounded — the markup, the spacing, and every character are identical; only the typeface is not. Dollars were the real hazard and the guard is Pandoc's: a memo saying `$250 per unit` and `$1.2M` twice in a paragraph would pair them into nonsense under a naive rule, so an opening `$` must be followed by a non-space and a closing `$` must be preceded by one and not followed by a digit — a currency amount is preceded by a space and therefore can never close a span. Code is skipped rather than scanned, so a shell snippet's `$PATH` and `$HOME` are safe, and the demo regenerates with zero math elements, which is the check that matters. Math is opt-in per call and **off for evidence**: a receipt's snippet must read as it was extracted, not as this renderer would prefer it. Conversion failure is data, at two different reliabilities — `latex2mathml` raises for some malformed input, which surfaces as a wavy mark at the formula and a note giving the reason, and silently degrades for the rest (`\notacommand{x}` becomes an identifier), which cannot be caught and is recorded here as a known limit rather than papered over. |
+| 2026-08-25 | **The registry export is a specified format, or it is not a format.** `backdraft export` has written `"$format": "backdraft/registry-v1"` since v0 — a version string promising a specification that did not exist — while being the only complete, portable form a registry has, and therefore what a second implementation, a migration or an audit actually reads. The gap stopped being theoretical when URL sources added a conditional `meta` key to every exported document: a change to a format with nothing to change against. So spec/registry.md joins tokens, chunking and artifact as normative prose, and the pin is the spec itself rather than a golden file beside it — tests/test_spec_registry.py parses the spec's key tables, exports a registry built to exercise every branch, and fails in both directions, so an undocumented key and a documented-but-absent one are equally a test failure. Two boundaries were drawn rather than blurred. `bindings[].report` stays spec/artifact.md's, quoted opaquely here, because one format with two specifications is one too many and they would drift. And the export is content, not a backup: page images, sheet styling and the FTS index are deliberately outside it, so an export round-trips every citation and every receipt and does not round-trip a database — stated in the spec as a limit rather than left for a reader to discover by restoring one. |
+| 2026-08-26 | **`search` reports the size of the answer, not the size of the page.** `--limit` defaults to 20 and the count line said `20 results` whether twenty matched or two hundred did, which is the silent cap this repo rejects everywhere else — `read` closes with `[Showing 0-464 of 3115 chars. Continue with: …]` for exactly this reason. Search is the surface an agent leans on hardest, since it is how a claim finds its evidence, and relevance order is not the same as the sentence the writer needed: a reader told it has twenty results picks the best of twenty and never learns the twenty-first existed. So `SearchResults` gains `total` beside `phrase_fallback` — the same shape for the same reason, an out-of-band fact riding on Addendum A's pinned `list[SearchHit]` so every consumer and every fake is untouched — and a capped run renders `2 of 56 results` plus a closing line naming the exact widening command, shell-quoted, because a hint carrying `$` or a space that has to be repaired before it runs is not a hint. The count is a `COUNT(*)` over the *same* joins the fetch runs, shared through `_match_sql` rather than written twice: a count that joined differently would report a total the caller can never reach. It is asked for only when the page came back full, since a page the limit did not fill is already the whole answer — so the common uncapped run still runs one query, and the output it prints is byte-identical to what it printed before, pinned as a test the way the artifact's bytes are. Two things were deliberately not built. No `--offset`: paging a relevance-ordered list is a different design question, and `--limit` already exists for the hint to name. And the total is not carried into anything durable — no token, anchor, receipt or artifact byte moves, because how many other sentences also matched is a fact about a query, not about a citation. |
 
 ## Open
 
@@ -150,8 +158,6 @@ Queued and parked work lives in ROADMAP.md; this list is questions still
 awaiting a decision:
 
 - Re-bind/orphan pass on re-ingest of changed docs (chunk ordinal drift)
-- Slug assignment/collision rules (the trailing-hyphen truncation from the
-  first field trial lives here)
 - Distribution: published to PyPI as `backdraft` 0.2.0 (2026-07-28); domain
   backdraft.dev acquired; still open: skill registration, deploying site/
 - First external user (design-partner validation layer vs eval substrate vs

{backdraft-0.7.0 → backdraft-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: backdraft
-Version: 0.7.0
+Version: 0.9.0
 Summary: Drop-in provenance for factual claims: one click from any claim to the evidence behind it.
 Project-URL: Homepage, https://backdraft.dev
 Project-URL: Documentation, https://backdraft.dev/docs.html
@@ -18,6 +18,8 @@ Requires-Dist: python-pptx>=1.0
 Requires-Dist: typer>=0.12
 Provides-Extra: entail
 Requires-Dist: anthropic>=0.40; extra == 'entail'
+Provides-Extra: math
+Requires-Dist: latex2mathml>=3.77; extra == 'math'
 Provides-Extra: vlm
 Provides-Extra: xls
 Requires-Dist: python-calamine>=0.3; extra == 'xls'
@@ -67,11 +69,27 @@ documents: 0
 … plus where settings live and what to do next
 
 $ backdraft ingest sources/t12-summary.pdf sources/underwriting-model.xlsx
-t12-summary  t12-summary.pdf  pdf  3 pages
-underwriting-model  underwriting-model.xlsx  xlsx  2 sheets
+t12-summary  t12-summary.pdf  pdf  3 pages  8865 chars
+underwriting-model  underwriting-model.xlsx  xlsx  2 sheets  2357 chars
 note: extracted with pdf-text (the embedded text layer). Glossy or scanned PDFs extract better through a vision model: set BACKDRAFT_VLM_API_KEY in .backdraft/env.
+
+$ backdraft ingest "https://en.wikipedia.org/w/index.php?title=Franklin_County,_Ohio&oldid=1367935775" --slug franklin-county
+franklin-county  https://en.wikipedia.org/w/index.php?title=Franklin_County,_Ohio&oldid=1367935775  html  1 page  34141 chars
 ```
 
+The demo cites that page for market context. It is Wikipedia's *permanent
+link* — `?oldid=` serves one revision's bytes forever — because a citation into
+a live article reports `drifted` the moment somebody edits it, and the quoted
+sentence would no longer be the sentence there.
+
+Every ingest line ends with how much text came out, and says which of three
+things happened: a document created, a **new generation** of one whose bytes
+moved — which is when citations into the previous snapshot start reporting
+`drifted` — or `unchanged`, a no-op because re-running would reproduce what is
+already there. When almost no text came out, a note names the likely cause (a
+scan with no text layer, a page behind a login) and what to do; it is a note at
+exit 0, because a thin snapshot is still a real one.
+
 **Read.** The page arrives with a citable name over each chunk. This is the whole
 mechanism: what you can cite is exactly what you were shown.
 
@@ -112,6 +130,11 @@ $ backdraft search "24850000"
 [Read the page: backdraft read underwriting-model p2]
 ```
 
+Search shows twenty results by default. A run that hit the limit says so —
+`20 of 56 results` — and closes with the command that shows the rest, because
+"20 results" over an answer of 56 is how a reader concludes it has seen
+everything when it has seen a third.
+
 A cell you can already see mints directly:
 
 ```console
@@ -150,12 +173,13 @@ Multiple citations are `;`-separated in one href.
 
 ```console
 $ backdraft bind memo.md --session s-bridgeview --check value-trace,overlap
-bound 15 claim(s), 16 citation(s) [frontwalk]
-  resolved: 15
+bound 17 claim(s), 18 citation(s) [frontwalk]
+  resolved: 17
   unresolved: 1
-  overlap: pass 11, skip 4
-  value-trace: pass 15
-  ! unresolved: bd:t12-summary:p4.c1:1a2b — replacement reserve of $250 per unit per year @2900
+  overlap: pass 13, skip 4
+    skip 4 — wording overlap does not apply to a single cell
+  value-trace: pass 17
+  ! unresolved: bd:t12-summary:p4.c1:1a2b — replacement reserve of $250 per unit per year @3629
 wrote .backdraft/records/memo.backdraft.json
 
 $ echo $?
@@ -177,6 +201,29 @@ memo.backdraft.html
 That file is the whole deliverable: send it over email or Slack and the
 recipient gets the full experience by double-clicking it.
 
+**The recipient can check it.** `backdraft verify` takes the artifact or its
+sidecar and does the checking that the file is built to make possible: every
+snippet rehashed against the sha256 recorded beside it, every token checked
+against the anchor it names, `summary` recounted from the claims.
+
+```console
+$ backdraft verify memo.backdraft.html
+checked memo.backdraft.html [backdraft/artifact-v1]
+  receipts: 17 of 17 hold
+  record: 17 claim(s), 18 citation(s); the summary recount agrees
+  recorded: resolved 17, unresolved 1
+  sources: no .backdraft/ found from here — not re-checked
+[Re-check against the sources: run this inside the project it was bound in.]
+```
+
+That first tier needs nothing but the file, which is the point — it is the check
+someone who was emailed the artifact can still make. Run it inside the project
+the document was bound in and it also re-resolves every citation against the
+registry, so a source that has changed since shows up as `drifted` rather than
+going unnoticed. Exit 0 when everything it checked passed, 2 when something did
+not, so a hook can gate on it. It opens no session and mints nothing: an audit
+must not make its subject citable.
+
 **Theming.** The artifact ships with a default look and two alternates,
 `press` and `slate`:
 
@@ -244,18 +291,23 @@ address.
 
 ```console
 $ backdraft ingest https://example.com/reports/q4-2025
-q4-2025  q4-2025.html  html  1 page
+q4-2025  https://example.com/reports/q4-2025  html  1 page  18402 chars
 
 $ backdraft ls
-q4-2025	q4-2025.html	html	1 page	https://example.com/reports/q4-2025
+q4-2025	https://example.com/reports/q4-2025	html	1 page
 ```
 
+Every surface names a fetched source by its page. The filename you never see —
+`q4-2025.html` — is the temporary file the fetch staged the bytes in, and it
+exists on nobody's disk, so `ingest`, `ls`, `backdraft read` and the artifact
+all show the URL in its place rather than beside it: two names for one thing
+would let the invented one look authoritative.
+
 The origin travels into the artifact too. A claim citing a fetched page shows
-the URL as a link on its receipt, with the date the bytes were taken, and the
-source list names the page rather than the staged filename. That pointer is the
-half of citing a web page a frozen receipt cannot answer on its own: the
-snippet says what the page said, the link is how a reader asks whether it still
-says it.
+the URL as a link on its receipt, with the date the bytes were taken. That
+pointer is the half of citing a web page a frozen receipt cannot answer on its
+own: the snippet says what the page said, the link is how a reader asks whether
+it still says it.
 
 What it does not do, stated rather than worked around: JavaScript-rendered
 pages give you whatever the server sends to a plain GET, pages behind a login
@@ -299,12 +351,13 @@ the keyless text layer and says so — still storing each page's image, which it
 renders locally. PDF page rendering needs poppler, installed separately; without
 it ingest succeeds without the images and names `snapshot-pages` as the backfill.
 
-Two extras:
+Three extras:
 
 | Extra | Adds | For |
 |---|---|---|
 | `[entail]` | `anthropic` | `bind --check entail`, the model-judge verifier |
 | `[xls]` | `python-calamine` | legacy `.xls` workbooks, values only, rendered the same shape as xlsx |
+| `[math]` | `latex2mathml` | LaTeX in a document becomes MathML in the artifact; without it, formulas render verbatim and `render` says so |
 
 `backdraft[vlm]` still installs: it is an empty compat alias from when the
 vision deps were an extra.
@@ -325,7 +378,7 @@ Three agent skills ship inside the package and in this repo:
 |---|---|
 | [`backdraft`](skills/backdraft/SKILL.md) | writing a new document from sources, citing as it goes |
 | [`backdraft-backfill`](skills/backdraft-backfill/SKILL.md) | attributing a document that already exists |
-| [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | reading someone else's artifact cold |
+| [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | checking and reading someone else's artifact cold |
 
 The CLI is the system; a skill is one page telling an agent to use it. Nothing in
 the skills is required to use backdraft by hand. How the skills reach your agent
@@ -383,9 +436,10 @@ spans are citable. In a sandboxed session run every command as
 | [spec/tokens.md](spec/tokens.md) | the citation token grammar, normatively |
 | [spec/chunking.md](spec/chunking.md) | the deterministic chunker |
 | [spec/artifact.md](spec/artifact.md) | the artifact format, sidecar payload, legend, HTML rules |
+| [spec/registry.md](spec/registry.md) | the registry export format `backdraft export` writes |
 | [demo/walkthrough.md](demo/walkthrough.md) | the whole thing end to end, with real output |
 
-The three files under `spec/` are the portable specification: another
+The four files under `spec/` are the portable specification: another
 implementation reads them and nothing else.
 
 ## Status

{backdraft-0.7.0 → backdraft-0.9.0}/README.md

@@ -42,11 +42,27 @@ documents: 0
 … plus where settings live and what to do next
 
 $ backdraft ingest sources/t12-summary.pdf sources/underwriting-model.xlsx
-t12-summary  t12-summary.pdf  pdf  3 pages
-underwriting-model  underwriting-model.xlsx  xlsx  2 sheets
+t12-summary  t12-summary.pdf  pdf  3 pages  8865 chars
+underwriting-model  underwriting-model.xlsx  xlsx  2 sheets  2357 chars
 note: extracted with pdf-text (the embedded text layer). Glossy or scanned PDFs extract better through a vision model: set BACKDRAFT_VLM_API_KEY in .backdraft/env.
+
+$ backdraft ingest "https://en.wikipedia.org/w/index.php?title=Franklin_County,_Ohio&oldid=1367935775" --slug franklin-county
+franklin-county  https://en.wikipedia.org/w/index.php?title=Franklin_County,_Ohio&oldid=1367935775  html  1 page  34141 chars
 ```
 
+The demo cites that page for market context. It is Wikipedia's *permanent
+link* — `?oldid=` serves one revision's bytes forever — because a citation into
+a live article reports `drifted` the moment somebody edits it, and the quoted
+sentence would no longer be the sentence there.
+
+Every ingest line ends with how much text came out, and says which of three
+things happened: a document created, a **new generation** of one whose bytes
+moved — which is when citations into the previous snapshot start reporting
+`drifted` — or `unchanged`, a no-op because re-running would reproduce what is
+already there. When almost no text came out, a note names the likely cause (a
+scan with no text layer, a page behind a login) and what to do; it is a note at
+exit 0, because a thin snapshot is still a real one.
+
 **Read.** The page arrives with a citable name over each chunk. This is the whole
 mechanism: what you can cite is exactly what you were shown.
 
@@ -87,6 +103,11 @@ $ backdraft search "24850000"
 [Read the page: backdraft read underwriting-model p2]
 ```
 
+Search shows twenty results by default. A run that hit the limit says so —
+`20 of 56 results` — and closes with the command that shows the rest, because
+"20 results" over an answer of 56 is how a reader concludes it has seen
+everything when it has seen a third.
+
 A cell you can already see mints directly:
 
 ```console
@@ -125,12 +146,13 @@ Multiple citations are `;`-separated in one href.
 
 ```console
 $ backdraft bind memo.md --session s-bridgeview --check value-trace,overlap
-bound 15 claim(s), 16 citation(s) [frontwalk]
-  resolved: 15
+bound 17 claim(s), 18 citation(s) [frontwalk]
+  resolved: 17
   unresolved: 1
-  overlap: pass 11, skip 4
-  value-trace: pass 15
-  ! unresolved: bd:t12-summary:p4.c1:1a2b — replacement reserve of $250 per unit per year @2900
+  overlap: pass 13, skip 4
+    skip 4 — wording overlap does not apply to a single cell
+  value-trace: pass 17
+  ! unresolved: bd:t12-summary:p4.c1:1a2b — replacement reserve of $250 per unit per year @3629
 wrote .backdraft/records/memo.backdraft.json
 
 $ echo $?
@@ -152,6 +174,29 @@ memo.backdraft.html
 That file is the whole deliverable: send it over email or Slack and the
 recipient gets the full experience by double-clicking it.
 
+**The recipient can check it.** `backdraft verify` takes the artifact or its
+sidecar and does the checking that the file is built to make possible: every
+snippet rehashed against the sha256 recorded beside it, every token checked
+against the anchor it names, `summary` recounted from the claims.
+
+```console
+$ backdraft verify memo.backdraft.html
+checked memo.backdraft.html [backdraft/artifact-v1]
+  receipts: 17 of 17 hold
+  record: 17 claim(s), 18 citation(s); the summary recount agrees
+  recorded: resolved 17, unresolved 1
+  sources: no .backdraft/ found from here — not re-checked
+[Re-check against the sources: run this inside the project it was bound in.]
+```
+
+That first tier needs nothing but the file, which is the point — it is the check
+someone who was emailed the artifact can still make. Run it inside the project
+the document was bound in and it also re-resolves every citation against the
+registry, so a source that has changed since shows up as `drifted` rather than
+going unnoticed. Exit 0 when everything it checked passed, 2 when something did
+not, so a hook can gate on it. It opens no session and mints nothing: an audit
+must not make its subject citable.
+
 **Theming.** The artifact ships with a default look and two alternates,
 `press` and `slate`:
 
@@ -219,18 +264,23 @@ address.
 
 ```console
 $ backdraft ingest https://example.com/reports/q4-2025
-q4-2025  q4-2025.html  html  1 page
+q4-2025  https://example.com/reports/q4-2025  html  1 page  18402 chars
 
 $ backdraft ls
-q4-2025	q4-2025.html	html	1 page	https://example.com/reports/q4-2025
+q4-2025	https://example.com/reports/q4-2025	html	1 page
 ```
 
+Every surface names a fetched source by its page. The filename you never see —
+`q4-2025.html` — is the temporary file the fetch staged the bytes in, and it
+exists on nobody's disk, so `ingest`, `ls`, `backdraft read` and the artifact
+all show the URL in its place rather than beside it: two names for one thing
+would let the invented one look authoritative.
+
 The origin travels into the artifact too. A claim citing a fetched page shows
-the URL as a link on its receipt, with the date the bytes were taken, and the
-source list names the page rather than the staged filename. That pointer is the
-half of citing a web page a frozen receipt cannot answer on its own: the
-snippet says what the page said, the link is how a reader asks whether it still
-says it.
+the URL as a link on its receipt, with the date the bytes were taken. That
+pointer is the half of citing a web page a frozen receipt cannot answer on its
+own: the snippet says what the page said, the link is how a reader asks whether
+it still says it.
 
 What it does not do, stated rather than worked around: JavaScript-rendered
 pages give you whatever the server sends to a plain GET, pages behind a login
@@ -274,12 +324,13 @@ the keyless text layer and says so — still storing each page's image, which it
 renders locally. PDF page rendering needs poppler, installed separately; without
 it ingest succeeds without the images and names `snapshot-pages` as the backfill.
 
-Two extras:
+Three extras:
 
 | Extra | Adds | For |
 |---|---|---|
 | `[entail]` | `anthropic` | `bind --check entail`, the model-judge verifier |
 | `[xls]` | `python-calamine` | legacy `.xls` workbooks, values only, rendered the same shape as xlsx |
+| `[math]` | `latex2mathml` | LaTeX in a document becomes MathML in the artifact; without it, formulas render verbatim and `render` says so |
 
 `backdraft[vlm]` still installs: it is an empty compat alias from when the
 vision deps were an extra.
@@ -300,7 +351,7 @@ Three agent skills ship inside the package and in this repo:
 |---|---|
 | [`backdraft`](skills/backdraft/SKILL.md) | writing a new document from sources, citing as it goes |
 | [`backdraft-backfill`](skills/backdraft-backfill/SKILL.md) | attributing a document that already exists |
-| [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | reading someone else's artifact cold |
+| [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | checking and reading someone else's artifact cold |
 
 The CLI is the system; a skill is one page telling an agent to use it. Nothing in
 the skills is required to use backdraft by hand. How the skills reach your agent
@@ -358,9 +409,10 @@ spans are citable. In a sandboxed session run every command as
 | [spec/tokens.md](spec/tokens.md) | the citation token grammar, normatively |
 | [spec/chunking.md](spec/chunking.md) | the deterministic chunker |
 | [spec/artifact.md](spec/artifact.md) | the artifact format, sidecar payload, legend, HTML rules |
+| [spec/registry.md](spec/registry.md) | the registry export format `backdraft export` writes |
 | [demo/walkthrough.md](demo/walkthrough.md) | the whole thing end to end, with real output |
 
-The three files under `spec/` are the portable specification: another
+The four files under `spec/` are the portable specification: another
 implementation reads them and nothing else.
 
 ## Status