docs: rewrite the Warp Factories overview copy

[hongyi-chen]

Summary

The Warp Factories overview (docs.warp.dev/factories) read like a launch post rather than the entry page of technical docs: persona and feature-pitch sections ("Who benefits", "What you get"), a product-positioning table, heavy bullet-paragraphs, and an undefined "delivery policy" coinage, with no single place that said what a factory is. Its sibling how-factories-work opened with a different definition and repeated much of the same material.

This PR reshapes the overview into the register of the warp.dev/factories page and the GitHub Actions overview that AGENTS.md points to: a concrete definition with an example up front, one short section per part of a factory, sizing guidance, and related pages. The same one-sentence definition now appears on the overview, how-factories-work, and the docs homepage.

Changes

src/content/docs/factories/index.mdx

• New opening: a factory is a team of cloud agents attached to a set of repositories; names where work comes from, what the foreman does, and what comes back, with three example uses folded into one sentence.
• Added "The parts of a factory" with one short H3 each for work items, the foreman and factory agents (including the Foreman-name caveat), stages and checkpoints, the factory definition, work sources, execution, and measurement. Each defines the part in one to three sentences and links to its canonical page.
• Removed "Who benefits from Warp Factories", the six "What you get" bullet-paragraphs, the three-row product table, the "Key terms" framing and its duplicate mermaid diagram, and the "delivery policy" coinage.
• Promoted "Sizing a factory" to its own H2, so the #sizing-a-factory anchor linked from how-factories-work, connect-your-factory, and quickstart still resolves.
• Related pages now name their destinations instead of using CTA verbs ("Meet the factory agents", "Adapt the system").
• Rewrote the frontmatter description to say what a factory is instead of echoing the marketing headline (142 characters).

src/content/docs/factories/how-factories-work.mdx

• Opening definition aligned word for word with the overview.
• Cut the "Deciding which repositories belong in this factory is a separate question" meta line; the sizing link moved to Related pages.
• Tightened the diagram legend to one line per component and lowercased agent names per the glossary (stages stay capitalized).
• Cut "Your factory is self-improving, and you define what 'better' means."
• Added the Related pages section the style guide requires.

src/content/docs/index.mdx

• Warp Factories blurb uses the same definition as the overview.

Content design plan

• Reader and job: An engineer or engineering lead who landed on /factories from the marketing site or search and wants to know, in about a minute, what a factory is and how it is put together before deciding whether to read the quickstart.
• Gap today: The page sold the product instead of defining it, and the definition a reader could find differed from the one on how-factories-work one click away.
• Change: Replace the pitch sections with a concrete definition, one short section per part of a factory, and sizing guidance; align the definition across the three entry points. Excludes the stage-by-stage lifecycle and human-checkpoint detail, which stay on how-factories-work.

Unverified claims

None new. The rewrite adds no UI labels, paths, flags, defaults, or eligibility claims that were not already published on a canonical factories page. Each retained claim was checked against the page it links to (factory-agents for the harness list and Foreman name, how-factories-work for the default checkpoints, connect-your-factory for the source list, factory-dashboard for dashboard metrics, and measure-and-improve/self-improvement for proposals arriving as pull requests) rather than against warp-internal or warp-server. Review feedback confirmed that the factory never merges and repository permissions plus branch protection determine who can approve and merge.

Documentation risk

Risk: engineering-review-required
Rationale: Copy rewrite that restates existing claims (work sources, stages and checkpoints, execution and self-hosting, metrics, harness choice) on the overview, where some did not previously appear; classified conservatively per the policy. No source files in warp-internal or warp-server back the change, so no engineering owner resolves and none is requested; Docs validates each claim against the canonical factories page it links to. The pages consulted are all under src/content/docs/factories/ at the merged main SHA.
Source files consulted: factory-agents.mdx@b43e00b7, how-factories-work.mdx@b43e00b7, connect-your-factory.mdx@b43e00b7, factory-dashboard.mdx@b43e00b7, benchmarks.mdx@b43e00b7, measure-and-improve/self-improvement.mdx@b43e00b7, infrastructure-and-security.mdx@b43e00b7
Engineering review status: not-applicable
Docs override: none

