aether-colony 5.3.2 → 5.4.0

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

@@ -53,7 +53,6 @@ Do not touch during init:
 - .aether/dreams/ (user notes)
 - .aether/chambers/ (archived colonies)
 - .env* files
-- .claude/settings.json
 - .github/workflows/
 </read_only>
 
@@ -102,7 +101,7 @@ Stop here. Do not proceed.
 
 Run:
 ```
-bash .aether/aether-utils.sh queen-init
+aether queen-init
 ```
 
 Parse the JSON result:
@@ -115,7 +114,7 @@ This step is non-blocking -- proceed regardless of outcome.
 
 Run the scan via Bash tool:
 ```bash
-scan_result=$(bash .aether/aether-utils.sh init-research 2>/dev/null)
+scan_result=$(aether init-research 2>/dev/null)
 scan_data=$(echo "$scan_result" | jq '.result')
 ```
 
@@ -168,7 +167,7 @@ Strip `(Colony: ...)` suffixes using sed. If grep finds nothing, variables remai
 Display a brief header:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   A E T H E R   C O L O N Y   I N I T
+🥚 A E T H E R   C O L O N Y   I N I T
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -286,14 +285,14 @@ Only reached after user approval. ALL file writes happen here.
 
 1. Write charter content via:
 ```bash
-bash .aether/aether-utils.sh charter-write --intent "{approved_intent}" --vision "{approved_vision}" --governance "{approved_governance}" --goals "{approved_goals}"
+aether charter-write --intent "{approved_intent}" --vision "{approved_vision}" --governance "{approved_governance}" --goals "{approved_goals}"
 ```
 
 2. Auto-apply approved pheromone suggestions (see pheromone auto-apply below).
 
 3. Update the goal field in COLONY_STATE.json in-place using the state API:
 ```bash
-bash .aether/aether-utils.sh state-write "$(jq --arg new_goal "{approved_intent}" '.goal = $new_goal' .aether/data/COLONY_STATE.json)"
+aether state-write "$(jq --arg new_goal "{approved_intent}" '.goal = $new_goal' .aether/data/COLONY_STATE.json)"
 ```
 
 4. **Verify the write** — read back and confirm goal is set:
@@ -311,7 +310,7 @@ if [[ "$verify_goal" == "null" || -z "$verify_goal" ]]; then
 fi
 ```
 
-5. Run `bash .aether/aether-utils.sh session-init "$(jq -r '.session_id' .aether/data/COLONY_STATE.json)" "{approved_intent}"`
+5. Run `aether session-init "$(jq -r '.session_id' .aether/data/COLONY_STATE.json)" "{approved_intent}"`
 
 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.
 
@@ -369,12 +368,12 @@ for template in pheromones midden learning-observations; do
 done
 ```
 
-8. Run `bash .aether/aether-utils.sh context-update init "{approved_intent}"`
-9. Run `bash .aether/aether-utils.sh validate-state colony`
+8. Run `aether context-update init "{approved_intent}"`
+9. Run `aether 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
+domain_tags=$(aether domain-detect 2>/dev/null | jq -r '.result.tags // ""' || echo "")
+aether registry-add --path "$(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):
@@ -384,10 +383,10 @@ domain_tags=$(jq -r --arg repo "$(pwd)" \
   "$HOME/.aether/registry.json" 2>/dev/null || echo "")
 seed_args="queen-seed-from-hive --limit 5"
 [[ -n "$domain_tags" ]] && seed_args="$seed_args --domain $domain_tags"
-seed_result=$(bash .aether/aether-utils.sh $seed_args 2>/dev/null || echo '{}')
+seed_result=$(aether $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}"`
+12. Run `aether session-init "{session_id}" "{approved_intent}"`
 
 **Pheromone auto-apply (referenced by both re-init and fresh init paths above):**
 
