aether-colony 5.1.0 → 5.3.0

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

@@ -144,8 +144,14 @@ If `scan_result` is empty or `jq` fails, set all fields to fallback values (empt
 
 Use Read tool to check `.aether/data/COLONY_STATE.json`.
 
-- If file exists AND has a non-null `goal` field: set `reinit_mode = true`, store `existing_goal`
-- Otherwise: set `reinit_mode = false`
+- If file exists AND has a non-null `goal` field:
+  - Check the `milestone` field. If `milestone == "Crowned Anthill"`:
+    - This is a **sealed colony**. Treat as **fresh init**, NOT re-init.
+    - Set `reinit_mode = false`
+    - Display: `Previous colony was sealed. Starting fresh colony.`
+    - The old COLONY_STATE.json will be overwritten in Step 7 (fresh init path).
+  - Otherwise (colony exists but is NOT sealed): set `reinit_mode = true`, store `existing_goal`
+- If file does not exist or `goal` is null: set `reinit_mode = false`
 
 If re-init mode, read existing charter entries from `.aether/QUEEN.md`:
 ```bash
@@ -285,14 +291,29 @@ bash .aether/aether-utils.sh charter-write --intent "{approved_intent}" --vision
 
 2. Auto-apply approved pheromone suggestions (see pheromone auto-apply below).
 
-3. Optionally update the goal field in COLONY_STATE.json in-place:
+3. Update the goal field in COLONY_STATE.json in-place using the state API:
 ```bash
-jq --arg new_goal "{approved_intent}" '.goal = $new_goal' .aether/data/COLONY_STATE.json > .aether/data/COLONY_STATE.json.tmp && mv .aether/data/COLONY_STATE.json.tmp .aether/data/COLONY_STATE.json
+bash .aether/aether-utils.sh state-write "$(jq --arg new_goal "{approved_intent}" '.goal = $new_goal' .aether/data/COLONY_STATE.json)"
 ```
 
-4. Run `bash .aether/aether-utils.sh session-init "$(jq -r '.session_id' .aether/data/COLONY_STATE.json)" "{approved_intent}"`
+4. **Verify the write** — read back and confirm goal is set:
+```bash
+verify_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json)
+if [[ "$verify_goal" == "null" || -z "$verify_goal" ]]; then
+  echo "ERROR: Colony state write failed — goal is still null after write. Re-run /ant:init."
+  # Attempt recovery: write goal directly
+  jq --arg g "{approved_intent}" '.goal = $g' .aether/data/COLONY_STATE.json > .aether/data/COLONY_STATE.json.tmp && mv .aether/data/COLONY_STATE.json.tmp .aether/data/COLONY_STATE.json
+  verify_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json)
+  if [[ "$verify_goal" == "null" || -z "$verify_goal" ]]; then
+    echo "FATAL: Recovery write also failed. Colony state may be corrupted."
+    stop
+  fi
+fi
+```
+
+5. Run `bash .aether/aether-utils.sh session-init "$(jq -r '.session_id' .aether/data/COLONY_STATE.json)" "{approved_intent}"`
 
-5. Skip to Step 8 (display result). Do NOT write COLONY_STATE.json from template, do NOT write constraints.json, do NOT write pheromones.json.
+6. Skip to Step 8 (display result). Do NOT write COLONY_STATE.json from template, do NOT write constraints.json, do NOT write pheromones.json.
 
 **If fresh init:**
 
@@ -308,12 +329,24 @@ jq --arg new_goal "{approved_intent}" '.goal = $new_goal' .aether/data/COLONY_ST
    - Remove ALL keys starting with underscore
    - Write the resulting JSON to `.aether/data/COLONY_STATE.json` using the Write tool
 
-5. Write constraints.json from template:
+5. **Verify the write** — read back and confirm COLONY_STATE.json is valid and goal is set:
+```bash
+verify_goal=$(jq -r '.goal' .aether/data/COLONY_STATE.json 2>/dev/null)
+verify_valid=$(jq -e . .aether/data/COLONY_STATE.json >/dev/null 2>&1 && echo "valid" || echo "invalid")
+if [[ "$verify_valid" != "valid" || "$verify_goal" == "null" || -z "$verify_goal" ]]; then
+  echo "ERROR: Colony state write verification failed (valid=$verify_valid, goal=$verify_goal)"
+  echo "The colony file may be corrupted. Remove .aether/data/COLONY_STATE.json and re-run /ant:init."
+  stop
+fi
+echo "Colony state verified: goal=\"$verify_goal\""
+```
+
+6. Write constraints.json from template:
    - Resolve template: check `~/.aether/system/templates/constraints.template.json` first, then `.aether/templates/constraints.template.json`
    - If no template found: output "Template missing: constraints.template.json. Run aether update to fix." and stop
    - Read template, follow `_instructions`, remove `_` prefixed keys, write to `.aether/data/constraints.json`
 
-6. Initialize runtime files from templates (non-blocking):
+7. Initialize runtime files from templates (non-blocking):
 ```bash
 for template in pheromones midden learning-observations; do
   if [[ "$template" == "midden" ]]; then
