From 47cd94a5bc43db3f4fd2fa4a5705a8916a88ff56 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 18 Aug 2026 00:16:54 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(factories):=20deep=20content=20pass=20?= =?UTF-8?q?=E2=80=94=20accuracy,=20tone,=20and=20cross-linking?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to #557's mechanical pass, addressing the deeper audit asked for on #508: tone consistency, missing cross-links, and accuracy against the product. Accuracy (verified against warp-server's factory frontend): - Drop the Time saved metric from control-room and measure-and-improve; the dashboard card was removed (client/packages/factory api/metrics.ts). - Rename PR latency to PR cycle time to match the card label, and align the metric's definition on both pages (kickoff → PR → first review → merge, per-stage medians). - Align the Autonomy definition on both pages with the product semantics: no human input beyond an approving review and the merge itself. - Align control-room's Live-managed description with the product copy (managed through the API). Links: - Convert 9 relative links in factory-as-code to root-absolute; they resolved to /factories/... paths and 404'd in production (same class of bug #557 fixed; this page landed after that sweep). - Add missing cross-links: quickstart → control room + platform credits, factory-agents → control room, control-room/infrastructure → credentialStrategy, control-room → Self-improvement anchor, how-factories-work → PR checks anchor, Slack Home tab → Activity view, Linear prereq → GitHub connection, troubleshooting → integration troubleshooting sections. - Add the missing Linear entry to connect-your-factory's default automations list. Tone and consistency: - Rewrite the Linear intro: present tense, correct stage names (it claimed a spec/implement/review/verify pipeline), direction consistent with sibling pages, and a lifecycle link. - Normalize Scorer / Self-improvement capitalization across pages. - Replace the 'Oz model ID' coinage with a model_id reference linked to the model catalog. - Trim inward-facing phrasing (Early Access note) and a roadmap promise (Jira caution); fix future tense and em dashes in the quickstart. Validated: npm run build passes, style_lint clean on touched files, link checker reports 0 broken links. Co-Authored-By: Warp --- .../docs/factories/connect-your-factory.mdx | 1 + src/content/docs/factories/control-room.mdx | 21 +++++++++---------- src/content/docs/factories/factory-agents.mdx | 2 +- .../docs/factories/factory-as-code.mdx | 20 +++++++++--------- .../docs/factories/how-factories-work.mdx | 4 ++-- src/content/docs/factories/index.mdx | 2 +- .../factories/infrastructure-and-security.mdx | 2 +- .../docs/factories/integrations/jira.mdx | 2 +- .../docs/factories/integrations/linear.mdx | 10 ++++----- .../docs/factories/integrations/slack.mdx | 8 ++++--- .../docs/factories/measure-and-improve.mdx | 11 +++++----- src/content/docs/factories/quickstart.mdx | 10 ++++----- .../docs/factories/troubleshooting.mdx | 2 ++ 13 files changed, 49 insertions(+), 46 deletions(-) diff --git a/src/content/docs/factories/connect-your-factory.mdx b/src/content/docs/factories/connect-your-factory.mdx index 9b741b8b..8626c7ba 100644 --- a/src/content/docs/factories/connect-your-factory.mdx +++ b/src/content/docs/factories/connect-your-factory.mdx @@ -51,6 +51,7 @@ When you create a factory through the setup wizard, Warp adds default automation * **GitHub** - Starts work when the factory is mentioned or assigned, and follows up when pull requests close or merge, completing a linked tracker issue when it can. See the [GitHub integration guide](/factories/integrations/github/). * **Jira** - Starts work when someone assigns or mentions Warp on a work item in one of the Jira projects you selected. See the [Jira integration guide](/factories/integrations/jira/). +* **Linear** - Starts work when a new agent session arrives from one of the Linear teams you selected. See the [Linear integration guide](/factories/integrations/linear/). * **Slack** - Starts work from mentions and messages, as described in the [Slack integration guide](/factories/integrations/slack/). These defaults are starting points. Review each automation's filters, agent, and run settings, and adjust them to match your workflow. diff --git a/src/content/docs/factories/control-room.mdx b/src/content/docs/factories/control-room.mdx index 59abae0f..031c906b 100644 --- a/src/content/docs/factories/control-room.mdx +++ b/src/content/docs/factories/control-room.mdx @@ -15,13 +15,13 @@ Select a factory in the sidebar to open its pages. **Runs**, **MCPs and apps**, | Page | What it shows | What you do there | | --- | --- | --- | -| **Dashboard** | Factory metrics: autonomy, time saved, PR latency, cost, and run volume | Compare periods and find work worth investigating | +| **Dashboard** | Factory metrics: autonomy, PR cycle time, cost, and run volume | Compare periods and find work worth investigating | | **Activity** | Work items grouped by stage | Search, filter, open, and stop work items | | **Agents** | The factory's agent roster | Create and edit agents | | **Automations** | Triggers that start runs | Create, edit, and delete automations | | **Runs** | The factory's individual agent runs | Start, stop, and score runs | | **Scorers** | Scorer definitions and results | Define rubrics and review classifications | -| **Self-improvement** | Pull requests filed to fix scorer-detected failures | Review fix PRs and open the runs behind them | +| **Self-improvement** | Pull requests filed to fix Scorer-detected failures | Review fix PRs and open the runs behind them | | **Benchmarks** | Benchmark suites and their runs | Compare harness, model, and runner configurations | | **Code** | The factory's definition files | Browse and edit a Warp-managed definition | | **Settings** | Configuration the factory owns | Change identity, repos, runners, and the integrations the factory can access | @@ -52,12 +52,11 @@ Run pages don't include a chat input, but you can still steer a run: **View sess **Dashboard** summarizes the factory over a date range you choose: -* **Autonomy** - The share of merged PRs that needed no human input beyond an approving review. -* **Time saved** - Approximate engineer-hours saved, estimated from the line changes in merged PRs. -* **PR latency** - The median time from run kickoff through PR, review, and merge. +* **Autonomy** - The share of the factory's merged PRs that needed no human input beyond an approving review and the merge itself. +* **PR cycle time** - The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with a median for each stage. * **Cost per PR** - The median cost of PRs opened in the range. Treat it as a lower-bound estimate: it can miss some run usage and does not match billing. See [Measure and improve a factory](/factories/measure-and-improve/) for its limitations. -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. +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. ## Manage agents and automations @@ -71,19 +70,19 @@ Environment is set in the factory definition, not the agent editor, and automati * **Warp-managed** - Browse and edit the definition files. Saving validates the definition and commits all changes together. * **Managed in GitHub** - Links to the repository; edit the definition through pull requests there. -* **Live-managed** - The factory is edited directly in the control room, so there are no definition files to browse. +* **Live-managed** - The factory is managed through the API, so there are no definition files to browse. When an agent proposes a change to a Warp-managed definition, its work item on **Activity** links to a review of the branch inside the control room. From there, comment on the diff, use **Request changes** to send feedback back to the agent, or **Approve & merge**. ## Score and benchmark -A scorer is an LLM judge that classifies completed runs against a rubric you define, scoped to the agents you choose and sampled at a rate you set. Each scorer has a **Self-improvement** toggle: when it's on, the factory periodically triages the runs that scorer marks as failing and files fixes for recurring issues. The **Self-improvement** page tracks the pull requests those fixes open, linking each one to the run that produced it. +A Scorer is an LLM judge that classifies completed runs against a rubric you define, scoped to the agents you choose and sampled at a rate you set. Each Scorer has a **Self-improvement** toggle: when it's on, the factory periodically triages the runs that Scorer marks as failing and files fixes for recurring issues. The **Self-improvement** page tracks the pull requests those fixes open, linking each one to the run that produced it. -**Benchmarks** compares harness, model, and runner configurations against a fixed set of tasks with success criteria. Benchmark results are only as reliable as the scorers behind them, so read them alongside [Measure and improve a factory](/factories/measure-and-improve/). +**Benchmarks** compares harness, model, and runner configurations against a fixed set of tasks with success criteria. Benchmark results are only as reliable as the Scorers behind them, so read them alongside [Measure and improve a factory](/factories/measure-and-improve/). ## Change factory settings -**Settings** holds the configuration the factory owns: the factory's name and connected repos, whether pull requests are authored by the agent or the run creator, the **Analysis model** self-improvement uses to analyze failed runs, runners, the integrations accessible to this factory, and deletion. Deleting a factory cannot be undone. +**Settings** holds the configuration the factory owns: the factory's name and connected repos, whether pull requests are authored by the agent or the run creator (the definition's [`credentialStrategy`](/factories/factory-as-code/#credentialstrategy)), the **Analysis model** [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) uses to analyze failed runs, runners, the integrations accessible to this factory, and deletion. Deleting a factory cannot be undone. For a file-managed factory, `runners/*.yaml` in the repository is the source of truth. Anything managed in an external repository is read-only in Settings. @@ -91,4 +90,4 @@ For a file-managed factory, `runners/*.yaml` in the repository is the source of * [How Warp Factories work](/factories/how-factories-work/) - The lifecycle behind Activity's stages and where humans stay in the loop. * [Factory definitions as code](/factories/factory-as-code/) - Define agents, automations, runners, and source ownership in code. -* [Measure and improve a factory](/factories/measure-and-improve/) - Configure the scorers and benchmarks behind the Dashboard. +* [Measure and improve a factory](/factories/measure-and-improve/) - Configure the Scorers and benchmarks behind the Dashboard. diff --git a/src/content/docs/factories/factory-agents.mdx b/src/content/docs/factories/factory-agents.mdx index 8feb1873..c5e9bd6a 100644 --- a/src/content/docs/factories/factory-agents.mdx +++ b/src/content/docs/factories/factory-agents.mdx @@ -62,7 +62,7 @@ Each default agent also has its own [Auto-memory store](/agents/agent-memory/). ## Configure agent behavior -Use the agent editor in the control room to change an agent's description, model, runner, host, MCP servers, secrets, and instructions. +Use the agent editor in the [control room](/factories/control-room/) to change an agent's description, model, runner, host, MCP servers, secrets, and instructions. You can also manage the whole factory as version-controlled code, with [factory definition files](/factories/factory-as-code/) in a Git repository, where changes get the same review, history, and rollback as any other code. A few agent settings can only be set in the files: harness, environment, and credential strategy. Where the repository lives determines how the two editing paths work together: diff --git a/src/content/docs/factories/factory-as-code.mdx b/src/content/docs/factories/factory-as-code.mdx index 6067ae56..960e3e03 100644 --- a/src/content/docs/factories/factory-as-code.mdx +++ b/src/content/docs/factories/factory-as-code.mdx @@ -98,11 +98,11 @@ repositories: ### `secrets` -Optional. Names of [managed secrets](../platform/secrets) granted to every agent in the factory, in addition to anything individual agents declare. +Optional. Names of [managed secrets](/platform/secrets/) granted to every agent in the factory, in addition to anything individual agents declare. ### `mcpServers` -Optional. [MCP servers](../platform/mcp) granted to every agent, keyed by the name the agent sees. Each entry references a Warp-managed MCP server by `warpId`. +Optional. [MCP servers](/platform/mcp/) granted to every agent, keyed by the name the agent sees. Each entry references a Warp-managed MCP server by `warpId`. ```yaml mcpServers: @@ -143,7 +143,7 @@ agentDefaults: ### `agentDefaults.model` -The model runs execute with, as an Oz model ID. `model` is shorthand for running on the Warp Agent harness: +The model runs execute with, as a `model_id` from [model choice for agents](/agents/inference/model-choice/). `model` is shorthand for running on the Warp Agent harness: ```yaml model: auto @@ -161,7 +161,7 @@ harness: ### `agentDefaults.harness` -The harness and model runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude` (alias `claude-code`), `codex`, or `gemini`; see [supported harnesses](../platform/harnesses/). +The harness and model runs execute with. Use the `harness` form to run a third-party harness or to set advanced options. `type` accepts `oz`, `claude` (alias `claude-code`), `codex`, or `gemini`; see [supported harnesses](/platform/harnesses/). ```yaml harness: @@ -173,7 +173,7 @@ harness: secretName: CODEX_API_KEY ``` -For a third-party harness, `auth` sets where credentials come from: `source: managedSecret` reads the [managed secret](../platform/secrets) named by `secretName`, and `source: workerEnvironment` reads them from your self-hosted worker's environment (and requires a self-hosted `workerHost`). The `oz` harness supplies its own credentials and takes no `auth` or `reasoningLevel`. +For a third-party harness, `auth` sets where credentials come from: `source: managedSecret` reads the [managed secret](/platform/secrets/) named by `secretName`, and `source: workerEnvironment` reads them from your self-hosted worker's environment (and requires a self-hosted `workerHost`). The `oz` harness supplies its own credentials and takes no `auth` or `reasoningLevel`. ### `agentDefaults.runner` @@ -181,7 +181,7 @@ The name of a runner defined under [`runners/`](#runnersnameyaml) that provides ### `agentDefaults.environmentId` -The ID of an existing [environment](../platform/environments) runs execute in. +The ID of an existing [environment](/platform/environments/) runs execute in. ### `agentDefaults.secrets` @@ -193,7 +193,7 @@ MCP servers for agents that don't declare their own, in the same form as [`mcpSe ### `agentDefaults.workerHost` -Where runs execute: `warp` for Warp-hosted compute, or the ID of a connected [self-hosted worker](../platform/self-hosting/). +Where runs execute: `warp` for Warp-hosted compute, or the ID of a connected [self-hosted worker](/platform/self-hosting/). ## `agents//agent.md` @@ -260,7 +260,7 @@ The providers and their events: * `schedule` - `cron_fired` * `factory` - `work_item_stage_changed` -Slack, Linear, and Jira triggers require the matching [integration](../platform/integrations/) to be connected. GitHub triggers work through the factory's `repositories`. +Slack, Linear, and Jira triggers require the matching [integration](/platform/integrations/) to be connected. GitHub triggers work through the factory's `repositories`. ### `triggers[].filter` @@ -285,7 +285,7 @@ An automation may also declare `model` or `harness`, `runner`, `environmentId`, ## `runners/.yaml` -Optional. Each file defines a runner: the compute a run executes on. The runner's name comes from the file name, and agents and automations select it by that name. See [cloud agent runners](../platform/runners) for how runners behave. +Optional. Each file defines a runner: the compute a run executes on. The runner's name comes from the file name, and agents and automations select it by that name. See [cloud agent runners](/platform/runners/) for how runners behave. ```yaml title="runners/linux-build.yaml" description: Linux runner for payments builds and tests @@ -315,7 +315,7 @@ The operating system and architecture. `os` is `linux` (the default) or `macos`, ## Skills -A skill is a directory containing a `SKILL.md`, not a YAML key. Skills under `skills/` are available to every agent in the factory; skills under `agents//skills/` are available only to that agent. See [Skills for agents](../agents/capabilities/skills). +A skill is a directory containing a `SKILL.md`, not a YAML key. Skills under `skills/` are available to every agent in the factory; skills under `agents//skills/` are available only to that agent. See [Skills for agents](/agents/capabilities/skills/). ## Example factory definition diff --git a/src/content/docs/factories/how-factories-work.mdx b/src/content/docs/factories/how-factories-work.mdx index 275ed9a2..9dabcb12 100644 --- a/src/content/docs/factories/how-factories-work.mdx +++ b/src/content/docs/factories/how-factories-work.mdx @@ -70,8 +70,8 @@ These checkpoints come from the factory's agent instructions and your repository Each completed work item leaves evidence behind, including run and pull request activity, costs, [Scorer](/factories/measure-and-improve/) evaluations, and benchmarks. Teams use this evidence to spot repeated failures and compare model or harness configurations. -The factory can also act on that evidence directly. Its [self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) capability groups the failures Scorers flag and files follow-up runs that propose changes to the application code or the factory's own definition. Nothing is adopted without your review. +The factory can also act on that evidence directly. Its [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) capability groups the failures Scorers flag and files follow-up runs that propose changes to the application code or the factory's own definition. Nothing is adopted without your review. -Anyone on the team, or an agent, can also propose changes to the factory's instructions, skills, models, environments, or other [definitions](/factories/factory-as-code/). Definitions stored in GitHub can go through pull request review and configuration checks before a change reaches the production branch; Warp-managed definitions sync changes directly. Match your review policy to the definition source and the risk of the change. +Anyone on the team, or an agent, can also propose changes to the factory's instructions, skills, models, environments, or other [definitions](/factories/factory-as-code/). Definitions stored in GitHub can go through pull request review and [configuration checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) before a change reaches the production branch; Warp-managed definitions sync changes directly. Match your review policy to the definition source and the risk of the change. Benchmarks organize the evidence; they don't replace your judgment about whether a change is correct. 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 outer-loop pattern to a standalone agent. diff --git a/src/content/docs/factories/index.mdx b/src/content/docs/factories/index.mdx index 65b67f84..eb05f337 100644 --- a/src/content/docs/factories/index.mdx +++ b/src/content/docs/factories/index.mdx @@ -11,7 +11,7 @@ import { VARS } from '@data/vars'; 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. Your team sets the policy and makes the final decisions; the factory does the repetitive work and records the evidence you need to improve it. :::note -This feature is currently in **Early Access**. Warp Factories is available to a limited set of teams while Warp validates the product. +Warp Factories is in **Early Access** and available to a limited set of teams. ::: ## What is a software factory? diff --git a/src/content/docs/factories/infrastructure-and-security.mdx b/src/content/docs/factories/infrastructure-and-security.mdx index 95560317..76f1b43d 100644 --- a/src/content/docs/factories/infrastructure-and-security.mdx +++ b/src/content/docs/factories/infrastructure-and-security.mdx @@ -95,7 +95,7 @@ A factory handles four kinds of credentials, each with its own boundary: | **Inference credentials** | Model provider requests | Used only at the inference boundary; never injected into the sandbox | | **Execution secrets** | APIs, package registries, and tools an agent uses | Delivered from an explicit per-agent allowlist; factory agents that don't act as a specific user receive no managed secrets by default | | **Harness authentication** | Third-party harnesses such as Claude Code or Codex | Configured separately from the agent's secret allowlist | -| **Repository identity** | Checking out code and pushing changes | Runs act with the creating user's authorization (changes are attributed to them) or as the agent itself for unattended work | +| **Repository identity** | Checking out code and pushing changes | Runs act with the creating user's authorization (changes are attributed to them) or as the agent itself for unattended work; set by the definition's [`credentialStrategy`](/factories/factory-as-code/#credentialstrategy) | Scope each credential to the resources and actions its agent needs. Warp redacts known secret values at output boundaries, but redaction is a backstop, not a substitute for narrow external permissions and rotation. See [cloud agent secrets](/platform/secrets/), [harness authentication](/platform/harnesses/authentication/), [secret redaction](/support-and-community/privacy-and-security/secret-redaction/), and [team identity](/platform/team-access-billing-and-identity/) for the underlying controls. diff --git a/src/content/docs/factories/integrations/jira.mdx b/src/content/docs/factories/integrations/jira.mdx index 418258ff..f01dc477 100644 --- a/src/content/docs/factories/integrations/jira.mdx +++ b/src/content/docs/factories/integrations/jira.mdx @@ -63,7 +63,7 @@ All Jira work reaches the factory through a single event, `agent_session_created A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything. For the matching rules shared by every source, see [automation filters](/factories/automation-filters/). :::caution -Filters like `project_keys` decide whether *your* automation starts a run; they aren't an access boundary. A Jira event is evaluated against every team's automations in the connected workspace, so another team's automation with a broader or different filter can still start its own run on the same work item. Installing the Warp app doesn't scope its Jira access to specific projects either — scoping Jira project access by Warp team is coming soon. +Filters like `project_keys` decide whether *your* automation starts a run; they aren't an access boundary. A Jira event is evaluated against every team's automations in the connected workspace, so another team's automation with a broader or different filter can still start its own run on the same work item. Installing the Warp app doesn't scope its Jira access to specific projects either. ::: ## What happens during a run diff --git a/src/content/docs/factories/integrations/linear.mdx b/src/content/docs/factories/integrations/linear.mdx index b3ab4d07..dabd6b14 100644 --- a/src/content/docs/factories/integrations/linear.mdx +++ b/src/content/docs/factories/integrations/linear.mdx @@ -1,18 +1,18 @@ --- title: Connect Linear to your factory description: >- - Connect Warp to Linear so issues flow into your software factory and + Connect Linear to a factory so issues flow into your software factory and progress flows back to the issue. sidebar: label: "Linear" topic: factories --- -Connect Warp to Linear to send issues directly into your software factory. Assign an issue to your factory or tag it in a comment, and the factory will pick up the issue with its full context. +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 up the issue with its full context. -From there, your factory will spec, implement, review, and verify any work assigned to it. As work progresses, the factory keeps the Linear issue updated so your team can follow along without switching tools. +From there, the factory routes the issue through its stages, triage through review, and keeps the Linear issue updated as work progresses, so your team can follow along without switching tools. If you're new to factories, see [how Warp Factories work](/factories/how-factories-work/) for the lifecycle. -When human input is needed, your team can respond in Linear or open the live factory run to inspect and steer the agent directly. +When the factory needs human input, respond in Linear or open the live factory run to inspect and steer the agent directly. Two parts work together: @@ -24,7 +24,7 @@ Two parts work together: * **A factory** - Create a factory with the agents, repositories, and environment needed to handle Linear work. * **A Linear workspace** - Use a Linear account that can authorize the Warp app for the workspace. * **A linked Warp account (agent sessions only)** - Anyone who starts a Linear agent session must link their Linear user to their Warp account. If Warp can't identify the session creator, Linear shows an authentication prompt instead of starting work. -* **Code host access** - Configure repository credentials separately. The factory needs them to change code or create a pull request. +* **Code host access** - Configure repository access separately through the factory's [GitHub connection](/platform/integrations/github/). The factory needs it to change code or create a pull request. For workspace-level installation, reconnection, and removal steps, see the [Linear integration setup guide](/platform/integrations/linear/). diff --git a/src/content/docs/factories/integrations/slack.mdx b/src/content/docs/factories/integrations/slack.mdx index 9f200167..2eec0930 100644 --- a/src/content/docs/factories/integrations/slack.mdx +++ b/src/content/docs/factories/integrations/slack.mdx @@ -8,7 +8,7 @@ sidebar: topic: factories --- -Connect a factory to Slack so your team can send it work without leaving their conversations. Each factory gets its own dedicated Slack app: mention the app in a channel or send it a direct message, and the factory picks up the request with the conversation as context, then posts progress and results back into the same thread. You can also set up automations that start work from Slack events without a mention. If you're new to factories, see [How factories work](/factories/how-factories-work/) for what a factory is and how it runs work. +Connect a factory to Slack so your team can send it work without leaving their conversations. Each factory gets its own dedicated Slack app: mention the app in a channel or send it a direct message, and the factory picks up the request with the conversation as context, then posts progress and results back into the same thread. You can also set up automations that start work from Slack events without a mention. If you're new to factories, see [how Warp Factories work](/factories/how-factories-work/) for what a factory is and how it runs work. ## Prerequisites and authorization @@ -18,7 +18,9 @@ Installing the app grants the Slack permissions shown on the authorization scree ### How the Slack connection works -Warp uses Slack's managed apps model: Warp's main Slack app acts as the manager. The first time you connect a factory, you authorize the manager once for your workspace. That authorization lets Warp create and install Slack apps on your behalf, but nothing is created until you connect a factory. Each time you click **Add to Slack**, Warp creates that factory's dedicated app, installs it, and manages it from then on: the app's name, icon, and configuration stay in sync with the factory. The manager's permissions apply only to apps it created. Depending on your workspace's app-approval settings, a Slack administrator may need to approve the manager authorization once, and each factory's app before it installs. +Warp uses Slack's managed apps model: Warp's main Slack app acts as the manager. The first time you connect a factory, you authorize the manager once for your workspace. That authorization lets Warp create and install Slack apps on your behalf, but nothing is created until you connect a factory. + +Each time you click **Add to Slack**, Warp creates that factory's dedicated app, installs it, and manages it from then on: the app's name, icon, and configuration stay in sync with the factory. The manager's permissions apply only to apps it created. Depending on your workspace's app-approval settings, a Slack administrator may need to approve the manager authorization once, and each factory's app before it installs. ## Connect the factory @@ -76,7 +78,7 @@ A single Slack message can match more than one automation. For example, if one a The Slack thread where work started is also where you follow it: the factory posts progress and the final response there. Reply in the thread to add information or attachments while work is active, or to pick the same work item back up later. -For an overview of your factory tasks, open the app's **Home** tab in Slack. It groups tasks by stage (Triage, Planning, Building, Reviewing, Completed, and Cancelled), offers stage and date filters, and links each task back to its Slack thread, factory run, issue, or pull request when available. +For an overview of the factory's work items, open the app's **Home** tab in Slack. It groups them by the same stages as the control room's [Activity view](/factories/control-room/#track-work-items-on-activity) (Triage, Planning, Building, Reviewing, Completed, and Cancelled), offers stage and date filters, and links each work item back to its Slack thread, factory run, issue, or pull request when available. A factory can create issues, branches, and pull requests, but your repository's review and merge rules still apply. Work that starts in Slack doesn't bypass required human review. diff --git a/src/content/docs/factories/measure-and-improve.mdx b/src/content/docs/factories/measure-and-improve.mdx index ca99051e..b7b5ea7c 100644 --- a/src/content/docs/factories/measure-and-improve.mdx +++ b/src/content/docs/factories/measure-and-improve.mdx @@ -26,18 +26,17 @@ The control room dashboard shows activity, cost, autonomy, and evaluation result | **Total runs** | All agent runs, with breakdowns by agent type, status, source, model, and more. | | **PRs opened** | Pull requests created from factory work. | | **PRs merged** | Pull requests that merged. | -| **Autonomy %** | The share of merged work that shipped without human edits. | -| **Time saved** | An estimate of engineer-hours saved by merged factory PRs. | -| **PR latency** | How long pull requests spend in each stage. | +| **Autonomy** | The share of the factory's merged PRs that needed no human input beyond an approving review and the merge itself. | +| **PR cycle time** | The median time the factory's merged PRs took from run kickoff through PR, first review, and merge, with a median for each stage. | | **Cost per PR** | An estimate of credits spent per pull request. | | **Most expensive PRs** | The highest-cost pull requests. | | **Scorer cards** | Results from your Scorers. | | **Self-improvement PRs** | The three newest Self-improvement pull requests, regardless of the selected date range. | -**Time saved** and **Cost per PR** are estimates, not billing figures. Time saved converts merged pull requests into engineer-hours, and the per-teammate view divides that estimate by your team size. Cost per PR counts recorded credits and can undercount actual usage. +**Cost per PR** is an estimate, not a billing figure: it counts recorded credits and can undercount actual usage. :::caution -**PRs merged**, **PR latency**, and the detail in **Most expensive PRs** require the GitHub App and only cover activity from after you install it. +**PRs merged**, **Autonomy**, **PR cycle time**, and the detail in **Most expensive PRs** require the GitHub App and only cover activity from after you install it. ::: Use the dashboard to pick which runs to investigate, not to conclude what caused a change. **Total runs** includes evaluation, benchmark, and Self-improvement runs, so a higher run count with a flat PR count could mean harder tasks, retries, or measurement activity. @@ -73,7 +72,7 @@ A benchmark compares configurations of a single agent on the same fixed tasks, s You can create a benchmark task from a completed run's detail pane, and Warp copies the run's input into the task. Add success criteria before you launch. -Every benchmark also runs **Correctness**, a built-in scorer that marks each trial as pass or fail against the task's success criteria. Results show pass rates, cost, and quality for each configuration, with per-task detail. Warp doesn't combine these signals into one score or pick a winner; you weigh the results and decide. Benchmark credit totals don't include model usage, so the true cost is higher. +Every benchmark also runs **Correctness**, a built-in Scorer that marks each trial as pass or fail against the task's success criteria. Results show pass rates, cost, and quality for each configuration, with per-task detail. Warp doesn't combine these signals into one score or pick a winner; you weigh the results and decide. Benchmark credit totals don't include model usage, so the true cost is higher. ## Configure and review Self-improvement diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 08bcfc7b..010fdb91 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -8,11 +8,11 @@ sidebar: --- import { VARS } from '@data/vars'; -A factory is a team of cloud agents — a foreman you talk to, plus the subagents it dispatches — that turns incoming requests into pull requests for your team to review. In this quickstart, you will create a factory, connect a GitHub repository, and take one small work item from prompt to pull request in about 10 minutes. +A factory is a team of cloud agents: a foreman you talk to, plus the subagents it dispatches. Together they turn incoming requests into pull requests for your team to review. In this quickstart, you will create a factory, connect a GitHub repository, and take one small work item from prompt to pull request in about 10 minutes. ## Prerequisites -* **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/). Factory agents consume the team's credits. +* **A Warp team with credits** - A factory belongs to a [Warp team](/knowledge-and-collaboration/teams/). Factory agents consume the team's [credits](/support-and-community/plans-and-billing/platform-credits/). * **GitHub repository access** - Authorize GitHub and choose repositories during setup. If your organization restricts app installations, ask a GitHub organization owner to approve the connection. See the [GitHub integration](/platform/integrations/github/) for details. ## Create your factory @@ -23,7 +23,7 @@ _~5 minutes_ 2. In the sidebar, next to **Factories**, click **+** to start the setup wizard. :::note - **No team yet?** If the team that owns the factory has no plan or credits, the wizard will ask you to select one. A factory needs credits to run its agents. + **No team yet?** If the team that owns the factory has no plan or credits, the wizard asks you to select one. A factory needs credits to run its agents. ::: 3. Click **I want to use repos from GitHub** and complete the GitHub authorization. @@ -31,7 +31,7 @@ _~5 minutes_ Warp provisions a default [environment](/platform/environments/) for the selected repos. -5. Enter a **Factory name**, e.g., `Payments services`. Warp derives a matching **Factory alias**, the handle teammates use to @-mention the factory from connected tools like Slack and Linear. Keep it short and recognizable. +5. Enter a **Factory name**, such as `Payments services`. Warp derives a matching **Factory alias**, the handle teammates use to @-mention the factory from connected tools like Slack and Linear. Keep it short and recognizable. 6. The next screen offers to connect Slack. Click **Next** to skip it for now. See [Connect your factory](/factories/connect-your-factory/) to add integrations later. 7. Toggle the subagents the foreman can dispatch: **Triage**, **Spec**, **Code**, and **Review**. Keep **Code** on so this quickstart's work item can end in a pull request. @@ -58,7 +58,7 @@ _~5 minutes_ The foreman picks up the request as a run and dispatches your subagents as child runs. -3. Follow progress from two pages in your factory's sidebar: +3. Follow progress from two pages in the factory's [control room](/factories/control-room/) sidebar: * **Runs** - The foreman's run and the child runs it dispatches. * **Activity** - The work item as it moves through its stages. Open it to see its event history and pull request artifacts. diff --git a/src/content/docs/factories/troubleshooting.mdx b/src/content/docs/factories/troubleshooting.mdx index 40ab6d59..939906b6 100644 --- a/src/content/docs/factories/troubleshooting.mdx +++ b/src/content/docs/factories/troubleshooting.mdx @@ -10,6 +10,8 @@ import { VARS } from '@data/vars'; Solutions for common issues when creating and operating a factory in the {VARS.FACTORY_WEB_APP}. +For issues with a specific intake source, see the troubleshooting sections of the [Slack](/factories/integrations/slack/#troubleshooting-and-reconnection), [Linear](/factories/integrations/linear/#troubleshooting), and [Jira](/factories/integrations/jira/#troubleshooting) integration guides. For events that match but don't start work, see [automation filters](/factories/automation-filters/#troubleshooting). + ## A GitHub repository doesn't appear in the picker **Cause:** The GitHub installation doesn't cover the repository. From 67cb9b435089f5521839f8e3c19dec501d94aef8 Mon Sep 17 00:00:00 2001 From: hongyi-chen Date: Tue, 18 Aug 2026 00:21:07 +0000 Subject: [PATCH 2/2] docs(factories): drop redundant team/credits note from quickstart The Prerequisites section already states a factory needs a team with credits. Co-Authored-By: Warp --- src/content/docs/factories/quickstart.mdx | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/content/docs/factories/quickstart.mdx b/src/content/docs/factories/quickstart.mdx index 010fdb91..75f2d91c 100644 --- a/src/content/docs/factories/quickstart.mdx +++ b/src/content/docs/factories/quickstart.mdx @@ -21,11 +21,6 @@ _~5 minutes_ 1. Go to the {VARS.FACTORY_WEB_APP} at platform.warp.dev and sign in. 2. In the sidebar, next to **Factories**, click **+** to start the setup wizard. - - :::note - **No team yet?** If the team that owns the factory has no plan or credits, the wizard asks you to select one. A factory needs credits to run its agents. - ::: - 3. Click **I want to use repos from GitHub** and complete the GitHub authorization. 4. Choose the repositories the factory will work in and click **Add repos**. Start with one or two repositories. Every agent in the factory shares this repo set, so a focused set keeps their context tight.