May AEO docs updates

.agents/skills/style_lint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: style_lint
-description: Scan Warp Astro Starlight documentation for style guide violations including formatting issues (Settings path format, UI element format, header case, missing frontmatter, image alt text, callout syntax) and terminology issues (product name casing, Oz terms to avoid, deprecated terms). Run with --changed for PR workflows or --all for periodic audits. Optionally auto-fix high-confidence issues with --fix.
+description: Scan Warp Astro Starlight documentation for style guide violations including formatting issues (Settings path format, UI element format, header case, missing frontmatter, image alt text, standardized screenshot widths, callout syntax) and terminology issues (product name casing, Oz terms to avoid, deprecated terms). Run with --changed for PR workflows or --all for periodic audits. Optionally auto-fix high-confidence issues with --fix.
 ---
 
 # Style Lint
@@ -46,6 +46,7 @@ python3 .warp/skills/style_lint/style_lint.py --all --fix --create-pr
 - **Header case**: Title Case in H2/H3/H4 headers (should be sentence case, with exceptions for proper feature names)
 - **Missing frontmatter**: Pages without YAML `description` field
 - **Image alt text**: `<img>` or `<figure>` without alt text or with generic alt text ("screenshot", "image")
+- **Screenshot widths**: Likely UI/product screenshots must use `<figure style={{ maxWidth: "..." }}>` with a standard width (`300px`, `350px`, `375px`, or `563px`)
 - **Callout syntax**: Leftover GitBook `{% hint %}` tags that should be migrated to Starlight `:::note` / `:::caution` / `:::danger` asides
 - **List format**: Bulleted feature/capability lists missing the bold term + dash pattern (report only, never auto-fixed)
 

.agents/skills/style_lint/style_lint.py

@@ -92,6 +92,31 @@
 
 TERMINOLOGY_FILE = Path(".warp/references/terminology.md")
 
