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