backdraft 0.8.0__tar.gz → 0.9.0__tar.gz

{backdraft-0.8.0 → backdraft-0.9.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "backdraft",
   "displayName": "Backdraft",
-  "version": "0.8.0",
+  "version": "0.9.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.8.0 → backdraft-0.9.0}/DESIGN.md

@@ -29,7 +29,7 @@ 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 (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.
+- **`render`** — produce the clickable artifact. Its reader half is `verify`: an artifact carries the checks it wants run in its own legend, so the tool that writes them ships the command that runs them.
 
 ### 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.
@@ -147,6 +147,10 @@ Self-contained HTML (plus the machine-readable sidecar): **quotes + receipts + e
 | 2026-08-18 | **One rule names a source, and every surface that names one uses it.** A fetched page's `filename` is the temporary file `fetch.filename_for` staged the bytes in — `index.html` for a permanent link, a name on nobody's disk — and the 2026-08-06 row settled what to do about it ("showing both would give a reader two names for one thing and let the fictional one look authoritative") for the artifact alone. The four CLI surfaces that name a document kept the fiction: `ingest`'s line, the gate's document list, its table-of-contents headline, and `ls` — which showed *both*, filename in column two and URL in a fifth field, the exact shape that row rejected. `gate.source_name` is now the single owner, exported the way `gate.unit` is and imported downward by `cli.py`, so a writing agent learns a source's provenance from the surface it already lives on instead of being sent to `ls` by the skill. Display only: the slug, the token and everything a citation resolves through are untouched, which is the 2026-08-05 "provenance, never identity" rule. Two consequences named rather than discovered. `ls` loses a field — a fetched row is four columns, not five — so anything parsing column five stops seeing one; that is the point, since column two was a lie and one true name beats two names of which one is fictional. And in the gate's aligned list a URL *overflows* the name column rather than widening it: the column is sized on filenames alone, so one 80-character address pushes its own row's later columns right instead of pushing every row's past column 100. The cost is a ragged right on fetched rows, accepted because the file rows a mostly-file registry is made of stay byte-identical to what they printed before — pinned by a test, the way the artifact's byte-identity is. `bind`'s unmatched-claim report still names a source by filename: the fix cannot be shared into it without a sideways `bind` → `gate` import, which SPEC § Dependency rule forbids, and duplicating the rule there is the reinvention this row exists to end. |
 | 2026-08-19 | **A slug is assigned by a rule, and the rule is written down.** The Open list carried "slug assignment/collision rules" from the first field trial, and URL sources sharpened it into a live failure: `fetch.filename_for` took the stem from a URL's last path segment, so `https://a.example/reports/2025/index.html` and `https://b.example/docs/index.html` both staged as `index.html` and became `index` and `index-2` — two handles that say which is which to nobody, carried by every token in every document written against them, permanently, since a slug is stable once assigned. The rule now has two clauses and they are stated together for files and URLs. A **file** is named by its filename's stem, kebabed and cut to 32 characters, which is unchanged and was never the problem. A **URL** is named by its last path segment, *except* when that segment names the site's plumbing rather than its page — a directory index or generic handler (`_GENERIC_STEMS`: `index`, `view`, `page`, `show`, and a dozen more), an all-digit id, or no segment at all — in which case the host goes in front of it, minus `www.` and minus the port, so the two pages above become `a-example-index` and `b-example-index`. The common case is deliberately untouched: `https://example.com/reports/q4-2025` is still `q4-2025`, because a rule that made every good name uglier to fix the bad ones would be the wrong trade. `_dedupe`'s `-2` stays, demoted from the normal outcome to the backstop it was meant to be — the host is a *better* stem, not a unique one, and two `index.html` pages on one site still collide. Truncation is trimmed on both cuts now (`slug_for` and `_dedupe`), which is the other half of the Open line: a 32-character cut lands on a hyphen often enough that `q4-report-` was a slug this repo could produce, legal in the grammar and reading like a bug. The compatibility statement, said out loud because nothing else will say it: two registries built on either side of this change disagree about a fetched page's slug, and an artifact's tokens are not portable between them. Existing registries are unaffected, and that is not luck — `_find_document` matches a re-fetch on the URL, never the slug, so re-ingesting a page keeps the slug it already has. `--slug` remains the way to overrule all of this and is still the advice for a fetched page worth citing, because `a-example-index` names a site rather than nothing, which is better and is not good. |
 | 2026-08-20 | **`ingest` says which of its three outcomes happened, and how much text came out.** One line served three different events — a document created, a *new generation* of one whose bytes moved, and a no-op that wrote nothing — so an agent re-ingesting after a fix could not tell whether anything had changed, at exactly the moment it most needed to: a new generation is when citations into the previous snapshot begin resolving to a superseded one and `bind` starts calling them `drifted`. The registry already distinguished all three internally (`_find_document`, `_is_noop`, `_upsert_document`) and threw the answer away, so `ingest` now returns an `Ingested` — a `Document` subclass carrying `outcome`, the shape `SearchResults` established for `search`: Addendum A's pinned `-> Document` still holds, every `.slug` caller and every fake is untouched, and the one consumer that cares reads the extra field. Re-deriving the outcome in the CLI was the alternative and would have meant a second implementation of `_is_noop` living away from the first. The wart is named rather than papered over: a dataclass compares by class, so an `Ingested` never equals the plain `Document` the read side returns for the same row, and the two tests that compared them now compare what persists. The second half is a number: the extracted character count, beside the page count on every line. A scanned PDF with no text layer and a page behind a login both ingest cleanly, exit 0 and print a page count like any success, which is how a shell of a source gets cited — and the writing skill's instruction to notice "thin or empty" gave the agent nothing to notice it with. Under `THIN_SOURCE_CHARS` (200) a note names the likely cause by media type and what to do about it. That threshold is a heuristic, which this repo refuses elsewhere on purpose — the `html` extractor is a parse and not a readability guess, because a heuristic that changes its mind moves anchors. This one is admissible for the reason those are not: it is display only, at exit 0, and no token, anchor, status or byte of the artifact derives from it, so being wrong costs one line of advice and never a citation. `chars` counts sheets too, where `read`'s window unit is rows: this is the extraction's volume, not a window into it. Grouping follows the 2026-08-13 rule — thin sources group by cause, since one missing text layer explains every scan at once and each document's own count is already on its own line, while the failure report still lists by source. |
+| 2026-08-24 | **`backdraft verify` — the recipient's check, and the drift bug it found in the spec.** The artifact's whole promise is that someone holding only the file can check it, and until now the instructions for doing so were prose: `skills/backdraft-artifact/SKILL.md` walked an agent through recomputing hashes by hand, which is a deterministic procedure re-implemented per reading — the way a recipient's audit ends up weaker than the producer's. It is now a command, in `render/cli.py` because that module already holds the format's reader half (`render.sidecar`), taking either the `.backdraft.html` or the `.backdraft.json`. Two tiers, and the output names which ran: the record against itself, which needs nothing but the file, and — only where a `.backdraft/` is discoverable — every token re-resolved against the sources. Discovery is from **cwd**, not from the artifact's own directory as `bind` does it from the document's: an artifact is a file people forward, so the folder it landed in is evidence about the recipient's machine and not about which registry produced it. Exit 2 joins `bind`'s, which was documented as "`bind`'s alone"; the shared meaning is "the run completed and the document is not clean", which is exactly what a Stop hook gates on, so a hook written for one now catches the other — the gate's `show` stays at 1, because a lookup answering "that token names nothing" is not a document failing. Read-only and minting nothing, which is the line between it and `show`: showing is minting, and an audit that made its own subject citable would manufacture the evidence it was sent to inspect. A record faithfully carrying an `unresolved` citation still passes tier one — a kept failure is the record working, so the same bytes exit 0 in an inbox and 2 in the project, answering different questions. Two consolidations came with it rather than a third copy of each: `registry.citation_for` is the token-to-status walk `bind` and `verify` both need and the dependency rule forbids either importing from the other, so it sits beside `current_at` for the same reason, with `not_shown` deliberately left out as a fact about a session the caller holds; and `cli_context.claim_words` is the line-item shape, since two commands reporting on the same claims must not print two layouts. The real find was in the spec. `spec/artifact.md` § Checking an artifact and the legend's `verify_this_record` both said the token's hash must prefix `anchor.snippet_sha256` — false for every `drifted` citation by construction, since the token names `drifted_from` (what the author cited) while `anchor` carries what stands there now, and the two differing *is* what drift means. Implemented as written, `verify` would have called every drifted artifact forged: the one status the format exists to carry honestly. Both statements are corrected, which moves the legend and therefore every artifact's bytes — goldens and the demo regenerated — and is worth the churn, because a known-wrong normative instruction shipped inside every artifact is a worse cost than a diff. |
+| 2026-08-24 | **Math is rendered, not forbidden, and MathML is why that is affordable.** An agent writing a memo about coverage writes `$\mathrm{DSCR} = \frac{NOI}{D}$`, and the renderer handed the reader raw TeX — or worse, corrupted TeX, since `$x_1$ and $x_2$` paired its subscripts into emphasis and `\(a^2\)` lost its delimiters to the backslash-escape pass. The alternative on the table was to forbid math in the writing skill, and it was rejected twice over: this product's documents are exactly the finance and science memos that contain formulas, and a skill instruction cannot be enforced against an agent that did not read it carefully, so the corruption would have arrived anyway. Shipping *unrendered* TeX was rejected too — nobody wants to read `\frac{NOI}{D}`, and a document a reader cannot read is not a lesser artifact but a broken one. The target is MathML via `latex2mathml`, behind a `[math]` extra: it is static markup the browser lays out itself, so rules 1 and 2 of § The HTML artifact hold *by construction* rather than by care — no script, no font file, no request — where inlining KaTeX would have cost roughly a megabyte of fonts as `data:` URIs on every artifact, math or not. The tradeoff, stated because it is the one place the format's fixed-at-render promise is soft: MathML leans on whatever math font the reader's system has, so two readers of one artifact may see different glyph quality. That is a smaller and more honest cost than the alternative, and it is bounded — the markup, the spacing, and every character are identical; only the typeface is not. Dollars were the real hazard and the guard is Pandoc's: a memo saying `$250 per unit` and `$1.2M` twice in a paragraph would pair them into nonsense under a naive rule, so an opening `$` must be followed by a non-space and a closing `$` must be preceded by one and not followed by a digit — a currency amount is preceded by a space and therefore can never close a span. Code is skipped rather than scanned, so a shell snippet's `$PATH` and `$HOME` are safe, and the demo regenerates with zero math elements, which is the check that matters. Math is opt-in per call and **off for evidence**: a receipt's snippet must read as it was extracted, not as this renderer would prefer it. Conversion failure is data, at two different reliabilities — `latex2mathml` raises for some malformed input, which surfaces as a wavy mark at the formula and a note giving the reason, and silently degrades for the rest (`\notacommand{x}` becomes an identifier), which cannot be caught and is recorded here as a known limit rather than papered over. |
+| 2026-08-25 | **The registry export is a specified format, or it is not a format.** `backdraft export` has written `"$format": "backdraft/registry-v1"` since v0 — a version string promising a specification that did not exist — while being the only complete, portable form a registry has, and therefore what a second implementation, a migration or an audit actually reads. The gap stopped being theoretical when URL sources added a conditional `meta` key to every exported document: a change to a format with nothing to change against. So spec/registry.md joins tokens, chunking and artifact as normative prose, and the pin is the spec itself rather than a golden file beside it — tests/test_spec_registry.py parses the spec's key tables, exports a registry built to exercise every branch, and fails in both directions, so an undocumented key and a documented-but-absent one are equally a test failure. Two boundaries were drawn rather than blurred. `bindings[].report` stays spec/artifact.md's, quoted opaquely here, because one format with two specifications is one too many and they would drift. And the export is content, not a backup: page images, sheet styling and the FTS index are deliberately outside it, so an export round-trips every citation and every receipt and does not round-trip a database — stated in the spec as a limit rather than left for a reader to discover by restoring one. |
+| 2026-08-26 | **`search` reports the size of the answer, not the size of the page.** `--limit` defaults to 20 and the count line said `20 results` whether twenty matched or two hundred did, which is the silent cap this repo rejects everywhere else — `read` closes with `[Showing 0-464 of 3115 chars. Continue with: …]` for exactly this reason. Search is the surface an agent leans on hardest, since it is how a claim finds its evidence, and relevance order is not the same as the sentence the writer needed: a reader told it has twenty results picks the best of twenty and never learns the twenty-first existed. So `SearchResults` gains `total` beside `phrase_fallback` — the same shape for the same reason, an out-of-band fact riding on Addendum A's pinned `list[SearchHit]` so every consumer and every fake is untouched — and a capped run renders `2 of 56 results` plus a closing line naming the exact widening command, shell-quoted, because a hint carrying `$` or a space that has to be repaired before it runs is not a hint. The count is a `COUNT(*)` over the *same* joins the fetch runs, shared through `_match_sql` rather than written twice: a count that joined differently would report a total the caller can never reach. It is asked for only when the page came back full, since a page the limit did not fill is already the whole answer — so the common uncapped run still runs one query, and the output it prints is byte-identical to what it printed before, pinned as a test the way the artifact's bytes are. Two things were deliberately not built. No `--offset`: paging a relevance-ordered list is a different design question, and `--limit` already exists for the hint to name. And the total is not carried into anything durable — no token, anchor, receipt or artifact byte moves, because how many other sentences also matched is a fact about a query, not about a citation. |
 
 ## Open
 

{backdraft-0.8.0 → backdraft-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: backdraft
-Version: 0.8.0
+Version: 0.9.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
@@ -18,6 +18,8 @@ Requires-Dist: python-pptx>=1.0
 Requires-Dist: typer>=0.12
 Provides-Extra: entail
 Requires-Dist: anthropic>=0.40; extra == 'entail'
+Provides-Extra: math
+Requires-Dist: latex2mathml>=3.77; extra == 'math'
 Provides-Extra: vlm
 Provides-Extra: xls
 Requires-Dist: python-calamine>=0.3; extra == 'xls'
@@ -128,6 +130,11 @@ $ backdraft search "24850000"
 [Read the page: backdraft read underwriting-model p2]
 ```
 
+Search shows twenty results by default. A run that hit the limit says so —
+`20 of 56 results` — and closes with the command that shows the rest, because
+"20 results" over an answer of 56 is how a reader concludes it has seen
+everything when it has seen a third.
+
 A cell you can already see mints directly:
 
 ```console
@@ -170,6 +177,7 @@ bound 17 claim(s), 18 citation(s) [frontwalk]
   resolved: 17
   unresolved: 1
   overlap: pass 13, skip 4
+    skip 4 — wording overlap does not apply to a single cell
   value-trace: pass 17
   ! unresolved: bd:t12-summary:p4.c1:1a2b — replacement reserve of $250 per unit per year @3629
 wrote .backdraft/records/memo.backdraft.json
@@ -193,6 +201,29 @@ 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 recipient can check it.** `backdraft verify` takes the artifact or its
+sidecar and does the checking that the file is built to make possible: every
+snippet rehashed against the sha256 recorded beside it, every token checked
+against the anchor it names, `summary` recounted from the claims.
+
+```console
+$ backdraft verify memo.backdraft.html
+checked memo.backdraft.html [backdraft/artifact-v1]
+  receipts: 17 of 17 hold
+  record: 17 claim(s), 18 citation(s); the summary recount agrees
+  recorded: resolved 17, unresolved 1
+  sources: no .backdraft/ found from here — not re-checked
+[Re-check against the sources: run this inside the project it was bound in.]
+```
+
+That first tier needs nothing but the file, which is the point — it is the check
+someone who was emailed the artifact can still make. Run it inside the project
+the document was bound in and it also re-resolves every citation against the
+registry, so a source that has changed since shows up as `drifted` rather than
+going unnoticed. Exit 0 when everything it checked passed, 2 when something did
+not, so a hook can gate on it. It opens no session and mints nothing: an audit
+must not make its subject citable.
+
 **Theming.** The artifact ships with a default look and two alternates,
 `press` and `slate`:
 
@@ -320,12 +351,13 @@ 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:
+Three extras:
 
 | Extra | Adds | For |
 |---|---|---|
 | `[entail]` | `anthropic` | `bind --check entail`, the model-judge verifier |
 | `[xls]` | `python-calamine` | legacy `.xls` workbooks, values only, rendered the same shape as xlsx |
+| `[math]` | `latex2mathml` | LaTeX in a document becomes MathML in the artifact; without it, formulas render verbatim and `render` says so |
 
 `backdraft[vlm]` still installs: it is an empty compat alias from when the
 vision deps were an extra.
@@ -346,7 +378,7 @@ Three agent skills ship inside the package and in this repo:
 |---|---|
 | [`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 |
+| [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | checking and 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. How the skills reach your agent
@@ -404,9 +436,10 @@ spans are citable. In a sandboxed session run every command as
 | [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/registry.md](spec/registry.md) | the registry export format `backdraft export` writes |
 | [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
+The four files under `spec/` are the portable specification: another
 implementation reads them and nothing else.
 
 ## Status

{backdraft-0.8.0 → backdraft-0.9.0}/README.md

@@ -103,6 +103,11 @@ $ backdraft search "24850000"
 [Read the page: backdraft read underwriting-model p2]
 ```
 
+Search shows twenty results by default. A run that hit the limit says so —
+`20 of 56 results` — and closes with the command that shows the rest, because
+"20 results" over an answer of 56 is how a reader concludes it has seen
+everything when it has seen a third.
+
 A cell you can already see mints directly:
 
 ```console
@@ -145,6 +150,7 @@ bound 17 claim(s), 18 citation(s) [frontwalk]
   resolved: 17
   unresolved: 1
   overlap: pass 13, skip 4
+    skip 4 — wording overlap does not apply to a single cell
   value-trace: pass 17
   ! unresolved: bd:t12-summary:p4.c1:1a2b — replacement reserve of $250 per unit per year @3629
 wrote .backdraft/records/memo.backdraft.json
@@ -168,6 +174,29 @@ 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 recipient can check it.** `backdraft verify` takes the artifact or its
+sidecar and does the checking that the file is built to make possible: every
+snippet rehashed against the sha256 recorded beside it, every token checked
+against the anchor it names, `summary` recounted from the claims.
+
+```console
+$ backdraft verify memo.backdraft.html
+checked memo.backdraft.html [backdraft/artifact-v1]
+  receipts: 17 of 17 hold
+  record: 17 claim(s), 18 citation(s); the summary recount agrees
+  recorded: resolved 17, unresolved 1
+  sources: no .backdraft/ found from here — not re-checked
+[Re-check against the sources: run this inside the project it was bound in.]
+```
+
+That first tier needs nothing but the file, which is the point — it is the check
+someone who was emailed the artifact can still make. Run it inside the project
+the document was bound in and it also re-resolves every citation against the
+registry, so a source that has changed since shows up as `drifted` rather than
+going unnoticed. Exit 0 when everything it checked passed, 2 when something did
+not, so a hook can gate on it. It opens no session and mints nothing: an audit
+must not make its subject citable.
+
 **Theming.** The artifact ships with a default look and two alternates,
 `press` and `slate`:
 
@@ -295,12 +324,13 @@ 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:
+Three extras:
 
 | Extra | Adds | For |
 |---|---|---|
 | `[entail]` | `anthropic` | `bind --check entail`, the model-judge verifier |
 | `[xls]` | `python-calamine` | legacy `.xls` workbooks, values only, rendered the same shape as xlsx |
+| `[math]` | `latex2mathml` | LaTeX in a document becomes MathML in the artifact; without it, formulas render verbatim and `render` says so |
 
 `backdraft[vlm]` still installs: it is an empty compat alias from when the
 vision deps were an extra.
@@ -321,7 +351,7 @@ Three agent skills ship inside the package and in this repo:
 |---|---|
 | [`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 |
+| [`backdraft-artifact`](skills/backdraft-artifact/SKILL.md) | checking and 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. How the skills reach your agent
@@ -379,9 +409,10 @@ spans are citable. In a sandboxed session run every command as
 | [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/registry.md](spec/registry.md) | the registry export format `backdraft export` writes |
 | [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
+The four files under `spec/` are the portable specification: another
 implementation reads them and nothing else.
 
 ## Status

backdraft-0.9.0/ROADMAP.md

@@ -0,0 +1,393 @@
+# 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. `session show` says what the ledger holds
+
+**Intent.** The ledger is the mechanism the design rests on — the set of citable
+tokens is exactly the set the gate emitted — and nothing reads it back.
+`backdraft session show` prints `session default  (from default)` and stops, so
+an agent cannot answer "have I read enough to write this yet?" except by binding
+and reading the `not_shown` count, which means finding out after the draft
+exists. Worse, the default session is documented as stable across invocations
+*so reads accumulate*, which means an agent that never exported
+`BACKDRAFT_SESSION` has its `not_shown` judged against everything ever read in
+that registry by any previous run on any document — a real weakening of the
+system's strongest check, currently invisible at every surface. `skills/
+backdraft/SKILL.md` tells the agent to start a named session and calls it
+optional; nothing shows it what optional costs.
+
+**Shape.** `gate/cli.py`'s `session show` and `gate/reader.py` (the ledger is
+the gate's, and `session start` already lives there). Report what the session
+holds: how many anchors, across how many documents, and per document a slug and
+a count — read off the `shown` rows the registry already keeps, which may need
+one accessor on `Registry` beside `was_shown` (SPEC Addendum A, so state it
+there). When the session is the default one, say plainly that it accumulates
+across runs and that a named session is what makes `not_shown` mean "this
+draft's author saw it" — the same voice the `--config` and poppler notes use, a
+note at exit 0 and never a failure. An empty session says so and names
+`backdraft read` rather than printing a bare zero.
+
+**Acceptance.** After reading two pages of one document and searching another,
+`backdraft session show` names both documents with their counts and a total; on
+a fresh registry it says the session is empty and what to run. Running under
+`BACKDRAFT_SESSION=s-x` shows `s-x` and no accumulation note; running with
+nothing set shows the default and the note. `README.md`, `site/docs.html`,
+`site/llms.txt` and `skills/backdraft/SKILL.md` point at it as the way to check
+coverage before binding, and the skill's "optional" for `session start` becomes
+a stated tradeoff.
+
+**Size.** Two days.
+
+### 2. An unreadable source says what to do, not what errno it was
+
+**Intent.** `ingest` now finishes its list and names each failure (2026-08-13),
+which turned the reason string into something a calling agent actually reads —
+and the reason is Python. A directory says `cannot read adir: [Errno 21] Is a
+directory: 'adir'`; a locked file says `[Errno 13] Permission denied`; a missing
+one says `[Errno 2] No such file or directory`. Each names the source three
+times, leaks an errno an agent must not have to know, and — the real cost —
+says nothing about the fix, though the fix differs completely between the three
+and is obvious in each case. A directory means "name the files inside it, or
+glob"; the repo's own rule is that an error says what went wrong *and* what to
+do next, and this is the boundary where an unattended agent meets it most.
+
+**Shape.** Wherever the read failure is raised on the ingest path — `cli.py`'s
+`_staged`, `registry/store.py`'s ingest read, and `fetch.py` for the URL half —
+turn the `OSError` into a `BackdraftError` whose message is written for the
+caller: what the source is, why it could not be read, what to do. Map the causes
+worth distinguishing (missing, a directory, unreadable, empty, and the fetch
+side's own) and let anything unmapped keep the underlying text rather than
+guessing — an unknown cause reported plainly beats a wrong suggestion. Say the
+source once: the `!` line already leads with it, so the reason should not repeat
+it. This is *not* the queued "Ingest says what it did and what it got" item, which is about what a successful ingest says
+(no-op, new generation, character count); this is the failure half, and the two
+should not be merged.
+
+**Acceptance.** `backdraft ingest <a-directory>` names the directory once and
+says to pass the files inside it or a glob; a missing file, an unreadable file
+and an empty file each get their own reason and their own next step; none of the
+four prints `[Errno`. A URL that 404s keeps saying so. The count line and the
+closing re-run line are unchanged, and the clean-run stdout byte-identity test
+from 2026-08-13 still passes. `site/llms.txt` says the failure reasons are
+actionable so an agent surfaces them to the user rather than paraphrasing.
+
+**Size.** One day.
+
+### 3. A registry can forget a source
+
+**Intent.** Ingest is one-way. An agent working unattended over a folder — which
+is now the normal case, since `ingest` finishes its list — will ingest something
+it should not have: a scratch copy, a duplicate under two names, a file the user
+did not mean to include. Nothing removes it. It stays in `backdraft read`'s list
+forever, its anchors stay in `search` competing with the real source, and an
+agent picking evidence can cite the wrong copy without anything looking wrong.
+The only recovery is deleting `.backdraft/` and starting over, which throws away
+every other document and the whole ledger.
+
+**Shape.** Withdraw, do not delete — a new `backdraft forget <slug>` in `cli.py`
+beside `ingest`, and the storage half in `registry/store.py`. A withdrawn
+document disappears from `documents()`, from the gate's list and table of
+contents, and from `search`; its anchors keep resolving, because a token already
+written into somebody's draft or artifact must not silently become `unresolved`
+— that is the failure mode this whole system exists to prevent, and the
+2026-08-05 "provenance, never identity" row governs. So `Registry.resolve` still
+finds it and `show` and `bind` report it, with the closed status set gaining
+nothing: reuse `unresolved` and let the *reason* say withdrawn, since adding a
+status is an artifact-format change and this does not need one. Storage is a
+flag on `documents`, not a DELETE, for the same reason. Require confirmation or
+an explicit flag, since this is the one command that takes something away.
+`spec/registry.md` has landed and pins the export against what it emits, so a
+withdrawal flag reaching `documents[]` is a spec change: name the key there,
+say what a reader must conclude from it, or keep it out of the export.
+
+**Acceptance.** Ingest two documents, `forget` one: `read`, `ls` and `search`
+show only the other; a token minted from the forgotten one still resolves
+through `backdraft show`, saying it was withdrawn and when; `bind` on a document
+citing it reports it and does not crash. `forget` on an unknown slug exits 1
+naming the known ones. Re-ingesting the same file after forgetting it brings it
+back as a new generation of the same document rather than a second slug — pin
+that, it is the case that decides whether the flag was the right storage.
+`README.md`, `site/docs.html`, `site/llms.txt` and `SPEC.md`'s command list gain
+it, and it earns a DESIGN.md row: withdraw-not-delete, with the tradeoff that a
+registry never actually shrinks.
+
+**Size.** Three days.
+
+### 4. Bind's markdown names a fetched source by a file nobody has
+
+**Intent.** The 2026-08-18 row made `gate.source_name` the one owner of what a
+source is called and named the one surface it could not reach — bind, because
+`bind` → `gate` is a sideways import SPEC forbids. The exception is larger than
+that row said. `binder.py`'s `_doc_name` returns `document.filename`, and it
+feeds both the generated `## References` section of `bind --bound` and the
+proposals in the unmatched-claims section, so the markdown projection — the
+form that travels into a pull request or an email, where the HTML artifact
+cannot follow — calls the demo's Wikipedia article `index.html`. Bind the demo
+with `--mode backfill --bound` and `memo.bound.md` says
+`**[2]** index.html — p1.c11 — resolved` for a source that `render --to
+footnotes` names `**franklin-county** · <https://en.wikipedia.org/…>` and the
+artifact names `Franklin County`. Two of backdraft's own output formats
+disagree about what a source is, and the one that disagrees is the one a reader
+gets without a browser.
+
+**Shape.** Answer the dependency objection rather than working around it.
+`source_name` is a pure function of a `Document`, and `Document` lives in
+`kernel/model.py`, which `gate` and `bind` both import *downward* from — so the
+kernel is the owner the rule was always looking for, and it stays stdlib-pure
+there. Decide and write down whether `gate.source_name` becomes a redirect or
+whether callers move to the kernel path, remembering that kernel API in this
+repo is module paths rather than flat re-exports, and that `cli.py` imports
+`gate.source_name` today and SPEC § Gate names it. Leave the render side alone:
+`render/html/text.source_title` and `render/footnotes._origin` read a `url` off
+the *artifact's* `docs` dict, a different shape from a `Document`, and they are
+already correct — say so in the row rather than letting the next reader think
+they were missed.
+
+**Acceptance.** Add an uncited claim to a copy of `demo/memo.md`, run `bind
+memo.md --mode backfill --bound`, and `memo.bound.md` contains no `index.html`
+and names the URL in both its References entries and its unmatched proposals.
+A References entry for a *file* source is byte-identical to today's — pin it,
+the way the file rows of the gate's list are pinned. `render --to footnotes` is
+unchanged. SPEC's dependency rule and § Gate are updated, and the 2026-08-18
+row gains its correction: the exception it accepted is now closed and the row
+should say how.
+
+**Size.** Two days.
+
+### 5. A web page has a name, and `read` shows it the navigation menu instead
+
+**Intent.** `backdraft read franklin-county` — the demo's own web source —
+prints `p1  Franklin County, Ohio - Wikipedia  Jump to content Main menu Main
+menu move to sidebar hide Navigation - Main page - Contents - Current events -
+Random art...`. The table-of-contents line is the one surface that tells an
+agent what is on a page before it spends context reading it, and for every web
+source it is site chrome. The page's real name is sitting in the extracted text
+and in the markup's `<title>`, unused: a fetched page ingested without `--slug`
+also titles itself `En Wikipedia Org Index` in the artifact's source list,
+because `render/html/text.source_title` falls back to the slug and title-cases
+it. Two surfaces need one fact nothing captures. Separately, an HTML source is
+a single page, so its table of contents is that one line and does no
+navigating at all — for a 34,000-character article the citable unit is the
+chunk and nothing lists the chunks.
+
+**Shape.** Capture the fact once, at extraction: `extract/html.py` already
+parses the markup, so the document's `<title>` becomes page or document meta
+there, and everything downstream reads it instead of guessing. Then
+`gate/reader.py`'s TOC preview (`TOC_PREVIEW_CHARS`, `_preview`) prefers it,
+and `render/html/text.source_title` prefers it over the slug fallback for a
+document that has one. For the single-page case, `render_toc` lists the page's
+chunks with their opening words, so a one-page source's table of contents is
+one. **This is display only and must stay that way**: no chunk boundary moves,
+no anchor moves, no token changes, and the slug is not derived from the title —
+that is the admissibility argument the 2026-08-20 thin-source note made, and
+this row must make it again, because the neighbouring rule ("no boilerplate
+stripping: a heuristic that changes its mind moves anchors") is about
+extraction and is not being touched. A page with no `<title>`, and every
+non-HTML source, keeps exactly what it prints today.
+
+**Acceptance.** In `demo/`, `backdraft read franklin-county` names the county
+rather than "Jump to content", and lists the page's chunks. `backdraft read
+t12-summary` and `backdraft read underwriting-model` are byte-identical to
+today's — pin both. `backdraft bind memo.md --session s-bridgeview --check
+value-trace,overlap` still reports 17 resolved and the same one unresolved,
+with the same tokens: mint them before and after and diff. An HTML fixture with
+no `<title>` falls back to what it prints now. `demo/walkthrough.md`'s read
+blocks and `README.md`'s show the real output. DESIGN row.
+
+**Size.** Three days.
+
+### 6. A page read has no budget and no closing line
+
+**Intent.** `backdraft read franklin-county p1` prints 36,442 characters and
+stops, with nothing to say how much that was or whether it was all of it — it
+ends mid-navigation on `49 languages Add topic`, which reads exactly like a
+truncation and is not one. `--limit` defaults to "all of them", so the
+continuation hint this repo is proud of — `[Showing 0-464 of 3115 chars.
+Continue with: …]` — only ever appears to a caller who already knew to pass
+`--limit`. The gate is the one surface an agent is *required* to use, which
+makes the default the case that matters: one `read` can spend a large fraction
+of a context window with no warning, and the agent cannot tell a complete page
+from a cut one. `search` caps at 20 by default; `read` caps at nothing. This is
+the same silent-cap family as the queued `search` item, from the other end — an
+uncapped read that looks capped, rather than a capped search that looks
+complete.
+
+**Shape.** `gate/reader.py`'s page rendering and `gate/cli.py`'s `--limit`. The
+decision to make and write down is a default budget versus staying unbounded
+and always closing with the size and the continuation line; prefer whichever
+keeps a small page byte-identical, since most pages are small and their output
+is a contract. Whatever lands, a read that shows part of a page must close by
+naming the exact command that continues it, as the existing hint does. One
+constraint to state and test rather than discover: the window slices by
+characters and a chunk token stands above its chunk, so a cut must not leave a
+token over a chunk the reader only half received — either the window respects
+chunk boundaries or the closing line says the last chunk is partial. Do not add
+an offset story to `search` here; that is the queued item's ground.
+
+**Acceptance.** `backdraft read t12-summary p1` in `demo/` is byte-identical to
+what it prints today — pin it. `backdraft read franklin-county p1` closes by
+saying how much of the page it showed and how to see the rest, and running the
+command it names continues where it stopped. No read output ever shows a token
+above a chunk it did not finish. `demo/walkthrough.md`, `README.md`,
+`site/llms.txt` and `skills/backdraft/SKILL.md` show the real output and tell
+the agent to continue rather than assume it saw the page. DESIGN row.
+
+**Size.** Two days.
+
+### 7. The thin-source signal exists only in the ingest that printed it
+
+**Intent.** 2026-08-20 gave `ingest` a character count and a `note: little text
+extracted` naming the likely cause — the signal that a source is a shell and
+must not be cited. Both are printed once and then gone: nothing stores the
+count, and `ls`, the gate's document list and a document's table of contents
+say nothing about it. The agent that writes is usually not the process that
+ingested — the skill says to ingest everything up front and then read, and a
+registry travels with the project folder — so the one signal that matters is
+the one an agent is least likely to be present for. Off `backdraft read`'s
+list, a 34,000-character article and a 60-character login wall are the same
+row.
+
+**Shape.** The count is derivable from the current extraction
+(`sum(len(page.text))`), so this is a reporting change rather than a storage
+one unless measurement says otherwise. One owner, shared between `cli.py`'s
+ingest line and `gate/reader.py`'s list and headline, the way `unit` and
+`source_name` already are — the point of this item is that three surfaces give
+one answer, so a second implementation of the count would defeat it. Display
+only, as the ingest note is: no token, anchor or status derives from it. Hold
+the byte-identity rule the source-naming work established — a registry of
+ordinary sources must not gain a column for this, so mark only the sources that
+are thin rather than annotating every row.
+
+**Acceptance.** Ingest a login-wall HTML file beside a real source: `backdraft
+read` and `backdraft ls` mark the thin one and say nothing new about the other,
+and `backdraft read <thin-slug>` says it in the headline too. A registry with
+no thin source prints what it prints today, byte for byte — pinned, including
+`demo/`'s three sources. `THIN_SOURCE_CHARS` is read from one place.
+`skills/backdraft/SKILL.md` and `site/llms.txt` tell the agent that the
+document list is where it learns this, not only the ingest it may not have run.
+
+**Size.** Two days.
+
+### 8. What a URL will be called, before the answer is permanent
+
+**Intent.** Three docs now tell an agent to pass `--slug` when it ingests a URL,
+because a slug is permanent once tokens carry it and the default may name a
+site rather than a page. None of them lets the agent find out what the default
+would be. `fetch.filename_for` settles the answer from the address alone,
+before any bytes exist — that is the 2026-08-19 row's own words — so the
+question is cheap and answerable, and today the only way to ask it is to ingest
+and live with the result. An agent that guesses wrong has written a name into
+every token of the document, and the fix is re-ingesting under a new slug and
+rewriting the draft.
+
+**Shape.** Small and read-only. The natural home is beside the thing it
+predicts: a flag on `ingest` that resolves each source to the slug and media
+type it would take and prints them without fetching, writing or minting
+anything, or a sibling command if a flag on a writing verb reads badly — pick
+one and say why in the DESIGN row, since "a verb that does not do its verb" is
+the objection to answer. For a URL the answer comes from `fetch.filename_for`
+plus `registry.slug_for` and needs no network; the media type is the honest
+gap, because only the served content type settles it, and the output must say
+so rather than guessing. For a file, both are already knowable. Existing
+collisions matter: a slug already taken must be reported as taken, since that is
+what turns a predicted `index` into a real `index-2`.
+
+**Acceptance.** Against `demo/`, asking about
+`https://en.wikipedia.org/w/index.php?title=Franklin_County,_Ohio&oldid=1367935775`
+prints `en-wikipedia-org-index` and does not create a document, open a socket,
+or touch the ledger — check the registry's document count and `ls` before and
+after. Asking about a path prints the slug the file would take. Asking about a
+source whose slug is already in the registry says so. `README.md`,
+`site/docs.html`, `site/llms.txt` and `skills/backdraft/SKILL.md` name it where
+they currently say "pass `--slug`", so the advice comes with the way to check
+it.
+
+**Size.** One day.
+
+## 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 shipped
+  2026-08-05; `document_meta` is where an email's provenance would land.
+- **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.