backdraft 0.4.1__tar.gz → 0.5.0__tar.gz

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

@@ -1,7 +1,7 @@
 {
   "name": "backdraft",
   "displayName": "Backdraft",
-  "version": "0.4.1",
+  "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",

{backdraft-0.4.1 → 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.1 → backdraft-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: backdraft
-Version: 0.4.1
+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:
 

{backdraft-0.4.1 → 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:
 

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.1 → 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.1 → 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.1 → backdraft-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "backdraft"
-version = "0.4.1"
+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.1 → backdraft-0.5.0}/site/docs.html

@@ -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>
@@ -297,6 +299,13 @@ 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>
@@ -339,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

{backdraft-0.4.1 → backdraft-0.5.0}/site/llms.txt

@@ -22,9 +22,16 @@ uv tool install backdraft   # pip install backdraft where uv is absent
 # Vision-model extraction for PDFs and images ships by default (needs poppler
 # for PDFs + BACKDRAFT_VLM_API_KEY). Ambient provider keys (OPENAI_API_KEY
 # etc.) are NEVER read; only BACKDRAFT_*.
+# Every PDF ingest stores each page's image (poppler renders them locally, no
+# model calls) so artifacts show the cited page. No poppler: ingest still
+# succeeds, notes it, and `backdraft snapshot-pages <slug>` backfills later.
 # Formats: pdf, xlsx/xlsm, xls (via [xls]), csv/tsv, docx, pptx,
 # png/jpeg/tiff, txt/md. pptx is slide text only; export visual-heavy
 # decks to PDF and ingest via the vision extractor.
+# Sandboxes usually cannot reach model providers: if VLM ingest fails on
+# network, continue with the text layer and say so. The registry travels
+# with the project folder (.backdraft/), so a registry ingested with the
+# vision model elsewhere works in any session; bind and render need no key.
 
 ## The contract
 

backdraft-0.5.0/site/privacy.html

@@ -0,0 +1,126 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Backdraft, privacy</title>
+<meta name="description" content="Backdraft's privacy policy: the software runs locally, collects nothing, and sends nothing anywhere unless you configure a model provider yourself.">
+<link rel="icon" href='data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"%3E%3Crect width="64" height="64" rx="13" fill="%23FBFAF6"/%3E%3Cg transform="translate(32 32) scale(0.82) translate(-32 -32)"%3E%3Cpath fill="%23282828" fill-rule="evenodd" d="M44 3 C38 8 30 10 26 16 C23.5 20 24.5 24 27 26.5 C20.5 28 14.5 33 14 41 C13.3 51.5 22 59.5 33 59.5 C44 59.5 51.5 51.5 51 41.5 C50.6 33.5 45 29 42.5 22.5 C40.8 18 42.5 9 44 3 Z M34 34 C38 38.5 39.5 43.5 37.5 47.5 C35 52 28.5 51.5 26.5 47 C25 43.5 27.5 40 30 38.5 C31.8 37.5 33.2 36 34 34 Z"/%3E%3C/g%3E%3C/svg%3E'>
+<style>
+*,*::before,*::after{box-sizing:border-box}
+:root{
+  --paper:#FFFFFF; --ink:#232323; --muted:#676767; --faint:#A3A19A;
+  --hairline:#E8E5DD; --hairline-strong:#D6D2C6;
+  --notebook:#FBFAF6; --notebook-line:rgba(40,40,40,.05);
+  --sel:#1F7244; --sel-soft:#EAF3EE; --gold:#F5E6AE; --alarm:#A63A2E;
+  --serif:'Iowan Old Style','Iowan Old Style BT',Palatino,'Palatino Linotype',Georgia,serif;
+  --sans:ui-sans-serif,system-ui,-apple-system,'Segoe UI',Helvetica,sans-serif;
+  --mono:ui-monospace,'SF Mono',Menlo,Consolas,monospace;
+}
+html{-webkit-text-size-adjust:100%}
+body{margin:0;background:var(--notebook);color:var(--ink);
+  font-family:var(--serif);font-size:16.5px;line-height:1.62;
+  background-image:
+    repeating-linear-gradient(0deg,var(--notebook-line) 0 1px,transparent 1px 18px),
+    repeating-linear-gradient(90deg,var(--notebook-line) 0 1px,transparent 1px 18px)}
+a{color:inherit;text-decoration:underline;text-decoration-color:rgba(40,40,40,.28);
+  text-underline-offset:3px;text-decoration-thickness:1px}
+a:hover{text-decoration-color:var(--ink)}
+.wrap{max-width:72rem;margin:0 auto;padding:0 1.5rem}
+.bar{display:flex;align-items:center;justify-content:space-between;gap:1rem;
+  padding:1.4rem 0;font-family:var(--sans);font-size:.82rem}
+.brand{display:flex;align-items:center;gap:.5rem;font-family:var(--serif);
+  font-weight:600;font-size:1.05rem;text-decoration:none}
+.bar nav{display:flex;flex-wrap:wrap;justify-content:flex-end;gap:.35rem 1.3rem}
+.bar nav a{text-decoration:none;color:var(--muted);font-weight:500;padding:.2rem 0}
+.bar nav a:hover{color:var(--ink)}
+main{max-width:44rem;padding:2rem 0 6rem}
+main h1{font-size:2rem;font-weight:600;letter-spacing:-.01em;margin:.5rem 0 .6rem}
+.lede{color:var(--muted);margin:0 0 2.5rem;font-size:1rem}
+section{border-top:1px solid var(--hairline);padding:2.2rem 0 .8rem;margin-top:1.6rem}
+h2{font-size:1.35rem;font-weight:600;margin:0 0 .9rem;letter-spacing:-.005em}
+p{margin:0 0 .95rem}
+ul{margin:0 0 .95rem;padding-left:1.3rem}
+li{margin:.25rem 0}
+code{font-family:var(--mono);font-size:.85em;background:rgba(40,40,40,.05);
+  border-radius:3px;padding:.05em .3em}
+footer{text-align:center;font-family:var(--sans);font-size:.74rem;color:var(--muted);
+  padding:0 0 3rem}
+@media (max-width:640px){
+  .wrap{padding:0 1.1rem}
+  .bar{flex-direction:column;align-items:flex-start;gap:.5rem;padding:1.1rem 0}
+  .bar nav{justify-content:flex-start;gap:.35rem 1.1rem}
+  main{padding:1.2rem 0 4rem}
+  main h1{font-size:1.7rem}
+}
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<div class="bar">
+  <a class="brand" href="index.html">
+    <svg width="22" height="22" viewBox="0 0 64 64" aria-hidden="true"><path fill="#232323" fill-rule="evenodd" d="M44 3 C38 8 30 10 26 16 C23.5 20 24.5 24 27 26.5 C20.5 28 14.5 33 14 41 C13.3 51.5 22 59.5 33 59.5 C44 59.5 51.5 51.5 51 41.5 C50.6 33.5 45 29 42.5 22.5 C40.8 18 42.5 9 44 3 Z M34 34 C38 38.5 39.5 43.5 37.5 47.5 C35 52 28.5 51.5 26.5 47 C25 43.5 27.5 40 30 38.5 C31.8 37.5 33.2 36 34 34 Z"/></svg>
+    backdraft
+  </a>
+  <nav>
+    <a href="docs.html">Docs</a>
+    <a href="demo.html">Demo</a>
+    <a href="https://github.com/spencerbraun/backdraft">GitHub</a>
+  </nav>
+</div>
+
+<main>
+<h1>Privacy</h1>
+<p class="lede">Backdraft is local software. It collects nothing.</p>
+
+<section>
+<h2>What Backdraft collects</h2>
+<p>Nothing. The CLI and the agent skills run entirely on your machine. There
+is no telemetry, no analytics, no usage reporting, no crash reporting, and no
+account. We do not see your documents, your queries, or the fact that you use
+Backdraft at all.</p>
+<p>Everything Backdraft produces stays where you put it: the registry and its
+snapshots live in a <code>.backdraft/</code> directory inside your project
+folder, and the rendered artifact is a single self-contained HTML file that
+works with no network connection.</p>
+</section>
+
+<section>
+<h2>When data leaves your machine</h2>
+<p>Only when you configure it, and only to a provider you chose. If you set
+<code>BACKDRAFT_VLM_API_KEY</code>, page images or document images are sent
+to that vision-model provider during ingest; if you set
+<code>BACKDRAFT_ENTAIL_API_KEY</code>, claim and evidence text is sent to
+that provider during the optional entailment check. Without those keys,
+nothing is ever transmitted anywhere.</p>
+<p>Backdraft deliberately never reads ambient provider keys such as
+<code>OPENAI_API_KEY</code>: a key in your environment is not consent to send
+your documents to its provider. Consent is a <code>BACKDRAFT_</code>-scoped
+setting you write yourself.</p>
+<p>Data sent to a provider you configure is governed by that provider's
+privacy policy, not this one.</p>
+</section>
+
+<section>
+<h2>This website</h2>
+<p>backdraft.dev is a static site. It sets no cookies and runs no analytics.
+Standard web server logs may record requests, as with any website.</p>
+</section>
+
+<section>
+<h2>Changes and contact</h2>
+<p>If this policy changes, the change lands in the
+<a href="https://github.com/spencerbraun/backdraft">public repository</a>
+with its full history. Questions: open an issue there.</p>
+<p>Last updated: July 29, 2026.</p>
+</section>
+
+</main>
+</div>
+
+<footer>
+  Backdraft · MIT · <a href="index.html">Home</a> · <a href="https://github.com/spencerbraun/backdraft">GitHub</a>
+</footer>
+</body>
+</html>

{backdraft-0.4.1 → backdraft-0.5.0}/skills/backdraft/SKILL.md

@@ -29,11 +29,18 @@ export BACKDRAFT_SESSION=s-<short-name>
 For real PDFs (glossy layouts, info boxes, scans) the VLM extractor produces the
 best receipts; `auto` prefers it when `BACKDRAFT_VLM_API_KEY` is set (env or `.backdraft/env`; ambient provider keys
 are never read) — the default model is Gemini 3.1 Flash Lite through OpenRouter. If ingest prints a note about falling back to the text
-layer, surface that note to the user — it affects receipt quality.
-
-VLM ingest also stores each page's image, so the artifact can show the cited
-pages themselves. For a registry ingested before that (or via the text layer),
-`backdraft snapshot-pages <slug>` backfills them locally — no model calls.
+layer, surface that note to the user — it affects receipt quality. In a
+sandbox that cannot reach the model provider, do not retry: continue with the
+text layer, tell the user, and mention that a registry ingested with the
+vision model on their own machine travels with the project folder
+(`.backdraft/`) and needs no key at bind or render time.
+
+Ingest also stores each PDF page's image — both paths, since the text-layer
+path renders the pages locally through poppler — so the artifact can show the
+cited pages themselves. If ingest prints a note that page images were not
+captured, the machine has no poppler; ingest and citations are unaffected, and
+`backdraft snapshot-pages <slug>` backfills the images later (also the fix for
+a registry built before ingest did this). No model calls either way.
 
 Then read, narrowing as you go: