diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx
index eb87c381c..372438085 100644
--- a/src/content/docs/factories/how-factories-work.mdx
+++ b/src/content/docs/factories/how-factories-work.mdx
@@ -7,24 +7,22 @@ sidebar:
label: "How factories work"
---
-A factory is a fleet of agents wired to your software development lifecycle. It connects your repositories and tools to move requests through triage, specification, implementation, review, and verification, while people stay in control of key decisions. You talk to one agent, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, and each one owns a part of the software development lifecycle.
-
-Deciding which repositories belong in this factory is a separate question. See [sizing a factory](/factories/#sizing-a-factory) for that guidance.
+A factory is a team of cloud agents attached to a set of repositories. You talk to one of them, the **foreman**, from the tool that sends the request, such as Slack or Linear. The foreman dispatches the factory's other agents, each of which owns one part of the software development lifecycle, and people make the key decisions along the way.
A **work item** is a single request the factory acts on, such as an issue, support request, pull request, or Factory MCP task. It keeps its identity from intake to handoff, however many agents contribute to it along the way.
-The diagram's components, from intake to improvement:
+The diagram, from intake to improvement:
-* **Work sources** - Work items arrive from [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), from [custom webhooks](/factories/webhooks/) and [factory endpoints](/factories/factory-api/), from local coding agents through the [Factory MCP](/factories/factory-mcp/), or from direct runs and schedules.
-* **Automations** - [Automations](/factories/automations/) filter provider events and decide which agent handles them. Schedules fire them on a timer; direct requests go straight to the foreman.
-* **Foreman and stage agents** - The foreman holds one conversation per work item and dispatches the Triage, Spec, Implement, and Review agents as the work needs them. See [factory agents](/factories/factory-agents/) and the stages below.
-* **Human handoff** - The factory opens a pull request with evidence, updates the original work item, and you review and merge.
-* **Factory definition** - Version-controlled agents, automations, runners, scorers, skills, and webhooks define the factory, either Warp-managed or in a GitHub repository your team owns. See [definitions as code](/factories/factory-as-code/).
-* **Execution** - Every stage runs as a cloud agent run on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, with the workspace from the factory's repositories and each stage's configured model and [harness](/platform/harnesses/).
-* **Factory dashboard** - Metrics, work items by stage, and runs and costs. See the [factory dashboard](/factories/factory-dashboard/).
-* **Measure and improve** - [Scorers](/factories/measure-and-improve/) classify completed runs, benchmarks compare configurations, and self-improvement turns repeat failures into follow-up pull requests for your review.
+* **Work sources** - [Slack](/factories/integrations/slack/), [Microsoft Teams](/factories/integrations/teams/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), [Jira](/factories/integrations/jira/), [custom webhooks](/factories/webhooks/), [factory endpoints](/factories/factory-api/), the [Factory MCP](/factories/factory-mcp/), direct runs, and schedules.
+* **Automations** - [Automations](/factories/automations/) filter provider events and schedules and decide which agent handles them. Direct requests go straight to the foreman.
+* **Foreman and stage agents** - The foreman holds one conversation per work item and dispatches the triage, spec, implement, and review agents as the work needs them. See [factory agents](/factories/factory-agents/).
+* **Human handoff** - The factory opens a pull request with evidence and updates the original work item. You review and merge.
+* **Factory definition** - Version-controlled agents, automations, runners, scorers, skills, and webhooks, either Warp-managed or in a GitHub repository your team owns. See [definitions as code](/factories/factory-as-code/).
+* **Execution** - Every stage is a cloud agent run on Warp-hosted or [managed self-hosted](/factories/self-hosting/) compute, using the factory's repositories and each stage's configured model and [harness](/platform/harnesses/).
+* **Factory dashboard** - Metrics, work items by stage, runs, and costs. See the [factory dashboard](/factories/factory-dashboard/).
+* **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.
## How a work item moves through the factory
@@ -64,7 +62,7 @@ Stages and agents are named separately, so the spec agent works the Planning sta
## Where your team stays in charge
-A factory is built to pause when there is a decision that needs to be made by a person. By default, that's three places:
+A factory pauses when a person needs to decide. By default, that's three places:
* **Approving the spec** - When work goes through the Planning stage, the Building stage waits until a person signs off on the plan.
* **Answering questions** - When requirements are unclear or a review finding is ambiguous, the foreman asks instead of guessing.
@@ -74,8 +72,14 @@ The first two are workflow policy, written into the foreman's instructions; edit
## How the factory improves itself
-Your factory is self-improving, and you define what "better" means. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, and [Self-improvement](/factories/measure-and-improve/self-improvement/) groups the failures they flag into follow-up runs that propose fixes — to the application code or to the factory's own definition. Every proposal arrives as a change for your review; nothing is adopted on its own.
+[Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, and [Self-improvement](/factories/measure-and-improve/self-improvement/) groups the failures they flag into follow-up runs that propose fixes to the application code or to the factory's own definition. Every proposal arrives as a pull request for your review; nothing is adopted on its own.
The factory's definition is open to the same loop. Anyone on the team, or an agent, can propose changes to its instructions, skills, models, or other [definition files](/factories/factory-as-code/), and definitions stored in GitHub go through pull request review and [configuration checks](/factories/factory-as-code/#pull-request-checks) before a change reaches the production branch.
-See [measure and improve](/factories/measure-and-improve/) for the evaluation workflow, or [build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent/) to apply the same pattern to a standalone agent.
+## Related pages
+
+* [Sizing a factory](/factories/#sizing-a-factory) - Which repositories belong in one factory.
+* [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure it.
+* [Connect your factory](/factories/connect-your-factory/) - Every way work can enter a factory.
+* [Measure and improve](/factories/measure-and-improve/) - Scorers, benchmarks, and Self-improvement.
+* [Build a self-improving agent](/guides/agent-workflows/build-a-self-improving-agent/) - Apply the same loop to a standalone agent.
diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx
index d0945518f..6fab7c08d 100644
--- a/src/content/docs/factories/index.mdx
+++ b/src/content/docs/factories/index.mdx
@@ -1,8 +1,8 @@
---
title: Warp Factories overview
description: >-
- Warp Factories is open infrastructure for building internal software
- factories as code, from triage to implementation, review, and monitoring.
+ Warp Factories turns issues, tickets, and Slack requests into reviewed pull
+ requests with teams of cloud agents, while people approve specs and merges.
sidebar:
label: "Overview"
---
@@ -10,7 +10,7 @@ import { VARS } from '@data/vars';
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
import VideoEmbed from '@components/VideoEmbed.astro';
-A factory is a group of agents that shares repositories and delivery policy. Its foreman accepts work from connected tools, dispatches the right agents, and returns the result to the source.
+A factory is a team of cloud agents attached to a set of repositories. It takes work from Slack, GitHub, Linear, or Jira through triage, spec, implementation, and review, and returns the result, usually a pull request, where the work started.
+## What a factory does
+
+A factory can work through a backlog of issues, fix defects reported in a support channel, or review incoming pull requests across several repositories.
+
-## What is a software factory?
+
+
+The software factory loop. The default agents cover triage through review.
+
-Each request becomes a work item, such as an issue, ticket, or triggered task. Specialized agents can triage it, write a specification, implement the change, and review the result.
+## The parts of a factory
-Each factory applies a single policy across its work sources, so deploy separate factories for repository groups that need different policies.
+### Work items
-### Sizing a factory
+A work item is one request the factory acts on: an issue, a support thread, a pull request, or a scheduled job. It keeps its source context from intake to handoff, however many agents contribute along the way.
-Size factories by product surface, not by workflow. Group the repositories that ship together into one factory. For example:
+### Foreman and factory agents
-* One factory for your main application
-* One factory for your marketing site
-* One factory for your data pipelines
+Every factory has one foreman, the agent you talk to. It decides which agent a work item goes to next, asks you when it needs a decision, and hands back the finished pull request. Behind it are the default triage, spec, implement, and review agents; add custom agents for work they don't cover. Each agent can run on its own model and harness, including the Warp Agent, Claude Code, and Codex. See [factory agents](/factories/factory-agents/).
-Don't split those same repositories across multiple factories by team or task (frontend vs. platform, for example). Add [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/) to specialize instead.
+Setup gives the foreman the same handle as the factory, so `payments` is the factory and `@payments` reaches its foreman from Slack or Linear. See [Foreman name](/factories/factory-agents/#foreman-name).
-
-
-The general software factory loop. Warp Factories' default agents cover triage through review; add custom agents for the rest.
-
+### Stages and checkpoints
+
+The foreman moves a work item through the Triage, Planning, Building, and Reviewing stages, skipping the ones a well-defined request doesn't need and sending work back when review finds problems. Spec approval and the foreman's questions are written into its instructions, which your team can edit. The factory never merges. Your repository's permissions and branch protection determine who can approve and merge. See [how Warp Factories work](/factories/how-factories-work/).
-## Who benefits from Warp Factories
+### Factory definition
-Warp Factories is for engineering teams with repeatable work that extends beyond one coding session:
+A factory's repositories, agents, automations, runners, skills, and MCP servers are declared in definition files, either managed by Warp or stored in a GitHub repository your team owns. Changes to a GitHub-backed factory go through pull request review like any other code. See [definitions as code](/factories/factory-as-code/).
-* Process a backlog of issues with a consistent triage and delivery policy.
-* Fix defects reported through support channels.
-* Review incoming pull requests or maintain services across repositories.
+### Work sources
-## What you get with Warp Factories
+Connect [Slack](/factories/integrations/slack/), [Microsoft Teams](/factories/integrations/teams/), [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), [Linear](/factories/integrations/linear/), or [Jira](/factories/integrations/jira/), and the factory posts results back in the same thread, issue, or pull request. [Custom webhooks](/factories/webhooks/) and [factory endpoints](/factories/factory-api/) cover other systems, schedules start recurring work, and the [Factory MCP](/factories/factory-mcp/) lets a local coding agent hand work to a factory and take it back. See [connect your factory](/factories/connect-your-factory/).
-* **Coordinated specialist agents** - A team of [factory agents](/factories/factory-agents/) handles each work item. A coordinating foreman routes it through the triage, spec, implement, and review agents, skipping stages that don't apply. You can add custom agents and automations to handle work the defaults don't cover.
-* **Definitions as code** - [Version-controlled definition files](/factories/factory-as-code/) describe your repositories, agents, automations, runners, [skills](/factories/factory-skills/), and MCP servers, so factory changes get the same review, history, and rollback as code changes.
-* **Code forges and work sources** - Connect [GitHub](/factories/integrations/github/), [GitLab](/factories/integrations/gitlab/), [Azure DevOps](/factories/integrations/azure-devops/), or [another code forge](/factories/code-forges/other-code-forges/) to the repository your factory works in. Route work from [Slack](/factories/integrations/slack/), [Linear](/factories/integrations/linear/), [Jira](/factories/integrations/jira/), [custom webhooks](/factories/webhooks/), direct runs, or schedules. The [Factory MCP](/factories/factory-mcp/) connects coding agents and other MCP clients.
-* **Model and harness choice** - Each agent can use a different model and [supported harness](/platform/harnesses/), including the Warp Agent, Claude Code, and Codex.
-* **Measurement and self-improvement** - The [factory dashboard](/factories/factory-dashboard/) shows work-item status, runs, automations, costs, and benchmarks. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs, [Benchmarks](/factories/benchmarks/) compare fixed tasks across configurations, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into follow-up work the factory proposes for review.
-* **Infrastructure control** - Choose Warp-hosted execution, or use managed self-hosted execution on an eligible Enterprise plan. The [infrastructure and security](/factories/infrastructure-and-security/) page compares execution models and links to the self-hosting setup path, as well as available inference and credential controls.
+### Execution
-## How Warp Factories fits into Warp
+Every agent run in a factory is an ordinary [cloud agent run](/platform/) on the {VARS.WARP_AUTOMATION_PLATFORM}. Runs execute on Warp-hosted compute by default; Enterprise teams can keep checkout and execution on their own infrastructure with [managed self-hosting](/factories/self-hosting/). See [infrastructure and security](/factories/infrastructure-and-security/) for runners, inference, and credential boundaries.
-Warp Factories builds on the same agent infrastructure used across Warp. Every factory agent produces a standard [cloud agent run](/platform/), so the same APIs, runners, models, security controls, and observability apply.
+### Measurement
-| Product | Role |
-| --- | --- |
-| **Warp** | The interactive development experience for local work with agents and code review. |
-| **Warp Agent** | The built-in agent harness that can power an individual factory agent. |
-| **Warp Factories** | Multi-agent workflows for software development. |
+The [factory dashboard](/factories/factory-dashboard/) shows autonomy, pull request cycle time, cost per pull request, opened versus merged pull requests, and run breakdowns. [Scorers](/factories/measure-and-improve/scorers/) classify completed runs against criteria you write, [benchmarks](/factories/benchmarks/) compare models, harnesses, and runners on the same tasks, and [Self-improvement](/factories/measure-and-improve/self-improvement/) turns repeated failures into pull requests for your review. See [measure and improve](/factories/measure-and-improve/).
-## Key terms
+## Sizing a factory
-Setup gives a factory and its foreman the same name by default, so it's easy to mistake one for the other. Here's how the terms differ:
+Group the repositories that ship together into one factory, and keep separate products in separate factories. For example:
-* **factory** - The repositories, delivery policy, agents, and connected tools that handle a related set of work. It is distinct from Warp Factories, the product, and from the foreman, its coordinating agent.
-* **foreman** - The coordinating agent inside a factory, and the only one you talk to. It dispatches the other [factory agents](/factories/factory-agents/) and reports back. Every factory has exactly one.
-* **Foreman name** - The handle your team @-mentions in Slack and Linear to reach the foreman. Setup copies it from the factory's name, so the two usually match even though they're different things. See [Foreman name](/factories/factory-agents/#foreman-name).
+* One factory for your main application
+* One factory for your marketing site
+* One factory for your data pipelines
-```mermaid
-flowchart LR
- subgraph Factory["One factory"]
- Foreman["Foreman"] --> Agents["Triage, spec, implement, and review agents"]
- end
- Slack["Slack or Linear"] -->|"@handle"| Foreman
-```
+Don't split the same repositories across factories by team or task, such as frontend and platform. Add [agents](/factories/factory-agents/) and [skills](/factories/factory-skills/) to specialize instead.
## Related pages
-* [**Set up a factory**](/factories/quickstart/) - Create a factory and send its first work item.
-* [**Understand the execution model**](/factories/how-factories-work/) - See how the foreman coordinates stages, runs, and human decisions.
-* [**Meet the factory agents**](/factories/factory-agents/) - See what each agent does and how to configure its model, harness, and instructions.
-* **Adapt the system** - [Define the factory as code](/factories/factory-as-code/) and [connect its work sources](/factories/connect-your-factory/), or start from a working definition in [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples).
+* [Warp Factories quickstart](/factories/quickstart/) - Create a factory and send its first work item.
+* [How Warp Factories work](/factories/how-factories-work/) - The work-item lifecycle, stage by stage.
+* [Factory agents](/factories/factory-agents/) - What each default agent does and how to configure its model and harness.
+* [Definitions as code](/factories/factory-as-code/) - The definition file format, with working examples in [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples).
diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx
index e3695b83f..7b1666c57 100644
--- a/src/content/docs/index.mdx
+++ b/src/content/docs/index.mdx
@@ -31,7 +31,7 @@ The {VARS.WARP_AUTOMATION_PLATFORM} runs cloud agents from triggers, schedules,
## Warp Factories
-A factory turns incoming engineering work into a repeatable, multi-stage workflow with specialized agents, review points, and measurable outcomes.
+A factory is a team of cloud agents attached to a set of repositories. It takes work from Slack, GitHub, Linear, or Jira through triage, spec, implementation, and review, and returns the result, usually a pull request, where the work started.
* [Warp Factories overview](/factories/) - Learn how a factory receives, routes, and tracks work.
* [Factory quickstart](/factories/quickstart/) - Create a factory and send it its first work item.