Concepts

The words a newcomer meets in the first ten minutes, each defined once here rather than re-explained in every guide that uses it.

run — one experiment run, as discovered on disk: a project, a name, the source_path it was read from, its metrics, and (once linked) which corpus it used. RunRecord in src/attestation/ledger.py; see the ledger guide.

family — the group a run's siblings fall into, so a sweep can be compared as one thing. family_of() strips a shared filename prefix, hyphen-joined regardless of separator (dit_small_rope_crossattn and dit_small_rope_melmask both group under dit-small-rope); a bare hyperparameter stem with nothing to strip (lr_0.001, lr_0.01) falls back to the recognised token itself (lr) as the family. See the ledger guide.

arm — one run within a family's sweep — one point of comparison runs.compare ranks against the others, with its own source_path, sample size, and caveats. See the ledger guide.

spec — a design document under docs/superpowers/specs/, written before the code it describes, recording why a subsystem exists the way it does. CLAUDE.md's "Docs Index" names which spec goes with which code area; docs/site/specs.md (generated by scripts/render_spec_index.py) lists every one.

claim — an HTML comment beside a piece of prose, asserting that a number matches a specific run's metric: . claims.parse_file() finds them; check_claim() scores each against the ledger. See the claims and citations guide.

verdict — what check_claim() returns for one claim, one of five kinds (VerdictKind in src/attestation/claims.py): supported (a run agrees), contradicted (a run disagrees), unsupported (no run matches), ambiguous (several runs match and which is meant is undecidable), and stale (the value matches but the artifact changed after as_of). A sixth, uncited, is a citation lint rather than a claim-checking verdict. See the claims and citations guide.

corpus — the dataset a run trained or evaluated against, detected from driver-script syntax (AST) rather than from the model's own claims about itself — corpus.detect_in_source(). runs.corpus_id links a run to one; compare() refuses to rank arms that cross corpora rather than treating a different task as a loss. When detection finds nothing or finds the wrong thing, a corpus can be declared instead in corpora.toml, read by corpus.load_manifest(). See src/attestation/corpus.py and the ledger guide.

persona — a reader identity the feed ranks for: a name and an interests profile text, plus whatever click history it has accumulated. "Persona" is the word used in prose; in code and in the schema the same row is a user — the users table, the user_id foreign key — one row, two names for it depending on which side of the guide you're reading. Personas auto-create on read so an agent's first plausible name becomes a real (if initially empty) profile rather than a refusal; attest bootstrap-persona seeds the three demo personas (researcher/bench-chemist/ml-engineer) with pseudo-clicks. See the feed guide.

provenance (click provenance) — the recorded source of one click, which decides whether it may train the ranker: ui, agent, implicit (inferred from an explanation request), simulated (a model reacting to the text as the persona), or bootstrap (synthetic seeding, excluded from evaluation as tautological). See the feed guide.

surface — a restricted view of the MCP tool set for one kind of agent session: feed, provenance, knowledge, or symbolic, selected with ATTEST_TOOLS and defined in AGENT_SURFACES (src/attestation/mcp/__init__.py). Unset serves all 47 tools; a typo raises rather than silently serving everything. See the agents guide.

golden path — a directory under examples/<name>/ that a newcomer can run from a clean clone, with everything it needs already on disk, and whose README the test suite runs verbatim rather than trusting as prose. See docs/superpowers/specs/2026-08-28-golden-paths-design.md and the golden paths catalogue.

convention (tracker convention) — a directory layout a third-party experiment tracker (W&B, MLflow, Sacred, DVC, Hydra) already writes, read by the ledger as a convention rather than requiring the tracker's own package as a dependency. "A convention helps every project; a named adapter helps exactly one." See docs/superpowers/specs/2026-08-22-tracker-adapters-design.md and the ledger guide.