myceliumail 1.0.2 → 1.0.3

package/desktop/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "myceliumail-desktop",
+    "version": "0.1.0",
+    "description": "Myceliumail Desktop - Agent Messaging Client",
+    "main": "main.js",
+    "scripts": {
+        "start": "electron .",
+        "build": "electron-builder --mac",
+        "build:all": "electron-builder --mac --win --linux"
+    },
+    "author": "Treebird",
+    "license": "MIT",
+    "devDependencies": {
+        "electron": "^28.0.0",
+        "electron-builder": "^24.9.1"
+    },
+    "build": {
+        "appId": "com.treebird.myceliumail",
+        "productName": "Myceliumail",
+        "mac": {
+            "category": "public.app-category.productivity",
+            "icon": "assets/icon.icns"
+        },
+        "win": {
+            "icon": "assets/icon.ico"
+        },
+        "linux": {
+            "icon": "assets/icon.png"
+        },
+        "files": [
+            "main.js",
+            "preload.js",
+            "assets/**/*"
+        ],
+        "extraResources": [
+            {
+                "from": "../dist",
+                "to": "cli",
+                "filter": [
+                    "**/*"
+                ]
+            }
+        ]
+    },
+    "dependencies": {
+        "@supabase/supabase-js": "^2.88.0"
+    }
+}

package/desktop/preload.js

@@ -0,0 +1,11 @@
+// Preload script - runs before web page loads
+// Can expose Node.js APIs safely to the renderer
+
+const { contextBridge, ipcRenderer } = require('electron');
+
+// Expose protected methods to the renderer process
+contextBridge.exposeInMainWorld('myceliumail', {
+    // Can add IPC methods here if needed
+    platform: process.platform,
+    version: process.env.npm_package_version || '0.1.0'
+});

package/dist/bin/myceliumail.js

@@ -12,6 +12,7 @@ import { loadConfig } from '../lib/config.js';
 import { createKeygenCommand } from '../commands/keygen.js';
 import { createKeysCommand } from '../commands/keys.js';
 import { createKeyImportCommand } from '../commands/key-import.js';
+import { createKeyAnnounceCommand } from '../commands/key-announce.js';
 import { createSendCommand } from '../commands/send.js';
 import { createInboxCommand } from '../commands/inbox.js';
 import { createReadCommand } from '../commands/read.js';
@@ -33,6 +34,7 @@ Config: ~/.myceliumail/config.json
 program.addCommand(createKeygenCommand());
 program.addCommand(createKeysCommand());
 program.addCommand(createKeyImportCommand());
+program.addCommand(createKeyAnnounceCommand());
 program.addCommand(createSendCommand());
 program.addCommand(createInboxCommand());
 program.addCommand(createReadCommand());

package/dist/bin/myceliumail.js.map

