---
id: docs
title: Only what cannot be discovered by running the tool or reading the code
status: continuous
repos: [atgc]
dependsOn: []
exitCriterion: >
  None. A page earns its place by holding something no other source can, or
  it is deleted.
---

# docs

Four pages under `docs/`: the model, the output contracts, the module layout
and what earns a test. Flags are in `--help`, why a dependency is vendored is
in `Cargo.toml`, what changed is in `git log`, what is enforced is in
`prek.toml` — none of that is repeated, because a second copy is a second thing
to be wrong.

They are compiled into rustdoc through `src/docs.rs`, with
`rustdocflags = -D warnings`, so a reference from prose into code that no
longer resolves is a build failure. mdBook was rejected for being a second tool
outside the toolchain pin that could not check exactly that.

This register is under the same rule, and the entry below is the reason it
exists in this shape rather than as one flat file.

## Done

- [x] Documentation: narrative pages in docs/ (architecture, pull requests,
      accounts, sessions), compiled into rustdoc through src/docs.rs so prose
      and generated reference are one build — `cargo docs`, aliased in
      .cargo/config.toml, with rustdocflags = -D warnings making a
      prose-to-code link that no longer resolves a build failure. mdBook was
      rejected: a second tool outside the rust-toolchain.toml pin, and it
      cannot check the links that rot
- [x] Four entries in this file claimed work was undone that was done, which
      before a 1.0 is worse than no entry at all: two were plain staleness
      (the reserved-TLD list, which jacquard enforces and always has, and the
      `?` promotion, which moved *into* `gather` rather than being aligned
      the way its entry proposed), and two were damage from resolving rebase
      conflicts in this file — one entry kept a `[ ]` box over a body
      rewritten to describe the finished work, and one survived twice, once
      in each state. Found by reading every `- [ ]` back against the code
      rather than by trusting the boxes
- [x] A 1.0 pass over the prose against the code it describes, since 1.0 is
      when the most strangers read it. `docs/index.md` called `output.md`
      three rules where it has four; `plan/output.md` said `--help` has three
      command groups where `src/help.rs` has five; the README said every
      command takes `--json`, where six do not and `docs/output.md` already
      argued each one. The README's install was `cargo install --path .`,
      which only works from a clone — it now names the `--git` install and
      says crates.io is blocked, so it cannot become false on the day
      `plan/publishing.md` is unblocked