docs: restructure factories documentation

.agents/skills/doc_quality_policy/test_agent_docs_review_workflow.py

@@ -34,6 +34,20 @@ def test_all_review_findings_must_supply_actionable_details(self):
         self.assertIn("critical, important, suggestion, or nit", self.workflow)
         self.assertIn("file and line or quoted text", self.workflow)
 
+    def test_review_signal_is_passed_through_a_file(self):
+        self.assertIn('oz "${args[@]}" > /tmp/agent-output.txt', self.workflow)
+        self.assertIn("--agent-output /tmp/agent-output.txt", self.workflow)
+        self.assertNotIn(".agent-docs-review-signal.txt", self.workflow)
+        self.assertNotIn(
+            "AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}", self.workflow
+        )
+
+    def test_review_uses_a_signed_oz_package(self):
+        self.assertIn("0913165C78D5B7A41B42AC657FF7AB39D60F803F", self.workflow)
+        self.assertIn("signed-by=/etc/apt/keyrings/warpdotdev.gpg", self.workflow)
+        self.assertIn("sudo apt-get install -y oz-stable", self.workflow)
+        self.assertIn("oz --version", self.workflow)
+
 
 if __name__ == "__main__":
     unittest.main()

.agents/skills/doc_quality_policy/test_verify_review_signal.py

@@ -78,6 +78,18 @@ def test_escaped_action_output_signal_passes(self):
             problems = vrs.check_review_signal("o/r", "1", "sha1", output)
         self.assertEqual(problems, [])
 
+    def test_signal_with_braces_in_an_actionable_finding_passes(self):
+        output = (
+            '[SIGNAL:pr-review] {"pr":"1","head_sha":"sha1",'
+            '"reviewer_login":"github-actions[bot]","verdict":"Approve with nits",'
+            '"critical":0,"important":0,"suggestions":1,"nits":0,'
+            '"actionable_findings":["`factory-api.mdx:20` — Check '
+            '`POST /factory/{uid}/runs`."]}'
+        )
+        with mock.patch.object(vrs.cpc, "_fetch_reviews", return_value=[{**GOOD_REVIEW, "body": output}]):
+            problems = vrs.check_review_signal("o/r", "1", "sha1", output)
+        self.assertEqual(problems, [])
+
     def test_distinct_signals_fail(self):
         different_signal = GOOD_OUTPUT.replace('"Approve"', '"Approve with nits"')
         output = f"{GOOD_OUTPUT}\n\n{different_signal}"

.agents/skills/doc_quality_policy/verify_review_signal.py

@@ -5,7 +5,6 @@
 import argparse
 import importlib.util
 import json
-import re
 import sys
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple
@@ -16,7 +15,7 @@
 sys.modules[_spec.name] = cpc
 _spec.loader.exec_module(cpc)
 
-_SIGNAL_RE = re.compile(r"\[SIGNAL:pr-review\]\s*(\{.*?\})", re.DOTALL)
+_SIGNAL_PREFIX = "[SIGNAL:pr-review]"
 _PASSING_VERDICTS = {"approve", "approve with nits", "approve_with_nits"}
 
 
@@ -25,25 +24,24 @@ def _parse_signal(
     pr_number: Optional[str] = None,
     head_sha: Optional[str] = None,
 ) -> Tuple[Optional[Dict[str, object]], List[str]]:
-    matches = _SIGNAL_RE.findall(text)
-    if not matches:
+    occurrences = text.count(_SIGNAL_PREFIX)
+    if not occurrences:
         return None, ["expected exactly one [SIGNAL:pr-review] record, found 0"]
 
     unique_signals = {}
-    for match in matches:
-        try:
-            signal = json.loads(match)
-        except json.JSONDecodeError as original_error:
+    offset = 0
+    while True:
+        marker = text.find(_SIGNAL_PREFIX, offset)
+        if marker == -1:
+            break
+        offset = marker + len(_SIGNAL_PREFIX)
+        candidate = text[offset:].lstrip()
+        signal = None
+        for payload in (candidate, candidate.replace('\\"', '"')):
             try:
-                # The GitHub Action can serialize its text output once more,
-                # leaving an otherwise valid object in the form
-                # {\"key\":\"value\"}. Decode that wrapper only after direct
-                # JSON parsing has failed.
-                signal = json.loads(match.replace('\\"', '"'))
+                signal, _ = json.JSONDecoder().raw_decode(payload)
+                break
             except json.JSONDecodeError:
