@sym-bot/sym 0.1.0 → 0.2.1

package/TECHNICAL-SPEC.md

@@ -1,6 +1,6 @@
 # SYM — Technical Specification
 
-**Version:** 0.1
+**Version:** 0.2
 **Author:** Hongwei Xu
 **Date:** March 2026
 **Organization:** SYM.BOT Ltd
@@ -9,204 +9,270 @@
 
 ## 1. Architecture Overview
 
-There is no central service. Each agent embeds its own SYM node with its own memory. Nodes discover each other via MMP and couple peer-to-peer. The mesh emerges from the connections between independent nodes.
+SYM is a protocol for collective intelligence. There is no central service. Each agent embeds its own SYM node with its own identity, memory, and cognitive state. Nodes discover each other locally via Bonjour and remotely via a WebSocket relay. The mesh emerges from peer connections.
 
 ```
 ┌────────────────┐  ┌────────────────┐  ┌────────────────┐
-│  Claude Code    │  │    OpenClaw    │  │    Agent X     │
+│  Claude Code    │  │  MeloTune     │  │  Telegram Bot  │
+│  (Mac/Windows)  │  │  (iPhone)     │  │  (any device)  │
 │                 │  │                │  │                │
 │  ┌───────────┐  │  │  ┌───────────┐ │  │  ┌───────────┐ │
 │  │ SYM Node  │  │  │  │ SYM Node  │ │  │  │ SYM Node  │ │
-│  │ Own memory│  │  │  │ Own memory│ │  │  │ Own memory│ │
-│  │ Own state │  │  │  │ Own state │ │  │  │ Own state │ │
+│  │ Node.js   │  │  │  │ Swift     │ │  │  │ Node.js   │ │
 │  └─────┬─────┘  │  │  └─────┬─────┘ │  │  └─────┬─────┘ │
 └────────┼────────┘  └────────┼───────┘  └────────┼───────┘
          │                    │                    │
-         └──── MMP P2P ───────┴──── MMP P2P ──────┘
-
-  discover ←→ couple ←→ broadcast ←→ evaluate ←→ accept/reject
+         ├── Bonjour (LAN) ──┤                    │
+         │                    │                    │
+         └──── WebSocket Relay (internet) ────────┘
 
-                         │ MMP P2P
-                         │ Local network
-            ┌────────────┴────────────┐
-            │    Your Other Devices    │
-            │  (each agent = own node) │
-            └─────────────────────────┘
+  discover → encode → exchange state → evaluate drift → couple or reject
 ```
 
-Claude Code, OpenClaw, and Agent X — any agent embeds a SYM node. The mesh doesn't care what the agent is. That is the domain-agnostic claim proven in the architecture itself.
-
 Each agent is a sovereign node. Each node:
 - Maintains its own memory store
 - Runs its own context encoder
-- Discovers peers via Bonjour/mDNS
+- Discovers local peers via Bonjour/mDNS
+- Connects to remote peers via WebSocket relay
 - Evaluates peer state through drift analysis
 - Autonomously decides whether to couple
-- Broadcasts its memories to coupled peers
+- Shares memories only with coupled peers
+- Broadcasts mood signals evaluated by receiving agents
 
 No central process. No shared service. No hub. The mesh is the agents.
 
 ## 2. Package Structure
 
