Glossary

Who this is for — readers hitting a term in this book that carries more weight here than it does elsewhere.

Read this if — a word looked oddly specific.
Skip this if — you are reading linearly; come back when something snags.

Takeaways

Most terms here name a file or a command, not an abstraction — that is deliberate.

Where a term has a common industry meaning, the entry says how this book narrows it.

If a word is load-bearing in an argument, it is defined here; if it is not here, it is being used ordinarily.

The working vocabulary of a local-first, agent-assisted fleet.

The set of small, finished applications one developer keeps alive at the same time. A fleet is defined by maintenance, not by authorship: code you wrote and no longer verify has left the fleet. Avoid: portfolio, suite.

Harness

The automated machinery that decides whether a change is acceptable — tests, golden corpora, canaries, formatters, and the target that runs them. The harness is what an agent is measured against, and the reason its output can be trusted without line-by-line review. In this repository the harness is make preflight and everything it depends on. Avoid: CI, pipeline (those are where a harness runs, not what it is).

Preflight Gate

The single command that runs the whole harness and answers green or red (make preflight: canary, unit and golden tests, formatting). Run before ending a turn, writing a handover, or committing. Avoid: build step.

Canary

A real external mechanism, exercised for real, cheaply, before or alongside the thing that depends on it. That is the invariant; the packaging varies, and this library uses the word in three related senses:

The canonical form — a minimal, standalone script that verifies one external mechanism (mdbook, chromium, a socket, a sandbox) before any feature is built on it. No assertions framework, outside the main suite, never deleted. See Canary-First Development.
The gate — make canary, the preflight layer that runs those scripts. Sense 1 is the artefact; sense 2 is the target that invokes it.
A canary test — a case inside the unit suite that shells out to the real binary rather than a fake, when the mechanism is too small to deserve its own script. It inherits the role but not the isolation, and with it a failure mode the standalone form does not have: a test can skip, and a skipped check reports the same green as a passing one. See The Canary That Skipped Itself.

Sense 3 is a compromise, not a synonym. If a mechanism is worth probing at all and the probe is not trivially cheap, prefer sense 1. Avoid: test, probe (unqualified).

Reel

A scripted terminal session (a .reel file driven by the Wayreel recorder) that launches a TUI in a virtual display, injects keystrokes, and captures the result for visual or PTY verification. A reel is to a terminal UI what a golden file is to a renderer. Avoid: recording, macro.

Golden File

A verified, checked-in reference output — PNG, ANSI dump, or HTML — that a test compares against. Trustworthy only in proportion to the discipline behind its last regeneration. Avoid: snapshot, fixture.

Golden Change

A deliberate update to golden files, performed under the seven-step discipline in The Golden-Change Playbook: predict the diff set first, then regenerate, then verify that exactly the predicted files changed. A golden change that was not predicted is a bug being ratified. Avoid: snapshot update.

Handover

The file an agent writes before a context compaction or the end of a session: current state, files touched, open warnings, next steps, blockers. It lives in issues/ and is the repository’s substitute for a memory the model does not have. See Agentic Dev Patterns. Avoid: summary, notes.

Spec-Driven

The practice of keeping configuration — labels, layouts, key bindings, colors, fonts — in declarative files under spec/, embedded at compile time, with every derivative format generated rather than hand-maintained. Code reads the spec; the spec never mirrors the code. Avoid: config-driven, data-driven.

Stop-Words Gate

The build-time check that scans every book’s Markdown for forbidden terms listed in spec/config.yaml and aborts the build with file and line number on a match. It is how the books stay accurate about which models and tools were actually used. Avoid: linter, filter.

Teardown Contract

The strict, ordered sequence an inline TUI must execute on every exit path — mouse off, drain input, restore termios, erase only its own rows, park the cursor. Not a cleanup routine but a contract, because partial compliance corrupts the user’s terminal. See TUI Restoration & Safe Teardown. Avoid: cleanup, shutdown.

Inline TUI

A terminal user interface that renders inside the normal scrollback buffer instead of switching to the alternate screen — which is what makes the teardown contract necessary in the first place. Avoid: full-screen TUI.

House Rules

The per-language subset this project writes in (Go, Zig, Bash, Make), chosen so a cold reader can establish correctness locally. Argued in How to Read the House Rules. Avoid: style guide, lint config.

Sentinel (⚙️)

The Unicode gear used as a dependency in Makefile targets to make them phony without maintaining a .PHONY list, and as the marker the self-documenting help target scrapes. Avoid: marker, flag.

local-first

Development patterns and tools that run entirely on the developer’s workstation, with no dependency on cloud dashboards or online-only services. Its stronger form in this book: if it is not in the repository, it does not exist. Avoid: offline mode, self-hosted.

ADR (Architectural Decision Record)

A short Markdown file capturing one architectural decision, its context, and its rationale, numbered sequentially (0003-spec-baseline-theme-cascade.md). The artefact produced when a question is settled by judgement rather than by a check. Avoid: design doc, RFC.

Agentic Software Development: The Ubunatic Way