orangerail-docs-gen

The prompt rail of orangerail: walk an ontology registry and deterministically generate the agent-facing domain document — AGENTS.md sections plus an embedded Mermaid classDiagram — that describes the runtime rail truthfully.

The point is that the document an agent reads and the MCP server it calls come from the same declaration, so they cannot drift apart. Nobody hand-maintains a markdown file that says which writes need approval.

Most users never install this directly: the orangerail CLI depends on it and orangerail docs is the command that writes the file.

npx orangerail docs --out ./docs

Install

npm install orangerail-docs-gen

orangerail-core is a dependency; zod is a peer dependency (^3.23 || ^4). mermaid and jsdom are dev-only — they back the tests that parse the generated diagram to prove it is valid, and nothing at runtime imports them.

Use

Two pure functions, zero I/O. File writing lives only in the CLI command.

import { generateDocs, generateMermaid } from 'orangerail-docs-gen';

const markdown = generateDocs({ registry });
const diagram = generateMermaid({ registry });

• generateDocs({ registry, preset? }) — the complete document: the agent-usage guide, the domain map, the MCP tool list, and the object / link / action type sections.
• generateMermaid({ registry }) — just the classDiagram body, if you are embedding it somewhere of your own.
• deriveTools({ registry, preset? }) — the tool list as data rather than markdown.

preset mirrors the MCP server's exposure and defaults to 'approval-for-writes', exactly as createMcpServer does, so the document claims the tools the server actually serves. 'sandbox' and 'readonly' render the guide and tool list those presets produce.

Output is byte-deterministic

Entities are sorted alphabetically and nothing carries a timestamp or a random id, so regenerating an unchanged registry produces a byte-identical file and an empty git diff. That is what makes the generated document safe to commit and to check in CI.

The output opens with <!-- Generated by \orangerail docs`. DO NOT EDIT — regenerate instead. -->`.

Governance facts are truthful

An action's approval gate, approver roles and where guard are rendered from the registry, not from a description someone typed. A declarative guard renders as condition: only when status neq "soldout"; a functional predicate renders as custom code predicate — evaluated at runtime, not representable here, because its body is opaque to this package exactly as it is to the action signature hash. The document never claims to state a condition it cannot read.

License

MIT