May AEO docs updates

[rachaelrenk]

Summary

This PR implements the May AEO docs content updates by turning Peec findings into answer-first docs improvements for Warp agents. It adds two new workflow guides, expands or refines existing source docs, and adds cross-links so users and AI answer engines can connect observability, PR review context, unattended runs, self-hosting data boundaries, MCP workflows, and multi-agent coordination.

Content model note

The AEO work is intentionally integrated into the docs' existing content models rather than appended as standalone sections. Follow-up feedback tightened the self-hosting locality/security copy by folding answer-first language into the overview intro, How self-hosting works, and Data boundaries, softened broad audit wording into review/inspection language, and strengthened real-time observability framing in Managing cloud agents without turning the page into a generic APM/OpenTelemetry article.

High-level overview of changes by area

Navigation

• src/sidebar.ts — Adds the new Agent workflows guides for attaching agent context to PRs and running unattended agents so they are discoverable from the docs sidebar.

Agent observability and session sharing

• src/content/docs/agent-platform/cloud-agents/overview.mdx — Adds answer-first guidance for monitoring, inspecting, and sharing cloud agent runs, including what run records and transcripts contain.
• src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.mdx — Strengthens the management view docs with explicit “track and observe agent activity in real time” language; active/running status; source, trigger, and owner context; parent/child run visibility; prompt, plan, commands, logs, outputs, and session links; and a clear boundary that Warp observability is run/session-oriented rather than full APM/OpenTelemetry-style tracing.
• src/content/docs/agent-platform/cloud-agents/viewing-cloud-agent-runs.mdx — Positions cloud agent session sharing as the review surface for cloud runs and adds links to management, PR context, and local session-sharing docs.
• src/content/docs/agent-platform/local-agents/session-sharing.mdx — Expands Agent Session Sharing guidance around reviewing local or third-party agent work, including what shared sessions can expose.

PR review and agent session context

• src/content/docs/guides/agent-workflows/how-to-attach-agent-session-context-to-github-prs.mdx — Adds a new guide for attaching Warp agent session or cloud run links to GitHub PRs, including a PR summary template, review workflow, reviewer checklist, and sensitive-context guidance.
• src/content/docs/code/code-review.mdx — Adds a tip directing PR reviewers to include shared agent session or cloud run links when reviewing agent-generated diffs.
• src/content/docs/agent-platform/local-agents/interactive-code-review.mdx — Adds the new PR session-context guide as a next step from local interactive code review.
• src/content/docs/guides/agent-workflows/how-to-review-ai-generated-code.mdx — Adds a cross-link from the AI-generated code review workflow to the new PR session-context guide.

Unattended and triggered cloud agents

• src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx — Adds a new guide for choosing between schedules, Slack, Linear, GitHub Actions, the Oz CLI, and the Oz API; also covers setup requirements, inspection surfaces, and review paths.
• src/content/docs/agent-platform/cloud-agents/triggers/index.mdx — Adds a decision-oriented link from trigger docs to the unattended agents guide.
• src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.mdx — Adds guidance for comparing scheduled agents with other unattended trigger types.
• src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart.mdx — Adds a next step that points users to the broader unattended-trigger comparison guide.
• src/content/docs/agent-platform/cloud-agents/integrations/index.mdx — Adds a cross-link from integrations to the unattended agents guide for users deciding where an agent should run from.
• src/content/docs/agent-platform/cloud-agents/integrations/github-actions.mdx — Adds a cross-link that frames GitHub Actions as one unattended trigger option among schedules, Slack, Linear, CLI, and API workflows.

Self-hosted execution, security, and data boundaries

• src/content/docs/agent-platform/cloud-agents/self-hosting/index.mdx — Integrates source-code and execution-locality language into the overview intro and How self-hosting works, clarifying split-plane architecture without adding a standalone AEO-only section.
• src/content/docs/agent-platform/cloud-agents/self-hosting/security-and-networking.mdx — Strengthens the existing Data boundaries section with a concise answer about what stays on customer infrastructure and what routes through Warp.
• src/content/docs/agent-platform/cloud-agents/deployment-patterns.mdx — Adds plain-language framing that self-hosted execution is customer-hosted execution with Warp-hosted orchestration, not a fully offline agent stack.
• src/content/docs/enterprise/security-and-compliance/security-overview.mdx — Adds self-hosted cloud agent execution to ZDR/data-boundary language and clarifies BYOLLM data-locality wording.

MCP workflows and source-doc links

• src/content/docs/guides/external-tools/using-mcp-servers-with-warp.mdx — Reworks the guide into an answer-first MCP workflows entry point covering local agents, third-party CLI agents, cloud agents, repeatable automation, shared MCP servers, security checks, and example developer tools.
• src/content/docs/agent-platform/capabilities/mcp.mdx — Adds a link from local MCP setup docs to the workflow-oriented MCP guide.
• src/content/docs/agent-platform/cloud-agents/mcp.mdx — Adds the workflow guide to the cloud MCP related links.
• src/content/docs/reference/cli/mcp-servers.mdx — Adds the workflow guide as the conceptual entry point for choosing local, cloud, shared, and repeatable MCP setup paths.

Multi-agent coordination, orchestration, and handoff

