aether-colony 3.1.17 → 5.0.0

package/.claude/commands/ant/tunnels.md

@@ -9,9 +9,9 @@ You are the **Queen**. Browse the colony history.
 
 ### Argument Handling
 
-- No arguments: Show chamber list (Step 4)
-- One argument: Show single chamber detail (Step 3)
-- Two arguments: Compare two chambers (Step 5)
+- No arguments: Show timeline view (Step 4)
+- One argument: Show single chamber detail with seal document (Step 3)
+- Two arguments: Compare two chambers side-by-side (Step 5)
 - More than two: "Too many arguments. Use: /ant:tunnels [chamber1] [chamber2]"
 
 ### Step 1: Check for Chambers Directory
@@ -20,9 +20,7 @@ Check if `.aether/chambers/` exists.
 
 If not:
 ```
-🕳️ ═══════════════════════════════════════════════════
-   T U N N E L S   (Colony History)
-══════════════════════════════════════════════════ 🕳️
+TUNNELS — Colony Timeline
 
 No chambers found.
 
@@ -32,26 +30,24 @@ Stop here.
 
 ### Step 2: List All Chambers
 
-Run: `bash .aether/aether-utils.sh chamber-list`
+Run using the Bash tool with description "Loading chamber list...": `bash .aether/aether-utils.sh chamber-list`
 
 Parse JSON result into array of chambers.
 
 If no chambers (empty array):
 ```
-🕳️ ═══════════════════════════════════════════════════
-   T U N N E L S   (Colony History)
-══════════════════════════════════════════════════ 🕳️
+TUNNELS — Colony Timeline
 
-Chambers: 0 colonies archived
+0 colonies archived
 
 The tunnel network is empty.
 Archive colonies with /ant:entomb to preserve history.
 ```
 Stop here.
 
-### Step 3: Handle Detail View (if argument provided)
+### Step 3: Detail View — Show Seal Document (if one argument provided)
 
-If `$ARGUMENTS` is not empty:
+If `$ARGUMENTS` is not empty and contains exactly one argument:
 - Treat it as chamber name
 - Check if `.aether/chambers/{arguments}/` exists
 - If not found:
@@ -62,43 +58,111 @@ If `$ARGUMENTS` is not empty:
   ```
   Stop here.
 
-- If found, read manifest.json and display detailed view:
+**If CROWNED-ANTHILL.md exists in the chamber:**
+
+```bash
+seal_doc=".aether/chambers/{arguments}/CROWNED-ANTHILL.md"
+```
+
+Display the header:
+```
+CHAMBER DETAILS — {chamber_name}
+```
+
+Then display the FULL content of `CROWNED-ANTHILL.md` (read and output the file contents — this IS the seal ceremony record).
+
+After the seal document, check if `colony-archive.xml` exists in the chamber:
+
+```bash
+chamber_has_xml=false
+[[ -f ".aether/chambers/{chamber_name}/colony-archive.xml" ]] && chamber_has_xml=true
 ```
-🕳️ ═══════════════════════════════════════════════════
-   C H A M B E R   D E T A I L S
-══════════════════════════════════════════════════ 🕳️
 
-📦 {chamber_name}
+**If `colony-archive.xml` exists in the chamber**, show footer with import option:
+```
+Chamber integrity: {hash_status from chamber-verify}
+Chamber location: .aether/chambers/{chamber_name}/
+XML Archive: colony-archive.xml found
+
+Actions:
+  1. Import signals from this colony into current colony
+  2. Return to timeline
+  3. Compare with another chamber
+
+Select an action (1/2/3)
+```
+
+Use AskUserQuestion with three options.
 
-👑 Goal:
-   {goal}
+If option 1 selected: proceed to Step 6 (Import Signals from Chamber).
+If option 2 selected: return to timeline (run /ant:tunnels).
+If option 3 selected: prompt for second chamber name then run /ant:tunnels {chamber_a} {chamber_b}.
 
-🏆 Milestone: {milestone} ({version})
-📍 Progress: {phases_completed} of {total_phases} phases
-📅 Entombed: {entombed_at}
+**If `colony-archive.xml` does NOT exist in the chamber**, show the existing footer unchanged:
+```
+Chamber integrity: {hash_status from chamber-verify}
+Chamber location: .aether/chambers/{chamber_name}/
 
-{If decisions exist:}
-🧠 Decisions Preserved:
-   {N} architectural decisions recorded
-{End if}
+Run /ant:tunnels to return to timeline
+Run /ant:tunnels {chamber_a} {chamber_b} to compare chambers
+```
 
