aether-colony 5.0.0 → 5.1.0

package/.claude/commands/ant/phase.md

@@ -1,3 +1,4 @@
+<!-- Generated from .aether/commands/phase.yaml - DO NOT EDIT DIRECTLY -->
 ---
 name: ant:phase
 description: "📝🐜📍🐜📝 Show phase details - Queen reviews phase status, tasks, and caste assignment"
@@ -34,11 +35,13 @@ Find the phase by ID in `plan.phases`.
 
 Output this header:
 
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📝🐜📍🐜📝  P H A S E   {id}   D E T A I L S
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+
+
 
 Then display:
 
@@ -55,14 +58,18 @@ Then display:
 ✅ Success Criteria:
    • <criterion>
 
-──────────────────────────────────────────────────
+───────────────────────────────────────────────────
+
 🐜 Next Up
-──────────────────────────────────────────────────
+
+
+───────────────────────────────────────────────────
    /ant:build <id>       🔨 Phase <id>: <phase_name>
    /ant:phase <next_id>  📋 Phase <next_id>: <next_phase_name> (only if not last phase)
    /ant:status           📊 Colony status
 ```
 
+
 After displaying phase details, 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)
@@ -71,56 +78,38 @@ 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"
 ```
 
+
 Status icons: `[ ]` pending, `[~]` in_progress, `[✓]` completed
 
 ### Step 3b: List View
 
 Output this header:
 
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 📝🐜📍🐜📝  A L L   P H A S E S
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-Then display all phases as a summary:
 
-```
-👑 Goal: "<goal>"
-
-   {icon} Phase <id>: <name>
-         <completed>/<total> tasks | <status>
-
-(repeat for each phase)
 
-─────────────────────────────────────────────────────
-Legend: [✓] completed  [~] in progress  [ ] pending
 
-🐜 /ant:phase <id> for details
+For each phase in `plan.phases`, display:
 ```
-
-### Step 4: Update Handoff (Optional)
-
-After displaying phase details, offer to update the handoff document with review notes:
-
-Use AskUserQuestion:
+[{id}] {name} [{status}]
+   {short_description}
 ```
-Update handoff with phase review notes?
 
-1. Yes — add notes about blockers or decisions
-2. No — continue without updating
+Display phases grouped by status:
 ```
-
-If option 1 selected:
-Use AskUserQuestion to collect notes, then append to handoff:
-
-```bash
-cat >> .aether/HANDOFF.md << 'HANDOFF_EOF'
-
-## Phase {id} Review Notes
-- Reviewed: $(date -u +%Y-%m-%dT%H:%M:%SZ)
-- Notes: {user_notes}
-HANDOFF_EOF
+✓ Completed
+   [{id}] {name}
+~ In Progress
+   [{id}] {name}
+[ ] Pending
+   [{id}] {name}
 ```
 
-Display: `Handoff updated with review notes.`
+Display completion progress:
+```
+📊 Overall: {completed_count}/{total_count} phases complete
+```

package/.claude/commands/ant/pheromones.md

