From b94e8e0c98f8eaa5024643b470b3a0f5ef8ef916 Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Thu, 7 May 2026 12:39:47 -1000
Subject: [PATCH 1/5] docs: restore image figcaptions from GitBook migration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 scripts/apply-figcaptions.py                  | 141 ++++++++++++++++++
 scripts/migrate-figcaptions.py                | 131 ++++++++++++++++
 .../capabilities/agent-notifications.mdx      |   9 ++
 .../agent-profiles-permissions.mdx            |  15 ++
 .../capabilities/codebase-context.mdx         |   6 +
 .../capabilities/full-terminal-use.mdx        |  18 +++
 .../docs/agent-platform/capabilities/mcp.mdx  |  15 ++
 .../capabilities/model-choice.mdx             |   3 +
 .../agent-platform/capabilities/planning.mdx  |  27 ++++
 .../agent-platform/capabilities/rules.mdx     |   9 ++
 .../capabilities/slash-commands.mdx           |  12 ++
 .../capabilities/task-lists.mdx               |   9 ++
 .../agent-platform/cli-agents/overview.mdx    |   3 +
 .../cli-agents/remote-control.mdx             |   3 +
 .../agent-platform/cli-agents/rich-input.mdx  |   9 ++
 .../cloud-agents/environments.mdx             |   3 +
 .../cloud-agents/integrations/slack.mdx       |   3 +
 .../cloud-agents/managing-cloud-agents.mdx    |   3 +
 .../cloud-agents/oz-web-app.mdx               |  18 +++
 .../team-access-billing-and-identity.mdx      |   6 +
 .../agent-context/blocks-as-context.mdx       |   3 +
 .../agent-context/images-as-context.mdx       |   6 +
 .../agent-context/selection-as-context.mdx    |   3 +
 .../agent-context/urls-as-context.mdx         |   3 +
 .../agent-context/using-to-add-context.mdx    |   9 ++
 .../local-agents/code-diffs.mdx               |   6 +
 .../agent-platform/local-agents/generate.mdx  |   9 ++
 .../interacting-with-agents/index.mdx         |  12 ++
 .../terminal-and-agent-modes.mdx              |   6 +
 .../interacting-with-agents/voice.mdx         |   6 +
 .../local-agents/interactive-code-review.mdx  |   3 +
 .../local-agents/session-sharing.mdx          |   6 +
 .../docs/code/code-editor/file-tree.mdx       |   3 +
 src/content/docs/code/code-review.mdx         |   6 +
 src/content/docs/code/overview.mdx            |   3 +
 .../team-management/admin-panel.mdx           |   3 +
 .../getting-started/keyboard-shortcuts.mdx    |   3 +
 .../migrate-to-warp-from-iterm2.mdx           |   3 +
 .../how-to-review-ai-generated-code.mdx       |  12 ++
 .../how-to-run-multiple-ai-coding-agents.mdx  |  12 ++
 ...ice-and-images-to-prompt-coding-agents.mdx |   6 +
 src/content/docs/index.mdx                    |   3 +
 .../admin-panel.mdx                           |   3 +
 .../knowledge-and-collaboration/teams.mdx     |   3 +
 .../warp-drive/index.mdx                      |  21 +++
 .../warp-drive/notebooks.mdx                  |  21 +++
 .../warp-drive/prompts.mdx                    |  12 ++
 .../warp-drive/web.mdx                        |   6 +
 .../warp-drive/workflows.mdx                  |  12 ++
 src/content/docs/reference/cli/api-keys.mdx   |   3 +
 .../docs/reference/cli/mcp-servers.mdx        |   3 +
 .../plans-and-billing/credits.mdx             |   3 +
 .../plans-and-billing/overages-legacy.mdx     |   3 +
 .../known-issues.mdx                          |   6 +
 .../sending-us-feedback.mdx                   |   3 +
 .../docs/terminal/appearance/app-icons.mdx    |   3 +
 .../docs/terminal/appearance/prompt.mdx       |   6 +
 .../terminal/blocks/sticky-command-header.mdx |   3 +
 src/content/docs/terminal/command-palette.mdx |   3 +
 src/content/docs/terminal/editor/index.mdx    |   3 +
 .../docs/terminal/entry/command-history.mdx   |   3 +
 .../docs/terminal/input/classic-input.mdx     |  12 ++
 .../docs/terminal/input/universal-input.mdx   |  42 ++++++
 .../terminal/integrations-and-plugins.mdx     |   6 +
 .../more-features/full-screen-apps.mdx        |   3 +
 .../more-features/markdown-viewer.mdx         |   6 +
 .../terminal/more-features/settings-sync.mdx  |   9 ++
 .../terminal/more-features/text-selection.mdx |   6 +
 .../docs/terminal/windows/tab-configs.mdx     |   6 +
 .../docs/terminal/windows/vertical-tabs.mdx   |  18 +++
 src/styles/custom.css                         |  21 +++
 71 files changed, 818 insertions(+)
 create mode 100644 scripts/apply-figcaptions.py
 create mode 100644 scripts/migrate-figcaptions.py

diff --git a/scripts/apply-figcaptions.py b/scripts/apply-figcaptions.py
new file mode 100644
index 0000000..43d3f59
--- /dev/null
+++ b/scripts/apply-figcaptions.py
@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""
+Apply <figure>+<figcaption> wrappers to Astro MDX images that had captions
+in the GitBook source.
+
+Usage:
+    python3 scripts/apply-figcaptions.py          # dry run (preview changes)
+    python3 scripts/apply-figcaptions.py --apply   # write changes to disk
+
+Transforms:
+    ![alt text](path/to/image.png)
+  →
+    <figure>
+    ![alt text](path/to/image.png)
+    <figcaption>Caption text from GitBook</figcaption>
+    </figure>
+"""
+
+import os
+import re
+import sys
+from pathlib import Path
+from collections import defaultdict
+
+GITBOOK_ROOT = Path(os.path.expanduser("~/Documents/Warp/gitbook"))
+ASTRO_CONTENT = Path(os.path.expanduser("~/Documents/Warp/docs/src/content/docs"))
+
+FIGURE_RE = re.compile(
+    r'<figure>'
+    r'.*?<img\s+src="([^"]+)"[^>]*>'
+    r'.*?<figcaption>(?:<p>)?(.*?)(?:</p>)?</figcaption>'
+    r'.*?</figure>',
+    re.DOTALL
+)
+
+MD_IMAGE_RE = re.compile(r'^(\s*)(!\[[^\]]*\]\([^)]*?/([^/)"]+)\))\s*$')
+
+
+def extract_gitbook_captions():
+    """Extract all non-empty figcaptions from GitBook source."""
+    captions = {}
+    for md_file in GITBOOK_ROOT.rglob("*.md"):
+        rel = str(md_file.relative_to(GITBOOK_ROOT))
+        if rel.startswith(".") or "node_modules" in rel:
+            continue
+        try:
+            content = md_file.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        for match in FIGURE_RE.finditer(content):
+            img_src = match.group(1)
+            caption = match.group(2).strip()
+            if not caption:
+                continue
+            caption = re.sub(r'<[^>]+>', '', caption).strip()
+            if not caption:
+                continue
+            basename = os.path.basename(img_src)
+            captions[basename] = caption
+    return captions
+
+
+def apply_figcaptions(captions, dry_run=True):
+    """Apply <figure>+<figcaption> wrappers to MDX files."""
+    total_applied = 0
+    files_modified = set()
+
+    for mdx_file in sorted(ASTRO_CONTENT.rglob("*.mdx")):
+        try:
+            content = mdx_file.read_text(encoding="utf-8")
+        except Exception:
+            continue
+
+        lines = content.splitlines(keepends=True)
+        new_lines = []
+        modified = False
+
+        i = 0
+        while i < len(lines):
+            line = lines[i]
+            match = MD_IMAGE_RE.match(line)
+
+            if match:
+                indent = match.group(1)
+                full_image = match.group(2)
+                img_basename = match.group(3)
+
+                if img_basename in captions:
+                    # Check if already wrapped in <figure>
+                    prev_line = new_lines[-1].strip() if new_lines else ""
+                    if "<figure>" in prev_line:
+                        new_lines.append(line)
+                        i += 1
+                        continue
+
+                    caption = captions[img_basename]
+                    new_lines.append(f"{indent}<figure>\n")
+                    new_lines.append(line)
+                    new_lines.append(f"{indent}<figcaption>{caption}</figcaption>\n")
+                    new_lines.append(f"{indent}</figure>\n")
+                    modified = True
+                    total_applied += 1
+                    i += 1
+                    continue
+
+            new_lines.append(line)
+            i += 1
+
+        if modified:
+            rel_file = str(mdx_file.relative_to(ASTRO_CONTENT))
+            files_modified.add(rel_file)
+            if dry_run:
+                print(f"  Would modify: {rel_file}")
+            else:
+                mdx_file.write_text("".join(new_lines), encoding="utf-8")
+                print(f"  Modified: {rel_file}")
+
+    return total_applied, files_modified
+
+
+def main():
+    dry_run = "--apply" not in sys.argv
+
+    if dry_run:
+        print("DRY RUN — pass --apply to write changes\n")
+
+    print("Extracting GitBook captions...")
+    captions = extract_gitbook_captions()
+    print(f"  Found {len(captions)} non-empty figcaptions\n")
+
+    print("Applying figcaptions to Astro MDX files...")
+    total, files = apply_figcaptions(captions, dry_run=dry_run)
+
+    print(f"\n{'Would apply' if dry_run else 'Applied'} {total} figcaptions across {len(files)} files")
+
+    if dry_run:
+        print("\nRun with --apply to write changes to disk.")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/migrate-figcaptions.py b/scripts/migrate-figcaptions.py
new file mode 100644
index 0000000..41f8e68
--- /dev/null
+++ b/scripts/migrate-figcaptions.py
@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""
+Extract non-empty figcaptions from GitBook source and generate a report
+of which Astro MDX images need <figure>+<figcaption> wrappers.
+
+Usage:
+    python3 scripts/migrate-figcaptions.py
+
+Output:
+    Prints a TSV report: astro_file, image_filename, caption_text
+    Also prints summary stats.
+
+The script matches GitBook figures to Astro images by image filename
+(basename), since the directory structure differs between repos.
+"""
+
+import os
+import re
+import sys
+from pathlib import Path
+from collections import defaultdict
+
+GITBOOK_ROOT = Path(os.path.expanduser("~/Documents/Warp/gitbook"))
+ASTRO_CONTENT = Path(os.path.expanduser("~/Documents/Warp/docs/src/content/docs"))
+
+# Pattern for GitBook's <figure><img ...><figcaption><p>text</p></figcaption></figure>
+FIGURE_RE = re.compile(
+    r'<figure>'
+    r'.*?<img\s+src="([^"]+)"[^>]*>'
+    r'.*?<figcaption>(?:<p>)?(.*?)(?:</p>)?</figcaption>'
+    r'.*?</figure>',
+    re.DOTALL
+)
+
+# Pattern for markdown images in Astro MDX: ![alt](path)
+MD_IMAGE_RE = re.compile(r'!\[([^\]]*)\]\(([^)]+)\)')
+
+
+def extract_gitbook_captions():
+    """Extract all non-empty figcaptions from GitBook source."""
+    captions = {}  # image_basename -> caption_text
+    
+    for md_file in GITBOOK_ROOT.rglob("*.md"):
+        # Skip non-content files
+        rel = str(md_file.relative_to(GITBOOK_ROOT))
+        if rel.startswith(".") or "node_modules" in rel:
+            continue
+        
+        try:
+            content = md_file.read_text(encoding="utf-8")
+        except Exception:
+            continue
+        
+        for match in FIGURE_RE.finditer(content):
+            img_src = match.group(1)
+            caption = match.group(2).strip()
+            
+            # Skip empty captions
+            if not caption:
+                continue
+            
+            # Strip any remaining HTML tags from caption
+            caption = re.sub(r'<[^>]+>', '', caption).strip()
+            if not caption:
+                continue
+            
+            # Use image basename as the key
+            basename = os.path.basename(img_src)
+            captions[basename] = caption
+    
+    return captions
+
+
+def find_astro_images():
+    """Find all markdown images in Astro MDX files."""
+    images = defaultdict(list)  # image_basename -> [(astro_file, line_num, full_line)]
+    
+    for mdx_file in ASTRO_CONTENT.rglob("*.mdx"):
+        try:
+            lines = mdx_file.read_text(encoding="utf-8").splitlines()
+        except Exception:
+            continue
+        
+        for i, line in enumerate(lines, 1):
+            for match in MD_IMAGE_RE.finditer(line):
+                img_path = match.group(2)
+                basename = os.path.basename(img_path)
+                rel_file = str(mdx_file.relative_to(ASTRO_CONTENT))
+                images[basename].append((rel_file, i, line.strip()))
+    
+    return images
+
+
+def main():
+    print("Scanning GitBook source for figcaptions...", file=sys.stderr)
+    captions = extract_gitbook_captions()
+    print(f"  Found {len(captions)} non-empty figcaptions", file=sys.stderr)
+    
+    print("Scanning Astro MDX files for images...", file=sys.stderr)
+    astro_images = find_astro_images()
+    print(f"  Found {len(astro_images)} unique image filenames", file=sys.stderr)
+    
+    # Match captions to Astro images
+    matched = 0
+    unmatched_captions = []
+    
+    print("\n# Matched figcaptions (astro_file\tline\timage\tcaption)")
+    print("# " + "=" * 80)
+    
+    for basename, caption in sorted(captions.items()):
+        if basename in astro_images:
+            for astro_file, line_num, _ in astro_images[basename]:
+                print(f"{astro_file}\t{line_num}\t{basename}\t{caption}")
+                matched += 1
+        else:
+            unmatched_captions.append((basename, caption))
+    
+    print(f"\n# Summary:", file=sys.stderr)
+    print(f"#   Matched: {matched} images in Astro have captions to restore", file=sys.stderr)
+    print(f"#   Unmatched: {len(unmatched_captions)} GitBook captions couldn't be matched to Astro images", file=sys.stderr)
+    
+    if unmatched_captions:
+        print(f"\n# Unmatched captions (image may have been renamed or removed):", file=sys.stderr)
+        for basename, caption in unmatched_captions[:20]:
+            print(f"#   {basename}: {caption[:60]}...", file=sys.stderr)
+        if len(unmatched_captions) > 20:
+            print(f"#   ... and {len(unmatched_captions) - 20} more", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/content/docs/agent-platform/capabilities/agent-notifications.mdx b/src/content/docs/agent-platform/capabilities/agent-notifications.mdx
index ef50787..fe5b342 100644
--- a/src/content/docs/agent-platform/capabilities/agent-notifications.mdx
+++ b/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>A toast notification in the corner of the Warp window signals that an agent task has completed. Click the toast to jump to the agent's session.</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>The notification mailbox collects all agent notifications in one place. Use the filter tabs to switch between All tabs and Unread.</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>Warp surfaces a one-click install chip in the agent utility bar when a supported CLI agent is running without the notification plugin installed.</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.
 
diff --git a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx b/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx
index d1cbaa0..cd7295b 100644
--- a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx
+++ b/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx
@@ -13,7 +13,10 @@ 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 Profiles in Settings: define how your Agent operates.</figcaption>
+</figure>
 
 **In each Agent Profile, you can configure:**
 
@@ -21,7 +24,10 @@ Agent Profiles let you configure how your Agent behaves in different situations.
 * **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>Agent Profiles in Settings: editing a 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>Customize how the Agent interacts with MCP servers by choosing between “Agent decides,” allowlist, or denylist settings.</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>A button overlay in the lower-right corner lets you enable auto-approve or end the Agent interaction.</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.
diff --git a/src/content/docs/agent-platform/capabilities/codebase-context.mdx b/src/content/docs/agent-platform/capabilities/codebase-context.mdx
index 56d3621..cf3935e 100644
--- a/src/content/docs/agent-platform/capabilities/codebase-context.mdx
+++ b/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 in Warp. Easily track sync status and manage which folders are indexed for AI-powered context and suggestions.</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>View and manage the indexing status of your codebases in Warp. Easily see which projects are synced, in progress, or require attention.</figcaption>
+</figure>
 
 ### When does codebase syncing happen?
 
diff --git a/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx b/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx
index d230f28..cd2f865 100644
--- a/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx
+++ b/src/content/docs/agent-platform/capabilities/full-terminal-use.mdx
@@ -33,7 +33,10 @@ 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.”
@@ -41,9 +44,15 @@ You can either ask the agent to run an interactive command, or start one manuall
 
 <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)
 
diff --git a/src/content/docs/agent-platform/capabilities/mcp.mdx b/src/content/docs/agent-platform/capabilities/mcp.mdx
index fb1f827..18a6a2c 100644
--- a/src/content/docs/agent-platform/capabilities/mcp.mdx
+++ b/src/content/docs/agent-platform/capabilities/mcp.mdx
@@ -25,7 +25,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
 
@@ -37,7 +40,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.
@@ -55,7 +61,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**
 
@@ -99,7 +108,10 @@ Warp detects MCP server configurations managed by supported third-party agents a
 
 To enable, go to **Settings** > **Agents** > **MCP servers** and toggle **File-based MCP Servers** on.
 
+<figure>
 ![File-based MCP Servers toggle](/assets/agent-platform/file-based-mcp-toggle.gif)
+<figcaption>File-based MCP Servers toggle</figcaption>
+</figure>
 
 When enabled:
 
@@ -125,7 +137,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.
 
diff --git a/src/content/docs/agent-platform/capabilities/model-choice.mdx b/src/content/docs/agent-platform/capabilities/model-choice.mdx
index 03bf595..95e14e6 100644
--- a/src/content/docs/agent-platform/capabilities/model-choice.mdx
+++ b/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.
 
diff --git a/src/content/docs/agent-platform/capabilities/planning.mdx b/src/content/docs/agent-platform/capabilities/planning.mdx
index 78761e4..efb513b 100644
--- a/src/content/docs/agent-platform/capabilities/planning.mdx
+++ b/src/content/docs/agent-platform/capabilities/planning.mdx
@@ -18,7 +18,10 @@ 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>Prompting the agent to create a plan using the slash 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.
 
@@ -26,29 +29,44 @@ The agent then creates a structured plan inside Warp’s native rich text editor
 
 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>Manually referencing the plan using @ to kickoff the plan.</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>Option to pass new plan to agent if plan changes during runtime.</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.
 
@@ -56,15 +74,24 @@ This gives you clear oversight, helps confirm expected behavior, and lets you in
 
 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**.
 
diff --git a/src/content/docs/agent-platform/capabilities/rules.mdx b/src/content/docs/agent-platform/capabilities/rules.mdx
index dbe86b0..0439616 100644
--- a/src/content/docs/agent-platform/capabilities/rules.mdx
+++ b/src/content/docs/agent-platform/capabilities/rules.mdx
@@ -87,7 +87,10 @@ This ensures the most specific, project-relevant rules take priority over broade
 * From the macOS Menu: `AI > Open Rules` &#x20;
 * From the Slash Commands menu: `/open-project-rules`  to open Project Rules directly in Warp's code editor
 
+<figure>
 ![Project Rules UI open in a Rules pane](../../../../assets/agent-platform/project-scoped-rules-pane.png)
+<figcaption>Project Rules UI open in a Rules pane</figcaption>
+</figure>
 
 ## How to create, edit, or delete Rules
 
@@ -115,9 +118,15 @@ To view all Project Rules and open them in Warp, access it via the Warp Drive Ru
 
 When relevant, Agents automatically pull in applicable rules to guide their responses. Rules used in an interaction will appear in the conversation under **References** or marked as derived from a specific rule.
 
+<figure>
 ![Context derived from memory](../../../../assets/agent-platform/context-derived-from-memory.png)
+<figcaption>Derived from rules</figcaption>
+</figure>
 
+<figure>
 ![Context derived from memory](../../../../assets/agent-platform/context-references-memory.png)
+<figcaption>Rules as references</figcaption>
+</figure>
 
 ### Rules privacy
 
diff --git a/src/content/docs/agent-platform/capabilities/slash-commands.mdx b/src/content/docs/agent-platform/capabilities/slash-commands.mdx
index ef24b7b..0ee95b7 100644
--- a/src/content/docs/agent-platform/capabilities/slash-commands.mdx
+++ b/src/content/docs/agent-platform/capabilities/slash-commands.mdx
@@ -7,7 +7,10 @@ description: >-
 
 When using Agent Mode or Auto-Detection Mode, typing `/` in the input field opens the Slash Commands menu.
 
+<figure>
 ![Slash Commands menu](../../../../assets/agent-platform/slash-commands-menu.png)
+<figcaption>Slash Commands menu</figcaption>
+</figure>
 
 As you type, the menu filters results in real time, making it easy to find and run the command or prompt you need.
 
