aether-colony 5.3.1 → 5.3.3

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

@@ -53,7 +53,6 @@ Do not touch during init:
 - .aether/dreams/ (user notes)
 - .aether/chambers/ (archived colonies)
 - .env* files
-- .claude/settings.json
 - .github/workflows/
 </read_only>
 
@@ -168,7 +167,7 @@ Strip `(Colony: ...)` suffixes using sed. If grep finds nothing, variables remai
 Display a brief header:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   A E T H E R   C O L O N Y   I N I T
+🥚 A E T H E R   C O L O N Y   I N I T
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -482,30 +481,48 @@ Display "Import skipped. Starting fresh colony." and proceed to Step 8.
 **If xml_import_available is false (no chambers, no XML, or no xmllint):**
 
 Skip silently -- proceed directly to Step 8 without any mention of import (per D-11).
+### Step 7.5: Install Clash Detection Hook
+
+If `.aether/utils/clash-detect.sh` exists, run:
+
+```bash
+bash .aether/aether-utils.sh clash-setup --install 2>/dev/null || true
+```
+
+This installs the PreToolUse hook that prevents conflicting edits across worktrees.
+Non-blocking — if it fails, init continues normally.
+
+Also configure the merge driver for package-lock.json:
+
+```bash
+git config merge.lockfile.driver "bash .aether/utils/merge-driver-lockfile.sh %O %A %B" 2>/dev/null || true
+git config merge.lockfile.name "npm lockfile auto-merge" 2>/dev/null || true
+```
+
 ### Step 8: Display Result
 
 Display the success header and result block:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   A E T H E R   C O L O N Y
+🥚 A E T H E R   C O L O N Y
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Queen has set the colony's intention
+👑 Queen has set the colony's intention
 
    "{approved_intent}"
 
-   Colony Status: READY
+   🟢 Colony Status: READY
 
-{If re-init: "   Mode: Re-init (charter updated, state preserved)"}
-{If fresh and seeded_count > 0: "   Hive wisdom: {seeded_count} cross-colony pattern(s) seeded into QUEEN.md"}
+{If re-init: "   🔄 Mode: Re-init (charter updated, state preserved)"}
+{If fresh and seeded_count > 0: "   🧠 Hive wisdom: {seeded_count} cross-colony pattern(s) seeded into QUEEN.md"}
 
-State persisted -- safe to /clear, then run /ant:plan
+💾 State persisted -- safe to /clear, then run /ant:plan
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   Next Up
+🐜 Next Up
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   /ant:plan                 Generate execution plan
-   /ant:status               Check colony state
-   /ant:focus                Set initial focus
+   /ant:plan                 📊 Generate execution plan
+   /ant:status               📋 Check colony state
+   /ant:focus                🎯 Set initial focus
 ```

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

@@ -283,6 +283,41 @@ Describe the research topic in detail. The more specific, the better the Oracle'
 
 (The user will type their topic via the "Other" free-text option.)
 
+**Question 1.5: Research Brief — Formulate and Approve**
+
+Take the user's raw topic (from `$normalized_args` or Question 1) and reformulate it into a structured research brief. The user may have typed casual natural language — your job is to sharpen it into a clear, well-scoped research prompt that will produce better results.
+
+Display the brief for approval:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🔮 R E S E A R C H   B R I E F
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Topic:** {reformulated topic — clear, specific, actionable}
+**Core Question:** {the single most important question this research should answer}
+**Context:** {what we already know from the codebase or user input}
+**Success Criteria:** {what a good answer looks like — what would make this research useful}
+```
+
+Guidelines for formulation:
+- Turn vague topics into specific ones ("auth stuff" → "Authentication architecture: session-based vs token-based for this Node.js API")
+- Add codebase context if relevant (tech stack, existing patterns)
+- Make the core question answerable — not open-ended philosophy
+- Keep success criteria concrete ("A recommendation with trade-offs" not "understand everything")
+
+Then ask the user to approve:
+
+```
+Does this capture what you're looking for? (approve / edit)
+```
+
+- If the user approves: use the reformulated topic as the research topic going forward
+- If the user edits: incorporate their changes, display the updated brief, and ask again
+- Max 2 revision rounds (same as init). After 2, ask for final approval or cancel.
+
+The approved **Topic** from the brief becomes the topic used in all subsequent steps (state.json, plan.json, research-plan.md).
+
 **Question 2: Research Template**
 
 ```

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

@@ -85,7 +85,7 @@ Extract from COLONY_STATE.json:
 Display audit header:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   C O L O N Y   A U D I T
+🔍 C O L O N Y   A U D I T
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Goal: {goal}
@@ -507,7 +507,7 @@ Display the formatted audit summary:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   A U D I T   R E S U L T S
+📋 A U D I T   R E S U L T S
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Goal: {goal}

package/.opencode/commands/ant/run.md

@@ -55,7 +55,7 @@ If `--dry-run`: read COLONY_STATE.json, list remaining incomplete phases
 (applying `--max-phases` cap), display the plan, then stop without executing.
 
 ```
