backdraft 0.5.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,7 +1,7 @@
 {
   "name": "backdraft",
   "displayName": "Backdraft",
-  "version": "0.5.0",
+  "version": "0.7.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/.github/workflows/site.yml

@@ -0,0 +1,36 @@
+name: site
+on:
+  push:
+    branches: [main]
+    paths: ["site/**"]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+# One deployment at a time, and a publish in flight is never cancelled: a
+# cancelled Pages deploy can leave the backend with a deployment that never
+# completes, which is a stuck site rather than a lost run.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+jobs:
+  # Build and deploy are separate so that re-running the failed job re-runs
+  # only the deploy. Bundled, a retry uploaded a second `github-pages`
+  # artifact and `deploy-pages` refused the run for finding two of them.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

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

@@ -135,6 +135,14 @@ Self-contained HTML (plus the machine-readable sidecar): **quotes + receipts + e
 | 2026-07-29 | **The vision extractor ships by default (supersedes "[vlm] as extra").** `openai` + `pdf2image` moved into core dependencies; `[vlm]` remains as an empty compat alias. Rationale: the VLM path is the recommended path for real PDFs, and an extra made the recommended path opt-in. The consent boundary does not move — installing deps was never consent; the backdraft-scoped `BACKDRAFT_VLM_API_KEY` is, and ambient provider keys stay unread. There is no slim install: pip extras can only add, never subtract; a separate core distribution is possible later if anyone asks. poppler stays a runtime capability check. |
 | 2026-07-29 | **Renderer decomposed; Python is the formatting authority.** `render/html.py` (1,300 lines) became the `render/html/` package (fmt, text, components, assets, page), byte-identical at the seam. The deliberate `fmt_cell` (Python) / `fmtCell` (JS) duplication is now pinned by one shared vector table driving both tests, with the JS run under node when available. The JS was found diverging on exact rounding ties (`toFixed` rounds half-up; Python rounds half-to-even on the double's value) and was rewritten to round exactly — Python defines correct, JS matches it. The artifact emits minified CSS/JS and unindented markup; the `$legend` and sidecar JSON stay readable in view-source (spec constraint). Snapshot budget knobs `BACKDRAFT_SNAPSHOT_QUALITY`/`BACKDRAFT_SNAPSHOT_MAX_HEIGHT` tune page-image weight at ingest — display only, tokens never derive from pixels. |
 | 2026-07-30 | **Every PDF ingest captures page images, not just the VLM path's.** The text-layer route stored none, so the keyless path produced visually poorer artifacts for no principled reason — the pages render locally through poppler, no model calls, and the capability already existed as the `snapshot-pages` backfill. The capture is a step *after* extraction, owned by `cli.py` over `extract/snapshots.py`, deliberately **not** inside `pdf-text`: an extractor whose output varied with whether poppler happened to be installed would not be `deterministic = True`, and the same bytes must extract identically on every machine. Because snapshots only ever write `page_images` — a table no token, chunk, or receipt path reads — capture is safe to make best-effort: no poppler means ingest still exits 0, with a one-line note naming `snapshot-pages` as the backfill, rather than failing over a display concern. Tradeoff accepted: PDF ingest is now slower by a local render per page (one poppler call per page rather than one per document, to bound peak memory on long PDFs), and a library caller using `Registry.ingest` directly gets no snapshots — the policy lives at the CLI, which is the substrate that has a user to notify. |
+| 2026-08-03 | **The card divides its own height; nothing inside it is pinned.** The receipt card is user-resizable, so it is a flex column: header, source selector, source line and tabs are fixed rows that never scroll away, and the evidence region takes whatever is left — dragging the card taller grows the evidence rather than the whitespace under it. The caps that survive are relative (the card at `82vh` of the window; the quote, drift diff and record at `40%` of the card), and a `5rem` floor keeps the evidence from vanishing at the card's minimum, with the citation scrolling instead. Resizing means *more*, not *smaller*: the page image keeps its scale and the pane scrolls over it, because a page shrunk to fit a short card is a page you cannot read, while the sheet window — which has no scale to lose — grows to fill, matching the full-sheet overlay it opens into. Both sheet views now stick their headers from one rule. Display only, as ever: no token, receipt or record moves, and the phone card keeps `resize:none` and the fixed caps it always had, since there is no drag there for the evidence to follow. |
+| 2026-08-04 | **A theme is an override block, not a stylesheet.** The artifact's look is themeable, and a theme is a small TOML file naming values for the CSS custom properties the stylesheet already exposes — the sixteen colors and the three font roles — plus four bounded heading knobs (family, case, weight, tracking) that the theme module compiles into one rule over the document's own headings (`HEADING_SELECTOR`) that it owns. The built-in stylesheet is not edited and not replaced: the resolved theme is emitted as a block *after* it, so with nothing configured the artifact is byte-identical to an untheme'd build and theming is provably inert by default. A theme may not touch layout, structure, or any verification affordance, and never touches a token, receipt or record — `--rail-w` and `color-scheme` are deliberately outside the allowlist for that reason, and so is the artifact's refusal to follow the reader's system theme. Keys and values are both validated against declared allowlists, so `--colour` or `#GGG` fails by name before anything is written rather than producing a half-styled file; `url(...)` is rejected with the reason, since a font the file would have to fetch is exactly what the CSP forbids. Precedence is `--theme` > project `.backdraft/theme.toml` > XDG `~/.config/backdraft/theme.toml` > built-in, the user-wide file being what makes a preference stick across projects. The bundled `default.toml` restates today's values and is pinned by a test against the stylesheet's own `:root`, which makes it the audit as well as the reference sample. Tradeoff accepted: `--serif`/`--sans`/`--mono` name roles (body, UI, code) rather than classifications, so a sans-bodied theme sets `serif`. *(2026-08-04, follow-up: `--hl` was declared in `:root` and read by no rule, so it is deleted rather than left as a themeable key that paints nothing, and the `#fff` behind page images now tracks `--paper` — white there was coincidence, and every stored image is opaque RGB, so it was dead either way. The six constants that remain hardcoded — the card and rail shadows, the overlay scrim, the PDF tab accent, the `partial` verdict amber, sheet-header grey — were considered and deliberately left: each is near-neutral at any sane palette distance, and promoting them is a wider audit for churn rather than effect. Separately, `.doc h3` through `h6` had no rule at all — the markdown renderer emits every level and only two were styled, so a memo with `### ` fell to the browser's bold-Times default mid-page — and they are now a two-step scale that *brackets* the body rather than continuing down from `h2`, since the sheet sizes in `rem` while `body` sets 17px and a plain `1rem` heading lands under the text it heads. The theme's heading selector covers the whole scale for the same reason it exists: small-caps section heads above a body-face subsection read as a mistake, not a choice.)* |
+| 2026-08-04 | **Failure speaks at the claim, not in the masthead (amends the 2026-07-28 reader doctrine).** The artifact no longer prints a failure summary under the title. "Success is silent; only failure speaks" stands, and so does the principle under it — failures are data, never warn-and-drop — but *where* it speaks moves: the wavy alarm-coloured mark on the affected claim, and that claim's note with the reason, both of which a reader meets in context. The line that went was a bare count, and a count is the one thing about a failed citation a reader cannot act on: whether `1 of 16 citations could not be traced` matters depends entirely on which claim it was, which the headline does not say and the mark and the note do. It was also aimed at the wrong reader — the writer verifying the work learns about failures from `bind`, which exits 2 and lists them, while the recipient got a number out of context before the first sentence. Nothing loses its last surface: an unmatched claim with no citations ranks `unresolved` and is marked in the body like any other failure, and a claim that is not in the document at all was already the Notes' job under artifact rule 4. This is a spec change — `spec/artifact.md` rule 6 is rewritten, and the summary is now explicitly *not* required of a conforming producer rather than merely unmentioned, so another implementation reads the same intent. |
+| 2026-08-05 | **A web page's identity is the sha256 of the snapshot fetched at ingest time; the URL is provenance, not identity.** `ingest` accepts an http(s) URL alongside files (graduating the "HTML pages" question from Later). The fetched bytes are hashed and snapshotted exactly as a file's are, so everything downstream — anchors, the ledger, `bind`, generations — is unchanged, and a page that changed since the last fetch is a *new generation of the same document*, which is the machinery drift already describes. Continuity across a re-fetch follows the URL rather than the path, because the path is a temporary staging file; `documents.sha256` is UNIQUE, so bytes still win over origin when the same content arrives twice under two URLs. The URL and `fetched_at` live in a new `document_meta` table — a JSON sibling of `page_meta`, chosen over columns on `documents` so an existing registry needs no migration and so the next provenance question (`.eml` headers) needs no second one; `fetched_at` moves on a re-fetch that changed nothing, since "when was this last confirmed to say this" is the question a reader of an old citation actually has. Fetching is stdlib `urllib` and lives in `fetch.py`, *outside* `extract/`: an extractor stays a pure function of a file's bytes, which is what keeps `deterministic` honest and lets a saved `.html` file and a fetched page extract identically. The CLI owns the network the way it already owns page-snapshot capture. The new `html` extractor is a parse, not a readability heuristic — no boilerplate stripping, no main-content guess, because a heuristic that changes its mind moves anchors, which is the failure mode this system exists to prevent; navigation and footers are part of the page. Its representation follows `docx`: tables as markdown pipe tables, lists as `- `/`1. ` lines kept in one block, `<pre>` verbatim. Decoding is BOM, then the document's own `<meta charset>`, then UTF-8 with replacement — the server's `Content-Type` charset is deliberately *not* consulted, so the bytes alone determine the text. Known limitations, accepted and documented rather than worked around: JavaScript-rendered pages yield whatever the server sends, pages behind a login are out of reach, and a non-UTF-8 page that declares its encoding only in the HTTP header will render as mojibake in the snapshot — visibly, rather than silently. |
+| 2026-08-06 | **A fetched source's origin travels into the artifact as a live link, dated.** The capture half of the row above stored `url` and `fetched_at` and stopped at the registry, so an artifact citing a web page named `q4-2025.html` — a staging filename that never existed on anyone's disk — and a reader holding the file had the frozen receipt with no way back to the page. `bind`'s evidence `documents` map now carries `url` and `fetched_at` through to the record, and both renderers show them: the receipt card, the script-free note, the source list and the rail all print the URL as a real `<a href>` with the fetch date beside it, and the markdown projection carries it as an autolink. This is an artifact-format change, so `spec/artifact.md` and the `$legend` name the two keys together, both OPTIONAL. The keys are emitted *only* where a document has a URL, which is what keeps an artifact built from files byte-identical to one built before this existed — the conditional is the compatibility guarantee, and it is a test rather than an intention. Linking does not weaken the self-containment rule: the CSP (`default-src 'none'`) forbids *fetching*, and an anchor fetches nothing until a reader chooses to follow it, so the file still renders identically offline. The href is allowlisted to `http`/`https` rather than merely screened for `javascript:`, since artifact rule 3 is a conformance requirement and an allowlist cannot be outflanked by a scheme nobody thought of; a URL under any other scheme is printed as plain text rather than dropped, because failures are data and provenance the reader must paste by hand still beats provenance withheld. In the source list the URL *replaces* the filename rather than joining it — showing both would give a reader two names for one thing and let the fictional one look authoritative. The date is the day, not the timestamp: "as of" is what makes a frozen quote from a live page defensible, and no reader needs the seconds. |
+| 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. |
 
 ## Open
 

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: backdraft
-Version: 0.5.0
+Version: 0.7.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
@@ -54,8 +54,11 @@ cd demo
 
 **Ingest** the sources. Every anchor is minted here, chunks for PDF pages,
 cells for spreadsheet sheets. Formats: PDF, XLSX/XLSM, XLS, CSV/TSV, DOCX,
-PPTX, images (png, jpeg, tiff, through the vision model), plain text and
-Markdown.
+PPTX, HTML, images (png, jpeg, tiff, through the vision model), plain text and
+Markdown. A source can also be an `http(s)` URL — the page is fetched once and
+snapshotted like any other source, and the URL travels with it. A source that
+cannot be read does not end the run: the rest of the list is ingested anyway,
+and the command exits 1 naming each source that failed and why.
 
 ```console
 $ backdraft init
@@ -65,7 +68,7 @@ documents: 0
 
 $ 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 pages
+underwriting-model  underwriting-model.xlsx  xlsx  2 sheets
 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.
 ```
 
@@ -116,6 +119,25 @@ $ backdraft cell underwriting-model "assumptions!B10"
 [bd:underwriting-model:assumptions!B10:964a]  24850000
 ```
 
+And a token you were handed — out of an artifact, a draft, someone else's
+message — runs backwards to what it actually says:
+
+```console
+$ backdraft show bd:t12-summary:p1.c1:c2e8
+[bd:t12-summary:p1.c1:c2e8]  resolved  t12-summary p1.c1
+Bridgeview Commons — Trailing Twelve Month Summary
+
+Property: Bridgeview Commons, 4400 Halsted Avenue, Columbus, OH 43214. 128 units across four three-story
+garden buildings on 6.2 acres, built in 1998 and substantially renovated between 2019 and 2021. …
+
+[Read the page: backdraft read t12-summary p1]
+```
+
+`show` is the gate too, so what it shows is minted and citable. A token whose
+source has changed since prints both snippets, the one that was cited and the
+one standing there now; a token that names nothing exits 1 and says whether the
+slug or the locator is the wrong half.
+
 **Cite** by writing the token as the href of a markdown link on the claim span.
 Multiple citations are `;`-separated in one href.
 
@@ -133,7 +155,7 @@ bound 15 claim(s), 16 citation(s) [frontwalk]
   unresolved: 1
   overlap: pass 11, skip 4
   value-trace: pass 15
-  ! unresolved: bd:t12-summary:p4.c1:1a2b
+  ! unresolved: bd:t12-summary:p4.c1:1a2b — replacement reserve of $250 per unit per year @2900
 wrote .backdraft/records/memo.backdraft.json
 
 $ echo $?
@@ -155,6 +177,33 @@ 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.
 
+**Theming.** The artifact ships with a default look and two alternates,
+`press` and `slate`:
+
+```console
+$ backdraft render memo.md --theme slate
+```
+
+A theme is a small TOML file naming colors, font stacks and heading treatment.
+Drop one at `~/.config/backdraft/theme.toml` and every artifact you render, in
+any project, honors it without a flag; `.backdraft/theme.toml` overrides that
+for one project, and `--theme` overrides both. Themes are display only — they
+never touch a token, a receipt or the record.
+
+```console
+$ backdraft theme list
+default
+press
+slate
+
+in effect here: the built-in look
+[Start your own: backdraft theme show default > /Users/you/.config/backdraft/theme.toml]
+```
+
+`theme show` prints a validated file, so redirecting it writes a fully
+commented starting point with every key and what it paints — and pointing it
+at a file of your own checks that file without rendering anything.
+
 The full version of this, with every command and every output:
 [`demo/walkthrough.md`](demo/walkthrough.md). The artifact it produces is checked
 in at [`demo/memo.backdraft.html`](demo/memo.backdraft.html).
@@ -183,6 +232,38 @@ Failures are data throughout: `unresolved`, `not_shown`, `drifted`, `malformed`
 and `unmatched` are first-class records in the report and visible sections in the
 artifact. Nothing is ever warned about and dropped.
 
+## Web sources
+
+`backdraft ingest https://example.com/q4-results` fetches the page once and
+snapshots it exactly as a file: the bytes at fetch time are the document's
+identity, and the URL and fetch timestamp ride along as provenance. So a page
+that has changed since you cited it comes back as a new generation of the same
+document and the old citations report `drifted` — the same machinery as an
+edited PDF, which is the point of hashing the snapshot rather than trusting the
+address.
+
+```console
+$ backdraft ingest https://example.com/reports/q4-2025
+q4-2025  q4-2025.html  html  1 page
+
+$ backdraft ls
+q4-2025	q4-2025.html	html	1 page	https://example.com/reports/q4-2025
+```
+
+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.
+
+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
+are out of reach, and the extractor is a parse rather than a readability guess
+— navigation and footers are part of the page, because a heuristic that changes
+its mind between two versions of a site would move anchors. Responses are
+capped at 32 MiB.
+
 ## What lives where
 
 A working directory stays clean: the authored document and its artifact are
@@ -209,7 +290,11 @@ explicit, backdraft-scoped consent: `BACKDRAFT_VLM_API_KEY` (env or
 `OPENAI_API_KEY`/`OPENROUTER_API_KEY` are deliberately never read; a generic
 key in the environment is not consent to send documents to its provider. The
 default provider is OpenRouter running Gemini 3.1 Flash Lite; direct OpenAI is
-base_url + model, set explicitly. Without a scoped key, `auto` falls back to
+base_url + model, set explicitly (`--config base_url=...` and `--config
+model=...`, one key per flag). Every `--config` key is declared by the extractor
+that reads it and checked against the one `ingest` chose, so a misspelled key
+fails and names the keys that apply rather than being silently ignored.
+Without a scoped key, `auto` falls back to
 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.

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

@@ -29,8 +29,11 @@ cd demo
 
 **Ingest** the sources. Every anchor is minted here, chunks for PDF pages,
 cells for spreadsheet sheets. Formats: PDF, XLSX/XLSM, XLS, CSV/TSV, DOCX,
-PPTX, images (png, jpeg, tiff, through the vision model), plain text and
-Markdown.
+PPTX, HTML, images (png, jpeg, tiff, through the vision model), plain text and
+Markdown. A source can also be an `http(s)` URL — the page is fetched once and
+snapshotted like any other source, and the URL travels with it. A source that
+cannot be read does not end the run: the rest of the list is ingested anyway,
+and the command exits 1 naming each source that failed and why.
 
 ```console
 $ backdraft init
@@ -40,7 +43,7 @@ documents: 0
 
 $ 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 pages
+underwriting-model  underwriting-model.xlsx  xlsx  2 sheets
 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.
 ```
 
@@ -91,6 +94,25 @@ $ backdraft cell underwriting-model "assumptions!B10"
 [bd:underwriting-model:assumptions!B10:964a]  24850000
 ```
 
+And a token you were handed — out of an artifact, a draft, someone else's
+message — runs backwards to what it actually says:
+
+```console
+$ backdraft show bd:t12-summary:p1.c1:c2e8
+[bd:t12-summary:p1.c1:c2e8]  resolved  t12-summary p1.c1
+Bridgeview Commons — Trailing Twelve Month Summary
+
+Property: Bridgeview Commons, 4400 Halsted Avenue, Columbus, OH 43214. 128 units across four three-story
+garden buildings on 6.2 acres, built in 1998 and substantially renovated between 2019 and 2021. …
+
+[Read the page: backdraft read t12-summary p1]
+```
+
+`show` is the gate too, so what it shows is minted and citable. A token whose
+source has changed since prints both snippets, the one that was cited and the
+one standing there now; a token that names nothing exits 1 and says whether the
+slug or the locator is the wrong half.
+
 **Cite** by writing the token as the href of a markdown link on the claim span.
 Multiple citations are `;`-separated in one href.
 
@@ -108,7 +130,7 @@ bound 15 claim(s), 16 citation(s) [frontwalk]
   unresolved: 1
   overlap: pass 11, skip 4
   value-trace: pass 15
-  ! unresolved: bd:t12-summary:p4.c1:1a2b
+  ! unresolved: bd:t12-summary:p4.c1:1a2b — replacement reserve of $250 per unit per year @2900
 wrote .backdraft/records/memo.backdraft.json
 
 $ echo $?
@@ -130,6 +152,33 @@ 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.
 
+**Theming.** The artifact ships with a default look and two alternates,
+`press` and `slate`:
+
+```console
+$ backdraft render memo.md --theme slate
+```
+
+A theme is a small TOML file naming colors, font stacks and heading treatment.
+Drop one at `~/.config/backdraft/theme.toml` and every artifact you render, in
+any project, honors it without a flag; `.backdraft/theme.toml` overrides that
+for one project, and `--theme` overrides both. Themes are display only — they
+never touch a token, a receipt or the record.
+
+```console
+$ backdraft theme list
+default
+press
+slate
+
+in effect here: the built-in look
+[Start your own: backdraft theme show default > /Users/you/.config/backdraft/theme.toml]
+```
+
+`theme show` prints a validated file, so redirecting it writes a fully
+commented starting point with every key and what it paints — and pointing it
+at a file of your own checks that file without rendering anything.
+
 The full version of this, with every command and every output:
 [`demo/walkthrough.md`](demo/walkthrough.md). The artifact it produces is checked
 in at [`demo/memo.backdraft.html`](demo/memo.backdraft.html).
@@ -158,6 +207,38 @@ Failures are data throughout: `unresolved`, `not_shown`, `drifted`, `malformed`
 and `unmatched` are first-class records in the report and visible sections in the
 artifact. Nothing is ever warned about and dropped.
 
+## Web sources
+
+`backdraft ingest https://example.com/q4-results` fetches the page once and
+snapshots it exactly as a file: the bytes at fetch time are the document's
+identity, and the URL and fetch timestamp ride along as provenance. So a page
+that has changed since you cited it comes back as a new generation of the same
+document and the old citations report `drifted` — the same machinery as an
+edited PDF, which is the point of hashing the snapshot rather than trusting the
+address.
+
+```console
+$ backdraft ingest https://example.com/reports/q4-2025
+q4-2025  q4-2025.html  html  1 page
+
+$ backdraft ls
+q4-2025	q4-2025.html	html	1 page	https://example.com/reports/q4-2025
+```
+
+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.
+
+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
+are out of reach, and the extractor is a parse rather than a readability guess
+— navigation and footers are part of the page, because a heuristic that changes
+its mind between two versions of a site would move anchors. Responses are
+capped at 32 MiB.
+
 ## What lives where
 
 A working directory stays clean: the authored document and its artifact are
@@ -184,7 +265,11 @@ explicit, backdraft-scoped consent: `BACKDRAFT_VLM_API_KEY` (env or
 `OPENAI_API_KEY`/`OPENROUTER_API_KEY` are deliberately never read; a generic
 key in the environment is not consent to send documents to its provider. The
 default provider is OpenRouter running Gemini 3.1 Flash Lite; direct OpenAI is
-base_url + model, set explicitly. Without a scoped key, `auto` falls back to
+base_url + model, set explicitly (`--config base_url=...` and `--config
+model=...`, one key per flag). Every `--config` key is declared by the extractor
+that reads it and checked against the one `ingest` chose, so a misspelled key
+fails and names the keys that apply rather than being silently ignored.
+Without a scoped key, `auto` falls back to
 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.