Reference
You will be able to look up the exact shape of anything commission accepts or returns — a command, a flag, a config key, a document field, an MCP tool, an HTTP route, an exit code — and trust that it matches the binary you are running.
Reference is exhaustive and joyless by design. If a page reads like an explanation, it belongs in Concepts; if it reads like advice, it belongs in Guides.
Pages
| page | you will be able to | source | owner |
|---|---|---|---|
cli.md | Find every command, argument, and option, with the exit code each refusal uses. | generated — scripts/generate-docs.ts, walked from the commander program | relay-58 |
config.md | Look up every .commission.json key, its type, its default, and which layer wins. | generated — scripts/generate-config-reference.ts | relay-30 |
apply.md | Write a valid commission apply document: every field, with the JSON Schema. | generated — scripts/generate-docs.ts, from applySchemaJson() | relay-58 |
mcp.md | See exactly which MCP tools an agent gets and what each one takes. | generated — scripts/generate-docs.ts, read over the MCP protocol | relay-58 |
cli-contract.md | Rely on the CLI as an API: the naming, flag, output, and exit-code promises the command tree is tested against. | written | relay-46 |
refusals.md | Judge a refusal: the twenty an agent actually hits, audited one by one, plus the rules a new one has to meet. | written | relay-68 |
http.md | Call the HTTP API: every route, its request and response shape, and how auth works. | written | relay-59 |
json.md | Parse --json output: the shape of a task, a bundle, a board, an event, a refusal. | written | relay-59 |
exit-codes.md | Branch correctly on commission’s exit codes from a script or an agent, and read a refusal. | written | relay-59 |
config-examples.md | Copy a .commission.json that matches how your team works, and know which keys are not yet applied. | written | relay-59 |
Generated pages are not editable
Four of the pages above are written by a script and overwritten on the next run. Editing them by hand looks like it worked and is silently reverted; worse, it can make the documentation disagree with the binary, which is the exact failure this section exists to prevent.
bun run generate:docs # cli.md, apply.md, mcp.md
bun run generate:config # config.md and schema/commission-config.schema.jsontests/docs.test.ts and tests/config.test.ts fail if any generated page is stale, so
a source change that would have rotted the docs breaks the build instead. The full
rule, and how to tell at a glance which kind of page you are in, is
Contributing → documentation.
Exit codes and refusals
The four exit codes, the { error, message, missing, hint } refusal envelope, and
how each maps onto an HTTP status and an MCP result are defined once, in
exit-codes.md. Every other page links there rather than restating
them — a second copy of a contract is exactly the drift this section exists to
prevent.
Code 2 is not a failure. A refusal is a prompt an agent can act on without a human;
see positioning.md §6.
This page is docs/reference/index.md in the Commission
repository, rendered in place — the site keeps no copy of it. The repository is private, so there is no edit link to follow.