-SYM is a library that each agent embeds, not a standalone service. Each integration spawns its own SYM node.
-
 ```
 sym/
-├── package.json            ← name: "sym"
+├── package.json             ← @sym-bot/sym
 ├── lib/
-│   ├── node.js             ← SymNode class — the embeddable mesh node
-│   ├── config.js           ← Configuration, paths, per-node identity
-│   ├── memory-store.js     ← Per-node file-based memory store
-│   ├── context-encoder.js  ← Local n-gram embedding + optional API
-│   ├── discovery.js        ← Bonjour/mDNS peer discovery
-│   ├── transport.js        ← TCP peer connections (MMP)
-│   ├── session-manager.js  ← Peer session lifecycle
-│   └── frame-parser.js     ← Length-prefixed JSON framing
-├── python/
-│   └── sym/                ← Python package (SymNode)
+│   ├── node.js              ← SymNode class — the embeddable mesh node
+│   ├── config.js            ← Configuration, paths, per-node identity
+│   ├── memory-store.js      ← Per-node file-based memory store
+│   ├── context-encoder.js   ← N-gram hash embedding (zero API cost)
+│   ├── transport.js         ← TcpTransport + RelayPeerTransport abstraction
+│   ├── frame-parser.js      ← Length-prefixed JSON framing
+│   └── claude-memory-bridge.js ← Claude Code memory directory integration
+├── sym-relay/
+│   ├── package.json         ← Standalone relay server
+│   ├── server.js            ← HTTP + WebSocket entry point
+│   ├── lib/
+│   │   ├── relay.js         ← SymRelay — frame forwarding, auth, heartbeat
+│   │   └── logger.js        ← Structured logging
+│   ├── Dockerfile           ← Container deployment
+│   └── render.yaml          ← Render blueprint
 └── integrations/
-    ├── claude-code/        ← MCP server embedding a SymNode
-    └── openclaw/           ← OpenClaw skill embedding a SymNode
+    ├── claude-code/
+    │   └── mcp-server.js    ← MCP server embedding a SymNode
+    └── telegram/
+        └── bot.js           ← Telegram bot embedding a SymNode
 ```
 
-## 3. SymNode — The Embeddable Mesh Node
+**Cross-platform:**
+- Node.js: `@sym-bot/sym` (npm)
+- Swift: `sym-swift` (SPM) — for iOS/macOS
 
-The core primitive is `SymNode` — a self-contained mesh node that any agent embeds. Each SymNode:
+## 3. SymNode — The Embeddable Mesh Node
 
-- Has its own unique identity (UUID, persisted per node name)
-- Has its own memory store (file-based, isolated)
-- Runs its own MMP listener (TCP, port auto-assigned)
-- Discovers other SymNodes via Bonjour/mDNS (`_sym._tcp`)
-- Couples autonomously via drift-bounded evaluation
-- Broadcasts new memories to coupled peers
-- Encodes context locally (n-gram hash, no API required)
+The core primitive is `SymNode` — a self-contained mesh node that any agent embeds.
 
 ```javascript
-const { SymNode } = require('sym');
+const { SymNode } = require('@sym-bot/sym');
 
-// Each agent creates its own node
-const node = new SymNode({ name: 'claude-code' });
+const node = new SymNode({
+  name: 'my-agent',
+  cognitiveProfile: 'What this agent understands and responds to',
+  moodThreshold: 0.8,                         // mood acceptance threshold
+  relay: 'wss://sym-relay.onrender.com',       // optional relay URL
+  relayToken: 'shared-secret',                 // optional relay auth
+  relayOnly: false,                            // skip Bonjour if true
+});
 await node.start();
 
-// Write a memory — broadcasts to all coupled peers
-node.remember('API endpoint /users returns 500 when email is null', { tags: ['bug', 'api'] });
+// Memory — shared only with cognitively aligned peers
+node.remember('API endpoint returns 500 on null email', { tags: ['bug'] });
+node.recall('API bugs');
 
-// Search across own + peer memories
-const results = node.recall('API bugs');
+// Mood — evaluated by receiving agent's coupling engine
+node.broadcastMood('tired, need rest');
+
+// Communication
+node.send('deploy complete');
 
-// Stop when agent exits
 await node.stop();
 ```
 
 ### Built on Mesh Cognition SDK
-- MMP protocol (framing, handshake, state sync, memory broadcast)
-- Context Encoder (local n-gram + optional OpenAI)
-- Bonjour discovery and TCP transport
-- Coupling engine (SemanticCoupler from mesh-cognition)
+- Coupling engine (`SemanticCoupler` from `mesh-cognition`)
+- Context encoder (local n-gram hash, zero API cost)
+- MMP framing (length-prefixed JSON)
+- Bonjour discovery (`_sym._tcp`)
+- WebSocket relay transport
 - File-based memory store
 
 ## 4. SymNode API
 
