docs(factories): launch fast-follow fixes

.agents/templates/feature-doc.md

@@ -24,7 +24,8 @@ Remove this callout if not needed.]
 ## Key features
 
 [Bulleted list. Bold term + dash + description for each.
-Focus on what each capability means for the user.]
+Focus on what each capability means for the user.
+If one capability is a genuine differentiator (e.g., an agent- or API-driven alternative to the default UI flow), give it real visual weight here or in its own callout near the top of the relevant section — don't bury it as a footnote after the primary flow is already documented.]
 
 * **Feature A** - What it does and why it matters to the user.
 * **Feature B** - What it does and why it matters to the user.
@@ -38,6 +39,7 @@ IMPORTANT: Do NOT include step-by-step procedures in this section.
 Keep the conceptual and procedural sections clearly separated.
 State platform, plan, preview, or interactive-only limits next to the behavior they constrain.
 Do not invent internal tool names or implementation details the reader cannot act on.
+Do not cite exact counts of tools, steps, or subcomponents (e.g., "ten tools") if they could change — describe the capability instead; a stale number is worse than no number.
 Do NOT embed full error messages here — put failures in Troubleshooting at the end.]
 
 [SCREENSHOTS: If this feature has a distinctive visual surface (statusline, tab bar, side pane, multi-control layout), place a screenshot immediately after the paragraph that introduces that surface. Use descriptive alt text. Skip screenshots for purely textual CLI behavior.]

AGENTS.md

@@ -13,6 +13,7 @@ This guide establishes standards for writing Warp documentation. It covers voice
 - **Direct and action-oriented**: Lead with what users can accomplish, not just what features exist
 - **User-focused**: Use second person ("you can", "allows you to") rather than passive voice
 - **Confident without jargon**: Explain technical concepts clearly without oversimplifying
