docs(factories): surface the factory API and align factory-api/MCP/integration decision language - #622

Summary

Holistic editorial + IA pass on the Warp Factories developer-tooling story (factory API, Factory MCP, integrations, Agent API), requested after the recent wave of Factory API and tooling doc merges (#609, #590). Scope: warpdotdev/docs only, no product-code changes.

Audit

Walked the factories section, reference/api-and-sdk/, and the adjacent platform/guide cross-links against the four lenses in the ask: tone, consistency, discoverability, developer-tooling cohesion.

Discoverability — the factory API was invisible from the overview. factories/index.mdx's "What you get" list bundled the factory API's dispatch path into a bullet titled "Integrations and the Factory MCP," so a reader landing on the overview (the most common entry point from search) never saw that a REST/SDK path exists at all. "Next steps" had the same gap. Fix: renamed the bullet, named the factory API alongside Factory MCP, and added a "Work with a factory programmatically" next step.

Consistency — three different framings for the same decision. factory-api.mdx framed its choice as "factory API vs Agent API" (an endpoint-level question). connect-your-factory.mdx listed the factory API and Factory MCP as two rows in an intake table with no shared vocabulary between them. reference/api-and-sdk/index.mdx pointed at the factory API but never mentioned MCP or integrations as alternatives. A reader bounced between three unrelated framings instead of one decision path. Fix: added a single new section to factory-api.mdx, "Choosing how work reaches a factory" (bot/service/script → factory API; coding agent session → Factory MCP; chat platform/tracker → integration), kept the existing factory-API-vs-Agent-API table as a narrower subsection underneath it, and pointed the other two pages at it instead of restating the decision themselves.

Tone — already largely clean. factory-api.mdx and factory-mcp.mdx read well post-#609/#590 (active voice, no meta-openers, define-show-link). style_lint --changed on the touched files reports zero tone-buzzword or meta-opener hits. No tone rewrite was needed on the files I touched.

Sidebar — already correct. src/sidebar.ts already places Factory API directly above Factory MCP inside the "Integrations" group, with a code comment explaining why ("Alongside Factory MCP: both are direct API-style connection mechanisms..."). No reordering needed; left as-is.

DIY guides vs product — already distinct. guides/agent-workflows/set-up-a-software-factory.mdx already says "To run this same loop as a managed product instead of wiring it yourself, see Warp Factories" and links back from Related pages. No change needed.

Changes

src/content/docs/factories/index.mdx

• Renamed the "Integrations and the Factory MCP" bullet to "Multiple ways to send work in" and named the factory API alongside Factory MCP, with a link to connect-your-factory for the full picture.
• Added a "Work with a factory programmatically" item to Next steps, pointing at the factory API and Factory MCP.

src/content/docs/factories/factory-api.mdx

• Added a new "Choosing how work reaches a factory" section framing the factory API, Factory MCP, and integrations by who's calling in (bot/service/script, coding agent session, or a connected chat/tracker), with links out to Factory MCP and connect-your-factory for the other two paths.
• Kept the existing factory-API-vs-Agent-API comparison table as a subsection under the new framing (### The factory API vs the Agent API), unchanged in content.

src/content/docs/factories/connect-your-factory.mdx

• Reworded the "Factory API" section to use the same "bot, service, or script" language as factory-api.mdx, and linked to the new decision section for the full comparison.
• Linked "Factory MCP" in the "Factory MCP" section heading's prose (it wasn't linked before).

src/content/docs/reference/api-and-sdk/index.mdx

• Extended the existing factory-API migration note with a pointer to the new decision section, for the case where a coding agent or integration — not custom code — should start the work.

Coordination notes (open factory PRs)

Implemented against current main (post-#609, post-#590, post-#620). Cross-checked every related open PR listed on the ticket before editing:

• docs: clarify factory, foreman, and Factory MCP terminology #618 (factory/foreman/Factory MCP terminology) and Document single-prompt Factory MCP onboarding #585 (single-prompt Factory MCP onboarding) both make substantial edits to factory-mcp.mdx and #618 also touches factories/index.mdx's "What is a software factory?"/"Key terms" area and how-factories-work.mdx/factory-agents.mdx/quickstart.mdx/troubleshooting.mdx. I deliberately left factory-mcp.mdx and those other pages untouched and edited only sections of index.mdx those PRs don't touch (the "What you get" and "Next steps" lists), to avoid overlapping hunks. Aligning factory-mcp.mdx's own decision language is deferred to a follow-up once docs: clarify factory, foreman, and Factory MCP terminology #618/Document single-prompt Factory MCP onboarding #585 land — the new section on factory-api.mdx already links out to it, so nothing here presumes its content.
• docs: terminology sweep - CLI/API reference sunset callouts (GROW-6090) #593 (CLI/API reference terminology sweep) adds a callout near the top of reference/api-and-sdk/index.mdx; my edit is a separate paragraph further down (the existing factory-redirect sentence), no overlapping lines.
• docs: add Factory Dashboard metrics reference (APP-5546) #582 (Factory Dashboard metrics reference) touches src/sidebar.ts in the "Management & observability" group; I made no sidebar changes at all, so no overlap.
• docs(factories): document scorers/ in the definition syntax page #584 / docs(factories): document agentDefaults.computerUseModel (unreleased feature) #581 (factory-as-code scorers / computerUseModel) touch factory-as-code.mdx only, which this PR doesn't touch.
• docs: terminology cleanup, surface-map hygiene, and --mcp well-known-id docs #583 (terminology/surface-map hygiene) and docs: sync agent-api-openapi.yaml from warp-server #613 (OpenAPI sync) don't touch any file this PR changes.

No regressions to #609/#590 content: the factory-API-vs-Agent-API table from #609 is preserved verbatim, just nested under the new section; the sidebar ordering and comments from #590 are unchanged.

Content design plan

Short form (update adding a new decision-framework subsection, not a new page):

Reader and job: A developer or platform engineer deciding how to wire a factory into their own tooling — a bot, a coding agent, or an existing chat/tracker integration — who lands on the factories overview, the factory API page, or the Agent API reference from search.

Gap today: The factory API had no visibility from the overview's "What you get"/Next steps, and each of factory-api.mdx, connect-your-factory.mdx, and reference/api-and-sdk/index.mdx described the factory-API-vs-alternatives choice differently, so the reader had to reconcile three framings instead of following one.

Change: One decision-framework section on factory-api.mdx, linked from the other three pages, plus two index.mdx bullets naming the factory API. Excludes rewriting factory-mcp.mdx itself or the stage-naming/terminology work already in flight on #618/#585.

Unverified claims

None — every claim in the touched sections restates or links to existing, previously-shipped content (the factory API endpoints, Factory MCP tools, and Agent API endpoints were already documented pre-#609/#590); no new product behavior is asserted.

Verification

• style_lint --changed on the four touched files: 0 errors, 10 pre-existing unrecognized-term warnings on lines this PR didn't touch (glossary-candidate flags for terms like "GitHub"/"Jira"/"Early Access"), 0 tone/buzzword/meta-opener/callout findings.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only: 379 files scanned, 3911 internal links checked (including the new #choosing-how-work-reaches-a-factory anchor), 0 broken.
• npm run build: completed successfully; all pages including the four touched files prerendered without errors.
• Testing-exempt category: pure data/copy (docs IA/copy change, no runtime behavior) — the docs build and link check above are the applicable gate per factory-verification; no regression test applies.

Originating thread: https://warpdev.slack.com/archives/C09BVK0PL3Y/p1787616063014279

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