# 🧙 Context Studio Wizard

> Scaffold a fully configured multi-agent AI development environment in seconds.

---

## ✨ What it does

One command. A complete project drops out:

```
~/.context-studio/core/          ← 🔧 installed once, shared globally

~/Projects/my-project/
├── .devcontainer/               ← 🐳 Node 22 · Rust · Claude Code
├── workflow/                    ← 🤖 agents, roles, A2A config, project docs
├── src/                         ← 💻 your code
├── bin/claude                   ← 🔀 wrapper: routes claude → container
├── start.sh                     ← ▶️  start container + Context Studio UI
├── stop.sh                      ← ⏹️  stop the agents container
└── update.sh                    ← 🔄 update core, claude-code, OS packages
```

Run `./start.sh` → Podman container starts → Electron UI opens → agents prime automatically → talk to your team.

---

## 🏗️ Architecture (Option B)

```
HOST                                    CONTAINER (cs-<project>)
─────────────────────────────           ────────────────────────
Context Studio Core (Electron)          Claude Code binary
  A2A agent servers (node)       ←───  bin/claude wrapper routes
  Electron UI                          every claude call here
  workflow management                  mounted at same abs path
```

- **CS Core + all agent servers** run on the host (no display issues, native Electron)
- **Claude Code binary** runs inside the Podman container as the current user (not root)
- **`bin/claude`** is prepended to PATH so CS Core's server process finds it automatically
- **Paths match** host ↔ container (project mounted at the same absolute path)

---

## 📋 Prerequisites

| | Tool | Notes |
|---|------|---------|
| 🔀 | `git` | Auto-installed if missing |
| 🐳 | `podman` _(preferred)_ or `docker` | Auto-installed if missing |
| 🔑 | SSH key → `github.com` | Must be set up manually |
| 🗝️ | Anthropic credentials | API key or `claude auth login` — wizard checks automatically |

**Auto-install supported on:** Arch · Debian/Ubuntu · RHEL/Fedora · openSUSE

---

## 🚀 Usage

```bash
./wizard.sh
```

The wizard guides you through:

1. 🔧 **Prerequisites** — checks git, podman/docker, Anthropic credentials
2. 🔧 **Core setup** — clones `context-studio-core` to `~/.context-studio/core/` (once, shared)
3. 📝 **Project name & location**
4. ⚙️ **Workflow** — generate from scratch _or_ clone an existing repo
5. 🤖 **Agent preset** _(if generating)_

   | Preset | Agents |
   |--------|--------|
   | `minimal` | 5 agents: coordinator · 2× coder · researcher · tester |
   | `standard` | 9 agents: 2× coordinator · 3× coder · 2× researcher · tester · reviewer |

6. ✅ **Done** — project created, git repo initialized

**Ctrl+C at any point** → confirmation prompt → reverts all created files (installed packages kept).

> ⚠️ **First `./start.sh`** builds the container image. Expect 5–15 min. Subsequent starts are instant.

---

## 🔑 Anthropic credentials

The wizard checks for credentials in this order:

1. `ANTHROPIC_API_KEY` environment variable
2. `~/.claude/.credentials.json` (default `claude auth login` location)
3. `~/.claude.json`
4. `$CLAUDE_CONFIG_DIR/.credentials.json` / `$CLAUDE_CONFIG_DIR/.claude.json`
5. `~/.anthropic/.credentials.json`

If none found, you're prompted to enter an API key (masked input) with an option to save it to `~/.zshrc` / `~/.bashrc`.

All credential files that exist are **mounted read-only** into the container so Claude Code can authenticate.

---

## ▶️ Starting your project

```bash
cd ~/Projects/my-project
./start.sh
```

This will:
1. Build the container image if not yet built (first run: 5–15 min)
2. Start the Podman container (agents run inside as your user, not root)
3. Register the project with Context Studio (required for server startup)
4. Launch the Context Studio Electron UI
5. Agents start, prime automatically — no trust dialogs, no manual steps
6. When you close the UI → container is stopped automatically

```bash
./stop.sh      # force-stop container without closing the UI
./update.sh    # update core, claude-code inside container, OS packages
```

---

## 🔄 How `bin/claude` works

CS Core on the host needs to call `claude`. Instead of using the host's `claude`, `start.sh` prepends `bin/claude` to `PATH`. This wrapper:

1. Checks the agents container is running
2. Relays the call into the container via `podman exec`
3. Falls back to project root as workdir if cwd isn't mounted in the container
4. Creates the CS Core ready marker (`/tmp/cs-ready-<agentId>`) after 3s so `/prime` injection isn't delayed

---

## 🗂️ Repository layout

```
🧙 wizard.sh               ← entry point
📁 lib/
   utils.sh                ← prompts, colors, gum helpers
   prereqs.sh              ← auto-install git + podman/docker + API key check
   core.sh                 ← global core install/update
   project.sh              ← devcontainer + project scaffold
   workflow.sh             ← generate or clone workflow config
   container.sh            ← generates start/stop/update/bin/claude
📁 templates/
   Dockerfile              ← Node 22 + Rust + build tools + Claude Code
   devcontainer.json       ← mounts, env vars, VS Code extensions
   agents-minimal.json     ← 5-agent preset
   agents-standard.json    ← 9-agent preset
   system.json             ← A2A server defaults
   📁 roles/               ← coordinator, coder, researcher, tester, reviewer
   📁 hooks/rules/         ← per-role tool restrictions
```

---

## ⚠️ Hard rules

- **`~/.context-studio/core/` source is READ-ONLY** — never modify source files, commit, or push to it
- `~/.context-studio/core/config/electron-config.js` is a config file — safe to edit (e.g. timeouts)
- The wizard only clones and `npm install`s core; it never touches core source

---

## 🌍 Portability

Commit your project. On any machine:

```bash
git clone <your-project-repo>
cd my-project
./start.sh   # wizard re-runs if core missing; image builds on first run
```