Documentation Automation Agent Guidelines

This file governs automated documentation updates triggered by code changes. All automation phases must comply with these rules.

Repository Context

This is the Zed code editor repository, a Rust-based application using the custom GPUI UI framework. The project is a large monorepo with ~200 crates organized under crates/. Documentation is built with mdBook and uses a custom preprocessor (docs_preprocessor) that handles special syntax like {#kb action::Name} for keybindings. The documentation source is in docs/src/ with a table of contents in SUMMARY.md, and all docs must pass Prettier formatting (80 char line width). The style guide (docs/.rules) and agent guidelines (docs/AGENTS.md) provide specific conventions for documentation writing.

Documentation System

This documentation uses mdBook (https://rust-lang.github.io/mdBook/).

Key Files

• docs/src/SUMMARY.md: Table of contents following mdBook format (https://rust-lang.github.io/mdBook/format/summary.html)
• docs/book.toml: mdBook configuration
• docs/.prettierrc: Prettier config (80 char line width)

SUMMARY.md Format

The SUMMARY.md file defines the book structure. Format rules:

• Chapter titles are links: [Title](./path/to/file.md)
• Nesting via indentation (2 spaces per level)
• Separators: --- for horizontal rules between sections
• Draft chapters: [Title]() (empty parens, not yet written)

Example:

# Section Title

- [Chapter](./chapter.md)
  - [Nested Chapter](./nested.md)

---

# Another Section

Custom Preprocessor

The docs use a custom preprocessor (docs_preprocessor) that expands special commands:

Rules:

• Always use preprocessor syntax for keybindings instead of hardcoding
• Action names use snake_case in the namespace, PascalCase for the action
• Common namespaces: agent::, editor::, assistant::, vim::

Formatting Requirements

All documentation must pass Prettier formatting:

cd docs && npx prettier --check src/

Before any documentation change is considered complete:

1. Run Prettier to format: cd docs && npx prettier --write src/
2. Verify it passes: cd docs && npx prettier --check src/

Prettier config: 80 character line width (docs/.prettierrc)

Section Anchors

Use {#anchor-id} syntax for linkable section headers:

## Getting Started {#getting-started}

### Custom Models {#anthropic-custom-models}

Anchor IDs should be:

• Lowercase with hyphens
• Unique within the page
• Descriptive (can include parent context like anthropic-custom-models)

Code Block Annotations

Use annotations after the language identifier to indicate file context:

\`\`\`json [settings]
{
"agent": { ... }
}
\`\`\`

\`\`\`json [keymap]
[
{ "bindings": { ... } }
]
\`\`\`

Valid annotations: [settings] (for settings.json), [keymap] (for keymap.json)

Blockquote Formatting

Use bold labels for callouts:

> **Note:** Important information the user should know.

> **Tip:** Helpful advice that saves time or improves workflow.

> **Warn:** Caution about potential issues or gotchas.

Image References

Images are hosted externally. Reference format:

![Alt text description](https://zed.dev/img/path/to/image.webp)

Cross-Linking

• Relative links for same-directory: [Agent Panel](./agent-panel.md)
• With anchors: [Custom Models](./llm-providers.md#anthropic-custom-models)
• Parent directory: [Telemetry](../telemetry.md)

Scope

In-Scope Documentation

• All Markdown files in docs/src/
• docs/src/SUMMARY.md (mdBook table of contents)
• Language-specific docs in docs/src/languages/
• Feature docs (AI, extensions, configuration, etc.)

Out-of-Scope (Do Not Modify)

• CHANGELOG.md, CONTRIBUTING.md, README.md at repo root
• Inline code comments and rustdoc
• CLAUDE.md, GEMINI.md, or other AI instruction files
• Build configuration (book.toml, theme files, docs_preprocessor)
• Any file outside docs/src/

Page Structure Patterns

Standard Page Layout

Most documentation pages follow this structure:

1. Title (H1) - Single sentence or phrase
2. Overview/Introduction - 1-3 paragraphs explaining what this is
3. Getting Started {#getting-started} - Prerequisites and first steps
4. Main Content - Feature details, organized by topic
5. Advanced/Configuration - Power user options
6. See Also (optional) - Related documentation links

Settings Documentation Pattern

When documenting settings:

1. Show the Settings Editor (UI) approach first
2. Then show JSON as "Or add this to your settings.json:"
3. Always show complete, valid JSON with surrounding structure:

{
  "agent": {
    "default_model": {
      "provider": "anthropic",
      "model": "claude-sonnet-4"
    }
  }
}

Provider/Feature Documentation Pattern

For each provider or distinct feature:

1. H3 heading with anchor: ### Provider Name {#provider-name}
2. Brief description (1-2 sentences)
3. Setup steps (numbered list)
4. Configuration example (JSON code block)
5. Custom models section if applicable: #### Custom Models {#provider-custom-models}

Style Rules

Inherit all conventions from docs/.rules. Key points:

Voice

• Second person ("you"), present tense
• Direct and concise—no hedging ("simply", "just", "easily")
• Honest about limitations; no promotional language

Formatting

• Keybindings: backticks with + for simultaneous keys (Cmd+Shift+P)
• Show both macOS and Linux/Windows variants when they differ
• Use sh code blocks for terminal commands
• Settings: show Settings Editor UI first, JSON as secondary

Terminology

Zed-Specific Conventions

Recognized Rules Files

When documenting rules/instructions for AI, note that Zed recognizes these files (in priority order):

• .rules
• .cursorrules
• .windsurfrules
• .clinerules
• .github/copilot-instructions.md
• AGENT.md
• AGENTS.md
• CLAUDE.md
• GEMINI.md

Settings File Locations

• macOS: ~/.config/zed/settings.json
• Linux: ~/.config/zed/settings.json
• Windows: %AppData%\Zed\settings.json

Keymap File Locations

• macOS: ~/.config/zed/keymap.json
• Linux: ~/.config/zed/keymap.json
• Windows: %AppData%\Zed\keymap.json

Safety Constraints

Must Not

• Delete existing documentation files
• Remove sections documenting existing functionality
• Change URLs or anchor links without verifying references
• Modify SUMMARY.md structure without corresponding content
• Add speculative documentation for unreleased features
• Include internal implementation details not relevant to users

Must

• Preserve existing structure when updating content
• Maintain backward compatibility of documented settings/commands
• Flag uncertainty explicitly rather than guessing
• Link to related documentation when adding new sections

Change Classification

Requires Documentation Update

• New user-facing features or commands
• Changed keybindings or default behaviors
• Modified settings schema or options
• Deprecated or removed functionality
• API changes affecting extensions

Does Not Require Documentation Update

• Internal refactoring without behavioral changes
• Performance optimizations (unless user-visible)
• Bug fixes that restore documented behavior
• Test changes
• CI/CD changes

Output Format

Phase 4 Documentation Plan

When generating a documentation plan, use this structure:

## Documentation Impact Assessment

### Summary

Brief description of code changes analyzed.

### Documentation Updates Required: [Yes/No]

### Planned Changes

#### 1. [File Path]

- **Section**: [Section name or "New section"]
- **Change Type**: [Update/Add/Deprecate]
- **Reason**: Why this change is needed
- **Description**: What will be added/modified

#### 2. [File Path]

...

### Uncertainty Flags

- [ ] [Description of any assumptions or areas needing confirmation]

### No Changes Needed

- [List files reviewed but not requiring updates, with brief reason]

Phase 6 Summary Format

## Documentation Update Summary

### Changes Made

| File           | Change            | Related Code      |
| -------------- | ----------------- | ----------------- |
| path/to/doc.md | Brief description | link to PR/commit |

### Rationale

Brief explanation of why these updates were made.

### Review Notes

Any items reviewers should pay special attention to.

Behavioral Guidelines

Conservative by Default

• When uncertain whether to document something, flag it for human review
• Prefer smaller, focused updates over broad rewrites
• Do not "improve" documentation unrelated to the triggering code change

Traceability

• Every documentation change should trace to a specific code change
• Include references to relevant commits, PRs, or issues in summaries

Incremental Updates

• Update existing sections rather than creating parallel documentation
• Maintain consistency with surrounding content
• Follow the established patterns in each documentation area