docs: documentation quality sweep (typos, clarity, terminology)

[hongyi-chen]

Summary

A documentation quality copy-edit sweep across all 293 in-scope pages under src/content/docs/ (everything except guides/). Every page was read; 115 files needed changes.

Scope was deliberately narrow: typos, unclear wording, and terminology drift only. No pages were restructured, no content was added or removed, and no technical details, commands, URLs, prices, or version numbers were changed.

Note on how this sweep was produced

The sweep was first run against the previous docs home, warpdotdev/gitbook, producing ~500 verified fixes across 128 files. That repo is now archived and read-only, so the findings were re-verified against the current text here and applied to the live Astro content. A large share of the original defects had already been fixed during the GitBook to Astro port; only what still applied was carried over, plus new issues found while reading these files.

Fixes by type

1. Typos and spelling errors

Inverted meaning (highest-impact fix)

• terminal/editor/syntax-error-highlighting.mdx — the error-underlining caution read "Newly installed apps or newly created aliases will trigger error underlining until you open a new Warp session," which is the opposite of the intended behavior. The parallel syntax-highlighting caution directly above it correctly says "will not trigger." Added the missing "not."

Grammar and missing words

• terminal/more-features/accessibility.mdx — "filling up the onboarding survey" → "filling out"; "each command and output create a Block" → "creates"
• agent-platform/capabilities/codebase-context.mdx — "agents will still be able use terminal commands" → "able to use"
• knowledge-and-collaboration/teams.mdx — "authenticate you have access" → "authenticate that you have access"
• terminal/windows/index.mdx — "Split Panes ... allows you to divide" → "allow"
• terminal/appearance/text-fonts-cursor.mdx — "(vim mode) is active" → "are active"
• terminal/more-features/settings-sync.mdx — "settings ... becomes the default" → "become"; "Device specific" → "Device-specific"
• changelog/2026.mdx — "installation path into de Windows" → "into the Windows"

Punctuation

