diff --git a/ecc-setup-guide.md b/ecc-setup-guide.md
new file mode 100644
index 0000000..f3b8d21
--- /dev/null
+++ b/ecc-setup-guide.md
@@ -0,0 +1,163 @@
+# Everything Claude Code (ECC) — Setup Guide
+
+Step-by-step instructions for setting up ECC on a new machine. Can be followed manually or by Claude.
+
+## Prerequisites
+
+- Node.js + npm installed
+- Git installed
+- Claude Code CLI installed
+- PowerShell (Windows) or Bash (macOS/Linux)
+
+## Step 1 — Clone and install
+
+**Windows (PowerShell):**
+```powershell
+git clone https://github.com/affaan-m/everything-claude-code.git C:\Users\<USERNAME>\everything-claude-code
+cd C:\Users\<USERNAME>\everything-claude-code
+npm install
+```
+
+**macOS/Linux (Bash):**
+```bash
+git clone https://github.com/affaan-m/everything-claude-code.git ~/everything-claude-code
+cd ~/everything-claude-code
+npm install
+```
+
+## Step 2 — Run the installer
+
+Run the installer **from inside the cloned repo**.
+
+**Windows (PowerShell):**
+```powershell
+.\install.ps1 <languages>
+# Example: .\install.ps1 python typescript
+```
+
+**macOS/Linux (Bash):**
+```bash
+./install.sh <languages>
+# Example: ./install.sh python typescript
+```
+
+**Cross-platform (npm):**
+```bash
+npx ecc-install <languages>
+```
+
+Available languages: `python`, `typescript`, `golang`, `swift`, `php`, `rust`, `cpp`, `csharp`, `java`, `kotlin`, `perl`
+
+> **Note:** In legacy-compat mode the installer copies rules for ALL languages regardless of arguments. The extra rules are harmless — they sit in `~/.claude/rules/<lang>/` and only load when relevant.
+
+### What gets installed
+
+All files go to `~/.claude/` (global, applies to all projects):
+
+| Category | Location | Examples |
+|----------|----------|---------|
+| Rules | `~/.claude/rules/` | coding-style, testing, security (per language) |
+| Agents | `~/.claude/agents/` | planner, architect, code-reviewer, tdd-guide, security-reviewer |
+| Skills | `~/.claude/skills/` | python-patterns, tdd-workflow, e2e-testing, continuous-learning |
+| Commands | `~/.claude/commands/` | `/plan`, `/tdd`, `/code-review`, `/verify`, `/learn` |
+| Hooks | `~/.claude/hooks/` | auto-format, console-log check, cost tracker |
+
+## Step 3 — Add Bash tool to read-only agents
+
+Some agents (planner, architect) ship with only `Read, Grep, Glob` tools. To enable `ast-index` and other CLI tools, add `Bash` to their tool lists.
+
+Edit these files in `~/.claude/agents/`:
+- `planner.md`
+- `architect.md`
+
+Change the frontmatter `tools` line from:
+```yaml
+tools: ["Read", "Grep", "Glob"]
+```
+To:
+```yaml
+tools: ["Read", "Grep", "Glob", "Bash"]
+```
+
+All other agents already have `Bash` in their tools list.
+
+## Step 4 — Configure Continuous Learning v2
+
+### 4a. Add observation hooks
+
+Add the following to `~/.claude/settings.json` (merge into existing `hooks` key if one exists):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
+      }]
+    }],
+    "PostToolUse": [{
+      "matcher": "*",
+      "hooks": [{
+        "type": "command",
+        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
+      }]
+    }]
+  }
+}
+```
+
+### 4b. Create the directory structure
+
+```bash
+mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}
+```
+
+### 4c. Verify the observe script exists
+
+```bash
+ls ~/.claude/skills/continuous-learning-v2/hooks/observe.sh
+```
+
+If missing, re-run the installer from Step 2.
+
+## Step 5 — Restart Claude Code
+
+Hooks and new agents only take effect after restarting Claude Code.
+
+## Post-install verification
+
+Run these commands inside Claude Code to verify:
+
+| Command | Expected result |
+|---------|----------------|
+| `/plan "test"` | Should invoke the planner agent |
+| `/instinct-status` | Should show instinct status (empty on first run) |
+| `/code-review` | Should invoke the code-reviewer agent |
+
+## Useful commands
+
+| Command | Purpose |
+|---------|---------|
+| `/plan` | Create implementation plan before coding |
+| `/tdd` | Test-driven development workflow |
+| `/code-review` | Review code for quality issues |
+| `/verify` | Run verification loop |
+| `/learn` | Manually extract patterns mid-session |
+| `/instinct-status` | View learned instincts |
+| `/evolve` | Cluster instincts into skills/commands/agents |
+| `/promote` | Promote project instincts to global scope |
+| `/projects` | List known projects and instinct counts |
+
+## Known gotchas
+
+1. **`/plugin` commands don't exist** — The ECC README references `/plugin marketplace add` and `/plugin install` but Claude Code has no such CLI commands. Use the `install.ps1` / `install.sh` script instead.
+
+2. **The `extraKnownMarketplaces` entry is cosmetic** — Adding ECC to `extraKnownMarketplaces` in `settings.json` does NOT enable it as a plugin and it will NOT appear in the enabled/disabled plugins list. The manual install is the actual installation method.
+
+3. **Windows: don't mix WSL and PowerShell** — If npm is installed on Windows, run everything in PowerShell with Windows paths (`C:\Users\...`). If using WSL, run everything in WSL with Linux paths (`~/...`). Mixing causes path resolution failures.
+
+4. **Windows paths in PowerShell** — Use `C:\Users\<USERNAME>\...`, NOT `/c/Users/...` (that's Git Bash / WSL syntax).
+
+5. **Agent model selection** — Each agent `.md` file in `~/.claude/agents/` supports a `model` field in frontmatter. Options: `haiku` (fast/cheap), `sonnet` (balanced), `opus` (deep reasoning). Choose based on agent complexity needs.