docs: add AEO cross-links for agents and orchestration

[rachaelrenk]

AEO cross-link audit — agents and orchestration

Small, high-confidence internal cross-links connecting agent and cloud-agent pages to the multi-agent orchestration docs. Scope is limited to adding links with minimal surrounding copy changes.

Goal

Identify small internal cross-link improvements for agents, cloud agents, and orchestration docs so readers who encounter multi-agent concepts can continue to the orchestration model and how-to pages.

Source signals

• Peec: unavailable this run (PEEC_PAT not set in the environment).
• Google Search Console: unavailable this run (GSC_SERVICE_ACCOUNT_CREDENTIALS_JSON not set).
• Existing-docs signal (low-signal run): Each link is grounded in existing on-page text that already describes orchestration/multi-agent behavior but did not link to the orchestration docs. Confirmed via a gap analysis of pages that mention orchestration concepts (orchestrat, multi-agent, subagent, child agent) yet had no link to /platform/orchestration/.

Per the skill's low-signal policy, a PR is only opened when there are at least 3 additions each strongly grounded in existing on-page content and a clear reader journey. This PR meets that bar with 3 additions.

Pages touched

• src/content/docs/agent-platform/capabilities/slash-commands.mdx — the /orchestrate row described "run them in parallel with multiple agents" but, unlike every peer command (e.g. /plan → planning), had no link to its feature doc.
• src/content/docs/platform/faqs.mdx — the "multi-agent coordination" FAQ answer describes running and coordinating multiple concurrent agents with no link to the orchestration model.
• src/content/docs/platform/software-factory.mdx — describes specialized agents coordinated as cloud runs ("Oz orchestrates each agent as a cloud run") but the Related pages list omitted the orchestration doc.

Links added

• slash-commands.mdx → /platform/orchestration/ — anchors "multiple agents" in the /orchestrate description, matching the established pattern where each command links to its feature page.
• platform/faqs.mdx → /platform/orchestration/ — anchors "running and coordinating multiple concurrent agents" in the multi-agent coordination answer.
• platform/software-factory.mdx → /platform/orchestration/ — adds a Related pages bullet for the parent/child model behind coordinating specialized agents.

Reader next step

• A reader browsing slash commands who sees /orchestrate most likely wants to understand what orchestration does and how to start it — the orchestration overview is the direct next step.
• A reader on the cloud-agent FAQ asking how multi-agent coordination works wants the model that explains parent/child runs, messaging, and patterns.
• A reader learning about the software factory (multiple coordinated agent roles) benefits from the general orchestration model that underpins it.

Open questions for human review

• All three links point to the conceptual /platform/orchestration/ overview. For the /orchestrate slash command specifically, reviewers may prefer the how-to page /platform/orchestration/multi-agent-runs/ instead; happy to switch if that better matches the reader journey.

Validation

• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — 0 broken links (3182 internal links checked).
• git diff --check — clean.
• style_lint --changed — the 9 warnings reported are all pre-existing (headers, screenshot widths, glossary terms) and not introduced by these anchor-only additions.

Conversation: https://app.warp.dev/conversation/1a89d2cb-c09a-4524-8db9-b8972e8d4df5
Run: https://oz.warp.dev/runs/019fa9e8-cff8-710d-b615-18d88edad918

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	Jul 28, 2026 6:15pm