docs(factories): consolidated holistic pass — factory API surfacing, decision framework, and OpenAPI sync - #622
Conversation
…ation decision language Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
@warp-agent-staging[bot] 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 Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR updates the Warp Factories docs to make the factory API easier to discover, adds a decision framework for factory API vs Factory MCP vs integrations, and aligns related cross-links in the API/SDK reference. I found no correctness, link-target, terminology, security, or spec-alignment issues in the changed lines.
Concerns
- None.
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
# Conflicts: # src/content/docs/factories/index.mdx
…g across developer reference Consolidates three overlapping docs PRs into one per requester ask: - Keeps this PR's (#622) already-reviewed factory-API decision-framework section on factory-api.mdx as the base. - Folds in #626's OpenAPI sync (supersedes #613), the factory-api.mdx Endpoints rename + interactive reference link, and the tone/structure rewrite of reference/api-and-sdk/index.mdx, reference/index.mdx, reference/api-and-sdk/quickstart.mdx, reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx, and reference/api-and-sdk/troubleshooting/errors/index.mdx. - Re-threads the choosing-how-work-reaches-a-factory cross-link into the rewritten reference/api-and-sdk/index.mdx overview paragraph so neither PR's intent is lost.
warp-agent-staging
Bot
changed the title
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/docsonly, no product-code changes.Consolidated with #613 and #626 (see "### Rework changes" below) at the requester's ask in the originating thread: all three PRs covered overlapping developer-tooling/factory-API ground, so this PR now carries the combined, de-duplicated result instead of three separate PRs.
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.mdxframed its choice as "factory API vs Agent API" (an endpoint-level question).connect-your-factory.mdxlisted the factory API and Factory MCP as two rows in an intake table with no shared vocabulary between them.reference/api-and-sdk/index.mdxpointed 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 tofactory-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.mdxandfactory-mcp.mdxread well post-#609/#590 (active voice, no meta-openers, define-show-link).style_lint --changedon 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.tsalready 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.mdxalready 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.mdxconnect-your-factoryfor the full picture.src/content/docs/factories/factory-api.mdxconnect-your-factoryfor the other two paths.### The factory API vs the Agent API), unchanged in content.src/content/docs/factories/connect-your-factory.mdxfactory-api.mdx, and linked to the new decision section for the full comparison.src/content/docs/reference/api-and-sdk/index.mdx:::cautioncross-reference callouts, deduplicated the intro, renamed "Agents API" → "Agent API" per the glossary, backtickedAmbientAgentConfig, replaced the stale hand-maintained models list with a pointer to/api, and added a## Related pagesclosing section.Rework changes (PR consolidation)
Per the requester's ask in the originating thread to consolidate the three overlapping open docs PRs into one, this PR now also carries:
developers/agent-api-openapi.yaml+.agents/skills/sync-openapi-spec/— regenerated OpenAPI spec with thefactorytag no longer blanket-excluded, surfacing the public factory + scorer endpoints ondocs.warp.dev/api. This supersedes and replaces docs: sync agent-api-openapi.yaml from warp-server #613's earlier sync (see below).src/content/docs/reference/index.mdx— reworked into a map of every developer surface (Agent API reference, quickstart, API keys, errors, factory API, Factory MCP, both CLIs).src/content/docs/reference/api-and-sdk/quickstart.mdx— tone sweep (dropped---separators, fixed link-text casing, pointed the states reference at/api, restructured Next steps).src/content/docs/reference/api-and-sdk/demo-sentry-monitoring-with-sdk.mdx— tone sweep (real heading structure, neutral prose, added Related pages).src/content/docs/reference/api-and-sdk/troubleshooting/errors/index.mdx— sentence-cased the title, dropped---separators, renamed closing section to## Related pages.factory-api.mdxEndpoints rename/interactive-reference link and thereference/api-and-sdk/index.mdxrewrite, both combined with this PR's already-reviewed content rather than replacing it.Coordination notes (open factory PRs)
Implemented against current
main(post-#609, post-#590, post-#620, and now merged forward through the currentmaintip to pick up unrelated drift onfactories/index.mdxandconnect-your-factory.mdxfrom #618/#632/#641/#651). Cross-checked every related open PR listed on the ticket before editing:factory-mcp.mdxand#618also touchesfactories/index.mdx's "What is a software factory?"/"Key terms" area andhow-factories-work.mdx/factory-agents.mdx/quickstart.mdx/troubleshooting.mdx. I deliberately leftfactory-mcp.mdxand those other pages untouched and edited only sections ofindex.mdxthose PRs don't touch (the "What you get" and "Next steps" lists), to avoid overlapping hunks. Aligningfactory-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 onfactory-api.mdxalready links out to it, so nothing here presumes its content.reference/api-and-sdk/index.mdx; my edit is a separate paragraph further down (the existing factory-redirect sentence), no overlapping lines.src/sidebar.tsin the "Management & observability" group; I made no sidebar changes at all, so no overlap.computerUseModel) touchfactory-as-code.mdxonly, which this PR doesn't touch.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, the Agent API reference, or the Technical reference landing page from search.
Gap today: The factory API had no visibility from the overview's "What you get"/Next steps, each of
factory-api.mdx,connect-your-factory.mdx, andreference/api-and-sdk/index.mdxdescribed the factory-API-vs-alternatives choice differently, the interactive/apireference excluded every factory endpoint, and the Technical reference landing page didn't map the developer surfaces.Change: One decision-framework section on
factory-api.mdx, linked from the other three pages; twoindex.mdxbullets naming the factory API; the public factory/scorer endpoints synced into the interactive reference; and a tone/structure rewrite of the API & SDK overview pages. Excludes rewritingfactory-mcp.mdxitself or the stage-naming/terminology work already in flight on #618/#585.Unverified claims
warp-server/public_api/openapi.yamlx-internalmarkers ataa0ab5031; the regenerated file contains nox-internalcontent and only the public factory paths.Verification
style_lint --changedon the touched files: 0 new errors. One pre-existingUI-BACKTICKwarning on an unchanged line inquickstart.mdx(status_messagein backticks, present onmainbefore this PR) and pre-existingunrecognized-termwarnings on lines this PR didn't touch.python3 .agents/skills/check_for_broken_links/check_links.py --internal-only: 381 files scanned, 4001 internal links checked, 0 broken.npm run build: completed successfully, including regeneratingpublic/openapi.jsonfrom the updateddevelopers/agent-api-openapi.yamland prerendering all pages.factory-verification; no regression test applies.Note for the next reviewer: this PR was previously reviewed and approved before this consolidation rework (folding in #613 and #626) expanded its scope substantially — a fresh review pass covering the newly-folded-in content is warranted.
Originating thread: https://warpdev.slack.com/archives/C09BVK0PL3Y/p1787616063014279
Co-Authored-By: Warp agent@warp.dev