aether-colony 3.1.17 → 5.1.0

package/.claude/commands/ant/plan.md

@@ -1,9 +1,10 @@
+<!-- Generated from .aether/commands/plan.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:plan
 description: "📊🐜🗺️🐜📊 Show project plan or generate project-specific phases"
 ---
 
-You are the **Queen**. Orchestrate research and planning until 80% confidence (maximum 4 iterations).
+You are the **Queen**. Orchestrate research and planning until the selected confidence target is reached within the selected iteration budget.
 
 ## Instructions
 
@@ -11,25 +12,7 @@ Parse `$ARGUMENTS`:
 - If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
 - Otherwise: set `visual_mode = true`
 
-### Step 0: Initialize Visual Mode (if enabled)
-
-If `visual_mode` is true:
-```bash
-# Generate session ID
-plan_id="plan-$(date +%s)"
-
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$plan_id"
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Generating colony plan" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
-```
-
-### Step 0.5: Version Check (Non-blocking)
-
-Run using the Bash tool: `bash .aether/aether-utils.sh version-check 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: Read State + Version Check
+### Step 1: Read State
 
 Read `.aether/data/COLONY_STATE.json`.
 
@@ -80,6 +63,33 @@ Parse `$ARGUMENTS`:
 - If contains `--accept`: Set `force_accept = true` (accept current plan regardless of confidence)
 - Otherwise: `force_accept = false`
 
+Select planning depth (prompt user if not explicitly provided):
+- Presets:
+  - `fast`: `target_confidence = 80`, `max_iterations = 4`
+  - `balanced`: `target_confidence = 90`, `max_iterations = 6`
+  - `deep`: `target_confidence = 95`, `max_iterations = 8`
+  - `exhaustive`: `target_confidence = 99`, `max_iterations = 12`
+- Preset selectors:
+  - `--fast`, `--balanced`, `--deep`, `--exhaustive`
+  - `--quality fast|balanced|deep|exhaustive`
+- CLI overrides:
+  - `--target <70-99>` to set `target_confidence`
+  - `--max-iterations <2-12>` to set `max_iterations`
+- If no preset/overrides are provided, ask:
+  `Planning depth? 1) Fast 2) Balanced 3) Deep (recommended) 4) Exhaustive`
+- Map user choice to a preset, default to `deep` on unclear input.
+- If overrides are out of range, clamp to valid ranges and continue.
+
+### Step 2.5: Load Compact Context Capsule
+
+Run using the Bash tool with description "Loading compact planning context...":
+```bash
+bash .aether/aether-utils.sh context-capsule --compact --json 2>/dev/null
+```
+
+If JSON is valid and `.ok == true`, extract `.result.prompt_section` into `context_capsule_prompt`.
+If command fails or returns invalid JSON, set `context_capsule_prompt = ""` and continue.
+
 ### Step 3: Initialize Planning State
 
 Update watch files for tmux visibility:
@@ -92,7 +102,7 @@ AETHER COLONY :: PLANNING
 State: PLANNING
 Phase: 0/0 (generating plan)
 Confidence: 0%
-Iteration: 0/4
+Iteration: 0/{max_iterations}
 
 Active Workers:
   [Research] Starting...
@@ -109,17 +119,12 @@ Progress
 
 [                    ] 0%
 
-Target: 80% confidence
+Target: {target_confidence}% confidence
 
-Iteration: 0/4
+Iteration: 0/{max_iterations}
 Gaps: (analyzing...)
 ```
 
-Log start:
-```bash
-bash .aether/aether-utils.sh activity-log "PLAN_START" "queen" "Iterative planning loop initiated for goal"
-```
-
 ### Step 3.5: Load Territory Survey
 
 Check if territory survey exists before research:
