docs: restore 175 image figcaptions from GitBook migration (#37)

* docs: restore image figcaptions from GitBook migration

Add <figure>+<figcaption> wrappers to 175 images across 68 MDX files,
restoring the visible captions that were lost during the GitBook →
Astro Starlight migration. Captions extracted from the GitBook source
and matched by image filename.

Also adds:
- CSS styling for figure and figcaption elements (centered, sm text,
  gray-3 color) in custom.css
- Migration scripts (migrate-figcaptions.py for analysis,
  apply-figcaptions.py for automated application)

Empty figcaptions (145 instances) are intentionally skipped — they
had no visible text in GitBook either.

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

* chore: remove one-time figcaption migration scripts

These were used to generate the content changes in this PR and
don't need to live in the repo.

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

* docs: add image caption guidelines to style guide and CSS

Add an 'Image caption guidelines' section to AGENTS.md with rules
for writing good figcaptions: orient don't instruct, keep short,
no marketing language, don't repeat prose, don't list everything.
Includes positive and negative examples.

Also adds a brief editorial note in custom.css next to the
figcaption styles pointing to the AGENTS.md guidelines.

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

* docs: rewrite figcaptions to follow image caption guidelines

Apply the caption guidelines from AGENTS.md to all 174 figcaptions:
- Remove procedural instructions from captions (belongs in body text)
- Remove marketing language ('easily,' 'at a glance,' etc.)
- Shorten exhaustive lists to concise subject descriptions
- Trim verbose captions to ~10 words
- Add missing trailing periods for consistency
- Fix 'Oz Web App' casing to 'Oz web app' per terminology

140 captions rewritten across 58 files.

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

* docs: rewrite fragment captions as complete sentences

Rewrite 28 cryptic fragment captions (e.g. 'Derived from rules.',
'Alt-screen padding setting.') as complete sentences that orient
the reader without requiring them to look at the image.

Also adds 'Write complete sentences' as an explicit rule in the
AGENTS.md image caption guidelines.

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

---------

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

Author: 2 people

AGENTS.md

@@ -177,6 +177,26 @@ Use formatting consistently to distinguish different types of content:
 - File naming: lowercase, hyphens, descriptive (`agent-mode-code-diff.png`, not `Screenshot 2026-03-15.png`)
 - Store PNGs in `src/assets/<section>/` (Astro optimizes them) and GIFs in `public/assets/<section>/` (to bypass optimization). See the "Assets" section below for the full convention.
 
+#### Image caption guidelines
+Captions orient the reader — they identify what the image shows so the reader knows where to look. They are not a place for instructions, marketing language, or exhaustive descriptions.
+
+**Rules:**
+- **Orient, don't instruct** — describe what is shown, not what to do. Procedural steps belong in the body text.
+- **Write complete sentences** — every caption should read as a standalone sentence, not a fragment or label. A reader should understand what the image shows without looking at it.
+- **Keep it short** — aim for 10 words or fewer. Never exceed ~20 words.
+- **No marketing language** — avoid "easily," "quickly," "powerful," "at a glance," or similar.
+- **Don't repeat the prose** — if the paragraph above already describes the image, the caption should add context, not echo it.
+- **Don't list everything visible** — name the subject, not every detail in the screenshot.
+- **Sentence case, end with a period** — consistent with all other text in the docs.
+
+**Examples:**
+- ✅ `<figcaption>The Environments page in the Oz web app.</figcaption>`
+- ✅ `<figcaption>Agent Profile settings.</figcaption>`
+- ✅ `<figcaption>Codebase indexing settings.</figcaption>`
+- ❌ `<figcaption>Codebase indexing settings in Warp. Easily track sync status and manage which folders are indexed for AI-powered context and suggestions.</figcaption>` (marketing language, too long)
+- ❌ `<figcaption>Click the toast to jump to the agent's session.</figcaption>` (procedural — belongs in body text)
+- ❌ `<figcaption>Universal Input's contextual input chips, from left to right: conversation management, node version, active directory, Git and code diffs, and 2 attached images.</figcaption>` (exhaustive list)
+
 ### Links and cross-references
 - Use descriptive link text that explains what users will find
   - ✅ "Learn more about [Codebase Context](...)" / "See [configuring environments](...)"

src/content/docs/agent-platform/capabilities/agent-notifications.mdx

@@ -25,13 +25,19 @@ Floating toast notifications appear in the corner of the Warp window when an age
 
 Up to two toasts are visible at a time. If additional notifications arrive, the oldest toast is replaced.
 
+<figure>
 ![A Warp toast notification in the upper-right corner showing an agent task completed, with an Open conversation action and a keyboard shortcut chip](../../../../assets/agent-platform/toast-notification.png)
+<figcaption>Agent task completion notification.</figcaption>
+</figure>
 
 ### Notification mailbox
 
 The notification mailbox is a sidebar panel that collects all agent notifications in one place. Open it from the bell icon in the top-right corner of Warp.
 
+<figure>
 ![The Warp notification mailbox open in the upper-right of the window with All tabs and Unread filter tabs, a Mark all as read action, and a notification entry](../../../../assets/agent-platform/notification-mailbox.png)
+<figcaption>Agent notification mailbox.</figcaption>
+</figure>
 
 The mailbox includes:
 
@@ -83,7 +89,10 @@ For **third-party CLI agents**, each agent requires a one-time setup. The proces
 * **Codex** - add `notification_condition = "always"` under `[tui]` in `~/.codex/config.toml`, then restart Codex. See [Codex setup](/agent-platform/cli-agents/codex/#setting-up-notifications).
 * **OpenCode** - add `"@warp-dot-dev/opencode-warp"` to the `plugin` array in your OpenCode config. See [OpenCode setup](/agent-platform/cli-agents/opencode/#setting-up-notifications).
 
+<figure>
 ![The Enable Claude Code notifications chip in the agent utility bar with a tooltip reading Install the Warp plugin to enable rich agent notifications within Warp](../../../../assets/agent-platform/enable-cli-agent-notifications.png)
+<figcaption>Notification plugin install chip.</figcaption>
+</figure>
 
 If auto-install doesn't work or you're running an agent over SSH, Warp displays an installation-instructions chip in the terminal with setup steps you can follow directly.
 

src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx

@@ -13,15 +13,21 @@ Agent Profiles let you configure how your Agent behaves in different situations.
 * **Default profile**: Every user starts with a default profile, you can edit it at any time, and new profiles will copy its settings as a starting point.
 * **Other profiles**: Set up different profiles for different workflows (e.g., "Safe & cautious", "YOLO mode", etc.). Manage them in the Profiles settings menu.
 
+<figure>
 ![Agent Profiles in Settings: define how your Agent operates.](../../../../assets/agent-platform/agent-profiles.png)
+<figcaption>Agent Profile settings.</figcaption>
+</figure>
 
 **In each Agent Profile, you can configure:**
 
 * The name of the profile
 * **Base model**: The core engine for your Agent. It handles most interactions and invokes other models when needed (e.g. for code generation). This model is also used for [Planning](/agent-platform/capabilities/planning/) by default, though you can configure a separate planning model.
 * Agent autonomy and permissions
 
+<figure>
 ![Agent Profiles in Settings: editing a Profile.](../../../../assets/agent-platform/agent-profiles-settings.png)
+<figcaption>Editing an Agent Profile.</figcaption>
+</figure>
 
 ## Agent Permissions
 
@@ -63,7 +69,10 @@ The Agent lets you define an allowlist of commands that run automatically withou
 
 You can add your own regular expressions to this list in **Settings** > **Agents** > **Profiles** > **Command allowlist**. Commands in the allowlist will always auto-execute, even if they are not read-only operations.
 
+<figure>
 ![Command allowlist and denylists as part of an Agent Profile.](../../../../assets/agent-platform/agent-profiles-allow-and-denylists.png)
+<figcaption>Command allowlist and denylists as part of an Agent Profile.</figcaption>
+</figure>
 
 ### Command denylist
 
@@ -86,7 +95,10 @@ In this settings menu, you can configure which MCP servers the Agent is allowed
 * Use the MCP denylist to require approval before calling certain servers, even if they’re also in the allowlist.
 * Or set the Agent to “decide” — it will act autonomously when confident, and ask for confirmation when uncertain.
 
+<figure>
 ![Customize how the Agent interacts with MCP servers by choosing between “Agent decides,” allowlist, or denylist settings.](../../../../assets/agent-platform/MCP_servers_agent_permissions.png)
+<figcaption>MCP server interaction settings in an Agent Profile.</figcaption>
+</figure>
 
 :::note
 To learn how to build and configure your own MCP server, check out the [MCP feature docs](/agent-platform/capabilities/mcp/).
@@ -108,7 +120,10 @@ During an Agent interaction, you can give the Agent full autonomy for the curren
   </TabItem>
 </Tabs>
 
+<figure>
 ![A button overlay in the lower-right corner lets you enable auto-approve or end the Agent interaction.](../../../../assets/agent-platform/run-until-completion.png)
+<figcaption>Auto-approve and take-over controls.</figcaption>
+</figure>
 
 :::note
 _Run until completion_ ignores the denylist entirely. It's the purest form of “YOLO” mode and essentially a fully "autonomous mode" where the Agent proceeds without asking for confirmation.

src/content/docs/agent-platform/capabilities/codebase-context.mdx

@@ -47,7 +47,10 @@ Feature requests:
 * WSL: [GitHub #6744](https://github.com/warpdotdev/Warp/issues/6744)
 :::
 
+<figure>
 ![Codebase indexing settings in Warp. Easily track sync status and manage which folders are indexed for AI-powered context and suggestions.](../../../../assets/agent-platform/codebase-context-main.png)
+<figcaption>Codebase indexing settings.</figcaption>
+</figure>
 
 **Codebase indexing intervals and triggers:**
 
@@ -79,7 +82,10 @@ When viewing indexed codebases in Warp under **Settings** > **Code** > **Indexin
 * **Failed** – Indexing failed. Common reasons include unreadable `.git` directories or corrupted repositories. Try re-cloning the repo and syncing again.
 * **Codebase too large** – The number of files in the codebase exceeds your current plan’s limit. You can either reduce the number of files being indexed using `.warpindexingignore`, or [contact sales](https://warp.dev/contact-sales) for support with larger codebases.
 
+<figure>
 ![View and manage the indexing status of your codebases in Warp. Easily see which projects are synced, in progress, or require attention.](../../../../assets/agent-platform/codebase-context-statuses.png)
+<figcaption>Codebase indexing status overview.</figcaption>
+</figure>
 
 ### When does codebase syncing happen?
 

src/content/docs/agent-platform/capabilities/full-terminal-use.mdx

@@ -33,17 +33,26 @@ You can either ask the agent to run an interactive command, or start one manuall
   * Example:
     * If you’ve already launched an interactive tool (for example `psql` or `npm run dev`), you can bring the agent into the running session using the "Use Agent" button in the terminal footer or via `CMD + I` .
 
+    <figure>
     ![Option to tag the agent into a running command.](../../../../assets/agent-platform/full-terminal-use-tag-hint.png)
+    <figcaption>Option to tag the agent into a running command.</figcaption>
+    </figure>
     *   Once the agent is tagged in, you can follow up with natural-language requests such as:
 
         “Watch this process and help debug the error on the /session endpoint.”
     * Warp then attaches the agent to the active PTY so it can see the current terminal buffer and propose actions inside the session.
 
 <VideoEmbed url="https://www.loom.com/share/bcedc521071a4b6a9bbcf74b5156f903" title="Tagging in the agent." />
 
+<figure>
 ![Running a build command.](../../../../assets/agent-platform/full-terminal-use-build.png)
+<figcaption>Running a build command.</figcaption>
+</figure>
 
+<figure>
 ![Tagging in the Agent to monitor the dev server.](../../../../assets/agent-platform/full-terminal-use-dev-monitor.png)
+<figcaption>Tagging in the Agent to monitor the dev server.</figcaption>
+</figure>
 
 Warp attaches the agent to the running command so it can see and control the terminal buffer.
 
@@ -68,14 +77,20 @@ You can swap control at any time.
 * Use the Takeover control to stop the agent from typing or performing any actions.
 * The shell stays open, and you can type directly into the same session.
 
+<figure>
 ![Option to take over from agent in the footer.](../../../../assets/agent-platform/full-terminal-use-takeover.png)
+<figcaption>Option to take over from agent in the footer.</figcaption>
+</figure>
 
 **Hand back control**
 
 * When you’re ready for the agent to continue, click the control again.
 * The agent resumes where you left off, with full access to the current terminal state.
 
+<figure>
 ![Option to hand-off to the agent in the conversation footer.](../../../../assets/agent-platform/full-terminal-use-handoff.png)
+<figcaption>Option to hand-off to the agent in the conversation footer.</figcaption>
+</figure>
 
 This makes it easy to:
 
@@ -140,7 +155,10 @@ Each time the agent wants to take an action inside an interactive shell, you’l
 * Refine the request with `CTRL + C`, which clears the proposed action and lets you follow up with a different query.
 * Take over manually with `CMD + I`, which stops the agent from issuing any further PTY writes until you hand control back.
 
+<figure>
 ![Allow, Refine, or Take over an agent response.](../../../../assets/agent-platform/allow-refine-takeover.png)
+<figcaption>Allow, Refine, or Take over an agent response.</figcaption>
+</figure>
 
 ![Ability to accept or auto-approve future interactions.](../../../../assets/agent-platform/full-terminal-use-options-2.png)
 

src/content/docs/agent-platform/capabilities/mcp.mdx

@@ -26,7 +26,10 @@ You can navigate to the MCP servers page in any of the following ways:
 
 This will show a list of all configured MCP servers, including which are currently running. If you close Warp with an MCP server running, it will run again on next start of Warp. MCP servers that are stopped will remain so on next launch of Warp.
 
+<figure>
 ![MCP servers page](../../../../assets/agent-platform/mcp-servers-list.png)
+<figcaption>MCP servers page.</figcaption>
+</figure>
 
 ### Adding an MCP Server
 
@@ -38,7 +41,10 @@ MCP server types you can add:
   <TabItem label="CLI Server (Command)">
     Provide a startup command. Warp will launch this command when starting up and shut it down on exit.
 
+    <figure>
     ![Adding a CLI MCP Server (Command)](../../../../assets/agent-platform/mcp-servers-add-cli.png)
+    <figcaption>Adding a CLI MCP Server (Command).</figcaption>
+    </figure>
 
     :::note
     Always set `working_directory` explicitly when your MCP server command or args include relative paths. This ensures consistent and predictable behavior across machines and sessions.
@@ -56,7 +62,10 @@ MCP server types you can add:
   <TabItem label="Streamable HTTP or SSE Server (URL)">
     Provide a URL where Warp can reach an already-running MCP server that supports Server-Sent Events.
 
+    <figure>
     ![Adding an SSE MCP Server (URL)](../../../../assets/agent-platform/mcp-servers-add-sse.png)
+    <figcaption>Adding an SSE MCP Server (URL).</figcaption>
+    </figure>
 
     **Streamable HTTP or SSE Server (URL) MCP Configuration Properties**
 
@@ -161,7 +170,10 @@ You can rename and edit a server's name, as well as delete the server. If you ar
 
 MCP servers can be shared with your teammates by clicking the share icon. When sharing, sensitive values in the `env` configuration will be automatically scrubbed and replaced with variables.
 
+<figure>
 ![Sharing a MCP Server](../../../../assets/agent-platform/mcp-servers-share.png)
+<figcaption>Sharing a MCP Server.</figcaption>
+</figure>
 
 Your teammates can find shared MCP servers under the `Shared` section of their MCP settings. When your teammates install your server configuration, they will be prompted to enter any scrubbed `env` values.
 

src/content/docs/agent-platform/capabilities/model-choice.mdx

@@ -91,7 +91,10 @@ Warp also supports leading open source models hosted via Fireworks AI, so you ca
 
 You can use the model picker in your prompt input to quickly switch between models. The currently active model appears directly in the input editor.
 
+<figure>
 ![Model selector dropdown showing available models with Intelligence, Speed, and Cost benchmarks](../../../../assets/agent-platform/model-selector-dropdown.png)
+<figcaption>Model selector in Warp's input.</figcaption>
+</figure>
 
 To change models, click the displayed model name (for example, _Claude Sonnet 4.5_) to open a dropdown with all supported options. Your selection will automatically persist for future prompts.
 

src/content/docs/agent-platform/capabilities/planning.mdx

@@ -18,53 +18,80 @@ Warp has native planning functionality that helps you break down complex enginee
 
 You can generate a plan using the `/plan` [slash command](/agent-platform/capabilities/slash-commands/) or by asking the agent in natural language.
 
+<figure>
 ![Prompting the agent to create a plan using the slash command.](../../../../assets/agent-platform/plan-slash-command.png)
+<figcaption>Creating a plan with the /plan command.</figcaption>
+</figure>
 
 The agent then creates a structured plan inside Warp’s native rich text editor, which is designed for long, multi-step workflows. The editor includes clean formatting, inline code blocks, and clickable file paths so you can open referenced files immediately in Warp (see below) or in your external editor.
 
 ### Reviewing and editing
 
 Once a plan is generated, you can review it, reorganize steps, or refine details. You can edit the document manually or ask the agent to revise sections for you.
 
+<figure>
 ![Plan editor in Warp.](../../../../assets/agent-platform/planning-main-view.png)
+<figcaption>Plan editor in Warp.</figcaption>
+</figure>
 
 Any update made by the agent **creates a new version**. Version history lets you compare past iterations and restore an older version if you want to revert your approach, preserving a clear decision trail as the plan evolves.
 
+<figure>
 ![Access previous versions of your plan.](../../../../assets/agent-platform/agent-plans-versioning.png)
+<figcaption>Access previous versions of your plan.</figcaption>
+</figure>
 
 ### Executing a plan
 
 When you’re ready to start implementing, prompt the agent to run the plan. You can ask it to execute the full set of steps or only a specific section, such as “Implement phase 1 of the plan.”
 
+<figure>
 ![Manually referencing the plan using @ to kickoff the plan.](../../../../assets/agent-platform/manually-trigger-plan.png)
+<figcaption>Referencing a plan using @.</figcaption>
+</figure>
 
 The agent applies changes incrementally and updates files as it proceeds. This makes it easy to validate early steps before moving forward, adjust the plan mid-run, or try alternative paths without committing to the full workflow.
 
 If you revise the plan while the agent is running, you can notify it directly; the agent will adjust its execution based on your updates.
 
+<figure>
 ![Option to pass new plan to agent if plan changes during runtime.](../../../../assets/agent-platform/update-agent-mid-plan.png)
+<figcaption>Prompt to update the agent's plan during execution.</figcaption>
+</figure>
 
 ### Monitoring progress
 
 While the agent is running, you can reopen the plan at any time by selecting **View plan** in the input. You can also follow each change in real time through the [Code Review](/code/code-review/) panel and add comments or guidance using [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/).
 
+<figure>
 ![Monitoring progress with the task list and plan view.](../../../../assets/agent-platform/agent-plans-tasks.png)
+<figcaption>Monitoring progress with the task list and plan view.</figcaption>
+</figure>
 
 This gives you clear oversight, helps confirm expected behavior, and lets you intervene quickly if something needs correction.
 
 ### Saving and sharing
 
 Warp automatically saves all plans in the _Plans_ folder in [Warp Drive](/knowledge-and-collaboration/warp-drive/). You'll see a confirmation when your plan is synced.
 
+<figure>
 ![Plans are automatically synced to Warp Drive.](../../../../assets/agent-platform/agent-plans-synced.png)
+<figcaption>Plans are automatically synced to Warp Drive.</figcaption>
+</figure>
 
 You can export any plan as Markdown, check it into your repository, or share a link—useful for GitHub PRs, design reviews, or async collaboration.
 
+<figure>
 ![Different ways to share a plan.](../../../../assets/agent-platform/export-notebooks.png)
+<figcaption>Different ways to share a plan.</figcaption>
+</figure>
 
 Because plans persist in Warp Drive, you can return to them later, reuse them for new work, or treat them as documentation for ongoing projects. This is also naturally passed to the agent as context.
 
+<figure>
 ![Plans are accessible directly from the Warp Drive side panel.](../../../../assets/agent-platform/plans-in-warp-drive-side-panel.png)
+<figcaption>Plans are accessible directly from the Warp Drive side panel.</figcaption>
+</figure>
 
 You can configure whether your plans will be automatically added and synced to Warp Drive in your [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) under **Settings** > **Agents** > **Profiles**.