-{If learnings exist:}
-💡 Learnings Preserved:
-   {N} validated learnings recorded
-{End if}
+**If CROWNED-ANTHILL.md does NOT exist (older chamber):**
 
-📁 Files:
-   - COLONY_STATE.json (verified: {hash_status})
-   - manifest.json
+Display the header:
+```
+CHAMBER DETAILS — {chamber_name}
 
-Run /ant:tunnels to return to chamber list.
+(No seal document — this chamber was created before the sealing ceremony was introduced)
 ```
 
-To get the counts and hash status:
+Fall back to manifest data display:
+- Read `manifest.json` and show: goal, milestone, version, phases_completed, total_phases, entombed_at
+- Show decisions count and learnings count from manifest
+- Show hash status from `chamber-verify`
+
+Footer with navigation guidance:
+```
+Run /ant:tunnels to return to timeline
+Run /ant:tunnels {chamber_a} {chamber_b} to compare chambers
+```
+
+To get the hash status, run using the Bash tool with description "Verifying chamber integrity...":
 - Run `bash .aether/aether-utils.sh chamber-verify .aether/chambers/{chamber_name}`
-- If verified: hash_status = "✅"
-- If not verified: hash_status = "⚠️ hash mismatch"
-- If error: hash_status = "⚠️ error"
+- If verified: hash_status = "verified"
+- If not verified: hash_status = "hash mismatch"
+- If error: hash_status = "error"
+
+Stop here.
+
+### Step 4: Timeline View (default, no arguments)
+
+Display header:
+```
+TUNNELS — Colony Timeline
+
+{count} colonies archived
+```
+
+For each chamber in sorted list (already sorted by `chamber-list` — newest first), display as a timeline entry:
+```
+[{date}] {milestone_emoji} {chamber_name}
+           {goal (truncated to 60 chars)}
+           {phases_completed} phases | {milestone}
+```
+
+Where `milestone_emoji` is:
+- Crowned Anthill: crown emoji
+- Sealed Chambers: lock emoji
+- Other: circle emoji
+
+After the timeline entries, show:
+```
+Run /ant:tunnels <chamber_name> to view seal document
+Run /ant:tunnels <chamber_a> <chamber_b> to compare two colonies
+```
+
+Use the entombed_at field from the chamber-list JSON to extract the date (first 10 chars of ISO timestamp).
 
 Stop here.
 
@@ -106,9 +170,8 @@ Stop here.
 
 If two arguments provided (chamber names separated by space):
 - Treat as: `/ant:tunnels <chamber_a> <chamber_b>`
-- Run comparison: `bash .aether/utils/chamber-compare.sh compare <chamber_a> <chamber_b>`
 
-If either chamber not found:
+Check both chambers exist. If either missing:
 ```
 Chamber not found: {chamber_name}
 
@@ -117,73 +180,75 @@ Available chambers:
 ```
 Stop here.
 