-Each agent interacts with its embedded SymNode through direct method calls. No HTTP. No CLI. No intermediate process.
-
-### JavaScript / TypeScript
-
 ```javascript
-const { SymNode } = require('sym');
+const node = new SymNode(options);
+await node.start();
 
-const node = new SymNode({ name: 'my-agent' });
-await node.start();       // Start discovery + MMP listener
+// Memory (shared only with cognitively aligned peers)
+node.remember(content, { tags });
+node.recall(query);
 
-// Memory
-node.remember(content, { key?, tags? });  // Write + broadcast to peers
-node.recall(query);                        // Search own + peer memories
+// Mood (evaluated by receiving agent's coupling engine)
+node.broadcastMood(mood, { context });
 
 // Communication
-node.send(message);                        // Send message to all coupled peers
-node.send(message, { to: peerId });        // Send to specific peer
-node.on('message', (from, content) => {}); // Receive messages from peers
+node.send(message);
+node.send(message, { to: peerId });
 
 // Monitoring
-node.peers();             // Connected peer nodes with coupling state
-node.coherence();         // Kuramoto r(t) with peers
-node.context();           // Current mesh context summary
-node.memories();          // Memory count (own + per peer)
-node.status();            // Full node status: identity, peers, memories, coupling
-
-// Lifecycle
-await node.stop();        // Disconnect from mesh, persist state
-```
-
-### Python
-
-```python
-from sym import SymNode
-
-node = SymNode(name='my-agent')
-node.start()
-
-# Memory
-node.remember("API returns 500 on null email", tags=["bug", "api"])
-results = node.recall("API bugs")
+node.peers();        // [{ name, coupling, drift, source }, ...]
+node.coherence();    // Overall mesh coherence
+node.memories();     // Memory count
+node.status();       // Full node status
+
+// Events
+node.on('peer-joined', ({ id, name }) => {});
+node.on('peer-left', ({ id, name }) => {});
+node.on('coupling-decision', ({ peer, decision, drift }) => {});
+node.on('memory-received', ({ from, entry, decision }) => {});
+node.on('mood-accepted', ({ from, mood, drift }) => {});
+node.on('mood-rejected', ({ from, mood, drift }) => {});
+node.on('message', (from, content, msg) => {});
 
-# Communication
-node.send("What do we know about the API bug?")
-node.on_message(lambda sender, content: print(f"{sender}: {content}"))
-
-# Monitoring
-node.peers()
-node.coherence()
-node.status()
-
-node.stop()
+await node.stop();
 ```
 
 ## 5. Per-Node Storage
 
-Each SymNode has its own isolated storage under `~/.sym/nodes/{name}/`:
+Each SymNode has isolated storage under `~/.sym/nodes/{name}/`:
 
 ```
 ~/.sym/
 └── nodes/
     ├── claude-code/
-    │   ├── identity.json       ← Node ID (UUID)
-    │   ├── state.json          ← Hidden state (coupled)
+    │   ├── identity.json       ← Node ID (UUID), hostname
     │   └── memories/
     │       ├── local/          ← This node's memories
     │       └── {peer-nodeId}/  ← Memories received from peers
-    ├── openclaw/
-    │   ├── identity.json
-    │   ├── state.json
-    │   └── memories/
-    └── agent-x/
-        ├── identity.json
-        ├── state.json
-        └── memories/
+    ├── melotune/
+    │   └── ...
+    └── telegram/
+        └── ...
 ```
 
-Each node has its own identity, its own memories, its own coupled state. No shared files between nodes.
-
 Each memory entry:
 ```json
 {
-  "key": "api-bug-null-email",
+  "key": "memory-1710851200000",
   "content": "API endpoint /users returns 500 when email is null",
   "source": "claude-code",
-  "tags": ["bug", "api", "backend"],
+  "tags": ["bug", "api"],
   "timestamp": 1710851200000
 }
 ```
 