-                # Agent output includes the skill's marker examples and prior
-                # review transcripts. Ignore malformed candidates and require
-                # a valid, current-head record below.
                 continue
         if not isinstance(signal, dict):
             continue
@@ -57,7 +55,7 @@ def _parse_signal(
     if len(signals) != 1:
         return None, [
             "expected one valid [SIGNAL:pr-review] record for the current PR head, "
-            f"found {len(signals)} across {len(matches)} occurrences"
+            f"found {len(signals)} across {occurrences} occurrences"
         ]
     return signals[0], []
 

.github/workflows/agent-docs-review.yml

@@ -37,12 +37,30 @@ jobs:
         uses: actions/checkout@v4
 
       - name: Run independent review-docs-pr agent
-        id: oz-review
-        uses: warpdotdev/oz-agent-action@main
-        with:
-          warp_api_key: ${{ secrets.WARP_API_KEY }}
-          profile: ${{ vars.WARP_AGENT_PROFILE || '' }}
-          prompt: |
+        env:
+          WARP_API_KEY: ${{ secrets.WARP_API_KEY }}
+          WARP_AGENT_PROFILE: ${{ vars.WARP_AGENT_PROFILE || '' }}
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y gpg
+          curl --fail --location https://releases.warp.dev/linux/keys/warp.asc \
+            --output /tmp/warpdotdev.asc
+          # Verified against releases.warp.dev/linux/keys/warp.asc on 2026-09-18.
+          # Reverify this fingerprint before updating the Warp signing key.
+          test "$(
+            gpg --show-keys --with-colons /tmp/warpdotdev.asc |
+              awk -F: '/^fpr:/ { print $10; exit }'
+          )" = "0913165C78D5B7A41B42AC657FF7AB39D60F803F"
+          gpg --dearmor --output /tmp/warpdotdev.gpg /tmp/warpdotdev.asc
+          sudo install -D -o root -g root -m 644 /tmp/warpdotdev.gpg \
+            /etc/apt/keyrings/warpdotdev.gpg
+          sudo tee /etc/apt/sources.list.d/warpdotdev.list > /dev/null <<'EOF'
+          deb [arch=amd64 signed-by=/etc/apt/keyrings/warpdotdev.gpg] https://releases.warp.dev/linux/deb stable main
+          EOF
+          sudo apt-get update
+          sudo apt-get install -y oz-stable
+          oz --version
+          PROMPT="$(cat <<'EOF'
             Run the review-docs-pr skill against warpdotdev/docs PR #${{ github.event.pull_request.number }}
             at head SHA ${{ github.event.pull_request.head.sha }}. This PR carries the warpy-factory agent
             marker, so it requires the independent v1 agent-doc quality review pass (see
@@ -60,6 +78,15 @@ jobs:
                changed file and line or quoted text, explain the problem, and state the requested
                resolution. Set reviewer_login to `github-actions[bot]`, the runner account that
                will publish the review.
+            5. Your final response must contain only the single [SIGNAL:pr-review] JSON record.
+               Do not repeat the diff, review rationale, or findings outside that record.
+          EOF
+          )"
+          args=(agent run --output-format text --prompt "$PROMPT")
+          if [ -n "$WARP_AGENT_PROFILE" ]; then
+            args+=(--profile "$WARP_AGENT_PROFILE")
+          fi
+          oz "${args[@]}" > /tmp/agent-output.txt
       - name: Dismiss stale automated change requests
         env:
           GH_TOKEN: ${{ github.token }}
@@ -78,9 +105,7 @@ jobs:
       - name: Publish the independent review
         env:
           GH_TOKEN: ${{ github.token }}
-          AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}
         run: |
-          printf '%s' "$AGENT_OUTPUT" > /tmp/agent-output.txt
           python3 .agents/skills/doc_quality_policy/publish_review_signal.py \
             --agent-output /tmp/agent-output.txt \
             --pr "${{ github.event.pull_request.number }}" \
@@ -96,9 +121,7 @@ jobs:
       - name: Verify the current review signal and GitHub review
         env:
           GH_TOKEN: ${{ github.token }}
-          AGENT_OUTPUT: ${{ steps.oz-review.outputs.agent_output }}
         run: |
-          printf '%s' "$AGENT_OUTPUT" > /tmp/agent-output.txt
           python3 .agents/skills/doc_quality_policy/verify_review_signal.py \
             --repo "${{ github.repository }}" \
             --pr "${{ github.event.pull_request.number }}" \

astro.config.mjs

