Add handover doc, update README with Option B architecture

README: rewritten to reflect actual Option B architecture (Electron on
host, agents in container), correct start.sh usage, bin/claude routing,
and portability. Remove outdated manual docker run instructions.

HANDOVER.md: documents all fixes made this session, what is unverified,
what still needs testing (claude-code check, localhost:null, network),
and key architecture facts for the next session.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

HANDOVER.md

@@ -0,0 +1,84 @@
+# Handover — Context Studio Wizard
+
+_Last updated: 2026-03-09_
+
+## Current status
+
+The wizard runs end-to-end. The generated project (`thewiztest`) starts the container
+and opens the Electron UI. **The last fix was NOT yet confirmed working by the user.**
+The session ended before the user could test it.
+
+## What was fixed this session (newest first)
+
+### 1. `bin/claude` — workdir fallback (UNVERIFIED — last fix, not yet tested)
+**File:** `lib/container.sh` → generated `bin/claude`
+**Symptom:** `[Server:err] claude-code is required but not found` → `[Server] Exited with code 1` → all agents fail to start
+**Root cause:** When Electron spawns `node core/start.js`, its cwd is `~/.context-studio/core`. The `bin/claude` wrapper used `--workdir "$PWD"` in `podman exec`. That directory isn't mounted in the container → podman fails → returns non-zero → claude appears "missing".
+**Fix:** If `$PWD` is not under `$PROJECT_DIR`, fall back to `$PROJECT_DIR` as the container workdir.
+**Also patched:** `thewiztest/bin/claude`
+
+### 2. Container runs as root → `--dangerously-skip-permissions` rejected
+**File:** `lib/container.sh` → generated `start.sh`
+**Symptom:** `--dangerously-skip-permissions cannot be used with root/sudo privileges`
+**Fix:** Added `--user "$(id -u):$(id -g)"` and `-e HOME="$HOME"` to `podman run`
+**Why it works:** Host user `elmar` = uid 1000 = `node` user in `node:22` image → permissions match
+**Also patched:** `thewiztest/start.sh`
+
+### 3. Electron manages server startup — removed redundant headless node
+**File:** `lib/container.sh` → generated `start.sh`
+**Symptom:** Would have caused port conflicts
+**Fix:** Removed `node start.js --ui-mode=headless &` from start.sh. The Electron app's `server-management.js` checks the lock file and spawns servers itself.
+**Also patched:** `thewiztest/start.sh`
+
+### 4. Electron must be launched separately
+**File:** `lib/container.sh`
+**Symptom:** UI never opened — servers ran but no window
+**Root cause:** `node core/start.js --ui-mode=electron` does NOT launch Electron. It logs "Electron app started separately" and only manages A2A servers.
+**Fix (later superseded):** Direct Electron launch via `$CS_CORE/app/node_modules/.bin/electron $CS_CORE/app`
+
+## What still needs verifying
+
+1. **Does the server now start without the `claude-code missing` error?**
+   - Run `./start.sh` in `thewiztest/`
+   - Watch for `[12:xx:xx] ✅ All agent servers started` (no `Server startup failed`)
+   - The Electron UI should open and kai's terminal should start without root errors
+
+2. **`localhost:null` network error** — this is downstream of (1). If servers start cleanly, the registry port gets written to the lock file and `localhost:null` disappears.
+
+3. **Kai can't connect to the internet** — mentioned by user but not investigated. Could be:
+   - Container network settings (Podman default: slirp4netns, should have internet)
+   - ANTHROPIC_API_KEY not set or not passed into container
+   - Proxy/VPN issue on the host network
+
+## Key architecture facts
+
+### How CS Core + Electron work together
+- `electron app/` starts the UI
+- Electron's `server-management.js` checks `workflow/data/` for a lock file
+- If no lock file → it spawns `node core/start.js --ui-mode=headless` as a child process
+- Child process inherits Electron's `process.env` including PATH (with `bin/claude`)
+- When the requirements check runs `claude --version`, it finds `bin/claude` in PATH
+- `bin/claude` proxies to `podman exec cs-<slug> claude --version`
+- Container must be running BEFORE Electron is launched (start.sh handles this)
+
+### Path that must be mounted in container
+Only `$PROJECT_DIR` is mounted (at the same absolute path). NOT:
+- `~/.context-studio/core`
+- `~/.anthropic` (mounted read-only separately)
+- Any other host path
+
+### Generated files per project
+- `bin/claude` — wrapper with hardcoded `PROJECT_DIR` and `CONTAINER_NAME`
+- `start.sh` — starts container as `$(id -u):$(id -g)`, exports PATH, launches Electron
+- `stop.sh` — force-removes container
+- `update.sh` — git pull core, npm update claude-code in container, apt upgrade
+
+## File locations
+- Wizard: `/home/elmar/Projects/ContextStudioWizard/`
+- Test project: `/home/elmar/Projects/thewiztest/`
+- Core (read-only!): `/home/elmar/.context-studio/core/`
+- Wizard repo remote: check `git remote -v` in ContextStudioWizard
+
+## What NOT to do
+- Never modify `~/.context-studio/core` — it is read-only
+- Never commit or push to the core repo