@@ -336,15 +369,22 @@ for template in pheromones midden learning-observations; do
 done
 ```
 
-7. Run `bash .aether/aether-utils.sh context-update init "{approved_intent}"`
-8. Run `bash .aether/aether-utils.sh validate-state colony`
-9. Register repo (silent on failure):
+8. Run `bash .aether/aether-utils.sh context-update init "{approved_intent}"`
+9. Run `bash .aether/aether-utils.sh validate-state colony`
+10. Register repo (silent on failure):
 ```bash
 domain_tags=$(bash .aether/aether-utils.sh domain-detect 2>/dev/null | jq -r '.result.tags // ""' || echo "")
 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
 ```
-10. 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(",")' \
@@ -354,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")
 ```
-11. 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/insert-phase.md

@@ -22,6 +22,10 @@ If `goal` is null:
 `No colony initialized. Run /ant:init first.`
 Stop.
 
+If `milestone` == `"Crowned Anthill"`:
+`This colony has been sealed. Start a new colony with /ant:init "new goal".`
+Stop.
+
 If `plan.phases` is empty:
 `No project plan. Run /ant:plan first.`
 Stop.

package/.opencode/commands/ant/plan.md

@@ -30,7 +30,7 @@ If `version` field is missing, "1.0", or "2.0":
 3. Output: `State auto-upgraded to v3.0`
 4. Continue with command.
 
-Extract: `goal`, `plan.phases`
+Extract: `goal`, `milestone`, `plan.phases`
 
 **Validate:** If `goal: null`:
 ```
@@ -38,6 +38,12 @@ No colony initialized. Run /ant:init "<goal>" first.
 ```
 Stop here.
 
+If `milestone` == `"Crowned Anthill"`:
+```
+This colony has been sealed. Start a new colony with /ant:init "new goal".
+```
+Stop here.
+
 ### Step 1.5: Load State and Show Resumption Context
 
 Run using Bash tool: `bash .aether/aether-utils.sh load-state`
@@ -567,6 +573,25 @@ Read current COLONY_STATE.json, then update:
 
 Write COLONY_STATE.json.
 
