docs: fine-tune migration guides (#96)

* docs: fine-tune migration guides

Co-Authored-By: Oz <oz-agent@warp.dev>

* Apply suggestion from @rachaelrenk

---------

Co-authored-by: Oz <oz-agent@warp.dev>

Author: rachaelrenk

src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx

@@ -43,32 +43,32 @@ Claude Code's authentication (API key or Anthropic account) is handled by Claude
 
 ## Switching to Agent Mode from Claude Code
 
-If you're ready to replace Claude Code with Warp's built-in agent, the core workflow is:
+If you're ready to replace Claude Code with Warp's built-in Agent, the core workflow is:
 
 1. Open a new tab in Warp.
-2. To switch to switch to [Agent Mode](/agent-platform/local-agents/overview/) from terminal mode, press `⌘+Enter` (or `Ctrl+Shift+Enter`)
+2. From terminal mode, press `⌘+Enter` (macOS) or `Ctrl+Shift+Enter` (Linux/Windows) to switch to [Agent Mode](/agent-platform/local-agents/overview/).
 3. Describe what you want in natural language.
 
-Warp's agent reads your codebase, runs commands, and edits files the same way Claude Code does.
+Warp's Agent reads your codebase, runs commands, and edits files the same way Claude Code does.
 
 ### What transfers: context and rules
 
-A recurring question from Claude Code users: **what files and context does Warp's agent read automatically?** Warp picks up project rules from an `AGENTS.md` (or `WARP.md`) at your repo root — the direct equivalent of Claude Code's `CLAUDE.md`. Run `/init` in Agent Mode to generate one, or rename your existing rules file and you're done — no rewriting needed.
+A recurring question from Claude Code users: **what files and context does Warp's Agent read automatically?** Warp picks up project rules from an `AGENTS.md` (or `WARP.md`) at your repo root — the direct equivalent of Claude Code's `CLAUDE.md`. Run `/init` in Agent Mode to generate one, or rename your existing rules file and you're done — no rewriting needed.
 
-Warp's agent also pulls context from several other explicit sources:
+Warp's Agent also pulls context from several other explicit sources:
 
-* **[Codebase Context](/agent-platform/capabilities/codebase-context/)** - when you open a directory, Warp indexes your Git-tracked files so the agent can search and reference your code without you pasting snippets.
+* **[Codebase Context](/agent-platform/capabilities/codebase-context/)** - when you open a directory, Warp indexes your Git-tracked files so the Agent can search and reference your code without you pasting snippets.
 * **[Rules](/agent-platform/capabilities/rules/)** - global and project-scoped rules. `AGENTS.md` and `WARP.md` are automatically picked up at the project root; additional rules live in Warp Drive.
-* **[Warp Drive](/knowledge-and-collaboration/warp-drive/)** - notebooks, workflows, and environment variables you've saved are available to the agent as context.
-* **[Agent Mode context](/knowledge-and-collaboration/warp-drive/agent-mode-context/)** - pin specific files or notebooks to a conversation so the agent always has them in scope.
-* **[MCP](/agent-platform/capabilities/mcp/)** - any MCP servers you've configured give the agent access to external tools and data.
+* **[Warp Drive](/knowledge-and-collaboration/warp-drive/)** - notebooks, workflows, and environment variables you've saved are available to the Agent as context.
+* **[Agent Mode context](/knowledge-and-collaboration/warp-drive/agent-mode-context/)** - pin specific files or notebooks to a conversation so the Agent always has them in scope.
+* **[MCP](/agent-platform/capabilities/mcp/)** - any MCP servers you've configured give the Agent access to external tools and data.
 
 ### What to reconfigure
 
 * **Bring over your `CLAUDE.md`.** Rename it to `AGENTS.md` (or copy it into a Warp [Rule](/agent-platform/capabilities/rules/) if you want it scoped beyond the repo). Warp applies it automatically to new conversations.
 * **Set up [MCP servers](/agent-platform/capabilities/mcp/)** you relied on in Claude Code.
 * **Pick a model** per conversation using the model selector. See [model choice](/agent-platform/inference/model-choice/). Warp supports Claude, GPT, Gemini, and Auto.
-* **Configure [agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/)** for what the agent can auto-execute.
+* **Configure [agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/)** for what the Agent can auto-execute.
 
 ### Key differences from Claude Code
 
@@ -79,7 +79,7 @@ Warp's agent also pulls context from several other explicit sources:
 
 ## Warp-native equivalents
 
-Claude Code concepts and their closest Warp analog:
+Use this table to find the closest Warp equivalent for Claude Code concepts:
 
 | From Claude Code | In Warp |
 | --- | --- |

src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-cursor.mdx

@@ -5,42 +5,42 @@ description: >-
   Cursor, or run Warp alongside Cursor as your agent terminal.
 ---
 
-Warp gives Cursor users two clean migration paths: keep Cursor as your editor and use Warp for terminal and agent work, or move fully to Warp's built-in code editor and Agent Mode. This page walks through both options.
+Warp gives Cursor users two migration paths: keep Cursor as your editor and use Warp for terminal and Agent work, or move fully to Warp's built-in code editor and Agent Mode. This page walks through both options.
 
-## What transfers automatically
+## What Warp can help transfer
 
-Warp doesn't ship a Cursor importer. Cursor is built on the VS Code codebase, so its terminal settings live in `settings.json` under keys like `terminal.integrated.fontFamily` and `terminal.integrated.defaultProfile.*`. Open your user settings with **Command Palette** > **Preferences: Open User Settings (JSON)** to reference them while you reconfigure Warp.
+Warp doesn't have a one-click Cursor importer. Cursor is built on the VS Code codebase, so its terminal settings live in `settings.json` under keys like `terminal.integrated.fontFamily` and `terminal.integrated.defaultProfile.*`. Because that file is readable, Warp's Agent can translate matching terminal values into Warp's `settings.toml`. In Cursor, open the Command Palette and select **Preferences: Open User Settings (JSON)** to reference your settings while you reconfigure Warp.
 
-## Use Warp's agent to migrate your settings (recommended)
+## Use Warp's Agent to migrate your settings (recommended)
 
-The fastest way to bring over your Cursor terminal setup is to ask Warp's agent to translate your `settings.json` directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the agent read your existing config and write equivalent values into Warp's settings.
+The fastest way to bring over your Cursor terminal setup is to ask Warp's Agent to translate your `settings.json` directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the Agent read your existing config and write equivalent values into Warp's settings.
 
-1. In Warp, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows).
-2. Paste a prompt like:
+1. In the Warp app, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows).
+2. Copy and paste this prompt into the Agent Mode input, then press `Enter`.
 
    > Read my Cursor `settings.json` (`~/Library/Application Support/Cursor/User/settings.json` on macOS) and port the equivalent terminal settings (font, cursor style, default profile) into my Warp `settings.toml` using the `modify-settings` skill. Show me a diff before applying.
 
-3. Review the proposed diff and approve. Warp hot-reloads `settings.toml`, so changes take effect immediately.
+3. Review the proposed diff, then approve the changes. Warp hot-reloads `settings.toml`, so changes take effect immediately.
 
 If you'd rather configure each setting manually through the Settings UI, the steps below cover the most common cases.
 
 ## What to reconfigure manually
 
 ### Terminal settings
 
-Terminal settings in Cursor follow the same schema as VS Code. The migration steps are identical to the VS Code terminal migration - see [Migrate to Warp from VS Code terminal](/getting-started/migrate-to-warp/migrate-to-warp-from-vs-code-terminal/) for step-by-step guidance on shell, font, theme, and keybinding setup.
+Terminal settings in Cursor follow the same schema as VS Code. The migration steps are identical to the VS Code terminal migration. See [Migrate to Warp from VS Code terminal](/getting-started/migrate-to-warp/migrate-to-warp-from-vs-code-terminal/) for step-by-step guidance on shell, font, theme, and keybinding setup.
 
 ### Agent and AI settings
 
-Cursor's Composer and Agent features don't have a one-to-one migration path - they map to different Warp concepts.
+Cursor's Composer and Agent features don't have a one-to-one migration path; they map to different Warp concepts.
 
-* **Composer / Agent** in Cursor maps to Warp's [Agent Mode](/agent-platform/local-agents/overview/). Start an agent conversation in any tab.
-* **Rules files** (`.cursorrules`) - Warp uses [Rules](/agent-platform/capabilities/rules/) stored in Warp Drive or committed to your repo as `AGENTS.md` (or `WARP.md`). Run `/init` in Agent Mode to generate an `AGENTS.md`, or copy your `.cursorrules` content directly.
+* **Composer / Agent** - In Cursor, these features map to Warp's [Agent Mode](/agent-platform/local-agents/overview/). Start an Agent conversation in any tab.
+* **Rules files** - Warp uses [Rules](/agent-platform/capabilities/rules/) stored in Warp Drive or committed to your repo as `AGENTS.md` (or `WARP.md`). Run `/init` in Agent Mode to generate an `AGENTS.md`, or copy your `.cursorrules` content directly.
 * **MCP servers** - Warp supports MCP natively. See [MCP](/agent-platform/capabilities/mcp/) for configuration.
 
 ### Model choice
 
-Cursor lets you pick a model per conversation. Warp does the same - use the model selector in any agent conversation. See [model choice](/agent-platform/inference/model-choice/).
+Cursor lets you pick a model per conversation. Warp does the same; use the model selector in any Agent conversation. See [model choice](/agent-platform/inference/model-choice/).
 
 ### Keybindings
 