@@ -395,7 +394,7 @@ If approved pheromone suggestions exist (the user kept them in the prompt and di
 
 For each approved pheromone suggestion, call:
 ```bash
-bash .aether/aether-utils.sh pheromone-write "{type}" '{content}' --source "system:init" --reason '{reason}' --ttl "30d" 2>/dev/null || true
+aether pheromone-write "{type}" '{content}' --source "system:init" --reason '{reason}' --ttl "30d" 2>/dev/null || true
 ```
 
 Implementation notes:
@@ -453,21 +452,21 @@ Import ALL available data types (per D-09 -- no cherry-picking):
 ```bash
 # Import pheromones (per D-09)
 if [[ -f "$latest_chamber/pheromones.xml" ]]; then
-  pher_import=$(bash .aether/aether-utils.sh pheromone-import-xml "$latest_chamber/pheromones.xml" "imported" 2>/dev/null || echo '{"ok":false}')
+  pher_import=$(aether pheromone-import-xml --input "$latest_chamber/pheromones.xml" --colony "imported" 2>/dev/null || echo '{"ok":false}')
   pher_imported=$(echo "$pher_import" | jq -r '.result.imported // 0' 2>/dev/null || echo "0")
   echo "Pheromones: ${pher_imported} signal(s) imported"
 fi
 
 # Import wisdom to queen-wisdom.json (per D-09)
 if [[ -f "$latest_chamber/queen-wisdom.xml" ]]; then
-  wis_import=$(bash .aether/aether-utils.sh wisdom-import-xml "$latest_chamber/queen-wisdom.xml" ".aether/data/queen-wisdom.json" 2>/dev/null || echo '{"ok":false}')
+  wis_import=$(aether wisdom-import-xml "$latest_chamber/queen-wisdom.xml" ".aether/data/queen-wisdom.json" 2>/dev/null || echo '{"ok":false}')
   wis_imported=$(echo "$wis_import" | jq -r '.result.imported // 0' 2>/dev/null || echo "0")
   echo "Wisdom: ${wis_imported} entries(s) imported to queen-wisdom.json"
 fi
 
 # Import registry lineage (per D-09)
 if [[ -f "$latest_chamber/colony-registry.xml" ]]; then
-  reg_import=$(bash .aether/aether-utils.sh registry-import-xml "$latest_chamber/colony-registry.xml" 2>/dev/null || echo '{"ok":false}')
+  reg_import=$(aether registry-import-xml "$latest_chamber/colony-registry.xml" 2>/dev/null || echo '{"ok":false}')
   reg_imported=$(echo "$reg_import" | jq -r '.result.imported // 0' 2>/dev/null || echo "0")
   echo "Registry: ${reg_imported} colon(ies) lineage imported"
 fi
@@ -482,30 +481,48 @@ Display "Import skipped. Starting fresh colony." and proceed to Step 8.
 **If xml_import_available is false (no chambers, no XML, or no xmllint):**
 
 Skip silently -- proceed directly to Step 8 without any mention of import (per D-11).
+### Step 7.5: Install Clash Detection Hook
+
+If `.aether/utils/clash-detect.sh` exists, run:
+
+```bash
+aether clash-setup --install 2>/dev/null || true
+```
+
+This installs the PreToolUse hook that prevents conflicting edits across worktrees.
+Non-blocking — if it fails, init continues normally.
+
+Also configure the merge driver for package-lock.json:
+
+```bash
+git config merge.lockfile.driver "bash .aether/utils/merge-driver-lockfile.sh %O %A %B" 2>/dev/null || true
+git config merge.lockfile.name "npm lockfile auto-merge" 2>/dev/null || true
+```
+
 ### Step 8: Display Result
 
 Display the success header and result block:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   A E T H E R   C O L O N Y
+🥚 A E T H E R   C O L O N Y
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Queen has set the colony's intention
+👑 Queen has set the colony's intention
 
    "{approved_intent}"
 
-   Colony Status: READY
+   🟢 Colony Status: READY
 
-{If re-init: "   Mode: Re-init (charter updated, state preserved)"}
-{If fresh and seeded_count > 0: "   Hive wisdom: {seeded_count} cross-colony pattern(s) seeded into QUEEN.md"}
+{If re-init: "   🔄 Mode: Re-init (charter updated, state preserved)"}
+{If fresh and seeded_count > 0: "   🧠 Hive wisdom: {seeded_count} cross-colony pattern(s) seeded into QUEEN.md"}
 
-State persisted -- safe to /clear, then run /ant:plan
+💾 State persisted -- safe to /clear, then run /ant:plan
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   Next Up
+🐜 Next Up
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   /ant:plan                 Generate execution plan
-   /ant:status               Check colony state
-   /ant:focus                Set initial focus
+   /ant:plan                 📊 Generate execution plan
+   /ant:status               📋 Check colony state
+   /ant:focus                🎯 Set initial focus
 ```

package/.opencode/commands/ant/insert-phase.md

@@ -76,7 +76,7 @@ Example:
 Run:
 
 ```bash
-bash .aether/aether-utils.sh phase-insert "<phase_name>" "<goal_text>" "<constraints_text>"
+aether phase-insert --name "<phase_name>" --goal "<goal_text>" --constraints "<constraints_text>"
 ```
 
 Parse JSON result:

package/.opencode/commands/ant/interpret.md

@@ -233,7 +233,7 @@ Wait for user response.
 
 
 ```bash
-bash .aether/aether-utils.sh activity-log "INTERPRET" "Interpreter" "Dream review: {dream_file}, {confirmed} confirmed, {partial} partial, {unconfirmed} unconfirmed, {refuted} refuted, {actions_taken} actions taken"
+aether activity-log "INTERPRET" "Interpreter" "Dream review: {dream_file}, {confirmed} confirmed, {partial} partial, {unconfirmed} unconfirmed, {refuted} refuted, {actions_taken} actions taken"
 ```
 
 ### Step 8: Display Closing

package/.opencode/commands/ant/lay-eggs.md

@@ -147,7 +147,7 @@ echo "System files copied."
 
 
 
-Run: `bash .aether/aether-utils.sh queen-init`
+Run: `aether queen-init`
 
 
 Parse the JSON result:
@@ -163,7 +163,7 @@ Attempt to register this repo in the global hub. Silent on failure — registry
 Run (ignore errors):
 
 ```bash
-bash .aether/aether-utils.sh registry-add "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" 2>/dev/null || true
+aether registry-add --path "$(pwd)" "$(jq -r '.version // "unknown"' ~/.aether/version.json 2>/dev/null || echo 'unknown')" 2>/dev/null || true
 ```
 
 ### Step 7: Verify Setup

package/.opencode/commands/ant/maturity.md

@@ -17,7 +17,7 @@ You are the **Queen**. Display the colony's maturity journey.
 ### Step 1: Detect Current Milestone
 
 Run:
-`bash .aether/aether-utils.sh milestone-detect`
+`aether milestone-detect`
 
 Parse JSON result to get:
 - `milestone`: Current milestone name (First Mound, Open Chambers, Brood Stable, Ventilated Nest, Sealed Chambers, Crowned Anthill)

package/.opencode/commands/ant/memory-details.md

@@ -26,7 +26,7 @@ Drill-down view of accumulated colony wisdom, pending promotions, and recent fai
 
 Run using the Bash tool with description "Loading colony memory...":
 ```bash
-bash .aether/aether-utils.sh memory-metrics
+aether memory-metrics
 ```
 
 ### Step 2: Display Wisdom (from QUEEN.md)

package/.opencode/commands/ant/oracle.md

@@ -49,10 +49,10 @@ Oracle peering into the depths...
 
 ### Step 0b: Stop Oracle
 
-Create the stop signal file:
+Stop any active Oracle research:
 
 ```bash
-mkdir -p .aether/oracle && touch .aether/oracle/.stop
+mkdir -p .aether/oracle && touch .aether/oracle/.stop && rm -f .aether/oracle/.loop-active
 ```
 
 Output:
@@ -60,8 +60,9 @@ Output:
 ```
 🔮 Oracle Stop Signal Sent
 
-   Created .aether/oracle/.stop
-   The research loop will halt at the end of the current iteration.
+   Created .aether/oracle/.stop (legacy tmux signal)
+   Removed .aether/oracle/.loop-active (in-session loop marker)
+   The research loop will halt at the next iteration boundary.
 
    To check final results: /ant:oracle status
 ```
@@ -283,6 +284,41 @@ Describe the research topic in detail. The more specific, the better the Oracle'
 
 (The user will type their topic via the "Other" free-text option.)
 
+**Question 1.5: Research Brief — Formulate and Approve**
+
+Take the user's raw topic (from `$normalized_args` or Question 1) and reformulate it into a structured research brief. The user may have typed casual natural language — your job is to sharpen it into a clear, well-scoped research prompt that will produce better results.
+
+Display the brief for approval:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔮 R E S E A R C H   B R I E F
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Topic:** {reformulated topic — clear, specific, actionable}
+**Core Question:** {the single most important question this research should answer}
+**Context:** {what we already know from the codebase or user input}
+**Success Criteria:** {what a good answer looks like — what would make this research useful}
+```
+
+Guidelines for formulation:
+- Turn vague topics into specific ones ("auth stuff" → "Authentication architecture: session-based vs token-based for this Node.js API")
+- Add codebase context if relevant (tech stack, existing patterns)
+- Make the core question answerable — not open-ended philosophy
+- Keep success criteria concrete ("A recommendation with trade-offs" not "understand everything")
+
+Then ask the user to approve:
+
+```
+Does this capture what you're looking for? (approve / edit)
+```
+
+- If the user approves: use the reformulated topic as the research topic going forward
+- If the user edits: incorporate their changes, display the updated brief, and ask again
+- Max 2 revision rounds (same as init). After 2, ask for final approval or cancel.
+
+The approved **Topic** from the brief becomes the topic used in all subsequent steps (state.json, plan.json, research-plan.md).
+
 **Question 2: Research Template**
 
 ```
@@ -418,7 +454,7 @@ Use the Write tool to create `.aether/oracle/state.json`:
 For each focus area string from Question 7:
 
 ```bash
-bash .aether/aether-utils.sh pheromone-write FOCUS "$focus_area" \
+aether pheromone-write --type FOCUS --content "$focus_area" \
   --strength 0.8 --source "oracle:wizard" \
   --reason "Focus area set in oracle wizard" --ttl "24h" 2>/dev/null || true
 ```
@@ -517,7 +553,7 @@ Proceed to Step 3.
 
 ---
 
-### Step 3: Launch
+### Step 3: Launch (In-Session Loop)
 
 Output the research configuration summary, showing the sub-questions from plan.json:
 
@@ -541,53 +577,46 @@ Output the research configuration summary, showing the sub-questions from plan.j
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Now launch the loop. Try tmux first, fall back to manual.
-
-**Try tmux:**
+**Create the loop marker file:**
 
 ```bash
-tmux new-session -d -s oracle "cd $(pwd) && bash .aether/utils/oracle/oracle.sh; echo ''; echo '🔮 Oracle loop finished. Press any key to close.'; read -n1" 2>/dev/null && echo "TMUX_OK" || echo "TMUX_FAIL"
-```
-
-**If TMUX_OK:**
-
-```
-🔮 Oracle Launched
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-   The Oracle is researching in a background tmux session.
-
-   👁️  Watch live:     tmux attach -t oracle
-   📊 Check status:   /ant:oracle status
-   🛑 Stop early:     /ant:oracle stop
-
-   Research progress visible at .aether/oracle/research-plan.md
-   The Oracle will stop when it reaches {target_confidence}% confidence
-   or completes {max_iterations} iterations.
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-   You can keep working. The Oracle runs independently.
+SESSION_ID="${CLAUDE_SESSION_ID:-$(uuidgen 2>/dev/null || date +%s)}"
+MAX_IT=<max_iterations from wizard>
+TARGET_CONF=<target_confidence from wizard>
+cat > .aether/oracle/.loop-active <<MARKER
+---
+iteration: 0
+max_iterations: $MAX_IT
+session_id: $SESSION_ID
+phase: survey
+target_confidence: $TARGET_CONF
+synthesis_done: false
+oracle_md_path: .aether/utils/oracle/oracle.md
+---
+Oracle research loop active
+MARKER
+echo "LOOP_MARKER_CREATED"
 ```
 
-Stop here.
-
-**If TMUX_FAIL** (tmux not installed or error):
+Output:
 
 ```
-🔮 Ready to Launch
+🔮 Oracle Research Started (In-Session Loop)
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-   tmux not available. Run this in a separate terminal:
+   The Oracle is researching IN THIS SESSION.
 
-   cd {current_working_directory}
-   bash .aether/utils/oracle/oracle.sh
+   The Stop hook keeps the loop running automatically between iterations.
+   Phases advance: survey -> investigate -> synthesize -> verify
+   Loop ends when confidence target is reached or max iterations hit.
 
-   Then come back here:
    📊 Check status:   /ant:oracle status
    🛑 Stop early:     /ant:oracle stop
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   You can continue chatting. The Oracle loop runs between your messages.
 ```
 
-Stop here.
+**Now begin the first iteration.** Read `.aether/utils/oracle/oracle.md` and start survey phase research.
+Target the first untouched question from plan.json. Update state files as you go.

package/.opencode/commands/ant/organize.md

@@ -36,7 +36,7 @@ From COLONY_STATE.json, extract:
 
 Run using the Bash tool:
 ```bash
-bash .aether/aether-utils.sh pheromone-read
+aether pheromone-read
 ```
 
 Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
@@ -213,7 +213,7 @@ Next:
 
 Use the Bash tool to run:
 ```
-bash .aether/aether-utils.sh activity-log "COMPLETE" "queen" "Hygiene report generated"
+aether activity-log "COMPLETE" "queen" "Hygiene report generated"
 ```
 
 Display persistence confirmation:

package/.opencode/commands/ant/patrol.md

@@ -85,7 +85,7 @@ Extract from COLONY_STATE.json:
 Display audit header:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   C O L O N Y   A U D I T
+🔍 C O L O N Y   A U D I T
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Goal: {goal}
@@ -255,12 +255,12 @@ Run these commands in parallel using the Bash tool:
 
 **Flags check:**
 ```bash
-bash .aether/aether-utils.sh flag-list 2>/dev/null || echo '{"result":{"flags":[]}}'
+aether flag-list --json 2>/dev/null || echo '{"result":{"flags":[]}}'
 ```
 
 **Midden check:**
 ```bash
-bash .aether/aether-utils.sh midden-recent-failures 2>/dev/null || echo '{"result":{"failures":[]}}'
+aether midden-recent-failures 2>/dev/null || echo '{"result":{"failures":[]}}'
 ```
 
 **Parse flag results:**
@@ -338,12 +338,12 @@ Display: `Checking colony health...`
 
 **Expire stale pheromones:**
 ```bash
-bash .aether/aether-utils.sh pheromone-expire 2>/dev/null || true
+aether pheromone-expire 2>/dev/null || true
 ```
 
 **Load memory metrics:**
 ```bash
-bash .aether/aether-utils.sh memory-metrics 2>/dev/null || echo '{}'
+aether memory-metrics 2>/dev/null || echo '{}'
 ```
 
 **Load instincts:**
@@ -363,7 +363,7 @@ From COLONY_STATE.json `events`:
 
 **Count pheromone signals:**
 ```bash
-bash .aether/aether-utils.sh pheromone-count 2>/dev/null || echo '{"result":{"count":0}}'
+aether pheromone-count 2>/dev/null || echo '{"result":{"count":0}}'
 ```
 
 Display:
@@ -507,7 +507,7 @@ Display the formatted audit summary:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   A U D I T   R E S U L T S
+📋 A U D I T   R E S U L T S
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Goal: {goal}
@@ -592,7 +592,7 @@ Next:
 
 Run using the Bash tool:
 ```bash
-bash .aether/aether-utils.sh activity-log "COMPLETE" "queen" "Colony audit completed - {recommendation}"
+aether activity-log "COMPLETE" "queen" "Colony audit completed - {recommendation}"
 ```
 
 Display persistence confirmation:

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

@@ -28,7 +28,7 @@ If `goal` is null, output `No colony initialized. Nothing to pause.` and stop.
 
 Run using the Bash tool:
 ```bash
-bash .aether/aether-utils.sh pheromone-read
+aether pheromone-read
 ```
 
 Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
@@ -109,7 +109,7 @@ If `last_commit_suggestion_phase` equals the current phase, skip this step silen
 
 3. **Generate the commit message:**
 ```bash
-bash .aether/aether-utils.sh generate-commit-message "pause" {current_phase} "{phase_name}"
+aether generate-commit-message --type "pause" --phase {current_phase} --subject "{phase_name}"
 ```
 Parse the returned JSON to extract `message` and `files_changed`.
 

package/.opencode/commands/ant/pheromones.md

@@ -118,7 +118,7 @@ Stop here.
 
 Run using the Bash tool with description "Displaying pheromones...":
 ```bash
-bash .aether/aether-utils.sh pheromone-display "{subcommand or 'all'}"
+aether pheromone-display "{subcommand or 'all'}"
 ```
 
 The output will be the formatted pheromone table.

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

@@ -46,7 +46,7 @@ Stop here.
 
 ### Step 1.5: Load State and Show Resumption Context
 
-Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+Run using Bash tool: `aether load-state`
 
 If successful and goal is not null:
 1. Extract current_phase from state
@@ -61,7 +61,7 @@ If .aether/HANDOFF.md exists (detected in load-state output):
 - Read .aether/HANDOFF.md for additional context
 - Remove .aether/HANDOFF.md after display (cleanup)
 
-Run: `bash .aether/aether-utils.sh unload-state` to release lock.
+Run: `aether unload-state` to release lock.
 
 **Error handling:**
 - If E_FILE_NOT_FOUND: "No colony initialized. Run /ant:init first." and stop
@@ -97,7 +97,7 @@ Select planning depth (prompt user if not explicitly provided):
 
 Run using the Bash tool with description "Loading compact planning context...":
 ```bash
-bash .aether/aether-utils.sh context-capsule --compact --json 2>/dev/null
+aether context-capsule --compact --json 2>/dev/null
 ```
 
 If JSON is valid and `.ok == true`, extract `.result.prompt_section` into `context_capsule_prompt`.
@@ -179,7 +179,7 @@ Investigate domain knowledge for each phase before the planning loop begins. Thi
 **1. Retrieve hive wisdom for research priming:**
 
 ```bash
-hive_context=$(bash .aether/aether-utils.sh hive-read --limit 5 --format text 2>/dev/null)
+hive_context=$(aether hive-read --limit 5 --format text 2>/dev/null)
 ```
 
 Parse the JSON result to extract `.result.text` as `hive_text`. If command fails or returns empty, set `hive_text = ""`.
@@ -581,7 +581,7 @@ 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)"
+  aether 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."
@@ -592,7 +592,7 @@ 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"`
+Log plan completion: `aether activity-log "PLAN_COMPLETE" "queen" "Plan finalized with {confidence}% confidence"`
 
 Update watch-status.txt:
 ```

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

@@ -39,7 +39,7 @@ Stop here.
 
 Run:
 ```bash
