docs: collapse the Agents intro pages and de-duplicate the CLI conversation doc - #500
Merged
Conversation
PR #486 left two intro pages competing on content. This makes `agents/getting-started/agents-in-warp` the single narrative intro and reduces `agents/local-agents/overview` to an index for the Warp Agents group. The scope line added during #486 review already names the CLI, cloud agents, Oz, and third-party CLI agents with links, so the sections restating them lower on the page are removed. The global AI-disable and Zero Data Retention note moves from the overview page, where it was the only copy in the Agents tab. `local-agents/overview` keeps an orienting paragraph rather than becoming a bare list: it is the destination of roughly 60 legacy `/warp-ai`, `/agent-mode`, and `/ai-features` redirects. Inbound links are retargeted by category rather than with a blanket replace: - Procedural "switch to Agent Mode" steps in the migration guides now point at Terminal and Agent modes, which is what those steps describe. - Conceptual "Agent Mode" and "AI features" - Conceptual "Agent Mode" and "AI features" - to-index links stay on the overview page. - Two pre-existing misl- Two pre-existing misl- Two pre-existing misl- Two pre-existinow point- Two pre-existing misl- Two pre-existing misl- Two pre-existing mislreverted. - Two pre-existing misl- Two pre-existing misl- Two pre-existing miin- Two pre-existing misl- Two pre-existing mis-warp` is their only inbound link from the Agents tab. No slug, path, or URL changes, so no redirects are needed. Co-Authored-By: Warp Agent <agent@warp.dev>
`agents/cli/agent-conversations.mdx` explained several cross-surface concepts from scratch even though canonical pages already cover them. Its Task lists and Planning sections already used the right pattern: describe the CLI-specific behavior, then link out. This extends that pattern to the sections that were missing it. - Code diffs now links to Agent code diffs and review. - Agent questions now links to the Agent questions page, which documents the Ask questions permission. - Conversation persistence leads with the two CLI-only constraints and links sync and restore behavior to Cloud-synced conversations. - Starting a new conversation keeps the slash commands and links the follow-up-versus-fresh guidance to Interacting with agents. - Compacting context links the context window explanation to the canonical section instead of re-explaining it. Genuinely CLI-only behavior is unchanged: transcript rendering, tool-call display, thinkdisplay, thinkdisplay, thinkdisplay, thinkdisplay, thinkdisplay, th command itself. No other CLI page is touched, and the CLI reference keeps its slash command and flag tables. 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 consolidates overlapping Agents introduction content, retargets cross-links to the more specific Agents pages, and reduces duplicated conceptual coverage in the CLI conversations page. I checked the changed documentation for link target validity, docs style/terminology fit, spec drift, and security-sensitive changes.
Concerns
- No blocking concerns found.
- No approved or repository spec context was provided, so there are no spec-alignment findings.
- The security pass found no code, configuration, secret-handling, dependency, or privacy changes that introduce a security concern.
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
rachaelrenk
commented
Aug 11, 2026
|
|
||
| Options the agent suggests as the best fit are labeled `(recommended)`. For multi-select questions, chosen options are marked with a check mark so you can select more than one. When the agent asks several questions at once, the card advances through them. | ||
|
|
||
| To control whether the agent pauses to ask at all, see [Agent questions](/agents/local-agents/interacting-with-agents/agent-questions/). |
Contributor
Author
There was a problem hiding this comment.
"ask at all" is awkward phrasing. It would read better to say something like, "To control whether teh agent pauses to ask questions, see..."
rachaelrenk
commented
Aug 11, 2026
|
|
||
| The CLI shows one conversation at a time. Opening a past conversation replaces the current transcript, and the previous one remains available in history. You can't switch conversations while the current conversation is responding or a command is running. Finish or stop it with `Ctrl+C` first. | ||
|
|
||
| Conversations sync to your Warp account, so the same history is available in the Warp app and on your other devices. See [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) for how syncing, restoring, and sharing work. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| Conversations sync to your Warp account, so the same history is available in the Warp app and on your other devices. See [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) for how syncing, restoring, and sharing work. | |
| Conversations sync to your Warp account, so the same history is available in the Warp app and on your other devices. See [Cloud-synced conversations](/agents/local-agents/cloud-conversations/) for details about syncing, restoring, and sharing work. |
rachaelrenk
commented
Aug 11, 2026
| :::note | ||
| Warp's AI features can be globally disabled in **Settings** > **Agents** > **Warp Agent** with the AI toggle.\ | ||
| \ | ||
| These features send input data to various LLM providers through their API. Warp is **SOC 2 compliant** and has **Zero Data Retention** policies with all contracted LLM providers — no customer AI data is retained, stored, or used for training. Read more about data privacy for Warp features [on our privacy page](https://www.warp.dev/privacy). |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| These features send input data to various LLM providers through their API. Warp is **SOC 2 compliant** and has **Zero Data Retention** policies with all contracted LLM providers — no customer AI data is retained, stored, or used for training. Read more about data privacy for Warp features [on our privacy page](https://www.warp.dev/privacy). | |
| These features send input data to various LLM providers through their API. Warp is **SOC 2 compliant** and has **Zero Data Retention** policies with all contracted LLM providers. No customer AI data is retained, stored, or used for training. Read more about data privacy for Warp features [on our privacy page](https://www.warp.dev/privacy). |
Collaborator
|
I agree with these changes and your feedback, approving to unblock. One thing I did notice though is that there are a lot of pages that 'describe' warp's agent E.g. I wonder if there's a way we can consolidate or simplify some of this content? I wonder if there's anything we can do for the Warp Agent CLI overview page as well? |
hongyi-chen
approved these changes
Aug 11, 2026
- Replace the awkward "pauses to ask at all" with "pauses to ask questions" in the CLI agent questions section. - Reword the cloud-sync pointer to "for details about syncing, restoring, and sharing work". - Split the Zero Data Retention sentence at the em dash, per the style guide's guidance to use em dashes sparingly. 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
2 participants
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 #486, which deliberately deferred two content problems as out of scope. This picks up both, as two independently reviewable commits.
agents/getting-started/agents-in-warpbecomes the single narrative intro;agents/local-agents/overviewbecomes the index for the Warp Agents group.No slug, path, or URL changes, so no redirects are needed.
vercel.json,src/sidebar.ts, andastro.config.mjsare untouched.Note for reviewers: #497's cross-links were relocated, not reverted
#497 (an
aeo_crosslink_auditrun) added four AEO cross-links to the From local to cloud section ofagents-in-warp— a section this PR removes.agents-in-warpis the only page in the Agents tab linking to/platform/triggers/scheduled-agents/and the unattended-agents guide, so deleting the section outright would have stranded both.Both links moved into the new Next steps block.
/platform/managing-cloud-agents/is still linked from the surviving Managing agents section, and/platform/orchestration/has six other inbound links from the Agents tab. Verified post-change: all four destinations still have at least one Agents-tab inbound link.Changes
Commit 1 — collapse the competing intro pages
agents/getting-started/agents-in-warp.mdx(131 → 102 lines):::notehere from the overview page, where it was the only copy in the Agents tab.agents/local-agents/overview.mdx(46 → 29 lines)/agents/), and Outside the Warp app./warp-ai,/agent-mode,/ai-features,/generate).Agents in Warpis now the first entry in the list, framed as the place to start.Inbound link retargeting (18 files) — applied by category, not with a blanket replace:
⌘+I" steps in the 7 migration guides →terminal-and-agent-modes, which is what those steps actually describe.agents-in-warp.local-agents/overview./agents/local-agents/generate/(credits.mdx,using-warp-offline.mdx).Local Agents→Using the Warp Agentincapabilities/index.mdx, matching the docs: consolidate the Warp Agent CLI docs into the Agents section #486 retitle.Net effect:
local-agents/overviewgoes from 33 inbound links to 4 (all index-to-index);agents-in-warpgoes from 1 to 20 across 18 files.Commit 2 — link the CLI conversations page out to canonical pages
agents/cli/agent-conversations.mdxalready used the right pattern in its Task lists and Planning sections. This extends it to the sections that were missing it:Agent code diffs and review.Agent questions, which documents theAsk questionspermission.Cloud-synced conversations.Interacting with agents.Unchanged because it is genuinely CLI-only: transcript rendering, tool-call display, thinking blocks, terminal text selection,
--resume, and/compactitself. No other CLI page is touched, andcli/reference.mdxkeeps its slash-command and flag tables — that feature-doc-vs-reference split is intentional, not duplication.Validation
npm run build— 364 pages, no errors.origin/mainwas also 0).style_lint --all— 1460 → 1457 issues. No net-new; the 3 resolved were hardcodedOz web app/oz.warp.dev/Oz CLIstrings that left with the Resources section.trunk checknot run: Trunk CLI is not installed in this environment.Unverified claims
None — this PR only removes, relocates, and re-points existing prose. It introduces no new UI labels, Settings paths, CLI flags, permission defaults, or plan-eligibility claims. The one retained UI path (Settings > Agents > Warp Agent, in the moved AI-disable note) is carried over verbatim from
local-agents/overview.mdx.Co-Authored-By: Warp Agent agent@warp.dev