docs(factories): document Jira integration

Co-Authored-By: Warp Agent <agent@warp.dev>

Author: hongyi-chen

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

@@ -0,0 +1,63 @@
+---
+title: Connect a factory to Jira
+description: >-
+  Connect Jira Cloud to a factory so issue activity can route work, preserve
+  context, and return updates to Jira.
+sidebar:
+  label: Jira
+topic: factories
+---
+
+Connect Jira Cloud to a factory to turn issue activity into work and return results to the issue. Jira provides the authorized site and project context, while factory automations decide which events start or continue work.
+
+## Before you connect
+
+* **Jira Cloud** - The integration supports Jira Cloud, not Jira Server or Data Center.
+* **Jira site admin** - A site admin installs the Warp app on the Jira site and connects the installation to a Warp workspace.
+* **Factory access** - You need a factory in the connected workspace and permission to configure its automations.
+
+The Jira app's authorization determines which site and projects Warp can access and what the app can read or update. Automation filters only route events within that authorized access. A project filter does not reduce the app's credential permissions.
+
+## Connect and configure Jira
+
+1. Follow the [Jira integration setup](../../platform/integrations/jira) to install the app, open its **Configure** page, and click **Connect to Warp**. The connected Jira installation is available to factories in that Warp workspace.
+2. In the factory's control room, open **Automations**, then click **New**. Enter an automation name and choose the agent that will handle matching Jira work.
+3. Click **Add trigger** > **Jira**, then choose **Issue created**, **Issue labeled**, or **Status changed**. Select **Projects**, then add **Labels** or **Statuses** when the event supports them. Empty filters match all values that the connected installation can deliver.
+4. Add any instructions the agent needs, then click **Save**. Send a matching Jira event and confirm the run appears on the automation's **Runs** tab.
+
+The automation editor exposes those three Jira events. For a file-managed factory, define the other supported event classes, `issue_commented`, `issue_mentioned`, `comment_mentioned`, and `assignee_changed`, in `automations/<name>/automation.md`. See [factory definitions as code](../factory-as-code) for the automation file format.
+
+## Supported events, context, and outputs
+
+| Jira event class | Available routing filters | Context and typical output |
+| --- | --- | --- |
+| Issue created | Project and labels present at creation | Issue details and initial fields; comments, issue updates, or artifact links |
+| Issue labeled | Project and newly added labels | Issue details and the label change; comments or follow-up work |
+| Assignee changed | Project and destination assignee, including unassigned | Issue details and assignment change; comments or issue updates |
+| Status changed | Project and destination status | Issue details and status transition; comments or further issue updates |
+| Issue commented | Project | Issue and new comment; a follow-up on the same factory workstream |
+| Issue mentioned or comment mentioned | Project and mentioned account | Issue or comment mention context; a follow-up and Jira writeback |
+
+Different filter fields combine together. Multiple values within one field act as alternatives. Label and status triggers match the change into the selected value, not an unrelated update that leaves the value unchanged.
+
+## Continue work and write back
+
+Jira activity for the same issue and factory shares one workstream. When a matching event arrives after work already exists, the factory continues that work instead of starting a competing work item. This continuity applies across matching event classes, so a run started by a label can receive a later comment, mention, status, or assignment change.
+
+The factory can read the issue and its comments, post or update comments, transition the issue, add or remove labels, and update issue fields when the Jira installation authorizes those actions. It can also create Jira issues when the workflow calls for one. Completion comments can include links to branches, pull requests, and the full run.
+
+Jira writeback follows the permissions and workflow rules already configured in Jira. Pull request review and merge requirements remain repository or workflow policy, not factory-specific access control.
+
+## Permissions and delivery caveats
+
+Grant the Jira app only the site and project access required for the factory's work. Restrict intake separately with project, label, status, assignee, or mention filters. Review both boundaries when an automation receives too much context or an expected event does not match.
+
+Jira can deliver the same change more than once during retries. Build duplicate-safe workflows: check the current issue state before posting a comment, changing a status, or adding a label, and make repeated actions harmless whenever possible.
+
+## Troubleshooting
+
+* **The Jira site is not connected** - In Jira, open the Warp app's **Configure** page and click **Connect to Warp**. If the factory editor shows **Attach Jira**, **Set up Jira**, or **Reinstall Jira**, follow that action and retry.
+* **No run starts** - Confirm the automation is saved, the event class matches, and every configured project, label, status, assignee, or mention filter matches the Jira change.
+* **Writeback fails** - Check that the app can access the issue's project and perform the requested Jira action, including the target workflow transition.
+
+For other intake paths and provider boundaries, see [connecting your factory](../connect-your-factory).

src/sidebar.ts

@@ -374,6 +374,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
 			// Icon is a placeholder (gear) -- Starlight's built-in icon set has no
 			// literal factory glyph. A true factory icon would need a custom icon
 			// library plugin + Sidebar component override; revisit post-launch.
+			id: 'factories',
 			label: 'Factories',
 			link: '/factories/',
 			icon: 'setting',