docs: fix terminal docs factual issues + keybinding/link style pass, reconcile with main, settle key-chord casing (GROW-6086)

[warp-agent-staging]

Summary

Non-SSH half of the GROW-6086 terminal docs follow-up: the remaining factual issues (stale subshell defaults, dead/mislabeled Command Palette references, a pre-Ventura macOS path) plus a keybinding/link-text style pass across src/content/docs/terminal/, extended repo-wide in this rework pass. This rework also reconciles the branch with main (PR #629, the SSH half, merged underneath it) and settles the key-chord casing question the requester raised.

The SSH/Warpify reframe is deliberately out of scope for this PR. terminal/warpify/ssh.mdx, terminal/warpify/ssh-legacy.mdx, terminal/warpify/index.mdx, and the Warpify SSH section of terminal/settings/all-settings.mdx are untouched — that's a separate information-architecture decision pending with the requester.

Originating thread: https://warpdev.slack.com/archives/C09BVK0PL3Y/p1787780357018299

Related issues

GROW-6086 — Update Terminal docs

Changes

Commit 1 — factual fixes

• warpify/subshells.mdx — replaced the stale "by default" subshell-compatible command list with the actual SUBSHELL_COMMAND_REGEXES defaults from app/src/terminal/warpify/settings.rs (bash/zsh/fish, docker/podman run/exec, poetry shell, pipenv shell, aws-vault exec, flox activate, wsl on Windows). Removed gcloud compute ssh / eb ssh, which have no built-in regex. Also tightened the denylist reference to the exact live UI list name Denylisted commands (settings_view/warpify_page.rs).
• windows/global-hotkey.mdx — updated the pre-Ventura System Preferences path to System Settings, using the macOS Apple-icon menu-path convention.
• more-features/full-screen-apps.mdx — fixed the "Mouse Reporting" Command Palette entry casing to match the real dynamic action description ("Enable/Disable mouse reporting", lowercase) produced by ToggleSettingActionPair in settings_view/features_page.rs / settings_view/mod.rs.
• editor/vim.mdx — fixed the "Vim Keybindings" Command Palette reference to the real dynamic entry "Enable/Disable editing commands with Vim keybindings", and fixed the Settings toggle label to the current text "Edit code and commands with Vim keybindings" (VimModeWidget). "Exit Vim insert mode" was already correct.

Commit 2 — style pass

• Normalized legacy key-chord notation (CMD-P, SHIFT-CMD-C, CTRL-TAB, plus +/space-separated and Windows META variants) to the AGENTS.md convention across ~30 files: ⌘+P, ⌘+Shift+C, Ctrl+Tab, arrow symbols for Up/Down/Left/Right, and spelled-out named keys (Enter, Esc, Home, End, Page Up, Page Down, etc). Left literal shell/config strings and mouse-click terms (RIGHT-CLICK, TRIPLE-CLICK) untouched.
• editor/index.mdx — while normalizing the keybinding table, fixed two cells that had been corrupted into single elements during the docs migration: a Ctrl+K Cmd+Delete cell split into two alternatives, and a "start / end of line" row that had an erroneous extra Cmd+Down binding (verified against editor/view/mod.rs — Cmd+Down maps to a different action, moving to the bottom of the buffer).
• entry/yaml-workflows.mdx — replaced commands.dev used as bare link text with descriptive anchor text.

Commit 3 — review-driven fixes

A second review pass found the two-cell fix in editor/index.mdx above hadn't gone far enough, plus one more wording issue:

• windows/global-hotkey.mdx — current macOS System Settings shows a per-app toggle for Accessibility access, not a checkbox. Reworded the step accordingly.
• editor/index.mdx — rebuilt all three keybinding tables (macOS, Windows, Linux) row by row against editor/view/mod.rs, finding eight more defects beyond the two already fixed: a delete-vs-cut conflation for "everything to the right" (also present on Windows/Linux, where no true delete-only binding exists), delete-word bindings that duplicated the cut-word bindings on all three platforms, a non-Mac "clear selected lines" row with no matching binding, a mac "select everything left/right" row mislabeled (it's actually "select to line start/end", SelectToLineStart/SelectToLineEnd) with the equivalent Windows/Linux cells left empty, a non-Mac "move cursor to start/end of line" row using a mac-only binding (Linux Ctrl+E is actually a distinct "Emacs-style binding" hint, not cursor movement), and swapped word/subword navigation chords on Windows/Linux. Of ~20 rows per table, 10 were changed; the rest were confirmed correct against source and left unchanged.

Commit 4 — reconcile with main (PR #629)

Rebased/merged main into the branch to pick up PR #629 (the SSH half, merged underneath this PR). Two files conflicted:

• warpify/subshells.mdx — kept both sides: this PR's wsl (Windows only) bullet and main's gcloud compute ssh/eb ssh/doctl compute ssh bullet (recognized via the SSH-like command detection path added by docs(terminal): fix legacy SSH, settings, subshells, and hotkey docs #629, confirmed against app/src/terminal/ssh/util.rs's SshWarpifyCommand::matches — these commands aren't in SUBSHELL_COMMAND_REGEXES but are still subshell-compatible through a separate code path). Also kept main's docker run/podman run wording.
• windows/global-hotkey.mdx — kept main's literal-symbol punctuation keys (⌘+`, ⌘+., ⌘+~) over this PR's spelled-out ⌘+Backtick/⌘+Period/⌘+Tilde, matching the AGENTS.md ⌘+Shift++ precedent for punctuation keys (see the notation survey below for why literal symbols were kept generally). Merged both independent accessibility-toggle wording fixes. Also restored a missing `` (U+F8FF Apple icon) before the macOS menu path on the line I touched, per AGENTS.md's "preserving the Apple icon" note — it had been silently stripped on both sides of the merge.

Verified after resolving: nothing from this PR's Commits 1–3 was reverted, and nothing from main/#629 was dropped — the merge commit is additive on both files.

Commit 5 — repo-wide key-chord notation sweep

Per the requester's "make sure our docs follow these conventions" ask, extended the same key-chord normalization from src/content/docs/terminal/ to the rest of src/content/docs/: 21 pages across getting-started/, agents/, knowledge-and-collaboration/, code/, support-and-community/, and guides/ (full list in the two commits). Normalized legacy CMD-X/CTRL-X hyphenated notation and CMD + X spaced-plus-sign notation to the settled convention (title-case modifier names, + separator, ⌘ glyph on macOS, arrow symbols, spelled-out named keys). Left mouse-click terms (RIGHT-CLICK), literal shell/config strings, and keybinding config values untouched, per the requester's brief. src/content/docs/changelog/ was intentionally excluded — it's a frozen historical record, and both style_lint and validate_ui_refs already skip it by default. No bare-URL link text was found outside terminal/ during this pass, so there was nothing further to fix there.

Key-chord casing: survey and decision

The requester said they personally prefer CTRL+SHIFT+C (ALL CAPS) but asked for a survey of other developer tools to decide, not their stated preference. Surveyed:

• Editors/IDEs: VS Code, JetBrains (IntelliJ/WebStorm/CLion), Zed — all use title-case modifiers (Ctrl+Shift+P, ⌘⇧A, Cmd+P), never ALL CAPS.
• GitHub: docs consistently use Command+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux) — title case.
• Terminal-adjacent (tmux): internal binding syntax uses short lowercase prefixes (C-, M-, S-); in prose/man pages, chords are written Ctrl-b/C-b — never ALL CAPS.
• Style guides: Microsoft Writing Style Guide ("Key names, combinations, and sequences: Capitalize... Ctrl+Alt+Del"), Google's developer doc style guide ("spelled-out modifier keys", standard capitalization), and Apple Style Guide/HIG (Command-C, Shift-Command-Z, hyphen-separated word form; ⌘C for the glyph form) all mandate title case, never ALL CAPS.
• Outliers found: Vim's own :help docs are a known, long-standing exception that uses CTRL- in prose. Cloudflare's (unrelated) developer style guide explicitly recommends abbreviated ALL CAPS (CTRL + C). These are the only two data points favoring the requester's preference, against roughly a dozen tools/guides on the other side.

Decision: keep the current convention (title-case: Ctrl+Shift+C, not CTRL+SHIFT+C). This directly contradicts the requester's stated CTRL+SHIFT+C preference — the evidence overwhelmingly favors the guide's existing rule, so no change was made to AGENTS.md, .agents/references/, or style_lint. Note: style_lint does not currently have an automated check for key-chord casing at all (confirmed by reading style_lint.py), so there was no linter rule to update either way; the convention is enforced by AGENTS.md prose only.

Migration status (what survived vs. what this PR fixes)

Per the orchestrator's request, here's what changed between the original gitbook-era triage and the migrated Astro/Starlight repo:

• Already fixed by the migration: all 37 empty/generic image alts from the original triage count (0 remain in terminal/); the "here"/"this page" bare link text items (0 remain); Universal Input references (confined to the properly sidebar: hidden legacy page with a caution banner); denylist heading/wording in subshells.mdx (only the exact UI element name needed tightening); vim.mdx's "Exit Vim insert mode" casing.
• Still stale, fixed here: the subshell defaults list, the System Preferences path, the Mouse Reporting and Vim Keybindings Command Palette casing.
• New discovery, not in the original triage: two corrupted table cells in editor/index.mdx (see above) — a migration artifact, not something the original gitbook triage could have found since that content didn't exist in that form pre-migration.

Unverified claims

None — all UI labels, Command Palette entries, and Settings paths touched in this PR were verified directly against warp-internal/warp source (app/src/terminal/warpify/settings.rs, app/src/terminal/ssh/util.rs, app/src/settings_view/warpify_page.rs, app/src/settings_view/features_page.rs, app/src/settings_view/mod.rs, app/src/editor/view/mod.rs, app/src/search/command_palette/data_sources.rs).

One tooling note for reviewers: vim.mdx's "Enable/Disable editing commands with Vim keybindings" Command Palette reference still shows as unmatched by validate_ui_refs.py. This is a validator limitation, not a doc error — the entry is a dynamically-generated FixedBinding description (via ToggleSettingActionPair, app/src/settings_view/mod.rs), and the extraction script only parses static EditableBinding::new(...) calls. I traced the exact string through settings_view/features_page.rs → ToggleSettingActionPair::new("editing commands with Vim keybindings", ...) → format!("Enable {description_suffix}") to confirm it's correct.

Validation

• npm run build — passes.
• npm run typecheck — 0 errors, 0 warnings (7 pre-existing hints only, unrelated to this PR).
• python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --check-paths --check-commands --check-format --warp ../warp — 0 settings-path issues, 0 format issues repo-wide; 1 command-palette "issue" which is the known validator limitation described above (verified correct against source).
• python3 .agents/skills/check_for_broken_links/check_links.py --internal-only — 0 broken links (3918 internal links checked across 379 files).
• python3 .agents/skills/style_lint/style_lint.py --all — 1362 issues repo-wide, all pre-existing and outside the categories this PR addresses (callout density/consecutive, header-case, screenshot-width, tone, product-casing, deprecated-term, oz-term, unrecognized-term, link-anchor on unrelated pages). style_lint has no key-chord/casing check at all (confirmed by reading the script), so there is no linter category for the convention this PR enforces — it's AGENTS.md-prose-enforced only. Every page this PR touches was spot-checked and none introduce a new style_lint issue in a category the diff touches.
• Merge mergeability: branch merged cleanly with main (2 conflicts resolved, see Commit 4); final gh pr view mergeability check run before marking ready (see PR checks).

Follow-ups

• SSH/Warpify reframe — tracked as the other half of GROW-6086, pending the five IA questions posed to the requester (tmux vs. extension model, legacy content scope, ssh-feature-support.md scope, etc.).
• header-case (14+ flags) — reviewed by hand in the original terminal/ pass; all are false positives (established feature names or genuine proper nouns). No changes made.
• ui-backtick — file names in backticks, not UI elements; backticks are correct per the style guide. No changes made.
• screenshot-width (112+ flags repo-wide) — standardizing <figure> maxWidth values is a real but separate cleanup; out of scope here since it's unrelated to the factual/keybinding/link fixes this issue asked for, and the brief said not to touch screenshots.
• unrecognized-term (97+ flags repo-wide) — glossary-addition suggestions only, not errors.
• Other style_lint categories surfaced by --all (callout density, tone buzzwords, product-casing, deprecated-term, oz-term) are pre-existing and out of scope for this key-chord/factual-accuracy PR; not addressed here.

Rework changes (cycle 1)

Code review returned rework_needed with two findings. Both addressed:

1. [IMPORTANT] Missing Home/End row in terminal/editor/index.mdx Windows/Linux tables — Fixed. Added a Home / End row ("Move the cursor to the start / end of the line") to both tables, matching the macOS table's existing combined row. Verified against app/src/editor/view/mod.rs: editor_view:home/editor_view:end bind the bare home/end keys on Linux and Windows. This is distinct from the existing Shift+Home/Shift+End select-to-line-start/end row, which was already correct and untouched.

2. [IMPORTANT] terminal/editor/vim.mdx:22 Command Palette reference disputed as non-existent — Disagree, with source evidence; left as-is pending human review. The reviewer's claim conflicts with the original claim in this PR body. I re-traced the full call chain in /workspace/warp:

   • app/src/settings_view/features_page.rs:492-505 calls ToggleSettingActionPair::new("editing commands with Vim keybindings", ..., context, flags::VIM_MODE_CONTEXT_FLAG), and this call is pushed into toggle_binding_pairs, which is passed to ToggleSettingActionPair::add_toggle_setting_action_pairs_as_bindings(toggle_binding_pairs, app) at line 705 of the same file (i.e. it is not dead code / not filtered out).
   • app/src/settings_view/mod.rs:840-863: ToggleSettingActionPair::new's own doc comment states description_suffix "will be visible to the user, e.g. Enable {description_suffix} or Disable {description_suffix}", and builds descriptions.enable = format!("Enable {description_suffix}") — producing the exact string "Enable editing commands with Vim keybindings" quoted in the doc.
   • The same doc comment states context_prefix "should be Workspace to have the action pair display in the command palette." app/src/workspace/mod.rs:105 calls settings_view::init_actions_from_parent_view(app, &id!("Workspace"), ...) — confirming context_prefix for this specific pair actually is Workspace.
   • app/src/settings_view/mod.rs:897-973 (add_toggle_setting_action_pairs_as_bindings) builds FixedBinding::empty(descriptions.enable, ...) / descriptions.disable and calls app.register_fixed_bindings(enable_bindings) / (disable_bindings) — these are real, registered bindings, not discarded.
   • app/src/search/command_palette/data_sources.rs:43-44,113-116: the Command Palette's actions_data_source (CommandBindingDataSource) is built from the app's binding_source, which aggregates all registered bindings (both EditableBinding and FixedBinding), and is wired into the palette's Actions filter.

   This traces a complete, unbroken path from the exact doc string to a real registered Command Palette action. The reviewer's counter-evidence (VimModeWidget::search_terms() returning "vim mode keybindings" in the same file) is a different, unrelated mechanism — that's the fuzzy-match search string for the Settings page widget (found via Settings search), not the Command Palette action list. Both can and do coexist. I could not find any code path that filters this specific FixedBinding out of the Command Palette before display.

   Given this, I believe the original PR claim stands: validate_ui_refs.py's --check-commands static extractor genuinely cannot see this reference because it's assembled at runtime via format!() inside ToggleSettingActionPair, not a static EditableBinding::new("...") call the extractor's regex can parse (this exact class of miss is already acknowledged in validate_ui_refs.py's own _settings_toggle_phrases allowlist, which separately excludes "vim keybindings" from the extractor for the same reason). I have not changed vim.mdx or this PR body's original claim about it. validate_ui_refs --check-commands still reports this single reference as unmatched — flagging it explicitly here rather than silently leaving it, per the reviewer's own escalation path, so a human can make the final call with both sides' evidence in hand.

[vercel]

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

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

[warp-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 /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR updates Terminal docs to correct stale factual references and normalize shortcut/link formatting. Most changes are documentation-only cleanups, but the editor shortcut table now drops an existing Windows/Linux start/end-of-line shortcut while fixing other keybinding rows.

Concerns

• Windows and Linux no longer document the default Home / End start/end-of-line bindings in terminal/editor/, even though those bindings still exist in the Warp client.
• One added autosuggestions line still uses legacy all-caps key casing for END.

Security

No security-sensitive code, configuration, dependencies, or secrets are changed in this documentation-only diff.

Verdict

Found: 0 critical, 1 important, 0 suggestions

Request changes

Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz