Refactor and update Warp Factories documentation

[rachaelrenk]

What this feature does

Warp Factories gives teams a configurable development workflow that takes requests through planning, implementation, and review, then returns results to the tools where work began. Standalone cloud agents remain a separate path for individual tasks. Phase 1 shipped on October 6, 2026, per the requester-confirmed launch context; a corresponding desktop release version has not been established.

Summary

This PR streamlines the documentation for Warp Factories and cloud agents to better distinguish between standing factory workflows and standalone agent tasks.

This is the public-content half of the first-pass plan, not the completed plan. Content-production guidance is in #881, not this PR. Keep #786 exclusively Phase 2.

Changes

• Transition guidance - Replaces platform/documentation-map.mdx with platform/transitioning-from-oz.mdx, covering existing web-app, CLI, SDK, and API workflows without retirement dates or automatic-transfer promises. Historical Oz references are intentional.
• Navigation and redirects - Lists the transition page under both Factories Overview and the Automation Platform for cross-topic discovery; restores its original URL and redirects the former map URL to it. No tab reorder.
• Platform entry pages - Removes the old introductory video from both overviews, distinguishes shared infrastructure from standalone workflows, and links to factory setup. Shortens the standalone quickstart while retaining environment choices, execution consequences, and result inspection.
• Factory onboarding - Adds direct access and quickstart paths, retains permissions and repository prerequisites, and keeps team-assisted onboarding as an alternative. Changes the review instruction from Implement completion to foreman handoff.
• Developer tools and multi-agent guide - Separates factory dispatch and dashboard paths from standalone API and legacy web-app paths. Does not globally change WEB_APP_URL.
• Redirect regressions - Tests that the restored transition page is not shadowed by a redirect and the former map URL reaches it without another redirect.
• Quickstart accuracy - Corrects the prompt-first creation flow, setup-mode choices, exact field labels, repository-relative setup command, and Create environment action. Defers detailed billing requirements to existing references rather than restating a universal 20-credit minimum or paid-usage eligibility.

Content design plan

This records the intent of the supplied implementation plan, not a claim that a separate pre-draft artifact was completed.

Audience and JTBD: A developer or platform engineer with an existing Oz workflow assessing a move to a factory, or a team choosing between a standing development workflow and a standalone run. The factory quickstart also serves new Warp users creating their first factory; account/team setup belongs in its steps.

Problem: The documentation map replaced the transition explanation. Entry pages repeat infrastructure detail and blur factory setup with standalone workflows.

Goals:

• Readers can find the appropriate setup and inspection paths without treating factory and standalone workflows as interchangeable.
• Existing users can assess command, web-app, and SDK dependencies without relying on unconfirmed migration promises.
• Quickstart readers retain enough context to choose configuration and recognize a usable result.

Purpose and value: Restore the transition page's purpose rather than add another chooser page. Link to the references that own detailed command, API, and lifecycle behavior.

Content type: The transition page supports conceptual assessment, not a step-by-step migration. Existing overview, combined-feature, quickstart, and tutorial pages retain their roles.

Skill and template: The original transition text is the recovery scaffold, not a newly imposed template. Continued work uses draft_docs and relevant type guidance; retrospective skill execution is not asserted.

High-impact scenarios: Covers factory entry paths, standalone runs, legacy CLI use, and SDK/API routing. Excludes full workflow migration, broad billing/security corrections, schema rewrites, and Phase 2 navigation.

Unverified claims

• Billing requirements — question for eng/growth - Is the 20-credit minimum universal for cloud-agent and factory workflows, or specific to particular funding paths? Which included-credit, bonus-credit, pay-as-you-go, and overage paths are eligible, and are there separate launch/access checks? The cited server resolver supports multiple paths but is not complete policy confirmation or an authenticated billing test. Both quickstarts now defer detailed requirements to existing references. Billing/pricing pages remain unchanged and any broader correction belongs in separate work. Tracked follow-up after eng/growth confirmation: reconcile the remaining minimum-credit claims in src/content/docs/platform/team-access-billing-and-identity.mdx as separate billing-reference work.