+Run comparison using the Bash tool with description "Comparing chambers...":
+```bash
+bash .aether/utils/chamber-compare.sh compare <chamber_a> <chamber_b>
+bash .aether/utils/chamber-compare.sh stats <chamber_a> <chamber_b>
+```
+
 Display comparison header:
 ```
-🕳️ ═══════════════════════════════════════════════════
-   C H A M B E R   C O M P A R I S O N
-══════════════════════════════════════════════════ 🕳️
+CHAMBER COMPARISON
 
-📦 {chamber_a}  vs  📦 {chamber_b}
+{chamber_a}  vs  {chamber_b}
 ```
 
 Display side-by-side comparison:
 ```
-┌─────────────────────┬─────────────────────┐
-│ {chamber_a}         │ {chamber_b}         │
-├─────────────────────┼─────────────────────┤
-│ 👑 {goal_a}         │ 👑 {goal_b}         │
-│                     │                     │
-│ 🏆 {milestone_a}    │ 🏆 {milestone_b}    │
-│    {version_a}      │    {version_b}      │
-│                     │                     │
-│ 📍 {phases_a} done  │ 📍 {phases_b} done  │
-│    of {total_a}     │    of {total_b}     │
-│                     │                     │
-│ 🧠 {decisions_a}    │ 🧠 {decisions_b}    │
-│    decisions        │    decisions        │
-│                     │                     │
-│ 💡 {learnings_a}    │ 💡 {learnings_b}    │
-│    learnings        │    learnings        │
-│                     │                     │
-│ 📅 {date_a}         │ 📅 {date_b}         │
-└─────────────────────┴─────────────────────┘
++---------------------+---------------------+
+| {chamber_a}         | {chamber_b}         |
++---------------------+---------------------+
+| Goal: {goal_a}      | Goal: {goal_b}      |
+|                     |                     |
+| {milestone_a}       | {milestone_b}       |
+| {version_a}         | {version_b}         |
+|                     |                     |
+| {phases_a} done     | {phases_b} done     |
+| of {total_a}        | of {total_b}        |
+|                     |                     |
+| {decisions_a}       | {decisions_b}       |
+| decisions           | decisions           |
+|                     |                     |
+| {learnings_a}       | {learnings_b}       |
+| learnings           | learnings           |
+|                     |                     |
+| {date_a}            | {date_b}            |
++---------------------+---------------------+
 ```
 
 Display growth metrics:
 ```
-📈 Growth Between Chambers:
-   Phases: +{phases_diff} ({phases_a} → {phases_b})
-   Decisions: +{decisions_diff} new
-   Learnings: +{learnings_diff} new
-   Time: {time_between} days apart
+Growth Between Chambers:
+  Phases: +{phases_diff} ({phases_a} -> {phases_b})
+  Decisions: +{decisions_diff} new
+  Learnings: +{learnings_diff} new
+  Time: {time_between} days apart
 ```
 
-If phases_diff > 0: show "📈 Colony grew"
-If phases_diff < 0: show "📉 Colony reduced (unusual)"
-If same_milestone: show "🏆 Same milestone reached"
-If milestone changed: show "🏆 Milestone advanced: {milestone_a} → {milestone_b}"
+If phases_diff > 0: show "Colony grew"
+If phases_diff < 0: show "Colony reduced (unusual)"
+If same_milestone: show "Same milestone reached"
+If milestone changed: show "Milestone advanced: {milestone_a} -> {milestone_b}"
 
-Display pheromone trail diff (new decisions/learnings in B):
+Display pheromone trail diff (new decisions/learnings in B) by running using the Bash tool with description "Analyzing pheromone differences...":
 ```bash
 bash .aether/utils/chamber-compare.sh diff <chamber_a> <chamber_b>
 ```
 
 Parse result and show:
 ```
-🧠 New Decisions in {chamber_b}:
-   {N} new architectural decisions
-   {if N <= 5, list them; else show first 3 + "...and {N-3} more"}
+New Decisions in {chamber_b}:
+  {N} new architectural decisions
+  {if N <= 5, list them; else show first 3 + "...and {N-3} more"}
 
-💡 New Learnings in {chamber_b}:
-   {N} new validated learnings
-   {if N <= 5, list them; else show first 3 + "...and {N-3} more"}
+New Learnings in {chamber_b}:
+  {N} new validated learnings
+  {if N <= 5, list them; else show first 3 + "...and {N-3} more"}
 ```
 
-Display knowledge preservation:
+If both chambers have `CROWNED-ANTHILL.md`, note:
 ```
-📚 Knowledge Preservation:
-   {preserved_decisions} decisions carried forward
-   {preserved_learnings} learnings carried forward
+Both colonies have seal documents. Run /ant:tunnels <name> to view individually.
 ```
 
 Footer:
@@ -194,36 +259,145 @@ Run /ant:tunnels <chamber> to view single chamber details
 
 Stop here.
 
-### Step 4: Display Chamber List (default view)
+### Step 6: Import Signals from Chamber
+
+When user selects "Import signals" from Step 3:
+
+**Step 6.1: Check XML tools** by running using the Bash tool with description "Checking XML tools...":
+```bash
+if command -v xmllint >/dev/null 2>&1; then
+  xmllint_available=true
+else
+  xmllint_available=false
+fi
+```
+
+If xmllint not available:
+```
+Import requires xmllint. Install it first:
+  macOS: xcode-select --install
+  Linux: apt-get install libxml2-utils
+```
+Stop here (return to timeline).
+
+**Step 6.2: Extract source colony name** by running using the Bash tool with description "Extracting colony info...":
+```bash
+chamber_xml=".aether/chambers/{chamber_name}/colony-archive.xml"
+# Extract colony_id from the archive root element
+source_colony=$(xmllint --xpath "string(/*/@colony_id)" "$chamber_xml" 2>/dev/null)
+[[ -z "$source_colony" ]] && source_colony="{chamber_name}"
+```
+
+**Step 6.3: Extract pheromone section and show import preview**
+
+The combined `colony-archive.xml` contains pheromones, wisdom, and registry sections. Extract the pheromone section to a temp file before counting or importing. This prevents over-counting signals from wisdom/registry sections and ensures `pheromone-import-xml` receives the format it expects (`<pheromones>` as root element).
 
