docs: add AEO cross-links for agents and orchestration

[rachaelrenk]

AEO cross-link audit: agents and orchestration

Goal

Add small, high-confidence internal cross-links to improve discoverability of orchestration content from related agent platform pages. These links connect existing docs pages where a reader naturally continues from one topic to the next.

Source signals

Google Search Console (Mar–Jun 2026):

• warp orchestration — 13 impressions, 1 click on docs root; 1 impression/click on /agent-platform/ (avg pos 2.0). Users searching for orchestration often land on high-level pages that don't link to orchestration docs.
• oz agent orchestration — 1 click landing on /agent-platform/cloud-agents/platform/ (pos 11.0). The platform page links to orchestration, but feeder pages (planning, handoff, capabilities, harnesses) do not.
• warp multi agent — 5 clicks on the guide page (pos 1.4). The guide cross-links orchestration well, but the product docs feeding into it (planning, capabilities) do not.
• ai coding agent orchestration — 1 impression on /agent-platform (pos 5.0). Signals that users are looking for orchestration from high-level agent pages.
• multi-agent orchestration claude code tutorial — 4 impressions on the guide page (pos 5.5). Cross-harness orchestration is a real user interest.

Existing docs signals:

• The planning page (capabilities/planning.mdx) describes /plan but never mentions that /plan can propose orchestration — even though this is the primary in-app entry point for orchestration approval.
• The handoff page (cloud-agents/handoff/index.mdx) covers local→cloud and cloud→cloud flows but doesn't mention that once work is in the cloud, orchestration can fan it out to parallel children.
• The capabilities overview (capabilities/index.mdx) lists every capability but omits orchestration entirely, even though it's a core cloud agent capability.
• The harnesses overview (cloud-agents/harnesses/index.mdx) lists what stays the same across harnesses but doesn't mention cross-harness orchestration — a differentiating feature of the Warp Agent harness.

Pages touched

File	Why
src/content/docs/agent-platform/capabilities/planning.mdx	Planning is the primary in-app entry to orchestration via /plan. The Next steps section links to cloud agents but not orchestration.
src/content/docs/agent-platform/cloud-agents/handoff/index.mdx	Handoff moves work to the cloud; orchestration is the natural next step for parallel execution. Related pages had no orchestration link.
src/content/docs/agent-platform/capabilities/index.mdx	Hub page listing all capabilities. Orchestration was missing from the Related section.
src/content/docs/agent-platform/cloud-agents/harnesses/index.mdx	"What stays the same" section lists triggers, environments, skills, and observability but omitted cross-harness orchestration.

Links added

Source page	Target page	Reader next step
capabilities/planning.mdx → cloud-agents/orchestration/	A reader who just learned about /plan wants to understand what happens when the plan proposes orchestration — how the approval flow works, what the parent/child model is, and what patterns are available.
cloud-agents/handoff/index.mdx → cloud-agents/orchestration/	A reader who handed off a local conversation to the cloud may want to scale the work further by fanning it out to multiple child agents. Orchestration is the mechanism for this.
capabilities/index.mdx → cloud-agents/orchestration/	A reader scanning the capabilities hub should be able to discover orchestration alongside skills, planning, MCP, and other capabilities.
cloud-agents/harnesses/index.mdx → cloud-agents/orchestration/	A reader comparing harnesses should see that cross-harness orchestration (Warp Agent parent → Claude Code/Codex children) is a platform feature, not just a Warp Agent feature.

Open questions for human review

• Planning page link placement: The orchestration link is in the "Next steps" section. It could also appear inline in the "Creating a plan" section where /plan is first introduced. Human reviewers should decide if inline placement is better.
• Harnesses page link wording: The cross-harness orchestration bullet names specific harnesses (Claude Code, Codex). If more harnesses are added, this should be updated.

Self-review checklist

• ✅ Every link is backed by GSC or existing-docs signals
• ✅ Every link helps a developer understand or complete a real workflow
• ✅ Link text is descriptive and specific (no generic anchors)
• ✅ Surrounding sentences explain why the destination is relevant
• ✅ No link stuffing — 1 link added per page
• ✅ All targets exist (check_links.py --internal-only passes)
• ✅ style_lint.py --changed passes
• ✅ git diff --check passes
• ✅ Diff is limited to cross-linking with minimal copy changes

---

Conversation: https://app.warp.dev/conversation/10e8556a-9d42-4c9f-b75e-c854b707a432
Run: https://oz.warp.dev/runs/019e9c29-1d38-791f-a464-e030aea2a8d1

This PR was generated with Oz.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 6, 2026 9:07am