@matt82198/aesop 0.3.2 → 0.4.1

package/docs/INSTALL.md

@@ -2,6 +2,9 @@
 
 **TL;DR**: Install Aesop in ~5 minutes using `npx`, set your repos, then verify with a single watchdog test run.
 
+**New repo?** Follow the scaffolding guide below.
+**Existing repo?** See [PORTING.md](PORTING.md) for adopting Aesop on a foreign codebase (with 10 common pitfalls covered).
+
 ---
 
 ## Prerequisites
@@ -15,7 +18,26 @@ Before you start, make sure you have:
 - **Python** (v3.10+) — for secret-scan and log rotation
 - **jq** (optional) — for TUI dashboard parsing
 
-Check your versions:
+### Install Claude Code CLI
+
+Claude Code is required to run `/power` and `/buildsystem` skills.
+
+**Download and install**:
+- Visit https://claude.com/claude-code to download and install Claude Code for your operating system
+
+**Verify installation**:
+```bash
+claude --version
+```
+
+Expected output: `Claude Code vX.Y.Z` (v0.1 or higher)
+
+**If not on PATH**: On macOS/Linux, add the install directory to your `$PATH`. On Windows, the installer registers Claude Code in your PATH automatically. If `claude` is not found:
+- Reinstall Claude Code and ensure the installer adds it to PATH
+- Or add the installation directory to PATH manually (usually `~/.claude/bin` or `C:\Program Files\Claude Code\bin`)
+
+### Check your versions
+
 ```bash
 claude --version
 git --version
@@ -61,6 +83,15 @@ cp -r skills/power/ ~/.claude/skills/power/
 cp -r skills/buildsystem/ ~/.claude/skills/buildsystem/
 ```
 
+**Verify the skills were copied**:
+```bash
+# Check both skills exist
+ls -la ~/.claude/skills/power/SKILL.md
+ls -la ~/.claude/skills/buildsystem/SKILL.md
+```
+
+Expected output: Two SKILL.md files should exist.
+
 ### Step 3: Verify the installation
 
 Run the watchdog once to test everything:
@@ -79,6 +110,8 @@ Expected output:
 
 If you see errors, check the logs in `state/FLEET-BACKUP.log`.
 
+**Note**: The `reproduce` command runs full test suites if you're working in the aesop repo itself. For scaffolded fleets, verification uses `aesop doctor` + `watchdog --once` to check preflight requirements and basic health.
+
 ---
 
 ## Manual Setup: Git Clone (For Development)