Merge with #841

Merged main after #841 (Factories launch readiness) landed on the same three files. Kept its changes: the Early Access callouts are gone, the two-card "Get started / Open Warp Factories" CardGrid sits under the overview's intro, and the homepage sentence no longer mentions Early Access. Updated the overview's benchmarks sentence to "models, harnesses, and runners" to match the revised benchmarks page. Also applied the automated reviewer's suggestion ("repeated failures") and reclassified the risk level as it recommended.

The independent review's two suggestions are addressed in 892cc2d3: Microsoft Teams and Azure DevOps added to the how-factories-work legend, and the restated-consequence clause in the overview's Execution section replaced with what the infrastructure page covers. The sidebar's Early Access badge is left as is: #841 removed it and then deliberately restored it ("retain Factories Early Access badge").

Follow-up review findings are addressed in f66db114: the overview now returns the result, usually a pull request, to the source, and its examples no longer repeat the dispatch and checkpoint details covered below.

Additional context

• Validation: style_lint reports 0 errors on the three files (the remaining warnings are "bolded term not in glossary" notes on bold list lead terms); npm run build passes; the internal link checker finds 0 broken links; id="sizing-a-factory" and both LinkCards are present in the built /factories/ page.
• trunk check was not run locally (Trunk CLI not installed); relying on CI.
• Plan: Rewrite the Warp Factories overview copy
• Conversation: https://staging.warp.dev/conversation/9eb54357-e7b2-4479-9d52-fda764a8fa5b

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

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 7, 2026 12:14am UTC

[warp-for-oss]

@hongyi-chen

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 rewrites the Warp Factories overview and aligns related entry-point copy across the docs homepage and how-it-works page. The copy is clearer overall, and I did not find security-specific issues or spec drift because no approved spec context was provided.

Concerns

• The PR body declares Documentation risk as low, but this diff adds or changes public technical claims about supported work sources, stages/checkpoints, execution, self-hosting, metrics, and harness/model behavior. The docs quality policy's low-risk allowlist excludes changes to technical claim categories even when they are sourced from existing canonical pages, so this should be reclassified as engineering-review-required or carry an explicit docs verification/waiver.

Verdict

Found: 0 critical, 1 important, 1 suggestions

Request changes

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]

💡 [SUGGESTION] Use “repeated failures” here; “repeat failures” reads like a typo.

Suggested change

	* **Measure and improve** - [Scorers](/factories/measure-and-improve/) classify completed runs, benchmarks compare configurations, and Self-improvement turns repeat failures into pull requests for your review.
	* **Measure and improve** - [Scorers](/factories/measure-and-improve/) classify completed runs, benchmarks compare configurations, and Self-improvement turns repeated failures into pull requests for your review.

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/how-factories-work.mdx:18 — [SUGGESTION] The Work sources legend item omits Microsoft Teams and Azure DevOps, which src/content/docs/factories/index.mdx:59 lists, so the two pages disagree. Requested change: add both sources, linked to /factories/integrations/teams/ and /factories/integrations/azure-devops/.
• src/content/docs/factories/index.mdx:63 — [SUGGESTION] The clause "so the same runners, models, APIs, and security controls apply" restates the consequence of the previous clause. Requested change: cut it, or replace it with the one control that matters to the reader and link to infrastructure and security.

Verdict

