This file is the canonical instruction set for AI tools (Claude Code,
Cursor, Codex, Copilot, and any other agent that reads AGENTS.md from a
repo root) working on the Apollo documentation site at
wiki.apolloautomation.com.
If you're using Claude Code, CLAUDE.md exists as a pointer to this
file. Read this one.
Read STYLE_GUIDE.md. It is the source of truth for tone, language, terminology, voice, and formatting. The style guide is prescriptive, not advisory.
For workflow (branching, previewing, opening PRs, file layout), see CONTRIBUTING.md. Key points:
- All edits target the
devbranch, nevermain. - Maintainers merge
dev → mainto publish to the live wiki. - Run
mkdocs serveto preview locally before opening a PR. - Run
mkdocs buildto catch broken internal links before pushing.
Read the full style guide, but these are the ones worth checking twice:
- Product IDs are uppercase with a hyphen: AIR-1, MTR-1, never
Air-1orair1. - Apollo addons (hardware modules) and Home Assistant apps (formerly add-ons) are different things and not interchangeable.
- ESPHome is the only correct casing.
- No em dashes anywhere in user-facing copy.
- Second person, imperative voice for action copy. Wrap numbered steps with framing copy (what the reader unlocks, what success looks like).
- Avoid corporate filler: simply, just, easy, powerful, seamlessly.
If you notice a recurring pattern that should be standardized but isn't
in STYLE_GUIDE.md, surface it to the user before applying it in the
current edit. Examples:
- A new product name or capitalization that isn't covered by the naming rules.
- A formatting convention you're about to use repeatedly (a new admonition type, a new way of showing CLI output) that future contributors should follow.
- A drift between pages where the guide is ambiguous about which pattern wins.
Propose the addition to STYLE_GUIDE.md in the same PR (or a separate
follow-up if it's substantial). The goal is for the guide to stay ahead
of the docs, not behind them.
One-off stylistic choices on a single page don't need a suggestion. This is about patterns that will repeat.