docs(factories): Skills primitive page, Automations rename, factory sizing guidance

.agents/references/terminology.md

@@ -320,6 +320,15 @@ Docs match the screen; the fix belongs in the app.
 - **factory dashboard** — The web app surface for operating a single factory: its work items, runs, agents, automations, and settings.
   *Usage note:* Lowercase common noun. Distinct from **Dashboard**, the metrics page inside it, which is also the factory's landing page — bold **Dashboard** when you mean that page, and leave "factory dashboard" unbolded when you mean the surface. Replaced "control room," a docs-only coinage that appeared nowhere in the product.
 
+- **automation** — A factory resource, defined by an `automations/<name>/automation.md` file, that starts runs on one or more triggers (a connected-tool event or a schedule) and routes them to a chosen agent, with optional filters and execution overrides.
+  *Usage note:* Lowercase common noun. Distinct from the **Automation Platform**, the product; and from a **trigger**, the event that fires an automation.
+
+- **runner** — A factory resource, defined by a `runners/<name>.yaml` file, that defines the compute a run executes on: operating system, architecture, sandbox image, and instance shape. Agents and automations select a runner by name, or inherit the factory's default.
+  *Usage note:* Lowercase common noun. Scoped to a factory's definition; distinct from the general [cloud agent runner](/platform/runners/) reference, which covers the same concept for standalone cloud agents outside a factory.
+
+- **Scorer** — An LLM judge, configured per factory, that classifies completed agent conversations against criteria a team defines, scoped to chosen agents and sampled at a set rate. Feeds the **Dashboard** page's Scorer cards, benchmarks, and Self-improvement.
+  *Usage note:* Capitalize, since it names a specific configured entity in the factory dashboard's UI (parallel to **Dashboard**), not a generic industry term.
+
 - **AI sovereignty** — Warp Factories' positioning around customer ownership and control of inference, hosting, and data exhaust (agent conversations, evals, memories) for their factory.
 
 ## Technical terms

.agents/skills/check_for_broken_links/check_links.py

@@ -80,11 +80,25 @@
 
 def slugify_heading(text):
     """Approximate github-slugger, which is what Starlight uses for anchor ids."""
+    # Code span contents are literal text, never Markdown/MDX/JSX. Protect them
+    # from the substitutions below by stashing them first and restoring the raw
+    # text afterward. Without this, a heading like `automations/<name>/automation.md`
+    # has its `<name>` placeholder stripped as if it were a real JSX tag, even
+    # though Starlight's actual heading-id generator keeps it (verified against
+    # the rendered `id` attribute: `automationsnameautomationmd`, not
+    # `automationsautomationmd`).
+    code_spans = []
+
+    def _stash(m):
+        code_spans.append(m.group(1))
+        return f'\x00{len(code_spans) - 1}\x00'
+
+    text = re.sub(r'`([^`]*)`', _stash, text)             # code spans (stashed)
     text = re.sub(r'\{[^}]*\}', '', text)                 # MDX expressions, e.g. {VARS.X}
     text = re.sub(r'<[^>]+>', '', text)                   # inline HTML/JSX
-    text = re.sub(r'`([^`]*)`', r'\1', text)              # code spans
     text = re.sub(r'\[([^\]]*)\]\([^)]*\)', r'\1', text)  # links keep their text
     text = re.sub(r'[*_]{1,3}', '', text)                 # emphasis
+    text = re.sub(r'\x00(\d+)\x00', lambda m: code_spans[int(m.group(1))], text)
     text = text.strip().lower()
     text = re.sub(r'[^\w\- ]+', '', text, flags=re.UNICODE)
     return text.replace(' ', '-')

src/content/docs/factories/automation-filters.mdx → src/content/docs/factories/automations.mdx

@@ -1,33 +1,35 @@
 ---
-title: Automation filters
+title: Automations
 description: >-
-  Automation filters decide which events from connected tools start factory
-  runs: matching rules, per-source filters, and what filters don't control.
+  An automation starts factory runs from a trigger, routes them to an agent,
+  and filters which events start a run.
 sidebar:
-  label: Automation filters
+  label: Automations
 ---
 
