Contribute to the documentation

ActionRail documentation lives with the framework so behavior, tests, and operator guidance can change in the same pull request.

Run the site

From the repository root:

cd docs
npm ci
npm start

Build the production artifact before submitting:

npm run build

The build fails on broken internal and Markdown links and compiles every Mermaid diagram.

Choose the right section

Section	Content
Getting started	The shortest verified path to a real outcome.
Core concepts	Stable mental model, object names, and architecture.
SDK	Framework integration and application lifecycle.
Rules	Policy and grounding behavior.
Sources	Adapter setup, result semantics, and least privilege.
Security	Trust boundaries, data movement, credentials, and non-goals.
Operations	Outages, audit delivery, reviews, readiness, and diagnosis.
Reference	Exact signatures, fields, enums, defaults, and codes.
Contributing	Documentation conventions and the OSS-to-Cloud development contract.

Put a concept in one authoritative page and link to it. Do not copy the same explanation across several tutorials and let the copies drift.

Maintainers working on the hosted distribution must also follow the Downstream Cloud contract. The contract stays tracked in OSS so its extension boundaries and sync rules change with the code they govern.

Canonical language

• ActionRail is the product and Python package family. Always use this exact capitalization in prose, navigation, labels, titles, and diagrams. Lowercase is reserved for literal technical identifiers such as Python imports, package and command names, filenames, environment paths, and domain names.
• Agent is a registered deployed identity/configuration boundary.
• Source is a configured verification instance; capitalize it when referring to the ActionRail object.
• Adapter is the implementation type: SQLite, Postgres, MySQL, HTTP, or MCP.
• Grounding is deterministic live verification, not RAG.
• Console is the operator UI/local distribution; control plane is the wider API/storage boundary.
• Action is one proposed or executed tool invocation; tool is the reusable callable.
• Use actions blocked, not “actions prevented.”
• Use held for review, not “waiting for confirmation” when describing the decision state.
• Use allow, hold, and block for runtime outcomes.

Do not introduce connector, integration, or data source as alternate object names. “System of record” may describe a Source’s role, but not every Source is the canonical system of record.

Security writing rules

Every security claim must say which boundary enforces it.

Good:

Source credentials resolve from environment references inside the SDK process and are not sent to the control plane.

Too broad:

No data ever leaves the customer environment.

The second claim is false when decision metadata is reported or write.report_args explicitly exports values.

When adding a feature, document:

• default behavior;
• fail-open and fail-closed choices;
• data that crosses process/control-plane boundaries;
• the real authorization boundary;
• outage and shutdown behavior;
• unsupported or unsafe configurations.

Code examples

• Use current public imports and parameter names.
• Show environment references instead of literal credentials.
• Prefer deterministic examples that do not require a paid model API.
• State whether a command runs a real agent or tool.
• Use Postgres/MySQL %(name)s and SQLite :name parameter syntax correctly.
• Show trusted_context() for request identity.
• Assign the object returned by enforce() or instrument().
• Include close_reporting() in long-running or short-lived managed examples when lifecycle matters.

Diagrams

Use Mermaid when a sequence, trust boundary, or failure state is easier to understand visually. Keep node labels plain and quote labels containing punctuation.

Diagrams must reinforce the text, not introduce a second undocumented architecture.

Review checklist

• Behavior matches the current implementation and tests.
• Defaults and units are explicit.
• Internal links use Docusaurus-relative paths.
• New pages are added to sidebars.js.
• Terminology follows the canonical language above.
• Security and privacy claims include their boundary and exceptions.
• Examples contain no real secrets, hosts, customer IDs, or private data.
• npm run build passes.