@@ -368,6 +368,40 @@ which do expand.
368368Crush has preliminary support for hooks. For details, see
369369[the hook guide](./docs/hooks/).
370370
371+### Sharing a workspace across clients
372+
373+When Crush is run against a shared backend (for example two TUIs talking to
374+the same `crush serve`), clients are grouped into **workspaces** keyed by
375+their resolved `--cwd`. Two clients with the same `--cwd` join the same
376+underlying workspace, so they share the session list, message history,
377+permission queue, LSP, and MCP state.
378+
379+Joining is implicit: pointing a second client at the same working directory
380+attaches it to the existing workspace. Each new invocation, however, starts
381+in its own fresh session by default. To pick up the conversation another
382+client already has open, use the session manager (the session picker) and
383+select it. Sessions surface two signals there:
384+
385+- `IsBusy` is set while an agent turn is in flight for that session.
386+- `AttachedClients` reports how many clients are currently viewing it.
387+
388+A non-zero `AttachedClients` (often combined with `IsBusy`) is the cue that a
389+session is "in progress" on another client and joining it will mirror that
390+view live.
391+
392+The first client to create a workspace fixes its process-wide flags. In
393+particular, `--yolo` and `--debug` follow a **first-wins** rule: later
394+clients that arrive at the same `--cwd` with different values for those
395+flags do not change the running workspace. A debug log line is emitted
396+recording the mismatch, and the workspace keeps the flags it was created
397+with.
398+
399+A workspace lives as long as at least one client has an SSE event stream
400+open against it. When the last stream disconnects, the workspace is torn
401+down. There is a short grace window right after `POST /v1/workspaces` so a
402+client that has created the workspace but not yet opened its event stream
403+does not get reaped before it can attach.
404+
371405### Ignoring Files
372406
373407Crush respects `.gitignore` files by default, but you can also create a