@@ -63,11 +63,11 @@ Warp's built-in [code editor](/code/code-editor/) supports Language Server Proto
 
 ## Warp-native equivalents
 
-Cursor features and their Warp counterparts:
+Use this table to find Warp equivalents for Cursor features you might look for after switching:
 
 | From Cursor | In Warp |
 | --- | --- |
-| Composer / Agent panel | [Agent Mode](/agent-platform/local-agents/overview/) in any tab (toggle with `⌘+I`) |
+| Composer / Agent panel | [Agent Mode](/agent-platform/local-agents/overview/) in any tab (toggle with `⌘+I` on macOS or `Ctrl+I` on Linux/Windows) |
 | Agent tabs | Multiple [agents in parallel](/agent-platform/local-agents/overview/) across tabs |
 | `.cursorrules` | `AGENTS.md` / `WARP.md` at the project root, picked up as a [Rule](/agent-platform/capabilities/rules/) |
 | MCP servers | [MCP](/agent-platform/capabilities/mcp/) |

src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-ghostty.mdx

@@ -6,61 +6,61 @@ description: >-
   features.
 ---
 
-Warp gives Ghostty users a fast path to bring over themes, fonts, and keybindings — plus native equivalents for the Ghostty features you rely on, from the quick terminal to native tabs and splits.
+Warp gives Ghostty users a fast path to bring over themes, fonts, and keybindings, plus native equivalents for the Ghostty features you rely on, from the quick terminal to native tabs and splits.
 
-## What transfers automatically
+## What Warp can help transfer
 
-Warp doesn't ship a Ghostty importer, but it can do most of the work for you agentically. Ghostty stores its configuration in a plain-text key-value file at `~/.config/ghostty/config`.
+Warp doesn't have a one-click Ghostty importer. Because Ghostty stores its configuration in a plain-text key-value file at `~/.config/ghostty/config`, Warp's Agent can read that file and translate matching values into Warp's `settings.toml`.
 
-## Use Warp's agent to migrate your settings (recommended)
+## Use Warp's Agent to migrate your settings (recommended)
 
-The fastest way to bring over your Ghostty setup is to ask Warp's agent to translate your config directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the agent read your existing config and write equivalent values into Warp's settings, including translating your Ghostty theme into a Warp [custom theme](/terminal/appearance/custom-themes/).
+The fastest way to bring over your Ghostty setup is to ask Warp's Agent to translate your config directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the Agent read your existing config and write equivalent values into Warp's settings, including translating your Ghostty theme into a Warp [custom theme](/terminal/appearance/custom-themes/).
 
-1. In Warp, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows).
-2. Paste a prompt like:
+1. In the Warp app, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows).
+2. Paste this prompt into Agent Mode, then press `Enter`.
 
    > Read my Ghostty config at `~/.config/ghostty/config` and any referenced theme files in `~/.config/ghostty/themes/`. Port the equivalent settings (theme, font, keybindings, shell) into my Warp `settings.toml` using the `modify-settings` skill, and create a matching custom theme. Show me a diff before applying.
 
-3. Review the proposed diff and approve. Warp hot-reloads `settings.toml`, so changes take effect immediately.
+3. Review the proposed diff, then approve the changes. Warp hot-reloads `settings.toml`, so changes take effect immediately.
 
 If you'd rather configure each setting manually through the Settings UI, the steps below cover the most common cases.
 
 ## What to reconfigure manually
 
 ### Theme and colors
 
-1. Open **Settings** > **Appearance** > **Themes** in Warp.
-2. Pick a built-in theme that matches your Ghostty setup, or [create a custom theme](/terminal/appearance/custom-themes/) by translating your Ghostty colors into a YAML theme file.
-3. Ghostty's theme files live in `~/.config/ghostty/themes/`. Open the file named in your Ghostty `theme` setting to copy the foreground, background, and 16 ANSI color values.
+1. In the Warp app, open **Settings** > **Appearance** > **Themes**.
+2. Choose a built-in theme that matches your Ghostty setup, or [create a custom theme](/terminal/appearance/custom-themes/) by translating your Ghostty colors into a YAML theme file.
+3. If your Ghostty config references a custom theme, open the matching file in `~/.config/ghostty/themes/` and copy the foreground, background, and 16 ANSI color values.
 
 ### Font and text
 
-1. In **Settings** > **Appearance** > **Text, fonts, & cursor**, match your Ghostty `font-family` and `font-size` values.
-2. If you use font ligatures, ensure **Ligatures** is enabled.
+1. In the Warp app, open **Settings** > **Appearance** > **Text, fonts, & cursor** and match your Ghostty `font-family` and `font-size` values.
+2. If you use font ligatures, toggle **Ligatures** on.
 
 ### Keybindings
 