• oz command and legacy web-app support - Current source still defines and packages the oz command tree (public client source) and builds the agents app for oz.warp.dev (web-app production source); the live URL still serves its sign-in page. This establishes current implementation and availability, but not a support commitment or deprecation date. CLI and platform owner confirmation is still required before publishing continued-support or retirement guidance. Automatic transfer of agents, skills, schedules, integrations, environments, credentials, and run history is also not established and is not promised.

• Account-specific availability - The factory quickstart links to account and team setup without promising those actions inside the factory wizard or automatic onboarding. Production open-access/role flags, plan entitlements, and account-specific GUI overrides were not authenticated or tested end to end. No waitlist is requester-confirmed.

• Run inspection - Source confirms factory/global routes and multiple feature-gated detail views. Production visibility, permission grants, history access, and successful control actions still need authenticated verification.

• Authenticated API behavior - Published SDK dispatch wrappers and server foreman resolution are verified. Live unauthenticated requests return authentication-required responses; successful authenticated dispatch and account entitlement were not tested.

• Factory launch/version mapping - October 6 SDK releases are independently verified. The October 7 desktop/CLI metadata does not identify a factory backend build or independently prove the October 6 Phase 1 deployment. The launch date remains requester-attributed; no desktop version is assigned to it.

Documentation risk

Risk: engineering-review-required
Rationale: Restores transition content and changes setup, access, and workflow-routing claims; technical verification remains incomplete.
Source files consulted: Public-doc diff through 1f3bcd3; released client commands.rs, terminal/view.rs, workspace/view.rs, update_environment_form.rs, and environment-selection sources at 1efc48d1e16665f1edb92425ccd649c573e25a9b; warp-server access/authz, factory dispatch, and logic/ai/ai_usage/cost_resolution.go at db5eaff4b665abf9dc2ee305733963a2ed4a95ef. Deployment, production flag state, and authenticated behavior are not established by source verification.
Engineering review status: pending
Docs override: none

Verification evidence

• Transition structure - Compared independently with fc2c1d6c and 45be6f43: the narrowed status table and web-app, CLI, and SDK/API sections remain. Final prose approval is an editorial checkpoint, not an unverified product claim.
• Released client flow and labels - Both slash commands remain registered. The cloud-mode creation callback selects the new environment and starts the pending request. See released creation flow. Default form copy confirms independent commands from /workspace; labels and actions were checked in the same release source.
• Billing qualification - The current credit resolver limits the 20-credit threshold to a specific credit-source branch, then considers other eligible sources. The quickstart no longer treats it as universal. This is code verification, not a live billing test.
• SDK names and publication - Python 1.0.0 and TypeScript 2.0.0 were published October 6. Registry artifacts confirm warp-platform-sdk and @warp-dot-dev/warp-platform-sdk, the current client exports, and factory dispatch wrappers. The old-named repositories remain active; older packages are not described as withdrawn.

Validation

At the current head:

• Local typecheck: 0 errors; 7 hints.
• Heading-variable tests: 5 passed.
• Build, generated heading TOCs, and homepage JSON-LD: passed.
• Internal links: 4,383 checked across 396 files; no broken links.
• Changed-file UI-reference scan: no reported issues.
• Style scan: 39 warnings across 17 branch-changed files, including historical Oz references needing contextual review and glossary suggestions; not a clean editorial verdict.
• Trunk is unavailable. Local Node 25 is outside the repository's supported range; Vercel reports deployment on Node 24.
• Installation reported dependency advisories and a successfully applied patch-version mismatch. No dependency remediation is included here.

Focused transition route invariants pass: restored page exists, no redirect shadows it, and the former map redirects to it. The continuation adds permanent regressions for these invariants: all 5 redirect tests pass; the static audit checks 536 destinations with 0 broken. Live verification and final editorial review remain unfinished. Passing CI does not establish migration or availability claims.

The continuation is committed and pushed as ea6ed667, including three refined public pages and scripts/test_check_redirects.py. Both quickstart compression checks pass. The revised guidance linter reports only 8 glossary warnings; its historical-name exemptions and negative controls pass, but that linter change belongs to the separate guidance branch and is not included here.

