Merge origin/main into docs/self-hosting-private-registry

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: warp-agent-staging[bot]

.agents/references/terminology.md

@@ -259,7 +259,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;
@@ -273,9 +272,10 @@ 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.
 
-- **Artifacts** — Files 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. Retrieved with `oz artifact` (see the [Artifacts CLI reference](/reference/cli/artifacts/)) and one of the three data categories in [self-hosted agent data storage](/platform/data-storage/).
+- **Artifacts** — Files 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. Retrieved with `oz artifact` (see the [Artifacts CLI reference](/agents/cli/oz-cli/artifacts/)) and one of the three data categories in [self-hosted agent data storage](/platform/data-storage/).
   *Usage note:* Capitalize as **Artifacts** when referring to the named category (a CLI reference page, an Admin Panel storage category); lowercase "artifacts" as the generic noun for the files themselves.
 
 - **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).
@@ -297,7 +297,7 @@ Not every "Oz" in the docs is stale. These are deliberate and correct until
 - **Run** — The tracked unit of work for a run, including status and outputs.
   *Usage note:* Use when describing observability, history, and auditability.
 
-- **SDK** — Official client libraries for the Agent API (for example, TypeScript SDK, Python SDK).
+- **SDK** — Official client libraries for the Warp Platform API (for example, TypeScript SDK, Python SDK).
   *Usage note:* Spell out the language on first mention.
 
 - **Trigger** — The event that starts a run (Slack mention, schedule, CI event, API call).
@@ -306,7 +306,7 @@ Not every "Oz" in the docs is stale. These are deliberate and correct until
 
 - **Warp CLI** — Ambiguous since the Warp Agent CLI launched; avoid the bare term. Use "Oz CLI" for the `oz` binary that runs and manages cloud agents (formerly called `warp-cli`), or "Warp Agent CLI" for the `warp` binary that runs the Warp Agent in any terminal.
 
-- **Automation Platform** — Warp's cloud agent platform, covering environments, integrations, orchestration, self-hosting, and the Agent API/SDK. Renamed from "Oz" on 2026-08-18.
+- **Automation Platform** — Warp's cloud agent platform, covering environments, integrations, orchestration, self-hosting, and the Warp Platform API and SDKs. Renamed from "Oz" on 2026-08-18.
   *Usage note:* See "Automation Platform terminology" above for the full entry and the article rule. Always write it as `{VARS.WARP_AUTOMATION_PLATFORM}` / `{{WARP_AUTOMATION_PLATFORM}}`, never as a literal string, so a future rename stays a one-line change.
 
 - **Direct backend** — The self-hosted worker backend that runs cloud agent tasks directly on the worker host, without Docker or Kubernetes. One of three self-hosting backends alongside the Docker and Kubernetes backends.
@@ -375,7 +375,7 @@ Docs match the screen; the fix belongs in the app.
   *Usage note:* Lowercase common noun. Distinct from the **Automation Platform**, the product; and from a **trigger**, the event that fires an automation.
 
 - **runner** — A factory resource, defined by a `runners/<name>.yaml` file, that defines the compute a run executes on: operating system, architecture, sandbox image, and instance shape. Agents and automations select a runner by name, or inherit the factory's default.
-  *Usage note:* Lowercase common noun. Scoped to a factory's definition; distinct from the general [cloud agent runner](/platform/runners/) reference, which covers the same concept for standalone cloud agents outside a factory.
+  *Usage note:* Lowercase common noun. Scoped to a factory's definition; distinct from the general [cloud agent runner](/factories/runners/) reference, which covers the same concept for standalone cloud agents outside a factory.
 
 - **Scorer** — A configured LLM judge, scoped per factory to chosen agents and sampled at a set rate, that classifies completed runs against criteria you write, such as "did the agent run the tests before opening a PR?" A Scorer assigns a label (a classification with a score), not a freeform numeric grade. Feeds the **Dashboard** page's Scorer cards, benchmarks, and Self-improvement.
   *Usage note:* Capitalize "Scorer"/"Scorers" when referring to the feature or a configured instance ("create a Scorer," "Scorer cards"); lowercase only for a generic instance count or file listing ("two scorers," alongside "skills" in an example tree). Say "classify," never "grade" — the docs draw this distinction deliberately. The unit a Scorer evaluates is a **run** (a single agent execution), not a "conversation" or "completed work." `measure-and-improve/scorers.mdx` is the canonical page for what a Scorer is and how to configure one; other pages link there rather than repeating the definition.

.agents/skills/afdocs-audit/references/known-exceptions.md

@@ -28,7 +28,7 @@ This file lists checks from the afdocs-audit skill that may flag as warnings or
 - `/platform/triggers/scheduled-agents-quickstart/` — step headings
 - `/platform/integrations/github-actions/` — numbered use case headings
 - `/support-and-community/troubleshooting-and-support/troubleshooting-login-issues/` — URLs with special chars
-- `/reference/cli/quickstart/` — optional step headings
+- `/agents/cli/oz-cli/quickstart/` — optional step headings
 - `/guides/getting-started/welcome-to-warp/` — numbered section headings
 - `/terminal/editor/vim/` — "See Vim docs:" link text
 - `/guides/getting-started/10-coding-features-you-should-know/` — numbered feature headings

.agents/skills/docs-seo-audit/SKILL.md