-Warp's [default keyboard shortcuts](/getting-started/keyboard-shortcuts/) cover most Ghostty bindings. For custom bindings from your Ghostty `keybind` lines, open **Settings** > **Keyboard shortcuts** and add them manually.
+Warp's [default keyboard shortcuts](/getting-started/keyboard-shortcuts/) cover most Ghostty bindings. For custom bindings from your Ghostty `keybind` lines, open **Settings** > **Keyboard shortcuts** in the Warp app and add them manually.
 
 ### Shell and prompt
 
-Warp detects your login shell automatically. To override it, go to **Settings** > **Features** > **Session** and pick a shell from **Startup shell for new sessions**.
+Warp detects your login shell automatically. To override it, open **Settings** > **Features** > **Session** in the Warp app and choose a shell from **Startup shell for new sessions**.
 
 For prompts, choose between Warp's [native prompt](/terminal/appearance/prompt/#warp-prompt) (drag-and-drop context chips) or the [shell prompt (PS1)](/terminal/appearance/prompt/#custom-prompt) if you want to keep your existing prompt configuration.
 
 ### Quick terminal (Quake mode)
 
-Configure Warp's equivalent via **Settings** > **Features** > **Window** > **Global hotkey**. See [global hotkey](/terminal/windows/global-hotkey/) for the full configuration.
+In the Warp app, configure Warp's equivalent from **Settings** > **Features** > **Window** > **Global hotkey**. See [global hotkey](/terminal/windows/global-hotkey/) for the full configuration.
 
 ## Warp-native equivalents
 
-Features Ghostty users commonly miss, and where they live in Warp:
+Use this table to find the closest Warp equivalent for Ghostty features you might look for after switching:
 
 | From Ghostty | In Warp |
 | --- | --- |
 | Quick terminal / dropdown window | [Global hotkey](/terminal/windows/global-hotkey/) |
 | Native tabs and splits | [Tabs](/terminal/windows/tabs/), [vertical tabs](/terminal/windows/vertical-tabs/), [split panes](/terminal/windows/split-panes/) |
-| Command palette | [Command Palette](/terminal/command-palette/) (`⌘+P` on macOS, `Ctrl+Shift+P` on Linux) |
+| Command palette | [Command Palette](/terminal/command-palette/) (`⌘+P` on macOS, `Ctrl+Shift+P` on Linux/Windows) |
 | GPU-accelerated rendering | GPU-rendered natively on all supported platforms |
 | Kitty graphics protocol | Image rendering for most common workflows (see [more features](/terminal/more-features/)) |
 | Shaders and custom visual effects | Not supported; closest: [size, opacity, and blurring](/terminal/appearance/size-opacity-blurring/) + [pane dimming](/terminal/appearance/pane-dimming/) |

src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx

@@ -27,21 +27,21 @@ To run the importer:
 3. Select **iTerm2 Profile: Default**. Warp only imports the profile marked as your Default Bookmark in iTerm2.
 4. Choose which settings to keep or skip on the preview screen.
 
-<figure>
+<figure style={{ maxWidth: "563px" }}>
 ![Select a settings profile to import](../../../../assets/terminal/migrate-to-warp.png)
 <figcaption>Select a settings profile to import.</figcaption>
 </figure>
 
-## Use Warp's agent for follow-up settings
+## Use Warp's Agent for follow-up settings
 
-If the importer doesn't pick up something you care about — a non-default profile, an unusual keybinding, a specific setting — ask Warp's agent to translate it directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the agent read your iTerm2 plist and write equivalent values into Warp's settings.
+If the importer doesn't pick up something you care about, such as a non-default profile, an unusual keybinding, or a specific setting, ask Warp's Agent to translate it directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the Agent read your iTerm2 plist and write equivalent values into Warp's settings.
 
-1. In Warp, switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I`.
-2. Paste a prompt like:
+1. In the Warp app, switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I`.
+2. Paste this prompt into Agent Mode, then press `Enter`.
 
    > Read my iTerm2 preferences with `defaults read com.googlecode.iterm2` and port any settings that the importer didn't cover (extra profiles, custom keybindings) into my Warp `settings.toml` using the `modify-settings` skill. Show me a diff before applying.
 
-3. Review the proposed diff and approve. Warp hot-reloads `settings.toml`.
+3. Review the proposed diff, then approve the changes. Warp hot-reloads `settings.toml`.
 
 ## What to reconfigure manually
 
@@ -61,7 +61,7 @@ After the import, choose which [prompt](/terminal/appearance/prompt/) to use:
 
 ## Warp-native equivalents
 
-Features switchers commonly look for after leaving iTerm2, and where they live in Warp:
+Use this table to find Warp equivalents for iTerm2 features you might look for after switching:
 
 | From iTerm2 | In Warp |
 | --- | --- |