@matt82198/aesop 0.1.0-beta.3 → 0.1.0-beta.5

package/README.md

@@ -9,345 +9,226 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@matt82198/aesop"><img src="https://img.shields.io/npm/v/@matt82198/aesop/beta" alt="npm"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/@matt82198/aesop" alt="license"></a>
+  <a href="https://github.com/matt82198/aesop/actions/workflows/ci.yml"><img src="https://github.com/matt82198/aesop/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
 </p>
 
-**Aesop** is an open-source orchestration harness for Claude Code, implementing a cost-optimized, self-healing multi-agent dispatch system. One orchestrator model (Opus/Sonnet) directs a fleet of cheap subagents (Haiku) across durable, observable machinery.
+**Aesop** is an open-source orchestration harness for Claude Code that builds itself. It runs a `/buildsystem` wave cycle—ranking a backlog, fanning out parallel Haiku agents (1/3 the cost of Opus), watchdogging them, verifying merges, then feeding the next wave via audit + ideation + fleet-ops monitoring. **This repo's own PRs are built by Aesop's own loop.** Dogfooding, not doctrine.
 
-The naming is a conceit: Aesop directs the Fables (the AI models). Like the tortoise and the hare, Aesop favors the slow, deliberate orchestrator directing a fleet of fast, cheap agents toward reliable outcomes.
+What you get: **cost-optimized multi-agent dispatch** (Haiku-first subagents, lean orchestrator), **durable state** (git-committed checkpoints survive wipes), **observable machinery** (every agent run logged, every cost tracked), **live dashboard** (real-time fleet health at http://localhost:8770), and **security gates** (secret-scan blocks pushes, CI validates each merge).
 
-## Origin
+## What You Get
 
-Aesop began as damage control: an endpoint-security agent kept deleting work mid-session, so everything was forced into git—committed continuously, pushed constantly, reconstructable from nothing but the remotes. What started as a survival mechanism against a machine that wiped itself grew into a full multi-agent orchestration system—and one worth sharing.
+- **Parallel Haiku fleets** — Cheap, scoped subagents dispatch in parallel; orchestrator stays lean on main thread.
+- **Durable state** — STATE.md + BUILDLOG.md checkpoints survive machine wipes; re-sync on resume, zero data loss.
+- **Observable & auditable** — Every agent run logged, every cost tracked, every security event triaged.
+- **Self-healing watchdog** — Runs every 150s: backs up work, scans for secrets, detects drift, restores on reboot.
+- **Live web dashboard** — Real-time fleet health, security alerts, work-item kanban at `http://localhost:8770`.
+- **Secret-scan gates** — Pre-push hook blocks leaks; audit trail logged. Pair with GitHub branch protection for enforcement.
 
-## What it is
+## Get Started (3 steps, 5 min)
 
-A filesystem-first orchestration system that:
+**Note:** Aesop is in beta. Install the `@beta` tag for the latest prerelease (0.1.0-beta.1+).
 
-- **Dispatch pattern**: Opus orchestrator on the main thread coordinates tiny scoped tasks to Haiku subagents (1/3 the token cost).
-- **Durable state**: git-committed checkpoints (STATE.md, BUILDLOG.md) survive machine wipes and interruptions.
-- **Observable machinery**: every agent run logged, every cost tracked, every security breach detected.
-- **Self-healing watchdog**: runs every 150s, backs up work, scans for secrets and drift, restores on reboot.
-- **Refinement monitor**: standing Haiku loop that watches orchestration health and auto-acts on rule friction.
-- **TUI dashboard**: real-time fleet status, security alerts, heartbeat liveness.
-
-## Install & Quick Start
-
-### Option 1: npm (Recommended for quick scaffolding)
-
-**Note:** Aesop is currently in beta. Install the prerelease version:
+### Quickest path: npx scaffold
 
 ```bash
-# Create a new aesop fleet directory
-# Using @beta tag to install the latest prerelease version (0.1.0-beta.1)
-npx @matt82198/aesop@beta my-fleet
+npx @matt82198/aesop@beta my-fleet \
+  --name "my-api" \
+  --repos "/path/to/repo1,/path/to/repo2"
 cd my-fleet
 
-# Configure
-cp aesop.config.example.json aesop.config.json
-# Edit aesop.config.json with your paths and repos
-
 # Start the daemon
 bash daemons/run-watchdog.sh --once
 
-# Launch the dashboard
+# Launch dashboard on localhost:8770
 python ui/serve.py
 ```
 
-Open `http://localhost:8770` to monitor your fleet.
+Pre-push hook auto-installed. See [docs/HOOK-INSTALL.md](./docs/HOOK-INSTALL.md) for branch protection pairing.
 
-Alternatively, install globally:
-```bash
-npm install -g @matt82198/aesop@beta
-aesop my-fleet
-```
+**State Store**: Aesop uses an event-sourced SQLite WAL backing store (`state_store/`) for durable state persistence. The `tracker.json` file is automatically re-rendered as an export for git-friendly checkpointing. Mutations follow a dual-path model: append new events via the StateAPI, then rendered exports for external consumption.
 
-### Option 2: git clone (For development or full customization)
+### Or: git clone for hacking
 
 ```bash
 git clone https://github.com/matt82198/aesop ~/aesop
 cd ~/aesop
 cp aesop.config.example.json aesop.config.json
-# Edit aesop.config.json with your paths and repos
+# Edit paths and repos
 
-# Start the daemon
 export AESOP_ROOT=$HOME/aesop
 bash $AESOP_ROOT/daemons/run-watchdog.sh --once
-
-# Launch the dashboard
 python ui/serve.py
 ```
 
-## Architecture
-
-### Directory layout
+## How It Works
 
 ```
-aesop/
-  daemons/          # Watchdog daemon + backup scripts
-  dash/             # TUI dashboard (watchdog-gui.sh)
-  monitor/          # Orchestration monitor (collect-signals.mjs, CHARTER.md)
-  tools/            # Build utilities (stubs for extend)
-  docs/             # Migration guides, deep-dives
-  state/            # Durable checkpoints (created at runtime)
-  aesop.config.json # Your local configuration (git-ignored)
+daemons/run-watchdog.sh         Every 150s: backs up work, scans secrets, detects drift
+  ↓
+orchestrator (via Claude Code)  Reads backlog, dispatches Haiku subagents in parallel
+  ↓
+parallel Haiku fleet            Tiny, scoped domains (tests, build, review, docs, etc.)
+  ↓
+watchdog verifies & merges      GREEN → push to main
+  ↓
+monitor/collect-signals.mjs     Audits orchestration health, feeds next wave's backlog
+  ↓
+STATE.md + BUILDLOG.md          Git-committed, survives machine wipes
 ```
 
-### Operating the harness
+See [docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md) for cost analysis and parallel patterns.
 
-#### 1. Bootstrap
+<!-- SELF-STATS:START -->
 
-```bash
-git clone <aesop-repo> ~/aesop
-cd ~/aesop
-cp aesop.config.example.json aesop.config.json
-# Edit aesop.config.json with your paths and repos
-```
+## Aesop builds itself
 
-#### 2. Start the watchdog daemon
+Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel Haiku fleets across ranked backlog items, verifying merges, auditing orchestration health. These stats are the receipts: all numbers computed LIVE from git, verified by anyone who clones.
 
-```bash
-export AESOP_ROOT=$HOME/aesop
-bash $AESOP_ROOT/daemons/run-watchdog.sh &
-```
+| Metric | Value |
+| --- | --- |
+| Merged PRs | 141 <!-- metrics-verified: self_stats.py (git log) --> |
+| Total Commits | 377 <!-- metrics-verified: self_stats.py (git log) --> |
+| Project Age | 3 days <!-- metrics-verified: self_stats.py (git log) --> |
+| Waves | 15 <!-- metrics-verified: self_stats.py (git log) --> |
+| Insertions + Deletions | 70,439 <!-- metrics-verified: self_stats.py (git log) --> |
+| Files Tracked | 257 <!-- metrics-verified: self_stats.py (git log) --> |
+| Distinct Co-authors | 7 <!-- metrics-verified: self_stats.py (git log) --> |
 
-Runs every 150s: discovers changed repos, stashes uncommitted work, pushes backups to `backup/wip-*` branches, runs secret-scan gate.
+<!-- SELF-STATS:END -->
 
-#### 3. Launch the Web Dashboard (Primary Interface)
+## Recommended Agents
 
-The web dashboard is the recommended way to monitor your fleet. It provides real-time observability, security alerts, and inbox integration in a modern, responsive interface.
+Aesop pairs well with the open-source [Claude specialized-agent catalog](https://github.com/anthropics/claude-code/tree/main/agents) — a library of ~130 domain-specific agents (TDD orchestrators, security reviewers, performance engineers, etc.). For optimal results, install agents from the upstream source and pair them with Aesop's cost-optimized Haiku dispatch. This is optional; Aesop works standalone with general-purpose Claude Code agents.
 
-```bash
-python $AESOP_ROOT/ui/serve.py
-```
-
-Opens `http://localhost:8770` with:
-- Real-time daemon heartbeats and liveness
-- Active subagent tracking
-- Security alerts panel
-- Recent events log
-- Inbox for orchestrator communication
-- Repository sync status
-
-See `ui/README.md` for configuration, environment variables, and troubleshooting.
+## Use with Claude Code
 
-#### (Optional) Legacy TUI Dashboard
-
-If you prefer a terminal-based interface:
+If you're using **Claude Code**, invoke `/power` at the start of each session. It loads your orchestrator brain (cardinal rules, domain map, team memory, system state) and outputs a health brief. Setup once:
 
 ```bash
-# On Windows (in a dedicated terminal):
-Start-Process "C:\Program Files\Git\git-bash.exe" -ArgumentList '-c', 'bash /c/Users/you/aesop/dash/watchdog-gui.sh'
-
-# On Unix:
-bash ~/aesop/dash/watchdog-gui.sh &
+# Copy the /power skill
+cp -r skills/power/ ~/.claude/skills/power/
 ```
 
-Note: The TUI is maintained for backward compatibility but is not actively developed. The web dashboard is recommended for new deployments.
-
-#### 4. Arm the monitor loop
-
-```bash
-# If using Claude Code, add to your CLAUDE.md or invoke via /power:
-# Runs collect-signals.mjs every cycle, emits BRIEF.md + SIGNALS.json,
-# then acts on AUTO-tier findings or stages PROPOSE-tier changes.
-```
+Then in Claude Code, type `/power` or `/buildsystem` to start a wave cycle. See [skills/power/SKILL.md](./skills/power/SKILL.md) for details.
 
-## Cardinal Rules (abridged)
+## Core Principles
 
-Read `docs/CARDINAL-RULES.md` for the full text. Core principles:
+1. **Haiku-first dispatch** — Subagents always cheap; orchestrator stays lean on main thread.
+2. **Durable state** — STATE.md + BUILDLOG.md survive wipes; re-sync on resume.
+3. **Observable** — Every agent run logged, every cost tracked, every security event triaged.
+4. **TDD-first** — Fail tests before implementation; one Haiku per scoped domain.
+5. **Never wait** — Dispatch work in parallel; connect with heartbeats, not polling.
+6. **Push discipline** — feature/* branches only; secret-scan gates every push.
 
-1. **Dispatch**: Haiku subagents only (cost lever). Opus orchestrates main-thread only.
-2. **TDD-first**: Fail tests before implementation. Tiny scoped domains; one Haiku per domain.
-3. **Reliability**: Every input produces output (brief/log/heartbeat/FAILED). Never wait.
-4. **Durable state**: STATE.md + BUILDLOG.md checkpoints survive wipes. Re-sync on resume.
-5. **Push discipline**: feature/branch → PR (never main). Continuously push green work.
-6. **Control files**: Single-writer discipline (STATE.md orchestrator, MEMORY.md keeper, BUILDLOG.md append-only).
-7. **Local execution**: Python runs locally only (no cloud runners). Reusable scripts in ~/scripts.
-8. **Secret gates**: `secret_scan.py` blocks every push. No credentials in repos.
-9. **Observability**: Every agent run logged, every cost tracked, every security event triaged.
+Read [docs/CARDINAL-RULES.md](./docs/CARDINAL-RULES.md) for the full text.
 
 ## Requirements
 
-- **Claude Code CLI** (v0.1+): the agent-spawning harness.
-- **Git** (v2.40+): version control for durable state.
-- **Bash** (v4+): scripting (Git Bash on Windows, bash on Unix).
-- **Node.js** (v18+): for monitor signal collection and dashboard extras.
-- **Python** (v3.10+): for log rotation, secret-scan, and custom tooling.
-- **jq** (optional): JSON parsing in TUI dashboard.
+- Claude Code CLI (v0.1+)
+- Git (v2.40+)
+- Bash (v4+) or Git Bash on Windows
+- Node.js (v18+) for dashboard and monitor
+- Python (v3.10+) for log rotation and secret-scan
+- jq (optional) for TUI dashboard
 
-## Setup Walkthrough
+## Scaling Cheaply
 
-### 1. Edit your configuration
+The **dispatch model** fans work across parallel Haiku subagents (each 1/3 the cost of Opus). The orchestrator stays lean on the main thread, coordinating via durable STATE.md. Result: ~25% the cost of an all-Opus fleet.
 
-```bash
-cp aesop.config.example.json aesop.config.json
-```
+**Action tiers**: AUTO (immediate, logged) for read-only checks and appends; PROPOSE (staged in `monitor/PROPOSALS.md`) for changes requiring approval. See [docs/GOVERNANCE.md](./docs/GOVERNANCE.md).
 
-Edit `aesop.config.json`:
-- Set `aesop_root`, `brain_root`, `scripts_root`, `temp_root` to your paths.
-- List your project repos under `repos[]`.
-- Tune watchdog and monitor cycle times.
-- Disable secret-scan if you don't have `tools/secret_scan.py` yet.
+## Security
 
-### 2. Create required directories
+The pre-push hook (`hooks/pre-push-policy.sh`) enforces branch discipline and secret scanning locally. It is bypassable (use `--no-verify` to skip), so **pair it with GitHub branch protection** for real enforcement:
 
-```bash
-mkdir -p ~/aesop/state
-mkdir -p ~/.heartbeats
 ```
-
-### 3. (Optional) Add your secret-scan script
-
-If you have a security scanner, drop it at `aesop/tools/secret_scan.py`. The watchdog will call it before pushing.
-
-Example stub:
-```python
-#!/usr/bin/env python3
-import sys
-sys.exit(0)  # TODO: implement secret scanning
+Settings > Branches > main
+  ✓ Require pull request reviews
+  ✓ Require status checks to pass
+  ✓ Dismiss stale PR approvals
+  ✓ Restrict pushes to (Admins only)
 ```
 
-### 4. Start the daemon
-
-```bash
-export AESOP_ROOT=$HOME/aesop
-bash $AESOP_ROOT/daemons/run-watchdog.sh &
-```
+Private brain (`~/.claude`) is never committed to this repo. Keep `aesop.config.json` git-ignored. Implement `tools/secret_scan.py` with your security rules. See [docs/HOOK-INSTALL.md](./docs/HOOK-INSTALL.md) for setup.
 
-Test mode: `bash $AESOP_ROOT/daemons/run-watchdog.sh --once`
+## Dashboard (Wave-14 Rewrite)
 
-### 5. Launch the dashboard
+The dashboard is a **React 18 + Vite + TypeScript** single-page app with four hash-routed views:
 
+### Viewing the Dashboard
 ```bash
-bash ~/aesop/dash/watchdog-gui.sh
+python ui/serve.py
 ```
+Opens `http://localhost:8770` — live fleet health, security alerts, work-item kanban, cost analytics.
 
-### 6. Arm the monitor (optional)
+### Architecture
+- **Backend**: Python stdlib HTTP server (`ui/handler.py`) serves the built React app + JSON/SSE APIs (`/api/state`, `/api/cost`, `/events`).
+- **Frontend**: `ui/web/` (React app) is built to `dist/` (committed to git) and served as static files by the Python server.
+- **CSRF protection**: Token injected into `dist/index.html` via sentinel substitution; mutations gated by `/submit` and `/api/tracker` endpoints.
 
-If you're using Claude Code, add this to your orchestrator loop:
+### Development
 ```bash
-export AESOP_ROOT=$HOME/aesop
-node $AESOP_ROOT/monitor/collect-signals.mjs
-```
-
-The monitor will read `BRIEF.md` and `SIGNALS.json` each cycle and act on findings.
-
-## Usage Patterns
-
-### Dispatch model (how to scale cheaply)
-
-```plaintext
-Orchestrator (main thread)
-  ├─ Haiku subagent 1 (domain A: tests)
-  ├─ Haiku subagent 2 (domain B: build)
-  ├─ Haiku subagent 3 (domain C: review)
-  └─ Haiku subagent 4 (domain D: docs)
+cd ui/web
+npm install
+npm run dev        # Vite dev server with API proxy to http://localhost:8770
+npm run build      # Build to dist/ (commit the dist/)
 ```
 
-Each subagent is **tiny**, **scoped**, and **disposable**. Total cost: ~25% of all-Opus fleet.
-
-### Action tiers (AUTO vs PROPOSE)
-
-- **AUTO**: immediate + logged (read-only checks, appends to logs, heartbeat updates).
-- **PROPOSE**: staged in `monitor/PROPOSALS.md`, requires user approval before execution.
-
-### Heartbeat pattern
-
-Daemons write epoch-seconds to `.heartbeat` files. The dashboard reads these to detect stalls:
-- Watchdog: alert if >300s old.
-- Monitor: alert if >3600s old.
-- Custom loops: check before spawning (skip if <200s).
+The dev server proxies `/data`, `/api`, `/events`, `/agent`, `/submit` to the Python backend on :8770, so the frontend can develop against live APIs.
 
-## Security & Privacy
+### Views
+- **Overview**: Fleet agents, security alerts, recent events.
+- **Work** (`#/work`): Tracker kanban (4 lanes: proposed/ranked/in-progress/done), audit backlog progress.
+- **Activity** (`#/activity`): Agent timeline, main-thread message tail (live reasoning).
+- **Cost** (`#/cost`): Per-model spend/tokens, per-day bar chart, verdict scorecard (success/failure rates).
 
-**⚠️ Important**: This harness assumes a **private brain directory** (`~/.claude`) that is **NEVER committed** to this repo. Your cardinal rules, agent catalog, and memory belong in your private remote (e.g., `claude-config`).
+## Extending Aesop
 
-- `aesop.config.json` is git-ignored (keep your paths secret).
-- `state/` and `.log` files are git-ignored (keep runtime data local).
-- Implement `tools/secret_scan.py` with your own security rules.
-- Use `secret_scan.py` as a gate on every push (don't bypass).
+**Custom signal collectors**: Edit `monitor/collect-signals.mjs` to add domain-specific health checks.
 
-## Extension points
+**Custom watchdog hooks**: Edit `daemons/backup-fleet.sh` to run linters, integrate with your CI, or customize secret-scan logic.
 
-### Add a custom signal collector
-
-Edit `monitor/collect-signals.mjs`:
-```javascript
-// Example: detect junk scripts
-function findJunkScripts() {
-  const junk = fs.readdirSync('/tmp').filter(f => f.endsWith('.py'));
-  return junk;
-}
-
-// Then add to signals:
-signals.junkScripts = findJunkScripts();
-```
-
-### Customize the watchdog
-
-Edit `daemons/backup-fleet.sh`:
-- Parse `aesop.config.json` to discover repos dynamically.
-- Add per-repo hooks (e.g., run linters before backup).
-- Implement your own secret-scan gate.
-
-### Extend the dashboard
-
-Edit `dash/watchdog-gui.sh`:
-- Add panels for CPU/memory/disk usage.
-- Integrate with your monitoring system.
-- Color-code alerts by severity.
+**Dashboard components**: Add React components in `ui/web/src/components/` or new views in `ui/web/src/views/`. Rebuild and commit `dist/`.
 
 ## Troubleshooting
 
-### Watchdog doesn't start
-
-Check `state/FLEET-BACKUP.log` for errors. Verify `AESOP_ROOT` is set correctly.
+| Issue | Check |
+|-------|-------|
+| Watchdog doesn't start | `state/FLEET-BACKUP.log` for errors; verify `AESOP_ROOT` is set |
+| Dashboard shows "unavailable" | Install Node.js v18+; check `dash-extra.mjs` is in sync |
+| Secret-scan blocks push | Add suppression to `tools/secret_scan.py`; no auto-bypass (by design) |
+| Monitor doesn't start | Verify Node.js on PATH; check `monitor/BRIEF.md` for logs |
 
-### Dashboard shows "unavailable"
+For deeper docs, see `docs/`:
+- `CARDINAL-RULES.md` — full 10 principles
+- `DISPATCH-MODEL.md` — cost analysis and patterns
+- `CHECKPOINTING.md` — how STATE.md + BUILDLOG.md survive wipes
+- `GOVERNANCE.md` — AUTO/PROPOSE tiers
+- `case-study-portfolio.md` — How Aesop built its own portfolio site; full audit trail and cost breakdown
 
-- If you see `(agents/processes panel unavailable)`, `node` is missing or `dash-extra.mjs` is not in sync.
-- Install Node.js v18+ and re-run.
+See [CHANGELOG.md](./CHANGELOG.md) for release notes.
 
-### Secret-scan blocks a legitimate push
-
-Add a suppression to your `tools/secret_scan.py`. Aesop never auto-bypasses gates (by design).
-
-### Monitor doesn't start
+## Contributing
 
-Ensure Node.js is on PATH and `collect-signals.mjs` has execute permissions. Check `monitor/BRIEF.md` for the latest cycle log.
+Aesop welcomes improvements. The repo uses its own `/buildsystem` loop for development—PRs from `feature/*` branches are built, tested, and merged by Aesop itself. To contribute:
 
-## Architecture deep-dives
+1. Fork and create a `feature/*` branch.
+2. Write failing tests first (TDD).
+3. Open a PR; Aesop's wave cycle will verify and merge.
 
-See `docs/` for detailed guides:
-- `CARDINAL-RULES.md` — full text of the 10 cardinal rules.
-- `DISPATCH-MODEL.md` — cost analysis and parallel orchestration patterns.
-- `STATE-MACHINE.md` — how STATE.md and BUILDLOG.md survive wipes.
-- `MONITOR-GOVERNANCE.md` — monitor AUTO/PROPOSE tiers and approval flow.
+Maintain the core principles: **Haiku-first** subagents, **lean** orchestrator, **durable** state, **observable** machinery.
 
 ## License
 
-MIT License. See `LICENSE` file.
-
-## Contributing
-
-Aesop is open-source and welcomes improvements. To contribute:
-
-1. Fork this repo.
-2. Create a feature branch: `git checkout -b feature/your-idea`.
-3. Add tests (TDD first).
-4. Commit with clear messages.
-5. Push to origin and open a PR.
-
-Maintain the cardinal rules: keep subagents cheap (Haiku), orchestrator lean, state durable, and machinery observable.
+MIT. See `LICENSE`.
 
 ## References
 
-- [Anthropic Claude API](https://docs.anthropic.com)
+- [Anthropic Claude API docs](https://docs.anthropic.com)
 - [Claude Code CLI](https://github.com/anthropics/claude-code)
-- [Git documentation](https://git-scm.com/doc)
-- Inspiration: "The Missing Memory Layer", "Agent Cost Trauma", "120 Words to Shipped" (publications on AI orchestration patterns).
+- [Git docs](https://git-scm.com/doc)
 
 ---
 
-**Aesop Contributors**  
-Built with the fable-fleet dispatch model in mind. May your orchestrator be wise and your subagents swift.
+**Aesop**: Fable-fleet orchestration, built by Aesop itself. May your orchestrator be wise and your subagents swift.

package/aesop.config.example.json

@@ -1,47 +1,55 @@
 {
-  "description": "Aesop configuration example. Copy to aesop.config.json and customize for your setup.",
-  "aesop_root": "/path/to/aesop",
-  "brain_root": "/path/to/your/brain",
-  "scripts_root": "/path/to/your/scripts",
-  "temp_root": "/path/to/temp/scratch",
+  "description": "Aesop configuration. Precedence: environment variables > config file > built-in defaults.",
+  "_paths": {
+    "aesop_root": "Set via AESOP_ROOT env var (no config key)",
+    "brain_root": "Override via BRAIN_ROOT env var or config; default: {aesop_root}/../.claude",
+    "scripts_root": "Override via SCRIPTS_ROOT env var or config; default: {aesop_root}/../scripts",
+    "temp_root": "Override via TEMP_ROOT env var or config; default: system temp + /claude",
+    "state_root": "Override via AESOP_STATE_ROOT env var or config; default: {aesop_root}/state",
+    "fleet_root": "Override via AESOP_FLEET_ROOT env var or config; default: $HOME. SECURITY: all repository clone targets must remain under fleet_root to prevent credential harvesting across account boundaries. The monitor validates clone targets on each cycle and surfaces violations as HIGH alerts.",
+    "transcripts_root": "Override via AESOP_TRANSCRIPTS_ROOT env var or config; default: ~/.claude/projects"
+  },
+  "brain_root": "~/.claude",
+  "scripts_root": "~/scripts",
+  "temp_root": "~/.aesop-temp",
+  "_temp_root_notes": "Portable path for temporary aesop files. ~ expands to home directory on both Windows and POSIX. Alternatively, on Windows set to %TEMP%/aesop, on POSIX set to /tmp/aesop. Config loaders expand ~ at runtime.",
+  "state_root": "./state",
+  "fleet_root": "/path/to/fleet",
+  "transcripts_root": "~/.claude/projects",
   "repos": [
     {
       "path": "/path/to/project1",
       "name": "project1",
+      "url": "https://github.com/user/project1.git",
       "primary_branch": "main",
       "backup_branch": "backup/wip"
     },
     {
       "path": "/path/to/project2",
       "name": "project2",
+      "url": "git@github.com:user/project2.git",
       "primary_branch": "main",
       "backup_branch": "backup/wip"
     }
   ],
-  "watchdog": {
-    "cycle_seconds": 150,
-    "heartbeat_threshold_seconds": 200,
-    "enable_secret_scan": true,
-    "secret_scan_script": "tools/secret_scan.py"
-  },
   "monitor": {
-    "enable": true,
-    "cycle_seconds": 3600,
-    "heartbeat_threshold_seconds": 3600,
-    "memory_staleness_days": 30,
     "log_max_lines": 500,
-    "log_max_kb": 40
-  },
-  "dashboard": {
-    "refresh_seconds": 1,
-    "enable_jq_parsing": true,
-    "theme": "dark"
+    "log_max_kb": 40,
+    "extended_signals": false,
+    "heartbeat_thresholds": {
+      "monitor": 3600,
+      "watchdog": 300,
+      "default": 1800
+    }
   },
   "cardinal_rules": {
-    "subagent_model": "haiku",
-    "orchestrator_model": "opus",
-    "tdd_first": true,
-    "never_push_main": true,
-    "secret_scan_gates_push": true
+    "subagent_model": "haiku"
+  },
+  "alerts": {
+    "_comment": "Slack/Discord webhook integration for fleet alerts. webhook_url: null (default) disables alerts (feature opt-in). SETUP: (1) Slack: Create an app at https://api.slack.com/apps, enable 'Incoming Webhooks', add a new webhook to your channel, copy the Webhook URL. (2) Discord: In your Discord server, go to Server Settings > Integrations > Webhooks, create a webhook, copy its URL. SECURITY: NEVER commit a real webhook URL to version control — retrieve at runtime via environment variable AESOP_ALERTS_WEBHOOK_URL or load from a .env.local file. Provider: 'slack' (block-kit format) or 'discord' (embed format). min_severity: filter by HIGH/CRITICAL/etc. heartbeat_stall_s: alert if watchdog heartbeat older than N seconds (null = skip).",
+    "webhook_url": null,
+    "provider": "slack",
+    "min_severity": "HIGH",
+    "heartbeat_stall_s": 600
   }
 }

package/bin/CLAUDE.md

@@ -0,0 +1,67 @@
+# bin/ — CLI scaffolder
+
+**Purpose**: Node.js CLI entry point that clones the aesop orchestration template into a target directory with idempotent validation, plus an interactive onboarding wizard for new adopters.
+
+## Invocation
+
+- **npm registry**: `npx @matt82198/aesop [target-dir]` (default: `aesop-fleet`)
+- **Local dev**: `node bin/cli.js [target-dir]`
+- **Help**: `npx @matt82198/aesop --help` or `-h`
+- **Interactive wizard**: `npx @matt82198/aesop wizard` (on a TTY, prompts; with `--yes`, uses defaults)
+
+## What gets copied
+
+Files in `filesToCopy` array (cli.js line 57–69):
+- **Directories**: `daemons/`, `dash/`, `monitor/`, `tools/`, `ui/`, `docs/`
+- **Files**: `aesop.config.example.json`, `README.md`, `LICENSE`, `CHANGELOG.md`, `CLAUDE-TEMPLATE.md`
+- **Brain templates** (in docs/): `MEMORY-TEMPLATE.md` (via docs/ directory copy)
+
+## What does NOT get copied
+
+- `aesop.config.json` (users must `cp aesop.config.example.json` and edit)
+- `state/` (runtime durable state, git-ignored, created by daemons)
+- `.git/`, `node_modules/`, build artifacts
+
+## Post-scaffold guidance
+
+Scaffolder prints steps for users:
+1. `cd target-dir && cp aesop.config.example.json aesop.config.json`
+2. Edit config with paths and repos
+3. Initialize brain: `cp CLAUDE-TEMPLATE.md ~/.claude/CLAUDE.md` (edit)
+4. Initialize memory: `cp docs/MEMORY-TEMPLATE.md ~/.claude/MEMORY.md` (edit)
+5. Test daemon: `bash daemons/run-watchdog.sh --once`
+6. Launch dashboard: `python ui/serve.py`
+
+## Interactive wizard (`aesop wizard`)
+
+The wizard mode provides an interactive onboarding flow for new adopters, guiding them through fleet setup in ~60 seconds:
+
+1. **Trigger**: `npx @matt82198/aesop wizard` on a TTY (interactive terminal)
+2. **Questions** (all have sensible defaults, press Enter-Enter-Enter to skip):
+   - Project name (default: "my-fleet")
+   - Repos to watch (auto-discovers git repos under `~`, offers choices)
+   - Dashboard port (default: 8770, validates 1–65535)
+   - Brain root directory (default: `~/.claude`)
+3. **Output**:
+   - Scaffolds template files
+   - Generates CLAUDE.md (substituted with project name)
+   - Generates aesop.config.json (with discovered repos)
+   - Prints "next 3 commands" epilogue
+   - Offers to run `watchdog --once` smoke test immediately
+4. **Non-interactive mode** (`--yes` flag or non-TTY stdin): Uses defaults, zero prompts (CI-safe)
+
+### Wizard implementation details
+
+- **Repo discovery** (`discoverRepos`): Scans `~` for `.git` directories at first level (non-recursive)
+- **Port validation** (`validatePort`): Rejects invalid ports, accepts 1–65535
+- **Portable paths**: All config paths use `~` form (`~/.claude`, `~/scripts`, etc.) for cross-platform compatibility
+- **Defaults**: Every prompt has a default so users can skip it (press Enter)
+- **Non-destructive**: Never overwrites existing `aesop.config.json` without user confirmation
+
+## Invariants & gotchas
+
+- **Idempotent on empty targets**: Fails if `targetDir` exists and is non-empty (non-destructive). Safe to retry.
+- **Adding shipped files**: Any new file/dir added to `filesToCopy` array must also be added to `package.json` `files` array (lines 9–21 in package.json) so npm publish includes it.
+- **No machine-specific paths**: Use relative paths only; `__dirname` and `path.join()` handle cross-platform resolution.
+- **Wizard prompts are async**: Main execution is wrapped in async IIFE to support readline prompts
+- **Help text accuracy**: If invocation steps or output paths change, update help text