Detailed changes
@@ -0,0 +1,350 @@
+# Zed Documentation Conventions
+
+This document covers structural conventions for Zed documentation: what to document, how to organize it, and when to create new pages.
+
+For voice, tone, and writing style, see the [brand-voice/](./brand-voice/) directory, which contains:
+
+- `SKILL.md` β Core voice principles and workflow
+- `rubric.md` β 8-point scoring criteria for quality
+- `taboo-phrases.md` β Patterns and phrases to avoid
+- `voice-examples.md` β Before/after transformation examples
+
+---
+
+## What Needs Documentation
+
+### Document
+
+- **New user-facing features** β Anything users interact with directly
+- **New settings or configuration options** β Include the setting key, type, default value, and example
+- **New keybindings or commands** β Use `{#action ...}` and `{#kb ...}` syntax
+- **All actions** β Completeness matters; document every action, not just non-obvious ones
+- **New AI capabilities** β Agent tools, providers, workflows
+- **New providers or integrations** β LLM providers, MCP servers, external agents
+- **New tools** β Agent tools, MCP tools, built-in tools
+- **New UI panels or views** β Any new panel, sidebar, or view users interact with
+- **Public extension APIs** β For extension developers
+- **Breaking changes** β Even if the fix is simple, document what changed
+- **Version-specific behavior changes** β Include version callouts (e.g., "In Zed v0.224.0 and above...")
+
+### Skip
+
+- **Internal refactors** β No user-visible change, no docs
+- **Bug fixes** β Unless the fix reveals that existing docs were wrong
+- **Performance improvements** β Unless user-visible (e.g., startup time)
+- **Test changes** β Never document tests
+- **CI/tooling changes** β Internal infrastructure
+
+---
+
+## Page vs. Section Decisions
+
+### Create a new page when:
+
+- Introducing a **major feature** with multiple sub-features (e.g., Git integration, Vim mode)
+- The topic requires **extensive configuration examples**
+- Users would search for it **by name** (e.g., "Zed terminal", "Zed snippets")
+- It's a **new category** (e.g., a new AI provider type)
+
+### Add to an existing page when:
+
+- Adding a **setting** to a feature that already has a page
+- Adding a **keybinding** to an existing feature
+- The change is a **minor enhancement** to existing functionality
+- It's a **configuration option** for an existing feature
+
+### Examples
+
+| Change | Action |
+| ------------------------------------ | -------------------------------------- |
+| New "Stash" feature for Git | Add section to `git.md` |
+| New "Remote Development" capability | Create `remote-development.md` |
+| New setting `git.inline_blame.delay` | Add to existing Git config section |
+| New AI provider (e.g., "Ollama") | Add section to `llm-providers.md` |
+| New agent tool category | Potentially new page, depends on scope |
+
+---
+
+## Document Structure
+
+### Frontmatter
+
+Every doc page needs YAML frontmatter:
+
+```yaml
+---
+title: Feature Name - Zed
+description: One sentence describing what this page covers. Used in search results.
+---
+```
+
+- `title`: Feature name, optionally with "- Zed" suffix for SEO
+- `description`: Concise summary for search engines and link previews
+
+### Section Ordering
+
+1. **Title** (`# Feature Name`) β Clear, scannable
+2. **Opening paragraph** β What this is and why you'd use it (1-2 sentences)
+3. **Getting Started / Usage** β How to access or enable it
+4. **Core functionality** β Main features and workflows
+5. **Configuration** β Settings, with JSON examples
+6. **Keybindings / Actions** β Reference tables
+7. **See Also** β Links to related docs
+
+### Section Depth
+
+- Use `##` for main sections
+- Use `###` for subsections
+- Avoid `####` unless absolutely necessary β if you need it, consider restructuring
+
+### Anchor IDs
+
+Add explicit anchor IDs to sections users might link to directly:
+
+```markdown
+## Getting Started {#getting-started}
+
+### Configuring Models {#configuring-models}
+```
+
+Use anchor IDs when:
+
+- The section is a common reference target
+- You need a stable link that won't break if the heading text changes
+- The heading contains special characters that would create ugly auto-generated anchors
+
+---
+
+## Formatting Conventions
+
+### Code Formatting
+
+Use inline `code` for:
+
+- Setting names: `vim_mode`, `buffer_font_size`
+- Keybindings: `cmd-shift-p`, `ctrl-w h`
+- Commands: `:w`, `:q`
+- File paths: `~/.config/zed/settings.json`
+- Action names: `git::Commit`
+- Values: `true`, `false`, `"eager"`
+
+### Action and Keybinding References
+
+Use Zed's special syntax for dynamic rendering:
+
+- `{#action git::Commit}` β Renders the action name
+- `{#kb git::Commit}` β Renders the keybinding for that action
+
+This ensures keybindings stay accurate if defaults change.
+
+### JSON Examples
+
+Always use the `[settings]` or `[keymap]` annotation:
+
+```json [settings]
+{
+ "vim_mode": true
+}
+```
+
+```json [keymap]
+{
+ "context": "Editor",
+ "bindings": {
+ "ctrl-s": "workspace::Save"
+ }
+}
+```
+
+### Tables
+
+Use tables for:
+
+- Action/keybinding reference lists
+- Setting options with descriptions
+- Feature comparisons
+
+Keep tables scannable β avoid long prose in table cells.
+
+### Paragraphs
+
+- Keep paragraphs short (2-3 sentences max)
+- One idea per paragraph
+- Use bullet lists for multiple related items
+
+### Pronouns
+
+Minimize vague pronouns like "it", "this", and "that". Repeat the noun so readers know exactly what you're referring to.
+
+**Bad:**
+
+> The API creates a token after authentication. It should be stored securely.
+
+**Good:**
+
+> The API creates a token after authentication. The token should be stored securely.
+
+This improves clarity for both human readers and AI systems parsing the documentation.
+
+### Callouts
+
+Use blockquote callouts for tips, notes, and warnings:
+
+```markdown
+> **Note:** This feature requires signing in.
+
+> **Tip:** Hold `cmd` when submitting to automatically follow the agent.
+
+> **Warning:** This action cannot be undone.
+```
+
+### Version-Specific Notes
+
+When behavior differs by version, be explicit:
+
+```markdown
+> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
+```
+
+Include the version number and what changed. This helps users on older versions understand why their behavior differs.
+
+---
+
+## Cross-Linking
+
+### Internal Links
+
+Link to other docs using relative paths:
+
+- `[Vim mode](./vim.md)`
+- `[AI configuration](./ai/configuration.md)`
+
+### External Links
+
+- Link to `zed.dev` pages when appropriate
+- Link to upstream documentation (e.g., Tree-sitter, language servers) when explaining integrations
+
+### "See Also" Sections
+
+End pages with related links when helpful:
+
+```markdown
+## See also
+
+- [Agent Panel](./agent-panel.md): Agentic editing with file read/write
+- [Inline Assistant](./inline-assistant.md): Prompt-driven code transformations
+```
+
+---
+
+## Language-Specific Documentation
+
+Language docs in `src/languages/` follow a consistent structure:
+
+1. Language name and brief description
+2. Installation/setup (if needed)
+3. Language server configuration
+4. Formatting configuration
+5. Language-specific settings
+6. Known limitations (if any)
+
+Keep language docs focused on Zed-specific configuration, not general language tutorials.
+
+---
+
+## Settings Documentation
+
+When documenting settings:
+
+1. **Show the Settings Editor (UI) approach first** β Most settings have UI support
+2. **Then show JSON** as "or add to your settings file:"
+3. **State the setting key** in code formatting
+4. **Describe what it does** in one sentence
+5. **Show the type and default** if not obvious
+6. **Provide a complete JSON example**
+
+Example:
+
+> Configure inline blame in Settings ({#kb zed::OpenSettings}) by searching for "inline blame", or add to your settings file:
+>
+> ```json [settings]
+> {
+> "git": {
+> "inline_blame": {
+> "enabled": false
+> }
+> }
+> }
+> ```
+
+For JSON-only settings (complex types without UI support), note this and link to instructions:
+
+> Add the following to your settings file ([how to edit](./configuring-zed.md#settings-files)):
+
+### Settings File Locations
+
+- **macOS/Linux:** `~/.config/zed/settings.json`
+- **Windows:** `%AppData%\Zed\settings.json`
+
+### Keymap File Locations
+
+- **macOS/Linux:** `~/.config/zed/keymap.json`
+- **Windows:** `%AppData%\Zed\keymap.json`
+
+---
+
+## Terminology
+
+Use consistent terminology throughout:
+
+| Use | Instead of |
+| --------------- | -------------------------------------- |
+| folder | directory |
+| project | workspace |
+| Settings Editor | settings UI |
+| command palette | command bar |
+| panel | sidebar (be specific: "Project Panel") |
+
+---
+
+## Formatting Requirements
+
+All documentation must pass **Prettier** formatting (80 character line width):
+
+```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/`
+
+---
+
+## Quality Checklist
+
+Before finalizing documentation:
+
+- [ ] Frontmatter includes `title` and `description`
+- [ ] Opening paragraph explains what and why
+- [ ] Settings show UI first, then JSON examples
+- [ ] Actions use `{#action ...}` and `{#kb ...}` syntax
+- [ ] All actions are documented (completeness matters)
+- [ ] Anchor IDs on sections likely to be linked
+- [ ] Version callouts where behavior differs by release
+- [ ] No orphan pages (linked from somewhere)
+- [ ] Passes Prettier formatting check
+- [ ] Passes brand voice rubric (see `brand-voice/rubric.md`)
+
+---
+
+## Gold Standard Examples
+
+See `../.doc-examples/` for curated examples of well-documented features. Use these as templates when writing new documentation.
+
+---
+
+## Reference
+
+For automation-specific rules (safety constraints, change classification, output formats), see `docs/AGENTS.md`.
@@ -0,0 +1,265 @@
+---
+name: brand-writer
+description: Write clear, developer-first copy for Zed β leading with facts, grounded in craft.
+allowed-tools: Read, Write, Edit, Glob, Grep, AskUserQuestion, WebFetch
+user-invocable: true
+---
+
+# Zed Brand Writer
+
+Write in Zed's brand voice: thoughtful, technically grounded, and quietly confident. Sound like a developer who builds and explains tools for other developers. Write like the content on zed.dev β clear, reflective, and built around principles rather than persuasion.
+
+## Invocation
+
+```bash
+/brand-writer # Start a writing session
+/brand-writer "homepage hero copy" # Specify what you're writing
+/brand-writer --review "paste copy" # Review existing copy for brand fit
+```
+
+## Core Voice
+
+You articulate Zed's ideas, capabilities, and philosophy through writing that earns trust. Never try to sell. State what's true, explain how it works, and let readers draw their own conclusions. Speak as part of the same community you're writing for.
+
+**Tone:** Fluent, calm, direct. Sentences flow naturally with complete syntax. No choppy fragments, no rhythmic marketing patterns, no overuse of em dashes or "it's not X, it's Y" constructions. Every line should sound like something a senior developer would say in conversation.
+
+---
+
+## Core Messages
+
+**Code as craft**
+Built from scratch, made with intention. Every feature is fit for purpose, and everything has its place.
+
+**Made for multiplayer**
+Code is collaborative. But today, our conversations happen outside the codebase. In Zed, your team and your AI agents work in the same space, in real time.
+
+**Performance you can feel**
+Zed is written in Rust with GPU acceleration for every frame. When you type or move the cursor, pixels respond instantly. That responsiveness keeps you in flow.
+
+**Always shipping**
+Zed is built for today and improved weekly. Each release moves the craft forward.
+
+**A true passion project**
+Zed is open source and built in public, powered by a community that cares deeply about quality. From the team behind Atom and Tree-sitter.
+
+---
+
+## Writing Principles
+
+1. **Most important information first** β Start with what the developer needs to know right now: what changed, what's possible, or how it works. Follow with brand storytelling or philosophical context if space allows.
+
+2. **Thoughtful, not performative** β Write like you're explaining something you care about, not pitching it.
+
+3. **Explanatory precision** β Share technical detail when it matters. Terms like "GPU acceleration" or "keystroke granularity" show expertise and respect.
+
+4. **Philosophy first, product second** β Start from an idea about how developers work or what they deserve, then describe how Zed supports that.
+
+5. **Natural rhythm** β Vary sentence length. Let ideas breathe. Avoid marketing slogans and forced symmetry.
+
+6. **No emotional manipulation** β Never use hype, exclamation points, or "we're excited." Don't tell the reader how to feel.
+
+---
+
+## Structure
+
+When explaining features or ideas:
+
+1. Lead with the most essential fact or change a developer needs to know.
+2. Explain how Zed addresses it.
+3. Add brand philosophy or context to deepen understanding.
+4. Let the reader infer the benefit β never oversell.
+
+---
+
+## Avoid
+
+- AI/marketing tropes (em dashes, mirrored constructions, "it's not X, it's Y")
+- Buzzwords ("revolutionary," "cutting-edge," "game-changing")
+- Corporate tone or startup voice
+- Fragmented copy and slogans
+- Exclamation points
+- "We're excited to announce..."
+
+---
+
+## Litmus Test
+
+Before finalizing copy, verify:
+
+- Would a senior developer respect this?
+- Does it sound like something from zed.dev?
+- Does it read clearly and naturally aloud?
+- Does it explain more than it sells?
+
+If not, rewrite.
+
+---
+
+## Workflow
+
+### Phase 1: Understand the Ask
+
+Ask clarifying questions:
+
+- What is this for? (homepage, release notes, docs, social, product page)
+- Who's the audience? (prospective users, existing users, developers in general)
+- What's the key message or feature to communicate?
+- Any specific constraints? (character limits, format requirements)
+
+### Phase 2: Gather Context
+
+1. **Load reference files** (auto-loaded from skill folder):
+
+ - `rubric.md` β 8 scoring criteria for validation
+ - `taboo-phrases.md` β patterns to eliminate
+ - `voice-examples.md` β transformation patterns and fact preservation rules
+
+2. **Search for relevant context** (if needed):
+ - Existing copy on zed.dev for tone reference
+ - Technical details about the feature from docs or code
+ - Related announcements or prior messaging
+
+### Phase 3: Draft (Two-Pass System)
+
+**Pass 1: First Draft with Fact Markers**
+
+Write initial copy. Mark all factual claims with `[FACT]` tags:
+
+- Technical specifications
+- Proper nouns and product names
+- Version numbers and dates
+- Keyboard shortcuts and URLs
+- Attribution and quotes
+
+Example:
+
+> Zed is [FACT: written in Rust] with [FACT: GPU-accelerated rendering at 120fps]. Built by [FACT: the team behind Atom and Tree-sitter].
+
+**Pass 2: Diagnosis**
+
+Score the draft against all 8 rubric criteria:
+
+| Criterion | Score | Issues |
+| -------------------- | ----- | ------ |
+| Technical Grounding | /5 | |
+| Natural Syntax | /5 | |
+| Quiet Confidence | /5 | |
+| Developer Respect | /5 | |
+| Information Priority | /5 | |
+| Specificity | /5 | |
+| Voice Consistency | /5 | |
+| Earned Claims | /5 | |
+
+Scan for taboo phrases. Flag each with line reference.
+
+**Pass 3: Reconstruction**
+
+For any criterion scoring <4 or any taboo phrase found:
+
+1. Identify the specific problem
+2. Rewrite the flagged section
+3. Verify `[FACT]` markers survived
+4. Re-score the rewritten section
+
+Repeat until all criteria score 4+.
+
+### Phase 4: Validation
+
+Present final copy with scorecard:
+
+```
+## Final Copy
+
+[The copy here]
+
+## Scorecard
+
+| Criterion | Score |
+|---------------------|-------|
+| Technical Grounding | 5 |
+| Natural Syntax | 4 |
+| Quiet Confidence | 5 |
+| Developer Respect | 5 |
+| Information Priority| 4 |
+| Specificity | 5 |
+| Voice Consistency | 4 |
+| Earned Claims | 5 |
+| **TOTAL** | 37/40 |
+
+β
All criteria 4+
+β
Zero taboo phrases
+β
All facts preserved
+
+## Facts Verified
+- [FACT: Rust] β
+- [FACT: GPU-accelerated] β
+- [FACT: 120fps] β
+```
+
+**Output formats by context:**
+
+| Context | Format |
+| ------------- | ---------------------------------------------------- |
+| Homepage | H1 + H2 + supporting paragraph |
+| Product page | Section headers with explanatory copy |
+| Release notes | What changed, how it works, why it matters |
+| Docs intro | Clear explanation of what this is and when to use it |
+| Social | Concise, no hashtags, link to learn more |
+
+---
+
+## Review Mode
+
+When invoked with `--review`:
+
+1. **Load reference files** (rubric, taboo phrases, voice examples)
+
+2. **Score the provided copy** against all 8 rubric criteria
+
+3. **Scan for taboo phrases** β list each with line number:
+
+ ```
+ Line 2: "revolutionary" (hype word)
+ Line 5: "β" used 3 times (em dash overuse)
+ Line 7: "We're excited" (empty enthusiasm)
+ ```
+
+4. **Present diagnosis:**
+
+ ```
+ ## Review: [Copy Title]
+
+ | Criterion | Score | Issues |
+ |---------------------|-------|--------|
+ | Technical Grounding | 3 | Vague claims about "performance" |
+ | Natural Syntax | 2 | Triple em dash chain in P2 |
+ | ... | | |
+
+ ### Taboo Phrases Found
+ - Line 2: "revolutionary"
+ - Line 5: "seamless experience"
+
+ ### Verdict
+ β Does not pass (3 criteria below threshold)
+ ```
+
+5. **Offer rewrite** if any criterion scores <4:
+ - Apply transformation patterns from voice-examples.md
+ - Preserve all facts from original
+ - Present rewritten version with new scores
+
+---
+
+## Examples
+
+### Good
+
+> Zed is written in Rust with GPU acceleration for every frame. When you type or move the cursor, pixels respond instantly. That responsiveness keeps you in flow.
+
+### Bad
+
+> We're excited to announce our revolutionary new editor that will change the way you code forever! Say goodbye to slow, clunky IDEs β Zed is here to transform your workflow.
+
+### Fixed
+
+> Zed is a new kind of editor, built from scratch for speed. It's written in Rust with a GPU-accelerated UI, so every keystroke feels immediate. We designed it for developers who notice when their tools get in the way.
@@ -0,0 +1,178 @@
+# Brand Voice Rubric
+
+Score each criterion 1-5. Copy must score **4+ on ALL criteria** to pass.
+
+---
+
+## 1. Technical Grounding (1-5)
+
+Does the copy make specific, verifiable technical claims?
+
+| Score | Description |
+| ----- | ----------------------------------------------------------------------------------------- |
+| 5 | Precise technical details that can be verified (specs, architecture, measurable outcomes) |
+| 4 | Concrete technical claims with clear meaning |
+| 3 | Mix of specific and vague technical references |
+| 2 | Mostly abstract with occasional technical terms |
+| 1 | No technical substance; pure marketing language |
+
+**Examples:**
+
+- β
"Written in Rust with GPU-accelerated rendering at 120fps"
+- β "Blazingly fast performance that will transform your workflow"
+
+---
+
+## 2. Natural Syntax (1-5)
+
+Does the writing flow like natural speech from a thoughtful developer?
+
+| Score | Description |
+| ----- | --------------------------------------------------------------- |
+| 5 | Varied sentence structure, natural rhythm, reads aloud smoothly |
+| 4 | Mostly natural with minor rhythm issues |
+| 3 | Some AI patterns visible but not dominant |
+| 2 | Obvious structural patterns (parallel triplets, em dash chains) |
+| 1 | Robotic cadence, formulaic construction throughout |
+
+**Red flags:** Em dash overuse, "It's not X, it's Y" constructions, triple parallel lists, sentences all same length.
+
+---
+
+## 3. Quiet Confidence (1-5)
+
+Does the copy state facts without hype or emotional manipulation?
+
+| Score | Description |
+| ----- | -------------------------------------------------------- |
+| 5 | Facts speak for themselves; reader draws own conclusions |
+| 4 | Confident statements with minimal flourish |
+| 3 | Some restraint but occasional hype creeps in |
+| 2 | Frequent superlatives or emotional appeals |
+| 1 | Aggressive marketing tone, telling reader how to feel |
+
+**Examples:**
+
+- β
"Zed renders every frame on the GPU. You'll notice the difference when you scroll."
+- β "Experience the revolutionary speed that will absolutely transform how you code!"
+
+---
+
+## 4. Developer Respect (1-5)
+
+Does the copy treat the reader as a peer, not a prospect?
+
+| Score | Description |
+| ----- | ------------------------------------------------------- |
+| 5 | Peer-to-peer conversation; assumes technical competence |
+| 4 | Respectful with appropriate technical depth |
+| 3 | Slightly patronizing or oversimplified |
+| 2 | Condescending explanations or forced enthusiasm |
+| 1 | Treats reader as uninformed consumer to be persuaded |
+
+**Examples:**
+
+- β
"Tree-sitter provides incremental parsing, so syntax highlighting updates as you type."
+- β "Don't worry about the technical details β just know it's fast!"
+
+---
+
+## 5. Information Priority (1-5)
+
+Is the most important information first?
+
+| Score | Description |
+| ----- | --------------------------------------------------- |
+| 5 | Key fact or change leads; context follows naturally |
+| 4 | Important info near top with minor preamble |
+| 3 | Buried lede but recoverable |
+| 2 | Significant buildup before substance |
+| 1 | Key information buried or missing entirely |
+
+**Examples:**
+
+- β
"Inline completions now stream token-by-token. Previously, you waited for the full response."
+- β "We've been thinking a lot about the developer experience, and after months of work, we're thrilled to share that..."
+
+---
+
+## 6. Specificity (1-5)
+
+Are claims concrete and measurable?
+
+| Score | Description |
+| ----- | -------------------------------------- |
+| 5 | Every claim is specific and verifiable |
+| 4 | Mostly specific with rare abstractions |
+| 3 | Mix of concrete and vague claims |
+| 2 | Mostly abstract benefits |
+| 1 | All claims are vague or unverifiable |
+
+**Examples:**
+
+- β
"Startup time under 100ms on M1 Macs"
+- β "Lightning-fast startup that respects your time"
+
+---
+
+## 7. Voice Consistency (1-5)
+
+Does the tone remain unified throughout?
+
+| Score | Description |
+| ----- | ------------------------------------------ |
+| 5 | Single coherent voice from start to finish |
+| 4 | Minor tonal shifts that don't distract |
+| 3 | Noticeable drift between sections |
+| 2 | Multiple competing voices |
+| 1 | Jarring tonal inconsistency |
+
+**Check for:** Shifts between casual/formal, technical/marketing, confident/hedging.
+
+---
+
+## 8. Earned Claims (1-5)
+
+Are assertions supported or supportable?
+
+| Score | Description |
+| ----- | ------------------------------------------- |
+| 5 | Every claim can be demonstrated or verified |
+| 4 | Claims are reasonable and mostly verifiable |
+| 3 | Some unsupported assertions |
+| 2 | Multiple unverifiable superlatives |
+| 1 | Bold claims with no backing |
+
+**Examples:**
+
+- β
"Built by the team behind Atom and Tree-sitter"
+- β "The most advanced editor ever created"
+
+---
+
+## Quick Scoring Template
+
+```
+| Criterion | Score | Notes |
+|---------------------|-------|-------|
+| Technical Grounding | /5 | |
+| Natural Syntax | /5 | |
+| Quiet Confidence | /5 | |
+| Developer Respect | /5 | |
+| Information Priority| /5 | |
+| Specificity | /5 | |
+| Voice Consistency | /5 | |
+| Earned Claims | /5 | |
+| **TOTAL** | /40 | |
+
+Pass threshold: 32/40 (all criteria 4+)
+```
+
+---
+
+## Decision Rules
+
+- **All 4+:** Copy passes. Minor polish optional.
+- **Any 3:** Rewrite flagged sections, re-score.
+- **Any 2 or below:** Full reconstruction required.
+- **Multiple failures:** Start fresh with new approach.
@@ -0,0 +1,195 @@
+# Taboo Phrases
+
+These patterns signal AI-generated or marketing-heavy copy. Eliminate all instances.
+
+---
+
+## Hype Words
+
+Never use these unless quoting someone else:
+
+| Word/Phrase | Why It Fails |
+| ---------------- | ---------------------------------- |
+| revolutionary | Unearned superlative |
+| game-changing | Unearned superlative |
+| cutting-edge | Vague tech buzzword |
+| next-generation | Meaningless without context |
+| blazingly fast | ClichΓ©, unquantified |
+| lightning-fast | ClichΓ©, unquantified |
+| powerful | Vague; what does it do? |
+| robust | Vague; how is it robust? |
+| seamless | Almost never true |
+| frictionless | Almost never true |
+| effortless | Dismisses real complexity |
+| leverage | Corporate jargon |
+| unlock | Marketing manipulation |
+| supercharge | Marketing manipulation |
+| turbocharge | Marketing manipulation |
+| best-in-class | Unverifiable claim |
+| world-class | Unverifiable claim |
+| state-of-the-art | Vague tech buzzword |
+| groundbreaking | Unearned superlative |
+| innovative | Show, don't tell |
+| intuitive | Often means "we didn't explain it" |
+| elegant | Self-congratulatory |
+
+---
+
+## AI Structural Patterns
+
+These constructions reveal AI authorship:
+
+### Em Dash Chains
+
+```
+β "Zed is fast β really fast β and it shows in every interaction."
+β
"Zed is fast. You'll feel it in every interaction."
+```
+
+### "It's not X, it's Y"
+
+```
+β "It's not just an editor β it's a complete development environment."
+β
"Zed combines editing, collaboration, and AI assistance in one workspace."
+```
+
+### Triple Parallel Lists
+
+```
+β "Fast. Focused. Collaborative."
+β "Write code. Ship faster. Stay in flow."
+β
"Zed is built for speed and collaboration."
+```
+
+### Colon-Introduced Lists in Prose
+
+```
+β "Three things make Zed different: speed, collaboration, and AI."
+β
"Zed prioritizes speed, real-time collaboration, and AI integration."
+```
+
+### Rhetorical Questions as Openers
+
+```
+β "What if your editor could keep up with your thinking?"
+β
"Zed renders every keystroke instantly."
+```
+
+---
+
+## Empty Enthusiasm
+
+Remove all emotional manipulation:
+
+| Pattern | Problem |
+| --------------------------------- | -------------------------------- |
+| "We're excited to announce..." | Nobody cares about your emotions |
+| "We're thrilled to share..." | Same |
+| "We can't wait for you to try..." | Presumptuous |
+| "You'll love..." | Telling reader how to feel |
+| "Get ready to..." | Marketing hype |
+| "Say goodbye to..." | ClichΓ© setup |
+| "Say hello to..." | ClichΓ© followup |
+| "Finally, an editor that..." | Implies all others failed |
+| "The wait is over" | Presumes anticipation |
+| "Introducing..." (as standalone) | Weak opener |
+
+---
+
+## Vague Benefits
+
+Replace with specific outcomes:
+
+| Vague | Ask Instead |
+| ----------------------- | ------------------------------ |
+| "enhanced productivity" | How much faster? At what task? |
+| "improved workflow" | What specific improvement? |
+| "better experience" | Better how? Measurable? |
+| "streamlined process" | What steps were removed? |
+| "optimized performance" | What metric improved? |
+| "increased efficiency" | What takes less time/effort? |
+| "modern development" | What specific capability? |
+| "next-level coding" | Meaningless |
+| "superior quality" | By what measure? |
+
+---
+
+## Forbidden Punctuation
+
+| Pattern | Rule |
+| ----------- | ---------------------------------- |
+| `!` | Never. Zero exclamation points. |
+| `...` | No dramatic ellipses |
+| ALL CAPS | No shouting for emphasis |
+| `?` as hook | No rhetorical questions as openers |
+| `β` overuse | Max one em dash per paragraph |
+
+---
+
+## Corporate Euphemisms
+
+| Phrase | Problem |
+| ------------------- | ----------------------------- |
+| move the needle | Jargon |
+| synergy | Meme-tier corporate |
+| ecosystem | Often meaningless |
+| paradigm shift | Dated buzzword |
+| holistic approach | Vague |
+| scalable solution | What scales? How? |
+| actionable insights | Corporate speak |
+| value proposition | Never in customer-facing copy |
+| leverage (verb) | Use "use" instead |
+| utilize | Use "use" instead |
+| facilitate | Use clearer verb |
+| empower | Patronizing |
+| enable | Often vague; be specific |
+
+---
+
+## Filler Phrases
+
+Delete without replacement:
+
+- "In today's fast-paced world..."
+- "As developers, we know..."
+- "Let's face it..."
+- "The truth is..."
+- "At the end of the day..."
+- "When it comes to..."
+- "In order to..."
+- "It goes without saying..."
+- "Needless to say..."
+- "As you may know..."
+
+---
+
+## Detection Checklist
+
+Before finalizing, scan for:
+
+1. **Superlatives:** best, most, fastest, only, first, ultimate
+2. **Absolutes:** always, never, every, all, completely, totally
+3. **Hedging:** might, could, potentially, possibly, may help
+4. **Intensifiers:** very, really, extremely, incredibly, absolutely
+5. **Vague quantifiers:** many, numerous, significant, substantial
+
+**Rule:** If you can't prove it or measure it, rewrite it.
+
+---
+
+## Quick Reference
+
+**Instant red flags (auto-fail if present):**
+
+- Any exclamation point
+- "We're excited/thrilled"
+- "Revolutionary" or "game-changing"
+- Em dash used 2+ times in one paragraph
+- "It's not X, it's Y" construction
+
+**Yellow flags (review carefully):**
+
+- Any word from Hype Words list
+- Sentences starting with "And" or "But"
+- Questions in headlines
+- Lists of exactly three items
@@ -0,0 +1,267 @@
+# Voice Transformation Examples
+
+Ten before/after transformations demonstrating Zed's brand voice. Use these as calibration for diagnosis and reconstruction.
+
+---
+
+## 1. Hype to Specifics
+
+**Before (Score: 2/5 Technical Grounding)**
+
+> Zed delivers blazingly fast performance that will revolutionize your coding experience. Our cutting-edge technology ensures you never wait again.
+
+**After (Score: 5/5)**
+
+> Zed is written in Rust with GPU-accelerated rendering. Keystrokes register in under 8ms. Scrolling stays at 120fps even in large files.
+
+**Transformation notes:**
+
+- "blazingly fast" β specific latency numbers
+- "revolutionize" β removed entirely
+- "cutting-edge technology" β actual tech stack
+- "never wait again" β measurable claim
+
+---
+
+## 2. Marketing to Technical
+
+**Before (Score: 2/5 Developer Respect)**
+
+> Don't worry about the complicated stuff β Zed handles it all for you! Just focus on what you do best: writing amazing code.
+
+**After (Score: 5/5)**
+
+> Zed runs language servers in separate processes with automatic crash recovery. If a language server fails, you keep editing while it restarts.
+
+**Transformation notes:**
+
+- Removed patronizing tone ("don't worry")
+- Removed enthusiasm ("amazing")
+- Added technical mechanism
+- Treats reader as capable of understanding
+
+---
+
+## 3. Abstract to Concrete
+
+**Before (Score: 2/5 Specificity)**
+
+> Zed provides a seamless collaborative experience that brings your team together in powerful new ways.
+
+**After (Score: 5/5)**
+
+> Share your workspace with `cmd+shift+c`. Collaborators see your cursor, selections, and edits in real time. Voice chat is built in β no separate call needed.
+
+**Transformation notes:**
+
+- "seamless" β actual UX flow
+- "powerful new ways" β specific features
+- Added keyboard shortcut (concrete entry point)
+- Described what collaboration actually looks like
+
+---
+
+## 4. Em Dash Chains to Natural Flow
+
+**Before (Score: 2/5 Natural Syntax)**
+
+> Zed is fast β really fast β and built for the way developers actually work β not how tools think they should work.
+
+**After (Score: 5/5)**
+
+> Zed is built for speed. We optimized for the workflows developers actually use: jumping between files, searching across projects, editing multiple cursors at once.
+
+**Transformation notes:**
+
+- Removed all em dashes
+- Split into two clear sentences
+- Abstract claim β specific examples
+- "really fast" β removed (show, don't tell)
+
+---
+
+## 5. Enthusiasm to Confidence
+
+**Before (Score: 1/5 Quiet Confidence)**
+
+> We're thrilled to announce Zed 1.0! After years of hard work, we can't wait for you to experience what we've built. You're going to love it!
+
+**After (Score: 5/5)**
+
+> Zed 1.0 is available today. This release includes GPU text rendering, multi-buffer editing, and native collaboration. Download it at zed.dev.
+
+**Transformation notes:**
+
+- Removed all emotional language
+- "thrilled" β deleted
+- "can't wait" β deleted
+- "You're going to love it" β deleted
+- Added substance instead of feelings
+
+---
+
+## 6. "It's Not X, It's Y" Fix
+
+**Before (Score: 2/5 Natural Syntax)**
+
+> Zed isn't just an editor β it's a complete development environment. It's not about features β it's about flow. And it's not slow β it's instant.
+
+**After (Score: 5/5)**
+
+> Zed combines editing, debugging, collaboration, and AI assistance in one application. Everything runs in the same process, so switching between tasks has no context-switch overhead.
+
+**Transformation notes:**
+
+- Eliminated all "it's not X, it's Y" patterns
+- Replaced negation with positive statements
+- Added technical reasoning
+- One clear sentence instead of three choppy ones
+
+---
+
+## 7. Vague Benefits to Specific Outcomes
+
+**Before (Score: 2/5 Specificity)**
+
+> Zed's AI integration enhances your productivity and streamlines your workflow, helping you code smarter and ship faster.
+
+**After (Score: 5/5)**
+
+> Zed runs AI completions inline as you type. Suggestions appear in 200ms. Accept with Tab, reject by continuing to type. The model runs locally or connects to your preferred API.
+
+**Transformation notes:**
+
+- "enhances productivity" β specific UX
+- "streamlines workflow" β actual interaction model
+- "code smarter" β deleted (meaningless)
+- Added technical options (local vs API)
+
+---
+
+## 8. Social Media Cleanup
+
+**Before (Score: 1/5 across multiple criteria)**
+
+> π Big news! Zed just dropped MASSIVE updates! Multi-file editing, insane AI features, and SO much more. This is a game-changer, folks! Try it now! π₯
+
+**After (Score: 4/5)**
+
+> Zed 0.150: Multi-buffer editing is here. Edit across files in a single view. AI completions now stream inline. Full changelog at zed.dev/releases.
+
+**Transformation notes:**
+
+- Removed all emoji
+- Removed exclamation points
+- "MASSIVE" β specific features
+- "game-changer" β deleted
+- "SO much more" β link to changelog
+- Added version number for precision
+
+---
+
+## 9. Feature Announcement
+
+**Before (Score: 2/5 Information Priority)**
+
+> We've been listening to your feedback, and after months of development, our incredible team has built something truly special. Today, we're excited to finally share our new terminal integration!
+
+**After (Score: 5/5)**
+
+> Zed now includes a built-in terminal. Open it with `ctrl+\``. Terminals run in splits alongside your editor panes and share the same working directory as your project.
+
+**Transformation notes:**
+
+- Lead with the feature, not the backstory
+- Removed emotional buildup
+- Added keyboard shortcut
+- Described actual behavior
+
+---
+
+## 10. Philosophy Statement
+
+**Before (Score: 3/5 Quiet Confidence)**
+
+> At Zed, we believe that developers deserve better tools. We're passionate about creating the best possible coding experience because we know how frustrating slow, bloated editors can be.
+
+**After (Score: 5/5)**
+
+> Developer tools should be fast, understandable, and collaborative. We built Zed to meet that standard. It's open source so you can verify our work and extend it.
+
+**Transformation notes:**
+
+- "We believe" β direct statement
+- "passionate about" β deleted
+- "best possible" β specific standard
+- "frustrating, slow, bloated" β removed comparison
+- Added concrete proof point (open source)
+
+---
+
+## Fact Preservation Rules
+
+When transforming copy, certain elements must survive unchanged:
+
+### Mark During Diagnosis
+
+Tag factual claims with `[FACT]` during diagnosis phase:
+
+```
+Zed is written in [FACT: Rust] with [FACT: GPU-accelerated rendering].
+It was built by [FACT: the team behind Atom and Tree-sitter].
+```
+
+### Never Change
+
+| Category | Examples |
+| ------------------ | ------------------------------------------ |
+| Technical specs | "120fps", "8ms latency", "Rust" |
+| Proper nouns | "Tree-sitter", "Anthropic", "Claude" |
+| Version numbers | "Zed 1.0", "v0.150" |
+| Keyboard shortcuts | "cmd+shift+c", "ctrl+\`" |
+| URLs | "zed.dev/releases" |
+| Attribution | "built by the team behind Atom" |
+| Dates | "available today", "released January 2024" |
+| Quotes | Any attributed quotation |
+
+### Verification Step
+
+After reconstruction, diff against original `[FACT]` markers:
+
+1. List all facts from original
+2. Confirm each appears in final copy
+3. If a fact was removed, justify why (e.g., not relevant to new scope)
+4. If a fact was changed, flag as error
+
+### Example Verification
+
+**Original with markers:**
+
+> Zed is [FACT: written in Rust] with [FACT: GPU-accelerated rendering at 120fps]. Built by [FACT: the team behind Atom and Tree-sitter].
+
+**Reconstruction:**
+
+> Zed renders every frame on the GPU at 120fps. The Rust codebase prioritizes memory safety without garbage collection pauses. The same engineers who built Atom and Tree-sitter lead development.
+
+**Verification:**
+
+- β
"Rust" preserved
+- β
"GPU-accelerated" preserved
+- β
"120fps" preserved
+- β
"team behind Atom and Tree-sitter" preserved
+- **Pass**
+
+---
+
+## Transformation Patterns Summary
+
+| Problem | Solution |
+| -------------------- | ---------------------------- |
+| Hype words | Replace with measurements |
+| Em dash chains | Split into sentences |
+| "It's not X, it's Y" | State positively what it is |
+| Enthusiasm | Delete; add substance |
+| Vague benefits | Name specific features |
+| Buried lede | Lead with the news |
+| Rhetorical questions | Make declarative statements |
+| Abstract claims | Add mechanism or measurement |
@@ -0,0 +1,349 @@
+<!--
+ GOLD STANDARD EXAMPLE: Complex Feature Documentation
+
+ This example demonstrates documentation for a major feature with multiple
+ sub-features, configuration options, and an action reference table.
+
+ Key patterns to note:
+ - Anchor IDs on all major sections for stable deep-linking
+ - Opening paragraph explains what and why
+ - Configuration section with JSON examples
+ - Proper callout formatting (> **Note:** and > **Tip:**)
+ - Comprehensive action reference table at the end
+ - Uses {#action ...} and {#kb ...} syntax throughout
+-->
+
+---
+
+description: Zed is a text editor that supports lots of Git features
+title: Zed Editor Git integration documentation
+
+---
+
+# Git
+
+Zed has built-in Git support that lets you manage version control without leaving the editor. The Git Panel shows your working tree state, staging area, and branch information. Changes you make on the command line are reflected immediately in Zed.
+
+For operations that Zed doesn't support natively, you can use the integrated terminal.
+
+## Git Panel {#git-panel}
+
+The Git Panel shows the state of your working tree and Git's staging area.
+
+You can open the Git Panel using {#action git_panel::ToggleFocus}, or by clicking the Git icon in the status bar.
+
+In the panel you can see the state of your project at a glance: which repository and branch are active, what files have changed and the current staging state of each file.
+
+Zed monitors your repository so that changes you make on the command line are instantly reflected.
+
+### Configuration {#configuration}
+
+Open the Settings Editor (`Cmd+,` on macOS, `Ctrl+,` on Linux/Windows) to customize Git behavior. Settings are spread across two pages:
+
+- **Panels > Git Panel**: Panel position, tree vs flat view, status display style
+- **Version Control**: Gutter indicators, inline blame, hunk styles
+
+#### Moving the Git Panel
+
+By default, the Git Panel docks on the left. Go to **Panels > Git Panel** and change **Git Panel Dock** to move it to the right or bottom.
+
+#### Switching to Tree View
+
+The Git Panel shows a flat list of changed files by default. To see files organized by folder hierarchy instead, toggle **Tree View** in the panel's context menu, or enable it in **Panels > Git Panel**.
+
+#### Inline Blame
+
+Zed shows Git blame information on the current line. To turn this off or add a delay before it appears, go to **Version Control > Inline Git Blame**.
+
+#### Hiding the Gutter Indicators
+
+The colored bars in the gutter that show added, modified, and deleted lines can be hidden. Go to **Version Control > Git Gutter** and set **Visibility** to "Hide".
+
+#### Commit Message Line Length
+
+Zed wraps commit messages at 72 characters (a Git convention). To change this, search for "Git Commit" in Settings and adjust **Preferred Line Length**.
+
+## Project Diff {#project-diff}
+
+You can see all of the changes captured by Git in Zed by opening the Project Diff ({#kb git::Diff}), accessible via the {#action git::Diff} action in the Command Palette or the Git Panel.
+
+All of the changes displayed in the Project Diff behave exactly the same as any other multibuffer: they are all editable excerpts of files.
+
+You can stage or unstage each hunk as well as a whole file by hitting the buttons on the tab bar or their corresponding keybindings.
+
+### Word Diff Highlighting {#word-diff}
+
+By default, Zed highlights changed words within modified lines to make it easier to spot exactly what changed. To disable this globally, open the Settings Editor and go to **Languages & Tools > Miscellaneous**, then turn off **Word Diff Enabled**.
+
+To disable word diff for specific languages only, add this to your settings.json:
+
+```json
+{
+ "languages": {
+ "Markdown": {
+ "word_diff_enabled": false
+ }
+ }
+}
+```
+
+## File History {#file-history}
+
+File History shows the commit history for an individual file. Each entry displays the commit's author, timestamp, and message. Selecting a commit opens a diff view filtered to show only the changes made to that file in that commit.
+
+To open File History:
+
+- Right-click on a file in the Project Panel and select "Open File History"
+- Right-click on a file in the Git Panel and select "Open File History"
+- Right-click on an editor tab and select "Open File History"
+- Use the Command Palette and search for "file history"
+
+## Fetch, Push, and Pull {#fetch-push-pull}
+
+Fetch, push, or pull from your Git repository in Zed via the buttons available on the Git Panel or via the Command Palette by looking at the respective actions: {#action git::Fetch}, {#action git::Push}, and {#action git::Pull}.
+
+### Push Configuration {#push-configuration}
+
+Zed respects Git's push configuration. When pushing, Zed checks the following in order:
+
+1. `pushRemote` configured for the current branch
+2. `remote.pushDefault` in your Git config
+3. The branch's tracking remote
+
+This matches Git's standard behavior, so if you've configured `pushRemote` or `pushDefault` in your `.gitconfig` or via `git config`, Zed will use those settings.
+
+## Remotes {#remotes}
+
+When your repository has multiple remotes, Zed shows a remote selector in the Git Panel. Click the remote button next to push/pull to choose which remote to use for that operation.
+
+## Staging Workflow {#staging-workflow}
+
+Zed has two primary staging workflows, using either the Project Diff or the panel directly.
+
+### Using the Project Diff {#staging-project-diff}
+
+In the Project Diff view, you can focus on each hunk and stage them individually by clicking on the tab bar buttons or via the keybindings {#action git::StageAndNext} ({#kb git::StageAndNext}).
+
+Similarly, stage all hunks at the same time with the {#action git::StageAll} ({#kb git::StageAll}) keybinding and then immediately commit with {#action git::Commit} ({#kb git::Commit}).
+
+### Using the Git Panel {#staging-git-panel}
+
+From the panel, you can simply type a commit message and hit the commit button, or {#action git::Commit}. This will automatically stage all tracked files (indicated by a `[Β·]` in the entry's checkbox) and commit them.
+
+Entries can be staged using each individual entry's checkbox. All changes can be staged using the button at the top of the panel, or {#action git::StageAll}.
+
+## Committing {#committing}
+
+Zed offers two commit textareas:
+
+1. The first one is available right at the bottom of the Git Panel. Hitting {#kb git::Commit} immediately commits all of your staged changes.
+2. The second is available via the action {#action git::ExpandCommitEditor} or via hitting the {#kb git::ExpandCommitEditor} while focused in the Git Panel commit textarea.
+
+### Undoing a Commit {#undo-commit}
+
+As soon as you commit in Zed, in the Git Panel, you'll see a bar right under the commit textarea, which will show the recently submitted commit.
+In there, you can use the "Uncommit" button, which performs the `git reset HEADΛ--soft` command.
+
+### Configuring Commit Line Length
+
+By default, Zed sets the commit line length to `72` but it can be configured in your local `settings.json` file.
+
+Find more information about setting the `preferred-line-length` in the [Configuration](#configuration) section.
+
+## Branch Management {#branch-management}
+
+### Creating and Switching Branches {#create-switch-branches}
+
+Create a new branch using {#action git::Branch} or switch to an existing branch using {#action git::Switch} or {#action git::CheckoutBranch}.
+
+### Deleting Branches {#delete-branches}
+
+To delete a branch, open the branch switcher with {#action git::Switch}, find the branch you want to delete, and use the delete option. Zed will confirm before deleting to prevent accidental data loss.
+
+> **Note:** You cannot delete the branch you currently have checked out. Switch to a different branch first.
+
+## Merge Conflicts {#merge-conflicts}
+
+When you encounter merge conflicts after a merge, rebase, or pull, Zed highlights the conflicting regions in your files and displays resolution buttons above each conflict.
+
+### Viewing Conflicts {#viewing-conflicts}
+
+Conflicting files appear in the Git Panel with a warning icon. You can also see conflicts in the Project Diff view, where each conflict region is highlighted:
+
+- Changes from your current branch are highlighted in green
+- Changes from the incoming branch are highlighted in blue
+
+### Resolving Conflicts {#resolving-conflicts}
+
+Each conflict shows three buttons:
+
+- **Use [branch-name]**: Keep the changes from one branch (shows the actual branch name, like "main")
+- **Use [other-branch]**: Keep the changes from the other branch (like "feature-branch")
+- **Use Both**: Keep both sets of changes, with your branch's changes first
+
+Click a button to resolve that conflict. The conflict markers are removed and replaced with your chosen content. After resolving all conflicts in a file, stage it and commit to complete the merge.
+
+> **Tip:** For complex conflicts that need manual editing, you can edit the file directly. Remove the conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) and keep the content you want.
+
+## Stashing {#stashing}
+
+Git stash allows you to temporarily save your uncommitted changes and revert your working directory to a clean state. This is particularly useful when you need to quickly switch branches or pull updates without committing incomplete work.
+
+### Creating Stashes {#creating-stashes}
+
+To stash all your current changes, use the {#action git::StashAll} action. This will save both staged and unstaged changes to a new stash entry and clean your working directory.
+
+### Managing Stashes {#managing-stashes}
+
+Zed provides a stash picker accessible via {#action git::ViewStash} or from the Git Panel's overflow menu. From the stash picker, you can:
+
+- **View stash list**: Browse all your saved stashes with their descriptions and timestamps
+- **Open diffs**: See exactly what changes are stored in each stash
+- **Apply stashes**: Apply stash changes to your working directory while keeping the stash entry
+- **Pop stashes**: Apply stash changes and remove the stash entry from the list
+- **Drop stashes**: Delete unwanted stash entries without applying them
+
+### Quick Stash Operations {#quick-stash}
+
+For faster workflows, Zed provides direct actions to work with the most recent stash:
+
+- **Apply latest stash**: Use {#action git::StashApply} to apply the most recent stash without removing it
+- **Pop latest stash**: Use {#action git::StashPop} to apply and remove the most recent stash
+
+### Stash Diff View {#stash-diff-view}
+
+To view a stash's contents, select it in the stash picker and press {#kb stash_picker::ShowStashItem}. From the diff view, you can use these keybindings:
+
+| Action | Keybinding |
+| ------------------------------------ | ---------------------------- |
+| Apply stash | {#kb git::ApplyCurrentStash} |
+| Pop stash (apply and remove) | {#kb git::PopCurrentStash} |
+| Drop stash (remove without applying) | {#kb git::DropCurrentStash} |
+
+## AI Support in Git {#ai-support}
+
+Zed currently supports LLM-powered commit message generation.
+You can ask AI to generate a commit message by focusing on the message editor within the Git Panel and either clicking on the pencil icon in the bottom left, or reaching for the {#action git::GenerateCommitMessage} ({#kb git::GenerateCommitMessage}) keybinding.
+
+> **Note:** You need to have an LLM provider configured either via your own API keys or through Zed's hosted AI models.
+> Visit [the AI configuration page](./ai/configuration.md) to learn how to do so.
+
+You can specify your preferred model to use by providing a `commit_message_model` agent setting.
+See [Feature-specific models](./ai/agent-settings.md#feature-specific-models) for more information.
+
+```json [settings]
+{
+ "agent": {
+ "commit_message_model": {
+ "provider": "anthropic",
+ "model": "claude-3-5-haiku"
+ }
+ }
+}
+```
+
+To customize the format of generated commit messages, run {#action agent::OpenRulesLibrary} and select the "Commit message" rule on the left side.
+From there, you can modify the prompt to match your desired format.
+
+Any specific instructions for commit messages added to [Rules files](./ai/rules.md) are also picked up by the model tasked with writing your commit message.
+
+## Git Integrations {#git-integrations}
+
+Zed integrates with popular Git hosting services to ensure that Git commit hashes and references to Issues, Pull Requests, and Merge Requests become clickable links.
+
+Zed currently supports links to the hosted versions of
+[GitHub](https://github.com),
+[GitLab](https://gitlab.com),
+[Bitbucket](https://bitbucket.org),
+[SourceHut](https://sr.ht) and
+[Codeberg](https://codeberg.org).
+
+### Self-Hosted Instances {#self-hosted}
+
+Zed automatically identifies Git hosting providers by checking for keywords in your Git remote URL. For example, if your self-hosted URL contains `gitlab`, `gitea`, or other recognized provider names, Zed will automatically register that hosting provider without any configuration needed.
+
+However, if your self-hosted Git instance URL doesn't contain identifying keywords, you can manually configure Zed to create clickable links to your instance by adding a `git_hosting_providers` setting so commit hashes and permalinks resolve to your domain:
+
+```json [settings]
+{
+ "git_hosting_providers": [
+ {
+ "provider": "gitlab",
+ "name": "Corp GitLab",
+ "base_url": "https://git.example.corp"
+ }
+ ]
+}
+```
+
+The `provider` field specifies which type of hosting service you're using. Supported `provider` values are `github`, `gitlab`, `bitbucket`, `gitea`, `forgejo`, and `sourcehut`. The `name` is optional and used as a display name for your instance, and `base_url` is the root URL of your self-hosted server.
+
+You can configure multiple custom providers if you work with several self-hosted instances.
+
+### Permalinks {#permalinks}
+
+Zed also has a Copy Permalink feature to create a permanent link to a code snippet on your Git hosting service.
+These links are useful for sharing a specific line or range of lines in a file at a specific commit.
+Trigger this action via the [Command Palette](./getting-started.md#command-palette) (search for `permalink`),
+by creating a [custom key bindings](key-bindings.md#custom-key-bindings) to the
+`editor::CopyPermalinkToLine` or `editor::OpenPermalinkToLine` actions
+or by simply right clicking and selecting `Copy Permalink` with line(s) selected in your editor.
+
+## Diff Hunk Keyboard Shortcuts {#diff-hunks}
+
+When viewing files with changes, Zed displays diff hunks that can be expanded or collapsed for detailed review:
+
+- **Expand all diff hunks**: {#action editor::ExpandAllDiffHunks} ({#kb editor::ExpandAllDiffHunks})
+- **Collapse all diff hunks**: Press `Escape` (bound to {#action editor::Cancel})
+- **Toggle selected diff hunks**: {#action editor::ToggleSelectedDiffHunks} ({#kb editor::ToggleSelectedDiffHunks})
+- **Navigate between hunks**: {#action editor::GoToHunk} and {#action editor::GoToPreviousHunk}
+
+> **Tip:** The `Escape` key is the quickest way to collapse all expanded diff hunks and return to an overview of your changes.
+
+## Action Reference {#action-reference}
+
+| Action | Keybinding |
+| ----------------------------------------- | ------------------------------------- |
+| {#action git::Add} | {#kb git::Add} |
+| {#action git::StageAll} | {#kb git::StageAll} |
+| {#action git::UnstageAll} | {#kb git::UnstageAll} |
+| {#action git::ToggleStaged} | {#kb git::ToggleStaged} |
+| {#action git::StageAndNext} | {#kb git::StageAndNext} |
+| {#action git::UnstageAndNext} | {#kb git::UnstageAndNext} |
+| {#action git::Commit} | {#kb git::Commit} |
+| {#action git::ExpandCommitEditor} | {#kb git::ExpandCommitEditor} |
+| {#action git::Push} | {#kb git::Push} |
+| {#action git::ForcePush} | {#kb git::ForcePush} |
+| {#action git::Pull} | {#kb git::Pull} |
+| {#action git::PullRebase} | {#kb git::PullRebase} |
+| {#action git::Fetch} | {#kb git::Fetch} |
+| {#action git::Diff} | {#kb git::Diff} |
+| {#action git::Restore} | {#kb git::Restore} |
+| {#action git::RestoreFile} | {#kb git::RestoreFile} |
+| {#action git::Branch} | {#kb git::Branch} |
+| {#action git::Switch} | {#kb git::Switch} |
+| {#action git::CheckoutBranch} | {#kb git::CheckoutBranch} |
+| {#action git::Blame} | {#kb git::Blame} |
+| {#action git::StashAll} | {#kb git::StashAll} |
+| {#action git::StashPop} | {#kb git::StashPop} |
+| {#action git::StashApply} | {#kb git::StashApply} |
+| {#action git::ViewStash} | {#kb git::ViewStash} |
+| {#action editor::ToggleGitBlameInline} | {#kb editor::ToggleGitBlameInline} |
+| {#action editor::ExpandAllDiffHunks} | {#kb editor::ExpandAllDiffHunks} |
+| {#action editor::ToggleSelectedDiffHunks} | {#kb editor::ToggleSelectedDiffHunks} |
+
+> **Note:** Not all actions have default keybindings, but can be bound by [customizing your keymap](./key-bindings.md#user-keymaps).
+
+## Git CLI Configuration {#cli-configuration}
+
+If you would like to also use Zed for your [git commit message editor](https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_core_editor) when committing from the command line you can use `zed --wait`:
+
+```sh
+git config --global core.editor "zed --wait"
+```
+
+Or add the following to your shell environment (in `~/.zshrc`, `~/.bashrc`, etc):
+
+```sh
+export GIT_EDITOR="zed --wait"
+```
@@ -0,0 +1,158 @@
+<!--
+ GOLD STANDARD EXAMPLE: Configuration Documentation
+
+ This example demonstrates documentation for settings and configuration.
+
+ Key patterns to note:
+ - Anchor IDs on all major sections
+ - Opening paragraph explains what this guide covers
+ - Multiple JSON examples with [settings] annotation
+ - Platform-specific file paths
+ - Proper callout formatting
+ - "See Also" section at the end (not "What's Next")
+-->
+
+---
+
+title: Configuring Zed - Settings and Preferences
+description: Configure Zed with the Settings Editor, JSON files, and project-specific overrides. Covers all settings options.
+
+---
+
+# Configuring Zed
+
+This guide explains how Zed's settings system works, including the Settings Editor, JSON configuration files, and project-specific settings.
+
+For visual customization (themes, fonts, icons), see [Appearance](./appearance.md).
+
+## Settings Editor {#settings-editor}
+
+The **Settings Editor** ({#kb zed::OpenSettings}) is the primary way to configure Zed. It provides a searchable interface where you can browse available settings, see their current values, and make changes.
+
+To open it:
+
+- Press {#kb zed::OpenSettings}
+- Or run `zed: open settings` from the command palette
+
+As you type in the search box, matching settings appear with descriptions and controls to modify them. Changes save automatically to your settings file.
+
+> **Note:** Not all settings are available in the Settings Editor yet. Some advanced options, like language formatters, require editing the JSON file directly.
+
+## Settings Files {#settings-files}
+
+### User Settings {#user-settings}
+
+Your user settings apply globally across all projects. Open the file with {#kb zed::OpenSettingsFile} or run `zed: open settings file` from the command palette.
+
+The file is located at:
+
+- macOS: `~/.config/zed/settings.json`
+- Linux: `~/.config/zed/settings.json` (or `$XDG_CONFIG_HOME/zed/settings.json`)
+- Windows: `%APPDATA%\Zed\settings.json`
+
+The syntax is JSON with support for `//` comments.
+
+### Default Settings {#default-settings}
+
+To see all available settings with their default values, run {#action zed::OpenDefaultSettings} from the command palette. This opens a read-only reference you can use when editing your own settings.
+
+### Project Settings {#project-settings}
+
+Override user settings for a specific project by creating a `.zed/settings.json` file in your project root. Run {#action zed::OpenProjectSettings} to create this file.
+
+Project settings take precedence over user settings for that project only.
+
+```json [settings]
+// .zed/settings.json
+{
+ "tab_size": 2,
+ "formatter": "prettier",
+ "format_on_save": "on"
+}
+```
+
+You can also add settings files in subdirectories for more granular control.
+
+> **Note:** Not all settings can be set at the project level. Settings that affect the editor globally (like `theme` or `vim_mode`) only work in user settings. Project settings are limited to editor behavior and language tooling options like `tab_size`, `formatter`, and `format_on_save`.
+
+## How Settings Merge {#how-settings-merge}
+
+Settings are applied in layers:
+
+1. **Default settings** β Zed's built-in defaults
+2. **User settings** β Your global preferences
+3. **Project settings** β Project-specific overrides
+
+Later layers override earlier ones. For object settings (like `terminal`), properties merge rather than replace entirely.
+
+## Per-Release Channel Overrides {#release-channel-overrides}
+
+Use different settings for Stable, Preview, or Nightly builds by adding top-level channel keys:
+
+```json [settings]
+{
+ "theme": "One Dark",
+ "vim_mode": false,
+ "nightly": {
+ "theme": "RosΓ© Pine",
+ "vim_mode": true
+ },
+ "preview": {
+ "theme": "Catppuccin Mocha"
+ }
+}
+```
+
+With this configuration:
+
+- **Stable** uses One Dark with vim mode off
+- **Preview** uses Catppuccin Mocha with vim mode off
+- **Nightly** uses RosΓ© Pine with vim mode on
+
+Changes made in the Settings Editor apply across all channels.
+
+## Settings Deep Links {#deep-links}
+
+Zed supports deep links that open specific settings directly:
+
+```
+zed://settings/theme
+zed://settings/vim_mode
+zed://settings/buffer_font_size
+```
+
+These are useful for sharing configuration tips or linking from documentation.
+
+## Example Configuration {#example-configuration}
+
+```json [settings]
+{
+ "theme": {
+ "mode": "system",
+ "light": "One Light",
+ "dark": "One Dark"
+ },
+ "buffer_font_family": "JetBrains Mono",
+ "buffer_font_size": 14,
+ "tab_size": 2,
+ "format_on_save": "on",
+ "autosave": "on_focus_change",
+ "vim_mode": false,
+ "terminal": {
+ "font_family": "JetBrains Mono",
+ "font_size": 14
+ },
+ "languages": {
+ "Python": {
+ "tab_size": 4
+ }
+ }
+}
+```
+
+## See Also {#see-also}
+
+- [Appearance](./appearance.md) β Themes, fonts, and visual customization
+- [Key bindings](./key-bindings.md) β Customize keyboard shortcuts
+- [AI Configuration](./ai/configuration.md) β Set up AI providers, models, and agent settings
+- [All Settings](./reference/all-settings.md) β Complete settings reference
@@ -0,0 +1,119 @@
+<!--
+ GOLD STANDARD EXAMPLE: Reference Documentation
+
+ This example demonstrates documentation for API/reference content like tools,
+ actions, or other enumerable items.
+
+ Key patterns to note:
+ - Anchor IDs on categories and individual items for deep-linking
+ - Opening paragraph explains what these are and where they're used
+ - Organized into logical categories
+ - Each item has a clear, actionable description
+ - Links to related configuration docs
+ - "See Also" section for related topics
+-->
+
+---
+
+title: AI Agent Tools - Zed
+description: Built-in tools for Zed's AI agent including file editing, code search, terminal commands, web search, and diagnostics.
+
+---
+
+# Tools
+
+Zed's built-in agent has access to these tools for reading, searching, and editing your codebase. These tools are used in the [Agent Panel](./agent-panel.md) during conversations with AI agents.
+
+You can configure permissions for tool actions, including situations where they are automatically approved, automatically denied, or require your confirmation on a case-by-case basis. See [Tool Permissions](./tool-permissions.md) for the list of permission-gated tools and details.
+
+To add custom tools beyond these built-in ones, see [MCP servers](./mcp.md).
+
+## Read & Search Tools {#read-search-tools}
+
+### `diagnostics` {#diagnostics}
+
+Gets errors and warnings for either a specific file or the entire project, useful after making edits to determine if further changes are needed.
+When a path is provided, shows all diagnostics for that specific file.
+When no path is provided, shows a summary of error and warning counts for all files in the project.
+
+### `fetch` {#fetch}
+
+Fetches a URL and returns the content as Markdown. Useful for providing docs as context.
+
+### `find_path` {#find-path}
+
+Quickly finds files by matching glob patterns (like `**/*.js`), returning matching file paths alphabetically.
+
+### `grep` {#grep}
+
+Searches file contents across the project using regular expressions, preferred for finding symbols in code without knowing exact file paths.
+
+### `list_directory` {#list-directory}
+
+Lists files and directories in a given path, providing an overview of filesystem contents.
+
+### `now` {#now}
+
+Returns the current date and time.
+
+### `open` {#open}
+
+Opens a file or URL with the default application associated with it on the user's operating system.
+
+### `read_file` {#read-file}
+
+Reads the content of a specified file in the project, allowing access to file contents.
+
+### `thinking` {#thinking}
+
+Allows the Agent to work through problems, brainstorm ideas, or plan without executing actions, useful for complex problem-solving.
+
+### `web_search` {#web-search}
+
+Searches the web for information, providing results with snippets and links from relevant web pages, useful for accessing real-time information.
+
+## Edit Tools {#edit-tools}
+
+### `copy_path` {#copy-path}
+
+Copies a file or directory recursively in the project, more efficient than manually reading and writing files when duplicating content.
+
+### `create_directory` {#create-directory}
+
+Creates a new directory at the specified path within the project, creating all necessary parent directories (similar to `mkdir -p`).
+
+### `delete_path` {#delete-path}
+
+Deletes a file or directory (including contents recursively) at the specified path and confirms the deletion.
+
+### `edit_file` {#edit-file}
+
+Edits files by replacing specific text with new content.
+
+### `move_path` {#move-path}
+
+Moves or renames a file or directory in the project, performing a rename if only the filename differs.
+
+### `restore_file_from_disk` {#restore-file}
+
+Discards unsaved changes in open buffers by reloading file contents from disk. Useful for resetting files to their on-disk state before retrying an edit.
+
+### `save_file` {#save-file}
+
+Saves files that have unsaved changes. Used when files need to be saved before further edits can be made.
+
+### `terminal` {#terminal}
+
+Executes shell commands and returns the combined output, creating a new shell process for each invocation.
+
+## Other Tools {#other-tools}
+
+### `subagent` {#subagent}
+
+Spawns a subagent with its own context window to perform a delegated task. Useful for running parallel investigations, completing self-contained tasks, or performing research where only the outcome matters. Each subagent has access to the same tools as the parent agent.
+
+## See Also {#see-also}
+
+- [Agent Panel](./agent-panel.md) β Where you interact with AI agents
+- [Tool Permissions](./tool-permissions.md) β Configure which tools require approval
+- [MCP Servers](./mcp.md) β Add custom tools via Model Context Protocol
@@ -0,0 +1,81 @@
+<!--
+ GOLD STANDARD EXAMPLE: Simple Feature / Overview Documentation
+
+ This example demonstrates concise documentation for a feature overview
+ or navigation guide.
+
+ Key patterns to note:
+ - Anchor IDs on all sections
+ - Brief opening paragraph explains what this covers
+ - Each section is concise (1-2 paragraphs max)
+ - Links to detailed docs for each feature
+ - Quick reference table at the end
+ - Uses {#kb ...} syntax for all keybindings
+-->
+
+---
+
+title: Finding and Navigating Code - Zed
+description: Navigate your codebase in Zed with file finder, project search, go to definition, symbol search, and the command palette.
+
+---
+
+# Finding & Navigating
+
+Zed provides several ways to move around your codebase quickly. Here's an overview of the main navigation tools.
+
+## Command Palette {#command-palette}
+
+The Command Palette ({#kb command_palette::Toggle}) is your gateway to almost everything in Zed. Type a few characters to filter commands, then press Enter to execute.
+
+[Learn more about the Command Palette β](./command-palette.md)
+
+## File Finder {#file-finder}
+
+Open any file in your project with {#kb file_finder::Toggle}. Type part of the filename or path to narrow results.
+
+## Project Search {#project-search}
+
+Search across all files with {#kb pane::DeploySearch}. Results appear in a [multibuffer](./multibuffers.md), letting you edit matches in place.
+
+## Go to Definition {#go-to-definition}
+
+Jump to where a symbol is defined with {#kb editor::GoToDefinition} (or `Cmd+Click` / `Ctrl+Click`). If there are multiple definitions, they open in a multibuffer.
+
+## Go to Symbol {#go-to-symbol}
+
+- **Current file:** {#kb outline::Toggle} opens an outline of symbols in the active file
+- **Entire project:** {#kb project_symbols::Toggle} searches symbols across all files
+
+## Outline Panel {#outline-panel}
+
+The Outline Panel ({#kb outline_panel::ToggleFocus}) shows a persistent tree view of symbols in the current file. It's especially useful with [multibuffers](./multibuffers.md) for navigating search results or diagnostics.
+
+[Learn more about the Outline Panel β](./outline-panel.md)
+
+## Tab Switcher {#tab-switcher}
+
+Quickly switch between open tabs with {#kb tab_switcher::Toggle}. Tabs are sorted by recent useβkeep holding Ctrl and press Tab to cycle through them.
+
+[Learn more about the Tab Switcher β](./tab-switcher.md)
+
+## Quick Reference {#quick-reference}
+
+| Task | Keybinding |
+| ----------------- | -------------------------------- |
+| Command Palette | {#kb command_palette::Toggle} |
+| Open file | {#kb file_finder::Toggle} |
+| Project search | {#kb pane::DeploySearch} |
+| Go to definition | {#kb editor::GoToDefinition} |
+| Find references | {#kb editor::FindAllReferences} |
+| Symbol in file | {#kb outline::Toggle} |
+| Symbol in project | {#kb project_symbols::Toggle} |
+| Outline Panel | {#kb outline_panel::ToggleFocus} |
+| Tab Switcher | {#kb tab_switcher::Toggle} |
+
+## See Also {#see-also}
+
+- [Command Palette](./command-palette.md) β Full command palette documentation
+- [Multibuffers](./multibuffers.md) β Edit multiple files simultaneously
+- [Outline Panel](./outline-panel.md) β Symbol tree view
+- [Tab Switcher](./tab-switcher.md) β Switch between open files