Audience: anyone who needs the exact answer to a narrow
question. What's the default for [hnsw] ef_search? What's the
wire opcode for ENCODE? What error code does Brain return when an
idempotency conflict is detected?
Goal: information. Tables, field lists, grammar. Not
"how do I use X" (see ../guides/), not "why is X
this way" (see ../concepts/ and
../architecture/).
Reference pages are short and skimmable. They cite the spec section that owns the contract. If a reference page contradicts the spec, the spec wins and the reference page is stale.
| Page | Covers |
|---|---|
configuration.md |
Every TOML field, every default, every env-override pattern |
brain-shell.md |
Overview of the brain interactive shell (deep ref in shell/) |
cli.md |
brain-cli admin subcommand reference |
http-api.md |
HTTP routes on the metrics port — /healthz, /metrics, /v1/* |
sdk-rust.md |
Public surface of brain-sdk-rust |
metrics.md |
Catalogue of Prometheus metrics Brain emits |
performance.md |
Latency + throughput targets per operation |
| Subtree | Covers |
|---|---|
shell/ |
brain shell deep reference: commands, REPL meta, output formats, configuration, errors |
wire-protocol/ |
Frame format, opcodes, error codes, handshake |
cognitive-operations/ |
Exact semantics of ENCODE / RECALL / PLAN / REASON / FORGET |
schema-dsl/ |
Grammar + worked examples of the schema language |
- The Rust API by signature — that's
cargo doc/ rustdoc. Runcargo doc --workspace --no-deps --openin the workspace root for the rendered version. - The authoritative spec — that's
../../spec/. Reference pages here are derived from the spec; the spec is the source of truth. - "How do I use this?" — that's
../guides/. - "Why is this designed this way?" — that's
../concepts/(high-level) and../architecture/(deep).
Every reference page ends with **Spec:** §NN/MM pointing at the
authoritative section. If a code change makes a reference page
wrong, both the page and the cited spec section need re-checking
— the spec might be wrong too, but that requires the user to
approve a spec edit. Open an issue rather than fixing it silently.