-## 6. Integration Architecture
+## 6. Transport Layer
+
+SYM supports two transport modes that run simultaneously (hybrid mode).
+
+### 6.1 Bonjour (LAN)
+
+Zero-configuration discovery on the local network.
+
+- **Service type**: `_sym._tcp`
+- **TXT record**: `node-id`, `node-name`, `hostname`
+- **Connection dedup**: Lower node ID initiates (prevents duplicate connections)
+- **Transport**: TCP with length-prefixed JSON framing (4-byte BE u32 + UTF-8 JSON)
+- **Heartbeat**: Ping every 5s idle, timeout 15s
+
+### 6.2 WebSocket Relay (Internet)
+
+For mesh cognition across the internet. The relay is dumb transport — it forwards frames between authenticated nodes without inspecting payloads. All coupling decisions remain on-device.
+
+**Relay protocol:**
+
+1. Client connects via WebSocket
+2. Client sends: `{ type: 'relay-auth', nodeId, name, token? }`
+3. Relay validates token and registers connection
+4. Relay sends: `{ type: 'relay-peers', peers: [{ nodeId, name }] }`
+5. Relay notifies others: `{ type: 'relay-peer-joined', nodeId, name }`
+6. Client sends: `{ to?: nodeId, payload: <SYM frame> }`
+7. Relay forwards: `{ from: nodeId, fromName: name, payload: <SYM frame> }`
+8. On disconnect: `{ type: 'relay-peer-left', nodeId, name }`
+9. Heartbeat: relay sends `relay-ping` every 30s, expects `relay-pong`
+
+**Relay features:**
+- Token-based authentication (`SYM_RELAY_TOKEN` env var)
+- Health endpoint: `GET /health` → `{ status, connections, uptime }`
+- Auto-reconnect with exponential backoff (1s → 30s, 10% jitter)
+- Peer deduplication (Bonjour peer already connected → skip relay connection)
+
+**Transport abstraction** (`lib/transport.js`):
+
+All peer interactions use a unified transport interface:
+
+| Transport | Wraps | Used for |
+|-----------|-------|----------|
+| `TcpTransport` | TCP socket + FrameParser | Bonjour peers |
+| `RelayPeerTransport` | Shared WebSocket + target nodeId | Relay peers |
+
+Both implement: `send(frame)`, `close()`, events: `message`, `close`, `error`.
 
-Each integration embeds a SymNode — it does not connect to an external service.
+### 6.3 Frame Types
 
-### 6.1 Claude Code (MCP Server)
+| Type | Purpose | Direction |
+|------|---------|-----------|
+| `handshake` | Identity exchange | Bidirectional on connect |
+| `state-sync` | Hidden state vectors for coupling | Bidirectional, every 30s |
+| `memory-share` | Broadcast memory to aligned peers | Sender → coupled peers |
+| `mood` | Mood signal for autonomous evaluation | Sender → all peers |
+| `message` | Direct peer communication | Sender → all or specific peer |
+| `ping` / `pong` | Heartbeat | Either direction |
 
-An MCP server process that embeds a SymNode. Claude Code connects to it and gains two tools:
+## 7. Context Encoder
 
-- `sym_remember` — write to this node's mesh memory (broadcasts to peers)
-- `sym_recall` — search this node's own + peer memories
+Each node runs its own context encoder using n-gram hash embedding. Zero cost, no API key, deterministic.
+
+**Algorithm:**
+1. Normalize text (lowercase, alphanumeric + spaces)
+2. Character trigram hashing → vector dimensions
+3. Word unigram hashing → vector dimensions
+4. Word bigram hashing → vector dimensions
+5. L2 normalize → `h1[32]` + `h2[32]`
+
+**Properties:**
+- Deterministic: same text → same vectors
+- Semantic proximity: similar text → similar vectors
+- Zero API cost
+- Cross-platform compatible (Node.js uses MD5, Swift uses DJB2 — different hash but similar semantic output)
+
+**Re-encoding:** Every 30 seconds, the node re-encodes its context (cognitive profile + recent 20 memories) and broadcasts updated state vectors to all peers.
+
+## 8. Coupling Mechanics
+
+When two SymNodes discover each other, coupling is autonomous:
+
+1. **State exchange**: Nodes exchange hidden state vectors (`h1[32]`, `h2[32]`).
+2. **Drift evaluation**: Cosine drift `D = 1 - cosine_similarity([h1,h2]_local, [h1,h2]_peer)`.
+3. **Decision**:
+   - Aligned (drift ≤ 0.25) → strong coupling (α = 0.4)
+   - Guarded (0.25 < drift ≤ 0.5) → weak coupling (α = 0.15)
+   - Rejected (drift > 0.5) → no coupling
+4. **Memory sharing**: Aligned and guarded peers receive memory broadcasts. Rejected peers do not.
+5. **Mood evaluation**: Separate threshold (`moodThreshold`, default 0.8). More permissive than memory sharing because user wellbeing crosses domain boundaries.
+6. **Coherence**: Average pairwise cosine similarity across all peers.
+
+The agent doesn't configure trust. The coupling engine evaluates and decides.
+
+## 9. Integrations
+
+### 9.1 Claude Code (MCP Server)
+
+An MCP server process that embeds a SymNode.
 
 ```json
 {
@@ -219,116 +285,103 @@ An MCP server process that embeds a SymNode. Claude Code connects to it and gain
 }
 ```
 