@@ -28,7 +31,10 @@ In addition to static commands, the menu also shows [Agent Prompts](/knowledge-a
 * These prompts can be custom ones you’ve created or ones shared with you.
 * As you type after `/`, prompts are filtered dynamically, so you can quickly run them without leaving the input field.
 
+<figure>
 ![Slash Commands menu with filtered Agent Prompts](../../../../assets/agent-platform/slash-commands-prompts.png)
+<figcaption>Slash Commands menu with filtered Agent Prompts</figcaption>
+</figure>
 
 ### Tips
 
@@ -39,6 +45,12 @@ In addition to static commands, the menu also shows [Agent Prompts](/knowledge-a
 
 Below is an example interaction when `/init` is run:
 
+<figure>
 ![/init setup flow; 1 of 2](../../../../assets/agent-platform/init-setup-flow-1.png)
+<figcaption>/init setup flow; 1 of 2</figcaption>
+</figure>
 
+<figure>
 ![/init setup flow; 2 of 2](../../../../assets/agent-platform/init-setup-flow-2.png)
+<figcaption>/init setup flow; 2 of 2</figcaption>
+</figure>
diff --git a/src/content/docs/agent-platform/capabilities/task-lists.mdx b/src/content/docs/agent-platform/capabilities/task-lists.mdx
index 2ce6b8a..3c21489 100644
--- a/src/content/docs/agent-platform/capabilities/task-lists.mdx
+++ b/src/content/docs/agent-platform/capabilities/task-lists.mdx
@@ -10,7 +10,10 @@ The Agent can automatically break down complex requests into clear, trackable st
 \
 When you make a sufficiently complex request that requires multiple actions, the Agent will automatically create a list of steps, execute them in order, and track progress from start to finish. There’s no need to adjust settings or enable a special mode—the Agent detects and creates task lists automatically.
 
+<figure>
 ![An example of a task list in progress.](../../../../assets/agent-platform/in-progress-tasklist.png)
+<figcaption>An example of a Task List in progress.</figcaption>
+</figure>
 
 ### How task lists work
 
@@ -20,7 +23,10 @@ When you make a sufficiently complex request that requires multiple actions, the
 
 After each step is completed, there is also a completion marker in the Agent conversation.
 
+<figure>
 ![Completion markers inside the Agent conversation after each task is completed.](../../../../assets/agent-platform/completion-markers.png)
+<figcaption>Completion markers inside the Agent conversation after each task is completed.</figcaption>
+</figure>
 
 ### Task statuses
 
@@ -37,4 +43,7 @@ During any Agent conversation, a task list chip appears at the bottom-right of t
 * Click the chip to open the current task list.
 * You can collapse or expand the view at any time without interrupting the Agent.
 
+<figure>
 ![Access the task list during an Agent conversation in the task list chip in the conversation.](../../../../assets/agent-platform/tasklist-popup.png)
+<figcaption>Access the Task List during an Agent conversation in the Task List chip in the conversation.</figcaption>
+</figure>
diff --git a/src/content/docs/agent-platform/cli-agents/overview.mdx b/src/content/docs/agent-platform/cli-agents/overview.mdx
index 84fbfe0..42c173b 100644
--- a/src/content/docs/agent-platform/cli-agents/overview.mdx
+++ b/src/content/docs/agent-platform/cli-agents/overview.mdx
@@ -28,7 +28,10 @@ Warp currently supports the following CLI coding agents:
 
 When you launch a supported agent inside Warp, the **agent toolbelt** appears automatically, giving you quick access to Warp's enhanced features.
 
+<figure>
 ![The agent toolbelt appearing at the bottom of the pane when a supported CLI agent is running in Warp](../../../../assets/agent-platform/cli-agent-toolbelt.png)
+<figcaption>The agent toolbelt appears automatically when a supported CLI agent is running</figcaption>
+</figure>
 
 ## Feature support
 
diff --git a/src/content/docs/agent-platform/cli-agents/remote-control.mdx b/src/content/docs/agent-platform/cli-agents/remote-control.mdx
index a5f149d..0c21712 100644
--- a/src/content/docs/agent-platform/cli-agents/remote-control.mdx
+++ b/src/content/docs/agent-platform/cli-agents/remote-control.mdx
@@ -32,7 +32,10 @@ Remote Control differs from standard [Agent Session Sharing](/agent-platform/loc
 1. Start or resume a third-party agent session in Warp (for example, Claude Code or Codex).
 2. Click the **`/remote-control`** chip in the agent utility bar. Warp publishes the session to the cloud and copies the shareable link to your clipboard.
 
+<figure>
 ![The /remote-control chip in the agent utility bar with a Start remote control tooltip](../../../../assets/agent-platform/remote-control.png)
+<figcaption>Click the /remote-control chip in the agent utility bar to publish the session.</figcaption>
+</figure>
 
 3. A **Sharing link copied** toast notification confirms the link is on your clipboard, and the pane's status icon changes to a red broadcast indicator to show that publishing is active.
 4. Open the link on another device, or share it with a teammate.
diff --git a/src/content/docs/agent-platform/cli-agents/rich-input.mdx b/src/content/docs/agent-platform/cli-agents/rich-input.mdx
index 61233a1..e2ab94e 100644
--- a/src/content/docs/agent-platform/cli-agents/rich-input.mdx
+++ b/src/content/docs/agent-platform/cli-agents/rich-input.mdx
@@ -22,13 +22,19 @@ There are two ways to open the rich input editor:
 1. **Keyboard shortcut** - Press `Ctrl-G` (configurable) while a supported agent is running in the active pane.
 2. **Rich Input button** - Click the **Rich Input** button in the agent utility bar at the bottom of the pane.
 
+<figure>
 ![The Rich Input button in the agent utility bar at the bottom of the pane](../../../../assets/agent-platform/rich-input-button.png)
+<figcaption>The Rich Input button in the agent utility bar</figcaption>
+</figure>
 
 The rich input editor also auto-opens when an agent resumes from a blocked state (for example, after you approve a command). This requires the agent's plugin to be supported and installed. Toggle **Auto show/hide based on agent status** in [Rich input settings](#rich-input-settings) to control this behavior.
 
 When the rich input editor is active, Warp hides the cursor inside the CLI agent and moves focus to the editor input. Submit your prompt from here and it goes directly to the running agent.
 
+<figure>
 ![The rich input editor open with a prompt being composed](../../../../assets/agent-platform/rich-input-prompt.png)
+<figcaption>The rich input editor with IDE-style editing and multi-line prompt support</figcaption>
+</figure>
 
 ## Rich input settings
 
@@ -40,7 +46,10 @@ In the Warp app, go to **Settings** > **Agents** > **Third party CLI agents** to
 * **Keyboard shortcut** - The default shortcut is `Ctrl-G`. Customize this in **Settings** > **Keyboard shortcuts**.
 * **Disable the Rich Input button** - Right-click the agent utility bar and remove the **Rich Input** chip, or disable the footer entirely in **Settings** > **Agents** > **Third party CLI agents**.
 
+<figure>
 ![Rich input settings panel](../../../../assets/agent-platform/rich-input-settings.png)
+<figcaption>Rich input settings in Warp</figcaption>
+</figure>
 
 ## Related pages
 
diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx
index 92730a7..a1f29e4 100644
--- a/src/content/docs/agent-platform/cloud-agents/environments.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/environments.mdx
@@ -144,7 +144,10 @@ Musl-based Docker images (such as Alpine Linux) are not supported. The agent run
 Create one environment per codebase, then reuse it across triggers like Slack, Linear, and CLI runs.
 :::
 
+<figure>
 ![Creating a new environment in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-new-environment.png)
+<figcaption>Creating a new environment in the Oz Web App.</figcaption>
+</figure>
 
 ### Create an environment with guided setup (recommended)
 
diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx
index da29e2b..d67d942 100644
--- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx
@@ -161,7 +161,10 @@ To remove the Oz app from your Slack workspace:
 5. Scroll to the bottom and select **Remove App**.
 6. Confirm the removal.
 
+<figure>
 ![Warpy is just an internal Slackbot, your Warp slackbot should be called Oz.](../../../../../assets/agent-platform/delete-warpy.png)
+<figcaption>Warpy is just an internal Slackbot, your Warp slackbot should be called Oz.</figcaption>
+</figure>
 
 ![Confirmation dialog to remove the Oz app from a Slack workspace.](../../../../../assets/agent-platform/remove-slack-app.png)
 
diff --git a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx
index 2c87987..c5a96f1 100644
--- a/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx
@@ -22,7 +22,10 @@ The management view is designed to answer, at a glance:
 
 This management view includes your **local (interactive) agents** and [cloud agent](/agent-platform/cloud-agents/overview/) runs.
 
+<figure>
 ![Warp's management view showing interactive and cloud agent runs.](../../../../assets/agent-platform/management-view-scannable-list.png)
+<figcaption>Warp's management view showing interactive and cloud agent runs.</figcaption>
+</figure>
 
 ### What appears in the management view
 
diff --git a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx
index feb4cdb..bdbafc9 100644
--- a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx
@@ -21,7 +21,10 @@ Watch this short demo to create an environment and run an agent using the Oz web
 
 <table><thead><tr><th width="150">Page</th><th width="120">Path</th><th>What you can do</th></tr></thead><tbody><tr><td><strong>Dashboard</strong></td><td><code>/dashboard</code></td><td>Quick actions, suggested agents, recent agents, and featured reads</td></tr><tr><td><strong>Runs</strong></td><td><code>/runs</code></td><td>View all runs, filter by status/source/creator, start new runs, inspect transcripts</td></tr><tr><td><strong>Agents</strong></td><td><code>/agents</code></td><td>Browse skills from your environments, view suggested skills, dispatch skills as agents</td></tr><tr><td><strong>Schedules</strong></td><td><code>/schedules</code></td><td>Create scheduled agents, pause/enable schedules, view run history</td></tr><tr><td><strong>Environments</strong></td><td><code>/environments</code></td><td>Create and manage environments with repos, Docker images, and setup commands</td></tr><tr><td><strong>Integrations</strong></td><td><code>/integrations</code></td><td>Connect Slack and Linear to trigger agents from external tools</td></tr></tbody></table>
 
+<figure>
 ![The Oz Web App's management view.](../../../../assets/agent-platform/oz-web-app-runs-view.png)
+<figcaption>The Oz Web App's management view.</figcaption>
+</figure>
 
 ## When to use the web app
 
@@ -124,7 +127,10 @@ Each skill displays:
 
 <table><thead><tr><th width="150">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>The skill's identifier</td></tr><tr><td><strong>Description</strong></td><td>What the skill does</td></tr><tr><td><strong>Environments</strong></td><td>Which environments have access to this skill</td></tr></tbody></table>
 
+<figure>
 ![The Agents page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-agents.png)
+<figcaption>The Agents page in the Oz Web App.</figcaption>
+</figure>
 
 Filter by environment or switch to the **Suggested** tab to see pre-built skills for common workflows like code review, dependency updates, and documentation sync.
 
@@ -140,7 +146,10 @@ For more details on how skills work with cloud agents, see [Skills as Agents](/a
 
 Click **New agent** to create a new skill. The guided flow helps you define the skill's instructions, which are then available for future runs.
 
+<figure>
 ![Creating a new agent skill in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-new-agent.png)
+<figcaption>Creating a new agent skill in the Oz Web App.</figcaption>
+</figure>
 
 ---
 
@@ -154,7 +163,10 @@ Each schedule displays:
 
 <table><thead><tr><th width="150">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>A descriptive name for the scheduled task</td></tr><tr><td><strong>Frequency</strong></td><td>Human-readable description of the cron schedule (e.g., "Every Monday at 10am")</td></tr><tr><td><strong>Next run</strong></td><td>When the schedule will next execute</td></tr><tr><td><strong>Environment</strong></td><td>Which environment the scheduled agent runs in</td></tr><tr><td><strong>Agent</strong></td><td>Which skill the schedule uses (if any)</td></tr><tr><td><strong>Status</strong></td><td>Whether the schedule is active or paused</td></tr></tbody></table>
 
+<figure>
 ![The Schedules page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-schedules.png)
+<figcaption>The Schedules page in the Oz Web App.</figcaption>
+</figure>
 
 ---
 
@@ -197,7 +209,10 @@ Each environment displays:
 
 <table><thead><tr><th width="170">Field</th><th>Description</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>The environment's identifier</td></tr><tr><td><strong>Docker image</strong></td><td>The container image used for execution</td></tr><tr><td><strong>Repositories</strong></td><td>Which repos the agent can access</td></tr><tr><td><strong>Setup commands</strong></td><td>Commands run before the agent starts</td></tr></tbody></table>
 
+<figure>
 ![The Environments page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-environments.png)
+<figcaption>The Environments page in the Oz Web App.</figcaption>
+</figure>
 
 ---
 
@@ -226,7 +241,10 @@ The **Integrations** page (`/integrations`) lets you configure first-party integ
 
 <table><thead><tr><th width="120">Integration</th><th>Description</th></tr></thead><tbody><tr><td><strong>Slack</strong></td><td>Tag @Oz in messages or threads to trigger agents directly from Slack conversations</td></tr><tr><td><strong>Linear</strong></td><td>Tag @Oz on issues to trigger agents from your issue tracker</td></tr></tbody></table>
 
+<figure>
 ![The Integrations page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-integrations.png)
+<figcaption>The Integrations page in the Oz Web App.</figcaption>
+</figure>
 
 ### Setting up an integration
 
diff --git a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx
index 9b28fb6..298e9f9 100644
--- a/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/team-access-billing-and-identity.mdx
@@ -124,11 +124,17 @@ There are two places you may encounter this installation flow:
    Each installation is scoped to a single GitHub organization or personal account — you can install the app to multiple orgs separately.
 :::
 
+   <figure>
    ![Oz by Warp GitHub App installation page showing repository access options](../../../../assets/agent-platform/oz-github-app-installation.png)
+   <figcaption>Installing the Oz by Warp GitHub App.</figcaption>
+   </figure>
 
 2. **Enable the GitHub org for your Warp team.** A Warp team admin opens the Admin Panel in the Warp app (**Settings** > **Admin Panel** > **Platform**) and adds the GitHub organization under **Enabled GitHub Orgs**. This associates the GitHub App installation with your Warp team.
 
+   <figure>
    ![Enabled GitHub Orgs setting in the Admin Panel Platform section](../../../../assets/agent-platform/admin-panel-enabled-github-orgs.png)
+   <figcaption>Enabled GitHub Orgs setting in the Admin Panel.</figcaption>
+   </figure>
 
 3. **Use a team API key.** Tasks initiated with a team API key now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed.
 
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx
index 6254c48..46a5720 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx
@@ -12,7 +12,10 @@ Warp’s Agent can use blocks from your Agent conversations as context to better
 
 You can attach a block directly from the terminal blocklist by clicking the AI sparkles icon on it and selecting “Attach as context.”
 
+<figure>
 ![From a block of output, attach the block and ask Agent Mode to remove all untracked files.](../../../../../assets/agent-platform/remove_all_untracked_files.png)
+<figcaption>From a block of output, attach the block and ask Agent Mode to remove all untracked files.</figcaption>
+</figure>
 
 The most common use case is to ask the AI to fix an error. You can attach the error in a query to Agent Mode and type "fix it."
 
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx
index b4691c2..aad2071 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx
@@ -13,9 +13,15 @@ You can attach images in the following ways:
 
 * Using the **image upload button** found on the toolbelt (either on the bottom left or right), depending on which input mode you're using:
 
+<figure>
 ![Attaching 5 images on the new "Universal" input (bottom left toolbelt)](../../../../../assets/agent-platform/image-as-context-universal.png)
+<figcaption>Attaching 5 images on the new "Universal" input (bottom left toolbelt)</figcaption>
+</figure>
 
+<figure>
 ![Attaching 4 images on the "Classic" input (bottom right)](../../../../../assets/agent-platform/image-as-context-classic.png)
+<figcaption>Attaching 4 images on the "Classic" input (bottom right)</figcaption>
+</figure>
 
 * Copy and paste images directly (e.g. right-click an image > "Copy image" or copy from a file manager) into Warp.
 * Drag and drop images, such as from a file manager or screenshot utility.
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx
index ba39a9f..a5273da 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx
@@ -15,7 +15,10 @@ When you have Warp’s [native code editor](/code/code-editor/) open beside a re
 
 This makes it easy to highlight just the lines you want the Agent to analyze or modify.
 
+<figure>
 ![Selecting a function and attaching it as context from Warp's native code editor.](../../../../../assets/agent-platform/selection-as-context.png)
+<figcaption>Selecting a function and attaching it as context from Warp's native code editor.</figcaption>
+</figure>
 
 ### Attaching selections from Warp’s Code Review panel
 
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx
index 8999060..297f3c8 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx
@@ -17,4 +17,7 @@ You can attach a public URL to any prompt to provide page content as context. Wa
 **Important**: URL attachments are different from web search. If you need the agent to look something up, gather real-time information, or pull in multiple sources, use [Web Search](/agent-platform/capabilities/web-search/) instead.
 :::
 
+<figure>
 ![Example of referencing docs via a URL](../../../../../assets/agent-platform/url-as-context.png)
+<figcaption>Example of referencing docs via a URL</figcaption>
+</figure>
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
index 877724a..5e11771 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
@@ -16,13 +16,22 @@ Attaching context with @ works in **both natural language mode** (when interacti
 
 **Note**: the search in the @-context menu is always relative to the root of the Git repository, even when you're working in a subdirectory. This means you can reference _any_ file or folder tracked in the repo, regardless of the current working directory.
 
+<figure>
 ![Using the @ symbol to search for and attach a file or folder from the project root.](../../../../../assets/agent-platform/at-context.png)
+<figcaption>Using the @ symbol to search for and attach a file or folder from the project root.</figcaption>
+</figure>
 
 Additionally, no codebase indexing (via [Codebase Context](/agent-platform/capabilities/codebase-context/)) is required — file search is available immediately in any Git-initialized directory. The search also respects `.gitignore` rules and will exclude ignored files from the results.
 
+<figure>
 ![Filtering files using @app to locate files containing “app” in their name or path.](../../../../../assets/agent-platform/at-context-app.png)
+<figcaption>Filtering files using @app to locate files containing “app” in their name or path.</figcaption>
+</figure>
 
+<figure>
 ![Referencing a folder or all files within it by typing @styles.](../../../../../assets/agent-platform/at-context-styles.png)
+<figcaption>Referencing a folder or all files within it by typing @styles.</figcaption>
+</figure>
 
 ### Referencing code symbols
 
diff --git a/src/content/docs/agent-platform/local-agents/code-diffs.mdx b/src/content/docs/agent-platform/local-agents/code-diffs.mdx
index 88d8bf0..1391cde 100644
--- a/src/content/docs/agent-platform/local-agents/code-diffs.mdx
+++ b/src/content/docs/agent-platform/local-agents/code-diffs.mdx
@@ -22,7 +22,10 @@ If the `Apply Code Diffs` permission is set to `Always allow` in [Agent Profiles
 Code diffs generated by Warp are never stored on our servers. Warp's coding agent only works on local repositories. The agent can make changes on remote or docker repositories, but falls back to using terminal commands (i.e. `sed`, `grep` ) to make the changes.
 :::
 
+<figure>
 ![A code diff surfaced in an Agent Conversation.](../../../../assets/agent-platform/generated_blocklist_diff.png)
+<figcaption>A code diff surfaced in an Agent Conversation.</figcaption>
+</figure>
 
 You can also choose whether Warp automatically opens the [Code Review](/code/code-review/) panel the first time you accept a diff in a conversation.
 
@@ -50,7 +53,10 @@ If the initial suggestion needs more work:
 You can open up code files in Warp in various different ways, refer to: [Opening files in Warp](/code/code-editor/#opening-files-in-warp)
 :::
 
+<figure>
 ![Editing a code diff directly in Warp's native code editor](../../../../assets/agent-platform/editting_diff.png)
+<figcaption>Editing the code diff directly in Warp's native code editor.</figcaption>
+</figure>
 
 ## Accepting diffs and continuing in Agent Mode
 
diff --git a/src/content/docs/agent-platform/local-agents/generate.mdx b/src/content/docs/agent-platform/local-agents/generate.mdx
index 327f649..0dad694 100644
--- a/src/content/docs/agent-platform/local-agents/generate.mdx
+++ b/src/content/docs/agent-platform/local-agents/generate.mdx
@@ -24,7 +24,10 @@ Currently, you need to be online to use this feature. If this feature doesn't wo
 
 Type `#` on the command-line input to generate command suggestions.
 
+<figure>
 ![Typing '#' on the command line opens the suggestions interface](../../../../assets/agent-platform/open-ai-commands.png)
+<figcaption>Typing '#' on the command line opens the suggestions interface</figcaption>
+</figure>
 
 <VideoEmbed url="https://www.loom.com/share/424a763ef0c8455e8269e541301968f2" title="Generating commands as command-line input demo" />
 
@@ -42,9 +45,15 @@ The agent can provide input when prompted, navigate interactive screens, and con
 
 In interactive CLI applications, you can generate input using natural language.
 
+<figure>
 ![Generate a SQL query](../../../../assets/agent-platform/generate-psql.png)
+<figcaption>Generate a SQL query</figcaption>
+</figure>
 
+<figure>
 ![Generate Vim input](../../../../assets/agent-platform/generate-vim.png)
+<figcaption>Generate Vim input</figcaption>
+</figure>
 
 <Tabs>
   <TabItem label="macOS">
diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx
index d1a0ec4..1034677 100644
--- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx
+++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx
@@ -34,9 +34,15 @@ By default, if you ask an AI query immediately after interacting in Agent Mode,
 * Open the **Conversations menu** (`CMD + Y` on macOS, `CTRL + SHIFT + Y` on Windows/Linux), select a conversation, and then enter your query.
 * Alternatively, click the pink conversation chip in the input field to resume.
 
+<figure>
 ![Continuing an Agent conversation in Classic Input (with indicator)](../../../../../assets/agent-platform/classic-input-follow-up.png)
+<figcaption>Continuing an Agent conversation in Classic Input (with indicator)</figcaption>
+</figure>
 
+<figure>
 ![Continuing an Agent conversation in agent conversation view](../../../../../assets/agent-platform/follow-up-universal-input.png)
+<figcaption>Continuing an Agent conversation in agent conversation view</figcaption>
+</figure>
 
 #### Agent tips in the input
 
@@ -92,9 +98,15 @@ Visual indicators differ slightly depending on input mode:
   </TabItem>
 </Tabs>
 
+<figure>
 ![Starting a new Conversation in Classic Input](../../../../../assets/agent-platform/classic-input-new-convo.png)
+<figcaption>Starting a new Conversation in Classic Input</figcaption>
+</figure>
 
+<figure>
 ![Starting a new Agent Conversation in agent conversation view](../../../../../assets/agent-platform/universal-input-new-convo.png)
+<figcaption>Starting a new Agent Conversation in agent conversation view</figcaption>
+</figure>
 
 ## Context window management
 
diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx
index 988d880..dabfd22 100644
--- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx
+++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx
@@ -73,7 +73,10 @@ The shortcuts shown on this page use macOS keybindings. For Windows and Linux sh
 * Familiar "charms" (current directory, git branch, diff view entry point, etc.) are still available.
 * Designed for multi-turn workflows and managing multiple conversations.
 
+<figure>
 ![The dedicated Agent Conversation View.](../../../../../assets/agent-platform/agent-modality-conversation-view.png)
+<figcaption>The dedicated Agent Conversation View.</figcaption>
+</figure>
 
 **Key difference**
 
@@ -301,7 +304,10 @@ For more forking methods and use cases, see [Conversation Forking](/agent-platfo
 
 If you prefer to type natural language at any point in a terminal session and have it automatically routed to an agent, you can configure this using the "default mode for new sessions" setting.
 
+<figure>
 ![Using Agent as your default for new tab sessions](/assets/agent-platform/recreate-universal-input.gif)
+<figcaption>Using Agent as your default for new tab sessions</figcaption>
+</figure>
 
 ### Step 1 — Set new tabs to open in agent view
 
diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/voice.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/voice.mdx
index 4598860..7d264ab 100644
--- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/voice.mdx
+++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/voice.mdx
@@ -55,7 +55,10 @@ There are two ways to activate Voice:
   </TabItem>
 </Tabs>
 
+<figure>
 ![Voice settings panel showing hotkey configuration and voice input toggle options](../../../../../assets/agent-platform/voice-settings.png)
+<figcaption>Voice settings panel showing hotkey configuration and voice input toggle options</figcaption>
+</figure>
 
 ### Sample use cases
 
@@ -65,7 +68,10 @@ You can also describe multi-step system tasks like "Find all log files in my pro
 
 Voice input is not limited to just Agent Mode - it works across all of Warp's input interfaces. Whether you're using the Find dialog to search through text, entering commands in the terminal, or working with other input editors, you can use voice commands to quickly input your text.
 
+<figure>
 ![Voice input works across Warp's editor interfaces, including the Find dialog and other input editors](../../../../../assets/agent-platform/voice-in-find.png)
+<figcaption>Voice input works across Warp's editor interfaces, including the Find dialog and other input editors</figcaption>
+</figure>
 
 ## Privacy & security
 
diff --git a/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx b/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx
index e1acd96..b568d9f 100644
--- a/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx
+++ b/src/content/docs/agent-platform/local-agents/interactive-code-review.mdx
@@ -47,7 +47,10 @@ Select any changed line or block and add a comment describing what you want adju
 
 Add as many comments as you need before submitting them. The agent receives your entire batch of feedback, applies the changes in one iteration, and returns an updated diff for verification.
 
+<figure>
 ![Adding comments directly in the Code Review view.](../../../../assets/agent-platform/interactive-code-review-batch-comments.png)
+<figcaption>Adding comments directly in the Code Review view.</figcaption>
+</figure>
 
 ### Example demo
 
diff --git a/src/content/docs/agent-platform/local-agents/session-sharing.mdx b/src/content/docs/agent-platform/local-agents/session-sharing.mdx
index 5d26b68..7982c6d 100644
--- a/src/content/docs/agent-platform/local-agents/session-sharing.mdx
+++ b/src/content/docs/agent-platform/local-agents/session-sharing.mdx
@@ -34,9 +34,15 @@ When you share an agent session, Warp publishes it to the cloud and generates a
 4. Confirm the share. Warp uploads the session to the cloud and generates a shareable link.
 5. Copy the link and share it with teammates, or open it on another device.
 
+<figure>
 ![Starting a shared agent session from the right-click context menu](../../../../assets/agent-platform/agent-session-sharing-right-click-menu.png)
+<figcaption>Start a shared session via the right click menu.</figcaption>
+</figure>
 
+<figure>
 ![Starting a shared agent session from the Command Palette](../../../../assets/agent-platform/agent-session-sharing-command-palette.png)
+<figcaption>Start a shared session via the Command Palette.</figcaption>
+</figure>
 
 ## Viewing shared sessions
 
diff --git a/src/content/docs/code/code-editor/file-tree.mdx b/src/content/docs/code/code-editor/file-tree.mdx
index 6ebcf5f..a6ab134 100644
--- a/src/content/docs/code/code-editor/file-tree.mdx
+++ b/src/content/docs/code/code-editor/file-tree.mdx
@@ -40,7 +40,10 @@ Right-clicking any **file** opens a context menu with several useful options:
 * **Copy path**: Copy the absolute file path.
 * **Copy relative path**: Copy the path relative to your current working directory.
 
+<figure>
 ![Right-click context menu on a folder in the file tree.](../../../../assets/terminal/file-tree-context-menu.png)
+<figcaption>Right-click context menu on a folder in the file tree.</figcaption>
+</figure>
 
 Right-clicking any **folder** opens a context menu with the following options:
 
diff --git a/src/content/docs/code/code-review.mdx b/src/content/docs/code/code-review.mdx
index 4f4a6bb..f532917 100644
--- a/src/content/docs/code/code-review.mdx
+++ b/src/content/docs/code/code-review.mdx
@@ -19,7 +19,10 @@ Any uncommitted changes appear in the panel (or compare the changes on your bran
 
 <VideoEmbed url="https://www.loom.com/share/96581523168742eb9b95c3973924728c?sid=a3ee9164-4274-4468-ac32-38ce6807f9a8" title="Code Review Demo" />
 
+<figure>
 ![Full view of Code Review panel and terminal pane.](../../../assets/terminal/code-review-panel-update.png)
+<figcaption>Full view of Code Review panel and terminal pane.</figcaption>
+</figure>
 
 :::note
 To review agent-generated diffs, leave inline comments, batch your feedback, and have the agent apply all requested changes, see [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/).
@@ -94,7 +97,10 @@ Any saved edits made outside of Warp (e.g. in another editor), as well as change
 
 The Code Review pane makes it simple to share changes with the Agent. You can attach an entire diff to a prompt so the Agent has full visibility into what was added or removed.
 
+<figure>
 ![Attaching a diff as context from the Code Review panel.](../../../assets/terminal/attach-diff-hunk-as-context.png)
+<figcaption>Attaching a diff as context from the Code Review panel.</figcaption>
+</figure>
 
 This ensures responses are grounded in your latest edits, whether you're asking for feedback, explanations, or follow-up changes. For more details, see [Selection as Context](/agent-platform/local-agents/agent-context/selection-as-context/).
 
diff --git a/src/content/docs/code/overview.mdx b/src/content/docs/code/overview.mdx
index 04ca6ff..b0b1b09 100644
--- a/src/content/docs/code/overview.mdx
+++ b/src/content/docs/code/overview.mdx
@@ -66,7 +66,10 @@ Code responds to prompts related to code generation, editing, and analysis. Here
 
 Warp provides multiple entry points to begin coding with agents, whether you are starting a new project, opening an existing one, or cloning from GitHub. Each new tab shows a **zero state** that lets you choose how to proceed.
 
+<figure>
 ![Zero-state tab with 3 starting points for agentic coding in Warp.](../../../assets/terminal/code_mode.png)
+<figcaption>Zero-state tab with 3 starting points for agentic coding in Warp.</figcaption>
+</figure>
 
 #### 1. Starting a new project
 
diff --git a/src/content/docs/enterprise/team-management/admin-panel.mdx b/src/content/docs/enterprise/team-management/admin-panel.mdx
index 78a3449..be62cc2 100644
--- a/src/content/docs/enterprise/team-management/admin-panel.mdx
+++ b/src/content/docs/enterprise/team-management/admin-panel.mdx
@@ -260,7 +260,10 @@ To configure:
 2. Under **Enabled GitHub Orgs**, review the list of GitHub organizations where the Oz by Warp GitHub App is installed.
 3. Select which organizations your team should have access to.
 
+<figure>
 ![Enabled GitHub Orgs setting in the Admin Panel Platform section](../../../../assets/agent-platform/admin-panel-enabled-github-orgs.png)
+<figcaption>Enabled GitHub Orgs setting in the Admin Panel.</figcaption>
+</figure>
 
 The organizations and repository access shown here reflect the Oz by Warp GitHub App installation scope, which is configured in [GitHub settings](https://github.com/settings/installations). To change which repositories the app can access, edit the installation directly in GitHub.
 
diff --git a/src/content/docs/getting-started/keyboard-shortcuts.mdx b/src/content/docs/getting-started/keyboard-shortcuts.mdx
index 76affb5..62fc625 100644
--- a/src/content/docs/getting-started/keyboard-shortcuts.mdx
+++ b/src/content/docs/getting-started/keyboard-shortcuts.mdx
@@ -23,7 +23,10 @@ On macOS, [system keyboard shortcuts](https://support.apple.com/en-us/HT201236)
 Keybinds that conflict with others are highlighted with an orange border.
 :::
 
+<figure>
 ![keybinds that conflict with others are highlighted in orange](../../../assets/terminal/keybinds-conflict.png)
+<figcaption>Keybind Conflict Example</figcaption>
+</figure>
 
 ## All available shortcuts
 
diff --git a/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx b/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx
index 93d516b..7c2cb6a 100644
--- a/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx
+++ b/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx
@@ -27,7 +27,10 @@ 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>
 ![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
 
diff --git a/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx b/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx
index 3cb3020..283672a 100644
--- a/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx
+++ b/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx
@@ -46,11 +46,17 @@ Once the agent has finished the task, open Warp's [Code Review panel](/code/code
 * **Review changes button**: After an agent conversation, click **Review changes** at the bottom of the conversation
 * **Tab bar**: Click the Code Review button in the top-right corner of Warp
 
+<figure>
 ![Code Review button in the top-right corner of the Warp title bar showing file and line change counts](../../../../assets/guides/code-review-button.png)
+<figcaption>The Code Review button in the top-right corner shows the number of changed files and lines.</figcaption>
+</figure>
 
 The panel shows all uncommitted changes as a visual diff, grouped by file. Additions are highlighted in green with a `+` prefix, removals in red with a `-` prefix.
 
+<figure>
 ![Code Review panel showing file diffs between branches](../../../../assets/guides/code-review-panel-with-diffs.png)
+<figcaption>Code Review panel showing diffs with additions highlighted in green.</figcaption>
+</figure>
 
 ## 3. Review diffs by file
 
@@ -62,14 +68,20 @@ With the Code Review panel, you can review changes file-by-file:
 
 Focus on the areas where agents are most likely to make mistakes: imports, error handling, and anything that touches security or authentication.
 
+<figure>
 ![Code Review panel with file navigation sidebar showing changed files](../../../../assets/guides/code-review-file-sidebar.png)
+<figcaption>File sidebar lists all changed files with addition and deletion counts.</figcaption>
+</figure>
 
 ## 4. Leave inline comments on issues
 
 Click the "Add comment" button on any line or block of code and add a comment describing what needs to change. Warp anchors each comment to the exact file and line, so any agent understands precisely what to fix.
 You can add as many comments as you need before submitting — Warp batches them so the agent receives all your feedback at once instead of processing changes one at a time.
 
+<figure>
 ![Adding an inline comment on a diff line in the Code Review panel](../../../../assets/guides/code-review-inline-comment.png)
+<figcaption>Inline comments anchor to specific lines so the agent knows exactly what to fix.</figcaption>
+</figure>
 
 ## 5. Submit all comments to the agent
 
diff --git a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx
index ce808ae..d40f679 100644
--- a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx
+++ b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx
@@ -29,7 +29,10 @@ You can configure what information to display for each tab:
 * The working directory
 * A status indicator showing whether the agent is active, waiting for input, or idle
 
+<figure>
 ![Warp vertical tabs sidebar showing multiple terminal sessions with branch metadata](../../../../assets/terminal/vertical-tabs-multi-agent.png)
+<figcaption>Vertical tabs show which agent is running, the Git branch, and session status.</figcaption>
+</figure>
 
 ## 2. Launch agents in separate tabs
 
@@ -59,7 +62,10 @@ Refactor src/auth/ to use async/await instead of callbacks
 Write comprehensive tests for src/auth/ covering edge cases
 ```
 
+<figure>
 ![Multiple agent tabs in Warp's vertical sidebar showing session status, branch, and directory metadata](../../../../assets/terminal/multi-agents.png)
+<figcaption>Each vertical tab shows the agent name, working directory, branch, and diff stats at a glance.</figcaption>
+</figure>
 
 ## 3. Monitor agents with notifications
 
@@ -77,7 +83,10 @@ Notification setup varies by agent:
 Agent notifications are currently supported for Claude Code, Codex, and OpenCode. For setup details, see [Agent notifications](/agent-platform/capabilities/agent-notifications/). For a full breakdown of which features work with each agent, see the [third-party CLI agents feature matrix](/agent-platform/cli-agents/overview/).
 :::
 
+<figure>
 ![Warp notification popup showing an agent requesting permission to edit a file](../../../../assets/guides/tab-notification-indicator.png)
+<figcaption>Warp surfaces a notification when an agent needs approval, so you can jump directly to the tab that needs input.</figcaption>
+</figure>
 
 ## 4. Compare outputs from different agents
 
@@ -96,7 +105,10 @@ If you regularly work with the same multi-agent setup, save it as a tab config s
 1. Hover over the tab and click the three dots on the right-hand side.
 2. Click **Save as new config**.
 
+<figure>
 ![Creating a new tab config from the tab context menu in Warp](../../../../assets/terminal/save-new-tab-config.png)
+<figcaption>Save a tab config to recreate your multi-agent workspace with one click.</figcaption>
+</figure>
 
 Tab configs are TOML files that define the directory, startup commands, and layout for a tab. For example, you might create a config that:
 
diff --git a/src/content/docs/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents.mdx
index 73eac82..672ea80 100644
--- a/src/content/docs/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents.mdx
+++ b/src/content/docs/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents.mdx
@@ -21,7 +21,10 @@ Voice transcription is available in Warp's agent input. To use it:
 
 1. Click the **microphone icon** in the input area, or use the voice input keyboard shortcut.
 
+<figure>
 ![Warp input area showing the microphone icon for voice transcription](../../../../assets/guides/voice-input-microphone.png)
+<figcaption>The microphone icon appears in the input area for voice transcription.</figcaption>
+</figure>
 
 2. Speak your prompt naturally. Warp transcribes your speech and places the text in the input field.
 3. Review the transcription, edit if needed, then submit your prompt.
@@ -56,7 +59,10 @@ Paste (`⌘+V`) or drag images directly into the input area to give the agent vi
 * **Error messages** — Screenshot a stack trace instead of copying and reformatting it.
 * **Visual diffs** — Show the agent what the UI looks like now vs. what it should look like.
 
+<figure>
 ![Image attached as context in the Warp input area alongside a text prompt](../../../../assets/guides/image-as-context.png)
+<figcaption>Paste or drag images into the input to give the agent visual context.</figcaption>
+</figure>
 
 ## 4. Combine voice and images for design-to-code workflows
 
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index 91e6eb9..8c1b61b 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -10,7 +10,10 @@ import VideoEmbed from '@components/VideoEmbed.astro';
 
 Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Development Environment**, a modern terminal combined with powerful agents that help you build, test, deploy, and debug code. Warp's AI is powered by **Oz**, the orchestration platform for cloud agents.
 
+<figure>
 ![Warp, the Agentic Development Environment: Warp (a modern terminal built for coding with agents) and Oz (the orchestration platform for cloud agents)](../../assets/terminal/warp-oz-welcome.png)
+<figcaption>Warp combines a modern terminal with Oz, the orchestration platform for cloud agents</figcaption>
+</figure>
 
 ---
 
diff --git a/src/content/docs/knowledge-and-collaboration/admin-panel.mdx b/src/content/docs/knowledge-and-collaboration/admin-panel.mdx
index d03f3fa..c28d504 100644
--- a/src/content/docs/knowledge-and-collaboration/admin-panel.mdx
+++ b/src/content/docs/knowledge-and-collaboration/admin-panel.mdx
@@ -25,7 +25,10 @@ Admin Panel access is restricted to team administrators. Right now, only the cre
 
 Team administrators can access the Admin Panel directly at https://app.warp.dev/admin/
 
+<figure>
 ![Admin Panel main interface with sections for AI, privacy, billing, code, and sharing settings](../../../assets/terminal/admin-panel-overview.png)
+<figcaption>Admin Panel main interface with sections for AI, privacy, billing, code, and sharing settings</figcaption>
+</figure>
 
 ## How settings enforcement works
 
diff --git a/src/content/docs/knowledge-and-collaboration/teams.mdx b/src/content/docs/knowledge-and-collaboration/teams.mdx
index 759da1a..1d6fba9 100644
--- a/src/content/docs/knowledge-and-collaboration/teams.mdx
+++ b/src/content/docs/knowledge-and-collaboration/teams.mdx
@@ -42,7 +42,10 @@ If you’re on a paid plan, upgrading will automatically include all team member
 For more details on how team member billing works, please see our [billing FAQs](/support-and-community/plans-and-billing/pricing-faqs/#what-counts-as-a-team-member-and-how-does-billing-work-for-members).
 :::
 
+<figure>
 ![Teams settings panel](../../../assets/terminal/teams-invite-demo.png)
+<figcaption>Teams settings panel</figcaption>
+</figure>
 
 When you share this link with your teammates directly (we suggest using a secure channel like Slack or email), they will be able to join your team in Warp.
 
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
index 149035c..5271797 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
@@ -28,7 +28,10 @@ All objects stored in Warp Drive sync immediately as they’re updated, so you a
   </TabItem>
 </Tabs>
 
+<figure>
 ![Warp Drive icon on top left corner of Warp](../../../../assets/terminal/Open_Warp_Drive.png)
+<figcaption>Warp Drive Icon</figcaption>
+</figure>
 
 ## Workspaces in Warp Drive
 
@@ -51,7 +54,10 @@ If you are a member of a team using Warp Drive, your team’s workspace will als
 
 In offline mode, some files will be read-only. You can still create and edit files while offline in your personal space. They will only be saved locally and will not be synced. They cannot be moved into a team or deleted until you are back online.
 
+<figure>
 ![Warp Drive offline mode](../../../../assets/terminal/warp_drive_offline.png)
+<figcaption>Warp Drive offline mode</figcaption>
+</figure>
 
 ## Navigating Warp Drive with your keyboard
 
@@ -89,7 +95,10 @@ You can take these keyboard actions within Warp Drive:
   </TabItem>
 </Tabs>
 
+<figure>
 ![Warp Drive navigation states](../../../../assets/terminal/warp_drive_nav1.png)
+<figcaption>Warp Drive navigation states</figcaption>
+</figure>
 
 To switch between panels using your keyboard, you can use the “Switch Focus to Left Panel” and “Switch Focus to Right Panel” commands in the [Command Palette](/terminal/command-palette/).
 
@@ -108,7 +117,10 @@ Every object in Warp Drive can be exported to or imported from a file. When impo
 
 To import a local file or directory, `RIGHT-CLICK` on a folder or click **+** on a workspace and choose "Import." If importing a directory, supported files in the directory and its sub-directories will be imported into a matching folder structure.
 
+<figure>
 ![Import modal](../../../../assets/terminal/notebook-import-modal.png)
+<figcaption>Import modal</figcaption>
+</figure>
 
 ### Exporting files from Warp Drive
 
@@ -130,17 +142,26 @@ To share a Drive object, navigate to the object's overflow menu, and choose "Cop
 To access an object, link-followers must have permission to open it through one of the sharing methods above. If they do not have permission, they can automatically request access from the object owner or team admin.
 :::
 
+<figure>
 ![Copy link Menu Item](../../../../assets/terminal/wd-copy-link-menu.png)
+<figcaption>Copy link Menu Item</figcaption>
+</figure>
 
 ### Managing permissions
 
 To manage a Drive object's permissions, navigate to its overflow menu and choose "Share". If the object is open, you can also use the [Command Palette](/terminal/command-palette/#how-to-access-it) and search for "Share pane", or click the share button in the pane header:
 
+<figure>
 ![The pane header for a notebook, with the share button circled](../../../../assets/terminal/wd-share-button.png)
+<figcaption>Pane header share button</figcaption>
+</figure>
 
 This opens a dialog that lists the current sharing settings and allows you to change them:
 
+<figure>
 ![A sharing dialog showing that anyone with the link can view, the owner has full access, and another user can edit.](../../../../assets/terminal/wd-share-dialog.png)
+<figcaption>Warp Drive sharing dialog</figcaption>
+</figure>
 
 In this dialog, you can:
 
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
index e9fc91d..41b5ad4 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
@@ -39,7 +39,10 @@ Any of these entry points will open the notebook editor where you can:
 Note: The notebook will not be saved until either title or body text is added.
 :::
 
+<figure>
 ![Editing a Notebook](/assets/terminal/notebooks_editor.gif)
+<figcaption>Editing a Notebook</figcaption>
+</figure>
 
 ### Working with Notebooks
 
@@ -51,7 +54,10 @@ Notebook elements (text, code, list items) can be added in several ways:
 * Typing /, which will open up a selection menu of supported elements.
 * Pressing the + icon which appears when hovering over a line and selecting from the menu of supported elements.
 
+<figure>
 ![Markdown element types](../../../../assets/terminal/markdown-element-types.png)
+<figcaption>Markdown element types</figcaption>
+</figure>
 
 #### Styling existing elements
 
@@ -72,7 +78,10 @@ Command and code blocks have several unique properties such as syntax highlighti
 
 Once you’ve inserted your code block you can select the language at the bottom of the block from numerous options which will apply the appropriate syntax highlighting if available (or default to Code if your language is not found). All code and command blocks will apply syntax highlighting and provide a quick copy button for easy access.
 
+<figure>
 ![Example code block](../../../../assets/terminal/notebook-code-block.png)
+<figcaption>Example code block</figcaption>
+</figure>
 
 #### Special properties of command blocks
 
@@ -99,13 +108,19 @@ Developers can execute shell command blocks by:
 
 The command text will be inserted into the developer’s active terminal session, or a new session if none are active.
 
+<figure>
 ![Run option for command block](../../../../assets/terminal/notebook-cmd-block-run.png)
+<figcaption>Run option for command block</figcaption>
+</figure>
 
 #### Adding arguments to Command Blocks
 
 Command blocks accept parameters in the same format as [Workflows](/knowledge-and-collaboration/warp-drive/workflows/). To add an argument to your command block, use `{{double_curly_brackets}}` to specify your argument term.
 
+<figure>
 ![Command block with parameters](../../../../assets/terminal/notebook-cmd-with-params.png)
+<figcaption>Command block with parameters</figcaption>
+</figure>
 
 #### Navigating command blocks with the keyboard
 
@@ -136,7 +151,10 @@ Command Blocks also support keyboard navigation. There are two ways to enter the
 
 If you have existing [Workflows](/knowledge-and-collaboration/warp-drive/workflows/) that you’d like to insert into your notebook rather than duplicating their content, you can select Embedded Workflow from the new element menu and select from the available Workflows. Once embedded in a notebook, the workflow will be executable like a regular command block. To edit the content of the embedded workflow, you will need to edit the source workflow which can be found by searching for the title in the [Command Palette](/terminal/command-palette/).
 
+<figure>
 ![Embedding an existing workflow in a notebook.](../../../../assets/terminal/embedding-a-workflow.png)
+<figcaption>Embedding an existing workflow in a notebook.</figcaption>
+</figure>
 
 ### Working with Notebooks in a team
 
@@ -146,7 +164,10 @@ If the notebook is shared with a team, all team members will have access to edit
 Note that only one editor is allowed at a given time. Opening the notebook while there is an active editor will open the notebook in Viewing mode. Your mode (view vs edit) can be toggled above the notebook’s title.
 :::
 
+<figure>
 ![View mode example](../../../../assets/terminal/notebook-view-mode.png)
+<figcaption>View mode example</figcaption>
+</figure>
 
 ### Import and export notebooks in Warp Drive
 
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx
index 8be413d..a66f7a8 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx
@@ -13,7 +13,10 @@ A prompt is a parameterized natural language query you can name and save in Warp
 
 Prompts are searchable and easily accessed from the [Command Palette](/terminal/command-palette/) so you can find and execute them without switching context. They allow you to save and reuse specific and complex AI workflows, making it easier to repeat multi-step tasks with Agent Mode.
 
+<figure>
 ![View of a Prompt in Warp Drive showing the command view interface](../../../../assets/terminal/prompts-command-view.png)
+<figcaption>Command view of a Prompt in Warp Drive</figcaption>
+</figure>
 
 ### Demo: Trigger reusable actions with saved prompts
 
@@ -32,7 +35,10 @@ You can create a new prompt from Warp Drive by clicking the + button and selecti
 * Add a meaningful description that will be indexed for search (optional)
 * Add arguments, descriptions for arguments, and default values (optional)
 
+<figure>
 ![View of the Prompt editor interface showing the edit form with fields for name, query, description, and arguments](../../../../assets/terminal/prompts-edit-view.png)
+<figcaption>Edit view of a Prompt in Warp Drive</figcaption>
+</figure>
 
 Once a prompt has been created, you can edit it at any time, as long as you have access to an internet connection.
 
@@ -67,9 +73,15 @@ You can execute a prompt in several ways:
 * From the [Command Palette](/terminal/command-palette/) or [Command Search](/terminal/entry/command-search/), search for a prompt by name or type "prompts:" to see all available prompts and your prompt history
 * When a prompt is selected, you can use `SHIFT-TAB` to cycle through the arguments.
 
+<figure>
 ![Command Palette interface showing a search for Prompts with results displayed](../../../../assets/terminal/prompts-command-palette.png)
+<figcaption>Search for Prompts in the Command Palette with CMD + P</figcaption>
+</figure>
 
+<figure>
 ![Command Search interface showing a search for Prompts with results displayed](../../../../assets/terminal/prompts-command-search.png)
+<figcaption>Search for Prompts in Command Search with CTRL + R</figcaption>
+</figure>
 
 These options will paste the prompt into your active terminal input. Prompt names and any relevant descriptions and arguments will be displayed in a dialog, so you can understand how to use the prompt.
 
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx
index a4cc707..f29192c 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx
@@ -9,7 +9,10 @@ description: >-
 
 Warp Drive on the Web lets you view and edit your Warp Drive objects and shared sessions directly in the browser, on any device.
 
+<figure>
 ![A web-based rendering of a Team Workflow](../../../../assets/terminal/wd-web-team-workflow.png)
+<figcaption>A web-based rendering of a Team Workflow</figcaption>
+</figure>
 
 ## How to access Warp on the web
 
@@ -39,7 +42,10 @@ If you would like to use Warp locally and do not have it installed, please visit
 
 2.  This preference can be changed at any point in **Settings** > **Features** > **General** > **Open links in desktop app** Note that this setting is only available while on the web-based version of Warp.
 
+    <figure>
     ![Setting managing how to open links](../../../../assets/terminal/wd-open-links-preference.png)
+    <figcaption>Setting managing how to open links</figcaption>
+    </figure>
 3. You can always switch between web and desktop views on a case-by-case basis.
    1.  To switch from a web-view to Desktop for a given object, open the _overflow menu > Open link on Desktop._
 
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
index b0a5fd2..f633e9f 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
@@ -29,7 +29,10 @@ Any of these entry points will open the workflow editor where you can:
 * Add a meaningful description that will be indexed for search (optional)
 * Add arguments, descriptions for arguments, and default values (optional)
 
+<figure>
 ![Workflows save and edit modal](../../../../assets/terminal/edit-workflow-pane.png)
+<figcaption>Workflows save / edit pane</figcaption>
+</figure>
 
 <VideoEmbed url="https://www.youtube.com/watch?v=8UmreUTTrkg&start=9s&end=198s" title="Save Workflow Demo" />
 
@@ -71,7 +74,10 @@ Workflow aliases are not compatible with [YAML Workflows](/terminal/entry/yaml-w
 
 Once a workflow has been created, you can edit it at any time, as long as you have access to an internet connection.
 
+<figure>
 ![Edit workflow menu](../../../../assets/terminal/Edit_Workflow.png)
+<figcaption>Edit workflow menu</figcaption>
+</figure>
 
 #### AI Autofill
 
@@ -103,11 +109,17 @@ When you create two or more arguments with the same name, Warp automatically sel
 Also, tailor your Command Search experience by toggling off "Show Global Workflows" in **Settings** > **Features**. When disabled, your search will exclusively encompass YAML and Warp Drive Workflows.
 :::
 
+<figure>
 ![Search for any workflow in the Command Palette with CMD + P](../../../../assets/terminal/search-workflow-command-palette.png)
+<figcaption>Search for any workflow in the Command Palette with CMD + P</figcaption>
+</figure>
 
 These options will paste the workflow into your active terminal input. Workflow names and any relevant descriptions and arguments will be displayed in a dialog, so you can understand how to use the workflow.
 
+<figure>
 ![Execute a Workflow](../../../../assets/terminal/execute-a-workflow.png)
+<figcaption>Execute a Workflow</figcaption>
+</figure>
 
 You make any adjustments you need to the arguments (or the command itself) before running the command in your input editor.
 
diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx
index 4b8b091..9be27f2 100644
--- a/src/content/docs/reference/cli/api-keys.mdx
+++ b/src/content/docs/reference/cli/api-keys.mdx
@@ -34,7 +34,10 @@ Team keys without GitHub App authorization are the right fit for automated workf
 6. Click **Create key**.
 7. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.**
 
+<figure>
 ![API key management interface in Warp settings](../../../../assets/reference/api-key-management.png)
+<figcaption>API key management interface in Warp settings</figcaption>
+</figure>
 
 ## Personal vs team API keys
 
diff --git a/src/content/docs/reference/cli/mcp-servers.mdx b/src/content/docs/reference/cli/mcp-servers.mdx
index c8e5a19..88b7650 100644
--- a/src/content/docs/reference/cli/mcp-servers.mdx
+++ b/src/content/docs/reference/cli/mcp-servers.mdx
@@ -42,7 +42,10 @@ $ oz mcp list
 
   Alternatively, copy the UUID from Warp in **Settings** > **Agents** > **MCP servers**.
 
+<figure>
 ![MCP servers page, showing a server with its UUID](../../../../assets/reference/mcp-server-id.png)
+<figcaption>MCP servers page, showing a server with its UUID</figcaption>
+</figure>
 
 2. Pass the UUID to `--mcp`:
 
diff --git a/src/content/docs/support-and-community/plans-and-billing/credits.mdx b/src/content/docs/support-and-community/plans-and-billing/credits.mdx
index 86e784f..47db635 100644
--- a/src/content/docs/support-and-community/plans-and-billing/credits.mdx
+++ b/src/content/docs/support-and-community/plans-and-billing/credits.mdx
@@ -24,7 +24,10 @@ Since there's no exact formula for predicting usage, we recommend building an in
 
 In an Agent conversation, a **turn** represents a single exchange (a response from the LLM). To see how many credits a turn consumed, hover over the **credit count chip** at the bottom of the Agent's response:
 
+<figure>
 ![The conversation usage footer shows how many credits a conversation has consumed, and breaks down the usage by credits, tool calls, context window, files changed, diffs applied, and more.](../../../../assets/support-and-community/inline-credit-usage-footer.png)
+<figcaption>The conversation usage footer shows how many credits a conversation has consumed, and breaks down the usage by credits, tool calls, context window, files changed, diffs applied, and more.</figcaption>
+</figure>
 
 :::note
 You can view your total credit usage, along with other billing details, in **Settings** > **Billing and usage**.
diff --git a/src/content/docs/support-and-community/plans-and-billing/overages-legacy.mdx b/src/content/docs/support-and-community/plans-and-billing/overages-legacy.mdx
index b3ebc2f..eb3484e 100644
--- a/src/content/docs/support-and-community/plans-and-billing/overages-legacy.mdx
+++ b/src/content/docs/support-and-community/plans-and-billing/overages-legacy.mdx
@@ -9,7 +9,10 @@ Warp offers usage-based pricing for Subscribers, allowing continued access to pr
 
 You can manage usage-based pricing directly in Warp under **Settings** > **Billing and usage**.
 
+<figure>
 ![Billing and usage tab in settings, where admins can manage premium model usage overages](../../../../assets/support-and-community/overages-settings.png)
+<figcaption>Billing and usage tab in settings, where admins can manage premium model usage overages</figcaption>
+</figure>
 
 ### Enabling overages
 
diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx
index 0dcd53b..803a5b9 100644
--- a/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx
+++ b/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx
@@ -215,13 +215,19 @@ The following non-exhaustive list of plugins, prompts, or tools can cause potent
     On macOS, you may be [denied permission to SSH](https://github.com/warpdotdev/Warp/issues/5550) from Warp into other devices in your local network and see an error like: `ssh: connect to host <host_name> port 22: Undefined error: 0`.\
     To resolve this issue, go to  > **System Settings** > **Privacy & Security** > **Local Network** and add Warp.
 
+    <figure>
     ![macOS SSH permission error](../../../../assets/support-and-community/mac-ssh-permission.png)
+    <figcaption>macOS SSH permission error</figcaption>
+    </figure>
 
     **Unexpected loss of permission on macOS**
 
     On macOS, you may see an `Operation not permitted` error when trying to run commands in directories that have already been granted macOS permissions (Documents, Downloads, Desktop, etc). The best workaround at this time is to [apply any pending updates](/support-and-community/troubleshooting-and-support/updating-warp/) so that the new Warp binary has the correct permissions. We are tracking this issue [here](https://github.com/warpdotdev/Warp/issues/3009).
 
+    <figure>
     ![Permission error on macOS](../../../../assets/support-and-community/permission-error-macos.png)
+    <figcaption>Permission error on macOS</figcaption>
+    </figure>
 
     **Auto-Update error on macOS**
 
diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx
index c34186c..cdf3b74 100644
--- a/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx
+++ b/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx
@@ -224,7 +224,10 @@ Collect a sample using the steps for your platform and attach it to a new [GitHu
     1. Reproduce the high CPU usage or unresponsiveness in Warp.
     2. While the issue is occurring, open **Activity Monitor**, select the **Warp** process, and click **Sample Process**.
 
+    <figure>
     ![Sampling the Warp process in Activity Monitor](../../../../assets/support-and-community/activity-monitor-sample-process.png)
+    <figcaption>Sample Process in Activity Monitor</figcaption>
+    </figure>
 
     3. Save the resulting sample and attach it to your GitHub issue.
   </TabItem>
diff --git a/src/content/docs/terminal/appearance/app-icons.mdx b/src/content/docs/terminal/appearance/app-icons.mdx
index 6c6b045..c554989 100644
--- a/src/content/docs/terminal/appearance/app-icons.mdx
+++ b/src/content/docs/terminal/appearance/app-icons.mdx
@@ -32,7 +32,10 @@ App icons are only available for Warp on macOS. The feature doesn't support cust
 * Navigate to **Settings** > **Appearance** > **Icon** > **Customize your app icon**
 * Select the desired dock icon from the drop down menu
 
+<figure>
 ![Icon customization drop-down menu](../../../../assets/terminal/custom-dock-icon-dropdown.png)
+<figcaption>Icon customization drop-down menu</figcaption>
+</figure>
 
 ## Dock icons
 
diff --git a/src/content/docs/terminal/appearance/prompt.mdx b/src/content/docs/terminal/appearance/prompt.mdx
index 7ca10b1..7cfaadd 100644
--- a/src/content/docs/terminal/appearance/prompt.mdx
+++ b/src/content/docs/terminal/appearance/prompt.mdx
@@ -30,7 +30,10 @@ To customize which context chips your Warp prompt displays:
 
 1. Right-click the prompt area and select **Edit prompt**.
 
+<figure>
 ![Right-click context menu showing the Edit prompt option](../../../../assets/terminal/edit-prompt-modal.png)
+<figcaption>Right-click the prompt area to access Edit prompt</figcaption>
+</figure>
 
 2. Select **Warp Prompt**.
 3. Drag and drop context chips to configure which pieces of information your prompt displays.
@@ -180,7 +183,10 @@ When installing the Powerlevel10k (P10k) prompt, we recommend you use the [Meslo
 \
 P10K may display the arrow dividers as grey instead of color. The color for those chars is rendered grey due to Warp's minimum contrast setting. To [workaround](https://github.com/warpdotdev/Warp/issues/2851#issuecomment-1605005256) this issue, go to **Settings** > **Appearance** > **Text** > **Enforce minimum contrast** and set it to "Never".
 
+<figure>
 ![Example of the grey dividers in p10k](../../../../assets/terminal/p10k-grey-arrow-prompt.png)
+<figcaption>Example of the grey dividers in p10k</figcaption>
+</figure>
 
 Warp does support [p10k](https://github.com/romkatv/powerlevel10k#installation) version 1.19.0 and above. Ensure you have the latest version installed and restart Warp after the installation/update of p10k. Then enable the custom prompt as stated [above](/terminal/appearance/prompt/#choosing-your-prompt-type) and it should work.
 
diff --git a/src/content/docs/terminal/blocks/sticky-command-header.mdx b/src/content/docs/terminal/blocks/sticky-command-header.mdx
index ff6e187..f8d34cc 100644
--- a/src/content/docs/terminal/blocks/sticky-command-header.mdx
+++ b/src/content/docs/terminal/blocks/sticky-command-header.mdx
@@ -44,4 +44,7 @@ For long-running commands that take up the full screen, the sticky header only s
 
 <VideoEmbed url="https://www.loom.com/share/a86967c057e44ab4bee4860ba80538b9?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" title="Sticky Command Header Demo" />
 
+<figure>
 ![Toggle active header and Jump to bottom of block demo](/assets/terminal/sticky-header-toggle-active-demo.gif)
+<figcaption>Toggle active header and Jump to bottom of block demo</figcaption>
+</figure>
diff --git a/src/content/docs/terminal/command-palette.mdx b/src/content/docs/terminal/command-palette.mdx
index 786bb51..6ac78c6 100644
--- a/src/content/docs/terminal/command-palette.mdx
+++ b/src/content/docs/terminal/command-palette.mdx
@@ -7,7 +7,10 @@ description: >-
 import { Tabs, TabItem } from '@astrojs/starlight/components';
 import VideoEmbed from '@components/VideoEmbed.astro';
 
+<figure>
 ![Command Palette Panel](../../../assets/terminal/command-palette-panel.png)
+<figcaption>Command Palette Panel</figcaption>
+</figure>
 
 ## How to access it
 
diff --git a/src/content/docs/terminal/editor/index.mdx b/src/content/docs/terminal/editor/index.mdx
index 281cb7c..5bb567f 100644
--- a/src/content/docs/terminal/editor/index.mdx
+++ b/src/content/docs/terminal/editor/index.mdx
@@ -45,4 +45,7 @@ Warp can automatically complete quotes, brackets, and parentheses like you're us
 
 <VideoEmbed url="https://loom.com/share/1517049fefc34227bf1abaf19cc7e6ea?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" title="Text Editor Input Demo" />
 
+<figure>
 ![soft wrapping text in Warp input editor](../../../../assets/terminal/soft-wrapping.png)
+<figcaption>Soft Wrapping Demo</figcaption>
+</figure>
diff --git a/src/content/docs/terminal/entry/command-history.mdx b/src/content/docs/terminal/entry/command-history.mdx
index 291bab4..212a333 100644
--- a/src/content/docs/terminal/entry/command-history.mdx
+++ b/src/content/docs/terminal/entry/command-history.mdx
@@ -13,7 +13,10 @@ While running, Warp isolates the history of each shell session e.g. if you have
 
 Command History also provides rich information like exit code, directory, thread, time to finish running, last run, etc.
 
+<figure>
 ![Command History rich information](../../../../assets/terminal/command-history-rich.png)
+<figcaption>Command History rich information</figcaption>
+</figure>
 
 ## How to access it
 
diff --git a/src/content/docs/terminal/input/classic-input.mdx b/src/content/docs/terminal/input/classic-input.mdx
index b47e8e5..a178302 100644
--- a/src/content/docs/terminal/input/classic-input.mdx
+++ b/src/content/docs/terminal/input/classic-input.mdx
@@ -52,7 +52,10 @@ This opens an agent conversation where you can write questions and tasks in an o
 
 When you are in Agent Mode, a ✨ sparkles icon will display in line with your terminal input.
 
+<figure>
 ![The sparkles on the command line indicate Agent Mode is active.](../../../../assets/terminal/undo_my_git_commit.png)
+<figcaption>The sparkles in the Classic input indicates that Agent Mode is active.</figcaption>
+</figure>
 
 ## Auto-detection for natural language and configurable settings
 
@@ -64,7 +67,10 @@ You can also turn autodetection off from **Settings** > **Agents** > **Warp Agen
 
 The first time you enter Agent Mode, you will be served a banner with the option to disable auto-detection for natural language on your command line:
 
+<figure>
 ![Warp displays an option to toggle natural language detection on / off](../../../../assets/terminal/banner_for_auto-detection_first_experience.png)
+<figcaption>Warp displays an option to toggle natural language detection on / off</figcaption>
+</figure>
 
 ## Input hints
 
@@ -110,11 +116,17 @@ You must explicitly agree and press `Enter` to run the requested command. When y
 
 If you do not wish to send the command or its output to AI, you can click Cancel or press `Ctrl+C` to exit Agent Mode and return to the traditional command line.
 
+<figure>
 ![Oz asks permission to run a command and read the output.](../../../../assets/terminal/warp-ai-permissions.png)
+<figcaption>Warp AI asks permission to run a command and read the output.</figcaption>
+</figure>
 
 Once a requested command is executed, you can click to expand the output and view command details.
 
+<figure>
 ![Viewing command details](../../../../assets/terminal/warp-ai-viewing-commands.png)
+<figcaption>Viewing command details</figcaption>
+</figure>
 
 If a requested command fails, Oz detects it. Agent Mode is self-correcting. It will request another command until it completes the task for you.
 
diff --git a/src/content/docs/terminal/input/universal-input.mdx b/src/content/docs/terminal/input/universal-input.mdx
index 25d7a8d..041ed67 100644
--- a/src/content/docs/terminal/input/universal-input.mdx
+++ b/src/content/docs/terminal/input/universal-input.mdx
@@ -15,7 +15,10 @@ import VideoEmbed from '@components/VideoEmbed.astro';
 
 The **Universal Input** was the main input interface for using Warp.
 
+<figure>
 ![The Universal Input with an Agent prompt and multiple contextual chips active.](../../../../assets/terminal/universal-input-header.png)
+<figcaption>The Universal Input with an Agent prompt and multiple contextual chips active.</figcaption>
+</figure>
 
 <VideoEmbed url="https://www.youtube.com/watch?v=4c05OEqzQIA" title="Using the Universal Input" />
 
@@ -40,7 +43,10 @@ Ask Warp's agent to build, debug, or run tasks in natural language. Warp uses le
 
 _Indicator:_ Agent icon is highlighted in the switcher.
 
+<figure>
 ![Universal Input locked in Agent Mode.](../../../../assets/terminal/agent-mode-locked-universal-input.png)
+<figcaption>Universal Input locked in Agent Mode.</figcaption>
+</figure>
 
 #### 2. Terminal Mode (shell commands)
 
@@ -48,7 +54,10 @@ Enter shell commands just like any terminal, with the benefit of Warp’s modern
 
 _Indicator_: Terminal icon highlighted in the switcher
 
+<figure>
 ![Universal Input locked in Terminal Mode.](../../../../assets/terminal/universal-input-terminal-mode.png)
+<figcaption>Universal Input locked in Terminal Mode.</figcaption>
+</figure>
 
 #### 3. Auto-detection Mode
 
@@ -56,7 +65,10 @@ Warp automatically detects whether your input is natural language or a shell com
 
 _Indicator_: Neither mode highlighted.
 
+<figure>
 ![Universal Input in an empty / zero state.](../../../../assets/terminal/zero-state-universal-input.png)
+<figcaption>Universal Input in an empty / zero state.</figcaption>
+</figure>
 
 When Warp detects an input type, the input switcher softly highlights the corresponding mode.
 
@@ -117,11 +129,17 @@ By default, auto-detection is enabled. This means Warp decides whether to treat
 
 When you're in Agent Mode, the **Agent icon** will be highlighted in the [Universal Input(/terminal/input/universal-input/)
 
+<figure>
 ![The Agent icon in the Universal input indicates that Agent Mode is active.](../../../../assets/terminal/using-agents-universal-input.png)
+<figcaption>The Agent icon in the Universal input indicates that Agent Mode is active.</figcaption>
+</figure>
 
 In Classic Input, you’ll also see a ✨ sparkles indicator inline.
 
+<figure>
 ![The sparkles on the command line indicate Agent Mode is active.](../../../../assets/terminal/undo_my_git_commit.png)
+<figcaption>The sparkles in the Classic input indicates that Agent Mode is active.</figcaption>
+</figure>
 
 By default, entering Agent Mode starts you in _Pair Mode_, where you can continue an ongoing conversation by asking follow-up questions or assigning tasks. From here, you can ask the agent to build, debug, fix, or even deploy code as needed.
 
@@ -177,13 +195,19 @@ When auto-detection is turned off, you’ll need to explicitly switch between Te
 
 The first time you enter Agent Mode, Warp will display a banner with the option to disable natural language detection for your command line:
 
+<figure>
 ![Warp displays an option to toggle natural language detection on / off](../../../../assets/terminal/banner_for_auto-detection_first_experience.png)
+<figcaption>Warp displays an option to toggle natural language detection on / off</figcaption>
+</figure>
 
 ---
 
 ## Contextual Input Chips
 
+<figure>
 ![Universal Input's contextual input chips, from left to right: conversation management, node version, active directory, Git and code diffs, and 2 attached images.](../../../../assets/terminal/universal-input.png)
+<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>
+</figure>
 
 The Universal Input includes **contextual chips** that provide inline information about your current environment. These chips surface relevant details such as directory paths, Git status, conversations, or runtime versions, making it easier to navigate, manage context, and take quick actions without leaving the input.
 
@@ -193,7 +217,10 @@ The conversation management chip shows your recent [Agent conversations](/agent-
 
 These chips appear in both Agent Mode and Terminal Mode, so you can continue a previous conversation without starting from scratch. For more details, see [Agent Conversations](/agent-platform/local-agents/interacting-with-agents/).
 
+<figure>
 ![The Conversation Management chip displays recent Agent conversations and lets you continue or reopen them directly from the input.](../../../../assets/terminal/conversation-management-chip-universal-input.png)
+<figcaption>The Conversation Management chip displays recent Agent conversations and lets you continue or reopen them directly from the input.</figcaption>
+</figure>
 
 These chips appear in both Agent Mode and Terminal Mode, helping you continue a previous conversation without starting from scratch. For more details, refer to [Agent Conversations](/agent-platform/local-agents/interacting-with-agents/).
 
@@ -201,7 +228,10 @@ These chips appear in both Agent Mode and Terminal Mode, helping you continue a
 
 The active directory chip displays your current working directory and enables simple file navigation. Clicking on a folder moves you into that folder, while clicking on a file opens it in [Warp’s native code editor](/code/code-editor/). This makes it possible to move around your workspace seamlessly from within the input.
 
+<figure>
 ![The Active Directory chip lets you browse directories and open files directly from the input.](../../../../assets/terminal/active-directory-chip.png)
+<figcaption>The Active Directory chip lets you browse directories and open files directly from the input.</figcaption>
+</figure>
 
 #### Git Status chip
 
@@ -209,19 +239,28 @@ When you're in a Git-tracked repository, the Git Status chip displays file- and
 
 The chip updates automatically as files are added, removed, or changed, giving you a real-time view of your repository state.
 
+<figure>
 ![The Git Status chip highlights repository changes and provides quick access to code review.](../../../../assets/terminal/git-branch-chip.png)
+<figcaption>The Git Status chip highlights repository changes and provides quick access to code review.</figcaption>
+</figure>
 
 #### File attachments chips
 
 The file attachments chip lets you attach images and other files directly to a prompt. You can upload up to five [images at a time (as Agent Context)](/agent-platform/local-agents/agent-context/images-as-context/) using the upload button in the toolbelt or by dragging and dropping files into the input. This makes it possible to add screenshots, diagrams, PDFs, or other references directly to your query, giving the Agent richer context.
 
+<figure>
 ![The File Attachments chip allows you to add images or files as context for your queries.](../../../../assets/terminal/images-as-context-chip.png)
+<figcaption>The File Attachments chip allows you to add images or files as context for your queries.</figcaption>
+</figure>
 
 **Node version chip**
 
 In repositories that include a `package.json`, a Node Version chip appears to show the detected Node.js version. This gives you visibility into your runtime environment without needing to run additional commands.
 
+<figure>
 ![The Node Version chip displays the Node.js version detected in your repository.](../../../../assets/terminal/node-version-chip.png)
+<figcaption>The Node Version chip displays the Node.js version detected in your repository.</figcaption>
+</figure>
 
 :::note
 At this time, contextual chips are not configurable, but they update automatically based on your workspace and repository state.
@@ -233,7 +272,10 @@ At this time, contextual chips are not configurable, but they update automatical
 
 The **Input Toolbelt** provides quick-access controls alongside the Universal Input. These tools allow you to attach context, run shortcuts, and configure Agent behavior without leaving the input field. Depending on the mode you are in, some features are automatically enabled or will place you into Agent Mode.
 
+<figure>
 ![The Input Toolbelt in Warp’s Universal Input, showing quick-access controls for context, slash commands, voice input, attachments, profiles, and model selection.](../../../../assets/terminal/input-toolbar.png)
+<figcaption>The Input Toolbelt in Warp’s Universal Input, showing quick-access controls for context, slash commands, voice input, attachments, profiles, and model selection.</figcaption>
+</figure>
 
 #### @ - Context
 
diff --git a/src/content/docs/terminal/integrations-and-plugins.mdx b/src/content/docs/terminal/integrations-and-plugins.mdx
index 341521a..4ffd573 100644
--- a/src/content/docs/terminal/integrations-and-plugins.mdx
+++ b/src/content/docs/terminal/integrations-and-plugins.mdx
@@ -20,7 +20,10 @@ Currently, the Docker extension is only available on macOS.
 
 Select a container from the list and specify a shell type. Note, that only `bash|zsh|fish` are supported shells for docker containers. Then, select a user (optional) and finally click “Open in Warp” to run commands within the Docker container.
 
+<figure>
 ![Warp's extension for Docker lists available containers](../../../assets/terminal/docker-extension.png)
+<figcaption>Warp's extension for Docker lists available containers</figcaption>
+</figure>
 
 ## Raycast
 
@@ -37,7 +40,10 @@ Warp + Raycast extension helps you open new windows, tabs, or Launch Configurati
 Within `Raycast Settings > Extensions > Apps` search for Warp and assign the alias "terminal" so that it will show up on a search.
 :::
 
+<figure>
 ![Raycast Terminal Tip](../../../assets/terminal/raycast-terminal-tip.png)
+<figcaption>Raycast Terminal Tip</figcaption>
+</figure>
 
 ## VSCode
 
diff --git a/src/content/docs/terminal/more-features/full-screen-apps.mdx b/src/content/docs/terminal/more-features/full-screen-apps.mdx
index b8479da..8c6123b 100644
--- a/src/content/docs/terminal/more-features/full-screen-apps.mdx
+++ b/src/content/docs/terminal/more-features/full-screen-apps.mdx
@@ -49,4 +49,7 @@ Warp allows you to scale your terminal by fractions of a cell width | height. Wh
 Some full-screen applications don't behave well when resizing. If you are experiencing rendering issues with full screen apps, try turning this setting off. This will ensure that full-screen apps don't need to resize when starting up.
 :::
 
+<figure>
 ![alt-screen padding setting](../../../../assets/terminal/padding-settings.png)
+<figcaption>Alt-screen padding setting</figcaption>
+</figure>
diff --git a/src/content/docs/terminal/more-features/markdown-viewer.mdx b/src/content/docs/terminal/more-features/markdown-viewer.mdx
index 60dfea8..b0c1209 100644
--- a/src/content/docs/terminal/more-features/markdown-viewer.mdx
+++ b/src/content/docs/terminal/more-features/markdown-viewer.mdx
@@ -24,7 +24,10 @@ Warp can be used for both editing and viewing rendered Markdown files in a [spli
   </TabItem>
 </Tabs>
 
+<figure>
 ![Clicking a Markdown file link in the output of ls to open it in Warp](/assets/terminal/open-markdown-viewer.gif)
+<figcaption>Opening a Markdown file in Warp using the link tooltip</figcaption>
+</figure>
 
 ### Markdown-viewing commands
 
@@ -44,7 +47,10 @@ From Finder, you can open a Markdown file in Warp from the “Open With” menu
 
 You can toggle between the Markdown editor and viewer via the pane overflow menu.
 
+<figure>
 ![Clicking a Markdown file link in the output of ls to open it in Warp](/assets/terminal/markdown-raw-rendered-toggle.gif)
+<figcaption>Toggling between editor and viewer</figcaption>
+</figure>
 
 ## Shell commands in Markdown files
 
diff --git a/src/content/docs/terminal/more-features/settings-sync.mdx b/src/content/docs/terminal/more-features/settings-sync.mdx
index 694df17..e0d5a0b 100644
--- a/src/content/docs/terminal/more-features/settings-sync.mdx
+++ b/src/content/docs/terminal/more-features/settings-sync.mdx
@@ -12,9 +12,15 @@ sidebar:
 * You can toggle Settings Sync within the **Settings** > **Account** pane
 * Through the [Command Palette](/terminal/command-palette/) by searching for “Settings Sync”
 
+<figure>
 ![Settings Sync in Account pane](../../../../assets/terminal/settings-sync-account.png)
+<figcaption>Settings Sync in Account pane</figcaption>
+</figure>
 
+<figure>
 ![Settings Sync in Command Palette](../../../../assets/terminal/settings-sync-palette.png)
+<figcaption>Settings Sync in Command Palette</figcaption>
+</figure>
 
 ## How settings sync works
 
@@ -41,4 +47,7 @@ Not all settings are synced, however. Notably, Warp does not sync:
 
 You can tell when a setting is not synced because it will have a special cloud strikethrough icon in the settings panel.
 
+<figure>
 ![Settings not synced](../../../../assets/terminal/settings-not-synced.png)
+<figcaption>Settings not synced</figcaption>
+</figure>
diff --git a/src/content/docs/terminal/more-features/text-selection.mdx b/src/content/docs/terminal/more-features/text-selection.mdx
index 34672dd..003a0d1 100644
--- a/src/content/docs/terminal/more-features/text-selection.mdx
+++ b/src/content/docs/terminal/more-features/text-selection.mdx
@@ -9,7 +9,10 @@ description: >-
 
 **Smart selection** goes beyond the typical double-click selection, which only highlights a single word. Instead, it uses semantic rules to treat common patterns (like URLs or file paths) as one unit, even when separated by punctuation or whitespace.
 
+<figure>
 ![Using smart selection to select a file path by double clicking.](../../../../assets/terminal/smart-selection.png)
+<figcaption>Using smart selection to select a file path by double clicking.</figcaption>
+</figure>
 
 Double-click on text in the input or blocklist. The following patterns are recognized:
 
@@ -25,7 +28,10 @@ You can toggle smart selection on the **Settings** > **Features** > **Terminal**
 
 **Rectangular selection** lets you highlight text in a clean vertical block (also called _column_ or _box_ selection). This is especially useful for copying command output, logs, or prefixed text without grabbing unwanted characters.
 
+<figure>
 ![Using rectangular selection to select by columns in the block output.](../../../../assets/terminal/rectangular-selection.png)
+<figcaption>Using rectangular selection to select by columns in the block output.</figcaption>
+</figure>
 
 Hold the modifier keys while dragging your mouse:
 
diff --git a/src/content/docs/terminal/windows/tab-configs.mdx b/src/content/docs/terminal/windows/tab-configs.mdx
index f44614c..fffb196 100644
--- a/src/content/docs/terminal/windows/tab-configs.mdx
+++ b/src/content/docs/terminal/windows/tab-configs.mdx
@@ -27,7 +27,10 @@ Each Tab Config is a `.toml` file stored in `~/.warp/tab_configs/`. Every file d
 
 You can also capture a tab's current state as a reusable Tab Config without writing TOML. Right-click any tab in the [vertical tabs](/terminal/windows/vertical-tabs/) panel or horizontal tab bar to open the context menu, then click **Save as new config**. Warp generates a `.toml` file from the tab's layout, commands, and directory and adds it to the `+` menu.
 
+<figure>
 ![Tab context menu in Warp's vertical tabs panel with Save as new config highlighted](../../../../assets/terminal/save-new-tab-config.png)
+<figcaption>Save a tab config to recreate your multi-agent workspace with one click.</figcaption>
+</figure>
 
 ## Managing Tab Configs
 
@@ -37,7 +40,10 @@ Saved Tab Configs appear in the `+` menu for quick access. When you hover a Tab
 * **Remove** — Remove the Tab Config from the `+` menu.
 * **Make default** — Assign the Tab Config as the default `Cmd T` action for new tabs.
 
+<figure>
 ![Warp's + menu open with a saved screenshots_tab_config entry highlighted, and a sidecar panel showing Make default, Edit config, and Remove action buttons](../../../../assets/terminal/saved-tab-config-menu.png)
+<figcaption>Saved Tab Configs appear in the + menu. Hover a config to reveal the sidecar panel with Make default, Edit config, and Remove actions.</figcaption>
+</figure>
 
 ## Using skills to manage Tab Configs
 
diff --git a/src/content/docs/terminal/windows/vertical-tabs.mdx b/src/content/docs/terminal/windows/vertical-tabs.mdx
index 0923dc6..b510493 100644
--- a/src/content/docs/terminal/windows/vertical-tabs.mdx
+++ b/src/content/docs/terminal/windows/vertical-tabs.mdx
@@ -41,7 +41,10 @@ To switch from horizontal tabs to the vertical tabs panel:
 
 The vertical tabs panel appears as a resizable sidebar on the left side of the window. The horizontal tab bar is hidden while vertical tabs are active.
 
+<figure>
 ![A Warp window with the vertical tabs sidebar on the left listing a Claude Code tab and a codex tab alongside the main terminal pane](../../../../assets/terminal/multi-agents.png)
+<figcaption>Each vertical tab shows the agent name, working directory, branch, and diff stats at a glance.</figcaption>
+</figure>
 
 :::note
 You can also toggle vertical tabs from the [Command Palette](/terminal/command-palette/) by searching for "vertical tab layout."
@@ -55,19 +58,28 @@ The vertical tabs panel supports two display densities that you can switch betwe
 
 Compact mode is the default. Each pane row displays an icon and title on one line, with an optional subtitle below it. The subtitle is configurable via the **Additional metadata** setting in the settings popup.
 
+<figure>
 ![Vertical tabs sidebar in compact mode with each pane row showing an icon, title, and a short subtitle below](../../../../assets/terminal/vertical-tabs-condensed.png)
+<figcaption>Compact mode keeps each pane row to a single line with a short subtitle for quick scanning.</figcaption>
+</figure>
 
 ### Expanded mode
 
 Expanded mode shows each pane row with a title, description (such as the working directory or file path), and metadata (Git branch, diff stats badge, and PR badge when available).
 
+<figure>
 ![Vertical tab rows in expanded mode showing titles, working directories, Git branches, diff stats, and agent status badges](../../../../assets/terminal/vertical-tabs-multi-agent.png)
+<figcaption>Vertical tabs show which agent is running, the Git branch, and session status.</figcaption>
+</figure>
 
 ### Switching view modes
 
 Click the settings icon (sliders) in the control bar at the top of the vertical tabs panel. In the popup, use the **Density** segmented control to switch between compact and expanded views. The change takes effect immediately.
 
+<figure>
 ![The vertical tabs settings popup anchored to the sliders icon, showing View as, Density, Pane title as, Additional metadata, and Show details on hover options](../../../../assets/terminal/vertical-tab-settings.png)
+<figcaption>The settings popup lets you switch Density, customize pane titles and metadata, and toggle the hover detail sidecar.</figcaption>
+</figure>
 
 ## Customizing vertical tabs
 
@@ -105,7 +117,10 @@ Agent pane icons display a small circular badge overlay in the bottom-right corn
 | **Cancelled** | Gray stop | The user cancelled the agent's last turn. |
 | **Blocked** | Yellow stop | The agent is waiting for user approval to proceed. |
 
+<figure>
 ![Vertical tabs sidebar with four tab rows showing different agent status badges: a yellow blocked square, a magenta in-progress moon on the Claude Code brand icon, and green completion checks](../../../../assets/terminal/agent-status-badges.png)
+<figcaption>Pane icons in the vertical tabs panel carry a status badge overlay reflecting each agent's current state.</figcaption>
+</figure>
 
 Third-party CLI agents (Claude Code, Codex, Gemini CLI, and others) display their brand icon and color inside the circular pane icon, with the same status badge overlay.
 
@@ -144,7 +159,10 @@ Renaming applies to tabs only. Individual panes can't be renamed at this time.
 
 Hover any pane row to open a floating detail card anchored to the right side of the panel. The sidecar shows full, un-clipped metadata (complete directory paths, full branch names, and the full conversation or command title) without changing which pane is focused.
 
+<figure>
 ![The vertical tabs panel with a Claude Code tab hovered, showing a floating detail card with the agent's In progress status, working directory, and session title](../../../../assets/terminal/tab-hover-detail-card.png)
+<figcaption>Hovering a pane row reveals a floating detail card with full metadata — without changing the focused pane.</figcaption>
+</figure>
 
 The sidecar stays open as you move the cursor from the row into the card. Move away from both the row and the sidecar to dismiss it. Disable this behavior with the **Show details on hover** toggle in the settings popup.
 
diff --git a/src/styles/custom.css b/src/styles/custom.css
index d0dbb61..e082cb4 100644
--- a/src/styles/custom.css
+++ b/src/styles/custom.css
@@ -271,6 +271,27 @@ body {
   margin-right: auto;
 }
 
+/* Figures — centered block with image and optional caption.
+   GitBook rendered `<figure><img>…<figcaption>` natively; these styles
+   restore that treatment in Astro Starlight. */
+.sl-markdown-content figure {
+  margin: 1.5em 0;
+  text-align: center;
+}
+
+.sl-markdown-content figure img {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.sl-markdown-content figcaption {
+  margin-top: 0.5rem;
+  font-size: var(--sl-text-sm);
+  color: var(--sl-color-gray-3);
+  line-height: 1.4;
+}
+
 /* Center and constrain main content — Scalar uses a tighter column */
 .main-pane .sl-container {
   max-width: 46rem;

From d1b50a0bfd8ea234cf7c46a2b3f5feed313da633 Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Thu, 7 May 2026 14:31:40 -1000
Subject: [PATCH 2/5] 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>
---
 scripts/apply-figcaptions.py   | 141 ---------------------------------
 scripts/migrate-figcaptions.py | 131 ------------------------------
 2 files changed, 272 deletions(-)
 delete mode 100644 scripts/apply-figcaptions.py
 delete mode 100644 scripts/migrate-figcaptions.py

diff --git a/scripts/apply-figcaptions.py b/scripts/apply-figcaptions.py
deleted file mode 100644
index 43d3f59..0000000
--- a/scripts/apply-figcaptions.py
+++ /dev/null
@@ -1,141 +0,0 @@
-#!/usr/bin/env python3
-"""
-Apply <figure>+<figcaption> wrappers to Astro MDX images that had captions
-in the GitBook source.
-
-Usage:
-    python3 scripts/apply-figcaptions.py          # dry run (preview changes)
-    python3 scripts/apply-figcaptions.py --apply   # write changes to disk
-
-Transforms:
-    ![alt text](path/to/image.png)
-  →
-    <figure>
-    ![alt text](path/to/image.png)
-    <figcaption>Caption text from GitBook</figcaption>
-    </figure>
-"""
-
-import os
-import re
-import sys
-from pathlib import Path
-from collections import defaultdict
-
-GITBOOK_ROOT = Path(os.path.expanduser("~/Documents/Warp/gitbook"))
-ASTRO_CONTENT = Path(os.path.expanduser("~/Documents/Warp/docs/src/content/docs"))
-
-FIGURE_RE = re.compile(
-    r'<figure>'
-    r'.*?<img\s+src="([^"]+)"[^>]*>'
-    r'.*?<figcaption>(?:<p>)?(.*?)(?:</p>)?</figcaption>'
-    r'.*?</figure>',
-    re.DOTALL
-)
-
-MD_IMAGE_RE = re.compile(r'^(\s*)(!\[[^\]]*\]\([^)]*?/([^/)"]+)\))\s*$')
-
-
-def extract_gitbook_captions():
-    """Extract all non-empty figcaptions from GitBook source."""
-    captions = {}
-    for md_file in GITBOOK_ROOT.rglob("*.md"):
-        rel = str(md_file.relative_to(GITBOOK_ROOT))
-        if rel.startswith(".") or "node_modules" in rel:
-            continue
-        try:
-            content = md_file.read_text(encoding="utf-8")
-        except Exception:
-            continue
-        for match in FIGURE_RE.finditer(content):
-            img_src = match.group(1)
-            caption = match.group(2).strip()
-            if not caption:
-                continue
-            caption = re.sub(r'<[^>]+>', '', caption).strip()
-            if not caption:
-                continue
-            basename = os.path.basename(img_src)
-            captions[basename] = caption
-    return captions
-
-
-def apply_figcaptions(captions, dry_run=True):
-    """Apply <figure>+<figcaption> wrappers to MDX files."""
-    total_applied = 0
-    files_modified = set()
-
-    for mdx_file in sorted(ASTRO_CONTENT.rglob("*.mdx")):
-        try:
-            content = mdx_file.read_text(encoding="utf-8")
-        except Exception:
-            continue
-
-        lines = content.splitlines(keepends=True)
-        new_lines = []
-        modified = False
-
-        i = 0
-        while i < len(lines):
-            line = lines[i]
-            match = MD_IMAGE_RE.match(line)
-
-            if match:
-                indent = match.group(1)
-                full_image = match.group(2)
-                img_basename = match.group(3)
-
-                if img_basename in captions:
-                    # Check if already wrapped in <figure>
-                    prev_line = new_lines[-1].strip() if new_lines else ""
-                    if "<figure>" in prev_line:
-                        new_lines.append(line)
-                        i += 1
-                        continue
-
-                    caption = captions[img_basename]
-                    new_lines.append(f"{indent}<figure>\n")
-                    new_lines.append(line)
-                    new_lines.append(f"{indent}<figcaption>{caption}</figcaption>\n")
-                    new_lines.append(f"{indent}</figure>\n")
-                    modified = True
-                    total_applied += 1
-                    i += 1
-                    continue
-
-            new_lines.append(line)
-            i += 1
-
-        if modified:
-            rel_file = str(mdx_file.relative_to(ASTRO_CONTENT))
-            files_modified.add(rel_file)
-            if dry_run:
-                print(f"  Would modify: {rel_file}")
-            else:
-                mdx_file.write_text("".join(new_lines), encoding="utf-8")
-                print(f"  Modified: {rel_file}")
-
-    return total_applied, files_modified
-
-
-def main():
-    dry_run = "--apply" not in sys.argv
-
-    if dry_run:
-        print("DRY RUN — pass --apply to write changes\n")
-
-    print("Extracting GitBook captions...")
-    captions = extract_gitbook_captions()
-    print(f"  Found {len(captions)} non-empty figcaptions\n")
-
-    print("Applying figcaptions to Astro MDX files...")
-    total, files = apply_figcaptions(captions, dry_run=dry_run)
-
-    print(f"\n{'Would apply' if dry_run else 'Applied'} {total} figcaptions across {len(files)} files")
-
-    if dry_run:
-        print("\nRun with --apply to write changes to disk.")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/migrate-figcaptions.py b/scripts/migrate-figcaptions.py
deleted file mode 100644
index 41f8e68..0000000
--- a/scripts/migrate-figcaptions.py
+++ /dev/null
@@ -1,131 +0,0 @@
-#!/usr/bin/env python3
-"""
-Extract non-empty figcaptions from GitBook source and generate a report
-of which Astro MDX images need <figure>+<figcaption> wrappers.
-
-Usage:
-    python3 scripts/migrate-figcaptions.py
-
-Output:
-    Prints a TSV report: astro_file, image_filename, caption_text
-    Also prints summary stats.
-
-The script matches GitBook figures to Astro images by image filename
-(basename), since the directory structure differs between repos.
-"""
-
-import os
-import re
-import sys
-from pathlib import Path
-from collections import defaultdict
-
-GITBOOK_ROOT = Path(os.path.expanduser("~/Documents/Warp/gitbook"))
-ASTRO_CONTENT = Path(os.path.expanduser("~/Documents/Warp/docs/src/content/docs"))
-
-# Pattern for GitBook's <figure><img ...><figcaption><p>text</p></figcaption></figure>
-FIGURE_RE = re.compile(
-    r'<figure>'
-    r'.*?<img\s+src="([^"]+)"[^>]*>'
-    r'.*?<figcaption>(?:<p>)?(.*?)(?:</p>)?</figcaption>'
-    r'.*?</figure>',
-    re.DOTALL
-)
-
-# Pattern for markdown images in Astro MDX: ![alt](path)
-MD_IMAGE_RE = re.compile(r'!\[([^\]]*)\]\(([^)]+)\)')
-
-
-def extract_gitbook_captions():
-    """Extract all non-empty figcaptions from GitBook source."""
-    captions = {}  # image_basename -> caption_text
-    
-    for md_file in GITBOOK_ROOT.rglob("*.md"):
-        # Skip non-content files
-        rel = str(md_file.relative_to(GITBOOK_ROOT))
-        if rel.startswith(".") or "node_modules" in rel:
-            continue
-        
-        try:
-            content = md_file.read_text(encoding="utf-8")
-        except Exception:
-            continue
-        
-        for match in FIGURE_RE.finditer(content):
-            img_src = match.group(1)
-            caption = match.group(2).strip()
-            
-            # Skip empty captions
-            if not caption:
-                continue
-            
-            # Strip any remaining HTML tags from caption
-            caption = re.sub(r'<[^>]+>', '', caption).strip()
-            if not caption:
-                continue
-            
-            # Use image basename as the key
-            basename = os.path.basename(img_src)
-            captions[basename] = caption
-    
-    return captions
-
-
-def find_astro_images():
-    """Find all markdown images in Astro MDX files."""
-    images = defaultdict(list)  # image_basename -> [(astro_file, line_num, full_line)]
-    
-    for mdx_file in ASTRO_CONTENT.rglob("*.mdx"):
-        try:
-            lines = mdx_file.read_text(encoding="utf-8").splitlines()
-        except Exception:
-            continue
-        
-        for i, line in enumerate(lines, 1):
-            for match in MD_IMAGE_RE.finditer(line):
-                img_path = match.group(2)
-                basename = os.path.basename(img_path)
-                rel_file = str(mdx_file.relative_to(ASTRO_CONTENT))
-                images[basename].append((rel_file, i, line.strip()))
-    
-    return images
-
-
-def main():
-    print("Scanning GitBook source for figcaptions...", file=sys.stderr)
-    captions = extract_gitbook_captions()
-    print(f"  Found {len(captions)} non-empty figcaptions", file=sys.stderr)
-    
-    print("Scanning Astro MDX files for images...", file=sys.stderr)
-    astro_images = find_astro_images()
-    print(f"  Found {len(astro_images)} unique image filenames", file=sys.stderr)
-    
-    # Match captions to Astro images
-    matched = 0
-    unmatched_captions = []
-    
-    print("\n# Matched figcaptions (astro_file\tline\timage\tcaption)")
-    print("# " + "=" * 80)
-    
-    for basename, caption in sorted(captions.items()):
-        if basename in astro_images:
-            for astro_file, line_num, _ in astro_images[basename]:
-                print(f"{astro_file}\t{line_num}\t{basename}\t{caption}")
-                matched += 1
-        else:
-            unmatched_captions.append((basename, caption))
-    
-    print(f"\n# Summary:", file=sys.stderr)
-    print(f"#   Matched: {matched} images in Astro have captions to restore", file=sys.stderr)
-    print(f"#   Unmatched: {len(unmatched_captions)} GitBook captions couldn't be matched to Astro images", file=sys.stderr)
-    
-    if unmatched_captions:
-        print(f"\n# Unmatched captions (image may have been renamed or removed):", file=sys.stderr)
-        for basename, caption in unmatched_captions[:20]:
-            print(f"#   {basename}: {caption[:60]}...", file=sys.stderr)
-        if len(unmatched_captions) > 20:
-            print(f"#   ... and {len(unmatched_captions) - 20} more", file=sys.stderr)
-
-
-if __name__ == "__main__":
-    main()

From c1156bd62feb3c776e6bc86b335774fddd59b6b0 Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Thu, 7 May 2026 14:41:45 -1000
Subject: [PATCH 3/5] 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>
---
 AGENTS.md             | 19 +++++++++++++++++++
 src/styles/custom.css |  6 +++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3b29230..98cf2b7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -177,6 +177,25 @@ 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.
+- **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](...)"
diff --git a/src/styles/custom.css b/src/styles/custom.css
index e082cb4..6d9bfda 100644
--- a/src/styles/custom.css
+++ b/src/styles/custom.css
@@ -273,7 +273,11 @@ body {
 
 /* Figures — centered block with image and optional caption.
    GitBook rendered `<figure><img>…<figcaption>` natively; these styles
-   restore that treatment in Astro Starlight. */
+   restore that treatment in Astro Starlight.
+
+   Caption editorial rules (see AGENTS.md § "Image caption guidelines"):
+   Orient the reader, don't instruct. Keep under ~20 words. No marketing
+   language. Don't repeat surrounding prose or list everything visible. */
 .sl-markdown-content figure {
   margin: 1.5em 0;
   text-align: center;

From a293dbb4a540eac980edb5eb30ea10ad1b9a7d3b Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Thu, 7 May 2026 14:45:57 -1000
Subject: [PATCH 4/5] 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>
---
 .../capabilities/agent-notifications.mdx      |  6 ++---
 .../agent-profiles-permissions.mdx            |  8 +++----
 .../capabilities/codebase-context.mdx         |  4 ++--
 .../docs/agent-platform/capabilities/mcp.mdx  |  8 +++----
 .../agent-platform/capabilities/planning.mdx  |  6 ++---
 .../agent-platform/capabilities/rules.mdx     |  6 ++---
 .../capabilities/slash-commands.mdx           |  8 +++----
 .../capabilities/task-lists.mdx               |  4 ++--
 .../agent-platform/cli-agents/overview.mdx    |  2 +-
 .../cli-agents/remote-control.mdx             |  2 +-
 .../agent-platform/cli-agents/rich-input.mdx  |  6 ++---
 .../cloud-agents/environments.mdx             |  2 +-
 .../cloud-agents/integrations/slack.mdx       |  2 +-
 .../cloud-agents/oz-web-app.mdx               | 12 +++++-----
 .../agent-context/blocks-as-context.mdx       |  2 +-
 .../agent-context/images-as-context.mdx       |  4 ++--
 .../agent-context/selection-as-context.mdx    |  2 +-
 .../agent-context/urls-as-context.mdx         |  2 +-
 .../agent-context/using-to-add-context.mdx    |  6 ++---
 .../local-agents/code-diffs.mdx               |  2 +-
 .../agent-platform/local-agents/generate.mdx  |  6 ++---
 .../interacting-with-agents/index.mdx         |  8 +++----
 .../terminal-and-agent-modes.mdx              |  2 +-
 .../interacting-with-agents/voice.mdx         |  4 ++--
 src/content/docs/code/overview.mdx            |  2 +-
 .../getting-started/keyboard-shortcuts.mdx    |  2 +-
 .../migrate-to-warp-from-iterm2.mdx           |  2 +-
 .../how-to-review-ai-generated-code.mdx       |  8 +++----
 .../how-to-run-multiple-ai-coding-agents.mdx  |  8 +++----
 ...ice-and-images-to-prompt-coding-agents.mdx |  2 +-
 src/content/docs/index.mdx                    |  2 +-
 .../admin-panel.mdx                           |  2 +-
 .../knowledge-and-collaboration/teams.mdx     |  2 +-
 .../warp-drive/index.mdx                      | 14 ++++++------
 .../warp-drive/notebooks.mdx                  | 12 +++++-----
 .../warp-drive/prompts.mdx                    |  8 +++----
 .../warp-drive/web.mdx                        |  4 ++--
 .../warp-drive/workflows.mdx                  |  8 +++----
 src/content/docs/reference/cli/api-keys.mdx   |  2 +-
 .../docs/reference/cli/mcp-servers.mdx        |  2 +-
 .../plans-and-billing/credits.mdx             |  2 +-
 .../plans-and-billing/overages-legacy.mdx     |  2 +-
 .../known-issues.mdx                          |  4 ++--
 .../sending-us-feedback.mdx                   |  2 +-
 .../docs/terminal/appearance/app-icons.mdx    |  2 +-
 .../docs/terminal/appearance/prompt.mdx       |  4 ++--
 .../terminal/blocks/sticky-command-header.mdx |  2 +-
 src/content/docs/terminal/command-palette.mdx |  2 +-
 src/content/docs/terminal/editor/index.mdx    |  2 +-
 .../docs/terminal/entry/command-history.mdx   |  2 +-
 .../docs/terminal/input/classic-input.mdx     |  8 +++----
 .../docs/terminal/input/universal-input.mdx   | 22 +++++++++----------
 .../terminal/integrations-and-plugins.mdx     |  4 ++--
 .../more-features/full-screen-apps.mdx        |  2 +-
 .../more-features/markdown-viewer.mdx         |  4 ++--
 .../terminal/more-features/settings-sync.mdx  |  6 ++---
 .../docs/terminal/windows/tab-configs.mdx     |  4 ++--
 .../docs/terminal/windows/vertical-tabs.mdx   | 12 +++++-----
 58 files changed, 140 insertions(+), 140 deletions(-)

diff --git a/src/content/docs/agent-platform/capabilities/agent-notifications.mdx b/src/content/docs/agent-platform/capabilities/agent-notifications.mdx
index fe5b342..503f08a 100644
--- a/src/content/docs/agent-platform/capabilities/agent-notifications.mdx
+++ b/src/content/docs/agent-platform/capabilities/agent-notifications.mdx
@@ -27,7 +27,7 @@ Up to two toasts are visible at a time. If additional notifications arrive, the
 
 <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>A toast notification in the corner of the Warp window signals that an agent task has completed. Click the toast to jump to the agent's session.</figcaption>
+<figcaption>Agent task completion notification.</figcaption>
 </figure>
 
 ### Notification mailbox
@@ -36,7 +36,7 @@ The notification mailbox is a sidebar panel that collects all agent notification
 
 <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>The notification mailbox collects all agent notifications in one place. Use the filter tabs to switch between All tabs and Unread.</figcaption>
+<figcaption>Agent notification mailbox.</figcaption>
 </figure>
 
 The mailbox includes:
@@ -91,7 +91,7 @@ For **third-party CLI agents**, each agent requires a one-time setup. The proces
 
 <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>Warp surfaces a one-click install chip in the agent utility bar when a supported CLI agent is running without the notification plugin installed.</figcaption>
+<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.
diff --git a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx b/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx
index cd7295b..c93c436 100644
--- a/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx
+++ b/src/content/docs/agent-platform/capabilities/agent-profiles-permissions.mdx
@@ -15,7 +15,7 @@ Agent Profiles let you configure how your Agent behaves in different situations.
 
 <figure>
 ![Agent Profiles in Settings: define how your Agent operates.](../../../../assets/agent-platform/agent-profiles.png)
-<figcaption>Agent Profiles in Settings: define how your Agent operates.</figcaption>
+<figcaption>Agent Profile settings.</figcaption>
 </figure>
 
 **In each Agent Profile, you can configure:**
@@ -26,7 +26,7 @@ Agent Profiles let you configure how your Agent behaves in different situations.
 
 <figure>
 ![Agent Profiles in Settings: editing a Profile.](../../../../assets/agent-platform/agent-profiles-settings.png)
-<figcaption>Agent Profiles in Settings: editing a Profile.</figcaption>
+<figcaption>Editing an Agent Profile.</figcaption>
 </figure>
 
 ## Agent Permissions
@@ -97,7 +97,7 @@ In this settings menu, you can configure which MCP servers the Agent is allowed
 
 <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>Customize how the Agent interacts with MCP servers by choosing between “Agent decides,” allowlist, or denylist settings.</figcaption>
+<figcaption>MCP server interaction settings in an Agent Profile.</figcaption>
 </figure>
 
 :::note
@@ -122,7 +122,7 @@ During an Agent interaction, you can give the Agent full autonomy for the curren
 
 <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>A button overlay in the lower-right corner lets you enable auto-approve or end the Agent interaction.</figcaption>
+<figcaption>Auto-approve and take-over controls.</figcaption>
 </figure>
 
 :::note
diff --git a/src/content/docs/agent-platform/capabilities/codebase-context.mdx b/src/content/docs/agent-platform/capabilities/codebase-context.mdx
index cf3935e..03b7b0f 100644
--- a/src/content/docs/agent-platform/capabilities/codebase-context.mdx
+++ b/src/content/docs/agent-platform/capabilities/codebase-context.mdx
@@ -49,7 +49,7 @@ Feature requests:
 
 <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 in Warp. Easily track sync status and manage which folders are indexed for AI-powered context and suggestions.</figcaption>
+<figcaption>Codebase indexing settings.</figcaption>
 </figure>
 
 **Codebase indexing intervals and triggers:**
@@ -84,7 +84,7 @@ When viewing indexed codebases in Warp under **Settings** > **Code** > **Indexin
 
 <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>View and manage the indexing status of your codebases in Warp. Easily see which projects are synced, in progress, or require attention.</figcaption>
+<figcaption>Codebase indexing status overview.</figcaption>
 </figure>
 
 ### When does codebase syncing happen?
diff --git a/src/content/docs/agent-platform/capabilities/mcp.mdx b/src/content/docs/agent-platform/capabilities/mcp.mdx
index 58c3d20..b8b8a06 100644
--- a/src/content/docs/agent-platform/capabilities/mcp.mdx
+++ b/src/content/docs/agent-platform/capabilities/mcp.mdx
@@ -28,7 +28,7 @@ This will show a list of all configured MCP servers, including which are current
 
 <figure>
 ![MCP servers page](../../../../assets/agent-platform/mcp-servers-list.png)
-<figcaption>MCP servers page</figcaption>
+<figcaption>MCP servers page.</figcaption>
 </figure>
 
 ### Adding an MCP Server
@@ -43,7 +43,7 @@ MCP server types you can add:
 
     <figure>
     ![Adding a CLI MCP Server (Command)](../../../../assets/agent-platform/mcp-servers-add-cli.png)
-    <figcaption>Adding a CLI MCP Server (Command)</figcaption>
+    <figcaption>Adding a CLI MCP Server (Command).</figcaption>
     </figure>
 
     :::note
@@ -64,7 +64,7 @@ MCP server types you can add:
 
     <figure>
     ![Adding an SSE MCP Server (URL)](../../../../assets/agent-platform/mcp-servers-add-sse.png)
-    <figcaption>Adding an SSE MCP Server (URL)</figcaption>
+    <figcaption>Adding an SSE MCP Server (URL).</figcaption>
     </figure>
 
     **Streamable HTTP or SSE Server (URL) MCP Configuration Properties**
@@ -172,7 +172,7 @@ MCP servers can be shared with your teammates by clicking the share icon. When s
 
 <figure>
 ![Sharing a MCP Server](../../../../assets/agent-platform/mcp-servers-share.png)
-<figcaption>Sharing a MCP Server</figcaption>
+<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.
diff --git a/src/content/docs/agent-platform/capabilities/planning.mdx b/src/content/docs/agent-platform/capabilities/planning.mdx
index efb513b..aa45917 100644
--- a/src/content/docs/agent-platform/capabilities/planning.mdx
+++ b/src/content/docs/agent-platform/capabilities/planning.mdx
@@ -20,7 +20,7 @@ You can generate a plan using the `/plan` [slash command](/agent-platform/capabi
 
 <figure>
 ![Prompting the agent to create a plan using the slash command.](../../../../assets/agent-platform/plan-slash-command.png)
-<figcaption>Prompting the agent to create a plan using the slash command.</figcaption>
+<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.
@@ -47,7 +47,7 @@ When you’re ready to start implementing, prompt the agent to run the plan. You
 
 <figure>
 ![Manually referencing the plan using @ to kickoff the plan.](../../../../assets/agent-platform/manually-trigger-plan.png)
-<figcaption>Manually referencing the plan using @ to kickoff the plan.</figcaption>
+<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.
@@ -56,7 +56,7 @@ If you revise the plan while the agent is running, you can notify it directly; t
 
 <figure>
 ![Option to pass new plan to agent if plan changes during runtime.](../../../../assets/agent-platform/update-agent-mid-plan.png)
-<figcaption>Option to pass new plan to agent if plan changes during runtime.</figcaption>
+<figcaption>Prompt to update the agent's plan during execution.</figcaption>
 </figure>
 
 ### Monitoring progress
diff --git a/src/content/docs/agent-platform/capabilities/rules.mdx b/src/content/docs/agent-platform/capabilities/rules.mdx
index 0439616..7b80182 100644
--- a/src/content/docs/agent-platform/capabilities/rules.mdx
+++ b/src/content/docs/agent-platform/capabilities/rules.mdx
@@ -89,7 +89,7 @@ This ensures the most specific, project-relevant rules take priority over broade
 
 <figure>
 ![Project Rules UI open in a Rules pane](../../../../assets/agent-platform/project-scoped-rules-pane.png)
-<figcaption>Project Rules UI open in a Rules pane</figcaption>
+<figcaption>Project Rules UI open in a Rules pane.</figcaption>
 </figure>
 
 ## How to create, edit, or delete Rules
@@ -120,12 +120,12 @@ When relevant, Agents automatically pull in applicable rules to guide their resp
 
 <figure>
 ![Context derived from memory](../../../../assets/agent-platform/context-derived-from-memory.png)
-<figcaption>Derived from rules</figcaption>
+<figcaption>Derived from rules.</figcaption>
 </figure>
 
 <figure>
 ![Context derived from memory](../../../../assets/agent-platform/context-references-memory.png)
-<figcaption>Rules as references</figcaption>
+<figcaption>Rules as references.</figcaption>
 </figure>
 
 ### Rules privacy
diff --git a/src/content/docs/agent-platform/capabilities/slash-commands.mdx b/src/content/docs/agent-platform/capabilities/slash-commands.mdx
index 0ee95b7..9eef9ef 100644
--- a/src/content/docs/agent-platform/capabilities/slash-commands.mdx
+++ b/src/content/docs/agent-platform/capabilities/slash-commands.mdx
@@ -9,7 +9,7 @@ When using Agent Mode or Auto-Detection Mode, typing `/` in the input field open
 
 <figure>
 ![Slash Commands menu](../../../../assets/agent-platform/slash-commands-menu.png)
-<figcaption>Slash Commands menu</figcaption>
+<figcaption>Slash Commands menu.</figcaption>
 </figure>
 
 As you type, the menu filters results in real time, making it easy to find and run the command or prompt you need.
@@ -33,7 +33,7 @@ In addition to static commands, the menu also shows [Agent Prompts](/knowledge-a
 
 <figure>
 ![Slash Commands menu with filtered Agent Prompts](../../../../assets/agent-platform/slash-commands-prompts.png)
-<figcaption>Slash Commands menu with filtered Agent Prompts</figcaption>
+<figcaption>Slash Commands menu with filtered Agent Prompts.</figcaption>
 </figure>
 
 ### Tips
@@ -47,10 +47,10 @@ Below is an example interaction when `/init` is run:
 
 <figure>
 ![/init setup flow; 1 of 2](../../../../assets/agent-platform/init-setup-flow-1.png)
-<figcaption>/init setup flow; 1 of 2</figcaption>
+<figcaption>/init setup flow; 1 of 2.</figcaption>
 </figure>
 
 <figure>
 ![/init setup flow; 2 of 2](../../../../assets/agent-platform/init-setup-flow-2.png)
-<figcaption>/init setup flow; 2 of 2</figcaption>
+<figcaption>/init setup flow; 2 of 2.</figcaption>
 </figure>
diff --git a/src/content/docs/agent-platform/capabilities/task-lists.mdx b/src/content/docs/agent-platform/capabilities/task-lists.mdx
index 3c21489..06c6912 100644
--- a/src/content/docs/agent-platform/capabilities/task-lists.mdx
+++ b/src/content/docs/agent-platform/capabilities/task-lists.mdx
@@ -25,7 +25,7 @@ After each step is completed, there is also a completion marker in the Agent con
 
 <figure>
 ![Completion markers inside the Agent conversation after each task is completed.](../../../../assets/agent-platform/completion-markers.png)
-<figcaption>Completion markers inside the Agent conversation after each task is completed.</figcaption>
+<figcaption>Task completion markers in a conversation.</figcaption>
 </figure>
 
 ### Task statuses
@@ -45,5 +45,5 @@ During any Agent conversation, a task list chip appears at the bottom-right of t
 
 <figure>
 ![Access the task list during an Agent conversation in the task list chip in the conversation.](../../../../assets/agent-platform/tasklist-popup.png)
-<figcaption>Access the Task List during an Agent conversation in the Task List chip in the conversation.</figcaption>
+<figcaption>Task List chip in an agent conversation.</figcaption>
 </figure>
diff --git a/src/content/docs/agent-platform/cli-agents/overview.mdx b/src/content/docs/agent-platform/cli-agents/overview.mdx
index 42c173b..9fbad2f 100644
--- a/src/content/docs/agent-platform/cli-agents/overview.mdx
+++ b/src/content/docs/agent-platform/cli-agents/overview.mdx
@@ -30,7 +30,7 @@ When you launch a supported agent inside Warp, the **agent toolbelt** appears au
 
 <figure>
 ![The agent toolbelt appearing at the bottom of the pane when a supported CLI agent is running in Warp](../../../../assets/agent-platform/cli-agent-toolbelt.png)
-<figcaption>The agent toolbelt appears automatically when a supported CLI agent is running</figcaption>
+<figcaption>The agent toolbelt for CLI agents.</figcaption>
 </figure>
 
 ## Feature support
diff --git a/src/content/docs/agent-platform/cli-agents/remote-control.mdx b/src/content/docs/agent-platform/cli-agents/remote-control.mdx
index 0c21712..eda91e7 100644
--- a/src/content/docs/agent-platform/cli-agents/remote-control.mdx
+++ b/src/content/docs/agent-platform/cli-agents/remote-control.mdx
@@ -34,7 +34,7 @@ Remote Control differs from standard [Agent Session Sharing](/agent-platform/loc
 
 <figure>
 ![The /remote-control chip in the agent utility bar with a Start remote control tooltip](../../../../assets/agent-platform/remote-control.png)
-<figcaption>Click the /remote-control chip in the agent utility bar to publish the session.</figcaption>
+<figcaption>The /remote-control chip in the agent utility bar.</figcaption>
 </figure>
 
 3. A **Sharing link copied** toast notification confirms the link is on your clipboard, and the pane's status icon changes to a red broadcast indicator to show that publishing is active.
diff --git a/src/content/docs/agent-platform/cli-agents/rich-input.mdx b/src/content/docs/agent-platform/cli-agents/rich-input.mdx
index e2ab94e..6d37582 100644
--- a/src/content/docs/agent-platform/cli-agents/rich-input.mdx
+++ b/src/content/docs/agent-platform/cli-agents/rich-input.mdx
@@ -24,7 +24,7 @@ There are two ways to open the rich input editor:
 
 <figure>
 ![The Rich Input button in the agent utility bar at the bottom of the pane](../../../../assets/agent-platform/rich-input-button.png)
-<figcaption>The Rich Input button in the agent utility bar</figcaption>
+<figcaption>The Rich Input button in the agent utility bar.</figcaption>
 </figure>
 
 The rich input editor also auto-opens when an agent resumes from a blocked state (for example, after you approve a command). This requires the agent's plugin to be supported and installed. Toggle **Auto show/hide based on agent status** in [Rich input settings](#rich-input-settings) to control this behavior.
@@ -33,7 +33,7 @@ When the rich input editor is active, Warp hides the cursor inside the CLI agent
 
 <figure>
 ![The rich input editor open with a prompt being composed](../../../../assets/agent-platform/rich-input-prompt.png)
-<figcaption>The rich input editor with IDE-style editing and multi-line prompt support</figcaption>
+<figcaption>The rich input editor.</figcaption>
 </figure>
 
 ## Rich input settings
@@ -48,7 +48,7 @@ In the Warp app, go to **Settings** > **Agents** > **Third party CLI agents** to
 
 <figure>
 ![Rich input settings panel](../../../../assets/agent-platform/rich-input-settings.png)
-<figcaption>Rich input settings in Warp</figcaption>
+<figcaption>Rich input settings in Warp.</figcaption>
 </figure>
 
 ## Related pages
diff --git a/src/content/docs/agent-platform/cloud-agents/environments.mdx b/src/content/docs/agent-platform/cloud-agents/environments.mdx
index a1f29e4..a36a971 100644
--- a/src/content/docs/agent-platform/cloud-agents/environments.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/environments.mdx
@@ -146,7 +146,7 @@ Create one environment per codebase, then reuse it across triggers like Slack, L
 
 <figure>
 ![Creating a new environment in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-new-environment.png)
-<figcaption>Creating a new environment in the Oz Web App.</figcaption>
+<figcaption>Creating a new environment in the Oz web app.</figcaption>
 </figure>
 
 ### Create an environment with guided setup (recommended)
diff --git a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx
index d67d942..9d25797 100644
--- a/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/integrations/slack.mdx
@@ -163,7 +163,7 @@ To remove the Oz app from your Slack workspace:
 
 <figure>
 ![Warpy is just an internal Slackbot, your Warp slackbot should be called Oz.](../../../../../assets/agent-platform/delete-warpy.png)
-<figcaption>Warpy is just an internal Slackbot, your Warp slackbot should be called Oz.</figcaption>
+<figcaption>The Oz Slackbot in Slack.</figcaption>
 </figure>
 
 ![Confirmation dialog to remove the Oz app from a Slack workspace.](../../../../../assets/agent-platform/remove-slack-app.png)
diff --git a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx
index bdbafc9..c572f6b 100644
--- a/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx
+++ b/src/content/docs/agent-platform/cloud-agents/oz-web-app.mdx
@@ -23,7 +23,7 @@ Watch this short demo to create an environment and run an agent using the Oz web
 
 <figure>
 ![The Oz Web App's management view.](../../../../assets/agent-platform/oz-web-app-runs-view.png)
-<figcaption>The Oz Web App's management view.</figcaption>
+<figcaption>The Oz web app management view.</figcaption>
 </figure>
 
 ## When to use the web app
@@ -129,7 +129,7 @@ Each skill displays:
 
 <figure>
 ![The Agents page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-agents.png)
-<figcaption>The Agents page in the Oz Web App.</figcaption>
+<figcaption>The Agents page in the Oz web app.</figcaption>
 </figure>
 
 Filter by environment or switch to the **Suggested** tab to see pre-built skills for common workflows like code review, dependency updates, and documentation sync.
@@ -148,7 +148,7 @@ Click **New agent** to create a new skill. The guided flow helps you define the
 
 <figure>
 ![Creating a new agent skill in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-new-agent.png)
-<figcaption>Creating a new agent skill in the Oz Web App.</figcaption>
+<figcaption>Creating a new agent skill in the Oz web app.</figcaption>
 </figure>
 
 ---
@@ -165,7 +165,7 @@ Each schedule displays:
 
 <figure>
 ![The Schedules page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-schedules.png)
-<figcaption>The Schedules page in the Oz Web App.</figcaption>
+<figcaption>The Schedules page in the Oz web app.</figcaption>
 </figure>
 
 ---
@@ -211,7 +211,7 @@ Each environment displays:
 
 <figure>
 ![The Environments page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-environments.png)
-<figcaption>The Environments page in the Oz Web App.</figcaption>
+<figcaption>The Environments page in the Oz web app.</figcaption>
 </figure>
 
 ---
@@ -243,7 +243,7 @@ The **Integrations** page (`/integrations`) lets you configure first-party integ
 
 <figure>
 ![The Integrations page in the Oz Web App.](../../../../assets/agent-platform/oz-web-app-integrations.png)
-<figcaption>The Integrations page in the Oz Web App.</figcaption>
+<figcaption>The Integrations page in the Oz web app.</figcaption>
 </figure>
 
 ### Setting up an integration
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx
index 46a5720..fbe910c 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx
@@ -14,7 +14,7 @@ You can attach a block directly from the terminal blocklist by clicking the AI s
 
 <figure>
 ![From a block of output, attach the block and ask Agent Mode to remove all untracked files.](../../../../../assets/agent-platform/remove_all_untracked_files.png)
-<figcaption>From a block of output, attach the block and ask Agent Mode to remove all untracked files.</figcaption>
+<figcaption>Attaching a block as agent context.</figcaption>
 </figure>
 
 The most common use case is to ask the AI to fix an error. You can attach the error in a query to Agent Mode and type "fix it."
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx
index aad2071..50e775f 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/images-as-context.mdx
@@ -15,12 +15,12 @@ You can attach images in the following ways:
 
 <figure>
 ![Attaching 5 images on the new "Universal" input (bottom left toolbelt)](../../../../../assets/agent-platform/image-as-context-universal.png)
-<figcaption>Attaching 5 images on the new "Universal" input (bottom left toolbelt)</figcaption>
+<figcaption>Attaching images in Universal Input.</figcaption>
 </figure>
 
 <figure>
 ![Attaching 4 images on the "Classic" input (bottom right)](../../../../../assets/agent-platform/image-as-context-classic.png)
-<figcaption>Attaching 4 images on the "Classic" input (bottom right)</figcaption>
+<figcaption>Attaching images in Classic Input.</figcaption>
 </figure>
 
 * Copy and paste images directly (e.g. right-click an image > "Copy image" or copy from a file manager) into Warp.
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx
index a5273da..91c7cbf 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/selection-as-context.mdx
@@ -17,7 +17,7 @@ This makes it easy to highlight just the lines you want the Agent to analyze or
 
 <figure>
 ![Selecting a function and attaching it as context from Warp's native code editor.](../../../../../assets/agent-platform/selection-as-context.png)
-<figcaption>Selecting a function and attaching it as context from Warp's native code editor.</figcaption>
+<figcaption>Selecting code as agent context.</figcaption>
 </figure>
 
 ### Attaching selections from Warp’s Code Review panel
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx
index 297f3c8..c416ed2 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/urls-as-context.mdx
@@ -19,5 +19,5 @@ You can attach a public URL to any prompt to provide page content as context. Wa
 
 <figure>
 ![Example of referencing docs via a URL](../../../../../assets/agent-platform/url-as-context.png)
-<figcaption>Example of referencing docs via a URL</figcaption>
+<figcaption>Example of referencing docs via a URL.</figcaption>
 </figure>
diff --git a/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx b/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
index 5e11771..c2b6740 100644
--- a/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
+++ b/src/content/docs/agent-platform/local-agents/agent-context/using-to-add-context.mdx
@@ -18,19 +18,19 @@ Attaching context with @ works in **both natural language mode** (when interacti
 
 <figure>
 ![Using the @ symbol to search for and attach a file or folder from the project root.](../../../../../assets/agent-platform/at-context.png)
-<figcaption>Using the @ symbol to search for and attach a file or folder from the project root.</figcaption>
+<figcaption>File search using the @ symbol.</figcaption>
 </figure>
 
 Additionally, no codebase indexing (via [Codebase Context](/agent-platform/capabilities/codebase-context/)) is required — file search is available immediately in any Git-initialized directory. The search also respects `.gitignore` rules and will exclude ignored files from the results.
 
 <figure>
 ![Filtering files using @app to locate files containing “app” in their name or path.](../../../../../assets/agent-platform/at-context-app.png)
-<figcaption>Filtering files using @app to locate files containing “app” in their name or path.</figcaption>
+<figcaption>Filtering files with @app.</figcaption>
 </figure>
 
 <figure>
 ![Referencing a folder or all files within it by typing @styles.](../../../../../assets/agent-platform/at-context-styles.png)
-<figcaption>Referencing a folder or all files within it by typing @styles.</figcaption>
+<figcaption>Referencing a folder with @styles.</figcaption>
 </figure>
 
 ### Referencing code symbols
diff --git a/src/content/docs/agent-platform/local-agents/code-diffs.mdx b/src/content/docs/agent-platform/local-agents/code-diffs.mdx
index 1391cde..c2ca0fb 100644
--- a/src/content/docs/agent-platform/local-agents/code-diffs.mdx
+++ b/src/content/docs/agent-platform/local-agents/code-diffs.mdx
@@ -55,7 +55,7 @@ You can open up code files in Warp in various different ways, refer to: [Opening
 
 <figure>
 ![Editing a code diff directly in Warp's native code editor](../../../../assets/agent-platform/editting_diff.png)
-<figcaption>Editing the code diff directly in Warp's native code editor.</figcaption>
+<figcaption>Editing a code diff in Warp's code editor.</figcaption>
 </figure>
 
 ## Accepting diffs and continuing in Agent Mode
diff --git a/src/content/docs/agent-platform/local-agents/generate.mdx b/src/content/docs/agent-platform/local-agents/generate.mdx
index 0dad694..f93b9ee 100644
--- a/src/content/docs/agent-platform/local-agents/generate.mdx
+++ b/src/content/docs/agent-platform/local-agents/generate.mdx
@@ -26,7 +26,7 @@ Type `#` on the command-line input to generate command suggestions.
 
 <figure>
 ![Typing '#' on the command line opens the suggestions interface](../../../../assets/agent-platform/open-ai-commands.png)
-<figcaption>Typing '#' on the command line opens the suggestions interface</figcaption>
+<figcaption>Typing '#' on the command line opens the suggestions interface.</figcaption>
 </figure>
 
 <VideoEmbed url="https://www.loom.com/share/424a763ef0c8455e8269e541301968f2" title="Generating commands as command-line input demo" />
@@ -47,12 +47,12 @@ In interactive CLI applications, you can generate input using natural language.
 
 <figure>
 ![Generate a SQL query](../../../../assets/agent-platform/generate-psql.png)
-<figcaption>Generate a SQL query</figcaption>
+<figcaption>Generate a SQL query.</figcaption>
 </figure>
 
 <figure>
 ![Generate Vim input](../../../../assets/agent-platform/generate-vim.png)
-<figcaption>Generate Vim input</figcaption>
+<figcaption>Generate Vim input.</figcaption>
 </figure>
 
 <Tabs>
diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx
index 1034677..9aa4a05 100644
--- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx
+++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx
@@ -36,12 +36,12 @@ By default, if you ask an AI query immediately after interacting in Agent Mode,
 
 <figure>
 ![Continuing an Agent conversation in Classic Input (with indicator)](../../../../../assets/agent-platform/classic-input-follow-up.png)
-<figcaption>Continuing an Agent conversation in Classic Input (with indicator)</figcaption>
+<figcaption>Continuing an agent conversation in Classic Input.</figcaption>
 </figure>
 
 <figure>
 ![Continuing an Agent conversation in agent conversation view](../../../../../assets/agent-platform/follow-up-universal-input.png)
-<figcaption>Continuing an Agent conversation in agent conversation view</figcaption>
+<figcaption>Continuing an agent conversation in the conversation view.</figcaption>
 </figure>
 
 #### Agent tips in the input
@@ -100,12 +100,12 @@ Visual indicators differ slightly depending on input mode:
 
 <figure>
 ![Starting a new Conversation in Classic Input](../../../../../assets/agent-platform/classic-input-new-convo.png)
-<figcaption>Starting a new Conversation in Classic Input</figcaption>
+<figcaption>Starting a new Conversation in Classic Input.</figcaption>
 </figure>
 
 <figure>
 ![Starting a new Agent Conversation in agent conversation view](../../../../../assets/agent-platform/universal-input-new-convo.png)
-<figcaption>Starting a new Agent Conversation in agent conversation view</figcaption>
+<figcaption>Starting a new Agent Conversation in agent conversation view.</figcaption>
 </figure>
 
 ## Context window management
diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx
index dabfd22..d7386c6 100644
--- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx
+++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx
@@ -306,7 +306,7 @@ If you prefer to type natural language at any point in a terminal session and ha
 
 <figure>
 ![Using Agent as your default for new tab sessions](/assets/agent-platform/recreate-universal-input.gif)
-<figcaption>Using Agent as your default for new tab sessions</figcaption>
+<figcaption>Using Agent as your default for new tab sessions.</figcaption>
 </figure>
 
 ### Step 1 — Set new tabs to open in agent view
diff --git a/src/content/docs/agent-platform/local-agents/interacting-with-agents/voice.mdx b/src/content/docs/agent-platform/local-agents/interacting-with-agents/voice.mdx
index 7d264ab..c4abad4 100644
--- a/src/content/docs/agent-platform/local-agents/interacting-with-agents/voice.mdx
+++ b/src/content/docs/agent-platform/local-agents/interacting-with-agents/voice.mdx
@@ -57,7 +57,7 @@ There are two ways to activate Voice:
 
 <figure>
 ![Voice settings panel showing hotkey configuration and voice input toggle options](../../../../../assets/agent-platform/voice-settings.png)
-<figcaption>Voice settings panel showing hotkey configuration and voice input toggle options</figcaption>
+<figcaption>Voice input settings.</figcaption>
 </figure>
 
 ### Sample use cases
@@ -70,7 +70,7 @@ Voice input is not limited to just Agent Mode - it works across all of Warp's in
 
 <figure>
 ![Voice input works across Warp's editor interfaces, including the Find dialog and other input editors](../../../../../assets/agent-platform/voice-in-find.png)
-<figcaption>Voice input works across Warp's editor interfaces, including the Find dialog and other input editors</figcaption>
+<figcaption>Voice input in a Warp editor.</figcaption>
 </figure>
 
 ## Privacy & security
diff --git a/src/content/docs/code/overview.mdx b/src/content/docs/code/overview.mdx
index b0b1b09..a5abd77 100644
--- a/src/content/docs/code/overview.mdx
+++ b/src/content/docs/code/overview.mdx
@@ -68,7 +68,7 @@ Warp provides multiple entry points to begin coding with agents, whether you are
 
 <figure>
 ![Zero-state tab with 3 starting points for agentic coding in Warp.](../../../assets/terminal/code_mode.png)
-<figcaption>Zero-state tab with 3 starting points for agentic coding in Warp.</figcaption>
+<figcaption>Zero-state tab with coding starting points.</figcaption>
 </figure>
 
 #### 1. Starting a new project
diff --git a/src/content/docs/getting-started/keyboard-shortcuts.mdx b/src/content/docs/getting-started/keyboard-shortcuts.mdx
index 62fc625..31bd7ac 100644
--- a/src/content/docs/getting-started/keyboard-shortcuts.mdx
+++ b/src/content/docs/getting-started/keyboard-shortcuts.mdx
@@ -25,7 +25,7 @@ Keybinds that conflict with others are highlighted with an orange border.
 
 <figure>
 ![keybinds that conflict with others are highlighted in orange](../../../assets/terminal/keybinds-conflict.png)
-<figcaption>Keybind Conflict Example</figcaption>
+<figcaption>Keybind Conflict Example.</figcaption>
 </figure>
 
 ## All available shortcuts
diff --git a/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx b/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx
index 7c2cb6a..5a8aa7f 100644
--- a/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx
+++ b/src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx
@@ -29,7 +29,7 @@ To run the importer:
 
 <figure>
 ![Select a settings profile to import](../../../../assets/terminal/migrate-to-warp.png)
-<figcaption>Select a settings profile to import</figcaption>
+<figcaption>Select a settings profile to import.</figcaption>
 </figure>
 
 ## Use Warp's agent for follow-up settings
diff --git a/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx b/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx
index 283672a..f0c6008 100644
--- a/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx
+++ b/src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx
@@ -48,14 +48,14 @@ Once the agent has finished the task, open Warp's [Code Review panel](/code/code
 
 <figure>
 ![Code Review button in the top-right corner of the Warp title bar showing file and line change counts](../../../../assets/guides/code-review-button.png)
-<figcaption>The Code Review button in the top-right corner shows the number of changed files and lines.</figcaption>
+<figcaption>The Code Review button.</figcaption>
 </figure>
 
 The panel shows all uncommitted changes as a visual diff, grouped by file. Additions are highlighted in green with a `+` prefix, removals in red with a `-` prefix.
 
 <figure>
 ![Code Review panel showing file diffs between branches](../../../../assets/guides/code-review-panel-with-diffs.png)
-<figcaption>Code Review panel showing diffs with additions highlighted in green.</figcaption>
+<figcaption>Code Review panel with diffs.</figcaption>
 </figure>
 
 ## 3. Review diffs by file
@@ -70,7 +70,7 @@ Focus on the areas where agents are most likely to make mistakes: imports, error
 
 <figure>
 ![Code Review panel with file navigation sidebar showing changed files](../../../../assets/guides/code-review-file-sidebar.png)
-<figcaption>File sidebar lists all changed files with addition and deletion counts.</figcaption>
+<figcaption>Changed files sidebar.</figcaption>
 </figure>
 
 ## 4. Leave inline comments on issues
@@ -80,7 +80,7 @@ You can add as many comments as you need before submitting — Warp batches them
 
 <figure>
 ![Adding an inline comment on a diff line in the Code Review panel](../../../../assets/guides/code-review-inline-comment.png)
-<figcaption>Inline comments anchor to specific lines so the agent knows exactly what to fix.</figcaption>
+<figcaption>Inline comments on specific diff lines.</figcaption>
 </figure>
 
 ## 5. Submit all comments to the agent
diff --git a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx
index d40f679..21f5e98 100644
--- a/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx
+++ b/src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx
@@ -31,7 +31,7 @@ You can configure what information to display for each tab:
 
 <figure>
 ![Warp vertical tabs sidebar showing multiple terminal sessions with branch metadata](../../../../assets/terminal/vertical-tabs-multi-agent.png)
-<figcaption>Vertical tabs show which agent is running, the Git branch, and session status.</figcaption>
+<figcaption>Vertical tabs overview.</figcaption>
 </figure>
 
 ## 2. Launch agents in separate tabs
@@ -64,7 +64,7 @@ Write comprehensive tests for src/auth/ covering edge cases
 
 <figure>
 ![Multiple agent tabs in Warp's vertical sidebar showing session status, branch, and directory metadata](../../../../assets/terminal/multi-agents.png)
-<figcaption>Each vertical tab shows the agent name, working directory, branch, and diff stats at a glance.</figcaption>
+<figcaption>Vertical tab with agent details.</figcaption>
 </figure>
 
 ## 3. Monitor agents with notifications
@@ -85,7 +85,7 @@ Agent notifications are currently supported for Claude Code, Codex, and OpenCode
 
 <figure>
 ![Warp notification popup showing an agent requesting permission to edit a file](../../../../assets/guides/tab-notification-indicator.png)
-<figcaption>Warp surfaces a notification when an agent needs approval, so you can jump directly to the tab that needs input.</figcaption>
+<figcaption>Agent approval notification.</figcaption>
 </figure>
 
 ## 4. Compare outputs from different agents
@@ -107,7 +107,7 @@ If you regularly work with the same multi-agent setup, save it as a tab config s
 
 <figure>
 ![Creating a new tab config from the tab context menu in Warp](../../../../assets/terminal/save-new-tab-config.png)
-<figcaption>Save a tab config to recreate your multi-agent workspace with one click.</figcaption>
+<figcaption>Saving a tab config.</figcaption>
 </figure>
 
 Tab configs are TOML files that define the directory, startup commands, and layout for a tab. For example, you might create a config that:
diff --git a/src/content/docs/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents.mdx b/src/content/docs/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents.mdx
index 672ea80..c93c268 100644
--- a/src/content/docs/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents.mdx
+++ b/src/content/docs/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents.mdx
@@ -61,7 +61,7 @@ Paste (`⌘+V`) or drag images directly into the input area to give the agent vi
 
 <figure>
 ![Image attached as context in the Warp input area alongside a text prompt](../../../../assets/guides/image-as-context.png)
-<figcaption>Paste or drag images into the input to give the agent visual context.</figcaption>
+<figcaption>Attaching images as agent context.</figcaption>
 </figure>
 
 ## 4. Combine voice and images for design-to-code workflows
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index 8c1b61b..f3c3b06 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -12,7 +12,7 @@ Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Developme
 
 <figure>
 ![Warp, the Agentic Development Environment: Warp (a modern terminal built for coding with agents) and Oz (the orchestration platform for cloud agents)](../../assets/terminal/warp-oz-welcome.png)
-<figcaption>Warp combines a modern terminal with Oz, the orchestration platform for cloud agents</figcaption>
+<figcaption>Warp terminal with Oz orchestration.</figcaption>
 </figure>
 
 ---
diff --git a/src/content/docs/knowledge-and-collaboration/admin-panel.mdx b/src/content/docs/knowledge-and-collaboration/admin-panel.mdx
index c28d504..8c23a89 100644
--- a/src/content/docs/knowledge-and-collaboration/admin-panel.mdx
+++ b/src/content/docs/knowledge-and-collaboration/admin-panel.mdx
@@ -27,7 +27,7 @@ Team administrators can access the Admin Panel directly at https://app.warp.dev/
 
 <figure>
 ![Admin Panel main interface with sections for AI, privacy, billing, code, and sharing settings](../../../assets/terminal/admin-panel-overview.png)
-<figcaption>Admin Panel main interface with sections for AI, privacy, billing, code, and sharing settings</figcaption>
+<figcaption>Admin Panel main interface.</figcaption>
 </figure>
 
 ## How settings enforcement works
diff --git a/src/content/docs/knowledge-and-collaboration/teams.mdx b/src/content/docs/knowledge-and-collaboration/teams.mdx
index 1d6fba9..3602f8e 100644
--- a/src/content/docs/knowledge-and-collaboration/teams.mdx
+++ b/src/content/docs/knowledge-and-collaboration/teams.mdx
@@ -44,7 +44,7 @@ For more details on how team member billing works, please see our [billing FAQs]
 
 <figure>
 ![Teams settings panel](../../../assets/terminal/teams-invite-demo.png)
-<figcaption>Teams settings panel</figcaption>
+<figcaption>Teams settings panel.</figcaption>
 </figure>
 
 When you share this link with your teammates directly (we suggest using a secure channel like Slack or email), they will be able to join your team in Warp.
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
index 5271797..6b1dd5e 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
@@ -30,7 +30,7 @@ All objects stored in Warp Drive sync immediately as they’re updated, so you a
 
 <figure>
 ![Warp Drive icon on top left corner of Warp](../../../../assets/terminal/Open_Warp_Drive.png)
-<figcaption>Warp Drive Icon</figcaption>
+<figcaption>Warp Drive Icon.</figcaption>
 </figure>
 
 ## Workspaces in Warp Drive
@@ -56,7 +56,7 @@ In offline mode, some files will be read-only. You can still create and edit fil
 
 <figure>
 ![Warp Drive offline mode](../../../../assets/terminal/warp_drive_offline.png)
-<figcaption>Warp Drive offline mode</figcaption>
+<figcaption>Warp Drive offline mode.</figcaption>
 </figure>
 
 ## Navigating Warp Drive with your keyboard
@@ -97,7 +97,7 @@ You can take these keyboard actions within Warp Drive:
 
 <figure>
 ![Warp Drive navigation states](../../../../assets/terminal/warp_drive_nav1.png)
-<figcaption>Warp Drive navigation states</figcaption>
+<figcaption>Warp Drive navigation states.</figcaption>
 </figure>
 
 To switch between panels using your keyboard, you can use the “Switch Focus to Left Panel” and “Switch Focus to Right Panel” commands in the [Command Palette](/terminal/command-palette/).
@@ -119,7 +119,7 @@ To import a local file or directory, `RIGHT-CLICK` on a folder or click **+** on
 
 <figure>
 ![Import modal](../../../../assets/terminal/notebook-import-modal.png)
-<figcaption>Import modal</figcaption>
+<figcaption>Import modal.</figcaption>
 </figure>
 
 ### Exporting files from Warp Drive
@@ -144,7 +144,7 @@ To access an object, link-followers must have permission to open it through one
 
 <figure>
 ![Copy link Menu Item](../../../../assets/terminal/wd-copy-link-menu.png)
-<figcaption>Copy link Menu Item</figcaption>
+<figcaption>Copy link Menu Item.</figcaption>
 </figure>
 
 ### Managing permissions
@@ -153,14 +153,14 @@ To manage a Drive object's permissions, navigate to its overflow menu and choose
 
 <figure>
 ![The pane header for a notebook, with the share button circled](../../../../assets/terminal/wd-share-button.png)
-<figcaption>Pane header share button</figcaption>
+<figcaption>Pane header share button.</figcaption>
 </figure>
 
 This opens a dialog that lists the current sharing settings and allows you to change them:
 
 <figure>
 ![A sharing dialog showing that anyone with the link can view, the owner has full access, and another user can edit.](../../../../assets/terminal/wd-share-dialog.png)
-<figcaption>Warp Drive sharing dialog</figcaption>
+<figcaption>Warp Drive sharing dialog.</figcaption>
 </figure>
 
 In this dialog, you can:
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
index 41b5ad4..9719284 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
@@ -41,7 +41,7 @@ Note: The notebook will not be saved until either title or body text is added.
 
 <figure>
 ![Editing a Notebook](/assets/terminal/notebooks_editor.gif)
-<figcaption>Editing a Notebook</figcaption>
+<figcaption>Editing a Notebook.</figcaption>
 </figure>
 
 ### Working with Notebooks
@@ -56,7 +56,7 @@ Notebook elements (text, code, list items) can be added in several ways:
 
 <figure>
 ![Markdown element types](../../../../assets/terminal/markdown-element-types.png)
-<figcaption>Markdown element types</figcaption>
+<figcaption>Markdown element types.</figcaption>
 </figure>
 
 #### Styling existing elements
@@ -80,7 +80,7 @@ Once you’ve inserted your code block you can select the language at the bottom
 
 <figure>
 ![Example code block](../../../../assets/terminal/notebook-code-block.png)
-<figcaption>Example code block</figcaption>
+<figcaption>Example code block.</figcaption>
 </figure>
 
 #### Special properties of command blocks
@@ -110,7 +110,7 @@ The command text will be inserted into the developer’s active terminal session
 
 <figure>
 ![Run option for command block](../../../../assets/terminal/notebook-cmd-block-run.png)
-<figcaption>Run option for command block</figcaption>
+<figcaption>Run option for command block.</figcaption>
 </figure>
 
 #### Adding arguments to Command Blocks
@@ -119,7 +119,7 @@ Command blocks accept parameters in the same format as [Workflows](/knowledge-an
 
 <figure>
 ![Command block with parameters](../../../../assets/terminal/notebook-cmd-with-params.png)
-<figcaption>Command block with parameters</figcaption>
+<figcaption>Command block with parameters.</figcaption>
 </figure>
 
 #### Navigating command blocks with the keyboard
@@ -166,7 +166,7 @@ Note that only one editor is allowed at a given time. Opening the notebook while
 
 <figure>
 ![View mode example](../../../../assets/terminal/notebook-view-mode.png)
-<figcaption>View mode example</figcaption>
+<figcaption>View mode example.</figcaption>
 </figure>
 
 ### Import and export notebooks in Warp Drive
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx
index a66f7a8..59119a2 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/prompts.mdx
@@ -15,7 +15,7 @@ Prompts are searchable and easily accessed from the [Command Palette](/terminal/
 
 <figure>
 ![View of a Prompt in Warp Drive showing the command view interface](../../../../assets/terminal/prompts-command-view.png)
-<figcaption>Command view of a Prompt in Warp Drive</figcaption>
+<figcaption>Command view of a Prompt in Warp Drive.</figcaption>
 </figure>
 
 ### Demo: Trigger reusable actions with saved prompts
@@ -37,7 +37,7 @@ You can create a new prompt from Warp Drive by clicking the + button and selecti
 
 <figure>
 ![View of the Prompt editor interface showing the edit form with fields for name, query, description, and arguments](../../../../assets/terminal/prompts-edit-view.png)
-<figcaption>Edit view of a Prompt in Warp Drive</figcaption>
+<figcaption>Edit view of a Prompt in Warp Drive.</figcaption>
 </figure>
 
 Once a prompt has been created, you can edit it at any time, as long as you have access to an internet connection.
@@ -75,12 +75,12 @@ You can execute a prompt in several ways:
 
 <figure>
 ![Command Palette interface showing a search for Prompts with results displayed](../../../../assets/terminal/prompts-command-palette.png)
-<figcaption>Search for Prompts in the Command Palette with CMD + P</figcaption>
+<figcaption>Searching for Prompts in the Command Palette.</figcaption>
 </figure>
 
 <figure>
 ![Command Search interface showing a search for Prompts with results displayed](../../../../assets/terminal/prompts-command-search.png)
-<figcaption>Search for Prompts in Command Search with CTRL + R</figcaption>
+<figcaption>Searching for Prompts in Command Search.</figcaption>
 </figure>
 
 These options will paste the prompt into your active terminal input. Prompt names and any relevant descriptions and arguments will be displayed in a dialog, so you can understand how to use the prompt.
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx
index f29192c..420a289 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/web.mdx
@@ -11,7 +11,7 @@ Warp Drive on the Web lets you view and edit your Warp Drive objects and shared
 
 <figure>
 ![A web-based rendering of a Team Workflow](../../../../assets/terminal/wd-web-team-workflow.png)
-<figcaption>A web-based rendering of a Team Workflow</figcaption>
+<figcaption>A web-based rendering of a Team Workflow.</figcaption>
 </figure>
 
 ## How to access Warp on the web
@@ -44,7 +44,7 @@ If you would like to use Warp locally and do not have it installed, please visit
 
     <figure>
     ![Setting managing how to open links](../../../../assets/terminal/wd-open-links-preference.png)
-    <figcaption>Setting managing how to open links</figcaption>
+    <figcaption>Setting managing how to open links.</figcaption>
     </figure>
 3. You can always switch between web and desktop views on a case-by-case basis.
    1.  To switch from a web-view to Desktop for a given object, open the _overflow menu > Open link on Desktop._
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
index f633e9f..a3e9fb4 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
@@ -31,7 +31,7 @@ Any of these entry points will open the workflow editor where you can:
 
 <figure>
 ![Workflows save and edit modal](../../../../assets/terminal/edit-workflow-pane.png)
-<figcaption>Workflows save / edit pane</figcaption>
+<figcaption>Workflows save / edit pane.</figcaption>
 </figure>
 
 <VideoEmbed url="https://www.youtube.com/watch?v=8UmreUTTrkg&start=9s&end=198s" title="Save Workflow Demo" />
@@ -76,7 +76,7 @@ Once a workflow has been created, you can edit it at any time, as long as you ha
 
 <figure>
 ![Edit workflow menu](../../../../assets/terminal/Edit_Workflow.png)
-<figcaption>Edit workflow menu</figcaption>
+<figcaption>Edit workflow menu.</figcaption>
 </figure>
 
 #### AI Autofill
@@ -111,14 +111,14 @@ Also, tailor your Command Search experience by toggling off "Show Global Workflo
 
 <figure>
 ![Search for any workflow in the Command Palette with CMD + P](../../../../assets/terminal/search-workflow-command-palette.png)
-<figcaption>Search for any workflow in the Command Palette with CMD + P</figcaption>
+<figcaption>Searching for Workflows in the Command Palette.</figcaption>
 </figure>
 
 These options will paste the workflow into your active terminal input. Workflow names and any relevant descriptions and arguments will be displayed in a dialog, so you can understand how to use the workflow.
 
 <figure>
 ![Execute a Workflow](../../../../assets/terminal/execute-a-workflow.png)
-<figcaption>Execute a Workflow</figcaption>
+<figcaption>Execute a Workflow.</figcaption>
 </figure>
 
 You make any adjustments you need to the arguments (or the command itself) before running the command in your input editor.
diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx
index 9be27f2..0d2fb03 100644
--- a/src/content/docs/reference/cli/api-keys.mdx
+++ b/src/content/docs/reference/cli/api-keys.mdx
@@ -36,7 +36,7 @@ Team keys without GitHub App authorization are the right fit for automated workf
 
 <figure>
 ![API key management interface in Warp settings](../../../../assets/reference/api-key-management.png)
-<figcaption>API key management interface in Warp settings</figcaption>
+<figcaption>API key management interface in Warp settings.</figcaption>
 </figure>
 
 ## Personal vs team API keys
diff --git a/src/content/docs/reference/cli/mcp-servers.mdx b/src/content/docs/reference/cli/mcp-servers.mdx
index 88b7650..42cff41 100644
--- a/src/content/docs/reference/cli/mcp-servers.mdx
+++ b/src/content/docs/reference/cli/mcp-servers.mdx
@@ -44,7 +44,7 @@ $ oz mcp list
 
 <figure>
 ![MCP servers page, showing a server with its UUID](../../../../assets/reference/mcp-server-id.png)
-<figcaption>MCP servers page, showing a server with its UUID</figcaption>
+<figcaption>MCP servers page, showing a server with its UUID.</figcaption>
 </figure>
 
 2. Pass the UUID to `--mcp`:
diff --git a/src/content/docs/support-and-community/plans-and-billing/credits.mdx b/src/content/docs/support-and-community/plans-and-billing/credits.mdx
index 47db635..f039eed 100644
--- a/src/content/docs/support-and-community/plans-and-billing/credits.mdx
+++ b/src/content/docs/support-and-community/plans-and-billing/credits.mdx
@@ -26,7 +26,7 @@ In an Agent conversation, a **turn** represents a single exchange (a response fr
 
 <figure>
 ![The conversation usage footer shows how many credits a conversation has consumed, and breaks down the usage by credits, tool calls, context window, files changed, diffs applied, and more.](../../../../assets/support-and-community/inline-credit-usage-footer.png)
-<figcaption>The conversation usage footer shows how many credits a conversation has consumed, and breaks down the usage by credits, tool calls, context window, files changed, diffs applied, and more.</figcaption>
+<figcaption>Conversation usage footer.</figcaption>
 </figure>
 
 :::note
diff --git a/src/content/docs/support-and-community/plans-and-billing/overages-legacy.mdx b/src/content/docs/support-and-community/plans-and-billing/overages-legacy.mdx
index eb3484e..2aacddd 100644
--- a/src/content/docs/support-and-community/plans-and-billing/overages-legacy.mdx
+++ b/src/content/docs/support-and-community/plans-and-billing/overages-legacy.mdx
@@ -11,7 +11,7 @@ You can manage usage-based pricing directly in Warp under **Settings** > **Billi
 
 <figure>
 ![Billing and usage tab in settings, where admins can manage premium model usage overages](../../../../assets/support-and-community/overages-settings.png)
-<figcaption>Billing and usage tab in settings, where admins can manage premium model usage overages</figcaption>
+<figcaption>Billing and usage settings.</figcaption>
 </figure>
 
 ### Enabling overages
diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx
index 803a5b9..9eee528 100644
--- a/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx
+++ b/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx
@@ -217,7 +217,7 @@ The following non-exhaustive list of plugins, prompts, or tools can cause potent
 
     <figure>
     ![macOS SSH permission error](../../../../assets/support-and-community/mac-ssh-permission.png)
-    <figcaption>macOS SSH permission error</figcaption>
+    <figcaption>macOS SSH permission error.</figcaption>
     </figure>
 
     **Unexpected loss of permission on macOS**
@@ -226,7 +226,7 @@ The following non-exhaustive list of plugins, prompts, or tools can cause potent
 
     <figure>
     ![Permission error on macOS](../../../../assets/support-and-community/permission-error-macos.png)
-    <figcaption>Permission error on macOS</figcaption>
+    <figcaption>Permission error on macOS.</figcaption>
     </figure>
 
     **Auto-Update error on macOS**
diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx
index cdf3b74..ffae5dd 100644
--- a/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx
+++ b/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx
@@ -226,7 +226,7 @@ Collect a sample using the steps for your platform and attach it to a new [GitHu
 
     <figure>
     ![Sampling the Warp process in Activity Monitor](../../../../assets/support-and-community/activity-monitor-sample-process.png)
-    <figcaption>Sample Process in Activity Monitor</figcaption>
+    <figcaption>Sample Process in Activity Monitor.</figcaption>
     </figure>
 
     3. Save the resulting sample and attach it to your GitHub issue.
diff --git a/src/content/docs/terminal/appearance/app-icons.mdx b/src/content/docs/terminal/appearance/app-icons.mdx
index c554989..2859a32 100644
--- a/src/content/docs/terminal/appearance/app-icons.mdx
+++ b/src/content/docs/terminal/appearance/app-icons.mdx
@@ -34,7 +34,7 @@ App icons are only available for Warp on macOS. The feature doesn't support cust
 
 <figure>
 ![Icon customization drop-down menu](../../../../assets/terminal/custom-dock-icon-dropdown.png)
-<figcaption>Icon customization drop-down menu</figcaption>
+<figcaption>Icon customization drop-down menu.</figcaption>
 </figure>
 
 ## Dock icons
diff --git a/src/content/docs/terminal/appearance/prompt.mdx b/src/content/docs/terminal/appearance/prompt.mdx
index 7cfaadd..addcd1b 100644
--- a/src/content/docs/terminal/appearance/prompt.mdx
+++ b/src/content/docs/terminal/appearance/prompt.mdx
@@ -32,7 +32,7 @@ To customize which context chips your Warp prompt displays:
 
 <figure>
 ![Right-click context menu showing the Edit prompt option](../../../../assets/terminal/edit-prompt-modal.png)
-<figcaption>Right-click the prompt area to access Edit prompt</figcaption>
+<figcaption>Prompt editing via right-click.</figcaption>
 </figure>
 
 2. Select **Warp Prompt**.
@@ -185,7 +185,7 @@ P10K may display the arrow dividers as grey instead of color. The color for thos
 
 <figure>
 ![Example of the grey dividers in p10k](../../../../assets/terminal/p10k-grey-arrow-prompt.png)
-<figcaption>Example of the grey dividers in p10k</figcaption>
+<figcaption>Example of the grey dividers in p10k.</figcaption>
 </figure>
 
 Warp does support [p10k](https://github.com/romkatv/powerlevel10k#installation) version 1.19.0 and above. Ensure you have the latest version installed and restart Warp after the installation/update of p10k. Then enable the custom prompt as stated [above](/terminal/appearance/prompt/#choosing-your-prompt-type) and it should work.
diff --git a/src/content/docs/terminal/blocks/sticky-command-header.mdx b/src/content/docs/terminal/blocks/sticky-command-header.mdx
index f8d34cc..001bbbe 100644
--- a/src/content/docs/terminal/blocks/sticky-command-header.mdx
+++ b/src/content/docs/terminal/blocks/sticky-command-header.mdx
@@ -46,5 +46,5 @@ For long-running commands that take up the full screen, the sticky header only s
 
 <figure>
 ![Toggle active header and Jump to bottom of block demo](/assets/terminal/sticky-header-toggle-active-demo.gif)
-<figcaption>Toggle active header and Jump to bottom of block demo</figcaption>
+<figcaption>Toggle active header and Jump to bottom of block demo.</figcaption>
 </figure>
diff --git a/src/content/docs/terminal/command-palette.mdx b/src/content/docs/terminal/command-palette.mdx
index 6ac78c6..0dbfd50 100644
--- a/src/content/docs/terminal/command-palette.mdx
+++ b/src/content/docs/terminal/command-palette.mdx
@@ -9,7 +9,7 @@ import VideoEmbed from '@components/VideoEmbed.astro';
 
 <figure>
 ![Command Palette Panel](../../../assets/terminal/command-palette-panel.png)
-<figcaption>Command Palette Panel</figcaption>
+<figcaption>Command Palette Panel.</figcaption>
 </figure>
 
 ## How to access it
diff --git a/src/content/docs/terminal/editor/index.mdx b/src/content/docs/terminal/editor/index.mdx
index 5bb567f..e8392c2 100644
--- a/src/content/docs/terminal/editor/index.mdx
+++ b/src/content/docs/terminal/editor/index.mdx
@@ -47,5 +47,5 @@ Warp can automatically complete quotes, brackets, and parentheses like you're us
 
 <figure>
 ![soft wrapping text in Warp input editor](../../../../assets/terminal/soft-wrapping.png)
-<figcaption>Soft Wrapping Demo</figcaption>
+<figcaption>Soft Wrapping Demo.</figcaption>
 </figure>
diff --git a/src/content/docs/terminal/entry/command-history.mdx b/src/content/docs/terminal/entry/command-history.mdx
index 212a333..681a446 100644
--- a/src/content/docs/terminal/entry/command-history.mdx
+++ b/src/content/docs/terminal/entry/command-history.mdx
@@ -15,7 +15,7 @@ Command History also provides rich information like exit code, directory, thread
 
 <figure>
 ![Command History rich information](../../../../assets/terminal/command-history-rich.png)
-<figcaption>Command History rich information</figcaption>
+<figcaption>Command History rich information.</figcaption>
 </figure>
 
 ## How to access it
diff --git a/src/content/docs/terminal/input/classic-input.mdx b/src/content/docs/terminal/input/classic-input.mdx
index a178302..3519599 100644
--- a/src/content/docs/terminal/input/classic-input.mdx
+++ b/src/content/docs/terminal/input/classic-input.mdx
@@ -54,7 +54,7 @@ When you are in Agent Mode, a ✨ sparkles icon will display in line with your t
 
 <figure>
 ![The sparkles on the command line indicate Agent Mode is active.](../../../../assets/terminal/undo_my_git_commit.png)
-<figcaption>The sparkles in the Classic input indicates that Agent Mode is active.</figcaption>
+<figcaption>Agent Mode active indicator in Classic Input.</figcaption>
 </figure>
 
 ## Auto-detection for natural language and configurable settings
@@ -69,7 +69,7 @@ The first time you enter Agent Mode, you will be served a banner with the option
 
 <figure>
 ![Warp displays an option to toggle natural language detection on / off](../../../../assets/terminal/banner_for_auto-detection_first_experience.png)
-<figcaption>Warp displays an option to toggle natural language detection on / off</figcaption>
+<figcaption>Natural language detection toggle.</figcaption>
 </figure>
 
 ## Input hints
@@ -118,14 +118,14 @@ If you do not wish to send the command or its output to AI, you can click Cancel
 
 <figure>
 ![Oz asks permission to run a command and read the output.](../../../../assets/terminal/warp-ai-permissions.png)
-<figcaption>Warp AI asks permission to run a command and read the output.</figcaption>
+<figcaption>Agent command approval prompt.</figcaption>
 </figure>
 
 Once a requested command is executed, you can click to expand the output and view command details.
 
 <figure>
 ![Viewing command details](../../../../assets/terminal/warp-ai-viewing-commands.png)
-<figcaption>Viewing command details</figcaption>
+<figcaption>Viewing command details.</figcaption>
 </figure>
 
 If a requested command fails, Oz detects it. Agent Mode is self-correcting. It will request another command until it completes the task for you.
diff --git a/src/content/docs/terminal/input/universal-input.mdx b/src/content/docs/terminal/input/universal-input.mdx
index 041ed67..8619acb 100644
--- a/src/content/docs/terminal/input/universal-input.mdx
+++ b/src/content/docs/terminal/input/universal-input.mdx
@@ -17,7 +17,7 @@ The **Universal Input** was the main input interface for using Warp.
 
 <figure>
 ![The Universal Input with an Agent prompt and multiple contextual chips active.](../../../../assets/terminal/universal-input-header.png)
-<figcaption>The Universal Input with an Agent prompt and multiple contextual chips active.</figcaption>
+<figcaption>Universal Input with contextual chips.</figcaption>
 </figure>
 
 <VideoEmbed url="https://www.youtube.com/watch?v=4c05OEqzQIA" title="Using the Universal Input" />
@@ -131,14 +131,14 @@ When you're in Agent Mode, the **Agent icon** will be highlighted in the [Univer
 
 <figure>
 ![The Agent icon in the Universal input indicates that Agent Mode is active.](../../../../assets/terminal/using-agents-universal-input.png)
-<figcaption>The Agent icon in the Universal input indicates that Agent Mode is active.</figcaption>
+<figcaption>Agent Mode indicator in Universal Input.</figcaption>
 </figure>
 
 In Classic Input, you’ll also see a ✨ sparkles indicator inline.
 
 <figure>
 ![The sparkles on the command line indicate Agent Mode is active.](../../../../assets/terminal/undo_my_git_commit.png)
-<figcaption>The sparkles in the Classic input indicates that Agent Mode is active.</figcaption>
+<figcaption>Agent Mode active indicator in Classic Input.</figcaption>
 </figure>
 
 By default, entering Agent Mode starts you in _Pair Mode_, where you can continue an ongoing conversation by asking follow-up questions or assigning tasks. From here, you can ask the agent to build, debug, fix, or even deploy code as needed.
@@ -197,7 +197,7 @@ The first time you enter Agent Mode, Warp will display a banner with the option
 
 <figure>
 ![Warp displays an option to toggle natural language detection on / off](../../../../assets/terminal/banner_for_auto-detection_first_experience.png)
-<figcaption>Warp displays an option to toggle natural language detection on / off</figcaption>
+<figcaption>Natural language detection toggle.</figcaption>
 </figure>
 
 ---
@@ -206,7 +206,7 @@ The first time you enter Agent Mode, Warp will display a banner with the option
 
 <figure>
 ![Universal Input's contextual input chips, from left to right: conversation management, node version, active directory, Git and code diffs, and 2 attached images.](../../../../assets/terminal/universal-input.png)
-<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>
+<figcaption>Universal Input contextual chips.</figcaption>
 </figure>
 
 The Universal Input includes **contextual chips** that provide inline information about your current environment. These chips surface relevant details such as directory paths, Git status, conversations, or runtime versions, making it easier to navigate, manage context, and take quick actions without leaving the input.
@@ -219,7 +219,7 @@ These chips appear in both Agent Mode and Terminal Mode, so you can continue a p
 
 <figure>
 ![The Conversation Management chip displays recent Agent conversations and lets you continue or reopen them directly from the input.](../../../../assets/terminal/conversation-management-chip-universal-input.png)
-<figcaption>The Conversation Management chip displays recent Agent conversations and lets you continue or reopen them directly from the input.</figcaption>
+<figcaption>The Conversation Management chip.</figcaption>
 </figure>
 
 These chips appear in both Agent Mode and Terminal Mode, helping you continue a previous conversation without starting from scratch. For more details, refer to [Agent Conversations](/agent-platform/local-agents/interacting-with-agents/).
@@ -230,7 +230,7 @@ The active directory chip displays your current working directory and enables si
 
 <figure>
 ![The Active Directory chip lets you browse directories and open files directly from the input.](../../../../assets/terminal/active-directory-chip.png)
-<figcaption>The Active Directory chip lets you browse directories and open files directly from the input.</figcaption>
+<figcaption>The Active Directory chip.</figcaption>
 </figure>
 
 #### Git Status chip
@@ -241,7 +241,7 @@ The chip updates automatically as files are added, removed, or changed, giving y
 
 <figure>
 ![The Git Status chip highlights repository changes and provides quick access to code review.](../../../../assets/terminal/git-branch-chip.png)
-<figcaption>The Git Status chip highlights repository changes and provides quick access to code review.</figcaption>
+<figcaption>The Git Status chip.</figcaption>
 </figure>
 
 #### File attachments chips
@@ -250,7 +250,7 @@ The file attachments chip lets you attach images and other files directly to a p
 
 <figure>
 ![The File Attachments chip allows you to add images or files as context for your queries.](../../../../assets/terminal/images-as-context-chip.png)
-<figcaption>The File Attachments chip allows you to add images or files as context for your queries.</figcaption>
+<figcaption>The File Attachments chip.</figcaption>
 </figure>
 
 **Node version chip**
@@ -259,7 +259,7 @@ In repositories that include a `package.json`, a Node Version chip appears to sh
 
 <figure>
 ![The Node Version chip displays the Node.js version detected in your repository.](../../../../assets/terminal/node-version-chip.png)
-<figcaption>The Node Version chip displays the Node.js version detected in your repository.</figcaption>
+<figcaption>The Node Version chip.</figcaption>
 </figure>
 
 :::note
@@ -274,7 +274,7 @@ The **Input Toolbelt** provides quick-access controls alongside the Universal In
 
 <figure>
 ![The Input Toolbelt in Warp’s Universal Input, showing quick-access controls for context, slash commands, voice input, attachments, profiles, and model selection.](../../../../assets/terminal/input-toolbar.png)
-<figcaption>The Input Toolbelt in Warp’s Universal Input, showing quick-access controls for context, slash commands, voice input, attachments, profiles, and model selection.</figcaption>
+<figcaption>The Input Toolbelt in Universal Input.</figcaption>
 </figure>
 
 #### @ - Context
diff --git a/src/content/docs/terminal/integrations-and-plugins.mdx b/src/content/docs/terminal/integrations-and-plugins.mdx
index 4ffd573..dfa85ba 100644
--- a/src/content/docs/terminal/integrations-and-plugins.mdx
+++ b/src/content/docs/terminal/integrations-and-plugins.mdx
@@ -22,7 +22,7 @@ Select a container from the list and specify a shell type. Note, that only `bash
 
 <figure>
 ![Warp's extension for Docker lists available containers](../../../assets/terminal/docker-extension.png)
-<figcaption>Warp's extension for Docker lists available containers</figcaption>
+<figcaption>Warp's extension for Docker lists available containers.</figcaption>
 </figure>
 
 ## Raycast
@@ -42,7 +42,7 @@ Within `Raycast Settings > Extensions > Apps` search for Warp and assign the ali
 
 <figure>
 ![Raycast Terminal Tip](../../../assets/terminal/raycast-terminal-tip.png)
-<figcaption>Raycast Terminal Tip</figcaption>
+<figcaption>Raycast Terminal Tip.</figcaption>
 </figure>
 
 ## VSCode
diff --git a/src/content/docs/terminal/more-features/full-screen-apps.mdx b/src/content/docs/terminal/more-features/full-screen-apps.mdx
index 8c6123b..5905723 100644
--- a/src/content/docs/terminal/more-features/full-screen-apps.mdx
+++ b/src/content/docs/terminal/more-features/full-screen-apps.mdx
@@ -51,5 +51,5 @@ Some full-screen applications don't behave well when resizing. If you are experi
 
 <figure>
 ![alt-screen padding setting](../../../../assets/terminal/padding-settings.png)
-<figcaption>Alt-screen padding setting</figcaption>
+<figcaption>Alt-screen padding setting.</figcaption>
 </figure>
diff --git a/src/content/docs/terminal/more-features/markdown-viewer.mdx b/src/content/docs/terminal/more-features/markdown-viewer.mdx
index b0c1209..58be532 100644
--- a/src/content/docs/terminal/more-features/markdown-viewer.mdx
+++ b/src/content/docs/terminal/more-features/markdown-viewer.mdx
@@ -26,7 +26,7 @@ Warp can be used for both editing and viewing rendered Markdown files in a [spli
 
 <figure>
 ![Clicking a Markdown file link in the output of ls to open it in Warp](/assets/terminal/open-markdown-viewer.gif)
-<figcaption>Opening a Markdown file in Warp using the link tooltip</figcaption>
+<figcaption>Opening a Markdown file via link tooltip.</figcaption>
 </figure>
 
 ### Markdown-viewing commands
@@ -49,7 +49,7 @@ You can toggle between the Markdown editor and viewer via the pane overflow menu
 
 <figure>
 ![Clicking a Markdown file link in the output of ls to open it in Warp](/assets/terminal/markdown-raw-rendered-toggle.gif)
-<figcaption>Toggling between editor and viewer</figcaption>
+<figcaption>Toggling between editor and viewer.</figcaption>
 </figure>
 
 ## Shell commands in Markdown files
diff --git a/src/content/docs/terminal/more-features/settings-sync.mdx b/src/content/docs/terminal/more-features/settings-sync.mdx
index e0d5a0b..e429780 100644
--- a/src/content/docs/terminal/more-features/settings-sync.mdx
+++ b/src/content/docs/terminal/more-features/settings-sync.mdx
@@ -14,12 +14,12 @@ sidebar:
 
 <figure>
 ![Settings Sync in Account pane](../../../../assets/terminal/settings-sync-account.png)
-<figcaption>Settings Sync in Account pane</figcaption>
+<figcaption>Settings Sync in Account pane.</figcaption>
 </figure>
 
 <figure>
 ![Settings Sync in Command Palette](../../../../assets/terminal/settings-sync-palette.png)
-<figcaption>Settings Sync in Command Palette</figcaption>
+<figcaption>Settings Sync in Command Palette.</figcaption>
 </figure>
 
 ## How settings sync works
@@ -49,5 +49,5 @@ You can tell when a setting is not synced because it will have a special cloud s
 
 <figure>
 ![Settings not synced](../../../../assets/terminal/settings-not-synced.png)
-<figcaption>Settings not synced</figcaption>
+<figcaption>Settings not synced.</figcaption>
 </figure>
diff --git a/src/content/docs/terminal/windows/tab-configs.mdx b/src/content/docs/terminal/windows/tab-configs.mdx
index fffb196..35fc1a3 100644
--- a/src/content/docs/terminal/windows/tab-configs.mdx
+++ b/src/content/docs/terminal/windows/tab-configs.mdx
@@ -29,7 +29,7 @@ You can also capture a tab's current state as a reusable Tab Config without writ
 
 <figure>
 ![Tab context menu in Warp's vertical tabs panel with Save as new config highlighted](../../../../assets/terminal/save-new-tab-config.png)
-<figcaption>Save a tab config to recreate your multi-agent workspace with one click.</figcaption>
+<figcaption>Saving a tab config.</figcaption>
 </figure>
 
 ## Managing Tab Configs
@@ -42,7 +42,7 @@ Saved Tab Configs appear in the `+` menu for quick access. When you hover a Tab
 
 <figure>
 ![Warp's + menu open with a saved screenshots_tab_config entry highlighted, and a sidecar panel showing Make default, Edit config, and Remove action buttons](../../../../assets/terminal/saved-tab-config-menu.png)
-<figcaption>Saved Tab Configs appear in the + menu. Hover a config to reveal the sidecar panel with Make default, Edit config, and Remove actions.</figcaption>
+<figcaption>Tab config menu with sidecar options.</figcaption>
 </figure>
 
 ## Using skills to manage Tab Configs
diff --git a/src/content/docs/terminal/windows/vertical-tabs.mdx b/src/content/docs/terminal/windows/vertical-tabs.mdx
index b510493..c1f6885 100644
--- a/src/content/docs/terminal/windows/vertical-tabs.mdx
+++ b/src/content/docs/terminal/windows/vertical-tabs.mdx
@@ -43,7 +43,7 @@ The vertical tabs panel appears as a resizable sidebar on the left side of the w
 
 <figure>
 ![A Warp window with the vertical tabs sidebar on the left listing a Claude Code tab and a codex tab alongside the main terminal pane](../../../../assets/terminal/multi-agents.png)
-<figcaption>Each vertical tab shows the agent name, working directory, branch, and diff stats at a glance.</figcaption>
+<figcaption>Vertical tab with agent details.</figcaption>
 </figure>
 
 :::note
@@ -60,7 +60,7 @@ Compact mode is the default. Each pane row displays an icon and title on one lin
 
 <figure>
 ![Vertical tabs sidebar in compact mode with each pane row showing an icon, title, and a short subtitle below](../../../../assets/terminal/vertical-tabs-condensed.png)
-<figcaption>Compact mode keeps each pane row to a single line with a short subtitle for quick scanning.</figcaption>
+<figcaption>Vertical tabs in compact mode.</figcaption>
 </figure>
 
 ### Expanded mode
@@ -69,7 +69,7 @@ Expanded mode shows each pane row with a title, description (such as the working
 
 <figure>
 ![Vertical tab rows in expanded mode showing titles, working directories, Git branches, diff stats, and agent status badges](../../../../assets/terminal/vertical-tabs-multi-agent.png)
-<figcaption>Vertical tabs show which agent is running, the Git branch, and session status.</figcaption>
+<figcaption>Vertical tabs overview.</figcaption>
 </figure>
 
 ### Switching view modes
@@ -78,7 +78,7 @@ Click the settings icon (sliders) in the control bar at the top of the vertical
 
 <figure>
 ![The vertical tabs settings popup anchored to the sliders icon, showing View as, Density, Pane title as, Additional metadata, and Show details on hover options](../../../../assets/terminal/vertical-tab-settings.png)
-<figcaption>The settings popup lets you switch Density, customize pane titles and metadata, and toggle the hover detail sidecar.</figcaption>
+<figcaption>Vertical tabs settings popup.</figcaption>
 </figure>
 
 ## Customizing vertical tabs
@@ -119,7 +119,7 @@ Agent pane icons display a small circular badge overlay in the bottom-right corn
 
 <figure>
 ![Vertical tabs sidebar with four tab rows showing different agent status badges: a yellow blocked square, a magenta in-progress moon on the Claude Code brand icon, and green completion checks](../../../../assets/terminal/agent-status-badges.png)
-<figcaption>Pane icons in the vertical tabs panel carry a status badge overlay reflecting each agent's current state.</figcaption>
+<figcaption>Agent status badges on vertical tabs.</figcaption>
 </figure>
 
 Third-party CLI agents (Claude Code, Codex, Gemini CLI, and others) display their brand icon and color inside the circular pane icon, with the same status badge overlay.
@@ -161,7 +161,7 @@ Hover any pane row to open a floating detail card anchored to the right side of
 
 <figure>
 ![The vertical tabs panel with a Claude Code tab hovered, showing a floating detail card with the agent's In progress status, working directory, and session title](../../../../assets/terminal/tab-hover-detail-card.png)
-<figcaption>Hovering a pane row reveals a floating detail card with full metadata — without changing the focused pane.</figcaption>
+<figcaption>Hover detail card for a vertical tab.</figcaption>
 </figure>
 
 The sidecar stays open as you move the cursor from the row into the card. Move away from both the row and the sidecar to dismiss it. Disable this behavior with the **Show details on hover** toggle in the settings popup.

From 9c2ad646aa56e7124ad6efcb548244a8d707743f Mon Sep 17 00:00:00 2001
From: Rachael Rose Renk <91027132+rachaelrenk@users.noreply.github.com>
Date: Thu, 7 May 2026 14:52:16 -1000
Subject: [PATCH 5/5] 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>
---
 AGENTS.md                                            |  1 +
 .../docs/agent-platform/capabilities/rules.mdx       |  4 ++--
 .../agent-platform/capabilities/slash-commands.mdx   |  4 ++--
 .../docs/agent-platform/local-agents/generate.mdx    |  4 ++--
 .../docs/getting-started/keyboard-shortcuts.mdx      |  2 +-
 .../knowledge-and-collaboration/warp-drive/index.mdx | 12 ++++++------
 .../warp-drive/notebooks.mdx                         | 10 +++++-----
 .../warp-drive/workflows.mdx                         |  4 ++--
 .../troubleshooting-and-support/known-issues.mdx     |  4 ++--
 .../sending-us-feedback.mdx                          |  2 +-
 src/content/docs/terminal/editor/index.mdx           |  2 +-
 src/content/docs/terminal/entry/command-history.mdx  |  2 +-
 .../docs/terminal/integrations-and-plugins.mdx       |  2 +-
 .../docs/terminal/more-features/full-screen-apps.mdx |  2 +-
 .../docs/terminal/more-features/settings-sync.mdx    |  2 +-
 15 files changed, 29 insertions(+), 28 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 98cf2b7..d3ad135 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -182,6 +182,7 @@ Captions orient the reader — they identify what the image shows so the reader
 
 **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.
diff --git a/src/content/docs/agent-platform/capabilities/rules.mdx b/src/content/docs/agent-platform/capabilities/rules.mdx
index 7b80182..868c101 100644
--- a/src/content/docs/agent-platform/capabilities/rules.mdx
+++ b/src/content/docs/agent-platform/capabilities/rules.mdx
@@ -120,12 +120,12 @@ When relevant, Agents automatically pull in applicable rules to guide their resp
 
 <figure>
 ![Context derived from memory](../../../../assets/agent-platform/context-derived-from-memory.png)
-<figcaption>Derived from rules.</figcaption>
+<figcaption>An agent response showing which rules were applied.</figcaption>
 </figure>
 
 <figure>
 ![Context derived from memory](../../../../assets/agent-platform/context-references-memory.png)
-<figcaption>Rules as references.</figcaption>
+<figcaption>Rules listed as references in an agent conversation.</figcaption>
 </figure>
 
 ### Rules privacy
diff --git a/src/content/docs/agent-platform/capabilities/slash-commands.mdx b/src/content/docs/agent-platform/capabilities/slash-commands.mdx
index 9eef9ef..e3a2d51 100644
--- a/src/content/docs/agent-platform/capabilities/slash-commands.mdx
+++ b/src/content/docs/agent-platform/capabilities/slash-commands.mdx
@@ -47,10 +47,10 @@ Below is an example interaction when `/init` is run:
 
 <figure>
 ![/init setup flow; 1 of 2](../../../../assets/agent-platform/init-setup-flow-1.png)
-<figcaption>/init setup flow; 1 of 2.</figcaption>
+<figcaption>The /init setup flow, step 1 of 2.</figcaption>
 </figure>
 
 <figure>
 ![/init setup flow; 2 of 2](../../../../assets/agent-platform/init-setup-flow-2.png)
-<figcaption>/init setup flow; 2 of 2.</figcaption>
+<figcaption>The /init setup flow, step 2 of 2.</figcaption>
 </figure>
diff --git a/src/content/docs/agent-platform/local-agents/generate.mdx b/src/content/docs/agent-platform/local-agents/generate.mdx
index f93b9ee..55cf500 100644
--- a/src/content/docs/agent-platform/local-agents/generate.mdx
+++ b/src/content/docs/agent-platform/local-agents/generate.mdx
@@ -47,12 +47,12 @@ In interactive CLI applications, you can generate input using natural language.
 
 <figure>
 ![Generate a SQL query](../../../../assets/agent-platform/generate-psql.png)
-<figcaption>Generate a SQL query.</figcaption>
+<figcaption>Generating a SQL query using natural language.</figcaption>
 </figure>
 
 <figure>
 ![Generate Vim input](../../../../assets/agent-platform/generate-vim.png)
-<figcaption>Generate Vim input.</figcaption>
+<figcaption>Generating Vim commands using natural language.</figcaption>
 </figure>
 
 <Tabs>
diff --git a/src/content/docs/getting-started/keyboard-shortcuts.mdx b/src/content/docs/getting-started/keyboard-shortcuts.mdx
index 31bd7ac..4308ad7 100644
--- a/src/content/docs/getting-started/keyboard-shortcuts.mdx
+++ b/src/content/docs/getting-started/keyboard-shortcuts.mdx
@@ -25,7 +25,7 @@ Keybinds that conflict with others are highlighted with an orange border.
 
 <figure>
 ![keybinds that conflict with others are highlighted in orange](../../../assets/terminal/keybinds-conflict.png)
-<figcaption>Keybind Conflict Example.</figcaption>
+<figcaption>An example of a keybinding conflict warning.</figcaption>
 </figure>
 
 ## All available shortcuts
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
index 6b1dd5e..8ac2546 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/index.mdx
@@ -30,7 +30,7 @@ All objects stored in Warp Drive sync immediately as they’re updated, so you a
 
 <figure>
 ![Warp Drive icon on top left corner of Warp](../../../../assets/terminal/Open_Warp_Drive.png)
-<figcaption>Warp Drive Icon.</figcaption>
+<figcaption>The Warp Drive icon in the top-left corner.</figcaption>
 </figure>
 
 ## Workspaces in Warp Drive
@@ -56,7 +56,7 @@ In offline mode, some files will be read-only. You can still create and edit fil
 
 <figure>
 ![Warp Drive offline mode](../../../../assets/terminal/warp_drive_offline.png)
-<figcaption>Warp Drive offline mode.</figcaption>
+<figcaption>Warp Drive operating in offline mode.</figcaption>
 </figure>
 
 ## Navigating Warp Drive with your keyboard
@@ -97,7 +97,7 @@ You can take these keyboard actions within Warp Drive:
 
 <figure>
 ![Warp Drive navigation states](../../../../assets/terminal/warp_drive_nav1.png)
-<figcaption>Warp Drive navigation states.</figcaption>
+<figcaption>Navigation states in the Warp Drive sidebar.</figcaption>
 </figure>
 
 To switch between panels using your keyboard, you can use the “Switch Focus to Left Panel” and “Switch Focus to Right Panel” commands in the [Command Palette](/terminal/command-palette/).
@@ -119,7 +119,7 @@ To import a local file or directory, `RIGHT-CLICK` on a folder or click **+** on
 
 <figure>
 ![Import modal](../../../../assets/terminal/notebook-import-modal.png)
-<figcaption>Import modal.</figcaption>
+<figcaption>The import dialog for adding local files to Warp Drive.</figcaption>
 </figure>
 
 ### Exporting files from Warp Drive
@@ -144,7 +144,7 @@ To access an object, link-followers must have permission to open it through one
 
 <figure>
 ![Copy link Menu Item](../../../../assets/terminal/wd-copy-link-menu.png)
-<figcaption>Copy link Menu Item.</figcaption>
+<figcaption>The Copy link option in the right-click menu.</figcaption>
 </figure>
 
 ### Managing permissions
@@ -153,7 +153,7 @@ To manage a Drive object's permissions, navigate to its overflow menu and choose
 
 <figure>
 ![The pane header for a notebook, with the share button circled](../../../../assets/terminal/wd-share-button.png)
-<figcaption>Pane header share button.</figcaption>
+<figcaption>The share button in the pane header.</figcaption>
 </figure>
 
 This opens a dialog that lists the current sharing settings and allows you to change them:
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
index 9719284..8259d96 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/notebooks.mdx
@@ -56,7 +56,7 @@ Notebook elements (text, code, list items) can be added in several ways:
 
 <figure>
 ![Markdown element types](../../../../assets/terminal/markdown-element-types.png)
-<figcaption>Markdown element types.</figcaption>
+<figcaption>Available Markdown element types in the Notebook editor.</figcaption>
 </figure>
 
 #### Styling existing elements
@@ -80,7 +80,7 @@ Once you’ve inserted your code block you can select the language at the bottom
 
 <figure>
 ![Example code block](../../../../assets/terminal/notebook-code-block.png)
-<figcaption>Example code block.</figcaption>
+<figcaption>A code block with syntax highlighting in a Notebook.</figcaption>
 </figure>
 
 #### Special properties of command blocks
@@ -110,7 +110,7 @@ The command text will be inserted into the developer’s active terminal session
 
 <figure>
 ![Run option for command block](../../../../assets/terminal/notebook-cmd-block-run.png)
-<figcaption>Run option for command block.</figcaption>
+<figcaption>The run button on a command block in a Notebook.</figcaption>
 </figure>
 
 #### Adding arguments to Command Blocks
@@ -119,7 +119,7 @@ Command blocks accept parameters in the same format as [Workflows](/knowledge-an
 
 <figure>
 ![Command block with parameters](../../../../assets/terminal/notebook-cmd-with-params.png)
-<figcaption>Command block with parameters.</figcaption>
+<figcaption>A command block with editable parameters.</figcaption>
 </figure>
 
 #### Navigating command blocks with the keyboard
@@ -166,7 +166,7 @@ Note that only one editor is allowed at a given time. Opening the notebook while
 
 <figure>
 ![View mode example](../../../../assets/terminal/notebook-view-mode.png)
-<figcaption>View mode example.</figcaption>
+<figcaption>A Notebook displayed in view mode.</figcaption>
 </figure>
 
 ### Import and export notebooks in Warp Drive
diff --git a/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx b/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
index a3e9fb4..baf7b73 100644
--- a/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
+++ b/src/content/docs/knowledge-and-collaboration/warp-drive/workflows.mdx
@@ -76,7 +76,7 @@ Once a workflow has been created, you can edit it at any time, as long as you ha
 
 <figure>
 ![Edit workflow menu](../../../../assets/terminal/Edit_Workflow.png)
-<figcaption>Edit workflow menu.</figcaption>
+<figcaption>The edit menu for a Workflow in Warp Drive.</figcaption>
 </figure>
 
 #### AI Autofill
@@ -118,7 +118,7 @@ These options will paste the workflow into your active terminal input. Workflow
 
 <figure>
 ![Execute a Workflow](../../../../assets/terminal/execute-a-workflow.png)
-<figcaption>Execute a Workflow.</figcaption>
+<figcaption>Executing a Workflow from Warp Drive.</figcaption>
 </figure>
 
 You make any adjustments you need to the arguments (or the command itself) before running the command in your input editor.
diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx
index 9eee528..f221d31 100644
--- a/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx
+++ b/src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx
@@ -217,7 +217,7 @@ The following non-exhaustive list of plugins, prompts, or tools can cause potent
 
     <figure>
     ![macOS SSH permission error](../../../../assets/support-and-community/mac-ssh-permission.png)
-    <figcaption>macOS SSH permission error.</figcaption>
+    <figcaption>An SSH permission error on macOS.</figcaption>
     </figure>
 
     **Unexpected loss of permission on macOS**
@@ -226,7 +226,7 @@ The following non-exhaustive list of plugins, prompts, or tools can cause potent
 
     <figure>
     ![Permission error on macOS](../../../../assets/support-and-community/permission-error-macos.png)
-    <figcaption>Permission error on macOS.</figcaption>
+    <figcaption>A file permission error dialog on macOS.</figcaption>
     </figure>
 
     **Auto-Update error on macOS**
diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx
index ffae5dd..6d0e0d9 100644
--- a/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx
+++ b/src/content/docs/support-and-community/troubleshooting-and-support/sending-us-feedback.mdx
@@ -226,7 +226,7 @@ Collect a sample using the steps for your platform and attach it to a new [GitHu
 
     <figure>
     ![Sampling the Warp process in Activity Monitor](../../../../assets/support-and-community/activity-monitor-sample-process.png)
-    <figcaption>Sample Process in Activity Monitor.</figcaption>
+    <figcaption>Sampling a Warp process in Activity Monitor.</figcaption>
     </figure>
 
     3. Save the resulting sample and attach it to your GitHub issue.
diff --git a/src/content/docs/terminal/editor/index.mdx b/src/content/docs/terminal/editor/index.mdx
index e8392c2..9649b96 100644
--- a/src/content/docs/terminal/editor/index.mdx
+++ b/src/content/docs/terminal/editor/index.mdx
@@ -47,5 +47,5 @@ Warp can automatically complete quotes, brackets, and parentheses like you're us
 
 <figure>
 ![soft wrapping text in Warp input editor](../../../../assets/terminal/soft-wrapping.png)
-<figcaption>Soft Wrapping Demo.</figcaption>
+<figcaption>Soft wrapping applied to long lines in the editor.</figcaption>
 </figure>
diff --git a/src/content/docs/terminal/entry/command-history.mdx b/src/content/docs/terminal/entry/command-history.mdx
index 681a446..1f9d705 100644
--- a/src/content/docs/terminal/entry/command-history.mdx
+++ b/src/content/docs/terminal/entry/command-history.mdx
@@ -15,7 +15,7 @@ Command History also provides rich information like exit code, directory, thread
 
 <figure>
 ![Command History rich information](../../../../assets/terminal/command-history-rich.png)
-<figcaption>Command History rich information.</figcaption>
+<figcaption>Command history with rich metadata.</figcaption>
 </figure>
 
 ## How to access it
diff --git a/src/content/docs/terminal/integrations-and-plugins.mdx b/src/content/docs/terminal/integrations-and-plugins.mdx
index dfa85ba..1f77434 100644
--- a/src/content/docs/terminal/integrations-and-plugins.mdx
+++ b/src/content/docs/terminal/integrations-and-plugins.mdx
@@ -42,7 +42,7 @@ Within `Raycast Settings > Extensions > Apps` search for Warp and assign the ali
 
 <figure>
 ![Raycast Terminal Tip](../../../assets/terminal/raycast-terminal-tip.png)
-<figcaption>Raycast Terminal Tip.</figcaption>
+<figcaption>Warp integration with the Raycast launcher.</figcaption>
 </figure>
 
 ## VSCode
diff --git a/src/content/docs/terminal/more-features/full-screen-apps.mdx b/src/content/docs/terminal/more-features/full-screen-apps.mdx
index 5905723..2aa78d4 100644
--- a/src/content/docs/terminal/more-features/full-screen-apps.mdx
+++ b/src/content/docs/terminal/more-features/full-screen-apps.mdx
@@ -51,5 +51,5 @@ Some full-screen applications don't behave well when resizing. If you are experi
 
 <figure>
 ![alt-screen padding setting](../../../../assets/terminal/padding-settings.png)
-<figcaption>Alt-screen padding setting.</figcaption>
+<figcaption>The alt-screen padding setting in appearance preferences.</figcaption>
 </figure>
diff --git a/src/content/docs/terminal/more-features/settings-sync.mdx b/src/content/docs/terminal/more-features/settings-sync.mdx
index e429780..4adf705 100644
--- a/src/content/docs/terminal/more-features/settings-sync.mdx
+++ b/src/content/docs/terminal/more-features/settings-sync.mdx
@@ -49,5 +49,5 @@ You can tell when a setting is not synced because it will have a special cloud s
 
 <figure>
 ![Settings not synced](../../../../assets/terminal/settings-not-synced.png)
-<figcaption>Settings not synced.</figcaption>
+<figcaption>Indicator showing settings are not synced.</figcaption>
 </figure>