logiguard fork: GPUI xdg-activation keyboard-focus serial fix

Single-commit orphan branch: full zed-industries/zed @ 8c74db0 source tree
with a 3-file patch applied (no upstream history).

Patch (crates/gpui_linux/src/linux/wayland/):
  - serial.rs: add SerialKind::KeyboardEnter
  - client.rs: store wl_keyboard.enter serial; add latest_serial_of()
  - window.rs: activate() uses keyboard-enter serial (Mutter focus gate)

Mutter honors window activation only when the token carries the keyboard-
focus serial from wl_keyboard.enter; GPUI used a stale mouse-press serial.
See docs/tray-window-focus-wayland.md in logiguard.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/.conventions/CONVENTIONS.md

@@ -0,0 +1,380 @@
+# 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
+- Keep frontmatter values as simple single-line `key: value` entries (no
+  multiline values, no quotes) for compatibility with the docs postprocessor
+
+#### Frontmatter SEO Guidelines
+
+- Choose one primary keyword/intent phrase for each page
+- Write unique `title` values that clearly state the page topic and target user
+  intent; aim for ~50-60 characters
+- Write `description` values that summarize what the reader can do on the page;
+  aim for ~140-160 characters
+- Use the primary keyword naturally in the `title` and page body at least once
+  (usually in the opening paragraph); avoid keyword stuffing
+
+### 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
+```
+
+### SEO Linking Guidelines
+
+- Ensure each page is reachable from at least one other docs page (no orphan
+  pages)
+- For non-reference pages, include at least 3 internal links to related docs
+  when possible
+- Reference pages (for example, `docs/src/reference/*`) can use fewer links when
+  extra links would add noise
+- Add links to closely related docs where they help users complete the next task
+- Use descriptive link text that tells users what they will get on the linked
+  page
+- For main feature pages with a matching marketing page, include a relevant
+  `zed.dev` marketing link in addition to docs links
+
+---
+
+## 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`
+- [ ] Page has a clear primary keyword/intent phrase
+- [ ] Primary keyword appears naturally in the page body (no keyword stuffing)
+- [ ] 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)
+- [ ] Non-reference pages include at least 3 useful internal docs links
+- [ ] Main feature pages include a relevant `zed.dev` marketing link
+- [ ] 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`.

docs/.conventions/brand-voice/SKILL.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.

docs/.conventions/brand-voice/rubric.md

@@ -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.

docs/.conventions/brand-voice/taboo-phrases.md

@@ -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

docs/.conventions/brand-voice/voice-examples.md

@@ -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 |

docs/.doc-examples/complex-feature.md

@@ -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 view File History:
+
+- Right-click on a file in the Project Panel and select "View File History"
+- Right-click on a file in the Git Panel and select "View File History"
+- Right-click on an editor tab and select "View 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"
+```

docs/.doc-examples/configuration.md

@@ -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 {#action zed::OpenSettings} 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 {#action zed::OpenSettingsFile} 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

docs/.doc-examples/reference.md

@@ -0,0 +1,103 @@
+<!--
+  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.
+
+### `read_file` {#read-file}
+
+Reads the content of a specified file in the project, allowing access to file contents.
+
+### `search_web` {#search-web}
+
+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.
+
+### `write_file` {#write-file}
+
+Creates a new file or overwrites an existing file with completely new contents.
+
+### `terminal` {#terminal}
+
+Executes shell commands and returns the combined output, creating a new shell process for each invocation.
+
+## Other Tools {#other-tools}
+
+### `spawn_agent` {#spawn-agent}
+
+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

docs/.doc-examples/simple-feature.md

@@ -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

docs/.gitignore

@@ -0,0 +1 @@
+book/

docs/.prettierignore

@@ -0,0 +1,5 @@
+# Handlebars partials are not supported by Prettier.
+*.hbs
+
+# Automatically generated
+theme/c15t@*.js

docs/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "printWidth": 80
+}

docs/.rules

@@ -0,0 +1,169 @@
+# Zed Documentation Guidelines
+
+## Voice and Tone
+
+### Core Principles
+
+- **Practical over promotional**: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
+- **Honest about limitations**: When Zed lacks a feature or doesn't match another tool's depth, say so directly. Pair limitations with workarounds or alternative workflows.
+- **Direct and concise**: Use short sentences. Get to the point. Developers are scanning, not reading novels.
+- **Second person**: Address the reader as "you." Avoid "the user" or "one."
+- **Present tense**: "Zed opens the file" not "Zed will open the file."
+
+### What to Avoid
+
+- Superlatives without substance ("incredibly fast," "seamlessly integrated")
+- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
+- Apologetic tone for missing features—state the limitation and move on
+- Comparisons that disparage other tools—be factual, not competitive
+- Meta-commentary about honesty ("the honest take is...", "to be frank...", "honestly...")—let honesty show through frank assessments, not announcements
+- LLM-isms and filler words ("entirely," "certainly,", "deeply," "definitely," "actually")—these add nothing
+
+## Content Structure
+
+### Page Organization
+
+1. **Start with the goal**: Open with what the reader will accomplish, not background
+2. **Front-load the action**: Put the most common task first, edge cases later
+3. **Use headers liberally**: Readers scan; headers help them find what they need
+4. **End with "what's next"**: Link to related docs or logical next steps
+
+### Section Patterns
+
+For how-to content:
+1. Brief context (1-2 sentences max)
+2. Steps or instructions
+3. Example (code block or screenshot reference)
+4. Tips or gotchas (if any)
+
+For reference content:
+1. What it is (definition)
+2. How to access/configure it
+3. Options/parameters table
+4. Examples
+
+## Formatting Conventions
+
+### Keybindings
+
+- Use backticks for key combinations: `Cmd+Shift+P`
+- Show both macOS and Linux/Windows when they differ: `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows)
+- Use `+` to join simultaneous keys, space for sequences: `Cmd+K Cmd+C`
+
+### Code and Settings
+
+- Inline code for setting names, file paths, commands: `format_on_save`, `.zed/settings.json`, `zed .`
+- Code blocks for JSON config, multi-line commands, or file contents
+- Always show complete, working examples—not fragments
+
+### Terminal Commands
+
+Use `sh` code blocks for terminal commands, not plain backticks:
+
+```sh
+brew install zed-editor/zed/zed
+```
+
+Not:
+```
+brew install zed-editor/zed/zed
+```
+
+For single inline commands in prose, backticks are fine: `zed .`
+
+### Tables
+
+Use tables for:
+- Keybinding comparisons between editors
+- Settings mappings (e.g., VS Code → Zed)
+- Feature comparisons with clear columns
+
+Format:
+```
+| Action | Shortcut | Notes |
+| --- | --- | --- |
+| Open File | `Cmd+O` | Works from any context |
+```
+
+### Tips and Notes
+
+Use blockquote format with bold label:
+```
+> **Tip:** Practical advice that helps bridge gaps or saves time.
+```
+
+Reserve tips for genuinely useful information, not padding.
+
+## Writing Guidelines
+
+### Settings Documentation
+
+- **Settings Editor first**: Show how to find and change settings in the UI before showing JSON
+- **JSON as secondary**: Present JSON examples as "Or add this to your settings.json" for users who prefer direct editing
+- **Complete examples**: Include the full JSON structure, not just the value
+
+### Migration Guides
+
+- **Jobs to be done**: Frame around tasks ("How do I search files?") not features ("File Search Feature")
+- **Acknowledge the source**: Respect that users have muscle memory and preferences from their previous editor
+- **Keybindings tables**: Essential for migration docs—show what maps, what's different, what's missing
+- **Trade-offs section**: Be explicit about what the user gains and loses in the switch
+
+### Feature Documentation
+
+- **Start with the default**: Document the out-of-box experience first
+- **Configuration options**: Group related settings together
+- **Cross-link generously**: Link to related features, settings reference, and relevant guides
+
+## Terminology
+
+| Use | Instead of |
+| --- | --- |
+| folder | directory (in user-facing text) |
+| project | workspace (Zed doesn't have workspaces) |
+| Settings Editor | settings UI, preferences |
+| command palette | command bar, action search |
+| language server | LSP (spell out first use, then LSP is fine) |
+| panel | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
+
+## Examples
+
+### Good: Direct and actionable
+```
+To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
+
+Or add this to your settings.json:
+{
+  "format_on_save": "on"
+}
+```
+
+### Bad: Wordy and promotional
+```
+Zed provides a powerful and seamless formatting experience. Simply navigate to the settings and you'll find the format_on_save option which enables Zed's incredible auto-formatting capabilities.
+```
+
+### Good: Honest about limitations
+```
+Zed doesn't index your project like IntelliJ does. You open a folder and start working immediately—no waiting. The trade-off: cross-project analysis relies on language servers, which may not go as deep.
+
+**How to adapt:**
+- Use `Cmd+Shift+F` for project-wide text search
+- Use `Cmd+O` for symbol search (powered by your language server)
+```
+
+### Bad: Defensive or dismissive
+```
+While some users might miss indexing, Zed's approach is actually better because it's faster.
+```
+
+## Pull request hygiene
+
+- Include a `Release Notes:` section as the final section in the PR body.
+- For docs-only PRs, use exactly:
+
+```
+Release Notes:
+
+- N/A
+```

docs/AGENTS.md

@@ -0,0 +1,407 @@
+# 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
+![Alt text description](https://zed.dev/img/path/to/image.webp)
+```
+
+### Cross-Linking
+
+- Relative links for same-directory: `[Agent Panel](./agent-panel.md)`
+- With anchors: `[Custom Models](./llm-providers.md#anthropic-custom-models)`
+- Parent directory: `[Telemetry](../telemetry.md)`
+
+## Voice and Tone
+
+### Core Principles
+
+- **Practical over promotional**: Focus on what users can do, not on selling Zed. Avoid marketing language like "powerful," "revolutionary," or "best-in-class."
+- **Honest about limitations**: When Zed lacks a feature or doesn't match another tool's depth, say so directly. Pair limitations with workarounds or alternative workflows.
+- **Direct and concise**: Use short sentences. Get to the point. Developers are scanning, not reading novels.
+- **Second person**: Address the reader as "you." Avoid "the user" or "one."
+- **Present tense**: "Zed opens the file" not "Zed will open the file."
+
+### What to Avoid
+
+- Superlatives without substance ("incredibly fast," "seamlessly integrated")
+- Hedging language ("simply," "just," "easily")—if something is simple, the instructions will show it
+- Apologetic tone for missing features—state the limitation and move on
+- Comparisons that disparage other tools—be factual, not competitive
+- Lots of use of em or en dashes.
+
+## Examples of Good Copy
+
+### Good: Direct and actionable
+
+```
+To format on save, open the Settings Editor (`Cmd+,`) and search for `format_on_save`. Set it to `on`.
+
+Or add this to your settings.json:
+{
+  "format_on_save": "on"
+}
+```
+
+### Bad: Wordy and promotional
+
+```
+Zed provides a powerful and seamless formatting experience. Simply navigate to the settings and you'll find the format_on_save option which enables Zed's incredible auto-formatting capabilities.
+```
+
+### Good: Honest about limitations
+
+```
+Zed doesn't index your project like IntelliJ does. You open a folder and start working immediately—no waiting. The trade-off: cross-project analysis relies on language servers, which may not go as deep.
+
+**How to adapt:**
+- Use `Cmd+Shift+F` for project-wide text search
+- Use `Cmd+O` for symbol search (powered by your language server)
+```
+
+### Bad: Defensive or dismissive
+
+```
+While some users might miss indexing, Zed's approach is actually better because it's faster.
+```
+
+## 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           | tool window, sidebar (be specific: "Project Panel," "Terminal Panel") |
+| language server | LSP (spell out first use, then LSP is fine)                           |
+
+## 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

docs/README.md

@@ -0,0 +1,159 @@
+# Zed Docs
+
+Welcome to Zed's documentation.
+
+This is built on push to `main` and published automatically to [https://zed.dev/docs](https://zed.dev/docs).
+
+To preview the docs locally you will need to install [mdBook](https://rust-lang.github.io/mdBook/) (`cargo install mdbook@0.4.40`), generate the action metadata, and then serve:
+
+```sh
+script/generate-action-metadata
+mdbook serve docs
+```
+
+The first command dumps an action manifest to `crates/docs_preprocessor/actions.json`. Without it, the preprocessor cannot validate keybinding and action references in the docs and will report errors. You only need to re-run it when actions change.
+
+It's important to note the version number above. For an unknown reason, as of 2025-04-23, running 0.4.48 will cause odd URL behavior that breaks things.
+
+Before committing, verify that the docs are formatted in the way Prettier expects with:
+
+```
+cd docs && pnpm dlx prettier@3.5.0 . --write && cd ..
+```
+
+## Preprocessor
+
+We have a custom mdBook preprocessor for interfacing with our crates (`crates/docs_preprocessor`).
+
+If for some reason you need to bypass the docs preprocessor, you can comment out `[preprocessor.zed_docs_preprocessor]` from the `book.toml`.
+
+## Images and videos
+
+To add images or videos to the docs, upload them to another location (e.g., zed.dev, GitHub's asset storage) and then link out to them from the docs.
+
+Putting binary assets such as images in the Git repository will bloat the repository size over time.
+
+## Internal notes:
+
+- We have a Cloudflare router called `docs-proxy` that intercepts requests to `zed.dev/docs` and forwards them to the "docs" Cloudflare Pages project.
+- The CI uploads a new version to the Cloudflare Pages project from `.github/workflows/deploy_docs.yml` on every push to `main`.
+
+### Table of Contents
+
+The table of contents files (`theme/page-toc.js` and `theme/page-doc.css`) were initially generated by [`mdbook-pagetoc`](https://crates.io/crates/mdbook-pagetoc).
+
+Since all this preprocessor does is generate the static assets, we don't need to keep it around once they have been generated.
+
+## Referencing Keybindings and Actions
+
+When referencing keybindings or actions, use the following formats:
+
+### Keybindings
+
+{#kb scope::Action} - e.g., {#kb zed::OpenSettings}.
+
+This will output a code element like: `<code>Cmd + , | Ctrl + ,</code>`. We then use a client-side plugin to show the actual keybinding based on the user's platform.
+
+By using the action name, we can ensure that the keybinding is always up-to-date rather than hardcoding the keybinding.
+
+#### Keymap Overlays
+
+`{#kb:keymap_name scope::Action}` - e.g., `{#kb:jetbrains editor::GoToDefinition}`.
+
+This resolves the keybinding from a keymap overlay (e.g., JetBrains) first, falling back to the default keymap if the overlay doesn't define a binding for that action. This is useful for sections where the documentation expects a special base keymap to be configured.
+
+Supported overlays: `jetbrains`.
+
+### Actions
+
+{#action scope::Action} - e.g., {#action zed::OpenSettings}.
+
+This will render a human-readable version of the action name, e.g., "zed: open settings", and will allow us to implement things like additional context on hover, etc.
+
+### Creating New Templates
+
+Templates are functions that modify the source of the docs pages (usually with a regex match and replace).
+You can see how the actions and keybindings are templated in `crates/docs_preprocessor/src/main.rs` for reference on how to create new templates.
+
+## Consent Banner
+
+We pre-bundle the `c15t` package because the docs pipeline does not include a JS bundler. If you need to update `c15t` and rebuild the bundle, use:
+
+```
+mkdir c15t-bundle && cd c15t-bundle
+npm init -y
+npm install c15t@<version> esbuild
+echo "import { getOrCreateConsentRuntime } from 'c15t'; window.c15t = { getOrCreateConsentRuntime };" > entry.js
+npx esbuild entry.js --bundle --format=iife --minify --outfile=c15t@<version>.js
+cp c15t@<version>.js ../theme/c15t@<version>.js
+cd .. && rm -rf c15t-bundle
+```
+
+Replace `<version>` with the new version of `c15t` you are installing. Then update `book.toml` to reference the new bundle filename.
+
+### References
+
+- Template Trait: `crates/docs_preprocessor/src/templates.rs`
+- Example template: `crates/docs_preprocessor/src/templates/keybinding.rs`
+- Client-side plugins: `docs/theme/plugins.js`
+
+## Postprocessor
+
+A postprocessor is implemented as a sub-command of `docs_preprocessor` that wraps the built-in HTML renderer and applies post-processing to the HTML files, to add support for page-specific title and `meta` tag description values.
+
+An example of the syntax can be found in `git.md`, as well as below:
+
+```md
+---
+title: Some more detailed title for this page
+description: A page-specific description
+---
+
+# Editor
+```
+
+The above code will be transformed into (with non-relevant tags removed):
+
+```html
+<head>
+  <title>Editor | Some more detailed title for this page</title>
+  <meta name="description" contents="A page-specific description" />
+</head>
+<body>
+  <h1>Editor</h1>
+</body>
+```
+
+If no front matter is provided, or if one or both keys aren't provided, the `title` and `description` will be set based on the `default-title` and `default-description` keys in `book.toml` respectively.
+
+### Implementation details
+
+Unfortunately, mdBook does not support post-processing like it does pre-processing, and only supports defining one description to put in the `meta` tag per book rather than per file.
+So in order to apply post-processing (necessary to modify the HTML `head` tags) the global book description is set to a marker value `#description#` and the HTML renderer is replaced with a sub-command of `docs_preprocessor` that wraps the built-in HTML renderer and applies post-processing to the HTML files, replacing the marker value and the `<title>(.*)</title>` with the contents of the front matter if there is one.
+
+### Known limitations
+
+The front matter parsing is extremely simple, which avoids needing to take on an additional dependency, or implement full YAML parsing.
+
+- Double quotes and multi-line values are not supported, i.e. Keys and values must be entirely on the same line, with no double quotes around the value.
+
+The following will not work:
+
+```md
+---
+title: Some
+  Multi-line
+  Title
+---
+```
+
+neither this:
+
+```md
+---
+title: "Some title"
+---
+```
+
+- The front matter must be at the top of the file, with only white-space preceding it.
+- The contents of the `title` and `description` will not be HTML escaped. They should be simple ASCII text with no unicode or emoji characters.

docs/book.toml

@@ -0,0 +1,106 @@
+[book]
+authors = ["The Zed Team"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Zed"
+site-url = "/docs/"
+
+[build]
+extra-watch-dirs = ["../crates/docs_preprocessor"]
+
+# zed-html is a "custom" renderer that just wraps the
+# builtin mdbook html renderer, and applies post-processing
+# as post-processing is not possible with mdbook in the same way
+# pre-processing is
+# The config is passed directly to the html renderer, so all config
+# options that apply to html apply to zed-html
+[output.zed-html]
+command = "cargo run -p docs_preprocessor -- postprocess"
+# Set here instead of above as we only use it replace the `#description#` we set in the template
+# when no front-matter is provided value
+default-description = "Learn how to use and customize Zed, the fast, collaborative code editor. Official docs on features, configuration, AI tools, and workflows."
+default-title = "Zed Code Editor Documentation"
+no-section-label = true
+preferred-dark-theme = "dark"
+additional-css = ["theme/page-toc.css", "theme/plugins.css", "theme/highlight.css", "theme/consent-banner.css"]
+additional-js  = ["theme/page-toc.js", "theme/plugins.js", "theme/c15t@2.0.0-rc.3.js", "theme/analytics.js"]
+
+[output.zed-html.print]
+enable = false
+
+# Redirects for `/docs` pages.
+#
+# All of the source URLs are interpreted relative to mdBook, so they must:
+# 1. Not start with `/docs`
+# 2. End in `.html`
+#
+# The destination URLs are interpreted relative to `https://zed.dev`.
+# - Redirects to other docs pages should end in `.html`
+# - You can link to pages on the Zed site by omitting the `/docs` in front of it.
+[output.zed-html.redirect]
+# AI
+"/ai.html" = "/docs/ai/overview.html"
+"/assistant-panel.html" = "/docs/ai/agent-panel.html"
+"/assistant.html" = "/docs/assistant/assistant.html"
+"/assistant/assistant-panel.html" = "/docs/ai/agent-panel.html"
+"/assistant/assistant.html" = "/docs/ai/overview.html"
+"/assistant/commands.html" = "/docs/ai/text-threads.html"
+"/assistant/configuration.html" = "/docs/ai/configuration.html"
+"/assistant/context-servers.html" = "/docs/ai/mcp.html"
+"/assistant/contexts.html" = "/docs/ai/text-threads.html"
+"/assistant/inline-assistant.html" = "/docs/ai/inline-assistant.html"
+"/assistant/model-context-protocol.html" = "/docs/ai/mcp.html"
+"/assistant/prompting.html" = "/docs/ai/rules.html"
+"/language-model-integration.html" = "/docs/assistant/assistant.html"
+"/model-improvement.html" = "/docs/ai/ai-improvement.html"
+"/ai/temperature.html" = "/docs/ai/agent-settings.html#model-temperature"
+"/ai/subscription.html" = "/docs/ai/plans-and-usage.html"
+
+# Core
+"/configuring-zed.html" = "/docs/reference/all-settings.html"
+
+# Collaboration
+"/channels.html" = "/docs/collaboration/channels.html"
+"/collaboration.html" = "/docs/collaboration/overview.html"
+
+# Community
+"/community/feedback.html" = "/community-links"
+"/conversations.html" = "/community-links"
+
+# Debugger
+"/debuggers.html" = "/docs/debugger.html"
+
+# MCP
+"/assistant/model-context-protocolCitedby.html" = "/docs/ai/mcp.html"
+"/context-servers.html" = "/docs/ai/mcp.html"
+"/extensions/context-servers.html" = "/docs/extensions/mcp-extensions.html"
+
+# Languages
+"/adding-new-languages.html" = "/docs/extensions/languages.html"
+"/elixir.html" = "/docs/languages/elixir.html"
+"/javascript.html" = "/docs/languages/javascript.html"
+"/languages/languages/html.html" = "/docs/languages/html.html"
+"/languages/languages/javascript.html" = "/docs/languages/javascript.html"
+"/languages/languages/makefile.html" = "/docs/languages/makefile.html"
+"/languages/languages/nim.html" = "/docs/languages/nim.html"
+"/languages/languages/ruby.html" = "/docs/languages/ruby.html"
+"/languages/languages/scala.html" = "/docs/languages/scala.html"
+"/python.html" = "/docs/languages/python.html"
+"/ruby.html" = "/docs/languages/ruby.html"
+
+# Zed development
+"/contribute-to-zed.html" = "/docs/development.html#contributor-links"
+"/contributing.html" = "/docs/development.html#contributor-links"
+"/developing-zed.html" = "/docs/development.html"
+"/development/development/linux.html" = "/docs/development/linux.html"
+"/development/development/macos.html" = "/docs/development/macos.html"
+"/development/development/windows.html" = "/docs/development/windows.html"
+
+# Our custom preprocessor for expanding commands like `{#kb action::ActionName}`,
+# and other docs-related functions.
+#
+# Comment the below section out if you need to bypass the preprocessor for some reason.
+[preprocessor.zed_docs_preprocessor]
+command = "cargo run -p docs_preprocessor --"
+renderer = ["html", "zed-html"]

docs/src/SUMMARY.md

@@ -0,0 +1,217 @@
+# Summary
+
+# Welcome
+
+- [Getting Started](./getting-started.md)
+- [Installation](./installation.md)
+  - [Update](./update.md)
+  - [Uninstall](./uninstall.md)
+- [Troubleshooting](./troubleshooting.md)
+
+# AI
+
+- [Overview](./ai/overview.md)
+- [Agent Panel](./ai/agent-panel.md)
+  - [Tools](./ai/tools.md)
+  - [Tool Permissions](./ai/tool-permissions.md)
+  - [External Agents](./ai/external-agents.md)
+- [Parallel Agents](./ai/parallel-agents.md)
+- [Inline Assistant](./ai/inline-assistant.md)
+- [Edit Prediction](./ai/edit-prediction.md)
+- [Rules](./ai/rules.md)
+- [Model Context Protocol](./ai/mcp.md)
+- [Configuration](./ai/configuration.md)
+  - [Agent Settings](./ai/agent-settings.md)
+- [Models](./ai/models.md)
+- [Providers](./ai/llm-providers.md)
+
+# Working with Code
+
+- [Windows & Projects](./windows-and-projects.md)
+- [Editing Code](./editing-code.md)
+  - [Code Completions](./completions.md)
+  - [Snippets](./snippets.md)
+  - [Diagnostics & Quick Fixes](./diagnostics.md)
+  - [Multibuffers](./multibuffers.md)
+- [Finding & Navigating](./finding-navigating.md)
+  - [Command Palette](./command-palette.md)
+  - [Outline Panel](./outline-panel.md)
+  - [Project Panel](./project-panel.md)
+  - [Tab Switcher](./tab-switcher.md)
+- [Running & Testing](./running-testing.md)
+  - [Terminal](./terminal.md)
+  - [Tasks](./tasks.md)
+  - [Debugger](./debugger.md)
+  - [REPL](./repl.md)
+- [Git](./git.md)
+- [Modelines](./modelines.md)
+
+# Collaboration
+
+- [Overview](./collaboration/overview.md)
+  - [Channels](./collaboration/channels.md)
+  - [Contacts and Private Calls](./collaboration/contacts-and-private-calls.md)
+
+# Remote Development
+
+- [Overview](./remote-development.md)
+- [Environment Variables](./environment.md)
+- [Dev Containers](./dev-containers.md)
+
+# Account & Billing
+
+- [Authenticate](./authentication.md)
+- [Plans & Pricing](./ai/plans-and-usage.md)
+- [Billing](./ai/billing.md)
+
+# Zed Business
+
+- [Overview](./business/overview.md)
+- [Organizations](./business/organizations.md)
+- [Roles & Permissions](./roles.md)
+- [Admin Controls](./business/admin-controls.md)
+- [Business Support](./business/business-support.md)
+
+# Privacy & Security
+
+- [Overview](./ai/privacy-and-security.md)
+  - [Worktree Trust](./worktree-trust.md)
+  - [AI Improvement](./ai/ai-improvement.md)
+- [Privacy for Business](./business/privacy.md)
+- [Telemetry](./telemetry.md)
+- [SOC2](./soc2.md)
+
+# Platform Support
+
+- [macOS](./macos.md)
+- [Windows](./windows.md)
+- [Linux](./linux.md)
+
+# Customization
+
+- [Appearance](./appearance.md)
+  - [Themes](./themes.md)
+  - [Icon Themes](./icon-themes.md)
+  - [Fonts & Visual Tweaks](./visual-customization.md)
+- [Keybindings](./key-bindings.md)
+  - [Vim Mode](./vim.md)
+  - [Helix Mode](./helix.md)
+
+# Language Support
+
+- [All Languages](./languages.md)
+- [Configuring Languages](./configuring-languages.md)
+  - [Toolchains](./toolchains.md)
+  - [Semantic Tokens](./semantic-tokens.md)
+- [Ansible](./languages/ansible.md)
+- [AsciiDoc](./languages/asciidoc.md)
+- [Astro](./languages/astro.md)
+- [Bash](./languages/bash.md)
+- [Biome](./languages/biome.md)
+- [C](./languages/c.md)
+- [C++](./languages/cpp.md)
+- [C#](./languages/csharp.md)
+- [Clojure](./languages/clojure.md)
+- [CSS](./languages/css.md)
+- [Dart](./languages/dart.md)
+- [Deno](./languages/deno.md)
+- [Diff](./languages/diff.md)
+- [Docker](./languages/docker.md)
+- [Elixir](./languages/elixir.md)
+- [Elm](./languages/elm.md)
+- [Emmet](./languages/emmet.md)
+- [Erlang](./languages/erlang.md)
+- [Fish](./languages/fish.md)
+- [GDScript](./languages/gdscript.md)
+- [Gleam](./languages/gleam.md)
+- [GLSL](./languages/glsl.md)
+- [Go](./languages/go.md)
+- [Groovy](./languages/groovy.md)
+- [Haskell](./languages/haskell.md)
+- [Helm](./languages/helm.md)
+- [HTML](./languages/html.md)
+- [Java](./languages/java.md)
+- [JavaScript](./languages/javascript.md)
+- [Julia](./languages/julia.md)
+- [JSON](./languages/json.md)
+- [Jsonnet](./languages/jsonnet.md)
+- [Kotlin](./languages/kotlin.md)
+- [Lua](./languages/lua.md)
+- [Luau](./languages/luau.md)
+- [Makefile](./languages/makefile.md)
+- [Markdown](./languages/markdown.md)
+- [Nim](./languages/nim.md)
+- [OCaml](./languages/ocaml.md)
+- [OpenTofu](./languages/opentofu.md)
+- [PHP](./languages/php.md)
+- [PowerShell](./languages/powershell.md)
+- [Prisma](./languages/prisma.md)
+- [Proto](./languages/proto.md)
+- [PureScript](./languages/purescript.md)
+- [Python](./languages/python.md)
+- [R](./languages/r.md)
+- [Rego](./languages/rego.md)
+- [ReStructuredText](./languages/rst.md)
+- [Racket](./languages/racket.md)
+- [Roc](./languages/roc.md)
+- [Ruby](./languages/ruby.md)
+- [Rust](./languages/rust.md)
+- [Scala](./languages/scala.md)
+- [Scheme](./languages/scheme.md)
+- [Shell Script](./languages/sh.md)
+- [SQL](./languages/sql.md)
+- [Standard ML](./languages/sml.md)
+- [Svelte](./languages/svelte.md)
+- [Swift](./languages/swift.md)
+- [Tailwind CSS](./languages/tailwindcss.md)
+- [Terraform](./languages/terraform.md)
+- [TOML](./languages/toml.md)
+- [TypeScript](./languages/typescript.md)
+- [Uiua](./languages/uiua.md)
+- [Vue](./languages/vue.md)
+- [XML](./languages/xml.md)
+- [YAML](./languages/yaml.md)
+- [Yara](./languages/yara.md)
+- [Yarn](./languages/yarn.md)
+- [Zig](./languages/zig.md)
+
+# Extensions
+
+- [Overview](./extensions.md)
+- [Installing Extensions](./extensions/installing-extensions.md)
+- [Developing Extensions](./extensions/developing-extensions.md)
+- [Extension Capabilities](./extensions/capabilities.md)
+- [Language Extensions](./extensions/languages.md)
+- [Debugger Extensions](./extensions/debugger-extensions.md)
+- [Theme Extensions](./extensions/themes.md)
+- [Icon Theme Extensions](./extensions/icon-themes.md)
+- [Snippets Extensions](./extensions/snippets.md)
+- [Agent Server Extensions](./extensions/agent-servers.md)
+- [MCP Server Extensions](./extensions/mcp-extensions.md)
+
+# Coming From…
+
+- [VS Code](./migrate/vs-code.md)
+- [IntelliJ IDEA](./migrate/intellij.md)
+- [PyCharm](./migrate/pycharm.md)
+- [WebStorm](./migrate/webstorm.md)
+- [RustRover](./migrate/rustrover.md)
+
+# Reference
+
+- [All Settings](./reference/all-settings.md)
+- [All Actions](./all-actions.md)
+- [CLI Reference](./reference/cli.md)
+
+# Developing Zed
+
+- [Developing Zed](./development.md)
+  - [macOS](./development/macos.md)
+  - [Linux](./development/linux.md)
+  - [Windows](./development/windows.md)
+  - [FreeBSD](./development/freebsd.md)
+  - [Using Debuggers](./development/debuggers.md)
+  - [Performance](./performance.md)
+  - [Glossary](./development/glossary.md)
+- [Release Notes](./development/release-notes.md)
+- [Debugging Crashes](./development/debugging-crashes.md)

docs/src/ai/agent-panel.md

@@ -0,0 +1,259 @@
+---
+title: AI Coding Agent - Zed Agent Panel
+description: Use Zed's AI coding agent to generate, refactor, and debug code with tool calling, checkpoints, and multi-model support.
+---
+
+# Agent Panel
+
+The Agent Panel is where you interact with AI agents that can read, write, and run code in your project.
+It's the core of Zed's AI code editing experience — use it for code generation, refactoring, debugging, documentation, and general questions.
+
+Open it with {#action agent::NewThread} from [the Command Palette](../getting-started.md#command-palette) or click the ✨ icon in the status bar.
+
+## Getting Started {#getting-started}
+
+If you're using the Agent Panel for the first time, you need to have at least one LLM provider or external agent configured.
+You can do that by:
+
+1. [subscribing to our Pro plan](https://zed.dev/pricing), so you have access to our hosted models
+2. [using your own API keys](./llm-providers.md#use-your-own-keys), either from model providers like Anthropic or model gateways like OpenRouter.
+3. using an [external agent](./external-agents.md) like [Gemini CLI](./external-agents.md#gemini-cli) or [Claude Agent](./external-agents.md#claude-agent)
+
+## Overview {#overview}
+
+With an LLM provider or external agent configured, type in the message editor and press `enter` to submit.
+Expand the editor with {#kb agent::ExpandMessageEditor} if you need more room.
+
+Responses stream in with indicators showing [which tools](./tools.md) the model is using.
+The sections below cover what you can do from here.
+
+> Note that for external agents, like [Gemini CLI](./external-agents.md#gemini-cli) or [Claude Agent](./external-agents.md#claude-agent), some of the features outlined below may _not_ be supported—for example, _restoring threads from history_, _checkpoints_, _token usage display_, and others.
+> Their availability varies depending on the agent.
+
+### Creating New Threads {#new-thread}
+
+By default, the Agent Panel uses Zed's first-party agent.
+
+Start a new thread with {#kb agent::NewThread}, or open the "New Thread…" menu using the agent selector button on the left (in the empty state) or the `+` icon in the top-right of the panel toolbar. You can also open that menu with {#kb agent::ToggleNewThreadMenu}.
+
+From the "New Thread…" menu you can:
+
+- Pick **Zed Agent** or any installed [external agent](./external-agents.md) to start a new thread with that agent.
+- Choose **New From Summary** to start a fresh Zed Agent thread seeded with a summary of the current conversation — useful for compacting long threads as you approach the context window limit.
+
+{#action agent::NewExternalAgentThread} creates a new thread with the specified external agent id.
+
+You can also start a new thread from the [Threads Sidebar](./parallel-agents.md#threads-sidebar), scoped to a specific project — see [Running Multiple Threads](./parallel-agents.md#running-multiple-threads).
+
+### Managing Multiple Threads {#multiple-threads}
+
+You can run multiple agent threads at once, each working independently with its own agent, context window, and conversation history. Open the Threads Sidebar with {#kb multi_workspace::ToggleWorkspaceSidebar} to see all your threads grouped by project. Click any thread to switch to it, or use the thread switcher ({#kb agents_sidebar::ToggleThreadSwitcher}) to cycle between recent threads without opening the sidebar.
+
+Threads you're no longer working on can be archived by hovering over them in the sidebar and clicking the archive icon, or selecting them and pressing {#kb agent::ArchiveSelectedThread}. The Thread History holds all your threads across all projects, sorted chronologically, and you can restore them at any time.
+
+If two threads might edit the same files, you can isolate one in a new Git worktree. Use the worktree picker in the title bar to pick which worktree the agent runs in, or create a new one. See [Worktree Isolation](./parallel-agents.md#worktree-isolation) for details.
+
+For more details on the Threads Sidebar and managing multiple projects, see [Parallel Agents](./parallel-agents.md).
+
+### Editing Messages {#editing-messages}
+
+Any message that you send to the model is editable.
+You can click on the card that contains your message and re-submit it with an adjusted prompt and/or new pieces of context.
+
+### Queueing Messages
+
+Messages sent while the agent is in the generating state get, by default, queued.
+
+For the Zed agent, queued messages get sent at the next turn boundary, which is usually between a tool call and a response, whereas for external agents, the message gets sent at the end of the generation.
+
+You can edit or remove (an individual or all) queued messages.
+You can also still interrupt the agent immediately if you want by either clicking on the stop button or by clicking the "Send Now" (double-enter) on a queued message.
+
+### Checkpoints {#checkpoints}
+
+Every time the model performs an edit, you should see a "Restore Checkpoint" button at the top of your message, allowing you to return your code base to the state it was in prior to that message.
+
+The checkpoint button appears even if you interrupt the thread midway through an edit, as this is likely a moment when you've identified that the agent is not heading in the right direction and you want to revert back.
+
+### Context Menu {#context-menu}
+
+Right-click on any agent response in the thread view to access a context menu with the following actions:
+
+- **Copy Selection**: Copies the currently selected text as Markdown (available when text is selected).
+- **Copy This Agent Response**: Copies the full text of the agent response you right-clicked on.
+- **Scroll to Top / Scroll to Bottom**: Scrolls to the beginning or end of the thread, depending on your current position.
+- **Open Thread as Markdown**: Opens the entire thread as a Markdown file in a new tab.
+
+### Navigating the Thread {#navigating-the-thread}
+
+In long conversations, use the scroll arrow buttons at the bottom of the panel to jump to your most recent prompt or to the very beginning of the thread. You can also scroll the thread using arrow keys, Page Up/Down, Home/End, and Shift+Page Up/Down to jump between messages, when the thread pane is focused.
+
+When focus is in the message editor, you can also use {#kb agent::ScrollOutputPageUp}, {#kb agent::ScrollOutputPageDown}, {#kb agent::ScrollOutputToTop}, {#kb agent::ScrollOutputToBottom}, {#kb agent::ScrollOutputLineUp}, and {#kb agent::ScrollOutputLineDown} to navigate the thread, or {#kb agent::ScrollOutputToPreviousMessage} and {#kb agent::ScrollOutputToNextMessage} to jump between your prompts.
+
+### Thread titles {#thread-titles}
+
+Thread titles are auto-generated based on the content of the conversation.
+But you can also edit them manually by clicking the title and typing, or regenerate them by clicking the "Regenerate Thread Title" button in the ellipsis menu in the top right of the panel.
+
+### Following the Agent {#following-the-agent}
+
+Follow the agent as it reads and edits files by clicking the crosshair icon at the bottom left of the panel.
+Your editor will jump to each file the agent touches.
+
+You can also hold `cmd`/`ctrl` when submitting a message to automatically follow.
+
+### Get Notified {#get-notified}
+
+If you send a prompt to the Agent and then put Zed in the background, you can choose to be notified when its generation wraps up via:
+
+- a visual notification that appears in the top right of your screen
+- a sound notification
+
+These notifications can be used together or individually, and you can use the `agent.notify_when_agent_waiting` and `agent.play_sound_when_agent_done` settings keys to customize that, including turning both off entirely.
+
+### Reviewing Changes {#reviewing-changes}
+
+Once the agent has made changes to your project, the panel will surface which files, how many of them, and how many lines have been edited.
+
+To see which files specifically have been edited, expand the accordion bar that shows up right above the message editor or click the `Review Changes` button ({#kb agent::OpenAgentDiff}), which opens a special multi-buffer tab with all changes.
+
+You can accept or reject each individual change hunk, or the whole set of changes made by the agent.
+
+Edit diffs also appear in singleton buffers.
+If your active tab had edits made by the AI, you'll see diffs with the same accept/reject controls as in the multi-buffer.
+You can turn this off, though, through the `agent.single_file_review` setting.
+
+## Adding Context {#adding-context}
+
+The agent can search your codebase to find relevant context, but providing it explicitly improves response quality and reduces latency.
+
+Add context by typing `@` in the message editor.
+You can mention files, directories, symbols, previous threads, rules files, and diagnostics.
+
+When you paste multi-line code selections copied from a buffer, Zed automatically formats them as @-mentions with the file context.
+To paste content without this automatic formatting, use {#kb agent::PasteRaw} to paste raw text directly.
+
+### Selection as Context
+
+Additionally, you can also select text in a buffer or terminal and add it as context by using the {#kb agent::AddSelectionToThread} keybinding, running the {#action agent::AddSelectionToThread} action, or choosing the "Selection" item in the `+` menu in the message editor.
+
+### Images as Context
+
+It's also possible to attach images in your prompt for providers that support vision models.
+OpenAI GPT-4o and later, Anthropic Claude 3 and later, Google Gemini 1.5 and 2.0, and Bedrock vision models (Claude 3+, Amazon Nova Pro and Lite, Meta Llama 3.2 Vision, Mistral Pixtral) all support image inputs.
+
+To add an image, you can either search in your project's directory by @-mentioning it, or drag it from your file system directly into the agent panel message editor.
+Copying an image and pasting it is also supported.
+
+## Token Usage {#token-usage}
+
+Zed surfaces how many tokens you are consuming for your currently active thread near the profile selector in the panel's message editor.
+
+Once you approach the model's context window, a banner appears above the message editor suggesting to start a new thread with the current one summarized and added as context.
+You can also do this at any time with an ongoing thread via the "Agent Options" menu on the top right, where you'll see a "New from Summary" button, as well as simply @-mentioning a past thread in a new one..
+
+## Changing Models {#changing-models}
+
+After you've configured your LLM providers—either via [a custom API key](./llm-providers.md) or through [Zed's hosted models](./models.md)—you can switch between their models by clicking on the model selector on the message editor or by using the {#kb agent::ToggleModelSelector} keybinding.
+
+> The same model can be offered via multiple providers - for example, Claude Sonnet 4.5 is available via Zed Pro, OpenRouter, Anthropic directly, and more.
+> Make sure you've selected the correct model **_provider_** for the model you'd like to use, delineated by the logo to the left of the model in the model selector.
+
+### Favoriting Models
+
+You can mark specific models as favorites either through the model selector, by clicking on the star icon button that appears as you hover the model, or through your settings via the `agent.favorite_models` settings key.
+
+Cycle through your favorites with {#kb agent::CycleFavoriteModels} without opening the model selector.
+
+## Using Tools {#using-tools}
+
+The Agent Panel supports tool calling, which enables agentic editing.
+Zed includes several [built-in tools](./tools.md) for searching your codebase, editing files, running terminal commands, and more.
+
+You can also extend the set of available tools via [MCP Servers](./mcp.md).
+
+### Profiles {#profiles}
+
+Profiles act as a way to group tools.
+Zed offers three built-in profiles and you can create as many custom ones as you want.
+
+#### Built-in Profiles {#built-in-profiles}
+
+- `Write`: A profile with tools to allow the LLM to write to your files and run terminal commands.
+  This one essentially has all built-in tools turned on.
+- `Ask`: A profile with read-only tools.
+  Best for asking questions about your code base without the concern of the agent making changes.
+- `Minimal`: A profile with no tools.
+  Best for general conversations with the LLM where no knowledge of your code base is necessary.
+
+You can explore the exact tools enabled in each profile by clicking on the profile selector button > `Configure` button > the one you want to check out.
+
+Alternatively, you can also use either the command palette, by running {#action agent::ManageProfiles}, or the keybinding directly, {#kb agent::ManageProfiles}, to have access to the profile management modal.
+
+Use {#kb agent::CycleModeSelector} to cycle through available profiles without opening the modal.
+
+#### Custom Profiles {#custom-profiles}
+
+You can also create a custom profile through the Agent Profile modal.
+From there, you can choose to `Add New Profile` or fork an existing one with a custom name and your preferred set of tools.
+
+It's also possible to override built-in profiles.
+In the Agent Profile modal, select a built-in profile, navigate to `Configure Tools`, and rearrange the tools you'd like to keep or remove.
+
+Zed will store this profile in your settings using the same profile name as the default you overrode.
+
+All custom profiles can be edited via the UI or by hand under the `agent.profiles` key in your settings file.
+
+To delete a custom profile, open the Agent Profile modal, select the profile you want to remove, and click the delete button.
+
+### Tool Permissions
+
+> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
+> In earlier versions, it was controlled by the `agent.always_allow_tool_actions` boolean (default `false`).
+
+Zed's Agent Panel provides the `agent.tool_permissions.default` setting to control tool approval behavior:
+
+- `"confirm"` (default) — Prompts for approval before running any tool action
+- `"allow"` — Auto-approves tool actions without prompting
+- `"deny"` — Blocks all tool actions
+
+When the agent requests permission for an action, the confirmation menu includes options to allow or deny once, plus "Always for <tool>" choices that set a tool-level default.
+When Zed can extract a safe pattern from the input, it also offers pattern-based "Always for ..." choices that add `always_allow`/`always_deny` rules.
+MCP tools only support tool-level defaults.
+
+Even with `"default": "allow"`, per-tool `always_deny` and `always_confirm` patterns are still respected — so you can auto-approve most actions while blocking or gating specific ones.
+
+Learn more about [how tool permissions work](./tool-permissions.md), how to further customize them, and other details.
+
+### Model Support {#model-support}
+
+Tool calling needs to be individually supported by each model and model provider.
+Therefore, despite the presence of built-in tools, some models may not have the ability to pick them up.
+You should see a "No tools" label if you select a model that falls into this case.
+
+All [Zed's hosted models](./models.md) support tool calling out-of-the-box.
+
+### MCP Servers {#mcp-servers}
+
+Similarly to the built-in tools, some models may not support all tools included in a given MCP Server.
+Zed's UI will inform you about this via a warning icon that appears close to the model selector.
+
+## Errors and Debugging {#errors-and-debugging}
+
+If you hit an error or unusual LLM behavior, open the thread as Markdown with {#action agent::OpenActiveThreadAsMarkdown} and attach it to your GitHub issue.
+
+You can also open threads as Markdown by clicking on the file icon button, to the right of the thumbs down button, when focused on the panel's editor.
+
+## Feedback {#feedback}
+
+You can rate agent responses to help improve Zed's system prompt and tools.
+
+> Note that rating responses will send your data related to that response to Zed's servers.
+> See [AI Improvement](./ai-improvement.md) and [Privacy and Security](./privacy-and-security.md) for more information about Zed's approach to AI improvement, privacy, and security.
+> **_If you don't want data persisted on Zed's servers, don't rate_**.
+> We will not collect data for improving our Agentic offering without you explicitly rating responses.
+
+To help improve Zed's system prompt and tools, rate responses with the thumbs up/down controls at the end of each response.
+In case of a thumbs down, a new text area will show up where you can add more specifics about what happened.
+
+You can provide feedback on the thread at any point after the agent responds, and multiple times within the same thread.

docs/src/ai/agent-settings.md

@@ -0,0 +1,377 @@
+---
+title: AI Agent Settings - Zed
+description: "Customize Zed's AI agent: default models, temperature, tool approval, auto-run commands, notifications, and panel options."
+---
+
+# Agent Settings
+
+Settings for Zed's Agent Panel, including model selection, UI preferences, and tool permissions.
+
+## Model Settings {#model-settings}
+
+### Default Model {#default-model}
+
+If you're using [Zed's hosted LLM service](./subscription.md), it sets `claude-sonnet-4-5` as the default model for agentic work (agent panel, inline assistant) and `gpt-5-nano` as the default "fast" model (thread summarization, git commit messages). If you're not subscribed or want to change these defaults, you can manually edit the `default_model` object in your settings:
+
+```json [settings]
+{
+  "agent": {
+    "default_model": {
+      "provider": "openai",
+      "model": "gpt-4o"
+    }
+  }
+}
+```
+
+### Feature-specific Models {#feature-specific-models}
+
+You can assign distinct and specific models for the following AI-powered features:
+
+- Thread summary model: Used for generating thread summaries
+- Inline assistant model: Used for the inline assistant feature
+- Commit message model: Used for generating Git commit messages
+- Subagent model: Used for subagents spawned by the Agent Panel. If not set, the subagent will inherit the model settings from the parent thread.
+
+```json [settings]
+{
+  "agent": {
+    "default_model": {
+      "provider": "zed.dev",
+      "model": "claude-sonnet-4-5"
+    },
+    "inline_assistant_model": {
+      "provider": "anthropic",
+      "model": "claude-3-5-sonnet"
+    },
+    "commit_message_model": {
+      "provider": "openai",
+      "model": "gpt-4o-mini"
+    },
+    "thread_summary_model": {
+      "provider": "google",
+      "model": "gemini-2.0-flash"
+    },
+    "subagent_model": {
+      "provider": "zed.dev",
+      "model": "gpt-5-mini"
+    }
+  }
+}
+```
+
+> If a custom model isn't set for one of these features, they automatically fall back to using the default model.
+
+### Alternative Models for Inline Assists {#alternative-assists}
+
+With the Inline Assistant in particular, you can send the same prompt to multiple models at once.
+
+Here's how you can customize your settings file ([how to edit](../configuring-zed.md#settings-files)) to add this functionality:
+
+```json [settings]
+{
+  "agent": {
+    "default_model": {
+      "provider": "zed.dev",
+      "model": "claude-sonnet-4-5"
+    },
+    "inline_alternatives": [
+      {
+        "provider": "zed.dev",
+        "model": "gpt-5-mini"
+      }
+    ]
+  }
+}
+```
+
+When multiple models are configured, you'll see in the Inline Assistant UI buttons that allow you to cycle between outputs generated by each model.
+
+The models you specify here are always used in _addition_ to your [default model](#default-model).
+
+For example, the following configuration will generate three outputs for every assist.
+One with Claude Sonnet 4.5 (the default model), another with GPT-5-mini, and another one with Gemini 3 Flash.
+
+```json [settings]
+{
+  "agent": {
+    "default_model": {
+      "provider": "zed.dev",
+      "model": "claude-sonnet-4-5"
+    },
+    "inline_alternatives": [
+      {
+        "provider": "zed.dev",
+        "model": "gpt-5-mini"
+      },
+      {
+        "provider": "zed.dev",
+        "model": "gemini-3-flash"
+      }
+    ]
+  }
+}
+```
+
+### Model Temperature
+
+Specify a custom temperature for a provider and/or model:
+
+```json [settings]
+{
+  "agent": {
+    "model_parameters": [
+      // To set parameters for all requests to OpenAI models:
+      {
+        "provider": "openai",
+        "temperature": 0.5
+      },
+      // To set parameters for all requests in general:
+      {
+        "temperature": 0
+      },
+      // To set parameters for a specific provider and model:
+      {
+        "provider": "zed.dev",
+        "model": "claude-sonnet-4-5",
+        "temperature": 1.0
+      }
+    ]
+  }
+}
+```
+
+## Agent Panel Settings {#agent-panel-settings}
+
+Note that some of these settings are also surfaced in the Agent Panel's settings UI, which you can access either via the {#action agent::OpenSettings} action or by the dropdown menu on the top-right corner of the panel.
+
+### Font Size
+
+Use the `agent_ui_font_size` setting to change the font size of rendered agent responses in the panel.
+
+```json [settings]
+{
+  "agent_ui_font_size": 18
+}
+```
+
+> Editors in the Agent Panel—such as the main message textarea—use monospace fonts and are controlled by `agent_buffer_font_size` (which defaults to `buffer_font_size` when unset).
+
+### Default Tool Permissions
+
+> **Note:** In Zed v0.224.0 and above, tool approval uses the `agent.tool_permissions` settings described below.
+
+The `agent.tool_permissions.default` setting controls the baseline tool approval behavior for Zed's native agent:
+
+- `"confirm"` (default) — Prompts for approval before running any tool action
+- `"allow"` — Auto-approves tool actions without prompting
+- `"deny"` — Blocks all tool actions
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "default": "confirm"
+    }
+  }
+}
+```
+
+Even with `"default": "allow"`, per-tool `always_deny` and `always_confirm` patterns are still respected, so you can auto-approve most actions while keeping guardrails on dangerous or sensitive ones.
+
+### Per-tool Permission Rules {#per-tool-permission-rules}
+
+For granular control over individual tool actions, use the `tools` key inside `tool_permissions` to configure regex-based rules that auto-approve, auto-deny, or always require confirmation for specific inputs.
+
+Each tool entry supports the following keys:
+
+- `default` — Fallback when no patterns match: `"confirm"`, `"allow"`, or `"deny"`
+- `always_allow` — Array of patterns that auto-approve matching actions
+- `always_deny` — Array of patterns that block matching actions immediately
+- `always_confirm` — Array of patterns that always prompt for confirmation
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "default": "allow",
+      "tools": {
+        "terminal": {
+          "default": "confirm",
+          "always_allow": [
+            { "pattern": "^cargo\\s+(build|test|check)" },
+            { "pattern": "^git\\s+(status|log|diff)" }
+          ],
+          "always_deny": [{ "pattern": "rm\\s+-rf\\s+(/|~)" }],
+          "always_confirm": [{ "pattern": "sudo\\s" }]
+        },
+        "edit_file": {
+          "always_deny": [
+            { "pattern": "\\.env" },
+            { "pattern": "\\.(pem|key)$" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+#### Pattern Precedence
+
+When evaluating a tool action, rules are checked in the following order (highest priority first):
+
+1. **Built-in security rules** — Hardcoded protections (e.g., `rm -rf /`) that cannot be overridden
+2. **`always_deny`** — Blocks matching actions immediately
+3. **`always_confirm`** — Requires confirmation for matching actions
+4. **`always_allow`** — Auto-approves matching actions. For the terminal tool with chained commands (e.g., `echo hello && rm file`), **all** sub-commands must match an `always_allow` pattern
+5. **Tool-specific `default`** — Per-tool fallback when no patterns match (e.g., `tools.terminal.default`)
+6. **Global `default`** — Falls back to `tool_permissions.default`
+
+#### Case Sensitivity
+
+Patterns are **case-insensitive** by default. To make a pattern case-sensitive, set `case_sensitive` to `true`:
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "tools": {
+        "edit_file": {
+          "always_deny": [
+            {
+              "pattern": "^Makefile$",
+              "case_sensitive": true
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+#### `copy_path` and `move_path` Patterns
+
+For the `copy_path` and `move_path` tools, patterns are matched independently against both the source and destination paths. A `deny` or `confirm` match on **either** path takes effect. For `always_allow`, **both** paths must match for auto-approval.
+
+#### MCP Tool Permissions
+
+MCP tools use the key format `mcp:<server_name>:<tool_name>` in the `tools` configuration. For example:
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "tools": {
+        "mcp:github:create_issue": {
+          "default": "confirm"
+        },
+        "mcp:github:create_pull_request": {
+          "default": "deny"
+        }
+      }
+    }
+  }
+}
+```
+
+The `default` key on each MCP tool entry is the primary mechanism for controlling MCP tool permissions. Pattern-based rules (`always_allow`, `always_deny`, `always_confirm`) match against an empty string for MCP tools, so most patterns won't match — use the tool-level `default` instead.
+
+See the [Tool Permissions](./tool-permissions.md) documentation for more examples and complete details.
+
+> **Note:** Before Zed v0.224.0, tool approval was controlled by the `agent.always_allow_tool_actions` boolean (default `false`). Set it to `true` to auto-approve tool actions, or leave it `false` to require confirmation for edits and tool calls.
+
+### Edit Display Mode
+
+Control whether to display review actions (accept & reject) in single buffers after the agent is done performing edits.
+The default value is `false`.
+
+```json [settings]
+{
+  "agent": {
+    "single_file_review": false
+  }
+}
+```
+
+### Sound Notification
+
+Control whether to hear a notification sound when the agent is done generating changes or needs your input. The default value is `never`.
+
+- `"never"` (default) — Never play the sound.
+- `"when_hidden"` — Only play the sound when the agent panel is not visible.
+- `"always"` — Always play the sound on completion.
+
+```json [settings]
+{
+  "agent": {
+    "play_sound_when_agent_done": "never"
+  }
+}
+```
+
+### Message Editor Size
+
+Use the `message_editor_min_lines` setting to control the minimum number of lines of height the agent message editor should have.
+It is set to `4` by default, and the max number of lines is always double of the minimum.
+
+```json [settings]
+{
+  "agent": {
+    "message_editor_min_lines": 4
+  }
+}
+```
+
+### Modifier to Send
+
+Require a modifier (`cmd` on macOS, `ctrl` on Linux) to send messages. Prevents accidental sends while editing.
+The default value is `false`.
+
+```json [settings]
+{
+  "agent": {
+    "use_modifier_to_send": true
+  }
+}
+```
+
+### Edit Card
+
+Use the `expand_edit_card` setting to control whether edit cards show the full diff in the Agent Panel.
+It is set to `true` by default, but if set to false, the card's height is capped to a certain number of lines, requiring a click to be expanded.
+
+```json [settings]
+{
+  "agent": {
+    "expand_edit_card": false
+  }
+}
+```
+
+### Terminal Card
+
+Use the `expand_terminal_card` setting to control whether terminal cards show the command output in the Agent Panel.
+It is set to `true` by default, but if set to false, the card will be fully collapsed even while the command is running, requiring a click to be expanded.
+
+```json [settings]
+{
+  "agent": {
+    "expand_terminal_card": false
+  }
+}
+```
+
+### Feedback Controls
+
+Control whether to display the thumbs up/down buttons at the bottom of each agent response, allowing you to give Zed feedback about the agent's performance.
+The default value is `true`.
+
+```json [settings]
+{
+  "agent": {
+    "enable_feedback": false
+  }
+}
+```

docs/src/ai/ai-improvement.md

@@ -0,0 +1,138 @@
+---
+title: AI Improvement and Data Collection - Zed
+description: Zed's opt-in approach to AI data collection for improving the agent panel and edit predictions.
+---
+
+# Zed AI Features and Privacy
+
+## Overview
+
+AI features in Zed include:
+
+- [Agent Panel](./agent-panel.md)
+- [Edit Predictions](./edit-prediction.md)
+- [Inline Assist](./inline-assistant.md)
+- Auto Git Commit Message Generation
+
+By default, Zed does not store your prompts or code context. This data is sent to your selected AI provider (e.g., Anthropic, OpenAI, Google, or xAI) to generate responses, then discarded. Zed will not use your data to evaluate or improve AI features unless you explicitly share it (see [AI Feedback with Ratings](#ai-feedback-with-ratings)) or you opt in to edit prediction training data collection (see [Edit Predictions](#edit-predictions)).
+
+Zed is model-agnostic by design, and none of this changes based on which provider you choose. You can use your own API keys or Zed's hosted models without any data being retained.
+
+### Data Retention and Training
+
+Zed's Agent Panel can be used via:
+
+- [Zed's hosted models](./subscription.md)
+- [connecting a non-Zed AI service via API key](./llm-providers.md)
+- using an [external agent](./external-agents.md) via ACP
+
+When using Zed's hosted models, we require assurances from our service providers that your user content won't be used for training models.
+
+| Provider  | No Training Guarantee                                   | Zero-Data Retention (ZDR)                                                                                                                     |
+| --------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Anthropic | [Yes](https://www.anthropic.com/legal/commercial-terms) | [Yes](https://privacy.anthropic.com/en/articles/8956058-i-have-a-zero-data-retention-agreement-with-anthropic-what-products-does-it-apply-to) |
+| Google    | [Yes](https://cloud.google.com/terms/service-terms)     | [Yes](https://cloud.google.com/terms/service-terms), see Service Terms sections 17 and 19h                                                    |
+| OpenAI    | [Yes](https://openai.com/enterprise-privacy/)           | [Yes](https://platform.openai.com/docs/guides/your-data)                                                                                      |
+| xAI       | [Yes](https://x.ai/legal/faq-enterprise)                | [Yes](https://x.ai/legal/faq-enterprise)                                                                                                      |
+
+When you use your own API keys or external agents, **Zed does not have control over how your data is used by that service provider.**
+You should reference your agreement with each service provider to understand what terms and conditions apply.
+
+### AI Feedback with Ratings
+
+You can provide feedback on Zed's AI features by rating specific AI responses in Zed and sharing details related to those conversations with Zed. Each share is opt-in, and sharing once will not cause future content or data to be shared again.
+
+> **Rating = Data Sharing:** When you rate a response, your entire conversation thread is sent to Zed. This includes messages, AI responses, and thread metadata.
+> **_If you don't want data persisted on Zed's servers, don't rate_**. We will not collect data for improving our AI features without you explicitly rating responses.
+
+### Data Collected (AI Feedback)
+
+For conversations you have explicitly shared with us via rating, Zed may store:
+
+- All messages in the thread (your prompts and AI responses)
+- Any commentary you include with your rating
+- Thread metadata (model used, token counts, timestamps)
+- Metadata about your Zed installation
+
+If you do not rate responses, Zed will not store Customer Data (code, conversations, responses) related to your usage of the AI features.
+
+Telemetry related to Zed's AI features is collected. This includes metadata such as the AI feature being used and high-level interactions with the feature to understand performance (e.g., Agent response time, edit acceptance/rejection in the Agent panel or edit completions). You can read more in Zed's [telemetry](../telemetry.md) documentation.
+
+Collected data is stored in Snowflake, a private database. We periodically review this data to refine the agent's system prompt and tool use. All data is anonymized and stripped of sensitive information (access tokens, user IDs, email addresses).
+
+## Edit Predictions
+
+Edit predictions can be powered by **Zed's Zeta model** or by **third-party providers** like GitHub Copilot.
+
+### Zed's Zeta Model (Default)
+
+Zed sends a limited context window to the model to generate predictions:
+
+- A code excerpt around your cursor (not the full file)
+- Recent edits as diffs
+- Relevant excerpts from related open files
+
+This data is processed transiently to generate predictions and is not retained afterward.
+
+### Third-Party Providers
+
+When using third-party providers like GitHub Copilot, **Zed does not control how your data is handled** by that provider. You should consult their Terms and Conditions directly.
+
+Note: Zed's `disabled_globs` settings will prevent predictions from being requested, but third-party providers may receive file content when files are opened.
+
+### Training Data: Opt-In for Open Source Projects
+
+Zed does not collect training data for our edit prediction model unless the following conditions are met:
+
+1. **You opt in** – Toggle "Training Data Collection" under the **Privacy** section of the edit prediction status bar menu (click the edit prediction icon in the status bar).
+2. **The project is open source** — detected via LICENSE file ([see detection logic](https://github.com/zed-industries/zed/blob/main/crates/edit_prediction/src/license_detection.rs))
+3. **The file isn't excluded** — via `disabled_globs`
+
+### File Exclusions
+
+Certain files are always excluded from edit predictions—regardless of opt-in status:
+
+```json [settings]
+{
+  "edit_predictions": {
+    "disabled_globs": [
+      "**/.env*",
+      "**/*.pem",
+      "**/*.key",
+      "**/*.cert",
+      "**/*.crt",
+      "**/secrets.yml"
+    ]
+  }
+}
+```
+
+Users may explicitly exclude additional paths and/or file extensions by adding them to [`edit_predictions.disabled_globs`](https://zed.dev/docs/reference/all-settings#edit-predictions) in their Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "edit_predictions": {
+    "disabled_globs": ["secret_dir/*", "**/*.log"]
+  }
+}
+```
+
+### Data Collected (Edit Prediction Training Data)
+
+For open source projects where you've opted in, Zed may collect:
+
+- Code excerpt around your cursor
+- Recent edit diffs
+- The generated prediction
+- Repository URL and git revision
+- Buffer outline and diagnostics
+
+Collected data is stored in Snowflake. We periodically review this data to select training samples for inclusion in our model training dataset. We ensure any included data is anonymized and contains no sensitive information (access tokens, user IDs, email addresses, etc). This training dataset is publicly available at [huggingface.co/datasets/zed-industries/zeta](https://huggingface.co/datasets/zed-industries/zeta).
+
+### Model Output
+
+We then use this training dataset to fine-tune [Qwen2.5-Coder-7B](https://huggingface.co/Qwen/Qwen2.5-Coder-7B) and make the resulting model available at [huggingface.co/zed-industries/zeta](https://huggingface.co/zed-industries/zeta).
+
+## Applicable terms
+
+Please see the [Zed Terms of Service](https://zed.dev/terms) for more.

docs/src/ai/billing.md

@@ -0,0 +1,77 @@
+---
+title: Billing
+description: Manage billing for your Zed subscription, including payment methods, invoices, and sales tax information for individual and organization accounts.
+---
+
+# Billing
+
+Zed uses Stripe for payment processing. All plans that require payment do so via credit card or other supported payment methods. Individual Pro subscriptions also use Orb for invoicing and metering.
+
+For details on what's included in each plan and how token usage works, see [Plans & Pricing](./plans-and-usage.md).
+
+## Individual billing {#individual}
+
+### Billing information {#settings}
+
+Access billing information and settings from your [Zed dashboard](https://dashboard.zed.dev).
+This page embeds data from Orb, our invoicing and metering partner.
+
+### Billing cycles {#billing-cycles}
+
+Zed is billed on a monthly basis based on the date you initially subscribe. You'll receive _at least_ one invoice from Zed each month you're subscribed to Zed Pro, and more than one if you use more than $10 in incremental token spend within the month.
+
+### Threshold billing {#threshold-billing}
+
+Zed utilizes threshold billing to ensure timely payment collection. Every time your usage of Zed's hosted models crosses a $10 spend threshold, a new invoice is generated, and the threshold resets to $0.
+
+For example,
+
+- You subscribe on February 1. Your first invoice is $10.
+- You use $12 of incremental tokens in the month of February, with the first $10 spent on February 15. You'll receive an invoice for $10 on February 15.
+- On March 1, you receive an invoice for $12: $10 (March Pro subscription) and $2 in leftover token spend, since your usage didn't cross the $10 threshold.
+
+### Payment failures {#payment-failures}
+
+If payment of an invoice fails, Zed will block usage of our hosted models until the payment is complete. Email [billing-support@zed.dev](mailto:billing-support@zed.dev) for assistance.
+
+### Invoice history {#invoice-history}
+
+You can access your invoice history from the Billing page at [dashboard.zed.dev](https://dashboard.zed.dev) by clicking `Invoice history` within the embedded Orb portal.
+
+If you require historical Stripe invoices, email [billing-support@zed.dev](mailto:billing-support@zed.dev).
+
+## Organization billing {#organization}
+
+Zed Business consolidates your team's costs. Seat licenses and AI usage for all members appear on one bill, with no separate invoices per member. For a full feature overview, see [Zed Business](../business/overview.md).
+
+### Billing dashboard {#dashboard}
+
+Owners and admins can access billing information at [dashboard.zed.dev](https://dashboard.zed.dev). The dashboard shows the plan you're currently on and offers jumping off points to update billing details, such as the billing name and address, as well as payment information. You can also access your invoices history, accessible through the Orb billing portal.
+
+### AI usage {#ai-usage}
+
+AI usage across the organization is metered on a token basis at the same rates as individual Pro subscriptions. See [Plans & Pricing](./plans-and-usage.md#usage) for rate details.
+
+Administrators can set an org-wide AI spend limit from the Data & Privacy page in the organization dashboard. The limit starts at $0, so it must be increased before members can use any hosted models. Once the limit is reached, members will see an error when attempting to use hosted models.
+
+### Invoice history {#org-invoice-history}
+
+Owners and Admins can access an organization's invoice history from the Billing page at [dashboard.zed.dev](https://dashboard.zed.dev) by clicking `Invoice history` within the embedded Orb portal.
+
+If you require historical Stripe invoices, email [billing-support@zed.dev](mailto:billing-support@zed.dev).
+
+## Updating billing information {#updating-billing-info}
+
+From the _Billing_ page, owners can update their billing name, address, and payment method. Tax IDs are collected during checkout and cannot be changed self-serve; email [billing-support@zed.dev](mailto:billing-support@zed.dev) to update your tax ID.
+
+Changes to billing information will **only** affect future invoices. We cannot modify historical invoices. Email [billing-support@zed.dev](mailto:billing-support@zed.dev) with any questions.
+
+## Sales tax {#sales-tax}
+
+Zed partners with [Sphere](https://www.getsphere.com/) to calculate indirect tax rates for invoices, based on customer location and the product being sold. Tax is listed as a separate line item on invoices, based preferentially on your billing address, followed by the card issue country known to Stripe.
+
+If you have a VAT/GST ID, you can add it during checkout. Check the box that denotes you as a business.
+
+Changes to VAT/GST IDs and address will **only** affect future invoices. We cannot modify historical invoices.
+
+Email [billing-support@zed.dev](mailto:billing-support@zed.dev) with any tax questions.

docs/src/ai/configuration.md

@@ -0,0 +1,27 @@
+---
+title: Configure AI in Zed - Providers, Models, and Settings
+description: Set up AI in Zed with hosted models, your own API keys, or external agents. Includes how to disable AI entirely.
+---
+
+# Configuration
+
+You can configure multiple dimensions of AI usage in Zed:
+
+1. Which LLM providers you can use
+   - Zed's hosted models, which require [authentication](../authentication.md) and [subscription](./subscription.md)
+   - [Using your own API keys](./llm-providers.md), which do not require the above
+   - Using [external agents like Claude Agent](./external-agents.md), which also do not require the above
+2. [Model parameters and usage](./agent-settings.md#model-settings)
+3. [Interactions with the Agent Panel](./agent-settings.md#agent-panel-settings)
+
+## Turning AI Off Entirely
+
+To disable all AI features, add the following to your settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "disable_ai": true
+}
+```
+
+See [this blog post](https://zed.dev/blog/disable-ai-features) for further context on this option.

docs/src/ai/edit-prediction.md

@@ -0,0 +1,394 @@
+---
+title: AI Code Completion in Zed - Zeta, Copilot, Codestral, Mercury Coder
+description: Set up AI code completions in Zed with Zeta (built-in), GitHub Copilot, Codestral, or Mercury Coder. Multi-line predictions on every keystroke.
+---
+
+# Edit Prediction
+
+Edit Prediction is how Zed's AI code completions work: an LLM predicts the code you want to write.
+Each keystroke sends a new request to the edit prediction provider, which returns individual or multi-line suggestions you accept by pressing `tab`.
+
+The default provider is [Zeta, an open source model developed by Zed](https://zed.dev/blog/zeta2), but you can also use [other providers](#other-providers) like GitHub Copilot, Mercury Coder, and Codestral.
+
+## Configuring Zeta
+
+To use Zeta, [sign in](../authentication.md#what-features-require-signing-in).
+Once signed in, predictions appear as you type.
+
+You can confirm that Zeta is properly configured by opening the [Settings Editor](zed://settings/edit_predictions.providers) (`Cmd+,` on macOS or `Ctrl+,` on Linux/Windows) and searching for `edit_predictions`. The `provider` field should be set to `Zed AI`.
+
+Or verify this in your settings.json:
+
+```json [settings]
+{
+  "edit_predictions": {
+    "provider": "zed"
+  }
+}
+```
+
+The Z icon in the status bar also indicates Zeta is active.
+
+### Pricing and Plans
+
+The free plan includes 2,000 Zeta predictions per month. The [Pro plan](../ai/plans-and-usage.md) removes this limit. See [Zed's pricing page](https://zed.dev/pricing) for details.
+
+### Switching Modes {#switching-modes}
+
+Edit Prediction has two display modes:
+
+1. `eager` (default): predictions are displayed inline as long as it doesn't conflict with language server completions
+2. `subtle`: predictions only appear inline when holding a modifier key (`alt` by default)
+
+Toggle between them via the `mode` key:
+
+```json [settings]
+"edit_predictions": {
+  "mode": "eager" // or "subtle"
+},
+```
+
+Or directly via the UI through the status bar menu:
+
+![Edit Prediction status bar menu, with the modes toggle.](https://zed.dev/img/edit-prediction/status-bar-menu.webp)
+
+> Note that edit prediction modes work with any prediction provider.
+
+## Default Key Bindings
+
+On macOS and Windows, you can accept edit predictions with `alt-tab`. On Linux, `alt-tab` is often used by the window manager for switching windows, so `alt-l` is the default key binding for edit predictions.
+
+In `eager` mode, you can also use the `tab` key to accept edit predictions, unless the completion menu is open, in which case `tab` accepts LSP completions. To use `tab` to insert whitespace, you need to dismiss the prediction with {#kb editor::Cancel} before hitting `tab`.
+
+{#action editor::AcceptNextWordEditPrediction} ({#kb editor::AcceptNextWordEditPrediction}) can be used to accept the current edit prediction up to the next word boundary.
+{#action editor::AcceptNextLineEditPrediction} ({#kb editor::AcceptNextLineEditPrediction}) can be used to accept the current edit prediction up to the new line boundary.
+
+## Configuring Edit Prediction Keybindings {#edit-predictions-keybinding}
+
+### Keybinding Example: Always Use Tab
+
+To always use `tab` for accepting edit predictions, regardless of whether the LSP completions menu is open, you can add the following to your keymap:
+
+Open the keymap editor with {#action zed::OpenKeymap} ({#kb zed::OpenKeymap}), search for `AcceptEditPrediction`, right click on the binding for `tab` and hit `edit`. Then change the context the binding is active in to just `Editor && edit_prediction` and save it.
+
+Alternatively, you can put the following in your `keymap.json`:
+
+```json [keymap]
+[
+  {
+    "context": "Editor && edit_prediction",
+    "bindings": {
+      "tab": "editor::AcceptEditPrediction"
+    }
+  }
+]
+```
+
+After that, {#kb editor::ComposeCompletion} remains available for accepting LSP completions.
+
+### Keybinding Example: Always Use Alt-Tab
+
+To stop using `tab` for accepting edit predictions and always use `alt-tab` instead, unbind the default `tab` binding in the eager edit prediction context:
+
+Open the keymap editor with {#action zed::OpenKeymap} ({#kb zed::OpenKeymap}), search for `AcceptEditPrediction`, right click on the binding for `tab` and delete it.
+
+Alternatively, you can put the following in your `keymap.json`:
+
+```json [keymap]
+[
+  {
+    "context": "Editor && edit_prediction",
+    "unbind": {
+      "tab": "editor::AcceptEditPrediction"
+    }
+  }
+]
+```
+
+After that, `alt-tab` remains available for accepting edit predictions, and on Linux `alt-l` does too unless you unbind it.
+
+### Keybinding Example: Rebind Both Tab and Alt-Tab
+
+To move both default accept bindings to something else, unbind them and add your replacement:
+
+Open the keymap editor with {#action zed::OpenKeymap} ({#kb zed::OpenKeymap}), search for `AcceptEditPrediction`, right click on the binding for `tab` and delete it. Then right click on the binding for `alt-tab`, select "Edit", and record your desired keystrokes before hitting saving.
+
+Alternatively, you can put the following in your `keymap.json`:
+
+```json [keymap]
+[
+  {
+    "context": "Editor && edit_prediction",
+    "unbind": {
+      "alt-tab": "editor::AcceptEditPrediction",
+      // Add this as well on Windows/Linux
+      // "alt-l": "editor::AcceptEditPrediction",
+      "tab": "editor::AcceptEditPrediction"
+    },
+    "bindings": {
+      "ctrl-enter": "editor::AcceptEditPrediction"
+    }
+  }
+]
+```
+
+In this case, because the binding contains the modifier `ctrl`, it will be used to preview the prediction in subtle mode, or when the completions menu is open.
+
+### Cleaning Up Older Keymap Entries
+
+If you configured edit prediction keybindings before Zed `v0.229.0`, your `keymap.json` may have entries that are now redundant.
+
+**Old tab workaround**: Before `unbind` existed, the only way to prevent `tab` from accepting edit predictions was to copy all the default non-edit-prediction `tab` bindings into your keymap alongside a custom `AcceptEditPrediction` binding. If your keymap still contains those copy-pasted entries, delete them and use a single `"unbind"` entry as shown in the examples above.
+
+**Renamed context**: The `edit_prediction_conflict` context has been replaced by `edit_prediction && (showing_completions || in_leading_whitespace)`. Zed automatically migrates any bindings that used `edit_prediction_conflict`, so no changes are required on your end.
+
+## Disabling Automatic Edit Prediction
+
+You can disable edit predictions at several levels, or turn them off entirely.
+
+Alternatively, consider [using Subtle Mode](#switching-modes).
+
+### On Buffers
+
+To not have predictions appear automatically as you type, set this in your settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "show_edit_predictions": false
+}
+```
+
+This hides every indication that there is a prediction available, regardless of [the display mode](#switching-modes) you're in.
+Still, you can trigger edit predictions manually by executing {#action editor::ShowEditPrediction} or hitting {#kb editor::ShowEditPrediction}.
+
+### For Specific Languages
+
+To not have predictions appear automatically as you type when working with a specific language, set this in your settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "languages": {
+    "Python": {
+      "show_edit_predictions": false
+    }
+  }
+}
+```
+
+### In Specific Directories
+
+To disable edit predictions for specific directories or files, set this in your settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "edit_predictions": {
+    "disabled_globs": ["~/.config/zed/settings.json"]
+  }
+}
+```
+
+### Turning Off Completely
+
+To completely turn off edit prediction across all providers, explicitly set the settings to `none`, like so:
+
+```json [settings]
+{
+  "edit_predictions": {
+    "provider": "none"
+  }
+}
+```
+
+## Configuring Other Providers {#other-providers}
+
+Edit Prediction also works with other providers.
+
+### GitHub Copilot {#github-copilot}
+
+To use GitHub Copilot as your provider, set this in your settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "edit_predictions": {
+    "provider": "copilot"
+  }
+}
+```
+
+To sign in to GitHub Copilot, click on the Copilot icon in the status bar. A popup window appears displaying a device code. Click the copy button to copy the code, then click "Connect to GitHub" to open the GitHub verification page in your browser. Paste the code when prompted. The popup window closes automatically after successful authorization.
+
+#### Using GitHub Copilot Enterprise
+
+If your organization uses GitHub Copilot Enterprise, you can configure Zed to use your enterprise instance by specifying the enterprise URI in your settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "edit_predictions": {
+    "copilot": {
+      "enterprise_uri": "https://your.enterprise.domain"
+    }
+  }
+}
+```
+
+Replace `"https://your.enterprise.domain"` with the URL provided by your GitHub Enterprise administrator (e.g., `https://foo.ghe.com`).
+
+Once set, Zed routes Copilot requests through your enterprise endpoint.
+When you sign in by clicking the Copilot icon in the status bar, you are redirected to your configured enterprise URL to complete authentication.
+All other Copilot features and usage remain the same.
+
+Copilot can provide multiple completion alternatives, and these can be navigated with the following actions:
+
+- {#action editor::NextEditPrediction} ({#kb editor::NextEditPrediction}): To cycle to the next edit prediction
+- {#action editor::PreviousEditPrediction} ({#kb editor::PreviousEditPrediction}): To cycle to the previous edit prediction
+
+### Mercury Coder {#mercury-coder}
+
+To use [Mercury Coder](https://www.inceptionlabs.ai/) by Inception Labs as your provider:
+
+1. Open the Settings Editor ({#kb zed::OpenSettings})
+2. Search for "Edit Predictions" and click **Configure Providers**
+3. Find the Mercury section and enter your API key from the
+   [Inception Labs dashboard](https://platform.inceptionlabs.ai/dashboard/api-keys)
+
+Alternatively, click the edit prediction icon in the status bar and select
+**Configure Providers** from the menu.
+
+After adding your API key, Mercury Coder will appear in the provider dropdown in the status bar menu, where you can select it. You can also set it directly in your settings file:
+
+```json [settings]
+{
+  "edit_predictions": {
+    "provider": "mercury"
+  }
+}
+```
+
+### Codestral {#codestral}
+
+To use Mistral's Codestral as your provider:
+
+1. Open the Settings Editor (`Cmd+,` on macOS, `Ctrl+,` on Linux/Windows)
+2. Search for "Edit Predictions" and click **Configure Providers**
+3. Find the Codestral section and enter your API key from the
+   [Codestral dashboard](https://console.mistral.ai/codestral)
+
+Alternatively, click the edit prediction icon in the status bar and select
+**Configure Providers** from the menu.
+
+After adding your API key, Codestral will appear in the provider dropdown in the status bar menu, where you can select it. You can also set it directly in your settings file:
+
+```json [settings]
+{
+  "edit_predictions": {
+    "provider": "codestral"
+  }
+}
+```
+
+### Local and self-hosted models
+
+You can use local or self-hosted edit prediction models through Ollama or any server that implements the OpenAI completion API format. This works with Ollama, vLLM, llama.cpp server, LocalAI, and other compatible servers.
+
+#### Ollama
+
+Set `ollama` as your provider and configure the local model:
+
+```json [settings]
+{
+  "edit_predictions": {
+    "provider": "ollama",
+    "ollama": {
+      "api_url": "http://localhost:11434",
+      "model": "qwen2.5-coder:7b-base",
+      "prompt_format": "infer",
+      "max_output_tokens": 512
+    }
+  }
+}
+```
+
+#### OpenAI-compatible servers
+
+Set `open_ai_compatible_api` as your provider and configure the API endpoint:
+
+```json [settings]
+{
+  "edit_predictions": {
+    "provider": "open_ai_compatible_api",
+    "open_ai_compatible_api": {
+      "api_url": "http://localhost:8080/v1/completions",
+      "model": "deepseek-coder-6.7b-base",
+      "prompt_format": "deepseek_coder",
+      "max_output_tokens": 512
+    }
+  }
+}
+```
+
+The `prompt_format` setting controls how code context is formatted for the model. Use `"infer"` to detect the format from the model name, or specify one explicitly:
+
+- `zeta` - Zeta 1 format
+- `zeta2` - Zeta 2 format
+- `zeta2_1` - Zeta 2.1 format
+- `code_llama` - CodeLlama format: `<PRE> prefix <SUF> suffix <MID>`
+- `star_coder` - StarCoder format: `<fim_prefix>prefix<fim_suffix>suffix<fim_middle>`
+- `deepseek_coder` - DeepSeek format with special unicode markers
+- `qwen` - Qwen/CodeGemma format: `<|fim_prefix|>prefix<|fim_suffix|>suffix<|fim_middle|>`
+- `code_gemma` - CodeGemma format: `<|fim_prefix|>prefix<|fim_suffix|>suffix<|fim_middle|>`
+- `codestral` - Codestral format: `[SUFFIX]suffix[PREFIX]prefix`
+- `glm` - GLM-4 format with code markers
+- `infer` - Auto-detect from model name (default)
+
+With `"prompt_format": "infer"`, Zed automatically uses Zeta 2 format for models named `zeta2` and Zeta 2.1 format for models named `zeta2.1`.
+
+For example, to use Zeta 2 with Ollama:
+
+```json [settings]
+{
+  "edit_predictions": {
+    "provider": "ollama",
+    "ollama": {
+      "api_url": "http://localhost:11434",
+      "model": "zeta2",
+      "prompt_format": "infer",
+      "max_output_tokens": 512
+    }
+  }
+}
+```
+
+To use Zeta 2.1 with an OpenAI-compatible server:
+
+```json [settings]
+{
+  "edit_predictions": {
+    "provider": "open_ai_compatible_api",
+    "open_ai_compatible_api": {
+      "api_url": "http://localhost:8080/v1/completions",
+      "model": "zeta2.1",
+      "prompt_format": "infer",
+      "max_output_tokens": 512
+    }
+  }
+}
+```
+
+You can also set `"prompt_format": "zeta2"` or `"prompt_format": "zeta2_1"` explicitly when the model name does not match.
+
+Your OpenAI-compatible server must implement the OpenAI `/v1/completions` endpoint. Edit predictions will send POST requests with this format:
+
+```json
+{
+  "model": "your-model-name",
+  "prompt": "formatted-code-context",
+  "max_tokens": 256,
+  "temperature": 0.2,
+  "stop": ["<|endoftext|>", ...]
+}
+```
+
+## See also
+
+- [Agent Panel](./agent-panel.md): Agentic editing with file read/write and terminal access
+- [Inline Assistant](./inline-assistant.md): Prompt-driven transformations on selected code

docs/src/ai/external-agents.md

@@ -0,0 +1,345 @@
+---
+title: Use Claude Agent, Gemini CLI, and Codex in Zed
+description: Run Claude Agent, Gemini CLI, Codex, and other AI coding agents directly in Zed via the Agent Client Protocol (ACP).
+---
+
+# External Agents
+
+Zed supports many external agents, including CLI-based ones, through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
+
+Zed supports [Gemini CLI](https://github.com/google-gemini/gemini-cli) (the reference ACP implementation), [Claude Agent](https://platform.claude.com/docs/en/agent-sdk/overview), [Codex](https://developers.openai.com/codex), [GitHub Copilot](https://github.com/github/copilot-language-server-release), and [additional agents](#add-more-agents) you can configure.
+
+For Zed's built-in agent and the full list of tools it can use natively, see [Agent Tools](./tools.md).
+
+> Note that Zed's interaction with external agents is strictly UI-based; the billing, legal, and terms arrangement is directly between you and the agent provider.
+> Zed does not charge for use of external agents, and our [zero-data retention agreements/privacy guarantees](./ai-improvement.md) are **_only_** applicable for Zed's hosted models.
+
+## Gemini CLI {#gemini-cli}
+
+Zed provides the ability to run [Gemini CLI](https://github.com/google-gemini/gemini-cli) directly in the [agent panel](./agent-panel.md).
+Under the hood we run Gemini CLI in the background, and talk to it over ACP.
+
+### Getting Started
+
+First open the agent panel with {#kb agent::ToggleFocus}, and then start a new Gemini CLI thread using the agent selector button on the left (in the empty state) or the `+` button in the top right.
+
+If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the {#action zed::OpenKeymapFile} command to include:
+
+```json [keymap]
+[
+  {
+    "bindings": {
+      "cmd-alt-g": ["agent::NewExternalAgentThread", { "agent": "gemini" }]
+    }
+  }
+]
+```
+
+#### Installation
+
+The first time you create a Gemini CLI thread, Zed will install [@google/gemini-cli](https://github.com/google-gemini/gemini-cli).
+This installation is only available to Zed and is kept up to date as you use the agent.
+
+#### Authentication
+
+After you have Gemini CLI running, you'll be prompted to authenticate.
+
+Click the "Login" button to open the Gemini CLI interactively, where you can log in with your Google account or [Vertex AI](https://cloud.google.com/vertex-ai) credentials.
+Zed does not see your OAuth or access tokens in this case.
+
+If the `GEMINI_API_KEY` environment variable (or `GOOGLE_AI_API_KEY`) is already set, or you have configured a Google AI API key in Zed's [language model provider settings](./llm-providers.md#google-ai), it will be passed to Gemini CLI automatically.
+
+For more information, see the [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/index.md).
+
+### Usage
+
+Gemini CLI supports the same workflows as Zed's first-party agent: code generation, refactoring, debugging, and Q&A. Add context by @-mentioning files, recent threads, or symbols.
+
+> Some agent panel features are not yet available with Gemini CLI: editing past messages, resuming threads from history, and checkpointing.
+
+## Claude Agent
+
+Similar to Gemini CLI, you can also run [Claude Agent](https://platform.claude.com/docs/en/agent-sdk/overview) directly via Zed's [agent panel](./agent-panel.md).
+Under the hood, Zed runs the Claude Agent SDK, which runs Claude Code under the hood, and communicates to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/claude-agent-acp).
+
+### Getting Started
+
+Open the agent panel with {#kb agent::ToggleFocus}, and then start a new Claude Agent thread using the agent selector button on the left (in the empty state) or the `+` button in the top right.
+
+If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the {#action zed::OpenKeymapFile} command to include:
+
+```json [keymap]
+[
+  {
+    "bindings": {
+      "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "claude-acp" }]
+    }
+  }
+]
+```
+
+### Authentication
+
+As of version `0.202.7`, authentication to Zed's Claude Agent installation is decoupled entirely from Zed's agent.
+That is to say, an Anthropic API key added via the [Zed Agent's settings](./llm-providers.md#anthropic) will _not_ be utilized by Claude Agent for authentication and billing.
+
+To ensure you're using your billing method of choice, [open a new Claude Agent thread](./agent-panel.md#new-thread).
+Then, run `/login`, and authenticate either via API key, or via `Log in with Claude Code` to use a Claude Pro/Max subscription.
+
+#### Installation
+
+The first time you create a Claude Agent thread, Zed will install [@zed-industries/claude-agent-acp](https://github.com/zed-industries/claude-agent-acp).
+This installation is only available to Zed and is kept up to date as you use the agent.
+
+Zed will always use this managed version of the Claude Agent adapter, which includes a vendored version of the Claude Code CLI, even if you have it installed globally.
+
+If you want to override the executable used by the adapter, you can set the `CLAUDE_CODE_EXECUTABLE` environment variable in your settings to the path of your preferred executable.
+
+```json
+{
+  "agent_servers": {
+    "claude-acp": {
+      "type": "registry",
+      "env": {
+        "CLAUDE_CODE_EXECUTABLE": "/path/to/alternate-claude-code-executable"
+      }
+    }
+  }
+}
+```
+
+### Usage
+
+Claude Agent supports the same workflows as Zed's first-party agent. Add context by @-mentioning files, recent threads, diagnostics, or symbols.
+
+In complement to talking to it [over ACP](https://agentclientprotocol.com), Zed relies on the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) to support some of its specific features.
+However, the SDK doesn't yet expose everything needed to fully support all of them:
+
+- Slash Commands: [Custom slash commands](https://code.claude.com/docs/en/slash-commands#custom-slash-commands) are fully supported, and have been merged into skills. A subset of [built-in commands](https://code.claude.com/docs/en/slash-commands#built-in-slash-commands) are supported.
+- [Subagents](https://code.claude.com/docs/en/sub-agents) are supported.
+- [Agent teams](https://code.claude.com/docs/en/agent-teams) are currently _not_ supported.
+- [Hooks](https://code.claude.com/docs/en/hooks-guide) are currently _not_ supported.
+
+> Some [agent panel](./agent-panel.md) features are not yet available with Claude Agent: editing past messages, resuming threads from history, and checkpointing.
+
+#### CLAUDE.md
+
+Claude Agent in Zed will automatically use any `CLAUDE.md` file found in your project root, project subdirectories, or root `.claude` directory.
+
+If you don't have a `CLAUDE.md` file, you can ask Claude Agent to create one for you through the `init` slash command.
+
+## Codex CLI
+
+You can also run [Codex CLI](https://github.com/openai/codex) directly via Zed's [agent panel](./agent-panel.md).
+Under the hood, Zed runs Codex CLI and communicates to it over ACP, through [a dedicated adapter](https://github.com/zed-industries/codex-acp).
+
+### Getting Started
+
+As of version `0.208`, you should be able to use Codex directly from Zed.
+Open the agent panel with {#kb agent::ToggleFocus}, and then start a new Codex thread using the agent selector button on the left (in the empty state) or the `+` button in the top right.
+
+If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the {#action zed::OpenKeymapFile} command to include:
+
+```json
+[
+  {
+    "bindings": {
+      "cmd-alt-c": ["agent::NewExternalAgentThread", { "agent": "codex-acp" }]
+    }
+  }
+]
+```
+
+### Authentication
+
+Authentication to Zed's Codex installation is decoupled entirely from Zed's agent.
+That is to say, an OpenAI API key added via the [Zed Agent's settings](./llm-providers.md#openai) will _not_ be utilized by Codex for authentication and billing.
+
+To ensure you're using your billing method of choice, [open a new Codex thread](./agent-panel.md#new-thread).
+The first time you will be prompted to authenticate with one of three methods:
+
+1. Login with ChatGPT - allows you to use your existing, paid ChatGPT subscription. _Note: This method isn't currently supported in remote projects_
+2. `CODEX_API_KEY` - uses an API key you have set in your environment under the variable `CODEX_API_KEY`.
+3. `OPENAI_API_KEY` - uses an API key you have set in your environment under the variable `OPENAI_API_KEY`.
+
+If you are already logged in and want to change your authentication method, type `/logout` in the thread and authenticate again.
+
+If you want to use a third-party provider with Codex, you can configure that with your [Codex config.toml](https://github.com/openai/codex/blob/main/docs/config.md#model-selection) or pass extra [args/env variables](https://github.com/openai/codex/blob/main/docs/config.md#model-selection) to your Codex agent servers settings.
+
+#### Installation
+
+The first time you create a Codex thread, Zed will install [codex-acp](https://github.com/zed-industries/codex-acp).
+This installation is only available to Zed and is kept up to date as you use the agent.
+
+Zed will always use this managed version of Codex even if you have it installed globally.
+
+### Usage
+
+Codex supports the same workflows as Zed's first-party agent. Add context by @-mentioning files or symbols.
+
+> Some agent panel features are not yet available with Codex: editing past messages, resuming threads from history, and checkpointing.
+
+## Add More Agents {#add-more-agents}
+
+### Via Agent Server Extensions
+
+<div class="warning">
+
+Starting from `v0.221.x`, [the ACP Registry](https://agentclientprotocol.com/registry) is the preferred way to install external agents in Zed.
+Learn more about it in [the release blog post](https://zed.dev/blog/acp-registry).
+At some point in the near future, Agent Server extensions will be deprecated.
+
+</div>
+
+Add more external agents to Zed by installing [Agent Server extensions](../extensions/agent-servers.md).
+
+See what agents are available by filtering for "Agent Servers" in the extensions page, which you can access via the command palette with {#action zed::Extensions}, or the [Zed website](https://zed.dev/extensions?filter=agent-servers).
+
+### Via The ACP Registry
+
+#### Overview
+
+As mentioned above, the Agent Server extensions will be deprecated in the near future to give room to the ACP Registry.
+
+[The ACP Registry](https://github.com/agentclientprotocol/registry) lets developers distribute ACP-compatible agents to any client that implements the protocol. Agents installed from the registry update automatically.
+
+At the moment, the registry is a curated set of agents, including only the ones that [support authentication](https://agentclientprotocol.com/rfds/auth-methods).
+
+#### Using it in Zed
+
+Use the {#action zed::AcpRegistry} command to quickly go to the ACP Registry page.
+There's also a button ("Add Agent") that takes you there in the agent panel's configuration view.
+
+From there, you can click to install your preferred agent and it will become available right away in the `+` icon button in the agent panel.
+
+> If you installed the same agent through both the extension and the registry, the registry version takes precedence.
+
+### Custom Agents
+
+You can also add agents through your settings file ([how to edit](../configuring-zed.md#settings-files)) by specifying certain fields under `agent_servers`, like so:
+
+```json [settings]
+{
+  "agent_servers": {
+    "My Custom Agent": {
+      "type": "custom",
+      "command": "node",
+      "args": ["~/projects/agent/index.js", "--acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+This can be useful if you're in the middle of developing a new agent that speaks the protocol and you want to debug it.
+
+It's also possible to customize environment variables for registry-installed agents like Claude Agent, Codex, and Gemini CLI by using their registry names (`claude-acp`, `codex-acp`, `gemini`) with `"type": "registry"` in your settings.
+
+## Debugging Agents
+
+When using external agents in Zed, you can access the debug view via with {#action dev::OpenAcpLogs} from the Command Palette.
+This lets you see the messages being sent and received between Zed and the agent.
+
+![The debug view for ACP logs.](https://zed.dev/img/acp/acp-logs.webp)
+
+It's helpful to attach data from this view if you're opening issues about problems with external agents like Claude Agent, Codex, OpenCode, etc.
+
+## Configuration Boundaries {#configuration-boundaries}
+
+External agents run as separate processes that communicate with Zed via the [Agent Client Protocol (ACP)](https://agentclientprotocol.com). This creates important boundaries between Zed's configuration and the agent's native configuration.
+
+### What Zed Forwards to External Agents
+
+When you start an external agent thread, Zed sends:
+
+| Setting               | How to Configure                                                      |
+| --------------------- | --------------------------------------------------------------------- |
+| Model selection       | `agent_servers.<agent>.default_model` in settings                     |
+| Mode selection        | `agent_servers.<agent>.default_mode` in settings                      |
+| Environment variables | `agent_servers.<agent>.env` in settings                               |
+| MCP servers           | `context_servers` in settings (see [limitations](#mcp-server-access)) |
+| Working directory     | Automatically set to project root                                     |
+
+**Not forwarded:**
+
+- [Profiles](./agent-panel.md#profiles) — profiles only apply to Zed's first-party agent
+- [Tool permissions](./tool-permissions.md) settings — external agents request permissions at runtime via UI prompts
+- Rules files — Zed's [rules system](./rules.md) only applies to Zed's first-party agent (external agents read their own rules files directly)
+
+### What External Agents Read Directly {#native-config}
+
+External agents run as CLI tools with full filesystem access. They read their own configuration files directly — Zed doesn't forward or block these.
+
+#### Claude Agent
+
+Claude Agent runs Claude Code under the hood, which reads its standard configuration:
+
+| Config                              | Read by Claude Agent?                                             |
+| ----------------------------------- | ----------------------------------------------------------------- |
+| `~/.claude/` directory              | Yes — Claude Code reads its own settings and memory               |
+| CLAUDE.md files                     | Yes — Claude Code reads these directly from the project           |
+| Skills                              | Yes — exposed via the Claude Agent SDK                            |
+| MCP servers from Claude Code config | Yes — but Zed also forwards its own MCP servers via ACP           |
+| Hooks                               | No — [not supported](https://code.claude.com/docs/en/hooks-guide) |
+| Authentication                      | Separate — you must authenticate via `/login` in Zed              |
+
+> **Why separate authentication?** Zed isolates Claude Agent authentication to give you control over which account and billing method you use.
+
+#### Codex
+
+Codex runs the Codex CLI under the hood, which reads its standard configuration:
+
+| Config                        | Read by Codex?                                  |
+| ----------------------------- | ----------------------------------------------- |
+| `~/.codex/config.toml`        | Yes — Codex CLI reads its own config            |
+| MCP servers from Codex config | Yes — but Zed also forwards its own MCP servers |
+| `CODEX_API_KEY` env var       | Yes — inherited from your shell environment     |
+| `OPENAI_API_KEY` env var      | Yes — inherited from your shell environment     |
+| ChatGPT OAuth login           | Separate — you must re-authenticate in Zed      |
+
+You can also pass environment variables through Zed settings:
+
+```json [settings]
+{
+  "agent_servers": {
+    "codex-acp": {
+      "type": "registry",
+      "env": {
+        "CODEX_API_KEY": "your-key",
+        "CUSTOM_PROVIDER_URL": "https://..."
+      }
+    }
+  }
+}
+```
+
+### MCP Server Access {#mcp-server-access}
+
+MCP servers configured in Zed's `context_servers` are forwarded to Claude Agent and Codex via the ACP protocol.
+
+- **Local stdio-based MCP servers:** Work reliably
+- **Remote MCP servers with OAuth:** May have issues ([#54410](https://github.com/zed-industries/zed/issues/54410))
+
+External agents can access MCP servers from two sources: Zed's `context_servers` (forwarded via ACP) and their own native configuration files (`~/.claude/`, `~/.codex/config.toml`).
+
+For more on configuring MCP servers, see [Model Context Protocol](./mcp.md).
+
+### Troubleshooting {#troubleshooting}
+
+**"I enabled MCP tools in Zed but the agent can't see them"**
+
+1. Verify the MCP server is enabled in `context_servers` settings
+2. For remote MCP servers with OAuth, this is a [known issue](https://github.com/zed-industries/zed/issues/54410) — try local stdio-based servers instead
+3. Open {#action dev::OpenAcpLogs} from the Command Palette to debug
+
+**"My existing Claude Code / Codex setup isn't working in Zed"**
+
+External agents read their own config files, but authentication is handled separately:
+
+1. Re-authenticate via `/login` (Claude Agent) or the authentication prompt (Codex)
+2. Your existing MCP servers and settings from `~/.claude/` or `~/.codex/config.toml` should work
+3. You can also configure additional settings via `agent_servers.<agent>.env` in Zed
+
+**"Profiles don't affect my external agent"**
+
+Correct — [profiles](./agent-panel.md#profiles) only apply to Zed's first-party agent. External agents have their own tool sets and don't use Zed's profile system.

docs/src/ai/inline-assistant.md

@@ -0,0 +1,122 @@
+---
+title: Inline AI Code Editing - Zed
+description: Transform code inline with AI in Zed. Send selections to any LLM for refactoring, generation, or editing with multi-cursor support.
+---
+
+# Inline Assistant
+
+## Usage Overview
+
+Use {#kb assistant::InlineAssist} to open the Inline Assistant in editors, the rules library, channel notes, and the terminal panel.
+
+The Inline Assistant sends your current selection (or line) to a language model and replaces it with the response.
+
+## Getting Started
+
+If you're using the Inline Assistant for the first time, you need to have at least one LLM provider or external agent configured.
+You can do that by:
+
+1. [subscribing to our Pro plan](https://zed.dev/pricing), so you have access to our hosted models
+2. [using your own API keys](./llm-providers.md#use-your-own-keys), either from model providers like Anthropic or model gateways like OpenRouter.
+
+If you have already set up an LLM provider to interact with [the Agent Panel](./agent-panel.md#getting-started), then that will also work for the Inline Assistant.
+
+> Unlike the Agent Panel, though, the only exception at the moment is [external agents](./external-agents.md).
+> They currently can't be used for generating changes with the Inline Assistant.
+
+## Adding Context
+
+You can add context in the Inline Assistant the same way you can in [the Agent Panel](./agent-panel.md#adding-context):
+
+- @-mention files, directories, past threads, rules, and symbols
+- paste images that are copied on your clipboard
+
+You can also create a thread in the Agent Panel, then reference it with `@thread` in the Inline Assistant. This lets you refine a specific change from a larger thread without re-explaining context.
+
+## Parallel Generations
+
+The Inline Assistant can generate multiple changes at once:
+
+### Multiple Cursors
+
+With multiple cursors, pressing {#kb assistant::InlineAssist} sends the same prompt to each cursor position, generating changes at all locations simultaneously.
+
+This works well with excerpts in [multibuffers](../multibuffers.md).
+
+### Multiple Models
+
+You can use the Inline Assistant to send the same prompt to multiple models at once.
+
+Here's how you can customize your settings file ([how to edit](../configuring-zed.md#settings-files)) to add this functionality:
+
+```json [settings]
+{
+  "agent": {
+    "default_model": {
+      "provider": "zed.dev",
+      "model": "claude-sonnet-4-5"
+    },
+    "inline_alternatives": [
+      {
+        "provider": "zed.dev",
+        "model": "gpt-4-mini"
+      }
+    ]
+  }
+}
+```
+
+When multiple models are configured, you'll see in the Inline Assistant UI buttons that allow you to cycle between outputs generated by each model.
+
+The models you specify here are always used in _addition_ to your [default model](#default-model).
+
+For example, the following configuration will generate three outputs for every assist.
+One with Claude Sonnet 4.5 (the default model), another with GPT-5-mini, and another one with Gemini 3 Flash.
+
+```json [settings]
+{
+  "agent": {
+    "default_model": {
+      "provider": "zed.dev",
+      "model": "claude-sonnet-4-5"
+    },
+    "inline_alternatives": [
+      {
+        "provider": "zed.dev",
+        "model": "gpt-4-mini"
+      },
+      {
+        "provider": "zed.dev",
+        "model": "gemini-3-flash"
+      }
+    ]
+  }
+}
+```
+
+## Inline Assistant vs. Edit Prediction
+
+Both features generate inline code, but they work differently:
+
+- **Inline Assistant**: You write a prompt and select what to transform. You control the context.
+- **[Edit Prediction](./edit-prediction.md)**: Zed automatically suggests edits based on your recent changes, visited files, and cursor position. No prompting required.
+
+The key difference: Inline Assistant is explicit and prompt-driven; Edit Prediction is automatic and context-inferred.
+
+## Prefilling Prompts
+
+To create a custom keybinding that prefills a prompt, you can add the following format in your keymap:
+
+```json [keymap]
+[
+  {
+    "context": "Editor && mode == full",
+    "bindings": {
+      "ctrl-shift-enter": [
+        "assistant::InlineAssist",
+        { "prompt": "Build a snake game" }
+      ]
+    }
+  }
+]
+```

docs/src/ai/llm-providers.md

@@ -0,0 +1,888 @@
+---
+title: LLM Providers - Use Your Own API Keys in Zed
+description: Bring your own API keys to Zed. Set up Anthropic, OpenAI, Google AI, Ollama, DeepSeek, Mistral, OpenRouter, Vercel AI Gateway, and more.
+---
+
+# LLM Providers
+
+To use AI in Zed, you need to have at least one large language model provider set up. Once configured, providers are available in the [Agent Panel](./agent-panel.md) and [Inline Assistant](./inline-assistant.md).
+
+You can do that by either subscribing to [one of Zed's plans](./plans-and-usage.md), or by using API keys you already have for the supported providers. For general AI setup, see [Configuration](./configuration.md).
+
+## Use Your Own Keys {#use-your-own-keys}
+
+If you already have an API key for a provider like Anthropic or OpenAI, you can add it to Zed. No Zed subscription required.
+
+To add an existing API key to a given provider, go to the Agent Panel settings ({#action agent::OpenSettings}), look for the desired provider, paste the key into the input, and hit enter.
+
+> Note: API keys are _not_ stored as plain text in your settings file, but rather in your OS's secure credential storage.
+
+## Supported Providers
+
+Zed supports these providers with your own API keys:
+
+- [Amazon Bedrock](#amazon-bedrock)
+- [Anthropic](#anthropic)
+- [DeepSeek](#deepseek)
+- [GitHub Copilot Chat](#github-copilot-chat)
+- [Google AI](#google-ai)
+- [LM Studio](#lmstudio)
+- [Mistral](#mistral)
+- [Ollama](#ollama)
+- [OpenAI](#openai)
+- [OpenAI API Compatible](#openai-api-compatible)
+- [OpenCode](#opencode)
+- [OpenRouter](#openrouter)
+- [Vercel AI Gateway](#vercel-ai-gateway)
+- [xAI](#xai)
+
+### Amazon Bedrock {#amazon-bedrock}
+
+> Supports tool use with models that support streaming tool use.
+> More details can be found in the [Amazon Bedrock's Tool Use documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference-supported-models-features.html).
+
+To use Amazon Bedrock's models, an AWS authentication is required.
+Ensure your credentials have the following permissions set up:
+
+- `bedrock:InvokeModelWithResponseStream`
+- `bedrock:InvokeModel`
+
+Your IAM policy should look similar to:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "bedrock:InvokeModel",
+        "bedrock:InvokeModelWithResponseStream"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+With that done, choose one of the three authentication methods:
+
+#### Authentication via Named Profile (Recommended)
+
+1. Ensure you have the AWS CLI installed and configured with a named profile
+2. Open your settings file ({#action zed::OpenSettingsFile}) and include the `bedrock` key under `language_models` with the following settings:
+   ```json [settings]
+   {
+     "language_models": {
+       "bedrock": {
+         "authentication_method": "named_profile",
+         "region": "your-aws-region",
+         "profile": "your-profile-name"
+       }
+     }
+   }
+   ```
+
+#### Authentication via Static Credentials
+
+While it's possible to configure through the Agent Panel settings UI by entering your AWS access key and secret directly, we recommend using named profiles instead for better security practices.
+To do this:
+
+1. Create an IAM User in the [IAM Console](https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/users).
+2. Create security credentials for that User, save them and keep them secure.
+3. Open the Agent Configuration with ({#action agent::OpenSettings}) and go to the Amazon Bedrock section
+4. Copy the credentials from Step 2 into the respective **Access Key ID**, **Secret Access Key**, and **Region** fields.
+
+#### Authentication via Bedrock API Key
+
+Amazon Bedrock also supports [API Keys](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-use.html), which authenticate directly without requiring IAM users or named profiles.
+
+1. Create an API Key in the [Amazon Bedrock Console](https://console.aws.amazon.com/bedrock/)
+2. Open the Agent Configuration with ({#action agent::OpenSettings}) and go to the Amazon Bedrock section
+3. Enter your Bedrock API key in the **API Key** field and select your **Region**
+
+```json [settings]
+{
+  "language_models": {
+    "bedrock": {
+      "authentication_method": "api_key",
+      "region": "your-aws-region"
+    }
+  }
+}
+```
+
+The API key itself is stored securely in your OS keychain, not in your settings file.
+
+#### Cross-Region Inference
+
+The Zed implementation of Amazon Bedrock uses [Cross-Region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) to improve availability and throughput.
+With Cross-Region inference, you can distribute traffic across multiple AWS Regions, enabling higher throughput.
+
+##### Regional vs Global Inference Profiles
+
+Bedrock supports two types of cross-region inference profiles:
+
+- **Regional profiles** (default): Route requests within a specific geography (US, EU, APAC). For example, `us-east-1` uses the `us.*` profile which routes across `us-east-1`, `us-east-2`, and `us-west-2`.
+- **Global profiles**: Route requests across all commercial AWS Regions for maximum availability and performance.
+
+By default, Zed uses **regional profiles** which keep your data within the same geography. You can opt into global profiles by adding `"allow_global": true` to your Bedrock configuration:
+
+```json [settings]
+{
+  "language_models": {
+    "bedrock": {
+      "authentication_method": "named_profile",
+      "region": "your-aws-region",
+      "profile": "your-profile-name",
+      "allow_global": true
+    }
+  }
+}
+```
+
+**Note:** Only select newer models support global inference profiles. See the [AWS Bedrock supported models documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html#inference-profiles-support-system) for the current list of models that support global inference. If you encounter availability issues with a model in your region, enabling `allow_global` may resolve them.
+
+Although the data remains stored only in the source Region, your input prompts and output results might move outside of your source Region during cross-Region inference.
+All data will be transmitted encrypted across Amazon's secure network.
+
+We will support Cross-Region inference for each of the models on a best-effort basis, please refer to the [Cross-Region Inference method Code](https://github.com/zed-industries/zed/blob/main/crates/bedrock/src/models.rs#L297).
+
+For the most up-to-date supported regions and models, refer to the [Supported Models and Regions for Cross Region inference](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html).
+
+#### Image Support {#bedrock-image-support}
+
+Bedrock models that support vision (Claude 3 and later, Amazon Nova Pro and Lite, Meta Llama 3.2 Vision models, Mistral Pixtral) can receive images in conversations and tool results.
+
+#### Guardrails {#bedrock-guardrails}
+
+Some AWS environments enforce IAM policies that require a guardrail to be specified on every Bedrock API call. To apply a guardrail to all Bedrock requests, add `guardrail_identifier` to your Bedrock configuration:
+
+```json [settings]
+{
+  "language_models": {
+    "bedrock": {
+      "guardrail_identifier": "arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123",
+      "guardrail_version": "DRAFT"
+    }
+  }
+}
+```
+
+- `guardrail_identifier`: The ARN or ID of the guardrail to apply to every request.
+- `guardrail_version`: The version of the guardrail to use. Defaults to `"DRAFT"` if omitted.
+
+> **Note**: For more information, refer to the [AWS Bedrock Guardrails documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html).
+
+### Anthropic {#anthropic}
+
+You can use Anthropic models by choosing them via the model dropdown in the Agent Panel.
+
+1. Sign up for Anthropic and [create an API key](https://console.anthropic.com/settings/keys)
+2. Make sure that your Anthropic account has credits
+3. Open the settings view ({#action agent::OpenSettings}) and go to the Anthropic section
+4. Enter your Anthropic API key
+
+Even if you pay for Claude Pro, you will still have to [pay for additional credits](https://console.anthropic.com/settings/plans) to use it via the API.
+
+Zed will also use the `ANTHROPIC_API_KEY` environment variable if it's defined.
+
+#### Custom Models {#anthropic-custom-models}
+
+You can add custom models to the Anthropic provider by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "language_models": {
+    "anthropic": {
+      "available_models": [
+        {
+          "name": "claude-3-5-sonnet-20240620",
+          "display_name": "Sonnet 2024-June",
+          "max_tokens": 128000,
+          "max_output_tokens": 2560,
+          "tool_override": "some-model-that-supports-toolcalling"
+        }
+      ]
+    }
+  }
+}
+```
+
+Custom models will be listed in the model dropdown in the Agent Panel.
+
+You can configure a model to use [extended thinking](https://docs.anthropic.com/en/docs/about-claude/models/extended-thinking-models) (if it supports it) by changing the mode in your model's configuration to `thinking`, for example:
+
+```json
+{
+  "name": "claude-sonnet-4-latest",
+  "display_name": "claude-sonnet-4-thinking",
+  "max_tokens": 200000,
+  "mode": {
+    "type": "thinking",
+    "budget_tokens": 4096
+  }
+}
+```
+
+### DeepSeek {#deepseek}
+
+1. Visit the DeepSeek platform and [create an API key](https://platform.deepseek.com/api_keys)
+2. Open the settings view ({#action agent::OpenSettings}) and go to the DeepSeek section
+3. Enter your DeepSeek API key
+
+The DeepSeek API key will be saved in your keychain.
+
+Zed will also use the `DEEPSEEK_API_KEY` environment variable if it's defined.
+
+#### Custom Models {#deepseek-custom-models}
+
+The Zed agent comes pre-configured to use DeepSeek V4 Flash and DeepSeek V4 Pro.
+If you wish to use alternate models or customize the API endpoint, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "language_models": {
+    "deepseek": {
+      "api_url": "https://api.deepseek.com",
+      "available_models": [
+        {
+          "name": "deepseek-v4-flash",
+          "display_name": "DeepSeek V4 Flash",
+          "max_tokens": 1000000,
+          "max_output_tokens": 384000
+        },
+        {
+          "name": "deepseek-v4-pro",
+          "display_name": "DeepSeek V4 Pro",
+          "max_tokens": 1000000,
+          "max_output_tokens": 384000
+        }
+      ]
+    }
+  }
+}
+```
+
+Custom models will be listed in the model dropdown in the Agent Panel.
+You can also modify the `api_url` to use a custom endpoint if needed.
+
+### GitHub Copilot Chat {#github-copilot-chat}
+
+You can use GitHub Copilot Chat with the Zed agent by choosing it via the model dropdown in the Agent Panel.
+
+1. Open the settings view ({#action agent::OpenSettings}) and go to the GitHub Copilot Chat section
+2. Click on `Sign in to use GitHub Copilot`, follow the steps shown in the modal.
+
+Alternatively, you can provide an OAuth token via the `GH_COPILOT_TOKEN` environment variable.
+
+> **Note**: If you don't see specific models in the dropdown, you may need to enable them in your [GitHub Copilot settings](https://github.com/settings/copilot/features).
+
+To use Copilot Enterprise with Zed (for both agent and completions), you must configure your enterprise endpoint as described in [Configuring GitHub Copilot Enterprise](./edit-prediction.md#using-github-copilot-enterprise).
+
+### Google AI {#google-ai}
+
+You can use Gemini models with the Zed agent by choosing it via the model dropdown in the Agent Panel.
+
+1. Go to the Google AI Studio site and [create an API key](https://aistudio.google.com/app/apikey).
+2. Open the settings view ({#action agent::OpenSettings}) and go to the Google AI section
+3. Enter your Google AI API key and press enter.
+
+The Google AI API key will be saved in your keychain.
+
+Zed will also use the `GEMINI_API_KEY` environment variable if it's defined. See [Using Gemini API keys](https://ai.google.dev/gemini-api/docs/api-key) in the Gemini docs for more.
+
+#### Custom Models {#google-ai-custom-models}
+
+By default, Zed will use `stable` versions of models, but you can use specific versions of models, including [experimental models](https://ai.google.dev/gemini-api/docs/models/experimental-models). You can configure a model to use [thinking mode](https://ai.google.dev/gemini-api/docs/thinking) (if it supports it) by adding a `mode` configuration to your model. This is useful for controlling reasoning token usage and response speed. If not specified, Gemini will automatically choose the thinking budget.
+
+Here is an example of a custom Google AI model you could add to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "language_models": {
+    "google": {
+      "available_models": [
+        {
+          "name": "gemini-3.1-pro-preview",
+          "display_name": "Gemini 3.1 Pro",
+          "max_tokens": 1000000,
+          "mode": {
+            "type": "thinking",
+            "budget_tokens": 24000
+          }
+        },
+        {
+          "name": "gemini-3-flash-preview",
+          "display_name": "Gemini 3 Flash (Thinking)",
+          "max_tokens": 1000000,
+          "mode": {
+            "type": "thinking",
+            "budget_tokens": 24000
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+Custom models will be listed in the model dropdown in the Agent Panel.
+
+### LM Studio {#lmstudio}
+
+1. Download and install [the latest version of LM Studio](https://lmstudio.ai/download)
+2. In the app press `cmd/ctrl-shift-m` and download at least one model (e.g., qwen2.5-coder-7b). Alternatively, you can get models via the LM Studio CLI:
+
+   ```sh
+   lms get qwen2.5-coder-7b
+   ```
+
+3. Make sure the LM Studio API server is running by executing:
+
+   ```sh
+   lms server start
+   ```
+
+Tip: Set [LM Studio as a login item](https://lmstudio.ai/docs/advanced/headless#run-the-llm-service-on-machine-login) to automate running the LM Studio server.
+
+### Mistral {#mistral}
+
+1. Visit the Mistral platform and [create an API key](https://console.mistral.ai/api-keys/)
+2. Open the configuration view ({#action agent::OpenSettings}) and navigate to the Mistral section
+3. Enter your Mistral API key
+
+The Mistral API key will be saved in your keychain.
+
+Zed will also use the `MISTRAL_API_KEY` environment variable if it's defined.
+
+#### Custom Models {#mistral-custom-models}
+
+The Zed agent comes pre-configured to use the latest version for common Mistral models (Large, Medium, Small, Codestral, Devstral, and others).
+All the default models support tool use.
+If you wish to use alternate models or customize their parameters, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "language_models": {
+    "mistral": {
+      "api_url": "https://api.mistral.ai/v1",
+      "available_models": [
+        {
+          "name": "mistral-tiny-latest",
+          "display_name": "Mistral Tiny",
+          "max_tokens": 32000,
+          "max_output_tokens": 4096,
+          "max_completion_tokens": 1024,
+          "supports_tools": true,
+          "supports_images": false
+        }
+      ]
+    }
+  }
+}
+```
+
+Custom models will be listed in the model dropdown in the Agent Panel.
+
+### Ollama {#ollama}
+
+Download and install Ollama from [ollama.com/download](https://ollama.com/download) (Linux or macOS) and ensure it's running with `ollama --version`.
+
+1. Download one of the [available models](https://ollama.com/models), for example, for `mistral`:
+
+   ```sh
+   ollama pull mistral
+   ```
+
+2. Make sure that the Ollama server is running. You can start it either via running Ollama.app (macOS) or launching:
+
+   ```sh
+   ollama serve
+   ```
+
+3. In the Agent Panel, select one of the Ollama models using the model dropdown.
+
+#### Ollama Autodiscovery
+
+Zed will automatically discover models that Ollama has pulled. You can turn this off by setting
+the `auto_discover` field in the Ollama settings. If you do this, you should manually specify which
+models are available.
+
+```json [settings]
+{
+  "language_models": {
+    "ollama": {
+      "api_url": "http://localhost:11434",
+      "auto_discover": false,
+      "available_models": [
+        {
+          "name": "qwen2.5-coder",
+          "display_name": "qwen 2.5 coder",
+          "max_tokens": 32768,
+          "supports_tools": true,
+          "supports_thinking": true,
+          "supports_images": true
+        }
+      ]
+    }
+  }
+}
+```
+
+#### Ollama Context Length {#ollama-context}
+
+Zed API requests to Ollama include the context length as the `num_ctx` parameter. By default, Zed uses a context length of `4096` tokens for all Ollama models.
+
+> **Note**: Token counts displayed in the Agent Panel are only estimates and will differ from the model's native tokenizer.
+
+You can set a context length for all Ollama models using the `context_window` setting. This can also be configured in the Ollama provider settings UI:
+
+```json [settings]
+{
+  "language_models": {
+    "ollama": {
+      "context_window": 8192
+    }
+  }
+}
+```
+
+Alternatively, you can configure the context length per-model using the `max_tokens` field in `available_models`:
+
+```json [settings]
+{
+  "language_models": {
+    "ollama": {
+      "api_url": "http://localhost:11434",
+      "available_models": [
+        {
+          "name": "qwen2.5-coder",
+          "display_name": "qwen 2.5 coder 32K",
+          "max_tokens": 32768,
+          "supports_tools": true,
+          "supports_thinking": true,
+          "supports_images": true
+        }
+      ]
+    }
+  }
+}
+```
+
+> **Note**: If `context_window` is set, it overrides any per-model `max_tokens` values.
+
+If you specify a context length that is too large for your hardware, Ollama will log an error.
+You can watch these logs by running: `tail -f ~/.ollama/logs/ollama.log` (macOS) or `journalctl -u ollama -f` (Linux).
+Depending on the memory available on your machine, you may need to adjust the context length to a smaller value.
+
+You may also optionally specify a value for `keep_alive` for each available model.
+This can be an integer (seconds) or alternatively a string duration like "5m", "10m", "1h", "1d", etc.
+For example, `"keep_alive": "120s"` will allow the remote server to unload the model (freeing up GPU VRAM) after 120 seconds.
+
+The `supports_tools` option controls whether the model will use additional tools.
+If the model is tagged with `tools` in the Ollama catalog, this option should be supplied, and the built-in profiles `Ask` and `Write` can be used.
+If the model is not tagged with `tools` in the Ollama catalog, this option can still be supplied with the value `true`; however, be aware that only the `Minimal` built-in profile will work.
+
+The `supports_thinking` option controls whether the model will perform an explicit "thinking" (reasoning) pass before producing its final answer.
+If the model is tagged with `thinking` in the Ollama catalog, set this option and you can use it in Zed.
+
+The `supports_images` option enables the model's vision capabilities, allowing it to process images included in the conversation context.
+If the model is tagged with `vision` in the Ollama catalog, set this option and you can use it in Zed.
+
+#### Ollama Authentication
+
+In addition to running Ollama on your own hardware, which generally does not require authentication, Zed also supports connecting to remote Ollama instances. API keys are required for authentication.
+
+One such service is [Ollama Turbo](https://ollama.com/turbo). To configure Zed to use Ollama Turbo:
+
+1. Sign in to your Ollama account and subscribe to Ollama Turbo
+2. Visit [ollama.com/settings/keys](https://ollama.com/settings/keys) and create an API key
+3. Open the settings view ({#action agent::OpenSettings}) and go to the Ollama section
+4. Paste your API key and press enter.
+5. For the API URL enter `https://ollama.com`
+
+Zed will also use the `OLLAMA_API_KEY` environment variables if defined.
+
+### OpenAI {#openai}
+
+1. Visit the OpenAI platform and [create an API key](https://platform.openai.com/account/api-keys)
+2. Make sure that your OpenAI account has credits
+3. Open the settings view ({#action agent::OpenSettings}) and go to the OpenAI section
+4. Enter your OpenAI API key
+
+The OpenAI API key will be saved in your keychain.
+
+Zed will also use the `OPENAI_API_KEY` environment variable if it's defined.
+
+#### Custom Models {#openai-custom-models}
+
+The Zed agent comes pre-configured to use the latest version for common OpenAI models (GPT-5.2, GPT-5 mini, GPT-5.2 Codex, and others).
+To use alternate models, perhaps a preview release, or if you wish to control the request parameters, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "language_models": {
+    "openai": {
+      "available_models": [
+        {
+          "name": "gpt-5.2",
+          "display_name": "gpt-5.2 high",
+          "reasoning_effort": "high",
+          "max_tokens": 272000,
+          "max_completion_tokens": 20000
+        },
+        {
+          "name": "gpt-5-nano",
+          "display_name": "GPT-5 Nano",
+          "max_tokens": 400000
+        },
+        {
+          "name": "gpt-5.2-codex",
+          "display_name": "GPT-5.2 Codex",
+          "max_tokens": 128000,
+          "capabilities": {
+            "chat_completions": false
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+You must provide the model's context window in the `max_tokens` parameter; this can be found in the [OpenAI model documentation](https://platform.openai.com/docs/models).
+
+For reasoning-focused models, set `max_completion_tokens` as well to avoid incurring high reasoning token costs.
+
+If a model does not support the `/chat/completions` endpoint (for example `gpt-5.2-codex`), disable it by setting `capabilities.chat_completions` to `false`. Zed will use the Responses endpoint instead.
+
+Custom models will be listed in the model dropdown in the Agent Panel.
+
+### OpenAI API Compatible {#openai-api-compatible}
+
+Zed supports using [OpenAI compatible APIs](https://platform.openai.com/docs/api-reference/chat) by specifying a custom `api_url` and `available_models` for the OpenAI provider.
+This is useful for connecting to other hosted services (like Together AI, Anyscale, etc.) or local models.
+
+You can add a custom, OpenAI-compatible model either via the UI or by editing your settings file.
+
+To do it via the UI, go to the Agent Panel settings ({#action agent::OpenSettings}) and look for the "Add Provider" button to the right of the "LLM Providers" section title.
+Then, fill up the input fields available in the modal.
+
+To do it via your settings file ([how to edit](../configuring-zed.md#settings-files)), add the following snippet under `language_models`:
+
+```json [settings]
+{
+  "language_models": {
+    "openai_compatible": {
+      // Using Together AI as an example
+      "Together AI": {
+        "api_url": "https://api.together.xyz/v1",
+        "available_models": [
+          {
+            "name": "mistralai/Mixtral-8x7B-Instruct-v0.1",
+            "display_name": "Together Mixtral 8x7B",
+            "max_tokens": 32768,
+            "capabilities": {
+              "tools": true,
+              "images": false,
+              "parallel_tool_calls": false,
+              "prompt_cache_key": false
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+By default, OpenAI-compatible models inherit the following capabilities:
+
+- `tools`: true (supports tool/function calling)
+- `images`: false (does not support image inputs)
+- `parallel_tool_calls`: false (does not support `parallel_tool_calls` parameter)
+- `prompt_cache_key`: false (does not support `prompt_cache_key` parameter)
+- `chat_completions`: true (calls the `/chat/completions` endpoint)
+- `interleaved_reasoning`: false (thinking tokens are sent inline in message text; set to true to send them as a dedicated `reasoning_content` field for models that expect it)
+
+If a provider exposes models that only work with the Responses API, set `chat_completions` to `false` for those entries. Zed uses the Responses endpoint for these models.
+
+Note that LLM API keys aren't stored in your settings file.
+So, ensure you have it set in your environment variables (`<PROVIDER_NAME>_API_KEY=<your api key>`) so your settings can pick it up. In the example above, it would be `TOGETHER_AI_API_KEY=<your api key>`.
+
+### OpenCode {#opencode}
+
+OpenCode offers multiple ways to access AI models:
+
+- [OpenCode Zen](https://opencode.ai/zen/): a pay-as-you-go subscription with access to a large number of tested and verified models
+- [OpenCode Zen Free](https://opencode.ai/docs/zen/#pricing): free access to a limited set of models, with data and feedback collected to improve the models
+- [OpenCode Go](https://opencode.ai/go): a low-cost monthly subscription with access to a validated set of open coding models
+
+1. Visit [OpenCode Console](https://opencode.ai/auth) and create an account
+2. Free models are available without payment. To use Zen or Go models, make sure you have enough credits or an active subscription
+3. Generate an API key from the "API Keys" section in the OpenCode Console
+4. Open the settings view ({#action agent::OpenSettings}) and go to the OpenCode section
+5. Enter your OpenCode API key
+
+The OpenCode API key will be saved in your keychain.
+
+Zed will also use the `OPENCODE_API_KEY` environment variable if it's defined.
+
+By default, models from all subscription types are shown. Optionally, you can hide subscriptions that are not relevant to you by clicking the toggles or by adding the following to your settings:
+
+```json [settings]
+{
+  "language_models": {
+    "opencode": {
+      "show_zen_models": true,
+      "show_go_models": false,
+      "show_free_models": false
+    }
+  }
+}
+```
+
+#### Custom Models {#opencode-custom-models}
+
+The Zed agent comes pre-configured with OpenCode models. If you wish to use newer models or models with custom endpoints, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "language_models": {
+    "opencode": {
+      "available_models": [
+        {
+          "name": "my-custom-model",
+          "display_name": "My Custom Model",
+          "max_tokens": 123456,
+          "max_output_tokens": 98765,
+          "protocol": "openai_chat",
+          "reasoning_effort_levels": ["low", "medium", "high"],
+          "interleaved_reasoning": false,
+          "subscription": "go",
+          "custom_model_api_url": "https://example.com/zen"
+        }
+      ]
+    }
+  }
+}
+```
+
+The available configuration options for custom models are:
+
+- `name` (required): model id used by OpenCode, for example `glm-9000`
+- `display_name` (optional): human-readable model name shown in the UI, for example `Custom GLM 9000`
+- `max_tokens` (required): maximum model context window size, for example `1000000`
+- `max_output_tokens` (optional): maximum tokens the model can generate, for example `64000`
+- `protocol` (required): model API protocol, one of `"anthropic"`, `"openai_responses"`, `"openai_chat"`, or `"google"`
+- `reasoning_effort_levels` (optional): list of supported reasoning effort levels, for example `["low", "medium", "high"]`. The latest value in the list is used as the default
+- `interleaved_reasoning` (optional, default `false`): if thinking tokens are sent as a dedicated `reasoning_content` field (`true`) or inline in message text (`false`). Applies only when using the `openai_chat` protocol
+- `subscription` (optional): `"zen"`, `"go"`, or `"free"` (defaults to `"zen"`)
+- `custom_model_api_url` (optional): custom API base URL to use instead of the default OpenCode API
+
+Custom models will be listed in the model dropdown in the Agent Panel.
+
+### OpenRouter {#openrouter}
+
+OpenRouter provides access to multiple AI models through a single API. It supports tool use for compatible models.
+
+1. Visit [OpenRouter](https://openrouter.ai) and create an account
+2. Generate an API key from your [OpenRouter keys page](https://openrouter.ai/keys)
+3. Open the settings view ({#action agent::OpenSettings}) and go to the OpenRouter section
+4. Enter your OpenRouter API key
+
+The OpenRouter API key will be saved in your keychain.
+
+Zed will also use the `OPENROUTER_API_KEY` environment variable if it's defined.
+
+When using OpenRouter as your assistant provider, you must explicitly select a model in your settings. OpenRouter no longer provides a default model selection.
+
+Configure your preferred OpenRouter model in `settings.json`:
+
+```json [settings]
+{
+  "agent": {
+    "default_model": {
+      "provider": "openrouter",
+      "model": "openrouter/auto"
+    }
+  }
+}
+```
+
+The `openrouter/auto` model automatically routes your requests to the most appropriate available model. You can also specify any model available through OpenRouter's API.
+
+#### Custom Models {#openrouter-custom-models}
+
+You can add custom models to the OpenRouter provider by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "language_models": {
+    "open_router": {
+      "api_url": "https://openrouter.ai/api/v1",
+      "available_models": [
+        {
+          "name": "google/gemini-2.0-flash-thinking-exp",
+          "display_name": "Gemini 2.0 Flash (Thinking)",
+          "max_tokens": 200000,
+          "max_output_tokens": 8192,
+          "supports_tools": true,
+          "supports_images": true,
+          "mode": {
+            "type": "thinking",
+            "budget_tokens": 8000
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+The available configuration options for each model are:
+
+- `name` (required): The model identifier used by OpenRouter
+- `display_name` (optional): A human-readable name shown in the UI
+- `max_tokens` (required): The model's context window size
+- `max_output_tokens` (optional): Maximum tokens the model can generate
+- `max_completion_tokens` (optional): Maximum completion tokens
+- `supports_tools` (optional): Whether the model supports tool/function calling
+- `supports_images` (optional): Whether the model supports image inputs
+- `mode` (optional): Special mode configuration for thinking models
+
+You can find available models and their specifications on the [OpenRouter models page](https://openrouter.ai/models).
+
+Custom models will be listed in the model dropdown in the Agent Panel.
+
+#### Provider Routing
+
+You can optionally control how OpenRouter routes a given custom model request among underlying upstream providers via the `provider` object on each model entry.
+
+Supported fields (all optional):
+
+- `order`: Array of provider slugs to try first, in order (e.g. `["anthropic", "openai"]`)
+- `allow_fallbacks` (default: `true`): Whether fallback providers may be used if preferred ones are unavailable
+- `require_parameters` (default: `false`): Only use providers that support every parameter you supplied
+- `data_collection` (default: `allow`): `"allow"` or `"disallow"` (controls use of providers that may store data)
+- `only`: Whitelist of provider slugs allowed for this request
+- `ignore`: Provider slugs to skip
+- `quantizations`: Restrict to specific quantization variants (e.g. `["int4","int8"]`)
+- `sort`: Sort strategy for candidate providers (e.g. `"price"` or `"throughput"`)
+
+Example adding routing preferences to a model:
+
+```json [settings]
+{
+  "language_models": {
+    "open_router": {
+      "api_url": "https://openrouter.ai/api/v1",
+      "available_models": [
+        {
+          "name": "openrouter/auto",
+          "display_name": "Auto Router (Tools Preferred)",
+          "max_tokens": 2000000,
+          "supports_tools": true,
+          "provider": {
+            "order": ["anthropic", "openai"],
+            "allow_fallbacks": true,
+            "require_parameters": true,
+            "only": ["anthropic", "openai", "google"],
+            "ignore": ["cohere"],
+            "quantizations": ["int8"],
+            "sort": "price",
+            "data_collection": "allow"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+These routing controls let you fine‑tune cost, capability, and reliability trade‑offs without changing the model name you select in the UI.
+
+### Vercel AI Gateway {#vercel-ai-gateway}
+
+[Vercel AI Gateway](https://vercel.com/ai-gateway) provides access to many models through a single OpenAI-compatible endpoint.
+
+1. Create an API key from your [Vercel AI Gateway keys page](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys&title=Go+to+AI+Gateway)
+2. Open the settings view ({#action agent::OpenSettings}) and go to the **Vercel AI Gateway** section
+3. Enter your Vercel AI Gateway API key
+
+The Vercel AI Gateway API key will be saved in your keychain.
+
+Zed will also use the `VERCEL_AI_GATEWAY_API_KEY` environment variable if it's defined.
+
+You can also set a custom endpoint for Vercel AI Gateway in your settings file:
+
+```json [settings]
+{
+  "language_models": {
+    "vercel_ai_gateway": {
+      "api_url": "https://ai-gateway.vercel.sh/v1"
+    }
+  }
+}
+```
+
+### xAI {#xai}
+
+Zed includes a dedicated [xAI](https://x.ai/) provider. You can use your own API key to access Grok models.
+
+1. [Create an API key in the xAI Console](https://console.x.ai/team/default/api-keys)
+2. Open the settings view ({#action agent::OpenSettings}) and go to the **xAI** section
+3. Enter your xAI API key
+
+The xAI API key will be saved in your keychain. Zed will also use the `XAI_API_KEY` environment variable if it's defined.
+
+> **Note:** The xAI API is OpenAI-compatible, and Zed also includes a dedicated xAI provider. We recommend using the dedicated `x_ai` provider configuration instead of the [OpenAI API Compatible](#openai-api-compatible) method.
+
+#### Custom Models {#xai-custom-models}
+
+The Zed agent comes pre-configured with common Grok models. If you wish to use alternate models or customize their parameters, you can do so by adding the following to your Zed settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json [settings]
+{
+  "language_models": {
+    "x_ai": {
+      "api_url": "https://api.x.ai/v1",
+      "available_models": [
+        {
+          "name": "grok-1.5",
+          "display_name": "Grok 1.5",
+          "max_tokens": 131072,
+          "max_output_tokens": 8192
+        },
+        {
+          "name": "grok-1.5v",
+          "display_name": "Grok 1.5V (Vision)",
+          "max_tokens": 131072,
+          "max_output_tokens": 8192,
+          "supports_images": true
+        }
+      ]
+    }
+  }
+}
+```
+
+## Custom Provider Endpoints {#custom-provider-endpoint}
+
+You can use a custom API endpoint for different providers, as long as it's compatible with the provider's API structure.
+To do so, add the following to your settings file ([how to edit](../configuring-zed.md#settings-files)):
+
+```json
+{
+  "language_models": {
+    "some-provider": {
+      "api_url": "http://localhost:11434"
+    }
+  }
+}
+```
+
+Currently, `some-provider` can be any of the following values: `anthropic`, `google`, `ollama`, `openai`.
+
+This is the same infrastructure that powers models that are, for example, [OpenAI-compatible](#openai-api-compatible).

docs/src/ai/mcp.md

@@ -0,0 +1,173 @@
+---
+title: Model Context Protocol (MCP) in Zed
+description: Install and configure MCP servers in Zed to extend your AI agent with external tools, data sources, and integrations.
+---
+
+# Model Context Protocol
+
+Zed uses the [Model Context Protocol](https://modelcontextprotocol.io/) to interact with context servers.
+
+> The Model Context Protocol (MCP) is an open protocol for connecting LLM applications to external tools and data sources through a standard interface.
+
+## Supported Features
+
+Zed currently supports MCP's [Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) and [Prompts](https://modelcontextprotocol.io/specification/2025-11-25/server/prompts) features.
+We welcome contributions that help advance Zed's MCP feature coverage (Discovery, Sampling, Elicitation, etc).
+
+Zed also handles the `notifications/tools/list_changed` notification from MCP servers. When a server adds, removes, or modifies its available tools at runtime, Zed automatically reloads the tool list without requiring a server restart.
+
+## Installing MCP Servers
+
+### As Extensions
+
+One of the ways you can use MCP servers in Zed is by exposing them as an extension.
+Check out the [MCP Server Extensions](../extensions/mcp-extensions.md) page to learn how to create your own.
+
+Many MCP servers are available as extensions. Find them via:
+
+1. [the Zed website](https://zed.dev/extensions?filter=context-servers)
+2. in the app, open the Command Palette and run the {#action zed::Extensions} action
+3. in the app, go to the Agent Panel's top-right menu and look for the "View Server Extensions" menu item
+
+Popular servers available as an extension include:
+
+- [Context7](https://zed.dev/extensions/mcp-server-context7)
+- [GitHub](https://zed.dev/extensions/mcp-server-github)
+- [Puppeteer](https://zed.dev/extensions/mcp-server-puppeteer)
+- [Gem](https://zed.dev/extensions/gem)
+- [Brave Search](https://zed.dev/extensions/mcp-server-brave-search)
+- [Prisma](https://github.com/aqrln/prisma-mcp-zed)
+- [Framelink Figma](https://zed.dev/extensions/mcp-server-figma)
+- [Resend](https://zed.dev/extensions/mcp-server-resend)
+
+### As Custom Servers
+
+Creating an extension is not the only way to use MCP servers in Zed.
+You can connect them by adding their commands directly to your settings file ([how to edit](../configuring-zed.md#settings-files)), like so:
+
+```json [settings]
+{
+  "context_servers": {
+    "local-mcp-server": {
+      "command": "some-command",
+      "args": ["arg-1", "arg-2"],
+      "env": {}
+    },
+    "remote-mcp-server": {
+      "url": "custom",
+      "headers": { "Authorization": "Bearer <token>" }
+    },
+    "remote-mcp-server-with-oauth": {
+      "url": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+
+Alternatively, you can also add a custom server by accessing the Agent Panel's Settings view (also accessible via the {#action agent::OpenSettings} action).
+From there, you can add it through the modal that appears when you click the "Add Custom Server" button.
+
+> Note: When a remote MCP server has no configured `"Authorization"` header, Zed will prompt you to authenticate yourself against the MCP server using the standard MCP OAuth flow.
+
+## Using MCP Servers
+
+### Configuration Check
+
+Most MCP servers require configuration after installation.
+
+In the case of extensions, after installing it, Zed will pop up a modal displaying what is required for you to properly set it up.
+For example, the GitHub MCP extension requires you to add a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+In the case of custom servers, make sure you check the provider documentation to determine what type of command, arguments, and environment variables need to be added to the JSON.
+
+To check if your MCP server is properly configured, go to the Agent Panel's settings view and watch the indicator dot next to its name.
+If they're running correctly, the indicator will be green and its tooltip will say "Server is active".
+If not, other colors and tooltip messages will indicate what is happening.
+
+### Agent Panel Usage
+
+Once installation is complete, you can return to the Agent Panel and start prompting.
+
+How reliably MCP tools get called can vary from model to model.
+Mentioning the MCP server by name can help the model pick tools from that server.
+
+However, if you want to _ensure_ a given MCP server will be used, you can create [a custom profile](./agent-panel.md#custom-profiles) where all built-in tools (or the ones that could cause conflicts with the server's tools) are turned off and only the tools coming from the MCP server are turned on.
+
+As an example, [the Dagger team suggests](https://container-use.com/agent-integrations#zed) doing that with their [Container Use MCP server](https://zed.dev/extensions/mcp-server-container-use):
+
+```json [settings]
+"agent": {
+  "profiles": {
+    "container-use": {
+      "name": "Container Use",
+      "tools": {
+        "fetch": true,
+        "thinking": true,
+        "copy_path": false,
+        "find_path": false,
+        "delete_path": false,
+        "create_directory": false,
+        "list_directory": false,
+        "diagnostics": false,
+        "read_file": false,
+        "move_path": false,
+        "grep": false,
+        "edit_file": false,
+        "terminal": false
+      },
+      "enable_all_context_servers": false,
+      "context_servers": {
+        "container-use": {
+          "tools": {
+            "environment_create": true,
+            "environment_add_service": true,
+            "environment_update": true,
+            "environment_run_cmd": true,
+            "environment_open": true,
+            "environment_file_write": true,
+            "environment_file_read": true,
+            "environment_file_list": true,
+            "environment_file_delete": true,
+            "environment_checkpoint": true
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Tool Permissions
+
+> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
+> In earlier versions, it was controlled by the `agent.always_allow_tool_actions` boolean (default `false`).
+
+Zed's Agent Panel provides the `agent.tool_permissions.default` setting to control tool approval behavior for the native Zed agent:
+
+- `"confirm"` (default) — Prompts for approval before running any tool action, including MCP tool calls
+- `"allow"` — Auto-approves tool actions without prompting
+- `"deny"` — Blocks all tool actions
+
+For granular control over specific MCP tools, you can configure per-tool permission rules.
+MCP tools use the key format `mcp:<server>:<tool_name>` — for example, `mcp:github:create_issue`.
+The `default` key on a per-tool entry is the primary mechanism for MCP tools, since pattern-based rules match against an empty string for MCP tools and most patterns won't match.
+
+Learn more about [how tool permissions work](./tool-permissions.md), how to further customize them, and other details.
+
+### External Agents
+
+MCP servers configured in Zed are forwarded to [external agents](./external-agents.md) via the [Agent Client Protocol](https://agentclientprotocol.com/). External agents can also access MCP servers from their own native configuration files.
+
+For details on what configuration is shared between Zed and external agents, see [Configuration Boundaries](./external-agents.md#configuration-boundaries).
+
+### Error Handling
+
+When a MCP server encounters an error while processing a tool call, the agent receives the error message directly and the operation fails.
+Common error scenarios include:
+
+- Invalid parameters passed to the tool
+- Server-side failures (database connection issues, rate limits)
+- Unsupported operations or missing resources
+
+The error message from the context server will be shown in the agent's response, allowing you to diagnose and correct the issue.
+Check the context server's logs or documentation for details about specific error codes.

docs/src/ai/models.md

@@ -0,0 +1,135 @@
+---
+title: AI Models and Pricing - Zed
+description: AI models available via Zed Pro including Claude, GPT-5.5, Gemini 3.1 Pro, and Grok. Pricing, context windows, and tool call support.
+---
+
+# Models
+
+Zed's plans offer hosted versions of major LLMs with higher rate limits than direct API access. Model availability is updated regularly. To use your own API keys instead, see [LLM Providers](./llm-providers.md). For general setup, see [Configuration](./configuration.md).
+
+> **Note:** Claude Opus models, GPT-5.5 pro, and GPT-5.4 pro are not available on the [Student plan](./plans-and-usage.md#student).
+
+| Model                  | Provider  | Token Type          | Provider Price per 1M tokens | Zed Price per 1M tokens |
+| ---------------------- | --------- | ------------------- | ---------------------------- | ----------------------- |
+| Claude Opus 4.5        | Anthropic | Input               | $5.00                        | $5.50                   |
+|                        | Anthropic | Output              | $25.00                       | $27.50                  |
+|                        | Anthropic | Input - Cache Write | $6.25                        | $6.875                  |
+|                        | Anthropic | Input - Cache Read  | $0.50                        | $0.55                   |
+| Claude Opus 4.6        | Anthropic | Input               | $5.00                        | $5.50                   |
+|                        | Anthropic | Output              | $25.00                       | $27.50                  |
+|                        | Anthropic | Input - Cache Write | $6.25                        | $6.875                  |
+|                        | Anthropic | Input - Cache Read  | $0.50                        | $0.55                   |
+| Claude Opus 4.7        | Anthropic | Input               | $5.00                        | $5.50                   |
+|                        | Anthropic | Output              | $25.00                       | $27.50                  |
+|                        | Anthropic | Input - Cache Write | $6.25                        | $6.875                  |
+|                        | Anthropic | Input - Cache Read  | $0.50                        | $0.55                   |
+| Claude Sonnet 4.5      | Anthropic | Input               | $3.00                        | $3.30                   |
+|                        | Anthropic | Output              | $15.00                       | $16.50                  |
+|                        | Anthropic | Input - Cache Write | $3.75                        | $4.125                  |
+|                        | Anthropic | Input - Cache Read  | $0.30                        | $0.33                   |
+| Claude Sonnet 4.6      | Anthropic | Input               | $3.00                        | $3.30                   |
+|                        | Anthropic | Output              | $15.00                       | $16.50                  |
+|                        | Anthropic | Input - Cache Write | $3.75                        | $4.125                  |
+|                        | Anthropic | Input - Cache Read  | $0.30                        | $0.33                   |
+| Claude Haiku 4.5       | Anthropic | Input               | $1.00                        | $1.10                   |
+|                        | Anthropic | Output              | $5.00                        | $5.50                   |
+|                        | Anthropic | Input - Cache Write | $1.25                        | $1.375                  |
+|                        | Anthropic | Input - Cache Read  | $0.10                        | $0.11                   |
+| GPT-5.5 pro            | OpenAI    | Input               | $30.00                       | $33.00                  |
+|                        | OpenAI    | Output              | $180.00                      | $198.00                 |
+| GPT-5.5                | OpenAI    | Input               | $5.00                        | $5.50                   |
+|                        | OpenAI    | Output              | $30.00                       | $33.00                  |
+|                        | OpenAI    | Cached Input        | $0.50                        | $0.55                   |
+| GPT-5.4 pro            | OpenAI    | Input               | $30.00                       | $33.00                  |
+|                        | OpenAI    | Output              | $180.00                      | $198.00                 |
+| GPT-5.4                | OpenAI    | Input               | $2.50                        | $2.75                   |
+|                        | OpenAI    | Output              | $15.00                       | $16.50                  |
+|                        | OpenAI    | Cached Input        | $0.025                       | $0.0275                 |
+| GPT-5.3-Codex          | OpenAI    | Input               | $1.75                        | $1.925                  |
+|                        | OpenAI    | Output              | $14.00                       | $15.40                  |
+|                        | OpenAI    | Cached Input        | $0.175                       | $0.1925                 |
+| GPT-5.2                | OpenAI    | Input               | $1.75                        | $1.925                  |
+|                        | OpenAI    | Output              | $14.00                       | $15.40                  |
+|                        | OpenAI    | Cached Input        | $0.175                       | $0.1925                 |
+| GPT-5.2-Codex          | OpenAI    | Input               | $1.75                        | $1.925                  |
+|                        | OpenAI    | Output              | $14.00                       | $15.40                  |
+|                        | OpenAI    | Cached Input        | $0.175                       | $0.1925                 |
+| GPT-5 mini             | OpenAI    | Input               | $0.25                        | $0.275                  |
+|                        | OpenAI    | Output              | $2.00                        | $2.20                   |
+|                        | OpenAI    | Cached Input        | $0.025                       | $0.0275                 |
+| GPT-5 nano             | OpenAI    | Input               | $0.05                        | $0.055                  |
+|                        | OpenAI    | Output              | $0.40                        | $0.44                   |
+|                        | OpenAI    | Cached Input        | $0.005                       | $0.0055                 |
+| Gemini 3.1 Pro         | Google    | Input               | $2.00                        | $2.20                   |
+|                        | Google    | Output              | $12.00                       | $13.20                  |
+| Gemini 3 Flash         | Google    | Input               | $0.50                        | $0.55                   |
+|                        | Google    | Output              | $3.00                        | $3.30                   |
+| Grok 4                 | X.ai      | Input               | $3.00                        | $3.30                   |
+|                        | X.ai      | Output              | $15.00                       | $16.5                   |
+|                        | X.ai      | Cached Input        | $0.75                        | $0.825                  |
+| Grok 4 Fast            | X.ai      | Input               | $0.20                        | $0.22                   |
+|                        | X.ai      | Output              | $0.50                        | $0.55                   |
+|                        | X.ai      | Cached Input        | $0.05                        | $0.055                  |
+| Grok 4 (Non-Reasoning) | X.ai      | Input               | $0.20                        | $0.22                   |
+|                        | X.ai      | Output              | $0.50                        | $0.55                   |
+|                        | X.ai      | Cached Input        | $0.05                        | $0.055                  |
+| Grok Code Fast 1       | X.ai      | Input               | $0.20                        | $0.22                   |
+|                        | X.ai      | Output              | $1.50                        | $1.65                   |
+|                        | X.ai      | Cached Input        | $0.02                        | $0.022                  |
+
+## Recent Model Retirements
+
+As of February 19, 2026, Zed Pro serves newer model versions in place of the retired models below:
+
+- Claude Opus 4.1 → Claude Opus 4.5, Claude Opus 4.6, or Claude Opus 4.7
+- Claude Sonnet 4 → Claude Sonnet 4.5 or Claude Sonnet 4.6
+- Claude Sonnet 3.7 (retired Feb 19) → Claude Sonnet 4.5 or Claude Sonnet 4.6
+- GPT-5.1 and GPT-5 → GPT-5.2 or GPT-5.2-Codex
+- Gemini 2.5 Pro → Gemini 3.1 Pro
+- Gemini 3 Pro → Gemini 3.1 Pro
+- Gemini 2.5 Flash → Gemini 3 Flash
+
+## Usage {#usage}
+
+Any usage of a Zed-hosted model will be billed at the Zed Price (rightmost column above). See [Plans and Usage](./plans-and-usage.md) for details on Zed's plans and limits for use of hosted models.
+
+> LLMs can enter unproductive loops that require user intervention. Monitor longer-running tasks and interrupt if needed.
+
+## Context Windows {#context-windows}
+
+A context window is the maximum span of text and code an LLM can consider at once, including both the input prompt and output generated by the model.
+
+| Model                       | Provider  | Zed-Hosted Context Window |
+| --------------------------- | --------- | ------------------------- |
+| Claude Opus 4.5             | Anthropic | 200k                      |
+| Claude Opus 4.6             | Anthropic | 1M                        |
+| Claude Opus 4.7             | Anthropic | 1M                        |
+| Claude Sonnet 4.5           | Anthropic | 200k                      |
+| Claude Sonnet 4.6           | Anthropic | 1M                        |
+| Claude Haiku 4.5            | Anthropic | 200k                      |
+| GPT-5.5 pro                 | OpenAI    | 272k input / 400k total   |
+| GPT-5.5                     | OpenAI    | 272k input / 400k total   |
+| GPT-5.4 pro                 | OpenAI    | 272k input / 400k total   |
+| GPT-5.4                     | OpenAI    | 272k input / 400k total   |
+| GPT-5.3-Codex               | OpenAI    | 272k input / 400k total   |
+| GPT-5.2                     | OpenAI    | 272k input / 400k total   |
+| GPT-5.2-Codex               | OpenAI    | 272k input / 400k total   |
+| GPT-5 mini                  | OpenAI    | 272k input / 400k total   |
+| GPT-5 nano                  | OpenAI    | 272k input / 400k total   |
+| Gemini 3.1 Pro              | Google    | 200k                      |
+| Gemini 3 Flash              | Google    | 200k                      |
+| Grok 4                      | X.ai      | 128k                      |
+| Grok 4 Fast                 | X.ai      | 128k                      |
+| Grok 4 Fast (Non-Reasoning) | X.ai      | 128k                      |
+| Grok Code Fast 1            | X.ai      | 256k                      |
+
+> Context window limits for hosted Gemini 3.1 Pro/3 Flash may increase in future releases.
+
+Each Agent thread in Zed maintains its own context window.
+The more prompts, attached files, and responses included in a session, the larger the context window grows.
+
+Start a new thread for each distinct task to keep context focused.
+
+## Tool Calls {#tool-calls}
+
+Models can use [tools](./tools.md) to interface with your code, search the web, and perform other useful functions.

docs/src/ai/overview.md

@@ -0,0 +1,43 @@
+---
+title: AI Code Editor Documentation - Zed
+description: Docs for AI in Zed, the open-source AI code editor. Agentic coding, inline edits, AI code completion, and multi-model support.
+---
+
+# AI
+
+Zed is an open-source AI code editor. AI runs throughout the editing experience: agents that read and write your code, inline transformations, code completions on every keystroke, and conversations with models in any buffer.
+
+## How Zed approaches AI
+
+Zed's AI features run inside a native, GPU-accelerated application built in Rust. There is no Electron layer between you and the model output.
+
+- **Open source.** The editor and all AI features are [open source](https://github.com/zed-industries/zed). You can read how AI is implemented, how data flows to providers, and how tool calls execute.
+- **Multi-model.** Use Zed's hosted models or [bring your own API keys](./llm-providers.md) from Anthropic, OpenAI, Google, Ollama, and 8+ other providers. Run local models, connect to cloud APIs, or mix both. Switch models per task.
+- **External agents.** Run Claude Agent, Gemini CLI, Codex, and other CLI-based agents directly in Zed through the [Agent Client Protocol](https://zed.dev/acp). See [External Agents](./external-agents.md).
+- **Privacy by default.** AI data sharing is opt-in. When you use your own API keys, Zed maintains zero-data retention agreements with providers. See [Privacy and Security](./privacy-and-security.md).
+
+## Agentic editing
+
+The [Threads Sidebar](./parallel-agents.md#threads-sidebar) is where you organize agent work. Start a thread, give it a task, and the agent reads, edits, and runs code in your project. You can run multiple threads at once, each using a different agent and working against different projects. See [Tools](./tools.md) for the capabilities available to Zed's built-in agent.
+
+The [Agent Panel](./agent-panel.md) is the conversation view for the active thread. Use it to send prompts, review changes, add context, and interact with the agent as it works.
+
+You can extend agents with additional tools through [MCP servers](./mcp.md), control what they can access with [tool permissions](./tool-permissions.md), and shape their behavior with [rules](./rules.md).
+
+The [Inline Assistant](./inline-assistant.md) works differently: select code or a terminal command, describe what you want, and the model rewrites the selection in place. It works with multiple cursors.
+
+## Code completions
+
+[Edit Prediction](./edit-prediction.md) provides AI code completions on every keystroke. Each keypress sends a request to the prediction provider, which returns single or multi-line suggestions you accept with `tab`.
+
+The default provider is Zeta, Zed's open-source model trained on open data. You can also use GitHub Copilot, or Codestral.
+
+## Getting started
+
+- [Configuration](./configuration.md): Connect to Anthropic, OpenAI, Ollama, Google AI, or other LLM providers.
+- [Parallel Agents](./parallel-agents.md): Run multiple threads at once with the Threads Sidebar.
+- [External Agents](./external-agents.md): Run Claude Agent, Codex, Aider, or other external agents inside Zed.
+- [Subscription](./subscription.md): Zed's hosted models and billing.
+- [Privacy and Security](./privacy-and-security.md): How Zed handles data when using AI features.
+
+New to Zed? Start with [Getting Started](../getting-started.md), then come back here to set up AI. For a higher-level overview, see [zed.dev/ai](https://zed.dev/ai).

docs/src/ai/parallel-agents.md

@@ -0,0 +1,80 @@
+---
+title: Parallel Agents - Zed
+description: Run multiple agent threads concurrently using the Threads Sidebar, manage them across projects, and isolate work using Git worktrees.
+---
+
+# Parallel Agents
+
+Parallel Agents lets you run multiple agent threads at once, each working independently with its own agent, context window, and conversation history. The Threads Sidebar is where you start, manage, and switch between them.
+
+Open the Threads Sidebar with {#kb multi_workspace::ToggleWorkspaceSidebar}.
+
+> **Note:** From version 0.233.0 onward, the Agent Panel and Threads Sidebar are on the left by default. The Project Panel, Git Panel, and other panels move to the right, keeping the thread list and conversation next to each other. To rearrange panels, right-click any panel icon.
+
+## Threads Sidebar {#threads-sidebar}
+
+The sidebar shows your threads grouped by project. Each project gets its own section with a header. Threads appear below with their title, status indicator, and which agent is running them. Threads running in linked Git worktrees appear under the same project as their main worktree. See [Worktree Isolation](#worktree-isolation).
+
+To focus the sidebar without toggling it, use {#kb multi_workspace::FocusWorkspaceSidebar}. To search your threads, press {#kb agents_sidebar::FocusSidebarFilter} while the sidebar is focused.
+
+### Switching Threads {#switching-threads}
+
+Click any thread in the sidebar to switch to it. The Agent Panel updates to show that thread's conversation.
+
+For quick switching without opening the sidebar, use the thread switcher: press {#kb agents_sidebar::ToggleThreadSwitcher} to cycle forward through recent threads, or hold `Shift` while pressing that binding to go backward. This works from both the Agent Panel and the Threads Sidebar.
+
+### Thread History {#threads-history}
+
+To remove a thread from the sidebar, you can archive it by hovering over it and clicking the archive icon that appears. You can also select a thread and press {#kb agent::ArchiveSelectedThread}. Running threads cannot be moved to history until they finish.
+
+The Thread History view holds all your threads, including ones that you have archived. Toggle it with {#kb agents_sidebar::ToggleThreadHistory} or by clicking the clock icon in the sidebar bottom bar, next to the sidebar toggle.
+
+To restore a thread, open Thread History and click the thread you want to bring back. Zed moves it back to the thread list and opens it in the Agent Panel. If the thread was running in a Git worktree that was removed, Zed restores the worktree automatically.
+
+To permanently delete a thread, open Thread History, hover over the thread, and click the trash icon. This removes the thread's conversation history and cleans up any associated worktree data. Deleted threads cannot be recovered.
+
+You can search your threads in history; search will fuzzy match on thread titles.
+
+### Importing External Agent Threads {#importing-threads}
+
+If you have external agents installed, Zed will detect whether you have existing threads and invite you to import them into Zed. Once you open Thread History, you'll find an import icon button in the Thread History toolbar that lets you import threads at any time. Clicking on it opens a modal where you can select the agents whose threads you want to import.
+
+> **Note:** Thread import is subject to agent support. Some agents (such as Cursor and Gemini CLI) are not currently supported.
+
+## Running Multiple Threads {#running-multiple-threads}
+
+Each thread runs independently, so you can send a prompt, open a second thread, and give it a different task while the first continues working. To scope a new thread to a specific project, hover over that project's header in the Threads Sidebar and click the `+` button, or use {#action agents_sidebar::NewThreadInGroup} from the keyboard. See [Creating New Threads](./agent-panel.md#new-thread) for the other entry points.
+
+Each thread can use a different agent, so you can run Zed's built-in agent in one thread and an [external agent](./external-agents.md) like Claude Code or Codex in another.
+
+## Multiple Projects {#multiple-projects}
+
+The Threads Sidebar can hold multiple projects at once. Each project gets its own group with its own threads and conversation history. This mirrors how Zed handles projects in general — see [Windows & Projects](../windows-and-projects.md) for more on how projects open and how to manage them.
+
+To add another project to the sidebar, click the **Add Project** button (open-folder icon) in the sidebar bottom bar. The popover that opens lists your recent projects and also provides **Add Local Folders** and **Add Remote Folder** buttons at the bottom.
+
+### Multi-Root Folder Projects {#multi-root-folder-projects}
+
+A single project can contain multiple folders (a multi-root folder project). Agents can then read and write across all of those folders in a single thread. There are multiple ways to set one up:
+
+- **From the sidebar:** Click the **Add Project** button, choose **Add Local Folders**, and select multiple folders in the file picker. They open together as one multi-root project.
+- **From the title bar:** Click the project picker (the leftmost project name). For any local entry in the recent projects list, hover it and click the folder-with-plus icon (**Add Folder to this Project**) to merge that project's folders into the current project.
+- **From the Project panel:** Right-click a root folder or any empty space in the Project panel and choose **Add Folders to Project** to add more folders to the current project.
+
+## Worktree Isolation {#worktree-isolation}
+
+If two threads might edit the same files, start one in a new [Git worktree](../git.md#git-worktrees) to give it an isolated checkout.
+
+Worktrees are managed from the title bar. Click the worktree picker (to the right of the project picker) to switch between existing worktrees or create a new one. New worktrees are created in a detached HEAD state, so you won't accidentally share a branch between worktrees.
+
+Once you're in a new worktree, use the branch picker next to the worktree picker to create a new branch or check out an existing one. If the branch you pick is already checked out in another worktree, the current worktree stays in detached HEAD until you choose a different branch.
+
+To automate setup steps whenever a new worktree is created use a [Task hook](../tasks.md#hooks). The `create_worktree` hook runs automatically after Zed creates a linked worktree, with `ZED_WORKTREE_ROOT` pointing at the new worktree and `ZED_MAIN_GIT_WORKTREE` pointing at the original repository.
+
+After the agent finishes, review the diff and merge the changes through your normal Git workflow. If the thread was running in a linked worktree and no other active threads use it, moving the thread to Thread History saves the worktree's Git state and removes it from disk. Restoring the thread from history restores the worktree.
+
+## See Also {#see-also}
+
+- [Agent Panel](./agent-panel.md): Manage individual threads and configure the agent
+- [External Agents](./external-agents.md): Use Claude Code, Gemini CLI, and other agents
+- [Tools](./tools.md): Built-in tools available in each thread

docs/src/ai/plans-and-usage.md

@@ -0,0 +1,64 @@
+---
+title: Plans & Pricing
+description: Compare Zed's Free, Pro, and Business plans, and understand token-based usage metering, spend limits, and trial details.
+---
+
+# Plans & Pricing
+
+For costs and more information on pricing, visit [Zed's pricing page](https://zed.dev/pricing).
+
+Zed works without AI features or a subscription. No [authentication](../authentication.md) is required for the editor itself.
+
+## Plans {#plans}
+
+|                                           | Free    | Pro       | Student   | Business  |
+| ----------------------------------------- | ------- | --------- | --------- | --------- |
+| Zed-hosted AI models                      | —       | ✓         | ✓         | ✓         |
+| [AI via own API keys](./llm-providers.md) | ✓       | ✓         | ✓         | ✓         |
+| [External agents](./external-agents.md)   | ✓       | ✓         | ✓         | ✓         |
+| Edit Predictions                          | Limited | Unlimited | Unlimited | Unlimited |
+| Org-wide admin controls                   | —       | —         | —         | ✓         |
+| Roles & permissions                       | —       | —         | —         | ✓         |
+| Consolidated billing                      | —       | —         | —         | ✓         |
+
+### Zed Free {#free}
+
+Zed is free to use. You can configure AI agents with your own API keys via [Providers](./llm-providers.md). [Edit Predictions](./edit-prediction.md) are available on a limited basis. Zed's hosted models require a Pro subscription.
+
+### Zed Pro {#pro}
+
+Zed Pro includes access to all hosted AI models and Edit Predictions. The plan includes $5 of monthly token credit; usage beyond that is billed at the rates listed on [the Models page](./models.md). A trial of Zed Pro includes $20 of credit, usable for 14 days.
+
+For details on billing and payment, see [Individual Billing](./billing.md).
+
+### Zed Business {#business}
+
+Zed Business gives every member access to all of Zed's hosted AI models, unlimited edit predictions, plus org-wide controls for administrators: which AI features are available, what data leaves your organization, and how AI spend is tracked. All seats and AI usage are consolidated into a single invoice.
+
+For a full feature overview, see [Zed Business](../business/overview.md). For billing details, see [Billing](./billing.md#organization).
+
+### Student Plan {#student}
+
+The [Zed Student plan](https://zed.dev/education) includes all Zed Pro features: unlimited [Edit Predictions](./edit-prediction.md), all [hosted AI models](./models.md) except Claude Opus, and $10/month in token credits. Available free for one year to verified university students.
+
+## Usage {#usage}
+
+Usage of Zed's hosted models is measured on a token basis, converted to dollars at the rates listed on [the Models page](./models.md) (list price from the provider, +10%).
+
+Monthly included credit resets on your monthly billing date. To view your current usage, navigate to the Billing page at [dashboard.zed.dev](https://dashboard.zed.dev). Usage data from our metering provider, Orb, is embedded on that page.
+
+## Spend Limits {#usage-spend-limits}
+
+On your Billing page you'll find an input for `Monthly Spend Limit`. The dollar amount here specifies your _monthly_ limit for spend on tokens, _not counting_ the $5/month included with your Pro subscription.
+
+The default value for all Pro users is $10, for a total monthly spend with Zed of $20 ($10 for your Pro subscription, $10 in incremental token spend). This can be set to $0 to limit your spend with Zed to exactly $10/month. If you adjust this limit _higher_ than $10 and consume more than $10 of incremental token spend, you'll be billed via [threshold billing](./billing.md#threshold-billing).
+
+Once the spend limit is hit, we'll stop any further usage until your token spend limit resets.
+
+On Zed Business, administrators set an org-wide spend limit from the Data & Privacy page in the organization dashboard. See [Organization Billing](./billing.md#ai-usage) for details.
+
+> **Note:** Spend limits are a Zed Pro and Business feature. Student plan users cannot configure spend limits; usage is capped at the $10/month included credit.
+
+### Trials {#trials}
+
+Trials automatically convert to Zed Free when they end. Trials do not include access to Anthropic's Opus models. No cancellation is needed to prevent conversion to Zed Pro.

docs/src/ai/privacy-and-security.md

@@ -0,0 +1,33 @@
+---
+title: Privacy Overview - Zed
+description: "Zed's approach to privacy: opt-in data sharing, zero-data retention with AI providers, and an open-source codebase you can inspect."
+---
+
+# Privacy Overview
+
+Zed collects minimal data necessary to serve and improve the product. Features that could share data are either opt-in or can be disabled.
+
+- **Telemetry:** Zed collects only the data necessary to understand usage and fix issues. Client-side telemetry can be disabled in settings. See [Telemetry](../telemetry.md).
+
+- **AI:** Zed doesn't store your prompts or code context. Data sharing for AI improvement is opt-in, and each share is a one-time action; it doesn't grant permission for future collection. You can use Zed's AI features without sharing any data with Zed. See [AI Improvement](./ai-improvement.md).
+
+- **Open source:** Zed's codebase is public. You can inspect exactly what data is collected and how it's handled. If you find issues, [report them](https://github.com/zed-industries/zed/issues).
+
+On Zed Business, administrators can enforce these settings org-wide so members can't opt in to data sharing individually. See [Privacy for Business](../business/privacy.md).
+
+## Related documentation
+
+- [Tool Permissions](./tool-permissions.md): Configure which agent actions are auto-approved, blocked, or require confirmation.
+- [Worktree Trust](../worktree-trust.md): How Zed opens files and directories in restricted mode.
+- [Telemetry](../telemetry.md): What telemetry Zed collects and how to control it.
+- [AI Improvement](./ai-improvement.md): How data sharing for AI improvement works and how to opt in.
+- [Privacy for Business](../business/privacy.md): How Zed Business enforces privacy settings across an organization.
+- [Authentication](../authentication.md): When and why authentication is needed.
+- [SOC2](../soc2.md): Zed's security certification status.
+
+## Legal
+
+- [Terms of Service](https://zed.dev/terms)
+- [Privacy Policy](https://zed.dev/privacy-policy)
+- [Contributor License and Feedback Agreement](https://zed.dev/cla)
+- [Subprocessors](https://zed.dev/subprocessors)

docs/src/ai/rules.md

@@ -0,0 +1,77 @@
+---
+title: AI Rules in Zed - .rules, .cursorrules, CLAUDE.md
+description: Configure AI behavior in Zed with .rules files, .cursorrules, CLAUDE.md, AGENTS.md, and the Rules Library for project-level instructions.
+---
+
+# Using Rules {#using-rules}
+
+Rules are prompts that can be inserted either automatically at the beginning of each [Agent Panel](./agent-panel.md) interaction, through `.rules` files available in your project's file tree, or on-demand, through @-mentioning, via the Rules Library.
+
+## `.rules` files
+
+Zed supports including `.rules` files at the root of a project's file tree, and they act as project-level instructions that are auto-included in all of your interactions with the Agent Panel.
+
+Other names for this file are also supported for compatibility with other agents, but note that the first file which matches in this list will be used:
+
+- `.rules`
+- `.cursorrules`
+- `.windsurfrules`
+- `.clinerules`
+- `.github/copilot-instructions.md`
+- `AGENT.md`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `GEMINI.md`
+
+## Rules Library {#rules-library}
+
+The Rules Library is an interface for writing and managing rules.
+It's a full editor with syntax highlighting and all standard keybindings.
+
+You can also use the inline assistant right in the rules editor, allowing you to get quick LLM support for writing rules.
+
+### Opening the Rules Library
+
+1. Open the Agent Panel.
+2. Click on the Agent menu (`...`) in the top right corner.
+3. Select `Rules...` from the dropdown.
+
+You can also open it by running the {#action agent::OpenRulesLibrary} action or through the {#kb agent::OpenRulesLibrary} keybinding.
+
+### Managing Rules
+
+Once a rules file is selected, you can edit it directly in the built-in editor.
+Its title can be changed from the editor title bar as well.
+
+Rules can be duplicated, deleted, or added to the default rules using the buttons in the rules editor.
+
+### Creating Rules {#creating-rules}
+
+To create a rule file, simply open the `Rules Library` and click the `+` button.
+Rules files are stored locally and can be accessed from the library at any time.
+
+For guidance on writing effective rules:
+
+- [Anthropic: Prompt Engineering](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview)
+- [OpenAI: Prompt Engineering](https://platform.openai.com/docs/guides/prompt-engineering)
+
+### Using Rules
+
+You can @-mention every rule created through the Rules Library.
+This allows you to quickly reach for reusable prompts, saving the time to type them out every time you need to use them.
+
+#### Default Rules {#default-rules}
+
+All rules in the Rules Library can be set as a default rule, which means they’re automatically inserted into context for every new Agent Panel interaction.
+
+You can set any rule as the default by clicking the paper clip icon button in the top-right of the rule editor in the Rules Library.
+
+## Migrating from Prompt Library
+
+Previously, the Rules Library was called the "Prompt Library".
+The new rules system replaces the Prompt Library except in a few specific cases, which are outlined below.
+
+### Slash Commands in Rules
+
+Previously, it was possible to use slash commands (now @-mentions) in custom prompts (now rules).
+There is currently no support for using @-mentions in rules files.

docs/src/ai/subscription.md

@@ -0,0 +1,18 @@
+---
+title: Zed AI Subscription
+description: Learn about Zed Pro and Business plans for hosted AI models with higher rate limits and premium features.
+---
+
+# Subscription
+
+Zed's hosted models are offered via subscription to Zed Pro or Zed Business.
+
+> You can use [your own API keys](./llm-providers.md) or [external agents](./external-agents.md) without a Zed subscription.
+
+See the following pages for specific aspects of our subscription offering:
+
+- [Models](./models.md): Overview of the models offered by Zed's subscriptions.
+
+- [Plans and Usage](./plans-and-usage.md): Outlines Zed's plans and how usage is measured.
+
+- [Billing](./billing.md): Billing policies and procedures, and how to update or view various billing settings.

docs/src/ai/text-threads.md

@@ -0,0 +1,13 @@
+---
+title: Text Threads (Removed)
+description: Text threads have been removed from Zed. Use the Agent Panel for all AI conversations.
+redirect_to: ./agent-panel.md
+---
+
+# Text Threads
+
+Text threads have been removed from Zed.
+
+All AI conversations now happen through the [Agent Panel](./agent-panel.md), which supports agentic workflows including tool calls, file editing, terminal access, and [external agents](./external-agents.md).
+
+See the [Agent Panel documentation](./agent-panel.md) to get started.

docs/src/ai/tool-permissions.md

@@ -0,0 +1,307 @@
+# Tool Permissions
+
+Configure which [Agent Panel](./agent-panel.md) tools run automatically and which require your approval.
+For a list of available tools, [see the Tools page](./tools.md).
+
+> **Note:** In Zed v0.224.0 and above, tool approval is controlled by `agent.tool_permissions.default`.
+> In earlier versions, it was controlled by the `agent.always_allow_tool_actions` boolean (default `false`).
+
+## Quick Start
+
+Use Zed's Settings Editor to [configure tool permissions](zed://settings/agent.tool_permissions), or add rules directly to your settings file:
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "default": "allow",
+      "tools": {
+        "terminal": {
+          "default": "confirm",
+          "always_allow": [
+            { "pattern": "^cargo\\s+(build|test|check)" },
+            { "pattern": "^npm\\s+(install|test|run)" }
+          ],
+          "always_confirm": [{ "pattern": "sudo\\s+/" }]
+        }
+      }
+    }
+  }
+}
+```
+
+This example auto-approves `cargo` and `npm` commands in the terminal tool, while requiring manual confirmation on a case-by-case basis for `sudo` commands.
+Non-terminal commands follow the global `"default": "allow"` setting, but tool-specific defaults and `always_confirm` rules can still prompt.
+
+## How It Works
+
+The `tool_permissions` setting lets you customize tool permissions by specifying regex patterns that:
+
+- **Auto-approve** actions you trust
+- **Auto-deny** dangerous actions (blocked even when `tool_permissions.default` is set to `"allow"`)
+- **Always confirm** sensitive actions regardless of other settings
+
+## Supported Tools
+
+| Tool               | Input Matched Against        |
+| ------------------ | ---------------------------- |
+| `terminal`         | The shell command string     |
+| `edit_file`        | The file path                |
+| `write_file`       | The file path                |
+| `delete_path`      | The path being deleted       |
+| `move_path`        | Source and destination paths |
+| `copy_path`        | Source and destination paths |
+| `create_directory` | The directory path           |
+| `fetch`            | The URL                      |
+| `search_web`       | The search query             |
+
+For MCP tools, use the format `mcp:<server>:<tool_name>`.
+For example, a tool called `create_issue` on a server called `github` would be `mcp:github:create_issue`.
+
+## Configuration
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "default": "confirm",
+      "tools": {
+        "<tool_name>": {
+          "default": "confirm",
+          "always_allow": [{ "pattern": "...", "case_sensitive": false }],
+          "always_deny": [{ "pattern": "...", "case_sensitive": false }],
+          "always_confirm": [{ "pattern": "...", "case_sensitive": false }]
+        }
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option           | Description                                                                    |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `default`        | Fallback when no patterns match: `"confirm"` (default), `"allow"`, or `"deny"` |
+| `always_allow`   | Patterns that auto-approve (unless deny or confirm also matches)               |
+| `always_deny`    | Patterns that block immediately—highest priority, cannot be overridden         |
+| `always_confirm` | Patterns that always prompt, even when `tool_permissions.default` is `"allow"` |
+
+### Pattern Syntax
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "tools": {
+        "edit_file": {
+          "always_allow": [
+            {
+              "pattern": "your-regex-here",
+              "case_sensitive": false
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+Patterns use Rust regex syntax.
+Matching is case-insensitive by default.
+
+## Rule Precedence
+
+From highest to lowest priority:
+
+1. **Built-in security rules**: Hardcoded protections (e.g., `rm -rf /`). Cannot be overridden.
+2. **`always_deny`**: Blocks matching actions
+3. **`always_confirm`**: Requires confirmation for matching actions
+4. **`always_allow`**: Auto-approves matching actions
+5. **Tool-specific `default`**: Per-tool fallback when no patterns match (e.g., `tools.terminal.default`)
+6. **Global `default`**: Falls back to `tool_permissions.default` when no tool-specific default is set
+
+## Global Auto-Approve
+
+To auto-approve all tool actions:
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "default": "allow"
+    }
+  }
+}
+```
+
+This bypasses confirmation prompts for most tools, but `always_deny`, `always_confirm`, built-in security rules, and paths inside Zed settings directories still prompt or block.
+
+## Shell Compatibility
+
+For the `terminal` tool, Zed parses chained commands (e.g., `echo hello && rm file`) to check each sub-command against your patterns.
+
+All supported shells work with tool permission patterns, including sh, bash, zsh, dash, fish, PowerShell 7+, pwsh, cmd, xonsh, csh, tcsh, Nushell, Elvish, and rc (Plan 9).
+
+## Writing Patterns
+
+- Use `\b` for word boundaries: `\brm\b` matches "rm" but not "storm"
+- Use `^` and `$` to anchor patterns to start/end of input
+- Escape special characters: `\.` for literal dot, `\\` for backslash
+
+<div class="warning">
+
+Test carefully—a typo in a deny pattern blocks legitimate actions.
+You can use the "Test Your Rules" checker, available in each individual tool page, to confirm whether a pattern is correctly falling in the desired condition.
+
+</div>
+
+## Built-in Security Rules
+
+Zed includes a small set of hardcoded security rules that **cannot be overridden** by any setting.
+These only apply to the **terminal** tool and block recursive deletion of critical directories:
+
+- `rm -rf /` and `rm -rf /*` — filesystem root
+- `rm -rf ~` and `rm -rf ~/*` — home directory
+- `rm -rf $HOME` / `rm -rf ${HOME}` (and `$HOME/*`) — home directory via environment variable
+- `rm -rf .` and `rm -rf ./*` — current directory
+- `rm -rf ..` and `rm -rf ../*` — parent directory
+
+These patterns catch any flag combination (e.g., `-fr`, `-rfv`, `-r -f`, `--recursive --force`) and are case-insensitive.
+They are checked against both the raw command and each parsed sub-command in chained commands (e.g., `ls && rm -rf /`).
+
+There are no other built-in rules.
+The default settings file ({#action zed::OpenDefaultSettings}) includes commented-out examples for protecting `.env` files, secrets directories, and private keys — you can uncomment or adapt these to suit your needs.
+
+## Permission Request in the UI
+
+When the agent requests permission, you'll see in the thread view a tool card with a menu that includes:
+
+- **Allow once** / **Deny once** — One-time decision
+- **Always for <tool>** — Sets a tool-level default to allow or deny
+- **Always for <pattern>** — Adds an `always_allow` or `always_deny` pattern (when a safe pattern can be extracted)
+
+Selecting "Always for <tool>" sets `tools.<tool>.default` to allow or deny.
+When a pattern can be safely extracted, selecting "Always for <pattern>" adds an `always_allow` or `always_deny` rule for that input.
+MCP tools only support the tool-level option.
+
+## Examples
+
+### Terminal: Auto-Approve Build Commands
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "tools": {
+        "terminal": {
+          "default": "confirm",
+          "always_allow": [
+            { "pattern": "^cargo\\s+(build|test|check|clippy|fmt)" },
+            { "pattern": "^npm\\s+(install|test|run|build)" },
+            { "pattern": "^git\\s+(status|log|diff|branch)" },
+            { "pattern": "^ls\\b" },
+            { "pattern": "^cat\\s" }
+          ],
+          "always_deny": [
+            { "pattern": "rm\\s+-rf\\s+(/|~)" },
+            { "pattern": "sudo\\s+rm" }
+          ],
+          "always_confirm": [
+            { "pattern": "sudo\\s" },
+            { "pattern": "git\\s+push" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+### File Editing: Protect Sensitive Files
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "tools": {
+        "edit_file": {
+          "default": "confirm",
+          "always_allow": [
+            { "pattern": "\\.(md|txt|json)$" },
+            { "pattern": "^src/" }
+          ],
+          "always_deny": [
+            { "pattern": "\\.env" },
+            { "pattern": "secrets?/" },
+            { "pattern": "\\.(pem|key)$" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+### Path Deletion: Block Critical Directories
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "tools": {
+        "delete_path": {
+          "default": "confirm",
+          "always_deny": [
+            { "pattern": "^/etc" },
+            { "pattern": "^/usr" },
+            { "pattern": "\\.git/?$" },
+            { "pattern": "node_modules/?$" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+### URL Fetching: Control External Access
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "tools": {
+        "fetch": {
+          "default": "confirm",
+          "always_allow": [
+            { "pattern": "docs\\.rs" },
+            { "pattern": "github\\.com" }
+          ],
+          "always_deny": [{ "pattern": "internal\\.company\\.com" }]
+        }
+      }
+    }
+  }
+}
+```
+
+### MCP Tools
+
+```json [settings]
+{
+  "agent": {
+    "tool_permissions": {
+      "tools": {
+        "mcp:github:create_issue": {
+          "default": "confirm"
+        },
+        "mcp:github:create_pull_request": {
+          "default": "confirm"
+        }
+      }
+    }
+  }
+}
+```

docs/src/ai/tools.md

@@ -0,0 +1,96 @@
+---
+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
+
+### `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.
+
+**Example:** After editing `src/parser.rs`, call `diagnostics` with that path to check for type errors immediately. After a larger refactor touching many files, call it without a path to see a project-wide count of errors before deciding what to fix next.
+
+### `fetch`
+
+Fetches a URL and returns the content as Markdown. Useful for providing docs as context.
+
+**Example:** Fetching a library's changelog page to check whether a breaking API change was introduced in a recent version before writing integration code.
+
+### `find_path`
+
+Quickly finds files by matching glob patterns (like "\*_/_.js"), returning matching file paths alphabetically.
+
+### `grep`
+
+Searches file contents across the project using regular expressions, preferred for finding symbols in code without knowing exact file paths.
+
+**Example:** To find every call site of a function before renaming it, search for `parse_config\(` — the regex matches the function name followed by an opening parenthesis, filtering out comments or variable names that happen to contain the string.
+
+### `list_directory`
+
+Lists files and directories in a given path, providing an overview of filesystem contents.
+
+### `read_file`
+
+Reads the content of a specified file in the project, allowing access to file contents.
+
+### `search_web`
+
+Searches the web for information, providing results with snippets and links from relevant web pages, useful for accessing real-time information.
+
+**Example:** Looking up whether a known bug in a dependency has been patched in a recent release, or finding the current API signature for a third-party library when the local docs are out of date.
+
+> **Note:** The built-in `search_web` tool is only available to [Zed Pro](https://zed.dev/pricing) subscribers using the Zed provider. If you're on a free plan or using a different provider, you can get equivalent functionality by connecting an MCP server that provides web search capabilities. See [MCP servers](./mcp.md) for details.
+
+## Edit Tools
+
+### `copy_path`
+
+Copies a file or directory recursively in the project, more efficient than manually reading and writing files when duplicating content.
+
+### `create_directory`
+
+Creates a new directory at the specified path within the project, creating all necessary parent directories (similar to `mkdir -p`).
+
+### `delete_path`
+
+Deletes a file or directory (including contents recursively) at the specified path and confirms the deletion.
+
+### `edit_file`
+
+Edits files by replacing specific text with new content.
+
+**Example:** Updating a function signature — the agent identifies the exact lines to replace and provides the updated version, leaving the surrounding code untouched. For widespread renames, it pairs this with `grep` to find every occurrence first.
+
+### `move_path`
+
+Moves or renames a file or directory in the project, performing a rename if only the filename differs.
+
+### `write_file`
+
+Creates a new file or overwrites an existing file with completely new contents.
+
+### `terminal`
+
+Executes shell commands and returns the combined output, creating a new shell process for each invocation.
+
+**Example:** After editing a Rust file, run `cargo test --package my_crate 2>&1 | tail -30` to confirm the changes don't break existing tests. Or run `git diff --stat` to review which files have been modified before wrapping up a task.
+
+## Other Tools
+
+### `spawn_agent`
+
+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.
+
+**Example:** While refactoring the authentication module, spawn a subagent to investigate how session tokens are validated elsewhere in the codebase. The parent agent continues its work and reviews the subagent's findings when it completes — keeping both context windows focused on a single task.

docs/src/all-actions.md

@@ -0,0 +1,8 @@
+---
+title: All Actions
+description: "Complete reference of all available actions and commands in Zed."
+---
+
+# All Actions
+
+{#ACTIONS_TABLE#}

docs/src/appearance.md

@@ -0,0 +1,128 @@
+---
+title: Appearance and Visual Customization - Zed
+description: Customize Zed's themes, fonts, icons, UI density, and other visual settings to match your preferences.
+---
+
+# Appearance
+
+Customize Zed's visual appearance to match your preferences. This guide covers themes, fonts, icons, and other visual settings.
+
+For information on how the settings system works, see [All Settings](./reference/all-settings.md).
+
+## Customize Zed in 5 Minutes
+
+Here's how to make Zed feel like home:
+
+1. **Pick a theme**: Press {#kb theme_selector::Toggle} to open the Theme Selector. Arrow through the list to preview themes in real time, and press Enter to apply.
+
+2. **Toggle light/dark mode quickly**: Press {#kb theme::ToggleMode}. If you currently use a static `"theme": "..."` value, the first toggle converts it to dynamic mode settings with default themes.
+
+3. **Choose an icon theme**: Run {#action icon_theme_selector::Toggle} from the command palette to browse icon themes.
+
+4. **Set your font**: Open the Settings Editor with {#kb zed::OpenSettings} and search for `buffer_font_family`. Set it to your preferred coding font.
+
+5. **Adjust font size**: In the same Settings Editor, search for `buffer_font_size` and `ui_font_size` to tweak the editor and interface text sizes.
+
+That's it. You now have a personalized Zed setup.
+
+## Themes
+
+Install themes from the Extensions page ({#action zed::Extensions}), then switch between them with the Theme Selector ({#kb theme_selector::Toggle}).
+
+Zed supports separate themes for light and dark mode with automatic switching based on your system preference:
+
+```json [settings]
+{
+  "theme": {
+    "mode": "system",
+    "light": "One Light",
+    "dark": "One Dark"
+  }
+}
+```
+
+You can also override specific theme attributes for fine-grained control.
+
+→ [Themes documentation](./themes.md)
+
+## Icon Themes
+
+Customize file and folder icons in the Project Panel and tabs. Browse available icon themes with the Icon Theme Selector ({#action icon_theme_selector::Toggle} in the command palette).
+
+Like color themes, icon themes support separate light and dark variants:
+
+```json [settings]
+{
+  "icon_theme": {
+    "mode": "system",
+    "light": "Zed (Default)",
+    "dark": "Zed (Default)"
+  }
+}
+```
+
+→ [Icon Themes documentation](./icon-themes.md)
+
+## Fonts
+
+Zed uses three font settings for different contexts:
+
+| Setting                | Used for                  |
+| ---------------------- | ------------------------- |
+| `buffer_font_family`   | Editor text               |
+| `ui_font_family`       | Interface elements        |
+| `terminal.font_family` | [Terminal](./terminal.md) |
+
+Example configuration:
+
+```json [settings]
+{
+  "buffer_font_family": "JetBrains Mono",
+  "buffer_font_size": 14,
+  "ui_font_family": "Inter",
+  "ui_font_size": 16,
+  "terminal": {
+    "font_family": "JetBrains Mono",
+    "font_size": 14
+  }
+}
+```
+
+### Font Ligatures
+
+To disable font ligatures:
+
+```json [settings]
+{
+  "buffer_font_features": {
+    "calt": false
+  }
+}
+```
+
+### Line Height
+
+Adjust line spacing with `buffer_line_height`:
+
+- `"comfortable"` — 1.618 ratio (default)
+- `"standard"` — 1.3 ratio
+- `{ "custom": 1.5 }` — Custom ratio
+
+## UI Elements
+
+Zed provides extensive control over UI elements including:
+
+- **Tab bar** — Show/hide, navigation buttons, file icons, git status
+- **Status bar** — Language selector, cursor position, line endings
+- **Scrollbar** — Visibility, git diff indicators, search results
+- **Minimap** — Code overview display
+- **Gutter** — Line numbers, fold indicators, breakpoints
+- **Panels** — Project Panel, Terminal, Agent Panel sizing and docking
+
+→ [Visual Customization documentation](./visual-customization.md) for all UI element settings
+
+## What's Next
+
+- [All Settings](./reference/all-settings.md) — Complete settings reference
+- [Key bindings](./key-bindings.md) — Customize keyboard shortcuts
+- [Vim Mode](./vim.md) — Enable modal editing

docs/src/authentication.md

@@ -0,0 +1,42 @@
+---
+title: Authenticate with Zed
+description: "Sign in to Zed to access collaboration features and AI services."
+---
+
+# Authenticate with Zed
+
+Signing in to Zed is not required. You can use most features you'd expect in a code editor without ever doing so. We'll outline the few features that do require signing in, and how to do so, here.
+
+## What Features Require Signing In?
+
+1. All real-time [collaboration features](./collaboration/overview.md).
+2. [LLM-powered features](./ai/overview.md), if you are using Zed as the provider of your LLM models. To use AI without signing in, you can [bring and configure your own API keys](./ai/llm-providers.md#use-your-own-keys).
+
+## Signing In
+
+Zed uses GitHub's OAuth flow to authenticate users, requiring only the `read:user` GitHub scope, which grants read-only access to your GitHub profile information.
+
+1. Open Zed and click the `Sign In` button in the top-right corner of the window, or run the {#action client::SignIn} command from the command palette (`cmd-shift-p` on macOS or `ctrl-shift-p` on Windows/Linux).
+2. Your default web browser will open to the Zed sign-in page.
+3. Authenticate with your GitHub account when prompted.
+4. After successful authentication, your browser will display a confirmation, and you'll be automatically signed in to Zed.
+
+**Note**: If you're behind a corporate firewall, ensure that connections to `zed.dev` and `collab.zed.dev` are allowed.
+
+## Signing Out
+
+To sign out of Zed, you can use either of these methods:
+
+- Click on the profile icon in the upper right corner and select `Sign Out` from the dropdown menu.
+- Open the command palette and run the {#action client::SignOut} command.
+
+## Email Addresses {#email}
+
+Your Zed account's email address is the address provided by GitHub OAuth. If you have a public email address then it will be used, otherwise your primary GitHub email address will be used. Changes to your email address on GitHub can be synced to your Zed account by [signing in to zed.dev](https://zed.dev/sign_in).
+
+Stripe is used for billing, and will use your Zed account's email address when starting a subscription. Changes to your Zed account email address do not currently update the email address used in Stripe. See [Updating Billing Information](./ai/billing.md#updating-billing-info) for how to change this email address.
+
+## Hiding Sign In button from the interface
+
+In case the Sign In feature is not used, it's possible to hide that from the interface by using `show_sign_in` settings property.
+Refer to [Visual Customization page](./visual-customization.md) for more details.

docs/src/business/admin-controls.md

@@ -0,0 +1,43 @@
+---
+title: Admin Controls - Zed Business
+description: Configure AI, collaboration, and data sharing settings for your entire Zed Business organization.
+---
+
+# Admin Controls
+
+Owners and admins can configure settings that apply to every member of the organization.
+
+Most controls apply server-side to anything that routes through Zed's infrastructure. Some, like the Collaboration toggle, are enforced client-side and require members to be on a minimum Zed version. These controls don't cover [bring-your-own-key (BYOK) configurations](../ai/llm-providers.md), [external agents](../ai/external-agents.md), or [third-party extensions](../extensions.md), since those work independently of Zed's servers.
+
+## Accessing admin controls
+
+Admin controls are available to owners and admins in the organization dashboard at [dashboard.zed.dev](https://dashboard.zed.dev). Navigate to your organization, then select Data & Privacy from the sidebar to configure these settings.
+
+---
+
+## Collaboration
+
+The **Collaboration** toggle controls whether members can use Zed's real-time collaboration features, including [Channels](../collaboration/channels.md), shared projects, and voice chat. Collaboration is off by default for Business organizations.
+
+This control is configured from the Data & Privacy page in the organization dashboard. It is enforced client-side and requires members to be on Zed **0.233 or later**. Members on older versions will not have the setting enforced.
+
+## Hosted AI models
+
+The **Zed Model Provider** toggle controls whether members can use Zed's [hosted AI models](../ai/models.md):
+
+- **On:** Members can use Zed's hosted models for AI features.
+- **Off:** Members must bring their own API keys via [Providers](../ai/llm-providers.md) or use [external agents](../ai/external-agents.md) for AI features.
+
+## Edit Predictions
+
+The **Edit Prediction** toggle controls whether members can use Zed's hosted [Edit Predictions](../ai/edit-prediction.md) via the Zeta model family. Members using third-party providers or local models for edit predictions are not affected.
+
+**Edit Prediction Feedback** controls whether members can submit feedback on edit predictions. This setting is only configurable when Edit Prediction is enabled.
+
+## Agent Thread Feedback
+
+The **Agent Thread Feedback** toggle controls whether members can submit feedback on agent thread responses. When disabled, members cannot rate or provide feedback on AI agent conversations.
+
+## Data sharing
+
+On Free and Pro, [data sharing with Zed for AI improvement](../ai/ai-improvement.md) is opt-in per member. On Business, it's off by default and controlled by the Agent Thread Feedback and Edit Prediction Feedback toggles above.

docs/src/business/business-support.md

@@ -0,0 +1,14 @@
+---
+title: Business Support - Zed Business
+description: How to contact Zed for business inquiries and support.
+---
+
+# Business Support
+
+For billing and business support (account setup, invoices, organization questions), email [billing-support@zed.dev](mailto:billing-support@zed.dev). Business support is prioritized relative to other support channels.
+
+For general questions, email [hi@zed.dev](mailto:hi@zed.dev).
+
+## Open-source issues
+
+Questions and bugs about the Zed editor itself (features, extensions, language support, crashes) go through the main Zed project on [GitHub](https://github.com/zed-industries/zed/issues).

docs/src/business/organizations.md

@@ -0,0 +1,61 @@
+---
+title: Organizations - Zed Business
+description: Create and manage a Zed Business organization, invite members, and control access for your team.
+---
+
+# Organizations
+
+A Zed organization is your team's Zed Business subscription, with members, billing, and admin controls in one place.
+
+## Personal Organizations
+
+Every Zed account gets a personal organization at sign-up. It has its own subscription, billing, and settings, separate from any team you belong to.
+
+Your personal organization always stays active. Joining a Zed Business organization doesn't replace or affect it.
+
+In the Zed editor, an organization menu in the title bar shows your current organization by name. Click it to see all your organizations and switch between them.
+
+## Multiple Organizations
+
+A Zed account can belong to more than one organization at the same time. If you're invited to a second organization while already a member of one, you simply join both. Each organization has its own subscription, billing, and admin controls.
+
+To switch organizations in the dashboard, use the org switcher in the top-left corner. In the Zed editor, click the organization name in the title bar to see all your organizations and move between them.
+
+## Creating an organization
+
+To create an organization, go to [dashboard.zed.dev/create-organization](https://dashboard.zed.dev/create-organization). The person who creates the organization becomes its owner.
+
+If you don't have a payment method on file, you'll be taken through a checkout flow. If one is already on file, that step is skipped. After that, you'll land on an invite page to add your first members.
+
+## Inviting members
+
+Members are invited by email address. When an invite is accepted, the member's Zed account joins the organization and is covered by its subscription.
+
+To invite a member:
+
+1. Go to the Members page in your organization dashboard.
+2. Select **+ Invite Member**.
+3. Enter the member's email address and choose a role.
+4. They'll receive an email with a link to join.
+
+After accepting, they authenticate with their GitHub account and are added to the organization. For details on what each role can do, see [Roles & Permissions](../roles.md).
+
+## Managing members
+
+Owners and admins can manage members from the Members page in the dashboard.
+
+### Changing a member's role
+
+1. On the Members page, find the member.
+2. Open the menu and select a new role.
+
+### Removing a member
+
+1. On the Members page, find the member.
+2. Select **Remove** and confirm.
+
+Removing a member ends their access to the organization's subscription and admin-managed settings. Their personal Zed account and any other organization memberships are unaffected.
+
+## Organization Dashboard
+
+The dashboard shows your members, roles, and billing. Owners and admins have full access; members have no dashboard access.

docs/src/business/overview.md

@@ -0,0 +1,41 @@
+---
+title: Zed Business
+description: Zed Business gives every team member full Zed Pro access, with org-wide admin controls and enforced data settings for the whole organization.
+---
+
+# Zed Business
+
+Zed Business is Zed for your whole team. Every member gets access to Zed's hosted AI models and unlimited Edit Predictions, and administrators get controls to manage how Zed is used across the organization: which AI features are available, what data leaves your environment, and how AI spend is tracked.
+
+It's for teams that want modern AI tooling without security trade-offs, and for companies with procurement or compliance requirements that have blocked Zed deployment.
+
+## What's included
+
+Every member gets access to all [hosted AI models](../ai/models.md) and [Edit Predictions](../ai/edit-prediction.md).
+
+For the organization:
+
+- **Enforced data controls:** Administrators configure AI and data settings for
+  the whole organization from the Data & Privacy dashboard. Controls include the
+  [Zed Model Provider](./admin-controls.md#hosted-ai-models),
+  [Edit Predictions](./admin-controls.md#edit-predictions),
+  [Edit Prediction Feedback](./admin-controls.md#edit-predictions), and
+  [Agent Thread Feedback](./admin-controls.md#agent-thread-feedback). Members
+  can't override these settings individually.
+- **Private by default:** Zed doesn't store your prompts or train on them
+  without explicit opt-in.
+  [Data sharing for AI improvement](../ai/ai-improvement.md) is opt-in: members
+  can choose to share but are never enrolled automatically. Administrators can
+  [enforce this org-wide](./admin-controls.md#data-sharing), blocking members
+  from opting in at all.
+- **[Roles and permissions](../roles.md):** Owners, admins, and members have
+  different access levels. Billing and org settings are only visible to the
+  roles that need them.
+- **Consolidated billing:** Your team's licenses and AI usage appear on
+  [one invoice](../ai/billing.md#organization), with no separate bills per member.
+
+## Getting started
+
+To set up Zed Business for your team, see [Organizations](./organizations.md).
+
+For pricing, see [Plans & Pricing](../ai/plans-and-usage.md).

docs/src/business/privacy.md

@@ -0,0 +1,54 @@
+---
+title: Privacy for Business - Zed Business
+description: How Zed Business handles data privacy across your organization, including enforced protections for prompts and training data.
+---
+
+# Privacy for Business
+
+Zed Business removes the per-member data-sharing options that Free and Pro
+expose. These protections are on by default for every Business organization.
+Administrators can adjust them from
+[Admin Controls](./admin-controls.md); individual members can't opt in or out.
+
+## What's enforced by default
+
+For all members of a Zed Business organization:
+
+- **No prompt sharing:** Conversations and prompts are never shared with Zed.
+  Members can't opt into
+  [AI feedback via ratings](../ai/ai-improvement.md#ai-feedback-with-ratings).
+  Administrators can enable Agent Thread Feedback to allow this.
+- **No training data sharing:** Code context is never shared with Zed for
+  [Edit Prediction model training](../ai/ai-improvement.md#edit-predictions).
+  Members can't opt in individually. Administrators can enable Edit Prediction
+  Feedback to allow this.
+
+These protections are enforced server-side and apply to all org members.
+
+## How individual plans differ
+
+On Free and Pro, data sharing is opt-in:
+
+- Members can rate AI responses, which shares that conversation with Zed.
+- Members can opt into Edit Prediction training data collection for open source projects.
+
+Neither option is available to Zed Business members.
+
+## What data still leaves the organization
+
+These controls cover what Zed stores and trains on. They don't change how AI inference works: when members use Zed's hosted models, prompts and code context are still sent to the relevant provider (Anthropic, OpenAI, Google, etc.) to generate responses. Zed maintains zero-data retention agreements with these providers. See [AI Improvement](../ai/ai-improvement.md#data-retention-and-training) for details.
+
+[Bring-your-own-key](../ai/llm-providers.md) and [external agents](../ai/external-agents.md) are subject to each provider's own terms; Zed has no visibility into how they handle data.
+
+## Additional admin controls
+
+Administrators have additional options in [Admin Controls](./admin-controls.md):
+
+- Disable Zed-hosted models entirely via the Zed Model Provider toggle, so no
+  prompts reach Zed's infrastructure
+- Disable Edit Predictions org-wide
+- Disable Edit Prediction Feedback
+- Disable Agent Thread Feedback
+- Disable real-time collaboration
+
+See [Admin Controls](./admin-controls.md) for the full list.

docs/src/collaboration/channels.md

@@ -0,0 +1,125 @@
+---
+title: Channels
+description: "Persistent collaboration rooms in Zed for sharing projects, voice chat, and real-time code editing."
+---
+
+# Channels {#channels}
+
+Channels are persistent rooms for team collaboration. Each channel can contain shared projects, voice chat, and collaborative notes.
+
+Channels support:
+
+- Pairing – each collaborator keeps their own screen, mouse, and keyboard.
+- Mentoring – jump into someone else's context and help without asking them to hand over control.
+- Refactoring – multiple people can join the same large refactor in real time.
+- Ambient awareness – see what teammates are working on without status meetings.
+
+Each channel usually maps to an ongoing project or workstream.
+You can see who's in a channel because their avatars appear in the Collaboration Panel.
+
+Create a channel by clicking the `+` icon next to the `Channels` text in the Collaboration Panel.
+Create a subchannel by right-clicking an existing channel and selecting `New Subchannel`.
+
+You can keep both work and side-project channels in the Collaboration Panel.
+
+Joining a channel adds you to a shared room where you can work on projects together.
+
+_Join [our channel tree](https://zed.dev/channel/zed-283) to get an idea of how you can organize yours._
+
+## Inviting People
+
+By default, channels you create can only be accessed by you.
+You can invite collaborators by right-clicking and selecting `Manage members`.
+
+When you have subchannels nested under others, permissions are inherited.
+For instance, adding people to the top-level channel in your channel tree will automatically give them access to its subchannels.
+
+Once you have added someone, they can either join your channel by clicking on it in their Collaboration Panel, or you can share the link to the channel so that they can join directly.
+
+## Voice Chat
+
+You can mute/unmute your microphone via the microphone icon in the upper right-hand side of the window.
+
+> **Note:** When joining a channel, Zed automatically shares your microphone with other users in the call, if your OS allows it. To start muted, use the [`mute_on_join`](../reference/all-settings.md#calls) setting.
+
+## Sharing Projects
+
+After joining a channel, you can share a project over the channel via the `Share` button in the upper right-hand side of the window.
+This will allow channel members to edit the code hosted on your machine as though they had it checked out locally.
+
+When you edit someone else's project, your editor features still work: jump to definition, use AI features, and view diagnostics.
+For pairing, one person can implement while the other reads and validates nearby code.
+Because you keep your own local configuration, the session still feels like your normal setup.
+
+Collaborators can open, edit, and save files, perform searches, and interact with language servers.
+Guests have a read-only view of the project, including access to language server info.
+
+### Unsharing a Project
+
+You can remove a project from a channel by clicking on the `Unshare` button in the title bar.
+
+Collaborators that are currently in that project will be disconnected from the project and will not be able to rejoin it unless you share it again.
+
+## Channel Notes
+
+Each channel has a Markdown notes file associated with it to keep track of current status, new ideas, or to collaborate on building out the design for the feature that you're working on before diving into code.
+
+This works like a shared Markdown document backed by Zed's collaboration service.
+
+Open channel notes by clicking the document icon to the right of the channel name in the Collaboration Panel.
+
+> **Note:** You can view a channel's notes without joining the channel.
+
+## Following Collaborators
+
+To follow a collaborator, click on their avatar in the top left of the title bar.
+You can also cycle through collaborators using {#kb workspace::FollowNextCollaborator} or {#action workspace::FollowNextCollaborator} in the command palette.
+
+When you join a project, you'll immediately start following the collaborator that invited you.
+
+When a pane is following a collaborator, it will:
+
+- follow their cursor and scroll position
+- follow them to other files in the same project
+- instantly swap to viewing their screenshare in that pane, if they are sharing their screen and leave the project
+
+To stop following, simply move your mouse or make an edit via your keyboard.
+
+### How Following Works
+
+Following is confined to a particular pane.
+When a pane is following a collaborator, it is outlined in their cursor color.
+
+Collaborators in the same project appear in color and include a cursor color.
+Collaborators in other projects are shown in gray.
+
+This pane-specific behavior allows you to follow someone in one pane while navigating independently in another and can be an effective layout for some collaboration styles.
+
+### Following a Terminal
+
+Following in terminals is not currently supported the same way it is in the editor.
+As a workaround, collaborators can share their screen and you can follow that instead.
+
+## Screen Sharing
+
+Share your screen with collaborators in the current channel by clicking on the `Share screen` (monitor icon) button in the top right of the title bar.
+If you have multiple displays, you can choose which one to share via the chevron to the right of the monitor icon.
+
+After you've shared your screen, others can click the `Screen` entry under your name in the Collaboration Panel to open a tab that keeps it visible.
+If they are following you, Zed will automatically switch between following your cursor in their Zed instance and your screen share, depending on whether you are focused on Zed or another application, like a web browser.
+
+> **Warning:** Collaborators can see your entire screen when sharing. Stop screen sharing when finished.
+
+## Livestreaming & Guests
+
+A channel can also be made public.
+This allows anyone to join the channel by clicking on the link.
+
+Guest users in channels can hear and see everything that is happening, and have read-only access to projects and channel notes.
+
+If you'd like to invite a guest to participate in a channel for the duration of a call, you can do so by right-clicking them in the Collaboration Panel.
+"Allowing Write Access" will allow them to edit any projects shared into the call, and to use their microphone and share their screen if they wish.
+
+## Leaving a Call
+
+You can leave a channel by clicking on the `Leave call` button in the upper right-hand side of the window.

docs/src/collaboration/contacts-and-private-calls.md

@@ -0,0 +1,29 @@
+---
+title: Contacts and Private Calls
+description: "Add contacts and start private collaboration sessions in Zed."
+---
+
+# Contacts and Private Calls {#contacts}
+
+Private calls provide ad-hoc collaboration sessions outside of channels. Add contacts to your list and start calls with one or more people.
+
+## Adding a Contact
+
+1. In the Collaboration Panel, click the `+` button next to the `Contacts` section
+1. Search for the contact using their GitHub handle.\
+   _Note: Your contact must be an existing Zed user who has completed the GitHub authentication sign-in flow._
+1. Your contact will receive a notification.
+   Once they accept, you'll both appear in each other's contact list.
+
+## Private Calls
+
+To start a private call:
+
+1. Click the `...` menu next to an online contact's name in the Collaboration Panel.
+1. Click `Call <username>`
+
+Once you've begun a private call, you can add other online contacts by clicking their name in the Collaboration Panel.
+
+---
+
+_Private calls work like [channels](./channels.md), without channel-specific features such as channel notes._

docs/src/collaboration/overview.md

@@ -0,0 +1,48 @@
+---
+title: Collaboration
+description: "Real-time collaboration in Zed: share projects, edit code together, and communicate with voice chat."
+---
+
+# Collaboration {#collaboration}
+
+Zed supports real-time multiplayer editing. Multiple people can work in the same project simultaneously, seeing each other's cursors and edits as they happen.
+
+Open the Collaboration Panel with {#kb collab_panel::ToggleFocus}. You'll need to [sign in](../authentication.md#signing-in) to access collaboration features.
+
+## Collaboration Panel {#collaboration-panel}
+
+The Collaboration Panel has two sections:
+
+1. [Channels](./channels.md): Persistent project rooms for team collaboration, with shared projects and voice chat.
+2. [Contacts and Private Calls](./contacts-and-private-calls.md): Your contacts list for ad-hoc private sessions.
+
+> **Warning:** Sharing a project gives collaborators access to your local file system within that project. Only collaborate with people you trust.
+
+See the [Data and Privacy FAQs](https://zed.dev/faq#data-and-privacy) for more details.
+
+## Audio Settings {#audio-settings}
+
+### Selecting Audio Devices
+
+You can select specific input and output audio devices instead of using system defaults. To configure audio devices:
+
+1. Open {#kb zed::OpenSettings}
+2. Navigate to **Collaboration** > **Experimental**
+3. Use the **Output Audio Device** and **Input Audio Device** dropdowns to select your preferred devices
+
+Changes take effect immediately. If you select a device that becomes unavailable, Zed falls back to system defaults.
+
+To test your audio configuration, click **Test Audio** in the same section. This opens a window where you can verify your microphone and speaker work correctly with the selected devices.
+
+**JSON configuration:**
+
+```json [settings]
+{
+  "audio": {
+    "experimental.output_audio_device": "Device Name (device-id)",
+    "experimental.input_audio_device": "Device Name (device-id)"
+  }
+}
+```
+
+Set either value to `null` to use system defaults.

docs/src/command-palette.md

@@ -0,0 +1,14 @@
+---
+title: Command Palette - Zed
+description: Access any Zed action from the command palette. Fuzzy search commands, key bindings, and editor actions.
+---
+
+# Command Palette
+
+The Command Palette is the main way to access actions in Zed. Its keybinding is one of the first shortcuts to learn: {#kb command_palette::Toggle}.
+
+![The opened Command Palette](https://zed.dev/img/features/command-palette.jpg)
+
+To try it, open the Command Palette and type `new file`. The command list should narrow to {#action workspace::NewFile}. Press Return to create a new buffer.
+
+Any time you see instructions that include commands of the form `zed: ...` or `editor: ...` and so on that means you need to execute them in the Command Palette.

docs/src/completions.md

@@ -0,0 +1,37 @@
+---
+title: Code Completions - Zed
+description: Zed's code completions from language servers and edit predictions. Configure autocomplete behavior, snippets, and documentation display.
+---
+
+# Completions
+
+Zed supports two sources for completions:
+
+1. "Code Completions" provided by Language Servers (LSPs) automatically installed by Zed or via [Zed Language Extensions](languages.md).
+2. "Edit Predictions" provided by Zed's own Zeta model or by external providers like [GitHub Copilot](#github-copilot).
+
+## Language Server Code Completions {#code-completions}
+
+When there is an appropriate language server available, Zed will provide completions of variable names, functions, and other symbols in the current file. You can disable these by adding the following to your Zed `settings.json` file:
+
+```json [settings]
+"show_completions_on_input": false
+```
+
+You can manually trigger completions with `ctrl-space` or by triggering the `editor::ShowCompletions` action from the command palette.
+
+> Note: Using `ctrl-space` in Zed requires disabling the macOS global shortcut.
+> Open **System Settings** > **Keyboard** > **Keyboard Shortcut**s >
+> **Input Sources** and uncheck **Select the previous input source**.
+
+For more information, see:
+
+- [Configuring Supported Languages](./configuring-languages.md)
+- [List of Zed Supported Languages](./languages.md)
+
+## Edit Predictions {#edit-predictions}
+
+Zed has built-in support for predicting multiple edits at a time [via Zeta](https://huggingface.co/zed-industries/zeta), Zed's open-source and open-data model.
+Edit predictions appear as you type, and most of the time, you can accept them by pressing `tab`.
+
+See the [edit predictions documentation](./ai/edit-prediction.md) for more information on how to setup and configure Zed's edit predictions.

docs/src/configuring-languages.md

@@ -0,0 +1,521 @@
+---
+title: Language Server and Tree-sitter Config - Zed
+description: Configure language support in Zed with Tree-sitter for syntax highlighting and LSP for diagnostics, completion, and formatting.
+---
+
+# Configuring Supported Languages
+
+Zed's language support is built on two technologies:
+
+1. **Tree-sitter** handles syntax highlighting and structure-based features like the outline panel.
+2. **Language Server Protocol (LSP)** provides semantic features: code completion, diagnostics, go-to-definition, and refactoring.
+
+This page covers language-specific settings, file associations, language server configuration, formatting, linting, and syntax highlighting.
+
+For a list of supported languages, see [Supported Languages](./languages.md). To add support for new languages, see [Language Extensions](./extensions/languages.md).
+
+## Language-specific Settings
+
+Zed allows you to override global settings for individual languages. These custom configurations are defined in your `settings.json` file under the `languages` key.
+
+Here's an example of language-specific settings:
+
+```json [settings]
+"languages": {
+  "Python": {
+    "tab_size": 4,
+    "formatter": "language_server",
+    "format_on_save": "on"
+  },
+  "JavaScript": {
+    "tab_size": 2,
+    "formatter": {
+      "external": {
+        "command": "prettier",
+        "arguments": ["--stdin-filepath", "{buffer_path}"]
+      }
+    }
+  }
+}
+```
+
+You can customize a wide range of settings for each language, including:
+
+- [`tab_size`](./reference/all-settings.md#tab-size): The number of spaces for each indentation level
+- [`formatter`](./reference/all-settings.md#formatter): The tool used for code formatting
+- [`format_on_save`](./reference/all-settings.md#format-on-save): Whether to automatically format code when saving
+- [`enable_language_server`](./reference/all-settings.md#enable-language-server): Toggle language server support
+- [`hard_tabs`](./reference/all-settings.md#hard-tabs): Use tabs instead of spaces for indentation
+- [`preferred_line_length`](./reference/all-settings.md#preferred-line-length): The recommended maximum line length
+- [`soft_wrap`](./reference/all-settings.md#soft-wrap): How to wrap long lines of code
+- [`show_completions_on_input`](./reference/all-settings.md#show-completions-on-input): Whether or not to show completions as you type
+- [`show_completion_documentation`](./reference/all-settings.md#show-completion-documentation): Whether to display inline and alongside documentation for items in the completions menu
+- [`colorize_brackets`](./reference/all-settings.md#colorize-brackets): Whether to use tree-sitter bracket queries to detect and colorize the brackets in the editor (also known as "rainbow brackets")
+
+These settings allow you to maintain specific coding styles across different languages and projects.
+
+## File Associations
+
+Zed automatically detects file types based on their extensions, but you can customize these associations to fit your workflow.
+
+To set up custom file associations, use the [`file_types`](./reference/all-settings.md#file-types) setting in your `settings.json`:
+
+```json [settings]
+"file_types": {
+  "C++": ["c"],
+  "TOML": ["MyLockFile"],
+  "Dockerfile": ["Dockerfile*"]
+}
+```
+
+This configuration tells Zed to:
+
+- Treat `.c` files as C++ instead of C
+- Recognize files named "MyLockFile" as TOML
+- Apply Dockerfile syntax to any file starting with "Dockerfile"
+
+You can use glob patterns for more flexible matching, allowing you to handle complex naming conventions in your projects.
+
+## Working with Language Servers
+
+Language servers are a crucial part of Zed's intelligent coding features, providing capabilities like auto-completion, go-to-definition, and real-time error checking.
+
+### What are Language Servers?
+
+Language servers implement the Language Server Protocol (LSP), which standardizes communication between the editor and language-specific tools. This allows Zed to support advanced features for multiple programming languages without implementing each feature separately.
+
+Some key features provided by language servers include:
+
+- Code completion
+- Error checking and diagnostics
+- Code navigation (go to definition, find references)
+- Code actions (Rename, extract method)
+- Hover information
+- Workspace symbol search
+
+### Managing Language Servers
+
+Zed simplifies language server management for users:
+
+1. Automatic Download: When you open a file with a matching file type, Zed automatically downloads the appropriate language server. Zed may prompt you to install an extension for known file types.
+
+2. Storage Location:
+
+   - macOS: `~/Library/Application Support/Zed/languages`
+   - Linux: `$XDG_DATA_HOME/zed/languages`, `$FLATPAK_XDG_DATA_HOME/zed/languages`, or `$HOME/.local/share/zed/languages`
+
+3. Automatic Updates: Zed keeps your language servers up-to-date, ensuring you always have the latest features and improvements.
+
+### Choosing Language Servers
+
+Some languages in Zed offer multiple language server options. You might have multiple extensions installed that bundle language servers targeting the same language, potentially leading to overlapping capabilities. To ensure you get the functionality you prefer, Zed allows you to prioritize which language servers are used and in what order.
+
+You can specify your preference using the `language_servers` setting:
+
+```json [settings]
+  "languages": {
+    "PHP": {
+      "language_servers": ["intelephense", "!phpactor", "!phptools", "..."]
+    }
+  }
+```
+
+In this example:
+
+- `intelephense` is set as the primary language server.
+- `phpactor` and `phptools` are disabled (note the `!` prefix).
+- `"..."` expands to the rest of the language servers registered for PHP that are not already listed.
+
+The `"..."` entry acts as a wildcard that includes any registered language server you haven't explicitly mentioned. Servers you list by name keep their position, and `"..."` fills in the remaining ones at that point in the list. Servers prefixed with `!` are excluded entirely. This means that if a new language server extension is installed or a new server is registered for a language, `"..."` will automatically include it. If you want full control over which servers are enabled, omit `"..."` — only the servers you list by name will be used.
+
+#### Examples
+
+Suppose you're working with Ruby. The default configuration is:
+
+```json [settings]
+{
+  "language_servers": [
+    "solargraph",
+    "!ruby-lsp",
+    "!rubocop",
+    "!sorbet",
+    "!steep",
+    "!kanayago",
+    "..."
+  ]
+}
+```
+
+When you override `language_servers` in your settings, your list **replaces** the default entirely. This means default-disabled servers like `kanayago` will be re-enabled by `"..."` unless you explicitly disable them again.
+
+| Configuration                                     | Result                                                             |
+| ------------------------------------------------- | ------------------------------------------------------------------ |
+| `["..."]`                                         | `solargraph`, `ruby-lsp`, `rubocop`, `sorbet`, `steep`, `kanayago` |
+| `["ruby-lsp", "..."]`                             | `ruby-lsp`, `solargraph`, `rubocop`, `sorbet`, `steep`, `kanayago` |
+| `["ruby-lsp", "!solargraph", "!kanayago", "..."]` | `ruby-lsp`, `rubocop`, `sorbet`, `steep`                           |
+| `["ruby-lsp", "solargraph"]`                      | `ruby-lsp`, `solargraph`                                           |
+
+> Note: In the first example, `"..."` includes `kanayago` even though it is disabled by default. The override replaced the default list, so the `"!kanayago"` entry is no longer present. To keep it disabled, you must include `"!kanayago"` in your configuration.
+
+### Toolchains
+
+Some language servers need to be configured with a current "toolchain", which is an installation of a specific version of a programming language compiler or/and interpreter, which can possibly include a full set of dependencies of a project.
+An example of what Zed considers a toolchain is a virtual environment in Python.
+Not all languages in Zed support toolchain discovery and selection, but for those that do, you can specify the toolchain from a toolchain picker (via {#action toolchain::Select}). To learn more about toolchains in Zed, see [`toolchains`](./toolchains.md).
+
+### Configuring Language Servers
+
+When configuring language servers in your `settings.json`, autocomplete suggestions include all available LSP adapters recognized by Zed, not only those currently active for loaded languages. This helps you discover and configure language servers before opening files that use them.
+
+Many language servers accept custom configuration options. You can set these in the `lsp` section of your `settings.json`:
+
+```json [settings]
+  "lsp": {
+    "rust-analyzer": {
+      "initialization_options": {
+        "check": {
+          "command": "clippy"
+        }
+      }
+    }
+  }
+```
+
+This example configures the Rust Analyzer to use Clippy for additional linting when saving files.
+
+#### Nested objects
+
+When configuring language server options in Zed, it's important to use nested objects rather than dot-delimited strings. This is particularly relevant when working with more complex configurations. Let's look at a real-world example using the TypeScript language server:
+
+Suppose you want to configure the following settings for TypeScript:
+
+- Enable strict null checks
+- Set the target ECMAScript version to ES2020
+
+Here's how you would structure these settings in Zed's `settings.json`:
+
+```json [settings]
+"lsp": {
+  "typescript-language-server": {
+    "initialization_options": {
+      // These are not supported (VSCode dotted style):
+      // "preferences.strictNullChecks": true,
+      // "preferences.target": "ES2020"
+      //
+      // These is correct (nested notation):
+      "preferences": {
+        "strictNullChecks": true,
+        "target": "ES2020"
+      },
+    }
+  }
+}
+```
+
+#### Possible configuration options
+
+Depending on how a particular language server is implemented, they may depend on different configuration options, both specified in the LSP.
+
+- [initializationOptions](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#version_3_17_0)
+
+Sent once during language server startup, requires server's restart to reapply changes.
+
+For example, rust-analyzer and clangd rely on this way of configuring only.
+
+```json [settings]
+  "lsp": {
+    "rust-analyzer": {
+      "initialization_options": {
+        "checkOnSave": false
+      }
+    }
+  }
+```
+
+- [Configuration Request](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_configuration)
+
+May be queried by the server multiple times.
+Most of the servers would rely on this way of configuring only.
+
+```json [settings]
+"lsp": {
+  "tailwindcss-language-server": {
+    "settings": {
+      "tailwindCSS": {
+        "emmetCompletions": true,
+      },
+    }
+  }
+}
+```
+
+Apart of the LSP-related server configuration options, certain servers in Zed allow configuring the way binary is launched by Zed.
+
+Language servers are automatically downloaded or launched if found in your path, if you wish to specify an explicit alternate binary you can specify that in settings:
+
+```json [settings]
+  "lsp": {
+    "rust-analyzer": {
+      "binary": {
+        // Whether to fetch the binary from the internet, or attempt to find locally.
+        "ignore_system_version": false,
+        "path": "/path/to/langserver/bin",
+        "arguments": ["--option", "value"],
+        "env": {
+          "FOO": "BAR"
+        }
+      }
+    }
+  }
+```
+
+### Enabling or Disabling Language Servers
+
+You can toggle language server support globally or per-language:
+
+```json [settings]
+  "languages": {
+    "Markdown": {
+      "enable_language_server": false
+    }
+  }
+```
+
+This disables the language server for Markdown files, which can be useful for performance in large documentation projects. You can configure this globally in your `~/.config/zed/settings.json` or inside a `.zed/settings.json` in your project directory.
+
+## Formatting and Linting
+
+Zed provides support for code formatting and linting to maintain consistent code style and catch potential issues early.
+
+### Configuring Formatters
+
+Zed supports both built-in and external formatters. See [`formatter`](./reference/all-settings.md#formatter) docs for more. You can configure formatters globally or per-language in your `settings.json`:
+
+```json [settings]
+"languages": {
+  "JavaScript": {
+    "formatter": {
+      "external": {
+        "command": "prettier",
+        "arguments": ["--stdin-filepath", "{buffer_path}"]
+      }
+    },
+    "format_on_save": "on"
+  },
+  "Rust": {
+    "formatter": "language_server",
+    "format_on_save": "on"
+  }
+}
+```
+
+This example uses Prettier for JavaScript and the language server's formatter for Rust, both set to format on save.
+
+To disable formatting for a specific language:
+
+```json [settings]
+"languages": {
+  "Markdown": {
+    "format_on_save": "off"
+  }
+}
+```
+
+### Setting Up Linters
+
+Linting in Zed is typically handled by language servers. Many language servers allow you to configure linting rules:
+
+```json [settings]
+"lsp": {
+  "eslint": {
+    "settings": {
+      "codeActionOnSave": {
+        "rules": ["import/order"]
+      }
+    }
+  }
+}
+```
+
+This configuration sets up ESLint to organize imports on save for JavaScript files.
+
+To run linter fixes automatically on save:
+
+```json [settings]
+"languages": {
+  "JavaScript": {
+    "formatter": {
+      "code_action": "source.fixAll.eslint"
+    }
+  }
+}
+```
+
+### Formatting Selections
+
+Zed supports formatting only the selected text via {#action editor::FormatSelections} ({#kb editor::FormatSelections}). How
+this works depends on the configured formatter:
+
+- The action is only shown when the active formatter can actually format ranges for at least one
+  selected buffer.
+- **Language server**: Sends an LSP range formatting request for each selection. This provides the
+  most precise selection-only formatting, and is only available when the configured language server
+  advertises range-formatting support.
+- **Prettier**: Uses Prettier's built-in range formatting to format the encompassing range of all selections. Any
+  resulting edits that fall outside the selected ranges are discarded, so only the selected code is modified.
+- **External commands**: External command formatters do not support range formatting and are skipped when formatting
+  selections.
+- **Code action formatters**: Code actions operate on the whole buffer, so they do not enable
+  `format selections` on their own.
+
+### Integrating Formatting and Linting
+
+Zed allows you to run both formatting and linting on save. Here's an example that uses Prettier for formatting and ESLint for linting JavaScript files:
+
+```json [settings]
+"languages": {
+  "JavaScript": {
+    "formatter": [
+      {
+        "code_action": "source.fixAll.eslint"
+      },
+      {
+        "external": {
+          "command": "prettier",
+          "arguments": ["--stdin-filepath", "{buffer_path}"]
+        }
+      }
+    ],
+    "format_on_save": "on"
+  }
+}
+```
+
+### Troubleshooting
+
+If you encounter issues with formatting or linting:
+
+1. Check Zed's log file for error messages (Use the command palette: {#action zed::OpenLog})
+2. Ensure external tools (formatters, linters) are correctly installed and in your PATH
+3. Verify configurations in both Zed settings and language-specific config files (e.g., `.eslintrc`, `.prettierrc`)
+
+## Syntax Highlighting and Themes
+
+Zed offers customization options for syntax highlighting and themes, allowing you to tailor the visual appearance of your code.
+
+### Customizing Syntax Highlighting
+
+Zed uses Tree-sitter grammars for syntax highlighting. Override the default highlighting using the `theme_overrides` setting.
+
+This example makes comments italic and changes the color of strings:
+
+```json [settings]
+"theme_overrides": {
+  "One Dark": {
+    "syntax": {
+      "comment": {
+        "font_style": "italic"
+      },
+      "string": {
+        "color": "#00AA00"
+      }
+    }
+  }
+}
+```
+
+### Selecting and Customizing Themes
+
+Change your theme:
+
+1. Use the theme selector ({#kb theme_selector::Toggle})
+2. Or set it in your `settings.json`:
+
+```json [settings]
+"theme": {
+  "mode": "dark",
+  "dark": "One Dark",
+  "light": "GitHub Light"
+}
+```
+
+Create custom themes by creating a JSON file in `~/.config/zed/themes/`. Zed will automatically detect and make available any themes in this directory.
+
+### Using Theme Extensions
+
+Zed supports theme extensions. Browse and install theme extensions from the Extensions panel ({#kb zed::Extensions}).
+
+To create your own theme extension, refer to the [Developing Theme Extensions](./extensions/themes.md) guide.
+
+## Using Language Server Features
+
+### Semantic Tokens
+
+Semantic tokens provide richer syntax highlighting by using type and scope information from language servers. Enable them with the `semantic_tokens` setting:
+
+```json [settings]
+"semantic_tokens": "combined"
+```
+
+- `"off"` — Tree-sitter highlighting only (default)
+- `"combined"` — LSP semantic tokens overlaid on tree-sitter
+- `"full"` — LSP semantic tokens replace tree-sitter entirely
+
+You can customize token colors and styles through `global_lsp_settings.semantic_token_rules` in your settings.
+
+→ [Semantic Tokens documentation](./semantic-tokens.md)
+
+### Inlay Hints
+
+Inlay hints provide additional information inline in your code, such as parameter names or inferred types. Configure inlay hints in your `settings.json`:
+
+```json [settings]
+"inlay_hints": {
+  "enabled": true,
+  "show_type_hints": true,
+  "show_parameter_hints": true,
+  "show_other_hints": true
+}
+```
+
+For language-specific inlay hint settings, refer to the documentation for each language.
+
+### Code Actions
+
+Code actions provide quick fixes and refactoring options. Access code actions using the {#action editor::ToggleCodeActions} command or by clicking the lightbulb icon that appears next to your cursor when actions are available.
+
+### Go To Definition and References
+
+Use these commands to navigate your codebase:
+
+- {#action editor::GoToDefinition} (<kbd>f12|f12</kbd>)
+- {#action editor::GoToTypeDefinition} (<kbd>cmd-f12|ctrl-f12</kbd>)
+- {#action editor::FindAllReferences} (<kbd>shift-f12|shift-f12</kbd>)
+
+### Rename Symbol
+
+To rename a symbol across your project:
+
+1. Place your cursor on the symbol
+2. Use the {#action editor::Rename} command (<kbd>f2|f2</kbd>)
+3. Enter the new name and press Enter
+
+These features depend on the capabilities of the language server for each language.
+
+When renaming a symbol that spans multiple files, Zed will open a preview in a multibuffer. This allows you to review all the changes across your project before applying them. To confirm the rename, simply save the multibuffer. If you decide not to proceed with the rename, you can undo the changes or close the multibuffer without saving.
+
+### Hover Information
+
+Use the {#action editor::Hover} command to display information about the symbol under the cursor. This often includes type information, documentation, and links to relevant resources.
+
+### Workspace Symbol Search
+
+The {#action project_symbols::Toggle} command allows you to search for symbols (functions, classes, variables) across your entire project. This is useful for quickly navigating large codebases.
+
+### Code Completion
+
+Zed provides intelligent code completion suggestions as you type. You can manually trigger completion with the {#action editor::ShowCompletions} command. Use <kbd>tab|tab</kbd> or <kbd>enter|enter</kbd> to accept suggestions.
+
+### Diagnostics
+
+Language servers provide real-time diagnostics (errors, warnings, hints) as you code. View all diagnostics for your project using the {#action diagnostics::Deploy} command.

docs/src/configuring-zed.md

@@ -0,0 +1,146 @@
+---
+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
+
+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 {#action zed::OpenSettings} 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
+
+### User Settings
+
+Your user settings apply globally across all projects. Open the file with {#kb zed::OpenSettingsFile} or run {#action zed::OpenSettingsFile} 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
+
+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
+
+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.
+
+**Limitation:** 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
+
+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-file Settings
+
+Zed has some compatibility support for Emacs and Vim [modelines](./modelines.md), so you can set some settings per-file.
+
+## Per-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
+
+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
+
+```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
+    }
+  }
+}
+```
+
+## What's Next
+
+- [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

docs/src/debugger.md

@@ -0,0 +1,383 @@
+---
+title: Debugger - Zed
+description: Debug code in Zed with the Debug Adapter Protocol (DAP). Breakpoints, stepping, variable inspection across multiple languages.
+---
+
+# Debugger
+
+Zed uses the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) to provide debugging functionality across multiple programming languages.
+DAP is a standardized protocol that defines how debuggers, editors, and IDEs communicate with each other.
+It allows Zed to support various debuggers without needing to implement language-specific debugging logic.
+Zed implements the client side of the protocol, and various _debug adapters_ implement the server side.
+
+This protocol enables features like setting breakpoints, stepping through code, inspecting variables,
+and more, in a consistent manner across different programming languages and runtime environments.
+
+## Supported Languages
+
+To debug code written in a specific language, Zed needs to find a debug adapter for that language. Some debug adapters are provided by Zed without additional setup, and some are provided by [language extensions](./extensions/debugger-extensions.md). The following languages currently have debug adapters available:
+
+<!-- keep this sorted -->
+
+- [C](./languages/c.md#debugging) (built-in)
+- [C++](./languages/cpp.md#debugging) (built-in)
+- [Go](./languages/go.md#debugging) (built-in)
+- [Java](./languages/java.md#debugging) (provided by extension)
+- [JavaScript](./languages/javascript.md#debugging) (built-in)
+- [PHP](./languages/php.md#debugging) (built-in)
+- [Python](./languages/python.md#debugging) (built-in)
+- [Ruby](./languages/ruby.md#debugging) (provided by extension)
+- [Rust](./languages/rust.md#debugging) (built-in)
+- [Swift](./languages/swift.md#debugging) (provided by extension)
+- [TypeScript](./languages/typescript.md#debugging) (built-in)
+
+> If your language isn't listed, you can contribute by adding a debug adapter for it. Check out our [debugger extensions](./extensions/debugger-extensions.md) documentation for more information.
+
+Follow those links for language- and adapter-specific information and examples, or read on for more about Zed's general debugging features that apply to all adapters.
+
+## Getting Started
+
+For most languages, the fastest way to get started is to run {#action debugger::Start} ({#kb debugger::Start}). This opens the _new process modal_, which shows you a contextual list of preconfigured debug tasks for the current project. Debug tasks are created from tests, entry points (like a `main` function), and from other sources — consult the documentation for your language for full information about what's supported.
+
+You can open the same modal by clicking the "plus" button at the top right of the debug panel.
+
+For languages that don't provide preconfigured debug tasks (this includes C, C++, and some extension-supported languages), you can define debug configurations in the `.zed/debug.json` file in your project root. This file should be an array of configuration objects:
+
+```json [debug]
+[
+  {
+    "adapter": "CodeLLDB",
+    "label": "First configuration"
+    // ...
+  },
+  {
+    "adapter": "Debugpy",
+    "label": "Second configuration"
+    // ...
+  }
+]
+```
+
+Check the documentation for your language for example configurations covering typical use-cases. Once you've added configurations to `.zed/debug.json`, they'll appear in the list in the new process modal.
+
+Zed will also load debug configurations from `.vscode/launch.json`, and show them in the new process modal if no configurations are found in `.zed/debug.json`.
+
+#### Global debug configurations
+
+If you run the same launch profiles across multiple projects, you can store them once in your user configuration. Invoke {#action zed::OpenDebugTasks} from the command palette to open the global `debug.json` file; Zed creates it next to your user `settings.json` and keeps it in sync with the debugger UI. The file lives at:
+
+- **macOS:** `~/Library/Application Support/Zed/debug.json`
+- **Linux/BSD:** `$XDG_CONFIG_HOME/zed/debug.json` (falls back to `~/.config/zed/debug.json`)
+- **Windows:** `%APPDATA%\Zed\debug.json`
+
+Populate this file with the same array of objects you would place in `.zed/debug.json`. Any scenarios defined there are merged into every workspace, so your favorite launch presets appear automatically in the "New Debug Session" dialog.
+
+### Launching & Attaching
+
+Zed debugger offers two ways to debug your program; you can either _launch_ a new instance of your program or _attach_ to an existing process.
+Which one you choose depends on what you are trying to achieve.
+
+When launching a new instance, Zed (and the underlying debug adapter) can often do a better job at picking up the debug information compared to attaching to an existing process, since it controls the lifetime of a whole program.
+Running unit tests or a debug build of your application is a good use case for launching.
+
+Compared to launching, attaching to an existing process might seem inferior, but that's far from truth; there are cases where you cannot afford to restart your program, because for example, the bug is not reproducible outside of a production environment or some other circumstances.
+
+## Configuration
+
+Zed requires the `adapter` and `label` fields for all debug tasks. In addition, Zed will use the `build` field to run any necessary setup steps before the debugger starts [(see below)](#build-tasks), and can accept a `tcp_connection` field to connect to an existing process.
+
+All other fields are provided by the debug adapter and can contain [task variables](./tasks.md#variables). Most adapters support `request`, `program`, and `cwd`:
+
+```json [debug]
+[
+  {
+    // The label for the debug configuration and used to identify the debug session inside the debug panel & new process modal
+    "label": "Example Start debugger config",
+    // The debug adapter that Zed should use to debug the program
+    "adapter": "Example adapter name",
+    // Request:
+    //  - launch: Zed will launch the program if specified, or show a debug terminal with the right configuration
+    //  - attach: Zed will attach to a running program to debug it, or when the process_id is not specified, will show a process picker (only supported for node currently)
+    "request": "launch",
+    // The program to debug. This field supports path resolution with ~ or . symbols.
+    "program": "path_to_program",
+    // cwd: defaults to the current working directory of your project ($ZED_WORKTREE_ROOT)
+    "cwd": "$ZED_WORKTREE_ROOT"
+  }
+]
+```
+
+Check your debug adapter's documentation for more information on the fields it supports.
+
+### Build tasks
+
+Zed allows embedding a Zed task in the `build` field that is run before the debugger starts. This is useful for setting up the environment or running any necessary setup steps before the debugger starts.
+
+```json [debug]
+[
+  {
+    "label": "Build Binary",
+    "adapter": "CodeLLDB",
+    "program": "path_to_program",
+    "request": "launch",
+    "build": {
+      "command": "make",
+      "args": ["build", "-j8"]
+    }
+  }
+]
+```
+
+Build tasks can also refer to the existing tasks by unsubstituted label:
+
+```json [debug]
+[
+  {
+    "label": "Build Binary",
+    "adapter": "CodeLLDB",
+    "program": "path_to_program",
+    "request": "launch",
+    "build": "my build task" // Or "my build task for $ZED_FILE"
+  }
+]
+```
+
+### Automatic scenario creation
+
+Given a Zed task, Zed can automatically create a scenario for you. Automatic scenario creation also powers our scenario creation from gutter.
+Automatic scenario creation is currently supported for Rust, Go, Python, JavaScript, and TypeScript.
+
+## Breakpoints
+
+To set a breakpoint, simply click next to the line number in the editor gutter.
+Breakpoints can be tweaked depending on your needs; to access additional options of a given breakpoint, right-click on the breakpoint icon in the gutter and select the desired option.
+At present, you can:
+
+- Add a log to a breakpoint, which will output a log message whenever that breakpoint is hit.
+- Make the breakpoint conditional, which will only stop at the breakpoint when the condition is met. The syntax for conditions is adapter-specific.
+- Add a hit count to a breakpoint, which will only stop at the breakpoint after it's hit a certain number of times.
+- Disable a breakpoint, which will prevent it from being hit while leaving it visible in the gutter.
+
+Some debug adapters (e.g. CodeLLDB and JavaScript) will also _verify_ whether your breakpoints can be hit; breakpoints that cannot be hit are surfaced more prominently in the UI.
+
+All breakpoints enabled for a given project are also listed in "Breakpoints" item in your debugging session UI. From "Breakpoints" item in your UI you can also manage exception breakpoints.
+The debug adapter will then stop whenever an exception of a given kind occurs. Which exception types are supported depends on the debug adapter.
+
+## Working with Split Panes
+
+When debugging with multiple split panes open, Zed shows the active debug line in one pane and preserves your layout in others. If you have the same file open in multiple panes, the debugger picks a pane where the file is already the active tab—it won't switch tabs in panes where the file is inactive.
+
+Once the debugger picks a pane, it continues using that pane for subsequent breakpoints during the session. If you drag the tab with the active debug line to a different split, the debugger tracks the move and uses the new pane.
+
+This ensures the debugger doesn't disrupt your workflow when stepping through code across different files.
+
+## Settings
+
+The settings for the debugger are grouped under the `debugger` key in `settings.json`:
+
+- `dock`: Determines the position of the debug panel in the UI.
+- `stepping_granularity`: Determines the stepping granularity.
+- `save_breakpoints`: Whether the breakpoints should be reused across Zed sessions.
+- `button`: Whether to show the debug button in the status bar.
+- `timeout`: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
+- `log_dap_communications`: Whether to log messages between active debug adapters and Zed.
+- `format_dap_log_messages`: Whether to format DAP messages when adding them to the debug adapter logger.
+
+### Dock
+
+- Description: The position of the debug panel in the UI.
+- Default: `bottom`
+- Setting: debugger.dock
+
+**Options**
+
+1. `left` - The debug panel will be docked to the left side of the UI.
+2. `right` - The debug panel will be docked to the right side of the UI.
+3. `bottom` - The debug panel will be docked to the bottom of the UI.
+
+```json [settings]
+"debugger": {
+  "dock": "bottom"
+},
+```
+
+### Stepping granularity
+
+- Description: The Step granularity that the debugger will use
+- Default: `line`
+- Setting: `debugger.stepping_granularity`
+
+**Options**
+
+1. Statement - The step should allow the program to run until the current statement has finished executing.
+   The meaning of a statement is determined by the adapter and it may be considered equivalent to a line.
+   For example `for(int i = 0; i < 10; i++)` could be considered to have 3 statements `int i = 0`, `i < 10`, and `i++`.
+
+```json [settings]
+{
+  "debugger": {
+    "stepping_granularity": "statement"
+  }
+}
+```
+
+2. Line - The step should allow the program to run until the current source line has executed.
+
+```json [settings]
+{
+  "debugger": {
+    "stepping_granularity": "line"
+  }
+}
+```
+
+3. Instruction - The step should allow one instruction to execute (e.g. one x86 instruction).
+
+```json [settings]
+{
+  "debugger": {
+    "stepping_granularity": "instruction"
+  }
+}
+```
+
+### Save Breakpoints
+
+- Description: Whether the breakpoints should be saved across Zed sessions.
+- Default: `true`
+- Setting: `debugger.save_breakpoints`
+
+**Options**
+
+`boolean` values
+
+```json [settings]
+{
+  "debugger": {
+    "save_breakpoints": true
+  }
+}
+```
+
+### Button
+
+- Description: Whether the button should be displayed in the debugger toolbar.
+- Default: `true`
+- Setting: `debugger.button`
+
+**Options**
+
+`boolean` values
+
+```json [settings]
+{
+  "debugger": {
+    "button": true
+  }
+}
+```
+
+### Timeout
+
+- Description: Time in milliseconds until timeout error when connecting to a TCP debug adapter.
+- Default: `2000`
+- Setting: `debugger.timeout`
+
+**Options**
+
+`integer` values
+
+```json [settings]
+{
+  "debugger": {
+    "timeout": 3000
+  }
+}
+```
+
+### Inline Values
+
+- Description: Whether to enable editor inlay hints showing the values of variables in your code during debugging sessions.
+- Default: `true`
+- Setting: `inlay_hints.show_value_hints`
+
+**Options**
+
+```json [settings]
+{
+  "inlay_hints": {
+    "show_value_hints": false
+  }
+}
+```
+
+Inline value hints can also be toggled from the Editor Controls menu in the editor toolbar.
+
+### Log Dap Communications
+
+- Description: Whether to log messages between active debug adapters and Zed. (Used for DAP development)
+- Default: false
+- Setting: debugger.log_dap_communications
+
+**Options**
+
+`boolean` values
+
+```json [settings]
+{
+  "debugger": {
+    "log_dap_communications": true
+  }
+}
+```
+
+### Format Dap Log Messages
+
+- Description: Whether to format DAP messages when adding them to the debug adapter logger. (Used for DAP development)
+- Default: false
+- Setting: debugger.format_dap_log_messages
+
+**Options**
+
+`boolean` values
+
+```json [settings]
+{
+  "debugger": {
+    "format_dap_log_messages": true
+  }
+}
+```
+
+### Customizing Debug Adapters
+
+- Description: Custom program path and arguments to override how Zed launches a specific debug adapter.
+- Default: Adapter-specific
+- Setting: `dap.$ADAPTER.binary` and `dap.$ADAPTER.args`
+
+You can pass `binary`, `args`, or both. `binary` should be a path to a _debug adapter_ (like `lldb-dap`) not a _debugger_ (like `lldb` itself). The `args` setting overrides any arguments that Zed would otherwise pass to the adapter.
+
+```json [settings]
+{
+  "dap": {
+    "CodeLLDB": {
+      "binary": "/Users/name/bin/lldb-dap",
+      "args": ["--wait-for-debugger"]
+    }
+  }
+}
+```
+
+## Theme
+
+The Debugger supports the following theme options:
+
+- `debugger.accent`: Color used to accent breakpoint & breakpoint-related symbols
+- `editor.debugger_active_line.background`: Background color of active debug line
+
+## Troubleshooting
+
+If you're running into problems with the debugger, please [open a GitHub issue](https://github.com/zed-industries/zed/issues/new?template=04_bug_debugger.yml), providing as much context as possible. There are also some features you can use to gather more information about the problem:
+
+- When you have a session running in the debug panel, you can run the {#action dev::CopyDebugAdapterArguments} action to copy a JSON blob to the clipboard that describes how Zed initialized the session. This is especially useful when the session failed to start, and is great context to add if you open a GitHub issue.
+- You can also use the {#action dev::OpenDebugAdapterLogs} action to see a trace of all of Zed's communications with debug adapters during the most recent debug sessions.

docs/src/dev-containers.md

@@ -0,0 +1,55 @@
+---
+title: Dev Containers - Zed
+description: Open projects in dev containers with Zed. Reproducible development environments using devcontainer.json configuration.
+---
+
+# Dev Containers
+
+Dev Containers provide a consistent, reproducible development environment by defining your project's dependencies, tools, and settings in a container configuration.
+
+If your repository includes a `.devcontainer/devcontainer.json` file, Zed can open a project inside a development container.
+
+## Requirements
+
+- Docker must be installed and available in your `PATH`. Zed requires the `docker` command to be present. If you use Podman, you must alias it to `docker`, e.g. by using a symlink: `sudo ln -s $(which podman) {some_known_path}/docker`.
+- Your project must contain a `.devcontainer/devcontainer.json` directory/file.
+
+## Using Dev Containers in Zed
+
+### Automatic prompt
+
+When you open a project that contains the `.devcontainer/devcontainer.json` directory/file, Zed will display a prompt asking whether to open the project inside the dev container. Choosing "Open in Container" will:
+
+1. Build the dev container image (if needed).
+2. Launch the container.
+3. Reopen the project connected to the container environment.
+
+### Manual open
+
+If you dismiss the prompt or want to reopen the project inside a container later, you can use Zed's command palette to run the "Project: Open Remote" command and select the option to open the project in a dev container.
+Alternatively, you can reach for the Remote Projects modal (through the {#kb projects::OpenRemote} binding) and choose the "Connect Dev Container" option.
+
+## Editing the dev container configuration
+
+If you modify `.devcontainer/devcontainer.json`, Zed does not currently rebuild or reload the container automatically. After changing configuration:
+
+- Stop or kill the existing container manually (e.g., via `docker kill <container>`).
+- Reopen the project in the container.
+
+## Working in a Dev Container
+
+Once connected, Zed operates inside the container environment for tasks, terminals, and language servers.
+Files are linked from your workspace into the container according to the dev container specification.
+
+## Known Limitations
+
+> **Note:** This feature is still in development.
+
+- **Extensions:** Zed does not yet manage extensions separately for container environments. The host's extensions are used as-is.
+- **Port forwarding:** Only the `appPort` field is supported. `forwardPorts` and other advanced port-forwarding features are not implemented.
+- **Configuration changes:** Updates to `devcontainer.json` do not trigger automatic rebuilds or reloads; containers must be manually restarted.
+
+## See also
+
+- [Remote Development](./remote-development.md) for connecting to remote servers over SSH.
+- [Tasks](./tasks.md) for running commands in the integrated terminal.

docs/src/development.md

@@ -0,0 +1,118 @@
+---
+title: Developing Zed
+description: "Guide to building and developing Zed from source."
+---
+
+# Developing Zed
+
+See the platform-specific instructions for building Zed from source:
+
+- [macOS](./development/macos.md)
+- [Linux](./development/linux.md)
+- [Windows](./development/windows.md)
+
+## Keychain access
+
+Zed stores secrets in the system keychain.
+
+However, when running a development build of Zed on macOS (and perhaps other
+platforms) trying to access the keychain results in a lot of keychain prompts
+that require entering your password over and over.
+
+On macOS this is caused by the development build not having a stable identity.
+Even if you choose the "Always Allow" option, the OS will still prompt you for
+your password again the next time something changes in the binary.
+
+This quickly becomes annoying and impedes development speed.
+
+That is why, by default, when running a development build of Zed an alternative
+credential provider is used to bypass the system keychain.
+
+> **Note:** This is **only** the case for development builds. For all non-development
+> release channels the system keychain is always used.
+
+If you need to test something out using the real system keychain in a
+development build, run Zed with the following environment variable set:
+
+```
+ZED_DEVELOPMENT_USE_KEYCHAIN=1
+```
+
+## Performance Measurements
+
+Zed includes a frame time measurement system that can be used to profile how long it takes to render each frame. This is particularly useful when comparing rendering performance between different versions or when optimizing frame rendering code.
+
+### Using ZED_MEASUREMENTS
+
+To enable performance measurements, set the `ZED_MEASUREMENTS` environment variable:
+
+```sh
+export ZED_MEASUREMENTS=1
+```
+
+When enabled, Zed will print frame rendering timing information to stderr, showing how long each frame takes to render.
+
+### Performance Comparison Workflow
+
+Here's a typical workflow for comparing frame rendering performance between different versions:
+
+1. **Enable measurements:**
+
+   ```sh
+   export ZED_MEASUREMENTS=1
+   ```
+
+2. **Test the first version:**
+
+   - Checkout the commit you want to measure
+   - Run Zed in release mode and use it for 5-10 seconds: `cargo run --release &> version-a`
+
+3. **Test the second version:**
+
+   - Checkout another commit you want to compare
+   - Run Zed in release mode and use it for 5-10 seconds: `cargo run --release &> version-b`
+
+4. **Generate comparison:**
+
+   ```sh
+   script/histogram version-a version-b
+   ```
+
+The `script/histogram` tool can accept as many measurement files as you like and will generate a histogram visualization comparing the frame rendering performance data between the provided versions.
+
+### Using `util_macros::perf`
+
+For benchmarking unit tests, annotate them with the `#[perf]` attribute from the `util_macros` crate. Then run `cargo
+perf-test -p $CRATE` to benchmark them. See the rustdoc documentation on `crates/util_macros` and `tooling/perf` for
+in-depth examples and explanations.
+
+## ETW Profiling on Windows
+
+Zed supports performance profiling with Event Tracing for Windows (ETW) to capture detailed performance data, including CPU, GPU, memory, disk, and file I/O activity. Data is saved to an `.etl` file, which can be opened in standard profiling tools for analysis.
+
+ETW recordings may contain personally identifiable or security-sensitive information, such as paths to files and registry keys accessed, as well as process names. Please keep this in mind when sharing traces with others.
+
+### Recording a trace
+
+Open the command palette and run one of the following:
+
+- `zed: record etw trace`: records CPU, GPU, memory, and I/O activity
+- `zed: record etw trace with heap tracing`: includes heap allocation data for the Zed process
+
+Zed will prompt you to choose a save location for the `.etl` file, then request administrator permission. Once granted, recording will begin.
+
+### Saving or canceling
+
+While a trace is recording, open the command palette and run one of the following:
+
+- `zed: save etw trace`: stops recording and saves the trace to disk
+- `zed: cancel etw trace`: stops recording without saving
+
+Recordings automatically save after 60 seconds if not stopped manually.
+
+## Contributor links
+
+- [CONTRIBUTING.md](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md)
+- [Debugging Crashes](./development/debugging-crashes.md)
+- [Code of Conduct](https://zed.dev/code-of-conduct)
+- [Zed Contributor License](https://zed.dev/cla)

docs/src/development/debuggers.md

@@ -0,0 +1,113 @@
+---
+title: Using a debugger
+description: "Guide to using a debugger for Zed development."
+---
+
+# Using a debugger
+
+> This page is not about [configuring Zed's debugger](../debugger.md).
+> It covers how to use a debugger while developing Zed itself.
+
+## Using Zed's built-in debugger
+
+While the Zed project is open you can open the `New Process Modal` and select the `Debug` tab. There you can see two debug configurations to debug Zed with, one for GDB and one for LLDB. Select the configuration you want and Zed will build and launch the binary.
+
+GDB is not supported on Apple Silicon Macs.
+
+## Release build profile considerations
+
+By default, builds using the release profile (the profile used for nightly, preview, and stable) include limited debug info.
+
+This is done by setting the `profile.(release).debug` field in the root `Cargo.toml` field to `"limited"`.
+
+The official documentation for the `debug` field is [here](https://doc.rust-lang.org/cargo/reference/profiles.html#debug).
+In short, `"limited"` strips type-level and variable-level debug info.
+
+In release builds, this reduces binary size. Type-level and variable-level debug info is not required for useful stack traces.
+
+However, this data matters when you are actively debugging. Without it, debuggers cannot resolve local variables, inspect values, or format output with pretty-printers.
+
+To get the full debugger experience on a release build, compile a Zed binary with full debug info.
+
+The simplest way is to use `--config` to override the `debug` field in the root `Cargo.toml` when running `cargo run` or `cargo build`:
+
+```sh
+cargo run --config 'profile.release.debug="full"'
+cargo build --config 'profile.release.debug="full"'
+```
+
+> If you do not want to pass `--config` on every `cargo` command, you can also change the section in the [root `Cargo.toml`](https://github.com/zed-industries/zed/blob/main/Cargo.toml)
+>
+> from
+>
+> ```toml
+> [profile.release]
+> debug = "limited"
+> ```
+>
+> to
+>
+> ```toml
+> [profile.release]
+> debug = "full"
+> ```
+>
+> This makes all invocations of `cargo run --release` or `cargo build --release` compile with full debug info.
+>
+> **Warning:** Do not commit these changes.
+
+## Running Zed with a shell debugger GDB/LLDB
+
+### Background
+
+When you install Rust through rustup (the recommended setup for Zed development; see your platform guide [here](../development.md)), rustup also installs helper scripts for debugging Rust binaries.
+
+These scripts are `rust-gdb` and `rust-lldb`.
+
+You can read more about these scripts [here](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html).
+
+They are wrapper scripts around `gdb` and `lldb` that inject commands and flags for Rust-specific features such as pretty-printers and type info.
+
+To use `rust-gdb` or `rust-lldb`, install `gdb` or `lldb` on your system.
+
+The [linked article](https://michaelwoerister.github.io/2015/03/27/rust-xxdb.html) notes that the minimum supported versions are GDB 7.7 and LLDB 310. In practice, newer versions are usually better.
+
+> **Note**: `rust-gdb` is not installed by default on Windows because `gdb` support there is unstable. Use `rust-lldb` instead.
+
+If you are new to these tools, see the `gdb` docs [here](https://www.gnu.org/software/gdb/) and the `lldb` docs [here](https://lldb.llvm.org/).
+
+### Usage with Zed
+
+After enabling full debug info and building with `cargo build`, run `rust-gdb` or `rust-lldb` against the compiled Zed binary:
+
+```
+rust-gdb target/debug/zed
+rust-lldb target/debug/zed
+```
+
+You can also attach to a running Zed process (for example, one started with `cargo run`):
+
+```
+rust-gdb -p <pid>
+rust-lldb -p <pid>
+```
+
+`<pid>` is the process ID of the Zed instance you want to attach to.
+
+To find the PID, use your system's process tools, such as Task Manager on Windows or Activity Monitor on macOS.
+
+You can also run `ps aux | grep zed` on macOS and Linux, or `Get-Process | Select-Object Id, ProcessName` in PowerShell on Windows.
+
+#### Debugging Panics and Crashes
+
+Debuggers are useful for finding the cause of panics and crashes, including in Zed.
+
+By default, when a process attached to `gdb` or `lldb` hits an exception such as a panic, the debugger stops at that point so you can inspect program state.
+
+The initial stop point is often in Rust standard library panic or exception handling code, so you usually need to walk up the stack to find the root cause.
+
+In `lldb`, use `backtrace` with `frame select`. `gdb` provides equivalent commands.
+
+After the program stops on the exception, you usually cannot continue normal execution. You can still move between stack frames and inspect variables and expressions, which is often enough to identify the crash cause.
+
+You can find additional information on debugging Zed crashes [here](./debugging-crashes.md).

docs/src/development/debugging-crashes.md

@@ -0,0 +1,25 @@
+---
+title: Debugging Crashes
+description: "Guide to debugging crashes for Zed development."
+---
+
+# Debugging Crashes
+
+When Zed panics or crashes, it sends a message to a sidecar process that inspects the editor's memory and creates a [minidump](https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/getting_started_with_breakpad.md#the-minidump-file-format) in `~/Library/Logs/Zed` or `$XDG_DATA_HOME/zed/logs`. You can use this minidump to generate backtraces for all thread stacks.
+
+If telemetry is enabled, Zed uploads these reports when you restart the app. Reports are sent to a [Slack channel](https://zed-industries.slack.com/archives/C0977J9MA1Y) and to [Sentry](https://zed-dev.sentry.io/issues) (both are Zed-staff-only).
+
+These crash reports include useful data, but they are hard to read without spans or symbol information. You can still analyze them locally by downloading source and an unstripped binary (or separate symbols file) for your Zed release, then running:
+
+```sh
+zstd -d ~/.local/share/zed/<uuid>.dmp -o minidump.dmp
+minidump-stackwalk minidump.dmp
+```
+
+Alongside the minidump in your logs directory, you should also see a `<uuid>.json` file with metadata such as the panic message, span, and system specs.
+
+## Using a Debugger
+
+If you can reproduce the crash consistently, use a debugger to inspect program state at the crash point.
+
+For setup details, see [Using a debugger](./debuggers.md#debugging-panics-and-crashes).

docs/src/development/feature-process.md

@@ -0,0 +1,55 @@
+# Zed's Feature Development Process
+
+This is for moderate-to-large features — new UI, behavior changes, or work that cuts across multiple parts of Zed. Small keybindings or settings tweaks don't need all of this.
+
+> **Before you start:** If you're an external contributor, make sure the feature is something the team wants before investing significant effort. Please read the [Contributing Guide](../../../CONTRIBUTING.md) and our [Feature Request Guidelines](https://github.com/zed-industries/zed/discussions/51422) — if there isn't already a GitHub issue with clear staff confirmation, start with a GitHub Discussion. Feature request PRs that skip this process have a _very_ low merge rate. Taking the time to follow our process significantly increases the chances your idea gets picked up and built.
+
+## 1. Why does this matter?
+
+Every feature starts as an idea. Before writing any code, ground it:
+
+- **What problem does this solve?**
+- **What's the evidence?** GitHub issues, Discord requests, thumbs-up counts, blog posts.
+- **Is there prior art?** If it's in VS Code, JetBrains, Neovim, or a wildly popular plugin, that's a strong signal. If the idea is more novel, name what it's based on — "This is X, adapted for Zed's multi-buffers" is far more useful than "I think this would be cool."
+
+## 2. What is it?
+
+Write a short, concrete feature statement, then back it up with the context gathered above. If you can't describe the feature in a few sentences, it might be too big or too vague.
+
+Here's an example format, though adapt it to whatever your feature needs:
+
+**Feature:** Inline Git Blame
+
+**Purpose:** Show the last commit author and message for each line directly after the editor text, so developers can understand code history without opening the git blame.
+
+**Background:**
+This is standard across all major code editors:
+
+- \[screenshot of VSCode]
+- \[screenshot of Intellij]
+- \[screenshot of Neovim]
+- and has 146 thumbs up on this [github issue](https://github.com).
+
+**Decisions:**
+We have to decide whether to use the git CLI or a git library. Zed uses a git library but its blame implementation is too slow for a code editor, so we should use the CLI's porcelain interface.
+
+## 3. What else does this affect?
+
+Walk through this list before you start building. Not everything will apply:
+
+- **Actions & keybindings.** What actions does your feature define? Do the default keybindings conflict with existing ones?
+- **Settings.** Is any behavior configurable? Per-user vs. per-project vs. per-language? Don't forget to add new settings to the Settings UI.
+- **Themes & styling.** Does this need a new semantic token? Does it look right in both light and dark mode?
+- **Vim mode.** Vim users might have different expectations for this feature.
+- **Remote development.** Does your feature work with remote projects? File paths, shell commands, and environment variables all might behave differently.
+- **Persistence across restarts.** Should your feature's state persist across restarts?
+- **Accessibility.** Is it keyboard-navigable? Are focus states clear?
+- **Platform differences.** Does behavior differ on macOS, Linux, or Windows?
+- **Performance.** How does it behave with large files or big projects? Are interactions instant?
+- **Security.** How does this feature interact with Workspace Trust? Does it open new attack surfaces in Zed?
+
+If your feature touches the **editor** specifically: the editor has a lot of coexisting features — gutter elements, inline blocks, multiple cursors, folding, edit predictions, code intelligence popovers, the minimap. Test your changes with different combinations of them active. Features that work in a normal buffer might need to be disabled in a multi-buffer.
+
+## 4. Ship it
+
+Use this as the basis for your GitHub Discussion, issue, or PR description. Good product research gets everyone aligned on goals, the state of the art, and any tradeoffs we might need to consider.

docs/src/development/freebsd.md

@@ -0,0 +1,56 @@
+---
+title: Building Zed for FreeBSD
+description: "Guide to building zed for freebsd for Zed development."
+---
+
+# Building Zed for FreeBSD
+
+FreeBSD is not currently a supported platform, so this guide is a work in progress.
+
+## Repository
+
+Clone the [Zed repository](https://github.com/zed-industries/zed).
+
+## Dependencies
+
+- Install the necessary system packages and rustup:
+
+  ```sh
+  script/freebsd
+  ```
+
+  If preferred, you can inspect [`script/freebsd`](https://github.com/zed-industries/zed/blob/main/script/freebsd) and perform the steps manually.
+
+## Building from source
+
+Once the dependencies are installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
+
+For a debug build of the editor:
+
+```sh
+cargo run
+```
+
+And to run the tests:
+
+```sh
+cargo test --workspace
+```
+
+In release mode, the primary user interface is the `cli` crate. You can run it in development with:
+
+```sh
+cargo run -p cli
+```
+
+### WebRTC Notice
+
+Building `webrtc-sys` on FreeBSD currently fails due to missing upstream support and unavailable prebuilt binaries. As a result, collaboration features that depend on WebRTC (audio calls and screen sharing) are temporarily disabled.
+
+See [Issue #15309: FreeBSD Support] and [Discussion #29550: Unofficial FreeBSD port for Zed] for more.
+
+## Troubleshooting
+
+### Cargo errors claiming that a dependency is using unstable features
+
+Try `cargo clean` and `cargo build`.

docs/src/development/glossary.md

@@ -0,0 +1,122 @@
+---
+title: "Zed Development: Glossary"
+description: "Guide to zed development: glossary for Zed development."
+---
+
+# Zed Development: Glossary
+
+This page defines terms and structures used throughout the Zed codebase.
+
+It is a best-effort list and a work in progress.
+
+<!--
+TBD: Glossary Improvement
+
+Questions:
+
+- Can we generate this list from doc comments throughout zed?
+- We should have a section that shows the various UI parts and their names. (Can't do that in the channel.)
+-->
+
+## Naming conventions
+
+These are common naming patterns across the codebase. `Name` is a placeholder
+for any type name, such as `AnyElement` or `LspStore`.
+
+- `AnyName`: A type-erased version of _name_. Think `Box<dyn NameTrait>`.
+- `NameStore`: A wrapper type which abstracts over whether operations are running locally or on a remote.
+
+## GPUI
+
+### State management
+
+- `App`: A singleton that holds full application state, including all entities. `App` is not `Send`, so it exists only on the thread that created it (usually the main/UI thread). If you see `&mut App`, you are on the UI thread.
+- `Context`: A wrapper around `App` with specialized behavior for a specific `Entity`. You can think of it as `(&mut App, Entity<V>)`. For example, `App::spawn` takes `AsyncFnOnce(AsyncApp) -> Ret`, while `Context::spawn` takes `AsyncFnOnce(WeakEntity<V>, AsyncApp) -> Ret`.
+- `AsyncApp`: An owned version of `App` for async contexts. It is still not `Send`, so it still runs on the main thread, and operations may fail if the `App` has already terminated.
+  `AsyncApp` exists because `App` is usually accessed as `&mut App`, which is awkward to hold across async boundaries.
+- `AppContext`: A trait that abstracts over `App`, `AsyncApp`, `Context`, and their test variants.
+- `Task`: A future running (or scheduled to run) on a background or foreground executor. Unlike regular futures, tasks do not need `.await` to start. You still need to await them to read their result.
+- `Executor`: Used to spawn tasks that run either on the foreground or background thread. Try to run the tasks on the background thread.
+  - `BackgroundExecutor`: A threadpool running `Task`s.
+  - `ForegroundExecutor`: The main thread running `Task`s.
+- `Entity`: A strong, well-typed reference to a struct which is managed by gpui. Effectively a pointer/map key into the `App::EntityMap`.
+- `WeakEntity`: A runtime checked reference to an `Entity` which may no longer exist. Similar to [`std::rc::Weak`](https://doc.rust-lang.org/std/rc/struct.Weak.html).
+- `Global`: A singleton type which has only one value, that is stored in the `App`.
+- `Event`: A data type that can be sent by an `Entity` to subscribers.
+- `Action`: An event that represents a user's keyboard input that can be handled by listeners
+  Example: {#action file_finder::Toggle}
+- `Observing`: Reacting to notifications that entities have changed.
+- `Subscription`: An event handler that is used to react to the changes of state in the application.
+  1. Emitted event handling
+  2. Observing `{new,release,on notify}` of an entity
+
+### UI
+
+- `View`: An `Entity` which can produce an `Element` through its implementation of `Render`.
+- `Element`: A type that can be laid out and painted to the screen.
+- `element expression`: An expression that builds an element tree, example:
+
+```rust
+h_flex()
+    .id(text[i])
+    .relative()
+    .when(selected, |this| {
+        this.child(
+            div()
+                .h_4()
+                .absolute()
+                etc etc
+```
+
+- `Component`: A builder which can be rendered turning it into an `Element`.
+- `Dispatch tree`: TODO
+- `Focus`: The place where keystrokes are handled first
+- `Focus tree`: Path from the place that has the current focus to the UI Root. Example <img> TODO
+
+## Zed UI
+
+- `Window`: A struct representing a Zed window in your desktop environment (see image below). You can have multiple windows open. This is mostly passed around for rendering.
+- `Modal`: A UI element that floats on top of the rest of the UI
+- `Picker`: A struct representing a list of items floating on top of the UI (Modal). You can select an item and confirm. What happens on select or confirm is determined by the picker's delegate. (The 'Modal' in the image below is a picker.)
+- `PickerDelegate`: A trait used to specialize behavior for a `Picker`. The `Picker` stores the `PickerDelegate` in the field delegate.
+- `Center`: The middle of the zed window, the center is split into multiple `Pane`s. In the codebase this is a field on the `Workspace` struct. (see image below).
+- `Pane`: An area in the `Center` where we can place items, such as an editor, multi-buffer or terminal (see image below).
+- `Panel`: An `Entity` implementing the `Panel` trait. Panels can be placed in a `Dock`. In the image below: `ProjectPanel` is in the left dock, `DebugPanel` is in the bottom dock, and `AgentPanel` is in the right dock. `Editor` does not implement `Panel`.
+- `Dock`: A UI element similar to a `Pane` that can be opened and hidden. Up to three docks can be open at once: left, right, and bottom. A dock contains one or more `Panel`s, not `Pane`s.
+
+<img width="1921" height="auto" alt="Screenshot for the Pane and Dock features" src="https://github.com/user-attachments/assets/2cb1170e-2850-450d-89bb-73622b5d07b2" />
+
+- `Project`: One or more `Worktree`s
+- `Worktree`: Represents either local or remote files.
+
+<img width="552" height="auto" alt="Screenshot for the Worktree feature" src="https://github.com/user-attachments/assets/da5c58e4-b02e-4038-9736-27e3509fdbfa" />
+
+- [Multibuffer](https://zed.dev/docs/multibuffers): A list of Editors, a multi-buffer allows editing multiple files simultaneously. A multi-buffer opens when an operation in Zed returns multiple locations, examples: _search_ or _go to definition_. See project search in the image below.
+
+<img width="800" height="auto" alt="Screenshot for the MultiBuffer feature" src="https://github.com/user-attachments/assets/d59dcecd-8ab6-4172-8fb6-b1fc3c3eaf9d" />
+
+## Editor
+
+- `Editor`: The text editor type. Most editable surfaces in Zed are an `Editor`, including single-line inputs. Each pane in the image above contains one or more `Editor` instances.
+- `Workspace`: The root of the window
+- `Entry`: A file, dir, pending dir or unloaded dir.
+- `Buffer`: The in-memory representation of a 'file' together with relevant data such as syntax trees, git status and diagnostics.
+- `pending selection`: You have mouse down and you're dragging but you have not yet released.
+
+## Collab
+
+- `Collab session`: Multiple users working in a shared `Project`
+- `Upstream client`: The zed client which has shared their workspace
+- `Downstream client`: The zed client joining a shared workspace
+
+## Debugger
+
+- `DapStore`: Is an entity that manages debugger sessions
+- `debugger::Session`: An entity that manages the lifecycle of a debug session and communication with DAPs.
+- `BreakpointStore`: Is an entity that manages breakpoints states in local and remote instances of Zed
+- `DebugSession`: Manages a debug session's UI and running state
+- `RunningState`: Directly manages all the views of a debug session
+- `VariableList`: The variable and watch list view of a debug session
+- `Console`: TODO
+- `Terminal`: TODO
+- `BreakpointList`: TODO

docs/src/development/linux.md

@@ -0,0 +1,196 @@
+---
+title: Building Zed for Linux
+description: "Guide to building zed for linux for Zed development."
+---
+
+# Building Zed for Linux
+
+## Repository
+
+Clone the [Zed repository](https://github.com/zed-industries/zed).
+
+## Dependencies
+
+- Install [rustup](https://www.rust-lang.org/tools/install)
+
+- Install the necessary system libraries:
+
+  ```sh
+  script/linux
+  ```
+
+  If you prefer to install the system libraries manually, you can find the list of required packages in the `script/linux` file.
+
+## Building from source
+
+Once the dependencies are installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
+
+For a debug build of the editor:
+
+```sh
+cargo run
+```
+
+And to run the tests:
+
+```sh
+cargo test --workspace
+```
+
+In release mode, the primary user interface is the `cli` crate. You can run it in development with:
+
+```sh
+cargo run -p cli
+```
+
+## Installing a development build
+
+You can install a local build on your machine with:
+
+```sh
+./script/install-linux
+```
+
+This builds `zed` and the `cli` in release mode, installs the binary at `~/.local/bin/zed`, and installs `.desktop` files to `~/.local/share`.
+
+> **_Note_**: If you encounter linker errors similar to the following:
+>
+> ```bash
+> error: linking with `cc` failed: exit status: 1 ...
+> = note: /usr/bin/ld: /tmp/rustcISMaod/libaws_lc_sys-79f08eb6d32e546e.rlib(f8e4fd781484bd36-bcm.o): in function `aws_lc_0_25_0_handle_cpu_env':
+>           /aws-lc/crypto/fipsmodule/cpucap/cpu_intel.c:(.text.aws_lc_0_25_0_handle_cpu_env+0x63): undefined reference to `__isoc23_sscanf'
+>           /usr/bin/ld: /tmp/rustcISMaod/libaws_lc_sys-79f08eb6d32e546e.rlib(f8e4fd781484bd36-bcm.o): in function `pkey_rsa_ctrl_str':
+>           /aws-lc/crypto/fipsmodule/evp/p_rsa.c:741:(.text.pkey_rsa_ctrl_str+0x20d): undefined reference to `__isoc23_strtol'
+>           /usr/bin/ld: /aws-lc/crypto/fipsmodule/evp/p_rsa.c:752:(.text.pkey_rsa_ctrl_str+0x258): undefined reference to `__isoc23_strtol'
+>           collect2: error: ld returned 1 exit status
+>   = note: some `extern` functions couldn't be found; some native libraries may need to be installed or have their path specified
+>   = note: use the `-l` flag to specify native libraries to link
+>   = note: use the `cargo:rustc-link-lib` directive to specify the native libraries to link with Cargo (see https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-link-lib)
+> error: could not compile `remote_server` (bin "remote_server") due to 1 previous error
+> ```
+>
+> **Cause**:
+> This is caused by known bugs in aws-lc-rs (no GCC >= 14 support): [FIPS fails to build with GCC >= 14](https://github.com/aws/aws-lc-rs/issues/569)
+> & [GCC-14 - build failure for FIPS module](https://github.com/aws/aws-lc/issues/2010)
+>
+> You can refer to [linux: Linker error for remote_server when using script/install-linux](https://github.com/zed-industries/zed/issues/24880) for more information.
+>
+> **Workaround**:
+> Set the remote server target to `x86_64-unknown-linux-gnu` like so `export REMOTE_SERVER_TARGET=x86_64-unknown-linux-gnu; script/install-linux`
+
+## Wayland & X11
+
+Zed supports both X11 and Wayland. By default, we pick whichever we can find at runtime. If you're on Wayland and want to run in X11 mode, use the environment variable `WAYLAND_DISPLAY=''`.
+
+## Notes for packaging Zed
+
+This section is for distribution maintainers packaging Zed.
+
+### Technical requirements
+
+Zed has two main binaries:
+
+- You will need to build `crates/cli` and make its binary available in `$PATH` with the name `zed`.
+- You will need to build `crates/zed` and put it at `$PATH/to/cli/../../libexec/zed-editor`. For example, if you are going to put the cli at `~/.local/bin/zed` put zed at `~/.local/libexec/zed-editor`. As some linux distributions (notably Arch) discourage the use of `libexec`, you can also put this binary at `$PATH/to/cli/../../lib/zed/zed-editor` (e.g. `~/.local/lib/zed/zed-editor`) instead.
+- If you are going to provide a `.desktop` file you can find a template in `crates/zed/resources/zed.desktop.in`, and use `envsubst` to populate it with the values required. This file should also be renamed to `$APP_ID.desktop` so that the file [follows the FreeDesktop standards](https://github.com/zed-industries/zed/issues/12707#issuecomment-2168742761). You should also make this desktop file executable (`chmod 755`).
+- You will need to ensure that the necessary libraries are installed. You can get the current list by [inspecting the built binary](https://github.com/zed-industries/zed/blob/935cf542aebf55122ce6ed1c91d0fe8711970c82/script/bundle-linux#L65-L67) on your system.
+- For an example of a complete build script, see [script/bundle-linux](https://github.com/zed-industries/zed/blob/935cf542aebf55122ce6ed1c91d0fe8711970c82/script/bundle-linux).
+- You can disable Zed's auto updates and provide instructions for users who try to update Zed manually by building (or running) Zed with the environment variable `ZED_UPDATE_EXPLANATION`. For example: `ZED_UPDATE_EXPLANATION="Please use flatpak to update zed."`.
+- Make sure to update the contents of the `crates/zed/RELEASE_CHANNEL` file to 'nightly', 'preview', or 'stable', with no newline. This will cause Zed to use the credentials manager to remember a user's login.
+
+### Other things to note
+
+Zed moves quickly, and distribution maintainers often have different constraints and priorities. The points below describe current trade-offs:
+
+- Zed is a fast-moving project. We typically publish 2-3 builds per week to address reported issues and ship larger changes.
+- There are a couple of other `zed` binaries that may be present on Linux systems ([1](https://openzfs.github.io/openzfs-docs/man/v2.2/8/zed.8.html), [2](https://zed.brimdata.io/docs/commands/zed)). If you want to rename our CLI binary because of these issues, we suggest `zedit`, `zeditor`, or `zed-cli`.
+- Zed automatically installs versions of common developer tools, similar to rustup/rbenv/pyenv. This behavior is discussed [here](https://github.com/zed-industries/zed/issues/12589).
+- Users can install extensions locally and from [zed-industries/extensions](https://github.com/zed-industries/extensions). Extensions may install additional tools such as language servers. Planned safety improvements are tracked [here](https://github.com/zed-industries/zed/issues/12358).
+- Zed connects to several online services by default (AI, telemetry, collaboration). AI and our telemetry can be disabled by your users with their zed settings or by patching our [default settings file](https://github.com/zed-industries/zed/blob/main/assets/settings/default.json).
+- Because of the points above, Zed currently does not work well with sandboxes. See [this discussion](https://github.com/zed-industries/zed/pull/12006#issuecomment-2130421220).
+
+## Flatpak
+
+> Zed's current Flatpak integration exits the sandbox on startup. Workflows that rely on Flatpak's sandboxing may not work as expected.
+
+To build & install the Flatpak package locally follow the steps below:
+
+1. Install Flatpak for your distribution as outlined [here](https://flathub.org/setup).
+2. Run the `script/flatpak/deps` script to install the required dependencies.
+3. Run `script/flatpak/bundle-flatpak`.
+4. Now the package has been installed and has a bundle available at `target/release/{app-id}.flatpak`.
+
+## Memory profiling
+
+[`heaptrack`](https://github.com/KDE/heaptrack) is quite useful for diagnosing memory leaks. To install it:
+
+```sh
+$ sudo apt install heaptrack heaptrack-gui
+$ cargo install cargo-heaptrack
+```
+
+Then, to build and run Zed with the profiler attached:
+
+```sh
+$ cargo heaptrack -b zed
+```
+
+When this zed instance is exited, terminal output will include a command to run `heaptrack_interpret` to convert the `*.raw.zst` profile to a `*.zst` file which can be passed to `heaptrack_gui` for viewing.
+
+## Perf recording
+
+How to get a flamegraph with resolved symbols from a running Zed instance.
+Use this when Zed is using a lot of CPU. It is not useful for hangs.
+
+### During the incident
+
+- Find the PID (process ID) using:
+  `ps -eo size,pid,comm | grep zed | sort | head -n 1 | cut -d ' ' -f 2`
+  Or find the PID of `zed-editor` with the highest RAM usage in something
+  like htop/btop/top.
+
+- Install perf:
+  On Ubuntu (derivatives) run `sudo apt install linux-tools`.
+
+- Perf record:
+  Run `sudo perf record -p <pid you just found>`, wait a few seconds to gather data, then press Ctrl+C. You should now have a `perf.data` file.
+
+- Make the output file user owned:
+  run `sudo chown $USER:$USER perf.data`
+
+- Get build info:
+  Run zed again and type {#action zed::About} in the command pallet to get the exact commit.
+
+The `perf.data` file can be sent to Zed together with the exact commit.
+
+### Later
+
+This can be done by Zed staff.
+
+- Build Zed with symbols:
+  Check out the commit found previously and modify `Cargo.toml`.
+  Apply the following diff, then make a release build.
+
+```diff
+[profile.release]
+-debug = "limited"
++debug = "full"
+```
+
+- Add the symbols to the perf database:
+  `perf buildid-cache -v -a <path to release zed binary>`
+
+- Resolve the symbols from the db:
+  `perf inject -i perf.data -o perf_with_symbols.data`
+
+- Install flamegraph:
+  `cargo install cargo-flamegraph`
+
+- Render the flamegraph:
+  `flamegraph --perfdata perf_with_symbols.data`
+
+## Troubleshooting
+
+### Cargo errors claiming that a dependency is using unstable features
+
+Try `cargo clean` and `cargo build`.

docs/src/development/macos.md

@@ -0,0 +1,197 @@
+---
+title: Building Zed for macOS
+description: "Guide to building zed for macos for Zed development."
+---
+
+# Building Zed for macOS
+
+## Repository
+
+Clone the [Zed repository](https://github.com/zed-industries/zed).
+
+## Dependencies
+
+- Install [rustup](https://www.rust-lang.org/tools/install)
+
+- Install [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12) from the macOS App Store or from the [Apple Developer](https://developer.apple.com/download/all/) website. The Apple Developer download requires a developer account.
+
+> Launch Xcode after installation and install the macOS components (the default option).
+
+- Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
+
+  ```sh
+  xcode-select --install
+  ```
+
+- Ensure that the Xcode command line tools are using your newly installed copy of Xcode:
+
+  ```sh
+  sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+  sudo xcodebuild -license accept
+  ```
+
+- Install `cmake` (required by [a dependency](https://docs.rs/wasmtime-c-api-impl/latest/wasmtime_c_api/))
+
+  ```sh
+  brew install cmake
+  ```
+
+## Building Zed from Source
+
+Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
+
+For a debug build:
+
+```sh
+cargo run
+```
+
+For a release build:
+
+```sh
+cargo run --release
+```
+
+And to run the tests:
+
+```sh
+cargo test --workspace
+```
+
+## Visual Regression Tests
+
+Zed includes visual regression tests that capture screenshots of real Zed windows and compare them against baseline images. These tests require macOS with Screen Recording permission.
+
+### Prerequisites
+
+You must grant Screen Recording permission to your terminal:
+
+1. Run the visual test runner once - macOS will prompt for permission
+2. Or manually: System Settings > Privacy & Security > Screen Recording
+3. Enable your terminal app (e.g., Terminal.app, iTerm2, Ghostty)
+4. Restart your terminal after granting permission
+
+### Running Visual Tests
+
+```sh
+cargo run -p zed --bin zed_visual_test_runner --features visual-tests
+```
+
+### Baseline Images
+
+Baseline images are stored in `crates/zed/test_fixtures/visual_tests/` but are
+**gitignored** to avoid bloating the repository. You must generate them locally
+before running tests.
+
+#### Initial Setup
+
+Before making any UI changes, generate baseline images from a known-good state:
+
+```sh
+git checkout origin/main
+UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests
+git checkout -
+```
+
+This creates baselines that reflect the current expected UI.
+
+#### Updating Baselines
+
+When UI changes are intentional, update the baseline images after your changes:
+
+```sh
+UPDATE_BASELINE=1 cargo run -p zed --bin zed_visual_test_runner --features visual-tests
+```
+
+> **Note:** In the future, baselines may be stored externally. For now, they
+> remain local-only to keep the git repository lightweight.
+
+## Troubleshooting
+
+### Error compiling metal shaders
+
+```sh
+error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
+
+xcrun: error: unable to find utility "metal", not a developer tool or in PATH
+```
+
+Try `sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer`
+
+If you're on macOS 26, try `xcodebuild -downloadComponent MetalToolchain`.
+If that command fails, run `xcodebuild -runFirstLaunch` and try downloading the toolchain again.
+
+### Cargo errors claiming that a dependency is using unstable features
+
+Try `cargo clean` and `cargo build`.
+
+### Error: 'dispatch/dispatch.h' file not found
+
+If you encounter an error similar to:
+
+```sh
+src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
+
+Caused by:
+  process didn't exit successfully
+
+  --- stdout
+  cargo:rustc-link-lib=framework=System
+  cargo:rerun-if-changed=src/platform/mac/dispatch.h
+  cargo:rerun-if-env-changed=TARGET
+  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64-apple-darwin
+  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS_aarch64_apple_darwin
+  cargo:rerun-if-env-changed=BINDGEN_EXTRA_CLANG_ARGS
+```
+
+This file is part of Xcode. Make sure the Xcode command line tools are installed and the path is set correctly:
+
+```sh
+xcode-select --install
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+```
+
+Additionally, set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable:
+
+```sh
+export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
+```
+
+Then clean and rebuild the project:
+
+```sh
+cargo clean
+cargo run
+```
+
+### Tests failing due to `Too many open files (os error 24)`
+
+This error seems to be caused by OS resource constraints. Installing and running tests with `cargo-nextest` should resolve the issue.
+
+- `cargo install cargo-nextest --locked`
+- `cargo nextest run --workspace --no-fail-fast`
+
+## Tips & Tricks
+
+### Avoiding continual rebuilds
+
+If Zed continually rebuilds root crates, you may be opening the Zed codebase itself in your development build.
+
+This causes problems because `cargo run` exports a bunch of environment
+variables which are picked up by the `rust-analyzer` that runs in the development
+build of Zed. These environment variables are in turn passed to `cargo check`, which
+invalidates the build cache of some of the crates we depend on.
+
+To avoid this, run the built binary against a different project, for example `cargo run ~/path/to/other/project`.
+
+### Speeding up verification
+
+If you build Zed frequently, macOS may keep verifying new builds, which can add a few seconds to each iteration.
+
+To fix this, you can:
+
+- Run `sudo spctl developer-mode enable-terminal` to enable the Developer Tools panel in System Settings.
+- In System Settings, search for "Developer Tools" and add your terminal (e.g. iTerm or Ghostty) to the list under "Allow applications to use developer tools"
+- Restart your terminal.
+
+Thanks to the nextest developers for publishing [this](https://nexte.st/docs/installation/macos/#gatekeeper).

docs/src/development/release-notes.md

@@ -0,0 +1,34 @@
+---
+title: Release Notes
+description: "Guide to release notes for Zed development."
+---
+
+# Release Notes
+
+Whenever you open a pull request, the body is automatically populated based on this [pull request template](https://github.com/zed-industries/zed/blob/main/.github/pull_request_template.md).
+
+```md
+...
+
+Release Notes:
+
+- N/A _or_ Added/Fixed/Improved ...
+```
+
+On Wednesdays, we run [`get-preview-channel-changes`](https://github.com/zed-industries/zed/blob/main/script/get-preview-channel-changes), which collects `Release Notes` lines from pull requests landing in preview, as described in the [Release](https://zed.dev/docs/development/release-notes) docs.
+
+The script outputs everything below the `Release Notes` line, including metadata such as the pull request author (if they are not a Zed team member) and a link to the pull request.
+If you use `N/A`, the script skips your pull request entirely.
+
+## Guidelines for crafting your `Release Notes` line(s)
+
+- A `Release Notes` line should only be written if the user can see or feel the difference in Zed.
+- A `Release Notes` line should be written such that a Zed user can understand what the change is.
+  Don't assume a user knows technical editor developer lingo; phrase your change in language they understand as a user of a text editor.
+- If you want to include technical details about your pull request for other team members to see, do so above the `Release Notes` line.
+- Changes to docs should be labeled as `N/A`.
+- If your pull request adds/changes a setting or a keybinding, always mention that setting or keybinding.
+  Don't make the user dig into docs or the pull request to find this information (although it should be included in docs as well).
+- For pull requests that are reverts:
+  - If the item being reverted **has already been shipped**, include a `Release Notes` line explaining why we reverted, as this is a breaking change.
+- If the item being reverted **hasn't been shipped**, edit the original PR's `Release Notes` line to `N/A`; otherwise, it will still be included and the release notes compiler may not know to skip it.

docs/src/development/windows.md

@@ -0,0 +1,262 @@
+---
+title: Building Zed for Windows
+description: "Guide to building zed for windows for Zed development."
+---
+
+# Building Zed for Windows
+
+> The following commands may be executed in any shell.
+
+## Repository
+
+Clone the [Zed repository](https://github.com/zed-industries/zed).
+
+## Dependencies
+
+- Install [rustup](https://www.rust-lang.org/tools/install)
+
+- Install either [Visual Studio](https://visualstudio.microsoft.com/downloads/) with the optional components `MSVC v*** - VS YYYY C++ x64/x86 build tools` and `MSVC v*** - VS YYYY C++ x64/x86 Spectre-mitigated libs (latest)` (`v***` is your VS version and `YYYY` is the release year. Adjust architecture as needed).
+- Or, if you prefer a slimmer installation, install only the [Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (plus the libs above) and the "Desktop development with C++" workload.
+  This setup is not picked up automatically by rustup. Before compiling, initialize environment variables by launching the developer shell (cmd/PowerShell) installed in the Start menu or Windows Terminal.
+- Install the Windows 11 or 10 SDK for your system, and make sure at least `Windows 10 SDK version 2104 (10.0.20348.0)` is installed. You can download it from the [Windows SDK Archive](https://developer.microsoft.com/windows/downloads/windows-sdk/).
+- Install [CMake](https://cmake.org/download) (required by [a dependency](https://docs.rs/wasmtime-c-api-impl/latest/wasmtime_c_api/)). Or you can install it through Visual Studio Installer, then manually add the `bin` directory to your `PATH`, for example: `C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin`.
+
+If you cannot compile Zed, make sure a Visual Studio installation includes at least the following components:
+
+```json
+{
+  "version": "1.0",
+  "components": [
+    "Microsoft.VisualStudio.Component.CoreEditor",
+    "Microsoft.VisualStudio.Workload.CoreEditor",
+    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
+    "Microsoft.VisualStudio.ComponentGroup.WebToolsExtensions.CMake",
+    "Microsoft.VisualStudio.Component.VC.CMake.Project",
+    "Microsoft.VisualStudio.Component.Windows11SDK.26100",
+    "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre"
+  ],
+  "extensions": []
+}
+```
+
+If you are using Build Tools only, make sure these components are installed:
+
+```json
+{
+  "version": "1.0",
+  "components": [
+    "Microsoft.VisualStudio.Component.Roslyn.Compiler",
+    "Microsoft.Component.MSBuild",
+    "Microsoft.VisualStudio.Component.CoreBuildTools",
+    "Microsoft.VisualStudio.Workload.MSBuildTools",
+    "Microsoft.VisualStudio.Component.Windows10SDK",
+    "Microsoft.VisualStudio.Component.VC.CoreBuildTools",
+    "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
+    "Microsoft.VisualStudio.Component.VC.Redist.14.Latest",
+    "Microsoft.VisualStudio.Component.Windows11SDK.26100",
+    "Microsoft.VisualStudio.Component.VC.CMake.Project",
+    "Microsoft.VisualStudio.Component.TextTemplating",
+    "Microsoft.VisualStudio.Component.VC.CoreIde",
+    "Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Core",
+    "Microsoft.VisualStudio.Workload.VCTools",
+    "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre"
+  ],
+  "extensions": []
+}
+```
+
+You can export this component list as follows:
+
+- Open the Visual Studio Installer
+- Click on `More` in the `Installed` tab
+- Click on `Export configuration`
+
+### Notes
+
+Update `pg_hba.conf` in the `data` directory to use `trust` instead of `scram-sha-256` for the `host` method. Otherwise, the connection fails with `password authentication failed`. The file is typically at `C:\Program Files\PostgreSQL\17\data\pg_hba.conf`. After the change, it should look like this:
+
+```conf
+# IPv4 local connections:
+host    all             all             127.0.0.1/32            trust
+# IPv6 local connections:
+host    all             all             ::1/128                 trust
+```
+
+If you are using a non-Latin Windows locale, set the `lc_messages` parameter in `postgresql.conf` (in the `data` directory) to `English_United States.1252` (or another UTF-8-compatible encoding available on your system). Otherwise, the database may panic. The file should look like this:
+
+```conf
+# lc_messages = 'Chinese (Simplified)_China.936' # locale for system error message strings
+lc_messages = 'English_United States.1252'
+```
+
+After this, restart the `postgresql` service. Press `Win`+`R` to open the Run dialog, enter `services.msc`, and select **OK**. In Services Manager, find `postgresql-x64-XX`, right-click it, and select **Restart**.
+
+## Building from source
+
+Once you have the dependencies installed, you can build Zed using [Cargo](https://doc.rust-lang.org/cargo/).
+
+For a debug build:
+
+```sh
+cargo run
+```
+
+For a release build:
+
+```sh
+cargo run --release
+```
+
+And to run the tests:
+
+```sh
+cargo test --workspace
+```
+
+> **Note:** Visual regression tests are currently macOS-only and require Screen Recording permission. See [Building Zed for macOS](./macos.md#visual-regression-tests) for details.
+
+## Installing from msys2
+
+Zed does not support unofficial MSYS2 Zed packages built for Mingw-w64. Please report any issues you may have with [mingw-w64-zed](https://packages.msys2.org/base/mingw-w64-zed) to [msys2/MINGW-packages/issues](https://github.com/msys2/MINGW-packages/issues?q=is%3Aissue+is%3Aopen+zed).
+
+Please refer to [MSYS2 documentation](https://www.msys2.org/docs/ides-editors/#zed) first.
+
+## Troubleshooting
+
+### Setting `RUSTFLAGS` env var breaks builds
+
+If you set the `RUSTFLAGS` env var, it will override the `rustflags` settings in `.cargo/config.toml` which is required to properly build Zed.
+
+Because these settings change over time, the resulting build errors may vary from linker failures to other hard-to-diagnose errors.
+
+If you need extra Rust flags, use one of the following approaches in `.cargo/config.toml`:
+
+Add your flags in the build section
+
+```toml
+[build]
+rustflags = ["-C", "symbol-mangling-version=v0", "--cfg", "tokio_unstable"]
+```
+
+Add your flags in the windows target section
+
+```toml
+[target.'cfg(target_os = "windows")']
+rustflags = [
+    "--cfg",
+    "windows_slim_errors",
+    "-C",
+    "target-feature=+crt-static",
+]
+```
+
+Or, create a new `.cargo/config.toml` in the parent directory of the Zed repo (see below). This is useful in CI because you do not need to edit the repo's original `.cargo/config.toml`.
+
+```
+upper_dir
+├── .cargo          // <-- Make this folder
+│   └── config.toml // <-- Make this file
+└── zed
+    ├── .cargo
+    │   └── config.toml
+    └── crates
+        ├── assistant
+        └── ...
+```
+
+In the new (above) `.cargo/config.toml`, if we wanted to add `--cfg gles` to our rustflags, it would look like this
+
+```toml
+[target.'cfg(all())']
+rustflags = ["--cfg", "gles"]
+```
+
+### Cargo errors claiming that a dependency is using unstable features
+
+Try `cargo clean` and `cargo build`.
+
+### `STATUS_ACCESS_VIOLATION`
+
+This error can happen if you are using the "rust-lld.exe" linker. Consider trying a different linker.
+
+If you are using a global config, consider moving the Zed repository to a nested directory and add a `.cargo/config.toml` with a custom linker config in the parent directory.
+
+See this issue for more information [#12041](https://github.com/zed-industries/zed/issues/12041)
+
+### Invalid RC path selected
+
+Sometimes, depending on the security rules applied to your laptop, you may get the following error while compiling Zed:
+
+```
+error: failed to run custom build command for `zed(C:\Users\USER\src\zed\crates\zed)`
+
+Caused by:
+  process didn't exit successfully: `C:\Users\USER\src\zed\target\debug\build\zed-b24f1e9300107efc\build-script-build` (exit code: 1)
+  --- stdout
+  cargo:rerun-if-changed=../../.git/logs/HEAD
+  cargo:rustc-env=ZED_COMMIT_SHA=25e2e9c6727ba9b77415588cfa11fd969612adb7
+  cargo:rustc-link-arg=/stack:8388608
+  cargo:rerun-if-changed=resources/windows/app-icon.ico
+  package.metadata.winresource does not exist
+  Selected RC path: 'bin\x64\rc.exe'
+
+  --- stderr
+  The system cannot find the path specified. (os error 3)
+warning: build failed, waiting for other jobs to finish...
+```
+
+To fix this issue, manually set the `ZED_RC_TOOLKIT_PATH` environment variable to the RC toolkit path. Usually this is:
+`C:\Program Files (x86)\Windows Kits\10\bin\<SDK_version>\x64`.
+
+See this [issue](https://github.com/zed-industries/zed/issues/18393) for more information.
+
+### Build fails: Path too long
+
+You may receive an error like the following when building
+
+```
+error: failed to get `pet` as a dependency of package `languages v0.1.0 (D:\a\zed-windows-builds\zed-windows-builds\crates\languages)`
+
+Caused by:
+  failed to load source for dependency `pet`
+
+Caused by:
+  Unable to update https://github.com/microsoft/python-environment-tools.git?rev=ffcbf3f28c46633abd5448a52b1f396c322e0d6c#ffcbf3f2
+
+Caused by:
+  path too long: 'C:/Users/runneradmin/.cargo/git/checkouts/python-environment-tools-903993894b37a7d2/ffcbf3f/crates/pet-conda/tests/unix/conda_env_without_manager_but_found_in_history/some_other_location/conda_install/conda-meta/python-fastjsonschema-2.16.2-py310hca03da5_0.json'; class=Filesystem (30)
+```
+
+To fix this, enable long-path support for both Git and Windows.
+
+For git: `git config --system core.longpaths true`
+
+And for Windows with this PS command:
+
+```powershell
+New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
+```
+
+For more information on this, please see [win32 docs](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=powershell)
+
+(You need to restart your system after enabling long-path support.)
+
+### Graphics issues
+
+#### Zed fails to launch
+
+Zed currently uses Vulkan as its graphics API on Windows. If Zed fails to launch, Vulkan is a common cause.
+
+You can check the Zed log at:
+`C:\Users\YOU\AppData\Local\Zed\logs\Zed.log`
+
+If you see messages like:
+
+- `Zed failed to open a window: NoSupportedDeviceFound`
+- `ERROR_INITIALIZATION_FAILED`
+- `GPU Crashed`
+- `ERROR_SURFACE_LOST_KHR`
+
+Vulkan may not be working correctly on your system. Updating GPU drivers often resolves this.
+
+If there's nothing Vulkan-related in the logs and you happen to have Bandicam installed, try uninstalling it. Zed is currently not compatible with Bandicam.

docs/src/diagnostics.md

@@ -0,0 +1,75 @@
+---
+title: Diagnostics - Errors and Warnings in Zed
+description: View and navigate errors, warnings, and code diagnostics from language servers in Zed.
+---
+
+# Diagnostics
+
+Zed gets its diagnostics from the language servers and supports both push and pull variants of the LSP which makes it compatible with all existing language servers.
+
+# Regular diagnostics
+
+By default, Zed displays all diagnostics as underlined text in the editor and the scrollbar.
+
+Editor diagnostics could be filtered with the
+
+```json [settings]
+"diagnostics_max_severity": null
+```
+
+editor setting (possible values: `"off"`, `"error"`, `"warning"`, `"info"`, `"hint"`, `null` (default, all diagnostics)).
+
+The scrollbar ones are configured with the
+
+```json [settings]
+"scrollbar": {
+  "diagnostics": "all",
+}
+```
+
+configuration (possible values: `"none"`, `"error"`, `"warning"`, `"information"`, `"all"` (default))
+
+The diagnostics could be hovered to display a tooltip with full, rendered diagnostic message.
+Or, `editor::GoToDiagnostic` and `editor::GoToPreviousDiagnostic` could be used to navigate between diagnostics in the editor, showing a popover for the currently active diagnostic.
+
+# Inline diagnostics (Error lens)
+
+Zed supports showing diagnostic as lens to the right of the code.
+This is disabled by default, but can either be temporarily turned on (or off) using the editor menu, or permanently, using the
+
+```json [settings]
+"diagnostics": {
+  "inline": {
+    "enabled": true,
+    "max_severity": null, // same values as the `diagnostics_max_severity` from the editor settings
+  }
+}
+```
+
+# Other UI places
+
+## Project Panel
+
+Project panel can have its entries coloured based on the severity of the diagnostics in the file.
+
+To configure, use
+
+```json [settings]
+"project_panel": {
+  "show_diagnostics": "all",
+}
+```
+
+configuration (possible values: `"off"`, `"errors"`, `"all"` (default))
+
+## Editor tabs
+
+Similar to the project panel, editor tabs can be colorized with the
+
+```json [settings]
+"tabs": {
+  "show_diagnostics": "off",
+}
+```
+
+configuration (possible values: `"off"` (default), `"errors"`, `"all"`)

docs/src/editing-code.md

@@ -0,0 +1,37 @@
+---
+title: Editing Code in Zed
+description: Core code editing features in Zed including multi-cursor, refactoring, code actions, and language server integration.
+---
+
+# Editing Code
+
+Zed provides tools to help you write and modify code efficiently. This section covers the core editing features that work alongside your language server.
+
+## What's in This Section
+
+- **[Code Completions](./completions.md)** — Autocomplete from language servers and AI-powered edit predictions
+- **[Snippets](./snippets.md)** — Insert reusable code templates with tab stops
+- **[Formatting & Linting](./configuring-languages.md#formatting-and-linting)** — Configure automatic code formatting and linter integration
+- **[Diagnostics & Quick Fixes](./diagnostics.md)** — View errors, warnings, and apply fixes from your language server
+- **[Multibuffers](./multibuffers.md)** — Edit multiple files simultaneously with multiple cursors
+
+## How These Features Work Together
+
+When you're editing code, Zed combines input from multiple sources:
+
+1. **Language servers** provide completions, diagnostics, and quick fixes based on your project's types and structure
+2. **Edit predictions** suggest multi-character or multi-line changes as you type
+3. **Multibuffers** let you apply changes across files in one operation
+
+For example, you might:
+
+- Rename a function using your language server's rename refactor
+- See the results in a multibuffer showing all affected files
+- Use multiple cursors to make additional edits across all locations
+- Get immediate diagnostic feedback if something breaks
+
+## Related Features
+
+- [AI Features](./ai/overview.md) — Agentic editing, inline code transformations, and AI code completions
+- [Configuring Languages](./configuring-languages.md) — Set up language servers for your project
+- [Key Bindings](./key-bindings.md) — Customize keyboard shortcuts for editing commands

docs/src/environment.md

@@ -0,0 +1,97 @@
+---
+title: Environment Variables - Zed
+description: How Zed detects and uses environment variables. Shell integration, dotenv support, and troubleshooting.
+---
+
+# Environment Variables
+
+_**Note**: The following only applies to Zed 0.152.0 and later._
+
+Multiple features in Zed are affected by environment variables:
+
+- [Tasks](./tasks.md)
+- [Built-in terminal](./terminal.md)
+- Look-up of language servers
+- Language servers
+
+To make the best use of these features, it helps to understand where Zed gets environment variables and how it uses them.
+
+## Where does Zed get its environment variables from?
+
+How Zed starts affects which environment variables it can use. That includes launching from the macOS Dock, a Linux window manager, or the `zed` CLI.
+
+### Launched from the CLI
+
+If Zed is opened via the CLI (`zed`), it will inherit the environment variables from the surrounding shell session.
+
+That means if you do
+
+```
+$ export MY_ENV_VAR=hello
+$ zed .
+```
+
+the environment variable `MY_ENV_VAR` is now available inside Zed. For example, in the built-in terminal.
+
+Starting with Zed 0.152.0, the CLI `zed` will _always_ pass along its environment to Zed, regardless of whether a Zed instance was previously running or not. Prior to Zed 0.152.0 this was not the case and only the first Zed instance would inherit the environment variables.
+
+### Launched via window manager, Dock, or launcher
+
+When Zed has been launched via the macOS Dock, or a GNOME or KDE icon on Linux, or an application launcher like Alfred or Raycast, it has no surrounding shell environment from which to inherit its environment variables.
+
+To still have a useful environment, Zed spawns a login shell in the user's home directory and reads its environment. This environment is then set on the Zed _process_, so all Zed windows and projects inherit it.
+
+Since that can lead to problems for users who need different environment variables per project (for example with `direnv`, `asdf`, or `mise`), Zed spawns another login shell when opening a project. This second shell runs in the project's directory. The environment from that shell is _not_ set on the process, because opening a new project would otherwise change the environment for all Zed windows. Instead, that environment is stored and passed along when running tasks, opening terminals, or spawning language servers.
+
+## Where and how are environment variables used?
+
+There are two sets of environment variables:
+
+1. Environment variables of the Zed process
+2. Environment variables stored per project
+
+The variables from (1) are always used, since they are stored on the process itself and every spawned process (tasks, terminals, language servers, ...) will inherit them by default.
+
+The variables from (2) are used explicitly, depending on the feature.
+
+### Tasks
+
+Tasks are spawned with a combined environment. In order of precedence (low to high, with the last overwriting the first):
+
+- the Zed process environment
+- if the project was opened from the CLI: the CLI environment
+- if the project was not opened from the CLI: the project environment variables obtained by running a login shell in the project's root folder
+- optional, explicitly configured environment in settings
+
+### Built-in terminal
+
+Built-in terminals, like tasks, are spawned with a combined environment. In order of precedence (low to high):
+
+- the Zed process environment
+- if the project was opened from the CLI: the CLI environment
+- if the project was not opened from the CLI: the project environment variables obtained by running a login shell in the project's root folder
+- optional, explicitly configured environment in settings
+
+### Look-up of language servers
+
+For some languages the language server adapters lookup the binary in the user's `$PATH`. Examples:
+
+- Go
+- Zig
+- Rust (if [configured to do so](./languages/rust.md#binary))
+- C
+- TypeScript
+
+For this look-up, Zed uses the following environment:
+
+- if the project was opened from the CLI: the CLI environment
+- if the project was not opened from the CLI: the project environment variables obtained by running a login shell in the project's root folder
+
+### Language servers
+
+After looking up a language server, Zed starts them.
+
+These language server processes always inherit Zed's process environment. But, depending on the language server look-up, additional environment variables might be set or overwrite the process environment.
+
+- If the language server was found in the project environment's `$PATH`, then that project environment is passed along to the language server process. Where the project environment comes from depends on how the project was opened (via CLI or not). See the previous section on language server look-up.
+- If the language server was not found in the project environment, Zed tries to install and start it globally. In that case, the process inherits Zed's process environment and, if the project was opened via CLI, the CLI environment.

docs/src/extensions.md

@@ -0,0 +1,19 @@
+---
+title: Extensions
+description: "Extend Zed with themes, language support, AI tools, and more through the extension system."
+---
+
+# Extensions
+
+Zed lets you add new functionality using user-defined extensions.
+
+- [Installing Extensions](./extensions/installing-extensions.md)
+- [Extension Capabilities](./extensions/capabilities.md)
+- [Developing Extensions](./extensions/developing-extensions.md)
+  - [Developing Language Extensions](./extensions/languages.md)
+  - [Developing Debugger Extensions](./extensions/debugger-extensions.md)
+  - [Developing Themes](./extensions/themes.md)
+  - [Developing Icon Themes](./extensions/icon-themes.md)
+  - [Developing Snippets](./extensions/snippets.md)
+  - [Developing Agent Servers](./extensions/agent-servers.md)
+  - [Developing MCP Servers](./extensions/mcp-extensions.md)

docs/src/extensions/agent-servers.md

@@ -0,0 +1,183 @@
+---
+title: Agent Server Extensions
+description: "Agent Server Extensions for Zed extensions."
+---
+
+# Agent Server Extensions
+
+<div class="warning">
+
+Note that starting from `v0.221`.x, [the ACP Registry](https://agentclientprotocol.com/registry) is the preferred way to install external agents in Zed.
+You can learn more about it in [the release blog post](https://zed.dev/blog/acp-registry)
+
+At some point in the near future, Agent Server extensions will be deprecated.
+
+</div>
+
+Agent Servers are programs that provide AI agent implementations through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
+Agent Server Extensions let you package an Agent Server so users can install the extension and use your agent in Zed.
+
+You can see the current Agent Server extensions either by opening the Extensions tab in Zed (execute the {#action zed::Extensions} command) and changing the filter from `All` to `Agent Servers`, or by visiting [the Zed website](https://zed.dev/extensions?filter=agent-servers).
+
+## Defining Agent Server Extensions
+
+An extension can register one or more agent servers in the `extension.toml`:
+
+```toml
+[agent_servers.my-agent]
+name = "My Agent"
+
+[agent_servers.my-agent.targets.darwin-aarch64]
+archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
+cmd = "./agent"
+args = ["--serve"]
+
+[agent_servers.my-agent.targets.linux-x86_64]
+archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-linux-x64.tar.gz"
+cmd = "./agent"
+args = ["--serve"]
+
+[agent_servers.my-agent.targets.windows-x86_64]
+archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-windows-x64.zip"
+cmd = "./agent.exe"
+args = ["--serve"]
+```
+
+### Required Fields
+
+- `name`: A human-readable display name for the agent server (shown in menus)
+- `targets`: Platform-specific configurations for downloading and running the agent
+
+### Target Configuration
+
+Each target key uses the format `{os}-{arch}` where:
+
+- **os**: `darwin` (macOS), `linux`, or `windows`
+- **arch**: `aarch64` (ARM64) or `x86_64`
+
+Each target must specify:
+
+- `archive`: URL to download the archive from (supports `.tar.gz`, `.zip`, etc.)
+- `cmd`: Command to run the agent server (relative to the extracted archive)
+- `args`: Command-line arguments to pass to the agent server (optional)
+- `sha256`: SHA-256 hash string of the archive's bytes (optional, but recommended for security)
+- `env`: Environment variables specific to this target (optional, overrides agent-level env vars with the same name)
+
+### Optional Fields
+
+You can also optionally specify at the agent server level:
+
+- `env`: Environment variables to set in the agent's spawned process. These apply to all targets by default.
+- `icon`: Path to an SVG icon (relative to extension root) for display in menus.
+
+### Environment Variables
+
+Environment variables can be configured at two levels:
+
+1. **Agent-level** (`[agent_servers.my-agent.env]`): Variables that apply to all platforms
+2. **Target-level** (`[agent_servers.my-agent.targets.{platform}.env]`): Variables specific to a platform
+
+When both are specified, target-level environment variables override agent-level variables with the same name. Variables defined only at the agent level are inherited by all targets.
+
+### Complete Example
+
+Here's a more complete example with all optional fields:
+
+```toml
+[agent_servers.example-agent]
+name = "Example Agent"
+icon = "icon/agent.svg"
+
+[agent_servers.example-agent.env]
+AGENT_LOG_LEVEL = "info"
+AGENT_MODE = "production"
+
+[agent_servers.example-agent.targets.darwin-aarch64]
+archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-darwin-arm64.tar.gz"
+cmd = "./bin/agent"
+args = ["serve", "--port", "8080"]
+sha256 = "abc123def456..."
+
+[agent_servers.example-agent.targets.linux-x86_64]
+archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-linux-x64.tar.gz"
+cmd = "./bin/agent"
+args = ["serve", "--port", "8080"]
+sha256 = "def456abc123..."
+
+[agent_servers.example-agent.targets.linux-x86_64.env]
+AGENT_MEMORY_LIMIT = "2GB"  # Linux-specific override
+```
+
+## Installation Process
+
+When a user installs your extension and selects the agent server:
+
+1. Zed downloads the appropriate archive for the user's platform
+2. The archive is extracted to a cache directory
+3. Zed launches the agent using the specified command and arguments
+4. Environment variables are set as configured
+5. The agent server runs in the background, ready to assist the user
+
+Archives are cached locally, so subsequent launches are fast.
+
+## Distribution Best Practices
+
+### Use GitHub Releases
+
+GitHub Releases are a reliable way to distribute agent server binaries:
+
+1. Build your agent for each platform (macOS ARM64, macOS x86_64, Linux x86_64, Windows x86_64)
+2. Package each build as a compressed archive (`.tar.gz` or `.zip`)
+3. Create a GitHub release and upload the archives
+4. Use the release URLs in your `extension.toml`
+
+## SHA-256 Hashes
+
+For better supply-chain security, include SHA-256 hashes of your archives in `extension.toml`. Here's how to generate one:
+
+### macOS and Linux
+
+```bash
+shasum -a 256 agent-darwin-arm64.tar.gz
+```
+
+### Windows
+
+```bash
+certutil -hashfile agent-windows-x64.zip SHA256
+```
+
+Then add that string to your target configuration:
+
+```toml
+[agent_servers.my-agent.targets.darwin-aarch64]
+archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
+cmd = "./agent"
+sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+```
+
+## Testing
+
+To test your Agent Server Extension:
+
+1. [Install it as a dev extension](./developing-extensions.md#developing-an-extension-locally)
+2. Open the [Agent Panel](../ai/agent-panel.md)
+3. Select your Agent Server from the list
+4. Verify that it downloads, installs, and launches correctly
+5. Test its functionality by conversing with it and watching the [ACP logs](../ai/external-agents.md#debugging-agents)
+
+## Icon Guideline
+
+If your agent server has a logo, add it as an SVG icon.
+For consistent rendering, follow these guidelines:
+
+- Resize your SVG to fit a 16x16 bounding box with around one or two pixels of padding
+- Keep the SVG markup clean by processing it through [SVGOMG](https://jakearchibald.github.io/svgomg/)
+- Avoid gradients, which often increase SVG complexity and can render inconsistently
+
+Note that we'll automatically convert your icon to monochrome to preserve Zed's design consistency.
+(You can still use opacity in different paths of your SVG to add visual layering.)
+
+## Publishing
+
+Once your extension is ready, see [Publishing your extension](./developing-extensions.md#publishing-your-extension) to learn how to submit it to the Zed extension registry.

docs/src/extensions/capabilities.md

@@ -0,0 +1,101 @@
+---
+title: Extension Capabilities
+description: "Extension Capabilities for Zed extensions."
+---
+
+# Extension Capabilities
+
+The operations that Zed extensions are able to perform are governed by a capability system.
+
+## Restricting capabilities
+
+As a user, you have the option of restricting the capabilities that are granted to extensions.
+
+This is controlled via the `granted_extension_capabilities` setting.
+
+Restricting or removing a capability will cause an error to be returned when an extension attempts to call the corresponding extension API without sufficient capabilities.
+
+For example, to restrict downloads to files from GitHub, set `host` for the `download_file` capability:
+
+```diff
+{
+  "granted_extension_capabilities": [
+    { "kind": "process:exec", "command": "*", "args": ["**"] },
+-   { "kind": "download_file", "host": "*", "path": ["**"] },
++   { "kind": "download_file", "host": "github.com", "path": ["**"] },
+    { "kind": "npm:install", "package": "*" }
+  ]
+}
+```
+
+If you don't want extensions to be able to perform _any_ capabilities, you can remove all granted capabilities:
+
+```json
+{
+  "granted_extension_capabilities": []
+}
+```
+
+> Note that this will likely make many extensions non-functional, at least in their default configuration.
+
+## Capabilities
+
+### `process:exec`
+
+The `process:exec` capability grants extensions the ability to invoke commands using [`zed_extension_api::process::Command`](https://docs.rs/zed_extension_api/latest/zed_extension_api/process/struct.Command.html).
+
+#### Examples
+
+To allow any command to be executed with any arguments:
+
+```toml
+{ kind = "process:exec", command = "*", args = ["**"] }
+```
+
+To allow a specific command (e.g., `gem`) to be executed with any arguments:
+
+```toml
+{ kind = "process:exec", command = "gem", args = ["**"] }
+```
+
+### `download_file`
+
+The `download_file` capability grants extensions the ability to download files using [`zed_extension_api::download_file`](https://docs.rs/zed_extension_api/latest/zed_extension_api/fn.download_file.html).
+
+#### Examples
+
+To allow any file to be downloaded:
+
+```toml
+{ kind = "download_file", host = "*", path = ["**"] }
+```
+
+To allow any file to be downloaded from `github.com`:
+
+```toml
+{ kind = "download_file", host = "github.com", path = ["**"] }
+```
+
+To allow any file to be downloaded from a specific GitHub repository:
+
+```toml
+{ kind = "download_file", host = "github.com", path = ["zed-industries", "zed", "**"] }
+```
+
+### `npm:install`
+
+The `npm:install` capability grants extensions the ability to install npm packages using [`zed_extension_api::npm_install_package`](https://docs.rs/zed_extension_api/latest/zed_extension_api/fn.npm_install_package.html).
+
+#### Examples
+
+To allow any npm package to be installed:
+
+```toml
+{ kind = "npm:install", package = "*" }
+```
+
+To allow a specific npm package (e.g., `typescript`) to be installed:
+
+```toml
+{ kind = "npm:install", package = "typescript" }
+```

docs/src/extensions/debugger-extensions.md

@@ -0,0 +1,122 @@
+---
+title: Debugger Extensions
+description: "Debugger Extensions for Zed extensions."
+---
+
+# Debugger Extensions
+
+[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol) Servers can be exposed as extensions for use in the [debugger](../debugger.md).
+
+## Defining Debugger Extensions
+
+A given extension may provide one or more DAP servers.
+Each DAP server must be registered in the `extension.toml`:
+
+```toml
+[debug_adapters.my-debug-adapter]
+# Optional relative path to the JSON schema for the debug adapter configuration schema. Defaults to `debug_adapter_schemas/$DEBUG_ADAPTER_NAME_ID.json`.
+# Note that while this field is optional, a schema is mandatory.
+schema_path = "relative/path/to/schema.json"
+```
+
+Then, in the Rust code for your extension, implement the `get_dap_binary` method on your extension:
+
+```rust
+impl zed::Extension for MyExtension {
+    fn get_dap_binary(
+        &mut self,
+        adapter_name: String,
+        config: DebugTaskDefinition,
+        user_provided_debug_adapter_path: Option<String>,
+        worktree: &Worktree,
+    ) -> Result<DebugAdapterBinary, String>;
+}
+```
+
+This method should return the command to start up a debug adapter protocol server, along with any arguments or environment variables necessary for it to function.
+
+If you need to download the DAP server from an external source (GitHub Releases, npm, etc.), you can also do that in this function. Make sure to check for updates only periodically, as this function is called whenever a user spawns a new debug session with your debug adapter.
+
+You must also implement `dap_request_kind`. This function is used to determine whether a given debug scenario will _launch_ a new debuggee or _attach_ to an existing one.
+We also use it to determine that a given debug scenario requires running a _locator_.
+
+```rust
+impl zed::Extension for MyExtension {
+    fn dap_request_kind(
+        &mut self,
+        _adapter_name: String,
+        _config: Value,
+    ) -> Result<StartDebuggingRequestArgumentsRequest, String>;
+}
+```
+
+These two functions are sufficient to expose your debug adapter in `debug.json`-based user workflows, but you should strongly consider implementing `dap_config_to_scenario` as well.
+
+```rust
+impl zed::Extension for MyExtension {
+    fn dap_config_to_scenario(
+        &mut self,
+        _adapter_name: DebugConfig,
+    ) -> Result<DebugScenario, String>;
+}
+```
+
+`dap_config_to_scenario` is used when the user spawns a session via new process modal UI. At a high level, it takes a generic debug configuration (that isn't specific to any
+debug adapter) and tries to turn it into a concrete debug scenario for your adapter.
+Put another way, it is supposed to answer the question: "Given a program, a list of arguments, current working directory and environment variables, what would the configuration for spawning this debug adapter look like?".
+
+## Defining Debug Locators
+
+Zed offers an automatic way to create debug scenarios with _debug locators_.
+A locator locates the debug target and figures out how to spawn a debug session for it. Thanks to locators, we can automatically convert existing user tasks (e.g. `cargo run`) and convert them into debug scenarios (e.g. `cargo build` followed by spawning a debugger with `target/debug/my_program` as the program to debug).
+
+> Your extension can define its own debug locators even if it does not expose a debug adapter. We strongly recommend doing so when your extension already exposes language tasks, as it allows users to spawn a debug session without having to manually configure the debug adapter.
+
+Locators can (but don't have to) be agnostic to the debug adapter they are used with. They are responsible for locating the debug target and figuring out how to spawn a debug session for it. This lets extensions share locator logic across adapters.
+
+Your extension can define one or more debug locators. Each debug locator must be registered in the `extension.toml`:
+
+```toml
+[debug_locators.my-debug-locator]
+```
+
+Locators have two components.
+First, each locator is ran on each available task to figure out if any of the available locators can provide a debug scenario for a given task. This is done by calling `dap_locator_create_scenario`.
+
+```rust
+impl zed::Extension for MyExtension {
+    fn dap_locator_create_scenario(
+        &mut self,
+        _locator_name: String,
+        _build_task: TaskTemplate,
+        _resolved_label: String,
+        _debug_adapter_name: String,
+    ) -> Option<DebugScenario>;
+}
+```
+
+This function should return `Some` debug scenario when that scenario defines a debugging counterpart to a given user task.
+Note that a `DebugScenario` can include a [build task](../debugger.md#build-tasks). If there is one, we will execute `run_dap_locator` after a build task is finished successfully.
+
+```rust
+impl zed::Extension for MyExtension {
+    fn run_dap_locator(
+        &mut self,
+        _locator_name: String,
+        _build_task: TaskTemplate,
+    ) -> Result<DebugRequest, String>;
+}
+```
+
+`run_dap_locator` is useful in case you cannot determine a build target deterministically. Some build systems may produce artifacts whose names are not known up-front.
+Note however that you do _not_ need to go through a 2-phase resolution; if you can determine the full debug configuration with just `dap_locator_create_scenario`, you can omit `build` property on a returned `DebugScenario`. Please also note that your locator **will be** called with tasks it's unlikely to accept; thus you should take some effort to return `None` early before performing any expensive operations.
+
+## Available Extensions
+
+See DAP servers published as extensions [on Zed's site](https://zed.dev/extensions?filter=debug-adapters).
+
+Review their repositories to see common implementation patterns and structure.
+
+## Testing
+
+To test your new Debug Adapter Protocol server extension, you can [install it as a dev extension](./developing-extensions.md#developing-an-extension-locally).

docs/src/extensions/developing-extensions.md

@@ -0,0 +1,223 @@
+---
+title: Developing Extensions
+description: "Create Zed extensions: languages, themes, debuggers, and more."
+---
+
+# Developing Extensions {#developing-extensions}
+
+Zed extensions are Git repositories containing an `extension.toml` manifest. They can provide languages, themes, debuggers, snippets, and MCP servers.
+
+## Extension Features {#extension-features}
+
+Extensions can provide:
+
+- [Languages](./languages.md)
+- [Debuggers](./debugger-extensions.md)
+- [Themes](./themes.md)
+- [Icon Themes](./icon-themes.md)
+- [Snippets](./snippets.md)
+- [MCP Servers](./mcp-extensions.md)
+
+## Developing an Extension Locally
+
+Before starting to develop an extension for Zed, be sure to [install Rust via rustup](https://www.rust-lang.org/tools/install).
+
+> Rust must be installed via rustup. If you have Rust installed via homebrew or otherwise, installing dev extensions will not work.
+
+When developing an extension, you can use it in Zed without needing to publish it by installing it as a _dev extension_.
+
+From the extensions page, click the `Install Dev Extension` button (or the {#action zed::InstallDevExtension} action) and select the directory containing your extension.
+
+If you need to troubleshoot, check Zed.log ({#action zed::OpenLog}) for additional output. For debug output, close and relaunch Zed from the command line with `zed --foreground`, which shows more verbose INFO-level logs.
+
+If you already have the published version of the extension installed, the published version will be uninstalled prior to the installation of the dev extension. After successful installation, the `Extensions` page will indicate that the upstream extension is "Overridden by dev extension".
+
+## Directory Structure of a Zed Extension
+
+A Zed extension is a Git repository that contains an `extension.toml`. This file must contain some
+basic information about the extension:
+
+```toml
+id = "my-extension"
+name = "My extension"
+version = "0.0.1"
+schema_version = 1
+authors = ["Your Name <you@example.com>"]
+description = "Example extension"
+repository = "https://github.com/your-name/my-zed-extension"
+```
+
+In addition to this, there are several other optional files and directories that can be used to add functionality to a Zed extension. An example directory structure of an extension that provides all capabilities is as follows:
+
+```
+my-extension/
+  extension.toml
+  Cargo.toml
+  src/
+    lib.rs
+  languages/
+    my-language/
+      config.toml
+      highlights.scm
+  themes/
+    my-theme.json
+  snippets/
+    snippets.json
+    rust.json
+```
+
+## WebAssembly
+
+Procedural parts of extensions are written in Rust and compiled to WebAssembly. To develop an extension that includes custom code, include a `Cargo.toml` like this:
+
+```toml
+[package]
+name = "my-extension"
+version = "0.0.1"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+zed_extension_api = "0.1.0"
+```
+
+Use the latest version of the [`zed_extension_api`](https://crates.io/crates/zed_extension_api) available on crates.io. Make sure it's still [compatible with Zed versions](https://github.com/zed-industries/zed/blob/main/crates/extension_api#compatible-zed-versions) you want to support.
+
+In the `src/lib.rs` file in your Rust crate you will need to define a struct for your extension and implement the `Extension` trait, as well as use the `register_extension!` macro to register your extension:
+
+```rs
+use zed_extension_api as zed;
+
+struct MyExtension {
+    // ... state
+}
+
+impl zed::Extension for MyExtension {
+    // ...
+}
+
+zed::register_extension!(MyExtension);
+```
+
+> `stdout`/`stderr` is forwarded directly to the Zed process. In order to see `println!`/`dbg!` output from your extension, you can start Zed in your terminal with a `--foreground` flag.
+
+## Forking and cloning the repo
+
+1. Fork the repo
+
+> **Note:** It is very helpful if you fork the `zed-industries/extensions` repo to a personal GitHub account instead of a GitHub organization, as this allows Zed staff to push any needed changes to your PR to expedite the publishing process.
+
+2. Clone the repo to your local machine
+
+```sh
+# Substitute the url of your fork here:
+# git clone https://github.com/zed-industries/extensions
+cd extensions
+git submodule init
+git submodule update
+```
+
+## Extension License Requirements
+
+As of October 1st, 2025, extension repositories must include a license.
+The following licenses are accepted:
+
+- [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+- [BSD 2-Clause](https://opensource.org/license/bsd-2-clause)
+- [BSD 3-Clause](https://opensource.org/license/bsd-3-clause)
+- [CC BY 4.0](https://creativecommons.org/licenses/by/4.0)
+- [GNU GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html)
+- [GNU LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.en.html)
+- [MIT](https://opensource.org/license/mit)
+- [Unlicense](https://unlicense.org)
+- [zlib](https://opensource.org/license/zlib)
+
+This allows us to distribute the resulting binary produced from your extension code to our users.
+Without a valid license, the pull request to add or update your extension in the following steps will fail CI.
+
+Your license file should be at the root of your extension repository. Any filename that has `LICENCE` or `LICENSE` as a prefix (case insensitive) will be inspected to ensure it matches one of the accepted licenses. See the [license validation source code](https://github.com/zed-industries/extensions/blob/main/src/lib/license.js).
+
+> This license requirement applies only to your extension code itself (the code that gets compiled into the extension binary).
+> It does not apply to any tools your extension may download or interact with, such as language servers or other external dependencies.
+> If your repository contains both extension code and other projects (like a language server), you are not required to relicense those other projects — only the extension code needs to be one of the aforementioned accepted licenses.
+
+## Extension Publishing Prerequisites
+
+Before publishing your extension, make sure that you have chosen a unique extension ID for your extension in the [extension manifest](#directory-structure-of-a-zed-extension).
+This will be the primary identifier for your extension and cannot be changed after your extension has been published.
+Also, ensure that you have filled out all the required fields in the manifest.
+
+Furthermore, please make sure that your extension fulfills the following preconditions before you move on to publishing your extension:
+
+- Extension IDs and names must not contain the words `zed`, `Zed` or `extension`, since they are all Zed extensions.
+- Your extension ID should provide some information on what your extension tries to accomplish. E.g. for themes, it should be suffixed with `-theme`, snippet extensions should be suffixed with `-snippets` and so on. An exception to that rule are extension that provide support for languages or popular tooling that people would expect to find under that ID. You can take a look at the list of [existing extensions](https://github.com/zed-industries/extensions/blob/main/extensions.toml) to get a grasp on how this usually is enforced.
+- Extensions should provide something that is not yet available in the marketplace as opposed to fixing something that could be resolved within an existing extension. For example, if you find that an existing extension's support for a language server is not functioning properly, first try contributing a fix to the existing extension as opposed to submitting a new extension immediately.
+  - If you receive no response or reaction within the upstream repository within a reasonable amount of time, feel free to submit a pull request that aims to fix said issue. Please ensure that you provide your previous efforts within the pull request to the extensions repository for adding your extension. Zed maintainers will then decide on how to proceed on a case by case basis.
+- Extensions that intend to provide a language, debugger or MCP server must not ship the language server as part of the extension. Instead, the extension should either download the language server or check for the availability of the language server in the users environment using the APIs as provided by the [Zed Rust Extension API](https://docs.rs/zed_extension_api/latest/zed_extension_api/).
+- Themes and icon themes should not be published as part of extensions that provide other features, e.g. language support. Instead, they should be published as a distinct extension. This also applies to theme and icon themes living in the same repository.
+
+Non-compliance with these rules will be raised during the publishing process by reviewers. If you fail to comply with the laid out guidelines, the publishing of your extension will either be delayed or rejected.
+
+## Publishing your extension
+
+> Prior to publishing your extension, you should have installed as well as tested it locally thoroughly. Furthermore, you should have read the [prerequisites above](#extension-publishing-prerequisites). Note that untested extension submissions where the extension is not functioning at all will be closed eagerly without further feedback.
+
+To publish an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
+
+In your PR, do the following:
+
+1. Add your extension as a Git submodule within the `extensions/` directory under the `extensions/{extension-id}` path
+
+```sh
+git submodule add https://github.com/your-username/foobar-zed.git extensions/my-extension
+git add extensions/my-extension
+```
+
+> All extension submodules must use HTTPS URLs and not SSH URLS (`git@github.com`). Furthermore, your extension repository must be publicly available and the checked out submodule commit must be on a branch and thus not be detached commit.
+
+2. Add a new entry to the top-level `extensions.toml` file containing your extension:
+
+```toml
+[my-extension]
+submodule = "extensions/my-extension"
+version = "0.0.1"
+```
+
+If your extension is in a subdirectory within the submodule, you can use the `path` field to point to where the extension resides:
+
+```toml
+[my-extension]
+submodule = "extensions-my-extension"
+path = "packages/zed"
+version = "0.0.1"
+```
+
+> Note that the [required extension license](#extension-license-requirements) must reside at the specified path, a license at the root of the repository will not work. However, you are free to symlink an existing license within the repository or choose an alternative license from the list of accepted licenses for the extension code.
+
+3. Run `pnpm sort-extensions` to ensure `extensions.toml` and `.gitmodules` are sorted
+
+Once your PR is merged, the extension will be packaged and published to the Zed extension registry.
+
+## Updating an extension
+
+To update an extension, open a PR to [the `zed-industries/extensions` repo](https://github.com/zed-industries/extensions).
+
+In your PR do the following:
+
+1. Update the extension's submodule to the commit of the new version. For this, you can run
+
+```sh
+# From the root of the repository:
+git submodule update --remote extensions/your-extension-name
+```
+
+to update your extension to the latest commit available in your remote repository.
+
+2. Update the `version` field for the extension in `extensions.toml`
+   - Make sure the `version` matches the one set in `extension.toml` at the particular commit.
+
+If you'd like to automate this process, there is a [community GitHub Action](https://github.com/huacnlee/zed-extension-action) you can use.
+
+> **Note:** If your extension repository has a different license, you'll need to update it to be one of the [accepted extension licenses](#extension-license-requirements) before publishing your update.

docs/src/extensions/icon-themes.md

@@ -0,0 +1,83 @@
+---
+title: Icon Themes
+description: "Icon Themes for Zed extensions."
+---
+
+# Icon Themes
+
+Extensions may provide icon themes to change the icons Zed uses for folders and files.
+
+## Example extension
+
+The [Material Icon Theme](https://github.com/zed-extensions/material-icon-theme) serves as an example for the structure of an extension containing an icon theme.
+
+## Directory structure
+
+There are two important directories for an icon theme extension:
+
+- `icon_themes`: This directory will contain one or more JSON files containing the icon theme definitions.
+- `icons`: This directory contains the icon assets distributed with the extension. You can create subdirectories in this directory as needed.
+
+Each icon theme file should adhere to the JSON schema specified at [`https://zed.dev/schema/icon_themes/v0.3.0.json`](https://zed.dev/schema/icon_themes/v0.3.0.json).
+
+Here is an example icon theme structure:
+
+```json [icon-theme]
+{
+  "$schema": "https://zed.dev/schema/icon_themes/v0.3.0.json",
+  "name": "My Icon Theme",
+  "author": "Your Name",
+  "themes": [
+    {
+      "name": "My Icon Theme",
+      "appearance": "dark",
+      "directory_icons": {
+        "collapsed": "./icons/folder.svg",
+        "expanded": "./icons/folder-open.svg"
+      },
+      "named_directory_icons": {
+        "stylesheets": {
+          "collapsed": "./icons/folder-stylesheets.svg",
+          "expanded": "./icons/folder-stylesheets-open.svg"
+        }
+      },
+      "chevron_icons": {
+        "collapsed": "./icons/chevron-right.svg",
+        "expanded": "./icons/chevron-down.svg"
+      },
+      "file_stems": {
+        "Makefile": "make"
+      },
+      "file_suffixes": {
+        "mp3": "audio",
+        "rs": "rust"
+      },
+      "file_icons": {
+        "audio": { "path": "./icons/audio.svg" },
+        "default": { "path": "./icons/file.svg" },
+        "make": { "path": "./icons/make.svg" },
+        "rust": { "path": "./icons/rust.svg" }
+        // ...
+      }
+    }
+  ]
+}
+```
+
+Each icon path is resolved relative to the root of the extension directory.
+
+In this example, the extension would have this structure:
+
+```
+extension.toml
+icon_themes/
+  my-icon-theme.json
+icons/
+  audio.svg
+  chevron-down.svg
+  chevron-right.svg
+  file.svg
+  folder-open.svg
+  folder.svg
+  rust.svg
+```

docs/src/extensions/installing-extensions.md

@@ -0,0 +1,25 @@
+---
+title: Installing Extensions
+description: "Browse, install, and manage extensions from the Zed Extension Gallery."
+---
+
+# Installing Extensions {#installing-extensions}
+
+Extensions add functionality to Zed, including languages, themes, and AI tools. Browse and install them from the Extension Gallery.
+
+Open the Extension Gallery with {#kb zed::Extensions}, or select "Zed > Extensions" from the menu bar.
+
+## Installation Location
+
+- On macOS, extensions are installed in `~/Library/Application Support/Zed/extensions`.
+- On Linux, they are installed in either `$XDG_DATA_HOME/zed/extensions` or `~/.local/share/zed/extensions`.
+- On Windows, the directory is `%LOCALAPPDATA%\Zed\extensions`.
+
+This directory contains two subdirectories:
+
+- `installed`, which contains the source code for each extension.
+- `work` which contains files created by the extension itself, such as downloaded language servers.
+
+## Auto-installing
+
+To automate extension installation/uninstallation see the docs for [auto_install_extensions](../reference/all-settings.md#auto-install-extensions).

docs/src/extensions/languages.md

@@ -0,0 +1,550 @@
+---
+title: Language Extensions
+description: "Overview of programming language support in Zed, including built-in and extension-based languages."
+---
+
+# Language Extensions
+
+Language support in Zed has several components:
+
+- Language metadata and configuration
+- Grammar
+- Queries
+- Language servers
+
+## Language Metadata
+
+Each language supported by Zed must be defined in a subdirectory inside the `languages` directory of your extension.
+
+This subdirectory must contain a file called `config.toml` file with the following structure:
+
+```toml
+name = "My Language"
+grammar = "my-language"
+path_suffixes = ["myl"]
+line_comments = ["# "]
+```
+
+- `name` (required) is the human readable name that will show up in the Select Language dropdown.
+- `grammar` (required) is the name of a grammar. Grammars are registered separately, described below.
+- `path_suffixes` is an array of file suffixes that should be associated with this language. Unlike `file_types` in settings, this does not support glob patterns.
+- `line_comments` is an array of strings that are used to identify line comments in the language. This is used for the `editor::ToggleComments` keybind: {#kb editor::ToggleComments} for toggling lines of code.
+- `tab_size` defines the indentation/tab size used for this language (default is `4`).
+- `hard_tabs` whether to indent with tabs (`true`) or spaces (`false`, the default).
+- `first_line_pattern` is a regular expression that can be used alongside `path_suffixes` (above) or `file_types` in settings to match files that should use this language. For example, Zed uses this to identify Shell Scripts by matching [shebang lines](https://github.com/zed-industries/zed/blob/main/crates/languages/src/bash/config.toml) in the first line of a script.
+- `debuggers` is an array of strings that are used to identify debuggers in the language. When launching a debugger's `New Process Modal`, Zed will order available debuggers by the order of entries in this array.
+
+<!--
+TBD: Document `language_name/config.toml` keys
+
+- autoclose_before
+- brackets (start, end, close, newline, not_in: ["comment", "string"])
+- word_characters
+- prettier_parser_name
+- opt_into_language_servers
+- code_fence_block_name
+- scope_opt_in_language_servers
+- increase_indent_pattern, decrease_indent_pattern
+- collapsed_placeholder
+- auto_indent_on_paste, auto_indent_using_last_non_empty_line
+- overrides: `[overrides.element]`, `[overrides.string]`
+-->
+
+## Grammar
+
+Zed uses the [Tree-sitter](https://tree-sitter.github.io) parsing library to provide built-in language-specific features. There are grammars available for many languages, and you can also [develop your own grammar](https://tree-sitter.github.io/tree-sitter/creating-parsers/3-writing-the-grammar.html). A growing list of Zed features are built using pattern matching over syntax trees with Tree-sitter queries. As mentioned above, every language that is defined in an extension must specify the name of a Tree-sitter grammar that is used for parsing. These grammars are then registered separately in extensions' `extension.toml` file, like this:
+
+```toml
+[grammars.gleam]
+repository = "https://github.com/gleam-lang/tree-sitter-gleam"
+rev = "58b7cac8fc14c92b0677c542610d8738c373fa81"
+```
+
+The `repository` field must specify a repository where the Tree-sitter grammar should be loaded from, and the `rev` field must contain a Git revision to use, such as the SHA of a Git commit. If you're developing an extension locally and want to load a grammar from the local filesystem, you can use a `file://` URL for `repository`. An extension can provide multiple grammars by referencing multiple tree-sitter repositories.
+
+## Tree-sitter Queries
+
+Zed uses the syntax tree produced by the [Tree-sitter](https://tree-sitter.github.io) query language to implement
+several features:
+
+- Syntax highlighting
+- Bracket matching
+- Code outline/structure
+- Auto-indentation
+- Code injections
+- Syntax overrides
+- Text redactions
+- Runnable code detection
+- Selecting classes, functions, etc.
+
+The following sections elaborate on how [Tree-sitter queries](https://tree-sitter.github.io/tree-sitter/using-parsers/queries/index.html) enable these
+features in Zed, using [JSON syntax](https://www.json.org/json-en.html) as a guiding example.
+
+### Syntax highlighting
+
+In Tree-sitter, the `highlights.scm` file defines syntax highlighting rules for a particular syntax.
+
+Here's an example from a `highlights.scm` for JSON:
+
+```scheme
+(string) @string
+
+(pair
+  key: (string) @property.json_key)
+
+(number) @number
+```
+
+This query marks strings, object keys, and numbers for highlighting. The following is the full list of captures supported by themes:
+
+| Capture                  | Description                            |
+| ------------------------ | -------------------------------------- |
+| @attribute               | Captures attributes                    |
+| @boolean                 | Captures boolean values                |
+| @comment                 | Captures comments                      |
+| @comment.doc             | Captures documentation comments        |
+| @constant                | Captures constants                     |
+| @constant.builtin        | Captures built-in constants            |
+| @constructor             | Captures constructors                  |
+| @embedded                | Captures embedded content              |
+| @emphasis                | Captures emphasized text               |
+| @emphasis.strong         | Captures strongly emphasized text      |
+| @enum                    | Captures enumerations                  |
+| @function                | Captures functions                     |
+| @hint                    | Captures hints                         |
+| @keyword                 | Captures keywords                      |
+| @label                   | Captures labels                        |
+| @link_text               | Captures link text                     |
+| @link_uri                | Captures link URIs                     |
+| @number                  | Captures numeric values                |
+| @operator                | Captures operators                     |
+| @predictive              | Captures predictive text               |
+| @preproc                 | Captures preprocessor directives       |
+| @primary                 | Captures primary elements              |
+| @property                | Captures properties                    |
+| @punctuation             | Captures punctuation                   |
+| @punctuation.bracket     | Captures brackets                      |
+| @punctuation.delimiter   | Captures delimiters                    |
+| @punctuation.list_marker | Captures list markers                  |
+| @punctuation.special     | Captures special punctuation           |
+| @string                  | Captures string literals               |
+| @string.escape           | Captures escaped characters in strings |
+| @string.regex            | Captures regular expressions           |
+| @string.special          | Captures special strings               |
+| @string.special.symbol   | Captures special symbols               |
+| @tag                     | Captures tags                          |
+| @tag.doctype             | Captures doctypes (e.g., in HTML)      |
+| @text.literal            | Captures literal text                  |
+| @title                   | Captures titles                        |
+| @type                    | Captures types                         |
+| @type.builtin            | Captures built-in types                |
+| @variable                | Captures variables                     |
+| @variable.special        | Captures special variables             |
+| @variable.parameter      | Captures function/method parameters    |
+| @variant                 | Captures variants                      |
+
+#### Fallback captures
+
+A single Tree-sitter pattern can specify multiple captures on the same node to define fallback highlights.
+Zed resolves them right-to-left: It first tries the rightmost capture, and if the current theme has no style for it, falls back to the next capture to the left, and so on.
+
+For example:
+
+```scheme
+(type_identifier) @type @variable
+```
+
+Here Zed will first try to resolve `@variable` from the theme. If the theme defines a style for `@variable`, that style is used. Otherwise, Zed falls back to `@type`.
+
+This is useful when a language wants to provide a preferred highlight that not all themes may support, while still falling back to a more common capture that most themes define.
+
+### Bracket matching
+
+The `brackets.scm` file defines matching brackets.
+
+Here's an example from a `brackets.scm` file for JSON:
+
+```scheme
+("[" @open "]" @close)
+("{" @open "}" @close)
+("\"" @open "\"" @close)
+```
+
+This query identifies opening and closing brackets, braces, and quotation marks.
+
+| Capture | Description                                   |
+| ------- | --------------------------------------------- |
+| @open   | Captures opening brackets, braces, and quotes |
+| @close  | Captures closing brackets, braces, and quotes |
+
+Zed uses these to highlight matching brackets: painting each bracket pair with a different color ("rainbow brackets") and highlighting the brackets if the cursor is inside the bracket pair.
+
+To opt out of rainbow brackets colorization, add the following to the corresponding `brackets.scm` entry:
+
+```scheme
+(("\"" @open "\"" @close) (#set! rainbow.exclude))
+```
+
+### Code outline/structure
+
+The `outline.scm` file defines the structure for the code outline.
+
+Here's an example from an `outline.scm` file for JSON:
+
+```scheme
+(pair
+  key: (string (string_content) @name)) @item
+```
+
+This query captures object keys for the outline structure.
+
+| Capture        | Description                                                                          |
+| -------------- | ------------------------------------------------------------------------------------ |
+| @name          | Captures the content of object keys                                                  |
+| @item          | Captures the entire key-value pair                                                   |
+| @context       | Captures elements that provide context for the outline item                          |
+| @context.extra | Captures additional contextual information for the outline item                      |
+| @annotation    | Captures nodes that annotate outline item (doc comments, attributes, decorators)[^1] |
+
+[^1]: These annotations are used by Assistant when generating code modification steps.
+
+### Auto-indentation
+
+The `indents.scm` file defines indentation rules.
+
+Here's an example from an `indents.scm` file for JSON:
+
+```scheme
+(array "]" @end) @indent
+(object "}" @end) @indent
+```
+
+This query marks the end of arrays and objects for indentation purposes.
+
+| Capture | Description                                        |
+| ------- | -------------------------------------------------- |
+| @end    | Captures closing brackets and braces               |
+| @indent | Captures entire arrays and objects for indentation |
+
+### Code injections
+
+The `injections.scm` file defines rules for embedding one language within another, such as code blocks in Markdown or SQL queries in Python strings.
+
+Here's an example from an `injections.scm` file for Markdown:
+
+```scheme
+(fenced_code_block
+  (info_string
+    (language) @injection.language)
+  (code_fence_content) @injection.content)
+
+((inline) @content
+ (#set! injection.language "markdown-inline"))
+```
+
+This query identifies fenced code blocks, capturing the language specified in the info string and the content within the block. It also captures inline content and sets its language to "markdown-inline".
+
+| Capture             | Description                                                |
+| ------------------- | ---------------------------------------------------------- |
+| @injection.language | Captures the language identifier for a code block          |
+| @injection.content  | Captures the content to be treated as a different language |
+
+Note that we couldn't use JSON as an example here because it doesn't support language injections.
+
+### Syntax overrides
+
+The `overrides.scm` file defines syntactic _scopes_ that can be used to override certain editor settings within specific language constructs.
+
+For example, there is a language-specific setting called `word_characters` that controls which non-alphabetic characters are considered part of a word, for example when you double click to select a variable. In JavaScript, "$" and "#" are considered word characters.
+
+There is also a language-specific setting called `completion_query_characters` that controls which characters trigger autocomplete suggestions. In JavaScript, when your cursor is within a _string_, `-` should be considered a completion query character. To achieve this, the JavaScript `overrides.scm` file contains the following pattern:
+
+```scheme
+[
+  (string)
+  (template_string)
+] @string
+```
+
+And the JavaScript `config.toml` contains this setting:
+
+```toml
+word_characters = ["#", "$"]
+
+[overrides.string]
+completion_query_characters = ["-"]
+```
+
+You can also disable certain auto-closing brackets in a specific scope. For example, to prevent auto-closing `'` within strings, you could put the following in the JavaScript `config.toml`:
+
+```toml
+brackets = [
+  { start = "'", end = "'", close = true, newline = false, not_in = ["string"] },
+  # other pairs...
+]
+```
+
+#### Range inclusivity
+
+By default, the ranges defined in `overrides.scm` are _exclusive_. So in the case above, if your cursor was _outside_ the quotation marks delimiting the string, the `string` scope would not take effect. Sometimes, you may want to make the range _inclusive_. You can do this by adding the `.inclusive` suffix to the capture name in the query.
+
+For example, in JavaScript, we also disable auto-closing of single quotes within comments. And the comment scope must extend all the way to the newline after a line comment. To achieve this, the JavaScript `overrides.scm` contains the following pattern:
+
+```scheme
+(comment) @comment.inclusive
+```
+
+### Text objects
+
+The `textobjects.scm` file defines rules for navigating by text objects. This was added in Zed v0.165 and is currently used only in Vim mode.
+
+Vim provides two levels of granularity for navigating around files. Section-by-section with `[]` etc., and method-by-method with `]m` etc. Even languages that don't support functions and classes can work well by defining similar concepts. For example CSS defines a rule-set as a method, and a media-query as a class.
+
+For languages with closures, these typically should not count as functions in Zed. This is best-effort, however, because languages like JavaScript do not syntactically differentiate between closures and top-level function declarations.
+
+For languages with declarations like C, provide queries that match `@class.around` or `@function.around`. The `if` and `ic` text objects will default to these if there is no inside.
+
+If you are not sure what to put in textobjects.scm, both [nvim-treesitter-textobjects](https://github.com/nvim-treesitter/nvim-treesitter-textobjects), and the [Helix editor](https://github.com/helix-editor/helix) have queries for many languages. You can refer to the Zed [built-in languages](https://github.com/zed-industries/zed/tree/main/crates/languages/src) to see how to adapt these.
+
+| Capture          | Description                                                             | Vim mode                                         |
+| ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------ |
+| @function.around | An entire function definition or equivalent small section of a file.    | `[m`, `]m`, `[M`,`]M` motions. `af` text object  |
+| @function.inside | The function body (the stuff within the braces).                        | `if` text object                                 |
+| @class.around    | An entire class definition or equivalent large section of a file.       | `[[`, `]]`, `[]`, `][` motions. `ac` text object |
+| @class.inside    | The contents of a class definition.                                     | `ic` text object                                 |
+| @comment.around  | An entire comment (e.g. all adjacent line comments, or a block comment) | `gc` text object                                 |
+| @comment.inside  | The contents of a comment                                               | `igc` text object (rarely supported)             |
+
+For example:
+
+```scheme
+; include only the content of the method in the function
+(method_definition
+    body: (_
+        "{"
+        (_)* @function.inside
+        "}")) @function.around
+
+; match function.around for declarations with no body
+(function_signature_item) @function.around
+
+; join all adjacent comments into one
+(comment)+ @comment.around
+```
+
+### Text redactions
+
+The `redactions.scm` file defines text redaction rules. When collaborating and sharing your screen, it makes sure that certain syntax nodes are rendered in a redacted mode to avoid them from leaking.
+
+Here's an example from a `redactions.scm` file for JSON:
+
+```scheme
+(pair value: (number) @redact)
+(pair value: (string) @redact)
+(array (number) @redact)
+(array (string) @redact)
+```
+
+This query marks number and string values in key-value pairs and arrays for redaction.
+
+| Capture | Description                    |
+| ------- | ------------------------------ |
+| @redact | Captures values to be redacted |
+
+### Runnable code detection
+
+The `runnables.scm` file defines rules for detecting runnable code.
+
+Here's an example from a `runnables.scm` file for JSON:
+
+```scheme
+(
+    (document
+        (object
+            (pair
+                key: (string
+                    (string_content) @_name
+                    (#eq? @_name "scripts")
+                )
+                value: (object
+                    (pair
+                        key: (string (string_content) @run @script)
+                    )
+                )
+            )
+        )
+    )
+    (#set! tag package-script)
+    (#set! tag composer-script)
+)
+```
+
+This query detects runnable scripts in package.json and composer.json files.
+
+The `@run` capture specifies where the run button should appear in the editor. Other captures, except those prefixed with an underscore, are exposed as environment variables with a prefix of `ZED_CUSTOM_$(capture_name)` when running the code.
+
+| Capture | Description                                            |
+| ------- | ------------------------------------------------------ |
+| @\_name | Captures the "scripts" key                             |
+| @run    | Captures the script name                               |
+| @script | Also captures the script name (for different purposes) |
+
+<!--
+TBD: `#set! tag`
+-->
+
+## Language Servers
+
+Zed uses the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) to provide advanced language support.
+
+An extension may provide any number of language servers. To provide a language server from your extension, add an entry to your `extension.toml` with the name of your language server and the language(s) it applies to. The entry in the list of `languages` has to match the `name` field from the `config.toml` file for that language:
+
+```toml
+[language_servers.my-language-server]
+name = "My Language LSP"
+languages = ["My Language"]
+```
+
+Then, in the Rust code for your extension, implement the `language_server_command` method on your extension:
+
+```rust
+impl zed::Extension for MyExtension {
+    fn language_server_command(
+        &mut self,
+        language_server_id: &LanguageServerId,
+        worktree: &zed::Worktree,
+    ) -> Result<zed::Command> {
+        Ok(zed::Command {
+            command: get_path_to_language_server_executable()?,
+            args: get_args_for_language_server()?,
+            env: get_env_for_language_server()?,
+        })
+    }
+}
+```
+
+You can customize the handling of the language server using several optional methods in the `Extension` trait. For example, you can control how completions are styled using the `label_for_completion` method. For a complete list of methods, see the [API docs for the Zed extension API](https://docs.rs/zed_extension_api).
+
+### Syntax Highlighting with Semantic Tokens
+
+Zed supports syntax highlighting using semantic tokens from the attached language servers. This is currently disabled by default, but can be enabled in your settings file:
+
+```json [settings]
+{
+  // Enable semantic tokens globally, backed by tree-sitter highlights for each language:
+  "semantic_tokens": "combined",
+  // Or, specify per-language:
+  "languages": {
+    "Rust": {
+      // No tree-sitter, only LSP semantic tokens:
+      "semantic_tokens": "full"
+    }
+  }
+}
+```
+
+The `semantic_tokens` setting accepts the following values:
+
+- `"off"` (default): Do not request semantic tokens from language servers.
+- `"combined"`: Use LSP semantic tokens together with tree-sitter highlighting.
+- `"full"`: Use LSP semantic tokens exclusively, replacing tree-sitter highlighting.
+
+#### Extension-Provided Semantic Token Rules
+
+Language extensions can ship default semantic token rules for their language server's custom token types. To do this, place a `semantic_token_rules.json` file in the language directory alongside `config.toml`:
+
+```
+my-extension/
+  languages/
+    my-language/
+      config.toml
+      highlights.scm
+      semantic_token_rules.json
+```
+
+The file uses the same format as the `semantic_token_rules` array in user settings — a JSON array of rule objects:
+
+```json
+[
+  {
+    "token_type": "lifetime",
+    "style": ["lifetime"]
+  },
+  {
+    "token_type": "builtinType",
+    "style": ["type"]
+  },
+  {
+    "token_type": "selfKeyword",
+    "style": ["variable.special"]
+  }
+]
+```
+
+This is useful when a language server reports custom (non-standard) semantic token types that aren't covered by Zed's built-in default rules. Extension-provided rules act as sensible defaults for that language — users can always override them via `semantic_token_rules` in their settings file, and built-in default rules are only used when neither user nor extension rules match.
+
+#### Customizing Semantic Token Styles
+
+Zed supports customizing the styles used for semantic tokens. You can define rules in your settings file, which customize how semantic tokens get mapped to styles in your theme.
+
+```json [settings]
+{
+  "global_lsp_settings": {
+    "semantic_token_rules": [
+      {
+        // Highlight macros as keywords.
+        "token_type": "macro",
+        "style": ["syntax.keyword"]
+      },
+      {
+        // Highlight unresolved references in bold red.
+        "token_type": "unresolvedReference",
+        "foreground_color": "#c93f3f",
+        "font_weight": "bold"
+      },
+      {
+        // Underline all mutable variables/references/etc.
+        "token_modifiers": ["mutable"],
+        "underline": true
+      }
+    ]
+  }
+}
+```
+
+All rules that match a given `token_type` and `token_modifiers` are applied. Earlier rules take precedence. If no rules match, the token is not highlighted.
+
+Rules are applied in the following priority order (highest to lowest):
+
+1. **User settings** — rules from `semantic_token_rules` in your settings file.
+2. **Extension rules** — rules from `semantic_token_rules.json` in extension language directories.
+3. **Default rules** — Zed's built-in rules for standard LSP token types.
+
+Each rule in the `semantic_token_rules` array is defined as follows:
+
+- `token_type`: The semantic token type as defined by the [LSP specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_semanticTokens). If omitted, the rule matches all token types.
+- `token_modifiers`: A list of semantic token modifiers to match. All modifiers must be present to match.
+- `style`: A list of styles from the current syntax theme to use. The first style found is used. Any settings below override that style.
+- `foreground_color`: The foreground color to use for the token type, in hex format (e.g., `"#ff0000"`).
+- `background_color`: The background color to use for the token type, in hex format (e.g., `"#ff0000"`).
+- `underline`: A boolean or color to underline with, in hex format. If `true`, then the token will be underlined with the text color.
+- `strikethrough`: A boolean or color to strikethrough with, in hex format. If `true`, then the token have a strikethrough with the text color.
+- `font_weight`: One of `"normal"`, `"bold"`.
+- `font_style`: One of `"normal"`, `"italic"`.
+
+### Multi-Language Support
+
+If your language server supports additional languages, you can use `language_ids` to map Zed `languages` to the desired [LSP-specific `languageId`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentItem) identifiers:
+
+```toml
+
+[language-servers.my-language-server]
+name = "Whatever LSP"
+languages = ["JavaScript", "HTML", "CSS"]
+
+[language-servers.my-language-server.language_ids]
+"JavaScript" = "javascript"
+"TSX" = "typescriptreact"
+"HTML" = "html"
+"CSS" = "css"
+```

docs/src/extensions/mcp-extensions.md

@@ -0,0 +1,49 @@
+---
+title: MCP Server Extensions
+description: "MCP Server Extensions for Zed extensions."
+---
+
+# MCP Server Extensions
+
+[Model Context Protocol servers](../ai/mcp.md) can be exposed as extensions for use in the Agent Panel.
+
+## Defining MCP Extensions
+
+A given extension may provide one or more MCP servers.
+Each MCP server must be registered in the `extension.toml`:
+
+```toml
+[context_servers.my-context-server]
+```
+
+Then, in the Rust code for your extension, implement the `context_server_command` method on your extension:
+
+```rust
+impl zed::Extension for MyExtension {
+    fn context_server_command(
+        &mut self,
+        context_server_id: &ContextServerId,
+        project: &zed::Project,
+    ) -> Result<zed::Command> {
+        Ok(zed::Command {
+            command: get_path_to_context_server_executable()?,
+            args: get_args_for_context_server()?,
+            env: get_env_for_context_server()?,
+        })
+    }
+}
+```
+
+This method should return the command to start up an MCP server, along with any arguments or environment variables necessary for it to function.
+
+If you need to download the MCP server from an external source (GitHub Releases, npm, etc.), you can also do that in this function.
+
+## Available Extensions
+
+See MCP servers published as extensions [on Zed's site](https://zed.dev/extensions?filter=context-servers).
+
+Review their repositories to see common implementation patterns and structure.
+
+## Testing
+
+To test your new MCP server extension, you can [install it as a dev extension](./developing-extensions.md#developing-an-extension-locally).

docs/src/extensions/slash-commands.md

@@ -0,0 +1,11 @@
+---
+title: Slash Commands (Removed)
+description: Extension slash commands have been removed from Zed.
+redirect_to: ./mcp-extensions.md
+---
+
+# Slash Commands
+
+Extension-provided slash commands have been removed from Zed.
+
+To extend the Agent Panel with custom tools and context, use [MCP Servers](./mcp-extensions.md) instead.

docs/src/extensions/snippets.md

@@ -0,0 +1,27 @@
+---
+title: Snippets
+description: "Snippets for Zed extensions."
+---
+
+# Snippets
+
+Extensions may provide snippets for one or more languages.
+
+Each file containing snippets can be specified in the `snippets` field of the `extensions.toml` file.
+
+The referenced path must be relative to the `extension.toml`.
+
+## Defining Snippets
+
+A given extension may provide one or more snippets. Each snippet must be registered in the `extension.toml`.
+
+Zed matches snippet files based on the lowercase name of the language (e.g. `rust.json` for Rust).
+You can use `snippets.json` as a file name to define snippets that will be available regardless of the current buffer language.
+
+For example, here is an extension that provides snippets for Rust and TypeScript:
+
+```toml
+snippets = ["./snippets/rust.json", "./snippets/typescript.json"]
+```
+
+For more information on how to create snippets, see the [Snippets documentation](../snippets.md).

docs/src/extensions/themes.md

@@ -0,0 +1,63 @@
+---
+title: Themes
+description: "Themes for Zed extensions."
+---
+
+# Themes
+
+The `themes` directory in an extension should contain one or more theme files.
+
+Each theme file should adhere to the JSON schema specified at [`https://zed.dev/schema/themes/v0.2.0.json`](https://zed.dev/schema/themes/v0.2.0.json).
+
+See [this blog post](https://zed.dev/blog/user-themes-now-in-preview) for additional background on creating themes.
+
+## Theme JSON Structure
+
+The structure of a Zed theme is defined in the [Zed Theme JSON Schema](https://zed.dev/schema/themes/v0.2.0.json).
+
+A Zed theme consists of a Theme Family object including:
+
+- `name`: The name for the theme family
+- `author`: The name of the author of the theme family
+- `themes`: An array of Themes belonging to the theme family
+
+The core components of a Theme object include:
+
+1. Theme Metadata:
+
+   - `name`: The name of the theme
+   - `appearance`: Either "light" or "dark"
+
+2. Style Properties under the `style`, such as:
+
+   - `background`: The main background color
+   - `foreground`: The main text color
+   - `accent`: The accent color used for highlighting and emphasis
+
+3. Syntax Highlighting:
+
+   - `syntax`: An object containing color definitions for various syntax elements (e.g., keywords, strings, comments)
+
+4. UI Elements:
+
+   - Colors for various UI components such as:
+     - `element.background`: Background color for UI elements
+     - `border`: Border colors for different states (normal, focused, selected)
+     - `text`: Text colors for different states (normal, muted, accent)
+
+5. Editor-specific Colors:
+
+   - Colors for editor-related elements such as:
+     - `editor.background`: Editor background color
+     - `editor.gutter`: Gutter colors
+     - `editor.line_number`: Line number colors
+
+6. Terminal Colors:
+   - ANSI color definitions for the integrated terminal
+
+## Designing Your Theme
+
+You can use [Zed's Theme Builder](https://zed.dev/theme-builder) to design your own custom theme based on an existing one.
+
+This tool lets you fine-tune and preview how surfaces in Zed will look.
+You can then export the JSON and publish it in Zed's extension store.

docs/src/finding-navigating.md

@@ -0,0 +1,66 @@
+---
+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
+
+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)
+
+## Project Panel
+
+The Project Panel ({#kb project_panel::ToggleFocus}) shows a tree view of your workspace's files and directories. Browse, create, rename, move, and delete files without leaving the editor. It also surfaces git status and diagnostics at a glance.
+
+[Learn more about the Project Panel →](./project-panel.md)
+
+## 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
+
+Search across all files with {#kb pane::DeploySearch}. Start typing in the search field to begin searching—results appear as you type.
+
+Results appear in a [multibuffer](./multibuffers.md), letting you edit matches in place.
+
+## 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
+
+- **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
+
+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
+
+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
+
+| 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}       |
+| Project Panel     | {#kb project_panel::ToggleFocus} |

docs/src/getting-started.md

@@ -0,0 +1,92 @@
+---
+title: Getting Started with Zed
+description: Get started with Zed, the fast open-source code editor. Essential commands, environment setup, and navigation basics.
+---
+
+# Getting Started
+
+Zed is an open-source code editor with built-in collaboration and AI tools.
+
+This guide covers the essential commands, environment setup, and navigation basics.
+
+## Quick Start
+
+### Welcome Page
+
+When you open Zed without a folder, you see the welcome page in the main editor area. The welcome page offers quick actions to open a folder, clone a repository, or view documentation. Once you open a folder or file, the welcome page disappears. If you split the editor into multiple panes, the welcome page appears only in the center pane when empty—other panes show a standard empty state.
+
+To reopen the welcome page, close all items in the center pane or use the command palette to search for "Welcome".
+
+### 1. Open a Project
+
+Open a folder from the command line:
+
+```sh
+zed ~/projects/my-app
+```
+
+Or use `Cmd+O` (macOS) / `Ctrl+O` (Linux/Windows) to open a folder from within Zed.
+
+By default, new projects open in your current window's threads sidebar. To open in a new window instead, use `zed -n ~/projects/my-app` or press `Cmd+Enter` when selecting from Open Recent. See [Windows & Projects](./windows-and-projects.md) for more details.
+
+### 2. Learn the Essential Commands
+
+| Action          | macOS         | Linux/Windows  |
+| --------------- | ------------- | -------------- |
+| Command palette | `Cmd+Shift+P` | `Ctrl+Shift+P` |
+| Go to file      | `Cmd+P`       | `Ctrl+P`       |
+| Go to symbol    | `Cmd+Shift+O` | `Ctrl+Shift+O` |
+| Find in project | `Cmd+Shift+F` | `Ctrl+Shift+F` |
+| Toggle terminal | `` Ctrl+` ``  | `` Ctrl+` ``   |
+| Open settings   | `Cmd+,`       | `Ctrl+,`       |
+
+The command palette (`Cmd+Shift+P`) is your gateway to every action in Zed. If you forget a shortcut, search for it there.
+
+### 3. Configure Your Editor
+
+Open the Settings Editor with `Cmd+,` (macOS) or `Ctrl+,` (Linux/Windows). Search for any setting and change it directly.
+
+Common first changes:
+
+- **Theme**: Press `Cmd+K Cmd+T` (macOS) or `Ctrl+K Ctrl+T` (Linux/Windows) to open the theme selector
+- **Font**: Search for `buffer_font_family` in Settings
+- **Format on save**: Search for `format_on_save` and set to `on`
+
+### 4. Set Up Your Language
+
+Zed includes built-in support for many languages. For others, install the extension:
+
+1. Open Extensions with `Cmd+Shift+X` (macOS) or `Ctrl+Shift+X` (Linux/Windows)
+2. Search for your language
+3. Click Install
+
+See [Languages](./languages.md) for language-specific setup instructions.
+
+### 5. Try AI Features
+
+Zed includes built-in AI assistance. Open the Agent Panel with `Cmd+Shift+A` (macOS) or `Ctrl+Shift+A` (Linux/Windows) to start a conversation, or use `Cmd+Enter` (macOS) / `Ctrl+Enter` (Linux/Windows) for inline assistance.
+
+See [AI Overview](./ai/overview.md) to configure providers and learn what's possible.
+
+## Coming from Another Editor?
+
+We have dedicated guides for switching from other editors:
+
+- [VS Code](./migrate/vs-code.md) — Import settings, map keybindings, find equivalent features
+- [IntelliJ IDEA](./migrate/intellij.md) — Adapt to Zed's approach to navigation and refactoring
+- [PyCharm](./migrate/pycharm.md) — Set up Python development in Zed
+- [WebStorm](./migrate/webstorm.md) — Configure JavaScript/TypeScript workflows
+- [RustRover](./migrate/rustrover.md) — Rust development in Zed
+
+You can also enable familiar keybindings:
+
+- **Vim**: Enable `vim_mode` in settings. See [Vim Mode](./vim.md).
+- **Helix**: Enable `helix_mode` in settings. See [Helix Mode](./helix.md).
+
+## Join the Community
+
+Zed is open source. Join us on GitHub or in Discord to contribute code, report bugs, or suggest features.
+
+- [Discord](https://discord.com/invite/zedindustries)
+- [GitHub Discussions](https://github.com/zed-industries/zed/discussions)
+- [Zed Reddit](https://www.reddit.com/r/ZedEditor)

docs/src/git.md

@@ -0,0 +1,401 @@
+---
+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
+
+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
+
+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
+
+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
+
+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
+    }
+  }
+}
+```
+
+### Diff View Styles
+
+Zed displays diffs in two modes: **split** (side-by-side comparison) or **unified** (inline changes). Split view is the default.
+
+#### Changing the diff view
+
+Open the Settings Editor ({#kb zed::OpenSettings}) and search for "diff view style". Select either **Split** or **Unified**.
+
+To change the default, add this to your `settings.json`:
+
+```json
+{
+  "diff_view_style": "unified"
+}
+```
+
+See [Configuring Zed](./configuring-zed.md) for more about the Settings Editor.
+
+#### Split vs unified
+
+- **Split**: Shows the original and modified versions side by side. Useful for comparing file structure or reviewing large changes.
+- **Unified**: Shows changes inline with additions and deletions in a single view. Useful for focusing on specific line changes.
+
+You can switch between modes at any time. Your preference applies to [Project Diff](#project-diff), [File History](#file-history), and [Stash Diff View](#stash-diff-view). These diff views function as [multibuffers](./multibuffers.md), allowing you to edit multiple excerpts simultaneously.
+
+## 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 view File History:
+
+- Right-click on a file in the Project Panel and select "View File History"
+- Right-click on a file in the Git Panel and select "View File History"
+- Right-click on an editor tab and select "View File History"
+- Use the Command Palette and search for "file history"
+
+## Fetch, Push, and 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
+
+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
+
+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
+
+Zed has two primary staging workflows, using either the Project Diff or the panel directly.
+
+### Using the 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
+
+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.
+
+<!-- Show a set of changes with default staged -->
+
+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}.
+
+<!-- Add media -->
+
+## 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
+
+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
+
+### Creating and Switching Branches
+
+Create a new branch using {#action git::Branch} or switch to an existing branch using {#action git::Switch} or {#action git::CheckoutBranch}.
+
+When you are working in a [Git worktree](#git-worktrees), use the branch picker after switching to the worktree to create or check out the branch you want to use there.
+
+### Deleting 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.
+
+## Git Worktrees
+
+Git worktrees let you keep multiple checkouts of the same repository on disk at the same time.
+This is useful when you want to work on more than one branch or task without stashing, rebuilding, or disturbing the files in your main checkout.
+
+Open the worktree picker from the title bar, next to the project picker, or by running {#action git::Worktree}.
+From the picker, you can:
+
+- Create a new linked worktree either from the current branch or default branch
+- Type a name to create a named worktree or let Zed automatically pick one for you
+- Switch the current workspace to an existing worktree
+- Open an existing worktree in a new window
+- Delete linked worktrees that are not currently open in the project
+
+### Worktree Management
+
+New worktrees are created in detached HEAD state.
+After switching to the new worktree, use the branch picker next to the worktree picker to create a new branch or check out an existing, unused branch.
+This keeps Zed from accidentally checking out the same branch in multiple worktrees.
+
+The directory used for new worktrees is controlled by the `git.worktree_directory` setting.
+By default, Zed creates worktrees under `../worktrees` relative to the repository's working directory.
+
+See [All Settings](./reference/all-settings.md#git-worktree-directory) for examples.
+
+### Init Setup
+
+To run setup steps after Zed creates a linked worktree, use the [`create_worktree` task hook](./tasks.md#hooks).
+For agent-specific workflows, see [Worktree Isolation](./ai/parallel-agents.md#worktree-isolation).
+
+### Multi-root Workspaces
+
+If your project contains multiple Git repositories (i.e., multi-root folders), Zed creates a linked worktree for each repository when creating a new worktree from the picker.
+Non-Git folders in the same project are included in the new workspace as-is.
+
+## 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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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
+
+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 that 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.
+
+<!-- Add media -->
+
+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
+
+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
+
+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
+
+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
+
+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                                    | 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::Worktree}                   | {#kb git::Worktree}                   |
+| {#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} |
+
+> Not all actions have default keybindings, but can be bound by [customizing your keymap](./key-bindings.md#user-keymaps).
+
+## Git 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"
+```

docs/src/globs.md

@@ -0,0 +1,96 @@
+---
+title: Glob Patterns - Zed
+description: How glob patterns work in Zed for file matching, search filtering, and configuration. Syntax reference and examples.
+---
+
+# Globs
+
+Zed supports the use of [glob](<https://en.wikipedia.org/wiki/Glob_(programming)>) patterns that are the formal name for Unix shell-style path matching wildcards like `*.md` or `docs/src/**/*.md` supported by sh, bash, zsh, etc. A glob is similar but distinct from a [regex (regular expression)](https://en.wikipedia.org/wiki/Regular_expression). In Zed, globs are commonly used when matching filenames.
+
+## Glob Flavor
+
+Zed uses two different rust crates for matching glob patterns:
+
+- [ignore crate](https://docs.rs/ignore/latest/ignore/) for matching glob patterns stored in `.gitignore` files
+- [glob crate](https://docs.rs/glob/latest/glob/) for matching file paths in Zed
+
+While simple expressions are portable across environments (e.g. running `ls *.py` or `*.tmp` in a gitignore) there is significant divergence in the support for and syntax of more advanced features varies (character classes, exclusions, `**`, etc) across implementations. For the rest of this document we will be describing globs as supported in Zed via the `glob` crate implementation. Please see [References](#references) below for documentation links for glob pattern syntax for `.gitignore`, shells and other programming languages.
+
+The `glob` crate is implemented entirely in rust and does not rely on the `glob` / `fnmatch` interfaces provided by your platforms libc. This means that globs in Zed should behave similarly with across platforms.
+
+## Introduction
+
+A glob "pattern" is used to match a file name or complete file path. For example, when using "Search all files" {#kb project_search::ToggleFocus} you can click the funnel shaped Toggle Filters" button or {#kb project_search::ToggleFilters} and it will show additional search fields for "Include" and "Exclude" which support specifying glob patterns for matching file paths and file names.
+
+### Multiple Patterns
+
+You can specify multiple glob patterns in Project Search filters by separating them with commas. When using comma-separated patterns, Zed correctly handles braces within individual patterns:
+
+- `*.ts, *.tsx` — Match TypeScript and TSX files
+- `src/{components,utils}/**/*.ts, tests/**/*.test.ts` — Match TypeScript files in specific directories plus test files
+
+Each pattern is evaluated independently. Commas inside braces (like `{a,b}`) are treated as part of the pattern, not as separators.
+
+**Important:** While braces are preserved in patterns, Zed does not expand them into multiple patterns. The pattern `src/{a,b}/*.ts` matches the literal path structure, not `src/a/*.ts` OR `src/b/*.ts`. This differs from shell behavior.
+
+When creating a glob pattern you can use one or multiple special characters:
+
+| Special Character | Meaning                                                           |
+| ----------------- | ----------------------------------------------------------------- |
+| `?`               | Matches any single character                                      |
+| `*`               | Matches any (possibly empty) sequence of characters               |
+| `**`              | Matches the current directory and arbitrary subdirectories        |
+| `[abc]`           | Matches any one character in the brackets                         |
+| `[a-z]`           | Matches any of a range of characters (ordered by Unicode)         |
+| `[!...]`          | The negation of `[...]` (matches a character not in the brackets) |
+
+Notes:
+
+1. Brace characters `{` and `}` are literal pattern characters, not expansion operators. The pattern `src/{a,b}/*.ts` matches paths containing the literal text `{a,b}`, not paths matching either `src/a/*.ts` or `src/b/*.ts` as in shell globbing.
+2. To match a literal `-` character inside brackets it must come first `[-abc]` or last `[abc-]`.
+3. To match the literal `[` character use `[[]` or put it as the first character in the group `[[abc]`.
+4. To match the literal `]` character use `[]]` or put it as the last character in the group `[abc]]`.
+
+## Examples
+
+### Matching file extensions
+
+If you wanted to only search Markdown files add `*.md` to the "Include" search field.
+
+### Case insensitive matching
+
+Globs in Zed are case-sensitive, so `*.c` will not match `main.C` (even on case-insensitive filesystems like HFS+/APFS on macOS). Instead use brackets to match characters. So instead of `*.c` use `*.[cC]`.
+
+### Matching directories
+
+If you wanted to search the [zed repository](https://github.com/zed-industries/zed) for examples of [Configuring Language Servers](https://zed.dev/docs/configuring-languages#configuring-language-servers) (under `"lsp"` in Zed settings.json) you could search for `"lsp"` and in the "Include" filter specify `docs/**/*.md`. This would only match files whose path was under the `docs` directory or any nested subdirectories `**/` of that folder with a filename that ends in `.md`.
+
+If instead you wanted to restrict yourself only to [Zed Language-Specific Documentation](https://zed.dev/docs/languages) pages you could define a narrower pattern of: `docs/src/languages/*.md` this would match [`docs/src/languages/rust.md`](https://github.com/zed-industries/zed/blob/main/docs/src/languages/rust.md) and [`docs/src/languages/cpp.md`](https://github.com/zed-industries/zed/blob/main/docs/src/languages/cpp.md) but not [`docs/src/configuring-languages.md`](https://github.com/zed-industries/zed/blob/main/docs/src/configuring-languages.md).
+
+### Implicit Wildcards
+
+When using the "Include" / "Exclude" filters on a Project Search each glob is wrapped in implicit wildcards. For example to exclude any files with license in the path or filename from your search just type `license` in the exclude box. Behind the scenes Zed transforms `license` to `**license**`. This means that files named `license.*`, `*.license` or inside a `license` subdirectory will all be filtered out. This enables users to easily filter for `*.ts` without having to remember to type `**/*.ts` every time.
+
+Alternatively, if in your Zed settings you wanted a [`file_types`](./reference/all-settings.md#file-types) override which only applied to a certain directory you must explicitly include the wildcard globs. For example, if you had a directory of template files with the `html` extension that you wanted to recognize as Jinja2 template you could use the following:
+
+```json [settings]
+{
+  "file_types": {
+    "C++": ["[cC]"],
+    "Jinja2": ["**/templates/*.html"]
+  }
+}
+```
+
+## References
+
+While globs in Zed are implemented as described above, when writing code using globs in other languages, please reference your platform's glob documentation:
+
+- [macOS fnmatch](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/fnmatch.3.html) (BSD C Standard Library)
+- [Linux fnmatch](https://www.gnu.org/software/libc/manual/html_node/Wildcard-Matching.html) (GNU C Standard Library)
+- [POSIX fnmatch](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fnmatch.html) (POSIX Specification)
+- [node-glob](https://github.com/isaacs/node-glob) (Node.js `glob` package)
+- [Python glob](https://docs.python.org/3/library/glob.html) (Python Standard Library)
+- [Golang glob](https://pkg.go.dev/path/filepath#Match) (Go Standard Library)
+- [gitignore patterns](https://git-scm.com/docs/gitignore) (Gitignore Pattern Format)
+- [PowerShell: About Wildcards](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards) (Wildcards in PowerShell)

docs/src/helix.md

@@ -0,0 +1,20 @@
+---
+title: Helix Mode - Zed
+description: Helix-style keybindings and modal editing in Zed. Selection-first editing built on top of Vim mode.
+---
+
+# Helix Mode
+
+_Work in progress. Not all Helix keybindings are implemented yet._
+
+Zed's Helix mode is an emulation layer that brings Helix-style keybindings and modal editing to Zed. It builds upon Zed's [Vim mode](./vim.md), so much of the core functionality is shared. Enabling `helix_mode` will also enable `vim_mode`.
+
+For a guide on Vim-related features that are also available in Helix mode, please refer to our [Vim mode documentation](./vim.md).
+
+To check the current status of Helix mode, or to request a missing Helix feature, see the ["Are we Helix yet?" discussion](https://github.com/zed-industries/zed/discussions/33580).
+
+For a detailed list of Helix's default keybindings, please visit the [official Helix documentation](https://docs.helix-editor.com/keymap.html).
+
+## Core differences
+
+Any text object that works with `m i` or `m a` also works with `]` and `[`, so for example `] (` selects the next pair of parentheses after the cursor.

docs/src/icon-themes.md

@@ -0,0 +1,40 @@
+---
+title: Icon Themes
+description: "Zed comes with a built-in icon theme, with more icon themes available as extensions."
+---
+
+# Icon Themes
+
+Zed comes with a built-in icon theme, with more icon themes available as extensions.
+
+## Selecting an Icon Theme
+
+See what icon themes are installed and preview them via the Icon Theme Selector, which you can open from the command palette with {#action icon_theme_selector::Toggle}.
+
+Navigating through the icon theme list by moving up and down will change the icon theme in real time and hitting enter will save it to your settings file.
+
+## Installing more Icon Themes
+
+More icon themes are available from the Extensions page, which you can access via the command palette with {#action zed::Extensions} or the [Zed website](https://zed.dev/extensions?filter=icon-themes).
+
+## Configuring Icon Themes
+
+Your selected icon theme is stored in your settings file.
+You can open your settings file from the command palette with {#action zed::OpenSettingsFile} (bound to {#kb zed::OpenSettingsFile}).
+
+Just like with themes, Zed allows for configuring different icon themes for light and dark mode.
+You can set the mode to `"light"` or `"dark"` to ignore the current system mode.
+
+```json [settings]
+{
+  "icon_theme": {
+    "mode": "system",
+    "light": "Light Icon Theme",
+    "dark": "Dark Icon Theme"
+  }
+}
+```
+
+## Icon Theme Development
+
+See: [Developing Zed Icon Themes](./extensions/icon-themes.md)

docs/src/installation.md

@@ -0,0 +1,130 @@
+---
+title: Install Zed - macOS, Linux, Windows
+description: Download and install Zed on macOS, Linux, or Windows. Includes Homebrew, direct download, and package manager options.
+---
+
+# Installing Zed
+
+## Download Zed
+
+### macOS
+
+Get the latest stable builds via [the download page](https://zed.dev/download). If you want to download our preview build, you can find it on its [releases page](https://zed.dev/releases/preview). After the first manual installation, Zed will periodically check for install updates.
+
+You can also install Zed stable via Homebrew:
+
+```sh
+brew install --cask zed
+```
+
+As well as Zed preview:
+
+```sh
+brew install --cask zed@preview
+```
+
+### Windows
+
+Get the latest stable builds via [the download page](https://zed.dev/download). If you want to download our preview build, you can find it on its [releases page](https://zed.dev/releases/preview). After the first manual installation, Zed will periodically check for install updates.
+
+Additionally, you can install Zed using winget:
+
+```sh
+winget install -e --id ZedIndustries.Zed
+```
+
+### Linux
+
+For most Linux users, the easiest way to install Zed is through our installation script:
+
+```sh
+curl -f https://zed.dev/install.sh | sh
+```
+
+You can now optionally specify a **version** of Zed to install using the `ZED_VERSION` environment variable:
+
+```sh
+# Install the latest stable version (default)
+curl -f https://zed.dev/install.sh | sh
+
+# Install a specific version
+curl -f https://zed.dev/install.sh | ZED_VERSION=0.216.0 sh
+```
+
+To install the preview build, which receives updates about a week ahead of stable:
+
+```sh
+curl -f https://zed.dev/install.sh | ZED_CHANNEL=preview sh
+```
+
+This script supports `x86_64` and `AArch64`, as well as common Linux distributions: Ubuntu, Arch, Debian, RedHat, CentOS, Fedora, and more.
+
+If Zed is installed using this installation script, it can be uninstalled at any time by running the shell command `zed --uninstall`. The shell will then prompt you whether you'd like to keep your preferences or delete them. After making a choice, you should see a message that Zed was successfully uninstalled.
+
+If this script is insufficient for your use case, you run into problems running Zed, or there are errors in uninstalling Zed, please see our [Linux-specific documentation](./linux.md).
+
+## System Requirements
+
+### macOS
+
+Zed supports the follow macOS releases:
+
+| Version       | Codename | Apple Status   | Zed Status          |
+| ------------- | -------- | -------------- | ------------------- |
+| macOS 26.x    | Tahoe    | Supported      | Supported           |
+| macOS 15.x    | Sequoia  | Supported      | Supported           |
+| macOS 14.x    | Sonoma   | Supported      | Supported           |
+| macOS 13.x    | Ventura  | Supported      | Supported           |
+| macOS 12.x    | Monterey | EOL 2024-09-16 | Supported           |
+| macOS 11.x    | Big Sur  | EOL 2023-09-26 | Partially Supported |
+| macOS 10.15.x | Catalina | EOL 2022-09-12 | Partially Supported |
+
+The macOS releases labelled "Partially Supported" (Big Sur and Catalina) do not support screen sharing via Zed Collaboration. These features use the [LiveKit SDK](https://livekit.io) which relies upon [ScreenCaptureKit.framework](https://developer.apple.com/documentation/screencapturekit/) only available on macOS 12 (Monterey) and newer.
+
+#### Mac Hardware
+
+Zed supports machines with Intel (x86_64) or Apple (aarch64) processors that meet the above macOS requirements:
+
+- MacBook Pro (Early 2015 and newer)
+- MacBook Air (Early 2015 and newer)
+- MacBook (Early 2016 and newer)
+- Mac Mini (Late 2014 and newer)
+- Mac Pro (Late 2013 or newer)
+- iMac (Late 2015 and newer)
+- iMac Pro (all models)
+- Mac Studio (all models)
+
+### Linux
+
+Zed supports 64-bit Intel/AMD (x86_64) and 64-bit Arm (aarch64) processors.
+
+Zed requires a Vulkan 1.3 driver and the following desktop portals:
+
+- `org.freedesktop.portal.FileChooser`
+- `org.freedesktop.portal.OpenURI`
+- `org.freedesktop.portal.Secret` or `org.freedesktop.Secrets`
+
+### Windows
+
+Zed supports the following Windows releases:
+| Version | Zed Status |
+| ------------------------- | ------------------- |
+| Windows 11, version 22H2 and later | Supported |
+| Windows 10, version 1903 and later | Supported |
+
+A 64-bit operating system is required to run Zed.
+
+#### Windows Hardware
+
+Zed supports machines with x64 (Intel, AMD) or Arm64 (Qualcomm) processors that meet the following requirements:
+
+- Graphics: A GPU that supports DirectX 11 (most PCs from 2012+).
+- Driver: Current NVIDIA/AMD/Intel/Qualcomm driver (not the Microsoft Basic Display Adapter).
+
+### FreeBSD
+
+Not yet available as an official download. Can be built [from source](./development/freebsd.md).
+
+### Web
+
+Not supported at this time. See our [Platform Support issue](https://github.com/zed-industries/zed/issues/5391).

docs/src/key-bindings.md

@@ -0,0 +1,306 @@
+---
+title: Key Bindings and Shortcuts - Zed
+description: Customize Zed's keyboard shortcuts. Rebind actions, create key sequences, and set context-specific bindings.
+---
+
+# Key bindings
+
+Zed's key binding system is fully customizable. You can rebind any action, create key sequences, and define context-specific bindings.
+
+## Predefined Keymaps
+
+If you're used to a specific editor's defaults, you can change your `base_keymap` through the settings window ({#kb zed::OpenSettings}) or directly through your `settings.json` file ({#kb zed::OpenSettingsFile}).
+We currently support:
+
+- VS Code (default)
+- Atom
+- Emacs (Beta)
+- JetBrains
+- Sublime Text
+- TextMate
+- Cursor
+- None (disables _all_ key bindings)
+
+This setting can also be changed via the command palette through the {#action zed::ToggleBaseKeymapSelector} action.
+
+You can also enable `vim_mode` or `helix_mode`, which add modal bindings.
+For more information, see the documentation for [Vim mode](./vim.md) and [Helix mode](./helix.md).
+
+## Keymap Editor
+
+You can access the keymap editor through the {#kb zed::OpenKeymap} action or by running {#action zed::OpenKeymap} action from the command palette. You can easily add or change a keybind for an action with the `Change Keybinding` or `Add Keybinding` button on the command pallets left bottom corner.
+
+In there, you can see all of the existing actions in Zed as well as the associated keybindings set to them by default.
+
+You can also customize them right from there, either by clicking on the pencil icon that appears when you hover over a particular action, by double-clicking on the action row, or by pressing the `enter` key.
+
+Anything that you end up doing on the keymap editor also gets reflected on the `keymap.json` file.
+
+## User Keymaps
+
+The keymap file is stored in the following locations for each platform:
+
+- macOS/Linux: `~/.config/zed/keymap.json`
+- Windows: `~\AppData\Roaming\Zed/keymap.json`
+
+You can open the keymap with the {#action zed::OpenKeymapFile} action from the command palette.
+
+This file contains a JSON array of objects with `"bindings"`.
+If no `"context"` is set, the bindings are always active.
+If it is set, the binding is only active when the [context matches](#contexts).
+
+Within each binding section, a [key sequence](#keybinding-syntax) is mapped to [an action](#actions).
+If conflicts are detected, they are resolved as [described below](#precedence).
+
+If you are using a non-QWERTY, Latin-character keyboard, you may want to set `use_key_equivalents` to `true`. See [Non-QWERTY keyboards](#non-qwerty-keyboards) for more information.
+
+For example:
+
+```json [keymap]
+[
+  {
+    "bindings": {
+      "ctrl-right": "editor::SelectLargerSyntaxNode",
+      "ctrl-left": "editor::SelectSmallerSyntaxNode"
+    }
+  },
+  {
+    "context": "ProjectPanel && not_editing",
+    "bindings": {
+      "o": "project_panel::Open"
+    }
+  }
+]
+```
+
+You can see all of Zed's default bindings for each platform in the default keymaps files:
+
+- [macOS](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-macos.json)
+- [Windows](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-windows.json)
+- [Linux](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-linux.json).
+
+If you want to debug problems with custom keymaps, you can use {#action dev::OpenKeyContextView} from the command palette.
+Please file [an issue](https://github.com/zed-industries/zed) if you run into something you think should work but isn't.
+
+### Keybinding Syntax
+
+Zed has the ability to match against not just a single keypress, but a sequence of keys typed in order. Each key in the `"bindings"` map is a sequence of keypresses separated with a space.
+
+Each keypress is a sequence of modifiers followed by a key. The modifiers are:
+
+- `ctrl-` The control key
+- `cmd-`, `win-` or `super-` for the platform modifier (Command on macOS, Windows key on Windows, and the Super key on Linux).
+- `alt-` for alt (option on macOS)
+- `shift-` The shift key
+- `fn-` The function key
+- `secondary-` Equivalent to `cmd` when Zed is running on macOS and `ctrl` when on Windows and Linux
+
+The keys can be any single Unicode codepoint that your keyboard generates (for example `a`, `0`, `£` or `ç`), or any named key (`tab`, `f1`, `shift`, or `cmd`). If you are using a non-Latin layout (e.g. Cyrillic), you can bind either to the Cyrillic character or the Latin character that key generates with `cmd` pressed.
+
+A few examples:
+
+```json [keymap]
+{
+  "bindings": {
+    "cmd-k cmd-s": "zed::OpenKeymap", // matches ⌘-k then ⌘-s
+    "space e": "editor::ShowCompletions", // type space then e
+    "ç": "editor::ShowCompletions", // matches ⌥-c
+    "shift shift": "file_finder::Toggle" // matches pressing and releasing shift twice
+  }
+}
+```
+
+The `shift-` modifier can only be used in combination with a letter to indicate the uppercase version. For example, `shift-g` matches typing `G`. Although on many keyboards shift is used to type punctuation characters like `(`, the keypress is not considered to be modified, and so `shift-(` does not match.
+
+The `alt-` modifier can be used on many layouts to generate a different key. For example, on a macOS US keyboard, the combination `alt-c` types `ç`. You can match against either in your keymap file, though by convention, Zed spells this combination as `alt-c`.
+
+It is possible to match against typing a modifier key on its own. For example, `shift shift` can be used to implement JetBrains' 'Search Everywhere' shortcut. In this case, the binding happens on key release instead of on keypress.
+
+### Contexts
+
+If a binding group has a `"context"` key, it will be matched against the currently active contexts in Zed.
+
+Zed's contexts make up a tree, with the root being `Workspace`. Workspaces contain Panes and Panels, and Panes contain Editors, etc. The easiest way to see what contexts are active at a given moment is the key context view, which you can get to with the {#action dev::OpenKeyContextView} command in the command palette.
+
+For example:
+
+```
+# in an editor, it might look like this:
+Workspace os=macos keyboard_layout=com.apple.keylayout.QWERTY
+  Pane
+    Editor mode=full extension=md vim_mode=insert
+
+# in the project panel
+Workspace os=macos
+  Dock
+    ProjectPanel not_editing
+```
+
+Context expressions can contain the following syntax:
+
+- `X && Y`, `X || Y` to and/or two conditions
+- `!X` to check that a condition is false
+- `(X)` for grouping
+- `X > Y` to match if an ancestor in the tree matches X and this layer matches Y.
+
+For example:
+
+- `"context": "Editor"` - matches any editor (including inline inputs)
+- `"context": "Editor && mode == full"` - matches the main editors used for editing code
+- `"context": "!Editor && !Terminal"` - matches anywhere except where an Editor or Terminal is focused
+- `"context": "os == macos > Editor"` - matches any editor on macOS.
+
+It's worth noting that attributes are only available on the node they are defined on. This means that if you want to (for example) only enable a keybinding when the debugger is stopped in vim normal mode, you need to do `debugger_stopped > vim_mode == normal`.
+
+> Note: Before Zed v0.197.x, the `!` operator only looked at one node at a time, and `>` meant "parent" not "ancestor". This meant that `!Editor` would match the context `Workspace > Pane > Editor`, because (confusingly) the Pane matches `!Editor`, and that `os == macos > Editor` did not match the context `Workspace > Pane > Editor` because of the intermediate `Pane` node.
+
+If you're using Vim mode, we have information on how [vim modes influence the context](./vim.md#contexts). Helix mode is built on top of Vim mode and uses the same contexts.
+
+### Actions
+
+Almost all of Zed's functionality is exposed as actions.
+Although there is no explicitly documented list, you can find most of them by searching in the command palette, by looking in the default keymaps for [macOS](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-macos.json), [Windows](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-windows.json) or [Linux](https://github.com/zed-industries/zed/blob/main/assets/keymaps/default-linux.json), or by using Zed's autocomplete in your keymap file.
+
+Most actions do not require any arguments, and so you can bind them as strings: `"ctrl-a": "language_selector::Toggle"`. Some require a single argument and must be bound as an array: `"cmd-1": ["workspace::ActivatePane", 0]`. Some actions require multiple arguments and are bound as an array of a string and an object: `"ctrl-a": ["pane::DeploySearch", { "replace_enabled": true }]`.
+
+### Precedence
+
+When multiple keybindings have the same keystroke and are active at the same time, precedence is resolved in two ways:
+
+- Bindings that match on lower nodes in the context tree win. This means that if you have a binding with a context of `Editor`, it will take precedence over a binding with a context of `Workspace`. Bindings with no context match at the lowest level in the tree.
+- If there are multiple bindings that match at the same level in the tree, then the binding defined later takes precedence. As user keybindings are loaded after system keybindings, this allows user bindings to take precedence over built-in keybindings.
+
+The other kind of conflict that arises is when you have two bindings, one of which is a prefix of the other. For example, if you have `"ctrl-w":"editor::DeleteToNextWordEnd"` and `"ctrl-w left":"editor::DeleteToEndOfLine"`.
+
+When this happens, and both bindings are active in the current context, Zed will wait for 1 second after you type `ctrl-w` to see if you're about to type `left`. If you don't type anything, or if you type a different key, then `DeleteToNextWordEnd` will be triggered. If you do, then `DeleteToEndOfLine` will be triggered.
+
+### Non-QWERTY keyboards
+
+Zed's support for non-QWERTY keyboards is still a work in progress.
+
+If your keyboard can type the full ASCII range (DVORAK, COLEMAK, etc.), then shortcuts should work as you expect.
+
+Otherwise, read on...
+
+#### macOS
+
+On Cyrillic, Hebrew, Armenian, and other keyboards that are mostly non-ASCII, macOS automatically maps keys to the ASCII range when `cmd` is held. Zed takes this a step further, and it can always match key-presses against either the ASCII layout or the real layout, regardless of modifiers and the `use_key_equivalents` setting. For example, in Thai, pressing `ctrl-ๆ` will match bindings associated with `ctrl-q` or `ctrl-ๆ`.
+
+On keyboards that support extended Latin alphabets (French AZERTY, German QWERTZ, etc.), it is often not possible to type the entire ASCII range without `option`. This introduces an ambiguity: `option-2` produces `@`. To ensure that all the built-in keyboard shortcuts can still be typed on these keyboards, we move key bindings around. For example, shortcuts bound to `@` on QWERTY are moved to `"` on a Spanish layout. This mapping is based on the macOS system defaults and can be seen by running {#action dev::OpenKeyContextView} from the command palette.
+
+If you are defining shortcuts in your personal keymap, you can opt into the key equivalent mapping by setting `use_key_equivalents` to `true` in your keymap:
+
+```json [keymap]
+[
+  {
+    "use_key_equivalents": true,
+    "bindings": {
+      "ctrl->": "editor::Indent" // parsed as ctrl-: when a German QWERTZ keyboard is active
+    }
+  }
+]
+```
+
+### Linux
+
+Since v0.196.0, on Linux, if the key that you type doesn't produce an ASCII character, then we use the QWERTY-layout equivalent key for keyboard shortcuts. This means that many shortcuts can be typed on many layouts.
+
+We do not yet remap shortcuts so every built-in shortcut is typeable on every layout. If your layout cannot type some ASCII characters, you may need custom key bindings. We plan to improve this.
+
+## Tips and tricks
+
+### Disabling a binding
+
+If you'd like a given binding to do nothing in a given context, you can use
+`null` as the action. This is useful if you hit the key binding by accident and
+want to disable it, or if you want to type the character that would be typed by
+the sequence, or if you want to disable multikey bindings starting with that key.
+
+```json [keymap]
+[
+  {
+    "context": "Workspace",
+    "bindings": {
+      "cmd-r": null // cmd-r will do nothing when the Workspace context is active
+    }
+  }
+]
+```
+
+A `null` binding follows the same precedence rules as normal actions, so it disables all bindings that would match further up in the tree too. If you'd like a binding that matches further up in the tree to take precedence over a lower binding, you need to rebind it to the action you want in the context you want.
+
+This is useful for preventing Zed from falling back to a default key binding when the action you specified is conditional and propagates. For example, `buffer_search::DeployReplace` only triggers when the search bar is not in view. If the search bar is in view, it would propagate and trigger the default action set for that key binding, such as opening the right dock. To prevent this from happening:
+
+```json [keymap]
+[
+  {
+    "context": "Workspace",
+    "bindings": {
+      "cmd-r": null // cmd-r will do nothing when the search bar is in view
+    }
+  },
+  {
+    "context": "Workspace",
+    "bindings": {
+      "cmd-r": "buffer_search::DeployReplace" // cmd-r will deploy replace when the search bar is not in view
+    }
+  }
+]
+```
+
+### Remapping keys
+
+A common request is to be able to map from a single keystroke to a sequence. You can do this with the `workspace::SendKeystrokes` action.
+
+```json [keymap]
+[
+  {
+    "bindings": {
+      // Move down four times
+      "alt-down": ["workspace::SendKeystrokes", "down down down down"],
+      // Expand the selection (editor::SelectLargerSyntaxNode);
+      // copy to the clipboard; and then undo the selection expansion.
+      "cmd-alt-c": [
+        "workspace::SendKeystrokes",
+        "ctrl-shift-right ctrl-shift-right ctrl-shift-right cmd-c ctrl-shift-left ctrl-shift-left ctrl-shift-left"
+      ]
+    }
+  },
+  {
+    "context": "Editor && vim_mode == insert",
+    "bindings": {
+      "j k": ["workspace::SendKeystrokes", "escape"]
+    }
+  }
+]
+```
+
+There are some limitations to this, notably:
+
+- Any asynchronous operation will not happen until after all your key bindings have been dispatched. For example, this means that while you can use a binding to open a file (as in the `cmd-alt-r` example), you cannot send further keystrokes and hope to have them interpreted by the new view.
+- Other examples of asynchronous things are: opening the command palette, communicating with a language server, changing the language of a buffer, anything that hits the network.
+- There is a limit of 100 simulated keys at a time.
+
+The argument to `SendKeystrokes` is a space-separated list of keystrokes (using the same syntax as above). Due to the way that keystrokes are parsed, any segment that is not recognized as a keypress will be sent verbatim to the currently focused input field.
+
+If the argument to `SendKeystrokes` contains the binding used to trigger it, it will use the next-highest-precedence definition of that binding. This allows you to extend the default behavior of a key binding.
+
+### Forward keys to terminal
+
+If you're on Linux or Windows, you might find yourself wanting to forward key combinations to the built-in terminal instead of them being handled by Zed.
+
+For example, `ctrl-n` creates a new tab in Zed on Linux. If you want to send `ctrl-n` to the built-in terminal when it's focused, add the following to your keymap:
+
+```json [keymap]
+{
+  "context": "Terminal",
+  "bindings": {
+    "ctrl-n": ["terminal::SendKeystroke", "ctrl-n"]
+  }
+}
+```
+
+### Task Key bindings
+
+You can also bind keys to launch Zed Tasks defined in your `tasks.json`.
+See the [tasks documentation](tasks.md#custom-keybindings-for-tasks) for more.

docs/src/languages.md

@@ -0,0 +1,175 @@
+---
+title: Language Support
+description: "Overview of programming language support in Zed, including built-in and extension-based languages."
+---
+
+# Language Support in Zed
+
+Zed supports hundreds of programming languages and text formats.
+Some work out-of-the box and others rely on 3rd party extensions.
+
+> The ones included out-of-the-box, natively built into Zed, are marked with \*.
+
+## Languages with Documentation
+
+- [Ansible](./languages/ansible.md)
+- [AsciiDoc](./languages/asciidoc.md)
+- [Astro](./languages/astro.md)
+- [Bash](./languages/bash.md) \*
+- [Biome](./languages/biome.md)
+- [C](./languages/c.md) \*
+- [C++](./languages/cpp.md) \*
+- [C#](./languages/csharp.md)
+- [Clojure](./languages/clojure.md)
+- [CSS](./languages/css.md) \*
+- [Dart](./languages/dart.md)
+- [Deno](./languages/deno.md)
+- [Diff](./languages/diff.md) \*
+- [Docker](./languages/docker.md)
+- [Elixir](./languages/elixir.md)
+- [Elm](./languages/elm.md)
+- [Emmet](./languages/emmet.md)
+- [Erlang](./languages/erlang.md)
+- [Fish](./languages/fish.md)
+- [GDScript](./languages/gdscript.md)
+- [Gleam](./languages/gleam.md)
+- [GLSL](./languages/glsl.md)
+- [Go](./languages/go.md) \*
+- [Groovy](./languages/groovy.md)
+- [Haskell](./languages/haskell.md)
+- [Helm](./languages/helm.md)
+- [HTML](./languages/html.md)
+- [Java](./languages/java.md)
+- [JavaScript](./languages/javascript.md) \*
+- [Julia](./languages/julia.md)
+- [JSON](./languages/json.md) \*
+- [Jsonnet](./languages/jsonnet.md)
+- [Kotlin](./languages/kotlin.md)
+- [Lua](./languages/lua.md)
+- [Luau](./languages/luau.md)
+- [Makefile](./languages/makefile.md)
+- [Markdown](./languages/markdown.md) \*
+- [Nim](./languages/nim.md)
+- [OCaml](./languages/ocaml.md)
+- [PHP](./languages/php.md)
+- [Prisma](./languages/prisma.md)
+- [Proto](./languages/proto.md)
+- [PureScript](./languages/purescript.md)
+- [Python](./languages/python.md) \*
+- [R](./languages/r.md)
+- [Rego](./languages/rego.md)
+- [ReStructuredText](./languages/rst.md)
+- [Racket](./languages/racket.md)
+- [Roc](./languages/roc.md)
+- [Ruby](./languages/ruby.md)
+- [Rust](./languages/rust.md) \* (Zed's written in Rust)
+- [Scala](./languages/scala.md)
+- [Scheme](./languages/scheme.md)
+- [Shell Script](./languages/sh.md)
+- [Standard ML](./languages/sml.md)
+- [Svelte](./languages/svelte.md)
+- [Swift](./languages/swift.md)
+- [Tailwind CSS](./languages/tailwindcss.md) \*
+- [Terraform](./languages/terraform.md)
+- [TOML](./languages/toml.md)
+- [TypeScript](./languages/typescript.md) \*
+- [Uiua](./languages/uiua.md)
+- [Vue](./languages/vue.md)
+- [XML](./languages/xml.md)
+- [YAML](./languages/yaml.md) \*
+- [Yara](./languages/yarn.md)
+- [Yarn](./languages/yarn.md)
+- [Zig](./languages/zig.md)
+
+## Additional Community Language Extensions
+
+- [Ada](https://github.com/wisn/zed-ada-language)
+- [Aiken](https://github.com/aiken-lang/zed-aiken)
+- [Amber](https://github.com/amber-lang/zed-amber-extension)
+- [Assembly](https://github.com/DevBlocky/zed-asm)
+- [AWK](https://github.com/dangh/zed-awk)
+- [Beancount](https://github.com/zed-extensions/beancount)
+- [Bend](https://github.com/mrpedrobraga/zed-bend)
+- [Blade](https://github.com/bajrangCoder/zed-laravel-blade)
+- [Blueprint](https://github.com/tfuxu/zed-blueprint)
+- [BQN](https://github.com/DavidZwitser/zed-bqn)
+- [Brainfuck](https://github.com/JosephTLyons/zed-brainfuck)
+- [Cadence](https://github.com/janezpodhostnik/cadence.zed)
+- [Cairo](https://github.com/trbutler4/zed-cairo)
+- [Cap'n Proto](https://github.com/cmackenzie1/zed-capnp)
+- [Cedar](https://github.com/chrnorm/zed-cedar)
+- [CFEngine policy language](https://github.com/olehermanse/zed-cfengine)
+- [CSV](https://github.com/huacnlee/zed-csv)
+- [Cucumber/Gherkin](https://github.com/thlcodes/zed-extension-cucumber)
+- [CUE](https://github.com/jkasky/zed-cue)
+- [Curry](https://github.com/fwcd/zed-curry)
+- [D](https://github.com/staysail/zed-d)
+- [Database Markup Language (DBML)](https://github.com/shuklaayush/zed-dbml)
+- [Earthfile](https://github.com/glehmann/earthfile.zed)
+- [EJS template](https://github.com/dangh/zed-ejs)
+- [Elisp](https://github.com/JosephTLyons/zed-elisp)
+- [Ember](https://github.com/jylamont/zed-ember)
+- [Env](https://github.com/zarifpour/zed-env)
+- [Exograph](https://github.com/exograph/zed-extension)
+- [Fortran](https://github.com/Xavier-Maruff/zed-fortran)
+- [F#](https://github.com/nathanjcollins/zed-fsharp)
+- [Gemini gemtext](https://github.com/clseibold/gemini-zed)
+- [Git Firefly](https://github.com/d1y/git_firefly)
+- [GraphQL](https://github.com/11bit/zed-extension-graphql)
+- [Groq](https://github.com/juice49/zed-groq)
+- [INI](https://github.com/bajrangCoder/zed-ini)
+- [Java](https://github.com/zed-extensions/java)
+- [Justfiles](https://github.com/jackTabsCode/zed-just)
+- [LaTeX](https://github.com/rzukic/zed-latex)
+- [Ledger](https://github.com/mrkstwrt/zed-ledger)
+- [Less](https://github.com/jimliang/zed-less)
+- [LilyPond](https://github.com/nwhetsell/lilypond-zed-extension)
+- [Liquid](https://github.com/TheBeyondGroup/zed-shopify-liquid)
+- [Log](https://github.com/evrensen467/zed-log)
+- [Lox](https://github.com/arian81/zed-lox)
+- [Markdown Oxide](https://github.com/Feel-ix-343/markdown-oxide-zed)
+- [Marksman](https://github.com/vitallium/zed-marksman)
+- [Matlab](https://github.com/rzukic/zed-matlab)
+- [Meson](https://github.com/hqnna/zed-meson)
+- [Navi](https://github.com/navi-language/zed-navi)
+- [NeoCMake](https://github.com/k0tran/zed_neocmake)
+- [Nginx](https://github.com/d1y/nginx-zed)
+- [Nim](https://github.com/foxoman/zed-nim)
+- [Nix](https://github.com/zed-extensions/nix)
+- [Noir](https://github.com/shuklaayush/zed-noir)
+- [Nu](https://github.com/zed-extensions/nu)
+- [Odin](https://github.com/rxptr/zed-odin)
+- [Pact](https://github.com/kadena-community/pact-zed)
+- [Pest](https://github.com/pest-parser/zed-pest)
+- [PICA200 assembly](https://github.com/Squareheron942/zed-pica200)
+- [Pkl](https://github.com/Moshyfawn/pkl-zed)
+- [PlaydateSDK](https://github.com/notpeter/playdate-zed-extension)
+- [QML](https://github.com/lkroll/zed-qml)
+- [Rainbow CSV](https://github.com/weartist/zed-rainbow-csv)
+- [Rego](https://github.com/StyraInc/zed-rego)
+- [Rescript](https://github.com/humaans/rescript-zed)
+- [Roclang](https://github.com/h2000/zed-roc)
+- [Ron](https://github.com/onbjerg/zed-ron)
+- [Metals](https://github.com/scalameta/metals-zed)
+- [SCSS](https://github.com/bajrangCoder/zed-scss)
+- [Slim](https://github.com/calmyournerves/zed-slim)
+- [Slint](https://gitlab.com/flukejones/zed-slint)
+- [Smithy](https://github.com/joshrutkowski/zed-smithy)
+- [Solidity](https://github.com/zarifpour/zed-solidity)
+- [SQL](https://github.com/evrensen467/zed-sql)
+- [Strace](https://github.com/sigmaSd/zed-strace)
+- [Swift](https://github.com/zed-extensions/swift)
+- [Templ](https://github.com/makifdb/zed-templ)
+- [Tmux](https://github.com/dangh/zed-tmux)
+- [Tree-sitter Query](https://github.com/vitallium/zed-tree-sitter-query)
+- [Twig](https://github.com/YussufSassi/zed-twig)
+- [Typst](https://github.com/WeetHet/typst.zed)
+- [Unison](https://github.com/zetashift/unison-zed)
+- [UnoCSS](https://github.com/bajrangCoder/zed-unocss)
+- [Vlang](https://github.com/lv37/zed-v)
+- [Vala](https://github.com/FyraLabs/zed-vala)
+- [Vale](https://github.com/koozz/zed-vale)
+- [Verilog](https://github.com/someone13574/zed-verilog-extension)
+- [VHS](https://github.com/eth0net/zed-vhs)
+- [Wgsl](https://github.com/luan/zed-wgsl)
+- [WIT](https://github.com/valentinegb/zed-wit)

docs/src/languages/ansible.md

@@ -0,0 +1,141 @@
+---
+title: Ansible
+description: "Configure Ansible language support in Zed, including language servers, formatting, and debugging."
+---
+
+# Ansible
+
+Support for Ansible in Zed is provided via a community-maintained [Ansible extension](https://github.com/kartikvashistha/zed-ansible).
+
+- Tree-sitter: [zed-industries/tree-sitter-yaml](https://github.com/zed-industries/tree-sitter-yaml)
+- Language Server: [ansible/vscode-ansible](https://github.com/ansible/vscode-ansible/tree/main/packages/ansible-language-server)
+
+## Setup
+
+### File detection
+
+To avoid mishandling non-Ansible YAML files, the Ansible Language is not associated with any file extensions by default.
+
+To change this behavior, you can add a `"file_types"` section to Zed settings inside your project (`.zed/settings.json`) or your Zed user settings (`~/.config/zed/settings.json`) to match your folder/naming conventions. For example:
+
+```json [settings]
+{
+  "file_types": {
+    "Ansible": [
+      "**.ansible.yml",
+      "**.ansible.yaml",
+      "**/defaults/*.yml",
+      "**/defaults/*.yaml",
+      "**/meta/*.yml",
+      "**/meta/*.yaml",
+      "**/tasks/*.yml",
+      "**/tasks/*.yaml",
+      "**/handlers/*.yml",
+      "**/handlers/*.yaml",
+      "**/group_vars/*.yml",
+      "**/group_vars/*.yaml",
+      "**/host_vars/*.yml",
+      "**/host_vars/*.yaml",
+      "**/playbooks/*.yml",
+      "**/playbooks/*.yaml",
+      "**playbook*.yml",
+      "**playbook*.yaml"
+    ]
+  }
+}
+```
+
+Feel free to modify this list as per your needs.
+
+#### Inventory
+
+If your inventory file is in the YAML format, you can either:
+
+- Append the `ansible-lint` inventory JSON schema to it via the following comment at the top of your inventory file:
+
+```yml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/inventory.json
+```
+
+- or, configure the YAML language server settings to set this schema for all your inventory files, that match your inventory pattern, under your Zed settings ([ref](https://zed.dev/docs/languages/yaml)):
+
+```json [settings]
+{
+  "lsp": {
+    "yaml-language-server": {
+      "settings": {
+        "yaml": {
+          "schemas": {
+            "https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/inventory.json": [
+              "./inventory/*.yaml",
+              "hosts.yml"
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### LSP Configuration
+
+By default, the following configuration is passed to the Ansible language server. It conveniently mirrors the defaults set by [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/blob/03bc581e05e81d33808b42b2d7e76d70adb3b595/lua/lspconfig/configs/ansiblels.lua) for the Ansible language server:
+
+```json
+{
+  "ansible": {
+    "ansible": {
+      "path": "ansible"
+    },
+    "executionEnvironment": {
+      "enabled": false
+    },
+    "python": {
+      "interpreterPath": "python3"
+    },
+    "validation": {
+      "enabled": true,
+      "lint": {
+        "enabled": true,
+        "path": "ansible-lint"
+      }
+    }
+  }
+}
+```
+
+> **Note:** In order for linting to work, ensure that `ansible-lint` is installed and discoverable on your `$PATH`.
+
+When desired, any of the above default settings can be overridden under the `"lsp"` section of your Zed settings file. For example:
+
+```json [settings]
+{
+  "lsp": {
+    // The Zed Ansible extension prefixes all settings with `ansible`
+    // so use `ansible.path` instead of `ansible.ansible.path`.
+    "ansible-language-server": {
+      "settings": {
+        "ansible": {
+          "path": "ansible"
+        },
+        "executionEnvironment": {
+          "enabled": false
+        },
+        "python": {
+          "interpreterPath": "python3"
+        },
+        "validation": {
+          "enabled": false,
+          "lint": {
+            "enabled": false,
+            "path": "ansible-lint"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+A full list of options/settings that can be passed to the server can be found at the project's page [here](https://github.com/ansible/vscode-ansible/blob/main/docs/als/settings.md).

docs/src/languages/asciidoc.md

@@ -0,0 +1,11 @@
+---
+title: AsciiDoc
+description: "Configure AsciiDoc language support in Zed, including language servers, formatting, and debugging."
+---
+
+# AsciiDoc
+
+AsciiDoc language support in Zed is provided by the community-maintained [AsciiDoc extension](https://github.com/andreicek/zed-asciidoc).
+Report issues to: [https://github.com/andreicek/zed-asciidoc/issues](https://github.com/andreicek/zed-asciidoc/issues)
+
+- Tree-sitter: [cathaysia/tree-sitter-asciidoc](https://github.com/cathaysia/tree-sitter-asciidoc)

docs/src/languages/astro.md

@@ -0,0 +1,60 @@
+---
+title: Astro
+description: "Configure Astro language support in Zed, including language servers, formatting, and debugging."
+---
+
+# Astro
+
+Astro support is available through the [Astro extension](https://github.com/zed-extensions/astro).
+
+- Tree-sitter: [virchau13/tree-sitter-astro](https://github.com/virchau13/tree-sitter-astro)
+- Language Server: [withastro/language-tools](https://github.com/withastro/astro/tree/main/packages/language-tools/language-server)
+
+## Using the Tailwind CSS Language Server with Astro
+
+To get all the features (autocomplete, linting, etc.) from the [Tailwind CSS language server](https://github.com/tailwindlabs/tailwindcss-intellisense/tree/HEAD/packages/tailwindcss-language-server#readme) in Astro files, you need to configure the language server so that it knows about where to look for CSS classes by adding the following to your `settings.json`:
+
+```json [settings]
+{
+  "lsp": {
+    "tailwindcss-language-server": {
+      "settings": {
+        "includeLanguages": {
+          "astro": "html"
+        },
+        "experimental": {
+          "classRegex": [
+            "class=\"([^\"]*)\"",
+            "class='([^']*)'",
+            "class:list=\"{([^}]*)}\"",
+            "class:list='{([^}]*)}'"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+With these settings, you will get completions for Tailwind CSS classes in Astro template files. Examples:
+
+```astro
+---
+const active = true;
+---
+
+<!-- Standard class attribute -->
+<div class="flex items-center <completion here>">
+  <p class="text-lg font-bold <completion here>">Hello World</p>
+</div>
+
+<!-- class:list directive -->
+<div class:list={["flex", "items-center", "<completion here>"]}>
+  Content
+</div>
+
+<!-- Conditional classes -->
+<div class:list={{ "flex <completion here>": active, "hidden <completion here>": !active }}>
+  Content
+</div>
+```

docs/src/languages/bash.md

@@ -0,0 +1,40 @@
+---
+title: Bash
+description: "Configure Bash language support in Zed, including language servers, formatting, and debugging."
+---
+
+# Bash
+
+Bash support is available natively in Zed.
+
+- Tree-sitter: [tree-sitter/tree-sitter-bash](https://github.com/tree-sitter/tree-sitter-bash)
+- Language Server: [bash-lsp/bash-language-server](https://github.com/bash-lsp/bash-language-server)
+
+## Configuration
+
+It is highly recommended to install `shellcheck`, as `bash-language-server` depends on it to provide diagnostics.
+
+### Install `shellcheck`:
+
+```sh
+brew install shellcheck             # macOS (HomeBrew)
+apt-get install shellcheck          # Ubuntu/Debian
+pacman -S shellcheck                # ArchLinux
+dnf install shellcheck              # Fedora
+yum install shellcheck              # CentOS/RHEL
+zypper install shellcheck           # openSUSE
+choco install shellcheck            # Windows (Chocolatey)
+```
+
+And verify it is available from your path:
+
+```sh
+which shellcheck
+shellcheck --version
+```
+
+If you wish to customize the warnings/errors reported you just need to create a `.shellcheckrc` file. You can do this in the root of your project or in your home directory (`~/.shellcheckrc`). See: [shellcheck documentation](https://github.com/koalaman/shellcheck/wiki/Ignore#ignoring-one-or-more-types-of-errors-forever) for more.
+
+### See also:
+
+- [Zed Docs: Language Support: Shell Scripts](./sh.md)

docs/src/languages/biome.md

@@ -0,0 +1,40 @@
+---
+title: Biome
+description: "Configure Biome language support in Zed, including language servers, formatting, and debugging."
+---
+
+# Biome
+
+[Biome](https://biomejs.dev/) support in Zed is provided by the community-maintained [Biome extension](https://github.com/biomejs/biome-zed).
+Report issues to: [https://github.com/biomejs/biome-zed/issues](https://github.com/biomejs/biome-zed/issues)
+
+- Language Server: [biomejs/biome](https://github.com/biomejs/biome)
+
+## Biome Language Support
+
+The Biome extension includes support for the following languages:
+
+- JavaScript
+- TypeScript
+- JSX
+- TSX
+- JSON
+- JSONC
+- Vue.js
+- Astro
+- Svelte
+- CSS
+
+## Configuration
+
+By default, the `biome.json` file is required to be in the root of the workspace.
+
+```json
+{
+  "$schema": "https://biomejs.dev/schemas/1.8.3/schema.json"
+}
+```
+
+For a full list of `biome.json` options see [Biome Configuration](https://biomejs.dev/reference/configuration/) documentation.
+
+See the [Biome Zed Extension README](https://github.com/biomejs/biome-zed) for a complete list of features and configuration options.

docs/src/languages/c.md

@@ -0,0 +1,98 @@
+---
+title: C
+description: "Configure C language support in Zed, including language servers, formatting, and debugging."
+---
+
+# C
+
+C support is available natively in Zed.
+
+- Tree-sitter: [tree-sitter/tree-sitter-c](https://github.com/tree-sitter/tree-sitter-c)
+- Language Server: [clangd/clangd](https://github.com/clangd/clangd)
+- Debug Adapter: [CodeLLDB](https://github.com/vadimcn) (primary), [GDB](https://sourceware.org/gdb/) (secondary, not available on Apple silicon)
+
+## Clangd: Force detect as C
+
+Clangd out of the box assumes mixed C++/C projects. If you have a C-only project you may wish to instruct clangd to treat all files as C using the `-xc` flag. To do this, create a `.clangd` file in the root of your project with the following:
+
+```yaml
+# yaml-language-server: $schema=https://json.schemastore.org/clangd.json
+CompileFlags:
+  Add: [-xc]
+```
+
+By default clang and gcc will recognize `*.C` and `*.H` (uppercase extensions) as C++ and not C and so Zed too follows this convention. If you are working with a C-only project (perhaps one with legacy uppercase pathing like `FILENAME.C`) you can override this behavior by adding this to your settings:
+
+```json [settings]
+{
+  "file_types": {
+    "C": ["C", "H"]
+  }
+}
+```
+
+## Formatting
+
+By default Zed will use the `clangd` language server for formatting C code like the `clang-format` CLI tool. To configure this you can add a `.clang-format` file. For example:
+
+```yaml
+# yaml-language-server: $schema=https://json.schemastore.org/clang-format-21.x.json
+---
+BasedOnStyle: GNU
+IndentWidth: 2
+---
+```
+
+See [Clang-Format Style Options](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) for a complete list of options.
+
+You can trigger formatting via {#kb editor::Format} or the {#action editor::Format} action from the command palette or by enabling format on save.
+
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > C, or add to your settings file:
+
+```json [settings]
+  "languages": {
+    "C": {
+      "format_on_save": "on",
+      "tab_size": 2
+    }
+  }
+```
+
+## Compile Commands
+
+For some projects Clangd requires a `compile_commands.json` file to properly analyze your project. This file contains the compilation database that tells clangd how your project should be built.
+
+### CMake Compile Commands
+
+With CMake, you can generate `compile_commands.json` automatically by adding the following line to your `CMakeLists.txt`:
+
+```cmake
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+```
+
+After building your project, CMake will generate the `compile_commands.json` file in the build directory and clangd will automatically pick it up.
+
+## Debugging
+
+You can use CodeLLDB or GDB to debug native binaries. (Make sure that your build process passes `-g` to the C compiler, so that debug information is included in the resulting binary.) See below for examples of debug configurations that you can add to `.zed/debug.json`.
+
+- [CodeLLDB configuration documentation](https://github.com/vadimcn/codelldb/blob/master/MANUAL.md#starting-a-new-debug-session)
+- [GDB configuration documentation](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html)
+
+### Build and Debug Binary
+
+```json [debug]
+[
+  {
+    "label": "Debug native binary",
+    "build": {
+      "command": "make",
+      "args": ["-j8"],
+      "cwd": "$ZED_WORKTREE_ROOT"
+    },
+    "program": "$ZED_WORKTREE_ROOT/build/prog",
+    "request": "launch",
+    "adapter": "CodeLLDB"
+  }
+]
+```

docs/src/languages/clojure.md

@@ -0,0 +1,15 @@
+---
+title: Clojure
+description: "Configure Clojure language support in Zed, including language servers, formatting, and debugging."
+---
+
+# Clojure
+
+Clojure support is available through the [Clojure extension](https://github.com/zed-extensions/clojure).
+
+- Tree-sitter: [prcastro/tree-sitter-clojure](https://github.com/prcastro/tree-sitter-clojure)
+- Language Server: [clojure-lsp/clojure-lsp](https://github.com/clojure-lsp/clojure-lsp)
+
+<!--
+TBD: Add some Clojure Docs
+-->

docs/src/languages/cpp.md

@@ -0,0 +1,190 @@
+---
+title: C++
+description: "Configure C++ language support in Zed, including language servers, formatting, and debugging."
+---
+
+# C++
+
+C++ support is available natively in Zed.
+
+- Tree-sitter: [tree-sitter/tree-sitter-cpp](https://github.com/tree-sitter/tree-sitter-cpp)
+- Language Server: [clangd/clangd](https://github.com/clangd/clangd)
+
+## Binary
+
+You can configure which `clangd` binary Zed should use.
+
+By default, Zed will try to find a `clangd` in your `$PATH` and try to use that. If that binary successfully executes, it's used. Otherwise, Zed will fall back to installing its own `clangd` version and use that.
+
+If you want to install a pre-release `clangd` version instead you can instruct Zed to do so by setting `pre_release` to `true` in your `settings.json`:
+
+```json [settings]
+{
+  "lsp": {
+    "clangd": {
+      "fetch": {
+        "pre_release": true
+      }
+    }
+  }
+}
+```
+
+If you want to disable Zed looking for a `clangd` binary, you can set `ignore_system_version` to `true` in your `settings.json`:
+
+```json [settings]
+{
+  "lsp": {
+    "clangd": {
+      "binary": {
+        "ignore_system_version": true
+      }
+    }
+  }
+}
+```
+
+If you want to use a binary in a custom location, you can specify a `path` and optional `arguments`:
+
+```json [settings]
+{
+  "lsp": {
+    "clangd": {
+      "binary": {
+        "path": "/path/to/clangd",
+        "arguments": []
+      }
+    }
+  }
+}
+```
+
+This `"path"` has to be an absolute path.
+
+## Arguments
+
+You can pass any number of arguments to clangd. To see a full set of available options, run `clangd --help` from the command line. For example with `--function-arg-placeholders=0` completions contain only parentheses for function calls, while the default (`--function-arg-placeholders=1`) completions also contain placeholders for method parameters.
+
+```json [settings]
+{
+  "lsp": {
+    "clangd": {
+      "binary": {
+        "path": "/path/to/clangd",
+        "arguments": ["--function-arg-placeholders=0"]
+      }
+    }
+  }
+}
+```
+
+## Formatting
+
+By default Zed will use the `clangd` language server for formatting C++ code. The Clangd is the same as the `clang-format` CLI tool. To configure this you can add a `.clang-format` file. For example:
+
+```yaml
+# yaml-language-server: $schema=https://json.schemastore.org/clang-format-21.x.json
+---
+BasedOnStyle: LLVM
+IndentWidth: 4
+---
+Language: Cpp
+# Force pointers to the type for C++.
+DerivePointerAlignment: false
+PointerAlignment: Left
+---
+```
+
+See [Clang-Format Style Options](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) for a complete list of options.
+
+You can trigger formatting via {#kb editor::Format} or the {#action editor::Format} action from the command palette or by enabling format on save.
+
+Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > C++, or add to your settings file:
+
+```json [settings]
+  "languages": {
+    "C++": {
+      "format_on_save": "on",
+      "tab_size": 2
+    }
+  }
+```
+
+## More server configuration
+
+In the root of your project, it is generally common to create a `.clangd` file to set extra configuration.
+
+```yaml
+# yaml-language-server: $schema=https://json.schemastore.org/clangd.json
+CompileFlags:
+  Add:
+    - "--include-directory=/path/to/include"
+Diagnostics:
+  MissingIncludes: Strict
+  UnusedIncludes: Strict
+```
+
+For more advanced usage of clangd configuration file, take a look into their [official page](https://clangd.llvm.org/config.html).
+
+## Compile Commands
+
+For some projects Clangd requires a `compile_commands.json` file to properly analyze your project. This file contains the compilation database that tells clangd how your project should be built.
+
+### CMake Compile Commands
+
+With CMake, you can generate `compile_commands.json` automatically by adding the following line to your `CMakeLists.txt`:
+
+```cmake
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+```
+
+After building your project, CMake will generate the `compile_commands.json` file in the build directory and clangd will automatically pick it up.
+
+## Debugging
+
+You can use CodeLLDB or GDB to debug native binaries. (Make sure that your build process passes `-g` to the C++ compiler, so that debug information is included in the resulting binary.) See below for examples of debug configurations that you can add to `.zed/debug.json`.
+
+- [CodeLLDB configuration documentation](https://github.com/vadimcn/codelldb/blob/master/MANUAL.md#starting-a-new-debug-session)
+- [GDB configuration documentation](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Debugger-Adapter-Protocol.html)
+  - GDB needs to be at least v14.1
+
+### Build and Debug Binary
+
+```json [debug]
+[
+  {
+    "label": "Debug native binary",
+    "build": {
+      "command": "make",
+      "args": ["-j8"],
+      "cwd": "$ZED_WORKTREE_ROOT"
+    },
+    "program": "$ZED_WORKTREE_ROOT/build/prog",
+    "request": "launch",
+    "adapter": "CodeLLDB"
+  }
+]
+```
+
+## Protocol Extensions
+
+Zed currently implements the following `clangd` [extensions](https://clangd.llvm.org/extensions):
+
+### Inactive Regions
+
+Automatically dims inactive sections of code due to preprocessor directives, such as `#if`, `#ifdef`, or `#ifndef` blocks that evaluate to false.
+
+### Switch Between Source and Header Files
+
+Allows switching between corresponding C++ source files (e.g., `.cpp`) and header files (e.g., `.h`).
+by running the command {#action editor::SwitchSourceHeader} from the command palette or by setting
+a keybinding for the `editor::SwitchSourceHeader` action.
+
+```json [keymap]
+{
+  "context": "Editor",
+  "bindings": {
+    "alt-enter": "editor::SwitchSourceHeader"
+  }
+}
+```

docs/src/languages/csharp.md

@@ -0,0 +1,130 @@
+---
+title: C#
+description: "Configure C# language support in Zed, including language servers, formatting, and debugging."
+---
+
+# C#
+
+C# support is available through the [C# extension](https://github.com/zed-extensions/csharp).
+
+- Tree-sitter: [tree-sitter/tree-sitter-c-sharp](https://github.com/tree-sitter/tree-sitter-c-sharp)
+- Language Servers:
+  - [roslyn-language-server](https://www.nuget.org/packages/roslyn-language-server#readme)
+  - [OmniSharp/omnisharp-roslyn](https://github.com/OmniSharp/omnisharp-roslyn)
+
+Roslyn is enabled by default. To switch back to OmniSharp, add the following to your Zed settings file:
+
+```json [settings]
+{
+  "languages": {
+    "CSharp": {
+      "language_servers": ["omnisharp", "!roslyn", "..."]
+    }
+  }
+}
+```
+
+Note: the language name used in settings is "CSharp", not "C#".
+
+## Configuration
+
+Roslyn can be configured with the following language server settings:
+
+```json [settings]
+{
+  "lsp": {
+    "roslyn": {
+      "settings": {
+        // Default values are shown below, along with alternative options where applicable.
+        "csharp|symbol_search": {
+          "dotnet_search_reference_assemblies": true
+        },
+        "csharp|type_members": {
+          "dotnet_member_insertion_location": "atTheEnd", // or "withOtherMembersOfTheSameKind"
+          "dotnet_property_generation_behavior": "preferThrowingProperties" // or "preferAutoProperties"
+        },
+        "csharp|completion": {
+          "dotnet_show_name_completion_suggestions": true,
+          "dotnet_provide_regex_completions": true,
+          "dotnet_show_completion_items_from_unimported_namespaces": true,
+          "dotnet_trigger_completion_in_argument_lists": true
+        },
+        "csharp|quick_info": {
+          "dotnet_show_remarks_in_quick_info": true
+        },
+        "csharp|navigation": {
+          "dotnet_navigate_to_decompiled_sources": true,
+          "dotnet_navigate_to_source_link_and_embedded_sources": true
+        },
+        "csharp|highlighting": {
+          "dotnet_highlight_related_json_components": true,
+          "dotnet_highlight_related_regex_components": true
+        },
+        "csharp|inlay_hints": {
+          "dotnet_enable_inlay_hints_for_parameters": true,
+          "dotnet_enable_inlay_hints_for_literal_parameters": true,
+          "dotnet_enable_inlay_hints_for_indexer_parameters": true,
+          "dotnet_enable_inlay_hints_for_object_creation_parameters": true,
+          "dotnet_enable_inlay_hints_for_other_parameters": true,
+          "dotnet_suppress_inlay_hints_for_parameters_that_differ_only_by_suffix": true,
+          "dotnet_suppress_inlay_hints_for_parameters_that_match_method_intent": true,
+          "dotnet_suppress_inlay_hints_for_parameters_that_match_argument_name": true,
+          "csharp_enable_inlay_hints_for_types": true,
+          "csharp_enable_inlay_hints_for_implicit_variable_types": true,
+          "csharp_enable_inlay_hints_for_lambda_parameter_types": true,
+          "csharp_enable_inlay_hints_for_implicit_object_creation": true,
+          "csharp_enable_inlay_hints_for_collection_expressions": true
+        },
+        "csharp|code_style.formatting.indentation_and_spacing": {
+          "tab_width": 4,
+          "indent_size": 4,
+          "indent_style": "space" // or "tab"
+        },
+        "csharp|code_style.formatting.new_line": {
+          "end_of_line": "...", // platform-specific default
+          "insert_final_newline": false
+        },
+        "csharp|background_analysis": {
+          "dotnet_analyzer_diagnostics_scope": "default", // or "none" "openFiles" "fullSolution"
+          "dotnet_compiler_diagnostics_scope": "openFiles" // or "fullSolution"
+        },
+        "csharp|code_lens": {
+          "dotnet_enable_references_code_lens": false,
+          "dotnet_enable_tests_code_lens": false
+        },
+        "csharp|auto_insert": {
+          "dotnet_enable_auto_insert": true
+        },
+        "csharp|projects": {
+          "dotnet_binary_log_path": null,
+          "dotnet_enable_automatic_restore": true,
+          "dotnet_enable_file_based_programs": true,
+          "dotnet_enable_file_based_programs_when_ambiguous": true
+        },
+        "csharp|formatting": {
+          "dotnet_organize_imports_on_format": false
+        }
+      },
+      "binary": {
+        "path": "/path/to/roslyn-language-server",
+        "arguments": ["--stdio", "--autoLoadProjects" /* add extra arguments */]
+      }
+    }
+  }
+}
+```
+
+OmniSharp can be configured in a Zed settings file with:
+
+```json [settings]
+{
+  "lsp": {
+    "omnisharp": {
+      "binary": {
+        "path": "/path/to/OmniSharp",
+        "arguments": ["-lsp" /* add extra arguments */]
+      }
+    }
+  }
+}
+```

docs/src/languages/css.md

@@ -0,0 +1,25 @@
+---
+title: CSS
+description: "Configure CSS language support in Zed, including language servers, formatting, and debugging."
+---
+
+# CSS
+
+Zed has built-in support for CSS.
+
+- Tree-sitter: [tree-sitter/tree-sitter-css](https://github.com/tree-sitter/tree-sitter-css)
+- Language Servers:
+  - [microsoft/vscode-css-languageservice](https://github.com/microsoft/vscode-css-languageservice)
+  - [tailwindcss-language-server](https://github.com/tailwindlabs/tailwindcss-intellisense)
+
+## Tailwind CSS
+
+Zed also supports [Tailwind CSS](./tailwindcss.md) out-of-the-box for languages and frameworks like JavaScript, Astro, Svelte, and more.
+
+<!-- TBD: Document CS -->
+
+## Recommended Reading
+
+- [HTML](./html.md)
+- [TypeScript](./typescript.md)
+- [JavaScript](./javascript.md)

docs/src/languages/dart.md

@@ -0,0 +1,59 @@
+---
+title: Dart
+description: "Configure Dart language support in Zed, including language servers, formatting, and debugging."
+---
+
+# Dart
+
+Dart support is available through the [Dart extension](https://github.com/zed-extensions/dart).
+
+- Tree-sitter: [UserNobody14/tree-sitter-dart](https://github.com/UserNobody14/tree-sitter-dart)
+- Language Server: [dart language-server](https://github.com/dart-lang/sdk)
+
+## Pre-requisites
+
+You will need to install the Dart SDK.
+
+You can install dart from [dart.dev/get-dart](https://dart.dev/get-dart) or via the [Flutter Version Management CLI (fvm)](https://fvm.app/documentation/getting-started/installation)
+
+## Configuration
+
+The dart extension requires no configuration if you have `dart` in your path:
+
+```sh
+which dart
+dart --version
+```
+
+If you would like to use a specific dart binary or use dart via FVM you can specify the `dart` binary in your Zed settings.jsons file:
+
+```json [settings]
+{
+  "lsp": {
+    "dart": {
+      "binary": {
+        "path": "/opt/homebrew/bin/fvm",
+        "arguments": ["dart", "language-server", "--protocol=lsp"]
+      }
+    }
+  }
+}
+```
+
+### Formatting
+
+Dart by-default uses a very conservative maximum line length (80). If you would like the dart LSP to permit a longer line length when auto-formatting, add the following to your Zed settings.json:
+
+```json [settings]
+{
+  "lsp": {
+    "dart": {
+      "settings": {
+        "lineLength": 140
+      }
+    }
+  }
+}
+```
+
+Please see the Dart documentation for more information on [dart language-server capabilities](https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server/tool/lsp_spec/README.md).

docs/src/languages/deno.md

@@ -0,0 +1,134 @@
+---
+title: Deno
+description: "Configure Deno language support in Zed, including language servers, formatting, and debugging."
+---
+
+# Deno
+
+Deno support is available through the [Deno extension](https://github.com/zed-extensions/deno).
+
+- Language server: [Deno Language Server](https://docs.deno.com/runtime/manual/advanced/language_server/overview/)
+
+## Deno Configuration
+
+To use the Deno Language Server with TypeScript and TSX files, you will likely wish to disable the default language servers and enable Deno.
+
+Configure language servers and formatters in Settings ({#kb zed::OpenSettings}) under Languages > JavaScript/TypeScript/TSX, or add to your settings file:
+
+```json [settings]
+{
+  "lsp": {
+    "deno": {
+      "settings": {
+        "deno": {
+          "enable": true
+        }
+      }
+    }
+  },
+  "languages": {
+    "JavaScript": {
+      "language_servers": [
+        "deno",
+        "!typescript-language-server",
+        "!vtsls",
+        "!eslint"
+      ],
+      "formatter": "language_server"
+    },
+    "TypeScript": {
+      "language_servers": [
+        "deno",
+        "!typescript-language-server",
+        "!vtsls",
+        "!eslint"
+      ],
+      "formatter": "language_server"
+    },
+    "TSX": {
+      "language_servers": [
+        "deno",
+        "!typescript-language-server",
+        "!vtsls",
+        "!eslint"
+      ],
+      "formatter": "language_server"
+    }
+  }
+}
+```
+
+See [Configuring supported languages](../configuring-languages.md) in the Zed documentation for more information.
+
+<!--
+TBD: Deno TypeScript REPL instructions [docs/repl#typescript-deno](../repl.md#typescript-deno)
+-->
+
+## Configuration completion
+
+To get completions for `deno.json` or `package.json`, add the following to your settings file ([how to edit](../configuring-zed.md#settings-files)). For more details, see [JSON](./json.md).
+
+```json [settings]
+"lsp": {
+    "json-language-server": {
+      "settings": {
+        "json": {
+          "schemas": [
+            {
+              "fileMatch": [
+                "deno.json",
+                "deno.jsonc"
+              ],
+              "url": "https://raw.githubusercontent.com/denoland/deno/refs/heads/main/cli/schemas/config-file.v1.json"
+            },
+            {
+              "fileMatch": [
+                "package.json"
+              ],
+              "url": "https://www.schemastore.org/package"
+            }
+          ]
+        }
+      }
+    }
+  }
+```
+
+## DAP support
+
+To debug deno programs, add this to `.zed/debug.json`
+
+```json [debug]
+[
+  {
+    "adapter": "JavaScript",
+    "label": "Deno",
+    "request": "launch",
+    "type": "pwa-node",
+    "cwd": "$ZED_WORKTREE_ROOT",
+    "program": "$ZED_FILE",
+    "runtimeExecutable": "deno",
+    "runtimeArgs": ["run", "--allow-all", "--inspect-wait"],
+    "attachSimplePort": 9229
+  }
+]
+```
+
+## Runnable support
+
+To run deno tasks like tests from the ui, add this to `.zed/tasks.json`
+
+```json [tasks]
+[
+  {
+    "label": "deno test",
+    "command": "deno test -A '$ZED_FILE'",
+    "tags": ["js-test"]
+  }
+]
+```
+
+## See also:
+
+- [TypeScript](./typescript.md)
+- [JavaScript](./javascript.md)