Rendered from docs/interfaces/headwater-capture.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

headwater capture

Synopsis

headwater capture [--format text|json | --json] [--root <path>]

The verb takes no operand. It reads the capture-cost store and reports its population and reach.

Description

headwater capture reads one JSON object per line from .headwater/capture-cost.jsonl. Each valid reading records the lock, date, entry surface, kind, document, identifier and four assisted-count pairs.

The text report states the store, reading dates and unreadable lines. It then states the aggregate assisted fraction, groups by kind and surface, and document reach. A store with no readings reports an empty population rather than a measured zero.

The JSON report carries the same counts, lock list, date range, groups, classified count and documents whose readings resolve to nothing. It does not add a reading to the store. A reading under an old lock remains in the store and the report names every lock it spans.

Preconditions

The repository must carry a readable .headwater/taxonomy.lock, consumer declaration and corpus. The store may be absent, which represents a corpus with no readings.

Unreadable store lines are reported with their line numbers. An unreadable store file, rather than an unreadable line, is a refusal.

Options

Option	What it does
--format text\|json	Select the report. text writes the person-readable report and is the default. json writes the machine-readable count report.
--json	The same target as --format json.
--root <path>	Select the repository and store to read.
--no-color	Force plain text on both streams: bold and dim weight plus glyphs, no escape sequence. The default already senses whether each stream is a terminal, and renders color only there.
--no-banner	Suppress the masthead: the line naming this binary and its version, that the root help screen alone prints. It is accepted here and does nothing, since only the root screen prints one.

--format accepts only text and json. Stating --json beside --format is refused. --wide is refused because the verb prints no help layout. Global --help, --version and --no-banner are answered before the verb runs.

Exit status

0 means that the store and corpus were read and the report was printed. This includes unreadable lines that the store loader could identify.

1 means that the format, command line, store file or repository was refused. The verb does not use the report as a gate.

Every reason for exit 1 is a refusal, so standard output is empty on all of them. Each is decided before anything is written, and the account is one English sentence on standard error. That holds for --json and for --format json alike, which is what HW-DR-0043 rules.

1, and never 101, when standard output or standard error cannot be written, and one sentence on standard error names a failed standard output.

Environment

No environment variable reaches this verb. The format and repository come from the command line, and the store and corpus come from the tree.

Files

Path	How this verb treats it
.headwater/capture-cost.jsonl	Read one line per valid or unreadable store entry.
.headwater/taxonomy.lock	Read through the corpus loader.
.headwater/taxonomy.yml	Read through the consumer loader.
The corpus	Read to classify documents and resolve identifiers.
.headwater/imports/	Read where .headwater/taxonomy.yml declares an import, for the anchors that an imported snapshot supplies. An imports entry that does not read stops the verb with exit 1, and so does an at path outside the repository root.
the path each harvests.<name>.at names	Read where .headwater/taxonomy.yml declares a pinned corpus export, for the anchors that export supplies. A harvests entry that does not read stops the verb with exit 1, and so does an at path outside the repository root. A pin with no digest binds no anchor. An absent file binds no anchor, and neither does a file that fails the pinned digest or is not an export.

The verb writes no file. headwater new appends readings to the store before this verb reads them.

See also

headwater new appends a reading when it scaffolds a document.

headwater mcp records protocol scaffolding as a separate capture surface.

Spec 3 defines the assisted fraction and the store boundary.