@@ -228,7 +228,6 @@ export default defineConfig({
 						{ label: 'Enterprise', description: 'Enterprise features, SSO, team management, and security.', paths: ['enterprise/**'] },
 						{ label: 'Getting Started', description: 'Installation, quickstart, and migration guides.', paths: ['index', 'quickstart', 'getting-started/**'] },
 						{ label: 'Knowledge and Collaboration', description: 'Warp Drive, teams, and the Admin Panel.', paths: ['knowledge-and-collaboration/**'] },
-						{ label: 'API & Reference', description: 'CLI and API reference.', paths: ['reference/**'] },
 						// All support-and-community/ pages. open-source-licenses.mdx is excluded
 						// globally above (stack overflow in hast-util-to-text); the patch ensures
 						// it's excluded from this custom set as well.

developers/agent-api-openapi.yaml

@@ -1,8 +1,8 @@
 openapi: 3.0.0
 info:
-  title: Warp Agent API
+  title: Warp Platform API
   version: 1.0.0
-  description: "API for creating, managing, and querying Warp cloud agent runs.\n\nThese endpoints allow users to programmatically spawn agents, list runs, \nand retrieve detailed run information.\n"
+  description: "API for creating, managing, and querying factory and cloud agent runs.\n\nThese endpoints allow users to send work to factories, start standalone agents, list runs, \nand retrieve detailed run information.\n"
   contact:
     name: Warp Support
     url: https://docs.warp.dev

src/content/docs/agents/agent-memory/index.mdx

@@ -85,8 +85,8 @@ Attach stores to agents with read-only or read-write access. Each attachment inc
 
 These capabilities aren't part of the research preview yet, but they're on the way:
 
-* **Programmatic API access** - Read and manage memories and stores through the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), in addition to managing them in the {VARS.WEB_APP}.
-* **Self-hosting support** - Run Agent Memory on a [self-hosted {VARS.WARP_AUTOMATION_PLATFORM}](/platform/self-hosting/) instance to meet security, privacy, and compliance requirements.
+* **Programmatic API access** - Read and manage memories and stores through the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), in addition to managing them in the {VARS.WEB_APP}.
+* **Self-hosting support** - Run Agent Memory on a [self-hosted {VARS.WARP_AUTOMATION_PLATFORM}](/factories/self-hosting/) instance to meet security, privacy, and compliance requirements.
 
 ## Join the waitlist
 

src/content/docs/agents/capabilities/computer-use/index.mdx

@@ -44,7 +44,7 @@ Runs started from the Warp app don't use the server default: they always follow
 
 ### CLI
 