+Run using the Bash tool with description "Extracting pheromone signals...":
+```bash
+# Extract the <pheromones> section from the combined archive into a standalone temp file
+import_tmp_dir=$(mktemp -d)
+import_tmp_pheromones="$import_tmp_dir/pheromones-extracted.xml"
+
+# Use xmllint to extract the pheromones element (with its namespace)
+xmllint --xpath "//*[local-name()='pheromones']" "$chamber_xml" > "$import_tmp_pheromones" 2>/dev/null
+
+# Add XML declaration to make it a standalone well-formed document
+if [[ -s "$import_tmp_pheromones" ]]; then
+  # Portable approach: prepend declaration via temp file (avoids macOS/Linux sed -i differences)
+  { echo '<?xml version="1.0" encoding="UTF-8"?>'; cat "$import_tmp_pheromones"; } > "$import_tmp_dir/tmp_decl.xml"
+  mv "$import_tmp_dir/tmp_decl.xml" "$import_tmp_pheromones"
+fi
+
+# Count pheromone signals in extracted pheromone-only XML
+# Scoped to pheromone section only — no over-counting from wisdom/registry sections
+pheromone_count=$(xmllint --xpath "count(//*[local-name()='signal'])" "$import_tmp_pheromones" 2>/dev/null || echo "unknown")
 ```
-🕳️ ═══════════════════════════════════════════════════
-   T U N N E L S   (Colony History)
-══════════════════════════════════════════════════ 🕳️
 
-Chambers: {count} colonies archived
+Display:
+```
+IMPORT FROM COLONY: {source_colony}
 
-{For each chamber in sorted list:}
-📦 {chamber_name}
-   👑 {goal (truncated to 50 chars)}
-   🏆 {milestone} ({version})
-   📍 {phases_completed} phases | 📅 {date}
+Source: .aether/chambers/{chamber_name}/colony-archive.xml
+Signals available: ~{pheromone_count} pheromone signals
 
-{End for}
+Import behavior:
+  - Signals tagged with prefix "{source_colony}:" to identify origin
+  - Additive merge — your current signals are never overwritten
+  - On conflict, your current colony wins
 
-Run /ant:tunnels <chamber_name> to view details
+Import these signals? (yes/no)
 ```
 
-**Formatting details:**
-- Sort by entombed_at descending (newest first) - already sorted by chamber-list
-- Truncate goal to 50 characters with "..." if longer
-- Format date as YYYY-MM-DD from ISO timestamp (extract first 10 chars of entombed_at)
-- Show chamber count at top
+Use AskUserQuestion with yes/no options.
 
