Elevate Oz cloud agents & orchestration to a top-level section + fix top-nav overflow

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

@@ -25,8 +25,8 @@ This file lists checks from the afdocs-audit skill that may flag as warnings or
 **Expected status**: warn (several pages, ~2% average difference)
 **Reason**: False positive. The "missing" segments are numbered heading text like "2. Tabbed File Viewer" where Turndown correctly escapes the period (`### 2\. Tabbed File Viewer`) to prevent markdown parsers from interpreting it as a list item. The content IS present in the markdown — the AFDocs checker's text comparison doesn't account for markdown escaping.
 **Affected pages** (as of 2026-05-05):
-- `/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/` — step headings
-- `/agent-platform/cloud-agents/integrations/github-actions/` — numbered use case headings
+- `/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
 - `/guides/getting-started/welcome-to-warp/` — numbered section headings

.agents/skills/answer_question/SKILL.md

@@ -71,7 +71,7 @@ Key rules:
 - **`src/content/docs/` is the homepage space** — the `warp/` prefix is NOT included in URLs. Example: `src/content/docs/terminal/blocks/block-basics.mdx` → `https://docs.warp.dev/terminal/blocks/block-basics`
 - All other spaces include the space name in the URL. Example: `src/content/docs/agent-platform/capabilities/skills.mdx` → `https://docs.warp.dev/agent-platform/capabilities/skills`
 - Strip the `.mdx` extension.
-- `index.mdx` resolves to the parent directory path. Example: `src/content/docs/agent-platform/cloud-agents/integrations/index.mdx` → `https://docs.warp.dev/agent-platform/cloud-agents/integrations`
+- `index.mdx` resolves to the parent directory path. Example: `src/content/docs/platform/integrations/index.mdx` → `https://docs.warp.dev/platform/integrations`
 
 ### 5. Output format
 

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

@@ -183,15 +183,15 @@ Astro Starlight uses `title` for the `<title>` tag and `sidebar.label` for the s
 
 Example:
 - `agent-platform/capabilities/index.mdx`: `title: 'Capabilities overview'` + `sidebar.label: 'Overview'`
-- `agent-platform/cloud-agents/integrations/index.mdx`: `title: 'Integrations overview'` + `sidebar.label: 'Overview'`
+- `platform/integrations/index.mdx`: `title: 'Integrations overview'` + `sidebar.label: 'Overview'`
 
 When using this approach, also update the H1 in the markdown file to match the new `title`.
 
 #### Alternative: rename the sidebar config label
 
 If the short label is not intentional, rename the `label` in `src/sidebar.ts` to be unique and descriptive. Use sentence case and correct terminology per `AGENTS.md` (e.g., capitalize proper feature names like "Agent Mode", "Warp Drive", "Codebase Context" — but not generic terms like "overview", "quickstart", or "agents"). Example:
-- Before: `{ slug: 'agent-platform/local-agents', label: 'Overview' }` + `{ slug: 'agent-platform/cloud-agents', label: 'Overview' }`
-- After: `{ slug: 'agent-platform/local-agents', label: 'Local agents overview' }` + `{ slug: 'agent-platform/cloud-agents', label: 'Cloud agents overview' }`
+- Before: `{ slug: 'agent-platform/local-agents', label: 'Overview' }` + `{ slug: 'platform', label: 'Overview' }`
+- After: `{ slug: 'agent-platform/local-agents', label: 'Local agents overview' }` + `{ slug: 'platform', label: 'Cloud agents overview' }`
 
 When changing a sidebar config label, also update the H1 in the markdown file for consistency.
 

.agents/skills/docs-seo-audit/scripts/seo_audit.py

@@ -36,7 +36,7 @@
 # Astro Starlight content directory
 # ---------------------------------------------------------------------------
 # All content lives under src/content/docs/. URL paths map directly to this
-# directory (e.g. /agent-platform/cloud-agents → src/content/docs/agent-platform/cloud-agents).
+# directory (e.g. /platform → src/content/docs/platform).
 CONTENT_DIR = "src/content/docs"
 
 # ---------------------------------------------------------------------------

