docs(cursor-bridge): Phase 3 — Docs consolidation

Autonomous decisions:
- Added global bridge as recommended path at top of workspace-header-routing.md
  — per-repo install stays as fallback sections A–B below
- Linked manual regression doc from remote-access.mdx local Cursor subsection

Signed-off-by: crimsonsunset <jsangio1@gmail.com>

Author: crimsonsunset

docs/guide/remote-access.mdx

@@ -15,6 +15,16 @@ By default, McpMux serves MCP on **loopback only** (`http://localhost:45818/mcp`
 
 Local and remote MCP share the same gateway process. Remote clients use your **Public gateway URL**; local clients can keep using `localhost`.
 
+### Local Cursor: global bridge vs direct HTTP
+
+On the same machine, Cursor can connect via a **global** `~/.cursor/mcp.json` entry
+that spawns `npx mcp-remote` with `${workspaceFolder}` in the bridge args — no
+per-repo config files. Generate the snippet from **Connections → Global Cursor
+setup** in the desktop app. See
+[Cursor workspace bridge (manual test)](/docs/manual/cursor-workspace-bridge) for
+verification steps. The per-repo header install (Workspaces → Connect apps) remains
+the fallback when `npx` is unavailable.
+
 ## Recommended Layout
 
 Use **two hostnames** — one for MCP traffic, one for the admin UI:

docs/manual/cursor-workspace-bridge.md

@@ -0,0 +1,72 @@
+# Manual test — global Cursor bridge via `mcp-remote`
+
+Regression check for the global `~/.cursor/mcp.json` bridge (see
+[`cursor-workspace-routing-bridge` planning doc](../planning/cursor-workspace-routing-bridge.md)).
+
+This path replaces per-repo `.cursor/mcp.json` header installs for Cursor by
+routing through `npx mcp-remote` with `${workspaceFolder}` in the bridge args.
+
+## Prerequisites
+
+- `pnpm dev:admin` (or production McpMux) with gateway on `localhost:45818`.
+- Node.js / `npx` available (for `mcp-remote`).
+- Two real workspace folders mapped to **different** FeatureSets in
+  **Workspaces** (e.g. `~/proj/alpha` and `~/proj/beta`).
+- Cursor installed.
+
+## 1. Generate the global config
+
+1. Open **Connections** in McpMux.
+2. In **Global Cursor setup (no per-repo files)**, click **Generate global config**.
+3. Copy the snippet and paste it into `~/.cursor/mcp.json` (replace any existing
+   `mcpmux` entry, or merge if you have other servers).
+4. Reload MCP in Cursor (**Settings → MCP → refresh**).
+
+**Expected:** Cursor connects via stdio (`npx mcp-remote`), not a direct HTTP URL.
+On first connect, McpMux may show **Name this machine** — approve it.
+
+## 2. Two-window routing
+
+1. Open folder A in one Cursor window, folder B in another.
+2. In each window, list mcpmux tools (or invoke `@mux`).
+
+**Expected:**
+
+- Window A sees only FeatureSet tools bound to folder A.
+- Window B sees only FeatureSet tools bound to folder B.
+- No cross-contamination (the bug when Cursor reports the wrong `roots`).
+
+## 3. Log verification
+
+Check the McpMux log (macOS:
+`~/Library/Application Support/com.mcpmux.desktop/logs/mcpmux.<date>.log`):
+
+- `[SessionRoots] pinned explicit workspace root from X-Mcpmux-Workspace header`
+  with the correct path per session.
+- `[FeatureSetResolver] resolved via WorkspaceBinding workspace_root=…` matching
+  each window's folder.
+
+## 4. Bridge flags sanity check
+
+Confirm the generated config includes:
+
+- `--allow-http` (gateway is loopback HTTP, not TLS).
+- `--header` with **no space** after the colon:
+  `X-Mcpmux-Workspace:${workspaceFolder}`.
+- `Authorization:Bearer ${MCPMUX_API_KEY}` with the key in `env.MCPMUX_API_KEY`.
+
+To verify `mcp-remote` accepts these flags outside Cursor:
+
+```bash
+npx -y mcp-remote http://127.0.0.1:45818/mcp --allow-http \
+  --header "X-Mcpmux-Workspace:/path/to/folder" \
+  --header "Authorization:Bearer mcpk_…"
+```
+
+The process should stay up and the gateway should log an incoming MCP session.
+
+## Fallback
+
+If `${workspaceFolder}` does not resolve correctly in your Cursor version, use the
+per-repo install path documented in
+[`workspace-header-routing.md`](./workspace-header-routing.md) section B.

docs/manual/workspace-header-routing.md

@@ -12,6 +12,22 @@ state toggle, and the install panel (see _Automated tests_ at the end). The
 steps below verify the end-to-end behavior that automation can't — a real
 client connecting through the gateway.
 
+## Recommended: global Cursor bridge (no per-repo files)
+
+For Cursor on the same machine as McpMux, prefer the **global bridge** over
+per-repo `.cursor/mcp.json` installs:
+
+1. **Connections → Global Cursor setup** — generate and copy the
+   `~/.cursor/mcp.json` snippet (uses `npx mcp-remote` with
+   `${workspaceFolder}` in bridge args).
+2. Paste into `~/.cursor/mcp.json`, reload MCP in Cursor.
+3. Follow the regression steps in
+   [`cursor-workspace-bridge.md`](./cursor-workspace-bridge.md).
+
+This avoids maintaining a `.cursor/mcp.json` + `.gitignore` entry in every
+repo. The per-repo install path below (sections A–B) remains a supported
+fallback when you cannot use `npx`/`mcp-remote`.
+
 ## Prerequisites
 
 - `pnpm dev` (desktop app + gateway) running.

docs/planning/cursor-workspace-routing-bridge.md

@@ -1,7 +1,7 @@
 # Cursor Workspace Routing via Global `mcp-remote` Bridge
 
 **Last Updated:** Jul 20, 2026
-**Status:** Phase 1 complete — GO for Phase 2
+**Status:** Complete (Phases 1–3 on `dev-rebased`)
 **Branch:** `dev-rebased`
 
 ### Phase 1 spike results (Jul 20, 2026)