docs: describe shared server MCC sessions

.skills/mcc-dev-workflow/SKILL.md

@@ -12,7 +12,7 @@ Use this skill when the task needs a real local server loop, not just code readi
 - Solution: `MinecraftClient.sln`
 - Runtime target: `.NET 10` / `net10.0`
 - Environment: Linux, macOS, or WSL with Java, tmux, python3, and dotnet available
-- Default server root: `${MCC_SERVERS:-$MCC_REPO/MinecraftOfficial/downloads}`
+- Default server root after `source tools/mcc-env.sh`: `${MCC_SERVERS:-<repo>/MinecraftOfficial/downloads}`
 - Default validation target when the user does not specify a version: `1.21.11`
 
 ## Console modes
@@ -34,6 +34,50 @@ Both modes support the same commands and input/output through `ConsoleIO.Backend
 - A server log line containing `Done (` means startup finished. It does not guarantee that RCON is ready on the first attempt. Retry early `mc-rcon` commands.
 - When instructions, docs, and code disagree, trust current code and current tool behavior first.
 
+## Shared server, isolated MCC sessions
+
+- `mc-*` commands operate on the shared local Minecraft server.
+- `mcc-*` commands operate on one MCC client session.
+- The default `session` is the current worktree name.
+- The default username is derived from `session`, unless you pass `--username`.
+- Session files live under `${TMPDIR:-/tmp}/mcc-debug/<session>/`.
+- `MCC_SERVERS` stays the shared server-root override.
+
+Keep shared servers running by default. Do not stop or reset them unless the user explicitly asks for that, or you need to switch server versions.
+
+Two worktrees can debug against one shared server like this:
+
+```bash
+# worktree A
+cd ~/Minecraft/Minecraft-Console-Client
+source tools/mcc-env.sh
+mc-start 1.21.11
+mcc-debug -v 1.21.11 --file-input
+
+# worktree B
+cd ~/Minecraft/Minecraft-Console-Client-foo
+source tools/mcc-env.sh
+mcc-debug -v 1.21.11 --file-input
+
+# from each worktree, mcc-* targets that worktree's default session
+mcc-state
+```
+
+If you want two MCC sessions from the same worktree, pass `--session NAME` explicitly.
+
+## tmpfs build mode
+
+Use this on machines with enough RAM when you want worktree-isolated builds outside the repo tree:
+
+```bash
+source tools/mcc-env.sh
+export MCC_BUILD_MODE=tmpfs
+mcc-build
+mcc-build-clean
+```
+
+`MCC_BUILD_MODE=tmpfs` redirects build output to `/dev/shm/mcc-build/<worktree>/` on Linux, or `${TMPDIR:-/tmp}/mcc-build/<worktree>/` if `/dev/shm` is unavailable.
+
 ## Preflight and reset
 
 Before scripted runs, especially on macOS or in a reused tmux environment:
@@ -58,9 +102,11 @@ Interactive shell:
 
 ```bash
 source tools/mcc-env.sh
+SESSION="$(_mcc_resolve_session)"
+USERNAME="$(_mcc_resolve_username "$SESSION")"
 mc-start 1.21.11
 mc-log 1.21.11 100
-mc-rcon "op CursorBot"
+mc-rcon "op $USERNAME"
 mc-stop 1.21.11
 ```
 
@@ -68,7 +114,7 @@ Non-interactive shell:
 
 ```bash
 tools/start-server.sh 1.21.11
-tools/mc-rcon.sh "op CursorBot"
+tools/mc-rcon.sh "op mcc_smoke_a"
 ```
 
 If the servers live outside the repo, set `MCC_SERVERS` before sourcing or invoking the tools:
@@ -104,16 +150,16 @@ mcc-debug -v 1.21.11 --file-input --no-build
 ### What mcc-debug.sh does
 
 1. Builds MCC (unless `--no-build`)
-2. Creates a clean temp config at `/tmp/mcc-debug/MinecraftClient.debug.ini` with CursorBot account, Terrain/Inventory/Entity enabled and noisy bots disabled
+2. Creates a clean temp config at `${TMPDIR:-/tmp}/mcc-debug/<session>/MinecraftClient.debug.ini`
 3. Ensures server is running (starts if not, waits for `Done (`)
-4. Launches MCC in the specified mode
+4. Launches MCC in a session-scoped tmux session and session-scoped log/input/pid files
 
 ### After launch
 
-- **FileInput mode**: drive MCC via `mcc-cmd "debug state"` or `echo "debug state" >> mcc_input.txt`
-- **Interactive/TUI mode**: attach with `tmux attach -t mcc-debug`, type commands directly
-- **Logs**: `tail -f /tmp/mcc-debug/mcc-debug.log` (FileInput mode only; TUI/interactive mode outputs to tmux)
-- **Server RCON**: `mc-rcon "op CursorBot"`, `mc-rcon "gamemode creative CursorBot"`
+- **FileInput mode**: drive MCC via `mcc-cmd --session smoke-a "debug state"`, or just `mcc-cmd "debug state"` from the same worktree
+- **Interactive/TUI mode**: attach with `tmux attach -t mcc-<session>`
+- **Logs**: `mcc-log-mcc --session smoke-a` or `tail -f "${TMPDIR:-/tmp}/mcc-debug/<session>/mcc-debug.log"`
+- **Server RCON**: grant op or gamemode to the username derived from that session
 
 ## Debug commands (in-game)
 
@@ -128,7 +174,7 @@ Prints a one-shot summary of MCC's internal state:
 ```
 === MCC Debug State ===
 Server:    localhost:25565
-Username:  CursorBot
+Username:  mcc_smoke_a
 Protocol:  774
 GameMode:  1
 Health:    20.0
@@ -152,18 +198,20 @@ For agents calling MCC commands programmatically:
 
 ```bash
 source tools/mcc-env.sh
-mcc-debug -v 1.21.11 --file-input --no-build
+SESSION="smoke-a"
+mcc-debug -v 1.21.11 --file-input --session "$SESSION" --no-build
 
 # Send commands:
-mcc-cmd "debug state"
-mcc-cmd "inventory player list"
-mcc-cmd "entity"
+mcc-cmd --session "$SESSION" "debug state"
+mcc-cmd --session "$SESSION" "inventory player list"
+mcc-cmd --session "$SESSION" "entity"
 
 # Check results:
-tail -20 /tmp/mcc-debug/mcc-debug.log
+mcc-log-mcc --session "$SESSION"
 
 # Stop:
-mcc-cmd "quit"
+mcc-cmd --session "$SESSION" "quit"
+mcc-kill --session "$SESSION"
 mc-stop 1.21.11
 ```
 
@@ -171,10 +219,11 @@ mc-stop 1.21.11
 
 ```bash
 source tools/mcc-env.sh
-mcc-debug -v 1.21.11
+SESSION="live-a"
+mcc-debug -v 1.21.11 --session "$SESSION"
 
 # In another terminal:
-tmux attach -t mcc-debug
+tmux attach -t "mcc-$SESSION"
 # Type commands directly in MCC console
 ```
 
@@ -192,22 +241,23 @@ TUI mode runs Consolonia full-screen in a tmux session. Key differences:
 
 ```bash
 source tools/mcc-env.sh
-mcc-debug -v 1.21.11 -m tui --no-build
+SESSION="tui-a"
+mcc-debug -v 1.21.11 -m tui --session "$SESSION" --no-build
 
 # Cannot use mcc-cmd (no FileInput); must use tmux send-keys:
-tmux send-keys -t mcc-debug "/debug state" Enter
+tmux send-keys -t "mcc-$SESSION" "/debug state" Enter
 
 # Read TUI screen:
-tmux capture-pane -t mcc-debug -p -S -30
+tmux capture-pane -t "mcc-$SESSION" -p -S -30
 
 # Stop:
-tmux send-keys -t mcc-debug Escape
+tmux send-keys -t "mcc-$SESSION" Escape
 ```
 
 **Caveat with tmux send-keys and Consolonia**: When sending text containing `/`, the Enter key may need to be sent separately:
 ```bash
-tmux send-keys -t mcc-debug "/inventory player list"
-tmux send-keys -t mcc-debug Enter
+tmux send-keys -t "mcc-$SESSION" "/inventory player list"
+tmux send-keys -t "mcc-$SESSION" Enter
 ```
 
 ## mcc-env.sh quick reference
@@ -226,26 +276,28 @@ After `source tools/mcc-env.sh`:
 | `mc-wait-stop VER [SEC]` | Wait for server shutdown, with force-kill fallback |
 | `mc-reset-test-env [--all|VER...]` | Reset shared tmux server state and stale pipes |
 | `mcc-build` | Build MCC |
-| `mcc-run [PORT]` | Run MCC classic+FileInput on port |
-| `mcc-tui [PORT]` | Run MCC TUI mode in tmux |
-| `mcc-cmd "CMD"` | Append command to mcc_input.txt |
-| `mcc-kill` | Kill MCC process and debug session |
+| `mcc-build-clean` | Clear the current worktree's build output |
+| `mcc-run [--session NAME] [--username NAME] [--port PORT]` | Convenience wrapper for `mcc-debug --file-input --no-build` |
+| `mcc-tui [--session NAME] [--username NAME] [--port PORT]` | Convenience wrapper for `mcc-debug -m tui --no-build` |
+| `mcc-cmd [--session NAME] "CMD"` | Append a command to one session's input file |
+| `mcc-kill [--session NAME]` | Kill one MCC process and session |
 | `mcc-debug [OPTS]` | One-step debug session (see above) |
-| `mcc-log-mcc` | Tail MCC debug log |
-| `mcc-state` | Send `debug state` and print last 30 log lines |
+| `mcc-log-mcc [--session NAME]` | Tail one MCC debug log |
+| `mcc-state [--session NAME]` | Send `debug state` and print the last 30 log lines |
 | `mcc-preflight [VER...]` | Verify Java, tmux, dotnet, python3, and server dirs |
 
 ## Temporary config recipe
 
 ```bash
 source tools/mcc-env.sh
-TEST_ROOT="${TMPDIR:-/tmp}/mcc-dev"
-CFG="$TEST_ROOT/MinecraftClient.1.21.11.ini"
-mkdir -p "$TEST_ROOT"
+SESSION="smoke-a"
+USERNAME="$(_mcc_resolve_username "$SESSION")"
+CFG="$(_mcc_session_root "$SESSION")/MinecraftClient.debug.ini"
+mkdir -p "$(_mcc_session_root "$SESSION")"
 bash "$MCC_REPO/.skills/mcc-integration-testing/scripts/prepare_offline_mcc_config.sh" \
   "$CFG" \
   "1.21.11" \
-  "CursorBot"
+  "$USERNAME"
 ```
 
 For TUI mode, also add:
@@ -259,14 +311,14 @@ MCC output should include:
 
 - `[MCC] Server was successfully joined.`
 
-Server output should include:
+Server output should include the session-derived username, for example:
 
-- `CursorBot joined the game`
+- `mcc_smoke_a joined the game`
 
 Basic command check:
 
 ```bash
-mcc-cmd "inventory player list"
+mcc-cmd --session smoke-a "inventory player list"
 ```
 
 If a scripted run fails before MCC joins, check for a harness problem before assuming a product regression. Missing `mcc.log`, a pre-join `Connection refused`, or a server that never reached `Done (` usually means shared-state cleanup or startup failed.
@@ -292,7 +344,7 @@ If a scripted run fails before MCC joins, check for a harness problem before ass
 - Legacy `1.8` and `1.8.9` servers may need `use-native-transport=false` in `server.properties` on some Linux environments.
 - For timing-sensitive work, do not trust wall-clock intuition. Use a real server run and capture evidence from logs or test scripts.
 - **TUI mode tip**: if the terminal becomes unresponsive after a crash, run `stty sane && reset` to restore it.
-- **tmux capture trick**: `tmux capture-pane -t mcc-debug -p -S -50` captures the last 50 lines of a tmux session without attaching.
+- **tmux capture trick**: `tmux capture-pane -t mcc-<session> -p -S -50` captures the last 50 lines of a tmux session without attaching.
 
 ## Tool files