.agents/skills/draft_conceptual/SKILL.md

@@ -34,5 +34,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/agent-platform/cloud-agents/deployment-patterns.md`
-- `src/content/docs/agent-platform/cloud-agents/overview.md`
+- `src/content/docs/platform/deployment-patterns.md`
+- `src/content/docs/platform/index.mdx`

.agents/skills/draft_feature_doc/SKILL.md

@@ -35,4 +35,4 @@ All headings (H1–H4) must use **sentence case**: capitalize only the first wor
 
 Read 2-3 of these strong examples to match the existing pattern:
 - `src/content/docs/agent-platform/capabilities/skills.md`
-- `src/content/docs/agent-platform/cloud-agents/environments.md`
+- `src/content/docs/platform/environments.md`

.agents/skills/draft_procedural/SKILL.md

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

.agents/skills/draft_quickstart/SKILL.md

@@ -36,5 +36,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/agent-platform/cloud-agents/quickstart.md`
+- `src/content/docs/platform/quickstart.md`
 - `src/content/docs/getting-started/quickstart/installation-and-setup.md`

.agents/skills/missing_docs/references/feature_surface_map.md

@@ -13,8 +13,8 @@ Lines starting with `#` are comments. Blank lines are ignored.
 ## Feature flags -> doc pages
 
 AgentMode -> src/content/docs/agent-platform/local-agents/overview.mdx
-AgentManagementView -> src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.md
-AgentManagementDetailsView -> src/content/docs/agent-platform/cloud-agents/managing-cloud-agents.md
+AgentManagementView -> src/content/docs/platform/managing-cloud-agents.md
+AgentManagementDetailsView -> src/content/docs/platform/managing-cloud-agents.md
 AgentModeComputerUse -> src/content/docs/agent-platform/capabilities/computer-use.mdx
 AgentModeWorkflows -> src/content/docs/knowledge-and-collaboration/warp-drive/workflows.md
 AgentOnboarding -> src/content/docs/agent-platform/getting-started/agents-in-warp.md
@@ -36,11 +36,11 @@ CodebaseContext -> src/content/docs/agent-platform/capabilities/codebase-context
 CrossRepoContext -> src/content/docs/agent-platform/capabilities/codebase-context.mdx
 FullSourceCodeEmbedding -> src/content/docs/agent-platform/capabilities/codebase-context.mdx
 SearchCodebaseUI -> src/content/docs/agent-platform/capabilities/codebase-context.mdx
-CloudEnvironments -> src/content/docs/agent-platform/cloud-agents/environments.md
-CloudMode -> src/content/docs/agent-platform/cloud-agents/overview.md
-AmbientAgentsCommandLine -> src/content/docs/agent-platform/cloud-agents/overview.md
-ScheduledAmbientAgents -> src/content/docs/agent-platform/cloud-agents/triggers/scheduled-agents.md
-WarpManagedSecrets -> src/content/docs/agent-platform/cloud-agents/secrets.md
+CloudEnvironments -> src/content/docs/platform/environments.md
+CloudMode -> src/content/docs/platform/index.mdx
+AmbientAgentsCommandLine -> src/content/docs/platform/index.mdx
+ScheduledAmbientAgents -> src/content/docs/platform/triggers/scheduled-agents.md
+WarpManagedSecrets -> src/content/docs/platform/secrets.md
 IntegrationCommand -> src/content/docs/reference/cli/integration-setup.md
 ConversationManagement -> src/content/docs/agent-platform/local-agents/cloud-conversations.mdx
 ForkConversationFromBlock -> src/content/docs/agent-platform/local-agents/interacting-with-agents/conversation-forking.mdx
@@ -112,7 +112,7 @@ GitOperationsInCodeReview -> src/content/docs/code/code-review.md
 AgentView -> src/content/docs/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes.mdx
 AgentViewBlockContext -> src/content/docs/agent-platform/local-agents/agent-context/blocks-as-context.mdx
 CloudConversations -> src/content/docs/agent-platform/local-agents/cloud-conversations.mdx
