backdraft 0.4.0__tar.gz → 0.5.0__tar.gz

backdraft-0.5.0/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "backdraft",
+  "owner": {
+    "name": "Spencer Braun",
+    "url": "https://github.com/spencerbraun"
+  },
+  "description": "Self-hosting marketplace for the backdraft plugin: agent skills for writing documents whose factual claims carry verifiable citations.",
+  "plugins": [
+    {
+      "name": "backdraft",
+      "source": "./",
+      "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).",
+      "category": "productivity"
+    }
+  ]
+}

backdraft-0.5.0/.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "backdraft",
+  "displayName": "Backdraft",
+  "version": "0.5.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",
+    "url": "https://github.com/spencerbraun"
+  },
+  "homepage": "https://backdraft.dev",
+  "repository": "https://github.com/spencerbraun/backdraft",
+  "license": "MIT",
+  "keywords": ["citations", "provenance", "sources", "evidence", "documents", "pdf", "xlsx", "writing"]
+}

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

@@ -134,6 +134,7 @@ Self-contained HTML (plus the machine-readable sidecar): **quotes + receipts + e
 | 2026-07-29 | **Office formats extract natively, never through conversion.** DOCX and PPTX are read straight from their XML (python-docx / python-pptx, core deps). Converting to PDF was rejected on principle: conversion is rendering, so it needs a layout engine (LibreOffice, MS Office, or a cloud API — a 700MB dependency, a platform lock, or documents leaving the machine), and converter-dependent pagination would break content-addressed locator stability. DOCX pages are heading sections: the split level is the smallest outline level present among {Heading 1, Heading 2}; preamble is section 1; no headings → one section — locators stay `pN.cM`, no grammar change. PPTX pages are slides (slide N is slide N in every renderer). The text floor deliberately misses slide visuals; the ingest note says so and names the path that captures them — the user exporting the deck to PDF with the real renderer they already have, ingested through the vision extractor — so a calling agent can relay it. |
 | 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. |
 
 ## Open
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backdraft
-Version: 0.4.0
+Version: 0.5.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
@@ -61,6 +61,7 @@ Markdown.
 $ backdraft init
 registry: /…/demo/.backdraft
 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
@@ -130,7 +131,7 @@ $ backdraft bind memo.md --session s-bridgeview --check value-trace,overlap
 bound 15 claim(s), 16 citation(s) [frontwalk]
   resolved: 15
   unresolved: 1
-  overlap: partial 4, pass 11
+  overlap: pass 11, skip 4
   value-trace: pass 15
   ! unresolved: bd:t12-summary:p4.c1:1a2b
 wrote .backdraft/records/memo.backdraft.json
