Elevate Oz cloud agents & orchestration to a top-level section + fix top-nav overflow by rachaelrenk · Pull Request #262 · warpdotdev/docs

rachaelrenk · 2026-06-26T21:43:48Z

Summary

Elevates the Oz Cloud Agents & Orchestration subsection from the Agents tab's sidebar into its own top-level Oz section in the horizontal header nav, positioned between Agents and Reference. Also reorganizes the section's sidebar into collapsible groups, fixes the header topic-nav to wrap on narrow viewports, and adds redirects (verified live) so every old URL keeps working.

Content move

Moved src/content/docs/agent-platform/cloud-agents/* → src/content/docs/platform/* (49 files, via git mv).
overview.mdx → platform/index.mdx (landing at /platform/).
platform.mdx ("Oz Platform overview") → platform/overview.mdx (/platform/overview/).
Directory is named platform/ pre-emptively for the upcoming product rename; the nav label is Oz for now.

Navigation

New top-level Oz topic in src/sidebar.ts (link: '/platform/') between Agents and Reference. Memory stays under Agents.
The section's items are now organized into collapsible groups under the Cloud agents overview landing instead of a flat first-level list: Getting started, Triggers, Integrations, Managing agents, Orchestration, Handoff, Harnesses, Extending agents, Deployment & hosting, Access & support.
Added a cloud icon for the Oz tab in WarpTopicNav.astro (cloud-download mobile-drawer fallback).

Top-nav overflow fix

The header topic-nav now wraps to a second row instead of clipping when the window is narrow (removed overflow: hidden, added flex-wrap: wrap); --sl-nav-height grows in the crowded width range so the wrapped row doesn't overlap content.

Crosslinks & config

Rewrote ~700 internal references (/agent-platform/cloud-agents/... → /platform/...) across content + the docs.warp.dev/... absolutes; also updated AGENTS.md, astro.config.mjs, the SEO script, and .agents/skills/**.
Removed two tangential Cloud agents overview links (error-page template + Agent Memory "Related pages"), per review.
Added an Oz Platform llms customSet for platform/** and trimmed the Agent Platform set.

Redirects (every old URL preserved)

Repointed 143 existing destinations to /platform/... and kept the 36 legacy GitBook sources.
Explicit rules for the two special cases: /agent-platform/cloud-agents/overview/ → /platform/ and /agent-platform/cloud-agents/platform/ → /platform/overview/.
Wildcards for everything else: /agent-platform/cloud-agents/:path* and /agent-platform/cloud-agents/:path*/ → /platform/:path*/. The trailing-slash variant was added after live testing showed the non-trailing :path* alone didn't match trailing-slash URLs (our canonical form). An explicit per-page approach was tried first but pushed vercel.json over Vercel's redirect limit and failed the deploy, so the wildcard pair is the fix.

Testing

