diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index c224f7e0c185533b21b92d2fd823b4a60433f3db..160b2f76546f6c1ab1c72f84dff53bc25d6ad5f2 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -39,6 +39,7 @@
   - [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)
diff --git a/docs/src/appearance.md b/docs/src/appearance.md
index 8fd0f8f288d00e0a088ebbd772500d94b079349e..682980b4948e135b09cba90602911c902a6bfe16 100644
--- a/docs/src/appearance.md
+++ b/docs/src/appearance.md
@@ -64,7 +64,7 @@ Zed uses three font settings for different contexts:
 | ---------------------- | ------------------ |
 | `buffer_font_family`   | Editor text        |
 | `ui_font_family`       | Interface elements |
-| `terminal.font_family` | Terminal           |
+| `terminal.font_family` | [Terminal](./terminal.md)           |
 
 Example configuration:
 
diff --git a/docs/src/environment.md b/docs/src/environment.md
index 41980b2d96f5109776028392625e2e4642fa9022..11af40c91db5af6531d3cec282a6a3f2792e95bb 100644
--- a/docs/src/environment.md
+++ b/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
 
diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md
index d602af1f7968a8d463679b9de0ce83c2d9ad486f..fc31b617837462fee23748f7ead7bb5dd184ec5d 100644
--- a/docs/src/getting-started.md
+++ b/docs/src/getting-started.md
@@ -2,18 +2,77 @@
 
 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](./editing-code.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)
diff --git a/docs/src/running-testing.md b/docs/src/running-testing.md
index 3c23b9b2f3144687047f882b481d71411966eaff..249639a0719fc73ada2491cdb19f47ecb3d37442 100644
--- a/docs/src/running-testing.md
+++ b/docs/src/running-testing.md
@@ -4,6 +4,8 @@ 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.
@@ -12,7 +14,9 @@ This section covers how to run, test, and debug your code without leaving Zed.
 
 ## Quick start
 
-**Run a command**: Press `Cmd+Shift+T` (macOS) or `Ctrl+Shift+T` (Linux/Windows) to open the task picker, then type any shell command.
+**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.
 
diff --git a/docs/src/tasks.md b/docs/src/tasks.md
index a11988d9a030036ccd3e2602a161771f8288b549..095f05169921a5ec61ff3643ff651a7d813d5845 100644
--- a/docs/src/tasks.md
+++ b/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]
 [
diff --git a/docs/src/terminal.md b/docs/src/terminal.md
new file mode 100644
index 0000000000000000000000000000000000000000..4c1e15e6e18e4934261dac5b95ef3757f1059a4a
--- /dev/null
+++ b/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