1# Documentation Automation Agent Guidelines
2
3This file governs automated documentation updates triggered by code changes. All automation phases must comply with these rules.
4
5## Repository Context
6
7This 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.
8
9## Documentation System
10
11This documentation uses **mdBook** (https://rust-lang.github.io/mdBook/).
12
13### Key Files
14
15- **`docs/src/SUMMARY.md`**: Table of contents following mdBook format (https://rust-lang.github.io/mdBook/format/summary.html)
16- **`docs/book.toml`**: mdBook configuration
17- **`docs/.prettierrc`**: Prettier config (80 char line width)
18
19### SUMMARY.md Format
20
21The `SUMMARY.md` file defines the book structure. Format rules:
22
23- Chapter titles are links: `[Title](./path/to/file.md)`
24- Nesting via indentation (2 spaces per level)
25- Separators: `---` for horizontal rules between sections
26- Draft chapters: `[Title]()` (empty parens, not yet written)
27
28Example:
29
30```markdown
31# Section Title
32
33- [Chapter](./chapter.md)
34 - [Nested Chapter](./nested.md)
35
36---
37
38# Another Section
39```
40
41### Custom Preprocessor
42
43The docs use a custom preprocessor (`docs_preprocessor`) that expands special commands:
44
45| Syntax | Purpose | Example |
46| ----------------------------- | ------------------------------------- | ------------------------------- |
47| `{#kb action::ActionName}` | Keybinding for action | `{#kb agent::ToggleFocus}` |
48| `{#action agent::ActionName}` | Action reference (renders as command) | `{#action agent::OpenSettings}` |
49
50**Rules:**
51
52- Always use preprocessor syntax for keybindings instead of hardcoding
53- Action names use `snake_case` in the namespace, `PascalCase` for the action
54- Common namespaces: `agent::`, `editor::`, `assistant::`, `vim::`
55
56### Formatting Requirements
57
58All documentation must pass **Prettier** formatting:
59
60```sh
61cd docs && npx prettier --check src/
62```
63
64Before any documentation change is considered complete:
65
661. Run Prettier to format: `cd docs && npx prettier --write src/`
672. Verify it passes: `cd docs && npx prettier --check src/`
68
69Prettier config: 80 character line width (`docs/.prettierrc`)
70
71### Section Anchors
72
73Use `{#anchor-id}` syntax for linkable section headers:
74
75```markdown
76## Getting Started {#getting-started}
77
78### Custom Models {#anthropic-custom-models}
79```
80
81Anchor IDs should be:
82
83- Lowercase with hyphens
84- Unique within the page
85- Descriptive (can include parent context like `anthropic-custom-models`)
86
87### Code Block Annotations
88
89Use annotations after the language identifier to indicate file context:
90
91```markdown
92\`\`\`json [settings]
93{
94"agent": { ... }
95}
96\`\`\`
97
98\`\`\`json [keymap]
99[
100{ "bindings": { ... } }
101]
102\`\`\`
103```
104
105Valid annotations: `[settings]` (for settings.json), `[keymap]` (for keymap.json)
106
107### Blockquote Formatting
108
109Use bold labels for callouts:
110
111```markdown
112> **Note:** Important information the user should know.
113
114> **Tip:** Helpful advice that saves time or improves workflow.
115
116> **Warn:** Caution about potential issues or gotchas.
117```
118
119### Image References
120
121Images are hosted externally. Reference format:
122
123```markdown
124
125```
126
127### Cross-Linking
128
129- Relative links for same-directory: `[Agent Panel](./agent-panel.md)`
130- With anchors: `[Custom Models](./llm-providers.md#anthropic-custom-models)`
131- Parent directory: `[Telemetry](../telemetry.md)`
132
133## Scope
134
135### In-Scope Documentation
136
137- All Markdown files in `docs/src/`
138- `docs/src/SUMMARY.md` (mdBook table of contents)
139- Language-specific docs in `docs/src/languages/`
140- Feature docs (AI, extensions, configuration, etc.)
141
142### Out-of-Scope (Do Not Modify)
143
144- `CHANGELOG.md`, `CONTRIBUTING.md`, `README.md` at repo root
145- Inline code comments and rustdoc
146- `CLAUDE.md`, `GEMINI.md`, or other AI instruction files
147- Build configuration (`book.toml`, theme files, `docs_preprocessor`)
148- Any file outside `docs/src/`
149
150## Page Structure Patterns
151
152### Standard Page Layout
153
154Most documentation pages follow this structure:
155
1561. **Title** (H1) - Single sentence or phrase
1572. **Overview/Introduction** - 1-3 paragraphs explaining what this is
1583. **Getting Started** `{#getting-started}` - Prerequisites and first steps
1594. **Main Content** - Feature details, organized by topic
1605. **Advanced/Configuration** - Power user options
1616. **See Also** (optional) - Related documentation links
162
163### Settings Documentation Pattern
164
165When documenting settings:
166
1671. Show the Settings Editor (UI) approach first
1682. Then show JSON as "Or add this to your settings.json:"
1693. Always show complete, valid JSON with surrounding structure:
170
171```json [settings]
172{
173 "agent": {
174 "default_model": {
175 "provider": "anthropic",
176 "model": "claude-sonnet-4"
177 }
178 }
179}
180```
181
182### Provider/Feature Documentation Pattern
183
184For each provider or distinct feature:
185
1861. H3 heading with anchor: `### Provider Name {#provider-name}`
1872. Brief description (1-2 sentences)
1883. Setup steps (numbered list)
1894. Configuration example (JSON code block)
1905. Custom models section if applicable: `#### Custom Models {#provider-custom-models}`
191
192## Style Rules
193
194Inherit all conventions from `docs/.rules`. Key points:
195
196### Voice
197
198- Second person ("you"), present tense
199- Direct and concise—no hedging ("simply", "just", "easily")
200- Honest about limitations; no promotional language
201
202### Formatting
203
204- Keybindings: backticks with `+` for simultaneous keys (`Cmd+Shift+P`)
205- Show both macOS and Linux/Windows variants when they differ
206- Use `sh` code blocks for terminal commands
207- Settings: show Settings Editor UI first, JSON as secondary
208
209### Terminology
210
211| Use | Instead of |
212| --------------- | -------------------------------------- |
213| folder | directory |
214| project | workspace |
215| Settings Editor | settings UI |
216| command palette | command bar |
217| panel | sidebar (be specific: "Project Panel") |
218
219## Zed-Specific Conventions
220
221### Recognized Rules Files
222
223When documenting rules/instructions for AI, note that Zed recognizes these files (in priority order):
224
225- `.rules`
226- `.cursorrules`
227- `.windsurfrules`
228- `.clinerules`
229- `.github/copilot-instructions.md`
230- `AGENT.md`
231- `AGENTS.md`
232- `CLAUDE.md`
233- `GEMINI.md`
234
235### Settings File Locations
236
237- macOS: `~/.config/zed/settings.json`
238- Linux: `~/.config/zed/settings.json`
239- Windows: `%AppData%\Zed\settings.json`
240
241### Keymap File Locations
242
243- macOS: `~/.config/zed/keymap.json`
244- Linux: `~/.config/zed/keymap.json`
245- Windows: `%AppData%\Zed\keymap.json`
246
247## Safety Constraints
248
249### Must Not
250
251- Delete existing documentation files
252- Remove sections documenting existing functionality
253- Change URLs or anchor links without verifying references
254- Modify `SUMMARY.md` structure without corresponding content
255- Add speculative documentation for unreleased features
256- Include internal implementation details not relevant to users
257
258### Must
259
260- Preserve existing structure when updating content
261- Maintain backward compatibility of documented settings/commands
262- Flag uncertainty explicitly rather than guessing
263- Link to related documentation when adding new sections
264
265## Change Classification
266
267### Requires Documentation Update
268
269- New user-facing features or commands
270- Changed keybindings or default behaviors
271- Modified settings schema or options
272- Deprecated or removed functionality
273- API changes affecting extensions
274
275### Does Not Require Documentation Update
276
277- Internal refactoring without behavioral changes
278- Performance optimizations (unless user-visible)
279- Bug fixes that restore documented behavior
280- Test changes
281- CI/CD changes
282
283## Output Format
284
285### Phase 4 Documentation Plan
286
287When generating a documentation plan, use this structure:
288
289```markdown
290## Documentation Impact Assessment
291
292### Summary
293
294Brief description of code changes analyzed.
295
296### Documentation Updates Required: [Yes/No]
297
298### Planned Changes
299
300#### 1. [File Path]
301
302- **Section**: [Section name or "New section"]
303- **Change Type**: [Update/Add/Deprecate]
304- **Reason**: Why this change is needed
305- **Description**: What will be added/modified
306
307#### 2. [File Path]
308
309...
310
311### Uncertainty Flags
312
313- [ ] [Description of any assumptions or areas needing confirmation]
314
315### No Changes Needed
316
317- [List files reviewed but not requiring updates, with brief reason]
318```
319
320### Phase 6 Summary Format
321
322```markdown
323## Documentation Update Summary
324
325### Changes Made
326
327| File | Change | Related Code |
328| -------------- | ----------------- | ----------------- |
329| path/to/doc.md | Brief description | link to PR/commit |
330
331### Rationale
332
333Brief explanation of why these updates were made.
334
335### Review Notes
336
337Any items reviewers should pay special attention to.
338```
339
340## Behavioral Guidelines
341
342### Conservative by Default
343
344- When uncertain whether to document something, flag it for human review
345- Prefer smaller, focused updates over broad rewrites
346- Do not "improve" documentation unrelated to the triggering code change
347
348### Traceability
349
350- Every documentation change should trace to a specific code change
351- Include references to relevant commits, PRs, or issues in summaries
352
353### Incremental Updates
354
355- Update existing sections rather than creating parallel documentation
356- Maintain consistency with surrounding content
357- Follow the established patterns in each documentation area