docs(factories): add automation filters page

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

@@ -0,0 +1,83 @@
+---
+title: Automation filters
+description: >-
+  Automation filters decide which events from connected tools start factory
+  runs — matching rules, per-source filters, and what they don't control.
+sidebar:
+  label: Automation filters
+topic: factories
+---
+
+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.
+
+## 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:
+
+* **Every filter must match** - Filters combine with AND. A trigger that sets both a team and a label matches only events that carry both.
+* **Within a filter, any value matches** - Values combine with OR. A **Labels** filter listing `bug` and `regression` matches an issue that carries either label.
+* **An empty filter matches everything** - A filter you leave unset doesn't constrain matching, and a trigger with no filters starts work for every event of its type that the connection delivers.
+
+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 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:
+
+{/* TODO: link the GitLab row to /factories/integrations/gitlab/ once the GitLab integration page lands (PR #549). */}
+
+| Source | Filters |
+| --- | --- |
+| [Slack](/factories/integrations/slack/) | Conversations, authors or members, keywords, emoji, and reacted-message authors |
+| [GitHub](/factories/integrations/github/) | Repository, branches, base branches, paths, labels, authors, assignees, mentioned users or teams, reviewers, review states, workflows, and conclusions |
+| GitLab | Project, actions, and base branch |
+| [Linear](/factories/integrations/linear/) | Teams, labels, project, workflow state, assignee, mentioned user, and, for comment events, a specific issue |
+| [Jira](/factories/integrations/jira/) | Jira projects and assignment keywords |
+
+Each integration guide lists which filters appear on which event types.
+
+## Edit filters on an automation
+
+1. In the factory's control room, open **Automations**, then create an automation or edit an existing one.
+2. Under **Triggers**, open a trigger and set the filters shown for its event. Click **More filters** for the event-specific options.
+3. Click **Save**. To confirm the routing works, send a matching test event, such as opening a test issue, and check that a work item starts in the control room.
+
+Review the default automations Warp creates when you connect a provider, too: their filters are starting points, not fixed rules.
+
+## Filters in definitions as code
+
+In a [factory definition](/factories/factory-as-code/), each entry under an automation's `triggers` takes an optional `filter` whose keys mirror the filters in the automation editor:
+
+```markdown title="automations/labeled-issue/automation.md"
+---
+enabled: true
+agent: foreman
+triggers:
+  - provider: github
+    event: issue_labeled
+    filter:
+      repos: [ACME/PAYMENTS_SERVICE]
+      labels: [factory-ready]
+---
+
+Review the labeled issue and decide the next required stage.
+```
+
+The same matching rules apply: every key must match, any listed value within a key matches, and an omitted key matches everything. Each integration guide shows the keys its provider accepts.
+
+## Troubleshooting
+
+* **A matching event doesn't start work** - Confirm the automation is enabled and the trigger's event type matches, then check every filter; a single mismatch prevents routing. Each integration guide's troubleshooting section covers provider-specific causes, such as app installation coverage.
+
+## Related pages
+
+* [Connect your factory](/factories/connect-your-factory/) - Choose the sources that route work into the factory.
+* [Slack](/factories/integrations/slack/), [GitHub](/factories/integrations/github/), [Linear](/factories/integrations/linear/), and [Jira](/factories/integrations/jira/) integration guides - Per-source setup, events, and filter details.
+* [Definitions as code](/factories/factory-as-code/) - Manage automations, triggers, and filters as version-controlled files.
+* [Control room](/factories/control-room/) - Create and edit automations in the factory's **Automations** view.

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

@@ -60,7 +60,7 @@ All Jira work reaches the factory through a single event, `agent_session_created
 * **`project_keys`** - Match work items in these Jira projects.
 * **`keywords`** - Match assignment text that contains any of these words. Matching is case-insensitive.
 
-A session must match every field you set; within a field, any listed value is a match. Omit a field to match everything.
+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.

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

@@ -14,7 +14,7 @@ Connect a factory to Slack so your team can send it work without leaving their c
 
 You need permission to update the factory and install apps in the target Slack workspace. Workspace policy can require administrator approval.
 
-Installing the app grants the Slack permissions shown on the authorization screen. Filters on automations only control which events start work; they don't limit what the app can access. For workspace-level installation and removal behavior, see the [Slack platform integration](/platform/integrations/slack/).
+Installing the app grants the Slack permissions shown on the authorization screen. [Filters on automations](/factories/automation-filters/) only control which events start work; they don't limit what the app can access. For workspace-level installation and removal behavior, see the [Slack platform integration](/platform/integrations/slack/).
 
 ## Connect the factory
 

src/sidebar.ts

@@ -404,6 +404,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
 								{ slug: 'factories/integrations/jira', label: 'Jira' },
 							],
 						},
+						{ slug: 'factories/automation-filters', label: 'Automation filters' },
 						{ slug: 'factories/factory-mcp', label: 'Factory MCP' },
 					],
 				},