docs(factories): screenshots and content polish

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

@@ -11,7 +11,7 @@ Connect your factory to the tools where your team already discusses, tracks, and
 
 ## Choose a source
 
-Pick the sources that match where work starts for your team. You can connect more than one, though a factory can use Linear or Jira, or no tracker at all, but not both at once. The setup wizard currently offers Linear; to use Jira, connect it after setup or in your [factory definition](/factories/factory-as-code/).
+Pick the sources that match where work starts for your team. You can connect multiple sources, but not both Linear and Jira at the same time. The setup wizard currently offers Linear; to use Jira, connect it after setup or in your [factory definition](/factories/factory-as-code/).
 
 | Source | Best for | Where follow-ups continue |
 | --- | --- | --- |
@@ -25,10 +25,9 @@ Pick the sources that match where work starts for your team. You can connect mor
 
 ## Connect a source
 
-1. Pick the factory you want to connect. If you don't have one yet, follow the [Warp Factories quickstart](/factories/quickstart/).
-2. Connect the source: install the provider integration, set up the [Factory MCP](/factories/factory-mcp/), or create a schedule. Each integration guide below walks through authorization; grant only the access the factory needs.
-3. Tell the factory how to respond. Provider connections come with default automations that decide which events start work and which agent handles them. Review their [filters](/factories/automation-filters/) and run settings. Filters route work, not access: what a running agent can reach depends on its own configuration, not the filters that started it. Schedules and direct runs skip this step.
-4. Send a test request, such as mentioning the factory in Slack or assigning it an issue, and confirm it picks up the work and replies at the source.
+Each source's integration guide walks through authorizing access; grant only what the factory needs. Provider connections come with default automations that decide which events start work and which agent handles them. Review their [filters](/factories/automation-filters/) and run settings after connecting. Filters route work, not access: what a running agent can reach depends on its own configuration, not the filters that started it.
+
+After connecting, send a test request, such as mentioning the factory in Slack or assigning it an issue, and confirm it picks up the work and replies at the source.
 
 ## How work reaches your factory
 
