synabun 2026.3.308 → 2026.3.310

package/CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md
+
+====================================END SYNBUN
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What is SynaBun
+
+Persistent vector memory for AI assistants — SQLite + local Transformers.js embeddings (all-MiniLM-L6-v2, 384 dims). No external services, no API keys, no Docker. Installed via `npm install -g synabun` or cloned from GitHub.
+
+## Commands
+
+```bash
+# Start everything (installs deps, builds MCP, launches Neural Interface)
+npm start                                    # runs setup.js
+
+# Neural Interface only (Express server on :3344)
+node neural-interface/server.js
+
+# Build MCP server (required after any TypeScript change)
+cd mcp-server && npm run build               # ALWAYS use npm run build, never npx tsc
+
+# Dev mode (auto-rebuild on change)
+cd mcp-server && npm run dev                 # tsx src/index.ts
+
+# Tests
+cd mcp-server && npm test                    # vitest run
+cd mcp-server && npm run test:watch          # vitest watch mode
+
+# Register MCP with Claude Code
+claude mcp add SynaBun -s user -- node "/path/to/Synabun/mcp-server/run.mjs"
+```
+
+## Architecture
+
+Two independently running processes that share one SQLite database:
+
+### MCP Server (`mcp-server/`)
+TypeScript, compiles to `dist/`. Entry point: `run.mjs` → `dist/preload.js` → `dist/index.js`. Communicates with AI tools via MCP protocol (stdio or HTTP). 72 tools across 9 groups: Memory (8), Browser (39), Whiteboard (5), Cards (5), Discord (8), Leonardo (4), Git (1), Loop (1), TicTacToe (1).
+
+- `src/index.ts` — tool registration, schema refresh, server creation
+- `src/config.ts` — env config, project detection from `claude-code-projects.json`
+- `src/types.ts` — `MemoryPayload` interface
+- `src/http.ts` — HTTP MCP transport (stateless, fresh server per request)
+- `src/services/sqlite.ts` — storage layer, vectors as Float32Array BLOBs, cosine similarity in JS
+- `src/services/local-embeddings.ts` — Transformers.js embedding generation
+- `src/services/categories.ts` — category CRUD, hierarchy, dynamic schema refresh
+- `src/tools/` — one file per tool (or per tool group with a registration function)
+
+### Neural Interface (`neural-interface/`)
+Express server (`server.js`, ~15K lines) serving a vanilla JS + Three.js frontend. 55+ REST API endpoints. Runs on port 3344.
+
+- `server.js` — monolithic Express server with all API routes, WebSocket, terminal (node-pty), Playwright browser management, session registry, loop orchestration
+- `public/index.html` — 3D force-directed graph (Three.js)
+- `public/index2d.html` — 2D canvas variant
+- `public/onboarding.html` — first-time setup wizard
+- `public/claude-chat.html` — standalone Claude Code chat page
+- `public/shared/` — modular JS/CSS (~50 files): `ui-*.js` modules, `storage.js` (server-synced state), `styles.css`, `utils.js`
+- `lib/db.js` — shared SQLite access (same DB as MCP server)
+- `lib/session-indexer.js` — conversation session indexing
+- `skins/` — theme system (CSS + JSON per skin)
+- `i18n/` — internationalization (en.json)
+- `templates/CLAUDE-template.md` — source of truth for memory rulesets injected into project CLAUDE.md files
+
+### Hooks (`hooks/claude-code/`)
+7 ESM (.mjs) lifecycle hooks for Claude Code, registered in `.claude/settings.json`:
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `session-start.mjs` | SessionStart | Greeting, boot sequence, compaction recovery, loop detection |
+| `prompt-submit.mjs` | UserPromptSubmit | Tiered recall nudges, loop iteration injection |
+| `pre-compact.mjs` | PreCompact | Transcript capture before context compaction |
+| `stop.mjs` | Stop | Combined obligations: compaction, loops, task memory, user learning |
+| `post-remember.mjs` | PostToolUse | Edit tracking, flag clearing, user learning |
+| `pre-websearch.mjs` | PreToolUse | Blocks WebSearch/WebFetch during active browser sessions |
+| `post-plan.mjs` | PostToolUse | Auto-stores plans as memories on ExitPlanMode |
+
+`shared.mjs` contains utilities used across hooks.
+
+### Skills (`skills/`)
+Claude Code slash commands with `SKILL.md` entry points and `modules/` subdirectories:
+- `synabun/` — `/synabun` command hub (brainstorm, audit, health, search)
+- `leonardo/` — `/leonardo` master media prompter (video, image, model advisor, prompt library)
+
+### Data Flow
+```
+AI tool calls remember → MCP server embeds content → SQLite stores vector + payload
+AI tool calls recall   → MCP server embeds query  → cosine similarity search → re-ranked results
+Neural Interface       → reads same SQLite DB      → renders 3D graph, REST API, WebSocket
+Hooks                  → fire on Claude Code events → inject context, enforce memory obligations
+```
+
+### Shared State
+- `data/memory.db` — single SQLite database (memories, session chunks, trash)
+- `data/ui-state.json` — Neural Interface UI state (synced via `storage.js`)
+- `data/pending-compact/` — per-session compaction flags
+- `data/pending-remember/` — per-session edit tracking flags
+- `mcp-server/data/custom-categories-{connId}.json` — per-connection category definitions
+
+## Key Patterns
+
+- **Category descriptions are routing instructions**: Claude reads all category descriptions from the MCP tool schema to decide where to store memories. Descriptions must be prescriptive rules, not vague labels.
+- **Dynamic schema refresh**: Category changes trigger `refreshCategorySchemas()` → `notifications/tools/list_changed` → Claude re-fetches tool list. No restart needed.
+- **Per-tab session isolation**: Project/model/effort state stored per-tab in sidepanel (`ui-claude-panel.js`) and per-tab via `sessionStorage` in standalone (`claude-chat.js`). Global `ui-state.json` keys are "last used" defaults only.
+- **Browser sessions**: Playwright with persistent Chromium profiles. Multi-session isolation via dedicated browser session per automation. Leonardo tools are 100% browser-based (no API key).
+- **Compaction chain**: PreCompact → flag → SessionStart injects → Claude remembers(conversations) → PostToolUse clears → Stop allows.
+- **MCP calls must be sequential**: Parallel MCP tool calls can cascade failures. Always call memory tools one at a time.
+
+## Environment
+
+- Node.js 22.5+ required (for built-in `node:sqlite`)
+- `.env` at project root — `SQLITE_DB_PATH`, `NEURAL_PORT` (default 3344), `DISCORD_BOT_TOKEN`, `DISCORD_GUILD_ID`
+- CLAUDE.md is gitignored (user-local)
+
+## Persistent Memory
+
+You have persistent vector memory via the `SynaBun` MCP server (72 tools).
+Core memory tools: remember, recall, forget, restore, reflect, memories, sync, category.
+
+### Auto-Recall
+- Session start: recall current project context
+- Topic mentioned: recall what you know
+- Before architecture decisions: recall past decisions
+- Debugging: recall similar bugs
+
+### Auto-Remember (MANDATORY)
+After ANY task (bug fix, feature, refactor, config change, investigation, architecture decision), MUST `remember` BEFORE responding.
+
+Steps:
+1. `remember` — what + why + how, appropriate category, set project, related_files, importance (5=routine, 6-7=significant, 8+=critical), and 3-5 tags
+
+`remember` returns the full UUID and accepts all fields (tags, importance) directly. No need to recall+reflect afterward.
+
+**NOT triggered by:** Simple Q&A, file reads with no findings, trivial typos.
+
+**Importance scale:** 1-2=trivial, 3-4=low, 5=normal, 6-7=significant, 8-9=critical, 10=foundational. User says "remember this" → 8+. Architecture decisions → 8+.
+
+### Response Ordering
+When finishing a task: call `remember` (and any other memory tools) **FIRST**, then write your completion summary **LAST**. Never summary-then-tools — the stop hook will block you.
+
+### Tool Quirks
+- `remember` returns the full UUID and accepts tags + importance directly.
+- `reflect` requires FULL UUID — use the one from `remember`, or `recall` to find existing memories.
+- Sequential MCP calls only — never parallel.
+
+### Plan Mode
+When in plan mode and you need clarification:
+- ALWAYS use `AskUserQuestion` to present options — never plain text questions
+- Use `ExitPlanMode` for final plan approval
+- Use `multiSelect: true` in AskUserQuestion when options aren't mutually exclusive