-When running cloud agents with the [{VARS.WARP_AGENT_CLI}](/reference/cli/), use flags to control Computer Use per run:
+When running cloud agents with the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/), use flags to control Computer Use per run:
 
 ```bash
 oz agent run-cloud --computer-use --prompt "<task>"
@@ -53,7 +53,7 @@ oz agent run-cloud --no-computer-use --prompt "<task>"
 
 ### API
 
-When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp's built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run:
+When creating a cloud agent run with the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/), the optional `config.computer_use_enabled` field controls Computer Use. When omitted, it defaults to `true` for runs on Warp's built-in harness and `false` for runs on third-party harnesses. Set it to `false` to disable Computer Use for the run:
 
 ```json
 {
@@ -65,7 +65,7 @@ When creating a cloud agent run with the [{VARS.API_SDK_NAME}](/reference/api-an
 }
 ```
 
-For full API documentation, see the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) reference.
+For full API documentation, see the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) reference.
 
 ### Web app
 

src/content/docs/reference/cli/agent-profiles.mdx → src/content/docs/agents/cli/oz-cli/agent-profiles.mdx

@@ -9,7 +9,7 @@ sidebar:
 import { VARS } from '@data/vars';
 
 :::caution
-The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today.
+The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change.
 :::
 
 Agent profiles control what the agent can do, how it behaves, and where it can act when running from the {VARS.WARP_AGENT_CLI}. Create profiles in the Warp app to configure file access, command execution, MCP server usage, model selection, and directory permissions, then reference them by ID in CLI commands.

src/content/docs/reference/cli/api-keys.mdx → src/content/docs/agents/cli/oz-cli/api-keys.mdx

@@ -8,7 +8,7 @@ sidebar:
 import { VARS } from '@data/vars';
 
 :::caution
-The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today.
+The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change.
 :::
 
 API keys let the {VARS.WARP_AGENT_CLI} and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments.
@@ -46,7 +46,7 @@ You can create an API key in either the <a href={`${VARS.WEB_APP_URL}/settings`}
 7. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.**
 
 <figure>
-![API key management interface in Warp settings](../../../../assets/reference/api-key-management.png)
+![API key management interface in Warp settings](../../../../../assets/reference/api-key-management.png)
 <figcaption>API key management interface in Warp settings.</figcaption>
 </figure>
 
@@ -86,7 +86,7 @@ $ oz agent run --api-key "wk-xxx..." --prompt "analyze this codebase"
 ```
 
 :::note
-API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be [invalid or from an older format](/reference/api-and-sdk/troubleshooting/errors/authentication-required/).
+API keys start with the prefix `wk-`. If your key doesn't have this prefix, it may be [invalid or from an older format](/factories/api-and-sdk/troubleshooting/errors/authentication-required/).
 :::
 
 ## Managing API keys
@@ -107,11 +107,11 @@ The Warp app also shows additional metadata that isn't surfaced in the {VARS.WEB
 
 To delete an API key, find it in either the {VARS.WEB_APP} or the Warp app's API Keys list and click the delete icon next to the key.
 
-Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access and may return an [`authentication_required` error](/reference/api-and-sdk/troubleshooting/errors/authentication-required/).
+Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access and may return an [`authentication_required` error](/factories/api-and-sdk/troubleshooting/errors/authentication-required/).
 
 ## Manage API keys from the CLI
 
-In addition to the web and Warp app surfaces, you can manage API keys directly with the [{VARS.WARP_AGENT_CLI}](/reference/cli/). These commands are useful for scripting key rotation and for headless environments.
+In addition to the web and Warp app surfaces, you can manage API keys directly with the [{VARS.WARP_AGENT_CLI}](/agents/cli/oz-cli/). These commands are useful for scripting key rotation and for headless environments.
 
 ### List keys
 

src/content/docs/reference/cli/artifacts.mdx → src/content/docs/agents/cli/oz-cli/artifacts.mdx

@@ -9,7 +9,7 @@ sidebar:
 import { VARS } from '@data/vars';
 
 :::caution
-The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today.
+The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change.
 :::
 
 Artifacts are files that an agent produces during a run and uploads to Warp — screenshots, generated reports, build outputs, logs, or any other file the agent saves alongside its conversation. Use `oz artifact` to inspect those files from outside the run and pull them down to your machine.
@@ -22,7 +22,7 @@ Use artifacts when you need to retrieve files an agent produced after a run comp
 * **Local inspection** - Pull a generated file (HTML, image, CSV) onto your laptop to review.
 * **CI integration** - Fetch an agent-produced build artifact from a pipeline step that runs after the agent finishes.
 
-Artifacts are referenced by an artifact UID. You can find UIDs in the agent's run detail view, in the JSON returned by [`oz run get`](/reference/cli/), or in the response from the [{VARS.API_SDK_NAME}](/reference/api-and-sdk/).
+Artifacts are referenced by an artifact UID. You can find UIDs in the agent's run detail view, in the JSON returned by [`oz run get`](/agents/cli/oz-cli/), or in the response from the [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/).
 
 ## `oz artifact get`
 
@@ -78,5 +78,5 @@ oz artifact download "$ARTIFACT_UID" --out ./latest-report.html
 
 ## Related
 
-* [{VARS.API_SDK_NAME}](/reference/api-and-sdk/) - retrieve artifacts programmatically over HTTP.
+* [{VARS.WARP_PLATFORM_API}](/factories/api-and-sdk/) - retrieve artifacts programmatically over HTTP.
 * [Scheduled cloud agents](/platform/triggers/scheduled-agents/) - common producer of recurring artifacts that downstream tooling consumes.

src/content/docs/reference/cli/federate.mdx → src/content/docs/agents/cli/oz-cli/federate.mdx

@@ -9,7 +9,7 @@ sidebar:
 import { VARS } from '@data/vars';
 
 :::caution
-The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today.
+The {VARS.WARP_AGENT_CLI} (the `oz` binary) is a supported legacy interface. Existing users do not need to change their workflows. For new multi-stage development workflows, use [Warp Factories](/factories/). Warp will publish guidance before any support change.
 :::
 
 `oz federate` issues short-lived OIDC identity tokens for the agent that's currently running. Use these tokens to authenticate to cloud providers (AWS, GCP, Azure, and other OIDC-aware systems) without baking long-lived credentials into your environment.