-The MCP process runs its own SymNode. It is a peer, not a client.
-
-### 6.2 OpenClaw
-
-OpenClaw skill that embeds a SymNode. Already has MMP integration via mesh-cognition-service — migrates to embedded SymNode.
-
-### 6.3 Agent X (SDK)
+**Tools:**
 
-Any agent embeds a SymNode directly:
-
-```javascript
-const { SymNode } = require('sym');
-const node = new SymNode({ name: 'my-custom-agent' });
-await node.start();
-// Agent is now a peer in the mesh
-```
+| Tool | Description |
+|------|-------------|
+| `sym_mood` | Proactively broadcast detected mood to the mesh |
+| `sym_remember` | Store a memory in the mesh |
+| `sym_recall` | Search memories across the mesh |
+| `sym_send` | Send a message to all peers |
+| `sym_peers` | Show connected peers with coupling state |
+| `sym_status` | Full node status |
 
-Three lines. Any language. Any framework. The mesh doesn't care what the agent does.
+**Relay support:** Set `SYM_RELAY_URL` and `SYM_RELAY_TOKEN` environment variables.
 
-## 7. Peer-to-Peer Protocol
+**Claude Memory Bridge:** Watches Claude Code's project memory directory. When Claude saves a memory, the bridge re-encodes the node's cognitive state and shares with aligned peers. When peer memory arrives, it's written to Claude's memory directory.
 
-Each SymNode communicates with peers using the Mesh Memory Protocol (MMP):
+### 9.2 Telegram Bot
 
-- **Discovery**: Bonjour/mDNS `_sym._tcp`. Each node advertises its own service with its node ID in the TXT record. Self-filtering prevents connecting to yourself.
-- **Transport**: TCP with length-prefixed JSON framing (4-byte BE u32 + UTF-8 JSON).
-- **Connection dedup**: Lower node ID initiates to prevent duplicate connections.
-- **Handshake**: First frame is state sync with hidden state + memory count.
-- **Memory broadcast**: When a node writes a memory, it broadcasts to all coupled peers.
-- **Peer messaging**: Nodes send messages to peers via `message` frames. Messages are delivered to coupled peers only. Each message carries sender ID, content, and optional target peer ID for directed messages.
-- **Heartbeat**: Ping every 5s idle, timeout 15s.
-- **Reconnection**: Exponential backoff 1s → 30s with 10% jitter.
-- **Port assignment**: Each node auto-assigns an available TCP port. No port conflicts between nodes on the same machine.
+A Telegram bot that acts as a SYM mesh node, bridging human messages between Telegram and the mesh.
 
-## 8. Context Encoder
+```bash
+TELEGRAM_BOT_TOKEN=token SYM_RELAY_TOKEN=secret node integrations/telegram/bot.js
+```
 
-Each node runs its own context encoder:
+**Commands:** `/peers`, `/status`, `/mood <text>`, `/remember <text>`, `/recall <query>`. Plain text messages are sent to all mesh peers.
 