+**Verify the write** — read back and confirm the plan persisted:
+```bash
+verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+verify_timestamp=$(jq -r '.plan.generated_at' .aether/data/COLONY_STATE.json)
+verify_state=$(jq -r '.state' .aether/data/COLONY_STATE.json)
+if [[ "$verify_phases" -lt 1 || "$verify_timestamp" == "null" || "$verify_state" != "READY" ]]; then
+  echo "ERROR: Plan write verification failed (phases=$verify_phases, generated_at=$verify_timestamp, state=$verify_state)"
+  echo "Attempting retry write..."
+  bash .aether/aether-utils.sh state-write "$(jq --argjson phases "$(echo '$PLAN_JSON' | jq '.plan.phases')" --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '.plan.phases = $phases | .plan.generated_at = $ts | .state = "READY"' .aether/data/COLONY_STATE.json)"
+  verify_phases=$(jq '.plan.phases | length' .aether/data/COLONY_STATE.json)
+  if [[ "$verify_phases" -lt 1 ]]; then
+    echo "FATAL: Retry write also failed. Plan was not persisted."
+    echo "Re-run /ant:plan to regenerate."
+    stop
+  fi
+fi
+echo "Plan verified: $verify_phases phases, generated_at=$verify_timestamp, state=$verify_state"
+```
+
 Log plan completion: `bash .aether/aether-utils.sh activity-log "PLAN_COMPLETE" "queen" "Plan finalized with {confidence}% confidence"`
 
 Update watch-status.txt:

package/.opencode/commands/ant/quick.md

@@ -0,0 +1,91 @@
+<!-- Generated from .aether/commands/quick.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:quick
+description: "🔍🐜⚡🐜🔍 Quick scout query — fast answers without build ceremony"
+---
+
+### Step -1: Normalize Arguments
+
+Run: `normalized_args=$(bash .aether/aether-utils.sh normalize-args "$@")`
+
+This ensures arguments work correctly in both Claude Code and OpenCode. Use `$normalized_args` throughout this command.
+
+You are the **Queen**. Execute `/ant:quick` — a lightweight scout mission.
+
+The query is: `$normalized_args`
+
+## Purpose
+
+Quick, focused answers to questions about the codebase, patterns, or implementation
+details. No build ceremony, no state changes, no verification waves.
+
+## Instructions
+
+### Step 1: Validate Arguments
+
+If `$normalized_args` is empty:
+```
+Usage: /ant:quick "<question>"
+
+Examples:
+  /ant:quick "how does the pheromone system work?"
+  /ant:quick "find all uses of acquire_lock"
+  /ant:quick "what tests cover midden-write?"
+  /ant:quick "show me the colony-prime token budget logic"
+```
+Stop here.
+
+### Step 2: Generate Scout Name
+
+Run:
+```bash
+bash .aether/aether-utils.sh generate-ant-name "scout"
+```
+
+Capture the output as `scout_name`.
+
+### Step 3: Spawn Scout
+
+Display:
+```
+━━━ Quick Scout ━━━
+Spawning {scout_name} — {query truncated to 50 chars}
+```
+
+Run:
+```bash
+bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{scout_name}" "Quick query: {query}"
+```
+
+
+
+Investigate the query directly using available tools (Grep, Glob, Read).
+Search the codebase and provide a clear, focused answer with file paths and line numbers for key findings.
+Keep your answer concise and actionable.
+
+
+### Step 4: Display Results
+
+
+
+Display your findings directly to the user.
+
+
+Run:
+```bash
+bash .aether/aether-utils.sh spawn-complete "{scout_name}" "completed" "Quick query answered"
+```
+
+### Step 5: Update Session (lightweight)
+
+Run:
+```bash
+bash .aether/aether-utils.sh session-update "/ant:quick" "" "Quick query: {query truncated to 60 chars}" 2>/dev/null || true
+```
+
+**NOTE:** This command does NOT:
+- Modify COLONY_STATE.json
+- Advance phases
+- Create checkpoints
+- Spawn watchers or chaos ants
+- Run verification

package/.opencode/commands/ant/resume-colony.md

@@ -31,8 +31,9 @@ Run using Bash tool: `bash .aether/aether-utils.sh load-state`
 If successful:
 1. Parse state from result
 2. If goal is null: Show "No colony state found..." message and stop