Redirects — verified live on the preview deploy. Every old /agent-platform/cloud-agents/* URL returns 308 to its /platform/* equivalent, across top-level, nested, and deep paths. Spot-checked examples:

/agent-platform/cloud-agents/overview/ → /platform/
/agent-platform/cloud-agents/platform/ → /platform/overview/
/agent-platform/cloud-agents/viewing-cloud-agent-runs/ → /platform/viewing-cloud-agent-runs/
/agent-platform/cloud-agents/integrations/slack/ → /platform/integrations/slack/
/agent-platform/cloud-agents/self-hosting/quickstart/ → /platform/self-hosting/quickstart/

Other checks:

npm run build ✓ (340 pages) · npm run typecheck (astro check) ✓ (0 errors / 0 warnings)
python3 scripts/check_redirects.py ✓ (only wildcard sources flagged, as expected)
0 residual agent-platform/cloud-agents references in content
Vercel preview deploy is green
eyeball in the preview: the responsive top-nav wrap (resize ~50–90rem) and the active-tab underline placement when wrapped. @rachaelrenk
manually spot check redirects in the preview. @rachaelrenk

Notes

Merged latest main; resolved a conflict in platform/environments.mdx (kept the moved-file asset path + main's updated figcaption).
Caught and fixed a find/replace over-match that had corrupted the cloud-agents-infra.png asset reference; verified platform-credits links were untouched.

Plan: https://staging.warp.dev/drive/notebook/kH9pKwGM438cckB6SCAzyi
Conversation: https://staging.warp.dev/conversation/c5139d33-a19a-40d0-bc5e-56f25c1a051f

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

Move agent-platform/cloud-agents/* to a new top-level platform/ directory and add an 'Oz' top-level nav tab between Agents and Reference. Repoint all crosslinks and vercel.json redirects to /platform/*, add an Oz Platform llms customSet, and fix the header topic-nav to wrap to a second row instead of clipping on narrow viewports (bumping --sl-nav-height in the crowded range so content isn't overlapped). Co-Authored-By: Oz <oz-agent@warp.dev>

vercel · 2026-06-26T21:43:54Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 30, 2026 6:18pm

oz-for-oss · 2026-06-26T21:44:05Z

@rachaelrenk

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR moves the Oz cloud agents docs into a top-level platform/ section, updates sidebar/navigation, redirects, and route references, and adjusts header wrapping behavior. The route move and navigation tree look mechanically consistent, but several updated authoring/audit references now point to platform.md, which does not exist after the landing page moved to platform/index.mdx.

Concerns

Stale platform.md references in drafting guidance and the missing-docs surface map will point contributors or automation at nonexistent files; the audit resolver handles .md/.mdx variants but not directory index pages.

Verdict

Found: 0 critical, 3 important, 0 suggestions

Request changes

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

The meta-file sweep collapsed the old cloud-agents/overview file path to a nonexistent 'platform.md'; point these AGENTS.md, draft_conceptual, and feature_surface_map references at the real landing file 'platform/index.mdx'. Co-Authored-By: Oz <oz-agent@warp.dev>

rachaelrenk · 2026-06-27T00:26:31Z

/oz-review

oz-for-oss · 2026-06-27T00:26:48Z

@rachaelrenk

I'm re-reviewing this pull request in response to a review request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

oz-for-oss

Overview

This PR moves the Oz cloud agents and orchestration documentation into a new top-level platform section, updates sidebar and llms.txt grouping, refreshes internal links and redirects, and adjusts the header topic nav to wrap at crowded widths. I reviewed the attached annotated diff, including the docs migration, navigation/config changes, redirect updates, security-relevant content, and the empty spec context.

Concerns

No blocking concerns found.

Verdict

Found: 0 critical, 0 important, 0 suggestions

Approve

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

hongyi-chen · 2026-06-27T01:20:54Z


 * [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


i assume we don't need to link to the "overview" pages right?

hongyi-chen · 2026-06-27T01:22:18Z

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


similarly, just want to double check if we also need to link an overview page? i assume this is the same as above

hongyi-chen · 2026-06-27T01:27:08Z

    },
    {
      "source": "/agent-platform/agent-mode/ambient-agents-session-sharing",
-      "destination": "/agent-platform/cloud-agents/viewing-cloud-agent-runs/",


we shouldn't just change the redirects from the old links, we should also add brand new redirects from these old destination links

e.g. /agent-platform/cloud-agents/viewing-cloud-agent-runs/ should go to /agent-platform/cloud-agents/viewing-cloud-agent-runs/

ah i see these are added at the end, but i think we should also test them quite thoroughly. i see that it supports path matching via /agent-platform/cloud-agents/:path*, but would also like us to manually test a bit too!

hongyi-chen

could we change these sidebar items such that they're not all first level items? i.e. i think quickstart and others can live under cloud agents overview, and we can create a couple of groupings for these

…m-section # Conflicts: # src/content/docs/platform/environments.mdx

…icit redirects - Regroup the Oz topic into collapsible groups (Getting started, Managing agents, Orchestration kept as a separate sibling, Extending agents, Deployment & hosting, Access & support) instead of a flat first-level list. - Remove tangential 'Cloud agents overview' links from the error-page template and the Agent Memory see-also list. - Add explicit /agent-platform/cloud-agents/<page>/ -> /platform/<page>/ redirects (trailing and non-trailing variants) for all 47 moved pages. Live testing showed the :path* wildcard did not match trailing-slash URLs (the canonical form); explicit rules fix this. Kept both wildcards as fallback. Co-Authored-By: Oz <oz-agent@warp.dev>

vercel · 2026-06-30T00:58:23Z

Deployment failed with the following error:

The `vercel.json` schema validation failed with the following message: `redirects` should NOT have more than 2048 items

Learn More: https://vercel.com/docs/concepts/projects/project-configuration

…h wildcard The 94 explicit per-page redirects pushed vercel.json to 2056 entries and exceeded Vercel's redirect limit, failing the deployment. Revert to the wildcard approach and add a trailing-slash variant (/agent-platform/cloud-agents/:path*/ -> /platform/:path*/) to cover the trailing-slash URLs the non-trailing :path* wildcard was missing. Count back to 1962. Co-Authored-By: Oz <oz-agent@warp.dev>

rachaelrenk · 2026-06-30T15:40:59Z

Thanks @hongyi-chen! Pushed updates addressing all your feedback.

Sidebar grouping — the Oz section is no longer a flat first-level list. Items are now collapsible groups under the Cloud agents overview landing: Getting started · Triggers · Integrations · Managing agents · Orchestration · Handoff · Harnesses · Extending agents · Deployment & hosting · Access & support.

I kept "Orchestration" as its own group rather than nesting it under "Managing agents", since it's a headline concept (happy to nest it if you'd prefer).

"Overview" links — removed the tangential Cloud agents overview links from both the error-page template and the Agent Memory "Related pages" list.

