docs: fix typos, unclear phrasing, and terminology drift

[hongyi-chen]

Summary

Repo-wide sweep of the documentation content for quality issues, using AGENTS.md as the reference. Every change is either a clear error or a clear inconsistency with the style guide. No pages were restructured, no content was added, and no meaning was changed.

Detection used the style_lint skill, codespell, and targeted scans for duplicated words, broken punctuation, hedging language, and deprecated terminology.

Changes

1. Typos, spelling, and mechanics

• Corrected incorrect articles: a SSH host → an SSH host, a MCP → an MCP server (privacy.mdx, mcp.mdx).
• Fixed external product names: Iterm/iterm → iTerm2, Wezterm → WezTerm, Voice Over → VoiceOver, Github → GitHub.
• Fixed Non exhaustive → Non-exhaustive and Tab related → tab-related.
• Removed stray spaces before punctuation (**Permissions** ., `ESC` .) and fixed the image-format list in images-as-context style pages.
• Fixed a comma splice in the Prompt Suggestions note and a missing sentence period in the Warp Drive web preference step.
• Fixed three sentence fragments in login troubleshooting and known issues (for example, ...when you click "Sign up" or "Sign in". Please go to... → a single complete sentence).

2. Awkward or unclear messaging

• Removed please from instructional and cross-reference sentences (please see → see, please refer to → see, Please note that → Note that). Politeness in support/contact sentences and inside example prompts was left untouched.
• Replaced may with can for optional actions, per the guide's preference (You may also use your mouse → You can also use your mouse, you may email → you can email).
• Removed hedging and nominalized phrasing: you should be able to understand → you can understand, you are able to click → you can click, You may be able to remediate this error by... → To remediate this error, try....
• Removed dismissive simply from shell setup, Code overview, git worktrees, and accessibility instructions.
• Rewrote three ungrammatical or vague sentences on the accessibility page (...easily check what was the command..., Warp announces stuff on its own, In short - it's related to how our UI Framework is currently implemented and that as of now...).
• Tightened one telemetry description that repeated itself (Agent Mode used and cited external sources that were used in its response).

3. Tone and terminology drift

• Applied feature-name casing per the glossary: agent mode → Agent Mode, command palette → Command Palette, codebase context → Codebase Context, git repositories → Git repositories. Most instances are in the telemetry tables in privacy.mdx and in changelog entries.
• Replaced the internal name Agent Modality with Terminal and Agent modes.
• Replaced ambient agent with cloud agent in telemetry descriptions (event names such as AmbientAgent.DispatchFailed and CLI.Execute.Agent.RunAmbient are unchanged).
• Replaced Oz agent/Oz agents with agent/agents in the software factory guides.
• Corrected two title-case headings to sentence case (Exhaustive Telemetry Table, Launch Configuration YAML Format).

Deliberately not changed

• blocklist / Blocklist — these refer to Warp's terminal block list UI, not a denylist, so the lint hits are false positives.
• MacOS in /Applications/Warp.app/Contents/MacOS/stable — a literal path inside the app bundle.
• agent mode / shell mode in the CLI docs — the CLI's two input modes are consistently lowercase as a pair on those pages.
• AI credits — this is one of the three documented credit buckets (AI, compute, platform), not the deprecated "AI credits" phrasing.
• sorce in Command Corrections — an intentional example of a misspelled command being corrected.
• Keyboard-shortcut formatting, image alt text, and screenshot widths — pre-existing lint findings outside the scope of this sweep.

Validation

• npm run build — 364 pages built, no errors.
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — 3443 internal links, 0 broken.
• python3 .agents/skills/style_lint/style_lint.py --all — product-casing dropped from 41 to 12 (remaining are the false positives listed above) and oz-term from 10 to 0, with no new findings in any category.

Note on the source repo

This sweep was originally requested against warpdotdev/gitbook, which is now archived and read-only, so the same fixes were applied to the corresponding pages in this repo.

Co-Authored-By: Oz [email protected]

Conversation: https://app.warp.dev/conversation/b801d751-24ee-4934-bece-a59c70b4b0a3
Run: https://oz.warp.dev/runs/019fd126-b20a-7318-80a3-cc7d72c87f37

This PR was generated with Oz.

[vercel]

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

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

[oz-for-oss]

@hongyi-chen

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 performs a documentation-wide copy-edit sweep for typos, punctuation, tone, and terminology consistency. I reviewed the attached annotated diff, PR description, and spec context; no approved spec context was present, and the diff does not introduce code or configuration with security impact.

Concerns

• No blocking correctness, documentation-structure, link, or security concerns found in the attached diff.

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]

LGTM!

[hongyi-chen]

Merge conflicts resolved

Merged main into this branch. Both conflicts were the same terminology change resolved two different ways:

File	This branch	main (#481)	Resolution
run-a-software-factory-in-the-cloud.mdx	Oz agent workers → agent workers	Oz agent workers → cloud agent workers	took main
set-up-a-software-factory.mdx	triggering Oz agents → triggering agents	triggering Oz agents → triggering cloud agents	took main

Both branches were removing the Oz agent prefix flagged by the terminology glossary; #481 just landed the more specific wording first. This branch's edits to those two files were fully superseded, so after the merge both guides match origin/main byte-for-byte.

Additional fix: telemetry generator was left out of sync

This PR renames ### Exhaustive Telemetry Table → ### Exhaustive telemetry table in privacy.mdx (correct per the sentence-case heading rule), but .agents/skills/release_updates/scripts/update_telemetry.py matched that heading as a literal string to find where the generated table begins:

marker = "\n### Exhaustive Telemetry Table"
index = content.find(marker)
if index == -1:
    return content.rstrip() + "\n"   # whole file becomes "intro"

With the rename, find() returns -1, so the next weekly release run would treat all 1321 lines as intro and append a third full copy of the ~625-row telemetry table. Verified against the branch:

PR branch:   marker found at index: -1   -> intro = 1321 lines (entire file)
origin/main: marker found at index: 58017 -> intro = 694 lines

Fixed by hoisting the heading into a single TELEMETRY_TABLE_HEADING constant used for both the marker and the emitted heading, so the two can't drift again.

As a bonus, this also self-heals a pre-existing duplicate: privacy.mdx on main already contains two telemetry tables (lines 70 and 696) — the first got sentence-cased by an earlier sweep, which broke the marker once before and caused the generator to append a second table. With the marker now matching the first heading, the next release run truncates there and emits a single table:

intro lines kept: 67
headings in regenerated file: ['### Exhaustive telemetry table']
duplicate table removed: True

Validation

• npm run build — 364 pages, no errors.
• python3 -m py_compile update_telemetry.py — passes.
• style_lint --changed — 167 issues across the 39 touched files, but only 5 fall on lines this PR changed, and all 5 are pre-existing bolded settings-path terms (**Active AI**, **Prompt Suggestions**, **Next Command**, **Privacy**, **Classic**) that are byte-identical to main. No new violations introduced.

I could not submit a formal approval — this token authenticates as @hongyi-chen, the PR author, and GitHub blocks self-approval. The existing approval from @rachaelrenk is still active and was not dismissed by these pushes.

This comment was generated with Oz.