@@ -209,8 +210,9 @@ explicit, backdraft-scoped consent: `BACKDRAFT_VLM_API_KEY` (env or
 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
-the keyless text layer and says so. PDF page rendering needs poppler,
-installed separately.
+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:
 
@@ -232,13 +234,7 @@ uv run pytest
 
 ## Skills
 
-Three agent skills ship inside the package, and the CLI installs them:
-
-```bash
-backdraft skill install          # the writing skill, into ~/.claude/skills/
-backdraft skill install --all    # plus backfill and artifact-reading
-backdraft skill install --project  # into this repo's .claude/skills/
-```
+Three agent skills ship inside the package and in this repo:
 
 | Skill | For |
 |---|---|
@@ -247,7 +243,51 @@ backdraft skill install --project  # into this repo's .claude/skills/
 | [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | 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.
+the skills is required to use backdraft by hand. How the skills reach your agent
+depends on the harness:
+
+**Claude Code.** The repo is its own plugin marketplace, so the plugin route
+tracks releases:
+
+```text
+/plugin marketplace add spencerbraun/backdraft
+/plugin install backdraft@backdraft
+```
+
+Or have the CLI copy the skills into your skills directory:
+
+```bash
+backdraft skill install          # the writing skill, into ~/.claude/skills/
+backdraft skill install --all    # plus backfill and artifact-reading
+backdraft skill install --project  # into this repo's .claude/skills/
+```
+
+**Claude Cowork.** Once the plugin is listed in Anthropic's community
+directory, it installs from Cowork's built-in skills directory. Until then,
+zip a skill folder from `skills/` and upload it under Customize > Skills.
+Inside a Cowork session the CLI itself runs per-command as
+`uvx backdraft ...`, since installs do not persist between sessions.
+
+**Codex, Cursor, Copilot.** Agents in this family read skills from
+`~/.agents/skills`:
+
+```bash
+backdraft skill install --agent codex   # into ~/.agents/skills/
+```
+
+or commit the skill folders to your repo under `.agents/skills/` so every
+checkout carries them.
+
+**Standing context, any harness.** Paste this into your repo's AGENTS.md:
+
+```markdown
+## backdraft (cited writing)
+When a document must cite its sources, write it through the backdraft CLI:
+it shows source text with a citation token over every span, and only shown
+spans are citable. In a sandboxed session run every command as
+`uvx backdraft ...` (no install, no PATH edits). Start from
+`uvx backdraft --help`; ground truth is https://backdraft.dev/llms.txt.
+```
 
 ## Documentation
 

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

@@ -36,6 +36,7 @@ Markdown.
 $ backdraft init
 registry: /…/demo/.backdraft
 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
@@ -105,7 +106,7 @@ $ backdraft bind memo.md --session s-bridgeview --check value-trace,overlap
 bound 15 claim(s), 16 citation(s) [frontwalk]
   resolved: 15
   unresolved: 1
-  overlap: partial 4, pass 11
+  overlap: pass 11, skip 4
   value-trace: pass 15
   ! unresolved: bd:t12-summary:p4.c1:1a2b
 wrote .backdraft/records/memo.backdraft.json
@@ -184,8 +185,9 @@ explicit, backdraft-scoped consent: `BACKDRAFT_VLM_API_KEY` (env or
 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
-the keyless text layer and says so. PDF page rendering needs poppler,
-installed separately.
+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:
 
@@ -207,13 +209,7 @@ uv run pytest
 
 ## Skills
 
-Three agent skills ship inside the package, and the CLI installs them:
-
-```bash
-backdraft skill install          # the writing skill, into ~/.claude/skills/
-backdraft skill install --all    # plus backfill and artifact-reading
-backdraft skill install --project  # into this repo's .claude/skills/
-```
+Three agent skills ship inside the package and in this repo:
 
 | Skill | For |
 |---|---|
@@ -222,7 +218,51 @@ backdraft skill install --project  # into this repo's .claude/skills/
 | [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | 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.
+the skills is required to use backdraft by hand. How the skills reach your agent
+depends on the harness:
+
+**Claude Code.** The repo is its own plugin marketplace, so the plugin route
+tracks releases:
+
+```text
+/plugin marketplace add spencerbraun/backdraft
+/plugin install backdraft@backdraft
+```
+
+Or have the CLI copy the skills into your skills directory:
+
+```bash
+backdraft skill install          # the writing skill, into ~/.claude/skills/
+backdraft skill install --all    # plus backfill and artifact-reading
+backdraft skill install --project  # into this repo's .claude/skills/
+```
+
+**Claude Cowork.** Once the plugin is listed in Anthropic's community
+directory, it installs from Cowork's built-in skills directory. Until then,
+zip a skill folder from `skills/` and upload it under Customize > Skills.
+Inside a Cowork session the CLI itself runs per-command as
+`uvx backdraft ...`, since installs do not persist between sessions.
+
+**Codex, Cursor, Copilot.** Agents in this family read skills from
+`~/.agents/skills`:
+
+```bash
+backdraft skill install --agent codex   # into ~/.agents/skills/
+```
+
+or commit the skill folders to your repo under `.agents/skills/` so every
+checkout carries them.
+
+**Standing context, any harness.** Paste this into your repo's AGENTS.md:
+
+```markdown
+## backdraft (cited writing)
+When a document must cite its sources, write it through the backdraft CLI:
+it shows source text with a citation token over every span, and only shown
+spans are citable. In a sandboxed session run every command as
+`uvx backdraft ...` (no install, no PATH edits). Start from
+`uvx backdraft --help`; ground truth is https://backdraft.dev/llms.txt.
+```
 
 ## Documentation
 

backdraft-0.5.0/ROADMAP.md

@@ -0,0 +1,177 @@
+# Roadmap
+
+Sequenced intent. DESIGN.md records what was *decided*; this file records what
+is *queued*, so tabling something is an act of writing it down here rather than
+losing it. Items graduate by getting built and deleted.
+
+## How the queue runs
+
+The Now section is an ordered queue written for an implementing agent with no
+session context: each item carries its intent, its shape, and its acceptance
+test. The working agreement is one item at a time, top first, shipped complete
+— code, tests, docs, and a DESIGN.md decision row where the item calls for one
+— then deleted from this file in the same commit. Releases cut Friday, so an
+item that lands mid-week waits on PyPI until the release; nothing ships
+half-done to make a release. An item that turns out bigger than its sizing
+gets split here, not stretched silently.
+
+The cadence is daily and the runner is an agent: one item each morning Monday
+through Thursday, landing as a direct commit to `main` — this repo does not
+use pull requests, so a week of commits is the only review surface there is.
+
+Friday builds nothing new. It reads that week's diff instead — duplication,
+drift from the repo's own idioms, branches that landed untested, help text and
+error messages that confuse, commands the docs describe wrongly — and lands
+the fixes. Then the release, and only if something landed since the last tag:
+the version moves in both `pyproject.toml` and `.claude-plugin/plugin.json`,
+and publishing the GitHub release is what ships to PyPI. Then this section is
+refilled with five items for the week ahead, drawn against the core — the four
+verbs, the registry, the grammar, the artifact — and against where an agent
+using backdraft actually stumbles. What the maintenance pass just found is the
+best evidence available for what those five should be.
+
+## Now
+
+### 1. Source card: contents resize with the card
+
+**Intent.** The artifact's source card is user-resizable (`resize:vertical`,
+`max-height:82vh` — assets.py) but its inner blocks hold their own fixed caps
+— the quote scroller is pinned at `15rem`, and the sheet grid and page image
+size themselves — so dragging the card taller yields whitespace, not more
+evidence. Resizing should mean seeing more.
+
+**Shape.** Make the card a flex column whose scrollable evidence region
+(quote / drift / sheet / page image) flexes to fill the card's height, with the
+header, source selector, and tabs as fixed rows. Audit every fixed
+`max-height` inside `.card` and convert to flex-driven sizing. The mobile
+card keeps `resize:none` and its current behavior. Python is the formatting
+authority and this is CSS/JS only, so no fmt-parity surface is touched; the
+minified asset budget should move only trivially.
+
+**Acceptance.** Dragging the card taller visibly grows the quote, sheet, and
+page-image viewports; dragging it short reintroduces inner scrolling rather
+than clipping the header or tabs. Verified against a real artifact (the demo)
+across the three evidence kinds, plus the mobile breakpoint. Node-side DOM
+test if cheap; otherwise the existing render tests plus a manual screenshot
+pass recorded in the PR.
+
+**Size.** One day.
+
+### 2. Theming: sticky user preferences, drop-in themes
+
+**Intent.** The artifact's look is currently one hardcoded design. Let a user
+set a theme once and have every artifact they render honor it, and let a theme
+be a small file someone can drop in — fonts, colors, heading treatment at
+minimum.
+
+**Shape.** Two parts, in order:
+
+- *Decision row first.* A theme is a named set of overrides for the CSS custom
+  properties the stylesheet already exposes (`--paper`, `--ink`, `--sel`, the
+  font stacks) plus a bounded set of typographic choices (heading family/case,
+  maybe rule weight). A theme may not change layout, structure, or any
+  verification affordance — display only, tokens and records untouched.
+  Settle the file format (a flat TOML of variable names, or a raw CSS-variables
+  block) and write the DESIGN.md row before code.
+- *Then the loader.* Precedence: `render --theme <file-or-name>` >
+  project `.backdraft/theme.*` > user-wide config (XDG,
+  `~/.config/backdraft/theme.*`) > built-in default. The user-wide file is
+  what makes preferences stick across projects. Bundled themes (the default
+  plus one or two alternates) prove the format; the resolved theme is baked
+  into the artifact at render time so the file stays self-contained.
+
+**Acceptance.** Rendering with no config is byte-stable against today's
+output. A theme file in the XDG location changes fonts/colors/headers on every
+subsequent render in any project without flags; `--theme` overrides it; a
+malformed theme fails with a clear message, never a half-styled artifact.
+Docs page gains a short theming section with a sample theme file.
+
+**Size.** Two days — decision row and variable audit, then loader, bundled
+themes, docs.
+
+### 3. URL sources: capture and link back
+
+**Intent.** Diligence folders contain links, not just files. `backdraft ingest
+<url>` should fetch a page, snapshot it into the registry like any other
+source, and — the other half — artifacts should show a source's origin URL and
+link back to it, so a claim cited to a web page carries both the frozen
+receipt and the live pointer.
+
+**Shape.** This is the graduation of the "HTML pages" question from Later, and
+it needs its decision row: *the source's identity is the sha256 of the fetched
+snapshot at ingest time*, same as a file — the URL is provenance metadata, not
+identity. A page that changes later is a new generation; the existing drift
+machinery already describes that. Capture: fetch (stdlib or the lightest
+dependency that handles redirects and encodings), extract readable text into
+the normal page/chunk structure, store the origin URL and fetch timestamp in
+source meta. Render: sources carrying an origin URL show it in the resting
+source list and the card, as a real link. Out of scope for this item:
+JavaScript-rendered pages (note the limitation), authentication, and `.eml`
+(stays in Later).
+
+**Acceptance.** `ingest https://…` on a static page mints citable tokens;
+`read`/`search`/`cell`-equivalents behave as for text sources; bind embeds the
+receipt; the artifact's source entry links to the URL and the record JSON
+carries url + fetched-at. Re-ingesting a changed page produces a new
+generation and `drifted` behaves correctly. A network-free test suite (fixture
+HTML served locally or loaded from disk); DESIGN.md row written; docs updated.
+
+**Size.** Two to three days — decision row and capture first, render linkage
+second.
+
+## Parked
+
+Deliberately not queued, each with the reason, so picking one up starts from
+the objection rather than rediscovering it.
+
+- **Exhibits view** — the evidence-first inversion. Risk: it grows the
+  artifact and pollutes a design whose strength is restraint. Needs a
+  deliberate design pass and a real audience before any code; not a
+  weekend-feature shape.
+- **Excel region maps and range reads** — the research notes exist, but no
+  confidence the deterministic detection cascade lands well on the first
+  try. Revisit when large-sheet navigation hurts in a real corpus, with
+  test workbooks in hand.
+- **`bd:calc` derivations** — reserved in the grammar and parsed as
+  malformed-on-purpose, which is enough for now. Full support complicates
+  binding and verification for one field-trial case.
+- **Merged-cell and frozen-pane rendering** — ingest captures `merged` and
+  `frozen` in sheet meta and keeps them (cheap, and capture is the part you
+  cannot backfill). Frozen-pane rendering is cut; merged-cell rendering
+  waits for a real sheet that renders wrong without it.
+
+## Later
+
+- **Living documents** — re-ingest, re-bind, and a drift-first report: "these
+  claims cite figures that changed; cited-then vs. now." The primitives
+  (generations, `drifted`, the word-diff) all exist; the missing piece is a
+  diff-shaped report and a demo.
+- **Substrates beyond the CLI** — SDK middleware for pipelines (the exit-code
+  and `--to json` contracts are already shaped for it), and a client-side
+  drag-drop viewer page (no upload — the file never leaves the reader's
+  machine).
+- **Email (.eml)** — arrives in diligence folders alongside everything else;
+  identity questions (headers vs. body, attachments as child sources) deserve
+  a decision row before code. The web-page half of this item graduated to the
+  Now queue as URL sources.
+- **Anthropic-API provider for the VLM extractor** — Cowork's sandbox
+  egress allowlist includes api.anthropic.com but not the OpenAI-compatible
+  providers, so an Anthropic-native option would let sandboxed sessions
+  ingest at full fidelity. Needs a client abstraction the vlm module
+  currently doesn't have; the documented workaround (ingest locally, the
+  registry travels with the folder) covers it meanwhile.
+- **Distribution** — published on PyPI; the repo ships
+  `.claude-plugin/plugin.json` and `marketplace.json`, so it installs as a
+  Claude Code plugin and self-hosts its marketplace, and the AGENTS.md
+  snippet is published in the README and site docs. The community-directory
+  submission went in 2026-07-29 and is awaiting review — approval is what
+  surfaces the skills in Cowork's directory.
+
+## Someday
+
+- **Hosted team features** — upload, access control, shared registries.
+  Deliberately parked: the product's trust story is the self-contained file,
+  and a hosted viewer inverts it. Revisit only as a distinct teams product.
+- **Entail at scale** — the model-judge verifier is wired (`[entail]` extra)
+  but has never been field-calibrated; needs a corpus and a rubric before it
+  is recommended anywhere.

{backdraft-0.4.0 → backdraft-0.5.0}/SPEC.md

@@ -352,8 +352,10 @@ class Registry:
     # page snapshots (v0.2: evidence for the artifact)
     def page_image(self, slug: str, number: int) -> PageImage | None: ...
         # The stored visual snapshot of a current-extraction page: what the VLM
-        # extractor was shown (WebP q85), or a `snapshot-pages` backfill. None
-        # for text-only extractions.
+        # extractor was shown (WebP q85), the local poppler render the CLI
+        # captures after a text-layer PDF ingest, or a `snapshot-pages`
+        # backfill. None for non-PDFs, and for PDFs ingested where poppler was
+        # unavailable.
     def save_page_image(self, extraction_id: int, number: int, *, data: bytes,
                         format: str, width: int, height: int) -> None: ...
     def current_extraction_id(self, slug: str) -> int | None: ...    # for backfill tools
@@ -370,4 +372,4 @@ class Registry:
 
 ## Addendum B — CLI assembly
 
-Top-level `cli.py` (W1) owns: typer app, registry discovery (nearest `.backdraft/` walking up from cwd; `BACKDRAFT_HOME` override), session resolution (`--session` flag > `BACKDRAFT_SESSION` env > default session), and the `init` / `ingest` / `ls` / `export` commands. It mounts sub-apps `gate/cli.py` (W2: `read`, `search`, `session`), `bind/cli.py` (W3: `bind`), `render/cli.py` (W4: `render`) — each exposes `app = typer.Typer()`; the top level mounts each inside a try/except ImportError so partial merges still run. The `backdraft` console script is declared by W1.
+Top-level `cli.py` (W1) owns: typer app, registry discovery (nearest `.backdraft/` walking up from cwd; `BACKDRAFT_HOME` override), session resolution (`--session` flag > `BACKDRAFT_SESSION` env > default session), and the `init` / `ingest` / `ls` / `export` / `snapshot-pages` commands. After each ingest, `cli.py` captures page snapshots for any PDF whose extraction carries none — the text-layer path, since `vlm` stores its own — via `extract/snapshots.py` (poppler through pdf2image, `snapshot-pages`' internals). It sits outside the extractor so `pdf-text` stays deterministic regardless of whether poppler is installed, and it is best-effort: a `SnapshotError` leaves ingest at exit 0 with a one-line note naming `snapshot-pages` as the backfill. It mounts sub-apps `gate/cli.py` (W2: `read`, `search`, `session`), `bind/cli.py` (W3: `bind`), `render/cli.py` (W4: `render`) — each exposes `app = typer.Typer()`; the top level mounts each inside a try/except ImportError so partial merges still run. The `backdraft` console script is declared by W1.

{backdraft-0.4.0 → backdraft-0.5.0}/demo/walkthrough.md

@@ -43,17 +43,15 @@ underwriting-model  underwriting-model.xlsx  xlsx  2 pages
 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.
 ```
 
-The keyless text layer is fine for these clean generated sources. For the
-artifact to show the cited pages themselves, store their snapshots — local
-rendering, no model calls:
-
-```bash
-backdraft snapshot-pages t12-summary
-```
+The keyless text layer is fine for these clean generated sources.
 
 Ingest picked an extractor per file (`pdf-text` for the PDF, `xlsx` for the
 workbook), snapshotted the text, and minted every anchor: chunks for the PDF
-pages, cells for the sheets. Nothing is citable that was not ingested.
+pages, cells for the sheets. Nothing is citable that was not ingested. It also
+rendered each PDF page to an image and stored it, so the artifact at the end
+can show the cited pages themselves — local rendering through poppler, no model
+calls. On a machine without poppler ingest prints a note instead and
+`backdraft snapshot-pages t12-summary` backfills them whenever you like.
 
 The note is real: this walkthrough deliberately uses the keyless text-layer
 path so it reproduces anywhere, and our source PDF is born-digital, where that
@@ -362,12 +360,15 @@ claim occurs at the cited location, across unit, scale and format differences. I
 is what makes `[a purchase price of $24.85 million](…assumptions!B10:964a)` pass
 against a cell whose snippet is the eight characters `24850000`.
 
-**`overlap: partial 4, pass 11`.** Word-overlap between claim and snippet,
+**`overlap: pass 11, skip 4`.** Word-overlap between claim and snippet,
 report-only by construction — it never returns `fail`, because a faithful summary
-can share almost no vocabulary with its source. The four `partial`s are the
-claims citing Excel cells, where the snippet is a bare number and the claim is a
-sentence. That is a signal, not a fault. The quoted claim in the memo is checked
-differently: a quotation is an exact-substring assertion, and it passes.
+can share almost no vocabulary with its source. The four `skip`s are the overlap
+check declining to measure wording against single-cell sources: those claims cite
+Excel cells, and a bare number is not a sentence, so the record says it declined
+instead of emitting a low score as though it meant something. Where it does
+measure and finds little it says `partial` — a signal, not a fault. The quoted
+claim in the memo is checked differently: a quotation is an exact-substring
+assertion, and it passes.
 
 Both checks are off by default. Out of the box, bind is pure provenance.
 
@@ -379,10 +380,6 @@ directory; the memo and the artifact are the only files you see. (A readable
 markdown projection with a `## References` section is available with
 `bind --bound` when you want one.)
 
-The four `skip` verdicts are the overlap check declining to measure wording
-against single-cell sources — a number is not a sentence, and the record says
-so instead of emitting noise.
-
 Here is what one claim looks like in the sidecar:
 
 ```json
@@ -409,8 +406,8 @@ Here is what one claim looks like in the sidecar:
         },
         {
           "method": "overlap",
-          "status": "partial",
-          "detail": "0/6 claim tokens in snippet (ratio 0.00)"
+          "status": "skip",
+          "detail": "wording overlap does not apply to a single cell"
         }
       ]
     }
@@ -452,8 +449,10 @@ backdraft render memo.md --to html
 memo.backdraft.html
 ```
 
-[`memo.backdraft.html`](memo.backdraft.html) is one file, 64 KB, with no external
-request of any kind — no font, no stylesheet, no script that executes. Open it
+[`memo.backdraft.html`](memo.backdraft.html) is one file, 522 KB — most of it the
+embedded page images — with no external request of any kind: no font, no
+stylesheet, no script that executes. `bind --lean` skips the images and takes it
+to 126 KB, at the cost of the cited page being shown. Open it
 from `file://` with the network off. Hover or focus a claim to reveal its
 receipt: the verbatim snippet, the source slug and locator, the token, the full
 snippet hash, and a badge per verdict. Below the document body an **Unresolved**

{backdraft-0.4.0 → backdraft-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "backdraft"
-version = "0.4.0"
+version = "0.5.0"
 description = "Drop-in provenance for factual claims: one click from any claim to the evidence behind it."
 readme = "README.md"
 requires-python = ">=3.13"

{backdraft-0.4.0 → backdraft-0.5.0}/site/docs.html

@@ -109,7 +109,7 @@ footer{text-align:center;font-family:var(--sans);font-size:.74rem;color:var(--mu
   <a href="#writing">Writing rules</a>
   <a href="#verification">Verification</a>
   <a href="#files">Files &amp; the artifact</a>
-  <a href="#agents">Agents</a>
+  <a href="#agents">Agents &amp; harnesses</a>
   <a href="#security">Security &amp; privacy</a>
   <a href="#faq">FAQ</a>
 </aside>
@@ -131,9 +131,11 @@ repo</a>, and agents should start from <a href="llms.txt">llms.txt</a>.</p>
 <p>Python 3.13+. The vision-model extractor ships by default, the recommended
 path for real PDFs (glossy layouts, info boxes, scans) and the only path for
 scanned images; it activates only when <code>BACKDRAFT_VLM_API_KEY</code> is
-set, and PDFs need <code>poppler</code> on your PATH
-(<code>brew install poppler</code>). Without a key, PDFs fall back to the
-keyless embedded-text layer, and ingest says so.
+set. Without a key, PDFs fall back to the keyless embedded-text layer, and
+ingest says so. Either way PDFs want <code>poppler</code> on your PATH
+(<code>brew install poppler</code>) — it renders the pages, which is what puts
+the cited page into the artifact; without it ingest still works and says what
+is missing.
 Spreadsheets (xlsx, xlsm), CSV, Word (docx), PowerPoint (pptx), text and
 Markdown are keyless and built in, and sheet evidence carries the workbook's
 own styling: bold, fills, number formats, column widths. Legacy xls
@@ -209,7 +211,7 @@ skill</a> imposes the gate, and you receive the artifact.</div>
 <tr><th>Command</th><th>Does</th></tr>
 <tr><td><code>init</code></td><td>Create <code>.backdraft/</code> (registry, credentials template) in the current directory.</td></tr>
 <tr><td><code>ingest &lt;files&gt;</code></td><td>Snapshot sources into the registry, minting every anchor. Formats: PDF, XLSX/XLSM, XLS, CSV/TSV, DOCX, PPTX, images (png, jpeg, tiff), text and Markdown. <code>--extractor auto|vlm|image|pdf-text|xlsx|xls|csv|docx|pptx|text</code>, <code>--slug</code>, <code>--config k=v</code>.</td></tr>
-<tr><td><code>snapshot-pages &lt;slug&gt;</code></td><td>Backfill page images for an already-ingested PDF, locally, no model calls (needs <code>poppler</code> for rendering).</td></tr>
+<tr><td><code>snapshot-pages &lt;slug&gt;</code></td><td>Backfill page images for an already-ingested PDF, locally, no model calls (needs <code>poppler</code> for rendering). Ingest stores them already — this is for a registry built before it did, or on a machine that had no poppler then.</td></tr>
 <tr><td><code>ls</code></td><td>List ingested documents.</td></tr>
 <tr><td><code>read [slug] [selector]</code></td><td>The gate: document list, table of contents, or a token-marked page/range/sheet read. Mints what it shows.</td></tr>
 <tr><td><code>search &lt;query&gt;</code></td><td>Full-text search over every anchor; hits are citable. <code>--in slug</code>, <code>--limit</code>.</td></tr>
@@ -277,14 +279,48 @@ of a gigabyte corpus is a ~2&nbsp;MB file. Recipients need the one
 </section>
 
 <section id="agents">
-<h2>Agents</h2>
-<pre>backdraft skill install          <span class="dim"># the writing skill, into ~/.claude/skills/</span>
-backdraft skill install --all    <span class="dim"># plus backfill and artifact-reading</span>
-backdraft skill install --project<span class="dim">  # into this repo's .claude/skills/</span></pre>
+<h2>Agents and harnesses</h2>
 <p>The skill's core instruction is a substitution: for source documents, use
 <code>backdraft read</code>/<code>search</code>, never raw file reads. The
 token-efficient reference for any agent is <a href="llms.txt">llms.txt</a>
-(~800 tokens).</p>
+(~800 tokens). How the skill reaches your agent depends on the harness.</p>
+<h3>Claude Code</h3>
+<p>The repo is its own plugin marketplace, so the plugin route tracks
+releases:</p>
+<pre>/plugin marketplace add spencerbraun/backdraft
+/plugin install backdraft@backdraft</pre>
+<p>Or have the CLI copy the skills into your skills directory:</p>
+<pre>backdraft skill install          <span class="dim"># the writing skill, into ~/.claude/skills/</span>
+backdraft skill install --all    <span class="dim"># plus backfill and artifact-reading</span>
+backdraft skill install --project<span class="dim">  # into this repo's .claude/skills/</span></pre>
+<h3>Claude Cowork</h3>
+<p>Once the plugin is listed in Anthropic's community directory, it installs
+from Cowork's built-in skills directory; until then, zip a skill folder from
+the repo's <code>skills/</code> and upload it under Customize &gt; Skills.
+Inside a session, run the CLI per-command as <code>uvx backdraft ...</code>,
+since installs do not persist between sessions.</p>
+<p>Sandboxes and credentials: a sandbox usually cannot reach model providers,
+so ingest inside one falls back to the keyless text layer and says so. For
+full fidelity, ingest once on your own machine with the vision extractor.
+The registry lives in <code>.backdraft/</code> inside the project folder, so
+it travels with the folder into any session, and binding and rendering never
+need a key. Put <code>BACKDRAFT_VLM_API_KEY</code> in
+<code>.backdraft/env</code> yourself; never paste keys into a chat.</p>
+<h3>Codex, Cursor, Copilot</h3>
+<p>Agents in this family read skills from <code>~/.agents/skills</code>:</p>
+<pre>backdraft skill install --agent codex   <span class="dim"># into ~/.agents/skills/</span></pre>
+<p>Or commit the skill folders to your repo under <code>.agents/skills/</code>
+so every checkout carries them. For Codex cloud environments, add
+<code>pip install backdraft</code> to the setup script, which runs while the
+network is still on.</p>
+<h3>Standing context</h3>
+<p>For any harness that reads AGENTS.md, paste this into your repo's file:</p>
+<pre>## backdraft (cited writing)
+When a document must cite its sources, write it through the backdraft CLI:
+it shows source text with a citation token over every span, and only shown
+spans are citable. In a sandboxed session run every command as
+`uvx backdraft ...` (no install, no PATH edits). Start from
+`uvx backdraft --help`; ground truth is https://backdraft.dev/llms.txt.</pre>
 </section>
 
 <section id="security">
@@ -312,9 +348,13 @@ registry contains the full text of everything ingested.</li>
 Text-layer receipts are fine for clean digital PDFs; glossy or scanned ones
 deserve the vision model.</p>
 <h3>My artifact has no page images.</h3>
-<p>Images are stored at ingest by the VLM path. For text-layer or older
-registries, run <code>backdraft snapshot-pages &lt;slug&gt;</code> (local,
-free), then re-bind.</p>
+<p>Ingest stores them for every PDF, through both the vision and the text-layer
+path — the latter renders the pages locally, which needs <code>poppler</code>
+on the machine. If ingest printed a note that it could not capture them, install
+poppler; then, for that registry or any built before ingest did this, run
+<code>backdraft snapshot-pages &lt;slug&gt;</code> (local, free) and re-bind.
+Also check you did not bind with <code>--lean</code>, which skips them
+deliberately.</p>
 <h3>What does <code>not_shown</code> actually catch?</h3>
 <p>A real token, valid in the registry, that the writing session was never
 shown, i.e. the writer cited something it didn't read. Only a session ledger