Documentation rots because nothing holds it accountable. Headwater types your corpus, checks it as a graph, and accounts for every file it saw. Nothing else can answer "is this corpus still true?"
Recorded on 2026-09-30 with engine 0.5.0. This is a frozen recording, so the output of a later engine can differ from it. .github/assets/headwater-demo.tape records it again.
Start here: Your first governed corpus. Sixteen steps from an empty directory to a passing check, and it teaches the model rather than the commands. Every step states what you should now see, and sh .claude/tutorial/fixtures.sh runs the page against the engine in CI so that no output block on it can go stale quietly. That page, and the rest of the docs/ tree, is rendered at https://headwater.tools/. The specification itself is indexed at docs/spec/README.md, which headwater generate writes from the documents themselves in the reading order this corpus derives from its own relations.
Download the binary. You need no Rust toolchain. Every engine release carries a static Linux x86_64 archive and a macOS arm64 archive. The block below installs v0.6.0 on Linux into ~/.local/bin. On macOS on Apple silicon, put aarch64-apple-darwin where the block says x86_64-unknown-linux-musl.
mkdir -p ~/.local/bin
curl -fsSLO https://github.com/headwater-ai/headwater/releases/download/v0.6.0/headwater-v0.6.0-x86_64-unknown-linux-musl.tar.gz
tar -xzf headwater-v0.6.0-x86_64-unknown-linux-musl.tar.gz -C ~/.local/bin headwater
Each archive has a .sha256 file beside it on the release, which sha256sum -c reads, and shasum -a 256 -c on macOS. The archive holds the headwater binary and the license, and nothing else. It does not get you taxonomy-source, and the taxonomy paragraphs below say how to fetch it.
Install it with apt on Debian or Ubuntu. From v0.4.1, every engine release builds the headwater package. A release cut with the APT signing key set publishes it to a signed APT repository at https://headwater.tools/apt. A release cut without that key carries only the Debian package on its release page. The site then keeps the APT repository of the last signed release. It is for amd64 only. After you install it, apt upgrade brings each new release. The block below runs on Debian 12 or later and Ubuntu 20.04 or later. The package itself also installs on Debian 11, and the smoke-apt release job holds that. On Debian 11 the block stops at apt-get install -y ca-certificates curl, because the Debian 11 security archive no longer serves those packages, and no download tool installs there. On Debian 11, download headwater_<version>_amd64.deb from the release page on another machine and copy it across. Then run sudo apt-get install ./headwater_<version>_amd64.deb, which needs no network and no apt-get update. A package installed this way gets no update from apt upgrade. The block installs ca-certificates and curl first, because a minimal image has neither. It runs each command with sudo, so where you are already root and have no sudo, as in a container, remove sudo from each line.
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL -o /etc/apt/keyrings/headwater-archive-keyring.asc https://headwater.tools/apt/headwater-archive-keyring.asc
echo "deb [signed-by=/etc/apt/keyrings/headwater-archive-keyring.asc] https://headwater.tools/apt stable main" | sudo tee /etc/apt/sources.list.d/headwater.list
sudo apt-get update
sudo apt-get install -y headwater
headwater --version
The package installs the static Linux binary of the newest release at /usr/bin/headwater. It also holds the license and the shell completions for bash, zsh and fish, and it carries no taxonomy.
The alternative, if you already have a Rust toolchain. Every workspace crate is on crates.io, published in dependency order by .github/workflows/publish-crates.yml.
cargo install headwater-cli --locked
The command needs nothing this repository ships: no clone, no toolchain floor beyond what cargo itself resolves from the crate's declared rust-version. It gets you the headwater binary alone, at whatever the newest published version is. --locked builds it with the dependency versions that the release was published and tested with. A later release or a yank of a dependency then cannot break the install, and a yanked version only prints a warning.
A fixed version built from source, with the taxonomy package beside it. v0.6.0 is the newest tagged release, and the block below builds it from source. It needs a Rust toolchain at 1.91 or later, a floor engine/README.md explains and engine/Cargo.toml declares.
git clone https://github.com/headwater-ai/headwater.git
cd headwater
git checkout v0.6.0
cargo build --release -p headwater-cli --manifest-path engine/Cargo.toml --locked
The binary lands at engine/target/release/headwater, and headwater --version prints the number the tag names. The taxonomy package is verified through its own tag namespace. The notes of an engine release state the release.digest of the package in that tag's tree. That package can be older than the newest taxonomy release, so pin the digest that the taxonomy release states. The release for taxonomy/headwater-standard/v4.13.0 states sha256:b0f032403027e4c003396172c6ca3767709dcefa64317cbfc18dfa253adfb2a3: the value of the release.digest field inside .headwater/packages/headwater-standard/release.yml in the tree that tag names. It is not what sha256sum prints for that file, because the field covers the files the record lists and cannot cover the record itself.
The binary alone gets you the rest of the way there, with nothing else required. From v0.2.1, the vendor verb takes the https:// location of the release's zip and fetches it itself: headwater taxonomy vendor https://github.com/headwater-ai/headwater/releases/download/taxonomy/headwater-standard/v4.13.0/headwater-standard-4.13.0.zip --expect <digest>. It checks every file against the digest, installs the package into .headwater/packages/headwater-standard, and pins the digest in .headwater/taxonomy.yml. A digest that does not match exits 1, names both values and writes nothing. Where your organization allows no fetch from GitHub, get the zip by the route it does allow — a mirror, an air-gapped copy — and unpack it into .headwater/packages/headwater-standard. Then run headwater taxonomy vendor .headwater/packages/headwater-standard --expect <digest>, which checks the same digest with no network at all. The tutorial's step 3 runs the location form. tools/headwater-bootstrap.sh fetches nothing any more: for one release it stays at its path and prints the vendor command to run instead.
An engine tag pins whatever headwater/standard version happened to ship with it, which is not always the newest one. An engine tag is cut when the engine changes, not when the taxonomy does, so the version a v<n> tag carries can lag behind the version taxonomy-source/headwater-standard/package.yml states on the default branch for as long as nobody cuts the next engine release — #757 is that gap, and it is a gap in the route rather than in the package. taxonomy/headwater-standard/v<version> is a second tag namespace, distinct from v<version> so the two never collide, cut independently by whoever maintains headwater/standard whenever they choose to publish a fixed version of it alone: no engine version bump and no engine tag required. .github/workflows/release-taxonomy.yml (#760) runs headwater taxonomy publish against taxonomy-source/headwater-standard, and attaches headwater-standard-<version>.zip to the tag's GitHub release, with the release.digest value printed in the release notes. headwater taxonomy vendor https://github.com/headwater-ai/headwater/releases/download/taxonomy/headwater-standard/v<version>/headwater-standard-<version>.zip --expect <digest> fetches that zip and installs it, with headwater v0.2.1 or later. The tutorial's step 3 fetches taxonomy/headwater-standard/v4.13.0.
What each engine release carries. .github/workflows/release.yml attaches three archives to every tag whose name starts with v, each beside a checksum for sha256sum -c, and each archive holds the headwater binary and the license. headwater-<tag>-x86_64-unknown-linux-musl.tar.gz is a static Linux build that needs no particular C library, beside headwater-<tag>-x86_64-unknown-linux-musl.tar.gz.sha256. headwater-<tag>-aarch64-apple-darwin.tar.gz is for macOS on Apple silicon, beside headwater-<tag>-aarch64-apple-darwin.tar.gz.sha256. headwater-<tag>-x86_64-unknown-linux-gnu.tar.gz is x86_64 Linux built on ubuntu-24.04, so it needs glibc 2.39 or later, beside headwater-<tag>-x86_64-unknown-linux-gnu.tar.gz.sha256. The workflow runs the musl and the macOS archives on a host that did not build them and has no Rust toolchain, and it creates no release until both run. v0.2.0 is the first tag that carries all three. v0.1.2 carries the glibc archive alone, and v0.1.1 carries none after its release collided with an immutable release object. The releases page is where you see which tags carry a binary.
The tutorial installs from the same release download as the first block above, and it names cargo install only as the alternative. It pins the version it downloads, and CI runs every other block of the tutorial against the engine on the default branch.
The engine runs, and one campaign has measured part of what it claims. This repository types its own corpus, checks it on every commit, and scaffolds, explains, routes, generates and exports it. The counterfactual campaign of 2026-09-30 measured it by component. The documents under
docs/have a large effect: with the governance layer removed and the documents kept, 114 of 119 graded sessions gave a sufficient answer, and with the documents removed too, 46 of 120 did, +57.5 points. The hooks and skills showed no detectable gain: on navigability the campaign excludes a gain of more than about 13 points, and on sufficiency both arms were at the ceiling. No arm measured the MCP server or the quality of governance itself, and the efficacy claims stay open until one does. The work still open is on the milestones page.
Specs drift from code, rationale evaporates, standards multiply and contradict each other, and the AI assistants now reading that documentation as context inherit every one of those faults — silently, and at scale.
The usual answers are a style guide (unenforced), a wiki (unstructured), or a static-site generator (renders whatever you feed it). None of them can answer "is this corpus still true?", because none of them know what kind of document anything is.
Headwater's premise: make the structure of the corpus a machine-readable contract, then derive everything else from it — validation, navigation, templates, AI instruction context, publishing, and the evidence that the whole thing is working.
-
Taxonomy is data. What shelves exist, what document kinds live on them, what metadata they carry, what voice and lifecycle they obey, and how they may reference each other — all declared in one versioned schema. Two organizations with different documentation cultures run the same engine over different taxonomies. Customizing the taxonomy never means forking the tooling.
-
The corpus is a graph. Documents are typed nodes; front-matter references are typed edges. Every validation rule is a constraint on that graph, every query is a traversal of it, and every derived artifact (indexes, site navigation, AI rules, agent context) is a projection of it.
-
AI assistants are readers in their own right, and measured ones. The corpus feeds agents at intent time, read time, write time, and review time — and the system probes whether that context actually changes agent behavior, rather than assuming it does.
Code is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE.
The prose under docs/ is licensed under Creative Commons Attribution 4.0 International. See docs/LICENSE. Code samples inside that prose stay under Apache-2.0, so copying an example into your own project carries no attribution obligation.
Contributions arrive under the Developer Certificate of Origin, with a Signed-off-by line and no contributor license agreement. CONTRIBUTING.md states why. SECURITY.md carries the disclosure process, and TRADEMARKS.md states the trademark position, which is that there is no registered mark.
Q11 records the reasoning, and the first-contact evaluation carries the full argument. The design narrowed the field and did not choose within it: internal-only and source-available terms are refused by rulings the specification already made, and network copyleft is refused for the library that spec 6 requires. The choice among the terms that remained belongs to the owner, who made it on 2026-08-11.