Add docs for qurantining from cli / mcp

Author: ostenbom

src/content/docs/guides/modify-quarantine-rules-with-ai.mdx

@@ -0,0 +1,43 @@
+---
+title: Modify quarantine rules with AI
+description: Ask an AI coding agent to create and deactivate Endform quarantine rules
+sidebar:
+  order: 8
+---
+
+import Conversation from "../../../components/conversation/Conversation.astro";
+import UserMessage from "../../../components/conversation/UserMessage.astro";
+import ToolCall from "../../../components/conversation/ToolCall.astro";
+import AssistantMessage from "../../../components/conversation/AssistantMessage.astro";
+
+After you [connect the Endform MCP server](/docs/reference/mcp-server), your coding agent can inspect recent test runs and manage quarantine rules. The agent uses `query_samples` to retrieve the exact persisted suite and test IDs needed to create a rule.
+
+<Conversation title="Quarantine a failing test" open>
+  <UserMessage>
+    Quarantine the failing saved-card checkout test on the `main` branch while we investigate. Set it to expire on September 23, 2026 and explain exactly what the rule will match.
+  </UserMessage>
+
+  <ToolCall name="query_samples" summary="find recent failures for the saved-card checkout test" />
+  <ToolCall name="list_quarantine_rules" summary="check the current quarantine rules" />
+  <ToolCall name="create_quarantine_rule" summary="quarantine the exact test and branch until September 23" />
+
+  <AssistantMessage>
+    I created a rule for `checkout.spec.ts › saved card › completes payment` in the sampled suite. It matches that exact persisted test ID on the `main` branch across all Playwright projects and expires on September 23, 2026.
+  </AssistantMessage>
+</Conversation>
+
+<Conversation title="Remove quarantine after a fix">
+  <UserMessage>
+    Check whether the saved-card checkout test has recovered over the last seven days. If it has, deactivate its quarantine rule.
+  </UserMessage>
+
+  <ToolCall name="query_samples" summary="inspect the test's recent outcomes and retries" />
+  <ToolCall name="list_quarantine_rules" summary="find the active rule for the test" />
+  <ToolCall name="deactivate_quarantine_rule" summary="deactivate the exact quarantine rule" />
+
+  <AssistantMessage>
+    The test passed its last 18 runs without a retry, including six runs after the fix. I deactivated its quarantine rule, so it will return to normal failure behavior on new suite runs.
+  </AssistantMessage>
+</Conversation>
+
+See [Quarantine tests](/docs/guides/quarantine-tests) for how rules affect test execution and suite results. The complete tool reference is in [Endform MCP server](/docs/reference/mcp-server#manage-quarantine-rules).

src/content/docs/guides/quarantine-tests.mdx

@@ -45,6 +45,34 @@ counts each matching test once across projects and does not consider other
 quarantine rules. Future runs may contain different tests, so the preview is a
 guide to the rule's scope.
 
+## Manage rules from the CLI or AI
+
+Use `endform samples` to find the exact persisted suite and test IDs, then use
+them to create a rule:
+
+```bash
+npx endform@latest samples test-runs --where 'testRun.outcome = fail' --limit 10
+npx endform@latest quarantine create \
+  --suite-id suite_123 \
+  --test-id test_456 \
+  --reason 'Investigating checkout failures' \
+  --ends-at 2026-09-23T12:00:00Z
+```
+
+Creation requires `--suite-id` and at least one of `--test-id`, `--project`, or
+`--branch`. List active rules, include inactive rules, or deactivate a rule by
+its exact ID:
+
+```bash
+npx endform@latest quarantine list
+npx endform@latest quarantine list --all
+npx endform@latest quarantine deactivate rule_789
+```
+
+An AI coding agent can follow the same sample-driven workflow through the
+[Modify quarantine rules with AI](/docs/guides/modify-quarantine-rules-with-ai)
+guide.
+
 ## Example: quarantine a failing Firefox test
 
 This test, `launches firefox in lambda on arm64`, fails because its assertion

src/content/docs/reference/mcp-server.mdx

@@ -8,7 +8,7 @@ sidebar:
 import { Aside, Tabs, TabItem } from "@astrojs/starlight/components";
 import ParameterTable from "../../../components/ParameterTable.astro";
 
-The Endform CLI includes a local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. It gives AI coding agents tools for analyzing historical test data and debugging a Playwright test on Endform's remote infrastructure.
+The Endform CLI includes a local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. It gives AI coding agents tools for analyzing historical test data, managing quarantine rules, and debugging a Playwright test on Endform's remote infrastructure.
 
 ## Set up the MCP server
 
@@ -154,6 +154,56 @@ Returns raw OpenTelemetry trace data for a test attempt. The trace can show Play
 
 </ParameterTable>
 
+## Manage quarantine rules
+
+These tools let an AI agent list, create, and deactivate quarantine rules. See [Modify quarantine rules with AI](/docs/guides/modify-quarantine-rules-with-ai) for example conversations.
+
+### `list_quarantine_rules`
+
+Lists active quarantine rules and their exact rule IDs, scope, reason, and expiry.
+
+<ParameterTable>
+
+  | Parameter | Type | Description |
+  | --- | --- | --- |
+  | `organizationId` | string | Optional organization. Omit it to use the organization from the active login. |
+  | `includeInactive` | boolean | Include expired and deactivated rules. Defaults to `false`. |
+
+</ParameterTable>
+
+### `create_quarantine_rule`
+
+Creates a quarantine rule for an exact suite and scope. Use `query_samples` to retrieve the persisted `suite.id` and, when selecting a test, `test.id`. Test names, file paths, and Playwright worker IDs are not test IDs.
+
+<ParameterTable>
+
+  | Parameter | Type | Description |
+  | --- | --- | --- |
+  | `suiteId` | string | Exact persisted `suite.id` returned by `query_samples`. |
+  | `testId` | string | Optional exact persisted `test.id`. Omit it to match all tests in the suite. |
+  | `projectName` | string | Optional exact Playwright project name. |
+  | `branch` | string | Optional exact branch name. |
+  | `reason` | string | Optional reason for quarantining the matching tests. |
+  | `endsAt` | RFC 3339 string | Optional future expiry timestamp. Omit it for no expiry. |
+  | `organizationId` | string | Optional organization. Omit it to use the organization from the active login. |
+
+</ParameterTable>
+
+In addition to `suiteId`, provide at least one of `testId`, `projectName`, or `branch`. Omitted scope fields match any value within the suite.
+
+### `deactivate_quarantine_rule`
+
+Deactivates one quarantine rule by its exact ID. Use `list_quarantine_rules` to retrieve the ID.
+
+<ParameterTable>
+
+  | Parameter | Type | Description |
+  | --- | --- | --- |
+  | `ruleId` | string | Exact quarantine rule ID returned by `list_quarantine_rules`. |
+  | `organizationId` | string | Optional organization. Omit it to use the organization from the active login. |
+
+</ParameterTable>
+
 ## Debug tests
 
 These tools let an AI agent pause inside one Playwright test and inspect or interact with its live browser state. See [Debug tests with AI](/docs/guides/debug-tests-with-ai) for example conversations.