docs: audit and polish the Warp Factories docs

[hongyi-chen]

Summary

Editorial and accuracy pass over the whole src/content/docs/factories/ tree (43 pages touched), on top of the overview rewrite already on hyc/factories-overview-copy. The two overview pages themselves are left as HYC's review pass shaped them; everything else gets one consistent treatment: claims re-checked against warp-server, duplicated content given a single home, AI-draft patterns cut, and the cross-page conventions (closing sections, link style, titles, terminology) made uniform.

Changes

Claims corrected against warp-server

• Built-in skills (factory-skills.mdx, factory-agents.mdx): the docs said every default agent gets a GitHub skill, the foreman a Slack skill, and that these "aren't files in your definition". Warp actually seeds code-quality, code-review, ui-verification, the connected code host's skill (github, gitlab, or azuredevops), slack/microsoft-teams, and linear/jira as files under the factory-wide skills/ directory, shared by every agent including custom ones (logic/factorysource/defaults/skills.go, logic/factory_source_export.go, logic/factoryfile/path.go).
• Default models (factory-agents.mdx): "setup doesn't choose models for you" replaced; setup seeds a model per role (defaults/seeds.go).
• Default Scorers (scorers.mdx, measure-and-improve.mdx): new factories ship with Code Quality (implement agent) plus Efficiency, Task Compliance, Procedure Compliance, and Verbosity (defaults/scorers.go). Previously undocumented.
• Factory MCP tool table (factory-mcp.mdx): added list_inbox, attach_integration, and start_factory_learning (factory_mcp/server.go; factory_learning is on in config/prod.yaml).
• Work-source lists now include Microsoft Teams and Azure DevOps where they were missing (automations.mdx, factory-dashboard.mdx, deployment-patterns.mdx); linear.mdx no longer points code-host access at GitHub only.
• warp-hosting.mdx no longer claims hosted agents take only Linux x86-64 images (contradicted runners.mdx).

One home per fact

• Dashboard metric definitions live on measure-and-improve.mdx; factory-dashboard.mdx summarizes and links.
• The bundled-skill ID table and read_skill attribution guidance live on api-and-sdk/index.mdx; factory-skills.mdx links.
• Built-in skills are explained once on factory-skills.mdx; factory-agents.mdx carries a two-sentence summary.

Structure and tone

• Every non-quickstart page ends with ## Related pages (added to connect-your-factory, factory-agents, github, gitlab, jira, linear, slack, api-and-sdk/index, the Sentry demo); list links use one plain [Title](link) - description style throughout.
• factory-agents.mdx: the run_agents/agent_identity_uid section is rewritten for a human reader; the automations paragraph gets its own heading; the two paragraphs restating the decision table are cut.
• automations.mdx opens with one definition instead of two overlapping ones; infrastructure-and-security.mdx leads with "What runs where" instead of "Control plane and execution plane"; the dashboard's self-referential naming callout is folded into the intro; recap and framing lines removed (factory-api, connect-your-factory, troubleshooting, automations).
• Formatting fixes: jira.mdx numbered list no longer breaks; benchmarks.mdx embeds and figures are separated from adjacent paragraphs and list items; --- separators and em/en-dash list separators normalized in the self-hosting and API pages; slashed shorthand and the stale oz note on api-and-sdk/index.mdx removed.

Consistency

• Integration page titles use the gerund form (Connecting Slack to your factory, and so on); URLs and sidebar labels unchanged.
• "Warp-managed" and "GitHub-backed" everywhere (no more "file-managed", "Managed in GitHub", "external repository"); "default automations" instead of "seeded"; lowercase agent names in prose; "work item" outside the MCP page, with the MCP page saying once that a task is a work item.
• Link text matches page titles (Factory benchmarks, Factory definition syntax); factory-as-code.mdx frontmatter label matches sidebar.ts; sidebar.ts label is now "How factories work".
• platform/orchestration/index.mdx updated for the renamed factory-agents.mdx anchor.

Left alone, on purpose

• api-and-sdk/troubleshooting/errors/* (generated from the sync-error-docs template).
• {/* VISUAL: ... */} screenshot markers (invisible to readers, placed by hand).
• The IP allowlist on warp-hosting.mdx.

Follow-ups worth a separate PR

• The factory learning phase (start_factory_learning) has a table row but no page of its own.
• Screenshots for the pages that still carry VISUAL markers.

Content design plan

Audience and JTBD: Teams evaluating or operating Warp Factories at launch, reading several pages in one sitting and expecting them to agree with each other and with the product.

Problem: Five weeks of agent and human PRs left the section with contradictory claims (built-in skills, default models), duplicated sections, inconsistent terms and link styles, and leftover AI-draft rhythm.

Goals:

• Every technical claim on a touched page matches warp-server at the cited SHA.
• A reader meets one term for each concept and one closing section shape on every page.

Purpose and value: Launch-readiness copy was reviewed page by page; this is the cross-page pass.

Content type: Existing feature, conceptual, reference, and procedural pages; no new pages.

Skill and template: Manual audit against AGENTS.md; style_lint, check_for_broken_links, and npm run build for validation.

High-impact scenarios:

• Covers: skills, agent defaults, Scorers, MCP tools, work sources, hosting claims, and every page's closing section.
• Excludes: the overview pages HYC is iterating on, generated error pages, and new screenshots.

Unverified claims

None. UI labels on the touched pages were left as written (they are backed by the existing screenshots); the changed technical claims are listed under Documentation risk with their source files.

Documentation risk

Risk: engineering-review-required
Rationale: Corrects product claims about built-in factory skills, default agent models, default Scorers, and the Factory MCP tool list; the rest is tone, consistency, and cross-link work. The seeded skill files and their factory-wide placement were also confirmed in logic/factory_source_export.go and logic/factoryfile/path.go at the same warp-server commit.
Source files consulted: warp-server/logic/factorysource/defaults/skills.go@cf7e9149d422, seeds.go@cf7e9149d422 (same directory), scorers.go@cf7e9149d422 (same directory), warp-server/router/handlers/public_api/factory_mcp/server.go@cf7e9149d422
Engineering review status: pending
Docs override: none

Validation

• npm run build passes.
• check_links.py --internal-only: 4,388 internal links, 0 broken.
• style_lint.py --all: no new findings on factories pages (remaining hits are pre-existing false positives on "Microsoft Teams" headers and a verbatim product string).

Plans:

• Audit and polish the Warp Factories docs (PR into hyc/factories-overview-copy)

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

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 6, 2026 11:49pm UTC

[hongyi-chen]

Split into five smaller PRs for review, each against hyc/factories-overview-copy with no overlapping files:

• docs: match factory agents and skills pages to the seeded defaults (audit 1/5) #853 agents and skills (the built-in skills and default-model corrections)
• docs: polish the measurement and dashboard pages (audit 2/5) #854 measurement and dashboard (default Scorers, one home for metric definitions, benchmarks formatting)
• docs: polish the factory integration and intake pages (audit 3/5) #855 integrations and intake (titles, Related pages, terminology, list completions)
• docs: polish the factory developer tool pages (audit 4/5) #856 developer tools (Factory MCP tool table, API pages cleanup, webhooks)
• docs: polish the factory infrastructure and self-hosting pages (audit 5/5) #857 infrastructure and self-hosting, plus the quickstart, troubleshooting, definition-page label, and sidebar fixes

Closing this one in favor of those.