@@ -101,8 +134,8 @@ Open `aesop.config.json` and customize for your repos (see [CONFIGURE.md](CONFIG
 
 ```json
 {
-  "aesopRoot": "/home/user/my-aesop",
-  "braindRoot": "/home/user/.claude",
+  "aesop_root": "/home/user/my-aesop",
+  "brain_root": "/home/user/.claude",
   "repos": [
     {
       "path": "/home/user/my-repo1",
@@ -113,7 +146,9 @@ Open `aesop.config.json` and customize for your repos (see [CONFIGURE.md](CONFIG
       "name": "my-frontend"
     }
   ],
-  "dashboardPort": 8770,
+  "dashboard": {
+    "port": 8770
+  },
   "dashboardOrigin": "http://localhost:8770"
 }
 ```
@@ -169,10 +204,10 @@ After setup, you'll have:
 ### Configuration files
 
 - **aesop.config.json** — Main configuration (git-ignored, never commit credentials)
-  - `aesopRoot` — path to this harness directory
-  - `braindRoot` — path to Claude Code home (`~/.claude`)
+  - `aesop_root` — path to this harness directory
+  - `brain_root` — path to Claude Code home (`~/.claude`)
   - `repos` — list of monitored repositories
-  - `dashboardPort` — web dashboard port (default: 8770)
+  - `dashboard.port` — web dashboard port (default: 8770)
   - `dashboardOrigin` — CORS origin validation
 
 - **aesop.config.example.json** — Template with defaults (commit this, use as reference)
@@ -184,35 +219,149 @@ After setup, you'll have:
 Optional environment variables you can set in your shell:
 
 ```bash
-# Point to the Aesop harness root (used by daemons)
+# Point to the Aesop harness root (used by daemons and tools)
 export AESOP_ROOT=/home/user/my-aesop
 
-# Optional: custom location for Claude Code home
-export CLAUDE_CODE_HOME=/home/user/.claude
+# Optional: custom location for Aesop state directory (default: ./state)
+export AESOP_STATE_ROOT=/home/user/my-aesop/state
 
-# Optional: enable debug output in daemons
-export DEBUG=1
+# Optional: custom location for Claude Code home (used by /power skill)
+export BRAIN_ROOT=/home/user/.claude
+
+# Optional: custom location for reusable scripts directory
+export SCRIPTS_ROOT=/home/user/scripts
 ```
 
 ---
 
+## Already Have Aesop? Quick Setup
+
+If you've already scaffolded Aesop and just need to get running:
+
+1. **Verify your config**:
+   ```bash
+   node -e "console.log(JSON.parse(require('fs').readFileSync('aesop.config.json')))"
+   ```
+
+2. **Verify the setup**:
+   ```bash
+   bash daemons/run-watchdog.sh --once
+   ```
+
+3. **Copy skills** (if not done yet):
+   ```bash
+   cp -r skills/power/ ~/.claude/skills/power/
+   cp -r skills/buildsystem/ ~/.claude/skills/buildsystem/
+   ```
+
+4. **Run your first wave**:
+   - Open Claude Code
+   - Type `/power` to prime your brain
+   - Type `/buildsystem` to start a wave (see [FIRST-WAVE.md](FIRST-WAVE.md))
+
+---
+
 ## Using Non-Claude Backends
 
 By default, Aesop uses Claude Code (the orchestration harness) as its backend. You can configure it to use other models via the **AgentDriver abstraction**—enabling Ollama, OpenAI-compatible endpoints, OpenRouter, and more.
 
-### Configure a backend in aesop.config.json
+For the conceptual picture (the two swappable seats, what's proven vs. bounded about swapping them, and a 60-second copy-paste quickstart), see **[MICROKERNEL.md](MICROKERNEL.md)**. The rest of this section is the config-mechanics reference.
+
+### The unified two-seat config (0.4.0)
+
+One namespaced `seats` block in `aesop.config.json` selects BOTH seats:
+
+- **`seats.worker`** — the coding agents (AgentDriver). Same fields as the
+  legacy flat block below; takes precedence over it when both are present.
+- **`seats.orchestrator`** — the decision seat (`OrchestratorDriver.decide()`).
+  `"harness"` (default) means the live Claude Code session itself makes
+  decisions; `"openai-compatible"` routes decisions to an API model.
+
+**Swap a seat's model** — change just its block:
+
+```json
+{
+  "seats": {
+    "worker": {
+      "backend": "openai-compatible",
+      "base_url": "http://localhost:11434/v1",
+      "model": "mistral",
+      "is_local": true
+    },
+    "orchestrator": {
+      "backend": "openai-compatible",
+      "model": "gpt-4o-mini",
+      "api_key_env": "OPENAI_API_KEY"
+    }
+  }
+}
+```
 
-Add or modify the `backend` section:
+That is a local-Ollama worker fleet with a hosted `gpt-4o-mini` decision seat.
+To swap the worker to OpenRouter, replace `seats.worker` with
+`{"backend": "openai-compatible", "base_url": "https://openrouter.ai/api/v1",
+"model": "openai/gpt-4-turbo", "api_key_env": "OPENROUTER_API_KEY"}` — nothing
+else changes. API keys are read from the env var named by `api_key_env` at
+call time and are never stored in the config; `"is_local": true` endpoints
+need no key at all — and for exactly that reason `is_local` is only accepted
+with a loopback `base_url` (`localhost`, `127.0.0.1`, `::1`).
+
+`api_key_env` is checked with a **best-effort heuristic**, allowlist-primary:
+known LLM-provider key names (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+`OPENROUTER_API_KEY`, `TOGETHER_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`,
+`DEEPSEEK_API_KEY`, `FIREWORKS_API_KEY`, `OLLAMA_API_KEY`,
+`AZURE_OPENAI_API_KEY`, `GOOGLE_API_KEY`) are accepted silently; names that
+don't look like key env vars or contain obvious non-LLM secret fragments
+(`SECRET`/`TOKEN`/`PASSWORD`/`ACCESS`/...) are rejected; any other
+key-shaped name (custom LLM gateways) is **allowed but prints a loud
+NOTICE** — the env var's value will be sent as a Bearer token to your
+`base_url`, so that NOTICE is the real signal: review it whenever a
+non-provider name shows up at load time.
+
+Asymmetry worth knowing: a **worker** `openai-compatible` seat REQUIRES
+`base_url`; the **orchestrator** seat may omit it (defaults to the hosted
+OpenAI endpoint).
+
+**No `seats` block? Nothing changes.** Existing installs keep today's exact
+behavior: Claude Code workers + harness orchestrator, no OpenAI backend
+constructed, no key required. A pre-0.4.0 **legacy flat** backend block
+(`{"backend": "codex", ...}` at the top level) also changes nothing by
+itself: it still parses and validates, but it stays **inert** in the wave
+scheduler's default path until you migrate it to `seats.worker` — on older
+installs that block was documented but consumed by nothing, so activating it
+silently would change behavior under you. (`cardinal_rules.orchestrator_model`
+from older scaffolds was write-only and is retired; the orchestrator seat's
+model now lives in `seats.orchestrator.model`.)
+
+Consumers: `driver/wave_scheduler.py` builds its worker driver from this
+config (CLI `--driver claude|codex` remains an override), and
+`tools/shadow_adjudication.py` / `tools/seated_shadow_adjudication.py` build
+their live orchestrator backend from `seats.orchestrator` (CLI `--model`
+remains an override).
+
+### The legacy flat block (parse-compatible, but migrate it)
+
+Pre-0.4.0 docs described a flat top-level block:
 
 ```json
 {
   "backend": "openai-compatible",
   "model": "ollama-mistral",
   "base_url": "http://localhost:11434/v1",
-  "api_key_env": "OLLAMA_API_KEY"
+  "api_key_env": "OLLAMA_API_KEY",
+  "is_local": true
 }
 ```
 
+It still parses and validates (and direct `build_driver()` callers honor
+it), but the wave scheduler's default path treats it as **inert** and keeps
+the Claude Code worker: to actually activate a configured worker there, put
+the same fields under `seats.worker` (`{"seats": {"worker": { ...this
+block... }}}`).
+
+Set `"is_local": true` for local/small models (Ollama etc.) — it raises the
+verification tier honestly (tier 3 instead of hosted tier 2).
+
 Supported backends:
 - `"claude"` (default) — Claude Code CLI harness
 - `"openai-compatible"` — OpenAI Chat Completions API (Ollama, OpenRouter, etc.)
@@ -229,17 +378,22 @@ ollama serve
 # 2. In another terminal, pull a model
 ollama pull mistral
 
-# 3. Configure Aesop to use it
+# 3. Configure Aesop to use it (seats.worker is the opt-in surface)
 cat > aesop.config.json <<EOF
 {
-  "backend": "openai-compatible",
-  "model": "mistral",
-  "base_url": "http://localhost:11434/v1",
-  "api_key_env": "OLLAMA_API_KEY"
+  "seats": {
+    "worker": {
+      "backend": "openai-compatible",
+      "model": "mistral",
+      "base_url": "http://localhost:11434/v1",
+      "api_key_env": "OLLAMA_API_KEY",
+      "is_local": true
+    }
+  }
 }
 EOF
 
-# 4. Start Aesop (it will use Mistral for subagent dispatch)
+# 4. Start Aesop (components that dispatch through the AgentDriver seam will use Mistral)
 npx @matt82198/aesop my-fleet --name "my-api"
 ```
 
@@ -250,16 +404,16 @@ The AgentDriver framework applies **honest verification tiers** — weaker backe
 | Backend | Accuracy | Verification Tier | What it means |
 |---------|----------|-------------------|---------------|
 | Claude Code | ~0.99 | 1 (minimal) | Orchestrator trusts output; spot-check tests |
-| OpenAI (GPT-4) | ~0.95 | 2 | Validate all JSON, run full test suite |
-| Ollama (Mistral) | ~0.70 | 4 (maximum) | Validate all JSON, adversarial review, expensive repair cap |
+| Hosted OpenAI-compatible (codex / OpenRouter) | ~0.92 | 2 | Validate all JSON, ~50% spot-check, adversarial review |
+| Local small model (`"is_local": true`, e.g. Ollama) | ~0.80 | 3 | Validate all JSON, heavy spot-check, adversarial review |
 
-Lower tiers cost less but require more orchestrator work. See [driver/README.md](../driver/README.md) for full verification-policy details.
+Higher tiers mean MORE orchestrator verification work: weaker backends raise, never lower, the orchestrator's burden. See [driver/README.md](../driver/README.md) for full verification-policy details.
 
 ### Troubleshooting
 
 **Backend won't connect**: Check `OLLAMA_API_KEY` (or your backend's API key env var) is set and the `base_url` is reachable.
 
-**Verification tier too strict**: If your backend is over-verified (tier 4 when it should be tier 2), update `probe_capabilities()` in the driver to report higher accuracy scores honestly.
+**Verification tier too strict**: The tier comes from the driver's `probe_capabilities()` honesty contract — never inflate accuracy to lower it. For hosted-quality models, leave `"is_local"` unset (tier 2); reserve `"is_local": true` (tier 3) for genuinely small local models.
 
 For more details, see [driver/README.md](../driver/README.md).
 
@@ -333,6 +487,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File daemons/install-tasks.ps1 -D
 2. **Read [CONFIGURE.md](CONFIGURE.md)** — Customize repos, ports, and brain root
 3. **Run [FIRST-WAVE.md](FIRST-WAVE.md)** — Test a full `/power` → `/buildsystem` cycle
 4. **Understand [CONCEPTS.md](CONCEPTS.md)** — Learn the dispatch model and state model
-4. **Explore the dashboard** — `python3 ui/serve.py` then open http://localhost:8770
+5. **Read [MICROKERNEL.md](MICROKERNEL.md)** — Swap the worker or orchestrator seat to a non-Claude model
+6. **Explore the dashboard** — `python3 ui/serve.py` then open http://localhost:8770
 
 For troubleshooting, see the [Aesop README](../README.md#troubleshooting) or [GOVERNANCE.md](GOVERNANCE.md) for operational policies.