diff --git a/cmux-tui/docs/README.md b/cmux-tui/docs/README.md
index 046a56ee7c30..d68bb5bfa393 100644
--- a/cmux-tui/docs/README.md
+++ b/cmux-tui/docs/README.md
@@ -4,7 +4,7 @@
 
 ## Contents
 
-- [Getting started](getting-started.md): build prerequisites, local and headless runs, sockets, detach and attach.
+- [Getting started](getting-started.md): build prerequisites, local and headless runs, sockets, detach and attach, session isolation for products built on cmux-tui.
 - [Concepts](concepts.md): session tree, focus, collapse behavior, tab naming, smart split, terminals, and browsers.
 - [Keyboard](keyboard.md): prefix model, modeless Alt layer, default bindings, and `cmux-tui.json` key remapping.
 - [Mouse](mouse.md): clickable UI, drag reorder, resize, scrollbars, menus, selection, pointer shape, and dialogs.
diff --git a/cmux-tui/docs/getting-started.md b/cmux-tui/docs/getting-started.md
index 79b045909764..90a517fd57c0 100644
--- a/cmux-tui/docs/getting-started.md
+++ b/cmux-tui/docs/getting-started.md
@@ -86,6 +86,20 @@ $TMPDIR/cmux-tui-<uid>/<session>.sock
 
 The usual default is `$XDG_RUNTIME_DIR/cmux-tui-<uid>/main.sock` when `XDG_RUNTIME_DIR` is set, then `$TMPDIR/cmux-tui-<uid>/main.sock`, then `/tmp/cmux-tui-<uid>/main.sock`. `--session <name>` changes the final file name. `--socket <path>` bypasses the session-derived path. Server-started child processes receive both `CMUX_TUI_SOCKET` and legacy `CMUX_MUX_SOCKET` with the socket path.
 
+## Isolated products on top of cmux-tui
+
+A program that builds its own product on cmux-tui, such as an agent orchestrator or a test harness, must own a dedicated session. It must not share `main` or a person's interactive session. The session is the isolation unit: each session has its own control socket, workspace tree, and durable state subtree, so `server stop`, `session reset-state`, or a crash in one session never touches another.
+
+```bash
+cmux server start --session <product>-<instance> --headless
+cmux --session <product>-<instance> workspace create --name task-1
+cmux server stop --session <product>-<instance>
+```
+
+Put the product name and an instance discriminator in the session name, for example `firstmate-a1b2c3`. Two installations of one product then coexist on one machine without cross-matching each other's workspaces. Address every call with `--session <name>` or the exact `--socket` path, and store the typed resource IDs a mutation returns instead of resolving by display name later.
+
+The default config path is shared with the person's own cmux-tui and can enable a machine provider or key remaps the product does not expect. Point `CMUX_TUI_CONFIG` at a product-owned config file. Sessions already keep separate state subtrees under the platform state directory; pass `--state <path>` only when the product must keep its state out of the shared root entirely.
+
 ## Platforms and XDG
 
 cmux-tui supports macOS and Linux; Windows support via ConPTY is planned for phase 2. The TUI config path resolves `CMUX_TUI_CONFIG`, then legacy `CMUX_MUX_CONFIG`, then `$XDG_CONFIG_HOME/cmux/cmux-tui.json` or `~/.config/cmux/cmux-tui.json`. Existing `mux.json` files remain supported and are used when `cmux-tui.json` is absent.