The source-verified quickstart corrections are committed and pushed as 3a3093ac. Typecheck (0 errors), heading-variable tests (5 passed), build, generated TOCs, homepage JSON-LD, internal links, UI-reference scan, redirect tests (5 passed), compression, and whitespace checks pass. The setup-command example was syntax-checked, not executed against a customer repository.

Initial review revision

Rachael authorized this feedback commit and push, keeping the PR draft and resolving fully addressed threads. Revision: eb873fbc.

• Clarifies web-app versus documentation destinations, new-user onboarding, credits/paid usage, and repository prerequisites without duplicating setup.
• Applies suggested prose, gives evaluation tools a concrete heading and bulleted list, and preserves standalone observability.
• Adds figure introductions/captions and a flow-only crop; aligns Unmanaged execution naming without changing its URL; defines the transition and repairs heading structure.
• Removes unsupported time estimates and future command-support assurances. Scheduled factory runs remain independent of external integrations.
• Local typecheck (0 errors, 7 hints), 5 heading-variable tests, build, generated TOCs (3,360 entries across 396 HTML files), homepage JSON-LD, internal links, UI-reference scan, both quickstart compression checks, 5 redirect tests, and whitespace checks pass. Style scan: 19 warnings (6 intentional historical-name references and 13 glossary suggestions). Trunk remains unavailable.
• Reusable feedback candidates are recorded separately on docs: reconcile drafting guidance and protect reader understanding #881; no guidance code, Phase 2 work, or live factory tasks change in this revision. Existing engineering/availability verification gaps remain open.

Independent review revision

Revision: a1d24880.

• Replaces unverified “legacy” labels with current variable-backed surface names while preserving the neutral oz reference guidance and unresolved support question.
• Removes duplicate narration, two unreferenced assets, defensive CLI wording, and the one-sentence preparation section; uses the 563px lifecycle-image tier.
• Narrows the factory quickstart to verified sign-in and team-selection steps, removes vague spending-limit copy, and keeps the existing no-time-estimate exception.
• Keeps the transition page in both the Factories and Automation Platform sidebars. Both entries share a URL that activates Factories rather than preserving the source tab.
• Final checks passed for MDX types (0 errors, 7 hints), heading variables (5 tests), the site build, generated TOCs (3,371 entries across 397 HTML files), homepage JSON-LD, internal links (4,381 checked), quickstart compression, redirects (5 tests), the PR contract, and whitespace. The style scan remains at 17 existing warnings (6 intentional historical-name references and 11 glossary suggestions). Trunk remains unavailable.

Dual-sidebar follow-up

Revision: 2dc76eac.

• Restores the intentional Automation Platform sidebar entry and documents why the duplicate route exists.
• A locally served production build exposes one transition sidebar link in each topic. Both reach /platform/transitioning-from-oz/, render the expected page, and activate Factories; entering from the Automation Platform does not preserve that source-tab context.
• Computer-use capture is unavailable in this run, so no video or screenshots were produced.

Follow-up review revision

Rachael reviewed the findings from review 5480807751 and authorized commit/push. Revision: 1f3bcd36.

• Uses neutral billing-reference wording in both quickstarts and records the eng/growth question above. No billing/pricing pages are edited.
• Names steps 4 and 5 explicitly; applies the approved foreman definition in the glossary and public pages; restores integration names; provides signup/team-setup links; deletes the redundant API-surface sentence; preserves Scorers capitalization and aligns Benchmarks with its linked title.
• Makes transition checks concrete, replaces the vague web-app setup-path sentence with resource/history checks, and distinguishes factory dispatch from shared run management. Removes the disputed transfer sentence without replacing it with a no-copy or transfer guarantee.
• Rechecked SDK names/repositories against PyPI and npm. Client parsers at c1ec372cbd3e4960661779a031172e854e7964e8 distinguish oz and warp; factory-run dispatch at warp-server b3041e6fb3b8330ab9a3e3ff200da8a4232f3da1 uses the shared run infrastructure. Both web-app URLs respond. These checks do not establish authenticated behavior, support commitments, resource transfer, or history continuity.
• Final local typecheck: 0 errors, 7 hints. All 5 heading-variable tests, build, 3,371 generated TOC entries across 397 HTML files, homepage JSON-LD, both quickstart compression checks, 4,383 internal links, and whitespace checks pass. Branch-wide style scan: 39 warnings across 17 files, not a clean editorial verdict. Trunk remains unavailable; existing build/runtime warnings remain.

