---
name: docs-point-of-use-destruction
description: "Documentation exists for point of use, not archival. Use before any dedupe/compact/verify-docs job, and whenever a census or \"only copy\" argument is being used to KEEP documentation: apply the purpose test and destroy obsolete measurements. Supersedes the preservation conclusions of vault-one-fact-one-owner-dedupe §3/§12."
---

# Documentation exists for point of use

**Supersedes** `vault-one-fact-one-owner-dedupe` §3 ("port before cut") and §12
("expect docs flat") wherever those conclude a page must be *kept*. Sole custody of a
useless fact is still useless.

## The test, before you write and again before you keep

- Would the reader, doing a real task tomorrow, **act differently** because of this
  line? No → delete it.
- Is it a measured rate (t/s, tok/s, ms, MiB-of-pool, acceptance %, a bench ladder) for
  a model / runtime / layout that is **not running now and not being compared now**?
  Destroy it. Not "file it in an Eras row", not "preserve it for history". AI moves
  faster than the vault: the number is wrong before anyone reads it, and a wrong number
  in a runbook gets believed.
- Keep the **law** the measurement taught; drop the measurement. Qualitative causal
  stories survive; numbers do not.
- What survives: live config and its exact numbers, procedures, failure signatures,
  security posture, interface contracts, rollback pointers.
- **Losing information is an acceptable, usually correct outcome.** Frank said so
  explicitly on 2026-10-19 after rejecting a PR that had preserved 53 ledgers.

## Traps that lead agents to preserve junk

- **A census cannot decide what to keep.** `port-census.py`-style tools answer "where
  does this fact live", never "does anyone need it". "14–63 sole-record lines per page"
  was read as *irreplaceable* when the fact was *obsolete*. Ask usefulness, not custody.
- **A census that includes the file under test proves the page is held by itself.**
  Exclude it, print the corpus size, assert absence; treat `0 unheld` on a long page as
  a tool bug until proven otherwise.
- **"One fact, one owner" is a placement rule, not a preservation rule.** It says where
  a surviving fact lives; it never says the fact must survive.
- **A change diary (`log.md`) is the largest archive in most vaults** (this one: 2,380
  lines, ~8 % of the vault). Git holds the chronology; a causal law belongs on the page
  that owns the thing it governs. Retire the diary.

## Execution that worked (2026-10-19, −13.7k lines)

1. Write the kill list as a reviewed artifact, one path per line, grouped by *why it is
   dead* — that list becomes the PR's argument and the trash manifest.
2. Destroy whole pages first (`scripts/destroy-vault.py <list>`): move to
   `.AGENTTRASH/<date>-destruction/`, then delete every reference from survivors, whole
   line included when the dead link was its only content. Do not compare link targets
   with `pathlib.Path.stem` — it strips real suffixes (`sd.cpp`).
3. Then strip numbers from what remains (`scripts/axe-measurements.py`): delete ledger
   sections (noun-LEDS the heading, nothing instructional after it), blank any table cell
   reporting a rate, fold Eras older than the current one into a single row pointing at
   git. Never touch a shape number or a Laws/Wire/Rollback section.
4. Sweep indices (generator must exclude the trash dir, drop rows whose page cell became
   empty), re-lint, re-check links.
5. Rewrite the governing policy in the same PR, or the next agent re-grows the vault:
   project `AGENTS.md` *Documentation Policy* + the global agent settings.

## Report honestly, per area

docs / scripts / operator-doc separately, measured against the merge-base. The tools are
a cost that must be named, not hidden inside a headline "net" number — that is what got
the previous pass rejected.

## Verify the repair tools themselves

One repair pass matched "line ends with a comma" and deleted the trailing comma from 660
wrapped prose lines. Restore by matching lines that are byte-identical to `HEAD` except
for trailing punctuation (`restore-punctuation.py`), keep the destructive rule out of the
tool, and record the incident in its docstring.