docs: merge the agent overview pages on the Agents tab - #503
Open
rachaelrenk wants to merge 8 commits into
Open
Conversation
The Agents tab had three top-level pages whose titles all implied "overview of the agent" with nothing in the nav to distinguish them: Agents overview, Agents in Warp, and Warp Agents > Overview. PR #500 gave them distinct jobs but left all three in the sidebar, so the confusion HYC flagged was unchanged from the reader's side. Investigating them surfaced real duplication, not just ambiguous labels: - /agents/ and agents-in-warp shared their opening definition, their first link cluster, and their closing list. - agents-in-warp's Agent autonomy and Agent profiles sections summarized capabilities/agent-profiles-permissions, which covers the same material in more detail and was already linked from them. - local-agents/overview was a two-sentence intro plus a link list that the sidebar already renders. /agents/ is now the single page describing the agent. Routing content stays above the fold so a reader who came for the CLI can leave immediatelyimmediatelyimmediatelyimmediatelyimmediatelyimmediatelytioimmediatelyimmediatelyimmediatelyimmediatelyimmediatelyimmediateThimmediatelyimmediatelyimmediatelyimmediatelyimmediatelyimmediatelytas no other home in the tab. The "Getting started" group is renamed "Agents" and keeps Agent FAQs, which is troubleshooting and billing reference rather than onboarding. The Warp Agents group now starts at Capabilities. Redirects resolve in one hop rather than the two tRedirects resolve in one hop rather than the two tRedirects irectly iRedirects resolve in one hop rather than theenRedirects resolve in one hop rather than the two tRedirects resolve in s/ - 13 legacy /generate sources repointed to the Generate page, wh- 13 legacy /generate sources repointed to thules for the two retired URLs Also fixes a pre-existing stale rule where /agents redirected backwards to /agent-platform/ before bouncing to /agents/. It now resolves directly, which matters more since this change funnels traffic there. Co-Authored-By: Warp Agent <agent@warp.dev>
The Warp Agent CLI overview held procedural content the quickstart needed, so the quickstart linked backwards into it twice mid-install: once from the prerequisites for supported platforms, and once right after the install step for automatic updates. The overview also duplicated the quickstart's login step. Supported platforms, automatic updates, and the sign-out instruction now live in the quickstart, where install and login actually happen. Both backwards links are gone. The overview keeps what is conceptual: what the CLI is, key features, how it relates to the Warp app and Oz, coming from the Warp app, and next steps. It drops from 67 to 45 lines. The overview and quickstart stay separate. AGENTS.md treats quickstart as its own content type with its own template and a ten-minute target. Co-Authored-By: Warp Agent <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
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 Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR merges the overlapping Agents overview pages into /agents/, updates sidebar navigation, moves CLI install/login reference details into the CLI quickstart, and repoints legacy redirects and internal links to the new canonical pages. I did not find broken links, structural issues, security concerns, or spec-drift concerns in the attached diff.
Concerns
- No blocking concerns identified.
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
The Vercel deployment for this PR failed. Vercel caps "Routes created per Deployment" at 2048 and counts every redirect, rewrite, and header in vercel.json, plus routes the Astro Vercel adapter adds on top. main sits at 2036; the four new rules for the two retired URLs pushed this branch to 2040, tipping it over. This is the same ceiling hit in 27380fd. The four new rules are all required. Verified against the live site that a retired path with only a with-slash rule 404s in its no-slash form (/agent-platform/capabilities/web-search returns 404 while the with-slash form redirects), so both forms need an entry. Reclaim the routes elsewhere instead. All six /agent-platform/warp-ai rules already pointed at /agents/, so they collapse into two entries using the ':path(.*)' idiom from 05a0c7a, which captures the remainder of the path including its trailing slash. That covers the bare path, the trailing-slash form, and every descendant, incltrailing-slash form, and every descendant, incltrailing-slash form, aching main. Since this branch also deletes two pages, total routes including adapter output are strictly below main's. Co-Authored-By: Warp Agent <agent@warp.dev>
Addresses HYC's review of the merged page on the live preview. The page led with a generic capability list (write code, debug, run commands) that describes any coding agent, then spent four sections explaining features that have their own canonical pages, and routed readers from two separate places. Reframe around the two jobs the page actually has: give a reader the "aha" for why they'd use the Warp Agent, then route them to the docs that get them started. - Replace "What agents can do" with "What makes the Warp Agent different", covering full terminal use, context that carries across surfaces, interactive versus delegated work with handoff, the approval model, and running many agents at once. - Cut the permissions, managing agents, and context and knowledge sections. Each becomes one differentiator bullet that links to the canonical page instead of re-explaining it here. - Collapse two router sections into one. "Context and knowledge" was a link list competing with "Next steps"; its links now sit inline in the differentiator bullet where they mean somet the differentiator bullet where they mean somet the differentiing the platform as a separate concept further down. - Drop the AI-di- Drop the AI-di- Drop the AI-di- Drop the AI-di- Drop the AI-di- h- Drop the AI-di- Drop the AI-digent FAQs, which sits directly below this page in the same nav group. 112 lines to 62. Co-Authored-By: Warp Agent <agent@warp.dev>
rachaelrenk
commented
Aug 12, 2026
rachaelrenk
commented
Aug 12, 2026
- Use "The Warp Agent" rather than "Warp's coding agent" in the frontmatter description, matching the terminology rule against the ambiguous "Warp's agent" phrasing. Still 137 characters. - Rewrite the intro sentence to drop the awkward "where your code already runs" and the colon that followed it. Co-Authored-By: Warp Agent <agent@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #500, addressing @hongyi-chen's review comment that the Agents tab has "a lot of pages that 'describe' warp's agent."
The tab had three top-level pages whose titles all implied "overview of the agent," with nothing in the nav to tell them apart. #500 gave them distinct jobs (router, narrative, group index) but left all three in the sidebar, so nothing changed from the reader's side. This merges them into one.
Digging in surfaced real duplication underneath the labels, not just ambiguous naming — including a section that was a lossy copy of a better page two clicks away.
Before
After
Changes
Commit 1 — merge the three agent pages into
/agents/What was duplicated:
/agents/andagents-in-warpshared their opening definition, their first link cluster (CLI, cloud agents, Oz, third-party agents), and their closing "where to go next" list.agents-in-warp's Agent autonomy and Agent profiles sections (~37 lines) summarizedcapabilities/agent-profiles-permissions, which documents the same four autonomy levels, YOLO mode, allowlist, and denylist in more detail — and which those sections already linked to. The canonical page even records thatAgent decidesbehaves likeAlways askfor code diffs, a caveat the summary dropped.local-agents/overviewwas a two-sentence intro plus a twelve-item link list, eleven of which the sidebar already renders.The merged page puts routing content above the fold so a reader who came for the CLI can leave immediately, with the tour below it. Autonomy and profiles become a pointer to the canonical page.
Nav: the "Getting started" group is renamed Agents and keeps Agent FAQs, which is troubleshooting and billing reference rather than onboarding. The Warp Agents group now starts at Capabilities.
Redirects now resolve in one hop rather than the two they took before, because legacy sources were repointed directly instead of being left chained through the
/agent-platform/local-agents/overview/hub:/agents//generatesources repointed to/agents/local-agents/generate/, where they always belonged (same bug class as the two inline mislinks fixed in docs: collapse the Agents intro pages and de-duplicate the CLI conversation doc #500)One out-of-scope fix:
/agents(no trailing slash) had a stale rule redirecting backwards to/agent-platform/before bouncing to/agents/. It now resolves directly. Pre-existing, but this change funnels significant traffic to that URL, so it seemed worth the one line.Commit 2 — move CLI install and login reference into the quickstart
Answering the second half of @hongyi-chen's comment.
cli/index.mdxwasn't redundant, but it held procedural content the quickstart needed, so the quickstart linked backwards into it twice mid-install (prerequisites → supported platforms, post-install → automatic updates), and the overview duplicated the login step.Supported platforms, automatic updates, and sign-out now live in the quickstart. The overview keeps what is conceptual and drops from 67 to 45 lines.
The two pages stay separate — AGENTS.md treats quickstart as its own content type with a ten-minute target.
Commit 3 — stay under Vercel's route limit
The first deploy failed. Vercel caps Routes created per Deployment at 2048 and counts every redirect, rewrite, and header in
vercel.json, plus routes the Astro adapter adds. main sits at 2036 config routes with the adapter contributing 12, so it is already exactly at the cap; the four new rules pushed this branch to 2040. Same ceiling hit in27380fdf.The four new rules are all required — verified against the live site that a retired path with only a with-slash rule 404s in its no-slash form. So the routes were reclaimed elsewhere: all six
/agent-platform/warp-airules already pointed at/agents/, so they collapse into two using the:path(.*)idiom from05a0c7ab, which covers the bare path, the trailing-slash form, and every descendant. Back to 2036, and since this branch also deletes two pages, total routes including adapter output are strictly below main's.Commit 4 — refocus the page on what makes the agent different
Addresses @hongyi-chen's review of the merged page on the live preview. The page led with a generic capability list (write code, debug, run commands) that describes any coding agent, explained four features that have their own canonical pages, and routed readers from two separate places.
112 lines to 62. A follow-up commit applies review feedback on the opening: "The Warp Agent" rather than "Warp's coding agent" in the description, per the terminology rule against the ambiguous "Warp's agent" phrasing, and a smoother intro sentence.
Validation
Re-run after each commit; figures below are from the latest.
npm run build— 362 pages, no errors (down 2, as expected).style_lint --all— 0 issues on the pages this PR changes. Repo total is 1444, down from 1457 at the branch point.scheduled-agents,how-to-run-unattended-agents) for which/agents/is now the only source./agent-platform/warp-ai,/agent-platform/features/ai-features,/agent-platform/agent-mode,/agents/autonomy, and both retired URLs all reach a live page in 1 hop.trunk checknot run: Trunk CLI is not installed in this environment.Follow-up: the Oz tab repeats this pattern
Checked
/platform/for cross-tab duplication. The cross-tab relationship is healthy — the Agents tab links to/platform/18 times and every one is a one-sentence pointer or a scoping caveat, and/platform/links back rather than restating.But the Oz tab has the same structural shape we just fixed:
/platform/("Cloud agents overview," 162 lines) is the tab landing, and/platform/overview("Oz Platform overview," 299 lines) is a second overview filed inside its own Getting started group. They also share a near-identical section: "Using cloud agents with or without the Warp app" (platform/index.mdx:100) and "Using the Oz Platform with or without the Warp app" (platform/overview.mdx:286).Left out of scope — different tab, different reviewers, and this PR already touches the Agents redirect hub.
Unverified claims
None. This PR merges, deletes, re-points, and condenses existing prose; it introduces no new UI labels, Settings paths, CLI flags, permission defaults, or plan-eligibility claims. The merged page no longer contains any Settings path, since the sections that held them were cut. The CLI details moved into the quickstart (
general.autoupdate_enabled,WARP_TUI_DISABLE_AUTOUPDATE,/logout, supported platform list) are carried over verbatim from the CLI overview.Co-Authored-By: Warp Agent agent@warp.dev