@@ -0,0 +1,156 @@
+<!-- Generated from .aether/commands/pheromones.yaml - DO NOT EDIT DIRECTLY -->
+---
+name: ant:pheromones
+description: "🎯🐜🚫🐜💬 View and manage active pheromone signals"
+---
+
+You are the **Queen**. Display and manage the colony's pheromone signals.
+
+## Instructions
+
+Parse `$ARGUMENTS`:
+- If contains `--no-visual`: set `visual_mode = false` (visual is ON by default)
+- Otherwise: set `visual_mode = true`
+
+Extract subcommand from `$ARGUMENTS`:
+- No argument or `all`: Show all active pheromones
+- `focus`: Show only FOCUS signals
+- `redirect`: Show only REDIRECT signals
+- `feedback`: Show only FEEDBACK signals
+- `clear`: Clear expired/inactive signals
+- `expire <id>`: Expire a specific signal by ID
+
+### Step 1: Read Colony State
+
+Read `.aether/data/COLONY_STATE.json`.
+
+If file missing or `goal: null`:
+```
+No colony initialized. Run /ant:init first.
+```
+Stop here.
+
+### Step 2: Handle Subcommands
+
+**If subcommand is `clear`:**
+
+Run using the Bash tool:
+```bash
+# Count signals before
+before_count=$(jq '[.signals[] | select(.active == true)] | length' .aether/data/pheromones.json 2>/dev/null || echo "0")
+
+# Mark expired/inactive signals as inactive
+now=$(date +%s)
+jq --argjson now "$now" '
+  def to_epoch(ts):
+    if ts == null or ts == "" or ts == "phase_end" then null
+    else
+      (ts | split("T")) as $parts |
+      ($parts[0] | split("-")) as $d |
+      ($parts[1] | rtrimstr("Z") | split(":")) as $t |
+      (($d[0] | tonumber) - 1970) * 365 * 86400 +
+      (($d[1] | tonumber) - 1) * 30 * 86400 +
+      (($d[2] | tonumber) - 1) * 86400 +
+      ($t[0] | tonumber) * 3600 +
+      ($t[1] | tonumber) * 60 +
+      ($t[2] | rtrimstr("Z") | tonumber)
+    end;
+
+  def decay_days(t):
+    if t == "FOCUS"    then 30
+    elif t == "REDIRECT" then 60
+    else 90
+    end;
+
+  .signals = [.signals[] |
+    (to_epoch(.created_at)) as $created_epoch |
+    (if $created_epoch != null then ($now - $created_epoch) / 86400 else 0 end) as $elapsed_days |
+    (decay_days(.type)) as $dd |
+    ((.strength // 0.8) * (1 - ($elapsed_days / $dd))) as $eff_raw |
+    (if $eff_raw < 0 then 0 else $eff_raw end) as $eff |
+    if $eff < 0.1 then . + {active: false} else . end
+  ]
+' .aether/data/pheromones.json > .aether/data/pheromones.json.tmp && mv .aether/data/pheromones.json.tmp .aether/data/pheromones.json
+
+# Count signals after
+after_count=$(jq '[.signals[] | select(.active == true)] | length' .aether/data/pheromones.json 2>/dev/null || echo "0")
+cleared=$((before_count - after_count))
+
+echo "before=$before_count after=$after_count cleared=$cleared"
+```
+
+Display:
+```
+🧹 Pheromone Cleanup
+
+   Before: {before_count} active signals
+   After:  {after_count} active signals
+   Cleared: {cleared} expired signal(s)
+
+Run /ant:pheromones to see remaining signals.
+```
+Stop here.
+
+**If subcommand is `expire <id>`:**
+
+Extract the signal ID from arguments.
+Run using the Bash tool:
+```bash
+signal_id="{extracted_id}"
+jq --arg id "$signal_id" '.signals = [.signals[] | if .id == $id then . + {active: false} else . end]' .aether/data/pheromones.json > .aether/data/pheromones.json.tmp && mv .aether/data/pheromones.json.tmp .aether/data/pheromones.json && echo "expired=$signal_id"
+```
+
+Display:
+```
+✓ Signal expired: {signal_id}
+
+Run /ant:pheromones to see remaining signals.
+```
+Stop here.
+
+### Step 3: Display Active Pheromones (default or filter)
+
+Run using the Bash tool with description "Displaying pheromones...":
+```bash
+bash .aether/aether-utils.sh pheromone-display "{subcommand or 'all'}"
+```
+
+The output will be the formatted pheromone table.
+
+### Step 4: Summary and Next Steps
+
+Display guidance:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+💡 Managing Pheromones
+
+   /ant:focus "area"      🎯 Guide attention
+   /ant:redirect "avoid"  🚫 Set hard constraint
+   /ant:feedback "note"   💬 Provide guidance
+   /ant:pheromones clear  🧹 Clear expired signals
+
+🐜 Signals decay over time: FOCUS 30d, REDIRECT 60d, FEEDBACK 90d
+```
+
+### Edge Cases
+
+**No pheromones file:**
+```
+No pheromones active. Colony has no signals.
+
+Inject signals with:
+  /ant:focus "area"    - Guide attention
+  /ant:redirect "avoid" - Set hard constraint
+  /ant:feedback "note"  - Provide guidance
+```
+
+**No active signals of filtered type:**
+```
+No active {type} signals found.
+
+Try: /ant:pheromones (to see all)
+```
+
+**Invalid subcommand:**
+Display help showing valid subcommands.

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,24 +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 (consolidated)
-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 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: Read State + Version Check
+### Step 1: Read State
 
 Read `.aether/data/COLONY_STATE.json`.
 
@@ -79,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:
@@ -91,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...
@@ -108,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:
@@ -153,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:
@@ -163,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:
@@ -192,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:
@@ -236,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:}
@@ -269,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":
@@ -283,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
@@ -322,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}
 
@@ -383,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.
@@ -416,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
@@ -426,11 +559,6 @@ Read current COLONY_STATE.json, then update:
 
 Write COLONY_STATE.json.
 
-Validate the state file:
-```bash
-bash .aether/aether-utils.sh validate-state colony
-```
-
 Log: `bash .aether/aether-utils.sh activity-log "PLAN_COMPLETE" "queen" "Plan finalized with {confidence}% confidence"`
 
 Update watch-status.txt:
@@ -455,11 +583,6 @@ 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 (consolidated):**
-```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-text "$plan_id"
-```
-
 Read `plan.phases` from COLONY_STATE.json and display:
 
 ```
@@ -523,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.
 
 ---
 
@@ -531,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"
+```