backdraft 0.2.0__tar.gz → 0.3.0__tar.gz

backdraft-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras
+      - run: uv run pytest
+      - run: uv build

backdraft-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: release
+on:
+  release:
+    types: [published]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras
+      - run: uv run pytest
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # trusted publishing: OIDC, no stored token
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

backdraft-0.3.0/.github/workflows/site.yml

@@ -0,0 +1,26 @@
+name: site
+on:
+  push:
+    branches: [main]
+    paths: ["site/**"]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+      - id: deployment
+        uses: actions/deploy-pages@v4

{backdraft-0.2.0 → backdraft-0.3.0}/.gitignore

@@ -22,3 +22,4 @@ uv.lock.bak
 
 # Claude Code session state and agent worktrees
 .claude/
+.private/

{backdraft-0.2.0 → backdraft-0.3.0}/DESIGN.md

@@ -1,12 +1,12 @@
 # Backdraft — Design
 
-Status: v0 design, 2026-07-27. Decisions below are made unless marked open. Research backing this is in [research/20260727-research-findings.md](research/20260727-research-findings.md).
+Status: v0 design, 2026-07-27. Decisions below are made unless marked open.
 
 ## The point
 
-Drop-in provenance for factual claims: one click from any claim to the evidence behind it. Extracted from what was built inside the HighRoad app, redesigned from scratch, released standalone. The working problem statement is **verification cost** — an analyst who can't show where a number came from either re-reads the document or doesn't use the output, and both outcomes destroy the value of extraction.
+Drop-in provenance for factual claims: one click from any claim to the evidence behind it. The working problem statement is **verification cost** — an analyst who can't show where a number came from either re-reads the document or doesn't use the output, and both outcomes destroy the value of extraction.
 
-Not a port. The app proved the product (citations worked great from the frontend) but its mechanism was path-dependent: random UUIDs, four citation grammars, four resolver copies, silent failure everywhere, anchors that die on reprocessing. We port the ideas, not the code.
+Designed from first principles against the failure modes that kill citation systems in practice: random anchor ids, competing citation grammars, duplicated resolvers, silent failure, anchors that die on reprocessing.
 
 ## Principles
 
