Autofix

Support to Languages.

docs/book.toml

@@ -56,6 +56,9 @@ enable = false
 "/model-improvement.html" = "/docs/ai/ai-improvement.html"
 "/ai/temperature.html" = "/docs/ai/agent-settings.html#model-temperature"
 
+# Core
+"/configuring-zed.html" = "/docs/reference/all-settings.html"
+
 # Collaboration
 "/channels.html" = "/docs/collaboration/channels.html"
 "/collaboration.html" = "/docs/collaboration/overview.html"

docs/src/SUMMARY.md

@@ -6,55 +6,8 @@
 - [Installation](./installation.md)
   - [Update](./update.md)
   - [Uninstall](./uninstall.md)
-- [Authenticate](./authentication.md)
-- [Telemetry](./telemetry.md)
 - [Troubleshooting](./troubleshooting.md)
 
-# Configuration
-
-- [Configuring Zed](./configuring-zed.md)
-- [Configuring Languages](./configuring-languages.md)
-  - [Toolchains](./toolchains.md)
-- [Key bindings](./key-bindings.md)
-  - [All Actions](./all-actions.md)
-- [Snippets](./snippets.md)
-- [Themes](./themes.md)
-- [Icon Themes](./icon-themes.md)
-- [Visual Customization](./visual-customization.md)
-- [Vim Mode](./vim.md)
-- [Helix Mode](./helix.md)
-- [Privacy and Security](./ai/privacy-and-security.md)
-  - [Worktree Trust](./worktree-trust.md)
-  - [AI Improvement](./ai/ai-improvement.md)
-
-<!-- - [Globs](./globs.md) -->
-<!-- - [Fonts](./fonts.md) -->
-
-# Using Zed
-
-- [Multibuffers](./multibuffers.md)
-- [Command Palette](./command-palette.md)
-- [Command-line Interface](./command-line-interface.md)
-- [Outline Panel](./outline-panel.md)
-- [Code Completions](./completions.md)
-- [Collaboration](./collaboration/overview.md)
-  - [Channels](./collaboration/channels.md)
-  - [Contacts and Private Calls](./collaboration/contacts-and-private-calls.md)
-- [Git](./git.md)
-- [Debugger](./debugger.md)
-- [Diagnostics](./diagnostics.md)
-- [Tasks](./tasks.md)
-- [Tab Switcher](./tab-switcher.md)
-- [Remote Development](./remote-development.md)
-- [Dev Containers](./dev-containers.md)
-- [Environment Variables](./environment.md)
-- [REPL](./repl.md)
-
-# Platform Support
-
-- [Windows](./windows.md)
-- [Linux](./linux.md)
-
 # AI
 
 - [Overview](./ai/overview.md)
@@ -74,31 +27,57 @@
   - [Plans and Usage](./ai/plans-and-usage.md)
   - [Billing](./ai/billing.md)
 
-# Extensions
+# Working with Code
 
-- [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)
-- [Slash Command Extensions](./extensions/slash-commands.md)
-- [Agent Server Extensions](./extensions/agent-servers.md)
-- [MCP Server Extensions](./extensions/mcp-extensions.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)
+  - [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)
 
-# Coming From...
+# Collaboration
 
-- [VS Code](./migrate/vs-code.md)
-- [IntelliJ IDEA](./migrate/intellij.md)
-- [PyCharm](./migrate/pycharm.md)
-- [WebStorm](./migrate/webstorm.md)
-- [RustRover](./migrate/rustrover.md)
+- [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)
+
+# 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)
 - [Ansible](./languages/ansible.md)
 - [AsciiDoc](./languages/asciidoc.md)
 - [Astro](./languages/astro.md)
@@ -170,6 +149,42 @@
 - [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)
+- [Slash Command Extensions](./extensions/slash-commands.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)
+
+# Account & Privacy
+
+- [Authenticate](./authentication.md)
+- [Privacy and Security](./ai/privacy-and-security.md)
+  - [Worktree Trust](./worktree-trust.md)
+  - [AI Improvement](./ai/ai-improvement.md)
+- [Telemetry](./telemetry.md)
+
 # Developing Zed
 
 - [Developing Zed](./development.md)

docs/src/ai/ai-improvement.md