-bash .aether/aether-utils.sh generate-ant-name "scout"
+aether generate-ant-name --caste "scout"
 ```
 
 Capture the output as `scout_name`.
@@ -54,7 +54,7 @@ Spawning {scout_name} — {query truncated to 50 chars}
 
 Run:
 ```bash
-bash .aether/aether-utils.sh spawn-log "Queen" "scout" "{scout_name}" "Quick query: {query}"
+aether spawn-log --name "Queen" --caste "scout" --id "{scout_name}" --description "Quick query: {query}"
 ```
 
 
@@ -73,14 +73,14 @@ Display your findings directly to the user.
 
 Run:
 ```bash
-bash .aether/aether-utils.sh spawn-complete "{scout_name}" "completed" "Quick query answered"
+aether spawn-complete --id "{scout_name}" --status "completed" --summary "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
+aether session-update --command "/ant:quick" --worker "" --summary "Quick query: {query truncated to 60 chars}" 2>/dev/null || true
 ```
 
 **NOTE:** This command does NOT:

package/.opencode/commands/ant/redirect.md

@@ -57,8 +57,8 @@ Write constraints.json.
 
 **Write pheromone signal and update context:**
 ```bash
-bash .aether/aether-utils.sh pheromone-write REDIRECT "$normalized_args" --strength 0.9 --reason "User warned colony away from pattern" 2>/dev/null || true
-bash .aether/aether-utils.sh context-update constraint redirect "$normalized_args" "user" 2>/dev/null || true
+aether pheromone-write --type REDIRECT --content "$normalized_args" --strength 0.9 --reason "User warned colony away from pattern" 2>/dev/null || true
+aether context-update --section constraint --key redirect --content "$normalized_args" "user" 2>/dev/null || true
 ```
 
 ### Step 3: Confirm

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

@@ -20,13 +20,13 @@ Parse `$normalized_args`:
 
 ### Step 0.5: Version Check (Non-blocking)
 
-Run using the Bash tool: `bash .aether/aether-utils.sh version-check 2>/dev/null || true`
+Run using the Bash tool: `aether version-check-cached 2>/dev/null || true`
 
 If the command succeeds and the JSON result contains a non-empty string, display it as a one-line notice. Proceed regardless of outcome.
 
 ### Step 1: Load State and Validate
 
-Run using Bash tool: `bash .aether/aether-utils.sh load-state`
+Run using Bash tool: `aether load-state`
 
 If successful:
 1. Parse state from result
@@ -41,7 +41,7 @@ Keep state loaded (don't unload yet) - we'll need it for the full display.
 
 Run using the Bash tool:
 ```bash
-bash .aether/aether-utils.sh pheromone-read
+aether pheromone-read
 ```
 
 Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
@@ -133,7 +133,7 @@ Use Write tool to update COLONY_STATE.json:
 
 Use Bash tool to remove HANDOFF.md: `rm -f .aether/HANDOFF.md`
 
-Run: `bash .aether/aether-utils.sh unload-state` to release lock.
+Run: `aether unload-state` to release lock.
 
 ---