Approve

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/index.mdx:51 — [IMPORTANT] "Merging is enforced by your repository's branch protection" implies branch protection is always in place, but how-factories-work.mdx:71 only recommends it for human-only merges and factory-agents.mdx:153 says repository permissions decide who merges. Requested change: say the factory never merges and that repository permissions and branch protection decide who can.
• src/content/docs/index.mdx:34 — [SUGGESTION] "returns a pull request where the work started" is inaccurate for Slack, Teams, and Jira sources, where the pull request is opened in the repository and linked back. Requested change: match the overview wording, for example "returns the result, usually a pull request, where the work started."
• src/content/docs/factories/index.mdx:59 — [SUGGESTION] The Work sources paragraph has ten links and repeats the source lists in how-factories-work.mdx:18 and connect-your-factory.mdx. Requested change: shorten it to a sentence naming a few sources and link to connect-your-factory for the full list.
• src/content/docs/factories/index.mdx:67 — [SUGGESTION] "shows work items by stage" is not documented on factory-dashboard.mdx, and the same phrase is on how-factories-work.mdx:24. Requested change: describe what the Dashboard page shows (autonomy, cycle time, runs, cost per pull request) or link to a page that documents a stage view, and fix both pages.
• src/content/docs/factories/index.mdx:4 — [SUGGESTION] The PR title and body still describe an enterprise/index.mdx rewrite that head commit 9de16d4 reverted, including the risk rationale and Source files consulted list. Requested change: update the PR title and body to cover only the three changed pages, or restore the Enterprise change.

Verdict

Request changes

[warp-agent-staging]

Two factual claims need correction before approval. Current-head CI passes the build, link, editorial, technical-reference, CodeQL, and Vercel checks; local style, link, risk-contract, and compression checks also pass.

Found: 0 critical, 2 important, 1 suggestion, 0 nits.

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

[warp-agent-staging]

This PR was generated with Warp.

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

  

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/index.mdx:13 — [SUGGESTION] The lead says a factory "returns a pull request where the work started", but a pull request isn't always where work starts (Slack, Linear, Jira), and line 30 says "usually as a pull request". The docs homepage uses "returns the result, usually a pull request, where the work started", so the definition sentence differs across the overview, how-factories-work.mdx, and index.mdx despite the PR's alignment claim. Requested change: use the homepage wording "returns the result, usually a pull request, where the work started", or reuse one identical sentence on all three pages.
• src/content/docs/factories/index.mdx:30 — [SUGGESTION] The foreman dispatching the triage, spec, implement, and review agents is stated on lines 13, 30, and 49, and the human checkpoints on lines 32 and 55, which breaks the "Say it once" rule in AGENTS.md. Requested change: cut the first sentence of this paragraph or the matching text under "Foreman and factory agents", and fold the line 32 checkpoint sentence into the "Stages and checkpoints" section.

Verdict

Approve

[warp-agent-staging]

All requested fixes are addressed on the current head, and the final independent re-review found no remaining findings. Local build, style, link, risk-contract, and compression checks pass; current CI has no failures.

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/factories/index.mdx:43 — [SUGGESTION] The work item definition ("an issue, a support thread, a pull request, or a scheduled job") differs from how-factories-work.mdx:12 ("issue, support request, pull request, or Factory MCP task"), so two pages define the same term differently. Requested change: define it once and link to it from the other page, or use the same examples in both.
• src/content/docs/factories/index.mdx:28 — [SUGGESTION] The "What a factory does" section is a single sentence before the video and diagram. Requested change: fold the sentence into the opening paragraph at line 13 and place the video and diagram under "The parts of a factory", or add concrete detail to the section.
• src/content/docs/factories/index.mdx:61 — [SUGGESTION] The Work sources paragraph lists the same eleven sources as how-factories-work.mdx:18 and connect-your-factory.mdx, giving three copies to keep in sync. Requested change: name the main sources and link to connect your factory for the full list.
• src/content/docs/factories/index.mdx:69 — [SUGGESTION] The metric names "pull request cycle time" and "cost per pull request" don't match the dashboard labels PR cycle time and Cost per PR in factory-dashboard.mdx, and that page isn't listed under Source files consulted. Requested change: use the dashboard's labels or drop the metric names and link to the dashboard, and add factory-dashboard.mdx to Source files consulted in the PR body.
• src/content/docs/factories/index.mdx:65 — [NIT] "ordinary" in "an ordinary cloud agent run" adds nothing. Requested change: remove it (suggestion block provided in the inline comment).

Verdict

Approve with nits