Skip to content

docs: Warp Agent CLI launch documentation - #411

Draft
hongyi-chen wants to merge 19 commits into
mainfrom
hyc/launch-cli
Draft

docs: Warp Agent CLI launch documentation#411
hongyi-chen wants to merge 19 commits into
mainfrom
hyc/launch-cli

Conversation

@hongyi-chen

@hongyi-chen hongyi-chen commented Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Warp Agent CLI launch

Umbrella/integration branch for the new Warp Agent CLI docs section: a new sidebar topic with 9 pages under /cli/, plus the WARP_CLI content var and internal launch plan (drafts/warp-cli-launch-plan.md).

Sub-PRs into this branch (one per page bundle, per-eng review)

(#397, #403, #400 were absorbed during consolidation from 13 pages to 9 and closed.)

Remaining before this merges

  • All sub-PRs reviewed by eng and merged
  • Integration commit: delete 4 orphaned stubs, rename slugs (input-and-shell-commands, customization), flatten sidebar to 9 entries, cross-link sweep, final build
  • Install instructions confirmed (currently a placeholder in quickstart)
  • Blog-claim reconciliation: OpenAI-compatible endpoints, Grok subscription login, Windows support (none verified on master)
  • Merge timed with the launch

Links

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

hongyi-chen and others added 2 commits July 28, 2026 14:15
@hongyi-chen @oz-agent
Add Warp CLI launch docs skeleton and internal plan
5305f21 
- New 'Warp CLI' sidebar topic with 13 stub pages under src/content/docs/cli/
- drafts/warp-cli-launch-plan.md: internal feature->page->reviewer analysis
- New WARP_CLI content var (distinct from WARP_AGENT_CLI, reserved for the
  Oz CLI rename)

Co-Authored-By: Oz <oz-agent@warp.dev>
@hongyi-chen @oz-agent
Rename product to Warp Agent CLI
e2aebe3 
- WARP_CLI var value -> "Warp Agent CLI" (body prose updates site-wide)
- Sidebar topic label updated
- Frontmatter literals fixed in the four stubs pending deletion
- drafts doc: naming confirmed; WARP_AGENT_CLI key collision flagged

Co-Authored-By: Oz <oz-agent@warp.dev>
@cla-bot cla-bot Bot added the cla-signed label Jul 29, 2026
@vercel

vercel Bot commented Jul 29, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
docs Ready Ready Preview Aug 3, 2026 10:48pm

Request Review

@rachaelrenk rachaelrenk mentioned this pull request Jul 30, 2026
Closed
hongyi-chen and others added 4 commits July 30, 2026 16:00
@hongyi-chen @oz-agent
docs(cli): models and usage + reference with troubleshooting (#405)
37fec7f 
* docs(cli): draft reference, models & usage, and troubleshooting pages

Fill in the three cli-reference pages from the Warp CLI launch skeleton:

- cli/reference: command-line flags with examples, environment variables,
  full slash-command table (25 commands verified against the CLI command
  registry), and default keyboard shortcuts sourced from the CLI keybinding
  definitions.
- cli/models-and-usage: /model picker and footer model entry, BYOK via
  /add-api-key + provider flags (OpenAI/Anthropic/Google), custom model
  routers in the picker, and cost transparency (footer credits toggle,
  /cost per-response summary).
- cli/troubleshooting: /view-logs bundling and log locations, login
  troubleshooting, autoupdate behavior with /version and --version, and
  support links.

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

* docs(cli): use literal Warp CLI in frontmatter title/description

Frontmatter {{WARP_CLI}} tokens are not substituted by the build (Astro's
content layer parses frontmatter outside Vite), so built titles showed the
raw token. Body prose keeps {VARS.WARP_CLI}.

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

* docs(cli): fold troubleshooting into the reference page

Consolidation: the standalone troubleshooting page merges into
cli/reference.mdx as a final Troubleshooting section with problem-oriented
H3 subsections. Existing H2 anchors (#slash-commands, #keyboard-shortcuts)
are unchanged; internal links now point at #updating and
#command-line-flags. troubleshooting.mdx is restored to the base-branch
stub (the orchestrator removes it at integration).

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

* docs(cli): rename literal Warp CLI to Warp Agent CLI in frontmatter

Follows the base-branch WARP_CLI var value change; body prose picks up the
new name automatically via {VARS.WARP_CLI}.

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

* docs(cli): security fixes for API key examples

Address review feedback:
- Make WARP_API_KEY=... warp the primary non-interactive auth example and
  document --api-key secondarily with a caution that command-line arguments
  can be captured in shell history and process listings.
- Replace the persistent key.txt stdin example with a tool-agnostic
  secret-manager pipe and a note against staging keys in plaintext files.

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

* docs(cli): editorial polish pass

Reduce product-name density after each page's intro (prefer "the CLI"),
vary repeated trailing "See [X]" sentences, and fold two cross-links into
their sentences. No structural, factual, heading, or link-target changes.

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

* docs(cli): trim menu-mechanics narration

Cut the type-to-filter/arrows/Enter sentence from the model picker prose
and the keep-typing-to-filter clause from the slash-command intro, per the
editorial bar against narrating self-evident UI mechanics. Defaults,
exceptions, and lookup tables are unchanged.

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

* docs(cli): note macOS Option-as-Alt requirement for Alt shortcuts

Platform audit: every keybinding registration is identical on macOS and
Linux (the only platform-conditional binding is a Windows-only Alt+V
paste, which is not documented since no Windows build ships). Input
arrives as terminal key events, so Alt shortcuts depend on the host
terminal delivering Option as Alt on macOS; add one note to the keyboard
shortcuts section instead of per-row annotations.

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

* docs(cli): tighten disabled-models sentence in model picker prose

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

* docs(cli): update API key docs for /api-keys menu and --auto-approve flag

Address review feedback on the API key flow change (warpdotdev/warp#14472),
which replaced /add-api-key and /clear-provider-api-key with a single inline
/api-keys menu:

- models-and-usage: rewrite the BYOK section around the /api-keys menu —
  set/replace/clear provider keys with masked entry, connect or disconnect
  X Premium/SuperGrok via browser sign-in, and toggle Warp credit fallback.
  The --set-provider-api-key/--clear-provider-api-key flags stay documented
  for scripting (they remain supported per the CODE-1930 spec).
- reference: swap the /add-api-key and /clear-provider-api-key slash-command
  rows for /api-keys, and point --set-provider-api-key at the in-session menu.
- reference: document the new --auto-approve flag (warpdotdev/warp#14483),
  which starts new conversations in that launch with auto-approve enabled.

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

* docs(cli): editorial trim pass on API key and auto-approve additions

Remove redundant clauses: drop the repeated launch-default sentence in
--auto-approve, the doubled keys-over-credits statement in the fallback
bullet, the repeated browser-sign-in rationale in the scripting paragraph,
and tighten the /api-keys table row to match the terse row pattern.

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

---------

Co-authored-by: Oz <oz-agent@warp.dev>
@hongyi-chen @oz-agent
docs(cli): permissions and profiles (#404)
3daed2d 
Replaces the `cli/permissions-and-profiles.mdx` stub with a full draft covering the permission model, permission cards, auto-approve, and settings-file execution profiles.

Verified against `warp` master:
- Per-action-type permission values and CLI defaults (`AIExecutionProfile::default_profile_for_tui`)
- `warp --auto-approve` launch flag (warpdotdev/warp#14483)
- `auto_approve_bypasses_command_denylist` defaults to true, so auto-approve bypasses the user command denylist; team-enforced Admin Panel rules are never bypassed (`can_autoexecute_command`)

Follow-ups tracked, not included here:
- `--auto-approve` needs adding to the flags table on `cli/reference.mdx` (separate stub PR on this stack)
- `agent-platform/capabilities/agent-profiles-permissions.mdx` has two now-stale denylist statements given the new bypass default

Reviewed by @harryalbert.

Co-Authored-By: Oz <oz-agent@warp.dev>
@hongyi-chen @oz-agent
docs(cli): cloud handoff and orchestration (#402)
95fbeef 
Replaces the cli/cloud-and-orchestration stub with the full draft: /handoff flow and guardrails, resuming cloud runs (browser-first), multi-agent orchestration approval card and permission, child-agent tab bar management, and Ctrl+C kill paths. Includes review feedback from harryalbert and a final editorial pass.

Co-Authored-By: Oz <oz-agent@warp.dev>
@hongyi-chen @oz-agent
docs(cli): agent conversations and conversation management (#399)
d12e1b6 
* docs(cli): draft agent conversations page

Covers the streaming transcript, Markdown/Mermaid rendering, tool-call
rows, file-edit diffs, thinking blocks, interactive agent questions,
task lists, /plan flow, and transcript selection/copy for the Warp CLI.

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

* docs(cli): use literal Warp CLI in frontmatter

{{WARP_CLI}} tokens are not substituted in MDX frontmatter by the
content layer, so built titles/descriptions showed the raw token.
Body prose keeps {VARS.WARP_CLI}.

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

* docs(cli): absorb conversation management into agent conversations page

Adds a Managing conversations section group (persistence/restore,
/new /agent /clear, /conversations menu + left-arrow shortcut,
/compact, exit summary + --resume) from the standalone conversations
page, which is being removed in the consolidation. Updates the intro,
description, and related pages accordingly.

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

* docs(cli): rename to Warp Agent CLI in frontmatter

Follows the launch-name change; body prose picks up the new name via
the WARP_CLI var from the base branch merge.

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

* docs(cli): editorial polish on agent conversations page

Reduces product-name repetition after the intro, links bold lead terms
in the tool-call list instead of trailing See-X sentences, swaps
'unfolds' for 'appears', fixes 'just', and de-metas the intro's
managing-conversations pointer. No factual, heading, or link-target
changes.

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

* docs(cli): trim self-evident UI narration per review

Per PR review: cut transcript scrolling narration, collapse the
markdown-features list to its non-obvious caveats (folding the H3),
drop the tool-call glyph state-machine detail, and sweep the rest of
the page with the same lens (menu how-tos, click-to-collapse, and
double/triple-click narration removed). Feature facts, caveats,
shortcuts, and cross-links are unchanged.

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

* docs(cli): apply editorial audit cuts

Seven targeted trims: intro filler sentence, diff-header bullet detail,
multi-question tail, bold header adjective, copy-confirmation footer
mention, managing-conversations enumeration, and history restore
phrasing.

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

* docs(cli): address review feedback on agent conversations

- Trim styling narration from the transcript intro (prompt row marker,
  elapsed-time progress indicator) that would go stale with small UI
  changes; keep the durable behavior (streaming, Ctrl+C to stop).
- Color the task-list status glyphs to match the TUI: yellow in-progress
  dot and green completed check, via mode-aware Starlight hue tokens so
  they stay legible in dark and light mode.
- Lead "Resuming conversations" with the conversation menu, the primary
  way to resume in the CLI, and note type-to-filter in the menu.

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

* docs(cli): editorial pass for redundancy and flow

- Collapse three separate "restores the full transcript" statements into
  one, in Conversation persistence, where the detail belongs.
- Replace the duplicated "saved automatically" claim with the account vs.
  local-machine distinction, which sets up the menu contents and the
  offline caution that follow.
- Move Resuming conversations next to Conversation history so the two
  cross-referencing sections are adjacent instead of split by Compacting
  context.
- Point the intro's resume link at #resuming-conversations directly, and
  fix a dangling modifier in the tool-call description.

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

---------

Co-authored-by: Oz <oz-agent@warp.dev>
This was referenced Jul 30, 2026
Merged
Open
Merged
Open
hongyi-chen and others added 2 commits July 30, 2026 20:58
@hongyi-chen @oz-agent
docs(cli): remove orphaned conversations stub, repoint its links (#423)
ea87e8c 
PR #397 (hyc/launch-cli-cli-conversations) was closed unmerged when #399
absorbed its content into cli/agent-conversations.mdx, but the stub it was
meant to fill survived on the launch branch. The sidebar listed it as
"Managing conversations" four lines below the real "Agent conversations"
page, so the launch would have shipped a nav entry leading to a page that
reads "documentation for this page is in progress".

- Delete src/content/docs/cli/conversations.mdx.
- Drop its sidebar entry in src/sidebar.ts.
- Repoint the four inbound links from cloud-and-orchestration.mdx and
  reference.mdx to the corresponding anchors on cli/agent-conversations.

No redirect needed: /cli/conversations has never been published (404 live,
and src/content/docs/cli/ does not exist on main).

Co-authored-by: Oz <oz-agent@warp.dev>
@hongyi-chen @oz-agent
docs(cli): remove orphaned troubleshooting stub (#425)
7727639 
PR #405 consolidated troubleshooting into cli/reference.mdx (its
Troubleshooting section) and reset cli/troubleshooting.mdx back to the
skeleton stub, leaving the stub published in the sidebar with no
sub-PR left to fill it. Remove the stub and its sidebar entry, matching
the treatment #423 gives the conversations stub.

No inbound links exist to /cli/troubleshooting/ (checked all merged and
open cli sub-PR content), so no repoints are needed. Advances the
'delete 4 orphaned stubs' item on the #411 integration checklist.

Validation: npm run build green; internal link check 0 broken.

Co-authored-by: Oz <oz-agent@warp.dev>
@hongyi-chen @oz-agent
docs(cli): customization (settings, themes, statusline, rules, skills…
9b80487 
…, MCP) (#401)

* docs(cli): draft the Warp CLI configuration page

Cover the local TOML settings file (per-platform locations, hot reload,
error fallback, local-only/no cloud sync), editing settings by asking the
agent, /theme with terminal background detection, and the statusline with
/statusline customization. Drop the keybindings section: custom keybinding
overrides are not loaded by the CLI yet.

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

* docs(cli): use literal Warp CLI in configuration frontmatter

{{WARP_CLI}} tokens are not substituted in MDX frontmatter by the build
pipeline, so the built title/description showed the raw token. Body prose
keeps {VARS.WARP_CLI}.

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

* docs(cli): absorb agent context content into the customization page

Consolidate the CLI docs: fold the context page's rules, skills, bundled
skills, and MCP sections into configuration.mdx, retitled "Customizing the
Warp CLI". Dedupe the modify-settings bundled skill treatment and switch
cross-links to in-page anchors. The context.mdx file itself is removed at
integration.

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

* docs(cli): rename Warp CLI to Warp Agent CLI in customization frontmatter

Follows the site-wide WARP_CLI var update on the base branch; body prose
picks up the new name via the var automatically.

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

* docs(cli): qualify settings hot reload for theme edits

Address review on PR #401: settings values hot-reload from disk, but the
rendered theme only re-applies via /theme or at the next startup, so the
settings-file and agent-edit sections no longer promise immediate effect
for theme changes. Also scope the Themes section's immediate-apply claim
to /theme. Windows path verified to render with single backslashes in
source and built HTML; no change needed.

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

* docs(cli): reduce product-name density on the customization page

Editorial polish pass: after the intro's first mention, refer to the
product as "the CLI" instead of repeating the full name in every section.
The full name stays in the frontmatter, the intro, and the reference link.
No structural, factual, heading, or link-target changes.

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

* docs(cli): trim obvious menu-mechanics narration

Per editorial direction: collapse the skills-menu step list into the
non-obvious behaviors (selection inserts /skill-name for editing, argument
passing, direct invocation) and drop the arrow-select narration in the
/mcp view. Keep the statusline config steps since its keys are surprising
(Esc saves, arrows reorder). No headings, facts, or link targets changed.

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

* docs(cli): compress statusline catalog and tighten context and /mcp prose

Apply orchestrator audit: keep only statusline items with non-obvious
behavior as bullets and fold the self-explanatory ones into one sentence,
shorten the working-directory context paragraph, and replace the four
per-state /mcp bullets with two lines.

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

* docs(cli): re-verify statusline items against latest master

Master's statusline catalog changed (moira's #14257/#14458): the
auto-queue item was removed, and Vim mode indicator and GitHub pull
request items were added. Auto-approve and Vim mode indicator are now on
by default. Update the item list, defaults, and the auto-approve and git
diff descriptions accordingly. Themes, settings paths, and the /statusline
config flow re-verified against master and unchanged.

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

---------

Co-authored-by: Oz <oz-agent@warp.dev>
@hongyi-chen @oz-agent
Post-merge coherence pass on cli docs
befb385 
- Remove orphaned context stub (content lives in configuration.mdx via #401)
  and its sidebar entry; repoint the reference page link
- Fix stale auto-approve statusline claim in permissions page (the indicator
  is default-on since the statusline catalog update)

Co-Authored-By: Oz <oz-agent@warp.dev>
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/agent-conversations.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/agent-conversations.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/agent-conversations.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/agent-conversations.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/agent-conversations.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/configuration.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/configuration.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/models-and-usage.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/models-and-usage.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/models-and-usage.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/models-and-usage.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/models-and-usage.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/models-and-usage.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/models-and-usage.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/models-and-usage.mdx Outdated
@rachaelrenk @oz-agent
docs: address review feedback on models-and-usage.mdx
37113c0 
- Applies suggestion comments: intro rewording, model-picker/profile
  wording, semicolon and colon cleanup, usage bullet rewording
- Clarifies the ambiguous "footer" reference by naming and linking to
  the statusline section in configuration.mdx (applied consistently to
  both occurrences on the page)

Co-Authored-By: Oz <oz-agent@warp.dev>
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/permissions-and-profiles.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/permissions-and-profiles.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/permissions-and-profiles.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/permissions-and-profiles.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/permissions-and-profiles.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/permissions-and-profiles.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/permissions-and-profiles.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/permissions-and-profiles.mdx Outdated
rachaelrenk
rachaelrenk reviewed Aug 3, 2026
View reviewed changes
Comment thread src/content/docs/cli/reference.mdx Outdated
@rachaelrenk @oz-agent
docs: fix statusline default-items accuracy and add screenshot
5ad083d 
Verified against warpdotdev/warp origin/master (crates/warp_tui/src/
terminal_session_view/statusline.rs, app/src/settings/ai.rs):
- Adds the missing 'Working directory' bullet; it's a default item,
  not one you 'also add'
- Clarifies that enabling Git branch status replaces the plain Git
  branch chip rather than adding a second one
  (should_render_plain_git_branch requires branch status disabled)
- Adds a real screenshot of the statusline with credit usage, context
  window usage, and task-list chips enabled, captured live via the
  tui-verify-change skill in warpdotdev/warp

Co-Authored-By: Oz <oz-agent@warp.dev>
@rachaelrenk @oz-agent
docs: address review feedback on permissions-and-profiles.mdx and ref…
f1acfb4 
…erence.mdx

permissions-and-profiles.mdx:
- Applies suggestion comments: description/intro trims, colon removal
- Clarifies the vague "letting file reads through" example
- Converts the dense default-permissions paragraph into a scannable
  bulleted list
- Removes semicolons from the approval-card bullets and tightens
  wording
- Links the settings-file bypass instructions to configuration.mdx

reference.mdx:
- Applies the intro suggestion, removing the mid-sentence colon

Co-Authored-By: Oz <oz-agent@warp.dev>
@rachaelrenk @oz-agent
docs: holistic style pass across Warp Agent CLI docs
12e7b61 
Applies the same rubric from earlier review rounds (unclear language,
wordy passages, unnecessary UI detail, colons/semicolons) to the rest
of the PR:

- reference.mdx: fixes a grammar issue in the flags intro, removes
  mid-sentence colons/semicolons in the slash commands, keyboard
  shortcuts, and troubleshooting sections (only line 9 had been
  reviewed directly)
- Re-scanned all previously-edited files (agent-conversations,
  cloud-and-orchestration, configuration, models-and-usage) for
  remaining semicolons joining independent clauses and split them
  into separate sentences for consistency

index.mdx, quickstart.mdx, input-and-editing.mdx, and shell-commands.mdx
are still TODO-only placeholder stubs (no drafted prose yet), so there
was nothing to style-review there.

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

rachaelrenk commented Aug 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review feedback addressed

I reviewed and left comments file by file. Worked with an agent to go through each comment file by file and resolved the threads (84 of 85). Summary below, with individual replies left on threads that needed explanation rather than a straightforward suggestion.

Comments addressed by file:

  • agent-conversations.mdx — 27
  • cloud-and-orchestration.mdx — 21
  • configuration.mdx — 21
  • models-and-usage.mdx — 8
  • permissions-and-profiles.mdx — 8
  • reference.mdx — 1 (see holistic pass below)

Recurring fixes applied throughout:

  • Removed unnecessary colons/semicolons joining independent clauses, splitting them into separate sentences
  • Reworded vague or UI-documenting passages (e.g. describing hint text that isn't valuable) down to the useful mechanic
  • Made bulleted lists consistent (bold term + dash + description)
  • Trimmed wordy passages and cut information that didn't add reader value
  • Restructured configuration.mdx's settings-editing content into a clearer "Edit settings" section with three method-based subsections, and reworked cloud-and-orchestration.mdx's "Resume cloud conversations" section into an explicit two-option layout

Screenshots: Added real screenshots to cloud-and-orchestration.mdx (Agents: tab bar) and configuration.mdx (statusline with credit usage, context window usage, and task-list chips enabled). Both were captured live — built warp-tui-dev from warpdotdev/warp and ran an actual multi-agent orchestration / a live session via the tui-verify-change workflow, not mocked.

Accuracy fixes found along the way: While capturing the statusline screenshot, verified the statusline defaults directly against crates/warp_tui/src/terminal_session_view/statusline.rs and app/src/settings/ai.rs on warp's master. Found and fixed two bugs: "Working directory" was missing from the default-items list (it's on by default, not something you "also add"), and the doc didn't note that enabling "Git branch status" replaces the plain "Git branch" chip rather than showing both.

Holistic pass: After the comment-by-comment pass, did a second top-to-bottom read of the whole PR applying the same rubric, since only reference.mdx:9 had been directly commented on there. Fixed a grammar issue and 8 more mid-sentence colons/semicolons across reference.mdx and the already-reviewed files that the line-specific comments hadn't caught. index.mdx, quickstart.mdx, input-and-editing.mdx, and shell-commands.mdx are still TODO-only placeholder stubs (per the internal launch plan, they're owned by other page-bundle work), so there was nothing to review there yet.

Left open: The "Oz Platform" naming comment on cloud-and-orchestration.mdx — reworded this instance to sidestep the ambiguous phrase, but the underlying vars.ts gap (whether a dedicated var is needed for that exact phrase) is a broader product/marketing naming decision, so I left that thread unresolved rather than deciding it unilaterally.

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

@rachaelrenk @oz-agent
docs: crop and highlight the CLI screenshots for clarity
8680705 
Both screenshots previously showed the full 120x40 terminal window,
making it unclear which part was the actual subject. Cropped each to
the relevant region and added a highlighted border around the exact
row being documented:
- tui-agents-tab-bar.png: cropped to the top strip (bar + one line of
  context below); highlighted the Agents: tab bar row
- tui-statusline.png: cropped to the bottom strip (last transcript
  line, input box, statusline); highlighted the statusline row

Co-Authored-By: Oz <oz-agent@warp.dev>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rachaelrenk rachaelrenk rachaelrenk left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

cla-signed

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@hongyi-chen @rachaelrenk