Detailed changes
@@ -0,0 +1,55 @@
+# Phase 2: Explore Repository
+
+You are analyzing a codebase to understand its structure before reviewing documentation impact.
+
+## Objective
+Produce a structured overview of the repository to inform subsequent documentation analysis.
+
+## Instructions
+
+1. **Identify Primary Languages and Frameworks**
+ - Scan for Cargo.toml, package.json, or other manifest files
+ - Note the primary language(s) and key dependencies
+
+2. **Map Documentation Structure**
+ - This project uses **mdBook** (https://rust-lang.github.io/mdBook/)
+ - Documentation is in `docs/src/`
+ - Table of contents: `docs/src/SUMMARY.md` (mdBook format: https://rust-lang.github.io/mdBook/format/summary.html)
+ - Style guide: `docs/.rules`
+ - Agent guidelines: `docs/AGENTS.md`
+ - Formatting: Prettier (config in `docs/.prettierrc`)
+
+3. **Identify Build and Tooling**
+ - Note build systems (cargo, npm, etc.)
+ - Identify documentation tooling (mdbook, etc.)
+
+4. **Output Format**
+Produce a JSON summary:
+
+```json
+{
+ "primary_language": "Rust",
+ "frameworks": ["GPUI"],
+ "documentation": {
+ "system": "mdBook",
+ "location": "docs/src/",
+ "toc_file": "docs/src/SUMMARY.md",
+ "toc_format": "https://rust-lang.github.io/mdBook/format/summary.html",
+ "style_guide": "docs/.rules",
+ "agent_guidelines": "docs/AGENTS.md",
+ "formatter": "prettier",
+ "formatter_config": "docs/.prettierrc",
+ "custom_preprocessor": "docs_preprocessor (handles {#kb action::Name} syntax)"
+ },
+ "key_directories": {
+ "source": "crates/",
+ "docs": "docs/src/",
+ "extensions": "extensions/"
+ }
+}
+```
+
+## Constraints
+- Read-only: Do not modify any files
+- Focus on structure, not content details
+- Complete within 2 minutes
@@ -0,0 +1,57 @@
+# Phase 3: Analyze Changes
+
+You are analyzing code changes to understand their nature and scope.
+
+## Objective
+Produce a clear, neutral summary of what changed in the codebase.
+
+## Input
+You will receive:
+- List of changed files from the triggering commit/PR
+- Repository structure from Phase 2
+
+## Instructions
+
+1. **Categorize Changed Files**
+ - Source code (which crates/modules)
+ - Configuration
+ - Tests
+ - Documentation (already existing)
+ - Other
+
+2. **Analyze Each Change**
+ - Review diffs for files likely to impact documentation
+ - Focus on: public APIs, settings, keybindings, commands, user-visible behavior
+
+3. **Identify What Did NOT Change**
+ - Note stable interfaces or behaviors
+ - Important for avoiding unnecessary documentation updates
+
+4. **Output Format**
+Produce a markdown summary:
+
+```markdown
+## Change Analysis
+
+### Changed Files Summary
+| Category | Files | Impact Level |
+| --- | --- | --- |
+| Source - [crate] | file1.rs, file2.rs | High/Medium/Low |
+| Settings | settings.json | Medium |
+| Tests | test_*.rs | None |
+
+### Behavioral Changes
+- **[Feature/Area]**: Description of what changed from user perspective
+- **[Feature/Area]**: Description...
+
+### Unchanged Areas
+- [Area]: Confirmed no changes to [specific behavior]
+
+### Files Requiring Deeper Review
+- `path/to/file.rs`: Reason for deeper review
+```
+
+## Constraints
+- Read-only: Do not modify any files
+- Neutral tone: Describe what changed, not whether it's good/bad
+- Do not propose documentation changes yet
@@ -0,0 +1,76 @@
+# Phase 4: Plan Documentation Impact
+
+You are determining whether and how documentation should be updated based on code changes.
+
+## Objective
+Produce a structured documentation plan that will guide Phase 5 execution.
+
+## Documentation System
+This is an **mdBook** site (https://rust-lang.github.io/mdBook/):
+- `docs/src/SUMMARY.md` defines book structure per https://rust-lang.github.io/mdBook/format/summary.html
+- If adding new pages, they MUST be added to SUMMARY.md
+- Use `{#kb action::ActionName}` syntax for keybindings (custom preprocessor expands these)
+- Prettier formatting (80 char width) will be applied automatically
+
+## Input
+You will receive:
+- Change analysis from Phase 3
+- Repository structure from Phase 2
+- Documentation guidelines from `docs/AGENTS.md`
+
+## Instructions
+
+1. **Review AGENTS.md**
+ - Load and apply all rules from `docs/AGENTS.md`
+ - Respect scope boundaries (in-scope vs out-of-scope)
+
+2. **Evaluate Documentation Impact**
+ For each behavioral change from Phase 3:
+ - Does existing documentation cover this area?
+ - Is the documentation now inaccurate or incomplete?
+ - Classify per AGENTS.md "Change Classification" section
+
+3. **Identify Specific Updates**
+ For each required update:
+ - Exact file path
+ - Specific section or heading
+ - Type of change (update existing, add new, deprecate)
+ - Description of the change
+
+4. **Flag Uncertainty**
+ Explicitly mark:
+ - Assumptions you're making
+ - Areas where human confirmation is needed
+ - Ambiguous requirements
+
+5. **Output Format**
+Use the exact format specified in `docs/AGENTS.md` Phase 4 section:
+
+```markdown
+## 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
+
+### Uncertainty Flags
+- [ ] [Description of any assumptions or areas needing confirmation]
+
+### No Changes Needed
+- [List files reviewed but not requiring updates, with brief reason]
+```
+
+## Constraints
+- Read-only: Do not modify any files
+- Conservative: When uncertain, flag for human review rather than planning changes
+- Scoped: Only plan changes that trace directly to code changes from Phase 3
+- No scope expansion: Do not plan "improvements" unrelated to triggering changes
@@ -0,0 +1,67 @@
+# Phase 5: Apply Documentation Plan
+
+You are executing a pre-approved documentation plan for an **mdBook** documentation site.
+
+## Objective
+Implement exactly the changes specified in the documentation plan from Phase 4.
+
+## Documentation System
+- **mdBook**: https://rust-lang.github.io/mdBook/
+- **SUMMARY.md**: Follows mdBook format (https://rust-lang.github.io/mdBook/format/summary.html)
+- **Prettier**: Will be run automatically after this phase (80 char line width)
+- **Custom preprocessor**: Use `{#kb action::ActionName}` for keybindings instead of hardcoding
+
+## Input
+You will receive:
+- Documentation plan from Phase 4
+- Documentation guidelines from `docs/AGENTS.md`
+- Style rules from `docs/.rules`
+
+## Instructions
+
+1. **Validate Plan**
+ - Confirm all planned files are within scope per AGENTS.md
+ - Verify no out-of-scope files are targeted
+
+2. **Execute Each Planned Change**
+ For each item in "Planned Changes":
+ - Navigate to the specified file
+ - Locate the specified section
+ - Apply the described change
+ - Follow style rules from `docs/.rules`
+
+3. **Style Compliance**
+ Every edit must follow `docs/.rules`:
+ - Second person, present tense
+ - No hedging words ("simply", "just", "easily")
+ - Proper keybinding format (`Cmd+Shift+P`)
+ - Settings Editor first, JSON second
+ - Correct terminology (folder not directory, etc.)
+
+4. **Preserve Context**
+ - Maintain surrounding content structure
+ - Keep consistent heading levels
+ - Preserve existing cross-references
+
+## Constraints
+- Execute ONLY changes listed in the plan
+- Do not discover new documentation targets
+- Do not make stylistic improvements outside planned sections
+- Do not expand scope beyond what Phase 4 specified
+- If a planned change cannot be applied (file missing, section not found), skip and note it
+
+## Output
+After applying changes, output a summary:
+
+```markdown
+## Applied Changes
+
+### Successfully Applied
+- `path/to/file.md`: [Brief description of change]
+
+### Skipped (Could Not Apply)
+- `path/to/file.md`: [Reason - e.g., "Section not found"]
+
+### Warnings
+- [Any issues encountered during application]
+```
@@ -0,0 +1,54 @@
+# Phase 6: Summarize Changes
+
+You are generating a summary of documentation updates for PR review.
+
+## Objective
+Create a clear, reviewable summary of all documentation changes made.
+
+## Input
+You will receive:
+- Applied changes report from Phase 5
+- Original change analysis from Phase 3
+- Git diff of documentation changes
+
+## Instructions
+
+1. **Gather Change Information**
+ - List all modified documentation files
+ - Identify the corresponding code changes that triggered each update
+
+2. **Generate Summary**
+ Use the format specified in `docs/AGENTS.md` Phase 6 section:
+
+```markdown
+## Documentation Update Summary
+
+### Changes Made
+| File | Change | Related Code |
+| --- | --- | --- |
+| docs/src/path.md | Brief description | PR #123 or commit SHA |
+
+### Rationale
+Brief explanation of why these updates were made, linking back to the triggering code changes.
+
+### Review Notes
+- Items reviewers should pay special attention to
+- Any uncertainty flags from Phase 4 that were addressed
+- Assumptions made during documentation
+```
+
+3. **Add Context for Reviewers**
+ - Highlight any changes that might be controversial
+ - Note if any planned changes were skipped and why
+ - Flag areas where reviewer expertise is especially needed
+
+## Output Format
+The summary should be suitable for:
+- PR description body
+- Commit message (condensed version)
+- Team communication
+
+## Constraints
+- Read-only (documentation changes already applied in Phase 5)
+- Factual: Describe what was done, not justify why it's good
+- Complete: Account for all changes, including skipped items
@@ -0,0 +1,67 @@
+# Phase 7: Commit and Open PR
+
+You are creating a git branch, committing documentation changes, and opening a PR.
+
+## Objective
+Package documentation updates into a reviewable pull request.
+
+## Input
+You will receive:
+- Summary from Phase 6
+- List of modified files
+
+## Instructions
+
+1. **Create Branch**
+ ```sh
+ git checkout -b docs/auto-update-{date}
+ ```
+ Use format: `docs/auto-update-YYYY-MM-DD` or `docs/auto-update-{short-sha}`
+
+2. **Stage and Commit**
+ - Stage only documentation files in `docs/src/`
+ - Do not stage any other files
+
+ Commit message format:
+ ```
+ docs: auto-update documentation for [brief description]
+
+ [Summary from Phase 6, condensed]
+
+ Triggered by: [commit SHA or PR reference]
+
+ Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
+ ```
+
+3. **Push Branch**
+ ```sh
+ git push -u origin docs/auto-update-{date}
+ ```
+
+4. **Create Pull Request**
+ Use the Phase 6 summary as the PR body.
+
+ PR Title: `docs: [Brief description of documentation updates]`
+
+ Labels (if available): `documentation`, `automated`
+
+ Base branch: `main`
+
+## Constraints
+- Do NOT auto-merge
+- Do NOT request specific reviewers (let CODEOWNERS handle it)
+- Do NOT modify files outside `docs/src/`
+- If no changes to commit, exit gracefully with message "No documentation changes to commit"
+
+## Output
+```markdown
+## PR Created
+
+- **Branch**: docs/auto-update-{date}
+- **PR URL**: https://github.com/zed-industries/zed/pull/XXXX
+- **Status**: Ready for review
+
+### Commit
+- SHA: {commit-sha}
+- Files: {count} documentation files modified
+```
@@ -0,0 +1,256 @@
+name: Documentation Automation
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - 'crates/**'
+ - 'extensions/**'
+ workflow_dispatch:
+ inputs:
+ pr_number:
+ description: 'PR number to analyze (gets full PR diff)'
+ required: false
+ type: string
+ trigger_sha:
+ description: 'Commit SHA to analyze (ignored if pr_number is set)'
+ required: false
+ type: string
+
+permissions:
+ contents: write
+ pull-requests: write
+
+env:
+ FACTORY_API_KEY: ${{ secrets.FACTORY_API_KEY }}
+ DROID_MODEL: claude-opus-4-5
+
+jobs:
+ docs-automation:
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+
+ - name: Install Droid CLI
+ run: |
+ curl -fsSL https://cli.factory.ai/install.sh | bash
+ echo "${HOME}/.factory/bin" >> "$GITHUB_PATH"
+
+ - name: Setup Node.js (for Prettier)
+ uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+
+ - name: Install Prettier
+ run: npm install -g prettier
+
+ - name: Get changed files
+ id: changed
+ run: |
+ if [ -n "${{ inputs.pr_number }}" ]; then
+ # Get full PR diff
+ echo "Analyzing PR #${{ inputs.pr_number }}"
+ echo "source=pr" >> "$GITHUB_OUTPUT"
+ echo "ref=${{ inputs.pr_number }}" >> "$GITHUB_OUTPUT"
+ gh pr diff "${{ inputs.pr_number }}" --name-only > /tmp/changed_files.txt
+ elif [ -n "${{ inputs.trigger_sha }}" ]; then
+ # Get single commit diff
+ SHA="${{ inputs.trigger_sha }}"
+ echo "Analyzing commit $SHA"
+ echo "source=commit" >> "$GITHUB_OUTPUT"
+ echo "ref=$SHA" >> "$GITHUB_OUTPUT"
+ git diff --name-only "${SHA}^" "$SHA" > /tmp/changed_files.txt
+ else
+ # Default to current commit
+ SHA="${{ github.sha }}"
+ echo "Analyzing commit $SHA"
+ echo "source=commit" >> "$GITHUB_OUTPUT"
+ echo "ref=$SHA" >> "$GITHUB_OUTPUT"
+ git diff --name-only "${SHA}^" "$SHA" > /tmp/changed_files.txt || git diff --name-only HEAD~1 HEAD > /tmp/changed_files.txt
+ fi
+
+ echo "Changed files:"
+ cat /tmp/changed_files.txt
+ env:
+ GH_TOKEN: ${{ github.token }}
+
+ # Phase 0: Guardrails are loaded via AGENTS.md in each phase
+
+ # Phase 2: Explore Repository (Read-Only)
+ - name: "Phase 2: Explore Repository"
+ id: phase2
+ run: |
+ droid exec \
+ --model "$DROID_MODEL" \
+ --autonomy read-only \
+ --prompt-file .factory/prompts/docs-automation/phase2-explore.md \
+ --output /tmp/phase2-output.json \
+ --format json
+ echo "Repository exploration complete"
+ cat /tmp/phase2-output.json
+
+ # Phase 3: Analyze Changes (Read-Only)
+ - name: "Phase 3: Analyze Changes"
+ id: phase3
+ run: |
+ CHANGED_FILES=$(tr '\n' ' ' < /tmp/changed_files.txt)
+ droid exec \
+ --model "$DROID_MODEL" \
+ --autonomy read-only \
+ --prompt-file .factory/prompts/docs-automation/phase3-analyze.md \
+ --context "Changed files: $CHANGED_FILES" \
+ --context-file /tmp/phase2-output.json \
+ --output /tmp/phase3-output.md \
+ --format markdown
+ echo "Change analysis complete"
+ cat /tmp/phase3-output.md
+
+ # Phase 4: Plan Documentation Impact (Read-Only)
+ - name: "Phase 4: Plan Documentation Impact"
+ id: phase4
+ run: |
+ droid exec \
+ --model "$DROID_MODEL" \
+ --autonomy read-only \
+ --prompt-file .factory/prompts/docs-automation/phase4-plan.md \
+ --context-file /tmp/phase3-output.md \
+ --context-file docs/AGENTS.md \
+ --output /tmp/phase4-plan.md \
+ --format markdown
+ echo "Documentation plan complete"
+ cat /tmp/phase4-plan.md
+
+ # Check if updates are required
+ if grep -q "Documentation Updates Required: No" /tmp/phase4-plan.md; then
+ echo "updates_required=false" >> "$GITHUB_OUTPUT"
+ else
+ echo "updates_required=true" >> "$GITHUB_OUTPUT"
+ fi
+
+ # Phase 5: Apply Plan (Write-Enabled)
+ - name: "Phase 5: Apply Documentation Plan"
+ id: phase5
+ if: steps.phase4.outputs.updates_required == 'true'
+ run: |
+ droid exec \
+ --model "$DROID_MODEL" \
+ --autonomy medium \
+ --prompt-file .factory/prompts/docs-automation/phase5-apply.md \
+ --context-file /tmp/phase4-plan.md \
+ --context-file docs/AGENTS.md \
+ --context-file docs/.rules \
+ --output /tmp/phase5-report.md \
+ --format markdown
+ echo "Documentation updates applied"
+ cat /tmp/phase5-report.md
+
+ # Phase 5b: Format with Prettier
+ - name: "Phase 5b: Format with Prettier"
+ id: phase5b
+ if: steps.phase4.outputs.updates_required == 'true'
+ run: |
+ echo "Formatting documentation with Prettier..."
+ cd docs && prettier --write src/
+
+ echo "Verifying Prettier formatting passes..."
+ cd docs && prettier --check src/
+
+ echo "Prettier formatting complete"
+
+ # Phase 6: Summarize Changes
+ - name: "Phase 6: Summarize Changes"
+ id: phase6
+ if: steps.phase4.outputs.updates_required == 'true'
+ run: |
+ # Get git diff of docs
+ git diff docs/src/ > /tmp/docs-diff.txt || true
+
+ droid exec \
+ --model "$DROID_MODEL" \
+ --autonomy read-only \
+ --prompt-file .factory/prompts/docs-automation/phase6-summarize.md \
+ --context-file /tmp/phase5-report.md \
+ --context-file /tmp/phase3-output.md \
+ --context "Trigger SHA: ${{ steps.changed.outputs.sha }}" \
+ --output /tmp/phase6-summary.md \
+ --format markdown
+ echo "Summary generated"
+ cat /tmp/phase6-summary.md
+
+ # Phase 7: Commit and Open PR
+ - name: "Phase 7: Create PR"
+ id: phase7
+ if: steps.phase4.outputs.updates_required == 'true'
+ run: |
+ # Check if there are actual changes
+ if git diff --quiet docs/src/; then
+ echo "No documentation changes detected"
+ exit 0
+ fi
+
+ # Configure git
+ git config user.name "factory-droid[bot]"
+ git config user.email "138933559+factory-droid[bot]@users.noreply.github.com"
+
+ # Daily batch branch - one branch per day, multiple commits accumulate
+ BRANCH_NAME="docs/auto-update-$(date +%Y-%m-%d)"
+
+ # Check if branch already exists on remote
+ if git ls-remote --exit-code --heads origin "$BRANCH_NAME" > /dev/null 2>&1; then
+ echo "Branch $BRANCH_NAME exists, checking out and updating..."
+ git fetch origin "$BRANCH_NAME"
+ git checkout -B "$BRANCH_NAME" "origin/$BRANCH_NAME"
+ else
+ echo "Creating new branch $BRANCH_NAME..."
+ git checkout -b "$BRANCH_NAME"
+ fi
+
+ # Stage and commit
+ git add docs/src/
+ SUMMARY=$(head -50 < /tmp/phase6-summary.md)
+ git commit -m "docs: auto-update documentation
+
+ ${SUMMARY}
+
+ Triggered by: ${{ steps.changed.outputs.source }} ${{ steps.changed.outputs.ref }}
+
+ Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>"
+
+ # Push
+ git push -u origin "$BRANCH_NAME"
+
+ # Check if PR already exists for this branch
+ EXISTING_PR=$(gh pr list --head "$BRANCH_NAME" --json number --jq '.[0].number' || echo "")
+
+ if [ -n "$EXISTING_PR" ]; then
+ echo "PR #$EXISTING_PR already exists for branch $BRANCH_NAME, updated with new commit"
+ else
+ # Create new PR
+ gh pr create \
+ --title "docs: automated documentation update ($(date +%Y-%m-%d))" \
+ --body-file /tmp/phase6-summary.md \
+ --base main || true
+ echo "PR created on branch: $BRANCH_NAME"
+ fi
+ env:
+ GH_TOKEN: ${{ github.token }}
+
+ # Summary output
+ - name: "Summary"
+ if: always()
+ run: |
+ echo "## Documentation Automation Summary" >> "$GITHUB_STEP_SUMMARY"
+ echo "" >> "$GITHUB_STEP_SUMMARY"
+
+ if [ "${{ steps.phase4.outputs.updates_required }}" == "false" ]; then
+ echo "No documentation updates required for this change." >> "$GITHUB_STEP_SUMMARY"
+ elif [ -f /tmp/phase6-summary.md ]; then
+ cat /tmp/phase6-summary.md >> "$GITHUB_STEP_SUMMARY"
+ else
+ echo "Workflow completed. Check individual phase outputs for details." >> "$GITHUB_STEP_SUMMARY"
+ fi
@@ -0,0 +1,353 @@
+# Documentation Automation Agent Guidelines
+
+This file governs automated documentation updates triggered by code changes. All automation phases must comply with these rules.
+
+## 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:
+
+```markdown
+# 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:
+
+| Syntax | Purpose | Example |
+| ----------------------------- | ------------------------------------- | ------------------------------- |
+| `{#kb action::ActionName}` | Keybinding for action | `{#kb agent::ToggleFocus}` |
+| `{#action agent::ActionName}` | Action reference (renders as command) | `{#action agent::OpenSettings}` |
+
+**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:
+
+```sh
+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:
+
+```markdown
+## 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:
+
+```markdown
+\`\`\`json [settings]
+{
+"agent": { ... }
+}
+\`\`\`
+
+\`\`\`json [keymap]
+[
+{ "bindings": { ... } }
+]
+\`\`\`
+```
+
+Valid annotations: `[settings]` (for settings.json), `[keymap]` (for keymap.json)
+
+### Blockquote Formatting
+
+Use bold labels for callouts:
+
+```markdown
+> **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:
+
+```markdown
+
+```
+
+### 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:
+
+```json [settings]
+{
+ "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
+
+| Use | Instead of |
+| --------------- | -------------------------------------- |
+| folder | directory |
+| project | workspace |
+| Settings Editor | settings UI |
+| command palette | command bar |
+| panel | sidebar (be specific: "Project Panel") |
+
+## 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:
+
+```markdown
+## 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
+
+```markdown
+## 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