aether-colony 5.2.1 → 5.3.0

package/.aether/utils/queen.sh

@@ -1391,8 +1391,7 @@ _colony_depth() {
             local new_depth="${2:-}"
             case "$new_depth" in
                 light|standard|deep|full)
-                    local tmp="${DATA_DIR}/COLONY_STATE.json.tmp.$$"
-                    jq --arg d "$new_depth" '.colony_depth = $d' "$DATA_DIR/COLONY_STATE.json" > "$tmp" && mv "$tmp" "$DATA_DIR/COLONY_STATE.json"
+                    NEW_DEPTH="$new_depth" _state_mutate '.colony_depth = env.NEW_DEPTH'
                     json_ok "$(jq -n --arg depth "$new_depth" '{depth: $depth, updated: true}')"
                     ;;
                 *)
@@ -1476,8 +1475,7 @@ _queen_write_charter() {
         local current_name
         current_name=$(jq -r '.colony_name // empty' "$DATA_DIR/COLONY_STATE.json" 2>/dev/null) || true
         if [[ -z "$current_name" && -n "$cw_colony_name" ]]; then
-            local tmp_state="${DATA_DIR}/COLONY_STATE.json.tmp.$$"
-            jq --arg cn "$cw_colony_name" '.colony_name = $cn' "$DATA_DIR/COLONY_STATE.json" > "$tmp_state" && mv "$tmp_state" "$DATA_DIR/COLONY_STATE.json"
+            CW_COLONY_NAME="$cw_colony_name" _state_mutate '.colony_name = env.CW_COLONY_NAME'
         fi
     fi
 

package/.aether/utils/state-api.sh

@@ -96,11 +96,32 @@ _state_write() {
 
 _state_mutate() {
     # Read-modify-write COLONY_STATE.json with a jq expression
-    # Usage: state-mutate '<jq_expression>'
+    # Usage: state-mutate [--arg NAME VALUE] [--argjson NAME VALUE] '<jq_expression>'
+    # Supports jq --arg, --argjson, --slurpfile, --rawfile flags (forwarded to jq)
     # Acquires lock, creates backup, applies jq, validates, writes atomically
     # Returns: json_ok with mutated:true, or json_err on failure
 
-    sm_expr="${1:-}"
+    # Parse jq flags (--arg, --argjson, --slurpfile, --rawfile) from arguments
+    # The jq expression is always the last argument (after all flags)
+    local sm_jq_flags=()
+    local sm_expr=""
+    local i=0
+    local args=("$@")
+
+    while [[ $i -lt ${#args[@]} ]]; do
+        case "${args[$i]}" in
+            --arg|--argjson|--slurpfile|--rawfile)
+                # Flag requires a name and value — consume next two args
+                sm_jq_flags+=("${args[$i]}" "${args[$((i+1))]}" "${args[$((i+2))]}")
+                i=$((i + 3))
+                ;;
+            *)
+                # Last argument is the jq expression
+                sm_expr="${args[$i]}"
+                i=$((i + 1))
+                ;;
+        esac
+    done
 
     if [[ -z "$sm_expr" ]]; then
         json_err "$E_VALIDATION_FAILED" "state-mutate requires a jq expression argument"
@@ -122,8 +143,8 @@ _state_mutate() {
         fi
     fi
 
-    # Apply jq expression to current state
-    sm_updated=$(jq "$sm_expr" "$sm_state_file" 2>/dev/null) || {
+    # Apply jq expression to current state (with forwarded flags)
+    sm_updated=$(jq ${sm_jq_flags[@]+"${sm_jq_flags[@]}"} "$sm_expr" "$sm_state_file" 2>/dev/null) || {
         release_lock 2>/dev/null || true  # SUPPRESS:OK -- cleanup: lock may not be held
         json_err "$E_JSON_INVALID" "jq expression failed: $sm_expr"
     }

package/.aether/utils/swarm.sh

@@ -32,7 +32,7 @@ _autofix_checkpoint() {
         label="${1:-autofix-$(date +%s)}"
         stash_name="aether-checkpoint: $label"
         # Only stash Aether-managed directories, never touch user files
-        if git stash push -m "$stash_name" -- $target_dirs >/dev/null 2>&1; then  # SUPPRESS:OK -- existence-test: stash operation may fail
+        if git stash push -m "$stash_name" -- $target_dirs ":(exclude).aether/data/" >/dev/null 2>&1; then  # SUPPRESS:OK -- existence-test: stash operation may fail
           json_ok "$(jq -n --arg ref "$stash_name" '{type: "stash", ref: $ref}')"
         else
           # Stash failed (possibly due to conflicts), record commit hash

package/.aether/utils/worktree.sh

@@ -0,0 +1,189 @@
+#!/bin/bash
+# Worktree utility functions -- extracted from aether-utils.sh
+# Provides: _worktree_create, _worktree_cleanup
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, atomic_write, acquire_lock,
+# release_lock, DATA_DIR, COLONY_DATA_DIR, SCRIPT_DIR, AETHER_ROOT, error
+# constants) is available.
+
+# Default worktree location relative to AETHER_ROOT
+WORKTREE_BASE_DIR="${AETHER_ROOT}/.aether/worktrees"
+
+# _worktree_create
+# Creates a git worktree for an agent working on a specific task.
+#
+# Usage: _worktree_create --branch <branch-name> [--base <base-branch>] [--task-id <task-id>]
+# Returns JSON: {ok:true, result:{path, branch, base, worktree_dir, task_id}}
+_worktree_create() {
+    local branch=""
+    local base=""
+    local task_id=""
+
+    # Parse arguments
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --branch) branch="${2:-}"; shift 2 ;;
+            --base)   base="${2:-}";   shift 2 ;;
+            --task-id) task_id="${2:-}"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    # Validate required arguments
+    if [[ -z "$branch" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Usage: worktree-create --branch <branch-name> [--base <base-branch>] [--task-id <task-id>]"
+    fi
+
+    # Sanitize branch name: reject obviously dangerous patterns
+    if [[ "$branch" == *..* ]] || [[ "$branch" == */* ]] || [[ "$branch" == *\\* ]]; then
+        json_err "$E_VALIDATION_FAILED" "Branch name must not contain '..', '/', or backslashes"
+    fi
+
+    # Default base to current branch
+    if [[ -z "$base" ]]; then
+        base=$(git -C "$AETHER_ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "main")
+    fi
+
+    local worktree_dir="$WORKTREE_BASE_DIR/$branch"
+
+    # Check if worktree already exists
+    if [[ -d "$worktree_dir" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Worktree already exists for branch '$branch' at $worktree_dir"
+    fi
+
+    # Check if branch already exists as a git branch (would indicate duplicate)
+    if git -C "$AETHER_ROOT" show-ref --verify --quiet "refs/heads/$branch" 2>/dev/null; then
+        json_err "$E_VALIDATION_FAILED" "Branch '$branch' already exists"
+    fi
+
+    # Ensure base branch exists
+    if ! git -C "$AETHER_ROOT" show-ref --verify --quiet "refs/heads/$base" 2>/dev/null; then
+        json_err "$E_GIT_ERROR" "Base branch '$base' does not exist"
+    fi
+
+    # Ensure parent directory exists
+    mkdir -p "$WORKTREE_BASE_DIR"
+
+    # Create the worktree (git worktree add creates the branch automatically)
+    if ! git -C "$AETHER_ROOT" worktree add "$worktree_dir" -b "$branch" "$base" >/dev/null 2>&1; then
+        json_err "$E_GIT_ERROR" "Failed to create worktree for branch '$branch'"
+    fi
+
+    # Copy .aether/data/ structure to the new worktree so the agent has colony context
+    # Per state-contract-design.md, branch-local state lives in .aether/data/ (gitignored)
+    # and each worktree gets its own independent copy for colony context isolation.
+    if [[ -d "$AETHER_ROOT/.aether/data" ]]; then
+        mkdir -p "$worktree_dir/.aether/data"
+        cp -r "$AETHER_ROOT/.aether/data/." "$worktree_dir/.aether/data/" 2>/dev/null || true  # SUPPRESS:OK -- copy: data dir may be empty
+    fi
+
+    # Copy exchange scripts so xml-utils.sh can source pheromone-xml.sh etc.
+    if [[ -d "$AETHER_ROOT/.aether/exchange" ]]; then
+        mkdir -p "$worktree_dir/.aether/exchange"
+        cp -r "$AETHER_ROOT/.aether/exchange/." "$worktree_dir/.aether/exchange/" 2>/dev/null || true
+    fi
+
+    # Inject main's pheromone signals into the worktree (per D-01)
+    # Non-blocking: if injection fails, worktree still works without injected signals
+    if [[ -f "$worktree_dir/.aether/data/pheromones.json" ]]; then
+      local main_head
+      main_head=$(git -C "$AETHER_ROOT" rev-parse HEAD 2>/dev/null || echo "unknown")
+      (
+        cd "$worktree_dir" 2>/dev/null && \
+        DATA_DIR="$worktree_dir/.aether/data" \
+        COLONY_DATA_DIR="$worktree_dir/.aether/data" \
+        bash "$AETHER_ROOT/.aether/aether-utils.sh" \
+          pheromone-snapshot-inject --from-branch "$base" --from-commit "$main_head" \
+        >/dev/null 2>&1 || true
+      )
+    fi
+
+    # Build result JSON
+    local result
+    result=$(jq -n \
+        --arg path "$worktree_dir" \
+        --arg branch "$branch" \
+        --arg base "$base" \
+        --arg worktree_dir "$worktree_dir" \
+        --arg task_id "${task_id:-null}" \
+        '{
+            path: $path,
+            branch: $branch,
+            base: $base,
+            worktree_dir: $worktree_dir,
+            task_id: (if $task_id == "null" then null else $task_id end)
+        }')
+
+    json_ok "$result"
+}
+
+# _worktree_cleanup
+# Removes a git worktree and cleans up tracking.
+#
+# Usage: _worktree_cleanup --branch <branch-name> [--force]
+# Returns JSON: {ok:true, result:{removed, branch, path}}
+_worktree_cleanup() {
+    local branch=""
+    local force=false
+
+    # Parse arguments
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --branch) branch="${2:-}"; shift 2 ;;
+            --force)  force=true; shift ;;
+            *) shift ;;
+        esac
+    done
+
+    # Validate required arguments
+    if [[ -z "$branch" ]]; then
+        json_err "$E_VALIDATION_FAILED" "Usage: worktree-cleanup --branch <branch-name> [--force]"
+    fi
+
+    # Sanitize branch name
+    if [[ "$branch" == *..* ]] || [[ "$branch" == */* ]] || [[ "$branch" == *\\* ]]; then
+        json_err "$E_VALIDATION_FAILED" "Branch name must not contain '..', '/', or backslashes"
+    fi
+
+    local worktree_dir="$WORKTREE_BASE_DIR/$branch"
+
+    # Check if worktree exists
+    if [[ ! -d "$worktree_dir" ]]; then
+        json_err "$E_RESOURCE_NOT_FOUND" "No worktree found for branch '$branch'"
+    fi
+
+    # Check for uncommitted changes (unless --force)
+    # Exclude .aether/ files since they are branch-local state copies, not user changes
+    if [[ "$force" == "false" ]]; then
+        local dirty_count
+        dirty_count=$(git -C "$worktree_dir" status --porcelain 2>/dev/null \
+            | grep -v '\.aether/' \
+            | wc -l \
+            | tr -d ' ') || dirty_count=0
+
+        if [[ "$dirty_count" -gt 0 ]]; then
+            json_err "$E_VALIDATION_FAILED" "Worktree '$branch' has $dirty_count uncommitted changes. Use --force to remove anyway."
+        fi
+    fi
+
+    # Remove the worktree using git worktree remove
+    if ! git -C "$AETHER_ROOT" worktree remove "$worktree_dir" --force 2>/dev/null; then
+        # Fallback: manual cleanup if git worktree remove fails
+        rm -rf "$worktree_dir" 2>/dev/null || true
+        # Also prune stale worktree entries
+        git -C "$AETHER_ROOT" worktree prune 2>/dev/null || true
+    fi
+
+    # Attempt to delete the branch (best-effort -- may fail if branch is checked out elsewhere)
+    git -C "$AETHER_ROOT" branch -D "$branch" >/dev/null 2>&1 || true
+
+    # Build result JSON
+    local result
+    result=$(jq -n \
+        --arg branch "$branch" \
+        --arg path "$worktree_dir" \
+        '{removed: true, branch: $branch, path: $path}')
+
+    json_ok "$result"
+}

package/.claude/commands/ant/init.md

@@ -41,7 +41,6 @@ Do not touch during init:
 - .aether/dreams/ (user notes)
 - .aether/chambers/ (archived colonies)
 - .env* files
-- .claude/settings.json
 - .github/workflows/
 </read_only>
 
@@ -365,7 +364,14 @@ domain_tags=$(bash .aether/aether-utils.sh domain-detect 2>/dev/null | jq -r '.r
 bash .aether/aether-utils.sh registry-add "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" --goal "{approved_intent}" --active true --tags "$domain_tags" 2>/dev/null || true
 cp ~/.aether/version.json .aether/version.json 2>/dev/null || true
 ```
-11. Seed QUEEN.md from hive (non-blocking):
+11. Install clash detection hook and merge driver (non-blocking):
+```bash
+# Install PreToolUse hook to detect file conflicts across worktrees
+bash .aether/aether-utils.sh clash-setup --install 2>/dev/null || true
+# Register lockfile merge driver (keeps "ours" on package-lock.json conflicts)
+git config merge.lockfile.driver "bash .aether/utils/merge-driver-lockfile.sh %O %A %B" 2>/dev/null || true
+```
+12. Seed QUEEN.md from hive (non-blocking):
 ```bash
 domain_tags=$(jq -r --arg repo "$(pwd)" \
   '[.repos[] | select(.path == $repo) | .domain_tags // []] | .[0] // [] | join(",")' \
@@ -375,7 +381,7 @@ seed_args="queen-seed-from-hive --limit 5"
 seed_result=$(bash .aether/aether-utils.sh $seed_args 2>/dev/null || echo '{}')
 seeded_count=$(echo "$seed_result" | jq -r '.result.seeded // 0' 2>/dev/null || echo "0")
 ```
-12. Run `bash .aether/aether-utils.sh session-init "{session_id}" "{approved_intent}"`
+13. Run `bash .aether/aether-utils.sh session-init "{session_id}" "{approved_intent}"`
 
 **Pheromone auto-apply (referenced by both re-init and fresh init paths above):**
 

package/.opencode/commands/ant/init.md

@@ -377,7 +377,14 @@ domain_tags=$(bash .aether/aether-utils.sh domain-detect 2>/dev/null | jq -r '.r
 bash .aether/aether-utils.sh registry-add "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" --goal "{approved_intent}" --active true --tags "$domain_tags" 2>/dev/null || true
 cp ~/.aether/version.json .aether/version.json 2>/dev/null || true
 ```
-11. Seed QUEEN.md from hive (non-blocking):
+11. Install clash detection hook and merge driver (non-blocking):
+```bash
+# Install PreToolUse hook to detect file conflicts across worktrees
+bash .aether/aether-utils.sh clash-setup --install 2>/dev/null || true
+# Register lockfile merge driver (keeps "ours" on package-lock.json conflicts)
+git config merge.lockfile.driver "bash .aether/utils/merge-driver-lockfile.sh %O %A %B" 2>/dev/null || true
+```
+12. Seed QUEEN.md from hive (non-blocking):
 ```bash
 domain_tags=$(jq -r --arg repo "$(pwd)" \
   '[.repos[] | select(.path == $repo) | .domain_tags // []] | .[0] // [] | join(",")' \
@@ -387,7 +394,7 @@ seed_args="queen-seed-from-hive --limit 5"
 seed_result=$(bash .aether/aether-utils.sh $seed_args 2>/dev/null || echo '{}')
 seeded_count=$(echo "$seed_result" | jq -r '.result.seeded // 0' 2>/dev/null || echo "0")
 ```
-12. Run `bash .aether/aether-utils.sh session-init "{session_id}" "{approved_intent}"`
+13. Run `bash .aether/aether-utils.sh session-init "{session_id}" "{approved_intent}"`
 
 **Pheromone auto-apply (referenced by both re-init and fresh init paths above):**
 

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.3.0] - 2026-03-31
+
+Aether v2.7 — PR Workflow + Stability. Six phases (39-44) adding multi-branch safety, clash detection, and release hardening.
+
+### Added
+- **Pheromone propagation** — Signals flow across git branches via `pheromone-snapshot-inject` and `pheromone-merge-back`; worktree creation auto-copies active pheromones
+- **Midden collection** — Failure records from merged branches collected into main via `midden-collect` with idempotent dedup; cross-PR pattern detection via `midden-cross-pr-analysis`; revert-aware tagging via `midden-handle-revert`
+- **Clash detection** — PreToolUse hook (`clash-pre-tool-use.js`) blocks edits to files modified in other active worktrees; `.aether/data/` files allowlisted (branch-local state)
+- **Worktree utilities** — `_worktree_create` auto-copies colony context (COLONY_STATE.json, pheromones.json) and runs pheromone-snapshot-inject
+- **Merge driver** — `.gitattributes` merge driver resolves package-lock.json conflicts by keeping "ours" via `merge-driver-lockfile.sh`
+- **Midden wiring** — `midden-collect` and `midden-cross-pr-analysis` wired into `/ant:continue` playbooks (non-blocking, follows pheromone merge-back pattern)
+- **Interactive installer** — `npx aether-colony` now shows a 3-option menu (Full setup / Global only / Repo only) with environment detection and context-sensitive defaults; supports `--global`, `--repo`, `--yes` flags for scripting
+- **`aether setup` command** — CLI equivalent of `/ant:lay-eggs` for setting up Aether in a repo without Claude Code open
+
+### Changed
+- **Package validation** — `validate-package.sh` expanded from 15 to 38+ required file entries (100% coverage of packaged utils)
+- **NPX installer** — Replaced `npx-install.js` with interactive `npx-entry.js`; old installer kept as deprecation redirect
+- **Package cleanliness** — 8 dev-only files excluded from npm tarball (scripts/, design docs, example schemas)
+- **CLAUDE.md** — Full accuracy audit: version bumped to v2.7.0, all counts verified (5,500 lines, 35 utils, 45 commands, 509 tests)
+- **README.md** — Architecture counts updated (35 utils, 45 commands, ~5,500 lines)
+- **YAML commands** — 6 stale command files regenerated from YAML sources (init, plan, seal for Claude and OpenCode)
+
+### Fixed
+- **Clash detection dispatcher** — `clash-detect.sh` and `worktree.sh` wired into `aether-utils.sh` dispatcher (source lines, dispatch cases, help JSON)
+- **Init command** — Clash detection hook verification and read-only worktree list integrated into `/ant:init` Step 7.6
+
 ## [2.1.0] - 2026-03-24
 
 Six phases of production hardening (Phases 9-14) targeting reliability, maintainability, and developer experience.

package/README.md

@@ -18,7 +18,7 @@ Spawn a colony of 24 AI specialists that self-organize around your goal using ph
 *The whole is greater than the sum of its ants.*
 
 ```bash
-npm install -g aether-colony
+npx aether-colony
 ```
 
 </div>
@@ -72,7 +72,10 @@ The colony **remembers**. Wisdom, learnings, and instincts persist across sessio
 ## 🚀 Quick Start
 
 ```bash
-# Install globally
+# Interactive setup (recommended)
+npx aether-colony
+
+# Or install globally
 npm install -g aether-colony
 
 # In your project repo:
@@ -88,7 +91,7 @@ That's it. Five commands from zero to shipped.
 ## ✨ Key Features
 
 - 🐜 **24 Specialized Agents** — Real subagents spawned via Task tool, from builders to archaeologists
-- ⚡ **44 Slash Commands** — Full lifecycle management across Claude Code and OpenCode
+- ⚡ **45 Slash Commands** — Full lifecycle management across Claude Code and OpenCode
 - 🎯 **Pheromone System** — Guide the colony with FOCUS, REDIRECT, FEEDBACK signals
 - 🧠 **Colony Memory** — Learnings persist across sessions via QUEEN.md wisdom
 - 🌐 **Hive Brain** — Cross-colony wisdom sharing with domain-scoped retrieval
@@ -212,10 +215,10 @@ That's it. Five commands from zero to shipped.
 
 ```
 .aether/                      # 🐜 Colony files (repo-local)
-├── aether-utils.sh           # ⚡ Dispatcher (~5,200 lines, ~150 subcommands)
-├── utils/                    # 🔧 ~29 modular scripts
+├── aether-utils.sh           # ⚡ Dispatcher (~5,500 lines, ~130+ subcommands)
+├── utils/                    # 🔧 35 modular scripts
 ├── skills/                   # 📚 28 skills (10 colony + 18 domain)
-├── commands/                 # 📖 44 YAML command sources
+├── commands/                 # 📖 45 YAML command sources
 ├── exchange/                 # 📤 XML exchange modules
 ├── docs/                     # 📝 Documentation
 ├── templates/                # 📋 12 templates
@@ -229,8 +232,8 @@ That's it. Five commands from zero to shipped.
 
 ## 🔌 Works With
 
-- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — 44 slash commands + 24 agent definitions
-- **[OpenCode](https://github.com/opencode-ai/opencode)** — 44 slash commands + agent definitions
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — 45 slash commands + 24 agent definitions
+- **[OpenCode](https://github.com/opencode-ai/opencode)** — 45 slash commands + agent definitions
 
 ## ❤️ Support Aether
 

package/bin/cli.js

@@ -1313,79 +1313,111 @@ program.on('option:quiet', () => {
   globalQuiet = true;
 });
 
-// Install command
-program
-  .command('install')
-  .description('Install commands and agents to ~/.claude/ and set up distribution hub')
-  .action(wrapCommand(async () => {
-    log(c.header(`aether-colony v${VERSION} — installing...`));
-
-    // Sync commands to ~/.claude/commands/ant/ (with orphan cleanup)
-    if (!fs.existsSync(COMMANDS_SRC)) {
-      // Running from source repo — commands are in .claude/commands/ant/
-      const repoCommands = path.join(PACKAGE_DIR, '.claude', 'commands', 'ant');
-      if (fs.existsSync(repoCommands)) {
-        const result = syncDirWithCleanup(repoCommands, COMMANDS_DEST);
-        log(`  Commands: ${result.copied} files -> ${COMMANDS_DEST}`);
-        if (result.removed.length > 0) {
-          log(`  Commands: removed ${result.removed.length} stale files`);
-          for (const f of result.removed) log(`    - ${f}`);
-        }
-      } else {
-        console.error('  Commands source not found. Skipping.');
-      }
-    } else {
-      const result = syncDirWithCleanup(COMMANDS_SRC, COMMANDS_DEST);
+/**
+ * Perform a global installation of commands, agents, and hub setup.
+ * Extracted so it can be called from the interactive installer.
+ */
+async function performGlobalInstall() {
+  log(c.header(`aether-colony v${VERSION} — installing...`));
+
+  // Sync commands to ~/.claude/commands/ant/ (with orphan cleanup)
+  if (!fs.existsSync(COMMANDS_SRC)) {
+    // Running from source repo — commands are in .claude/commands/ant/
+    const repoCommands = path.join(PACKAGE_DIR, '.claude', 'commands', 'ant');
+    if (fs.existsSync(repoCommands)) {
+      const result = syncDirWithCleanup(repoCommands, COMMANDS_DEST);
       log(`  Commands: ${result.copied} files -> ${COMMANDS_DEST}`);
       if (result.removed.length > 0) {
         log(`  Commands: removed ${result.removed.length} stale files`);
         for (const f of result.removed) log(`    - ${f}`);
       }
+    } else {
+      console.error('  Commands source not found. Skipping.');
+    }
+  } else {
+    const result = syncDirWithCleanup(COMMANDS_SRC, COMMANDS_DEST);
+    log(`  Commands: ${result.copied} files -> ${COMMANDS_DEST}`);
+    if (result.removed.length > 0) {
+      log(`  Commands: removed ${result.removed.length} stale files`);
+      for (const f of result.removed) log(`    - ${f}`);
     }
+  }
 
-    // Sync agents to ~/.claude/agents/ant/ (with orphan cleanup)
-    const repoAgents = path.join(PACKAGE_DIR, '.claude', 'agents', 'ant');
-    if (fs.existsSync(repoAgents)) {
-      const result = syncDirWithCleanup(repoAgents, AGENTS_DEST);
-      log(`  Agents (claude): ${result.copied} files -> ${AGENTS_DEST}`);
-      if (result.removed.length > 0) {
-        log(`  Agents (claude): removed ${result.removed.length} stale files`);
-        for (const f of result.removed) log(`    - ${f}`);
-      }
+  // Sync agents to ~/.claude/agents/ant/ (with orphan cleanup)
+  const repoAgents = path.join(PACKAGE_DIR, '.claude', 'agents', 'ant');
+  if (fs.existsSync(repoAgents)) {
+    const result = syncDirWithCleanup(repoAgents, AGENTS_DEST);
+    log(`  Agents (claude): ${result.copied} files -> ${AGENTS_DEST}`);
+    if (result.removed.length > 0) {
+      log(`  Agents (claude): removed ${result.removed.length} stale files`);
+      for (const f of result.removed) log(`    - ${f}`);
     }
+  }
 
-    // Sync OpenCode commands to ~/.opencode/command/ (with orphan cleanup)
-    const opencodeCmdsSrc = path.join(PACKAGE_DIR, '.opencode', 'commands', 'ant');
-    if (fs.existsSync(opencodeCmdsSrc)) {
-      const result = syncDirWithCleanup(opencodeCmdsSrc, OPENCODE_COMMANDS_DEST);
-      log(`  Commands (opencode): ${result.copied} files -> ${OPENCODE_COMMANDS_DEST}`);
-      if (result.removed.length > 0) {
-        log(`  Commands (opencode): removed ${result.removed.length} stale files`);
-        for (const f of result.removed) log(`    - ${f}`);
-      }
+  // Sync OpenCode commands to ~/.opencode/command/ (with orphan cleanup)
+  const opencodeCmdsSrc = path.join(PACKAGE_DIR, '.opencode', 'commands', 'ant');
+  if (fs.existsSync(opencodeCmdsSrc)) {
+    const result = syncDirWithCleanup(opencodeCmdsSrc, OPENCODE_COMMANDS_DEST);
+    log(`  Commands (opencode): ${result.copied} files -> ${OPENCODE_COMMANDS_DEST}`);
+    if (result.removed.length > 0) {
+      log(`  Commands (opencode): removed ${result.removed.length} stale files`);
+      for (const f of result.removed) log(`    - ${f}`);
     }
+  }
 
-    // Sync OpenCode agents to ~/.opencode/agent/ (with orphan cleanup)
-    const opencodeAgentsSrc = path.join(PACKAGE_DIR, '.opencode', 'agents');
-    if (fs.existsSync(opencodeAgentsSrc)) {
-      const result = syncDirWithCleanup(opencodeAgentsSrc, OPENCODE_AGENTS_DEST);
-      log(`  Agents (opencode): ${result.copied} files -> ${OPENCODE_AGENTS_DEST}`);
-      if (result.removed.length > 0) {
-        log(`  Agents (opencode): removed ${result.removed.length} stale files`);
-        for (const f of result.removed) log(`    - ${f}`);
-      }
+  // Sync OpenCode agents to ~/.opencode/agent/ (with orphan cleanup)
+  const opencodeAgentsSrc = path.join(PACKAGE_DIR, '.opencode', 'agents');
+  if (fs.existsSync(opencodeAgentsSrc)) {
+    const result = syncDirWithCleanup(opencodeAgentsSrc, OPENCODE_AGENTS_DEST);
+    log(`  Agents (opencode): ${result.copied} files -> ${OPENCODE_AGENTS_DEST}`);
+    if (result.removed.length > 0) {
+      log(`  Agents (opencode): removed ${result.removed.length} stale files`);
+      for (const f of result.removed) log(`    - ${f}`);
     }
+  }
 
-    // Set up distribution hub at ~/.aether/
-    log('');
-    log(c.colony('Setting up distribution hub...'));
-    setupHub();
+  // Set up distribution hub at ~/.aether/
+  log('');
+  log(c.colony('Setting up distribution hub...'));
+  setupHub();
 
-    log('');
-    log(c.success('Install complete.'));
-    log(`  ${c.queen('Claude Code:')} run /ant to get started`);
-    log(`  ${c.colony('OpenCode:')} run /ant to get started`);
-    log(`  ${c.colony('Hub:')} ${c.dim('~/.aether/')} (for coordinated updates across repos)`);
+  log('');
+  log(c.success('Install complete.'));
+  log(`  ${c.queen('Claude Code:')} run /ant to get started`);
+  log(`  ${c.colony('OpenCode:')} run /ant to get started`);
+  log(`  ${c.colony('Hub:')} ${c.dim('~/.aether/')} (for coordinated updates across repos)`);
+}
+
+// Install command
+program
+  .command('install')
+  .description('Install commands and agents to ~/.claude/ and set up distribution hub')
+  .action(wrapCommand(performGlobalInstall));
+
+// Setup command — set up Aether in the current directory from hub
+program
+  .command('setup')
+  .description('Set up Aether in the current directory (copies system files from hub)')
+  .option('-f, --force', 'Overwrite existing setup')
+  .action(wrapCommand(async (options) => {
+    if (!fs.existsSync(HUB_VERSION)) {
+      console.error('Aether hub not installed.');
+      console.error('Run "npx aether-colony" or "aether install" to install the hub first.');
+      process.exit(1);
+    }
+    const repoPath = process.cwd();
+    log(c.header('Setting up Aether in this directory...'));
+    const result = await initializeRepo(repoPath, { setupOnly: true });
+    if (result.success) {
+      log('');
+      log(c.success('Aether is ready.'));
+      log(`  ${result.filesCopied} system files synced to .aether/`);
+      log('');
+      log('  Next steps:');
+      log('    In Claude Code: /ant:init "your goal"');
+      log('    Or terminal:    aether init --goal "your goal"');
+      log('');
+    }
   }));
 
 // Update command
@@ -2172,10 +2204,20 @@ module.exports = {
   syncDirWithCleanup,
   syncSkillsToHub,
   listFilesRecursive,
-  cleanEmptyDirs
+  cleanEmptyDirs,
+  performGlobalInstall,
+  run
 };
 
+/**
+ * Parse CLI arguments. Called automatically when run directly,
+ * or explicitly by npx-entry.js when delegating a subcommand.
+ */
+function run() {
+  program.parse();
+}
+
 // Parse command line arguments only when run directly (not when required as a module)
 if (require.main === module) {
-  program.parse();
+  run();
 }

package/bin/lib/banner.js

@@ -0,0 +1,14 @@
+/**
+ * Shared ASCII banner for Aether installers.
+ */
+
+const BANNER = `
+      █████╗ ███████╗████████╗██╗  ██╗███████╗██████╗
+     ██╔══██╗██╔════╝╚══██╔══╝██║  ██║██╔════╝██╔══██╗
+     ███████║█████╗     ██║   ███████║█████╗  ██████╔╝
+     ██╔══██║██╔══╝     ██║   ██╔══██║██╔══╝  ██╔══██╗
+     ██║  ██║███████╗   ██║   ██║  ██║███████╗██║  ██║
+     ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
+`;
+
+module.exports = { BANNER };

package/bin/lib/init.js

@@ -321,7 +321,7 @@ function validateInitialization(repoPath) {
  * @returns {object} Result: { success: boolean, stateFile: string|null, message: string }
  */
 async function initializeRepo(repoPath, options = {}) {
-  const { goal, skipIfExists = false, quiet = false } = options;
+  const { goal, skipIfExists = false, quiet = false, setupOnly = false } = options;
 
   // Check if already initialized
   if (isInitialized(repoPath) && skipIfExists) {
@@ -411,12 +411,13 @@ locks/
 `;
   fs.writeFileSync(gitignorePath, gitignoreContent);
 
-  // Create initial state
-  const state = createInitialState(goal);
-
-  // Write state file
-  const stateFile = path.join(repoPath, '.aether', 'data', 'COLONY_STATE.json');
-  fs.writeFileSync(stateFile, JSON.stringify(state, null, 2) + '\n');
+  // Create initial colony state (skipped in setupOnly mode)
+  let stateFile = null;
+  if (!setupOnly) {
+    const state = createInitialState(goal);
+    stateFile = path.join(repoPath, '.aether', 'data', 'COLONY_STATE.json');
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2) + '\n');
+  }
 
   // Get hub version
   const hubVersion = readJsonSafe(HUB_VERSION);