Redirects from old destinations — The agent-platform/cloud-agents/:path* wildcard was already in place, but live testing showed it only matched non-trailing-slash URLs. Trailing-slash URLs (our canonical form) were 404ing. I added a trailing-slash variant to cover them. (I first tried explicit per-page redirects, but that pushed past Vercel's redirect limit and failed the deploy, so the wildcard pair is the fix.)

Verified live on the preview deploy. Old cloud-agents URLs now all 308 to their /platform/… equivalents, e.g.:

…/cloud-agents/viewing-cloud-agent-runs/ → /platform/viewing-cloud-agent-runs/
…/cloud-agents/integrations/slack/ → /platform/integrations/slack/
…/cloud-agents/overview/ → /platform/
…/cloud-agents/platform/ → /platform/overview/

Build + typecheck pass and the Vercel deploy is green. Ready for another look!

Anchor the active-tab accent underline to the link's own bottom edge (bottom: 0) and let tabs hug their content instead of stretching to full header height. Previously the underline was dropped to the header's bottom hairline, which collided with the second row once the nav wrapped. Co-Authored-By: Oz <oz-agent@warp.dev>

hongyi-chen

nice, looks good, ty!

let's proceed with the follow-up now, i.e.agents-platform -> agents

Resolve quickstart.mdx conflict from the cloud-agents -> platform restructure (warpdotdev#262): keep the link-out Next steps (de-duplicated, with the schedule example and Build/Max/Business note) and adopt the new /platform/ link paths. Co-Authored-By: Oz <oz-agent@warp.dev>

Resolve conflicts from main's cloud-agents -> /platform/ restructure (#262) and reconcile independently-added settings docs: - slash-commands.mdx: keep new /environment, /harness, /host, /rename-conversation rows; retarget moved cloud-agents links to /platform/. - all-settings.mdx: keep the corrected [agents.warp_agent.active_ai] home for git_operations_autogen_enabled (verified toml_path in source) and drop main's re-added, incorrect [agents.oz.active_ai] section; retarget handoff/ orchestration links to /platform/. - feature_surface_map.md: take main's /platform/ targets for cloud-agents entries, keep RemoteCodebaseIndexing, and migrate remaining cloud-agents mappings (AgentHarness, OzHandoff, Handoff*, RunAgentsTool, NamedAgents) to /platform/. Audit: map_hygiene 0, unaccounted none, no audits skipped. Build: 340 pages OK. Co-Authored-By: Oz <oz-agent@warp.dev>

cla-bot Bot added the cla-signed label Jun 26, 2026

vercel Bot deployed to Preview June 26, 2026 21:45 View deployment

oz-for-oss Bot reviewed Jun 26, 2026

View reviewed changes

Comment thread .agents/skills/draft_conceptual/SKILL.md Outdated

Comment thread .agents/skills/missing_docs/references/feature_surface_map.md Outdated

Comment thread AGENTS.md Outdated

rachaelrenk self-assigned this Jun 26, 2026

vercel Bot deployed to Preview June 27, 2026 00:21 View deployment

Merge branch 'main' into rrenk/elevate-platform-section

b925cef

vercel Bot deployed to Preview June 27, 2026 00:28 View deployment

oz-for-oss Bot reviewed Jun 27, 2026

View reviewed changes

hongyi-chen approved these changes Jun 27, 2026

View reviewed changes

hongyi-chen requested changes Jun 27, 2026

View reviewed changes

rachaelrenk and others added 2 commits June 29, 2026 18:25

Merge remote-tracking branch 'origin/main' into rrenk/elevate-platfor…

0295923

…m-section # Conflicts: # src/content/docs/platform/environments.mdx

vercel Bot had a problem deploying to Preview June 30, 2026 00:58 Failure

vercel Bot deployed to Preview June 30, 2026 15:03 View deployment

Merge branch 'main' into rrenk/elevate-platform-section

5cc556a

vercel Bot deployed to Preview June 30, 2026 15:39 View deployment

rachaelrenk requested a review from hongyi-chen June 30, 2026 15:41

vercel Bot deployed to Preview June 30, 2026 16:48 View deployment

Merge branch 'main' into rrenk/elevate-platform-section

00e369d

vercel Bot deployed to Preview June 30, 2026 18:18 View deployment

hongyi-chen approved these changes Jun 30, 2026

View reviewed changes

rachaelrenk merged commit 08b53b6 into main Jun 30, 2026
8 checks passed

rachaelrenk deleted the rrenk/elevate-platform-section branch June 30, 2026 19:12

Uh oh!

Conversation

rachaelrenk commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Content move

Navigation

Top-nav overflow fix

Crosslinks & config

Redirects (every old URL preserved)

Testing

Notes

Uh oh!

vercel Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rachaelrenk commented Jun 27, 2026

Uh oh!

oz-for-oss Bot commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

oz-for-oss Bot left a comment

Choose a reason for hiding this comment

Overview

Concerns

Verdict

Uh oh!

hongyi-chen Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

hongyi-chen left a comment

Choose a reason for hiding this comment

Uh oh!

vercel Bot commented Jun 30, 2026

Uh oh!

rachaelrenk commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hongyi-chen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rachaelrenk commented Jun 26, 2026 •

edited

Loading

vercel Bot commented Jun 26, 2026 •

edited

Loading

oz-for-oss Bot commented Jun 26, 2026 •

edited

Loading

oz-for-oss Bot commented Jun 27, 2026 •

edited

Loading

rachaelrenk commented Jun 30, 2026 •

edited

Loading