-CloudModeFromLocalSession -> src/content/docs/agent-platform/cloud-agents/overview.md
+CloudModeFromLocalSession -> src/content/docs/platform/index.mdx
 TeamApiKeys -> src/content/docs/reference/cli/api-keys.md
 PRCommentsSlashCommand -> src/content/docs/agent-platform/capabilities/slash-commands.mdx
 PRCommentsV2 -> src/content/docs/agent-platform/local-agents/interacting-with-agents/index.mdx

.agents/skills/sync-error-docs/references/error-page-template.md

@@ -61,7 +61,7 @@ This error is returned when:
 ## Related
 
 * [Agent API & SDK](https://docs.warp.dev/reference/api-and-sdk/agent) — API reference
-* [Cloud Agents Overview](https://docs.warp.dev/agent-platform/cloud-agents/overview) — How cloud agents work
+* [Cloud Agents Overview](https://docs.warp.dev/platform) — How cloud agents work
 ```
 
 ## Placeholder reference

AGENTS.md

@@ -400,7 +400,7 @@ These rules apply regardless of content type:
 - Do NOT include step-by-step procedures — link to a procedural or quickstart page instead
 - Show real-world scenarios, not just abstract descriptions
 
-**Existing examples**: `agent-platform/cloud-agents/deployment-patterns.mdx`, `agent-platform/cloud-agents/overview.mdx`
+**Existing examples**: `platform/deployment-patterns.mdx`, `platform/index.mdx`
 
 **Template**: `.warp/templates/conceptual.md`
 
@@ -428,7 +428,7 @@ These rules apply regardless of content type:
 - Test all instructions for accuracy.
 - Provide troubleshooting for common failure points.
 
-**Existing examples**: `reference/cli/api-keys.mdx`, `agent-platform/cloud-agents/integrations/slack.mdx`
+**Existing examples**: `reference/cli/api-keys.mdx`, `platform/integrations/slack.mdx`
 
 **Template**: `.warp/templates/procedural.md`
 
@@ -453,7 +453,7 @@ These rules apply regardless of content type:
 - Keep steps focused on the critical path — defer edge cases and advanced options to other pages.
 - All procedural rules apply (focused steps, motivate steps, expected outcomes).
 
-**Existing examples**: `agent-platform/cloud-agents/quickstart.mdx`, `getting-started/quickstart/installation-and-setup.mdx`
+**Existing examples**: `platform/quickstart.mdx`, `getting-started/quickstart/installation-and-setup.mdx`
 
 **Template**: `.warp/templates/quickstart.md`
 
@@ -569,7 +569,7 @@ This is the most common page type in Warp's docs (~75+ pages). A feature documen
 - Apply the **procedural** rules to the step-by-step sections (one action per step, motivate steps, expected outcomes).
 - Keep the conceptual and procedural sections clearly separated with distinct headers.
 
-**Existing examples**: `agent-platform/capabilities/skills.mdx`, `agent-platform/cloud-agents/environments.mdx`
+**Existing examples**: `agent-platform/capabilities/skills.mdx`, `platform/environments.mdx`
 
 **Template**: `.warp/templates/feature-doc.md`
 

astro.config.mjs

@@ -63,7 +63,7 @@ export default defineConfig({
 					wrap: true,
 				},
 				// Map languages Shiki doesn't bundle to a safe fallback. PromQL
-				// blocks live in agent-platform/cloud-agents/self-hosting/monitoring.mdx;
+				// blocks live in platform/self-hosting/monitoring.mdx;
 				// without this alias every build emits noisy "language could not be
 				// found" warnings while still falling back to plaintext.
 				shiki: {
@@ -158,7 +158,8 @@ export default defineConfig({
 						'Documentation for Warp, the agentic development environment, and Oz, Warp\'s programmable agent for running and coordinating agents at scale.',
 					customSets: [
 						{ label: 'Terminal', description: 'Warp Terminal features and configuration.', paths: ['terminal/**'] },
-						{ label: 'Agent Platform', description: 'Warp\'s Agent Platform: capabilities, local agents, CLI agents, cloud agents.', paths: ['agent-platform/**'] },
+						{ label: 'Agent Platform', description: 'Warp\'s Agent Platform: capabilities, local agents, and CLI agents.', paths: ['agent-platform/**'] },
+						{ label: 'Oz Platform', description: 'Warp\'s Oz platform: cloud agents, orchestration, triggers, integrations, environments, harnesses, and self-hosting.', paths: ['platform/**'] },
 						{ label: 'Code', description: 'Code editor, code review, and Git worktrees.', paths: ['code/**'] },
 						{ 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/**'] },

scripts/seo-audit.mjs

@@ -11,13 +11,13 @@
  *   node scripts/seo-audit.mjs --dist ./dist
  *
  *   # Audit live URLs (handy for spot-checking the legacy GitBook output)
- *   node scripts/seo-audit.mjs --base https://docs.warp.dev /agent-platform/cloud-agents/oz-web-app /changelog
+ *   node scripts/seo-audit.mjs --base https://docs.warp.dev /platform/oz-web-app /changelog
  *
  *   # Diff between two sources, e.g. legacy vs. our preview deploy
  *   node scripts/seo-audit.mjs \\
  *     --base https://docs.warp.dev \\
  *     --compare https://docs-preview.warp.dev \\
- *     /agent-platform/cloud-agents/oz-web-app
+ *     /platform/oz-web-app
  *
  * The script is intentionally dependency-free (uses regex over the raw HTML
  * head) so it runs in CI without installing extra packages.
@@ -29,7 +29,7 @@ const DEFAULT_PATHS = [
 	'/',
 	'/quickstart/',
 	'/agent-platform/',
-	'/agent-platform/cloud-agents/oz-web-app/',
+	'/platform/oz-web-app/',
 	'/agent-platform/capabilities/skills/',
 	'/reference/cli/',
 	'/reference/api-and-sdk/',

src/components/WarpTopicNav.astro

@@ -40,6 +40,7 @@ const CUSTOM_TOPIC_ICONS: Record<string, true> = {
 	Agents: true,
 	API: true,
 	Enterprise: true,
+	Oz: true,
 };
 ---
 
@@ -95,6 +96,19 @@ const CUSTOM_TOPIC_ICONS: Record<string, true> = {
 										<line x1="15" y1="14" x2="15" y2="14.01" />
 										<path d="M10 22v-4h4v4" />
 									</svg>
+								) : topic.label === 'Oz' ? (
+									/* Cloud icon — Feather-style cloud outline, stroke weight
+									   matched to the other topic icons. */
+									<svg
+										viewBox="0 0 24 24"
+										fill="none"
+										stroke="currentColor"
+										stroke-width="2"
+										stroke-linecap="round"
+										stroke-linejoin="round"
+									>
+										<path d="M18 10h-1.26A8 8 0 1 0 9 20h9a5 5 0 0 0 0-10z" />
+									</svg>
 								) : (
 									/* Robot icon — stroke-based outline matching the visual
 									   weight of Starlight's other topic icons (laptop, book,
@@ -149,10 +163,12 @@ const CUSTOM_TOPIC_ICONS: Record<string, true> = {
 		margin: 0;
 		padding: 0;
 		display: flex;
+		flex-wrap: wrap;
 		align-items: stretch;
-		gap: 1.25rem;
+		/* Row gap applies only once the nav wraps to a second row on crowded
+		   mid-width viewports; column gap keeps the single-row spacing. */
+		gap: 0.25rem 1.25rem;
 		min-width: 0;
-		overflow: hidden;
 	}
 
 	li {
@@ -269,13 +285,13 @@ const CUSTOM_TOPIC_ICONS: Record<string, true> = {
 		display: inline-block;
 	}
 
-	/* Mid-width fallback. Below ~80rem (~1280px) the 8 topic items + logo +
+	/* Mid-width fallback. Below ~80rem (~1280px) the topic items + logo +
 	   right-group start to crowd. Drop the per-item icons first so the labels
 	   keep room. The mobile drawer (rendered separately) takes over below
 	   50rem where this nav is hidden entirely. */
 	@media (max-width: 80rem) {
 		ul {
-			gap: 1rem;
+			gap: 0.25rem 1rem;
 		}
 		.warp-topic-nav__icon {
 			display: none;

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

@@ -85,7 +85,7 @@ 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 [Oz API](/reference/api-and-sdk/), in addition to managing them in the Oz web app.
-* **Self-hosting support** - Run Agent Memory on a [self-hosted Oz](/agent-platform/cloud-agents/self-hosting/) instance to meet security, privacy, and compliance requirements.
+* **Self-hosting support** - Run Agent Memory on a [self-hosted Oz](/platform/self-hosting/) instance to meet security, privacy, and compliance requirements.
 
 ## Join the waitlist
 
@@ -97,4 +97,4 @@ Agent Memory is rolling out to design partner teams during research preview. [Jo
 * [Rules](/agent-platform/capabilities/rules/) - Define global and project-level guidelines that shape agent behavior.
 * [Skills](/agent-platform/capabilities/skills/) - Reusable, scoped instructions that teach agents how to perform specific tasks.
 * [Agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Control what permissions and autonomy agents have.
-* [Cloud agents overview](/agent-platform/cloud-agents/overview/) - Run background agents with team-wide observability.
+* [Cloud agents overview](/platform/) - Run background agents with team-wide observability.

src/content/docs/agent-platform/capabilities/agent-notifications.mdx

@@ -101,7 +101,7 @@ If auto-install doesn't work or you're running an agent over SSH, Warp displays
 
 ## Notifications in orchestrated runs
 
-In a [multi-agent orchestration](/agent-platform/cloud-agents/orchestration/), the parent agent and each child agent are separate conversations. Today, in-app notifications fire on the parent's conversation only: child agent conversations are excluded from the toast stream and the notification mailbox so the mailbox doesn't get cluttered with per-child status churn.
+In a [multi-agent orchestration](/platform/orchestration/), the parent agent and each child agent are separate conversations. Today, in-app notifications fire on the parent's conversation only: child agent conversations are excluded from the toast stream and the notification mailbox so the mailbox doesn't get cluttered with per-child status churn.
 
 That means:
 
@@ -112,8 +112,8 @@ That means:
 ## Related pages
 
 * [Desktop Notifications](/terminal/more-features/notifications/) - configure system-level notification permissions and troubleshoot delivery
-* [Managing Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - monitor all agent conversations, filter by status, and inspect sessions
-* [Multi-agent orchestration](/agent-platform/cloud-agents/orchestration/) - parent/child model, run state transitions, and the orchestration pill bar
+* [Managing Agents](/platform/managing-cloud-agents/) - monitor all agent conversations, filter by status, and inspect sessions
+* [Multi-agent orchestration](/platform/orchestration/) - parent/child model, run state transitions, and the orchestration pill bar
 * [Third-party CLI agents](/agent-platform/cli-agents/overview/) - overview of supported CLI agents and Warp features
 * [Claude Code](/agent-platform/cli-agents/claude-code/) - setup and notification plugin installation
 * [Codex](/agent-platform/cli-agents/codex/) - setup and notification configuration

src/content/docs/agent-platform/capabilities/codebase-context.mdx

@@ -35,7 +35,7 @@ git clone https://github.com/vercel/next.js.git && cd next.js
 When you open a directory in Warp, we check if it is part of a Git repository. If it is, Warp begins indexing the source code to provide rich context for Agents. Warp also detects [Git worktree](/code/git-worktrees/) checkouts — each worktree is indexed as its own repository, so Agents always have accurate context for the branch you're working on.
 
 :::note
-Code indexed with Codebase Context is never stored on our servers. Codebase Context works with both local agent sessions and [cloud agent runs](/agent-platform/cloud-agents/overview/). Without Codebase Context enabled, agents will still be able use terminal commands (i.e. `grep`, `sed`) to navigate your code.
+Code indexed with Codebase Context is never stored on our servers. Codebase Context works with both local agent sessions and [cloud agent runs](/platform/). Without Codebase Context enabled, agents will still be able use terminal commands (i.e. `grep`, `sed`) to navigate your code.
 :::
 
 :::note