-**Edge cases:**
-- Malformed manifest: show "⚠️  Invalid manifest" for that chamber and skip it
-- Missing COLONY_STATE.json: show "⚠️  Incomplete chamber" for that chamber
-- Very long chamber list: display all (no pagination for now)
+If no: "Import cancelled." Clean up: `rm -rf "$import_tmp_dir"`. Return to timeline.
+
+**Step 6.4: Perform import**
+
+Pass the extracted pheromone-only temp file (NOT the combined `colony-archive.xml`) to `pheromone-import-xml`, along with `$source_colony` as the second argument. This ensures:
+1. `pheromone-import-xml` receives XML with `<pheromones>` as root element (the format it expects)
+2. The prefix-tagging logic prepends `${source_colony}:` to each imported signal's ID before the merge
+
+Run using the Bash tool with description "Importing pheromone signals...":
+```bash
+# Import the EXTRACTED pheromone-only XML (NOT the combined colony-archive.xml)
+# $import_tmp_pheromones has <pheromones> as root — the format pheromone-import-xml expects
+# Second argument triggers prefix-tagging — imported signal IDs become "{source_colony}:original_id"
+import_result=$(bash .aether/aether-utils.sh pheromone-import-xml "$import_tmp_pheromones" "$source_colony" 2>&1)
+import_ok=$(echo "$import_result" | jq -r '.ok // false' 2>/dev/null)
+
+if [[ "$import_ok" == "true" ]]; then
+  imported_count=$(echo "$import_result" | jq -r '.result.signal_count // 0' 2>/dev/null)
+else
+  imported_count=0
+  import_error=$(echo "$import_result" | jq -r '.error // "Unknown error"' 2>/dev/null)
+fi
+
+# Clean up temp files
+rm -rf "$import_tmp_dir"
+```
+
+**Step 6.5: Display result**
+
+If import succeeded:
+```
+SIGNALS IMPORTED
+
+Source: {source_colony}
+Imported: {imported_count} pheromone signals
+Tagged with: "{source_colony}:" prefix
+
+Your colony now carries wisdom from {source_colony}.
+Run /ant:status to see current colony state.
+```
+
+If import failed:
+```
+Import failed: {import_error}
+
+The archive may be malformed. Check:
+  .aether/chambers/{chamber_name}/colony-archive.xml
+```
+
+### Edge Cases
+
+**Malformed manifest:** show "Invalid manifest" for that chamber and skip it.
+
+**Missing COLONY_STATE.json:** show "Incomplete chamber" for that chamber.
+
+**Very long chamber list:** display all (no pagination for now).
+
+**Older chambers without CROWNED-ANTHILL.md:** Fall back to manifest data in detail view.
+
+### 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"
+```
 
 ## Implementation Notes
 

package/.claude/commands/ant/update.md

@@ -28,7 +28,20 @@ Stop here. Do not proceed.
 
 Read the `version` field — this is the **available version**.
 
-### Step 2: Check Current Version
+### Step 2: Check Pending State and Current Version
+
+First, check for a pending sentinel using the Bash tool with description "Checking update state...":
+
+```bash
+test -f .aether/.update-pending && echo "PENDING" || echo "CLEAN"
+```
+
+If output is "PENDING":
+- Output: `Detected incomplete update, re-syncing...`
+- Run using the Bash tool with description "Clearing incomplete update sentinel...": `rm -f .aether/.update-pending`
+- Skip the version comparison entirely — proceed directly to Step 3.
+
+If output is "CLEAN":
 
 Use the Read tool to read `.aether/version.json`.
 
@@ -38,7 +51,7 @@ Otherwise, read the `version` field — this is the **current version**.
 If current version equals available version, output:
 
 ```
-Already up-to-date (v{version}).
+Already up to date (v{version}).
 
 System files and commands match the global hub.
 Colony data (.aether/data/) is always untouched by updates.
@@ -46,54 +59,79 @@ Colony data (.aether/data/) is always untouched by updates.
 
 Stop here. Do not proceed.
 
-### Step 3: Bootstrap System Files
+### Step 3: Sync System Files from Hub
 
