Writing pages (contract)¶

Goal: state the structure every operational page on docs.engineeringruntime.com must follow, so that a human or an AI assistant can execute the page without inferring anything.

This tab is about the docs website

It is the contract for updating these pages — not a guide to contributing code to the Runtime binary. Product / Control Plane contribution lives on the developer portal.

The primary reader of this site is increasingly an assistant acting on someone's behalf. An assistant cannot use a page that buries commands in prose: it needs to know what the page achieves, what must already be true, what to run, what success looks like, and what to do when it does not happen.

Which pages this applies to¶

Kind	Contract?	Examples
Operational — tells the reader to run something	Required	Install Runtime · Authenticate Runtime · Connect GitHub · Run Capabilities
Reference — describes a surface	Partial: Goal + accurate tables; the rest where it fits	`config.yaml` keys, CLI flags, provider operations
Conceptual — explains why	Exempt. Stays prose	Runtime Home, architecture explanations

Do not convert an explanation into a checklist to satisfy this contract. A fake procedure is worse than honest prose — it invites an assistant to execute something that was never a procedure.

The sections, in order¶

Section	Answers	Rule
Goal	What this page accomplishes	One sentence, imperative. First thing after the `# H1`
Prerequisites	What must already be true	Each one verifiable by a command, not by belief
Inputs	Values the operator supplies	Named, with an example value. Omit the section if there are none
Steps	The commands	Copy-pasteable exactly as written. No "open a terminal", no "navigate to"
Expected output	What success looks like	Literal output copied from a real run. Not a description of it
Common failures	Symptom → cause → fix	Table. Quote the real error text the binary prints
Exit codes	What non-zero means	Where the command defines them. Omit where it does not
Next	Where to go now	Exactly one link. A chain, not a menu

The rules behind the rules¶

Expected output is copied, never written from memory. Run the command, paste what came back. A plausible-looking block that does not match reality is the most damaging thing on this site: it teaches an assistant to expect something that will never appear, and it fails silently because nothing checks prose.

Error text is quoted character-for-character. An assistant matches on it. If the binary prints:

policy denied binary "helm": binary "helm" is not in allowed_binaries

then that is what the page says — not "a policy error is shown".

Prerequisites are verifiable. "You have Engineering Runtime installed" is not a prerequisite; runtime version printing a version is.

Next is one link. The Get Started chain is a sequence with one path through it. A menu at the end of every page turns a chain into a maze, and an assistant has no basis to choose.

Never document what the binary does not support. This is product hub hard rule 5, and it outranks any structure here. The binary ships two providers, files and github. Command Engine cheatsheets for other CLIs are a different mechanism and must not be presented as provider support. If a page cannot show a working path against the shipping binary, it does not ship the claim — the roadmap belongs on Enterprise → Roadmap.

Page names are goals, not nouns¶

Pages are named for what the reader is trying to do:

Not this	This
Installation	Install Runtime
Authentication	Authenticate Runtime
GitHub	Connect GitHub
Quick Start	Run Your First Capability
Providers → Overview	Configure Providers
Validate & Execute	Run Capabilities
Control Plane (Portal)	Connect the Control Plane

A noun names a screen. A verb names a task, and a task is something an assistant can be asked to complete.

Skeleton¶

# Connect GitHub

**Goal:** authenticate the runtime against GitHub so `runtime github` operations work.

## Prerequisites

| Must be true | Check |
|---|---|
| Runtime is installed | `runtime version` |
| Runtime Home exists | `runtime bootstrap` |

## Inputs

| Input | Example |
|---|---|
| A GitHub personal access token | `ghp_…` |

## Steps

```bash
export RUNTIME_GITHUB_TOKEN=ghp_your_token
runtime auth login github

Expected output¶

(paste the real output here)

Common failures¶

Symptom	Cause	Fix
`…real error text…`	…	…

Next¶

Run Your First Capability ```

Checklist before merging a page¶

[ ] Named for a goal, not a noun
[ ] Goal sentence is imperative and first
[ ] Every prerequisite has a command that proves it
[ ] Every command is copy-pasteable as written
[ ] Expected output was copied from a real run
[ ] Failure table quotes the real error text
[ ] Exactly one Next link
[ ] Nothing unshipped is described as available
[ ] mkdocs build --strict passes and the page is in mkdocs.yaml nav