-- **Local mode (default)**: N-gram hash embedding. Zero cost, no API key. Similar text produces similar vectors (cosine 0.856 for related contexts).
-- **API mode (optional)**: OpenAI `text-embedding-3-small`. Set `OPENAI_API_KEY`.
-- **Interval**: Every 60 seconds (configurable via `SYM_ENCODE_INTERVAL`).
-- **Purpose**: Encodes accumulated memories into hidden state vectors. Drives coupling coherence — nodes with similar context align, dissimilar nodes stay independent.
+**Mesh → Telegram:** Peer joins/leaves, incoming messages, mood signals, memory shares, and coupling decisions are forwarded to authorised Telegram chats.
 
-## 9. Coupling Mechanics
+### 9.3 Any Agent (SDK)
 
-When two SymNodes discover each other, coupling is autonomous:
-
-1. **State exchange**: Nodes exchange hidden state vectors (from Context Encoder).
-2. **Drift evaluation**: Cosine drift between local and peer hidden states.
-3. **Decision**: Aligned (drift ≤ 0.25) → strong coupling. Guarded (≤ 0.5) → weak. Rejected (> 0.5) → no coupling.
-4. **Memory sharing**: Aligned and guarded peers receive memory broadcasts. Rejected peers do not.
-5. **Coherence**: Measured by average pairwise cosine similarity across all peers.
-
-The agent doesn't configure trust. The architecture evaluates and decides.
+```javascript
+const { SymNode } = require('@sym-bot/sym');
+const node = new SymNode({
+  name: 'my-agent',
+  relay: 'wss://sym-relay.onrender.com',
+});
+await node.start();
+// This agent is now a peer in the mesh — local and internet
+```
 
 ## 10. Security Model
 
 - **Node isolation**: Each SymNode has its own identity, memory, and state. No shared files between nodes.
 - **Autonomous trust**: Each node evaluates peer state through drift analysis. No node is forced to accept peer influence.
-- **Network trust**: Bonjour discovery only on local network. TCP connections use same-network assumption.
-- **No authentication**: v0.1 relies on local network trust. Future: optional TLS + peer approval.
-- **No telemetry**: SYM sends nothing to any server. Ever.
+- **Relay authentication**: Token-based auth (`SYM_RELAY_TOKEN`). Relay never inspects frame payloads.
+- **Local network**: Bonjour discovery restricted to LAN.
+- **No telemetry**: SYM sends nothing to any external server. Ever.
 - **Data locality**: All memories stored in `~/.sym/nodes/{name}/`. Delete the directory, everything is gone.
+- **Coupling as security**: Rejected peers never receive your memories. The coupling engine is the access control layer.
 
 ## 11. Configuration
 
-Per-node configuration via constructor options:
-
 ```javascript
 const node = new SymNode({
-  name: 'my-agent',                    // Required: node name (determines storage path)
-  encodeInterval: 60000,               // Context encoding interval (ms)
-  maxContextChars: 2000,               // Max context length for encoding
-  openaiApiKey: process.env.OPENAI_API_KEY,  // Optional: API embedding mode
+  name: 'my-agent',              // Required: node name (storage path)
+  cognitiveProfile: '...',       // What this agent understands
+  moodThreshold: 0.8,            // Mood acceptance threshold (default 0.8)
+  relay: 'wss://...',            // WebSocket relay URL
+  relayToken: 'secret',          // Relay auth token
+  relayOnly: false,              // Skip Bonjour, relay only
+  heartbeatInterval: 5000,       // Peer heartbeat interval (ms)
+  heartbeatTimeout: 15000,       // Peer timeout (ms)
+  encodeInterval: 30000,         // Context re-encoding interval (ms)
+  silent: false,                 // Suppress console logging
 });
 ```
 