-Automation filters decide which events from your connected tools start factory work. Every trigger on a [factory automation](/factories/connect-your-factory/) carries filters — conditions such as a repository, channel, team, project, label, or author — and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them.
+An **automation** is a factory resource that starts runs from a trigger and routes them to an agent. Triggers fired by a connected tool also carry filters that decide which events start a run. Every default automation Warp creates when you connect a provider, and every custom one you add, is this same resource. See [`automations/<name>/automation.md`](/factories/factory-as-code/#automationsnameautomationmd) for the full schema.
+
+Automation filters decide which events from your connected tools start factory work. Every trigger on an automation carries filters (e.g., a repository, channel, team, project, label, or author) and an event starts a run only when it matches them. Filters let a factory watch busy channels and repositories without acting on everything in them.
 
 ## How matching works
 
-An event starts an automation only when it matches the trigger's provider, its event type, and every filter set on that trigger:
+An event starts an automation only when it matches the trigger's provider, event type, and filters:
 
 * **Every filter must match.** A trigger that sets both a team and a label matches only events carrying both.
 * **Within one filter, any value matches.** A **Labels** filter listing `bug` and `regression` matches an issue with either label.
 * **A filter you leave empty matches everything.** A trigger with no filters at all starts work for every event of its type.
 
 One event can match more than one automation, and each match starts its own run. If a single action starts duplicate runs, narrow or remove one of the overlapping triggers.
 
-## Filters route work; they don't restrict access
+## Filters don't control access
 
-Filters decide when work starts, not what a running agent can reach. Access comes from what you authorize on each provider — the GitHub App installation, the GitLab bot's project membership, the Slack app's authorization, the Linear OAuth scope, or the Jira app installation. Tightening a filter never shrinks that access, and removing one never widens it. To change what an integration can reach, change what you authorize for that provider.
+Filters decide when work starts, not what a running agent can reach. Access comes from what you authorize on each provider: the GitHub App installation, the GitLab bot's project membership, the Slack app's authorization, the Linear OAuth scope, or the Jira app installation. Tightening a filter never shrinks that access, and removing one never widens it. To change what an integration can reach, change what you authorize for that provider.
 
 Filters are still your main control over who starts runs. On GitHub and GitLab, the event author doesn't need to be a Warp team member, so use author, member, and branch filters to decide whose activity starts work. Slack mentions and direct messages additionally require a Slack account linked to a member of the factory's Warp team.
 
 ## What each source can filter on
 
-Every source filters on where the event happened — a repository, project, conversation, or team. The remaining filters vary by source and event type:
+Every source filters on where the event happened: a repository, project, conversation, or team. The remaining filters vary by source and event type:
 
 | Source | Filters |
 | --- | --- |

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

@@ -7,13 +7,15 @@ sidebar:
   label: "Connect your factory"
 ---
 
-Connect your factory to the tools where your team already discusses, tracks, and reviews work. Wherever work starts, the factory keeps the original context — the thread, issue, or pull request — and posts results back to the same place.
+Connect your factory to the tools where your team already discusses, tracks, and reviews work. Wherever work starts, the factory keeps the original context from that source (the thread, issue, or pull request), and posts results in the same place.
+
+Each source feeds into this factory's repositories. If the work belongs to a different product surface, [start a new factory](/factories/#sizing-a-factory) for it instead.
 
 ## Choose a source
 
 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 |
+| Source | Best for | Continues in |
 | --- | --- | --- |
 | [Slack](/factories/integrations/slack/) | Chat and support requests | The Slack thread or DM |
 | [GitHub](/factories/integrations/github/) | Issues, pull requests, reviews, and CI | The issue, pull request, or review thread |
@@ -26,7 +28,7 @@ Pick the sources that match where work starts for your team. You can connect mul
 
 ## Connect a 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.
+Each integration guide walks through authorizing access — grant only what the factory needs. New connections add default automations, so events start working right away. Review the [automations](/factories/automations/) and adjust their filters and run settings to fit your workflow.
 
 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.
 

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

@@ -53,7 +53,7 @@ Review independently examines the change for unmet requirements, broken conventi
 
 ## Built-in skills
 
-Every default agent comes with GitHub skills, and the foreman also comes with a Slack skill. The issue tracker you choose during setup adds to that baseline: choosing Linear or Jira gives the agents that tracker's skill and instructions. If you don't choose a tracker, the agents get only the baseline skills. Define custom procedures with [skills](/agents/capabilities/skills/) to extend what an agent can do beyond the built-in set.
+Every default agent comes with GitHub skills, and the foreman also comes with a Slack skill. The issue tracker you choose during setup adds to that baseline: choosing Linear or Jira gives the agents that tracker's skill and instructions. If you don't choose a tracker, the agents get only the baseline skills. Define custom procedures with [factory skills](/factories/factory-skills/) to extend what an agent can do beyond the built-in set.
 
 ## Configure agent behavior
 

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

@@ -182,7 +182,7 @@ For a definition that runs a different harness per agent, with managed-secret au
 
 ### `agentDefaults.runner`
 
-The name of a runner defined under [`runners/`](#runnersyaml) that provides the compute for runs.
+The name of a runner defined under [`runners/`](#runnersnameyaml) that provides the compute for runs.
 
 ### `agentDefaults.environmentId`
 
@@ -321,7 +321,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/<name>/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/<name>/skills/` are available only to that agent. See [factory skills](/factories/factory-skills/) for when to add one, and [Skills](/agents/capabilities/skills/) for the file format.
 
 ## Example factory definition
 

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

@@ -0,0 +1,75 @@
+---
+title: Factory skills
+description: >-
+  Skills give a factory's agents repeatable, version-controlled procedures
+  that can be shared across every agent or scoped to just one.
+sidebar:
+  label: "Factory skills"
+---
+
+:::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.
+:::
+
+A skill tells an agent what to check, how to classify results, what to produce, and when to escalate. In a factory, skills are how you extend or override [default agents](/factories/factory-agents/), without editing their prompts directly.
+
+## Factory-wide and per-agent skills
+
+A skill is a directory containing a `SKILL.md`. It's part of the factory's [definition](/factories/factory-as-code/), not an agent's settings. Where you place the directory decides who can use it:
+
+```text
+skills/
+  repository-conventions/
+    SKILL.md
+agents/
+  foreman/
+    skills/
+      incident-triage/
+        SKILL.md
+```
+
+* **`skills/<name>/SKILL.md`** - Available to every agent in the factory. Use this for procedures that apply regardless of role, such as your repository's coding conventions or a shared escalation policy.
+* **`agents/<name>/skills/<name>/SKILL.md`** - Available only to that agent. Use this for procedures specific to one role, such as how the review agent should apply your security checklist.
+
+Both forms use the same `SKILL.md` format as skills anywhere else in Warp. See [Skills](/agents/capabilities/skills/) for the file format, front matter, and argument syntax.
+
+## Built-in skills
+
+Every default agent starts with a baseline of built-in skills so the factory works immediately after setup, before you write anything custom:
+
+* **GitHub** - Every default agent gets a GitHub skill, covering how to read issues, open pull requests, and follow your repository's conventions.
+* **Slack** - The foreman also gets a Slack skill, since it's the agent that replies in threads and DMs.
+* **Issue tracker** - The tracker you choose during setup, Linear or Jira, adds that tracker's skill and instructions to the agents that use it. If you don't connect a tracker, agents keep only the GitHub and Slack skills.
+
+These baseline skills aren't files in your definition; they come from the agent roles and integrations you choose. Anything you add under `skills/` or `agents/<name>/skills/` extends this baseline rather than replacing it.
+
+## When to add a custom skill
+
+Add a custom skill when a default agent needs to do something the built-in baseline doesn't cover, such as:
+
+* Enforcing a specific test, lint, or validation command before a change is considered complete.
+* Following a runbook for a category of incident or request your triage agent sees repeatedly.
+* Applying a security or compliance checklist during review that goes beyond general code quality.
+* Teaching a custom agent its job. Custom agents have no built-in skills.
+
+A skill changes what an agent knows how to do, not what it can reach. To scope access, configure the agent's [secrets](/platform/secrets/) and [MCP servers](/platform/mcp/) — see [factory agents](/factories/factory-agents/#configure-agent-behavior) and [infrastructure and security](/factories/infrastructure-and-security/#credential-boundaries).
+
+## Add or edit a skill
+
+Where you edit a skill depends on [where the factory's definition lives](/factories/factory-as-code/#where-the-definition-lives):
+
+* **Warp-managed** - Add or edit `SKILL.md` files directly in the **Factory definition** tab of the [factory dashboard](/factories/factory-dashboard/). Saving validates and commits the change in one step.
+* **GitHub** - Add or edit the files in the connected definition repository and open a pull request. The same [pull request checks](/factories/factory-as-code/#pull-request-checks-for-github-backed-factories) that validate the rest of the definition apply to skill files.
+
+For worked examples, including a factory-wide skill and a per-agent skill together, see [`02-sdlc-issue-to-pr`](https://github.com/warpdotdev/warp-factory-examples/tree/main/examples/02-sdlc-issue-to-pr) in the [warp-factory-examples](https://github.com/warpdotdev/warp-factory-examples) repository.
+
+## Skills and self-improvement
+
+A factory can propose changes to a skill. When [Self-improvement](/factories/measure-and-improve/#configure-and-review-self-improvement) is on for a Scorer and it flags a recurring failure, it can edit the responsible skill in a follow-up run, the same way it can edit application code. The change still arrives as a pull request for your team to review, whether that's through the factory dashboard or your Git host.
+
+## Related pages
+
+* [Factory agents](/factories/factory-agents/) - The agents that use a factory's skills, and how to configure each one.
+* [Definitions as code](/factories/factory-as-code/) - The full schema for `factory.yaml`, agents, automations, and runners alongside skills.
+* [Skills](/agents/capabilities/skills/) - The general skill file format, shared across Warp, cloud agents, and factories.
+* [Measure and improve a factory](/factories/measure-and-improve/) - How Self-improvement turns repeated failures into skill and code changes.

src/content/docs/factories/how-factories-work.mdx

@@ -13,6 +13,8 @@ Warp Factories is in **Early Access** and available to a limited set of teams. [
 
 A factory is a team of cloud agents that ships software the way your team does: a request comes in, moves through the stages it needs, and comes back as a pull request ready for review. 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 **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.
 
 ## How a work item moves through the factory