docs: add AEO cross-links for agents, orchestration, and factories

[warp-factories]

Summary

Adds small internal cross-links so readers can continue agent, cloud-agent, orchestration, and factories workflows from pages that already mentioned those concepts without linking them.

AEO brief

Goal: Identify small internal cross-link improvements for agents, cloud agents, orchestration, and factories docs.

Recommendation: Update existing pages only (no new pages).

Source signals:

• Peec (project Warp, last 30 days): high-intent prompts and pending CONTENT_BRIEF / HOW_TO_GUIDE actions around AI software factories, cloud agent orchestration, multi-agent development, and CI/CD agent workflows. Search-query clusters include software factory platforms, Warp factory features, and enterprise agent orchestration.
• Google Search Console (sc-domain:warp.dev, ~28 days ending 2026-10-16): strong traffic to factories marketing and docs (/factories/, branded "warp factories" / "warp factory" / "warp software factory" queries), plus agent CLI and multi-agent surfaces.
• Existing docs: bare mentions of factory automations, factory skills, Warp Factories authorship, ad-hoc multi-agent fan-out, and standalone schedules on otherwise well-linked pages.

Vocabulary map:

• Users/answer engines say: software factory, cloud agent orchestration, multi agent, scheduled agents, factory automations
  Docs should say: Warp Factories, factory automations, multi-agent orchestration, scheduled agents, factory skills

Content scope:

• Include - Descriptive internal links where the source page already names the destination concept or reader next step.
• Avoid - New pages, rewrites, keyword stuffing, related-link dumps, or mismatched general targets.

Existing docs to touch or link:

• guides/agent-workflows/how-to-run-unattended-agents.mdx - trigger chooser lacked the factory automation path.
• agents/capabilities/skills.mdx - skills-as-agents path was covered; factory-scoped skills were not.
• platform/agents.mdx - Warp Factories GitHub App authorship was unlinked.
• factories/index.mdx and multi-agent guide - standing factory vs ad-hoc orchestration next steps.
• factories/automations.mdx - no pointer to standalone scheduled agents outside a factory.

Links added

• Unattended agents guide → Factory automations / Warp Factories. Reader choosing an unattended trigger needs the standing factory path beside schedules, Slack, and CI.
• Skills → Factory skills. Reader writing reusable skills needs the factory-scoped skill destination after skills-as-agents.
• Cloud agent accounts → Warp Factories. Reader configuring PR authorship needs the factories product page behind the GitHub App name.
• Factories overview → Multi-agent orchestration. Reader comparing standing factory teams to ad-hoc parent/child fan-out.
• Factory automations → Scheduled agents. Reader who wants cron runs outside a factory.
• Multi-agent guide → Warp Factories. Reader finishing parallel fan-out who needs a standing triage-to-merge workflow.

Reader next step

• Unattended trigger selection → pick factory automations when work should enter a triage-to-merge factory.
• Skills authoring → scope procedures to a factory agent when the skill is factory-owned.
• Cloud agent PR identity → understand Warp Factories as the GitHub App author surface.
• Factories vs orchestration → choose standing factories or ad-hoc multi-agent runs.
• Automations vs schedules → leave the factory path for standalone cron agents when appropriate.
• Multi-agent local/cloud fan-out → graduate to Warp Factories for recurring team workflows.

Changes

src/content/docs/guides/agent-workflows/how-to-run-unattended-agents.mdx

• Added factory automations row to the trigger chooser table
• Linked factory automations from Next steps

src/content/docs/agents/capabilities/skills.mdx

• Linked factory skills from the skills-as-agents paragraph; removed the duplicate Next steps pointer

src/content/docs/platform/agents.mdx

• Linked Warp Factories on the GitHub App authorship sentence

src/content/docs/factories/index.mdx

• Linked multi-agent orchestration from Related pages

src/content/docs/factories/automations.mdx

• Linked standalone scheduled agents from Related pages

src/content/docs/guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx

• Linked Warp Factories from Next steps

Open questions for human review

• None blocking. Confirm factory automations remain the preferred next step from the unattended-agents trigger table versus only linking the factories overview.

Documentation risk

Risk: low
Rationale: Cross-link-only edits to existing pages; no new product claims, commands, UI paths, or availability changes.
Source files consulted: none (link targets already exist in docs)
Requested engineering reviewers: none
Engineering review status: not-applicable
Docs override: none

Skills page compression exceptions

• Word budget: agents/capabilities/skills.mdx has 2,150 prose words against the 1,500-word feature-page budget; the merge-base has 2,136. The retained teaching explains discovery and name conflicts, file format, argument substitution, project versus global locations, creation, and supporting files. These examples and explanations let readers choose a scope, write a usable skill, and recognize what happens when arguments are missing. This cross-link change adds only a 14-word contextual pointer to factory-specific procedures, whose details remain on Factory skills. The deletion-only pass removed the duplicate pointer rather than cutting instructional context or mechanically splitting the canonical skills-authoring page.
• Callout budget: All four callouts are inherited, above the normal two-callout budget. They keep discovery's working-directory boundary, the Rules-versus-Skills choice, missing-argument behavior, and supported-directory discovery beside the relevant teaching. Each explains a choice or consequence needed to use skills correctly; none was added or expanded. This narrow change retains that context and the existing layout, including the adjacent discovery/Rules notes, rather than restructuring the page.

Validation

• python3 .agents/skills/style_lint/style_lint.py --changed — zero errors; the same 19 warnings as before this revision.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — zero broken links.
• python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --changed --require-provenance — zero issues across all six changed pages.
• check_pr_contract.py against all six changed public pages, without --enforce-engineering-gate, and check_pr_body.py — passed; zero VERIFY markers.
• npm run typecheck, npm run test:heading-vars, npm run build, npm run test:heading-tocs, and npm run test:homepage-json-ld — passed.
• check_compression_contract.py for skills.mdx — reports the two budget overages justified above, not a mechanical pass.
• Trunk formatting/lint checks were unavailable because the CLI is not installed.

Unverified claims

• None. No new technical claims; only internal links to existing canonical pages.

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 19, 2026 6:09pm UTC

[warp-factories]

This PR was generated with Warp.

Comment @warp-agent on this PR to send it follow-up work.

  View origin

[warp-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 /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR adds targeted internal cross-links across existing agent, orchestration, and factory documentation pages so readers can continue related workflows from pages that already mention those concepts. The changes are documentation-only, the introduced internal links resolve to existing docs pages, and the declared low documentation risk matches the cross-link-only scope.

Concerns

• No blocking concerns found.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

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

Powered by Oz

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/agents/capabilities/skills.mdx:451 (PR-wide metadata) — [CRITICAL] The Documentation risk section contains Engineering review status: not-required, which fails structural validation; the descriptive cross-link diff itself qualifies as low risk. Requested resolution: replace the field with Engineering review status: not-applicable or omit it, then rerun check_pr_contract.py against all six changed public pages without --enforce-engineering-gate.
• src/content/docs/agents/capabilities/skills.mdx:451 — [IMPORTANT] The changed feature page has 2,165 prose words and four callouts, exceeding the 1,500-word and two-callout budgets without PR-body justification. The merge-base already has 2,136 words and four callouts. Requested resolution: document an exception rationale for both inherited overages and the instructional context retained in this narrow cross-link change, or reduce padding to meet the budgets without losing necessary choices, consequences, or success signals; do not mechanically split the page.
• src/content/docs/agents/capabilities/skills.mdx:468 — [SUGGESTION] The new Factory skills bullet repeats the same destination and scope distinction added at line 451. Requested resolution: keep one contextual pointer and remove the other; this preserves the route to factory-specific procedures without repeating the same choice within 17 lines.

Verdict

Request changes

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• No findings.

Verdict

Approve