choir documentation
Getting started is in the top-level README. Everything else is here, indexed by task.
Each page is also pulled into the crate that implements it with
#![doc = include_str!], and the release gate runs cargo doc -D warnings,
so a Rust example here that stops compiling fails the build.
choir docs builds the book with rustdoc inside it at /api/. From a
checkout: cargo run -p choir-cli -- docs --open. The comment above is a
marker choir docs replaces with a link to the node (D76).
Start here
| You want | Read |
|---|---|
| What this is | Why choir exists |
| How the pieces fit | Architecture |
| To run a node | Running a node |
| To use a node | The CLI and HTTP API |
| To get a change reviewed and landed | The contribution workflow |
| Something is broken | Troubleshooting |
Operating a node
| Page | Covers |
|---|---|
| Running a node | Flags, policy files, supervised install |
| Authorization | ACLs (D29), ownership (D42), landing basis (D43), key rotation (D44), self-service (D36), publishing (D78) |
| Rate limits, quotas and fairness | Request log, rate limits (D33), quotas (D37), in-flight window |
| Webhooks | Ref-landed deliveries (D32) |
| Observability and repair | Decision journal, choir repair, derived records |
| Transports and the browser surface | Git over HTTPS and SSH (D31), read-only page (D28), browsing (D30) |
Runbooks:
- Private single-node beta runbook: network hold, TLS proxy, backups, staging promotion, go-live receipts.
- Restoring a node from a backup: ordering rule, and the secrets a backup never holds.
- Canonical-node flip runbook: supervised install, protected-ref gates.
Using a node
| Page | Covers |
|---|---|
| The CLI and HTTP API | Every command and endpoint, generated from one table |
| The contribution workflow | Workspace to landed ref, review rules |
| Agent templates | Snippets for Claude Code, Codex and Cursor |
AGENTS.md | The surface, written for an agent |
Reference
| Page | Covers |
|---|---|
| Troubleshooting | Symptoms, causes, fixes |
ERRORS.md | Every rejection code and repair hint, generated |
SYNC.md | Catching up on a log and verifying a served page |
DECISIONS.md | What each D<n> means, and which are one-way doors |
| Bridge permissions | Minimum GitHub App grants |
Which of these is generated
The gate fails when a generated file differs from its source. Regenerate
with cargo run -p choir-cli --example gen-surface.
| Generated | Source |
|---|---|
| The surface block in using/cli.md | crates/choir-cli/src/surface.rs |
theme/choir-tokens.css | crates/choir-node/src/ui.css |
| The cheat-sheet block in the README | crates/choir-cli/src/surface.rs |
AGENTS.md, /llms.txt, /api/schema | crates/choir-cli/src/surface.rs |
ERRORS.md | crates/choir-node/src/reject.rs |
The command lists in templates/ | crates/choir-cli/src/surface.rs |
Everything else on this page is hand-written.