SSH/Warpify docs information-architecture reframe (GROW-6121)

.agents/specs/GROW-6121-ssh-warpify-ia-reframe.md

@@ -0,0 +1,68 @@
+*Spec: SSH/Warpify docs information-architecture reframe*
+
+_Ticket: [GROW-6121](https://linear.app/warpdotdev/issue/GROW-6121/sshwarpify-docs-information-architecture-reframe). This is the carved-out other half of [GROW-6086](https://linear.app/warpdotdev/issue/GROW-6086/update-terminal-docs) (see [PR #595](https://github.com/warpdotdev/docs/pull/595), Follow-ups). Linear was unreachable factory-wide during the initial spec-alignment round; the ticket was created once connectivity was restored, after the requester had already approved the spec._
+
+== PRODUCT ==
+
+*Summary:* PR #595 deliberately left four pages under `src/content/docs/terminal/` untouched, calling the SSH/Warpify information architecture "a separate information-architecture decision pending with the requester." This spec resolves that decision: it tightens the framing of already-dead legacy content, removes a content duplication between two pages, demotes a fallback page out of primary navigation while keeping it linkable at the point of need, and fixes wording on two settings that no longer do anything. All five decisions below were confirmed with the requester (Rachael Renk) via a structured alignment round; see *Open questions resolved*.
+
+*Key design choices:*
+1. Treat "SSH Legacy" (`ssh-legacy.mdx`, the ControlMaster-based wrapper) and "tmux-based Warpification" (a section inside `ssh.mdx`) as two unrelated mechanisms that happen to share the word "legacy" — the fix for each is different (one is demoted-but-alive, the other is dead and gets a historical note).
+2. Deduplicate the SSH feature-support list by having `ssh.mdx` link to `code/ssh-feature-support.mdx` as the single source of truth instead of repeating the full bullet list.
+3. Reduce `warpify/index.mdx`'s three co-equal numbered items to two, nesting the fallback under SSH, to match the product model where SSH Legacy is a fallback state of SSH, not a sibling feature.
+
+*Behavior* (numbered, testable invariants from the reader's view):
+1. A reader on `ssh.mdx` who reads the "Legacy: tmux-based Warpification" section comes away understanding tmux-based Warpification no longer exists in the product today (not that it's merely deprecated or scheduled for future removal).
+2. A reader who lands on `ssh.mdx`'s Requirements section and hits a fallback condition (unsupported host, or `ssh_extension_install_mode` set to `never_install`) can reach `ssh-legacy.mdx` via exactly one link in that section.
+3. `ssh-legacy.mdx` no longer appears in the Warpify sidebar navigation, but remains reachable via direct link/URL and continues to render normally.
+4. A reader on `ssh.mdx` gets a short, accurate summary of what the SSH extension unlocks, with `code/ssh-feature-support.mdx` as the one place that carries the full, detailed feature matrix (no full duplicate list on `ssh.mdx`).
+5. A reader on `warpify/index.mdx` sees SSH Legacy presented as a nested fallback under SSH, not as a third co-equal item.
+6. A reader of `all-settings.mdx`'s `enable_legacy_ssh_wrapper` and `use_ssh_tmux_wrapper` entries understands that setting either key in `settings.toml` today has no effect on Warp's behavior, not just that a newer alternative exists.
+
+== TECH ==
+
+*Context:* All four pages are static Astro Starlight `.mdx` content under `warpdotdev/docs`, `src/content/docs/terminal/`. No code changes; this is a content-only, single-repo (`warpdotdev/docs`) change. Relevant current state (docs repo @ `719c27ab170f6917fd7701ce9883ff37c3bf8d6c`, warp repo @ `b7ec0fc5572fb085ea1ac7837fc4c7ff1addb64b`):
+- `warpdotdev/docs/src/content/docs/terminal/warpify/ssh.mdx` — has a "## Legacy: tmux-based Warpification" section (a `:::caution` block saying the flow "will eventually be removed"), a "## What you get over SSH" section with an 11-item bullet list that duplicates `code/ssh-feature-support.mdx`, and a Requirements section that describes fallback conditions (unsupported glibc/host, `ssh_extension_install_mode`) without linking to `ssh-legacy.mdx`.
+- `warpdotdev/docs/src/content/docs/terminal/warpify/ssh-legacy.mdx` — accurate, up to date (per PR #629); no content changes needed, only a sidebar-visibility change.
+- `warpdotdev/docs/src/content/docs/terminal/warpify/index.mdx` — a flat numbered list: 1. Subshells, 2. SSH, 3. SSH Legacy.
+- `warpdotdev/docs/src/content/docs/terminal/settings/all-settings.mdx` (`## Warpify` > `### SSH`) — `enable_legacy_ssh_wrapper` and `use_ssh_tmux_wrapper` entries read "Deprecated in favor of X," implying they still do something.
+- `warpdotdev/docs/src/content/docs/code/ssh-feature-support.mdx` — not in this PR's scope (outside the four carved-out files); already the more detailed/canonical feature matrix, and `ssh.mdx` already links to it once at the end of "What you get over SSH." No changes planned to this file.
+- Product source confirming the tmux removal (`warp` repo): `app/src/terminal/warpify/settings.rs:99-108` (`UseSshTmuxWrapper`, retained only for one-time migration; the `WarpifySettingsChangedEvent::UseSshTmuxWrapper` arm at line 350 is a no-op; the only reads of `.value()` are lines 386-392 inside `register`, the migration itself) and `app/src/terminal/view/ssh_tmux_deprecation_banner.rs:25-26` (shipped banner text: "The tmux option has been removed.").
+- Product source confirming `ssh-legacy.mdx`'s wrapper is unrelated to tmux and still live: `app/src/terminal/view/ssh_remote_server_choice_view.rs:1-4` (module doc: "...or continue without installing (falling back to the existing ControlMaster warpification path)"); `app/src/settings_view/warpify_page.rs:692-744` (`reuse_existing_control_master` toggle still rendered live in the SSH settings category).
+- Sidebar-hiding mechanism already used in this repo for an analogous legacy page: `terminal/input/universal-input.mdx:1-8` uses Starlight's native `sidebar:\n  hidden: true` frontmatter plus a `:::caution` banner pointing to the replacement — the same pattern this spec reuses for `ssh-legacy.mdx` (which already has an equivalent `:::note` banner; only the `sidebar: hidden` frontmatter needs adding).
+
+*Design alternatives:*
+- **Tmux content (delete vs. rewrite vs. keep):** Rewrite as a short historical note (chosen, per requester). Deleting outright removes a signpost for long-time users searching for their old tmux config; keeping the current wording actively misleads readers that it's still functional or pending removal.
+- **`ssh-legacy.mdx` placement (standalone-hidden vs. fold into `ssh.mdx` vs. keep in primary nav):** Standalone page, hidden from the sidebar via `sidebar: hidden`, linked once from `ssh.mdx`'s fallback description (chosen, per requester). Folding it into `ssh.mdx` as a subsection was considered but rejected — the page is long enough (troubleshooting section, its own screenshots) that inlining it would bloat `ssh.mdx`; keeping it in primary nav overstates it as a co-equal alternative to the extension.
+- **Feature list duplication (trim `ssh.mdx` vs. trim `ssh-feature-support.mdx` vs. keep both):** Trim `ssh.mdx` to a short summary, since `ssh-feature-support.mdx` is already the more detailed and better-organized version (it also correctly splits "works without extension" vs. "requires extension," which `ssh.mdx`'s current list does not) (chosen, per requester).
+- **Overview page structure (nest vs. keep flat vs. other):** Nest SSH Legacy under SSH (chosen, per requester) rather than keep the flat three-item list, since SSH detection and generic subshell detection are separate code paths (`SshWarpifyCommand::matches` in `app/src/terminal/ssh/util.rs` vs. `SUBSHELL_COMMAND_REGEXES` in `app/src/terminal/warpify/settings.rs`) and "SSH Legacy" is a fallback state of "SSH," not a sibling detection mechanism.
+
+*Proposed changes* (all in `warpdotdev/docs`, `src/content/docs/terminal/`):
+
+1. **`warpify/ssh.mdx` — rewrite the tmux section.** Replace the `## Legacy: tmux-based Warpification` section's `:::caution ... :::` block with plain prose (no callout — this is now a historical FYI, not an actionable caveat) stating plainly that tmux-based Warpification was removed in favor of the SSH extension described on the page, with no "will eventually be removed" hedging. Keep the `##` heading so the anchor/FAQ cross-reference structure is undisturbed.
+
+2. **`warpify/ssh.mdx` — trim the feature list.** Replace the `## What you get over SSH` section's 11-item bullet list with a short (2-4 sentence) summary naming a few headline features (file tree, code editor, code review, codebase indexing) and pointing to `code/ssh-feature-support.mdx` as the definitive breakdown up front, rather than only as a trailing "for a full breakdown" sentence. Keep the section heading, the screenshot, and the existing "Once the SSH extension is installed..." lead-in sentence pattern.
+
+3. **`warpify/ssh.mdx` — add one link to the legacy wrapper.** In the Requirements section, add a single trailing sentence (after the requirements bullet list, or appended to the closing `:::note`) stating that when the extension can't install (unsupported host) or `ssh_extension_install_mode` is set to `never_install`, Warp falls back to the [legacy SSH wrapper](/terminal/warpify/ssh-legacy/). This is the only new link to `ssh-legacy.mdx` added anywhere in this change — do not add others.
+
+4. **`warpify/ssh-legacy.mdx` — hide from primary nav.** Add `sidebar:\n  hidden: true` to the frontmatter (same pattern as `terminal/input/universal-input.mdx`). No body content changes — the page is already accurate and already carries a `:::note` pointing back to `ssh.mdx`.
+
+5. **`warpify/index.mdx` — nest SSH Legacy under SSH.** Change the numbered list from three co-equal items (Subshells, SSH, SSH Legacy) to two (Subshells, SSH), with SSH Legacy mentioned as a nested sub-bullet/sentence under the SSH item (e.g. "including a legacy fallback wrapper for hosts or settings that skip the extension"), linking to `/terminal/warpify/ssh-legacy/`. Leave the `## Subshells` and `## SSH` body sections (with their `DemoVideo` embeds) as-is — only the top numbered list changes.
+
+6. **`terminal/settings/all-settings.mdx` — explicit "no effect" wording.** In the `[warpify.ssh]` section, reword the `enable_legacy_ssh_wrapper` and `use_ssh_tmux_wrapper` bullets so each states plainly that the setting has no effect on current behavior and is retained only for a one-time migration, rather than just "Deprecated in favor of X." Do not change `use_ssh_tmux_wrapper`'s or `enable_legacy_ssh_wrapper`'s `toml_path`, type, or default columns — only the description text.
+
+*Open questions resolved:*
+- All five IA decisions above were confirmed with the requester (Rachael Renk) in a structured alignment round relayed through the foreman on the originating thread (`C09BVK0PL3Y` / `1787862877.099789`): tmux section → rewrite as historical note; `ssh-legacy.mdx` → standalone, hidden from primary nav, linked exactly once from `ssh.mdx`'s fallback-conditions paragraph; feature list → trim `ssh.mdx`, link out to `ssh-feature-support.mdx`; overview page → nest SSH Legacy under SSH; deprecated settings wording → make "no effect" explicit for both.
+- The original PR #595 follow-up note referenced "five IA questions" but recorded only three by name ("tmux vs. extension model, legacy content scope, `ssh-feature-support.md` scope, etc.") and the exact original wording could not be located in any durable record (GROW-6086's merged PRs, PR #595's review threads, or Slack history). The five questions in this spec were independently re-derived from the current docs and product source rather than recovered verbatim, per the task brief's instruction, and cover the same three named topics plus two more (overview page structure, deprecated-settings wording).
+- Exact wording for items 1, 2, 3, and 6 above (the tmux historical note, the feature-summary paragraph, the fallback-link sentence, and the settings description text) is left to the implementer to draft in the repo's established voice (see `AGENTS.md` — plain declarative sentences, no marketing language, "define, show, link"), since the requester approved the structural decisions, not literal copy.
+
+*Validation & verification criteria* (must ALL pass before merge):
+1. `npm run build` passes — verifies behavior invariants #1-6 (Astro build catches broken frontmatter, broken internal links, and MDX syntax errors).
+2. `npm run typecheck` — 0 new errors/warnings introduced by this change.
+3. `python3 .agents/skills/check_for_broken_links/check_links.py --internal-only` — 0 broken links, specifically confirming the new `ssh.mdx` → `ssh-legacy.mdx` link (item 3) and the `warpify/index.mdx` → `ssh-legacy.mdx` link (item 5) resolve; verifies invariant #2 and #5.
+4. `python3 .agents/skills/style_lint/style_lint.py --all` — introduces no new style_lint issues in the four touched files (compare before/after issue counts scoped to these paths); the tmux rewrite in particular must not introduce a new callout where the style guide prefers plain prose (see `AGENTS.md` → Callouts and hints).
+5. Manual/visual check that `ssh-legacy.mdx` no longer appears in the rendered Warpify sidebar navigation after `npm run build` / `npm run dev`, while `https://docs.warp.dev/terminal/warpify/ssh-legacy/` (or the local dev equivalent) still renders the page directly — verifies invariant #3. This is a static-site content check (no `computer_use` required — grep the built sidebar data or navigate `npm run dev` locally) rather than a Warp-client UI check, since nothing in the Warp app itself changes.
+6. Diff review confirms `code/ssh-feature-support.mdx` is untouched (out of scope) and `ssh.mdx`'s trimmed section still links to it exactly once, near the top of the section — verifies invariant #4.
+7. Diff review confirms exactly one new link to `/terminal/warpify/ssh-legacy/` was added in `ssh.mdx` (Requirements section) and none elsewhere in the four touched files — verifies invariant #2 and the "do not scatter additional links" constraint from the alignment round.
+8. Diff review confirms the `all-settings.mdx` changes are description-text-only for `enable_legacy_ssh_wrapper` and `use_ssh_tmux_wrapper` (no type/default/toml_path changes) — verifies invariant #6.
+9. `python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --check-paths --check-commands --check-format --warp ../warp` — 0 new issues (no UI-reference or settings-path claims are being added or changed in a way that could go stale; this is a regression guard, not a new check for this PR).

src/content/docs/terminal/settings/all-settings.mdx

@@ -494,8 +494,8 @@ Settings for Warp features in SSH sessions and subshells.
 **Section**: `[warpify.ssh]`
 
 * `enable_ssh_warpification` — Whether to enable Warp features in SSH sessions. Type: boolean. Default: `true`.
-* `enable_legacy_ssh_wrapper` — Deprecated in favor of `enable_ssh_warpification`. Type: boolean. Default: `true`.
-* `use_ssh_tmux_wrapper` — Deprecated in favor of the [SSH extension](/terminal/warpify/ssh/). Type: boolean. Default: `false`.
+* `enable_legacy_ssh_wrapper` — Has no effect on Warp's current behavior; retained only for a one-time migration to `enable_ssh_warpification`. Type: boolean. Default: `true`.
+* `use_ssh_tmux_wrapper` — Has no effect on Warp's current behavior now that tmux-based Warpification has been removed in favor of the [SSH extension](/terminal/warpify/ssh/); retained only for a one-time migration. Type: boolean. Default: `false`.
 * `reuse_existing_control_master` — Whether the legacy SSH wrapper attaches to an existing SSH `ControlMaster` for the destination host instead of always creating its own. Type: boolean. Default: `false`.
 * `ssh_extension_install_mode` — Controls SSH extension installation behavior. Type: string. Default: `"always_ask"`. Options: `"always_ask"` (always prompt before installing), `"always_install"` (auto-install and connect without prompting), `"never_install"` (fall back to the legacy, wrapper-only SSH warpification).
 * `ssh_hosts_denylist` — SSH hosts that should not trigger the warpification prompt. Type: array of strings. Default: `[]`.

src/content/docs/terminal/warpify/index.mdx

@@ -7,8 +7,7 @@ description: >-
 import DemoVideo from '@components/DemoVideo.astro';
 
 1. [Subshells](/terminal/warpify/subshells/), Warp supports enabling Warp features in subshells for bash, zsh, and fish.
-2. [SSH](/terminal/warpify/ssh/), Warp's SSH extension brings the file tree, code editing, code review, and reliable completions to remote macOS and Linux hosts.
-3. [SSH Legacy](/terminal/warpify/ssh-legacy/), Warp supports a legacy wrapper that enables Warp features in remote (SSH) sessions.
+2. [SSH](/terminal/warpify/ssh/), Warp's SSH extension brings the file tree, code editing, code review, and reliable completions to remote macOS and Linux hosts, including a [legacy fallback wrapper](/terminal/warpify/ssh-legacy/) for hosts or settings that skip the extension.
 
 ## Subshells
 

src/content/docs/terminal/warpify/ssh-legacy.mdx

@@ -3,6 +3,7 @@ title: Legacy SSH wrapper
 description: >-
   Use the legacy SSH wrapper as a fallback when skipping the SSH extension or
   when it can't run on a remote host.
+topic: terminal
 ---
 import DemoVideo from '@components/DemoVideo.astro';