Merge pull request 'docs: document terminal layout & StatusBar control gotchas' (#11) from docs/terminal-layout-gotchas into main

Capture the non-obvious implementation gotchas from PR #7
(terminal-layout-statusbar) in TECHNICAL.md: wrapper-vs-host xterm
padding, global StatusBar controls, recordingSessionIdRef transcript
pinning, active-only Jump-to-Current state, and the Zustand
object-merge rule for publishing action callbacks.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

TECHNICAL.md

@@ -57,6 +57,16 @@ Tauri uses a Rust backend paired with a web-based frontend rendered by the OS-na
 - **Web links addon** — `@xterm/addon-web-links` makes URLs in terminal output clickable. Combined with `tauri-plugin-opener`, clicked URLs open in the host browser — essential for the `claude login` OAuth flow where Claude prints an authentication URL that must be opened on the host.
 - **Bidirectional data flow** — xterm.js exposes `term.onData()` for user keystrokes and `term.write()` for incoming data. This maps directly to our Tauri event-based streaming architecture.
 
+#### Terminal Layout & StatusBar Controls
+
+Implementation gotchas for the terminal view and its global controls (merged in PR #7, `terminal-layout-statusbar`):
+
+- **xterm padding lives on a wrapper, never the host.** FitAddon measures the same element that `term.open()` mounts into, so any padding on that host element makes the grid overhang and clip its rightmost column / bottom row. Padding must live on a **wrapper `div`**; the xterm host fills it with no padding of its own. Do not reintroduce padding on the host element in `TerminalView.tsx`.
+- **STT mic and "Jump to Current" live in the global `StatusBar`, not per-terminal overlays.** There is a single `useSTT` instance in `App.tsx` bound to the active session. `Ctrl+Shift+M` routes through the Zustand store (`sttToggle`).
+- **Recording is pinned to where it started.** The STT transcript targets `recordingSessionIdRef` (the session recording began in), **not** the live active session — switching tabs mid-recording must not misroute the transcript.
+- **"Jump to Current" state is written only by the active terminal.** The active `TerminalView` surfaces `terminalAtBottom` and `scrollActiveToBottom` through the store; only the active terminal writes them, and they are cleared on its unmount.
+- **Set store function values via object-merge, not the updater form** — `set({ fn: value })`, not `set(state => ...)` — when publishing action callbacks (like `scrollActiveToBottom`) into the Zustand store.
+
 ### bollard (Docker API)
 
 **Chosen over:** Shelling out to the `docker` CLI, dockerode (Node.js), docker-api (Python)

app/src-tauri/src/commands/file_commands.rs

@@ -155,7 +155,7 @@ pub async fn download_container_file(
 /// Create a `.tar.gz` backup of the container and stream it to a host file.
 /// The archive contains:
 ///   - the workspace (default /workspace), minus regenerable build artifacts
-///     (node_modules, target), at the archive root, and
+///     (node_modules, target), under `workspace/`, and
 ///   - a sanitized copy of the home config under `home-claude/`: ~/.claude.json
 ///     with secret-bearing keys removed (mcpServers/settings kept) and ~/.claude/
 ///     minus the OAuth `.credentials.json`, so MCP servers, settings and skills
@@ -204,6 +204,16 @@ pub async fn download_container_backup(
     // transient unreadable file from aborting the whole backup. If jq can't
     // parse ~/.claude.json we substitute an empty object — never the raw file —
     // so secrets can't leak through the sanitization fallback.
+    // The `--transform` nests the workspace under `workspace/` (parallel to
+    // `home-claude/`) so an extracted archive has both clearly labeled instead
+    // of scattering the workspace files into the extraction dir. Rewriting the
+    // leading `.` (rather than `./`) also renames tar's root member from `./` to
+    // `workspace`, so the archive carries a proper `workspace/` dir entry rather
+    // than a bare `./` that would stamp the source root's mode/mtime onto the
+    // extraction directory. `flags=rh` rewrites regular member names AND
+    // hardlink target names (so an intra-workspace hardlink pair still resolves
+    // on extract) while leaving symlink targets untouched (rewriting those would
+    // corrupt relative/absolute links).
     let script = r#"set -e
 STAGE=$(mktemp -d)
 trap 'rm -rf "$STAGE"' EXIT
@@ -221,6 +231,7 @@ if [ -d "$HOME/.claude" ]; then
 fi
 tar czf - --ignore-failed-read \
   --exclude='*/node_modules' --exclude='*/target' \
+  --transform='flags=rh;s,^\.,workspace,' \
   -C "$TC_BACKUP_SRC" . \
   -C "$STAGE" home-claude"#;