@@ -42,9 +41,9 @@ flowchart LR
   Work --> Results["Results posted<br/>back to the source"]
 ```
 
-An event from a connected tool starts the automation whose filters match it, such as a specific repository, channel, or label. Schedules start their automation on a timer, and direct requests go straight to the factory.
+An event from a connected tool starts the automation based on filter matching, such as a specific repository, channel, or label. Schedules start their automation on a timer, and direct requests go straight to the factory.
 
-Every request then lands with the foreman agent, the factory's orchestrator. The foreman turns the request into a work item, determines which stage the work needs next, and dispatches a specialized agent for each stage: triage to scope the request, spec when the design needs agreement, implementation to write the code, and review to check it. Between stages it relays questions and progress back to the source, and it pauses wherever a decision belongs to a human, such as approving a spec or [merging a pull request](/factories/how-factories-work/#where-your-team-stays-in-charge). A reply in the same thread, issue, or pull request adds to that work item instead of starting a new one, and repeated event deliveries from a provider don't create duplicates. See [how Warp Factories work](/factories/how-factories-work/) for the full lifecycle.
+Every request lands with the foreman agent, which turns it into a work item and dispatches the agents each stage needs. A reply in the same thread, issue, or pull request continues that work item instead of starting a new one, and repeated event deliveries don't create duplicates. See [how Warp Factories work](/factories/how-factories-work/) for the full lifecycle, including where people stay in the loop.
 
 ## Review the default automations
 
@@ -58,25 +57,13 @@ When you create a factory through the setup wizard, Warp adds default automation
 
 These defaults are starting points. Review each automation's filters, agent, and run settings, and adjust them to match your workflow.
 
-## Integration guides
-
-* [Slack](/factories/integrations/slack/) - Route chat requests, direct messages, and thread follow-ups through a dedicated factory app.
-* [GitHub](/factories/integrations/github/) - Route repository events with issue, pull request, review, or CI context.
-* [GitLab](/factories/integrations/gitlab/) - Route merge request events and bot mentions through a per-factory service account.
-* [Linear](/factories/integrations/linear/) - Route planned issues through issue activity and agent sessions.
-* [Jira](/factories/integrations/jira/) - Route Jira work items assigned to Warp into factory work.
-
 ## Factory MCP
 
-The Factory MCP connects local coding agents and other MCP clients to your factory, and it works in both directions: send work to the factory, or take work over from it — pull a task down to your machine, iterate on it locally, and hand it back to the same work item. See the [Factory MCP guide](/factories/factory-mcp/).
+The Factory MCP connects local coding agents and other MCP clients to your factory, and it works in both directions. Send work to the factory, or take work over from it by pulling a task down to your machine, iterating on it locally, and handing it back to the same work item. See the [Factory MCP guide](/factories/factory-mcp/).
 
 ## Direct runs and schedules
 
 Not every task starts in an external tool:
 
-* Start a direct factory run for one-off work: describe the task and the foreman agent takes it from there.
-* Create a scheduled automation for recurring work such as maintenance or reports.
-
-See the [triggers overview](/platform/triggers/) for how schedules and other triggers work across the platform.
-
-Next, customize which agents receive work and how it's routed with [factory definitions as code](/factories/factory-as-code/).
+* Start a direct run for one-off work. Click **New** on the factory's Runs page and describe the task to the foreman, the same way you would from Slack or an issue tracker.
+* Create a scheduled automation for recurring work, such as maintenance or reports. See the [triggers overview](/platform/triggers/) for how schedules and other triggers work across the platform.

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

@@ -29,12 +29,27 @@ A factory opens on its **Dashboard** page, covered next. **Factory definition**
 
 The page also charts opened versus merged PRs and a breakdown of runs, and the **Cost per PR** card expands to list the most expensive PRs in the range. When Scorers are set up, Scorer cards summarize recent classification results.
 
+<figure style={{ maxWidth: "563px" }}>
+![The Dashboard page showing a Cost per PR chart broken down by compute, platform, and inference cost, plus two example Scorer cards.](../../../assets/factories/factory-dashboard-metrics.png)
+<figcaption>Cost per PR and example Scorer cards on the Dashboard page.</figcaption>
+</figure>
+
 ## Track work items on Activity
 
 **Activity** shows the factory's work items grouped by stage: Triage, Planning, Building, and Reviewing. Finished work items move to two terminal stages, Complete and Cancelled.
 
+<figure style={{ maxWidth: "563px" }}>
+![The Activity page of the factory dashboard, listing work items grouped under Triage, Planning, Building, and Reviewing.](../../../assets/factories/factory-dashboard-activity.png)
+<figcaption>Activity groups work items by stage, with counts for each.</figcaption>
+</figure>
+
 By default, Activity shows only work items you created, and only the four active stages. Change the **Created by** filter to see a teammate's work, and add a **Stage** filter for **Complete** or **Cancelled** to see finished work.
 
+<figure style={{ maxWidth: "563px" }}>
+![The Activity page with a Stage filter chip applied above the work item list, plus a search box and results count.](../../../assets/factories/factory-dashboard-activity-filters.png)
+<figcaption>Filter Activity by stage, creator, or a text search.</figcaption>
+</figure>
+
 Click a work item to open its detail pane, which includes the prompt that started it, the ticket or thread it came from, the pull requests it produced, and its cost. **View agent** opens the agent's session, **Event history** lists the runs behind the work item, and **Stop task** cancels the current run.
 
 :::caution

src/content/docs/factories/index.mdx

@@ -1,8 +1,8 @@
 ---
 title: Warp Factories overview
 description: >-
-  Warp Factories runs cloud software factories where specialized agents move
-  engineering work from intake to a reviewed pull request.
+  Warp Factories runs cloud software factories where specialized agents work
+  engineering requests from intake to a mergeable pull request.
 sidebar:
   label: "Overview"
 ---
@@ -12,21 +12,26 @@ import { VARS } from '@data/vars';
 Warp Factories is in **Early Access** and available to a limited set of teams. [Request access](https://www.warp.dev/factories/request-access) to use it with your team.
 :::
 
-Warp Factories lets engineering teams define and operate **software factories**: cloud workflows where specialized agents move engineering work from intake to a reviewed pull request. The factory does the repetitive work; your team stays in the loop at the points that matter, approving specs when needed and merging every pull request.
+A software factory takes in requests (bug reports, feature specs, support escalations), and a coordinated fleet of agents works them into a stream of mergeable pull requests instead of a growing backlog. Warp Factories gives you the building blocks, so your team stays in the loop where it matters, approving specs when needed and merging every pull request.
 
 ## What is a software factory?
 
-A software factory automates the software development lifecycle. It takes a **work item**, such as an issue, ticket, or triggered task, and moves it through specialized agents that triage it, write a specification when one is needed, implement the change, and review the result.
+In practice, that means tracking each request as a **work item**, such as an issue, ticket, or triggered task, and moving it through specialized agents that triage it, write a specification when one is needed, implement the change, and review the result.
 
 A **factory** is one deployed instance of that pattern. It connects your repositories and engineering tools to a team of agents, execution infrastructure, and a measurable workflow. Each factory applies a single policy across all of its work sources, so deploy separate factories for repository groups that need different policies.
 
+<figure style={{ maxWidth: "563px" }}>
+![A circular diagram of the software factory loop: triage, spec, implement, review, verify, ship, and monitor, with human review checkpoints for the spec, code, and product.](../../../assets/factories/factories-concept-loop.png)
+<figcaption>The general software factory loop. Warp Factories' default agents cover triage through review; add custom agents for the rest.</figcaption>
+</figure>
+
 ## Who benefits from Warp Factories
 
-Warp Factories is designed for engineering teams with repeatable work that extends beyond one coding session, such as:
+Warp Factories is designed for engineering teams with repeatable work that extends beyond one coding session. Here's where it helps most:
 
-* **Backlog work** - Process issues with a consistent triage and delivery policy.
-* **Operational requests** - Fix defects reported through support channels.
-* **Code maintenance** - Review incoming pull requests or maintain services across repositories.
+* 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.
 
 ## What you get with Warp Factories
 

src/content/docs/factories/integrations/github.mdx

@@ -96,13 +96,13 @@ New activity on an issue, pull request, or review thread the factory is already
 
 Issues and pull requests the factory opens carry its label, the same one you use to mention it. Warp adds the label to each repository you connect and removes it when you disconnect one or delete the factory, so you never create or clean it up by hand. If a label is ever left behind, delete it like any other GitHub label.
 
-Branches and pull requests the factory creates follow the repository's normal rules — branch protection, required reviews, and merge requirements all still apply.
+Branches and pull requests the factory creates follow the repository's normal rules: branch protection, required reviews, and merge requirements all still apply.
 
 ## Permissions
 
 Runs authenticate with the GitHub App installation, not with the account of the person whose activity triggered them:
 
-* **The app installation decides what agents can reach.** Agents get exactly the repositories and permissions the installation grants, so change the installation to change access — [automation filters](/factories/automation-filters/) only change when work starts.
+* **The app installation decides what agents can reach.** Agents get exactly the repositories and permissions the installation grants, so change the installation to change access. [Automation filters](/factories/automation-filters/) only change when work starts.
 * **Anyone who can create matching activity can start work.** The event author doesn't need to be a Warp team member. Use author, label, and branch filters to control what starts runs.
 
 For the full credential model, see [Permissions and identity](/platform/integrations/github/#permissions-and-identity) on the GitHub integration page.

src/content/docs/factories/integrations/jira.mdx

@@ -25,7 +25,7 @@ Connect Jira Cloud to your factory so your team can start factory work without l
 
 3. **Point an automation at Jira.** In the factory's dashboard, open **Automations** and add a trigger for **Jira** > **Agent session created**. Use **Projects** and, optionally, **Keywords** to scope which sessions start a run, and choose the agent that handles them.
 
-   If you picked Jira projects when you created the factory, that automation already exists — edit it rather than adding a second one.
+   If you picked Jira projects when you created the factory, that automation already exists. Edit it rather than adding a second one.
 
    To set this up in code instead, declare the `jira` integration in the factory's `factory.yaml` (`integrations: [{type: jira}]`), then add a file under `automations/`, such as `automations/jira-assignment/automation.md`, with an `agent_session_created` trigger:
 

src/content/docs/factories/integrations/linear.mdx

@@ -7,7 +7,7 @@ sidebar:
   label: "Linear"
 ---
 
-Connect Linear to your factory so your team can send it issues without leaving Linear. Assign an issue to the factory or tag it in a comment, and the factory picks it up with the issue's full context, then keeps the issue updated as the work moves through [its stages](/factories/how-factories-work/).
+Connect Linear to your factory so your team can send issues without leaving Linear. Assign an issue to the factory or tag it in a comment, and the factory picks it up with the issue's full context, then keeps the issue updated as the work moves through [its stages](/factories/how-factories-work/).
 
 When the factory needs an answer, reply in Linear, or open the live run to steer the agent directly.