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

package/README.md

@@ -9,345 +9,170 @@
 <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
-```
-
-### 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
-
-```
-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)
-```
-
-### Operating the harness
-
-#### 1. Bootstrap
-
-```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
-```
-
-#### 2. Start the watchdog daemon
+## How It Works
 
-```bash
-export AESOP_ROOT=$HOME/aesop
-bash $AESOP_ROOT/daemons/run-watchdog.sh &
 ```
-
-Runs every 150s: discovers changed repos, stashes uncommitted work, pushes backups to `backup/wip-*` branches, runs secret-scan gate.
-
-#### 3. Launch the Web Dashboard (Primary Interface)
-
-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.
-
-```bash
-python $AESOP_ROOT/ui/serve.py
+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
 ```
 
-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.
+See [docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md) for cost analysis and parallel patterns.
 
-#### (Optional) Legacy TUI Dashboard
+## Use with Claude Code
 
-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.
+Then in Claude Code, type `/power` or `/buildsystem` to start a wave cycle. See [skills/power/SKILL.md](./skills/power/SKILL.md) for details.
 
-#### 4. Arm the monitor loop
+## Core Principles
 
-```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.
-```
-
-## Cardinal Rules (abridged)
-
-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
+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.
 
-```bash
-export AESOP_ROOT=$HOME/aesop
-bash $AESOP_ROOT/daemons/run-watchdog.sh &
-```
-
-Test mode: `bash $AESOP_ROOT/daemons/run-watchdog.sh --once`
-
-### 5. Launch the dashboard
-
-```bash
-bash ~/aesop/dash/watchdog-gui.sh
-```
-
-### 6. Arm the monitor (optional)
-
-If you're using Claude Code, add this to your orchestrator loop:
-```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)
-```
-
-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.
+## Extending Aesop
 
-### Heartbeat pattern
+**Custom signal collectors**: Edit `monitor/collect-signals.mjs` to add domain-specific health checks.
 
-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).
+**Custom watchdog hooks**: Edit `daemons/backup-fleet.sh` to run linters, integrate with your CI, or customize secret-scan logic.
 
-## Security & Privacy
-
-**⚠️ 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`).
-
-- `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).
-
-## Extension points
-
-### 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 panels**: Edit `ui/serve.py` or `dash/watchdog-gui.sh` to surface your metrics.
 
 ## Troubleshooting
 
-### Watchdog doesn't start
-
-Check `state/FLEET-BACKUP.log` for errors. Verify `AESOP_ROOT` is set correctly.
-
-### Dashboard shows "unavailable"
+| 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 |
 
-- 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.
+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
 
-### Secret-scan blocks a legitimate push
+See [CHANGELOG.md](./CHANGELOG.md) for release notes.
 
-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,48 @@
 {
-  "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: validate clone targets remain under this root)",
+    "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"
   }
 }

package/bin/CLAUDE.md

@@ -0,0 +1,39 @@
+# bin/ — CLI scaffolder
+
+**Purpose**: Node.js CLI entry point that clones the aesop orchestration template into a target directory with idempotent validation.
+
+## 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`
+
+## 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`
+
+## 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.
+- **Help text accuracy**: If invocation steps or output paths change, update help text (lines 27–31).