@@ -154,7 +154,7 @@ Some page titles are intentionally short or specific and must **not** be changed
 - **`src/content/docs/terminal/windows/split-panes.mdx`** (`Split panes`) — Same rationale: the section header disambiguates the terminal context. The `title_too_short` warning is intentionally suppressed. Do not rename to "Terminal split panes".
 - **`src/content/docs/terminal/windows/tab-configs.mdx`** (`Tab Configs`) — Same rationale: the section header disambiguates the terminal context. Additionally, "Tab Configs" is a proper feature name and should not be prefixed. The `title_too_short` warning is intentionally suppressed. Do not rename to "Terminal Tab Configs".
 - **`src/content/docs/terminal/sessions/index.mdx`** (`Sessions`) — The sidebar section header ("Sessions") already provides terminal context. The `title_too_short` warning is intentionally suppressed. Do not rename to "Terminal sessions".
-- **`src/content/docs/reference/cli/artifacts.mdx`** (`Artifacts`) — The Reference > CLI section provides context, and "Artifacts" matches the `oz artifact` resource that the page documents. The `title_too_short` warning is intentionally suppressed.
+- **`src/content/docs/agents/cli/oz-cli/artifacts.mdx`** (`Artifacts`) — The Agents > CLI section provides context, and "Artifacts" matches the `oz artifact` resource that the page documents. The `title_too_short` warning is intentionally suppressed.
 
 When the audit flags these pages for `title_too_short`, exclude them from your fix list and include a note in your report explaining they are intentional exceptions.
 

.agents/skills/draft_guide/SKILL.md

@@ -76,7 +76,7 @@ When drafting a guide, check for relevant SEO and AEO data:
 
 When a guide includes Oz CLI commands or GitHub Actions workflows using `warpdotdev/oz-agent-action`:
 
-- **Verify Oz CLI commands against `/reference/cli/`.** Do not infer flag names or argument formats. Use only flags documented in the CLI reference. When in doubt, link to the reference page instead of showing a command.
+- **Verify Oz CLI commands against `/agents/cli/oz-cli/`.** Do not infer flag names or argument formats. Use only flags documented in the CLI reference. When in doubt, link to the reference page instead of showing a command.
 - **`oz-agent-action` input format**: `warp_api_key` is a `with:` input to the action, not an `env:` variable. `GITHUB_TOKEN` goes in `env:`. The correct pattern is:
   ```yaml
   - uses: warpdotdev/oz-agent-action@v1
@@ -112,14 +112,14 @@ Before adding any internal documentation link:
 
 - **Verify the target page exists.** Check `src/sidebar.ts` for sidebar entries and the corresponding file under `src/content/docs/` to confirm the page exists. Do NOT generate plausible-looking URLs to pages that don't exist.
 - **If a target page is planned but not yet published**, link to the closest existing page and add a TODO comment with the intended future path: `<!-- TODO: Update to [future-path] once [page name] is live -->`
-- **For third-party CLI agent pages**, the current paths are under `src/content/docs/agent-platform/cli-agents/` (e.g., `claude-code.mdx`, `codex.mdx`, `opencode.mdx`).
+- **For third-party CLI agent pages**, the current paths are under `src/content/docs/agents/cli-agents/` (e.g., `claude-code.mdx`, `codex.mdx`, `opencode.mdx`).
 
 ## Cross-linking
 
 Every guide should link to:
 - At least one other guide in the Guides section
-- Relevant feature documentation in the main docs (`src/content/docs/` or `src/content/docs/agent-platform/`)
-- If applicable, pages in the Third-Party CLI Agents section (`src/content/docs/agent-platform/cli-agents/`)
+- Relevant feature documentation in the main docs (`src/content/docs/` or `src/content/docs/agents/`)
+- If applicable, pages in the Third-Party CLI Agents section (`src/content/docs/agents/cli-agents/`)
 
 ## Pre-handoff self-review
 

.agents/skills/draft_procedural/SKILL.md

@@ -62,5 +62,5 @@ All headings (H1–H4) must use **sentence case**: capitalize only the first wor
 ## Existing examples
 
 Read 2-3 of these strong examples to match the existing pattern:
-- `src/content/docs/reference/cli/api-keys.md`
-- `src/content/docs/platform/integrations/slack.md`
+- `src/content/docs/agents/cli/oz-cli/api-keys.mdx`
+- `src/content/docs/platform/integrations/slack.mdx`

.agents/skills/draft_reference/SKILL.md

@@ -45,5 +45,5 @@ All headings (H1–H4) must use **sentence case**: capitalize only the first wor
 ## Existing examples
 
 Read 2-3 of these strong examples to match the existing pattern:
-- `reference/cli/index.mdx`
-- `reference/api-and-sdk/index.mdx`
+- `agents/cli/oz-cli/index.mdx`
+- `factories/api-and-sdk/index.mdx`

.agents/skills/draft_troubleshooting/SKILL.md

@@ -44,5 +44,5 @@ All headings (H1–H4) must use **sentence case**: capitalize only the first wor
 ## Existing examples
 
 Read 2-3 of these strong examples to match the existing pattern:
-- `src/content/docs/support-and-community/troubleshooting-and-support/known-issues.md`
-- `src/content/docs/reference/cli/troubleshooting.md`
+- `src/content/docs/support-and-community/troubleshooting-and-support/known-issues.mdx`
+- `src/content/docs/agents/cli/oz-cli/troubleshooting.mdx`