@@ -154,6 +159,129 @@ ls .aether/data/survey/*.md 2>/dev/null
 
 **If no survey:** Continue without survey context (scouts will do fresh exploration)
 
+### Step 3.6: Phase Domain Research
+
+Investigate domain knowledge for each phase before the planning loop begins. This runs every time `/ant:plan` generates a new plan -- no skip flag.
+
+**1. Retrieve hive wisdom for research priming:**
+
+```bash
+hive_context=$(bash .aether/aether-utils.sh 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 = ""`.
+
+**2. Clean any previous research for this phase:**
+
+```bash
+research_dir=".aether/data/phase-research"
+mkdir -p "$research_dir"
+rm -f "$research_dir/phase-{phase_number}-research.md"
+```
+
+Re-running /ant:plan always re-researches from scratch.
+
+**3. Spawn Research Scout** via Task tool with `subagent_type="aether-scout"`:
+
+FALLBACK: If "Agent type not found", use general-purpose and inject role: "You are a Scout Ant performing Phase Domain Research."
+
+```
+You are a Scout Ant performing Phase Domain Research.
+
+--- MISSION ---
+Investigate the domain knowledge needed for Phase {phase_number}: {phase_name}
+Goal: "{goal}"
+Phase description: "{phase_description}"
+
+{context_capsule_prompt}
+
+--- PRE-EXISTING COLONY WISDOM ---
+{hive_text}
+
+--- RESEARCH AREAS ---
+1. Key patterns in the existing codebase relevant to this phase
+2. External library/API documentation if the phase involves external tools
+3. Common gotchas and pitfalls in this domain
+4. Recommended implementation approach based on findings
+
+--- SCOPE CONSTRAINTS ---
+- Maximum 5 key patterns
+- Maximum 3 gotchas
+- Maximum 1 recommended approach paragraph
+- Total output under 3000 words
+- Prioritize actionable guidance over exhaustive documentation
+- Check hive wisdom above first -- do not re-discover known patterns
+
+--- TOOLS ---
+Use: Glob, Grep, Read, WebSearch, WebFetch
+Do NOT use: Task, Write, Edit
+
+--- OUTPUT FORMAT ---
+Return JSON:
+{
+  "hive_wisdom_used": ["list of hive entries that were relevant"],
+  "key_patterns": [
+    {"pattern": "description", "source": "file path or URL", "relevance": "why it matters for this phase"}
+  ],
+  "external_context": [
+    {"topic": "what", "finding": "description", "source": "URL or doc reference"}
+  ],
+  "gotchas": [
+    {"issue": "what can go wrong", "prevention": "how to avoid it", "source": "evidence"}
+  ],
+  "recommended_approach": "synthesis paragraph",
+  "files_to_study": ["path1", "path2"]
+}
+```
+
+**4. Wait for scout to complete** (blocking -- direct Task return).
+
+**5. Parse scout JSON output and write RESEARCH.md to disk.** The Queen (plan.md orchestrator) writes the file -- scout is read-only. Write to: `.aether/data/phase-research/phase-{phase_number}-research.md`
+
+RESEARCH.md format (6 fixed sections):
+
+```markdown
+# Phase {N} Research: {Phase Name}
+
+**Generated:** {ISO-8601 timestamp}
+**Phase:** {N} - {Phase Name}
+**Research scope:** {brief summary of what was investigated}
+
+## Hive Wisdom (Pre-existing Knowledge)
+{Format hive_wisdom_used entries, or "No relevant hive wisdom found" if empty}
+
+## Key Patterns
+{Format each key_patterns entry as: **{pattern}:** {relevance} (Source: {source})}
+
+## External Context
+{Format each external_context entry as: **{topic}:** {finding} (Source: {source})}
+{If empty: "No external research needed for this phase"}
+
+## Gotchas
+{Format each gotchas entry as: **{issue}:** {prevention} (Source: {source})}
+
+## Recommended Approach
+{recommended_approach text}
+
+## Files to Study
+{Format as bullet list of file paths}
+```
+
+**6. Store research findings** in a variable `research_findings_summary` for injection into the Route-Setter prompt in Step 4. This is a compact summary (not the full RESEARCH.md):
+
+```
+Key Patterns: {bullet list of pattern names}
+Gotchas: {bullet list of gotcha titles}
+Recommended: {recommended_approach, first sentence only}
+Files: {comma-separated file paths}
+```
+
+**7. Display completion:**
+
+```
+Research complete: phase-{phase_number}-research.md ({word_count} words)
+```
+
 ### Step 4: Research and Planning Loop
 
 Initialize tracking:
@@ -164,15 +292,15 @@ Initialize tracking:
 - `last_confidence = 0`
 - `stall_count = 0` (consecutive iterations with < 5% improvement)
 
-**Loop (max 4 iterations, 2 agents per iteration: 1 scout + 1 planner):**
+**Loop (max {max_iterations} iterations, 2 agents per iteration: 1 scout + 1 planner):**
 
 ```
-while iteration < 4 AND confidence < 80:
+while iteration < max_iterations AND confidence < target_confidence:
     iteration += 1
 
     # === AUTO-BREAK CHECKS (no user prompt needed) ===
     if iteration > 1:
-        if confidence >= 80:
+        if confidence >= target_confidence:
             Log: "Confidence threshold reached ({confidence}%), finalizing plan"
             break
         if stall_count >= 2:
@@ -193,7 +321,9 @@ while iteration < 4 AND confidence < 80:
         Research the codebase to understand what exists and how it works.
 
         Goal: "{goal}"
-        Iteration: {iteration}/4
+        Iteration: {iteration}/{max_iterations}
+
+        {context_capsule_prompt}
 
         --- EXPLORATION AREAS ---
         Cover ALL of these in a single pass:
@@ -237,7 +367,9 @@ while iteration < 4 AND confidence < 80:
         Investigate ONLY these specific knowledge gaps. Do not explore broadly.
 
         Goal: "{goal}"
-        Iteration: {iteration}/4
+        Iteration: {iteration}/{max_iterations}
+
+        {context_capsule_prompt}
 
         --- GAPS TO INVESTIGATE ---
         {for each gap in gaps:}
@@ -270,8 +402,6 @@ while iteration < 4 AND confidence < 80:
     # Wait for scout to complete.
     # Update gaps list from scout results.
 
-    Log: `bash .aether/aether-utils.sh activity-log "RESEARCH" "scout" "Iteration {iteration}: {scout.findings.length} findings, {scout.gaps_remaining.length} gaps"`
-
     # === PLANNING PHASE (always runs — 1 planner per iteration) ===
 
     Spawn Planning Ant (Route-Setter) via Task tool with subagent_type="aether-route-setter":
@@ -284,10 +414,11 @@ while iteration < 4 AND confidence < 80:
     Create or refine a project plan based on research findings.
 
     Goal: "{goal}"
-    Iteration: {iteration}/4
+    Iteration: {iteration}/{max_iterations}
+
+    {context_capsule_prompt}
 
     --- PLANNING DISCIPLINE ---
-    Read .aether/planning.md for full reference.
 
     Key rules:
     - Bite-sized tasks (2-5 minutes each) - one action per task
@@ -323,6 +454,9 @@ while iteration < 4 AND confidence < 80:
     --- RESEARCH FINDINGS ---
     {scout.findings formatted — compact, max 5 items}
 
+    --- PHASE DOMAIN RESEARCH (from Step 3.6) ---
+    {research_findings_summary if available, otherwise omit this section}
+
     Remaining Gaps:
     {gaps formatted — compact, max 3 items}
 
@@ -384,8 +518,6 @@ while iteration < 4 AND confidence < 80:
 
     Parse planning results. Update plan_draft and confidence.
 
-    Log: `bash .aether/aether-utils.sh activity-log "PLANNING" "route-setter" "Confidence: {confidence}% (+{delta}%)"`
-
     # === UPDATE WATCH FILES ===
 
     Update `.aether/data/watch-status.txt` with current state.
@@ -417,7 +549,7 @@ Proceed directly to Step 5. No user confirmation needed — the plan auto-finali
 
 ### Step 5: Finalize Plan
 
-Once loop exits (confidence >= 80, max iterations reached, or stall detected):
+Once loop exits (confidence >= {target_confidence}, max iterations reached, or stall detected):
 
 Read current COLONY_STATE.json, then update:
 - Set `plan.phases` to the final phases array
@@ -451,18 +583,12 @@ bash .aether/aether-utils.sh session-update "/ant:plan" "/ant:build 1" "Plan gen
 
 ### Step 7: Display Plan
 
-**If visual_mode is true, render final swarm display:**
-```bash
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Plan generated" "Colony" '{"read":8,"grep":4,"edit":2,"bash":1}' 100 "fungus_garden" 100
-bash .aether/aether-utils.sh swarm-display-inline "$plan_id"
-```
-
 Read `plan.phases` from COLONY_STATE.json and display:
 
 ```
-📊🐜🗺️🐜📊 ═══════════════════════════════════════════════════
+📊🐜🗺️🐜📊 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    C O L O N Y   P L A N
-═══════════════════════════════════════════════════ 📊🐜🗺️🐜📊
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊🐜🗺️🐜📊
 
 👑 Goal: {goal}
 
@@ -496,6 +622,14 @@ Read `plan.phases` from COLONY_STATE.json and display:
 
 Status icons: pending = `[ ]`, in_progress = `[~]`, completed = `[✓]`
 
+After displaying the plan, generate the state-based Next Up block:
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```
+
 ---
 
 ## Confidence Scoring Reference
@@ -512,7 +646,7 @@ Each dimension rated 0-100%:
 
 **Overall** = weighted average (knowledge 25%, requirements 25%, risks 20%, dependencies 15%, effort 15%)
 
-**Target: 80%** - Sufficient confidence for autonomous execution. Higher confidence is achieved during builds as gaps are resolved.
+**Target:** Use the selected planning depth target. Higher targets trade latency for stronger up-front plan quality.
 
 ---
 
@@ -520,9 +654,9 @@ Each dimension rated 0-100%:
 
 The planning loop terminates automatically without requiring user input:
 
-1. **Confidence Threshold**: Loop exits when overall confidence reaches 80%
+1. **Confidence Threshold**: Loop exits when overall confidence reaches `{target_confidence}%`
 
-2. **Hard Iteration Cap**: Maximum 4 iterations (8 subagents total: 1 scout + 1 planner per iteration)
+2. **Hard Iteration Cap**: Maximum `{max_iterations}` iterations (2 subagents per iteration: 1 scout + 1 planner)
 
 3. **Stall Detection**: If confidence improves < 5% for 2 consecutive iterations, auto-finalize current plan
 

package/.claude/commands/ant/preferences.md

@@ -0,0 +1,65 @@
+<!-- Generated from .aether/commands/preferences.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:preferences
+description: "Add or list user preferences in hub QUEEN.md"
+---
+
+You are the **Queen**. Manage user preferences in the hub `~/.aether/QUEEN.md`.
+
+## Instructions
+
+The input is: `$ARGUMENTS`
+
+### Step 1: Validate
+
+If `$ARGUMENTS` empty -> show usage: `/ant:preferences "preference text"` or `/ant:preferences --list`, stop.
+
+### Step 2: Route
+
+- `$ARGUMENTS` is `--list` -> **List mode**
+- Otherwise -> **Add mode**
+
+### List Mode
+
+Read `~/.aether/QUEEN.md`. If missing -> "No hub QUEEN.md found. Run /ant:init to create one.", stop.
+
+Find the `## User Preferences` section (with or without emoji). Extract bullet lines (`- ...`) between that heading and the next `---`.
+
+If user-added bullets exist, output each. Otherwise:
+```
+No user preferences set yet.
+Add one with: /ant:preferences "your preference"
+```
+Stop.
+
+### Add Mode
+
+Set `PREF` to `$ARGUMENTS` (strip surrounding quotes).
+If length > 500 chars -> "Preference too long (max 500 chars)", stop.
+
+Read `~/.aether/QUEEN.md`. If missing -> "No hub QUEEN.md found. Run /ant:init to create one.", stop.
+
+**If `## User Preferences` section exists** (with or without emoji):
+1. Remove `*No user preferences recorded yet.*` placeholder if present
+2. Append `- $PREF` at end of section (before next `---`)
+
+**If section missing** (migration case):
+1. Insert before `## Evolution Log` (with or without emoji):
+```
+## User Preferences
+
+- $PREF
+
+---
+
+```
+
+Update METADATA comment: increment `stats.total_user_prefs` by 1.
+
+### Confirm
+
+Output (2 lines, no banners):
+```
+Preference saved to hub QUEEN.md
+  "$PREF"
+```

package/.claude/commands/ant/redirect.md

@@ -1,9 +1,13 @@
+<!-- Generated from .aether/commands/redirect.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:redirect
-description: "⚠️🐜🚧🐜⚠️ Emit REDIRECT signal to warn colony away from patterns"
+description: "Emit REDIRECT signal to warn colony away from patterns"
 ---
 
-You are the **Queen**. Add an AVOID constraint.
+
+You are the **Queen**. Emit a REDIRECT pheromone signal.
+
+
 
 ## Instructions
 
@@ -14,48 +18,59 @@ The pattern to avoid is: `$ARGUMENTS`
 If `$ARGUMENTS` empty -> show usage: `/ant:redirect <pattern to avoid>`, stop.
 If content > 500 chars -> "Redirect content too long (max 500 chars)", stop.
 
-### Step 2: Read + Update Constraints
+
+Parse optional flags from `$ARGUMENTS`:
+- `--ttl <value>`: signal lifetime (e.g., `2h`, `1d`, `7d`). Default: `phase_end`.
+- Strip flags from content before using it as the pattern.
+
+
+### Step 2: Write Signal
 
 Read `.aether/data/COLONY_STATE.json`.
 If `goal: null` -> "No colony initialized.", stop.
 
-Read `.aether/data/constraints.json`. If file doesn't exist, create it with:
-```json
-{"version": "1.0", "focus": [], "constraints": []}
-```
 
-Generate constraint ID: `c_<unix_timestamp_ms>`
-
-Append to `constraints` array:
-```json
-{
-  "id": "<generated_id>",
-  "type": "AVOID",
-  "content": "<pattern to avoid>",
-  "source": "user:redirect",
-  "created_at": "<ISO-8601 timestamp>"
-}
+Run using the Bash tool with description "Setting colony redirect...":
+```bash
+bash .aether/aether-utils.sh pheromone-write REDIRECT "<content>" --strength 0.9 --reason "User warned colony away from pattern" --ttl <ttl>
 ```
 
-If `constraints` array exceeds 10 entries, remove the oldest entries to keep only 10.
+Parse the returned JSON for the signal ID.
 
-Write constraints.json.
+### Step 2.5: Update Context Document
 
-### Step 3: Confirm
+Run using the Bash tool with description "Updating context document...":
+```bash
+bash .aether/aether-utils.sh context-update constraint redirect "<content>" "user" 2>/dev/null || true
+```
 
-Output header:
+### Step 3: Get Active Counts
 
+Run using the Bash tool with description "Counting active signals...":
+```bash
+bash .aether/aether-utils.sh pheromone-count
 ```
-⚠️🐜🚧🐜⚠️ ═══════════════════════════════════════════════════
-   R E D I R E C T   S I G N A L
-═══════════════════════════════════════════════════ ⚠️🐜🚧🐜⚠️
-```
 
-Then output:
+### Step 4: Confirm
+
+Output (3-4 lines, no banners):
 ```
-🚫 REDIRECT signal emitted
+REDIRECT signal emitted
+  Avoid: "<content truncated to 60 chars>"
+  Strength: 0.9 | Expires: <phase end or ttl value>
+  Active signals: <focus_count> FOCUS, <redirect_count> REDIRECT, <feedback_count> FEEDBACK
+```
+
 
-   Avoid: "{content preview}"
 
-🐜 Colony warned away from this pattern.
+
+### Step 5: Next Up
+
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
 ```
+

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

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/resume-colony.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:resume-colony
 description: "🚦➡️🐜💨💨 Resume colony from saved session - restores all state"
@@ -13,25 +14,16 @@ Parse `$ARGUMENTS`:
 
 ### Step 0: Initialize Visual Mode (if enabled)
 
-If `visual_mode` is true:
-```bash
-# Generate session ID
-resume_id="resume-$(date +%s)"
-
-# Initialize swarm display
-bash .aether/aether-utils.sh swarm-display-init "$resume_id"
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "excavating" "Resuming colony" "Colony" '{"read":0,"grep":0,"edit":0,"bash":0}' 0 "fungus_garden" 0
-```
-
+If `visual_mode` is true, run using the Bash tool with description "Initializing resume display...":
 ### 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 with description "Checking colony version...": `bash .aether/aether-utils.sh 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 the Bash tool with description "Restoring colony session...": `bash .aether/aether-utils.sh load-state`
 
 If successful:
 1. Parse state from result
@@ -43,13 +35,35 @@ Keep state loaded (don't unload yet) - we'll need it for the full display.
 
 ### Step 2: Compute Active Signals
 
-Read active signals from COLONY_STATE.json `signals` array (already loaded in Step 1).
+Run using the Bash tool with description "Loading active pheromones...":
+```bash
+bash .aether/aether-utils.sh pheromone-read
+```
+
+Use `.result.signals` as the active signal list (already decay-filtered by runtime logic).
+If empty, treat as "no active pheromones."
 
-Filter signals where:
-- `expires_at` is null (permanent signals like INIT), OR
-- `expires_at` > current timestamp (not expired)
+### Step 2.5: Load Survey Context (Advisory)
+
+Run using the Bash tool with description "Loading survey context...":
+```bash
+survey_docs=$(ls -1 .aether/data/survey/*.md 2>/dev/null | wc -l | tr -d ' ')
+survey_latest=$(ls -t .aether/data/survey/*.md 2>/dev/null | head -1)
+if [[ -n "$survey_latest" ]]; then
+  now_epoch=$(date +%s)
+  modified_epoch=$(stat -f %m "$survey_latest" 2>/dev/null || stat -c %Y "$survey_latest" 2>/dev/null || echo 0)
+  survey_age_days=$(( (now_epoch - modified_epoch) / 86400 ))
+else
+  survey_age_days=-1
+fi
+echo "survey_docs=$survey_docs"
+echo "survey_age_days=$survey_age_days"
+```
 
-If `signals` array is empty or all expired, treat as "no active pheromones."
+Interpretation:
+- `survey_docs == 0` => survey missing
+- `survey_age_days > 14` => survey stale
+- otherwise survey fresh
 
 ### Step 3: Display Restored State
 
@@ -58,9 +72,9 @@ If `signals` array is empty or all expired, treat as "no active pheromones."
 Output header:
 
 ```
-🚦➡️🐜💨💨 ═══════════════════════════════════════════════════
+🚦➡️🐜💨💨 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    C O L O N Y   R E S U M E D
-═══════════════════════════════════════════════════ 🚦➡️🐜💨💨
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚦➡️🐜💨💨
 ```
 
 Read the .aether/HANDOFF.md for context about what was happening, then display:
@@ -87,18 +101,18 @@ PHASE PROGRESS
   Phase <id>: <name> [<status>]
   (list all phases from plan.phases)
 
+SURVEY CONTEXT
+  Docs: <survey_docs>
+  Age: <survey_age_days> days
+  Status: <fresh|stale|missing>
+  Recommendation: <if missing or stale, suggest /ant:colonize --force-resurvey>
+
 CONTEXT FROM HANDOFF
   <summarize what was happening from .aether/HANDOFF.md>
 
 NEXT ACTIONS
 ```
 
-**If visual_mode is true, render final swarm display:**
-```bash
-bash .aether/aether-utils.sh swarm-display-update "Queen" "prime" "completed" "Colony resumed" "Colony" '{"read":3,"grep":0,"edit":2,"bash":1}' 100 "fungus_garden" 100
-bash .aether/aether-utils.sh swarm-display-inline "$resume_id"
-```
-
 Route to next action based on state:
 - If state is `READY` and there's a pending phase -> suggest `/ant:build <phase>`
 - If state is `EXECUTING` -> note that a build was interrupted, suggest restarting with `/ant:build <phase>`
@@ -113,9 +127,19 @@ Use Write tool to update COLONY_STATE.json:
 - Update last_updated timestamp
 - Add event: `{timestamp, type: "colony_resumed", worker: "resume", details: "Session resumed"}`
 
-Use Bash tool to remove HANDOFF.md: `rm -f .aether/HANDOFF.md`
+Use Bash tool with description "Cleaning up handoff file..." to remove HANDOFF.md: `rm -f .aether/HANDOFF.md`
 
-Run: `bash .aether/aether-utils.sh unload-state` to release lock.
+Run using the Bash tool with description "Releasing colony lock...": `bash .aether/aether-utils.sh unload-state` to release lock.
+
+### Step 7: Next Up
+
+Generate the state-based Next Up block by running using the Bash tool with description "Generating Next Up suggestions...":
+```bash
+state=$(jq -r '.state // "IDLE"' .aether/data/COLONY_STATE.json)
+current_phase=$(jq -r '.current_phase // 0' .aether/data/COLONY_STATE.json)
+total_phases=$(jq -r '.plan.phases | length' .aether/data/COLONY_STATE.json)
+bash .aether/aether-utils.sh print-next-up "$state" "$current_phase" "$total_phases"
+```
 
 ---