-If `.aether/aether-utils.sh` does not exist yet (new repo that predates the hub), copy it from the hub first:
-```
-cp ~/.aether/system/aether-utils.sh .aether/aether-utils.sh && chmod +x .aether/aether-utils.sh
+The hub stores all system files at `~/.aether/system/`.
+
+Run ONE bash command with description "Syncing colony system files...":
+
+```bash
+mkdir -p .aether/docs .aether/utils .aether/templates .aether/schemas .aether/exchange && \
+cp -f ~/.aether/system/aether-utils.sh .aether/ && \
+cp -f ~/.aether/system/workers.md .aether/ 2>/dev/null || true && \
+cp -f ~/.aether/system/CONTEXT.md .aether/ 2>/dev/null || true && \
+cp -f ~/.aether/system/model-profiles.yaml .aether/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/docs/* .aether/docs/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/utils/* .aether/utils/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/templates/* .aether/templates/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/schemas/* .aether/schemas/ 2>/dev/null || true && \
+cp -Rf ~/.aether/system/exchange/* .aether/exchange/ 2>/dev/null || true && \
+chmod +x .aether/aether-utils.sh && \
+echo "System files synced"
 ```
 
-Then run using the Bash tool:
+Colony data (`.aether/data/`) is never touched.
+
+If any sync step fails, output:
 ```
-bash .aether/aether-utils.sh bootstrap-system
+Update couldn't finish — some files didn't copy. Run /ant:update again to retry.
 ```
 
-This copies system files (docs, utils, aether-utils.sh) from `~/.aether/system/` into `.aether/` using an explicit allowlist. Colony data is never touched.
+### Step 3.5: Sync Rules to .claude/rules/
+
+Rules files teach Claude Code about the colony system. Sync them from the hub with description "Syncing colony rules...":
 
-Parse the JSON output to get the count of copied files.
+```bash
+# Sync rules if hub has them
+if [ -d ~/.aether/system/rules ]; then
+  mkdir -p .claude/rules
+  cp -Rf ~/.aether/system/rules/* .claude/rules/ 2>/dev/null || true
+  echo "Rules synced"
+fi
+```
 
 ### Step 4: Sync Commands (with orphan cleanup)
 
 Sync command files from the hub to this repo **and remove stale files** that no longer exist in the hub. This prevents renamed or deleted commands from accumulating as orphans.
 
-For each directory pair, run using the Bash tool:
+For each directory pair, run using the Bash tool with description "Syncing colony commands and agents...":
 
 ```bash
 # Sync Claude commands
 mkdir -p .claude/commands/ant
-cp -R ~/.aether/commands/claude/* .claude/commands/ant/ 2>/dev/null
+cp -R ~/.aether/system/commands/claude/* .claude/commands/ant/ 2>/dev/null
 # Remove orphans: files in dest that aren't in hub
 comm -23 \
   <(cd .claude/commands/ant && find . -type f ! -name '.*' | sort) \
-  <(cd ~/.aether/commands/claude && find . -type f ! -name '.*' | sort) \
+  <(cd ~/.aether/system/commands/claude && find . -type f ! -name '.*' | sort) \
   | while read f; do rm ".claude/commands/ant/$f" && echo "  removed stale: .claude/commands/ant/$f"; done
 echo "claude: done"
 
 # Sync OpenCode commands
 mkdir -p .opencode/commands/ant
-cp -R ~/.aether/commands/opencode/* .opencode/commands/ant/ 2>/dev/null
+cp -R ~/.aether/system/commands/opencode/* .opencode/commands/ant/ 2>/dev/null
 comm -23 \
   <(cd .opencode/commands/ant && find . -type f ! -name '.*' | sort) \
-  <(cd ~/.aether/commands/opencode && find . -type f ! -name '.*' | sort) \
+  <(cd ~/.aether/system/commands/opencode && find . -type f ! -name '.*' | sort) \
   | while read f; do rm ".opencode/commands/ant/$f" && echo "  removed stale: .opencode/commands/ant/$f"; done
 echo "opencode: done"
 
 # Sync agents
 mkdir -p .opencode/agents
-cp -R ~/.aether/agents/* .opencode/agents/ 2>/dev/null
+cp -R ~/.aether/system/agents/* .opencode/agents/ 2>/dev/null
 comm -23 \
   <(cd .opencode/agents && find . -type f ! -name '.*' | sort) \
-  <(cd ~/.aether/agents && find . -type f ! -name '.*' | sort) \
+  <(cd ~/.aether/system/agents && find . -type f ! -name '.*' | sort) \
   | while read f; do rm ".opencode/agents/$f" && echo "  removed stale: .opencode/agents/$f"; done
 echo "agents: done"
 ```
@@ -102,7 +140,7 @@ Report any removed stale files in the summary.
 
 ### Step 5: Register and Version Stamp
 
-Run using the Bash tool:
+Run using the Bash tool with description "Registering colony in hub...":
 ```
 bash .aether/aether-utils.sh registry-add "$(pwd)" "{available_version}"
 ```
@@ -117,14 +155,27 @@ Then use the Write tool to write `.aether/version.json`:
 }
 ```
 
+Then delete any leftover pending sentinel (update is now complete) using the Bash tool with description "Clearing update sentinel...":
+```bash
+rm -f .aether/.update-pending
+```
+
+### Step 5.5: Clear Version Cache
+
+Clear the version check cache so the next command sees the fresh version:
+
+```bash
+rm -f .aether/data/.version-check-cache
+```
+
 ### Step 6: Display Summary
 
 Output:
 
 ```
-🔄🐜📦🐜🔄 ═══════════════════════════════════════════════════
+🔄🐜📦🐜🔄 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    A E T H E R   U P D A T E
-═══════════════════════════════════════════════════ 🔄🐜📦🐜🔄
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔄🐜📦🐜🔄
 
 Updated: v{current_version} -> v{available_version}
 
@@ -146,3 +197,13 @@ The CLI version (`aether update`) performs the same sync-with-cleanup and also s
 
 - `--dry-run` — Preview what would change without modifying any files
 - `--force` — Stash uncommitted changes in managed files and proceed with the update
+
+### 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"
+```