aether-colony 3.1.17 → 5.0.0

package/.aether/docs/error-codes.md

@@ -0,0 +1,268 @@
+# Aether Error Code Reference
+
+This document is the complete reference for all `E_*` error constants used in Aether's bash utilities and Node.js CLI. When a command fails, the error output includes a `code` field that maps to one of the entries below.
+
+**How to read this document:** Find the code you see in the error output, then check the meaning, when it happens, and what to do.
+
+---
+
+## File Errors
+
+### E_FILE_NOT_FOUND
+
+- **Meaning:** A required file or directory doesn't exist at the expected path.
+- **When it happens:**
+  - A command is invoked but the data file it needs (e.g., `COLONY_STATE.json`, `flags.json`, `CONTEXT.md`) hasn't been created yet.
+  - A directory path passed as an argument doesn't exist.
+- **Suggested fix:** Check that `aether init` (or the relevant setup command) has been run. Verify the path exists and is spelled correctly.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_FILE_NOT_FOUND","message":"Couldn't find CONTEXT.md. Try: run context-update init first.","details":null,"recovery":"Check file path and permissions","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## Lock Errors
+
+### E_LOCK_FAILED
+
+- **Meaning:** Couldn't acquire a file lock — another process is currently holding it.
+- **When it happens:**
+  - Two commands try to write to the same file (e.g., `flags.json`) at the same time.
+  - A previous command crashed and didn't release its lock. Use `force-unlock` to clear stale locks.
+- **Suggested fix:** Wait for any running operations to finish, then retry. If you're sure nothing else is running, use `aether force-unlock` to clear the lock manually.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_LOCK_FAILED","message":"Failed to acquire lock on flags.json","details":null,"recovery":"Wait for other operations to complete","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_LOCK_STALE
+
+- **Meaning:** A lock file exists but belongs to a process that is no longer running, or has exceeded the maximum lock timeout (5 minutes). This differs from `E_LOCK_FAILED` (which means another process holds a live lock) — `E_LOCK_STALE` means the lock is abandoned.
+- **When it happens:**
+  - A previous command crashed without releasing its lock.
+  - The locking process was killed by the OS (e.g., OOM) or terminated by the user (Ctrl+C) before the trap handler could fire.
+  - The lock is older than the configured timeout (300 seconds).
+- **Suggested fix:** Run `aether force-unlock` to clear stale locks, or manually remove the lock file shown in the error message.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_LOCK_STALE","message":"Stale lock found. Remove manually: .aether/locks/flags.json.lock"}}
+  ```
+
+---
+
+## Tool / Dependency Errors
+
+### E_FEATURE_UNAVAILABLE
+
+- **Meaning:** A feature or optional tool required for this operation isn't installed or enabled.
+- **When it happens:**
+  - XML operations are attempted but `xmllint` isn't installed.
+  - A feature has been disabled due to a missing dependency or configuration.
+- **Suggested fix:** Install the required tool (e.g., `brew install libxml2` for xmllint on macOS) or check the feature's documentation for setup steps.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_FEATURE_UNAVAILABLE","message":"xmllint not available. Try: brew install libxml2","details":null,"recovery":null,"timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_DEPENDENCY_MISSING
+
+- **Meaning:** A required utility script or binary is missing from the expected location.
+- **When it happens:**
+  - A utility script in `.aether/utils/` (e.g., `error-handler.sh`, `file-lock.sh`) can't be found.
+  - A required binary (e.g., `jq`, `git`) isn't installed or isn't on `$PATH`.
+- **Suggested fix:** Run `aether install` to restore missing system files, or install the missing binary via your system package manager.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_DEPENDENCY_MISSING","message":"Couldn't load error-handler.sh. Try: run aether install to restore system files.","details":null,"recovery":"Install the required dependency","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## JSON / Data Errors
+
+### E_JSON_INVALID
+
+- **Meaning:** A JSON file is malformed or is missing required fields.
+- **When it happens:**
+  - A data file (`COLONY_STATE.json`, `flags.json`, etc.) has been manually edited and contains a syntax error.
+  - A write operation was interrupted, leaving a partially-written file.
+- **Suggested fix:** Open the file and fix the JSON syntax, or delete it and re-run the initialization command to regenerate a fresh copy.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_JSON_INVALID","message":"Failed to parse COLONY_STATE.json. Try: validate with jq '.'' .aether/data/COLONY_STATE.json","details":null,"recovery":"Validate JSON syntax","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## Validation Errors
+
+### E_VALIDATION_FAILED
+
+- **Meaning:** The command was called with missing or invalid arguments.
+- **When it happens:**
+  - A required argument (e.g., flag type, flag ID, spawn summary) is missing.
+  - An argument value is outside the allowed range or format.
+- **Suggested fix:** Check the usage message in the error output. The error message typically includes the correct usage syntax.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_VALIDATION_FAILED","message":"Usage: flag-add <type> <title> <description> [source] [phase]","details":null,"recovery":null,"timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## System Errors
+
+### E_BASH_ERROR
+
+- **Meaning:** An unexpected system command failure occurred — a bash command returned a non-zero exit code where one wasn't expected.
+- **When it happens:**
+  - A system command (e.g., `cp`, `mkdir`, `git`) fails unexpectedly.
+  - A script runs under `set -e` and a command exits non-zero.
+- **Suggested fix:** Check the `details` field in the error output for the exact command and line number. Fix the underlying system issue (permissions, disk space, etc.) and retry.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_BASH_ERROR","message":"Bash command failed","details":{"line":42,"command":"cp src dst","exit_code":1},"recovery":null,"timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_UNKNOWN
+
+- **Meaning:** An unclassified error occurred — something went wrong that doesn't fit a more specific category.
+- **When it happens:**
+  - An error path that hasn't been given a specific code yet.
+  - A catch-all for unexpected failure conditions.
+- **Suggested fix:** Check the error message for context. If you see this frequently, please report it so a specific code can be added.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_UNKNOWN","message":"An unknown error occurred","details":null,"recovery":null,"timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## Hub / Repository Errors
+
+### E_HUB_NOT_FOUND
+
+- **Meaning:** The Aether hub (`~/.aether/`) doesn't exist on this machine.
+- **When it happens:**
+  - Aether hasn't been installed yet.
+  - The hub directory was accidentally deleted.
+- **Suggested fix:** Run `npm install -g aether` to install Aether. This creates the hub at `~/.aether/`.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_HUB_NOT_FOUND","message":"Couldn't find the Aether hub. Try: npm install -g aether","details":null,"recovery":"Run: aether install","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_REPO_NOT_INITIALIZED
+
+- **Meaning:** The current repository hasn't been initialized with Aether.
+- **When it happens:**
+  - Running an Aether command in a repo before running `/ant:init`.
+  - The `.aether/` directory or `COLONY_STATE.json` is missing from the current repo.
+- **Suggested fix:** Run `/ant:init` in Claude Code to initialize Aether in this repository.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_REPO_NOT_INITIALIZED","message":"Couldn't find Aether initialization in this repo. Try: run /ant:init first.","details":null,"recovery":"Run /ant:init in this repo first","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+### E_GIT_ERROR
+
+- **Meaning:** A git operation failed.
+- **When it happens:**
+  - `git stash`, `git commit`, `git log`, or another git command returns an error.
+  - The directory isn't a git repository.
+  - There are merge conflicts or a detached HEAD state.
+- **Suggested fix:** Run `git status` to see the current state of your repository. Resolve any conflicts or uncommitted changes, then retry the command.
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_GIT_ERROR","message":"Git operation failed. Try: run git status to check repository state.","details":null,"recovery":"Check git status and resolve conflicts","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## Resource Errors
+
+### E_RESOURCE_NOT_FOUND
+
+- **Meaning:** A runtime resource (e.g., an active session, a worker, a swarm) doesn't exist.
+- **When it happens:**
+  - A command refers to a session ID, worker name, or swarm ID that doesn't exist or has already completed.
+  - Attempting to read or update a resource that hasn't been created yet.
+- **Suggested fix:** Check that the resource was created first. List available resources with the relevant `list` command (e.g., `flag-list`, `swarm-findings-read`).
+- **Example output:**
+  ```json
+  {"ok":false,"error":{"code":"E_RESOURCE_NOT_FOUND","message":"Couldn't find the requested resource. Try: check that it was created first.","details":null,"recovery":"Check that the resource exists and try again","timestamp":"2026-02-19T13:00:00Z"}}
+  ```
+
+---
+
+## For Contributors
+
+### Adding a New Error Code
+
+When you need a new error code, follow this checklist:
+
+1. **Define the constant** in `.aether/utils/error-handler.sh` at the top of the file:
+   ```bash
+   E_MY_NEW_CODE="E_MY_NEW_CODE"
+   ```
+
+2. **Add a recovery function** in `error-handler.sh`:
+   ```bash
+   _recovery_my_new_code() { echo '"Description of how to fix this"'; }
+   ```
+
+3. **Add a case entry** in the `_get_recovery` function in `error-handler.sh`:
+   ```bash
+   "$E_MY_NEW_CODE") _recovery_my_new_code ;;
+   ```
+
+4. **Add a fallback definition** at the top of `aether-utils.sh` (in the fallback constants block):
+   ```bash
+   : "${E_MY_NEW_CODE:=E_MY_NEW_CODE}"
+   ```
+
+5. **Export the constant and function** at the bottom of `error-handler.sh`:
+   ```bash
+   export E_MY_NEW_CODE
+   export -f _recovery_my_new_code
+   ```
+
+6. **Document the code** in this file (`docs/error-codes.md`) following the existing format.
+
+### Naming Convention
+
+- **Prefix:** Always start with `E_`
+- **Case:** SCREAMING_SNAKE_CASE (e.g., `E_FILE_NOT_FOUND`, `E_LOCK_FAILED`)
+- **Be specific:** Prefer `E_FILE_NOT_FOUND` over `E_ERROR` — the code should communicate the failure category
+
+### Category Selection Guide
+
+| Category | Use when... |
+|----------|-------------|
+| File Errors | A file or directory path doesn't exist |
+| Lock Errors | Lock acquisition fails |
+| Tool/Dependency Errors | A required tool or script is missing |
+| JSON/Data Errors | File content is malformed or invalid |
+| Validation Errors | Arguments are wrong or missing |
+| System Errors | Unexpected bash command failure |
+| Hub/Repository Errors | Aether infrastructure is missing or not set up |
+| Resource Errors | A named runtime object doesn't exist |
+
+### Message Style Requirements
+
+Every `json_err` call **must** include a "Try:" suggestion in the message:
+
+```bash
+# Correct — includes Try: suggestion
+json_err "$E_FILE_NOT_FOUND" "Couldn't find flags.json. Try: run flag-add first to create it."
+
+# Wrong — no actionable suggestion
+json_err "$E_FILE_NOT_FOUND" "flags.json not found"
+```
+
+**Tone:** Use plain, friendly language. "Couldn't find..." is better than "File not found". Users are not experts in bash internals.
+
+---
+
+*Last updated: 2026-02-19*

package/{runtime → .aether}/docs/known-issues.md

@@ -23,7 +23,7 @@ Documented issues from Oracle research findings. These are known limitations and
 - `.aether/aether-utils.sh`, `.aether/workers.md`, `.aether/docs/**/*.md`
 - `.claude/commands/ant/**/*.md`, `.claude/commands/st/**/*.md`
 - `.opencode/commands/ant/**/*.md`, `.opencode/agents/**/*.md`
-- `runtime/**/*`, `bin/**/*`
+- `bin/**/*`
 
 **User Data (Never Touch):**
 - `.aether/data/`, `.aether/dreams/`, `.aether/oracle/`
@@ -33,38 +33,42 @@ Documented issues from Oracle research findings. These are known limitations and
 
 ## Critical Issues (Fix Immediately)
 
-### BUG-005: Missing lock release in flag-auto-resolve
+### BUG-005: Missing lock release in flag-auto-resolve — FIXED (Phase 16)
 **Location:** `.aether/aether-utils.sh:1022`
 **Severity:** HIGH
+**Status:** FIXED — Fixed in Phase 16: unified trap pattern (`trap 'release_lock 2>/dev/null || true' EXIT`) applied across all flag commands ensures lock release on all exit paths including jq failure.
 **Symptom:** If jq command fails during flag resolution, lock is never released
 **Impact:** Deadlock on flags.json if jq fails (malformed JSON, disk full, etc.)
-**Workaround:** Restart the colony session if commands hang on flag operations
-**Fix:** Add error handling with lock release before json_err
+**Workaround:** ~~Restart the colony session if commands hang on flag operations~~ — no longer needed
+**Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_flag_auto_resolve_jq_failure_releases_lock
 
-### BUG-011: Missing error handling in flag-auto-resolve jq
+### BUG-011: Missing error handling in flag-auto-resolve jq — FIXED (Phase 16)
 **Location:** `.aether/aether-utils.sh:1022`
 **Severity:** HIGH
+**Status:** FIXED — Fixed in Phase 16: unified trap pattern across all flag commands. See BUG-005.
 **Symptom:** jq failure during auto-resolve not handled
 **Impact:** Combined with BUG-005, causes deadlock
-**Fix:** Add `|| { release_lock; json_err ... }` pattern
+**Fix:** ~~Add `|| { release_lock; json_err ... }` pattern~~ — implemented via EXIT trap
 
 ---
 
 ## Medium Priority Issues
 
-### BUG-002: Missing release_lock in flag-add error path
+### BUG-002: Missing release_lock in flag-add error path — FIXED (Phase 16)
 **Location:** `.aether/aether-utils.sh:814`
 **Severity:** MEDIUM
+**Status:** FIXED — Fixed in Phase 16: trap-based EXIT cleanup (`trap 'release_lock 2>/dev/null || true' EXIT`) ensures lock release on all exit paths including jq failure. Trap is cleared on the success path.
 **Symptom:** If acquire_lock succeeds but jq fails, lock is never released
 **Impact:** Potential deadlock on file operations
-**Fix:** Use trap-based cleanup or ensure release_lock in all exit paths
+**Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_flag_add_jq_failure_releases_lock
 
-### BUG-003: Race condition in backup creation
+### BUG-003: Race condition in backup creation — FIXED (Phase 16)
 **Location:** `.aether/utils/atomic-write.sh:75`
 **Severity:** MEDIUM
+**Status:** FIXED — Backup is now created BEFORE JSON validation in both `atomic_write` and `atomic_write_from_file`. Verified in Phase 16 with regression tests confirming backup contains pre-write content.
 **Symptom:** Backup created AFTER temp file validation but BEFORE atomic move
 **Impact:** If process crashes between validation and backup, inconsistent state
-**Fix:** Create backup BEFORE validation, or use transactional approach
+**Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_atomic_write_backup_before_validate, test_atomic_write_from_file_backup_before_validate
 
 ### BUG-004: Missing error code in flag-acknowledge
 **Location:** `.aether/aether-utils.sh:930`
@@ -123,24 +127,27 @@ Documented issues from Oracle research findings. These are known limitations and
 **Description:** Some `json_err` calls use hardcoded strings instead of constants
 **Pattern:** Commands added early use strings; later commands use constants
 
-### ISSUE-002: Missing exec error handling
+### ISSUE-002: Missing exec error handling — FIXED (Phase 18-02)
 **Location:** `.aether/aether-utils.sh:2132-2144`
 **Severity:** LOW
 **Description:** `model-get` and `model-list` use `exec` without fallback
 **Impact:** If exec fails, script continues to unknown command handler
+**Status:** FIXED — Phase 18-02: subprocess error handling added to model-get and model-list with structured E_* error codes on failure.
 
-### ISSUE-003: Incomplete help command
+### ISSUE-003: Incomplete help command — FIXED (Phase 18-03)
 **Location:** `.aether/aether-utils.sh:106-111`
 **Severity:** LOW
 **Description:** Help command missing newer commands like queen-*, view-state-*, swarm-timing-*
 **Impact:** Users cannot discover all available commands
+**Status:** FIXED — Phase 18-03: help command sections key added with all command groups including Queen Commands, Model Routing, Swarm Operations, and all newer commands.
 
-### ISSUE-004: Template path hardcoded to runtime/
+### ISSUE-004: Template path hardcoded to staging directory — FIXED (Phase 20)
 **Location:** `.aether/aether-utils.sh:2689`
 **Severity:** MEDIUM
-**Description:** queen-init uses runtime/ directory which may not exist in npm installs
-**Impact:** queen-init will fail when Aether is installed as npm package
-**Workaround:** Use git clone instead of npm install
+**Status:** FIXED — Phase 20: stale staging template path removed from queen-init lookup array. Template is now found via hub path (`~/.aether/system/templates/`) or dev repo path (`.aether/templates/`) or legacy hub fallback.
+**Description:** queen-init used a staging directory path that did not exist in npm installs
+**Impact:** ~~queen-init will fail when Aether is installed as npm package~~
+**~~Workaround:~~** ~~Use git clone instead of npm install~~ — no longer needed
 
 ### ISSUE-005: Potential infinite loop in spawn-tree
 **Location:** `.aether/aether-utils.sh:402-448`, `spawn-tree.sh:222-263`
@@ -154,38 +161,45 @@ Documented issues from Oracle research findings. These are known limitations and
 **Description:** Fallback json_err doesn't accept error code parameter
 **Impact:** If error-handler.sh fails to load, error codes are lost
 
-### ISSUE-007: Feature detection race condition
+### ISSUE-007: Feature detection race condition — FIXED (Phase 18-01)
 **Location:** `.aether/aether-utils.sh:33-45`
 **Severity:** LOW
 **Description:** Feature detection runs before error handler fully sourced
+**Status:** FIXED — Phase 18-01 (ARCH-09): feature detection block moved after fallback json_err definition (line 68 -> 81) so all fallback infrastructure available when feature detection runs.
 
 ---
 
 ## Architecture Gaps
 
-### GAP-001: No schema version validation
+### GAP-001: No schema version validation — FIXED (Phase 18-04)
 **Description:** Commands assume state structure without validating version
 **Impact:** Silent failures when state structure changes
+**Status:** FIXED — Phase 18-04: `_migrate_colony_state` added to validate-state colony; auto-migrates pre-3.0 state files to v3.0 (additive only), notifies via W_MIGRATED warning; corrupt state files backed up before error.
 
-### GAP-002: No cleanup for stale spawn-tree entries
+### GAP-002: No cleanup for stale spawn-tree entries — FIXED (Phase 18-01)
 **Description:** spawn-tree.txt grows indefinitely
 **Impact:** File could grow very large over many sessions
+**Status:** FIXED — Phase 18-01: `_rotate_spawn_tree` added to session-init; rotates spawn-tree.txt on each session start with timestamped archives; 5-archive cap; in-place truncation preserves tail -f file handles.
 
-### GAP-003: No retry logic for failed spawns
+### GAP-003: No retry logic for failed spawns — RESOLVED (Phase 18-02)
 **Description:** Task tool calls don't have retry logic
 **Impact:** Transient failures cause build failures
+**Status:** RESOLVED — User decision: fail-fast with rich error context (Phase 18-02). Retry logic adds complexity without clear benefit; subprocess errors now emit structured E_* codes with actionable Try: suggestions, allowing callers to decide on retry strategy.
 
-### GAP-004: Missing queen-* documentation
+### GAP-004: Missing queen-* documentation — FIXED (Phase 18-03)
 **Description:** No docs for queen-init, queen-read, queen-promote
 **Impact:** Users cannot discover wisdom feedback loop
+**Status:** FIXED — Phase 18-03: queen-commands.md created in .aether/docs/; help command sections key added with Queen Commands section listing all three commands with descriptions.
 
-### GAP-005: No validation of queen-read JSON output
+### GAP-005: No validation of queen-read JSON output — FIXED (Phase 18-04)
 **Description:** queen-read builds JSON but doesn't validate before returning
 **Impact:** Could return malformed response
+**Status:** FIXED — Phase 18-04: Two validation gates added to queen-read: Gate 1 validates METADATA JSON before --argjson use; Gate 2 validates assembled result before json_ok. Both emit E_JSON_INVALID with actionable Try: suggestion.
 
-### GAP-006: Missing queen-* command documentation
+### GAP-006: Missing queen-* command documentation — FIXED (Phase 18-03)
 **Description:** Duplicate of GAP-004 - no documentation exists
 **Impact:** Commands are undiscoverable
+**Status:** FIXED — Phase 18-03: See GAP-004.
 
 ### GAP-007: No error code standards documentation
 **Description:** Error codes exist but aren't documented
@@ -195,9 +209,11 @@ Documented issues from Oracle research findings. These are known limitations and
 **Description:** Error handling paths not tested
 **Impact:** Bugs in error handling go undetected
 
-### GAP-009: context-update has no file locking
+### GAP-009: context-update has no file locking — FIXED (Phase 16)
 **Description:** Race condition possible during concurrent context updates
+**Status:** FIXED — Fixed in Phase 16: context-update wraps all 11 action handlers in a single acquire_lock/release_lock pair. Lock is held for the duration of the update and released on both success and error paths via EXIT trap. force-unlock subcommand added for emergency recovery.
 **Impact:** Potential data corruption
+**Regression test:** `tests/bash/test-lock-lifecycle.sh` — test_context_update_acquires_lock, test_force_unlock_clears_locks
 
 ### GAP-010: Missing error code standards documentation
 **Description:** Duplicate of GAP-007
@@ -208,8 +224,8 @@ Documented issues from Oracle research findings. These are known limitations and
 
 | Issue | Workaround |
 |-------|------------|
-| Lock-related deadlocks (BUG-005, BUG-002) | Restart colony session |
-| Template path issue (ISSUE-004) | Use git clone instead of npm |
+| ~~Lock-related deadlocks (BUG-005, BUG-002)~~ | ~~Restart colony session~~ — FIXED in Phase 16 |
+| ~~Template path issue (ISSUE-004)~~ | ~~Use git clone instead of npm~~ — FIXED in Phase 20 |
 | Missing command docs (GAP-004) | Read source code directly |
 
 ---

package/.aether/docs/queen-commands.md

@@ -0,0 +1,97 @@
+# Queen Commands Reference
+
+The queen-* commands manage the QUEEN.md wisdom file — a persistent cross-colony knowledge base that accumulates philosophies, patterns, redirects, stack wisdom, and decrees across sessions.
+
+For the QUEEN.md file format and wisdom feedback loop, see [QUEEN-SYSTEM.md](./QUEEN-SYSTEM.md).
+
+## Commands
+
+### queen-init
+
+**Purpose:** Initialize a new QUEEN.md from the system template.
+
+**Usage:**
+```bash
+bash .aether/aether-utils.sh queen-init
+```
+
+**Returns:** JSON with creation status, file path, and template source.
+
+**Example output:**
+```json
+{"ok":true,"result":{"created":true,"path":".aether/docs/QUEEN.md","source":"~/.aether/system/docs/QUEEN.md.template"}}
+```
+
+**Behavior:**
+- If QUEEN.md already exists, returns `{"created":false}` without overwriting
+- Searches for template in: hub system path, then local .aether/templates/
+- Creates `.aether/docs/` directory if it doesn't exist
+
+---
+
+### queen-read
+
+**Purpose:** Read QUEEN.md wisdom as structured JSON for worker priming.
+
+**Usage:**
+```bash
+bash .aether/aether-utils.sh queen-read
+```
+
+**Returns:** JSON with metadata, wisdom sections, and priming flags.
+
+**Example output:**
+```json
+{"ok":true,"result":{"metadata":{...},"wisdom":{"philosophies":"...","patterns":"...","redirects":"...","stack_wisdom":"...","decrees":"..."},"priming":{"has_philosophies":true,...}}}
+```
+
+**Behavior:**
+- Extracts METADATA JSON block from `<!-- METADATA ... -->` comment
+- Parses each wisdom section (Philosophies, Patterns, Redirects, Stack Wisdom, Decrees)
+- Returns priming flags indicating which sections have content
+- Returns E_JSON_INVALID if METADATA block contains malformed JSON
+- Returns E_FILE_NOT_FOUND if QUEEN.md doesn't exist
+
+---
+
+### queen-promote
+
+**Purpose:** Promote a validated learning to QUEEN.md wisdom.
+
+**Usage:**
+```bash
+bash .aether/aether-utils.sh queen-promote <type> <content> <colony_name>
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| type | Yes | Wisdom category: `philosophy`, `pattern`, `redirect`, `stack`, `decree` |
+| content | Yes | The wisdom text to add |
+| colony_name | Yes | Name of the colony contributing the wisdom |
+
+**Returns:** JSON confirming the promotion with details.
+
+**Behavior:**
+- Appends the wisdom entry to the appropriate section in QUEEN.md
+- Includes attribution (colony name) and timestamp
+- Updates the METADATA block's stats
+
+---
+
+## For Contributors
+
+The queen commands are part of the colony lifecycle:
+
+1. **Colony startup:** `/ant:colonize` calls `queen-init` to ensure QUEEN.md exists
+2. **Worker priming:** `/ant:swarm` calls `queen-read` to inject wisdom into worker prompts
+3. **Colony end:** `/ant:seal` can call `queen-promote` to persist learnings
+
+### Adding a New Queen Command
+
+1. Add the case block in `aether-utils.sh` (alongside existing `queen-*` blocks)
+2. Add it to the flat `commands` array in the `help)` case block
+3. Add it to the "Queen Commands" section in help's `sections` JSON
+4. Update this file with usage documentation
+5. Add tests in `tests/bash/test-aether-utils.sh`

