docs: restructure factories documentation

.agents/references/terminology.md

@@ -248,7 +248,6 @@ Not every "Oz" in the docs is stale. These are deliberate and correct until
 - **The `oz` binary** and every `oz <command>` invocation. Commands inside code
   fences are never rewritten. `{VARS.WARP_AGENT_CLI}` renders "Oz CLI".
 - **`oz.warp.dev`** and the Oz v1 web app. `{VARS.WEB_APP}`, `{VARS.WEB_APP_URL}`.
-- **`{VARS.API_SDK_NAME}`**, which renders "Oz API & SDK".
 - **`oz-agent-worker`, `oz-agent-action`, `oz-skills`** — repository and package
   names, not product names. These may never change.
 - **The `@oz-agent` GitHub handle.** Handles are strings the product owns;
@@ -262,7 +261,8 @@ Not every "Oz" in the docs is stale. These are deliberate and correct until
 
 ## Platform terms
 
-- **Agent API** — The HTTP API for triggering and inspecting Platform runs programmatically.
+- **Warp Platform API** — The HTTP API for sending work to factories and triggering and inspecting cloud agent runs programmatically.
+  *Usage note:* Use `{VARS.WARP_PLATFORM_API}` in body prose and `{{WARP_PLATFORM_API}}` in frontmatter.
 
 - **Auth** — The agent settings field for choosing or creating the credential (a team-owned secret) a harness uses to authenticate with its provider, matched to that harness's supported credential types (Anthropic keys for Claude Code, an OpenAI key for Codex).
   *Usage note:* Capitalize as **Auth** when referring to the settings field name.

.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], []
 

.agents/skills/style_lint/style_lint.py

@@ -108,7 +108,8 @@
     ("oz.warp.dev",  "WEB_APP_URL",              "{VARS.WEB_APP_URL} in prose or {{WEB_APP_URL}} in frontmatter"),
     ("Oz dashboard", "DASHBOARD",                "{VARS.DASHBOARD} in prose or {{DASHBOARD}} in frontmatter"),
     ("Oz run",       "PLATFORM_RUN",             "{VARS.PLATFORM_RUN} in prose or {{PLATFORM_RUN}} in frontmatter"),
-    ("Oz API & SDK", "API_SDK_NAME",             "{VARS.API_SDK_NAME} in prose or {{API_SDK_NAME}} in frontmatter"),
+    ("Oz API & SDK", "WARP_PLATFORM_API",        "{VARS.WARP_PLATFORM_API} in prose or {{WARP_PLATFORM_API}} in frontmatter"),
+    ("Warp Platform API", "WARP_PLATFORM_API",   "{VARS.WARP_PLATFORM_API} in prose or {{WARP_PLATFORM_API}} in frontmatter"),
     ("Oz Platform",  "WARP_AUTOMATION_PLATFORM", "{VARS.WARP_AUTOMATION_PLATFORM} in prose or {{WARP_AUTOMATION_PLATFORM}} in frontmatter"),
     ("Automation Platform", "WARP_AUTOMATION_PLATFORM", "{VARS.WARP_AUTOMATION_PLATFORM} in prose or {{WARP_AUTOMATION_PLATFORM}} in frontmatter"),
     ("Oz",           "WARP_AUTOMATION_PLATFORM", "{VARS.WARP_AUTOMATION_PLATFORM} in prose or {{WARP_AUTOMATION_PLATFORM}} in frontmatter"),

.agents/skills/sync-openapi-spec/references/sync-policy.md

@@ -18,7 +18,7 @@ This skill is the manual fallback for the same job, so its output has to match t
    top-level path operations.
 2. Drop every tag listed in `EXCLUDED_TAGS`.
 3. Drop every path whose tags are a subset of `EXCLUDED_TAGS`, plus every path listed explicitly in `EXCLUDED_PATHS` or matching a prefix in `EXCLUDED_PATH_PREFIXES`.
-4. Keep top-level `openapi`, `info`, `servers`, and `components.securitySchemes` verbatim.
+4. Keep top-level `openapi`, `servers`, and `components.securitySchemes` verbatim. Keep `info` from the source except for the docs-specific title and description override in `DOCS_INFO_OVERRIDES`.
 5. Keep only reusable component entries that are reachable from surviving paths via `$ref` walking (recursive over `allOf`/`oneOf`/`anyOf`/`items`/`additionalProperties`/etc.).
 6. Remove Factory-only values and matching description lines from `RunSourceType`.
 7. Recursively strip every key in `STRIP_FLAGS` from whatever survives
@@ -27,6 +27,17 @@ This skill is the manual fallback for the same job, so its output has to match t
 
 Rule 1 mirrors warp-server's own filter, so a surface the server team marks private stays private here without anyone having to maintain a matching allowlist entry.
 
+## Public API metadata
+
+The docs copy keeps endpoint behavior, contact details, licensing, and server
+configuration from `warp-server/public_api/openapi.yaml`. It overrides only
+`info.title` and `info.description` through `DOCS_INFO_OVERRIDES` in
+`scripts/sync_openapi.py`, so the Scalar reference uses the public docs name,
+**Warp Platform API**, and describes both factory and cloud-agent runs.
+
+Keep this override when syncing the docs subset. Update the source spec when
+its endpoint behavior or non-product metadata changes.
+
 ## `x-internal` deletes the whole marked object, not just the flag (`_prune_internal`)
 
 `x-internal: true` mirrors openapi-format's `flagValues` semantics in

.agents/skills/sync-openapi-spec/scripts/sync_openapi.py

@@ -109,6 +109,17 @@
 EXCLUDED_RUN_SOURCE_VALUES: frozenset[str] = frozenset(
     {"BENCHMARK_TRIAL", "CREATE_BENCHMARK_TASK", "CUSTOM_WEBHOOK"}
 )
+# The upstream spec owns endpoint behavior and non-product metadata. The docs
+# copy uses the public product name and description that frame the Scalar
+# reference alongside the Factory and cloud-agent documentation.
+DOCS_INFO_OVERRIDES: dict[str, str] = {
+    "title": "Warp Platform API",
+    "description": (
+        "API for creating, managing, and querying factory and cloud agent runs.\n\n"
+        "These endpoints allow users to send work to factories, start standalone agents, "
+        "list runs, and retrieve detailed run information.\n"
+    ),
+}
 
 # Default checkout layout: docs/ and warp-server/ as siblings.
 DEFAULT_SOURCE = Path("../warp-server/public_api/openapi.yaml")
@@ -411,6 +422,8 @@ def transform(source: dict[str, Any]) -> dict[str, Any]:
     for top_key in ("openapi", "info", "servers"):
         if top_key in source:
             out[top_key] = source[top_key]
+    if isinstance(out.get("info"), dict):
+        out["info"] = {**out["info"], **DOCS_INFO_OVERRIDES}
 
     src_tags = source.get("tags") or []
     out_tags = [
@@ -743,6 +756,8 @@ def _self_test() -> int:
     assert tag_names == ["agent"], f"unexpected tags: {tag_names}"
 
     assert out["components"].get("securitySchemes"), "securitySchemes should be preserved"
+    assert out["info"]["title"] == "Warp Platform API"
+    assert out["info"]["description"] == DOCS_INFO_OVERRIDES["description"]
 
     ref_errors = _validate_output(out)
     assert not ref_errors, f"unexpected unresolved refs: {ref_errors}"

.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.