package/hooks/claude-code/post-plan.mjs

@@ -309,7 +309,7 @@ async function main() {
   if (toolName === 'EnterPlanMode') {
     debugLog('EnterPlanMode fired — injecting AskUserQuestion reminder');
     process.stdout.write(JSON.stringify({
-      additionalContext: `SynaBun: You are now in plan mode. When you have questions or need clarification from the user, you MUST use the \`AskUserQuestion\` tool — do NOT write questions as plain text. Load it via \`ToolSearch\` if its schema is not yet available. Use \`ExitPlanMode\` for final plan approval.\n\n**Plan file location**: Write plan files to \`${PLANS_DIR}/\` — NOT \`~/.claude/plans/\`. This avoids sensitive-file permission prompts that stall the session.`,
+      additionalContext: `SynaBun: You are now in plan mode.\n\n**CRITICAL CONSTRAINT**: Do NOT make code changes (Edit, Write, NotebookEdit). Plan mode is RESEARCH AND PLANNING ONLY. Investigate, read files, search code — then present your plan. Do NOT implement anything until the user explicitly approves the plan and you exit plan mode.\n\nWhen you have questions or need clarification, you MUST use the \`AskUserQuestion\` tool — do NOT write questions as plain text. Load it via \`ToolSearch\` if its schema is not yet available. Use \`ExitPlanMode\` for final plan approval.\n\n**Plan file location**: Write plan files to \`${PLANS_DIR}/\` — NOT \`~/.claude/plans/\`. This avoids sensitive-file permission prompts.`,
     }));
     return;
   }

package/hooks/claude-code/session-start.mjs

@@ -464,6 +464,8 @@ async function main() {
       ``,
       `If an autonomous loop was active before compaction, the Stop hook will resume it automatically. Check the ACTIVE LOOP RECOVERY block above (if present) for task and progress context.`,
       ``,
+      `**Plan files**: Write plan files to the project's \`data/plans/\` directory — NOT \`~/.claude/plans/\`. This avoids sensitive-file permission prompts that don't persist across compactions.`,
+      ``,
       `---`,
       ``,
     );

package/neural-interface/public/shared/styles.css

@@ -8925,10 +8925,10 @@
   .settings-panel {
     position: fixed;
     z-index: 300000;
-    width: 720px;
+    width: 900px;
     max-width: 95vw;
     min-width: 480px;
-    height: 500px;
+    height: 650px;
     max-height: 88vh;
     min-height: 320px;
     display: flex;

package/neural-interface/public/shared/ui-settings.js

@@ -2678,8 +2678,8 @@ export async function openSettingsModal() {
   overlay.id = 'settings-panel';
 
   // Always open centered at default size
-  overlay.style.left = Math.max(20, (window.innerWidth - 720) / 2) + 'px';
-  overlay.style.top = Math.max(48, (window.innerHeight - 500) / 2) + 'px';
+  overlay.style.left = Math.max(20, (window.innerWidth - 900) / 2) + 'px';
+  overlay.style.top = Math.max(48, (window.innerHeight - 650) / 2) + 'px';
 
   // ── Build variant tab bodies ──
   let variantTabBodies = '';

package/neural-interface/server.js

@@ -6161,9 +6161,22 @@ app.get('/api/system/backup', async (req, res) => {
     for (const f of ['ui-state.json', 'greeting-config.json', 'hook-features.json',
                       'claude-code-projects.json', 'mcp-api-key.json', 'keybinds.json', 'cli-config.json',
                       'invite-key.json', 'invite-proxy.json', 'invite-permissions.json',
-                      'loop-templates.json', 'loop-schedules.json', 'auto-backup-config.json']) {
+                      'loop-templates.json', 'loop-schedules.json', 'auto-backup-config.json',
+                      'cost-tracking.json', 'skin-config.json', 'image-favorites.json',
+                      'browser-config.json', 'browser-storage.json', 'last-session.json',
+                      'invite-sessions.json']) {
       addFile(`data/${f}`, resolve(dataDir, f));
     }
+
+    // Session history caches (dynamically named per project cwd)
+    if (existsSync(dataDir)) {
+      for (const f of readdirSync(dataDir)) {
+        if (f.startsWith('sessions-cache-') && f.endsWith('.json')) {
+          addFile(`data/${f}`, resolve(dataDir, f));
+        }
+      }
+    }
+
     addJsonDir('data/pending-remember', resolve(dataDir, 'pending-remember'));
     addJsonDir('data/pending-compact', resolve(dataDir, 'pending-compact'));
     addJsonDir('data/loop', resolve(dataDir, 'loop'));
@@ -6172,6 +6185,9 @@ app.get('/api/system/backup', async (req, res) => {
     addFile('data/custom-icons.json', resolve(dataDir, 'custom-icons.json'));
     addDirRecursive('data/custom-icons', resolve(dataDir, 'custom-icons'));
 
+    // Screenshots, whiteboard captures, staged images
+    addDirRecursive('data/images', resolve(dataDir, 'images'));
+
     // 3. mcp-server/data/
     if (existsSync(CATEGORIES_DATA_DIR)) {
       for (const f of readdirSync(CATEGORIES_DATA_DIR)) {
@@ -6209,7 +6225,19 @@ app.get('/api/system/backup', async (req, res) => {
       }
     }
 
-    // 7. SQLite database file
+    // 7. Installed skins (user-customizable themes)
+    const skinsDir = join(__dirname, 'skins');
+    if (existsSync(skinsDir)) {
+      addDirRecursive('skins', skinsDir);
+    }
+
+    // 8. Global Claude Code settings (hooks, permissions)
+    const home = process.env.USERPROFILE || process.env.HOME || '';
+    if (home) {
+      addFile('claude-settings.json', join(home, '.claude', 'settings.json'));
+    }
+
+    // 9. SQLite database file
     const dbPath = getDbPath();
     if (existsSync(dbPath)) {
       try {
@@ -6346,6 +6374,25 @@ app.post('/api/system/restore',
           writeFileSync(target, entry.getData());
           results.files.push(rel);
         }
+
+        // Installed skins → neural-interface/skins/
+        if (rel.startsWith('skins/') && rel !== 'skins/') {
+          const target = join(__dirname, rel);
+          mkdirSync(dirname(target), { recursive: true });
+          writeFileSync(target, entry.getData());
+          results.files.push(rel);
+        }
+
+        // Global Claude Code settings → ~/.claude/settings.json
+        if (rel === 'claude-settings.json') {
+          const home = process.env.USERPROFILE || process.env.HOME || '';
+          if (home) {
+            const target = join(home, '.claude', 'settings.json');
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, entry.getData());
+            results.files.push(rel);
+          }
+        }
       }
     }
 
@@ -6480,15 +6527,31 @@ function buildBackupZipToFile(destPath) {
     for (const f of ['ui-state.json', 'greeting-config.json', 'hook-features.json',
                       'claude-code-projects.json', 'mcp-api-key.json', 'keybinds.json', 'cli-config.json',
                       'invite-key.json', 'invite-proxy.json', 'invite-permissions.json',
-                      'loop-templates.json', 'loop-schedules.json']) {
+                      'loop-templates.json', 'loop-schedules.json', 'auto-backup-config.json',
+                      'cost-tracking.json', 'skin-config.json', 'image-favorites.json',
+                      'browser-config.json', 'browser-storage.json', 'last-session.json',
+                      'invite-sessions.json']) {
       addFile(`data/${f}`, resolve(dataDir, f));
     }
+
+    // Session history caches (dynamically named per project cwd)
+    if (existsSync(dataDir)) {
+      for (const f of readdirSync(dataDir)) {
+        if (f.startsWith('sessions-cache-') && f.endsWith('.json')) {
+          addFile(`data/${f}`, resolve(dataDir, f));
+        }
+      }
+    }
+
     addJsonDir('data/pending-remember', resolve(dataDir, 'pending-remember'));
     addJsonDir('data/pending-compact', resolve(dataDir, 'pending-compact'));
     addJsonDir('data/loop', resolve(dataDir, 'loop'));
     addFile('data/custom-icons.json', resolve(dataDir, 'custom-icons.json'));
     addDirRecursive('data/custom-icons', resolve(dataDir, 'custom-icons'));
 
+    // Screenshots, whiteboard captures, staged images
+    addDirRecursive('data/images', resolve(dataDir, 'images'));
+
     if (existsSync(CATEGORIES_DATA_DIR)) {
       for (const f of readdirSync(CATEGORIES_DATA_DIR)) {
         if (f.endsWith('.json')) addFile(`mcp-data/${f}`, resolve(CATEGORIES_DATA_DIR, f));
@@ -6518,6 +6581,18 @@ function buildBackupZipToFile(destPath) {
       }
     }
 
+    // Installed skins (user-customizable themes)
+    const skinsDir = join(__dirname, 'skins');
+    if (existsSync(skinsDir)) {
+      addDirRecursive('skins', skinsDir);
+    }
+
+    // Global Claude Code settings (hooks, permissions)
+    const home = process.env.USERPROFILE || process.env.HOME || '';
+    if (home) {
+      addFile('claude-settings.json', join(home, '.claude', 'settings.json'));
+    }
+
     const dbPath = getDbPath();
     if (existsSync(dbPath)) {
       try {
@@ -7548,9 +7623,9 @@ function ensureSynaBunPermissions(settings) {
   if (!settings.permissions) settings.permissions = {};
   if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
 
-  // Plan files now write to data/plans/ (project-local) instead of ~/.claude/plans/.
-  // No special Write permission needed — data/ is within the project root.
-  // Clean up legacy rule if present from older installations.
+  // Plan files write to data/plans/ (project-local) to avoid ~/.claude/ sensitive-file
+  // permission prompts. No Write permission rule needed — data/ is within project root.
+  // Clean up any stale Write(~/.claude/plans/*) rules from older installations.
   const home = process.env.USERPROFILE || process.env.HOME || '';
   const legacyPlanRule = `Write(${join(home, '.claude', 'plans', '*')})`;
   const legacyIdx = settings.permissions.allow.indexOf(legacyPlanRule);
@@ -8625,9 +8700,8 @@ app.put('/api/greeting/config/:project', (req, res) => {
 // Supports ?format=claude (default) | cursor | generic
 app.get('/api/claude-code/ruleset', (req, res) => {
   try {
-    const claudeMdPath = resolve(PROJECT_ROOT, 'CLAUDE.md');
     const templatePath = resolve(__dirname, 'templates', 'CLAUDE-template.md');
-    const sourcePath = existsSync(claudeMdPath) ? claudeMdPath : templatePath;
+    const sourcePath = templatePath;
     if (!existsSync(sourcePath)) {
       return res.status(404).json({ error: 'CLAUDE.md template not found' });
     }

package/neural-interface/templates/CLAUDE-template.md

@@ -66,7 +66,9 @@ Never store directly in parent categories.
 
 ### Plan Mode (MANDATORY)
 
-When in plan mode and you need clarification or have questions:
+**CRITICAL**: Plan mode = research and planning ONLY. Do NOT use Edit, Write, or NotebookEdit. Read files, search code, investigate — then present the plan. Do NOT implement until the user approves and you exit plan mode.
+
+When you need clarification or have questions:
 - **ALWAYS** use `AskUserQuestion` to present options — never write questions as plain text
 - Load the tool via `ToolSearch` first if its schema is not yet available
 - Structure as distinct choices (2-4 options per question, max 4 questions)
@@ -161,6 +163,12 @@ Tools: remember, recall, forget, restore, reflect, memories, sync, category_*
 
 ---
 
+## Plan Files
+
+When in plan mode, write plan files to the project's `data/plans/` directory — **NOT** `~/.claude/plans/`. The `~/.claude/` directory is treated as sensitive by Claude Code, causing repeated permission prompts that don't persist across context compactions. The `data/plans/` directory is within the project root and requires no special permissions.
+
+---
+
 ## Hook System
 
 7 Claude Code hooks in `hooks/claude-code/`, registered in `~/.claude/settings.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synabun",
-  "version": "2026.3.308",
+  "version": "2026.3.310",
   "description": "Persistent vector memory for AI assistants",
   "license": "Apache-2.0",
   "author": "The SynaBun Authors",
@@ -16,6 +16,7 @@
   "files": [
     "setup.js",
     "postinstall.js",
+    "preuninstall.js",
     "mcp-server/package.json",
     "mcp-server/dist/",
     "mcp-server/tsconfig.json",
@@ -40,7 +41,8 @@
   ],
   "scripts": {
     "start": "node setup.js",
-    "postinstall": "node postinstall.js"
+    "postinstall": "node postinstall.js",
+    "preuninstall": "node preuninstall.js"
   },
   "keywords": [
     "claude",

package/preuninstall.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+/**
+ * SynaBun — NPM preuninstall script
+ *
+ * Runs before `npm uninstall synabun`.
+ * Removes nested node_modules that cause EPERM/deep-path errors on Windows.
+ * Graceful — if cleanup fails, don't block the uninstall.
+ */
+
+import { rmSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const dirs = [
+  resolve(__dirname, 'neural-interface', 'node_modules'),
+  resolve(__dirname, 'mcp-server', 'node_modules'),
+];
+
+for (const dir of dirs) {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // Non-fatal — npm will handle remaining cleanup
+  }
+}

package/setup.js

@@ -13,7 +13,7 @@
  */
 
 import { execSync, spawn, exec } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, cpSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { platform } from 'node:os';
@@ -37,6 +37,45 @@ function warn(msg) { console.log(`  ${c.yellow}!${c.reset} ${msg}`); }
 function fail(msg) { console.log(`  ${c.red}\u2717${c.reset} ${msg}`); }
 function info(msg) { console.log(`  ${c.cyan}\u2192${c.reset} ${msg}`); }
 
+// ── Global install detection & CWD scaffold ──
+
+function isGlobalInstall() {
+  const normalized = __dirname.replace(/\\/g, '/');
+  return normalized.includes('/node_modules/synabun');
+}
+
+function isAlreadyScaffolded(dir) {
+  return existsSync(resolve(dir, 'neural-interface', 'server.js'));
+}
+
+function getLocalVersion(dir) {
+  try {
+    return JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf-8')).version || '0.0.0';
+  } catch { return '0.0.0'; }
+}
+
+function getGlobalVersion() {
+  return JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8')).version;
+}
+
+function scaffoldToCwd(targetDir) {
+  info('Scaffolding SynaBun into current directory...');
+
+  cpSync(__dirname, targetDir, {
+    recursive: true,
+    filter: (src) => {
+      const normalized = src.replace(/\\/g, '/');
+      // Skip node_modules (installed fresh by setup)
+      if (normalized.includes('/node_modules')) return false;
+      // Skip .env (generated fresh per installation)
+      if (normalized.endsWith('/.env')) return false;
+      return true;
+    },
+  });
+
+  ok(`Scaffolded to ${targetDir}`);
+}
+
 // ── Phase 1: Prerequisite checks ──
 
 function checkNodeVersion() {
@@ -209,6 +248,52 @@ function startServer() {
 // ── Main ──
 
 function main() {
+  // ── Global install: scaffold to CWD + delegate ──
+  if (isGlobalInstall()) {
+    const cwd = process.cwd();
+    const globalVer = getGlobalVersion();
+
+    console.log('');
+    console.log(`  ${c.cyan}╔═══════════════════════════════════╗${c.reset}`);
+    console.log(`  ${c.cyan}║${c.reset}                                   ${c.cyan}║${c.reset}`);
+    console.log(`  ${c.cyan}║${c.reset}   ${c.bold}${c.cyan}[██] [██]${c.reset}   ${c.bold}${c.cyan}SynaBun${c.reset}             ${c.cyan}║${c.reset}`);
+    console.log(`  ${c.cyan}║${c.reset}                                   ${c.cyan}║${c.reset}`);
+    console.log(`  ${c.cyan}║${c.reset}   ${c.dim}Persistent Vector Memory${c.reset}       ${c.cyan}║${c.reset}`);
+    console.log(`  ${c.cyan}║${c.reset}                                   ${c.cyan}║${c.reset}`);
+    console.log(`  ${c.cyan}╚═══════════════════════════════════╝${c.reset}`);
+    console.log(`           ${c.dim}synabun.ai${c.reset}`);
+    console.log('');
+
+    if (!isAlreadyScaffolded(cwd)) {
+      info(`Scaffolding SynaBun v${globalVer} into:`);
+      console.log(`  ${c.cyan}${cwd}${c.reset}`);
+      console.log('');
+      scaffoldToCwd(cwd);
+    } else {
+      const localVer = getLocalVersion(cwd);
+      if (localVer !== globalVer) {
+        info(`Updating SynaBun: ${localVer} → ${globalVer}`);
+        scaffoldToCwd(cwd);
+        ok('Updated');
+      } else {
+        ok(`SynaBun v${globalVer} up to date`);
+      }
+    }
+
+    console.log('');
+
+    // Delegate to the local copy so __dirname resolves to CWD
+    const child = spawn('node', [resolve(cwd, 'setup.js')], {
+      cwd,
+      stdio: 'inherit',
+    });
+    child.on('exit', (code) => process.exit(code ?? 0));
+    process.on('SIGINT', () => { child.kill('SIGINT'); });
+    process.on('SIGTERM', () => { child.kill('SIGTERM'); });
+    return;
+  }
+
+  // ── Local/dev install: normal flow ──
   console.log('');
   console.log(`  ${c.cyan}╔═══════════════════════════════════╗${c.reset}`);
   console.log(`  ${c.cyan}║${c.reset}                                   ${c.cyan}║${c.reset}`);