• Stray space before a period or closing paren: reference/cli/index.mdx (`/usr/local/bin` .), agent-platform/capabilities/agent-profiles-permissions.mdx (**Permissions** .), code/code-review.mdx ( `master` )), terminal/blocks/sticky-command-header.mdx (( e.g.)
• Missing terminal periods: platform/environments.mdx, terminal/entry/yaml-workflows.mdx (2), support-and-community/troubleshooting-and-support/known-issues.mdx, support-and-community/privacy-and-security/privacy.mdx (2 numbered steps), troubleshooting-login-issues.mdx (several numbered steps)
• Missing commas: support-and-community/plans-and-billing/pricing-faqs.mdx ("In addition**,** certain promo codes"), knowledge-and-collaboration/warp-drive/environment-variables.mdx, using-warp-offline.mdx
• Missing serial commas in the argument-naming rules in knowledge-and-collaboration/warp-drive/prompts.mdx and workflows.mdx
• Stray apostrophe: troubleshooting-login-issues.mdx — "other SSO providers**'**," → "other SSO providers,"
• Double space in a numbered list item: agent-platform/local-agents/interacting-with-agents/voice.mdx
• terminal/more-features/accessibility.mdx — "please**,** do not hesitate" → "please do not hesitate"

Sentence fragments

• known-issues.mdx — "...(#3366). Please try adding..." → "...(#3366), try adding..."
• troubleshooting-login-issues.mdx — two dangling "If ..." sentences that were missing their consequent clause, merged into complete sentences
• known-issues.mdx — "You may see a similar error your logs" → "error in your logs"

Third-party name casing

• terminal/comparisons/terminal-features.mdx — table header "iTerm" → "iTerm2"
• getting-started/supported-shells.mdx — "homebrew" → "Homebrew"

Malformed markdown

• terminal/more-features/notifications.mdx (3) and terminal/windows/global-hotkey.mdx (1) — restored the Apple logo character (U+F8FF) that had been stripped from macOS system menu paths, leaving them rendering as a bare >. This character is invisible in most editors, so it is easy to lose during edits; AGENTS.md documents both the requirement and the repair.

2. Awkward or unclear messaging

Passive to active voice

• agent-platform/capabilities/codebase-context.mdx — "we check if it is part of a Git repository" → "Warp checks whether it's part of a Git repository"
• knowledge-and-collaboration/warp-drive/notebooks.mdx — "will not be saved until" → "Warp does not save ... until you add"
• using-warp-offline.mdx — "Requiring all users ... is required to allow use of" → "All users ... must be online ... to use"

Comma splices and run-on sentences
Fixed in terminal/appearance/prompt.mdx (3), terminal/more-features/accessibility.mdx, terminal/more-features/full-screen-apps.mdx, terminal/more-features/notifications.mdx, terminal/entry/command-history.mdx, terminal/entry/synchronized-inputs.mdx, terminal/comparisons/performance.mdx, terminal/warpify/ssh-legacy.mdx, terminal/warpify/subshells.mdx, secret-redaction.mdx, quickstart.mdx, knowledge-and-collaboration/warp-drive/web.mdx, and others.

Hedging and ambiguous modals

• network-log.mdx — "You may also disable" → "You can also disable" (AGENTS.md prefers "can" over "may" for optional actions)

Dismissive and ableist filler removed (per AGENTS.md)

• "just": reference/cli/index.mdx, platform/integrations/quickstart.mdx, enterprise/enterprise-features/team-managed-keys-and-endpoints.mdx
• "simply" / "Simply": terminal/more-features/accessibility.mdx, code/overview.mdx, getting-started/supported-shells.mdx (2), network-log.mdx
• "easily": secret-redaction.mdx

Verbose phrasing tightened

• "in order for the agent to write back to repos" → "so the agent can write back to repos" (reference/cli/integration-setup.mdx)
• "is able to run" → "can run" (getting-started/quickstart/installation-and-setup.mdx); "is able to detect" → "can detect" (warp-drive/web.mdx)
• "will exclusively encompass" → "will only include" (terminal/entry/command-search.mdx, yaml-workflows.mdx, warp-drive/workflows.mdx)
• "you will not be able to save changes; you will need to check out" → "you can't save changes; check out" (prompts.mdx, workflows.mdx)

Verb/noun confusion

• "to login" → "to log in" (reference/cli/index.mdx, reference/cli/quickstart.mdx, agent-platform/capabilities/mcp.mdx, pricing-faqs.mdx, troubleshooting-login-issues.mdx — multiple)
• "to workaround" → "to work around"; "will fallback to" → "will fall back to"; "will only setup" → "will only set up"

First-person plural removed from procedural text

• "we recommend that you install" → "install" and "We support apt ..." → "Warp supports apt ..." (reference/cli/index.mdx)
• "We recommend creating AGENTS.md" → "Create AGENTS.md" (rules.mdx); "We recommend storing them" → "Store them" (skills.mdx)
• "see our [Privacy page] ... how we handle data" → "see the [Privacy page] ... how Warp handles data" (rules.mdx, active-ai.mdx, faqs.mdx, getting-started/faqs.mdx)
• "see our [Environment Setup]" → "see the [Environment Setup]" (platform/integrations/linear.mdx, ×2)
• "Our legacy Generate feature" → "The legacy Generate feature" (generate.mdx)

Marketing filler removed from image alt text

• codebase-context.mdx (×2) — "Easily track sync status..." → "showing sync status..." (AGENTS.md cites this exact string as an anti-pattern)

3. Tone and terminology drift

Keyboard shortcuts normalized to AGENTS.md format (backticks, + separator, first letter capitalized, arrow glyphs) — the largest single category, spanning most of terminal/**, agent-platform/**, code/**, and knowledge-and-collaboration/**:

• CMD-K → ⌘+K, CTRL-SHIFT-F → Ctrl+Shift+F, ALT-UP → Alt+↑, OPT-SPACE → ⌥+Space
• CMD + SHIFT + I → Cmd+Shift+I, Ctrl-G → Ctrl+G, CMD-ENTER → Cmd+Enter
• ENTER → Enter, esc → Esc, TAB → Tab, PAGE UP → Page Up, BACKSPACE → Backspace
• ⌘I → ⌘+I, ⌘⇧H → ⌘+⇧+H, ⌥⌘↩ → ⌥+⌘+↩ (missing separators)
• Spelled-out arrow keys UP/DOWN/LEFT/RIGHT → ↑/↓/←/→
• ⌘⇧+ → ⌘+Shift++ for the code review pane, matching the canonical example in AGENTS.md

Product name casing

• "agent mode" → "Agent Mode" (×4 in the privacy.mdx telemetry tables)
• "command palette" → "Command Palette" (×5)
• "codebase context" → "Codebase Context" (×14 across both telemetry tables)
• "A.I. Command Search" → "AI Command Search" (changelog/2022.mdx) — AGENTS.md: "AI", not "A.I."
• "Auto-Detection" → "Auto-detection" (rules.mdx), matching the glossary's "Auto-detection Mode"
• "AI conversations" → "Agent conversations" (code/overview.mdx)

Oz terminology (per the terms-to-avoid list in AGENTS.md)

• "Agent Modality" → "Terminal and Agent modes" (changelog/2026.mdx)
• "Oz agents" → "agents", "Oz cloud agent" → "cloud agent", "the Oz agent" → "the agent" (changelog/2026.mdx)

Heading sentence case (proper feature names preserved)

• platform/skills-as-agents.mdx — "How Skills become available" → "How skills become available"; "Suggested Skills" → "Suggested skills" (matches the lowercase "skill(s)" used in the body)
• privacy.mdx — "Exhaustive Telemetry Table" → "Exhaustive telemetry table"
• troubleshooting-login-issues.mdx — "How to get an auth token to login" → "to log in"

UI element formatting

• Quoted or backticked UI control names converted to bold across ~25 files, e.g. "Show sticky command header" → Show sticky command header, `Code review` → Code review, "Dedicated hotkey window" → Dedicated hotkey window, "Open in Warp" → Open in Warp, "Create Theme" → Create Theme
• Backticked menu paths converted to bold-per-segment: `System Preferences > Security & Privacy > Accessibility` → >System Preferences > Security & Privacy > Accessibility
• Checkbox verbs corrected per AGENTS.md: "Uncheck the 'Block all cookies' checkbox" → "Deselect Block all cookies"; "check the box on Open with Rosetta" → "Select Open with Rosetta"; "tick the checkbox" → "select the checkbox"
• `RIGHT-CLICK` (all caps, backticked as though a shortcut) → "right-click" in prose
• "Utilize the Command Palette" → "Use the Command Palette"

Bold-term-dash list format (* **Term** - Description) applied to term-and-explanation lists in index.mdx (4 lists), code/code-editor/file-tree.mdx, code/overview.mdx, warp-drive/notebooks.mdx, warp-drive/workflows.mdx, credits.mdx

Hyphenation

• "full screen apps" → "full-screen apps", "multiline" → "multi-line", "sign in methods" → "sign-in methods", "Device specific" → "Device-specific", "tmux powered" → "tmux-powered", "floating point" → "floating-point"

Deliberately left alone

Several plausible-looking issues were checked and intentionally not changed:

• Contents/MacOS/ — flagged by tooling as a "macOS" casing error, but this is the literal, case-sensitive macOS app-bundle directory name inside shell commands. Changing it would break the documented command.
• "Blocklist" / "block list" — refers to Warp's own UI concept (the list of terminal Blocks), not the allowlist/denylist security term.
• "Ambient Agents" in older changelog entries — the genuine product name at time of release. Historical changelog wording was left intact apart from objective typos.
• getting-started/keyboard-shortcuts.mdx — the exhaustive shortcut reference table uses CMD-D-style strings that mirror the keysets config format the page itself links to. Reformatting it would misrepresent the real config syntax.
• Command Palette entry names — where an instruction appeared to reference the wrong palette entry, it was left as-is rather than renamed to something unverifiable.
• Frontmatter title, sidebar.label, and description — not touched, to avoid changing page titles, navigation labels, or meta descriptions.
• Image alt text — no alt text was added where missing, and none was invented.

Flagged for follow-up (no changes made)

These look like genuine issues but are outside a copy-edit's remit:

1. privacy.mdx contains a fully duplicated "Exhaustive telemetry table" section — the table and surrounding content appear twice, back to back. Deduplicating is a structural change and needs an owner's decision.
2. plans-and-billing consistently uses lowercase "add-on credits" while AGENTS.md specifies "Add-on Credits". It is 100% consistent across 100+ instances in 6 files, which suggests an intentional rename that AGENTS.md has not caught up with rather than an error. Worth reconciling in the glossary.
3. platform/integrations/slack.mdx image alt text reads "Warpy is just an internal Slackbot, your Warp slackbot should be called Oz." That looks like an internal review note left in the alt attribute rather than an accessibility description.
4. "We recommend ..." is pervasive site-wide, not isolated. AGENTS.md prefers the imperative in procedural content. Only clearly procedural instances were changed; a full pass is a larger editorial decision.
5. terminal/entry/command-search.mdx uses H-TAB / P-TAB / A-TAB notation whose intended key sequence could not be verified.
6. agent-platform/local-agents/active-ai.mdx lists Ctrl+Enter for macOS and Alt+Shift+Enter for Windows/Linux, which differs from the pre-port values. Only the formatting was normalized; the key bindings were left untouched since the change may be intentional.

Verification

• npm run build passes: 355 pages built, identical to the baseline count on main.
• Scripted checks confirm, for every changed file: no link, image, or VideoEmbed URL target was altered; no unbalanced inline code spans or bold markers were introduced; ::: callout fence counts are unchanged; and no U+F8FF Apple logo characters were lost (the count rises from 2 to 6 because four stripped ones were restored).
• All changes are confined to src/content/docs/**. No config, sidebar, script, or asset files were touched.

---

Conversation: https://app.warp.dev/conversation/8c785a5c-cc53-4e89-835d-3e0f9e395fc8
Run: https://oz.warp.dev/runs/019fc6d9-fc48-7b3c-8d90-184993f0e014

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 3, 2026 10:11am