aether-colony 5.2.1 → 5.3.1

package/README.md

@@ -1,59 +1,54 @@
 <div align="center">
 
-# 🐜 Aether Colony
+<br>
 
-**Multi-agent AI development for Claude Code and OpenCode**
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./AetherLogo.png" />
+  <source media="(prefers-color-scheme: light)" srcset="./AetherLogo.png" />
+  <img src="./AetherLogo.png" alt="Aether" width="240" />
+</picture>
 
-[![npm version](https://img.shields.io/npm/v/aether-colony.svg?style=flat-square)](https://www.npmjs.com/package/aether-colony)
-[![npm downloads](https://img.shields.io/npm/dw/aether-colony.svg?style=flat-square)](https://www.npmjs.com/package/aether-colony)
-[![License: MIT](https://img.shields.io/github/license/calcosmic/Aether.svg?style=flat-square)](LICENSE)
-[![GitHub stars](https://img.shields.io/github/stars/calcosmic/Aether.svg?style=flat-square)](https://github.com/calcosmic/Aether/stargazers)
-[![Sponsor](https://img.shields.io/badge/Sponsor-GitHub-%23ea4aaa.svg?style=flat-square&logo=github)](https://github.com/sponsors/calcosmic)
+<br>
 
-Spawn a colony of 24 AI specialists that self-organize around your goal using pheromone signals.
-1,000+ weekly installs.
+# Aether
 
-*Artificial Ecology For Thought and Emergent Reasoning*
+### Artificial Ecology for Thought and Emergent Reasoning
 
-*The whole is greater than the sum of its ants.*
+<br>
 
-```bash
-npm install -g aether-colony
-```
+[![npm](https://img.shields.io/npm/v/aether-colony?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=7B3FE4)](https://www.npmjs.com/package/aether-colony)
+[![downloads](https://img.shields.io/npm/dw/aether-colony?style=for-the-badge&logo=npm&logoColor=white&color=333333)](https://www.npmjs.com/package/aether-colony)
+[![license](https://img.shields.io/github/license/calcosmic/Aether?style=for-the-badge&color=333333)](LICENSE)
+[![stars](https://img.shields.io/github/stars/calcosmic/Aether?style=for-the-badge&logo=github&logoColor=white&color=333333)](https://github.com/calcosmic/Aether/stargazers)
+[![sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?style=for-the-badge&logo=github-sponsors&logoColor=white)](https://github.com/sponsors/calcosmic)
 
-</div>
+<br>
 
-<p align="center">
-  <img src="./AetherAnts.png" alt="Aether Colony" width="640" />
-</p>
+Multi-agent AI development for **Claude Code** and **OpenCode**.
+<br>
+Spawn 24 specialists that self-organize around your goal using pheromone signals.
+
+<br>
 
 ```
-         👑 Queen (you)
-          │
-          │  set the goal, steer with pheromone signals
-          ▼
-    ┌─────────────────────────────────────────┐
-    │         Colony self-organizes            │
-    │                                         │
-    │  🔨 Builders      write code (TDD)      │
-    │  👁️ Watchers      verify & test          │
-    │  🔍 Scouts        research first         │
-    │  🐛 Trackers      investigate bugs       │
-    │  🗺️ Colonizers    explore codebases      │
-    │  📋 Route-setters plan phases            │
-    │  🏺 Archaeologists excavate git history  │
-    │  🎲 Chaos Ants    resilience testing     │
-    │  📚 Keepers       preserve knowledge     │
-    │  🔮 Oracle        deep research          │
-    │  ...and 24 specialists total             │
-    └─────────────────────────────────────────┘
+$ npx aether-colony
 ```
 
-## 🐜 The Problem
+<br>
+
+*The whole is greater than the sum of its ants.*
+
+<br>
+
+</div>
+
+---
+
+## The Problem
 
 AI coding assistants work sequentially — one agent does everything: research, code, test, review. When it hits something complex, it either guesses or asks you. There's no specialization, no parallel work, no memory across sessions.
 
-## 🐜 The Solution
+## The Solution
 
 Aether brings **ant colony intelligence** to AI-assisted development. Instead of one AI doing everything, you get a colony of specialists that self-organize around your goal.
 
@@ -62,196 +57,201 @@ Workers spawn workers dynamically (max depth 3, max 10 per phase). When a Builde
 You steer the colony with **pheromone signals**, not micromanagement:
 
 ```
-/ant:focus "security"              # 🎯 "Pay attention here"
-/ant:redirect "no jQuery"          # 🚫 "Don't do this" (hard constraint)
-/ant:feedback "prefer composition" # 💬 "Adjust based on this"
+/ant:focus "security"              # "Pay attention here"
+/ant:redirect "no jQuery"          # "Don't do this" (hard constraint)
+/ant:feedback "prefer composition" # "Adjust based on this"
 ```
 
-The colony **remembers**. Wisdom, learnings, and instincts persist across sessions. The 🧠 Hive Brain shares knowledge across colonies on your machine.
+The colony **remembers**. Wisdom, learnings, and instincts persist across sessions. The Hive Brain shares knowledge across colonies on your machine.
 
-## 🚀 Quick Start
+## Quick Start
 
 ```bash
-# Install globally
+# Interactive setup (recommended)
+npx aether-colony
+
+# Or install globally
 npm install -g aether-colony
+```
+
+Then in your project:
 
-# In your project repo:
-/ant:lay-eggs            # 🥚 Set up Aether (one-time)
-/ant:init "Build X"      # 🌱 Start a colony with a goal
-/ant:plan                # 📋 Generate phased roadmap
-/ant:run                 # 🐜 Autopilot: build, verify, advance all phases
-/ant:seal                # 🏺 Done — archive the colony
+```
+/ant:lay-eggs            # Set up Aether (one-time)
+/ant:init "Build X"      # Start a colony with a goal
+/ant:plan                # Generate phased roadmap
+/ant:run                 # Autopilot: build, verify, advance all phases
+/ant:seal                # Done — archive the colony
 ```
 
-That's it. Five commands from zero to shipped.
+Five commands from zero to shipped.
 
-## ✨ Key Features
+## 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
-- 🎯 **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
-- 📚 **Skills System** — 28 skills (10 colony + 18 domain) inject domain knowledge into workers
-- 🤖 **Autopilot** (`/ant:run`) — Automated build-verify-advance loop with smart pause conditions
-- ✅ **6-Phase Verification** — Build, types, lint, tests, security, diff gates before any phase advances
-- 🛡️ **Quality Gates** — Security (Gatekeeper), quality (Auditor), coverage (Probe), performance (Measurer)
-- 🔍 **Per-Phase Research** — Scouts investigate domain knowledge before task decomposition
-- 🔮 **Oracle Deep Research** — Autonomous research loop for complex investigations
-- 💾 **Pause/Resume** — Full state serialization for context breaks
+| | Feature | Description |
+|---|---------|-------------|
+| **Agents** | 24 Specialized Workers | Builders, Watchers, Scouts, Trackers, Archaeologists, Oracle, and more |
+| **Commands** | 45 Slash Commands | Full lifecycle management across Claude Code and OpenCode |
+| **Signals** | Pheromone System | Guide the colony with FOCUS, REDIRECT, and FEEDBACK signals |
+| **Memory** | Colony Wisdom | Learnings and instincts persist across sessions via QUEEN.md |
+| **Sharing** | Hive Brain | Cross-colony wisdom sharing with domain-scoped retrieval |
+| **Skills** | 28 Skills | 10 colony + 18 domain skills inject knowledge into workers |
+| **Autopilot** | `/ant:run` | Automated build-verify-advance loop with smart pause conditions |
+| **Verification** | 6-Phase Gates | Build, types, lint, tests, security, diff gates before advancing |
+| **Quality** | 4 Gate Agents | Security (Gatekeeper), quality (Auditor), coverage (Probe), performance (Measurer) |
+| **Research** | Oracle + Scouts | Deep autonomous research before task decomposition |
+| **State** | Pause/Resume | Full state serialization for context breaks |
 
-## 📖 Commands
+## Commands
 
 <details>
-<summary><strong>🏗️ Core Lifecycle</strong></summary>
+<summary><strong>Core Lifecycle</strong></summary>
 
 | Command | Description |
 |---------|-------------|
-| `/ant:lay-eggs` | 🥚 Set up Aether in this repo (one-time) |
-| `/ant:init "goal"` | 🌱 Initialize colony with mission |
-| `/ant:plan` | 📋 Generate phased roadmap with domain research |
-| `/ant:build N` | 🔨 Execute phase N with worker waves |
-| `/ant:continue` | ➡️ 6-phase verification, advance to next phase |
-| `/ant:run` | 🐜 Autopilot — build, verify, advance automatically |
-| `/ant:patrol` | 🔍 Pre-seal audit — verify work against plan |
-| `/ant:seal` | 🏺 Complete and archive colony |
-| `/ant:entomb` | ⚰️ Create chamber from completed colony |
-| `/ant:pause-colony` | 💾 Save state for context break |
-| `/ant:resume-colony` | 🚦 Restore from pause |
+| `/ant:lay-eggs` | Set up Aether in this repo (one-time) |
+| `/ant:init "goal"` | Initialize colony with mission |
+| `/ant:plan` | Generate phased roadmap with domain research |
+| `/ant:build N` | Execute phase N with worker waves |
+| `/ant:continue` | 6-phase verification, advance to next phase |
+| `/ant:run` | Autopilot — build, verify, advance automatically |
+| `/ant:patrol` | Pre-seal audit — verify work against plan |
+| `/ant:seal` | Complete and archive colony |
+| `/ant:entomb` | Create chamber from completed colony |
+| `/ant:pause-colony` | Save state for context break |
+| `/ant:resume-colony` | Restore from pause |
 
 </details>
 
 <details>
-<summary><strong>🎯 Pheromone Signals</strong></summary>
+<summary><strong>Pheromone Signals</strong></summary>
 
 | Command | Description |
 |---------|-------------|
-| `/ant:focus "area"` | 🎯 FOCUS — "Pay attention here" |
-| `/ant:redirect "pattern"` | 🚫 REDIRECT — "Don't do this" (hard constraint) |
-| `/ant:feedback "note"` | 💬 FEEDBACK — "Adjust based on this" |
-| `/ant:pheromones` | 📊 View active signals |
-| `/ant:export-signals` | 📤 Export signals to XML |
-| `/ant:import-signals` | 📥 Import signals from XML |
+| `/ant:focus "area"` | FOCUS — "Pay attention here" |
+| `/ant:redirect "pattern"` | REDIRECT — "Don't do this" (hard constraint) |
+| `/ant:feedback "note"` | FEEDBACK — "Adjust based on this" |
+| `/ant:pheromones` | View active signals |
+| `/ant:export-signals` | Export signals to XML |
+| `/ant:import-signals` | Import signals from XML |
 
 </details>
 
 <details>
-<summary><strong>🔬 Research & Analysis</strong></summary>
+<summary><strong>Research & Analysis</strong></summary>
 
 | Command | Description |
 |---------|-------------|
-| `/ant:colonize` | 📊🗺️ 4 parallel scouts analyze your codebase |
-| `/ant:oracle "topic"` | 🔮 Deep research with autonomous loop |
-| `/ant:archaeology <path>` | 🏺 Excavate git history for any file |
-| `/ant:chaos <target>` | 🎲 Resilience testing, edge case probing |
-| `/ant:swarm "problem"` | 🔥 4 parallel scouts for stubborn bugs |
-| `/ant:dream` | 💭 Philosophical codebase wanderer |
-| `/ant:interpret` | 🔍 Grounds dreams in reality |
-| `/ant:organize` | 🧹 Codebase hygiene report |
+| `/ant:colonize` | 4 parallel scouts analyze your codebase |
+| `/ant:oracle "topic"` | Deep research with autonomous loop |
+| `/ant:archaeology <path>` | Excavate git history for any file |
+| `/ant:chaos <target>` | Resilience testing, edge case probing |
+| `/ant:swarm "problem"` | 4 parallel scouts for stubborn bugs |
+| `/ant:dream` | Philosophical codebase wanderer |
+| `/ant:interpret` | Grounds dreams in reality |
+| `/ant:organize` | Codebase hygiene report |
 
 </details>
 
 <details>
-<summary><strong>👁️ Visibility & Status</strong></summary>
+<summary><strong>Visibility & Status</strong></summary>
 
 | Command | Description |
 |---------|-------------|
-| `/ant:status` | 📈 Colony overview with memory health |
-| `/ant:memory-details` | 🧠 Wisdom, pending promotions, recent failures |
-| `/ant:watch` | 👁️ Real-time swarm display |
-| `/ant:history` | 📜 Recent activity log |
-| `/ant:flags` | 🚩 List blockers and issues |
-| `/ant:help` | 🐜 Full command reference |
+| `/ant:status` | Colony overview with memory health |
+| `/ant:memory-details` | Wisdom, pending promotions, recent failures |
+| `/ant:watch` | Real-time swarm display |
+| `/ant:history` | Recent activity log |
+| `/ant:flags` | List blockers and issues |
+| `/ant:help` | Full command reference |
 
 </details>
 
 <details>
-<summary><strong>🔧 Coordination & Maintenance</strong></summary>
+<summary><strong>Coordination & Maintenance</strong></summary>
 
 | Command | Description |
 |---------|-------------|
-| `/ant:council` | 📜 Clarify intent via multi-choice questions |
-| `/ant:flag "title"` | 🚩 Create project-specific flag |
-| `/ant:data-clean` | 🧹 Remove test artifacts from colony data |
-| `/ant:preferences` | ⚙️ Add or list user preferences |
-| `/ant:skill-create "topic"` | 🐜 Create custom domain skill |
-| `/ant:update` | 🔄 Update system files from hub |
+| `/ant:council` | Clarify intent via multi-choice questions |
+| `/ant:flag "title"` | Create project-specific flag |
+| `/ant:data-clean` | Remove test artifacts from colony data |
+| `/ant:preferences` | Add or list user preferences |
+| `/ant:skill-create "topic"` | Create custom domain skill |
+| `/ant:update` | Update system files from hub |
 
 </details>
 
-## 🐜 The 24 Agents
+## The 24 Agents
 
 | Tier | Agent | Role |
 |------|-------|------|
-| 👑 **Core** | Builder | 🔨 Writes code, TDD-first |
-| 👑 **Core** | Watcher | 👁️ Tests, validates, quality gates |
-| 👑 **Core** | Scout | 🔍 Researches, discovers |
-| 🏛️ **Orchestration** | Queen | 👑 Orchestrates phases, spawns workers |
-| 🏛️ **Orchestration** | Route-Setter | 📋 Plans phases, breaks down goals |
-| 🏛️ **Orchestration** | Architect | 🏗️ Architecture design |
-| 🗺️ **Surveyor** | surveyor-nest | 📂 Maps directory structure |
-| 🗺️ **Surveyor** | surveyor-disciplines | 📏 Documents conventions |
-| 🗺️ **Surveyor** | surveyor-pathogens | 🦠 Identifies tech debt |
-| 🗺️ **Surveyor** | surveyor-provisions | 📦 Maps dependencies |
-| ⚡ **Specialist** | Keeper | 📚 Preserves knowledge |
-| ⚡ **Specialist** | Tracker | 🐛 Investigates bugs |
-| ⚡ **Specialist** | Probe | 🔬 Coverage analysis |
-| ⚡ **Specialist** | Weaver | 🧵 Refactoring specialist |
-| ⚡ **Specialist** | Auditor | ✅ Quality gate |
-| 🎯 **Niche** | Chaos | 🎲 Resilience testing |
-| 🎯 **Niche** | Archaeologist | 🏺 Excavates git history |
-| 🎯 **Niche** | Gatekeeper | 🛡️ Security gate |
-| 🎯 **Niche** | Includer | ♿ Accessibility audits |
-| 🎯 **Niche** | Measurer | ⏱️ Performance analysis |
-| 🎯 **Niche** | Sage | 🧙 Wisdom synthesis |
-| 🎯 **Niche** | Oracle | 🔮 Deep research |
-| 🎯 **Niche** | Ambassador | 🌐 External integrations |
-| 🎯 **Niche** | Chronicler | 📝 Documentation |
-
-## 🏗️ Architecture
+| **Core** | Builder | Writes code, TDD-first |
+| **Core** | Watcher | Tests, validates, quality gates |
+| **Core** | Scout | Researches, discovers |
+| **Orchestration** | Queen | Orchestrates phases, spawns workers |
+| **Orchestration** | Route-Setter | Plans phases, breaks down goals |
+| **Orchestration** | Architect | Architecture design |
+| **Surveyor** | surveyor-nest | Maps directory structure |
+| **Surveyor** | surveyor-disciplines | Documents conventions |
+| **Surveyor** | surveyor-pathogens | Identifies tech debt |
+| **Surveyor** | surveyor-provisions | Maps dependencies |
+| **Specialist** | Keeper | Preserves knowledge |
+| **Specialist** | Tracker | Investigates bugs |
+| **Specialist** | Probe | Coverage analysis |
+| **Specialist** | Weaver | Refactoring specialist |
+| **Specialist** | Auditor | Quality gate |
+| **Niche** | Chaos | Resilience testing |
+| **Niche** | Archaeologist | Excavates git history |
+| **Niche** | Gatekeeper | Security gate |
+| **Niche** | Includer | Accessibility audits |
+| **Niche** | Measurer | Performance analysis |
+| **Niche** | Sage | Wisdom synthesis |
+| **Niche** | Oracle | Deep research |
+| **Niche** | Ambassador | External integrations |
+| **Niche** | Chronicler | Documentation |
+
+## Architecture
 
 ```
-.aether/                      # 🐜 Colony files (repo-local)
-├── aether-utils.sh           # ⚡ Dispatcher (~5,200 lines, ~150 subcommands)
-├── utils/                    # 🔧 ~29 modular scripts
-├── skills/                   # 📚 28 skills (10 colony + 18 domain)
-├── commands/                 # 📖 44 YAML command sources
-├── exchange/                 # 📤 XML exchange modules
-├── docs/                     # 📝 Documentation
-├── templates/                # 📋 12 templates
-└── data/                     # 💾 Colony state (local only)
-
-~/.aether/                    # 🌐 Hub (cross-colony, user-level)
-├── QUEEN.md                  # 👑 Wisdom + preferences
-├── hive/wisdom.json          # 🧠 Cross-colony wisdom (200 cap)
-└── registry.json             # 📊 All registered colonies
+.aether/                        Colony files (repo-local)
+├── aether-utils.sh             Dispatcher (~5,500 lines, ~130+ subcommands)
+├── utils/                      35 modular scripts
+├── skills/                     28 skills (10 colony + 18 domain)
+├── commands/                   45 YAML command sources
+├── exchange/                   XML exchange modules
+├── docs/                       Documentation
+├── templates/                  12 templates
+└── data/                       Colony state (local only)
+
+~/.aether/                      Hub (cross-colony, user-level)
+├── QUEEN.md                    Wisdom + preferences
+├── hive/wisdom.json            Cross-colony wisdom (200 cap)
+└── registry.json               All registered colonies
 ```
 
-## 🔌 Works With
+## 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
+## Support
 
-If Aether has been useful to you, here's how you can keep the colony alive:
+If Aether has been useful to you:
 
-**[Sponsor on GitHub](https://github.com/sponsors/calcosmic)** (preferred)
+**[Sponsor on GitHub](https://github.com/sponsors/calcosmic)**
 
 <details>
-<summary>💡 Crypto — no middlemen, no fees</summary>
+<summary>Crypto</summary>
 
 | Network | Address |
 |---------|---------|
-| **ETH** (MetaMask) | `0xE7F8C9BE190c207D49DF01b82747cf7B6Bd1c809` |
-| **SOL** (Phantom) | `6DVTdoZvvi9siUpgmRJZxk5Kqho8TZiN2ZzyVUVC9gX8` |
+| **ETH** | `0xE7F8C9BE190c207D49DF01b82747cf7B6Bd1c809` |
+| **SOL** | `6DVTdoZvvi9siUpgmRJZxk5Kqho8TZiN2ZzyVUVC9gX8` |
 
 </details>
 
 [PayPal](https://www.paypal.com/ncp/payment/RENG7ZMW5F59L) · [Buy Me a Coffee](https://buymeacoffee.com/music5y)
 
-*Your support funds servers, new features, docs, and keeps Aether free & open source (MIT).*
-
-## 📄 License
+## License
 
 MIT

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 };