-3. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
-4. Extract all state fields for display
+3. If `milestone` == `"Crowned Anthill"`: Show "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
+4. Check if paused flag is true - if not, note "Colony was not paused, but resuming anyway"
+5. Extract all state fields for display
 
 Keep state loaded (don't unload yet) - we'll need it for the full display.
 

package/.opencode/commands/ant/resume.md

@@ -68,6 +68,7 @@ Use the Read tool to read `.aether/data/COLONY_STATE.json`.
 
 COLONY_STATE.json is the authoritative source for goal and state (session.json may be stale). Extract:
 - `goal` (use this as authoritative, overriding session.json colony_goal)
+- `milestone` (check for sealed colony)
 - `state` (READY, PLANNING, EXECUTING, PAUSED)
 - `current_phase`
 - `plan.phases` (array with id, name, status for each phase)
@@ -75,6 +76,14 @@ COLONY_STATE.json is the authoritative source for goal and state (session.json m
 - `memory.decisions` (flat list — do NOT distinguish user vs Claude origin)
 - `events` (last 5 for recent activity context)
 
+**If `milestone` == `"Crowned Anthill"`:** This colony has been sealed. Display:
+```
+This colony has been sealed (Crowned Anthill).
+
+Start a new colony with /ant:init "new goal"
+```
+Stop here — do NOT display stale phase data from the sealed colony.
+
 If the file is missing or the JSON cannot be parsed, **stop immediately** and display:
 
 ```

package/.opencode/commands/ant/run.md

@@ -36,6 +36,7 @@ Parse `$normalized_args` for:
 - `--replan-interval N` — Pause for replan suggestion every N phases (default: 2)
 - `--continue` — Resume after a replan pause without replanning
 - `--dry-run` — Preview plan without executing
+- `--headless` — Run without interactive prompts; queue decisions for later review
 - `--verbose` / `-v`, `--no-visual`, `--no-suggest` — Pass through to playbooks
 
 ```
@@ -44,6 +45,7 @@ Parse `$normalized_args` for:
 /ant:run --replan-interval 3   Suggest replan every 3 phases instead of 2
 /ant:run --continue            Resume after replan pause without replanning
 /ant:run --dry-run             Preview the autopilot plan
+/ant:run --headless            Run all phases without interactive prompts
 /ant:run --max-phases 3 -v     Run 3 phases with verbose output
 ```
 
@@ -69,10 +71,14 @@ replan suggestion (every {replan_interval} phases)
 ### Step 0: Initialize
 
 1. Read `.aether/data/COLONY_STATE.json`; validate goal + plan.phases exist
+   - If `milestone` == `"Crowned Anthill"`: output "This colony has been sealed. Start a new colony with `/ant:init \"new goal\"`." and stop
 2. Determine remaining incomplete phases; apply `--max-phases` cap
 3. Set `phases_completed = 0`, `autopilot_start = $(date +%s)`
 4. Record pre-build blocker count: `bash .aether/aether-utils.sh flag-check-blockers {phase}`
-5. Display: `AUTOPILOT ENGAGED | Goal: {goal} | Phase {N} | Max: {max or "all"}`
+5. If `--headless` flag is present:
+   - Run: `bash .aether/aether-utils.sh autopilot-set-headless true`
+   - Display: `Headless mode: ON — interactive prompts will be queued as pending decisions`
+6. Display: `AUTOPILOT ENGAGED | Goal: {goal} | Phase {N} | Max: {max or "all"}`
 
 ### Step 1: Build Phase
 
@@ -103,6 +109,19 @@ On pause, display the AUTOPILOT PAUSED banner with reason, affected phase,
 specific issues, and instruction: "Fix issues, then run /ant:run to resume."
 Log: `"<timestamp>|autopilot_paused|run|Paused at Phase {id}: {reason}"`
 
+**Headless override for visual checkpoints:** If headless mode is active and a
+visual checkpoint prompt would normally be shown to the user, instead queue it as
+a pending decision:
+```bash
+bash .aether/aether-utils.sh pending-decision-add \
+  --title "Visual checkpoint: Phase {id}" \
+  --type "checkpoint" \
+  --description "{checkpoint_description}" \
+  --phase "{id}" \
+  --source "build-pause-check"
+```
+Then continue without pausing.
+
 **If no pause:** proceed to Step 3.
 
 ### Step 3: Continue (Verify + Advance)
@@ -120,6 +139,18 @@ Execute continue playbooks in order, carrying cross-stage state
 Skip the AskUserQuestion prompt. Instead, auto-PAUSE with reason
 "Runtime verification required" so the user can test manually before resuming.
 
+**Headless override for runtime verification:** If headless mode is active and
+runtime verification would normally pause, queue as a pending decision instead:
+```bash
+bash .aether/aether-utils.sh pending-decision-add \
+  --title "Runtime verification needed: Phase {id}" \
+  --type "runtime-verification" \
+  --description "Manual testing required before advancing past Phase {id}" \
+  --phase "{id}" \
+  --source "continue-gates"
+```
+Then continue without pausing.
+
 ### Step 4: Continue Pause Check
 
 **PAUSE if ANY of these are true:**
@@ -189,6 +220,11 @@ Phases completed: {N} | Elapsed: {Xm Ys} | Now at: Phase {current}
 {paused}        -> Fix {reason}, then /ant:run to resume
 ```
 
+If headless mode was active and pending decisions were queued, display:
+```
+Pending decisions: {N} — run `pending-decision-list` to review
+```
+
 Update session:
 `bash .aether/aether-utils.sh session-update "/ant:run" "/ant:run" "Autopilot: {N} phases, now Phase {current}"`
 

package/.opencode/commands/ant/status.md

@@ -286,6 +286,8 @@ Use the `phase_bar` and `task_bar` values computed in Step 2.7 for the actual ba
 
 
 
+
+
 **Edge cases:**
 - No phases yet: show `[░░░░░░░░░░░░░░░░░░░░] 0/0 phases`
 - No tasks in phase: show `[░░░░░░░░░░░░░░░░░░░░] 0/0 tasks in Phase 0`

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.
@@ -574,3 +600,93 @@ The following entries are automatically generated by the colony during work phas
 
 - **Files:** `.aether/data/AUDIT-REPORT.md`
 - **Decisions:** audit-report-corrected
+
+### Phase 0 — Plan 00
+
+- **Files:** `COLONY_STATE.json`, `QUEEN.md`, `learning.sh`
+- **Decisions:** Colony sealed at Crowned Anthill; Comprehensive audit colony
+- **What Worked:** 6 phases completed; Colony wisdom promoted to QUEEN.md
+
+## 2026-03-30
+
+### Phase 0 — Plan 00
+
+- **Files:** `aether-utils.sh`, `utils/immune.sh`, `utils/council.sh`, `utils/midden.sh`, `utils/session.sh`, `utils/state-api.sh`
+- **Decisions:** Colony sealed at Crowned Anthill; Implement next-gen Aether features: immune response, headless autopilot, vital signs, quick scout, council expansion, midden library
+- **What Worked:** 6 phases completed; Colony wisdom promoted to QUEEN.md
+
+### Phase 1 — Plan 01
+
+- **Files:** `.aether/utils/spawn-tree.sh`, `tests/unit/spawn-tree.test.js`
+- **Decisions:** gsub order is load-bearing for JSON escaping
+- **What Worked:** awk gsub escaping with correct order; TDD with 4 new tests
+- **Requirements:** spawn-tree.sh, spawn-tree.test.js addressed
+
+### Phase 2 — Plan 01
+
+- **Files:** `.aether/utils/queen.sh`, `tests/bash/test-queen-module.sh`
+- **Decisions:** use ENVIRON[] not awk -v for user content
+- **What Worked:** ENVIRON-based awk approach; head/tail for multi-line replacement; orphan cleanup
+- **Requirements:** .aether/utils/queen.sh addressed
+
+### Phase 3 — Plan 01
+
+- **Files:** `.aether/utils/error-handler.sh`, `.aether/utils/spawn.sh`, `.aether/aether-utils.sh`
+- **Decisions:** guard central subcommand plus individual sites
+- **What Worked:** AETHER_TESTING env guard
+- **Requirements:** error-handler.sh, spawn.sh, aether-utils.sh addressed
+
+### Phase 4 — Plan 01
+
+- **Files:** `package.json`, `package-lock.json`
+- **Decisions:** npm overrides for transitive deps
+- **What Worked:** minimatch; path-to-regexp; picomatch; tar; brace-expansion; diff
+- **Requirements:** package.json addressed
+
+### Phase 5 — Plan 01
+
+- **Decisions:** final verification sweep confirms all fixes
+- **What Worked:** midden acknowledgment; full test suite verification
+
+### Phase 0 — Plan 00
+
+- **Files:** `.aether/utils/spawn-tree.sh`, `.aether/utils/queen.sh`, `.aether/utils/error-handler.sh`, `.aether/utils/spawn.sh`, `.aether/aether-utils.sh`, `package.json`
+- **Decisions:** Colony sealed at Crowned Anthill; Fix critical midden entries and harden infrastructure
+- **What Worked:** 5 phases completed; Colony wisdom promoted to QUEEN.md
+
+### Phase 1 — Plan 01
+
+- **Files:** `.aether/aether-utils.sh`
+- **Decisions:** context-update now fully jq-safe
+- **What Worked:** 1 remaining raw json_ok fixed
+- **Requirements:** .aether/aether-utils.sh addressed
+
+### Phase 03 — Plan 01
+
+- **Files:** `.aether/aether-utils.sh`
+- **Decisions:** Use jq -nc --arg for all json_ok calls; parallel builder verification catches fabricated completions
+
+### Phase 2 — Plan 01
+
+- **Files:** `aether-utils.sh`, `package.json`
+- **Decisions:** Use jq --arg for all json_ok sites with user strings
+- **What Worked:** jq --arg escaping; empty-file guard in validate-state
+- **Requirements:** json_ok safe escaping addressed
+
+### Phase 3 — Plan 01
+
+- **Files:** `.aether/aether-utils.sh`, `.aether/utils/flag.sh`, `tests/bash/test-flag-module.sh`, `tests/bash/test-state-checkpoint.sh`
+- **Decisions:** Fixed view-state jq filter injection; Fixed fallback json_err escaping; Converted 14+ json_ok sites to jq --arg
+- **What Worked:** All 509 tests pass; Auditor score 73/100; No critical security issues
+
+### Phase 05 — Plan 01
+
+- **Files:** `.aether/utils/hive.sh`, `tests/bash/test-hive-read.sh`, `tests/bash/test-learning-recovery.sh`
+- **Decisions:** Compose null fallback with tonumber to preserve prior type coercion fix
+- **What Worked:** Archaeology pre-build scan prevented regression; Stale grep targets identified by root cause analysis
+
+### Phase 0 — Plan 00
+
+- **Files:** `aether-utils.sh`, `utils/hive.sh`, `utils/learning.sh`, `tests/`
+- **Decisions:** Colony sealed at Crowned Anthill; hardened ~40 json_ok sites + checkpointing + hive null safety
+- **What Worked:** 5 phases completed; 9 instincts created; 4 hive-eligible

package/README.md

@@ -8,14 +8,17 @@
 [![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)
 
 Spawn a colony of 24 AI specialists that self-organize around your goal using pheromone signals.
 1,000+ weekly installs.
 
+*Artificial Ecology For Thought and Emergent Reasoning*
+
 *The whole is greater than the sum of its ants.*
 
 ```bash
-npm install -g aether-colony
+npx aether-colony
 ```
 
 </div>
@@ -69,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:
@@ -85,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
@@ -209,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
@@ -226,8 +232,28 @@ 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
+
+If Aether has been useful to you, here's how you can keep the colony alive:
+
+**[Sponsor on GitHub](https://github.com/sponsors/calcosmic)** (preferred)
+
+<details>
+<summary>💡 Crypto — no middlemen, no fees</summary>
+
+| Network | Address |
+|---------|---------|
+| **ETH** (MetaMask) | `0xE7F8C9BE190c207D49DF01b82747cf7B6Bd1c809` |
+| **SOL** (Phantom) | `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