[rachaelrenk]

Summary

Make Warp Factories the primary home for shared cloud-agent configuration references, preserve supported standalone workflows, and retire duplicated or outdated guidance. Consolidate Skills as agents into existing skill and launch references, replace the full Platform FAQ with topic routing, merge the duplicate Agent Profiles tutorial, and redirect the obsolete cloud software-factory guide.

The aggregate traffic export and content audit informed these approved actions: move the five harness references, three environment references, and MCP-server reference into Factories; retain the two high-traffic Platform entry pages as useful factory-first bridges. Traffic prioritizes assessment, not automatic retirement. Raw analytics remain outside this public PR.

Trevor's self-hosting discoverability feedback and HYC's request add a tenth reference move: Security and networking now lives with factory self-hosting, including its outbound network requirements.

Article changes at a glance

3 articles retired · 10 articles moved from Platform to Factories · 2 Platform entry pages retained and revised · 1 full FAQ replaced by topic routing.

Action	Article	Previous URL	Destination or treatment
Retire	Obsolete DIY cloud software-factory guide	/guides/agent-workflows/run-a-software-factory-in-the-cloud/	Remove the tutorial; redirect to /factories/quickstart/
Consolidate and retire	Skills as agents	/platform/skills-as-agents/	Preserve discovery and extra-directory setup in /agents/capabilities/skills/; keep CLI, API, web, and scheduling instructions with their existing owners; redirect HTML and Markdown
Consolidate and retire	Use Agent Profiles efficiently	/guides/configuration/how-to-use-agent-profiles-efficiently/	Merge useful context into /guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles/; redirect HTML, Markdown, and historical aliases
Replace full article with routing	Cloud agent FAQs	/platform/faqs/	Keep the URL as Cloud agent topics; route all 34 questions to their owners and preserve all 40 original heading IDs
Move	Connecting MCP servers to agents	/platform/mcp/	/factories/mcp/
Move	Environments for factory agents	/platform/environments/	Concept: /factories/environments/
Move	Environment configuration	/platform/environments/configuring-environments/	Setup: /factories/environments/configuring-environments/
Move	Environment troubleshooting	/platform/environments/troubleshooting-environments/	Remedies: /factories/environments/troubleshooting-environments/
Move	Agent harnesses	/platform/harnesses/	/factories/harnesses/
Move	Configuring harness authentication	/platform/harnesses/authentication/	/factories/harnesses/authentication/
Move	Warp Agent harness	/platform/harnesses/warp-agent/	/factories/harnesses/warp-agent/
Move	Claude Code harness	/platform/harnesses/claude-code/	/factories/harnesses/claude-code/
Move	Codex harness	/platform/harnesses/codex/	/factories/harnesses/codex/
Move	Security and networking	/platform/execution-security/	/factories/self-hosting/security-and-networking/
Retain and revise	Cloud agents overview	/platform/	Same URL; factory-first orientation with standalone routes
Retain and revise	Automation Platform overview	/platform/overview/	Same URL; shared-platform orientation with factory-first next steps

Moved articles have complete successor pages, not stubs. Their old HTML and Markdown URLs receive permanent 308 redirects, and their existing section anchors are preserved. The retired guide also redirects in both formats. Both retained entry pages remain indexable and self-canonical.

Outside this batch: Enterprise documentation changes, further article retirements, relocating orchestration or run management, and removing the Platform tab.

Changes

• Delete /guides/agent-workflows/run-a-software-factory-in-the-cloud/, which teaches a DIY cloud-agent factory workflow predating the managed product documentation.

• Add permanent 308 redirects from the old HTML URL, with or without a trailing slash, to /factories/quickstart/, and from its .md URL to /factories/quickstart.md.

• Remove the retired guide from src/sidebar.ts.

• Update the setup and self-improving-agent companion guides to link directly to the factory quickstart and normalize their closing link lists.