@@ -14,7 +14,7 @@ Not a port. The app proved the product (citations worked great from the frontend
 2. **Content-addressed everything.** Anchors derive their identity from document content + location, not from a run. Reprocessing the same bytes yields the same anchors; citations survive.
 3. **The receipt travels with the claim.** An anchor is not a pointer — it is a pointer plus captured evidence: verbatim snippet, content hash, location. Defensible without reopening the source.
 4. **Failures are data.** Unresolvable tokens, drifted sources, unmatched claims are first-class records in reports and artifacts — never warn-and-drop.
-5. **Coordinates live in-band.** The app's only working sub-page attribution was Excel, because `[B10]` markers sat in the text the model read. Human-readable location in the token; side-channel geometry rots (bbox was plumbed through six layers and read by nothing).
+5. **Coordinates live in-band.** Sub-page attribution works when markers like `[B10]` sit in the text the model reads. Human-readable location in the token; side-channel geometry rots (a bbox plumbed through six layers ends up read by nothing).
 6. **The format is the product.** Substrates (skill, CLI, SDK, viewer) are thin shells over one spec + one library. Artifacts are self-describing and outlive any substrate (subtext's `$format` + embedded legend pattern).
 
 ## Architecture: three layers
@@ -27,13 +27,13 @@ Not a port. The app proved the product (citations worked great from the frontend
 ### 2. The library / CLI (the system)
 Four verbs:
 - **`ingest`** — deterministically anchor source documents (PDF/xlsx/md/…) into the registry: extract, locate, snapshot snippets, hash.
-- **`read` / `search`** — the gate. Emit token-marked context for a model. Search results are themselves mintable evidence (fixing pipeline-v2's gap where search returned nothing citable and forced a page read).
+- **`read` / `search`** — the gate. Emit token-marked context for a model. Search results are themselves mintable evidence (search that returns nothing citable forces a page read purely to obtain an anchor).
 - **`bind`** — postprocess a written document: resolve tokens, run enabled verification switches, backfill surface forms (doc names, pages, quotes), emit sidecar claims file + binding report.
 - **`render`** — produce the clickable artifact.
 
 ### 3. Substrates (sequenced)
 1. **Skill + CLI, together** (first release). The CLI is the system; the skill is ~a page instructing an agent to use it. Ships both the agent-native wedge and the zero-integration backfill demo.
-2. **SDK middleware** — wrap a model call: minted context in, bound citations out. The app-developer drop-in (LoanCore validation-layer shape).
+2. **SDK middleware** — wrap a model call: minted context in, bound citations out. The drop-in for application developers.
 3. **Viewer** — the artifact carries its own single-file viewer; a component version for embedding comes later.
 
 ## The registry
@@ -43,7 +43,7 @@ Four verbs:
 Tables (shape, not final DDL):
 - `documents` — path, display name, **slug**, content sha256, media type, ingest metadata.
 - `anchors` — token, document, locator, verbatim snippet, snippet sha256, created-by (ingest run).
-- `ledger` — session id, token, when shown. Records every token minted into context. Bind distinguishes "cited what you saw" from "cited a valid token you were never shown" — a caught hallucination class the app couldn't express.
+- `ledger` — session id, token, when shown. Records every token minted into context. Bind distinguishes "cited what you saw" from "cited a valid token you were never shown" — a caught hallucination class most systems cannot express.
 - `claims` (written at bind) — claim span text, source doc, citation tokens, verification records.
 
 FTS5 backs `search`. No server, no tenancy — single-analyst/single-project scope; multi-user is a substrate concern, not a registry concern.
@@ -54,7 +54,7 @@ FTS5 backs `search`. No server, no tenancy — single-analyst/single-project sco
 
 - `slug` — short kebab doc identifier assigned at ingest, unique per registry (`t12-audit`, `rent-roll-2025`).
 - `locator` — media-native:
-  - PDF/text: `p8` (page), `p8.c3` (chunk ordinal within page; chunking is deterministic with an explicit within-page ordinal — the column the app never had)
+  - PDF/text: `p8` (page), `p8.c3` (chunk ordinal within page; chunking is deterministic with an explicit within-page ordinal)
   - Excel: `Rent!B10`, `Rent!B10:C12` (sheet + cell/range, spreadsheet-native)
   - Prose files: heading-path or line-range forms (open detail)
 - `hash` — first 4+ hex of sha256 of the normalized snippet. Catches transcription typos, detects drift after re-ingest, and makes the token content-addressed. Registry extends length on collision.
@@ -65,11 +65,11 @@ Reserved extension — **declared derivations**: a claim whose value appears in
 
 ## The gate (context construction)
 
-Ported ideas from pipeline-v2's read tool, rebuilt local:
+The read tool's shape:
 - Unified dispatch: list docs → per-doc TOC of page/sheet summaries → page/range read → batch read. Short slugs everywhere.
 - Progressive disclosure with continuation, plus search hints.
-- **Excel**: sheet-per-page markdown table with `Row | A | B | …` headers and `[B10] value` cell prefixes — the representation that made Excel the app's only working sub-page attribution. Hardening kept: dimension caps, inflated-sheet placeholders, trimming.
-- Fixes over the app: search mints citable snippet tokens; Excel long-context gets structural navigation (detected regions/ranges) instead of char-offset slicing (open design area).
+- **Excel**: sheet-per-page markdown table with `Row | A | B | …` headers and `[B10] value` cell prefixes — the representation that makes cell-level attribution work. Hardening: dimension caps, inflated-sheet placeholders, trimming.
+- Search mints citable snippet tokens; Excel long-context gets structural navigation (detected regions/ranges) rather than char-offset slicing (open design area).
 
 The skill's core instruction is a substitution: for source documents, use `backdraft read`/`search`, not raw Read/Grep.
 
@@ -97,11 +97,11 @@ Independent checks per citation, recorded as graded evidence, never gating gener
 | 3 | `entail` | Model judge: does snippet support claim — tiny closed question, batchable, async | qualitative |
 | 4 | `recompute` | Deterministic re-execution of declared derivations | derived values |
 
-Rationale for default-off: out of the box this is pure provenance (one click to the receipt); verification is opt-in per claim class. Rung-pass rates aggregated per run/model double as an eval substrate (the Clarion use).
+Rationale for default-off: out of the box this is pure provenance (one click to the receipt); verification is opt-in per claim class. Rung-pass rates aggregated per run/model double as an eval substrate.
 
 ## Modes
 
-- **Front-walk** — citations minted during generation; bind resolves against the session ledger. The high-quality integrated path (what the app did).
+- **Front-walk** — citations minted during generation; bind resolves against the session ledger. The high-quality integrated path.
 - **Backfill** — an existing document + ingested sources; for each claim: search → propose anchors → bind via the fuzzier strategies (overlap, value-trace, structured lookup). Unmatched claims land in an explicit unresolved list, not silent non-attribution. Zero integration required — the demo wedge.
 
 Same anchors, same bind, same artifact out.
@@ -127,9 +127,9 @@ Self-contained HTML (plus the machine-readable sidecar): **quotes + receipts + e
 | 2026-07-27 | CLI unified on the gate's patterns: shared `cli_context` (constants, discovery, sessions, one error guard mapping `BackdraftError` → exit 1), `Annotated` params, relative imports. Test fakes renamed so the real and fake registries cannot be confused. |
 | 2026-07-27 | File naming is part of the artifact format, owned by `kernel/artifact.py`: `<stem>.bound.md`, `<stem>.backdraft.json`, `<stem>.backdraft.html`, `<stem>.footnotes.md`. |
 | 2026-07-27 | `bind --check entail` without the extra records `skip` verdicts carrying the reason — verifiers never gate, including at the CLI layer. |
-| 2026-07-27 | **Supersedes "VLM when key present":** credentials are explicit. Ambient provider keys (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`) are never read; a credential reaches backdraft only via `--config`, a `BACKDRAFT_*` variable, or `.backdraft/env` (`init` writes a template). `vlm_ready` — the `auto` gate — is therefore equivalent to consent. Decided after a real unapproved-spend incident during the Darnell trial: presence of a generic key in the environment is not consent to spend it or send documents to its provider. |
+| 2026-07-27 | **Supersedes "VLM when key present":** credentials are explicit. Ambient provider keys (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`) are never read; a credential reaches backdraft only via `--config`, a `BACKDRAFT_*` variable, or `.backdraft/env` (`init` writes a template). `vlm_ready` — the `auto` gate — is therefore equivalent to consent. Decided after a real unapproved-spend incident during the first field trial: presence of a generic key in the environment is not consent to spend it or send documents to its provider. |
 | 2026-07-28 | **Reader doctrine (supersedes "no script"):** the artifact is designed for two readers — the writer verifying the AI's work, and a normal person the document is sent to — in three disclosure layers: the document (editorial typography, quiet marks), the footnote (click a claim → the source's own words, named and paged — no tokens, no hashes, no jargon), and the record (one deliberate step to the full machine-readable layer). **Success is silent; only failure speaks**: a fully-resolved artifact looks like a well-made document, while unresolved citations announce themselves before the reader invests belief. The load-bearing constraint is *no network, single file* — enforced by a CSP `meta` tag (`default-src 'none'`) — not *no script*: inline JS is allowed as progressive enhancement over a CSS-only baseline that survives script-stripping. Decided after field use: the v1 artifact rendered success and failure at equal volume and read as machinery, not a document. |
-| 2026-07-28 | **Evidence embeds in the artifact (supersedes "no page images in v0"):** the footnote layer carries the evidence itself, not just the quote — the cited page as an image, the cited cell in a mini-grid window (neighbors, row labels, column headers). Bounded by *what is cited*, never the corpus, so a memo citing ten pages costs ~2–3 MB; `--lean` skips images. Evidence is assembled at **bind** (the step that has the registry) and travels in the sidecar; render stays registry-blind and the artifact stays reproducible from the two files a reader was handed. For the VLM path, the page image the model was shown is stored at **ingest** — for a non-deterministic extractor the input pixels are the only reproducible snapshot, so the image completes the receipt chain (claim → quote → page). Reference shapes ported from embed-ses `generate-preview`: WebP quality 85 for pages; sheet windows as compact JSON with typed cell values and column-letter headers. |
+| 2026-07-28 | **Evidence embeds in the artifact (supersedes "no page images in v0"):** the footnote layer carries the evidence itself, not just the quote — the cited page as an image, the cited cell in a mini-grid window (neighbors, row labels, column headers). Bounded by *what is cited*, never the corpus, so a memo citing ten pages costs ~2–3 MB; `--lean` skips images. Evidence is assembled at **bind** (the step that has the registry) and travels in the sidecar; render stays registry-blind and the artifact stays reproducible from the two files a reader was handed. For the VLM path, the page image the model was shown is stored at **ingest** — for a non-deterministic extractor the input pixels are the only reproducible snapshot, so the image completes the receipt chain (claim → quote → page). Reference shapes: WebP quality 85 for pages; sheet windows as compact JSON with typed cell values and column-letter headers. |
 | 2026-07-28 | **Exhibits: the evidence-first inversion.** The artifact carries a second reading mode: every source document with the data points cited from it, each with its evidence context and backlinks to the claims that lean on it — "this memo rests on N data points across M documents." Ranking is deterministic in v1 (an anchor cited by three claims outranks one cited once); model-judged importance is a later switch. This is the skeptical reader's entry point and the writer's spot-check checklist. |
 
 ## Open
@@ -139,8 +139,8 @@ substrates); this list is questions still awaiting a decision:
 
 - Re-bind/orphan pass on re-ingest of changed docs (chunk ordinal drift)
 - Prose-file locator forms; slug assignment/collision rules (the trailing-hyphen
-  truncation from the Darnell trial lives here)
-- Distribution: PyPI (name `backdraft` verified free 2026-07-28), skill
-  registration; domain backdraft.dev acquired 2026-07-28
-- First external user (LoanCore validation layer vs Clarion eval substrate vs
+  truncation from the first field trial lives here)
+- Distribution: published to PyPI as `backdraft` 0.2.0 (2026-07-28); domain
+  backdraft.dev acquired; still open: skill registration, deploying site/
+- First external user (design-partner validation layer vs eval substrate vs
   open release feedback)

{backdraft-0.2.0 → backdraft-0.3.0}/PKG-INFO

@@ -1,7 +1,11 @@
 Metadata-Version: 2.4
 Name: backdraft
-Version: 0.2.0
+Version: 0.3.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
+Project-URL: Repository, https://github.com/spencerbraun/backdraft
+Project-URL: Roadmap, https://github.com/spencerbraun/backdraft/blob/main/ROADMAP.md
 License: MIT
 License-File: LICENSE
 Requires-Python: >=3.13
@@ -27,25 +31,26 @@ or does not use the output. Backdraft removes that cost. In the usual loop, an
 **agent** does the writing: it reads your source documents only through a gate
 that mints a citation token over every span it shows, cites those tokens
 inline, and a postprocess resolves them, attaches the verbatim evidence, and
-renders one self-contained HTML file — the memo with the actual cited pages
+renders one self-contained HTML file, the memo with the actual cited pages
 and spreadsheet cells embedded inside it. The **human** just reads that file:
 click a claim, see the source.
 
 It works the same whether the writer is a model or a person, and whether the
 citations were minted during writing or attached to a document afterwards.
 
-Docs live at [backdraft.dev](https://backdraft.dev) — one page for people, and
+Docs live at [backdraft.dev](https://backdraft.dev), one page for people, and
 [backdraft.dev/llms.txt](https://backdraft.dev/llms.txt) for agents.
 
 ## 60 seconds
 
 ```bash
-uv tool install git+https://github.com/spencerbraun/backdraft
+uv tool install "backdraft[vlm]"
 cd demo
 ```
 
-**Ingest** the sources. Every anchor is minted here — chunks for PDF pages,
-cells for spreadsheet sheets.
+**Ingest** the sources. Every anchor is minted here, chunks for PDF pages,
+cells for spreadsheet sheets. Formats: PDF, XLSX/XLSM, CSV/TSV, images
+(png, jpeg, tiff, through the vision model), plain text and Markdown.
 
 ```console
 $ backdraft init
@@ -66,7 +71,7 @@ $ backdraft read t12-summary p1
 # t12-summary p1  (page 1 of 3)
 
 [bd:t12-summary:p1.c1:c2e8]
-Bridgeview Commons — Trailing Twelve Month Summary
+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. This summary
@@ -86,7 +91,7 @@ Chunks fall on the document's own paragraphs. A PDF stores glyphs at
 coordinates, not paragraphs, so the extractor rebuilds the breaks from the line
 geometry before the chunker sees the page.
 
-Search results are citable too — no page read required to get an anchor:
+Search results are citable too, no page read required to get an anchor:
 
 ```console
 $ backdraft search "24850000"
@@ -129,12 +134,12 @@ $ echo $?
 2
 ```
 
-Exit 2 means a citation did not resolve — the code a `Stop` hook or a CI job
+Exit 2 means a citation did not resolve, the code a `Stop` hook or a CI job
 gates on.
 
 **Render.** One self-contained HTML file: the document, the receipts, the
-evidence — cited page images, spreadsheet cells in place, the machine-readable
-record — all embedded, no network, nothing to install for the reader.
+evidence, cited page images, spreadsheet cells in place, the machine-readable
+record, all embedded, no network, nothing to install for the reader.
 
 ```console
 $ backdraft render memo.md --to html
@@ -152,13 +157,13 @@ in at [`demo/memo.backdraft.html`](demo/memo.backdraft.html).
 
 Reading is a **gate**: source documents reach the writer only through `read` and
 `search`, which mint a token over everything they show and record it in a
-**ledger**, so the set of citable things is exactly the set of things shown — and
+**ledger**, so the set of citable things is exactly the set of things shown, and
 a citation to something the writer never saw is a distinguishable failure rather
 than an invisible one. **Anchors are content-addressed**: a token's identity
 derives from the document's content and a location inside it, and it binds to an
 extraction snapshot, so re-ingesting the same bytes yields the same tokens and a
 changed source yields `drifted` instead of a broken link. **The receipt travels
-with the claim** — an anchor is not a pointer but a pointer plus the verbatim
+with the claim**, an anchor is not a pointer but a pointer plus the verbatim
 snippet and its hash, which is why the finished artifact is defensible with the
 registry deleted and the sources gone. **Verification is a set of switches,
 default off**: resolution is inherent to binding, but `value-trace`, `overlap`
@@ -175,31 +180,29 @@ artifact. Nothing is ever warned about and dropped.
 ## What lives where
 
 A working directory stays clean: the authored document and its artifact are
-the only visible outputs. Everything else — registry, credentials, bind
-records — lives under one hidden `.backdraft/` directory, and
+the only visible outputs. Everything else, registry, credentials, bind
+records, lives under one hidden `.backdraft/` directory, and
 `backdraft clean` tidies strays from older versions. The registry contains the
 full text of everything ingested, so **gitignore `.backdraft/` for
 confidential corpora**.
 
 ## Install
 
-Not yet on PyPI — install from the repository:
-
 ```bash
-uv tool install git+https://github.com/spencerbraun/backdraft      # CLI
-uv add "backdraft @ git+https://github.com/spencerbraun/backdraft" # as a dependency
-pip install git+https://github.com/spencerbraun/backdraft          # or plain pip
+uv tool install "backdraft[vlm]"   # CLI, recommended form
+uv add backdraft                   # as a dependency
+pip install backdraft              # or plain pip
 ```
 
 Python 3.13+. Two extras:
 
 | Extra | Adds | For |
 |---|---|---|
-| `[vlm]` | `openai`, `pdf2image` | the VLM extractor — the recommended path for real PDFs (glossy layouts, info boxes, scans): a vision model reads each page and its clean representation becomes the receipt. `--extractor auto` prefers it only on explicit, backdraft-scoped consent: `BACKDRAFT_VLM_API_KEY` (env or `.backdraft/env` — `backdraft init` writes a template). Ambient `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 the keyless text layer and says so. Needs poppler installed separately |
+| `[vlm]` | `openai`, `pdf2image` | the VLM extractor, the recommended path for real PDFs (glossy layouts, info boxes, scans): a vision model reads each page and its clean representation becomes the receipt. `--extractor auto` prefers it only on explicit, backdraft-scoped consent: `BACKDRAFT_VLM_API_KEY` (env or `.backdraft/env`, `backdraft init` writes a template). Ambient `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 the keyless text layer and says so. Needs poppler installed separately |
 | `[entail]` | `anthropic` | `bind --check entail`, the model-judge verifier |
 
 ```bash
-pip install "backdraft[vlm,entail] @ git+https://github.com/spencerbraun/backdraft"
+pip install "backdraft[vlm,entail]"
 ```
 
 From a checkout:
@@ -212,12 +215,12 @@ uv run pytest
 
 ## Skills
 
-Three agent skills ship in [`skills/`](skills). Copy the ones you want into your
-agent's skills directory — for Claude Code, `~/.claude/skills/` (personal) or
-`.claude/skills/` (per project):
+Three agent skills ship inside the package, and the CLI installs them:
 
 ```bash
-cp -r skills/backdraft skills/backdraft-backfill skills/backdraft-artifact ~/.claude/skills/
+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/
 ```
 
 | Skill | For |
@@ -233,11 +236,11 @@ the skills is required to use backdraft by hand.
 
 | Document | Is |
 |---|---|
-| [DESIGN.md](DESIGN.md) | why it is shaped this way — principles, architecture, decision log |
-| [SPEC.md](SPEC.md) | the builders' contract — types, grammar, DDL, CLI surface, module boundaries |
+| [DESIGN.md](DESIGN.md) | why it is shaped this way, principles, architecture, decision log |
+| [SPEC.md](SPEC.md) | the builders' contract, types, grammar, DDL, CLI surface, module boundaries |
 | [spec/tokens.md](spec/tokens.md) | the citation token grammar, normatively |
 | [spec/chunking.md](spec/chunking.md) | the deterministic chunker |
-| [spec/artifact.md](spec/artifact.md) | the artifact format — sidecar payload, legend, HTML rules |
+| [spec/artifact.md](spec/artifact.md) | the artifact format, sidecar payload, legend, HTML rules |
 | [demo/walkthrough.md](demo/walkthrough.md) | the whole thing end to end, with real output |
 
 The three files under `spec/` are the portable specification: another
@@ -246,8 +249,8 @@ implementation reads them and nothing else.
 ## Status
 
 v1. The registry format, the token grammar and the artifact format are pinned
-by prose specs and golden-file tests. What is deliberately queued — exhibits,
-Excel region maps, more formats, `bd:calc` derivations — is written down in
+by prose specs and golden-file tests. What is deliberately queued, exhibits,
+Excel region maps, more formats, `bd:calc` derivations, is written down in
 [ROADMAP.md](ROADMAP.md).
 
 MIT licensed.

{backdraft-0.2.0 → backdraft-0.3.0}/README.md

@@ -10,25 +10,26 @@ or does not use the output. Backdraft removes that cost. In the usual loop, an
 **agent** does the writing: it reads your source documents only through a gate
 that mints a citation token over every span it shows, cites those tokens
 inline, and a postprocess resolves them, attaches the verbatim evidence, and
-renders one self-contained HTML file — the memo with the actual cited pages
+renders one self-contained HTML file, the memo with the actual cited pages
 and spreadsheet cells embedded inside it. The **human** just reads that file:
 click a claim, see the source.
 
 It works the same whether the writer is a model or a person, and whether the
 citations were minted during writing or attached to a document afterwards.
 
-Docs live at [backdraft.dev](https://backdraft.dev) — one page for people, and
+Docs live at [backdraft.dev](https://backdraft.dev), one page for people, and
 [backdraft.dev/llms.txt](https://backdraft.dev/llms.txt) for agents.
 
 ## 60 seconds
 
 ```bash
-uv tool install git+https://github.com/spencerbraun/backdraft
+uv tool install "backdraft[vlm]"
 cd demo
 ```
 
-**Ingest** the sources. Every anchor is minted here — chunks for PDF pages,
-cells for spreadsheet sheets.
+**Ingest** the sources. Every anchor is minted here, chunks for PDF pages,
+cells for spreadsheet sheets. Formats: PDF, XLSX/XLSM, CSV/TSV, images
+(png, jpeg, tiff, through the vision model), plain text and Markdown.
 
 ```console
 $ backdraft init
@@ -49,7 +50,7 @@ $ backdraft read t12-summary p1
 # t12-summary p1  (page 1 of 3)
 
 [bd:t12-summary:p1.c1:c2e8]
-Bridgeview Commons — Trailing Twelve Month Summary
+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. This summary
@@ -69,7 +70,7 @@ Chunks fall on the document's own paragraphs. A PDF stores glyphs at
 coordinates, not paragraphs, so the extractor rebuilds the breaks from the line
 geometry before the chunker sees the page.
 
-Search results are citable too — no page read required to get an anchor:
+Search results are citable too, no page read required to get an anchor:
 
 ```console
 $ backdraft search "24850000"
@@ -112,12 +113,12 @@ $ echo $?
 2
 ```
 
-Exit 2 means a citation did not resolve — the code a `Stop` hook or a CI job
+Exit 2 means a citation did not resolve, the code a `Stop` hook or a CI job
 gates on.
 
 **Render.** One self-contained HTML file: the document, the receipts, the
-evidence — cited page images, spreadsheet cells in place, the machine-readable
-record — all embedded, no network, nothing to install for the reader.
+evidence, cited page images, spreadsheet cells in place, the machine-readable
+record, all embedded, no network, nothing to install for the reader.
 
 ```console
 $ backdraft render memo.md --to html
@@ -135,13 +136,13 @@ in at [`demo/memo.backdraft.html`](demo/memo.backdraft.html).
 
 Reading is a **gate**: source documents reach the writer only through `read` and
 `search`, which mint a token over everything they show and record it in a
-**ledger**, so the set of citable things is exactly the set of things shown — and
+**ledger**, so the set of citable things is exactly the set of things shown, and
 a citation to something the writer never saw is a distinguishable failure rather
 than an invisible one. **Anchors are content-addressed**: a token's identity
 derives from the document's content and a location inside it, and it binds to an
 extraction snapshot, so re-ingesting the same bytes yields the same tokens and a
 changed source yields `drifted` instead of a broken link. **The receipt travels
-with the claim** — an anchor is not a pointer but a pointer plus the verbatim
+with the claim**, an anchor is not a pointer but a pointer plus the verbatim
 snippet and its hash, which is why the finished artifact is defensible with the
 registry deleted and the sources gone. **Verification is a set of switches,
 default off**: resolution is inherent to binding, but `value-trace`, `overlap`
@@ -158,31 +159,29 @@ artifact. Nothing is ever warned about and dropped.
 ## What lives where
 
 A working directory stays clean: the authored document and its artifact are
-the only visible outputs. Everything else — registry, credentials, bind
-records — lives under one hidden `.backdraft/` directory, and
+the only visible outputs. Everything else, registry, credentials, bind
+records, lives under one hidden `.backdraft/` directory, and
 `backdraft clean` tidies strays from older versions. The registry contains the
 full text of everything ingested, so **gitignore `.backdraft/` for
 confidential corpora**.
 
 ## Install
 
-Not yet on PyPI — install from the repository:
-
 ```bash
-uv tool install git+https://github.com/spencerbraun/backdraft      # CLI
-uv add "backdraft @ git+https://github.com/spencerbraun/backdraft" # as a dependency
-pip install git+https://github.com/spencerbraun/backdraft          # or plain pip
+uv tool install "backdraft[vlm]"   # CLI, recommended form
+uv add backdraft                   # as a dependency
+pip install backdraft              # or plain pip
 ```
 
 Python 3.13+. Two extras:
 
 | Extra | Adds | For |
 |---|---|---|
-| `[vlm]` | `openai`, `pdf2image` | the VLM extractor — the recommended path for real PDFs (glossy layouts, info boxes, scans): a vision model reads each page and its clean representation becomes the receipt. `--extractor auto` prefers it only on explicit, backdraft-scoped consent: `BACKDRAFT_VLM_API_KEY` (env or `.backdraft/env` — `backdraft init` writes a template). Ambient `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 the keyless text layer and says so. Needs poppler installed separately |
+| `[vlm]` | `openai`, `pdf2image` | the VLM extractor, the recommended path for real PDFs (glossy layouts, info boxes, scans): a vision model reads each page and its clean representation becomes the receipt. `--extractor auto` prefers it only on explicit, backdraft-scoped consent: `BACKDRAFT_VLM_API_KEY` (env or `.backdraft/env`, `backdraft init` writes a template). Ambient `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 the keyless text layer and says so. Needs poppler installed separately |
 | `[entail]` | `anthropic` | `bind --check entail`, the model-judge verifier |
 
 ```bash
-pip install "backdraft[vlm,entail] @ git+https://github.com/spencerbraun/backdraft"
+pip install "backdraft[vlm,entail]"
 ```
 
 From a checkout:
@@ -195,12 +194,12 @@ uv run pytest
 
 ## Skills
 
-Three agent skills ship in [`skills/`](skills). Copy the ones you want into your
-agent's skills directory — for Claude Code, `~/.claude/skills/` (personal) or
-`.claude/skills/` (per project):
+Three agent skills ship inside the package, and the CLI installs them:
 
 ```bash
-cp -r skills/backdraft skills/backdraft-backfill skills/backdraft-artifact ~/.claude/skills/
+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/
 ```
 
 | Skill | For |
@@ -216,11 +215,11 @@ the skills is required to use backdraft by hand.
 
 | Document | Is |
 |---|---|
-| [DESIGN.md](DESIGN.md) | why it is shaped this way — principles, architecture, decision log |
-| [SPEC.md](SPEC.md) | the builders' contract — types, grammar, DDL, CLI surface, module boundaries |
+| [DESIGN.md](DESIGN.md) | why it is shaped this way, principles, architecture, decision log |
+| [SPEC.md](SPEC.md) | the builders' contract, types, grammar, DDL, CLI surface, module boundaries |
 | [spec/tokens.md](spec/tokens.md) | the citation token grammar, normatively |
 | [spec/chunking.md](spec/chunking.md) | the deterministic chunker |
-| [spec/artifact.md](spec/artifact.md) | the artifact format — sidecar payload, legend, HTML rules |
+| [spec/artifact.md](spec/artifact.md) | the artifact format, sidecar payload, legend, HTML rules |
 | [demo/walkthrough.md](demo/walkthrough.md) | the whole thing end to end, with real output |
 
 The three files under `spec/` are the portable specification: another
@@ -229,8 +228,8 @@ implementation reads them and nothing else.
 ## Status
 
 v1. The registry format, the token grammar and the artifact format are pinned
-by prose specs and golden-file tests. What is deliberately queued — exhibits,
-Excel region maps, more formats, `bd:calc` derivations — is written down in
+by prose specs and golden-file tests. What is deliberately queued, exhibits,
+Excel region maps, more formats, `bd:calc` derivations, is written down in
 [ROADMAP.md](ROADMAP.md).
 
 MIT licensed.

{backdraft-0.2.0 → backdraft-0.3.0}/ROADMAP.md

@@ -14,7 +14,7 @@ losing it. Items graduate by getting built and deleted.
   2026-07-28 pending a real audience for it.*
 
 - **Excel region maps and range reads** — navigation for large sheets. The
-  research is done (`research/20260727-excel-region-detection.md`): a
+  research is done (notes kept privately): a
   deterministic detection cascade (declared tables → named ranges → print
   areas / freeze panes → merged-aware connected components) producing a
   table of contents per sheet. Two hard constraints from that research:
@@ -23,24 +23,22 @@ losing it. Items graduate by getting built and deleted.
 
 ## Formats
 
-Today: PDF (VLM primary, text-layer floor), XLSX, plain text and Markdown.
-Each new format is one Extractor implementing the existing protocol — pages
-out, receipts quotable, nothing downstream changes.
+Today: PDF (VLM primary, text-layer floor), XLSX/XLSM, CSV/TSV, images
+(png, jpeg, tiff — VLM, the file is its own snapshot), plain text and
+Markdown. Each new format is one Extractor implementing the existing
+protocol — pages out, receipts quotable, nothing downstream changes.
 
-- **Images (png, jpeg, tiff)** — a photographed or scanned page is a
-  one-page document; the VLM extractor already is this pipeline minus the
-  pdf2image step, and the source file is its own stored snapshot. Cheapest
-  high-value addition.
-- **CSV** — a workbook with one sheet; reuse the sheet representation (A1
-  refs, cell anchors) wholesale. Deterministic, keyless, near-trivial.
 - **DOCX** — leases, LOIs, agreements. Structured XML, so the deterministic
   path is the good path (paragraphs and tables straight out of the file, no
-  OCR); tables render to markdown like sheets do.
+  OCR); tables render to markdown like sheets do. Needs a decision row
+  first: DOCX has no pages, so locators want synthesizing from heading
+  sections.
 - **PPTX** — offering memoranda that arrive as decks. Slide text is
-  extractable deterministically as the floor; the faithful path renders
-  slides to images through the VLM like PDF pages.
-- **XLS / XLSM** — legacy and macro workbooks. openpyxl covers xlsm;
-  xls wants the calamine fallback embed-ses already proved in production.
+  extractable deterministically as the floor; the faithful path (slide
+  images) needs a renderer on PATH, LibreOffice or similar, behind a
+  capability check like poppler's.
+- **XLS** — legacy workbooks; python-calamine as the tolerant fallback
+  behind an extra.
 - **Someday**: HTML pages, email (.eml) — both arrive in diligence folders,
   both have messy identity questions (what is "the source" of a web page?)
   that deserve a decision row before code.
@@ -52,10 +50,11 @@ out, receipts quotable, nothing downstream changes.
   malformed-on-purpose). The field-trial case: "about 4% of embedded
   loss-to-lease," derived from two cited cells, currently an honest
   value-trace fail with nowhere to point.
-- **Sheet styling fidelity** — carry bold / fills / merges / column widths
-  through ingest so sheet evidence looks like the workbook, not just its
-  values. The shapes to port are embed-ses `generate-preview`'s
-  (`SheetData.cell_styles`, `merged_ranges`, `column_widths`, `frozen_panes`).
+- **Merged-cell and frozen-pane rendering** — ingest already captures
+  `merged` and `frozen` in sheet meta; the artifact's sheet view renders
+  neither yet (merges want colspan/rowspan grid building, frozen panes want
+  a second sticky axis). Styling, number formats, and column widths already
+  render.
 - **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
@@ -64,8 +63,8 @@ out, receipts quotable, nothing downstream changes.
   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).
-- **Distribution** — PyPI publish decision and the "backdraft" name check;
-  install is git-only until then.
+- **Distribution** — published on PyPI; still queued: a skills-registry
+  listing when one becomes the standard channel.
 
 ## Someday