Documentation Standards¶

How to write, format, and maintain documentation in the AutonomyOps ADK.

Canonical Source¶

This repository root (/) is the canonical source for AutonomyOps product and technical truth: what the software does, how it is configured, what it ships, what guarantees it makes. All other AutonomyOps surfaces are derivative — they position, summarize, and link, but they do not restate canonical content.

Surface	Role	Authoring rule
This docs repo root (`/`)	Canonical product / technical docs	Author here when the content states what the software does, how to configure it, what it ships, or what it guarantees. CLI reference, quickstart, architecture, runbooks, release notes.
`adk/docs/internal/`	Engineering-internal source material	Author here when the content is engineering context not ready for customer sharing (Go symbol details, threat-model internals, in-flight commercial materials). Not built into the public site. Migration mechanics: `docs/internal/hosting-architecture-decision.md` § Content Flow and Promotion Model.
`autonomyops.ai` (marketing website)	Lighter public messaging	Position the product, summarize the value proposition, and link to canonical docs. Do not restate technical claims independently. Source repo for companion PRs: `autonomyops/autonomyops.github.io`.

Two-question test for marketing-surface authors¶

When adding or updating copy on the marketing website:

Is this a technical claim? A behavioral statement, a configuration detail, a guarantee, a CLI/API reference, an artifact name, a version number — if yes, it belongs in this docs repo. The website links to the canonical page.
Is this positioning? Audience-specific framing, value proposition, “why this matters” copy that points readers at canonical docs — the website may carry it, but every embedded technical claim must already exist canonically and the website must link out rather than restate.

Drift policy¶

Drift between the website (autonomyops.ai) and canonical docs is a website bug, not a canonical docs bug. When a change in this docs repo invalidates website copy, the canonical change lands here first; a companion PR in the website source repo autonomyops/autonomyops.github.io follows in the same review cycle and is referenced from the docs PR description.

Required website-companion PR¶

If your docs-repo change updates a claim that the marketing website (autonomyops.ai) also makes, the PR description must:

Name the affected website page(s).
Link the companion PR in the website source repo autonomyops/autonomyops.github.io (or explicitly state that the companion PR is already merged / not yet required because the website has not yet stated the claim).

A reviewer who finds a docs-repo PR that changes user-visible claims without a linked companion PR or an explicit not-required note must block on this rule.

Page Structure¶

Every documentation page must have YAML front matter:

---
title: "Page Title"
owner: "<team or person responsible for keeping this page current>"
last_verified: "YYYY-MM-DD"
source: "<relative path(s) in the repo where content originates>"
---

Required sections (adapt headings to page type):

Section	Purpose
Opening paragraph or `## Purpose`	One paragraph: what this page covers and why it exists
Core content	Interfaces, invariants, config keys, walkthrough steps, etc.
`## Do Not Do`	Anti-patterns — explicit list of what NOT to do, and why
`## See Also`	Cross-links to related pages (bidirectional where applicable)

Front Matter Fields¶

Field	Required	Notes
`title`	Yes	Shown in nav and browser tab
`owner`	Recommended	Team or person responsible for keeping the page current
`last_verified`	Recommended	ISO date when the content was last verified against code
`source`	Recommended	Relative repo path(s) where content originates
`description`	Optional	Used for `<meta name="description">` in the built site

File Naming¶

Rule	Example
Lowercase, hyphens only	`disk-ceiling.md` ✓ — `DiskCeiling.md` ✗
Match the nav slug	Nav entry `Disk Ceiling` → file `disk-ceiling.md`
No spaces or underscores in new files	`threat_model.md` ✗

Code Blocks¶

Always specify a language identifier:

```go
func Put(ctx context.Context, key string, val []byte) error { ... }
```

```bash
make build
```

```toml
[storage]
disk_ceiling_bytes = 10737418240
```

Fenced code blocks only — indented code blocks are forbidden (enforced by MD046: style: fenced in .markdownlint.yml).

Smoke-Test Markers¶

The  HTML comment enables CI validation of documented shell commands. A bash fenced block immediately following this marker (with at most blank lines between) is extracted by scripts/ci/extract-smoke-commands.sh and executed during the tagged-release command-smoke-test CI job (golang:1.22 container, no Docker, no external services).

Only mark commands that:

Are safe to run in a fresh Go container (make and go are available)
Do not require Docker, a running registry, or external services
Produce deterministic, non-destructive results

<!-- smoke-test -->
```bash
make build

**Do NOT mark commands that:**

- Start daemons or long-running processes
- Require Docker, a container registry, or network services
- Have side effects on shared infrastructure
- Depend on demo keys or pre-existing artifacts

If no annotated blocks are found across all docs, the smoke-test job passes with a
warning (soft pass). The first failed command in any annotated block is a release blocker.

## Admonitions

Use MkDocs Material admonitions for callouts. Available types:

```markdown
!!! warning "Title"
    Warning text here — use for non-obvious gotchas.

!!! info "Title"
    Informational note — use for tips and clarifications.

!!! danger "Title"
    Danger / non-negotiable constraint — use for invariant violations and
    security non-negotiables.

Use !!! danger for statements like “never bypass X” or “always require Y” that trace to a named invariant.

Internal Links¶

Always use relative paths:

[Invariants](../architecture/invariants.md)          ✓ relative path
[Invariants](invariants.md)                          ✓ same directory
[Invariants](/architecture/invariants/)              ✗ absolute — breaks offline
[Invariants](https://example.com/architecture/)      ✗ external URL for internal page

Bidirectional cross-links are required where pages reference each other (e.g., if disk-ceiling.md links to invariants.md#inv-04, then invariants.md should link to disk-ceiling.md).

Tables¶

Prefer Markdown tables over HTML. Table cells and heading lines are exempt from the 200-character line length limit (configured in .markdownlint.yml).

| Symbol | Signature | Description |
|---|---|---|
| `Put` | `func Put(ctx, key, value) error` | Stores a value under the disk ceiling. |

Generated vs Hand-Edited Content¶

Location	Status	Rule
`docs/_generated/`	Auto-generated	Never hand-edit — regenerate with `make docs-gen`
`docs/_meta/pkg-to-page.yaml`	Hand-edited	Always PR-reviewed; use `seed-pkg-map.sh` only as a draft seed
All other `docs/` pages	Hand-edited	May link to generated content; never embed it inline

Adding a New Page¶

Create docs/<section>/<page>.md with required front matter.
Add the filename (without .md) to the {toctree} in docs/<section>/index.md.
If the page documents a Go package, add an entry to docs/_meta/pkg-to-page.yaml.
Run make docs to verify the build succeeds, then make docs-freshness and make docs-coverage-gate.

Mermaid Diagrams¶

Pages containing Mermaid diagrams must include the air-gap warning admonition:

!!! warning "Mermaid diagrams require JavaScript"
    Diagrams on this page use [Mermaid](https://mermaid.js.org/) rendered via
    `sphinxcontrib-mermaid`. They require JavaScript to be enabled and, in
    non-air-gapped environments, an outbound connection to `cdn.jsdelivr.net`
    (pinned to mermaid.js 10.2.0 via `mermaid_version` in `docs/conf.py`).
    In air-gapped deployments, host `mermaid.min.js` locally and update
    `mermaid_version` to point to the local path.

Use the default Mermaid theme. Custom hex colours are reserved for trust-boundary diagrams (e.g., style A fill:#e8f5e9).

Parameterization¶

This documentation was structured from the Edge Capability Workplan (v0.6). When adapting for a different capability, substitute these placeholders:

Placeholder (in docs)	Replace with
`edged`	Your daemon binary name
`edgectl`	Your control CLI name
`edge` (in paths, slugs)	Your capability slug
`tutorial-fast-path.md`	`first-<capability>.md`
`edge-layer.md`	`<capability>-layer.md`
`{{CAPABILITY}}`	Your capability name
`INV-01..INV-13`	Your invariant set

Linting Locally¶

# Markdown style check
npx markdownlint-cli2 --config .markdownlint.yml "docs/**/*.md"

# Full docs build (strict — promotes all warnings to errors)
make docs-lint

# Verify all mapped pages exist on disk
make docs-freshness

# Verify all packages are mapped
make docs-coverage-gate

Review Checklist for Doc PRs¶

Front matter complete: title, owner, last_verified, source
No broken internal links (make docs-lint passes htmltest)
If a new package was added: pkg-to-page.yaml entry present
If a new page was added: {toctree} entry in docs/<section>/index.md
 markers used only on safe, generic commands
!!! danger used for invariant violations and security non-negotiables
docs/_generated/ files not hand-edited
Canonical-source rule: if the PR changes a user-visible claim the website also makes, PR description links the companion PR in the website source repo (or states none required).

Do Not Do¶

❌ Do NOT hand-edit docs/_generated/ — these files are regenerated by make docs-gen
❌ Do NOT use absolute URLs for internal links — they break offline and staged deployments
❌ Do NOT add indented code blocks — use fenced blocks (MD046: style: fenced)
❌ Do NOT put  on commands that require Docker, a running service, or network access
❌ Do NOT omit the Mermaid air-gap warning admonition on pages with Mermaid diagrams
❌ Do NOT restate canonical product/technical claims on marketing surfaces — link to the canonical docs-repo page instead