# 🧙 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 → talk to your agent team.

---

## 🏗️ Architecture (Option B)

```
HOST                                    CONTAINER (cs-<project>)
─────────────────────────────           ────────────────────────
Context Studio Core (Electron)   ←───  All Claude Code agents
  starts A2A servers                    mounted at same abs path
  opens Electron UI                     bin/claude wrapper routes
  manages workflow                      every claude call here
```

- **CS Core** runs on the host (Electron UI, no display issues)
- **All agents** run 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_API_KEY` | Must be set in your environment |

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

---

## 🚀 Usage

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

The wizard guides you through:

1. 🔧 **Core setup** — clones `context-studio-core` to `~/.context-studio/core/` (once, shared)
2. 📝 **Project name & location**
3. ⚙️ **Workflow** — generate from scratch _or_ clone an existing repo
4. 🤖 **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 |

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

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

---

## ▶️ 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 here as your user, not root)
3. Launch the Context Studio Electron UI
4. 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. Passes the working directory (falling back to project root if cwd isn't mounted)
4. All agents — including the main coordinator — run **inside the container**

---

## 🗂️ Repository layout

```
🧙 wizard.sh               ← entry point
📁 lib/
   utils.sh                ← prompts, colors, gum helpers
   prereqs.sh              ← auto-install git + podman/docker
   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` is READ-ONLY** — never modify, commit, or push to it
- It is a shared global dependency; the wizard only clones and `npm install`s it

---

## 🌍 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
```