Module surface 

The agent-facing surface, as data, and the generators that render it.

choir --help, docs/using/cli.md, the README’s cheat-sheet, the three templates/ snippets, the root AGENTS.md and the node’s llms.txt all describe one surface. Hand-maintained, they drift — and they had already started to: the API table carried a throughput figure that three later measurements had superseded.

So the surface is described once, here, and everything else is rendered from it. crate::surface is the source; a staleness test re-renders and compares, so a committed artifact cannot silently fall behind the table.

What is generated and what is not

Only the signatures — command names, arguments, endpoints, purposes. The conventions around them stay hand-written, because templates/ is a product deliverable whose value is judgement (“name no reviewers; the node draws them”) rather than syntax, and generating prose would flatten exactly the part worth shipping. In the templates the generated region is bounded by GEN_START/GEN_END markers and the prose lives outside them.

No dependency is added for any of this: rendering markdown from a const table is a few format! calls.

Structs

Command

One choir subcommand.

Endpoint

One HTTP endpoint on the node.

McpTool

The MCP-specific part of one HTTP endpoint.

Enums

McpArguments

How an MCP tool’s arguments become one HTTP request.

Constants

API_VERSION

Version of the machine-readable API description (D17).

AUTH_OPTIONS

Explicit global options for authenticated node access.

COMMANDS

Every choir subcommand, in help order.

DAY_ONE

The commands a first contribution needs, in reading order.

DEPRECATIONS

Wire names this API still accepts and no longer documents, with what replaced them.

ENDPOINTS

Every endpoint the node serves, in the order docs/using/cli.md lists them.

GEN_END

Closing marker of a generated region.

GEN_START

Opening marker of a generated region in an otherwise authored file.

GROUPS

The help sections, in reading order: what you do first, then the loop you live in, then the things you reach for when something is wrong.

SH_GEN_END

Closing marker of a generated region in a shell file.

SH_GEN_START

The same pair for a shell file, where an HTML comment is a syntax error rather than a comment.

SKILL_DIR

Directory name the agent skill installs under; the skill frontmatter’s name: must equal it, because skill loaders resolve by directory.

Functions

agents_md

AGENTS.md: the generated choir reference for coding agents.

api_table

The endpoint table docs/using/cli.md carries.

artifacts

Every artifact rendered from this table, as (path, full contents), relative to the repository root.

cli_doc_surface

The generated API and CLI reference in docs/using/cli.md.

cli_reference

The command reference in docs/using/cli.md: every command, its full argument spec, and what it is for.

command_bullets

The command list the agent templates carry, as a markdown bullet list.

command_help

The help for one command: its full spec and its whole summary.

command_help_in

command_help, styled for a terminal.

contribute_html

The three commands a newcomer runs, as an HTML fragment the node serves on its contribute page.

endpoint

Finds an HTTP endpoint by method and path.

llms_txt

llms.txt, served by the node: the same surface, compact, no markdown tables — a plain list survives a small context window better.

mcp_endpoint

Finds the HTTP endpoint backing an MCP tool.

mcp_tools

MCP tools in deterministic endpoint-table order.

python_client

The generated half of templates/python/choir.py: one method per tool, rendered from the schema document and nothing else (D17).

readme_cheatsheet

The README’s cheat-sheet: the day-one commands and nothing else.

schema_json

The machine-readable API description (D17), as pretty JSON.

shell_functions

The generated half of templates/shell/choir.sh: one function per agent-facing command (D17).

skill_md

The installable agent skill.

splice

Replaces the region between GEN_START and GEN_END in doc.

splice_between

splice with explicit markers, for a file whose comment syntax is not HTML.

usage

The choir usage block, as a bare invocation prints it.

usage_in

usage, styled for a terminal.