+- **Avoid copy that reads as AI-generated**: Watch for over-explained cause-and-effect, excessive hedging, or the same rhetorical pattern repeated across sections. Read a paragraph aloud — if it doesn't sound like something a person would say to a colleague, rewrite it plainly.
 
 ### Language guidelines
 - Use consistent terminology throughout (see [Terminology standards](#terminology-standards) and the full glossary in `.agents/references/terminology.md`)
@@ -411,8 +412,13 @@ These rules apply regardless of content type:
 - **Provide inline context for first references**: Assume the reader arrived directly at this page, not from a parent page. When a prerequisite, concept, or tool is mentioned for the first time, include: what the thing is (1 short clause), where to get or create it, and a link to the full reference.
   - ✅ "**A Warp API key** - Authenticate API requests with a key from **Settings** > **Platform** in the Warp app. See the API Keys reference for details."
   - ❌ "**An API key** - Create one in **Settings** > **Platform**." (what kind of key? Settings where?)
-- **Include practical examples**: Show real-world scenarios, not just toy examples. Concrete examples help the reader understand when and why to use a feature.
+- **Include practical examples**: Show real-world scenarios, not just toy examples. Concrete examples help the reader understand when and why to use a feature. For enterprise or infrastructure-heavy features, prefer a complete example (a full config file, a linked sample repository) over a fragment — abstract features are hardest to trust without something concrete to point at.
 - **Cross-reference related pages**: Link to related features, next steps, and deeper references so the reader can continue learning.
+- **Sequence basics before jargon**: Explain what something is in plain language before introducing internal-sounding framing, deep lifecycle terminology, or advanced configuration. A reader who doesn't know the concept yet should never hit unexplained jargon in the first few paragraphs. Save advanced or self-referential concepts (e.g., a system that improves itself) for after the reader understands the basic flow.
+- **Avoid appendix-style content**: Don't add a bullet list or table whose only job is to restate content already covered elsewhere on the page, such as an exhaustive index of tabs or settings that duplicates the dedicated sections below it. Weave supplementary details into the section they relate to instead of bolting them onto the end under a generic heading like "Good to know."
+- **Don't over-specify counts or internals that will drift**: Describe a capability rather than naming an exact count of tools, steps, or subcomponents behind it (e.g., "a small set of tools" instead of "ten tools"). Precise counts go stale the moment the implementation changes, and a stale number is worse than no number.
+- **Feature real differentiators structurally**: If a capability is a genuine advantage over the default path (an agent- or API-driven alternative to a UI flow, for example), give it real visual weight — a clear callout near the top of the relevant section, not a footnote after the primary steps are already done. Where something sits on the page communicates how important it is.
+- **Verify claims against the live product, not just prior drafts**: Terminology, UI labels, and calculated values drift between rounds of review. Confirm names, labels, and metric definitions against the actual app, API, or codebase before publishing — especially for pages describing metrics or anything computed.
 
 ### Conceptual
 
@@ -461,6 +467,7 @@ These rules apply regardless of content type:
 - Include expected outcomes after key steps so the reader can confirm they're on track.
 - Test all instructions for accuracy.
 - Provide troubleshooting for common failure points.
+- **Explain the default before the override.** When documenting configurable infrastructure or advanced settings, state the default behavior and the common case first, then cover manual overrides. Don't lead with the full matrix of options before establishing what "just works" out of the box.
 
 **Existing examples**: `reference/cli/api-keys.mdx`, `platform/integrations/slack.mdx`
 

src/content/docs/enterprise/team-management/admin-panel.mdx

@@ -269,20 +269,20 @@ Controls how screenshots and video recordings captured with [Computer Use](/agen
 
 **Enabled GitHub Orgs**
 
-The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations. That association does two things: it lets cloud agents initiated with an [agent API key](/reference/cli/api-keys/) clone repositories and open pull requests using the Oz by Warp GitHub App, and it tells Warp which team owns runs started from the [GitHub integration](/platform/integrations/github/) when someone mentions `@warp-agent` in those repositories.
+The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations. That association does two things: it lets cloud agents initiated with an [agent API key](/reference/cli/api-keys/) clone repositories and open pull requests using the Warp Factories GitHub App, and it tells Warp which team owns runs started from the [GitHub integration](/platform/integrations/github/) when someone mentions `@warp-agent` in those repositories.
 
 To configure:
 
 1. Navigate to the **Platform** section of the Admin Panel.
-2. Under **Enabled GitHub Orgs**, review the list of GitHub organizations where the Oz by Warp GitHub App is installed.
+2. Under **Enabled GitHub Orgs**, review the list of GitHub organizations where the Warp Factories GitHub App is installed.
 3. Select which organizations your team should have access to.
 
 <figure>
 ![Enabled GitHub Orgs setting in the Admin Panel Platform section](../../../../assets/agent-platform/admin-panel-enabled-github-orgs.png)
 <figcaption>Enabled GitHub Orgs setting in the Admin Panel.</figcaption>
 </figure>
 
-The organizations and repository access shown here reflect the Oz by Warp GitHub App installation scope, which is configured in [GitHub settings](https://github.com/settings/installations). To change which repositories the app can access, edit the installation directly in GitHub.
+The organizations and repository access shown here reflect the Warp Factories GitHub App installation scope, which is configured in [GitHub settings](https://github.com/settings/installations). To change which repositories the app can access, edit the installation directly in GitHub.
 
 :::note
 This setting controls which GitHub App installation agent API key runs authenticate with, and which GitHub organizations can start [GitHub integration](/platform/integrations/github/) runs for this team. Runs from an `@warp-agent` mention also authenticate with the installation's GitHub App token, so their repository access comes from the app installation rather than the person who wrote the mention. Runs triggered from a personal API key, Slack, Linear, or the Warp app continue to use that user's own GitHub authorization. For more details, see [Team GitHub authorization](/platform/team-access-billing-and-identity/#team-github-authorization).

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.
+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/).
 
 | Source | Best for | Where follow-ups continue |
 | --- | --- | --- |
@@ -27,7 +27,7 @@ Pick the sources that match where work starts for your team. You can connect mor
 
 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. Schedules and direct runs skip this step.
+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.
 
 ## How work reaches your factory
@@ -44,7 +44,7 @@ flowchart LR
 
 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.
 
-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. See [how Warp Factories work](/factories/how-factories-work/) for the full lifecycle.
+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.
 
 ## Review the default automations
 
@@ -79,11 +79,4 @@ Not every task starts in an external tool:
 
 See the [triggers overview](/platform/triggers/) for how schedules and other triggers work across the platform.
 
-## Good to know
-
-* **Follow-ups continue the same work item** - Replying in the same Slack thread, GitHub issue or pull request, Linear issue, or Jira agent session adds to the existing work item instead of starting a new one. Repeated event deliveries from a provider don't create duplicate work either.
-* **One issue tracker per factory** - A factory can use [Linear](/factories/integrations/linear/) or [Jira](/factories/integrations/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/).
-* **Filters route work; they don't restrict access** - Choosing which requests start work is separate from what a running agent can reach. See [automation filters](/factories/automation-filters/#filters-route-work-they-dont-restrict-access).
-* **The factory hands off at the pull request** - It pushes branches and opens pull requests, then waits for a person. See [where your team stays in charge](/factories/how-factories-work/#where-your-team-stays-in-charge).
-
 Next, customize which agents receive work and how it's routed with [factory definitions as code](/factories/factory-as-code/).

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

@@ -7,6 +7,10 @@ sidebar:
   label: "Factory agents"
 ---
 
+:::note
+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.
+:::
+
 Every factory has a **foreman**, the one agent you talk to from whichever tool a request starts in. Around it sit four default agents, one for each part of the software development lifecycle: triage scopes the request, spec writes the plan, implement writes the code, and review checks it. Together they take a work item from the moment it reaches your factory to a pull request ready for a person to review.
 
 ## The default agents

src/content/docs/factories/factory-as-code.mdx

@@ -382,6 +382,19 @@ platform:
     dockerImage: ubuntu:22.04
 ```
 
+### Routing to a self-hosted worker
+
+To route this factory's work to a [managed self-hosted worker](/factories/infrastructure-and-security/#choose-an-execution-host) instead of Warp-hosted compute, set `workerHost` on `agentDefaults` (or override it per agent or automation) to the worker's ID:
+
+```yaml title="factory.yaml"
+agentDefaults:
+  model: auto
+  runner: linux-build
+  workerHost: SELF_HOSTED_WORKER_ID
+```
+
+Pair `workerHost` with a runner whose `platform` matches the worker's operating system and architecture. See [choose an execution host](/factories/infrastructure-and-security/#choose-an-execution-host) for the full setup, including how to deploy and connect the worker.
+
 ## Pull request checks for GitHub-backed factories
 
 When your definition lives in GitHub, Warp validates every change before it takes effect: