# Docs as code

Documentation in this repository is treated like source code: plain text in git,
changed through pull requests, checked by a script, and kept next to the code it
describes. This page defines how.

## Principles

1. **Docs live in the repo.** Markdown files, versioned with the code. No wiki,
   no separate document store that can drift from the release it describes.
2. **One change, one pull request.** A change to behaviour, a file format,
   cryptography, SPV validation or key handling updates the affected docs in the
   same commit. `SECURITY.md` is the published threat model and must stay accurate
   (see `CLAUDE.md`, *Working rules*).
3. **Review docs like code.** Reviewers check that the text matches the diff.
4. **English only** for documentation, comments and commit messages.
5. **Diagrams are text.** Use Mermaid code blocks, which render on GitHub and diff
   cleanly. No binary diagram files unless a tool cannot export text.
6. **Prefer links to copies.** Point to the code path or the ADR instead of
   restating it, so there is one place to update.
7. **Check mechanically.** `docs/check-docs.sh` runs the checks below; run it
   before committing documentation changes.

## Where things go

| What | Where | Audience |
|------|-------|----------|
| Project overview, build and run, test | `README.md` | Developers |
| End-user manual | `USERGUIDE.md` | Users |
| Threat model, crypto parameters, SPV trust | `SECURITY.md` | Users, reviewers |
| What shipped in each release | `CHANGELOG.md` | Everyone |
| Why the design is the way it is | `docs/adr/` | Maintainers, reviewers |
| This process | `docs/docs-as-code.md` | Contributors |
| Build, signing and release procedure | `docker/README.md`, `docker/keystore/README.md` | Release managers |
| Rules for coding agents | `CLAUDE.md` and `AGENTS.md` (kept identical apart from their header) | Agents |

Rule of thumb: *what* and *how* belong to the README, user guide and code comments;
*why this and not the alternative* belongs to an ADR.

## Architecture Decision Records

One ADR per feature or significant decision, in `docs/adr/NNNN-slug.md`, written
from `docs/adr/template.md`. The index is `docs/adr/README.md`.

**When to write one.** Add or change an ADR when a change:

- introduces a feature or subsystem;
- touches cryptography, SPV validation, key or seed handling, or the file format;
- is hard to reverse, or someone is likely to ask "why not X?" later.

Bug fixes and refactors that keep the decision intact do not need an ADR.

**Lifecycle.**

```mermaid
stateDiagram-v2
    [*] --> Proposed: opened in a pull request
    Proposed --> Accepted: merged
    Proposed --> [*]: rejected, PR closed
    Accepted --> Superseded: a newer ADR replaces it
    Accepted --> Deprecated: feature removed
```

- Number ADRs sequentially; never reuse or renumber.
- Do not rewrite the substance of an Accepted ADR. To change a decision, write a
  new ADR, set the old one's status to `Superseded by [NNNN](NNNN-slug.md)` and
  link back from the new one. Typos and broken links can be fixed in place.
- Keep each ADR short: context, decision, consequences, references.
- Reference code by repository-relative path in backticks. The check script
  verifies these paths still exist, so a rename shows up as a docs failure.

## Workflow

```mermaid
flowchart LR
    A[Change code] --> B{Decision hard to<br/>reverse or security-relevant?}
    B -- yes --> C[Add or supersede ADR]
    B -- no --> D[Update README / USERGUIDE / SECURITY if affected]
    C --> D
    D --> E[Run docs/check-docs.sh]
    E --> F[Pull request: code + docs together]
    F --> G[Review checks text against diff]
```

1. Make the code change.
2. Decide whether an ADR is needed (see above) and write or supersede it.
3. Update `README.md`, `USERGUIDE.md`, `SECURITY.md` and `CHANGELOG.md` where the
   change affects them. If you edit `CLAUDE.md`, mirror the edit into `AGENTS.md`.
4. Run `docs/check-docs.sh`.
5. Commit code and docs together and open the pull request.

## What `docs/check-docs.sh` verifies

- Every ADR file is named `NNNN-slug.md`, numbers are unique and contiguous.
- Every ADR has a title line matching its number, a `Status`, and the sections
  *Context*, *Decision*, *Consequences*.
- Every ADR is listed in `docs/adr/README.md`, and every index row points to a file.
- Repository paths cited in backticks (`src/…`, `tests/…`, `docker/…`, root files)
  exist.
- Relative Markdown links in `docs/` resolve.
- `CLAUDE.md` and `AGENTS.md` match apart from their header block.

It needs only `bash` and standard tools, so it runs on a developer machine and in CI
(the `docs` job in `.github/workflows/ci.yml`, see ADR 0032).

## Possible next steps (not in place yet)

- Add a Markdown linter to the `docs` CI job.
- Add a link checker for external URLs.
- Publish `docs/` as a static site if the audience outgrows GitHub's renderer.