From 2b981359ea3f0655e4fe99d014c5d1592af999b3 Mon Sep 17 00:00:00 2001
From: Nicolas Marchildon <nicolas.marchildon@mobilityhouse.com>
Date: Fri, 29 May 2026 19:36:12 -0400
Subject: [PATCH] doc: add cross-workspace targeting note for
 send/send-key/read-screen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

These commands default --workspace to $CMUX_WORKSPACE_ID. When targeting
a surface outside the caller's workspace, omitting --workspace produces
the misleading error 'Surface is not a terminal' — the surface exists
and is a terminal, but cmux resolves it in the wrong workspace context.
---
 skills/cmux-workspace/references/commands.md | 2 ++
 skills/cmux/references/panes-surfaces.md     | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/skills/cmux-workspace/references/commands.md b/skills/cmux-workspace/references/commands.md
index ff91b9f321..f03426a412 100644
--- a/skills/cmux-workspace/references/commands.md
+++ b/skills/cmux-workspace/references/commands.md
@@ -66,6 +66,8 @@ cmux send-key --surface "$CMUX_SURFACE_ID" enter
 cmux read-screen --surface "$CMUX_SURFACE_ID"
 ```
 
+**Cross-workspace targeting:** `send`, `send-key`, and `read-screen` resolve `--workspace` from `$CMUX_WORKSPACE_ID`. When targeting a surface outside the caller's workspace, you must pass `--workspace` explicitly. Omitting it produces the misleading `Error: invalid_params: Surface is not a terminal`.
+
 ## Sidebar Metadata
 
 ```bash
diff --git a/skills/cmux/references/panes-surfaces.md b/skills/cmux/references/panes-surfaces.md
index c5c4b0273e..5882363411 100644
--- a/skills/cmux/references/panes-surfaces.md
+++ b/skills/cmux/references/panes-surfaces.md
@@ -35,3 +35,5 @@ cmux reorder-surface --surface surface:7 --before surface:3
 ```
 
 Surface identity is stable across move/reorder/split-off operations. Layout commands are focus-neutral by default; pass `--focus true` only when you want the moved or created surface selected.
+
+**Cross-workspace input:** `send`, `send-key`, and `read-screen` resolve `--workspace` from `$CMUX_WORKSPACE_ID`. When targeting a surface outside the caller's workspace, you must pass `--workspace` explicitly. Omitting it produces the misleading `Error: invalid_params: Surface is not a terminal`.