# 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