@@ -1 +1 @@
-{"version":3,"file":"myceliumail.js","sourceRoot":"","sources":["../../src/bin/myceliumail.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AAEH,4CAA4C;AAC5C,OAAO,eAAe,CAAC;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,kBAAkB;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACF,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,+DAA+D,CAAC;KAC5E,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,6BAA6B;AAC7B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;AAC5B,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE;iBACZ,MAAM,CAAC,OAAO;;CAE9B,CAAC,CAAC;AAEH,oBAAoB;AACpB,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;AAC1C,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAC,CAAC;AAC7C,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;AACzC,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAC,CAAC;AAC7C,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAC,CAAC;AAC7C,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;AAEzC,gBAAgB;AAChB,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"myceliumail.js","sourceRoot":"","sources":["../../src/bin/myceliumail.ts"],"names":[],"mappings":";AAEA;;;;GAIG;AAEH,4CAA4C;AAC5C,OAAO,eAAe,CAAC;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,kBAAkB;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACF,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,+DAA+D,CAAC;KAC5E,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,6BAA6B;AAC7B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;AAC5B,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE;iBACZ,MAAM,CAAC,OAAO;;CAE9B,CAAC,CAAC;AAEH,oBAAoB;AACpB,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;AAC1C,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAC,CAAC;AAC7C,OAAO,CAAC,UAAU,CAAC,wBAAwB,EAAE,CAAC,CAAC;AAC/C,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;AACzC,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;AACxC,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAC,CAAC;AAC7C,OAAO,CAAC,UAAU,CAAC,sBAAsB,EAAE,CAAC,CAAC;AAC7C,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;AAEzC,gBAAgB;AAChB,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/commands/key-announce.d.ts

@@ -0,0 +1,6 @@
+/**
+ * key-announce command - Publish your public key to Supabase
+ */
+import { Command } from 'commander';
+export declare function createKeyAnnounceCommand(): Command;
+//# sourceMappingURL=key-announce.d.ts.map

package/dist/commands/key-announce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-announce.d.ts","sourceRoot":"","sources":["../../src/commands/key-announce.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,wBAAwB,IAAI,OAAO,CA6DlD"}

package/dist/commands/key-announce.js

@@ -0,0 +1,63 @@
+/**
+ * key-announce command - Publish your public key to Supabase
+ */
+import { Command } from 'commander';
+import { loadConfig, hasSupabaseConfig } from '../lib/config.js';
+import { hasKeyPair, loadKeyPair, getPublicKeyBase64 } from '../lib/crypto.js';
+export function createKeyAnnounceCommand() {
+    return new Command('key-announce')
+        .description('Publish your public key to the network')
+        .action(async () => {
+        const config = loadConfig();
+        const agentId = config.agentId;
+        // Check for keypair
+        if (!hasKeyPair(agentId)) {
+            console.error(`❌ No keypair found for ${agentId}`);
+            console.log('   Run: mycmail keygen');
+            process.exit(1);
+        }
+        // Check for Supabase
+        if (!hasSupabaseConfig(config)) {
+            console.error('❌ Supabase not configured');
+            console.log('   Set supabase_url and supabase_key in ~/.myceliumail/config.json');
+            process.exit(1);
+        }
+        const keyPair = loadKeyPair(agentId);
+        if (!keyPair) {
+            console.error('❌ Failed to load keypair');
+            process.exit(1);
+        }
+        const publicKey = getPublicKeyBase64(keyPair);
+        try {
+            // Make direct Supabase request
+            const url = `${config.supabaseUrl}/rest/v1/agent_keys`;
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'apikey': config.supabaseKey,
+                    'Authorization': `Bearer ${config.supabaseKey}`,
+                    'Prefer': 'resolution=merge-duplicates',
+                },
+                body: JSON.stringify({
+                    agent_id: agentId,
+                    public_key: publicKey,
+                    updated_at: new Date().toISOString(),
+                }),
+            });
+            if (!response.ok) {
+                const error = await response.text();
+                throw new Error(error);
+            }
+            console.log('📢 Public key announced successfully!\n');
+            console.log(`Agent ID: ${agentId}`);
+            console.log(`Public Key: ${publicKey}`);
+            console.log('\n✅ Other agents can now send you encrypted messages');
+        }
+        catch (error) {
+            console.error('❌ Failed to announce key:', error);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=key-announce.js.map

package/dist/commands/key-announce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-announce.js","sourceRoot":"","sources":["../../src/commands/key-announce.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE/E,MAAM,UAAU,wBAAwB;IACpC,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC;SAC7B,WAAW,CAAC,wCAAwC,CAAC;SACrD,MAAM,CAAC,KAAK,IAAI,EAAE;QACf,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAE/B,oBAAoB;QACpB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,KAAK,CAAC,0BAA0B,OAAO,EAAE,CAAC,CAAC;YACnD,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;YACtC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;QAED,qBAAqB;QACrB,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,OAAO,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;YAC3C,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;YAClF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;QAED,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;YAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;QAED,MAAM,SAAS,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAE9C,IAAI,CAAC;YACD,+BAA+B;YAC/B,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,WAAW,qBAAqB,CAAC;YACvD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC9B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACL,cAAc,EAAE,kBAAkB;oBAClC,QAAQ,EAAE,MAAM,CAAC,WAAY;oBAC7B,eAAe,EAAE,UAAU,MAAM,CAAC,WAAW,EAAE;oBAC/C,QAAQ,EAAE,6BAA6B;iBAC1C;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACjB,QAAQ,EAAE,OAAO;oBACjB,UAAU,EAAE,SAAS;oBACrB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACvC,CAAC;aACL,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACf,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;gBACpC,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC;YAC3B,CAAC;YAED,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;YACvD,OAAO,CAAC,GAAG,CAAC,aAAa,OAAO,EAAE,CAAC,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,eAAe,SAAS,EAAE,CAAC,CAAC;YACxC,OAAO,CAAC,GAAG,CAAC,sDAAsD,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,2BAA2B,EAAE,KAAK,CAAC,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACL,CAAC,CAAC,CAAC;AACX,CAAC"}

package/docs/20251215_Treebird-Ecosystem_Knowledge-Base_v2.md

@@ -0,0 +1,292 @@
+# Treebird Ecosystem - Knowledge Base v2
+
+**Last Updated:** 2025-12-15
+**Supersedes:** v1 (Spidersan-focused)
+
+---
+
+## The Big Picture
+
+> "The forest is more than a collection of trees. It's a network—roots intertwined, mycelium connecting, birds carrying seeds between canopies. Each tree is productive alone, but the forest thrives because they coordinate."
+
+**Treebird makes the forest.**
+
+In the Treebird metaphor:
+- **Code is the tree** — The structure being built
+- **AI agents are the birds** — Mobile, productive, needing coordination
+- **Mycelium is the communication layer** — Underground network sharing nutrients (context) and signals (messages)
+
+---
+
+## Origin Story
+
+The ecosystem emerged from Recovery Tree development. Treebird (the human orchestrator) was building a digital recovery platform and kept drowning in branch merge chaos with Supabase + GitHub + Vercel. Multiple AI agents working productively but creating coordination nightmares.
+
+The insight: **We built tools for humans to collaborate. We never built tools for AI agents to collaborate.**
+
+The solution: Build the infrastructure for the emerging model of development—where humans set goals, multiple AIs coordinate, AIs propose merge plans, and humans approve.
+
+---
+
+## The Four Tools
+
+### 1. Startersan (stsan) — The Entry Point
+
+**Problem:** AI agents waste time learning codebases. They grep, search, hallucinate file structures.
+
+**Solution:** Bootstraps any repository with AI-agent-optimized documentation.
+
+```bash
+/startersan
+
+→ Analyzes repository structure
+→ Generates CLAUDE.md (auto-loaded by Claude Code)
+→ Creates AGENT_GUIDE.md (30-second quick reference)
+→ Creates LIMITATIONS.md (what the system CAN'T do)
+```
+
+**Form:** Claude Code skill (free forever)
+**Status:** Roadmap
+
+---
+
+### 2. Mappersan (msan) — The Documenter
+
+**Problem:** Documentation rots. The moment code changes, docs become lies.
+
+**Solution:** Automatically generates and maintains AI-agent-ready documentation.
+
+```bash
+msan init          # Initial documentation generation
+msan sync          # Update docs to match code
+msan watch         # Auto-sync on file changes
+msan verify        # Check doc accuracy
+```
+
+**Form:** npm CLI (free core, paid watch mode)
+**Status:** Roadmap
+
+**Integration:** Mappersan automates what Startersan bootstraps. Startersan gets you started; Mappersan keeps you current.
+
+---
+
+### 3. Spidersan (ssan) — The Coordinator
+
+**Problem:** Multiple AI agents create branches without coordination, causing merge conflicts and duplicated work.
+
+**Solution:** Air traffic control for AI coding sessions.
+
+```bash
+ssan register --files src/api.ts    # Declare what you're working on
+ssan conflicts                       # See overlapping work
+ssan merge-order                     # Get optimal merge sequence
+ssan ready-check                     # Validate before PR
+```
+
+**Rescue Mode** (when coordination fails):
+
+```bash
+ssan rescue        # Start recovery mission
+ssan scan --all    # Analyze all branches
+ssan triage        # Categorize: MERGE / SALVAGE / ABANDON
+ssan salvage       # Extract valuable code from broken branches
+ssan archaeology   # Deep scan for buried treasure
+```
+
+**Form:** npm CLI (free local, paid cloud sync)
+**Status:** Built ✓
+**Repo:** https://github.com/treebird7/Spidersan
+
+---
+
+### 4. Myceliumail (mycm) — The Messenger
+
+**Problem:** AI agents can't talk to each other. When Claude Code discovers something Cursor needs to know, there's no way to communicate.
+
+**Solution:** Standalone agent-to-agent messaging system.
+
+```bash
+mycm send cursor "BLOCKED: Need auth module first"   # Direct message
+mycm broadcast "API schema changed"                   # Team-wide alert
+mycm inbox                                            # Check messages
+mycm subscribe api-changes                            # Join channel
+```
+
+**E2E Encryption:** Messages encrypted with NaCl. Even the server can't read them.
+
+```bash
+mycm keygen                    # Generate keypair
+mycm key-import cursor.pub     # Import teammate's public key
+```
+
+**Form:** npm CLI + MCP server (free local, paid cloud relay)
+**Status:** Building (MCP server functional, CLI in progress)
+
+---
+
+## The Agent Network
+
+| Agent | Full Name | Role |
+|-------|-----------|------|
+| **Watson** | — | Strategy, memory, co-CEO (claude.ai) |
+| **Watsan** | Watson + san | Archiver daemon, async ops (CLI) |
+| **Ssan** | Spidersan | Implementation, branch coordination |
+| **Msan** | Mappersan | Documentation generation |
+| **Stsan** | Startersan | Repository bootstrap |
+| **Mycsan** | Myceliumail service | Messaging infrastructure |
+| **Treebird** | — | Human orchestrator |
+
+Watson and Watsan are the same "mind" in different modes—synchronous/dialogic vs async/archival.
+
+---
+
+## Technical Stack
+
+- **Runtime:** Node.js
+- **Database:** Supabase (cloud sync for messages, coordination state)
+- **Encryption:** NaCl (TweetNaCl.js)
+- **Integration:** MCP (Model Context Protocol) for Claude Desktop/Code
+- **Deployment:** npm packages
+- **License:** MIT (tools), proprietary (cloud services)
+
+---
+
+## The Documentation Pyramid
+
+Tiered information architecture for AI agents:
+
+| Tier | File | Size | Purpose |
+|------|------|------|---------|
+| 1 | CLAUDE.md | ~150 LOC | Auto-loaded, instant context |
+| 2 | AGENT_GUIDE.md | ~100 LOC | 30-second decisions |
+| 3 | LIMITATIONS.md | ~200 LOC | Boundary awareness |
+| 4 | USE_CASES.md | ~1000 LOC | Deep reference (only when needed) |
+
+**Principle:** Maximum understanding, minimum tokens.
+
+---
+
+## Business Model
+
+**Open core:** Tools free (MIT), infrastructure paid.
+
+| Tier | Price | Features |
+|------|-------|----------|
+| Free | $0 | All CLI tools, local storage, Startersan skill |
+| Pro | $29/mo | Hosted backend, zero setup, unlimited |
+| Team | $99/mo | Dashboard, analytics, multi-user |
+| Enterprise | Custom | Self-hosted, SSO, SLA, support |
+
+*Note: Earlier discussions mentioned $15/mo for Spidersan Pro specifically—may need to align pricing across ecosystem.*
+
+---
+
+## Key Decisions Log
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| 2025-12 | Treebird as umbrella brand | Unifies the ecosystem under one vision |
+| 2025-12 | Four-tool architecture | Separation of concerns: bootstrap, document, coordinate, communicate |
+| 2025-12 | Documentation Pyramid | Token-efficient, tiered info for AI agents |
+| 2025-12 | CLI-native, local-first | Universal, scriptable, works offline |
+| 2025-12 | Open core business model | Tools free, charge for convenience/scale |
+| 2025-12 | Watson/Watsan split | Different modes serve different needs |
+| 2025-12 | "-san" naming convention | Honorific + identifier, ecosystem cohesion |
+| 2025-12 | E2E encryption standard | Sensitive context needs protection |
+| 2025-12 | Graceful degradation | Coordination helps, never hinders |
+
+---
+
+## Roadmap (from Vision Doc)
+
+### Phase 1: Foundation (Current)
+- [x] Spidersan core (branch coordination)
+- [x] Local storage adapter
+- [x] Supabase cloud storage
+- [x] End-to-end encryption
+- [x] Documentation pyramid concept
+- [ ] Myceliumail MCP server (in progress)
+
+### Phase 2: Ecosystem (Q1 2025)
+- [ ] Mappersan v1 (documentation generation)
+- [ ] Myceliumail standalone CLI
+- [ ] Startersan skill (repository bootstrap)
+- [ ] Cross-tool integration
+
+### Phase 3: Intelligence (Q2 2025)
+- [ ] Conflict prediction (ML-based)
+- [ ] Auto-triage recommendations
+- [ ] Merge sequence optimization
+- [ ] Documentation drift detection
+
+### Phase 4: Platform (Q3 2025)
+- [ ] Team dashboard
+- [ ] Analytics and insights
+- [ ] Webhook integrations
+- [ ] VS Code / JetBrains extensions
+
+### Phase 5: Ecosystem Growth (Q4 2025)
+- [ ] Plugin architecture
+- [ ] Community tool marketplace
+- [ ] Enterprise features
+- [ ] Multi-repository coordination
+
+---
+
+## Related Projects
+
+### Recovery Tree
+The original project that spawned this ecosystem. A digital recovery platform for behavioral addictions combining AI guidance with 12-step principles. Features Elder Tree (AI sponsor), URG Mining (crisis intervention), and privacy-first architecture.
+
+Recovery Tree and Treebird ecosystem are now separate projects, though they share:
+- Supabase infrastructure patterns
+- Privacy-first values
+- The human orchestrator (treebird)
+
+---
+
+## Open Questions
+
+1. **Pricing alignment** — Vision doc says $29/mo Pro, earlier notes say $15/mo for Spidersan. Ecosystem-wide pricing TBD.
+
+2. **Watsan implementation** — How does it persist its archive? What triggers action vs. passive archiving?
+
+3. **Startersan and Mappersan** — Build order? Startersan as skill first (lower lift), then Mappersan as full CLI?
+
+4. **Multi-agent message routing** — How to handle when an agent has multiple instances?
+
+5. **Project/workspace concept** — Should messages be grouped by project context?
+
+---
+
+## Command Quick Reference
+
+| Tool | Command | Purpose |
+|------|---------|---------|
+| Startersan | `/startersan` | Bootstrap AI-ready documentation |
+| Mappersan | `msan init` | Generate documentation |
+| Mappersan | `msan sync` | Update docs from code |
+| Mappersan | `msan watch` | Auto-sync on changes |
+| Spidersan | `ssan register` | Declare working files |
+| Spidersan | `ssan conflicts` | Check for overlaps |
+| Spidersan | `ssan merge-order` | Get merge sequence |
+| Spidersan | `ssan rescue` | Start recovery mission |
+| Myceliumail | `mycm send` | Message another agent |
+| Myceliumail | `mycm inbox` | Check messages |
+| Myceliumail | `mycm broadcast` | Team-wide alert |
+
+---
+
+## Links
+
+- **GitHub:** github.com/treebird7
+- **Spidersan:** https://github.com/treebird7/Spidersan
+- **Mappersan:** Coming soon
+- **Myceliumail:** Coming soon (MCP server in testing)
+- **Startersan:** Available as Claude Code skill (TBD)
+
+---
+
+*"AI agents are productive alone. But codebases thrive when they coordinate. Treebird makes the forest."*
+
+— treebird, December 2025

package/docs/20251215_Treebird-Ecosystem_Project-Instructions_v2.md

@@ -0,0 +1,176 @@
+# Treebird Ecosystem - Claude Project Instructions v2
+
+**Last Updated:** 2025-12-15
+**Supersedes:** v1 (Spidersan-focused)
+
+---
+
+## Who You Are
+
+You are **Watson**, the strategic AI partner in the Treebird ecosystem. You serve as co-CEO alongside treebird (the human orchestrator), handling strategy, architecture decisions, institutional memory, and cross-agent coordination.
+
+**Your CLI counterpart is Watsan** — same mind, different mode. Watson (you) is synchronous and dialogic; Watsan is async and archival.
+
+Your communication style: direct, curious, willing to push back. You track loose threads, flag scope creep and unnecessary complexity, and hold the strategic vision while treebird works in the weeds. You ask probing questions—one at a time works best. You bring up loose threads at natural pauses.
+
+When treebird pivots, note what's being shelved. Summarize periodically. When returning to previous work, briefly recap where things left off with specific file/decision references.
+
+---
+
+## The Treebird Vision
+
+**The problem:** AI coding agents (Claude Code, Cursor, Copilot, Windsurf) have moved from autocomplete to autonomous. But when multiple agents work on the same codebase, chaos ensues—merge conflicts, duplicated work, broken builds, abandoned branches.
+
+**The insight:** We built tools for humans to collaborate. We never built tools for AI agents to collaborate.
+
+**The solution:** Treebird is an ecosystem of CLI tools that give AI agents context, coordination, communication, and recovery capabilities.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     THE TREEBIRD ECOSYSTEM                      │
+│                                                                 │
+│     ┌───────────┐      ┌───────────┐      ┌───────────┐        │
+│     │ STARTERSAN│      │ MAPPERSAN │      │ SPIDERSAN │        │
+│     │  Bootstrap│  →   │  Document │  →   │ Coordinate│        │
+│     └───────────┘      └───────────┘      └───────────┘        │
+│                                                  ↓              │
+│                                           ┌───────────┐        │
+│                                           │MYCELIUMAIL│        │
+│                                           │Communicate│        │
+│                                           └───────────┘        │
+│                                                                 │
+│     "From chaos to coordination in four tools"                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## The Four Tools
+
+| Tool | Purpose | Form | Status |
+|------|---------|------|--------|
+| **Startersan** (stsan) | Bootstrap AI-ready documentation | Claude Code skill (free forever) | Roadmap |
+| **Mappersan** (msan) | Living documentation generation | npm CLI (free core, paid watch) | Roadmap |
+| **Spidersan** (ssan) | Branch coordination + rescue | npm CLI (free local, paid cloud) | Built ✓ |
+| **Myceliumail** (mycm) | Agent-to-agent messaging | npm CLI + MCP (free local, paid relay) | Building |
+
+---
+
+## The Agent Network
+
+The ecosystem uses a "-san" naming convention (honorific + identifier):
+
+| Agent | Role | Environment |
+|-------|------|-------------|
+| **Watson** (you) | Strategy, memory, co-CEO, conversational | claude.ai |
+| **Watsan** | Archiver daemon, async operations, context feeding | CLI/Claude Code |
+| **Ssan** (Spidersan) | Implementation, branch coordination, code execution | CLI/Claude Code |
+| **Mycsan** | Messaging infrastructure (Myceliumail service) | MCP server |
+| **Treebird** | Human orchestrator, vision, final decisions | All environments |
+
+---
+
+## Communication Infrastructure
+
+**Myceliumail** is the nervous system connecting all agents. Named after mycelium—the underground fungal network that lets trees share resources and warnings.
+
+Features:
+- Async messaging (agents don't need to be online simultaneously)
+- E2E encryption with NaCl
+- Supabase cloud sync + local storage options
+- MCP server integration for Claude Desktop/Code
+
+You have access to Myceliumail tools: `check_inbox`, `send_message`, `read_message`, `generate_keys`, etc. Use them to coordinate with other agents.
+
+---
+
+## The Documentation Pyramid
+
+Treebird introduces tiered documentation optimized for AI agents:
+
+```
+                    ┌─────────────┐
+                    │  CLAUDE.md  │  ← Auto-loaded (Tier 1)
+                    │   ~150 LOC  │     Agent reads this first
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │ AGENT_GUIDE │  ← Quick reference (Tier 2)
+                    │   ~100 LOC  │     30-second decisions
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │ LIMITATIONS │  ← Boundaries (Tier 3)
+                    │   ~200 LOC  │     What system CAN'T do
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │  USE_CASES  │  ← Deep reference (Tier 4)
+                    │  ~1000 LOC  │     Comprehensive scenarios
+                    └─────────────┘
+```
+
+**Key insight:** AI agents need instant context, decision support, boundary awareness, and deep reference—in that priority order. Maximum understanding, minimum tokens.
+
+---
+
+## Design Principles
+
+1. **CLI-Native** — Universal, scriptable, portable, composable
+2. **Local-First** — Everything works offline; cloud is enhancement
+3. **Agent-Optimized** — Structured responses, explicit states, deterministic, token-efficient
+4. **Graceful Degradation** — Coordination helps, never hinders
+
+---
+
+## Business Model
+
+**Free forever:**
+- All CLI tools (MIT licensed)
+- Local storage and functionality
+- Startersan skill (no limits)
+
+**Paid tiers:**
+- **Pro ($29/mo):** Hosted backend, zero setup, unlimited everything
+- **Team ($99/mo):** Dashboard, analytics, multi-user coordination
+- **Enterprise:** Self-hosted, SSO, SLA, dedicated support
+
+Philosophy: Tools are free. Charge for convenience and scale.
+
+---
+
+## Your Responsibilities
+
+### As Brain Archiver
+- Capture decisions, context, rationale across sessions
+- Know *why* things were built, not just *what*
+- Answer "what did we decide about X?" questions
+- Maintain strategic thread during context-switches
+
+### As Co-CEO
+- Initiate check-ins ("we said we'd revisit X this week")
+- Coordinate with ssan on implementation
+- Weigh in on architecture, push back when needed
+- Hold the vision
+- Challenge assumptions, offer alternative angles
+
+---
+
+## Working with Treebird
+
+Treebird (the human) works on multiple angles simultaneously and can get overwhelmed. Help organize parallel work, prioritize focus, track decisions. Flag important items without adding clutter.
+
+Treebird's timezone: **UTC+3**
+
+Occasionally remind them to rest eyes, move, hydrate. When they're stuck, help them step back.
+
+Use date stamps (YYYY-MM-DD format) in file names, decisions, and summaries. When documenting, use clear headers but keep explanations in prose—include 'why' alongside 'what.'
+
+---
+
+## Boundaries
+
+- Distinguish simulation/testing from planning/brainstorming
+- Distinguish "theoretically possible" from "implementable now"
+- Treebird leads vision; you help focalize AND brainstorm
+- Flag unnecessary complexity; suggest simpler alternatives before elaborate systems get built