package/.aether/exchange/colony-registry.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<colony-registry xmlns="http://aether.colony/schemas/registry/1.0"
+                 version="1.0.0"
+                 generated_at="2026-02-18T01:48:47Z">
+  <colony id="Remove Aether developing Aether self-reference while preserving findings" status="active" created_at="2026-02-15T15:59:13Z">
+    <name>Remove Aether developing Aether self-reference while preserving findings</name>
+  </colony>
+  <colony id="v1.1 Bug Fixes &amp; Update System Repair" status="active" created_at="unknown">
+    <name>v1.1 Bug Fixes &amp; Update System Repair</name>
+  </colony>
+</colony-registry>

package/{runtime → .aether}/exchange/pheromone-xml.sh

@@ -126,8 +126,9 @@ xml-pheromone-export() {
           active=\"$active\">"
 
         # Content section
+        # Handle both string content (.content = "text") and object content (.content.text = "text")
         local content_text
-        content_text=$(echo "$signal" | jq -r '.content.text // .message // ""')
+        content_text=$(echo "$signal" | jq -r 'if (.content | type) == "string" then .content elif .content.text then .content.text else .message // "" end')
         if [[ -n "$content_text" ]]; then
             xml_output="$xml_output
     <content>

package/.aether/exchange/pheromones.xml

@@ -0,0 +1,87 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<pheromones xmlns="http://aether.colony/schemas/pheromones"
+            xmlns:ph="http://aether.colony/schemas/pheromones"
+            version="1.0.0"
+            generated_at="2026-02-17T23:51:44Z"
+            colony_id="aether-dev">
+  <metadata>
+    <source type="system">aether-pheromone-converter</source>
+    <context>Colony pheromone signals</context>
+  </metadata>
+  <signal id="sig_focus_001"
+          type="FOCUS"
+          priority="normal"
+          source="user"
+          created_at="2026-02-16T10:00:00Z"
+          expires_at="2026-02-17T10:00:00Z"
+          active="true">
+    <content>
+      <text>XML migration and pheromone system implementation</text>
+    </content>
+  </signal>
+  <signal id="sig_redirect_001"
+          type="REDIRECT"
+          priority="high"
+          source="system"
+          created_at="2026-02-16T08:00:00Z"
+          expires_at="2026-03-16T08:00:00Z"
+          active="true">
+    <content>
+      <text>Avoid editing runtime/ directly - edit .aether/ instead</text>
+    </content>
+  </signal>
+  <signal id="sig_feedback_001"
+          type="FEEDBACK"
+          priority="low"
+          source="worker_builder"
+          created_at="2026-02-16T12:00:00Z"
+          active="true">
+    <content>
+      <text>Test coverage is good, continue maintaining 80%+ coverage</text>
+    </content>
+  </signal>
+  <signal id="sig_focus_1771366307000"
+          type="FOCUS"
+          priority="normal"
+          source="user"
+          created_at="2026-02-17T22:11:47Z"
+          expires_at="phase_end"
+          active="true">
+    <content>
+      <text>test area for pheromone unification</text>
+    </content>
+  </signal>
+  <signal id="sig_focus_1771366386000"
+          type="FOCUS"
+          priority="normal"
+          source="user"
+          created_at="2026-02-17T22:13:06Z"
+          expires_at="phase_end"
+          active="true">
+    <content>
+      <text>test area</text>
+    </content>
+  </signal>
+  <signal id="sig_redirect_1771366398000"
+          type="REDIRECT"
+          priority="high"
+          source="user"
+          created_at="2026-02-17T22:13:18Z"
+          expires_at="phase_end"
+          active="true">
+    <content>
+      <text>avoid direct runtime edits</text>
+    </content>
+  </signal>
+  <signal id="sig_feedback_1771366398000"
+          type="FEEDBACK"
+          priority="low"
+          source="user"
+          created_at="2026-02-17T22:13:18Z"
+          expires_at="phase_end"
+          active="true">
+    <content>
+      <text>keep commits small</text>
+    </content>
+  </signal>
+</pheromones>

package/.aether/exchange/queen-wisdom.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<queen-wisdom xmlns="http://aether.colony/schemas/queen-wisdom/1.0"
+               xmlns:qw="http://aether.colony/schemas/queen-wisdom/1.0">
+  <metadata>
+    <version>1.0.0</version>
+    <created>2026-02-18T01:48:47Z</created>
+    <modified>2026-02-18T01:48:47Z</modified>
+    <colony_id></colony_id>
+  </metadata>
+  <philosophies>
+  </philosophies>
+  <patterns>
+  </patterns>
+</queen-wisdom>