Remaining review checkpoints

• Positioning synthesis and transition purpose/title/placement: approved by Rachael on October 9.
• Guidance/enforcement and readable evaluation pairs are published separately in docs: reconcile drafting guidance and protect reader understanding #881. They are not included in this PR.
• Identical-input comparisons and their limits are documented in docs: reconcile drafting guidance and protect reader understanding #881; no general drafting-performance improvement is claimed.
• Rachael's initial review is implemented; the revised wording remains available for normal editorial review. Broader billing-reference alignment remains outside this quickstart correction.
• Gather late-October migration decisions without publishing unconfirmed instructions.
• Review the public edits through this PR before marking it ready. Further commits and pushes require authorization. Guidance changes and their readable old/new evaluation excerpts belong in the separate guidance PR, not the local evaluation viewer.

Additional context

• Implementation plan: 1bdafdcc-6be7-4284-b463-e0c9fcf03d8b.
• Original work session.
• Continuation conversation.

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

Computer-use video recordings

Transitioning from Oz navigation: Platform vs Factories: Navigates from the Automation Platform overview and from the Factories overview to Transitioning from Oz, showing the active tab and sidebar selection each time.

Computer-use screenshots (2)

After clicking Transitioning from Oz from the Platform sidebar: URL /platform/transitioning-from-oz/, Factories tab active, Factories sidebar with Transitioning from Oz selected

After clicking Transitioning from Oz from the Factories sidebar: same URL /platform/transitioning-from-oz/, Factories tab active, sidebar item selected

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 10, 2026 11:07pm UTC