+STANDARD_SCREENSHOT_WIDTHS = {"300px", "350px", "375px", "563px"}
+
+SCREENSHOT_PATH_HINTS = (
+    "/assets/",
+    "../../assets/",
+    "../../../assets/",
+    "../../../../assets/",
+    "../../../../../assets/",
+    ".png",
+    ".gif",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+)
+
+NON_SCREENSHOT_HINTS = (
+    "architecture",
+    "diagram",
+    "flowchart",
+    "infra",
+    "infrastructure",
+    "logo",
+    "use-cases",
+)
+
 # Common bolded words that are NOT product terms (false positive suppression)
 COMMON_BOLD_WORDS = {
     # General emphasis words
@@ -333,6 +358,84 @@ def check_image_alt_text(lines: List[str], filepath: str) -> List[Issue]:
     return issues
 
 
+def _is_likely_screenshot(markdown_image_line: str) -> bool:
+    """Return True for UI/product screenshots while avoiding diagrams/logos."""
+    lower = markdown_image_line.lower()
+    if not any(hint in lower for hint in SCREENSHOT_PATH_HINTS):
+        return False
+    if any(hint in lower for hint in NON_SCREENSHOT_HINTS):
+        return False
+    return True
+
+
+def _figure_width(line: str) -> Optional[str]:
+    """Extract a maxWidth value from an MDX figure opening tag."""
+    match = re.search(r"maxWidth:\s*[\"']([^\"']+)[\"']", line)
+    if match:
+        return match.group(1)
+    return None
+
+
+def check_screenshot_widths(lines: List[str], filepath: str) -> List[Issue]:
+    """Check that screenshot images use standardized width-controlled figures.
+
+    The docs style guide asks screenshots to use consistent widths. This check
+    flags likely UI/product screenshots that are standalone Markdown images or
+    figure-wrapped images missing a standard maxWidth. Architecture diagrams,
+    logos, and broad conceptual illustrations are intentionally excluded by
+    filename/alt-text hints because they often need default content width.
+    """
+    issues = []
+    in_code_block = False
+    figure_start_line: Optional[int] = None
+    figure_opening = ""
+    figure_has_likely_screenshot = False
+
+    for i, line in enumerate(lines, 1):
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_code_block = not in_code_block
+            continue
+        if in_code_block:
+            continue
+
+        if "<figure" in line:
+            figure_start_line = i
+            figure_opening = line
+            figure_has_likely_screenshot = False
+
+        if "![" in line and _is_likely_screenshot(line):
+            if figure_start_line is None:
+                issues.append(Issue(
+                    filepath, i, "screenshot-width",
+                    "Likely screenshot image should be wrapped in a <figure> with a standard maxWidth (300px, 350px, 375px, or 563px)",
+                    "warning",
+                ))
+            else:
+                figure_has_likely_screenshot = True
+
+        if "</figure>" in line and figure_start_line is not None:
+            if figure_has_likely_screenshot:
+                width = _figure_width(figure_opening)
+                if width is None:
+                    issues.append(Issue(
+                        filepath, figure_start_line, "screenshot-width",
+                        "Screenshot figure is missing a standard maxWidth (300px, 350px, 375px, or 563px)",
+                        "warning",
+                    ))
+                elif width not in STANDARD_SCREENSHOT_WIDTHS:
+                    issues.append(Issue(
+                        filepath, figure_start_line, "screenshot-width",
+                        f"Screenshot figure uses non-standard maxWidth \"{width}\"; use one of {', '.join(sorted(STANDARD_SCREENSHOT_WIDTHS))}",
+                        "warning",
+                    ))
+            figure_start_line = None
+            figure_opening = ""
+            figure_has_likely_screenshot = False
+
+    return issues
+
+
 def check_callout_syntax(lines: List[str], filepath: str) -> List[Issue]:
     """Check for malformed hint/callout syntax."""
     issues = []
@@ -561,6 +664,7 @@ def run_all_checks(filepath: Path) -> List[Issue]:
     issues.extend(check_ui_element_backticks(lines, str(filepath)))
     issues.extend(check_header_case(lines, str(filepath)))
     issues.extend(check_image_alt_text(lines, str(filepath)))
+    issues.extend(check_screenshot_widths(lines, str(filepath)))
     issues.extend(check_callout_syntax(lines, str(filepath)))
     issues.extend(check_product_casing(lines, str(filepath)))
     issues.extend(check_oz_terms(lines, str(filepath)))

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

@@ -1,7 +1,7 @@
 ---
 title: Model Context Protocol (MCP)
 description: >-
-  Configure MCP servers in the Warp desktop app to extend local agents with
+  Configure MCP servers in the Warp app to extend local agents with
   custom tools and data sources through a standardized interface.
 ---
 import { Tabs, TabItem } from '@astrojs/starlight/components';
@@ -12,7 +12,7 @@ MCP servers extend Warp's [local agents](/agent-platform/local-agents/interactin
 MCP is an open source protocol. Check out the official [MCP documentation](https://modelcontextprotocol.io/introduction) for more detailed information on how this protocol is engineered.
 
 :::note
-This page covers MCP servers for local agents in the Warp desktop app. If you're using cloud agents, see [MCP Servers for cloud agents](/agent-platform/cloud-agents/mcp/).
+This page covers MCP servers for local agents in the Warp app. For help choosing between local, cloud, and shared MCP workflows, see [Connect developer tools to agents with MCP workflows](/guides/external-tools/using-mcp-servers-with-warp/). If you're using cloud agents, see [MCP Servers for cloud agents](/agent-platform/cloud-agents/mcp/).
 :::
 
 ### How to access MCP Server settings
@@ -26,7 +26,7 @@ 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>
+<figure style={{ maxWidth: "563px" }}>
 ![MCP servers page](../../../../assets/agent-platform/mcp-servers-list.png)
 <figcaption>MCP servers page.</figcaption>
 </figure>
@@ -41,7 +41,7 @@ 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>
+    <figure style={{ maxWidth: "375px" }}>
     ![Adding a CLI MCP Server (Command)](../../../../assets/agent-platform/mcp-servers-add-cli.png)
     <figcaption>Adding a CLI MCP Server (Command).</figcaption>
     </figure>
@@ -62,7 +62,7 @@ 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>
+    <figure style={{ maxWidth: "375px" }}>
     ![Adding an SSE MCP Server (URL)](../../../../assets/agent-platform/mcp-servers-add-sse.png)
     <figcaption>Adding an SSE MCP Server (URL).</figcaption>
     </figure>
@@ -134,7 +134,10 @@ To auto-spawn global servers from third-party agents:
 1. In the Warp app, go to **Settings** > **Agents** > **MCP servers**.
 2. Toggle **Auto-spawn servers from third-party agents** on.
 
+<figure style={{ maxWidth: "375px" }}>
 ![Toggle to auto-spawn global file-based MCP servers](/assets/agent-platform/file-based-mcp-setting.png)
+<figcaption>File-based MCP server settings.</figcaption>
+</figure>
 
 Project-scoped servers from any provider must be toggled on individually from the MCP servers page. These are session-scoped — after restarting Warp, toggle them on again if you still trust the repo.
 
@@ -170,7 +173,7 @@ 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>
+<figure style={{ maxWidth: "375px" }}>
 ![Sharing a MCP Server](../../../../assets/agent-platform/mcp-servers-share.png)
 <figcaption>Sharing a MCP Server.</figcaption>
 </figure>

src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx

@@ -114,6 +114,8 @@ When a task is naturally divisible, use [multi-agent orchestration](/agent-platf
 
 Use this when you need to control where agent execution happens while still using Oz orchestration and visibility. Repositories are cloned and stored only on your infrastructure; orchestration metadata, session transcripts, and LLM inference route through Warp's backend under [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr).
 
+Think of self-hosted execution as **customer-hosted execution with Warp-hosted orchestration**, not as a fully offline agent stack. Code repositories, build artifacts, runtime secrets, and execution workspaces stay on your infrastructure. Code context can still appear in session transcripts and LLM prompts as the agent works.
+
 :::note
 **Enterprise feature**: Self-hosted execution is available exclusively to teams on an Enterprise plan.
 :::

src/content/docs/agent-platform/cloud-agents/handoff/cloud-to-cloud.mdx

@@ -17,7 +17,7 @@ Watch this walkthrough to see how cloud-to-cloud handoff continues a cloud agent
 Use this handoff direction when:
 
 * You want to send a follow-up to a cloud agent after its session has ended.
-* You want to continue a background cloud agent run, such as a scheduled or integration-triggered run, while preserving it as a single unit of work in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/).
+* You want to continue a background cloud agent run, such as a scheduled or integration-triggered run, while preserving it as a single unit of work in the [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs).
 
 ## What carries over
 
@@ -58,9 +58,9 @@ Cloud-to-cloud handoff also works for supported third-party agent runtimes, but
 
 ## Inspecting a run that's been handed off
 
-The [management view](/agent-platform/cloud-agents/managing-cloud-agents/) shows one row per run, even when the run spans multiple sessions.
+The [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app and the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs) show one row per run, even when the run spans multiple sessions.
 
-1. Open the [management view](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app or Oz web app.
+1. Open the [Agent Management Panel](/agent-platform/cloud-agents/managing-cloud-agents/) in the Warp app or the [Runs page in the Oz web app](/agent-platform/cloud-agents/oz-web-app/#runs).
 2. Select the handed-off run.
 3. Review the transcript. Each session appears in order, so you can see where one session ended and the next began.
 

src/content/docs/agent-platform/cloud-agents/handoff/index.mdx

@@ -50,7 +50,7 @@ Each direction has a clear motivating workflow.
 ## Related pages
 
 * [Cloud agents overview](/agent-platform/cloud-agents/overview/) - What cloud agents are, when to use them, and how they fit into the Oz Platform.
-* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the management view alongside local conversations.
+* [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Inspect handoff runs from the Agent Management Panel in the Warp app or the Runs page in the Oz web app alongside local conversations.
 * [Viewing cloud agent runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) - Open and continue a cloud run locally with **Continue locally** or `/continue-locally`.
 * [Cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) - How conversations sync between local and cloud so handoff can find them.
 * [Environments](/agent-platform/cloud-agents/environments/) - The runtime context a cloud agent runs in after a handoff.

src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx

@@ -11,9 +11,9 @@ import VideoEmbed from '@components/VideoEmbed.astro';
 
 Oz can run third-party agent harnesses as cloud agents alongside Warp Agent, including [Claude Code](/agent-platform/cloud-agents/harnesses/claude-code/) and [Codex](/agent-platform/cloud-agents/harnesses/codex/). You choose the harness (agent runtime) that fits the task; the platform around the run stays the same.
 
-Watch this walkthrough to see how to run Warp Agent, Claude Code, or Codex as an Oz cloud agent.
+Watch this walkthrough to see how to run Warp Agent, Claude Code, or Codex as a cloud agent.
 
-<VideoEmbed url="https://www.youtube.com/watch?v=ZUYyuA5i1VU" title="How to run any agent in the cloud with Oz - Claude Code, Codex, or the Warp Agent" />
+<VideoEmbed url="https://www.youtube.com/watch?v=ZUYyuA5i1VU" title="Run any agent in the cloud with Oz - Claude Code, Codex, or Warp Agent" />
 
 ## What stays the same
 
@@ -30,7 +30,7 @@ Claude Code and Codex each call their provider directly using credentials you su
 
 ## How to switch harnesses
 
-### Warp desktop app
+### Warp app
 
 In Cloud Mode, choose a harness from the **Agent harness** dropdown above the input.
 

src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx

@@ -12,6 +12,8 @@ Run agents directly in your GitHub Actions workflows using `oz-agent-action`. Th
 **Getting started?** See the [GitHub Actions quickstart](/agent-platform/cloud-agents/integrations/quickstart-github-actions/) to set up your first workflow, or visit the [oz-agent-action repository](https://github.com/warpdotdev/oz-agent-action) for detailed setup instructions and ready-to-use workflow templates.
 :::
 
+If you're comparing GitHub Actions with schedules, Slack, Linear, the Oz CLI, or API-triggered runs, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/).
+
 Watch this demo to see the integration in action:
 
 <VideoEmbed url="https://www.loom.com/share/534f88b6a98e43ca9769ca09de6424b5" />

src/content/docs/agent-platform/cloud-agents/integrations/index.mdx

@@ -13,6 +13,8 @@ Warp integrations let your team trigger agents directly from the terminal, or fr
 * Run code inside your codebase in a remote environment
 * Open pull requests and perform other multi-step agent workflows on your behalf
 
+If you're deciding whether an agent should run from a schedule, Slack or Linear, GitHub Actions, the Oz CLI, or the API, see [Run agents unattended with schedules and triggers](/guides/agent-workflows/how-to-run-unattended-agents/).
+
 :::note
 For a full walkthrough of Warp's integrations and configurable environments, please refer to [Integration setup](/reference/cli/integration-setup/).
 :::