-━━━ A U T O P I L O T   P R E V I E W ━━━
+━━━ 🤖 A U T O P I L O T   P R E V I E W ━━━
 Goal: {goal} | Current: Phase {N} | Remaining: {count} | Max: {max or "all"}
 
   Phase {id}: {name} ({task_count} tasks) -> build -> continue -> advance
@@ -193,7 +193,7 @@ If `--continue` flag was passed: skip this check entirely (user dismissed replan
 If `result.should_replan == true`: **PAUSE** with replan suggestion banner:
 
 ```
-━━━ R E P L A N   S U G G E S T E D ━━━
+━━━ 🔄 R E P L A N   S U G G E S T E D ━━━
 Phases auto-completed: {N} | Learnings accumulated: {learnings_since_last}
 
 The colony has completed {N} phases since the last plan review.
@@ -211,7 +211,7 @@ If `result.should_replan == false`: proceed normally (no pause).
 ### Step 6: Final Summary
 
 ```
-━━━ A U T O P I L O T   C O M P L E T E ━━━
+━━━ ✅ A U T O P I L O T   C O M P L E T E ━━━
 Phases completed: {N} | Elapsed: {Xm Ys} | Now at: Phase {current}
 
 {all complete}  -> Colony goal achieved! Run /ant:seal

package/CHANGELOG.md

@@ -690,3 +690,86 @@ The following entries are automatically generated by the colony during work phas
 - **Files:** `aether-utils.sh`, `utils/hive.sh`, `utils/learning.sh`, `tests/`
 - **Decisions:** Colony sealed at Crowned Anthill; hardened ~40 json_ok sites + checkpointing + hive null safety
 - **What Worked:** 5 phases completed; 9 instincts created; 4 hive-eligible
+
+## 2026-03-31
+
+### Phase 0 — Plan 01
+
+- **Files:** `build-complete.md`, `build.yaml`, `build.md`
+- **Decisions:** Add Stage Audit Gate to build orchestrators
+- **What Worked:** Pre-synthesis verification gate ensures all stages complete
+
+### Phase 3 — Plan 01
+
+- **What Worked:** lint:sync clean; lint clean; 524 tests pass
+
+### Phase 0 — Plan 00
+
+- **Files:** `build-complete.md`, `build.yaml`, `update-transaction.test.js`
+- **Decisions:** Colony sealed at Crowned Anthill; Enforce non-skippable build playbook execution and verify exchange fix
+- **What Worked:** 3 phases completed; Colony wisdom promoted to QUEEN.md
+
+### Phase 1 — Plan 01
+
+- **Files:** `build-complete.md`, `state-contract-design.md`
+- **Decisions:** Deleted wrong test file; Fixed step numbering; Added DATA_DIR exception clause
+- **What Worked:** Swarm parallel audit; Pre-existing quality issues logged
+
+## 2026-04-01
+
+### Phase 2 — Plan 01
+
+- **Files:** `trust-scoring.sh`, `event-bus.sh`, `aether-utils.sh`
+- **Decisions:** Stateless calculation module; JSONL event bus with file locking
+- **What Worked:** Parallel builders; Self-registration pattern
+
+### Phase 3 — Plan 01
+
+- **Files:** `instinct-store.sh`, `graph.sh`, `learning.sh`, `aether-utils.sh`
+- **Decisions:** Standalone instinct storage; jq graph traversal; Trust-scored observations
+- **What Worked:** Additive parallel modification
+
+### Phase 4 — Plan 01
+
+- **Files:** `nurse.sh`, `herald.sh`, `librarian.sh`, `critic.sh`, `sentinel.sh`, `janitor.sh`, `archivist.sh`, `scribe.sh`, `orchestrator.sh`
+- **Decisions:** 8 curation ants; curation-run orchestrator; Sentinel-first execution order
+- **What Worked:** Parallel core/ops builders; Orchestrator integration
+
+### Phase 5 — Plan 01
+
+- **Files:** `consolidation.sh`, `consolidation-seal.sh`, `test-e2e-pipeline.sh`
+- **Decisions:** Lightweight phase-end; Full seal consolidation; E2E integration test
+
+### Phase 6 — Plan 01
+
+- **Files:** `structural-learning-stack.md`, `CLAUDE.md`
+- **Decisions:** Architecture documentation; Updated component counts; Full test sweep
+
+### Phase 0 — Plan 00
+
+- **Files:** `trust-scoring.sh`, `event-bus.sh`, `instinct-store.sh`, `graph.sh`, `consolidation.sh`, `curation-ants`
+- **Decisions:** Colony sealed at Crowned Anthill; Structural Learning Stack complete
+- **What Worked:** 6 phases completed; Colony wisdom promoted to QUEEN.md
+
+### Phase 0 — Plan 01
+
+- **Files:** `go.mod`, `pkg/storage/storage.go`, `pkg/storage/storage_test.go`
+- **Decisions:** Go module at github.com/aether-colony/aether; atomic writes via temp+rename; per-path RWMutex for concurrent safety
+- **What Worked:** Parallel builders for independent packages; TDD with race detector
+- **Requirements:** go build, test, vet pass;91.2% coverage;524 npm tests unaffected addressed
+
+### Phase 0 — Plan 02
+
+- **Files:** `.aether/utils/trust-scoring.sh`, `.aether/utils/event-bus.sh`
+
+### Phase 3 — Plan 03
+
+- **Files:** `learning.sh`, `instinct-store.sh`, `graph.sh`, `test-instinct-store.sh`
+- **Decisions:** Standalone instinct storage; Backward-compatible trust score migration; jq graph layer for instinct relationships
+- **What Worked:** Trust score integration with learning-observe; Full instinct schema with provenance; Graph link/neighbors/reach/cluster
+
+### Phase 0 — Plan 00
+
+- **Files:** `learning.sh`, `instinct-store.sh`, `graph.sh`, `test-instinct-store.sh`, `trust-scoring.sh`, `event-bus.sh`
+- **Decisions:** Colony sealed at Crowned Anthill; Structural Learning Stack verified
+- **What Worked:** 3 phases completed; Colony wisdom promoted to QUEEN.md

package/README.md

@@ -1,32 +1,27 @@
 <div align="center">
 
-<br>
-
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="./AetherLogo.png" />
-  <source media="(prefers-color-scheme: light)" srcset="./AetherLogo.png" />
-  <img src="./AetherLogo.png" alt="Aether" width="240" />
-</picture>
-
-<br>
+<img src="./AetherBanner.png" alt="Aether" width="100%" />
 
 # Aether
 
-### Artificial Ecology for Thought and Emergent Reasoning
+**Artificial Ecology for Thought and Emergent Reasoning**
 
 <br>
 
-[![npm](https://img.shields.io/npm/v/aether-colony?style=for-the-badge&logo=npm&logoColor=white&label=npm&color=7B3FE4)](https://www.npmjs.com/package/aether-colony)
-[![downloads](https://img.shields.io/npm/dw/aether-colony?style=for-the-badge&logo=npm&logoColor=white&color=333333)](https://www.npmjs.com/package/aether-colony)
-[![license](https://img.shields.io/github/license/calcosmic/Aether?style=for-the-badge&color=333333)](LICENSE)
-[![stars](https://img.shields.io/github/stars/calcosmic/Aether?style=for-the-badge&logo=github&logoColor=white&color=333333)](https://github.com/calcosmic/Aether/stargazers)
-[![sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?style=for-the-badge&logo=github-sponsors&logoColor=white)](https://github.com/sponsors/calcosmic)
-
-<br>
-
-Multi-agent AI development for **Claude Code** and **OpenCode**.
-<br>
-Spawn 24 specialists that self-organize around your goal using pheromone signals.
+[![npm version](https://img.shields.io/npm/v/aether-colony.svg?style=flat-square)](https://www.npmjs.com/package/aether-colony?utm_source=github&utm_medium=readme&utm_campaign=aether)
+[![npm downloads](https://img.shields.io/npm/dw/aether-colony.svg?style=flat-square)](https://www.npmjs.com/package/aether-colony?utm_source=github&utm_medium=readme&utm_campaign=aether)
+[![License: MIT](https://img.shields.io/github/license/calcosmic/Aether.svg?style=flat-square)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/calcosmic/Aether.svg?style=flat-square)](https://github.com/calcosmic/Aether/stargazers)
+[![Sponsor](https://img.shields.io/badge/Sponsor-GitHub-%23ea4aaa.svg?style=flat-square&logo=github)](https://github.com/sponsors/calcosmic?utm_source=github&utm_medium=readme&utm_campaign=aether)
+
+[![weekly downloads](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/calcosmic/Aether/main/docs/badges/weekly-downloads.json&style=flat-square)](https://www.npmjs.com/package/aether-colony?utm_source=github&utm_medium=readme&utm_campaign=aether)
+[![monthly downloads](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/calcosmic/Aether/main/docs/badges/monthly-downloads.json&style=flat-square)](https://www.npmjs.com/package/aether-colony?utm_source=github&utm_medium=readme&utm_campaign=aether)
+[![total downloads](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/calcosmic/Aether/main/docs/badges/total-downloads.json&style=flat-square)](https://www.npmjs.com/package/aether-colony?utm_source=github&utm_medium=readme&utm_campaign=aether)
+[![bundle size](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/calcosmic/Aether/main/docs/badges/bundle-size.json&style=flat-square)](https://www.npmjs.com/package/aether-colony?utm_source=github&utm_medium=readme&utm_campaign=aether)
+![test count](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/calcosmic/Aether/main/docs/badges/test-count.json&style=flat-square)
+![commands](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/calcosmic/Aether/main/docs/badges/commands.json&style=flat-square)
+![agents](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/calcosmic/Aether/main/docs/badges/agents.json&style=flat-square)
+[![colony version](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/calcosmic/Aether/main/docs/badges/colony-version.json&style=flat-square)](https://github.com/calcosmic/Aether/releases)
 
 <br>
 
@@ -36,34 +31,36 @@ $ npx aether-colony
 
 <br>
 
-*The whole is greater than the sum of its ants.*
+*The whole is greater than the sum of its ants.* 🐜
 
 <br>
 
+[![🐜 aetherantcolony.com](https://img.shields.io/badge/%F0%9F%90%9C_aetherantcolony.com-7B3FE4?style=for-the-badge&logoColor=white)](https://aetherantcolony.com?utm_source=github&utm_medium=readme&utm_campaign=aether)
+
 </div>
 
 ---
 
-## The Problem
+## Why Aether
 
-AI coding assistants work sequentially — one agent does everything: research, code, test, review. When it hits something complex, it either guesses or asks you. There's no specialization, no parallel work, no memory across sessions.
+Every AI coding tool now has "agents." Most of them are the same thing repackaged — a loop that plans, executes, and checks. That's not a colony. That's one ant doing laps.
 
-## The Solution
+Aether is different because it's modeled on how **real ant colonies work**: no central brain, no single agent trying to be everything. Instead, 24 specialized workers self-organize around your goal. A Builder writes code. When it hits something unfamiliar, it doesn't guess — it spawns a Scout to research. When code lands, a Watcher spawns to verify. A Tracker hunts bugs. An Archaeologist digs through git history. They work in parallel, in waves, across phases.
 
-Aether brings **ant colony intelligence** to AI-assisted development. Instead of one AI doing everything, you get a colony of specialists that self-organize around your goal.
+**What actually makes this different:**
 
-Workers spawn workers dynamically (max depth 3, max 10 per phase). When a Builder hits something complex, it spawns a Scout to research. When code is written, a Watcher spawns to verify. The colony adapts to the problem.
+🐜 **Pheromone signals, not prompt engineering.** You steer the colony the way a queen steers ants — with signals, not instructions. Drop a FOCUS signal on "security" and every worker weighs it. Drop a REDIRECT on "no raw SQL" and it becomes a hard constraint. The colony adapts without you rewriting prompts.
 
-You steer the colony with **pheromone signals**, not micromanagement:
+🐜 **Memory that compounds.** Learnings from one build become instincts for the next. Instincts promote to QUEEN.md wisdom. High-confidence wisdom flows to the Hive Brain and crosses into other projects on your machine. Your colonies get smarter over time.
+
+🐜 **Built to be fun.** You set a goal, the colony builds it. You steer with signals, not micromanagement. You watch workers spawn workers. You seal the colony when it's done and start a new one. It feels like tending a garden, not writing tickets.
 
 ```
-/ant:focus "security"              # "Pay attention here"
-/ant:redirect "no jQuery"          # "Don't do this" (hard constraint)
-/ant:feedback "prefer composition" # "Adjust based on this"
+/ant:focus "security"              # 🐜 "Pay attention here"
+/ant:redirect "no jQuery"          # 🐜 "Don't do this"
+/ant:feedback "prefer composition" # 🐜 "Adjust based on this"
 ```
 
-The colony **remembers**. Wisdom, learnings, and instincts persist across sessions. The Hive Brain shares knowledge across colonies on your machine.
-
 ## Quick Start
 
 ```bash
@@ -231,14 +228,14 @@ Five commands from zero to shipped.
 
 ## Works With
 
-- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** — 45 slash commands + 24 agent definitions
-- **[OpenCode](https://github.com/opencode-ai/opencode)** — 45 slash commands + agent definitions
+- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code?utm_source=github&utm_medium=readme&utm_campaign=aether)** — 45 slash commands + 24 agent definitions
+- **[OpenCode](https://github.com/opencode-ai/opencode?utm_source=github&utm_medium=readme&utm_campaign=aether)** — 45 slash commands + agent definitions
 
 ## Support
 
 If Aether has been useful to you:
 
-**[Sponsor on GitHub](https://github.com/sponsors/calcosmic)**
+**[Sponsor on GitHub](https://github.com/sponsors/calcosmic?utm_source=github&utm_medium=readme&utm_campaign=aether)**
 
 <details>
 <summary>Crypto</summary>
@@ -250,7 +247,7 @@ If Aether has been useful to you:
 
 </details>
 
-[PayPal](https://www.paypal.com/ncp/payment/RENG7ZMW5F59L) · [Buy Me a Coffee](https://buymeacoffee.com/music5y)
+[PayPal](https://www.paypal.com/ncp/payment/RENG7ZMW5F59L?utm_source=github&utm_medium=readme&utm_campaign=aether) · [Buy Me a Coffee](https://buymeacoffee.com/music5y?utm_source=github&utm_medium=readme&utm_campaign=aether)
 
 ## License
 

package/bin/lib/update-transaction.js

@@ -172,8 +172,9 @@ class UpdateTransaction {
 
     // Directories to exclude from sync (user data, local state, and separately-synced dirs)
     // v4.0: archive and chambers added — these are private and must not sync to target repos
-    // v6.0: oracle, midden, exchange added for complete user data protection
-    this.EXCLUDE_DIRS = ['data', 'dreams', 'oracle', 'midden', 'checkpoints', 'locks', 'temp', 'agents', 'commands', 'rules', 'archive', 'chambers', 'exchange'];
+    // v6.0: oracle, midden added for complete user data protection
+    // v7.0: exchange removed from exclusion — .sh scripts must distribute; .xml/.json data excluded by file extension
+    this.EXCLUDE_DIRS = ['data', 'dreams', 'oracle', 'midden', 'checkpoints', 'locks', 'temp', 'agents', 'commands', 'rules', 'archive', 'chambers'];
 
     // Files to exclude from sync (user wisdom, protected files)
     this.EXCLUDE_FILES = ['QUEEN.md'];
@@ -192,7 +193,6 @@ class UpdateTransaction {
       'temp',
       'archive',
       'chambers',
-      'exchange',
     ]);
     this.managedPrefixes = [
       '.claude/commands/ant',
@@ -792,6 +792,11 @@ class UpdateTransaction {
     if (this.EXCLUDE_FILES.includes(basename)) {
       return true;
     }
+    // Protect exchange data files — only .sh scripts should distribute
+    // Only filter files (not directories), so the exchange dir itself is traversed
+    if (parts.includes('exchange') && !basename.endsWith('.sh') && !relPath.endsWith('exchange')) {
+      return true;
+    }
     return false;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aether-colony",
-  "version": "5.3.1",
+  "version": "5.3.3",
   "description": "Multi-agent system using ant colony intelligence for Claude Code and OpenCode — workers self-organize via pheromone signals",
   "bin": {
     "aether": "bin/cli.js",

package/.aether/agents/aether-ambassador.md

@@ -1,140 +0,0 @@
----
-name: aether-ambassador
-description: "Use this agent for third-party API integration, SDK setup, and external service connectivity. The ambassador bridges your code with external systems."
----
-
-You are **🔌 Ambassador Ant** in the Aether Colony. You bridge internal systems with external services, negotiating connections like a diplomat between colonies.
-
-## Activity Logging
-
-Log progress as you work:
-```bash
-bash .aether/aether-utils.sh activity-log "ACTION" "{your_name} (Ambassador)" "description"
-```
-
-Actions: RESEARCH, CONNECTED, TESTED, DOCUMENTED, ERROR
-
-## Your Role
-
-As Ambassador, you:
-1. Research external APIs thoroughly
-2. Design integration patterns
-3. Implement robust connections
-4. Test error scenarios
-5. Document for colony use
-
-## When to Bridge
-
-- New external API needed
-- API version migration
-- Webhook integrations
-- SDK implementation
-- OAuth/Auth setup
-- Rate limiting implementation
-
-## Integration Patterns
-
-- **Client Wrapper**: Abstract API complexity
-- **Circuit Breaker**: Handle service failures
-- **Retry with Backoff**: Handle transient errors
-- **Caching**: Reduce API calls
-- **Webhook Handlers**: Receive async notifications
-- **Queue Integration**: Async processing
-
-## Error Handling
-
-- **Transient errors**: Retry with exponential backoff
-- **Auth errors**: Refresh tokens, then retry
-- **Rate limits**: Queue and retry later
-- **Timeout**: Set reasonable timeouts
-- **Validation errors**: Parse and return meaningful errors
-
-## Security Considerations
-
-- Store API keys securely (env vars, not code)
-- Use HTTPS always
-- Validate SSL certificates
-- Implement request signing if needed
-- Log securely (no secrets in logs)
-
-## Output Format
-
-```json
-{
-  "ant_name": "{your name}",
-  "caste": "ambassador",
-  "status": "completed" | "failed" | "blocked",
-  "summary": "What you accomplished",
-  "endpoints_integrated": [],
-  "authentication_method": "",
-  "rate_limits_handled": true,
-  "error_scenarios_covered": [],
-  "documentation_pages": 0,
-  "tests_written": [],
-  "blockers": []
-}
-```
-
-<failure_modes>
-## Failure Handling
-
-**Tiered severity — never fail silently.**
-
-### Minor Failures (retry silently, max 2 attempts)
-- **API endpoint returns unexpected format**: Parse what was received, log the actual response structure, retry with an adjusted request or parsing approach
-- **SDK method not found**: Check library version in package manifest, try alternate method name from SDK changelog or documentation
-
-### Major Failures (STOP immediately — do not proceed)
-- **API key or secret would be written to a tracked file**: STOP immediately. Do not write. Document the env var name needed and instruct the user to set it. Never log, echo, or commit secrets.
-- **Authentication failure after 2 retries**: STOP. Likely invalid or expired credentials — do not keep retrying. Escalate with auth error details and instruct user to verify credentials.
-- **2 retries exhausted on minor failure**: Promote to major. STOP and escalate.
-
-### Escalation Format
-When escalating, always provide:
-1. **What failed**: Specific endpoint, SDK method, or auth step — include the error code and message
-2. **Options** (2-3 with trade-offs): e.g., "Try alternate auth method / Use mock/stub for now / Surface to user for credential refresh"
-3. **Recommendation**: Which option and why
-</failure_modes>
-
-<success_criteria>
-## Success Verification
-
-**Ambassador self-verifies. Before reporting integration complete:**
-
-1. Verify integration connects successfully — make a real test API call (to a safe, read-only endpoint if possible):
-   ```bash
-   {test_command_or_curl}  # must return HTTP 2xx
-   ```
-2. Verify error handling covers the three core scenarios:
-   - Timeout: client has a configured timeout and catches it
-   - Auth failure: 401/403 is caught and surfaces a meaningful message (not a raw stack trace)
-   - Rate limit: 429 is caught and has retry/backoff behavior
-3. Verify no secrets appear in tracked files:
-   ```bash
-   grep -r "API_KEY\|SECRET\|TOKEN" {integration_files} --include="*.js" --include="*.ts"
-   ```
-   Result must show only env var references (e.g., `process.env.API_KEY`), not literal values.
-
-### Report Format
-```
-endpoints_integrated: [list]
-test_call_result: "HTTP 200 — connected"
-error_scenarios: [timeout, auth, rate_limit — each covered: true/false]
-secrets_check: "no literals in tracked files"
-```
-</success_criteria>
-
-<read_only>
-## Boundary Declarations
-
-### Global Protected Paths (never write to these)
-- `.aether/dreams/` — Dream journal; user's private notes
-- `.env*` — Environment secrets (never write API keys here — instruct user)
-- `.opencode/settings.json` — Hook configuration
-- `.github/workflows/` — CI configuration
-
-### Ambassador-Specific Boundaries
-- **Do not write API keys or secrets to any tracked file** — document the env var name needed and instruct the user to set it in their environment
-- **Do not modify `.env` files** — Ambassador documents what env vars are needed; the user sets them
-- **Do not modify unrelated source files** — integration code only; stay within the integration boundary
-</read_only>