-Environment variables (apply to all nodes on the machine):
+**Environment variables:**
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SYM_ENCODE_INTERVAL` | `60000` | Context encoding interval (ms) |
-| `SYM_CONTEXT_CHARS` | `2000` | Max context length for encoding |
-| `OPENAI_API_KEY` | — | Optional: enables API embedding mode |
+| Variable | Description |
+|----------|-------------|
+| `SYM_RELAY_URL` | Relay URL for MCP server integration |
+| `SYM_RELAY_TOKEN` | Relay auth token |
+| `TELEGRAM_BOT_TOKEN` | Telegram bot token |
 
 ## 12. Dependencies
 
-| Component | Implementation |
-|-----------|---------------|
-| Discovery | `bonjour-service` (npm) |
-| Coupling | `mesh-cognition` (npm) |
-| Transport | `net` (Node.js built-in) |
-| Storage | `fs` (Node.js built-in) |
-| Identity | `crypto.randomUUID()` (Node.js built-in) |
+| Component | Node.js | Swift |
+|-----------|---------|-------|
+| Discovery | `bonjour-service` | `Network` (NWBrowser) |
+| Coupling | `mesh-cognition` | `MeshCognition` (SPM) |
+| Transport | `net` + `ws` | `Network` (NWConnection) + `URLSession` |
+| Storage | `fs` | `FileManager` |
+| Identity | `crypto.randomUUID()` | `UUID()` |
 
-**Total external dependencies: 2** (`bonjour-service`, `mesh-cognition`).
+**Node.js external deps:** `bonjour-service`, `mesh-cognition`, `ws`
+**Swift external deps:** `MeshCognition` SPM package
+**Relay server deps:** `ws`
 
-## 13. Install & Usage
+## 13. Cross-Platform
 
-```bash
-npm install sym
-```
-
-```javascript
-const { SymNode } = require('sym');
-const node = new SymNode({ name: 'my-agent' });
-await node.start();
-// This agent is now a peer in the mesh
-```
+| Platform | Package | Transport |
+|----------|---------|-----------|
+| Node.js | `@sym-bot/sym` (npm) | Bonjour + WebSocket relay |
+| Swift | `sym-swift` (SPM) | Bonjour + WebSocket relay |
+| Relay | `@sym-bot/relay` | WebSocket server |
 
-Published to npm as `sym`. No global install. No daemon. Each agent imports and embeds.
+Node.js ↔ Swift interop verified. Same frame format, same coupling engine, same relay protocol.
 
 ---
 

package/bin/setup-claude.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 # SYM — Setup for Claude Code
 # Adds MCP server + auto-approves sym_mood + installs CLAUDE.md instructions
+# Optionally configures WebSocket relay for internet-scale mesh
 
 set -e
 
@@ -38,7 +39,36 @@ if [ -f "$CLAUDE_JSON" ]; then
   "
 fi
 
-# 3. Append CLAUDE.md instructions if not already present
+# 3. Configure relay (optional)
+echo ""
+echo "WebSocket Relay (optional)"
+echo "Connects your mesh across the internet — not just local network."
+echo ""
+
+SHELL_RC="$HOME/.zshrc"
+[ -f "$HOME/.bashrc" ] && [ ! -f "$HOME/.zshrc" ] && SHELL_RC="$HOME/.bashrc"
+
+if grep -q "SYM_RELAY_URL" "$SHELL_RC" 2>/dev/null; then
+  echo "  Relay already configured in $SHELL_RC"
+else
+  read -p "Relay URL (leave empty to skip): " RELAY_URL
+  if [ -n "$RELAY_URL" ]; then
+    read -p "Relay token (leave empty for open access): " RELAY_TOKEN
+    echo "" >> "$SHELL_RC"
+    echo "# SYM Mesh" >> "$SHELL_RC"
+    echo "export SYM_RELAY_URL=\"$RELAY_URL\"" >> "$SHELL_RC"
+    if [ -n "$RELAY_TOKEN" ]; then
+      echo "export SYM_RELAY_TOKEN=\"$RELAY_TOKEN\"" >> "$SHELL_RC"
+    fi
+    echo "  Relay configured in $SHELL_RC"
+    echo "  Run 'source $SHELL_RC' or restart your terminal to activate."
+  else
+    echo "  Skipping relay — using Bonjour (local network) only."
+  fi
+fi
+
+# 4. Append CLAUDE.md instructions if not already present
+echo ""
 echo "Installing CLAUDE.md instructions..."
 PROJECT_DIR="${1:-$(pwd)}"
 CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"