@@ -77,7 +77,7 @@ You can inspect this exclusion list by opening `zed: open default settings` from
 }
 ```
 
-Users may explicitly exclude additional paths and/or file extensions by adding them to [`edit_predictions.disabled_globs`](https://zed.dev/docs/configuring-zed#edit-predictions) in their Zed settings.json:
+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.json:
 
 ```json [settings]
 {

docs/src/appearance.md

@@ -0,0 +1,121 @@
+# 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. **Choose an icon theme**: Run `icon theme selector: toggle` from the command palette to browse icon themes.
+
+3. **Set your font**: Open the Settings Editor with {#kb zed::OpenSettings} and search for `buffer_font_family`. Set it to your preferred coding font.
+
+4. **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 (`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/collaboration/channels.md

@@ -35,7 +35,7 @@ Once you have added someone, they can either join your channel by clicking on it
 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 will automatically share your microphone with other users in the call, if your OS allows it.
-> If you'd prefer your microphone to be off when joining a channel, you can do so via the [`mute_on_join`](../configuring-zed.md#calls) setting.
+> If you'd prefer your microphone to be off when joining a channel, you can do so via the [`mute_on_join`](../reference/all-settings.md#calls) setting.
 
 ## Sharing Projects
 

docs/src/command-line-interface.md

@@ -1,18 +1,3 @@
-# Command-line Interface
+# Command-Line Interface
 
-Zed has a CLI, on Linux this should come with the distribution's Zed package (binary name can vary from distribution to distribution, `zed` will be used later for brevity).
-For macOS, the CLI comes in the same package with the editor binary, and could be installed into the system with the `cli: install` Zed command which will create a symlink to the `/usr/local/bin/zed`.
-It can also be built from source out of the `cli` crate in this repository.
-
-Use `zed --help` to see the full list of capabilities.
-General highlights:
-
-- Opening another empty Zed window: `zed`
-
-- Opening a file or directory in Zed: `zed /path/to/entry` (use `-n` to open in the new window)
-
-- Reading from stdin: `ps axf | zed -`
-
-- Starting Zed with logs in the terminal: `zed --foreground`
-
-- Uninstalling Zed and all its related files: `zed --uninstall`
+This page has moved to the [CLI Reference](./reference/cli.md).

docs/src/configuring-languages.md

@@ -49,16 +49,16 @@ Here's an example of language-specific settings:
 
 You can customize a wide range of settings for each language, including:
 
-- [`tab_size`](./configuring-zed.md#tab-size): The number of spaces for each indentation level
-- [`formatter`](./configuring-zed.md#formatter): The tool used for code formatting
-- [`format_on_save`](./configuring-zed.md#format-on-save): Whether to automatically format code when saving
-- [`enable_language_server`](./configuring-zed.md#enable-language-server): Toggle language server support
-- [`hard_tabs`](./configuring-zed.md#hard-tabs): Use tabs instead of spaces for indentation
-- [`preferred_line_length`](./configuring-zed.md#preferred-line-length): The recommended maximum line length
-- [`soft_wrap`](./configuring-zed.md#soft-wrap): How to wrap long lines of code
-- [`show_completions_on_input`](./configuring-zed.md#show-completions-on-input): Whether or not to show completions as you type
-- [`show_completion_documentation`](./configuring-zed.md#show-completion-documentation): Whether to display inline and alongside documentation for items in the completions menu
-- [`colorize_brackets`](./configuring-zed.md#colorize-brackets): Whether to use tree-sitter bracket queries to detect and colorize the brackets in the editor (also known as "rainbow brackets")
+- [`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.
 
@@ -66,7 +66,7 @@ These settings allow you to maintain specific coding styles across different lan
 
 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`](./configuring-zed.md#file-types) setting in your `settings.json`:
+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": {
@@ -266,7 +266,7 @@ Zed provides support for code formatting and linting to maintain consistent code
 
 ### Configuring Formatters
 
-Zed supports both built-in and external formatters. See [`formatter`](./configuring-zed.md#formatter) docs for more. You can configure formatters globally or per-language in your `settings.json`:
+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": {

docs/src/editing-code.md

@@ -0,0 +1,31 @@
+# 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
+
+- [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

@@ -4,8 +4,8 @@ _**Note**: The following only applies to Zed 0.152.0 and later._
 
 Multiple features in Zed are affected by environment variables:
 
-- Tasks
-- Built-in terminal
+- [Tasks](./tasks.md)
+- [Built-in terminal](./terminal.md)
 - Look-up of language servers
 - Language servers
 

docs/src/extensions/installing-extensions.md

@@ -17,4 +17,4 @@ This directory contains two subdirectories:
 
 ## Auto installing
 
-To automate extension installation/uninstallation see the docs for [auto_install_extensions](../configuring-zed.md#auto-install-extensions).
+To automate extension installation/uninstallation see the docs for [auto_install_extensions](../reference/all-settings.md#auto-install-extensions).

docs/src/finding-navigating.md

@@ -0,0 +1,52 @@
+# 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)
+
+## 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}. 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}       |

docs/src/getting-started.md

@@ -2,18 +2,78 @@
 
 Welcome to Zed! We are excited to have you. Zed is a powerful multiplayer code editor designed to stay out of your way and help you build what's next.
 
-## Key Features
+This guide gets you from zero to productive in Zed. You'll learn the essential commands, configure your environment, and find your way around.
 
-- [Smooth Editing](./configuring-zed.md): Built in Rust, Zed is responsive and intuitive, with a minimalistic aesthetic and pixel-level editing controls.
-- [Agentic Editing](./ai/overview.md): Use Zed's hosted models to collaborate with agents directly in an IDE. You can also plug into a third-party agent or bring your own keys.
-- [Debugger](./debugger.md): Debug your code in seconds, not hours, with minimal setup required.
-- [Remote Development](./remote-development.md): Offload the heavy lifting to the cloud, so you can focus on writing code.
-- [Extensions](./extensions.md): Leverage Zed's extensions to customize how you work.
+## Quick Start
 
-## Join the Zed Community
+### 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.
+
+### 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 proudly open source, and we get better with every contribution. Join us on GitHub or in Discord to contribute code, report bugs, or suggest features.
 
-- [Join Discord](https://discord.com/invite/zedindustries)
+- [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/globs.md

@@ -55,7 +55,7 @@ If instead you wanted to restrict yourself only to [Zed Language-Specific Docume
 
 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`](./configuring-zed.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:
+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]
 {

docs/src/languages/diff.md

@@ -6,7 +6,7 @@ Diff support is available natively in Zed.
 
 ## Configuration
 
-Zed will not attempt to format diff files and has [`remove_trailing_whitespace_on_save`](https://zed.dev/docs/configuring-zed#remove-trailing-whitespace-on-save) and [`ensure-final-newline-on-save`](https://zed.dev/docs/configuring-zed#ensure-final-newline-on-save) set to false.
+Zed will not attempt to format diff files and has [`remove_trailing_whitespace_on_save`](https://zed.dev/docs/reference/all-settings#remove-trailing-whitespace-on-save) and [`ensure-final-newline-on-save`](https://zed.dev/docs/reference/all-settings#ensure-final-newline-on-save) set to false.
 
 Zed will automatically recognize files with `patch` and `diff` extensions as Diff files. To recognize other extensions, add them to `file_types` in your Zed settings.json:
 

docs/src/languages/javascript.md

@@ -12,7 +12,7 @@ JavaScript support is available natively in Zed.
 Formatting on save is enabled by default for JavaScript, using TypeScript's built-in code formatting.
 But many JavaScript projects use other command-line code-formatting tools, such as [Prettier](https://prettier.io/).
 You can use one of these tools by specifying an _external_ code formatter for JavaScript in your settings.
-See [the configuration docs](../configuring-zed.md) for more information.
+See [the configuration docs](../reference/all-settings.md) for more information.
 
 For example, if you have Prettier installed and on your `PATH`, you can use it to format JavaScript files by adding the following to your `settings.json`:
 

docs/src/languages/markdown.md

@@ -23,7 +23,7 @@ def fib(n):
 
 ### Format
 
-Zed supports using Prettier to automatically re-format Markdown documents. You can trigger this manually via the {#action editor::Format} action or via the {#kb editor::Format} keyboard shortcut. Alternately, you can automatically format by enabling [`format_on_save`](../configuring-zed.md#format-on-save) in your settings.json:
+Zed supports using Prettier to automatically re-format Markdown documents. You can trigger this manually via the {#action editor::Format} action or via the {#kb editor::Format} keyboard shortcut. Alternately, you can automatically format by enabling [`format_on_save`](../reference/all-settings.md#format-on-save) in your settings.json:
 
 ```json [settings]
   "languages": {

docs/src/languages/proto.md

@@ -60,7 +60,7 @@ IndentWidth: 4
 ColumnLimit: 120
 ```
 
-Or you can have zed directly invoke `clang-format` by specifying it as a [formatter](https://zed.dev/docs/configuring-zed#formatter) in your settings:
+Or you can have zed directly invoke `clang-format` by specifying it as a [formatter](https://zed.dev/docs/reference/all-settings#formatter) in your settings:
 
 ```json [settings]
   "languages": {

docs/src/languages/python.md

@@ -63,7 +63,7 @@ Zed will recognize `.py` files automatically using its native tree-sitter-python
 
 ### Step 2: Use the Integrated Terminal (Optional)
 
-Zed includes an integrated terminal, accessible from the bottom panel. If Zed detects that your project is using a [virtual environment](#virtual-environments), it will be activated automatically in newly-created terminals. You can configure this behavior with the [`detect_venv`](../configuring-zed.md#terminal-detect_venv) setting.
+Zed includes an integrated terminal, accessible from the bottom panel. If Zed detects that your project is using a [virtual environment](#virtual-environments), it will be activated automatically in newly-created terminals. You can configure this behavior with the [`detect_venv`](../reference/all-settings.md#terminal-detect_venv) setting.
 
 ## Configure Python Language Servers in Zed
 

docs/src/languages/xml.md

@@ -6,7 +6,7 @@ XML support is available through the [XML extension](https://github.com/sweetppr
 
 ## Configuration
 
-If you have additional file extensions that are not being automatically recognized as XML just add them to [file_types](../configuring-zed.md#file-types) in your Zed settings:
+If you have additional file extensions that are not being automatically recognized as XML just add them to [file_types](../reference/all-settings.md#file-types) in your Zed settings:
 
 ```json [settings]
   "file_types": {

docs/src/languages/yarn.md

@@ -5,5 +5,5 @@
 ## Setup
 
 1. Run `yarn dlx @yarnpkg/sdks base` to generate a `.yarn/sdks` directory.
-2. Set your language server (e.g. VTSLS) to use TypeScript SDK from `.yarn/sdks/typescript/lib` directory in [LSP initialization options](../configuring-zed.md#lsp). The actual setting for that depends on language server; for example, for VTSLS you should set [`typescript.tsdk`](https://github.com/yioneko/vtsls/blob/6adfb5d3889ad4b82c5e238446b27ae3ee1e3767/packages/service/configuration.schema.json#L5).
+2. Set your language server (e.g. VTSLS) to use TypeScript SDK from `.yarn/sdks/typescript/lib` directory in [LSP initialization options](../reference/all-settings.md#lsp). The actual setting for that depends on language server; for example, for VTSLS you should set [`typescript.tsdk`](https://github.com/yioneko/vtsls/blob/6adfb5d3889ad4b82c5e238446b27ae3ee1e3767/packages/service/configuration.schema.json#L5).
 3. Voilla! Language server functionalities such as Go to Definition, Code Completions and On Hover documentation should work.

docs/src/macos.md

@@ -0,0 +1,118 @@
+# Zed on macOS
+
+Zed is developed primarily on macOS, making it a first-class platform with full feature support.
+
+## Installing Zed
+
+Download Zed from the [download page](https://zed.dev/download). The download is a `.dmg` file—open it and drag Zed to your Applications folder.
+
+For the preview build, which receives updates about a week ahead of stable, visit the [preview releases page](https://zed.dev/releases/preview).
+
+After installation, Zed checks for updates automatically and prompts you when a new version is available.
+
+### Homebrew
+
+You can also install Zed using Homebrew:
+
+```sh
+brew install --cask zed
+```
+
+For the preview version:
+
+```sh
+brew install --cask zed@preview
+```
+
+### Building from Source
+
+To build Zed from source, see the [macOS development documentation](./development/macos.md).
+
+## System Requirements
+
+- macOS 10.15.7 (Catalina) or later
+- Apple Silicon (M1/M2/M3/M4) or Intel processor
+
+Zed uses Metal for GPU-accelerated rendering, which is available on all supported macOS versions.
+
+## Installing the CLI
+
+Zed includes a command-line tool for opening files and projects from Terminal. To install it:
+
+1. Open Zed
+2. Open the command palette with `Cmd+Shift+P`
+3. Run `cli: install`
+
+This creates a `zed` command in `/usr/local/bin`. You can then open files and folders:
+
+```sh
+zed .                    # Open current folder
+zed file.txt             # Open a file
+zed project/ file.txt    # Open a folder and a file
+```
+
+See the [CLI Reference](./command-line-interface.md) for all available options.
+
+## Uninstall
+
+1. Quit Zed if it's running
+2. Drag Zed from Applications to the Trash
+3. Optionally, remove your settings and extensions:
+
+```sh
+rm -rf ~/.config/zed
+rm -rf ~/Library/Application\ Support/Zed
+rm -rf ~/Library/Caches/Zed
+rm -rf ~/Library/Logs/Zed
+rm -rf ~/Library/Saved\ Application\ State/dev.zed.Zed.savedState
+```
+
+If you installed the CLI, remove it with:
+
+```sh
+rm /usr/local/bin/zed
+```
+
+## Troubleshooting
+
+### Zed won't open or shows "damaged" warning
+
+If macOS reports that Zed is damaged or can't be opened, it's likely a Gatekeeper issue. Try:
+
+1. Right-click (or Control-click) on Zed in Applications
+2. Select "Open" from the context menu
+3. Click "Open" in the dialog that appears
+
+This tells macOS to trust the application.
+
+If that doesn't work, remove the quarantine attribute:
+
+```sh
+xattr -cr /Applications/Zed.app
+```
+
+### CLI command not found
+
+If the `zed` command isn't available after installation:
+
+1. Check that `/usr/local/bin` is in your PATH
+2. Try reinstalling the CLI via `cli: install` in the command palette
+3. Open a new terminal window to reload your PATH
+
+### GPU or rendering issues
+
+Zed uses Metal for rendering. If you experience graphical glitches:
+
+1. Ensure macOS is up to date
+2. Restart your Mac to reset the GPU state
+3. Check Activity Monitor for GPU pressure from other apps
+
+### High memory or CPU usage
+
+If Zed uses more resources than expected:
+
+1. Check for runaway language servers in the terminal output (`zed: open log`)
+2. Try disabling extensions one by one to identify conflicts
+3. For large projects, consider using [project settings](./reference/all-settings.md#file-scan-exclusions) to exclude unnecessary folders from indexing
+
+For additional help, see the [Troubleshooting guide](./troubleshooting.md) or visit the [Zed Discord](https://discord.gg/zed-community).

docs/src/migrate/_research-notes.md

@@ -1,73 +0,0 @@
-<!--
-  TEMPORARY RESEARCH FILE - Delete when migration guides are complete
-
-  This file contains external community insights used to add "flair" to migration guides.
-  These are NOT the template or backbone—use intellij.md as the structural template.
-
-  STATUS:
-  ✅ PyCharm guide - COMPLETE
-  ✅ WebStorm guide - COMPLETE
-  ✅ RustRover guide - COMPLETE
--->
-
-# Migration Research Notes
-
-## Completed Guides
-
-All three JetBrains migration guides have been populated with full content:
-
-1. **pycharm.md** - Python development, virtual environments, Ruff/Pyright, Django/Flask workflows
-2. **webstorm.md** - JavaScript/TypeScript development, npm workflows, framework considerations
-3. **rustrover.md** - Rust development, rust-analyzer parity, Cargo workflows, licensing notes
-
-## Key Sources Used
-
-- IntelliJ IDEA migration doc (structural template)
-- JetBrains PyCharm Getting Started docs
-- JetBrains WebStorm Getting Started docs
-- JetBrains RustRover Quick Start Guide
-- External community feedback (Reddit, Hacker News, Medium)
-
-## External Quotes Incorporated
-
-### WebStorm Guide
-
-> "I work for AWS and the applications I deal with are massive. Often I need to keep many projects open due to tight dependencies. I'm talking about complex microservices and micro frontend infrastructure which oftentimes lead to 2-15 minutes of indexing wait time whenever I open a project or build the system locally."
-
-### RustRover Guide
-
-- Noted rust-analyzer shared foundation between RustRover and Zed
-- Addressed licensing/telemetry concerns that motivate some users to switch
-- Included debugger caveats based on community feedback
-
-## Cross-Cutting Themes Applied to All Guides
-
-### Universal Pain Points Addressed
-
-1. Indexing (instant in Zed)
-2. Resource usage (Zed is lightweight)
-3. Startup time (Zed is near-instant)
-4. UI clutter (Zed is minimal by design)
-
-### Universal Missing Features Documented
-
-- No project model / SDK management
-- No database tools
-- No framework-specific integration
-- No visual run configurations (use tasks)
-- No built-in HTTP client
-
-### JetBrains Keymap Emphasized
-
-All three guides emphasize:
-
-- Select JetBrains keymap during onboarding or in settings
-- `Shift Shift` for Search Everywhere works
-- Most familiar shortcuts preserved
-
-## Next Steps (Optional Enhancements)
-
-- [ ] Cross-link guides to JetBrains docs for users who want to reference original IDE features
-- [ ] Add a consolidated "hub page" linking to all migration guides
-- [ ] Consider adding VS Code migration guide using similar structure
-- [ ] Review for tone consistency against Zed Documentation Guidelines

docs/src/migrate/intellij.md

@@ -349,7 +349,7 @@ Here are a few useful tweaks:
 
 Now that you're set up, here are some resources to help you get the most out of Zed:
 
-- [Configuring Zed](../configuring-zed.md) — Customize settings, themes, and editor behavior
+- [All Settings](../reference/all-settings.md) — Customize settings, themes, and editor behavior
 - [Key Bindings](../key-bindings.md) — Learn how to customize and extend your keymap
 - [Tasks](../tasks.md) — Set up build and run commands for your projects
 - [AI Features](../ai/overview.md) — Explore Zed's AI capabilities beyond code completion

docs/src/migrate/pycharm.md

@@ -430,7 +430,7 @@ Options are `"off"`, `"basic"`, `"standard"` (default), `"strict"`, or `"all"`.
 
 Now that you're set up, here are some resources to help you get the most out of Zed:
 
-- [Configuring Zed](../configuring-zed.md) — Customize settings, themes, and editor behavior
+- [All Settings](../reference/all-settings.md) — Customize settings, themes, and editor behavior
 - [Key Bindings](../key-bindings.md) — Learn how to customize and extend your keymap
 - [Tasks](../tasks.md) — Set up build and run commands for your projects
 - [AI Features](../ai/overview.md) — Explore Zed's AI capabilities beyond code completion

docs/src/migrate/rustrover.md

@@ -493,7 +493,7 @@ If you work with multiple Cargo projects that aren't in a workspace, you can tel
 
 Now that you're set up, here are some resources to help you get the most out of Zed:
 
-- [Configuring Zed](../configuring-zed.md) — Customize settings, themes, and editor behavior
+- [All Settings](../reference/all-settings.md) — Customize settings, themes, and editor behavior
 - [Key Bindings](../key-bindings.md) — Learn how to customize and extend your keymap
 - [Tasks](../tasks.md) — Set up build and run commands for your projects
 - [AI Features](../ai/overview.md) — Explore Zed's AI capabilities beyond code completion

docs/src/migrate/webstorm.md

@@ -446,7 +446,7 @@ In your `tsconfig.json`, enable strict mode for better type checking:
 
 Now that you're set up, here are some resources to help you get the most out of Zed:
 
-- [Configuring Zed](../configuring-zed.md) — Customize settings, themes, and editor behavior
+- [All Settings](../reference/all-settings.md) — Customize settings, themes, and editor behavior
 - [Key Bindings](../key-bindings.md) — Learn how to customize and extend your keymap
 - [Tasks](../tasks.md) — Set up build and run commands for your projects
 - [AI Features](../ai/overview.md) — Explore Zed's AI capabilities beyond code completion

docs/src/reference/cli.md

@@ -0,0 +1,191 @@
+# CLI Reference
+
+Zed includes a command-line interface (CLI) for opening files and directories, integrating with other tools, and controlling Zed from scripts.
+
+## Installation
+
+**macOS:** Run the `cli: install` command from the command palette ({#kb command_palette::Toggle}) to install the `zed` CLI to `/usr/local/bin/zed`.
+
+**Linux:** The CLI is included with Zed packages. The binary name may vary by distribution (commonly `zed` or `zeditor`).
+
+**Windows:** The CLI is included with Zed. Add Zed's installation directory to your PATH, or use the full path to `zed.exe`.
+
+## Usage
+
+```sh
+zed [OPTIONS] [PATHS]...
+```
+
+## Opening Files and Directories
+
+Open a file:
+
+```sh
+zed myfile.txt
+```
+
+Open a directory as a workspace:
+
+```sh
+zed ~/projects/myproject
+```
+
+Open multiple files or directories:
+
+```sh
+zed file1.txt file2.txt ~/projects/myproject
+```
+
+Open a file at a specific line and column:
+
+```sh
+zed myfile.txt:42        # Open at line 42
+zed myfile.txt:42:10     # Open at line 42, column 10
+```
+
+## Options
+
+### `-w`, `--wait`
+
+Wait for all opened files to be closed before the CLI exits. When opening a directory, waits until the window is closed.
+
+This is useful for integrating Zed with tools that expect an editor to block until editing is complete (e.g., `git commit`):
+
+```sh
+export EDITOR="zed --wait"
+git commit  # Opens Zed and waits for you to close the commit message file
+```
+
+### `-n`, `--new`
+
+Open paths in a new workspace window, even if the paths are already open in an existing window:
+
+```sh
+zed -n ~/projects/myproject
+```
+
+### `-a`, `--add`
+
+Add paths to the currently focused workspace instead of opening a new window:
+
+```sh
+zed -a newfile.txt
+```
+
+### `-r`, `--reuse`
+
+Reuse an existing window, replacing its current workspace with the new paths:
+
+```sh
+zed -r ~/projects/different-project
+```
+
+### `--diff <OLD_PATH> <NEW_PATH>`
+
+Open a diff view comparing two files. Can be specified multiple times:
+
+```sh
+zed --diff file1.txt file2.txt
+zed --diff old.rs new.rs --diff old2.rs new2.rs
+```
+
+### `--foreground`
+
+Run Zed in the foreground, keeping the terminal attached. Useful for debugging:
+
+```sh
+zed --foreground
+```
+
+### `--user-data-dir <DIR>`
+
+Use a custom directory for all user data (database, extensions, logs) instead of the default location:
+
+```sh
+zed --user-data-dir ~/.zed-custom
+```
+
+Default locations:
+
+- **macOS:** `~/Library/Application Support/Zed`
+- **Linux:** `$XDG_DATA_HOME/zed` (typically `~/.local/share/zed`)
+- **Windows:** `%LOCALAPPDATA%\Zed`
+
+### `-v`, `--version`
+
+Print Zed's version and exit:
+
+```sh
+zed --version
+```
+
+### `--uninstall`
+
+Uninstall Zed and remove all related files (macOS and Linux only):
+
+```sh
+zed --uninstall
+```
+
+### `--zed <PATH>`
+
+Specify a custom path to the Zed application or binary:
+
+```sh
+zed --zed /path/to/Zed.app myfile.txt
+```
+
+## Reading from Standard Input
+
+Read content from stdin by passing `-` as the path:
+
+```sh
+echo "Hello, World!" | zed -
+cat myfile.txt | zed -
+ps aux | zed -
+```
+
+This creates a temporary file with the stdin content and opens it in Zed.
+
+## URL Handling
+
+The CLI can open `zed://`, `http://`, and `https://` URLs:
+
+```sh
+zed zed://settings
+zed https://github.com/zed-industries/zed
+```
+
+## Using Zed as Your Default Editor
+
+Set Zed as your default editor for Git and other tools:
+
+```sh
+export EDITOR="zed --wait"
+export VISUAL="zed --wait"
+```
+
+Add these lines to your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`).
+
+## macOS: Switching Release Channels
+
+On macOS, you can launch a specific release channel by passing the channel name as the first argument:
+
+```sh
+zed --stable myfile.txt
+zed --preview myfile.txt
+zed --nightly myfile.txt
+```
+
+## WSL Integration (Windows)
+
+On Windows, the CLI supports opening paths from WSL distributions. This is handled automatically when launching Zed from within WSL.
+
+## Exit Codes
+
+| Code | Meaning                           |
+| ---- | --------------------------------- |
+| `0`  | Success                           |
+| `1`  | Error (details printed to stderr) |
+
+When using `--wait`, the exit code reflects whether the files were saved before closing.

docs/src/reference/default-key-bindings.md

@@ -0,0 +1 @@
+# Default Key Bindings

docs/src/remote-development.md

@@ -204,7 +204,7 @@ Alternatively, you can configure the proxy in the remote machine's `~/.config/ze
 }
 ```
 
-See the [proxy documentation](./configuring-zed.md#network-proxy) for supported proxy types and additional configuration options.
+See the [proxy documentation](./reference/all-settings.md#network-proxy) for supported proxy types and additional configuration options.
 
 ## Initializing the remote server
 

docs/src/running-testing.md

@@ -0,0 +1,23 @@
+# Running & Testing
+
+This section covers how to run, test, and debug your code without leaving Zed.
+
+## What's here
+
+- **[Terminal](./terminal.md)**: Zed's built-in terminal emulator. Open multiple terminals, customize your shell, and integrate with the editor. Tasks and commands run here.
+
+- **[Tasks](./tasks.md)**: Define and run shell commands with access to editor context like the current file, selection, or symbol. Use tasks to build, lint, run scripts, or execute any repeatable workflow.
+
+- **[Debugger](./debugger.md)**: Set breakpoints, step through code, and inspect variables using Zed's built-in debugger. Works with C, C++, Go, JavaScript, Python, Rust, TypeScript, and more through the Debug Adapter Protocol.
+
+- **[REPL](./repl.md)**: Run code interactively using Jupyter kernels. Execute selections or cells and see results inline—useful for Python, TypeScript (Deno), R, Julia, and other supported languages.
+
+## Quick start
+
+**Open a terminal**: Press `` Ctrl+` `` to toggle the terminal panel, or `Ctrl+~` to open a new terminal.
+
+**Run a command**: Press `Cmd+Shift+R` (macOS) or `Ctrl+Shift+R` (Linux/Windows) to open the task picker, then type any shell command.
+
+**Start debugging**: Press `Cmd+Shift+D` (macOS) or `Ctrl+Shift+D` (Linux/Windows) to open the debug panel and select a configuration.
+
+**Run code interactively**: In a Python or TypeScript file, select some code and press `Ctrl+Shift+Enter` to execute it in a REPL session.

docs/src/tasks.md

@@ -1,6 +1,6 @@
 # Tasks
 
-Zed supports ways to spawn (and rerun) commands using its integrated terminal to output the results. These commands can read a limited subset of Zed state (such as a path to the file currently being edited or selected text).
+Zed supports ways to spawn (and rerun) commands using its integrated [terminal](./terminal.md) to output the results. These commands can read a limited subset of Zed state (such as a path to the file currently being edited or selected text).
 
 ```json [tasks]
 [

docs/src/terminal.md

@@ -0,0 +1,370 @@
+# Terminal
+
+Zed includes a built-in terminal emulator that supports multiple terminal instances, custom shells, and deep integration with the editor.
+
+## Opening Terminals
+
+| Action                  | macOS           | Linux/Windows   |
+| ----------------------- | --------------- | --------------- |
+| Toggle terminal panel   | `` Ctrl+` ``    | `` Ctrl+` ``    |
+| Open new terminal       | `Ctrl+~`        | `Ctrl+~`        |
+| Open terminal in center | Command palette | Command palette |
+
+You can also open a terminal from the command palette with `terminal panel: toggle` or `workspace: new terminal`.
+
+### Terminal Panel vs Center Terminal
+
+Terminals can open in two locations:
+
+- **Terminal Panel** — Docked at the bottom (default), left, or right of the workspace. Toggle with `` Ctrl+` ``.
+- **Center Pane** — Opens as a regular tab alongside your files. Use `workspace: new center terminal` from the command palette.
+
+## Working with Multiple Terminals
+
+Create additional terminals with `Cmd+N` (macOS) or `Ctrl+N` (Linux/Windows) while focused in the terminal panel. Each terminal appears as a tab in the panel.
+
+Split terminals horizontally with `Cmd+D` (macOS) or `Ctrl+Shift+5` (Linux/Windows).
+
+## Configuring the Shell
+
+By default, Zed uses your system's default shell (from `/etc/passwd` on Unix systems). To use a different shell:
+
+```json [settings]
+{
+  "terminal": {
+    "shell": {
+      "program": "/bin/zsh"
+    }
+  }
+}
+```
+
+To pass arguments to your shell:
+
+```json [settings]
+{
+  "terminal": {
+    "shell": {
+      "with_arguments": {
+        "program": "/bin/bash",
+        "args": ["--login"]
+      }
+    }
+  }
+}
+```
+
+## Working Directory
+
+Control where new terminals start:
+
+| Value                                         | Behavior                                                        |
+| --------------------------------------------- | --------------------------------------------------------------- |
+| `"current_project_directory"`                 | Uses the project directory of the currently open file (default) |
+| `"first_project_directory"`                   | Uses the first project in your workspace                        |
+| `"always_home"`                               | Always starts in your home directory                            |
+| `{ "always": { "directory": "~/projects" } }` | Always starts in a specific directory                           |
+
+```json [settings]
+{
+  "terminal": {
+    "working_directory": "first_project_directory"
+  }
+}
+```
+
+## Environment Variables
+
+Add environment variables to all terminal sessions:
+
+```json [settings]
+{
+  "terminal": {
+    "env": {
+      "EDITOR": "zed --wait",
+      "MY_VAR": "value"
+    }
+  }
+}
+```
+
+> **Tip:** Use `:` to separate multiple values in a single variable: `"PATH": "/custom/path:$PATH"`
+
+### Python Virtual Environment Detection
+
+Zed can automatically activate Python virtual environments when opening a terminal. By default, it searches for `.env`, `env`, `.venv`, and `venv` directories:
+
+```json [settings]
+{
+  "terminal": {
+    "detect_venv": {
+      "on": {
+        "directories": [".venv", "venv"],
+        "activate_script": "default"
+      }
+    }
+  }
+}
+```
+
+The `activate_script` option supports `"default"`, `"csh"`, `"fish"`, and `"nushell"`.
+
+To disable virtual environment detection:
+
+```json [settings]
+{
+  "terminal": {
+    "detect_venv": "off"
+  }
+}
+```
+
+## Fonts and Appearance
+
+The terminal can use different fonts from the editor:
+
+```json [settings]
+{
+  "terminal": {
+    "font_family": "JetBrains Mono",
+    "font_size": 14,
+    "font_features": {
+      "calt": false
+    },
+    "line_height": "comfortable"
+  }
+}
+```
+
+Line height options:
+
+- `"comfortable"` — 1.618 ratio, good for reading (default)
+- `"standard"` — 1.3 ratio, better for TUI applications with box-drawing characters
+- `{ "custom": 1.5 }` — Custom ratio
+
+### Cursor
+
+Configure cursor appearance:
+
+```json [settings]
+{
+  "terminal": {
+    "cursor_shape": "bar",
+    "blinking": "on"
+  }
+}
+```
+
+Cursor shapes: `"block"`, `"bar"`, `"underline"`, `"hollow"`
+
+Blinking options: `"off"`, `"terminal_controlled"` (default), `"on"`
+
+### Minimum Contrast
+
+Zed adjusts terminal colors to maintain readability. The default value of `45` ensures text remains visible. Set to `0` to disable contrast adjustment and use exact theme colors:
+
+```json [settings]
+{
+  "terminal": {
+    "minimum_contrast": 0
+  }
+}
+```
+
+## Scrolling
+
+Navigate terminal history with these keybindings:
+
+| Action           | macOS                          | Linux/Windows    |
+| ---------------- | ------------------------------ | ---------------- |
+| Scroll page up   | `Shift+PageUp` or `Cmd+Up`     | `Shift+PageUp`   |
+| Scroll page down | `Shift+PageDown` or `Cmd+Down` | `Shift+PageDown` |
+| Scroll line up   | `Shift+Up`                     | `Shift+Up`       |
+| Scroll line down | `Shift+Down`                   | `Shift+Down`     |
+| Scroll to top    | `Shift+Home` or `Cmd+Home`     | `Shift+Home`     |
+| Scroll to bottom | `Shift+End` or `Cmd+End`       | `Shift+End`      |
+
+Adjust scroll speed with:
+
+```json [settings]
+{
+  "terminal": {
+    "scroll_multiplier": 3.0
+  }
+}
+```
+
+## Copy and Paste
+
+| Action | macOS   | Linux/Windows  |
+| ------ | ------- | -------------- |
+| Copy   | `Cmd+C` | `Ctrl+Shift+C` |
+| Paste  | `Cmd+V` | `Ctrl+Shift+V` |
+
+### Copy on Select
+
+Automatically copy selected text to the clipboard:
+
+```json [settings]
+{
+  "terminal": {
+    "copy_on_select": true
+  }
+}
+```
+
+### Keep Selection After Copy
+
+By default, text stays selected after copying. To clear the selection:
+
+```json [settings]
+{
+  "terminal": {
+    "keep_selection_on_copy": false
+  }
+}
+```
+
+## Search
+
+Search terminal content with `Cmd+F` (macOS) or `Ctrl+Shift+F` (Linux/Windows). This opens the same search bar used in the editor.
+
+## Vi Mode
+
+Toggle vi-style navigation in the terminal with `Ctrl+Shift+Space`. This allows you to navigate and select text using vi keybindings.
+
+## Clear Terminal
+
+Clear the terminal screen:
+
+- macOS: `Cmd+K`
+- Linux/Windows: `Ctrl+Shift+L`
+
+## Option as Meta (macOS)
+
+For Emacs users or applications that use Meta key combinations, enable Option as Meta:
+
+```json [settings]
+{
+  "terminal": {
+    "option_as_meta": true
+  }
+}
+```
+
+This reinterprets the Option key as Meta, allowing sequences like `Alt+X` to work correctly.
+
+## Alternate Scroll Mode
+
+When enabled, mouse scroll events are converted to arrow key presses in applications like `vim` or `less`:
+
+```json [settings]
+{
+  "terminal": {
+    "alternate_scroll": "on"
+  }
+}
+```
+
+## Path Hyperlinks
+
+Zed detects file paths in terminal output and makes them clickable. `Cmd+Click` (macOS) or `Ctrl+Click` (Linux/Windows) opens the file in Zed, jumping to the line number if one is detected.
+
+Common formats recognized:
+
+- `src/main.rs:42` — Opens at line 42
+- `src/main.rs:42:10` — Opens at line 42, column 10
+- `File "script.py", line 10` — Python tracebacks
+
+## Panel Configuration
+
+### Dock Position
+
+```json [settings]
+{
+  "terminal": {
+    "dock": "bottom"
+  }
+}
+```
+
+Options: `"bottom"` (default), `"left"`, `"right"`
+
+### Default Size
+
+```json [settings]
+{
+  "terminal": {
+    "default_width": 640,
+    "default_height": 320
+  }
+}
+```
+
+### Terminal Button
+
+Hide the terminal button in the status bar:
+
+```json [settings]
+{
+  "terminal": {
+    "button": false
+  }
+}
+```
+
+### Toolbar
+
+Show the terminal title in a breadcrumb toolbar:
+
+```json [settings]
+{
+  "terminal": {
+    "toolbar": {
+      "breadcrumbs": true
+    }
+  }
+}
+```
+
+The title can be set by your shell using the escape sequence `\e]2;Title\007`.
+
+## Integration with Tasks
+
+The terminal integrates with Zed's [task system](./tasks.md). When you run a task, it executes in the terminal. Rerun the last task from a terminal with:
+
+- macOS: `Cmd+Alt+R`
+- Linux/Windows: `Ctrl+Shift+R` or `Alt+T`
+
+## AI Assistance
+
+Get help with terminal commands using inline assist:
+
+- macOS: `Ctrl+Enter`
+- Linux/Windows: `Ctrl+Enter` or `Ctrl+I`
+
+This opens the AI assistant to help explain errors, suggest commands, or troubleshoot issues.
+
+## Sending Text and Keystrokes
+
+For advanced keybinding customization, you can send raw text or keystrokes to the terminal:
+
+```json [keymap]
+{
+  "context": "Terminal",
+  "bindings": {
+    "alt-left": ["terminal::SendText", "\u001bb"],
+    "ctrl-c": ["terminal::SendKeystroke", "ctrl-c"]
+  }
+}
+```
+
+## All Terminal Settings
+
+For the complete list of terminal settings, see the [Terminal section in All Settings](./reference/all-settings.md#terminal).
+
+## What's Next
+
+- [Tasks](./tasks.md) — Run commands and scripts from Zed
+- [REPL](./repl.md) — Interactive code execution
+- [CLI Reference](./reference/cli.md) — Command-line interface for opening files in Zed

docs/src/visual-customization.md

@@ -2,7 +2,7 @@
 
 Various aspects of Zed's visual layout can be configured via either the settings window or the `settings.json` file, which you can access via {#action zed::OpenSettings} ({#kb zed::OpenSettings}) and {#action zed::OpenSettingsFile} ({#kb zed::OpenSettingsFile}) respectively.
 
-See [Configuring Zed](./configuring-zed.md) for additional information and other non-visual settings.
+See [All Settings](./reference/all-settings.md) for additional information and other non-visual settings.
 
 ## Themes
 
@@ -525,7 +525,7 @@ See [Zed AI Documentation](./ai/overview.md) for additional non-visual AI settin
   }
 ```
 
-See [Terminal settings](./configuring-zed.md#terminal) for additional non-visual customization options.
+See [Terminal settings](./reference/all-settings.md#terminal) for additional non-visual customization options.
 
 ### Other Panels