Reference

Generated reference for the API, the CLI, command kinds, error codes, the daemon protocol, events, modules and packages, from a live control plane and the .proto files.

Most of this section is generated from the repository by apps/docs/scripts/generate.mjs, so it matches the code it documents. The generator does not parse source files. It imports the built packages and constructs a real control plane with betterCompute() and every module registered: the built-in node controllers, inventory and capacity, plus provision with metal, vps, events, fleet, rollout and audit. That control plane runs on a PGlite executor that is never opened and an IamPort that refuses every call, so nothing is migrated and no decision is made. What it reads is the registry a full deployment serves, plus the .proto files for the protocol page:

Page	Generated from
API	The method registry, joined with PLAN.md §9.2 (core's `apiSurface`), so every method shows as `registered` (served by this build) or `planned` with its phase
CLI	`cliManifest()` of `@better-compute/cli`, the same data `better-compute help --json` prints
Command kinds	`registry.commandKinds`: lane, roles, retry-safe, self-terminating, attested and destructive flags, timeout and payload message
Errors	Core's `errorCodes` and `defaultStatus`
Protocol	The `.proto` sources under `proto/bettercompute`, read by `apps/docs/scripts/protocol.mjs` (5cafb1e): every service, RPC, message and enum of `commands.proto`, `inventory.proto`, `session.proto`, `common.proto`, `driver.proto` and `site.proto`, with field numbers, labels, types linked to their message or enum, and each declaration's own comment. It reads the files rather than the compiled descriptors, which drop comments, and was checked against them (157 messages, 25 enums, equal field numbers)
Events	`eventCatalog` of `@better-compute/events`: every event family with its type, subject and module, the same list `webhooks.eventTypes` returns
Metrics	`metricCatalog()` of `@better-compute/observability`: every Prometheus family with its type, labels, help and buckets, grouped by the function that defines it
Modules	The registry's modules, their API groups and migrations, and every job in `compute.jobs`
Packages	Every `packages/*/package.json`: name, description and export subpaths

The prose on the API and error pages is hand-written and kept beside the generator in apps/docs/descriptions/: api/<group>.md holds an overview paragraph and one ## method section per method, whose first paragraph becomes the summary, and errors.md holds one ## CODE section per error code. The generator checks those files against the registry, so a description of a method or code that no longer exists fails the run.

The rest of the section is written by hand: the glossary (from apps/docs/data/glossary.json, which also feeds the hover cards on every term in the guides), how to use these docs with AI, the roadmap, and the changelog, which includes the repository's CHANGELOG.md at build time.

API

Every compute.api group and method: HTTP route, IAM action and resource, module, phase and status.

CLI

The better-compute command line: dev, serve, pki, fleet, sim, audit and the rest, with flags and environment variables.

Command kinds

The typed one-shot operations daemons run, with their lanes and safety flags.

Errors

Every stable error code with its HTTP status and meaning.

Protocol

Every service, message and enum of the daemon protocol, with field numbers and types.

Events

Every event type the outbox publishes, for webhooks and the watch stream.

Metrics

Every Prometheus series: type, labels, help text and buckets.

Modules

What each module registers: API groups, migrations and jobs.

Packages

Every package in the repository and its entry points.

Glossary

Atoms, bookings, leases, NodeSpecs and every other term the guides use.

Use the docs with AI

The docs MCP server, llms.txt and per-page Markdown.

Roadmap

The version plan from P0 to v1.0 and the honest state of each item.

Changelog

Every notable change, newest first.

Machine-readable docs

The site serves its content to tools and language models as well as to people:

URL	Content
`/llms.txt`	An index of every page with its URL and description, headed by a one-line summary of Better Compute
`/llms-full.txt`	Every page as Markdown in one file
`/docs/<page>.md`	One page as Markdown. A request for `/docs/<page>` with `Accept: text/markdown` gets the same answer
`/llms.mdx/docs/<page>/content.md`	The route both of the above are rewritten to, with a `Link: rel="canonical"` header pointing at the HTML page
`/api/search?query=...`	The search index behind the search dialog, as JSON
`/api/mcp`	An MCP server (Streamable HTTP) with search, page and reference lookup tools; see use the docs with AI

/llms.txt and /llms-full.txt are sent with X-Robots-Tag: noindex, so search engines index the pages themselves.

Regenerating

The generator imports the packages' dist/ output, so build them first. It stops with the list of missing builds when one is absent.

node node_modules/typescript/bin/tsc -b          # build every package the generator imports
node apps/docs/scripts/generate.mjs              # write apps/docs/generated/*.json and the generated pages
node apps/docs/scripts/generate.mjs --check      # fail when anything it would write differs (CI)
node apps/docs/scripts/check-content.mjs         # frontmatter, meta.json entries, links and anchors

generate.mjs writes apps/docs/generated/{api,errors,protocol,cli,command-kinds,events,metrics,modules,packages}.json next to the pages. The site reads them at build time: the MCP server's lookup_api_method, lookup_error_code and lookup_cli_command tools answer from them. In --check mode, pages in reference/api/ that the generator would no longer write count as drift too; without --check it deletes them.

tests/docs-generate.test.ts checks the committed output without a build: the descriptions name only real groups, methods and codes, every API group has its page and meta.json entry, the committed generated/protocol.json equals what protocol.mjs reads from the .proto files now and the protocol page has a heading for every message (2adc7a3), and check-content.mjs reports no problems. With the packages built and DOCS_GENERATE_CHECK=1 it also runs generate.mjs --check, so a registry change without regenerated docs fails the suite.

Edit the source, not the page

Every generated page starts with a comment naming its source. Change the code, or the matching file in apps/docs/descriptions/, and regenerate; a hand edit to a generated page is overwritten on the next run and fails --check until then.

Machine-readable docs

Regenerating

On this page