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,6 @@ 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
 ```
 
 ## 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

@@ -70,7 +70,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: {
@@ -165,7 +165,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,
@@ -135,12 +149,13 @@ const CUSTOM_TOPIC_ICONS: Record<string, true> = {
 <style>
 	.warp-topic-nav {
 		/* Sits between SiteTitle and the right control group inside `.header`.
-		   The header itself is `display: flex; align-items: center;` — this
-		   nav uses `align-self: stretch` so its links can pin a 2px accent
-		   underline to the header's bottom edge. */
+		   `align-self: stretch` keeps the nav at full header height so its
+		   row(s) of tabs center vertically; `align-items: center` centers the
+		   tab list within that height — important once the list wraps to a
+		   second row on crowded widths. */
 		align-self: stretch;
 		display: flex;
-		align-items: stretch;
+		align-items: center;
 		min-width: 0;
 	}
 
@@ -149,37 +164,37 @@ const CUSTOM_TOPIC_ICONS: Record<string, true> = {
 		margin: 0;
 		padding: 0;
 		display: flex;
-		align-items: stretch;
-		gap: 1.25rem;
+		flex-wrap: wrap;
+		align-items: center;
+		/* 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 {
 		display: flex;
-		align-items: stretch;
+		align-items: center;
 	}
 
 	a {
-		/* Stretches to the full header height so the bottom-anchored `::after`
-		   indicator sits flush with the header hairline (Scalar pattern) —
-		   not under the link's text box. `align-self: stretch` inherits the
-		   parent <li>'s height (which inherits from `<ul>` → nav → header). */
+		/* The link hugs its own content (icon + label) plus a little vertical
+		   padding, so the active-state `::after` underline sits just under the
+		   tab in both single-row and wrapped (two-row) layouts. Vertical
+		   centering of the row(s) is handled by the parent nav/ul rather than
+		   by stretching each link to the full header height. */
 		position: relative;
-		align-self: stretch;
 		display: flex;
 		align-items: center;
 		gap: 0.5rem;
-		padding: 0 0.25rem;
+		padding: 0.4rem 0.25rem;
 		font-size: var(--sl-text-sm);
 		font-weight: 500;
 		/* `1.25` is just enough to clear Inter's natural ascent + descent
 		   (~1.21em) so descenders in `Changelog` (`g`) and `Reference`
 		   (`f`) aren't clipped, while keeping the line-box close to the
-		   visible text. The link's outer height is set by `align-self:
-		   stretch` on the parent, so this only affects internal text
-		   layout (and the icon's optical centering, see
-		   `.warp-topic-nav__icon` below). */
+		   visible text — which keeps the underline tight to the tab and the
+		   icon optically centered (see `.warp-topic-nav__icon` below). */
 		line-height: 1.25;
 		/* Idle color uses `gray-3` so the active link's full-emphasis white
 		   text reads as clearly distinct (and not just "white-on-slightly-
@@ -213,23 +228,17 @@ const CUSTOM_TOPIC_ICONS: Record<string, true> = {
 		font-weight: 600;
 	}
 
-	/* 2px accent underline that REPLACES the header's 1px bottom hairline
-	   under the active topic (Scalar pattern). The outer Starlight
-	   `<header class="header">` owns the hairline
-	   (`border-bottom: 1px solid var(--sl-color-hairline-shade)`) and has
-	   `padding-block: var(--sl-nav-pad-y)` with `box-sizing: border-box`, so
-	   the link's bottom edge sits `--sl-nav-pad-y` above the hairline rather
-	   than directly on it. We anchor the indicator at the hairline by
-	   dropping it through the bottom padding (`-var(--sl-nav-pad-y)`) and the
-	   1px border (`-1px`); `height: 2px` then paints across both, leaving the
-	   blue accent as the only line at that position under the active tab.
-	   The remainder of the header keeps its hairline. */
+	/* 2px accent underline under the active tab, anchored to the link's own
+	   bottom edge so it hugs the tab. It previously dropped down to the
+	   header's bottom hairline (Scalar pattern), but once the nav can wrap to
+	   a second row that pushed the line into the row below — `bottom: 0` keeps
+	   it attached to the active tab in every layout. */
 	a[aria-current='page']::after {
 		content: '';
 		position: absolute;
 		left: 0;
 		right: 0;
-		bottom: calc(-1 * var(--sl-nav-pad-y) - 1px);
+		bottom: 0;
 		height: 2px;
 		background: var(--sl-color-text-accent);
 	}
@@ -269,13 +278,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;