Docs Standards

Structure

• Title (H1) → Warning/callout → Try this code → Overview → HR → Content (H2 sections)

Test Sync Rule

• Always update test assertions: When adding docs pages to features/, scenarios/, guides/, update corresponding EXPECTED_* arrays in test/docs-build.test.ts in the same commit

Examples

✓ Correct:

# Getting started with Squad

> ⚠️ **Experimental:** This feature is in preview.

Try this:
\`\`\`bash
squad init
\`\`\`

Squad helps you build AI teams...

---

## Install Squad

Run the following command...

✗ Incorrect:

# Getting Started With Squad  // Title case

Squad is a tool which will help users... // Third person, future tense

You can install Squad with npm & configure it... // Ampersand in prose

Anti-Patterns

• Title-casing headings because "it looks nicer"
• Writing in passive voice or third person
• Long paragraphs of dense text (breaks scannability)
• Adding doc pages without updating test assertions
• Using ampersands outside code blocks