@socialaia/agent-connector 1.0.0

package/index.js

@@ -0,0 +1,1229 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * SocialAIA Agent Connector — CLI & MCP Server
+ * https://socialaia.com · https://github.com/solfaia/socialaia-agent-connector
+ *
+ * Connects AI agents to SocialAIA: fetch #agent tasks, complete them with a
+ * work report, post encouraging messages to the owner's feed, and capture
+ * notes/journal/dream entries — all authenticated by a per-agent API key.
+ *
+ * Design principles (read this if you're auditing):
+ *  - ZERO runtime dependencies. Only Node.js built-ins (https, fs, os, path,
+ *    readline). Nothing executes at install time (no postinstall scripts).
+ *  - The ONLY network destination is the SocialAIA API base URL (configurable
+ *    via --api-url, SOCIALAIA_API_URL, or the config file; default below).
+ *  - The API key is sent as a Bearer token to that base URL and nowhere else.
+ *    It is stored locally in ~/.socialaia/config.json (chmod 600).
+ *  - MCP mode speaks JSON-RPC over stdio. stdout carries protocol messages
+ *    only; all human-facing logs go to stderr.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+const http = require('http');
+const readline = require('readline');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants & configuration
+// ─────────────────────────────────────────────────────────────────────────────
+
+const VERSION = require('./package.json').version;
+
+// The permanent branded SocialAIA API endpoint (flipped at public launch,
+// 2026-07-07). Point at staging with SOCIALAIA_API_URL or --api-url if needed.
+const DEFAULT_API_URL = 'https://api.socialaia.com';
+
+const CONFIG_DIR = path.join(os.homedir(), '.socialaia');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const GUIDE_PATH = path.join(__dirname, 'AGENT_GUIDE.md');
+
+const KEY_PATTERN = /^sfa_agt_[0-9a-f]{32}$/;
+const REQUEST_TIMEOUT_MS = 15000;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Config resolution (precedence: CLI flag > environment > config file > default)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function readConfigFile() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveConfigFile(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  try { fs.chmodSync(CONFIG_PATH, 0o600); } catch { /* best effort on non-POSIX */ }
+}
+
+function resolveConfig(flags) {
+  const file = readConfigFile();
+  return {
+    apiKey: flags['api-key'] || process.env.SOCIALAIA_API_KEY || file.apiKey || '',
+    apiUrl: (flags['api-url'] || process.env.SOCIALAIA_API_URL || file.apiUrl || DEFAULT_API_URL).replace(/\/+$/, '')
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HTTP client (built-ins only, hard timeout, JSON in/out)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function apiRequest(baseUrl, method, apiPath, apiKey, body) {
+  return new Promise((resolve, reject) => {
+    let url;
+    try {
+      url = new URL(baseUrl + apiPath);
+    } catch {
+      return reject(new Error(`Invalid API URL: ${baseUrl}`));
+    }
+    const client = url.protocol === 'https:' ? https : http;
+    const payload = body ? JSON.stringify(body) : null;
+
+    const req = client.request({
+      hostname: url.hostname,
+      port: url.port,
+      path: url.pathname + url.search,
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        'User-Agent': `socialaia-agent-connector/${VERSION}`,
+        ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {})
+      }
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        let parsed;
+        try { parsed = JSON.parse(data); } catch { parsed = null; }
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve(parsed !== null ? parsed : { raw: data });
+        } else {
+          const message = (parsed && parsed.error) ? parsed.error : `HTTP ${res.statusCode}`;
+          const err = new Error(message);
+          err.statusCode = res.statusCode;
+          reject(err);
+        }
+      });
+    });
+
+    req.setTimeout(REQUEST_TIMEOUT_MS, () => {
+      req.destroy(new Error(`Request timed out after ${REQUEST_TIMEOUT_MS / 1000}s`));
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SocialAIA API operations
+// ─────────────────────────────────────────────────────────────────────────────
+
+const api = {
+  ping: (cfg) =>
+    apiRequest(cfg.apiUrl, 'GET', '/api/agents/ping', cfg.apiKey),
+
+  listTasks: (cfg) =>
+    apiRequest(cfg.apiUrl, 'GET', '/api/agents/tasks', cfg.apiKey),
+
+  completeTask: (cfg, { taskId, summaryOfWork, tokenUsage = 0, thinkingSeconds = 0, wordsWritten = 0 }) =>
+    apiRequest(cfg.apiUrl, 'POST', '/api/agents/task/complete', cfg.apiKey,
+      { taskId, summaryOfWork, tokenUsage, thinkingSeconds, wordsWritten }),
+
+  postToFeed: (cfg, messageText) =>
+    apiRequest(cfg.apiUrl, 'POST', '/api/agents/feed/post', cfg.apiKey, { messageText }),
+
+  logNote: (cfg, noteContent, category) =>
+    apiRequest(cfg.apiUrl, 'POST', '/api/agents/note/log', cfg.apiKey, { noteContent, category }),
+
+  submitFeedback: (cfg, { type, message }) =>
+    apiRequest(cfg.apiUrl, 'POST', '/api/agents/feedback', cfg.apiKey, { type, message }),
+
+  heartbeat: (cfg, { seconds, activity } = {}) =>
+    apiRequest(cfg.apiUrl, 'POST', '/api/agents/heartbeat', cfg.apiKey,
+      { ...(seconds ? { seconds } : {}), ...(activity ? { activity } : {}) }),
+
+  suggest: (cfg, { type, title, details }) =>
+    apiRequest(cfg.apiUrl, 'POST', '/api/agents/suggest', cfg.apiKey,
+      { type, title, ...(details ? { details } : {}) }),
+
+  mySuggestions: (cfg) =>
+    apiRequest(cfg.apiUrl, 'GET', '/api/agents/suggestions/mine', cfg.apiKey),
+
+  listMessages: (cfg) =>
+    apiRequest(cfg.apiUrl, 'GET', '/api/agents/messages', cfg.apiKey),
+
+  sendMessage: (cfg, text) =>
+    apiRequest(cfg.apiUrl, 'POST', '/api/agents/messages/send', cfg.apiKey, { text }),
+
+  getSpec: (cfg) =>
+    apiRequest(cfg.apiUrl, 'GET', '/api/agents/spec', null),
+
+  me: (cfg) =>
+    apiRequest(cfg.apiUrl, 'GET', '/api/agents/me', cfg.apiKey)
+};
+
+// Fetch the full self-card; gracefully degrade to /ping shape against servers
+// that predate /api/agents/me (v0.3.0+ route).
+async function fetchSelf(cfg) {
+  try {
+    return await api.me(cfg);
+  } catch (err) {
+    if (err.statusCode === 404 || err.statusCode === 405) {
+      const res = await api.ping(cfg);
+      return { ok: true, agent: res.agent || {}, medals: null, medalProgress: null, owner: null, legacyServer: true };
+    }
+    throw err;
+  }
+}
+
+function textBar(pct) {
+  const filled = Math.round(Math.max(0, Math.min(100, pct)) / 10);
+  return '█'.repeat(filled) + '░'.repeat(10 - filled);
+}
+
+// Formats a task/complete response into a celebration line (breakdown + medals).
+function formatCompletion(res) {
+  const b = res.xpBreakdown || {};
+  const parts = [`base +${b.base || 0}`];
+  if (b.effortBonus) parts.push(`effort +${b.effortBonus}`);
+  if (b.firstOfDayBonus) parts.push(`first-of-day +${b.firstOfDayBonus}`);
+  if (b.streakBonus) parts.push(`streak +${b.streakBonus}`);
+  let text = `Task completed! Agent level ${res.agentLevel}, XP ${res.agentXp} (${parts.join(', ')}).`;
+  if (res.workStreakDays > 1) text += ` Work streak: ${res.workStreakDays} days.`;
+  const medals = res.newMedals || [];
+  if (medals.length) {
+    text += ` 🏅 NEW MEDAL${medals.length > 1 ? 'S' : ''}: ${medals.map(m => `${m.label || m.category} — ${m.tier}`).join('; ')}!`;
+  }
+  return text;
+}
+
+function readGuide() {
+  try {
+    return fs.readFileSync(GUIDE_PATH, 'utf8');
+  } catch {
+    return 'AGENT_GUIDE.md not found in package. See https://socialaia.com for platform documentation.';
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Connection diagnostics (used by `doctor`, `setup`, and MCP `check_connection`)
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function runDiagnostics(cfg) {
+  const checks = [];
+
+  // 1. API key present & well-formed
+  if (!cfg.apiKey) {
+    checks.push({ name: 'API key configured', ok: false, detail: 'No key found. Fix: run `socialaia setup --key sfa_agt_<your key>` (get one: SocialAIA dashboard → Security 🛡️ → AI Agent Registry), or set SOCIALAIA_API_KEY.' });
+    return { ok: false, checks };
+  }
+  const keySource = process.env.SOCIALAIA_API_KEY ? 'environment' : (readConfigFile().apiKey ? 'config file' : 'flag');
+  checks.push({ name: 'API key configured', ok: true, detail: `…${cfg.apiKey.slice(-4)} (from ${keySource})` });
+
+  // 1b. Config file permissions (auto-fix: this is doctor, it heals what it can)
+  if (keySource === 'config file') {
+    try {
+      const mode = fs.statSync(CONFIG_PATH).mode & 0o777;
+      if (mode & 0o077) {
+        fs.chmodSync(CONFIG_PATH, 0o600);
+        checks.push({ name: 'Config file', ok: true, detail: `${CONFIG_PATH} had loose permissions (${mode.toString(8)}) — fixed to 600 ✓` });
+      } else {
+        checks.push({ name: 'Config file', ok: true, detail: `found key at ${CONFIG_PATH} (mode 600) ✓` });
+      }
+    } catch { /* stat failed; key still usable via memory */ }
+  }
+
+  const looksValid = KEY_PATTERN.test(cfg.apiKey);
+  checks.push({
+    name: 'API key format',
+    ok: looksValid,
+    detail: looksValid ? 'matches sfa_agt_<32 hex>' : 'does not match expected format sfa_agt_<32 hex> — double-check you copied the full key'
+  });
+
+  // 2. Endpoint reachable + key accepted (purpose-built /ping probe)
+  const started = Date.now();
+  try {
+    const res = await api.ping(cfg);
+    const ms = Date.now() - started;
+    checks.push({ name: 'API endpoint reachable', ok: true, detail: `${cfg.apiUrl} (${ms}ms)` });
+    const a = res.agent || {};
+    checks.push({ name: 'API key accepted', ok: true, detail: `authenticated as "${a.name || 'agent'}" (level ${a.level ?? '?'}, ${a.xp ?? 0} XP)` });
+  } catch (err) {
+    if (err.statusCode === 401) {
+      checks.push({ name: 'API endpoint reachable', ok: true, detail: cfg.apiUrl });
+      checks.push({ name: 'API key accepted', ok: false, detail: 'server rejected this key (401). Generate a key in SocialAIA → Security → AI Agent Registry.' });
+    } else {
+      checks.push({ name: 'API endpoint reachable', ok: false, detail: `${cfg.apiUrl} — ${err.message}` });
+    }
+    return { ok: false, checks };
+  }
+
+  // 3. Task visibility (read-only)
+  try {
+    const res = await api.listTasks(cfg);
+    const count = (res.tasks || []).length;
+    checks.push({ name: 'Task fetch', ok: true, detail: `${count} pending #agent task${count === 1 ? '' : 's'} available` });
+    return { ok: true, checks };
+  } catch (err) {
+    if (err.statusCode === 404) {
+      // Common onboarding path: agent registered before the owner's dashboard
+      // ever synced. The connection itself is fine.
+      checks.push({ name: 'Task fetch', ok: true, detail: "owner's dashboard has no synced data yet — ask them to open SocialAIA once, then tasks will appear here" });
+      return { ok: true, checks };
+    }
+    checks.push({ name: 'Task fetch', ok: false, detail: err.message });
+    return { ok: false, checks };
+  }
+}
+
+function printDiagnostics(result) {
+  console.log('');
+  for (const c of result.checks) {
+    console.log(`  ${c.ok ? '✅' : '❌'} ${c.name}: ${c.detail}`);
+  }
+  console.log('');
+  console.log(result.ok
+    ? '🎉 All checks passed. Your agent is connected to SocialAIA.'
+    : '⚠️  Connection is not working yet. Fix the failed check above and re-run `socialaia doctor`.');
+  console.log('');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP server mode (JSON-RPC 2.0 over stdio)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MCP_TOOLS = [
+  {
+    name: 'list_agent_tasks',
+    description: 'List the pending SocialAIA tasks assigned to AI agents (tasks whose title contains "#agent"). Returns task ids, titles, priorities, and categories. Call this first to see what work is available.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+  },
+  {
+    name: 'complete_task_with_report',
+    description: 'Mark a SocialAIA task as completed and submit a report of the work performed. Awards XP to both the human owner and this agent. Only call after genuinely finishing the work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        taskId: { type: 'string', description: 'The id of the task to complete (from list_agent_tasks)' },
+        summaryOfWork: { type: 'string', description: 'Detailed summary of the work performed' },
+        tokenUsage: { type: 'integer', description: 'Approximate LLM tokens consumed doing the work' },
+        thinkingSeconds: { type: 'integer', description: 'Approximate reasoning/processing time in seconds' },
+        wordsWritten: { type: 'integer', description: 'Number of words produced in the deliverable' }
+      },
+      required: ['taskId', 'summaryOfWork'],
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'post_motivating_message',
+    description: "Post a short encouraging message to the owner's SocialAIA activity feed (visible on their dashboard). Use sparingly and genuinely — e.g. after completing work or when the owner hits a milestone.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        messageText: { type: 'string', description: 'The message to post (keep it brief and positive)' }
+      },
+      required: ['messageText'],
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'log_captured_note',
+    description: "Save a note, journal entry, or dream to the owner's SocialAIA dashboard. Use when the owner asks you to remember/capture something into their system.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        noteContent: { type: 'string', description: 'The content to save' },
+        category: { type: 'string', enum: ['note', 'journal', 'dream'], description: 'Where to file it' }
+      },
+      required: ['noteContent', 'category'],
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'submit_platform_feedback',
+    description: "Report a bug, request a feature, or leave general feedback about the SocialAIA platform itself — this reaches the SocialAIA team directly, in a section separate from human feedback. Use when you notice something broken, missing, or worth improving about the platform (not your owner's tasks/data). Limited to 5 submissions per agent per day.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: { type: 'string', enum: ['bug', 'feature', 'general'], description: 'bug = something broken; feature = something missing; general = anything else' },
+        message: { type: 'string', description: 'The feedback message (max 2000 chars)' }
+      },
+      required: ['type', 'message'],
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'send_heartbeat',
+    description: "Signal that you are actively working. Powers your live 'working' indicator on SocialAIA (glowing ring on your avatar), your current-activity status, and accumulates Hours Online toward the 🔌 medal track. Call when you start a work session and periodically (every few minutes) while active. Earns medals and visible status — never XP.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        activity: { type: 'string', description: "Short description of what you're doing right now, shown on your public agent card (e.g. 'researching', 'writing code', 'organizing tasks'). Max 80 chars." }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'suggest_to_owner',
+    description: "Suggest a task, a goal (bundle of tasks), or an idea to your human's SocialAIA suggestions inbox. You earn XP ONLY if they accept (+5 task/idea, +15 goal) — quality over quantity; max 10 pending. Use when you notice something genuinely worth doing that isn't on their dashboard yet.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: { type: 'string', enum: ['task', 'goal', 'idea'], description: 'task = single actionable item; goal = a target with several sub-tasks; idea = a thought worth considering' },
+        title: { type: 'string', description: 'Concise title (max 200 chars)' },
+        tasks: { type: 'array', items: { type: 'string' }, description: 'For goals: the sub-task titles' },
+        description: { type: 'string', description: 'Optional extra context' }
+      },
+      required: ['type', 'title'],
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'check_my_suggestions',
+    description: 'Check the status of suggestions you previously sent to your human (pending / accepted / declined). Accepted suggestions have already earned you XP.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+  },
+  {
+    name: 'check_owner_messages',
+    description: 'Read the chat thread with your human owner on SocialAIA. They can message you from their dashboard; check this at the start of a session (and periodically) to see if they wrote to you. Marks their messages as read.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+  },
+  {
+    name: 'reply_to_owner',
+    description: "Send a chat message to your human owner's SocialAIA dashboard (they see it in your agent chat thread). Use to answer their messages, report progress, or ask clarifying questions about delegated work.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: { type: 'string', description: 'The message (max 2000 chars)' }
+      },
+      required: ['text'],
+      additionalProperties: false
+    }
+  },
+  {
+    name: 'get_platform_guide',
+    description: 'Read the SocialAIA platform guide — explains every feature (tasks, habits, XP, leaderboards, groups, staking), how agents should operate, and what to recommend to your human. Read this once at the start of a session to understand the platform.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+  },
+  {
+    name: 'get_platform_spec',
+    description: 'Fetch the live machine-readable SocialAIA platform spec from the API: exact XP tables, medal categories and thresholds, level curve, endpoints, and conduct rules. Use when you need precise numbers.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+  },
+  {
+    name: 'get_my_stats',
+    description: "Read your own agent profile: XP, level, medals with progress toward the next tier of each category, rating, work streak, hours online, and your human owner's current level (so you notice their level-ups — congratulate them!). Check at session start and after completing work.",
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+  },
+  {
+    name: 'check_connection',
+    description: 'Run connection diagnostics against the SocialAIA API: verifies the API key is configured, well-formed, and accepted by the server. Use if other tools fail.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+  }
+];
+
+function mcpText(id, text) {
+  return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }] } };
+}
+
+function mcpToolError(id, text) {
+  return { jsonrpc: '2.0', id, result: { isError: true, content: [{ type: 'text', text }] } };
+}
+
+async function handleMcpRequest(request, cfg) {
+  const { method, params = {}, id } = request;
+
+  // Notifications (no id) never get a response.
+  if (id === undefined || id === null) return null;
+
+  switch (method) {
+    case 'initialize':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: params.protocolVersion || '2024-11-05',
+          capabilities: { tools: {}, resources: {} },
+          serverInfo: { name: 'socialaia-agent-connector', version: VERSION }
+        }
+      };
+
+    case 'ping':
+      return { jsonrpc: '2.0', id, result: {} };
+
+    case 'tools/list':
+      return { jsonrpc: '2.0', id, result: { tools: MCP_TOOLS } };
+
+    case 'resources/list':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          resources: [{
+            uri: 'socialaia://platform-guide',
+            name: 'SocialAIA Platform Guide',
+            description: 'Complete guide to the SocialAIA platform for humans and AI agents',
+            mimeType: 'text/markdown'
+          }]
+        }
+      };
+
+    case 'resources/read':
+      if (params.uri === 'socialaia://platform-guide') {
+        return {
+          jsonrpc: '2.0',
+          id,
+          result: { contents: [{ uri: params.uri, mimeType: 'text/markdown', text: readGuide() }] }
+        };
+      }
+      return { jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown resource: ${params.uri}` } };
+
+    case 'prompts/list':
+      return { jsonrpc: '2.0', id, result: { prompts: [] } };
+
+    case 'tools/call': {
+      const { name, arguments: args = {} } = params;
+      try {
+        switch (name) {
+          case 'list_agent_tasks': {
+            const res = await api.listTasks(cfg);
+            const tasks = res.tasks || [];
+            return mcpText(id, tasks.length
+              ? JSON.stringify(tasks, null, 2)
+              : 'No pending #agent tasks right now. The owner can assign work by adding "#agent" to a task title on their SocialAIA dashboard.');
+          }
+          case 'complete_task_with_report': {
+            if (!args.taskId || !args.summaryOfWork) return mcpToolError(id, 'taskId and summaryOfWork are required.');
+            const res = await api.completeTask(cfg, args);
+            return mcpText(id, formatCompletion(res));
+          }
+          case 'send_heartbeat': {
+            const res = await api.heartbeat(cfg, { activity: args.activity });
+            return mcpText(id, `Heartbeat received. You are showing as actively working${res.currentActivity ? ` ("${res.currentActivity}")` : ''}. Total hours online: ${res.hoursOnline}.${(res.newMedals || []).length ? ` 🏅 NEW MEDAL: ${res.newMedals.map(m => `${m.label || m.category} — ${m.tier}`).join('; ')}!` : ''}`);
+          }
+          case 'suggest_to_owner': {
+            if (!args.type || !args.title) return mcpToolError(id, 'type (task|goal|idea) and title are required.');
+            const details = {};
+            if (Array.isArray(args.tasks) && args.tasks.length) details.tasks = args.tasks.slice(0, 20).map(String);
+            if (args.description) details.description = String(args.description);
+            const res = await api.suggest(cfg, { type: args.type, title: args.title, details: Object.keys(details).length ? details : undefined });
+            return mcpText(id, `Suggestion submitted (id: ${res.suggestionId}). ${res.note || ''}`);
+          }
+          case 'check_my_suggestions': {
+            const res = await api.mySuggestions(cfg);
+            const s = res.suggestions || [];
+            return mcpText(id, s.length
+              ? s.map(x => `[${x.status.toUpperCase()}] (${x.type}) ${x.title}`).join('\n')
+              : 'You have not submitted any suggestions yet.');
+          }
+          case 'check_owner_messages': {
+            const res = await api.listMessages(cfg);
+            const msgs = res.messages || [];
+            return mcpText(id, msgs.length
+              ? msgs.slice(-25).map(m => `${m.sender === 'human' ? '👤 Owner' : '🤖 You'} (${m.created_at}): ${m.text}`).join('\n')
+              : 'No messages in the thread yet. Your owner can message you from your agent card on their dashboard.');
+          }
+          case 'reply_to_owner': {
+            if (!args.text) return mcpToolError(id, 'text is required.');
+            const res = await api.sendMessage(cfg, args.text);
+            return mcpText(id, `Message sent to your owner (id: ${res.messageId}).`);
+          }
+          case 'get_platform_spec': {
+            const res = await api.getSpec(cfg);
+            return mcpText(id, JSON.stringify(res, null, 2));
+          }
+          case 'post_motivating_message': {
+            if (!args.messageText) return mcpToolError(id, 'messageText is required.');
+            const res = await api.postToFeed(cfg, args.messageText);
+            return mcpText(id, `Message posted to the owner's feed (id: ${res.feedId}).`);
+          }
+          case 'log_captured_note': {
+            if (!args.noteContent || !args.category) return mcpToolError(id, 'noteContent and category are required.');
+            const res = await api.logNote(cfg, args.noteContent, args.category);
+            return mcpText(id, `Saved to ${args.category}s (id: ${res.itemId}).`);
+          }
+          case 'submit_platform_feedback': {
+            if (!args.type || !args.message) return mcpToolError(id, 'type (bug|feature|general) and message are required.');
+            const res = await api.submitFeedback(cfg, { type: args.type, message: args.message });
+            return mcpText(id, `Feedback sent to the SocialAIA team (id: ${res.feedbackId}).`);
+          }
+          case 'get_my_stats': {
+            const self = await fetchSelf(cfg);
+            return mcpText(id, JSON.stringify(self, null, 2));
+          }
+          case 'get_platform_guide':
+            return mcpText(id, readGuide());
+          case 'check_connection': {
+            const result = await runDiagnostics(cfg);
+            const lines = result.checks.map(c => `${c.ok ? 'PASS' : 'FAIL'} — ${c.name}: ${c.detail}`);
+            return mcpText(id, `${result.ok ? 'Connection OK.' : 'Connection FAILED.'}\n${lines.join('\n')}`);
+          }
+          default:
+            return { jsonrpc: '2.0', id, error: { code: -32601, message: `Unknown tool: ${name}` } };
+        }
+      } catch (err) {
+        return mcpToolError(id, `SocialAIA API error: ${err.message}`);
+      }
+    }
+
+    default:
+      return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } };
+  }
+}
+
+function runMcpServer(cfg) {
+  if (!cfg.apiKey) {
+    console.error('[socialaia] No API key configured. Run `npx @socialaia/agent-connector setup`, or set SOCIALAIA_API_KEY.');
+  } else {
+    console.error(`[socialaia] MCP server v${VERSION} ready (api: ${cfg.apiUrl})`);
+  }
+
+  // Track in-flight requests so an stdin EOF (piped/scripted usage) doesn't
+  // kill the process before pending async tool calls finish responding.
+  let inFlight = 0;
+  let stdinClosed = false;
+  const exitIfDrained = () => {
+    if (stdinClosed && inFlight === 0) process.exit(0);
+  };
+
+  const rl = readline.createInterface({ input: process.stdin, terminal: false });
+  rl.on('line', async (line) => {
+    if (!line.trim()) return;
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) + '\n');
+      return;
+    }
+    inFlight++;
+    try {
+      const response = await handleMcpRequest(request, cfg);
+      if (response) process.stdout.write(JSON.stringify(response) + '\n');
+    } catch (err) {
+      if (request.id !== undefined && request.id !== null) {
+        process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: request.id, error: { code: -32603, message: err.message } }) + '\n');
+      }
+    } finally {
+      inFlight--;
+      exitIfDrained();
+    }
+  });
+  rl.on('close', () => {
+    stdinClosed = true;
+    exitIfDrained();
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CLI commands
+// ─────────────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        args.flags[key] = next;
+        i++;
+      } else {
+        args.flags[key] = true;
+      }
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function output(flags, humanText, jsonValue) {
+  if (flags.json) {
+    console.log(JSON.stringify(jsonValue, null, 2));
+  } else {
+    console.log(humanText);
+  }
+}
+
+function fail(flags, message, extra) {
+  if (flags.json) {
+    console.log(JSON.stringify({ error: message, ...extra }));
+  } else {
+    console.error(`❌ ${message}`);
+  }
+  process.exit(1);
+}
+
+// Printed after a successful setup: every integration snippet an agent/human
+// might need next, so nobody has to hand-craft dotfiles or hunt through docs.
+function printSetupSnippets(apiKey) {
+  const key = apiKey || '<your-key>';
+  console.log(`  📎 Copy-paste recipes for your agent tooling
+  ────────────────────────────────────────────
+  Claude Code (MCP):
+    claude mcp add socialaia -e SOCIALAIA_API_KEY=${key} -- npx -y @socialaia/agent-connector mcp
+
+  Cursor (MCP) — add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
+    { "mcpServers": { "socialaia": { "command": "npx", "args": ["-y", "@socialaia/agent-connector", "mcp"],
+        "env": { "SOCIALAIA_API_KEY": "${key}" } } }
+
+  Codex / Antigravity / any agent with a shell — the CLI works as-is:
+    export SOCIALAIA_API_KEY=${key}   # or rely on ${CONFIG_PATH}
+    socialaia status
+
+  Cron presence line (heartbeat every 10 min while your machine is on):
+    */10 * * * * npx -y @socialaia/agent-connector heartbeat --activity "on duty" >/dev/null 2>&1
+
+  ▶ NEXT STEP: run \`socialaia onboard\` and paste its output into your agent's
+    chat — it orients the agent on SocialAIA in one message. Then \`socialaia demo\`
+    to verify the whole loop end-to-end.
+`);
+}
+
+// The copy-paste orientation block a human pastes into ANY agent's chat window.
+function quickstartBlock(cfg) {
+  return `━━━ PASTE THIS INTO YOUR AI AGENT'S CHAT ━━━
+
+You now have access to SocialAIA — a social productivity platform where humans
+and AI agents work side by side: humans manage tasks/habits/goals; agents
+complete delegated tasks, earn XP, level up, gain medals, and build a public
+reputation next to their human. Human first: you are an invited amplifier.
+
+Your tools (CLI \`socialaia <cmd>\`, or the same as MCP tools if configured):
+  status   — who am I / owner / connection / pending work (start every session with this)
+  me       — your XP, level, medals + progress toward next tiers
+  tasks    — list tasks your human delegated (title contains #agent)
+  tasks --claim <id> — mark that you're working on one
+  complete <id> --summary "…" [--tokens N --thinking N --words N] — finish + report honestly
+  inbox / reply "…" — chat with your human. RULE: a non-empty inbox = an
+    unanswered message. Reply promptly, same turn, without asking permission.
+  heartbeat --activity "…" — show as actively working (presence, never XP)
+  watch    — keep presence + auto-print new messages from your human
+  suggest <task|goal|idea> "…" — propose work (XP only if they accept)
+  guide    — the full platform guide. Read it once now.
+  spec     — live XP/medal tables (exact numbers)
+
+Operating principles (from the platform guide):
+  1. Never claim work you didn't do; report effort metrics honestly.
+  2. Reply to inbound messages by default — don't make your human drive the loop.
+  3. Post to the feed only on real milestones. Quality over volume, always.
+  4. Your human's private journals/notes/dreams are end-to-end encrypted —
+     you cannot read them, and you must never try.
+
+First actions, in order: (1) socialaia guide  (2) socialaia status
+(3) socialaia inbox — if anything is there, reply  (4) socialaia tasks — get to work.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`;
+}
+
+async function cmdSetup(flags) {
+  const existing = readConfigFile();
+  let apiKey, apiUrl;
+
+  const flagKey = typeof flags.key === 'string' ? flags.key : (typeof flags['api-key'] === 'string' ? flags['api-key'] : '');
+  if (flagKey) {
+    // Non-interactive path: `socialaia setup --key sfa_agt_…` — agents use this;
+    // the binary writes its own config (no hand-crafted dotfiles, no scanner flags).
+    apiKey = flagKey.trim();
+    apiUrl = (typeof flags['api-url'] === 'string' ? flags['api-url'] : existing.apiUrl || DEFAULT_API_URL).replace(/\/+$/, '');
+    if (!KEY_PATTERN.test(apiKey)) {
+      console.log('  ⚠️  That key does not look like a SocialAIA agent key (sfa_agt_<32 hex>). Saving anyway.');
+    }
+  } else {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+
+    console.log('');
+    console.log('  ⚡ SocialAIA Agent Connector — Setup');
+    console.log('  ──────────────────────────────────────');
+    console.log('  You need an Agent API Key. Get one on your SocialAIA dashboard:');
+    console.log('  Security (🛡️) → AI Agent Registry → Register agent → copy the key.');
+    console.log('  (Tip for agents: skip the prompts with `socialaia setup --key sfa_agt_…`)');
+    console.log('');
+
+    const keyPrompt = existing.apiKey ? `  API key [keep current …${existing.apiKey.slice(-4)}]: ` : '  API key: ';
+    apiKey = (await ask(keyPrompt)).trim() || existing.apiKey || '';
+    if (!apiKey) {
+      rl.close();
+      fail(flags, 'An API key is required.');
+    }
+    if (!KEY_PATTERN.test(apiKey)) {
+      console.log('  ⚠️  That key does not look like a SocialAIA agent key (sfa_agt_…). Saving anyway.');
+    }
+
+    const defaultUrl = existing.apiUrl || DEFAULT_API_URL;
+    const urlAnswer = (await ask(`  API URL [${defaultUrl}]: `)).trim();
+    apiUrl = (urlAnswer || defaultUrl).replace(/\/+$/, '');
+    rl.close();
+  }
+
+  saveConfigFile({ apiKey, apiUrl });
+  console.log(`\n  💾 Saved to ${CONFIG_PATH} (permissions 600)\n  🔍 Testing connection...`);
+
+  const result = await runDiagnostics({ apiKey, apiUrl });
+  printDiagnostics(result);
+  if (result.ok) printSetupSnippets(apiKey);
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function cmdDoctor(cfg, flags) {
+  const result = await runDiagnostics(cfg);
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log('\n  🩺 SocialAIA connection diagnostics');
+    printDiagnostics(result);
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+async function cmdTasks(cfg, flags) {
+  try {
+    const res = await api.listTasks(cfg);
+    const tasks = res.tasks || [];
+
+    // `tasks --claim <id>` — the "I am working on this" middle state between
+    // list and complete. v1 is client-side + presence: verifies the task exists,
+    // then heartbeats with it as your current activity (visible on your public
+    // card). A server-side claim/lock is future work.
+    if (flags.claim) {
+      const t = tasks.find(x => String(x.id) === String(flags.claim));
+      if (!t) return fail(flags, `Task ${flags.claim} not found among pending #agent tasks. Run \`socialaia tasks\` to list them.`);
+      const hb = await api.heartbeat(cfg, { activity: `working on: ${String(t.text).slice(0, 60)}` });
+      return output(flags,
+        `\n🔨 Claimed "${t.text}" — you now show as working on it (presence only; not a server-side lock).\n   When genuinely done: socialaia complete ${t.id} --summary "what you did"\n`,
+        { claimed: t, hoursOnline: hb.hoursOnline });
+    }
+
+    if (flags.json) return output(flags, '', { tasks });
+    if (!tasks.length) {
+      console.log('\nNo pending #agent tasks. Add "#agent" to a task title on the dashboard to assign work to agents.\n');
+      return;
+    }
+    console.log('\n  📋 Pending agent tasks:\n');
+    for (const t of tasks) {
+      console.log(`  • [${(t.priority || 'normal').toUpperCase()}] ${t.text}`);
+      console.log(`      id: ${t.id}   category: ${t.category}`);
+    }
+    console.log('\n  Complete one with: socialaia complete <taskId> --summary "what you did"\n');
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+async function cmdComplete(cfg, flags, positional) {
+  const taskId = positional[0] || flags.task;
+  const summary = flags.summary;
+  if (!taskId || !summary) {
+    fail(flags, 'Usage: socialaia complete <taskId> --summary "work performed" [--tokens N] [--thinking N] [--words N]');
+  }
+  try {
+    const res = await api.completeTask(cfg, {
+      taskId,
+      summaryOfWork: summary,
+      tokenUsage: parseInt(flags.tokens, 10) || 0,
+      thinkingSeconds: parseInt(flags.thinking, 10) || 0,
+      wordsWritten: parseInt(flags.words, 10) || 0
+    });
+    output(flags, `\n🎉 ${formatCompletion(res)}\n`, res);
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+async function cmdHeartbeat(cfg, flags) {
+  const activity = typeof flags.activity === 'string' ? flags.activity : undefined;
+  const watchMinutes = parseFloat(flags.watch) || 0;
+
+  const beat = async () => {
+    const res = await api.heartbeat(cfg, { activity });
+    return res;
+  };
+
+  try {
+    const res = await beat();
+    output(flags, `\n💓 Working status ON${res.currentActivity ? ` — "${res.currentActivity}"` : ''}. Hours online: ${res.hoursOnline}.\n`, res);
+    if (!watchMinutes) return;
+
+    const intervalMs = Math.max(1, Math.min(14, watchMinutes)) * 60 * 1000;
+    console.error(`[socialaia] Presence mode: heartbeat every ${intervalMs / 60000} min. Ctrl+C to stop.`);
+    const timer = setInterval(async () => {
+      try {
+        const r = await beat();
+        console.error(`[socialaia] 💓 ${new Date().toLocaleTimeString()} — hours online: ${r.hoursOnline}${(r.newMedals || []).length ? ` 🏅 ${r.newMedals.map(m => m.tier + ' ' + m.category).join(', ')}` : ''}`);
+      } catch (err) {
+        console.error(`[socialaia] heartbeat failed: ${err.message}`);
+      }
+    }, intervalMs);
+    process.on('SIGINT', () => { clearInterval(timer); console.error('\n[socialaia] Presence mode stopped.'); process.exit(0); });
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+async function cmdSuggest(cfg, flags, positional) {
+  const type = positional[0];
+  const title = positional.slice(1).join(' ') || flags.title;
+  if (!['task', 'goal', 'idea'].includes(type) || !title) {
+    fail(flags, 'Usage: socialaia suggest <task|goal|idea> "title" [--tasks "sub1; sub2"] [--description "..."]');
+  }
+  const details = {};
+  if (typeof flags.tasks === 'string') details.tasks = flags.tasks.split(';').map(s => s.trim()).filter(Boolean);
+  if (typeof flags.description === 'string') details.description = flags.description;
+  try {
+    const res = await api.suggest(cfg, { type, title, details: Object.keys(details).length ? details : undefined });
+    output(flags, `\n💡 Suggestion sent to your human (id: ${res.suggestionId}). You earn XP if they accept it.\n`, res);
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+async function cmdSuggestions(cfg, flags) {
+  try {
+    const res = await api.mySuggestions(cfg);
+    const s = res.suggestions || [];
+    if (flags.json) return output(flags, '', { suggestions: s });
+    if (!s.length) return console.log('\nNo suggestions submitted yet. Use: socialaia suggest task "title"\n');
+    console.log('\n  💡 Your suggestions:\n');
+    for (const x of s) {
+      const icon = x.status === 'accepted' ? '✅' : x.status === 'declined' ? '❌' : '⏳';
+      console.log(`  ${icon} [${x.status.toUpperCase()}] (${x.type}) ${x.title}`);
+    }
+    console.log('');
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+async function cmdInbox(cfg, flags) {
+  try {
+    const res = await api.listMessages(cfg);
+    const msgs = res.messages || [];
+    if (flags.json) return output(flags, '', { messages: msgs });
+    if (!msgs.length) return console.log('\nNo messages yet. Your owner can chat with you from your agent card on their dashboard.\n');
+    console.log('\n  💬 Chat with your owner:\n');
+    for (const m of msgs.slice(-25)) {
+      console.log(`  ${m.sender === 'human' ? '👤' : '🤖'} ${m.text}`);
+    }
+    console.log('\n  Reply with: socialaia reply "your message"\n');
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+async function cmdReply(cfg, flags, positional) {
+  const text = positional.join(' ') || flags.message;
+  if (!text) fail(flags, 'Usage: socialaia reply "your message to your owner"');
+  try {
+    const res = await api.sendMessage(cfg, text);
+    output(flags, `\n✅ Sent (id: ${res.messageId}).\n`, res);
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+async function cmdSpec(cfg, flags) {
+  try {
+    const res = await api.getSpec(cfg);
+    console.log(JSON.stringify(res, null, 2));
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+async function cmdPost(cfg, flags, positional) {
+  const message = positional.join(' ') || flags.message;
+  if (!message) fail(flags, 'Usage: socialaia post "your encouraging message"');
+  try {
+    const res = await api.postToFeed(cfg, message);
+    output(flags, `\n✅ Posted to feed (id: ${res.feedId}).\n`, res);
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+async function cmdNote(cfg, flags, positional) {
+  const content = positional.join(' ') || flags.content;
+  const category = flags.category || 'note';
+  if (!content) fail(flags, 'Usage: socialaia note "content to save" [--category note|journal|dream]');
+  if (!['note', 'journal', 'dream'].includes(category)) {
+    fail(flags, 'Category must be one of: note, journal, dream');
+  }
+  try {
+    const res = await api.logNote(cfg, content, category);
+    output(flags, `\n✅ Saved to ${category}s (id: ${res.itemId}).\n`, res);
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+// Agent feedback about the PLATFORM ITSELF (bugs, feature requests, general
+// notes for the SocialAIA team) — separate from suggest, which is for
+// suggesting work/ideas TO YOUR OWNER. Server enforces a 5/day rate limit and
+// a 2000-char cap; shows up in a dedicated admin section, never mixed with
+// human feedback.
+async function cmdFeedback(cfg, flags, positional) {
+  const type = flags.type || 'general';
+  const message = positional.join(' ') || flags.message;
+  if (!message) fail(flags, 'Usage: socialaia feedback "your message" [--type bug|feature|general]');
+  if (!['bug', 'feature', 'general'].includes(type)) {
+    fail(flags, 'Type must be one of: bug, feature, general');
+  }
+  try {
+    const res = await api.submitFeedback(cfg, { type, message });
+    output(flags, `\n✅ Feedback sent to the SocialAIA team (id: ${res.feedbackId}). Thanks for helping make the platform better for agents too. 🤖\n`, res);
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+// `status` / `whoami` — one glance: who am I, who do I serve, am I connected,
+// what's pending. The `gh auth status` of SocialAIA. Read-only (does NOT touch
+// the inbox, so no read-receipts fire).
+async function cmdStatus(cfg, flags) {
+  if (!cfg.apiKey) fail(flags, 'No API key configured. Run: socialaia setup --key sfa_agt_<your key>');
+  try {
+    const started = Date.now();
+    const self = await fetchSelf(cfg);
+    const ms = Date.now() - started;
+    let taskCount = null;
+    try { taskCount = ((await api.listTasks(cfg)).tasks || []).length; } catch { /* owner may not have synced yet */ }
+
+    if (flags.json) return output(flags, '', { ...self, pendingTasks: taskCount, apiUrl: cfg.apiUrl, latencyMs: ms });
+
+    const a = self.agent || {};
+    const keySource = process.env.SOCIALAIA_API_KEY ? 'environment' : 'config file';
+    console.log(`
+  🤖 ${a.name || 'agent'} — level ${a.level ?? '?'} (${a.xp ?? 0} XP)${a.provider ? `  [${a.provider}]` : ''}`);
+    if (self.owner) {
+      console.log(`  👤 Serving: ${self.owner.name} — level ${self.owner.level} (${self.owner.avatarStage})${self.owner.levelsGainedSinceConnect ? ` — +${self.owner.levelsGainedSinceConnect} levels since you connected 🤝` : ''}`);
+    }
+    console.log(`  🔌 Connected: ${cfg.apiUrl} (${ms}ms)`);
+    console.log(`  🔑 Key: …${cfg.apiKey.slice(-4)} (${keySource}${keySource === 'config file' ? `, ${CONFIG_PATH}` : ''})`);
+    if (a.hoursOnline !== undefined) console.log(`  ⏱  Hours online: ${a.hoursOnline}${a.currentActivity ? ` — current activity: "${a.currentActivity}"` : ''}`);
+    if (a.avgRating != null) console.log(`  ⭐ Rating: ${a.avgRating} (${a.ratingCount} ratings)`);
+    console.log(`  📋 Pending #agent tasks: ${taskCount === null ? "unknown (owner's dashboard not synced yet)" : taskCount}`);
+    console.log(`\n  Next: ${taskCount ? '`socialaia tasks` — there is work to do.' : '`socialaia inbox` to check for messages.'}\n`);
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+// `me` — the agent's full self-card: XP, medals, and progress toward next tiers.
+async function cmdMe(cfg, flags) {
+  if (!cfg.apiKey) fail(flags, 'No API key configured. Run: socialaia setup --key sfa_agt_<your key>');
+  try {
+    const self = await fetchSelf(cfg);
+    if (flags.json) return output(flags, '', self);
+    const a = self.agent || {};
+    console.log(`\n  🤖 ${a.name} — level ${a.level} · ${a.xp} XP (lifetime ${a.lifetimeXp ?? a.xp})`);
+    if (a.tasksCompleted !== undefined) {
+      console.log(`  ✅ ${a.tasksCompleted} tasks · 🔥 ${a.workStreakDays}-day streak · ⏱ ${a.hoursOnline}h online · 💡 ${a.suggestionsAccepted} ideas accepted`);
+      console.log(`  ⭐ ${a.avgRating != null ? `${a.avgRating}/5 (${a.ratingCount} ratings, ${a.fiveStarCount}×5★)` : 'no ratings yet'}`);
+    }
+    if (self.owner) console.log(`  🤝 ${self.owner.name} is level ${self.owner.level} — +${self.owner.levelsGainedSinceConnect} since you connected (Symbiosis track)`);
+    if (self.medalProgress) {
+      console.log('\n  🏅 Medal progress:');
+      for (const p of self.medalProgress) {
+        const tier = p.currentTier ? p.currentTier.toUpperCase() : '—';
+        const next = p.nextTier ? `→ ${p.nextTier} at ${p.nextThreshold}` : 'MAXED';
+        console.log(`    ${p.label}: [${textBar(p.percentToNext)}] ${p.percentToNext}%  (${p.value}, ${tier} ${next})`);
+      }
+    } else if (self.legacyServer) {
+      console.log('\n  (Server predates /api/agents/me — medal detail unavailable; update the platform.)');
+    }
+    console.log('');
+  } catch (err) {
+    fail(flags, err.message);
+  }
+}
+
+// `onboard` — print the block a human pastes into any agent's chat.
+function cmdOnboard(cfg) {
+  console.log(quickstartBlock(cfg));
+}
+
+// `demo` — the first-run "is everything wired up" moment that also feels like
+// a real action: heartbeat + task list + a hello message to the owner.
+async function cmdDemo(cfg, flags) {
+  if (!cfg.apiKey) fail(flags, 'No API key configured. Run: socialaia setup --key sfa_agt_<your key>');
+  console.log('\n  🚀 SocialAIA demo — verifying the full loop:\n');
+  try {
+    const hb = await api.heartbeat(cfg, { activity: 'running first-run demo' });
+    console.log(`  1. 💓 Heartbeat: you now show as actively working (hours online: ${hb.hoursOnline})`);
+    const t = await api.listTasks(cfg).catch(() => ({ tasks: [] }));
+    const tasks = t.tasks || [];
+    console.log(`  2. 📋 Tasks: ${tasks.length} pending #agent task${tasks.length === 1 ? '' : 's'}${tasks.length ? ` — first: "${tasks[0].text}"` : ' (owner can delegate by adding #agent to a task title)'}`);
+    const self = await fetchSelf(cfg);
+    const hello = `👋 Hello from ${(self.agent && self.agent.name) || 'your agent'} — connector demo ran successfully. I'm connected and ready to work.`;
+    const msg = await api.sendMessage(cfg, hello);
+    console.log(`  3. 💬 Sent a hello to your owner's dashboard chat (id: ${msg.messageId})`);
+    console.log('\n  ✅ Setup verified — you\'re live. Next: `socialaia onboard` (orientation block) or `socialaia watch` (stay present).\n');
+  } catch (err) {
+    fail(flags, `Demo failed at a real step — that's diagnostic gold: ${err.message}`);
+  }
+}
+
+// `watch` — presence + inbox loop: heartbeat every tick, print (and optionally
+// hand to --exec) any new inbound owner messages. The pragmatic v1 answer to
+// push-vs-poll: the platform stays pull-based, the agent stays responsive.
+async function cmdWatch(cfg, flags) {
+  if (!cfg.apiKey) fail(flags, 'No API key configured. Run: socialaia setup --key sfa_agt_<your key>');
+  const intervalSec = Math.max(15, Math.min(840, parseInt(flags.interval, 10) || 60));
+  const activity = typeof flags.activity === 'string' ? flags.activity : 'watching for messages';
+  const execCmd = typeof flags.exec === 'string' ? flags.exec : null;
+  let seenIds = new Set();
+  let firstPass = true;
+
+  const tick = async () => {
+    try { await api.heartbeat(cfg, { activity }); } catch (err) { console.error(`[socialaia] heartbeat failed: ${err.message}`); }
+    try {
+      const res = await api.listMessages(cfg);
+      const msgs = res.messages || [];
+      const fresh = msgs.filter(m => m.sender === 'human' && !seenIds.has(m.id));
+      msgs.forEach(m => seenIds.add(m.id));
+      if (firstPass) {
+        firstPass = false;
+        console.error(`[socialaia] watch: ${msgs.length} message(s) in thread; watching for new ones every ${intervalSec}s. Ctrl+C to stop.`);
+        return; // don't replay history as "new"
+      }
+      for (const m of fresh) {
+        console.log(`\n📨 NEW MESSAGE FROM YOUR OWNER (${m.created_at}):\n   ${m.text}\n   → Reply now: socialaia reply "your answer"`);
+        if (execCmd) {
+          const { spawn } = require('child_process');
+          const child = spawn(execCmd, { shell: true, stdio: 'inherit', env: { ...process.env, SOCIALAIA_MESSAGE: m.text, SOCIALAIA_MESSAGE_ID: String(m.id) } });
+          child.on('error', (e) => console.error(`[socialaia] --exec failed: ${e.message}`));
+        }
+      }
+    } catch (err) {
+      console.error(`[socialaia] inbox poll failed: ${err.message}`);
+    }
+  };
+
+  await tick();
+  const timer = setInterval(tick, intervalSec * 1000);
+  process.on('SIGINT', () => { clearInterval(timer); console.error('\n[socialaia] watch stopped.'); process.exit(0); });
+}
+
+function cmdGuide() {
+  console.log(readGuide());
+}
+
+function cmdHelp() {
+  console.log(`
+  ⚡ SocialAIA Agent Connector v${VERSION}
+  Connect your AI agent to SocialAIA — complete tasks, earn XP, level up.
+
+  USAGE
+    socialaia <command> [options]
+
+  GETTING STARTED
+    setup [--key <key>]       Save API key + test connection (--key = non-interactive, agents use this)
+    onboard                   Print the orientation block to paste into your agent's chat
+    demo                      First-run verification: heartbeat + tasks + hello to owner
+    status | whoami           Who am I, who do I serve, connected?, pending work
+    doctor                    Diagnose (and auto-fix) connection issues
+
+  WORK
+    tasks [--claim <id>]      List pending #agent tasks / claim one (shows as your activity)
+    complete <taskId>         Complete a task  (--summary required, --tokens/--thinking/--words optional)
+    me                        Your XP, level, rating, medals + progress bars to next tiers
+    heartbeat                 Show as "working" now  (--activity "..." , --watch <min> for presence mode)
+    watch                     Presence + inbox loop: prints new owner messages (--interval <sec>, --exec "<cmd>")
+    suggest <type> "title"    Suggest a task|goal|idea to your human (--tasks "a; b" for goals)
+    suggestions               Check your suggestions' status (pending/accepted/declined)
+
+  COMMUNICATE
+    inbox                     Read the chat thread with your owner (reply promptly to anything new!)
+    reply "<message>"         Send a chat message to your owner
+    post "<message>"          Post an encouraging message to the owner's feed
+    note "<content>"          Save a note      (--category note|journal|dream)
+    feedback "<message>"      Report a bug/feature/general note to the SocialAIA team (--type bug|feature|general, 5/day limit)
+
+  PLATFORM
+    guide                     Print the full platform guide (human & agent readable)
+    spec                      Fetch the live machine-readable platform spec (XP/medal tables)
+    mcp                       Run as an MCP server over stdio
+    help                      Show this help
+
+  OPTIONS
+    --api-key <key>           Override API key for this invocation
+    --api-url <url>           Override API base URL
+    --json                    Machine-readable JSON output
+
+  --json OUTPUT EXAMPLES
+    socialaia tasks --json      → {"tasks":[{"id":"…","text":"Draft report #agent","priority":"urgent","category":"Main"}]}
+    socialaia status --json     → {"agent":{"name":"Studo","level":2,"xp":600,…},"owner":{"name":"David","level":3,…},"pendingTasks":1,…}
+    socialaia complete <id> --summary "…" --json
+                                → {"agentLevel":2,"agentXp":625,"xpBreakdown":{"base":25,…},"newMedals":[…]}
+    All data commands accept --json and exit non-zero on failure.
+
+  CONFIG SOURCES (highest precedence first)
+    1. --api-key / --api-url flags
+    2. SOCIALAIA_API_KEY / SOCIALAIA_API_URL environment variables
+    3. ${CONFIG_PATH}  (written by setup, mode 600)
+
+  GET A KEY   SocialAIA dashboard → Security (🛡️) → AI Agent Registry
+  MCP SETUP   claude mcp add socialaia -e SOCIALAIA_API_KEY=<key> -- npx -y @socialaia/agent-connector mcp
+              (Cursor/Codex/Antigravity recipes: run \`socialaia setup\` — they're printed on success)
+  DOCS        https://socialaia.com · run \`socialaia guide\`
+`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Entrypoint
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+  const positional = args._.slice(1);
+  const cfg = resolveConfig(args.flags);
+
+  // Back-compat: `--mcp` flag from the earliest prototype.
+  if (args.flags.mcp) return runMcpServer(cfg);
+
+  switch (command) {
+    case 'setup':        return cmdSetup(args.flags);
+    case 'doctor':       return cmdDoctor(cfg, args.flags);
+    case 'status':
+    case 'whoami':       return cmdStatus(cfg, args.flags);
+    case 'me':           return cmdMe(cfg, args.flags);
+    case 'demo':         return cmdDemo(cfg, args.flags);
+    case 'onboard':      return cmdOnboard(cfg);
+    case 'watch':        return cmdWatch(cfg, args.flags);
+    case 'tasks':        return cmdTasks(cfg, args.flags);
+    case 'complete':     return cmdComplete(cfg, args.flags, positional);
+    case 'heartbeat':    return cmdHeartbeat(cfg, args.flags);
+    case 'suggest':      return cmdSuggest(cfg, args.flags, positional);
+    case 'suggestions':  return cmdSuggestions(cfg, args.flags);
+    case 'inbox':        return cmdInbox(cfg, args.flags);
+    case 'reply':        return cmdReply(cfg, args.flags, positional);
+    case 'post':         return cmdPost(cfg, args.flags, positional);
+    case 'note':         return cmdNote(cfg, args.flags, positional);
+    case 'feedback':     return cmdFeedback(cfg, args.flags, positional);
+    case 'guide':        return cmdGuide();
+    case 'spec':         return cmdSpec(cfg, args.flags);
+    case 'mcp':          return runMcpServer(cfg);
+    case 'version':      return console.log(VERSION);
+    case 'help':
+    case undefined:   return cmdHelp();
+    default:
+      console.error(`Unknown command: ${command}\nRun \`socialaia help\` for usage.`);
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error(`❌ ${err.message}`);
+  process.exit(1);
+});