docs: consolidate the Warp Agent CLI docs into the Agents section - #486
Open
rachaelrenk wants to merge 10 commits into
Open
docs: consolidate the Warp Agent CLI docs into the Agents section#486rachaelrenk wants to merge 10 commits into
rachaelrenk wants to merge 10 commits into
Conversation
The Warp Agent CLI had its own top-level docs tab at /cli, which framed it as a separate product area rather than another entry point to the Warp Agent. Nothing outside src/content/docs/cli/ linked into it, so the section was effectively orphaned from the rest of the docs. Move the nine CLI pages to src/content/docs/agents/cli/ and surface them as a "Warp Agent CLI" group inside the Agents tab, between "Warp Agents" and "Third-Party CLI Agents". - Move content and assets with git mv so history follows; rewrite 68 absolute self-links and both relative image paths. - Remove the standalone Agent CLI sidebar topic and add the new group, preserving the original ordering and labels. - Add nine 308 redirects so every /cli/* URL still resolves. - Repoint the llms.txt custom set at agents/cli/**. - Reference the CLI as an entry point from agents/index, agents-in-warp, local-agents/overview, and cli-agents/overview, which previously had no path to it. The path /agents/cli/ is deliberately generic: the Oz CLI is retired and wrapped into the Warp Agent CLI at the next launch (~2026-08-18), so the Oz CLI reference is expected to fold in here later. Recorded that decision in the terminology glossary and the vars.ts comment that previously flagged the WARP_AGENT_CLI / WARP_CLI collision as unresolved. Neither var changes in this commit. Also cropped the two CLI screenshots to their subject (the tab-bar capture included a cut-off prompt below the bar) and included a cut-off prompt below the bar) and included a cut-off proBy: 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 consolidates the Warp Agent CLI documentation under the Agents section, updates the sidebar and llms.txt custom set, rewrites moved-page self-links, and adds redirects for the old /cli/* URLs. I did not find correctness, docs-structure, security, or spec-alignment issues in the annotated diff.
Concerns
- None.
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
…oute limit 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 as a route. main sits at 2033; the nine per-page /cli redirects pushed this branch to 2042, and the Astro Vercel adapter contributes further routes on top of the config, tipping the deployment over the ceiling. Replace the nine per-page entries with two wildcard entries, bringing the total to 2035 (+2 over main instead of +9). The wildcard also covers deep links and any page added under the old path, which the enumerated list would not have. Co-Authored-By: Warp Agent <agent@warp.dev>
The previous wildcard used ':path*', which did not match the trailing-slash URLs this site serves. Verified against the preview deployment: /cli/ redirected correctly but /cli/quickstart/ and /cli/reference/ both returned 404, so eight of the nine original URLs were broken. Use a regex capture ':path(.*)' instead, which captures the remainder of the path including its trailing slash. Keeps the route count at +2 over main. Co-Authored-By: Warp Agent <agent@warp.dev>
The Warp Agent CLI statusline is content-bound: it clips rather than reflows, and showing every chip its alt text promises needs ~111 columns. Re-capturing at a narrower terminal cannot shrink it, so at 563px the text renders at roughly 48% of source and reads small. The existing standard had no width above 563px, leaving no correct option for a screenshot like this. Add 736px as a full-content-width tier. The value is not arbitrary: it is the content column, `max-width: 46rem` on `.main-pane .sl-container` in src/styles/custom.css. Because the container already caps there, 736px renders identically to omitting maxWidth — the point of naming it is that authors can now express "deliberately full width" and the lint can tell that apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart apart acheck messages from the constant so they cannot drift out of sync. - AGENTS.md: document the new tier and when to reach for it, add a "crop before widening" rule so widening stays the last resort, and make legibility explicitly outrank the preference for a smaller tier. - Apply 736px to the statusline figure. Verified: 0 net-new lint issues, 2 resolved. The 218 pre-existing missing-width warnings are still flagged, so the rule is not weakened. Co-Authored-By: Warp Agent <agent@warp.dev>
The previous capture was the full width of a ~105-column terminal, so roughly 45% of the image was empty background to the right of the tabs. Downscaled into the 563px figure, that left each character cell about 5.4 CSS px wide and the whole bar only 19px tall. Re-captured the same state from the running Warp Agent CLI and cropped tightly to the tab bar: - Dimensions: 1176x40 -> 1126x68 - Aspect ratio: 29.4:1 -> 16.56:1 - Rendered height at 563px: 19px -> 34px - Character cell at 563px: 5.4 CSS px -> 8.6 CSS px (~60% larger) 1126px is exactly 2x the 563px figure width, so the asset renders at a clean 2x with no resampling blur. Padding is symmetric: 37px left and right of the text, 18px above and below the tab-bar strip. The state still matches the caption: one child agent running and two finished. Verified by watching all three tabs transition rather than assuming glyph meanings - every tab shows a filled dot while running and switches to its own icon on completion, and the frame was captured when exactly one dot remained. The figure keeps its 563px maxWidth; the tighter crop makes widening unnecessary. Co-Authored-By: Warp Agent <agent@warp.dev>
Per HYC's review of #486: the page led by defining Oz rather than the Warp Agent, and its single flat "Key capabilities" list mixed surfaces (Local Agents, Warp Agent CLI, third-party CLI agents) with platform concerns (Cloud Agents, Integrations, Oz Platform). A first-time reader picked from six links before learning what the agent is. Restructure to answer, in order: what the agent is, how to reach it, what the platform adds. - Open with the Warp Agent instead of Oz. - Add "Ways to use the Warp Agent" as the page's spine, with the three surfaces as peers: the Warp app, the Warp Agent CLI, and cloud agents. - Give third-party CLI agents their own section. They belong on this tab, but they are not a way to use the Warp Agent, so the distinction is now structural rather than just wording. - Collapse the platform material into one pointer to the Oz tab, and drop the "Learn more" list that duplicated the Oz tab's own index (Integrations, Environments, Skills as Agents, Managing Cloud Agents). Verified none of those pages is orphaned; each has 9-86 other inbound links. Contextual crosslinks into Oz are kept. What is removed is the duplicate table of contents, per AGENTS.md: cross-reference related features prominently, "not as generic link lists added only for SEO." Co-Authored-By: WCo-Authored-By: WCo-Authored-By: WCo-Authc/content/docs/agents/local-agents/overview.mdx src/sidebar.ts src/content/docs/agents/getting-starCo-Authored-By: WCo-Authored-By: WCo-Aut-F - <<'EOF' docs: retitle the Warp Agents group landing and promote the CLI mention Three pages read as broad "here's the agent" pages: /agents/Three pages read as broad "here's the agent" pages: /agents/Three pag in Warp"), and /agents/local-agents/overview ("Warp Agents overview"). The tit/agents/local-agents/overview ( orients/agents/local-agents/overview ("Warp Agents overview"). The tit/agents/lverview", matching every sibling group. The Warp Agent CLI and Third-Party CLI Agents groups already label their landing page this way; this was the only group landing repeating its own group name, so the name,r read "WARP AGENTS > Warp Agents overview". - Page title becomes "Using the- Page title becomes "Using the- Page title becomes "Using the- Capabilities (Rules, Skills, MCP, planning), which are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-su are cross-tem list to a short "Outside the Warp app" section. HYC reviewed the branch preview with the bullet already present and still asked for a mention. - Update the one stale "Warp Agents overview" link label. No slug, path, or URL change, so no redirect. Co-Authored-By: Warp Agent <agent@warp.dev>
The main lThe main lThe main lThe main lThe main lThe main lThe main lThe main ls" and defined local agents as running "directly in the Warp app". There was There was There was There was There was There was There was Then wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwHYC, the CLI is called out as a way to use the Warp Agent without the Warp terminal / ADE. Also drop the duplicated multi-model sentence (the page already has a Multi-model support section), widen "same agent, anywhere" to name all three surfacthree surfacthree surfacthree surfacthree surfacthree surfacthree sure is unchanged. Co-Authored-By: Warp Agent <agent@warp.dev>
Three pages read as broad "here's the agent" pages: /agents/ ("Agents
overview"), /agents/getting-started/agents-in-warp ("Agents in Warp"), and
/agents/local-agents/overview ("Warp Agents overview"). The titles gave no
hint that the first orients, the second teaches, and the third indexes.
- Sidebar label becomes "Overview", matching every sibling group. The Warp
Agent CLI and Third-Party CLI Agents groups already label their landing
page this way; this was the only group landing repeating its own group
name, so the sidebar read "WARP AGENTS > Warp Agents overview".
- Page title becomes "Using the Warp Agent". Surface-neutral on purpose:
this group contains Capabilities (Rules, Skills, MCP, planning), which
are cross-surface and linked directly from the CLI docs, so a title like
"Agents in the Warp app" would over-claim and collide with the existing
"Agents in Warp" page.
- Promote the CLI from one bullet in an eleven-item list to a short
"Outside the Warp app" section. HYC reviewed the bran "Outside the Warp app" section. HYC reviewed the bran "Outside thention.
- Update the one stale "Warp Agents overview" link label.
No slug, path, or URL change, so no redirect.
Co-Authored-By: Warp Agent <agent@warp.dev>
Resolves the conflicts GitHub reported. Two of main's PRs edited the CLI pages at their old paths while this branch was moving them, and a third added a link into the path being moved. - #479 added the `freeze_animation_when_unfocused` start-screen setting to cli/configuration.mdx, and #459 added the `/copy-debugging-id` slash command row plus a troubleshooting paragraph to cli/reference.mdx. Git's rename detection carried both into the new agents/cli/ paths; verified present after the merge. - #459 also added a link to `/cli/` from sending-us-feedback.mdx, which this branch had moved out from under it. Repointed to `/agents/cli/`. The redirect would have caught it at runtime, but an internal link should target the real path and the CI link check fails on it. - #485 added a redirect, bringing vercel.json to 2036 routes against Vercel's 2048 limit. Still under, but the headroom is now 12. Verified nothing from main was lost: every file main touched that this branch does not also touch matches origin/main exactly. Validation on the merged tree: build 364 pages, typecheck 0 errors, 0 broken internal links across 3,453. 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.
Refactors the standalone Agent CLI tab out of the docs navigation and folds its content into the Agents tab, so the Warp Agent CLI reads as another entry point to the agent rather than a separate product area.
Implements the Notion project. Builds on #473, which merged first.
Why this ordering
Nothing outside
src/content/docs/cli/linked into/cli/*, so the section was orphaned from the rest of the docs. That also made it the cheap surface to move:/cli/*) — 9 pages, 0 inbound links, 0 existing redirects./reference/cli/*) — 11 pages, linked from 51 pages, already the destination of 57 redirects.The Oz CLI is retired and wrapped into the Warp Agent CLI at the next launch (~August 18), leaving a single CLI. Moving the cheap surface now and folding the expensive one in later disturbs the heavy inbound-link and redirect footprint once, not twice.
/agents/cli/is therefore deliberately generic rather than/agents/warp-agent-cli/, so the path still reads correctly once there is only one CLI.Nothing under
/reference/cli/*changes in this PR.What changed
src/content/docs/agents/cli/and both images tosrc/assets/agents/cli/, viagit mvso history follows. Rewrote 68 absolute self-links and both relative image paths.Agent CLIsidebar topic and added a Warp Agent CLI group inside the Agents tab, between Warp Agents and Third-Party CLI Agents./cli/*URL still resolves.agents/cli/**.vars.tscomment that previously flagged theWARP_AGENT_CLI/WARP_CLIcollision as an open product decision. Neither variable's key or value changes here.Redirects: wildcard, not per-page
The first version used nine per-page redirects. That broke the Vercel deployment: Vercel caps "Routes created per Deployment" at 2048 and counts every redirect, rewrite, and header in
vercel.jsonas a route.mainsits at 2033, so +9 tipped it over once the Astro adapter's own routes were added.Collapsed to two wildcard entries. The total is now 2035, only +2 over
main, and the wildcard also covers deep links and any future page under the old path.One trap worth flagging for future moves:
:path*does not match the trailing-slash URLs this site serves. Verified against the preview deployment that/cli/quickstart/and/cli/reference/returned 404 under:path*while/cli/worked. The working form is the regex capture:path(.*). All nine original URLs re-verified as308to the correct destination on the live preview.Screenshots and a new width tier
A cloud agent with computer use re-examined both CLI screenshots against a live CLI.
tui-agents-tab-bar.png— re-captured and tightly cropped:1176x40(29.4:1) becomes1126x68(16.56:1). The character cell at 563px goes from 5.4 to 8.6 CSS px, roughly 60% larger text.1126is exactly 2x563, so it renders at a clean 2x. The captured state matches the caption: one child running, two finished.tui-statusline.png— left unchanged, deliberately. It is content-bound rather than capture-bound: the statusline clips instead of reflowing, and showing every chip its alt text promises needs ~111 columns, so a narrower re-capture is impossible. The best achievable gain was ~5%.Since 563px was the widest tier available, there was no correct width for a screenshot like the statusline. This PR adds a 736px full-content-width tier:
max-width: 46remon.main-pane .sl-containerinsrc/styles/custom.css.736pxrenders identically to omittingmaxWidth. Naming it explicitly lets authors signal "deliberately full width" and lets the lint distinguish that from a figure that is simply missing a width, which it previously could not do.style_lintnow accepts it, and all three check messages derive their width list from the constant so they cannot drift.The tab bar stays at 563px, since cropping was sufficient there.
Agents IA reframe (added after review)
HYC reviewed the branch and asked for the Agents section to be put in order before merge.
agents/index.mdxreframed around three access surfaces. It previously opened by defining Oz and offered a single flat "Key capabilities" list that mixed surfaces (Local Agents, Warp Agent CLI, third-party CLI agents) with platform concerns (Cloud Agents, Integrations, Oz Platform). It now answers, in order: what the Warp Agent is, how to reach it, and what the platform adds. The three surfaces are the Warp app, the Warp Agent CLI, and cloud agents. Third-party CLI agents get their own section, since they belong on this tab but are not a way to use the Warp Agent.agents/local-agents/overview.mdxretitled, and the CLI mention promoted. The sidebar label is nowOverview, matching every sibling group; this was the only group landing that repeated its own group name. The page title is now "Using the Warp Agent", chosen to be surface-neutral because this group holds cross-surface Capabilities docs that the CLI links into. The CLI moved from one bullet in an eleven-item list to a short section. No slug or URL change, so no redirect.index.mdxtwo-mode section replaced. The page said "Oz operates in two modes: Local agents / Cloud agents" and defined local agents as running "directly in the Warp app", so there was structurally no slot for the CLI. It now uses the same three surfaces as the Agents landing page.The duplicate Learn more index on the Agents landing page was removed, since it re-listed Oz tab topics that already have their own landing page. Contextual crosslinks into Oz are kept. Verified that no removed link orphans a page; each target has between 9 and 86 other inbound links.
Deferred, deliberately
agents-in-warp(131 lines) andlocal-agents/overview(40 lines) still overlap as intro pages. Agreed direction: letagents-in-warpbe the single narrative intro and strip the other to a pure index.agents/cli/agent-conversations.mdx, roughly 4 duplicate app content, 4 describe concepts with canonical pages elsewhere, and 6 are legitimately CLI-only. The fix is linking out to canonical concept pages rather than merging pages.Validation
npm run buildpasses: 364 pages, no new warnings.npm run typecheck(astro check): 0 errors.style_lint: 10 fewer issues than theorigin/mainbaseline (1458 to 1448). One net-new warning, for the bolded page name "Agent FAQs" not being in the product glossary. That is the same false-positive class as the 200+ pre-existing ones, and a page title does not belong in a product glossary./cli/*URLs verified as308to the correct destination on the preview deployment.Agent CLItab is gone, nohref="/cli/"remains, and the new sidebar group renders in the right position.Reviewer notes
/agents/cli/sits next to/agents/cli-agents/*(third-party agents). Raised with Hong Yi Chen and resolved in favor of keeping/agents/cli/. A later rename of/agents/cli-agents/to/agents/third-party-agents/would remove the residual ambiguity, but it is out of scope here. In the meantimecli-agents/overviewgained a disambiguating pointer.agent modethat should beAgent Mode. They predate this work and survived docs: editorial review pass on Warp Agent CLI launch docs #473's editorial pass, so they are worth a small follow-up rather than inflating this diff.Co-Authored-By: Warp Agent agent@warp.dev