Cross-platform docs: add macOS & Linux coverage (currently Windows-centric)

[a5af]

Goal: The docs are Windows-centric. Bring every user-facing and internals page up to the same standard on macOS and Linux as Windows — without regressing the Windows content.

Collaboration: two authors in parallel — asaf (macOS owner) and the Linux agent (Linux owner) — plus shared cross-cutting work. Claim an item by checking the box + leaving a comment so we don't double-edit a page. One owner per page; if a page needs a platform you can't verify, write the structure + a TODO(linux)/TODO(macos) cell and the other agent fills it in a follow-up.

Full living spec: specs/PLAN_CROSS_PLATFORM_DOCS_2026_05_30.md (in this repo).

---

Gold-standard pages to copy the pattern from (do NOT rewrite)

internals/platform-support.md (the hub everything links to) · internals/clipboard.md · security/update-model.md · security/trust-model.md · internals/debugging.md / internals/wrr.md (correct :::note[Windows-only] usage).

Accuracy caveat — verify against current agentmuxai/agentmux source

Several macOS/Linux behaviors changed recently; old "Windows-only" framing is partly stale:

• macOS floating-pane tear-off / redock / drag slide-back now work (#1182/#1185/#1186/#1194).
• The launcher now drives srv + host on macOS/Linux task dev (#1193) — updates the "launcher is Windows-only / Unix invokes host directly" claims.
• Window transparency still Windows-only; WRR still Windows-only (those pages are correct).

Writing patterns to standardize (proposed → see Workstream 0)

1. Per-OS command blocks, consistent order macOS · Windows · Linux.
2. Feature-availability via :::note[…-only today] with the per-OS roadmap stated inline + link to /internals/platform-support/. Never leave a platform unmentioned — "not yet" is information.
3. Paths: lead with ~/.agentmux/…, then give literal per-OS resolution (macOS ~/Library/Application Support/…, Windows %APPDATA%/%LOCALAPPDATA%, Linux ~/.agentmux/$XDG_*).
4. Concept one-liners naming all three: "named pipe (Windows) / Unix domain socket (macOS+Linux)", "Job Object / process group", "HWND / NSView / X11·Wayland surface".
5. Code-location callouts citing the real source + #[cfg] split.

---

Workstream 0 — Conventions & hub (SHARED, do first)

• [shared] CLAUDE.md — add a "Cross-platform writing guide" (the 5 patterns + chosen command order)
• [shared] decide/optionally build a PlatformMatrix availability component
• [shared] refresh internals/platform-support.md against current source (tear-off, redock, launcher-on-Unix-dev, drag slide-back); confirm it's the canonical hub

HEAVY

• [macOS] internals/building.md — arm64-vs-x86_64 detection + Homebrew specifics; re-verify launcher build now that it builds on Unix
• [Linux] internals/building.md — compositor/graphics deps, ninja-build, X11/Wayland
• [macOS] lan-discovery.md — macOS section (Gatekeeper / local-network permission; no Windows-Firewall prompt)
• [Linux] lan-discovery.md — Linux section (ufw/firewalld rules, SELinux)
• [either] internals/reducer-stack.md + internals/architecture.md — replace "named pipe / Win32 hooks" with the 3-way concept binding + an IPC-mechanism table; re-verify vs the now-cross-platform launcher

MODERATE

• [macOS] multi-instance.md — explain Job Object → macOS/Linux process-group equivalent; re-check the "tear a tab into a new instance — Windows only" claim (may now be partly available on macOS)
• [Linux] multi-instance.md — Linux process-isolation cell
• [macOS] installation.md — confirm .dmg/notarization wording is current; add Windows uninstall/upgrade + MSIX-vs-portable note
• [Linux] installation.md — confirm AppImage/.deb wording is current (glibc/FUSE)
• [either] internals/modal-system.md — cross-platform modal stacking over native panes
• [either] pane-types.md — expand taskbar-flash / dock-bounce / urgency-hint attention per OS

LIGHT

• [either] settings.md — Windows default shell (pwsh.exe/Git Bash) vs Unix /bin/bash for term:localshellpath
• [either] config.md — add a Windows shell-path example
• [either] quickstart.md — Cmd-vs-Alt keybinding callout (link keybindings.md)
• [macOS] browser-pane.md — Cocoa embedding note; [Linux] X11/Wayland embedding note (alongside the HWND detail)
• [either] glossary.md — add HWND, named pipe / Unix domain socket, Job Object / process group, Gatekeeper, AppImage
• [either] security/network-exposure.md — note Windows DACL alongside Unix 0600
• [either] internals/data-layout.md — per-OS literal path examples for the ~/.agentmux/ tree
• [either] keybindings.md — footnote on why Ctrl+P / Ctrl+Shift+Arrow stay Ctrl on macOS (verify vs app)

VERIFY-ONLY (likely no change — spot-check)

• getting-started.md, main-menu.md, window-appearance.md, internals/{wrr,clipboard,debugging,persistence,lan-discovery}.md, security/{trust-model,update-model,identity-credential-storage,data-sovereignty,reactive-event-bus}.md, index.mdx, user-guide.mdx

---

Process

• One branch per page/page-group: docs/xplat-<page>; small PRs; bump package.json per the repo review checklist; run npm run build and note the page count in the PR.
• Land Workstream 0 first so both authors build on the agreed conventions.

Done criteria

A macOS or Linux user can read install → quickstart → first-agent → features → troubleshooting end-to-end and never hit a Windows-only instruction without a labeled alternative or an explicit "not yet" note. Every :::note[…-only] links to /internals/platform-support/. Claims cite current agentmuxai/agentmux source.