[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 refactors the Warp Factories and standalone cloud-agent documentation paths, removes the old documentation map, adds a transition page for existing Oz workflows, and updates sidebar and redirect entries accordingly.

Concerns

• No blocking concerns found. The changed links and key anchors resolve against the docs tree, the redirect for the removed documentation map points to the replacement page, and the diff does not introduce security-sensitive code or configuration changes.
• No approved or repository spec context was provided, so there is no implementation/spec drift to report.

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/platform/transitioning-from-oz.mdx:36 — [IMPORTANT] "Continue using oz commands for existing workflows" assures continued support, and the "legacy" labels (same file line 18, platform/index.mdx lines 15 and 19, platform/overview.mdx line 13) imply deprecation, but the PR's Unverified claims says support scope is unconfirmed. Requested change: reword neutrally, use {VARS.WEB_APP} and {VARS.WARP_AGENT_CLI} instead of "legacy", or record product-owner confirmation; if unresolved, add a VERIFY marker and list it under ## Unverified claims.
• src/content/docs/factories/quickstart.mdx:25 — [IMPORTANT] Step 1 ("sign in or create an account. Join or create the Warp team... onboarding opens automatically") and the line 11 intro state account and onboarding availability as fact, while the PR lists production access flags and entitlements as untested. Requested change: record authenticated verification, or narrow the wording to what source confirms and add a VERIFY marker listed under ## Unverified claims.
• src/content/docs/platform/overview.mdx:24 — [SUGGESTION] "The diagram shows this flow..." narrates the figure and duplicates the figcaption. Requested change: delete the sentence.
• src/content/docs/platform/overview.mdx:26 — [SUGGESTION] most-flexible-platform-for-building-with-agents.png and platform-architecture.png are no longer referenced under src/. Requested change: delete the unused assets or explain why they stay.
• src/content/docs/platform/overview.mdx:51 — [SUGGESTION] "Consult each command reference rather than treating the binaries as interchangeable" is defensive and repeats transitioning-from-oz.mdx line 18. Requested change: state the oz versus warp distinction once, plainly.
• src/content/docs/platform/index.mdx:31 — [SUGGESTION] The oz-use-cases.png figure uses the 736px tier instead of the 563px default. Requested change: check legibility at 563px and use it if readable.
• src/content/docs/platform/index.mdx:38 — [SUGGESTION] "Preparing a cloud-agent task" is a one-sentence section. Requested change: fold it into "What cloud agents are designed for" and remove the heading.
• src/content/docs/platform/quickstart.mdx:11 — [SUGGESTION] The quickstart no longer states a time budget (also factories/quickstart.mdx line 11), which AGENTS.md expects. Requested change: restore a supportable budget or note the deliberate exception in the PR body.
• src/content/docs/platform/quickstart.mdx:18 — [SUGGESTION] "Access and spending limits apply" gives the reader nothing to act on. Requested change: state the actual condition or drop the sentence and rely on the linked billing page.
• src/sidebar.ts:551 — [SUGGESTION] platform/transitioning-from-oz is listed in two sidebar topics (also line 404), the only duplicated slug. Requested change: confirm in the built site which tab is active when opened from Cloud agents, and keep it in one topic with a link from the other if the tab switches unexpectedly.

Verdict

Request changes

[warp-agent-staging]

Overview

The launch-doc update improves the Factories path, but product confirmation is needed before the self-service onboarding claim can be published.

Verdict

Checks: targeted tests pass; build not run locally because dependencies are absent; CI pending; visual proof n/a

Found: 0 critical, 0 important, 0 suggestions, 0 nits; 1 open question

Responding as Docs Factory (V2): Open session · View in factory

[warp-agent-staging]

Review summary

Public self-service availability is confirmed and no longer a concern, but the transition page still presents unverified legacy support as a user directive. Found: 0 critical, 1 important, 0 suggestions, 0 nits. Request changes.

Responding as Docs Factory (V2): Open session · View in factory

[warp-agent-staging]

Review summary

The revised transition guidance points readers to current CLI references without promising an unverified support window, and the PR body now makes the remaining owner-confirmation question explicit. No findings; approved at this head while required CI is still completing.

Responding as Docs Factory (V2): Open session · View in factory

[warp-agent-staging]

Review summary

All remaining review items are addressed: obsolete assets and duplicate copy/navigation were removed, transition terminology is neutral and variable-backed, and the quickstart guidance is concise and actionable. No findings; approved at this head while required CI completes.

Responding as Docs Factory (V2): Open session · View in factory

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/quickstart.mdx:18 — [IMPORTANT] "credits or paid usage" conflicts with the pages it links to. platform/team-access-billing-and-identity.mdx (lines 31 and 81) and platform/index.mdx (lines 87 and 99) still say teams need at least 20 credits. The same wording at factories/quickstart.mdx:16 links to platform-credits, which doesn't mention paid usage. The claim is also missing from ## Unverified claims. Requested change: align the linked billing pages and platform/index.mdx with the new wording, or revert to wording those pages support. Then add the claim, or the engineering confirmation, to ## Unverified claims and ## Documentation risk.
• src/content/docs/platform/quickstart.mdx:44 — [SUGGESTION] "Complete the next step; otherwise, skip to viewing the run." is a confusing conditional, and "viewing the run" doesn't name step 5. Requested change: split into two sentences, for example "If no environment is selected, submitting your request opens the creation form; complete step 4. If an environment is selected, go to step 5."
• src/content/docs/factories/index.mdx:47 — [SUGGESTION] The rewrite drops the definition "Every factory has one foreman, the agent you talk to," so "The foreman routes work..." uses the term before defining it. The closing link text "for support and configuration" is also vague. Requested change: restore a one-clause definition of the foreman and make the link text name the destination, such as "factory agents" with a concrete clause.
• src/content/docs/factories/index.mdx:61 — [SUGGESTION] "Connect chat services, issue trackers, and code forges" replaces the named list of Slack, Microsoft Teams, GitHub, GitLab, Azure DevOps, Linear, and Jira. This removes search-relevant terms from the overview page. Requested change: name the supported integrations in this paragraph, or confirm they are listed prominently on /factories/connect-your-factory/ and link there with that context.
• src/content/docs/platform/transitioning-from-oz.mdx:26 — [SUGGESTION] "Adopting a factory can involve changes to your workflow's configuration or integrations. Assess..." is a hedged, non-actionable opener. Requested change: state concretely what to check, such as the specific surfaces in the status table, or delete the paragraph since the subsections that follow already say it.
• src/content/docs/platform/transitioning-from-oz.mdx:30 — [SUGGESTION] "Creating a factory is not evidence that those resources or run history have transferred." is defensive phrasing that argues with an imagined reader. Requested change: state the fact plainly, for example "Agents, skills, environments, schedules, integrations, credentials, and run history are not copied when you create a factory." Verify that sentence with engineering first and add it to ## Unverified claims if unconfirmed.
• src/content/docs/factories/quickstart.mdx:25 — [SUGGESTION] The quickstart now assumes an existing Warp account and team ("Choose the Warp team that will own the factory"). Account and team creation was removed from the prerequisites, and a first-time user gets no path forward. Requested change: add one sentence or link for users without a team (for example the Get started with Warp link), or state that a team is required before starting.
• src/content/docs/factories/developer-tools.mdx:21 — [SUGGESTION] "Choose the endpoints for the work you want to run, then use the SDK and integration references to connect your tools." restates the bullets below it and adds no information. Requested change: delete the sentence.
• src/content/docs/platform/overview.mdx:67 — [NIT] "Scorers" is capitalized mid-sentence while "benchmarks" is lowercase. Requested change: use lowercase "scorers" in Use [scorers](/factories/measure-and-improve/scorers/), [benchmarks](...)....

Verdict

Request changes

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/index.mdx:83 — [IMPORTANT] The requirements under this heading (line 87) and under "For integrations" (line 99) still state an unqualified "at least 20 credits" threshold, while this PR removes that blanket minimum from platform/quickstart.mdx and its Unverified claims section says the threshold applies to one credit-source branch. platform/team-access-billing-and-identity.mdx (lines 31 and 81) repeats the claim. Requested change: use the same approved credits and paid-usage wording here, or link to the access-and-billing page instead of restating a number, and list the remaining pages as a tracked follow-up in the PR body.
• src/content/docs/platform/index.mdx:57 — [SUGGESTION] The heading "API access to tasks" uses a term that this page and platform/overview.mdx no longer define after the task and run-lifecycle sections were removed. Requested change: rename the heading to "API access to runs"; no inbound #api-access-to-tasks anchors exist.
• src/content/docs/platform/index.mdx:29 — [SUGGESTION] "Cloud agents can assist throughout the development lifecycle, from planning a change to validating it and investigating problems after deployment." restates what the figure below shows. Requested change: delete this sentence and keep the following sentence about trigger, context, and validation.
• src/content/docs/platform/transitioning-from-oz.mdx:24 — [SUGGESTION] The heading "Moving an existing workflow" promises migration steps, but the section only repeats the references already listed in the status table. Requested change: rename it to "Reviewing an existing workflow" and drop or merge the repeated sentences so each reference is linked once.
• src/content/docs/platform/transitioning-from-oz.mdx:30 — [SUGGESTION] "Check where you can access your existing run history." names no place to check. Requested change: link the page that owns run history (viewing cloud agent runs or /platform/oz-web-app/#runs), or delete the sentence if the answer is unconfirmed.
• src/content/docs/platform/transitioning-from-oz.mdx:20 — [NIT] The SDKs row label is the only unbolded surface name in the table. Requested change: write | **SDKs** | ... |.
• src/content/docs/factories/index.mdx:47 — [SUGGESTION] The foreman definition repeats factories/factory-agents.mdx:10 almost verbatim, and the rewrite dropped the example of where you talk to the foreman (Slack or Linear) from both pages. Requested change: keep the full definition on factory-agents.mdx, shorten this paragraph to one sentence plus the link, and restore the Slack or Linear example in one place.
• src/content/docs/factories/index.mdx:61 — [SUGGESTION] The work-sources paragraph dropped seven direct links to the Slack, Teams, GitHub, GitLab, Azure DevOps, Linear, and Jira integration pages in favor of one link to connect-your-factory. Requested change: keep the per-integration links in this sentence and keep the new connect-your-factory link.
• src/content/docs/platform/quickstart.mdx:82 — [SUGGESTION] The quickstart's closing section lacks the one-line recap AGENTS.md requires before next steps, and the old section had one. Requested change: add a sentence such as "You ran a cloud agent in an environment and inspected its output." before the list.
• src/sidebar.ts:551 — [SUGGESTION] The new wrapper group labeled "Overview" contains an item also labeled "Overview" and adds a nesting level although the PR states no tab reorder. Requested change: insert the platform/transitioning-from-oz entry as a flat item between platform/overview and platform/architecture, keeping the shared-URL comment.
• src/content/docs/platform/unmanaged-execution.mdx:2 — [SUGGESTION] The title and sidebar label now say "Unmanaged execution", but src/content/docs/factories/self-hosting/index.mdx still links to this page as "unmanaged architecture" (lines 19, 32, and 121). Requested change: update that link text to match the new title, or revert the rename into a separate change.

Verdict

Request changes

[rachaelrenk]

Warp agent note: intentional sidebar grouping

Rachael explicitly confirmed retaining the Automation Platform Overview group, with Overview, Transitioning from Oz, and Architecture nested beneath it. This matches the Factories tab structure and was a deliberate editorial/navigation choice.

The suggestion to flatten these pages is not being applied. Grouping pages within a tab does not reorder the tabs; the existing tab order and page URLs remain unchanged.

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/platform/unmanaged-execution.mdx:2 — [SUGGESTION] The page is renamed to "Unmanaged execution", but factories/self-hosting/external-orchestrators.mdx:117, guides/agent-workflows/run-a-software-factory-in-the-cloud.mdx:34, platform/handoff/snapshots.mdx:239, and platform/faqs.mdx:218,226,234 still link it as "Unmanaged architecture", and factories/self-hosting/index.mdx keeps the "## Unmanaged architecture" heading at line 105. Requested change: update those labels and the heading to "unmanaged execution", or limit the rename to the title and sidebar label and keep the surrounding terminology consistent.
• src/content/docs/factories/index.mdx:53 — [SUGGESTION] "Spec approval is part of the foreman's editable instructions, not a repository permission" is a new claim, and it reads against the next sentence, where repository permissions "control approval and merge access". Requested change: say which approval each sentence covers, for example "The foreman's instructions decide when it asks for spec approval. Repository permissions and branch protection control who approves and merges the pull request."
• src/content/docs/factories/index.mdx:61 — [SUGGESTION] "automations for scheduled work" links to /factories/automations/, which covers event triggers and filters but not schedules. platform/overview.mdx ("Integrations and triggers") has the same pointer. Requested change: link scheduled work to /factories/connect-your-factory/#direct-runs-and-schedules.
• src/content/docs/factories/index.mdx:96 — [SUGGESTION] "Get started with the Warp team - Get help choosing and setting up a workflow" describes VARS.GET_STARTED_URL as team-assisted onboarding, but the destination is titled "Get started with Warp Factories" and no source in the PR supports the assistance claim. Requested change: reword the link to match the destination, or add the claim to "Unverified claims" and confirm it with the page owner.
• src/content/docs/platform/quickstart.mdx:53 — [SUGGESTION] The cd REPO_DIR && npm ci example, the "relative to /workspace" claim, and the step 3 claims (input-footer environment selector, creation form opening on submit) are new technical claims. The cited client sources are private, nothing in this repo corroborates them, and the PR says the example was syntax-checked but not executed. Requested change: run the example against a real repository, or list these claims under "Unverified claims" so the engineering reviewer confirms them.
• src/content/docs/platform/index.mdx:23 — [SUGGESTION] The heading "What cloud agents are designed for" uses the "designed for" filler frame, and the following line "Cloud agents can assist throughout the development lifecycle." restates the figure. Requested change: retitle the heading (for example "Cloud agent use cases") and drop the lead-in sentence or fold it into the paragraph after the figure.
• src/content/docs/platform/index.mdx:76 — [SUGGESTION] "Billing and plan requirements" is now a one-sentence section that only links out, and the consequence that runs stop executing when credits run out no longer appears on the page. Requested change: merge the link into Related pages, or keep one plain sentence naming that consequence and link to the billing reference for details.
• src/content/docs/platform/transitioning-from-oz.mdx:17 — [SUGGESTION] The web app row ("Existing standalone cloud-agent workflows have their own web app setup and management paths") gives the reader nothing to act on, although the PR description says it was replaced with concrete resource and history checks. Requested change: name the task, for example "Manage environments, schedules, and integrations, and inspect run history, in the Oz web app."

Verdict

Approve with nits