Repository navigation
docs: consolidate factory-first references and retire outdated guidance - #953
rachaelrenk wants to merge 13 commits into
Conversation
Redirect HTML and Markdown URLs to the Warp Factories quickstart, remove the sidebar entry, and update companion guide links. Co-Authored-By: Warp <agent@warp.dev>
Preserve the approved cloud-guide retirement while incorporating merged secrets documentation and current main. Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Co-Authored-By: Warp <agent@warp.dev>
Relocate MCP, environment, and harness references with one-hop HTML and Markdown redirects. Preserve standalone workflows and legacy anchors, clarify both MCP connection directions, revise Platform entry bridges, and validate navigation and discovery. Co-Authored-By: Warp <agent@warp.dev>
rachaelrenk
changed the title
Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Preserve both validation scripts and retarget merged recipe and exemplar references to their Factories owners. Co-Authored-By: Warp <agent@warp.dev>
Lead environments with factory defaults, align harness reference titles and current links, expand Harnesses, clarify the Platform description, and promote security guidance under Infrastructure. Add rendered regression checks for the approved review changes. Co-Authored-By: Warp <agent@warp.dev>
Preserve legacy anchors and redirects, route FAQ topics to their owners, and add retirement regression coverage. Leave Enterprise documentation unchanged. Co-Authored-By: Warp <agent@warp.dev>
Preserve factory permissions and dynamic setup metadata guidance, including the environment reference relocated by this branch. Co-Authored-By: Warp <agent@warp.dev>
…ence Resolve the modify/delete conflict by retaining the Platform security retirement and applying incoming inference gateway guidance to its factory self-hosting successor. Preserve the existing AFDocs merge and add rendered regression coverage. Co-Authored-By: Warp <agent@warp.dev>
|
|
||
| :::note | ||
| Claude Code is also available as a harness in the {VARS.WARP_AUTOMATION_PLATFORM} for cloud orchestration. See [Claude Code with the {VARS.WARP_AUTOMATION_PLATFORM}](/platform/harnesses/claude-code/). | ||
| Claude Code is also available as a harness in the {VARS.WARP_AUTOMATION_PLATFORM} for cloud orchestration. See [Claude Code harness](/factories/harnesses/claude-code/). |
There was a problem hiding this comment.
it's kind of strange that we're referring to it as the automation platform and then link out to the factory page, and similar for other instances of this as well (in different harnesses, features, etc).
it's worth maybe saying this is like a primitive or something from the automation platform, but also available as a harness on the factory platform?
| 4. The run produces **outputs**, like a pull request, Slack reply, report, or transcript and summary. | ||
| A request or event supplies the task and its context. The agent executes on its configured host and produces results such as a pull request, report, or transcript. For the factory task lifecycle and review points, see [how Warp Factories work](/factories/how-factories-work/). | ||
|
|
||
| <figure style={{ maxWidth: "736px" }}> |
There was a problem hiding this comment.
i think we should update this graphic on the overview page, do you mind asking in #design or another channel like #pod-sales-enablement if we have a better asset we can place here? lmk if you don't have access to other channels and i can make sure you're added
| The {{WARP_AUTOMATION_PLATFORM}} provides shared execution, configuration, | ||
| and APIs for Warp Factories and standalone cloud agents. | ||
| Configure agents with Warp Factories, or run and manage cloud agents without | ||
| a factory. Both use the {{WARP_AUTOMATION_PLATFORM}}. |
There was a problem hiding this comment.
this "both use the Warp Automation Platform" sounds a bit weird
| ## Environments | ||
|
|
||
| An [environment](/platform/environments/) defines a Docker image with your toolchain, repositories, and setup commands. Use the [environment setup reference](/platform/environments/configuring-environments/) for standalone runs and [factory runners](/factories/runners/) for factory execution. | ||
| Factories manage their workspace by default. [Environments for factory agents](/factories/environments/) cover the optional existing-environment path and standalone setup; [runners](/factories/runners/) cover compute configuration. |
There was a problem hiding this comment.
for most of the content changes on this page, i actually prefer the style and tone of the previous content, the newer content isn't as clear to me and is a bit harder to grok given they're basically just all links out to other pages - i think we should still share some relevant details here? mind reverting back to the original version and improving upon that instead?
| Skills allow you to create reusable, shareable instructions that agents can invoke when performing tasks. Instead of repeating detailed prompts, you can encapsulate common workflows, coding patterns, or domain expertise into skill files that agents automatically discover and use. | ||
| Skills are reusable instructions for tasks such as deployment, code review, or documentation checks. Store them with your code so teammates can review and reuse them. | ||
|
|
||
| ## Key features |
There was a problem hiding this comment.
curious why we removed a bunch of the features here?
There was a problem hiding this comment.
actually, on this page, im noticing that we trimmed down on a lot of the context, some of which i understand, but curious why in this PR specifically we decided to remove a bunch of the content? was it moved into the factories pages?
| - "Add a feature flag for the new checkout flow" | ||
| - "Create a flag to enable dark mode for beta users" | ||
| ``` | ||
| An `add-feature-flag` skill can request the flag name and default, then update the repository's configuration, helper, tests, and documentation. |
There was a problem hiding this comment.
where did the rest of this content go?
| ```text | ||
| # Local paths | ||
| /create-environment ./warp-internal ./warp-server | ||
| /create-environment ./payments-service ./deployment-config |
There was a problem hiding this comment.
i like how we're using generic examples here instead of warp examples! could you do a pass in a separate PR of other places in our docs repo where we could do this?
| @@ -0,0 +1,54 @@ | |||
| --- | |||
There was a problem hiding this comment.
did any of this content change or is this mostly moving it over from the automation platform? would prefer to keep it mostly unchanged for now (if we do change, we can tackle that in a separate PR! which would be a lot easier to review)
| The same agent can be invoked consistently across entry points (Warp conversation, cloud agent web app, the CLI, API/SDK, Slack/GitHub triggers) without rewriting the underlying instructions. | ||
| * <span id="can-i-access-a-shell-inside-a-cloud-agent-environment-are-there-limitations-docker-playwright-etc" />[Environment tools and dependencies](/factories/environments/configuring-environments/) | ||
|
|
||
| ### What exactly are cloud agents in Warp? |
There was a problem hiding this comment.
did all of these FAQs move to other docs?
|
|
||
| ## Related pages | ||
|
|
||
| * [Cloud agents quickstart](/platform/quickstart/) — run a cloud agent with an environment. |
There was a problem hiding this comment.
curious why we removed a lot of these
| Before automating a task, identify its trigger, the context the agent needs, and how someone will validate its result. | ||
| Use [factory automations](/factories/automations/) for event-driven work and recurring maintenance in a factory. Standalone workflows have separate [integrations](/platform/integrations/) and [schedules](/platform/triggers/scheduled-agents/). [Multi-agent orchestration](/platform/orchestration/) explains how parent and child agents divide work. | ||
|
|
||
| ## How cloud agents work |
There was a problem hiding this comment.
similar feedback here as to other pages, i feel like we removed a lot of the detail on each of the features in favor of just linking out to other pages. i think linking out is good, but it's useful to provide some sort of baseline context on this page so they know what each of these features entail before clicking on the links
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.
/guides/agent-workflows/run-a-software-factory-in-the-cloud//factories/quickstart//platform/skills-as-agents//agents/capabilities/skills/; keep CLI, API, web, and scheduling instructions with their existing owners; redirect HTML and Markdown/guides/configuration/how-to-use-agent-profiles-efficiently//guides/configuration/how-to-configure-yolo-and-strategic-agent-profiles/; redirect HTML, Markdown, and historical aliases/platform/faqs//platform/mcp//factories/mcp//platform/environments//factories/environments//platform/environments/configuring-environments//factories/environments/configuring-environments//platform/environments/troubleshooting-environments//factories/environments/troubleshooting-environments//platform/harnesses//factories/harnesses//platform/harnesses/authentication//factories/harnesses/authentication//platform/harnesses/warp-agent//factories/harnesses/warp-agent//platform/harnesses/claude-code//factories/harnesses/claude-code//platform/harnesses/codex//factories/harnesses/codex//platform/execution-security//factories/self-hosting/security-and-networking//platform//platform/overview/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.mdURL 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
/platformto/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
AgentHarnessfeature mapping for the relocated harness reference, resolving the reproduced audit-accounting failure.Update the feature-documentation exemplar paths in
AGENTS.mdanddraft_feature_doc/SKILL.mdto 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-migrationto protect routes, rendered links, historical anchors, metadata, images, Markdown, and discovery.Sync current main at
e8d547c4in merge commitdf8c5904, preserving the previously approved guide deletion and merged secrets navigation.Incorporate the subsequent main sync in
ed677d5d, publish audit-path corrections in2f143640, and publish the security migration in3a2124aa.Merge main at
083d1f77in410f6e65. Resolve thepackage.jsonconflict by retaining bothtest:platform-reference-migrationand main'stest: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 andWARP_SKILL_DIRSguidance 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-retirementsand run both retirement and original migration regressions in CI. Enterprise source pages are unchanged.Merge latest main (
232cf279) infdb09a1dto 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
4aa3f120in47953440, preserving the existing AFDocs merge2f9290bf. 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_docsand matching content-type guidance,style_lint,check_for_broken_links,doc_quality_policy, andcreate_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: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-servercommit09f293ff19dee88690c5962f9c9c1ab0ccdd8827: 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-internalcommit0518d34bd44816cbe5b43c68af5fda0786ed3ce1: CLI harness identifiers/aliases, typed credential commands, scope selection, and related UI source.warpclient commiteafc6d18d18bea8c6cf78dc21a4e0eab59f4c6c6: environment setup timeout constants, environment CLI options, and guided setup.warp-agent-dockerRELEASE commit6903839315a328cf7644195c02abfad6bcf8969e: 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.warprevision9441000afee49e6f6a43a7f1b6a599dce4487e51for production endpoint defaults and harness configuration/transcript handling;warp-serverrevision6ca991369f565dc8f9e9f4ce1313f78cdcf9b812for self-hosted assignment and production configuration;oz-agent-workerrevision0e41f07e7aac08d4d3534836a9902d8642a3183cfor 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
Location:
src/content/docs/agents/capabilities/skills.mdx, “Extra directories for cloud runs.” Needs release evidence or owner confirmation.Inherited from main (#973) in
src/content/docs/factories/infrastructure-and-security.mdx, “Networking for BYO inference endpoints”; needs production-network owner confirmation.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