• Move full references from /platform/harnesses/*, /platform/environments/*, and /platform/mcp/ to matching /factories/ destinations. Preserve standalone CLI, personal/ad hoc authentication, legacy web-app setup, screenshots, troubleshooting, and all prior section IDs.

• Add one-to-one 308 redirects for the ten old HTML/Markdown routes and explicit historical cloud-agent and self-hosting aliases. Repoint other known aliases directly and correct bare /platform to /platform/, not /agents/.

• Move /platform/execution-security/ to /factories/self-hosting/security-and-networking/, preserve all 11 existing section IDs and standalone unmanaged guidance, and update sidebar placement and current links. Factory setup and infrastructure guidance link directly to #network-requirements.

• Clarify domain/port requirements, outbound HTTPS and WebSockets, conditional registry and provider traffic, services reached from Warp, and Direct-backend credential/workspace boundaries. Do not introduce a fixed-IP allowlist.

• Correct the active audit seed-store paths and AgentHarness feature mapping for the relocated harness reference, resolving the reproduced audit-accounting failure.

• Update the feature-documentation exemplar paths in AGENTS.md and draft_feature_doc/SKILL.md to the migrated environments source. Retarget the new incident-response recipe's MCP link and the billing reference's harness link to their Factories owners.

• Revise /platform/ and /platform/overview/ into distinct, indexable factory-first entry pages with supported standalone routes.

• Make the opposite MCP connection directions explicit before setup in both pages: agents connecting to external tools versus external coding agents connecting to a factory.

• Move runtime discovery into the Factories sidebar, update current internal links and full-title link text, and adjust LLM documentation-set descriptions. No stub exclusion/indexing framework is introduced.

• Correct verified harness object syntax, resource/authentication scope, conditional credential-picker labels and entitlement wording. Distinguish named factory-agent dispatch from ad hoc orchestration; do not promise universal shared credentials or local/cloud parity.

• Add a migration fixture and npm run test:platform-reference-migration to protect routes, rendered links, historical anchors, metadata, images, Markdown, and discovery.

• Sync current main at e8d547c4 in merge commit df8c5904, preserving the previously approved guide deletion and merged secrets navigation.

• Incorporate the subsequent main sync in ed677d5d, publish audit-path corrections in 2f143640, and publish the security migration in 3a2124aa.

• Merge main at 083d1f77 in 410f6e65. Resolve the package.json conflict by retaining both test:platform-reference-migration and main's test:page-title-order, alongside its Markdown-serialization and agent-discovery tests. Preserve main's new use-case navigation, page-title/Markdown rendering changes, discovery catalog, editorial guidance, and billing updates; those independently merged features are not new deliverables of this migration PR.

• Publish the approved review refinements in 67cfe72a: retitle and reframe the environments overview around factory-managed defaults and optional existing-environment reuse. Review the complete page for flow, keeping standalone instructions and distinguishing repositories, runner/image/setup configuration, model choice, profiles, and tools.

• Use reference-style titles for the harness family: “Agent harnesses,” “Warp Agent harness,” “Claude Code harness,” and “Codex harness.” Keep the overview and individual-agent sidebar labels, and update current full-title cross-links without rewriting historical changelog wording.

• Expand Harnesses by default without changing other groups' expansion settings. Keep the Cloud Agents sidebar label rather than introducing “Standalone cloud agents.”

• Replace the Platform overview's description with the approved action-led wording: “Configure agents with Warp Factories, or run and manage cloud agents without a factory. Both use the Automation Platform.”

• Promote Security and networking directly under Factory configuration → Infrastructure, outside Managed self-hosting. Its canonical URL, all original anchors, and existing redirects are unchanged.

• Extend rendered migration checks to protect the reviewed titles, default harness expansion on an unrelated page, direct Infrastructure placement, and the approved overview description.

• Publish the approved non-Enterprise consolidations in 2e2d77a3: retire Skills as agents after preserving discovery and WARP_SKILL_DIRS guidance in general Skills and launch examples in the existing CLI/API/web/schedule owners. Keep standalone workflows distinct from factory skills.

• Replace the full Platform FAQ with Cloud agent topics at the same URL. Preserve all 34 question IDs and six group IDs, route readers to topic owners, and keep unresolved Product/Billing and Security/Legal findings open rather than treating removed prose as resolution.

• Merge the duplicate Agent Profiles tutorial into Configure YOLO and strategic Agent Profiles. Preserve setup caveats and original anchors, reconcile file-reading permissions explicitly, and distinguish recorded outcomes from safety or performance guarantees.

• Update current navigation, guide cards, backlinks, one-hop HTML/Markdown redirects, and historical aliases. Add test:article-retirements and run both retirement and original migration regressions in CI. Enterprise source pages are unchanged.

• Merge latest main (232cf279) in fdb09a1d to clear the branch conflict. Preserve incoming factory permissions and dynamic setup-metadata guidance, including the edit to the relocated environment configuration page; re-run build, link, migration, retirement, and audit checks.

• Merge main at 4aa3f120 in 47953440, preserving the existing AFDocs merge 2f9290bf. Resolve the security-page modify/delete conflict by transferring main's inference-gateway correction to the relocated Security and networking reference, retaining old-URL redirects and adding rendered regression coverage. Preserve main's Enterprise endpoint clarification without introducing separate Enterprise edits.

Content design plan

Audience and JTBD: A developer configuring a factory agent's harness, credentials, tools, or runtime, including an existing standalone user following an older reference URL.

Problem: Shared reference material is discovered under the older Platform structure, while factory users need it in Factories. An obsolete cloud-factory tutorial also competes with current setup.

Goals: Route readers to the correct canonical reference, preserve supported standalone tasks and bookmarked sections, and make factory setup the primary entry route.

Purpose and value: Consolidate shared primitives without declaring them factory-only. The new references preserve supported setup methods and remedies; factory settings, secret lifecycle, billing, and general orchestration keep their existing owners. The two entry pages remain useful choices rather than moved notices. Additional page moves and the guide retirement have explicit human approval.

Content type: Relocated references, revised orientation pages, consolidated skill documentation and tutorial, and an anchor-preserving FAQ routing page. No new feature is announced.

Skill and template: draft_docs and matching content-type guidance, style_lint, check_for_broken_links, doc_quality_policy, and create_pr. Retain the existing reference structures rather than add unrelated scaffolding.

High-impact scenarios: Factory configuration, old bookmarks, inbound deep links, standalone compatibility, and direct Markdown consumers. Excludes further retirements, Enterprise source edits, orchestration relocation, integration protocol changes, and removal of the Platform tab.

Security migration addendum: The reader is an infrastructure or security engineer configuring self-hosted workers and firewall access. The gap is that the detailed network reference lives outside factory self-hosting navigation. Relocate the complete reference rather than duplicate or split it, preserve unmanaged coverage and anchors, and keep general infrastructure, privacy policy, and inference setup with their canonical owners.

Review-round editorial verdict: Lead the environments page with the factory reader's default and optional override before shared runtime details. Remove repeated local-setup explanation and an unconditional fresh-workspace statement; retain environment contents, supported standalone use, container-user requirements, and original anchors. Use noun-phrase harness titles to match their reference role, keep configuration procedures with their existing owners, and surface networking prerequisites without another URL move or duplicate page.

Approved consolidation addendum: Readers configuring reusable skills should find discovery and extra-directory setup in general Skills, with invocation details in existing references. Readers comparing profiles should have one NFL-data tutorial, not two versions of the same video. Old FAQ deep links should route to topic owners without duplicate answers or unsupported promises. Preserve useful context and all 54 original anchors; leave Enterprise docs untouched.

Validation

Local checks passed after merging main in 47953440:

• Typecheck, heading-variable tests, build (406 pages), TOCs, homepage metadata, and page-title order.
• Original migrations and new retirement regressions: ten moved references, two entry bridges, 54 additional preserved anchors, and all 34 FAQ destinations.
• All 4,642 internal links, HTML/Markdown redirects, Markdown/discovery and AFDocs tests, 34 audit tests, and whitespace checks.
• Prior consolidation checks: compression passed, style lint introduced no new findings, and read-only Platform and Guides reviews found no blocking defects.

Limits: Trunk is unavailable locally; deployed redirects, live infrastructure, and stable-release coverage noted below were not exercised. Existing reviewer-request snippets require newer Bash than local macOS Bash 3.2. Local checks do not establish green CI or merge readiness.

Source verification

Named source revisions and production-configuration checks are separate from live deployment or account-specific entitlement evidence:

• warp-server commit 09f293ff19dee88690c5962f9c9c1ab0ccdd8827: factory definition resolution, MCP managed/direct/OAuth and integration-tool paths, harness availability/authentication, typed secrets, API harness object, and named-agent dispatch. Exact controlling production checks passed; unrelated matches from broad scans were inspected rather than treated as applicable blockers.
• warp-internal commit 0518d34bd44816cbe5b43c68af5fda0786ed3ce1: CLI harness identifiers/aliases, typed credential commands, scope selection, and related UI source.
• Public warp client commit eafc6d18d18bea8c6cf78dc21a4e0eab59f4c6c6: environment setup timeout constants, environment CLI options, and guided setup.
• warp-agent-docker RELEASE commit 6903839315a328cf7644195c02abfad6bcf8969e: non-root startup, image-provided users, conditional UID/home behavior, sudo, fallback, and opt-out. Production stable-sidecar configuration and worker entrypoint wiring were inspected separately.
• Security addendum: public warp revision 9441000afee49e6f6a43a7f1b6a599dce4487e51 for production endpoint defaults and harness configuration/transcript handling; warp-server revision 6ca991369f565dc8f9e9f4ce1313f78cdcf9b812 for self-hosted assignment and production configuration; oz-agent-worker revision 0e41f07e7aac08d4d3534836a9902d8642a3183c for worker endpoint defaults and Direct backend environment/workspace handling. These source/configuration observations do not identify a customer's exact deployed binary.

The relocated references correct unsupported blanket assertions rather than retaining them: omitted run MCP configuration is not a tool-access revocation; repository authorization depends on the run's identity; factory and ad hoc children need not share resources; and cloud authentication is not universally one credential path. The image remedy recommends a glibc-based alternative after startup failure without declaring universal Alpine support or universal incompatibility.

Follow-up scope

Skills as agents, the full Platform FAQ, and the duplicate Agent Profiles tutorial are addressed in this PR. Enterprise changes and other retirement candidates remain deferred. Orchestration/run-management relocation and removal of the Platform tab are not included.

Unverified claims

• Extra-directory parsing and harness publication are verified against public source, but stable-release coverage has not been confirmed.

Location: src/content/docs/agents/capabilities/skills.mdx, “Extra directories for cloud runs.” Needs release evidence or owner confirmation.

• Confirm that all current production team-managed inference requests use only these two fixed outbound IPs.

Inherited from main (#973) in src/content/docs/factories/infrastructure-and-security.mdx, “Networking for BYO inference endpoints”; needs production-network owner confirmation.

• Product/Billing concurrency and Security/Legal policy findings remain open with their owners.
• Not live-tested: deployed versions/entitlements, provider authentication, billing, cloud/self-hosted execution, firewall/WebSocket/proxy behavior, or deployed redirects. No secrets were handled.
• Legacy Jira's automatic client path remains unverified; supported legacy setup is retained.

Documentation risk

Risk: engineering-review-required
Rationale: Relocates technical references, consolidates published articles, corrects runtime/authentication scope claims, and retains release and networking verification markers. Human approval covers the scope, not a waiver of verification.
Source files consulted: warp-server logic/harness_availability.go, logic/harness_auth.go, logic/factoryfile/resolution/resolution.go, public_api/openapi.yaml; warp-internal crates/warp_cli/src/agent.rs and secret.rs; warp app/src/ai/agent_sdk/driver/environment.rs; warp-agent-docker entrypoint.bash; named revisions recorded above
Requested engineering reviewers: none; this existing PR update does not add or re-request reviewers
Engineering review status: pending
Docs override: none

Agent context

Agent conversation

Co-Authored-By: Warp agent@warp.dev

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 30, 2026 9:09pm UTC