• src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx — Expands the guide from local parallel tabs into a broader coordination workflow covering task ownership, worktrees, cloud orchestration, validation, merge strategy, and PR handoff.
• src/content/docs/guides/agent-workflows/running-multiple-agents-at-once-with-warp.mdx — Adds a cross-link to the expanded multi-agent workflow guide.
• src/content/docs/agent-platform/cloud-agents/orchestration/index.mdx — Adds the expanded multi-agent guide as a practical related page for task splitting, worktrees, validation, and handoff.
• src/content/docs/agent-platform/cloud-agents/orchestration/multi-agent-runs.mdx — Adds the expanded multi-agent guide as the practical follow-up to orchestrated run launch docs.

Mapping to Notion item(s)

Parent item: May AEO docs content

Sub-items covered:

• Docs: Observe and audit agent runs via management and session sharing — Covered by the cloud agent overview, strengthened management view, cloud run sharing, and local Agent Session Sharing updates.
• Docs: Attach agent context to PRs via session sharing — Covered by the new PR session-context guide plus cross-links from code review, interactive code review, and AI-generated code review docs.
• Docs: Coordinate multiple AI agents across local, cloud, and orchestration — Covered by the expanded multi-agent guide and orchestration-related source-doc cross-links.
• Docs: Run agents unattended with schedules, triggers, and cloud runs — Covered by the new unattended agents guide and updates across triggers, scheduled agents, integrations, and GitHub Actions docs.
• Docs: Self-hosted agent source-code locality and data boundaries — Covered by self-hosting, security/networking, deployment patterns, and security overview updates.
• Docs: Connect developer tools to agents with MCP workflows — Covered by the reworked MCP workflow guide and links from local MCP, cloud MCP, and CLI MCP reference pages.
• Docs tweaks: Agent run observability surfaces — Covered by source-doc refinements to cloud agent overview, managing cloud agents, viewing cloud agent runs, and Agent Session Sharing.
• Docs tweaks: Unattended scheduled and triggered agents — Covered by source-doc refinements to triggers, scheduled agents, scheduled agent quickstart, integrations, and GitHub Actions.
• Docs tweaks: Self-hosting security and data-boundary language — Covered by source-doc refinements to self-hosting, security/networking, deployment patterns, and enterprise security overview.
• Docs tweaks: MCP workflow examples and local-vs-cloud setup — Covered by the MCP workflow guide rework and supporting links from MCP source/reference pages.
• Docs tweaks: Multi-agent coordination and review handoff — Covered by the expanded multi-agent guide, orchestration cross-links, and PR/review handoff docs.

Validation

• git diff --check passed after the latest real-time observability update.
• npm --prefix /Users/rachaelrenk/Documents/Warp/docs run typecheck passed with 0 errors after the guide rename and observability update.
• npm --prefix /Users/rachaelrenk/Documents/Warp/docs run build passed earlier in the PR and built 336 pages.
• npm --prefix /Users/rachaelrenk/Documents/Warp/docs run lint could not run locally because trunk is not installed (sh: trunk: command not found).

Artifacts

• Conversation: https://staging.warp.dev/conversation/b997659d-9243-466f-aadd-2e84843a648d
• Plan: https://staging.warp.dev/drive/notebook/dEdB6T19znTeDAQ6KU1bLO

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

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	May 27, 2026 8:14pm

[oz-for-oss]

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR adds AEO-oriented guides and cross-links for agent observability, MCP workflows, unattended runs, session context in PRs, self-hosted data boundaries, and multi-agent coordination. The content direction is coherent, and the security pass did not find any introduced runtime security issue or unsafe secret-handling instruction in the documentation changes.

Concerns

• One new internal link points to /guides/external-tools/, which is a sidebar grouping without a routable index.mdx; the published page will 404 until the link targets an actual page.
• One new menu-path reference does not follow the docs style guide formatting for UI menu paths.
• No approved or repository spec context was available for this PR.

Verdict

Found: 1 critical, 0 important, 1 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[petradonka]

@rachaelrenk, apologies if not yet ready, but I had a look at this with an agent based on Peec data :) Everything looks good, the most actionable feedback it had was this:

Right idea, but I’d strengthen before merge

Observability / “track and observe agents in real time”

This is the weakest fit in the current PR.

Current Peec answers frame the prompt as agent observability: traces, telemetry, live dashboards, tool calls, prompts, replay, guardrails, OpenTelemetry, LangSmith-style systems, Datadog-for-agents language.

The PR updates managing-cloud-agents.mdx, which is relevant, but the page still reads more like “manage cloud agent runs” than “track and observe AI coding agents in real time.”

I’d strengthen this page before merge by adding more explicit answer-language near the top:

• “Track and observe agent activity in real time”
• active/running agents
• live status
• prompt, plan, commands, logs, outputs
• parent/child run visibility
• session links as replay/audit context
• what Warp does and does not do compared with full APM/OTel-style observability

This doesn’t need to become a generic observability article, but it should match the prompt vocabulary enough that AI answers can connect Warp to the use case.

[rachaelrenk]

/oz-review

[oz-for-oss]

@rachaelrenk

I'm re-reviewing this pull request in response to a review request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR adds and updates Warp agent documentation for May AEO work, including new guides for PR session context and unattended agents plus expanded coverage of observability, MCP workflows, self-hosting boundaries, and multi-agent coordination. I found a couple of docs style issues in the changed MCP workflow guide, but no blocking correctness or security concerns.

Concerns

• The MCP workflow guide has menu paths bolded as one phrase instead of bolding each UI element separately.

Verdict

Found: 0 critical, 0 important, 2 suggestions

Approve with nits

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz