backdraft 0.2.0__tar.gz

backdraft-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+.Python
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+uv.lock.bak
+
+# Backdraft registry
+.backdraft/
+
+# OS
+.DS_Store
+
+# Claude Code session state and agent worktrees
+.claude/

backdraft-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

backdraft-0.2.0/DESIGN.md

@@ -0,0 +1,146 @@
+# 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).
+
+## 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.
+
+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.
+
+## Principles
+
+1. **Gate, don't verify.** The structure of how information reaches the model determines what it can cite. Reading happens through a tool that mints citation tokens; the set of citable things is exactly the set of things shown. Verification (below) is a separate, optional layer — not the correctness story.
+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).
+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
+
+### 1. The spec
+- **Citation token grammar** — one grammar, typed, shared parser (Python + TS).
+- **Anchor schema** — pointer + receipt.
+- **Artifact format** — self-describing annotated document: versioned format string, embedded legend, claims with citation lists, sources map, provenance slot (filled — `author_type: human|agent`, model, run; the field subtext specified and left empty), verification records, unresolved list.
+
+### 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).
+- **`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).
+3. **Viewer** — the artifact carries its own single-file viewer; a component version for embedding comes later.
+
+## The registry
+
+**SQLite**, in `.backdraft/` per project. JSON export command for portability and diffing.
+
+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.
+- `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.
+
+## Token grammar
+
+**`bd:<slug>:<locator>:<hash>`** — compound, human-readable location, content-hash suffix.
+
+- `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)
+  - 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.
+
+Examples: `[DSCR of 1.42x](bd:t12-audit:p8.c3:a7f3)` · `[NOI of $4.1M](bd:model:Rent!B10:9e2f)`
+
+Reserved extension — **declared derivations**: a claim whose value appears in no document carries its computation over multiple tokens (`bd:calc(model:Rent!B10 / t12-audit:p4.c1)` — sketch, grammar open). This is what makes "the numbers tie" a deterministic check instead of a slogan; only possible because we own the grammar.
+
+## The gate (context construction)
+
+Ported ideas from pipeline-v2's read tool, rebuilt local:
+- 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).
+
+The skill's core instruction is a substitution: for source documents, use `backdraft read`/`search`, not raw Read/Grep.
+
+## Wire format
+
+The writer emits inline tokens on the claim span — `[claim text](bd:…)` — and nothing else: no doc names, no footnotes, no display text. Span binding (which words the anchor supports) is captured at write time because it can never be recovered later and can always be projected away. Footnotes, endnote lists, hover cards are all render-time projections.
+
+## Bind
+
+Runs after writing (in Claude Code: enforceable as a Stop/PostToolUse hook so unbound tokens can't ship).
+
+1. **Resolve** every token: parses → registry hit → ledger hit → snippet hash matches current source. Resolution is inherent to bind (an unresolvable token can't be backfilled) — it is not a switch.
+2. **Verify** per enabled switches (below).
+3. **Backfill** surface forms: tokens become readable citations (doc name, page/cell, quote) in the output doc.
+4. **Report**: sidecar claims file + binding report. Every failure is a line item: `unresolved`, `not-shown`, `drifted`, `unmatched` (backfill mode). Nothing drops silently.
+
+## Verification — switches, default off
+
+Independent checks per citation, recorded as graded evidence, never gating generation. The record says which methods ran and what each found; switches off ⇒ record says unchecked. Grade schema is stable regardless of which switches are on.
+
+| # | Switch | Method | Claim class |
+|---|---|---|---|
+| 1 | `value-trace` | Deterministic: normalized value (units/scale/format) occurs at the cited location | numbers, dates, names |
+| 2 | `overlap` | Heuristic span overlap / exact substring for quotes — report-only signal | quotes, paraphrase |
+| 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).
+
+## Modes
+
+- **Front-walk** — citations minted during generation; bind resolves against the session ledger. The high-quality integrated path (what the app did).
+- **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.
+
+## The artifact
+
+Self-contained HTML (plus the machine-readable sidecar): **quotes + receipts + evidence embedded** — verbatim snippets, hashes, locations, verification grades, and the evidence itself: cited pages as images, cited cells in mini-grid windows. Bounded by what is cited, never the corpus; `--lean` drops images. Small and portable; defensible with sources absent. Designed in three disclosure layers (document → footnote → record) with success silent and failure loud — see the 2026-07-28 decision rows.
+
+## Decision log
+
+| Date | Decision |
+|---|---|
+| 2026-07-27 | Rewrite, not port; ideas only |
+| 2026-07-27 | Gate-over-verify: read path mints citable tokens; ledger records what was shown |
+| 2026-07-27 | Receipt (snippet + hash + location) is part of the anchor primitive |
+| 2026-07-27 | Registry: SQLite in `.backdraft/`, JSON export |
+| 2026-07-27 | Token grammar: compound `bd:slug:loc:hash` |
+| 2026-07-27 | Verification: independent switches, default off; resolution is inherent to bind, not a switch |
+| 2026-07-27 | First substrate: skill + CLI together; SDK middleware and viewer follow |
+| 2026-07-27 | Artifact: quotes + receipts embedded, no page images in v0 |
+| 2026-07-27 | VLM extraction is the recommended primary path for real PDFs (glossy layouts, info boxes — the snapshot is the receipt, and model reading beats scrambled text-layer order). Text-layer is the keyless floor and CI path, not "the default." `ingest --extractor auto` picks VLM when an API key is configured, else text-layer with a printed nudge. Known tradeoff, accepted: re-extraction under a non-deterministic extractor drifts all citations; generations + drift reporting carry that honestly. |
+| 2026-07-27 | Kernel API is module paths (`backdraft.kernel.tokens.parse`); no flat re-export surface. Package `__init__`s export exactly what outside consumers import. |
+| 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-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 | **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
+
+Queued work lives in ROADMAP.md (exhibits, region maps, formats, `bd:calc`,
+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
+  open release feedback)

backdraft-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spencer Braun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

backdraft-0.2.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: backdraft
+Version: 0.2.0
+Summary: Drop-in provenance for factual claims: one click from any claim to the evidence behind it.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: typer>=0.12
+Provides-Extra: entail
+Requires-Dist: anthropic>=0.40; extra == 'entail'
+Provides-Extra: vlm
+Requires-Dist: openai>=1.0; extra == 'vlm'
+Requires-Dist: pdf2image>=1.17; extra == 'vlm'
+Description-Content-Type: text/markdown
+
+<img src="assets/backdraft-mark.svg" width="56" alt="">
+
+# backdraft
+
+Drop-in provenance for factual claims: one click from any claim to the receipt
+behind it.
+
+An analyst who cannot show where a number came from either re-reads the source
+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
+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
+[backdraft.dev/llms.txt](https://backdraft.dev/llms.txt) for agents.
+
+## 60 seconds
+
+```bash
+uv tool install git+https://github.com/spencerbraun/backdraft
+cd demo
+```
+
+**Ingest** the sources. Every anchor is minted here — chunks for PDF pages,
+cells for spreadsheet sheets.
+
+```console
+$ backdraft init
+registry: /…/demo/.backdraft
+documents: 0
+
+$ backdraft ingest sources/t12-summary.pdf sources/underwriting-model.xlsx
+t12-summary  t12-summary.pdf  pdf  3 pages
+underwriting-model  underwriting-model.xlsx  xlsx  2 pages
+note: extracted with pdf-text (the embedded text layer). Glossy or scanned PDFs extract better through a vision model: install backdraft[vlm] and set BACKDRAFT_VLM_API_KEY in .backdraft/env.
+```
+
+**Read.** The page arrives with a citable name over each chunk. This is the whole
+mechanism: what you can cite is exactly what you were shown.
+
+```console
+$ backdraft read t12-summary p1
+# t12-summary p1  (page 1 of 3)
+
+[bd:t12-summary:p1.c1:c2e8]
+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
+covers the trailing twelve months ended March 31, 2026, prepared from the borrower's monthly operating
+statements and reconciled against the property manager's general ledger. Figures are unaudited.
+
+[bd:t12-summary:p1.c2:7f11]
+Total effective gross income for the trailing twelve months was $2,684,400, against gross potential rent of
+$2,972,160. The resulting economic occupancy of 90.3% reflects an average physical occupancy of 94.1% offset
+by concessions, bad debt, and vacancy loss. Physical occupancy was 96.4% in the most recent month and has not
+fallen below 92.0% in any month of the period.
+
+… five more chunks, c3 through c7.
+```
+
+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:
+
+```console
+$ backdraft search "24850000"
+1 result for "24850000"
+
+[bd:underwriting-model:assumptions!B10:964a]  underwriting-model p2
+  24850000
+
+[Read the page: backdraft read underwriting-model p2]
+```
+
+A cell you can already see mints directly:
+
+```console
+$ backdraft cell underwriting-model "assumptions!B10"
+[bd:underwriting-model:assumptions!B10:964a]  24850000
+```
+
+**Cite** by writing the token as the href of a markdown link on the claim span.
+Multiple citations are `;`-separated in one href.
+
+```markdown
+[net operating income of $1,429,600](bd:t12-summary:p1.c3:f10b)
+[Effective gross income of $2,684,400](bd:t12-summary:p1.c2:7f11;bd:underwriting-model:rent-roll!B11:4b79)
+```
+
+**Bind.** Every token resolves or is reported. Nothing drops silently.
+
+```console
+$ 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
+  value-trace: pass 15
+  ! unresolved: bd:t12-summary:p4.c1:1a2b
+wrote .backdraft/records/memo.backdraft.json
+
+$ echo $?
+2
+```
+
+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.
+
+```console
+$ backdraft render memo.md --to html
+memo.backdraft.html
+```
+
+That file is the whole deliverable: send it over email or Slack and the
+recipient gets the full experience by double-clicking it.
+
+The full version of this, with every command and every output:
+[`demo/walkthrough.md`](demo/walkthrough.md). The artifact it produces is checked
+in at [`demo/memo.backdraft.html`](demo/memo.backdraft.html).
+
+## The design in five sentences
+
+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
+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
+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`
+and `entail` are opt-in, recorded as graded evidence and never used as gates, so
+out of the box this is provenance rather than a truth oracle. **Artifacts are
+self-describing**: each carries a `$format` string matched byte-for-byte and an
+embedded `$legend` that teaches a reader who has never heard of backdraft how to
+decode and check it, so the format outlives this implementation.
+
+Failures are data throughout: `unresolved`, `not_shown`, `drifted`, `malformed`
+and `unmatched` are first-class records in the report and visible sections in the
+artifact. Nothing is ever warned about and dropped.
+
+## 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
+`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
+```
+
+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 |
+| `[entail]` | `anthropic` | `bind --check entail`, the model-judge verifier |
+
+```bash
+pip install "backdraft[vlm,entail] @ git+https://github.com/spencerbraun/backdraft"
+```
+
+From a checkout:
+
+```bash
+uv sync
+uv run backdraft --help
+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):
+
+```bash
+cp -r skills/backdraft skills/backdraft-backfill skills/backdraft-artifact ~/.claude/skills/
+```
+
+| Skill | For |
+|---|---|
+| [`backdraft`](skills/backdraft/SKILL.md) | writing a new document from sources, citing as it goes |
+| [`backdraft-backfill`](skills/backdraft-backfill/SKILL.md) | attributing a document that already exists |
+| [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | reading someone else's artifact cold |
+
+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.
+
+## Documentation
+
+| 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 |
+| [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 |
+| [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
+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
+[ROADMAP.md](ROADMAP.md).
+
+MIT licensed.