clearctx 3.0.0

package/bin/setup.js

@@ -0,0 +1,929 @@
+#!/usr/bin/env node
+
+/**
+ * ╔══════════════════════════════════════════════════════════════╗
+ * ║  clearctx — Interactive Setup CLI                 ║
+ * ╚══════════════════════════════════════════════════════════════╝
+ *
+ * Beautiful interactive installer using @clack/prompts.
+ * Lets users choose between local and global installation.
+ *
+ * Usage:
+ *   ctx-setup                       Interactive setup wizard
+ *   ctx-setup --global              Global install (all projects)
+ *   ctx-setup --local               Local install (this project only)
+ *   ctx-setup --global --yes        Non-interactive global install + guide (CI mode)
+ *   ctx-setup --local --yes         Non-interactive local install + guide (CI mode)
+ *   ctx-setup --global --no-guide   Global install without CLAUDE.md guide
+ *   ctx-setup --uninstall           Interactive uninstall
+ *   ctx-setup --uninstall --global  Non-interactive global uninstall
+ *   ctx-setup --migrate             Clean up old CLAUDE.md injection
+ *   ctx-setup --postinstall-hint    (Internal) Print hint after npm install
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+// The name of the MCP server entry in config files
+const MCP_SERVER_NAME = 'multi-session';
+
+// Markers used to identify our section in CLAUDE.md
+// (so we can detect duplicates and remove on uninstall)
+const CLAUDE_MD_START_MARKER = '<!-- clearctx:start -->';
+const CLAUDE_MD_END_MARKER = '<!-- clearctx:end -->';
+
+// ============================================================================
+// Strategy Guide Content — appended to CLAUDE.md when user opts in
+// ============================================================================
+
+// This teaches the main Claude session how to orchestrate team workers.
+// Wrapped in markers so we can find and remove it later.
+//
+// IMPORTANT: This content MUST stay in sync with docs/ORCHESTRATOR-CLAUDE.md.
+// When updating rules or adding features, update BOTH files.
+// Failure to sync caused all test runs 1-6 to use stale orchestrator rules.
+const STRATEGY_CONTENT = `
+${CLAUDE_MD_START_MARKER}
+
+## Multi-Session MCP Available (clearctx)
+
+You have access to a Multi-Session MCP server (\`mcp__multi-session__*\` tools) that lets you spawn and coordinate multiple Claude Code sessions working in parallel.
+
+IMPORTANT: When the user asks you to build something complex (more than 2 related tasks), use the multi-session system to parallelize the work instead of doing everything yourself.
+
+## Step 0: Verify Your Tools
+
+Before starting ANY orchestration work, call \`server_version()\` to verify you're running the latest MCP tools. If the response shows a version mismatch, tell the user to restart Claude Code before proceeding — stale tools cause phantom failures.
+
+## How to Orchestrate
+
+### Rule 0: Define shared conventions BEFORE spawning workers
+Before spawning workers, fill in the CONVENTION CHECKLIST. Either publish as an artifact (\`shared-conventions\`) or embed in every worker's prompt.
+
+=== CONVENTION CHECKLIST (define every item before spawning) ===
+- [ ] Response format: e.g., \`{ data: <result> }\`
+- [ ] Error format: e.g., \`{ error: <message> }\`
+- [ ] Status codes: create=201, read=200, update=200, delete=200, notFound=404, badRequest=400, conflict=409
+- [ ] Naming: e.g., snake_case for DB columns, camelCase for JS variables
+- [ ] File paths: relative only, never absolute
+- [ ] Enum/status values: list EXACT strings (e.g., "pending", "in_progress", "completed" — NOT "Pending" or "InProgress")
+- [ ] Boolean handling: true/false vs 1/0 — pick one, specify it
+- [ ] Date format: ISO 8601 strings, Unix timestamps, or other — specify which
+- [ ] Audit/log action names: exact strings (e.g., "created" vs "create" vs "CREATE")
+- [ ] Shared column names: list exact DB column names for tables multiple workers reference
+
+Missing even ONE item causes convention mismatches that the orchestrator then has to fix manually — which violates Rule 6.
+
+NEVER assume workers will independently agree on conventions — they won't.
+
+### Rule 1: You are the ORCHESTRATOR — not the implementer
+- Plan the work, spawn workers, monitor progress
+- Do NOT implement code yourself when you can delegate
+- Do NOT create project foundation files (package.json, db.js, app.js, server.js) yourself — spawn a setup worker for Phase 0
+- Do NOT read full outputs from workers — check artifacts and contract status instead
+
+**Phase 0: Foundation Setup** — If the project needs shared infrastructure (database, app skeleton, package.json), spawn a \`setup\` worker FIRST. Wait for its \`project-foundation\` artifact before spawning other workers. Do NOT create these files yourself.
+
+### Rule 2: Use team_spawn for multi-session work
+IMPORTANT: Spawn ALL independent workers in a SINGLE message with multiple tool calls. This makes them run in parallel.
+
+### Rule 3: Workers talk to each other — not through you
+- Workers have team_ask, team_send_message, team_broadcast tools
+- They can publish and read artifacts directly
+- You should NOT relay messages between them
+- If workers need each other's output, tell them to use team_ask
+- Note: team_ask is a **fallback** for unexpected ambiguity. In well-orchestrated projects where you provide all context upfront, team_ask may never be called — this is the ideal case.
+
+### Rule 4: Post-Phase Verification (MANDATORY)
+After ALL workers in a phase complete, BEFORE spawning the next phase, STOP and fill in this checklist:
+
+=== PHASE GATE CHECKPOINT (use phase_gate tool before EVERY team_spawn after Phase 0) ===
+
+Instead of manually running 4 separate tool calls, use the \`phase_gate\` tool which does ALL checks in one call:
+
+\`\`\`
+mcp__multi-session__phase_gate({
+  phase_completing: "Phase 0: Foundation",
+  phase_starting: "Phase 1: Routes",
+  expected_artifacts: ["project-foundation", "shared-conventions"],
+  expected_idle: ["setup"],
+  expected_readers: { "shared-conventions": ["api-dev", "db-dev"] }
+})
+\`\`\`
+
+The tool automatically:
+1. Checks all expected artifacts exist
+2. Validates artifact content and tracks the read as "orchestrator"
+3. Verifies all previous-phase workers are idle
+4. Confirms expected consumers actually read the artifacts
+5. Convention completeness advisory — warns if \`shared-conventions\` artifact is missing or incomplete (checks all 10 checklist keys: responseFormat, errorFormat, statusCodes, namingConventions, filePaths, enumValues, booleanHandling, dateFormat, auditActions, sharedColumnNames)
+
+Check 5 is advisory (WARNING, not a gate failure) — the gate still passes/fails based on checks 1-4. But convention warnings are highly visible and should be addressed.
+
+Returns a structured pass/fail report with recommendation.
+PROCEED ONLY IF the report says ALL CHECKS PASSED.
+
+**ENFORCED:** \`team_spawn\` will return an error if \`phase_gate\` was not called between spawn batches. The first batch (Phase 0) is free; every subsequent batch requires a passing \`phase_gate\` call first.
+
+Count your phases upfront. If you have N phases, fill in this checkpoint exactly N-1 times (between every adjacent pair of phases). Skipping verification for later phases is the #1 cause of test failures.
+
+Only intervene in workers when a session is BLOCKED or FAILED.
+Do NOT verify worker output by reading files directly — check artifacts instead.
+
+### Rule 5: Always tell workers to publish artifacts
+Every worker prompt should include instructions to:
+1. Check inbox before starting (\`team_check_inbox\`) — **ENFORCED**: artifact and contract tools are blocked until workers call this
+2. Use \`team_ask\` to communicate with teammates (NOT you)
+3. Publish output as artifacts (\`artifact_publish\`) — auto-registers file ownership from \`files\`/\`filesCreated\`/\`filesModified\` in data
+4. Broadcast completion (\`team_broadcast\`)
+5. ~~Update status to idle when done~~ — **AUTO-MANAGED**: status is automatically set to "active" on spawn and "idle" on stop/kill. Workers only need \`team_update_status\` for custom statuses like "blocked".
+6. Follow shared conventions defined in Rule 0 (include them in the prompt or reference the conventions artifact)
+
+### Rule 6: Don't fix worker code yourself (pragmatic exception for trivial fixes)
+
+=== FIX PROTOCOL (when you must fix worker code directly) ===
+STOP. Before editing any file a worker created, call \`check_file_owner({ file: "path/to/file" })\` to verify ownership, then answer these questions:
+
+1. Is this fix ≤ 3 lines?
+   NO → \`send_message\` to worker or spawn fix-worker. Do NOT fix yourself.
+   YES → continue to step 2.
+
+2. Is the worker done (idle status in \`team_roster\`)?
+   NO → \`send_message\` to worker. Do NOT fix yourself.
+   YES → continue to step 3.
+
+3. Make the fix.
+
+4. Broadcast: \`team_broadcast({ from: "orchestrator", content: "Fixed [file]:[lines] — [description of change]" })\`
+
+5. Re-publish: If the fix changes data in a published artifact, call \`artifact_publish\` to update it.
+
+NEVER skip steps 4-5. Unannounced fixes cause downstream workers to use stale assumptions.
+
+If the failure is due to convention mismatch (wrong response format, etc.), that's YOUR fault — update the conventions and notify the affected workers.
+
+### Rule 7: Verify artifacts between phases (Phase Gates)
+Use the PHASE GATE CHECKPOINT from Rule 4 between every pair of phases. This is the same checklist — Rule 7 reinforces that it applies to EVERY phase transition, not just the first one.
+
+After all workers finish, verify they consumed shared artifacts:
+\`\`\`
+mcp__multi-session__artifact_readers({ artifactId: "shared-conventions" })
+\`\`\`
+This shows which workers actually read the conventions. If a worker is missing, they may have ignored the shared contract.
+
+NEVER trust a worker's self-reported completion — verify the artifact exists yourself.
+
+## Auto-Behaviors (v2.7.0)
+
+These happen automatically — no action needed from you or the workers:
+- **Roster summary injection**: \`team_spawn\`, \`phase_gate\`, and \`send_message\` (to team workers) responses include a compact roster line: \`[Team: worker-a=active, worker-b=idle]\`
+- **Auto-status management**: Workers are set to "active" on spawn and "idle" when their session stops/is killed
+- **Inbox enforcement**: Workers are blocked from using artifact/contract tools until they call \`team_check_inbox\`
+- **File ownership tracking**: \`artifact_publish\` auto-registers file ownership from \`files\`/\`filesCreated\`/\`filesModified\` arrays in artifact data
+- **Convention completeness check**: \`phase_gate\` warns if \`shared-conventions\` artifact is missing or has incomplete fields
+
+## Quick Reference (68 tools)
+
+| You want to... | Use this tool |
+|----------------|---------------|
+| Verify tools before starting | \`server_version\` |
+| Build a multi-person project | \`team_spawn\` (multiple in parallel) |
+| Run a single isolated task | \`delegate_task\` |
+| Check who's working on what | \`team_roster\` (also auto-injected in spawn/gate/message responses) |
+| See published outputs | \`artifact_list\` |
+| See task completion status | \`contract_list\` |
+| Verify phase completion | \`phase_gate\` |
+| Send a correction to a worker | \`send_message\` to that session |
+| Check who read an artifact | \`artifact_readers\` |
+| Check file ownership (Rule 6) | \`check_file_owner\` |
+| Register file ownership | \`register_files\` |
+| Clean up between runs | \`team_reset\` |
+
+### When NOT to Delegate
+- Simple tasks (< 5 min, < 3 files) — do it yourself
+- Just reading/exploring — use Read, Grep, Glob directly
+- Tightly coupled changes — must happen atomically
+
+### Resetting Between Runs
+Call \`team_reset({ confirm: true })\` to clean up all team state between orchestration runs. This clears artifacts, contracts, roster, and messages.
+
+${CLAUDE_MD_END_MARKER}
+`;
+
+// ============================================================================
+// Helpers (kept from original — zero dependencies)
+// ============================================================================
+
+/**
+ * Figure out whether this package was installed globally or locally,
+ * and return the right MCP server command config.
+ *
+ * Global install: the `ctx-mcp` binary is on PATH, so we can just call it.
+ * Local install: we need an absolute path to bin/mcp.js.
+ */
+function detectMcpCommand() {
+  // __dirname is the "bin/" folder where this script lives
+  // One level up is the package root
+  const packageRoot = path.resolve(__dirname, '..');
+  const mcpBin = path.join(packageRoot, 'bin', 'mcp.js');
+
+  // Check if ctx-mcp is likely on PATH (global install)
+  // We do this by checking if the package is inside a global node_modules
+  const isGlobal = packageRoot.includes(path.join('node_modules', 'clearctx'))
+    && (
+      packageRoot.includes(path.join('lib', 'node_modules')) // npm global on Linux/Mac
+      || packageRoot.includes(path.join('AppData', 'Roaming', 'npm')) // npm global on Windows
+      || packageRoot.includes('nvm') // nvm managed
+      || packageRoot.includes('.volta') // volta managed
+    );
+
+  if (isGlobal) {
+    // Global install — ctx-mcp should be on PATH
+    return { command: 'ctx-mcp' };
+  } else {
+    // Local or dev install — use absolute path to bin/mcp.js
+    return { command: 'node', args: [mcpBin] };
+  }
+}
+
+/**
+ * Read a JSON file safely. Returns empty object if file doesn't exist
+ * or has invalid JSON.
+ */
+function readJsonSafe(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write JSON to a file with nice formatting.
+ * Creates parent directories if they don't exist.
+ */
+function writeJson(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * Register MCP server globally in ~/.claude.json.
+ * This is a simple upsert — adds our entry to the top-level "mcpServers" key.
+ * Safe and idempotent: won't overwrite if already present.
+ *
+ * @param {string} configPath — Path to ~/.claude.json
+ * @returns {boolean} true if we added/updated, false if already existed
+ */
+function registerGlobal(configPath) {
+  const config = readJsonSafe(configPath);
+
+  // Make sure the mcpServers object exists
+  if (!config.mcpServers) {
+    config.mcpServers = {};
+  }
+
+  // Skip if already registered (don't overwrite existing config)
+  if (config.mcpServers[MCP_SERVER_NAME]) {
+    return false; // already existed
+  }
+
+  // Add our MCP server entry
+  config.mcpServers[MCP_SERVER_NAME] = detectMcpCommand();
+  writeJson(configPath, config);
+  return true; // newly added
+}
+
+/**
+ * Register MCP server locally by creating .mcp.json in the project root.
+ * This is the standard Claude Code local MCP config format.
+ * Uses absolute path to the bin/mcp.js file.
+ *
+ * @param {string} projectDir — The project root directory (usually cwd)
+ * @returns {boolean} true if we created/updated, false if already existed
+ */
+function registerLocal(projectDir) {
+  const mcpJsonPath = path.join(projectDir, '.mcp.json');
+  const config = readJsonSafe(mcpJsonPath);
+
+  // Make sure the mcpServers object exists
+  if (!config.mcpServers) {
+    config.mcpServers = {};
+  }
+
+  // Skip if already registered
+  if (config.mcpServers[MCP_SERVER_NAME]) {
+    return false; // already existed
+  }
+
+  // Add our MCP server entry with absolute path
+  config.mcpServers[MCP_SERVER_NAME] = detectMcpCommand();
+  writeJson(mcpJsonPath, config);
+  return true; // newly added
+}
+
+/**
+ * Remove MCP server from global config (~/.claude.json).
+ * Cleans both the top-level mcpServers key and legacy per-project format.
+ *
+ * @param {string} configPath — Path to ~/.claude.json
+ * @returns {boolean} true if something was removed
+ */
+function removeGlobal(configPath) {
+  if (!fs.existsSync(configPath)) return false;
+
+  const config = readJsonSafe(configPath);
+  let removed = false;
+
+  // Remove from top-level mcpServers
+  if (config.mcpServers && config.mcpServers[MCP_SERVER_NAME]) {
+    delete config.mcpServers[MCP_SERVER_NAME];
+    removed = true;
+  }
+
+  // Also clean up legacy format: projects."<path>".mcpServers
+  if (config.projects) {
+    for (const projPath of Object.keys(config.projects)) {
+      const proj = config.projects[projPath];
+      if (proj && proj.mcpServers && proj.mcpServers[MCP_SERVER_NAME]) {
+        delete proj.mcpServers[MCP_SERVER_NAME];
+        removed = true;
+      }
+    }
+  }
+
+  if (removed) {
+    writeJson(configPath, config);
+  }
+
+  return removed;
+}
+
+/**
+ * Remove MCP server from local .mcp.json.
+ *
+ * @param {string} projectDir — The project root directory
+ * @returns {boolean} true if something was removed
+ */
+function removeLocal(projectDir) {
+  const mcpJsonPath = path.join(projectDir, '.mcp.json');
+  if (!fs.existsSync(mcpJsonPath)) return false;
+
+  const config = readJsonSafe(mcpJsonPath);
+  let removed = false;
+
+  if (config.mcpServers && config.mcpServers[MCP_SERVER_NAME]) {
+    delete config.mcpServers[MCP_SERVER_NAME];
+    removed = true;
+  }
+
+  if (removed) {
+    // If mcpServers is now empty, delete the file entirely
+    if (Object.keys(config.mcpServers).length === 0) {
+      fs.unlinkSync(mcpJsonPath);
+    } else {
+      writeJson(mcpJsonPath, config);
+    }
+  }
+
+  return removed;
+}
+
+/**
+ * Append the orchestrator guide to a CLAUDE.md file.
+ * Safe: checks for existing markers to avoid duplicates.
+ * Never deletes or replaces existing content.
+ *
+ * @param {'global'|'local'} scope — Where to write the guide
+ * @returns {{ path: string, created: boolean, skipped: boolean }}
+ */
+function addGuide(scope) {
+  // Choose the right CLAUDE.md path based on scope
+  const claudeMdPath = scope === 'global'
+    ? path.join(os.homedir(), '.claude', 'CLAUDE.md')
+    : path.join(process.cwd(), 'CLAUDE.md');
+
+  const result = { path: claudeMdPath, created: false, skipped: false };
+
+  // Read existing content (if any)
+  let existing = '';
+  if (fs.existsSync(claudeMdPath)) {
+    existing = fs.readFileSync(claudeMdPath, 'utf-8');
+  }
+
+  // Check if our section already exists
+  if (existing.includes(CLAUDE_MD_START_MARKER)) {
+    // Extract current content between markers and compare with latest
+    const startIdx = existing.indexOf(CLAUDE_MD_START_MARKER);
+    const endIdx = existing.indexOf(CLAUDE_MD_END_MARKER);
+    if (startIdx !== -1 && endIdx !== -1) {
+      const currentContent = existing.slice(startIdx, endIdx + CLAUDE_MD_END_MARKER.length).trim();
+      const newContent = STRATEGY_CONTENT.trim();
+      if (currentContent === newContent) {
+        result.skipped = true;
+        return result;
+      }
+      // Content is stale — replace our section, preserve user's other content
+      const before = existing.slice(0, startIdx).trimEnd();
+      const after = existing.slice(endIdx + CLAUDE_MD_END_MARKER.length).trimStart();
+      const updated = (before ? before + '\n\n' : '') + newContent + (after ? '\n\n' + after : '\n');
+      fs.writeFileSync(claudeMdPath, updated, 'utf-8');
+      result.updated = true;
+      return result;
+    }
+    // Malformed markers — skip to be safe
+    result.skipped = true;
+    return result;
+  }
+
+  // Create directory if needed
+  const dir = path.dirname(claudeMdPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // Append or create the file
+  if (existing) {
+    // Append to existing file — preserves all existing content
+    fs.appendFileSync(claudeMdPath, '\n' + STRATEGY_CONTENT, 'utf-8');
+  } else {
+    // Create new file
+    fs.writeFileSync(claudeMdPath, STRATEGY_CONTENT.trim() + '\n', 'utf-8');
+    result.created = true;
+  }
+
+  return result;
+}
+
+/**
+ * Remove the orchestrator guide section from a CLAUDE.md file.
+ * Finds content between our markers and removes it cleanly.
+ * If the file becomes empty after removal, deletes it.
+ *
+ * @param {string} claudeMdPath — Path to the CLAUDE.md file
+ * @returns {boolean} true if content was removed
+ */
+function removeGuideFromFile(claudeMdPath) {
+  if (!fs.existsSync(claudeMdPath)) return false;
+
+  let content = fs.readFileSync(claudeMdPath, 'utf-8');
+  if (!content.includes(CLAUDE_MD_START_MARKER)) return false;
+
+  // Find the markers and remove everything between them (inclusive)
+  const startIdx = content.indexOf(CLAUDE_MD_START_MARKER);
+  const endIdx = content.indexOf(CLAUDE_MD_END_MARKER);
+
+  if (startIdx === -1 || endIdx === -1) return false;
+
+  // Extract content before and after our section
+  const before = content.slice(0, startIdx).trimEnd();
+  const after = content.slice(endIdx + CLAUDE_MD_END_MARKER.length).trimStart();
+
+  // Rebuild the content
+  content = before + (after ? '\n\n' + after : '') + '\n';
+
+  // If the file is now effectively empty, delete it
+  if (content.trim().length === 0) {
+    fs.unlinkSync(claudeMdPath);
+  } else {
+    fs.writeFileSync(claudeMdPath, content, 'utf-8');
+  }
+
+  return true;
+}
+
+/**
+ * Run migration — clean up old CLAUDE.md injection from both global and local files.
+ *
+ * @returns {{ global: boolean, local: boolean }} which files were cleaned
+ */
+function runMigration() {
+  const globalPath = path.join(os.homedir(), '.claude', 'CLAUDE.md');
+  const localPath = path.join(process.cwd(), 'CLAUDE.md');
+
+  return {
+    global: removeGuideFromFile(globalPath),
+    local: removeGuideFromFile(localPath),
+  };
+}
+
+// ============================================================================
+// Postinstall Hint — silent, safe, runs after `npm install`
+// ============================================================================
+
+/**
+ * Called by npm's postinstall script.
+ * Does two things:
+ *   1. Silently registers MCP server globally (safe/additive, never overwrites)
+ *   2. Prints a short stderr hint telling users to run ctx-setup
+ *
+ * Does NOT touch CLAUDE.md — that requires interactive user consent.
+ */
+function runPostinstallHint() {
+  // npm suppresses stdout, so we use stderr for messages
+  const write = (msg) => process.stderr.write(msg + '\n');
+
+  try {
+    const configPath = path.join(os.homedir(), '.claude.json');
+
+    // Auto-register MCP server globally (safe — only adds if not present)
+    const added = registerGlobal(configPath);
+
+    if (added) {
+      write('');
+      write('  clearctx: MCP server registered globally.');
+      write('  Run "ctx-setup" to configure orchestrator guide.');
+      write('');
+    } else {
+      // Already registered — check if CLAUDE.md guide needs updating
+      write('');
+      const guideResult = addGuide('global');
+      if (guideResult.updated) {
+        write('  clearctx: Orchestrator guide updated in ~/.claude/CLAUDE.md');
+        write('  Restart Claude Code to use the latest rules.');
+      } else {
+        write('  clearctx: Already configured and up to date.');
+      }
+      write('');
+    }
+  } catch {
+    // If auto-config fails (permissions, etc.), print manual hint
+    write('');
+    write('  clearctx installed! Run "ctx-setup" to configure.');
+    write('');
+  }
+}
+
+// ============================================================================
+// Interactive Setup — beautiful CLI using @clack/prompts
+// ============================================================================
+
+/**
+ * Run the interactive setup wizard.
+ * Uses @clack/prompts for a beautiful terminal UI.
+ *
+ * @param {object} flags — CLI flags from argv
+ */
+async function runInteractiveSetup(flags) {
+  // Load @clack/prompts and picocolors
+  // (require here so postinstall-hint doesn't need them)
+  const clack = require('@clack/prompts');
+  const pc = require('picocolors');
+
+  // Read package version for the header
+  let version = '2.x';
+  try {
+    const pkg = require('../package.json');
+    version = pkg.version || version;
+  } catch {
+    // fallback to default
+  }
+
+  // Determine if we're in non-interactive (CI) mode
+  const nonInteractive = flags.yes === true;
+
+  // Determine scope from flags (if provided)
+  let scope = flags.global ? 'global' : flags.local ? 'local' : null;
+
+  // Determine guide preference from flags
+  let wantGuide = flags['no-guide'] ? false : (flags.yes ? true : null);
+
+  // ── Start the interactive UI ──
+  clack.intro(pc.cyan(`Claude Multi-Session System v${version}`));
+
+  // ── Step 1: Choose scope (global vs local) ──
+  if (!scope) {
+    if (nonInteractive) {
+      // Default to global in CI mode
+      scope = 'global';
+    } else {
+      const scopeChoice = await clack.select({
+        message: 'How would you like to install?',
+        options: [
+          {
+            value: 'global',
+            label: 'Global',
+            hint: 'Available in all projects',
+          },
+          {
+            value: 'local',
+            label: 'Local',
+            hint: 'This project only',
+          },
+        ],
+      });
+
+      // User cancelled (Ctrl+C)
+      if (clack.isCancel(scopeChoice)) {
+        clack.cancel('Setup cancelled.');
+        process.exit(0);
+      }
+
+      scope = scopeChoice;
+    }
+  }
+
+  // ── Step 2: Register MCP server ──
+  const spin = clack.spinner();
+  spin.start(scope === 'global' ? 'Registering MCP server globally...' : 'Registering MCP server locally...');
+
+  let registered;
+  const configPath = path.join(os.homedir(), '.claude.json');
+  const localMcpJsonPath = path.join(process.cwd(), '.mcp.json');
+
+  if (scope === 'global') {
+    registered = registerGlobal(configPath);
+  } else {
+    registered = registerLocal(process.cwd());
+  }
+
+  if (registered) {
+    if (scope === 'global') {
+      spin.stop(pc.green('MCP server registered globally in ~/.claude.json'));
+    } else {
+      spin.stop(pc.green('MCP server registered locally in .mcp.json'));
+    }
+  } else {
+    spin.stop(pc.yellow('MCP server already registered — skipped.'));
+  }
+
+  // ── Step 3: Check for conflicting registrations ──
+  // After global registration, check if local .mcp.json also has it
+  if (scope === 'global' && !nonInteractive) {
+    const localConfig = readJsonSafe(localMcpJsonPath);
+    if (localConfig.mcpServers && localConfig.mcpServers[MCP_SERVER_NAME]) {
+      const removeLocalChoice = await clack.confirm({
+        message: 'Local .mcp.json also has multi-session registered. Remove the local entry?',
+        initialValue: true,
+      });
+
+      if (!clack.isCancel(removeLocalChoice) && removeLocalChoice) {
+        removeLocal(process.cwd());
+        clack.log.success('Removed local .mcp.json entry.');
+      }
+    }
+  }
+
+  // After local registration, check if global config also has it
+  if (scope === 'local' && !nonInteractive) {
+    const globalConfig = readJsonSafe(configPath);
+    if (globalConfig.mcpServers && globalConfig.mcpServers[MCP_SERVER_NAME]) {
+      const removeGlobalChoice = await clack.confirm({
+        message: 'Global ~/.claude.json also has multi-session registered. Remove the global entry?',
+        initialValue: false,
+      });
+
+      if (!clack.isCancel(removeGlobalChoice) && removeGlobalChoice) {
+        removeGlobal(configPath);
+        clack.log.success('Removed global entry from ~/.claude.json');
+      }
+    }
+  }
+
+  // ── Step 4: Orchestrator guide in CLAUDE.md ──
+  // Figure out the target path and check if a file already exists there
+  const guideTargetPath = scope === 'global'
+    ? path.join(os.homedir(), '.claude', 'CLAUDE.md')
+    : path.join(process.cwd(), 'CLAUDE.md');
+  const guideDisplayPath = scope === 'global' ? '~/.claude/CLAUDE.md' : './CLAUDE.md';
+  const guideFileExists = fs.existsSync(guideTargetPath);
+  const guideAlreadyInjected = guideFileExists
+    && fs.readFileSync(guideTargetPath, 'utf-8').includes(CLAUDE_MD_START_MARKER);
+
+  if (wantGuide === null) {
+    // Tell the user what will happen before they confirm
+    if (guideAlreadyInjected) {
+      // Check if content is stale
+      const currentFile = fs.readFileSync(guideTargetPath, 'utf-8');
+      const startIdx = currentFile.indexOf(CLAUDE_MD_START_MARKER);
+      const endIdx = currentFile.indexOf(CLAUDE_MD_END_MARKER);
+      const currentContent = currentFile.slice(startIdx, endIdx + CLAUDE_MD_END_MARKER.length).trim();
+      const isStale = currentContent !== STRATEGY_CONTENT.trim();
+      if (isStale) {
+        clack.log.warn(`Orchestrator guide in ${guideDisplayPath} is outdated.`);
+        wantGuide = true; // Auto-update — addGuide handles the replacement
+      } else {
+        clack.log.info(`Orchestrator guide in ${guideDisplayPath} is up to date.`);
+        wantGuide = false;
+      }
+    } else if (guideFileExists) {
+      // File exists — reassure user their content is safe
+      clack.log.info(`Found existing ${guideDisplayPath} — your content will be preserved.`);
+      const guideChoice = await clack.confirm({
+        message: `Append orchestrator guide to ${guideDisplayPath}? (Recommended — your existing content stays intact)`,
+        initialValue: true,
+      });
+
+      if (clack.isCancel(guideChoice)) {
+        clack.cancel('Setup cancelled.');
+        process.exit(0);
+      }
+
+      wantGuide = guideChoice;
+    } else {
+      // No file yet — straightforward ask
+      const guideChoice = await clack.confirm({
+        message: `Create ${guideDisplayPath} with orchestrator guide? (Recommended)`,
+        initialValue: true,
+      });
+
+      if (clack.isCancel(guideChoice)) {
+        clack.cancel('Setup cancelled.');
+        process.exit(0);
+      }
+
+      wantGuide = guideChoice;
+    }
+  }
+
+  if (wantGuide) {
+    const guideResult = addGuide(scope);
+
+    if (guideResult.updated) {
+      clack.log.success(`Updated orchestrator guide in ${guideDisplayPath} (new rules synced)`);
+    } else if (guideResult.skipped) {
+      clack.log.info('Orchestrator guide already up to date — skipped.');
+    } else if (guideResult.created) {
+      clack.log.success(`Created ${guideDisplayPath} with orchestrator guide`);
+    } else {
+      clack.log.success(`Appended orchestrator guide to ${guideDisplayPath} (existing content preserved)`);
+    }
+  }
+
+  // ── Done! ──
+  clack.outro(pc.green('Setup complete!') + pc.dim(' Restart Claude Code to load multi-session tools.'));
+}
+
+// ============================================================================
+// Interactive Uninstall
+// ============================================================================
+
+/**
+ * Run the interactive uninstall wizard.
+ *
+ * @param {object} flags — CLI flags
+ */
+async function runUninstall(flags) {
+  const clack = require('@clack/prompts');
+  const pc = require('picocolors');
+
+  clack.intro(pc.red('Uninstall Claude Multi-Session'));
+
+  // Determine scope
+  let scope = flags.global ? 'global' : flags.local ? 'local' : flags.both ? 'both' : null;
+
+  if (!scope) {
+    const scopeChoice = await clack.select({
+      message: 'What would you like to remove?',
+      options: [
+        { value: 'global', label: 'Global', hint: 'Remove from ~/.claude.json' },
+        { value: 'local', label: 'Local', hint: 'Remove from .mcp.json' },
+        { value: 'both', label: 'Both', hint: 'Remove all registrations' },
+      ],
+    });
+
+    if (clack.isCancel(scopeChoice)) {
+      clack.cancel('Uninstall cancelled.');
+      process.exit(0);
+    }
+
+    scope = scopeChoice;
+  }
+
+  const spin = clack.spinner();
+  const configPath = path.join(os.homedir(), '.claude.json');
+
+  // Remove MCP registrations
+  spin.start('Removing MCP server registrations...');
+
+  let removedGlobal = false;
+  let removedLocal = false;
+
+  if (scope === 'global' || scope === 'both') {
+    removedGlobal = removeGlobal(configPath);
+  }
+
+  if (scope === 'local' || scope === 'both') {
+    removedLocal = removeLocal(process.cwd());
+  }
+
+  if (removedGlobal || removedLocal) {
+    const parts = [];
+    if (removedGlobal) parts.push('global (~/.claude.json)');
+    if (removedLocal) parts.push('local (.mcp.json)');
+    spin.stop(pc.green(`Removed MCP entries: ${parts.join(', ')}`));
+  } else {
+    spin.stop(pc.yellow('No MCP entries found to remove.'));
+  }
+
+  // Clean up CLAUDE.md
+  spin.start('Cleaning up CLAUDE.md...');
+
+  const migration = runMigration();
+
+  if (migration.global || migration.local) {
+    const parts = [];
+    if (migration.global) parts.push('~/.claude/CLAUDE.md');
+    if (migration.local) parts.push('./CLAUDE.md');
+    spin.stop(pc.green(`Removed orchestrator guide from: ${parts.join(', ')}`));
+  } else {
+    spin.stop(pc.dim('No orchestrator guide found in CLAUDE.md — nothing to clean.'));
+  }
+
+  clack.outro(pc.green('Uninstall complete.') + pc.dim(' Restart Claude Code to apply.'));
+}
+
+// ============================================================================
+// Main Entry Point — dispatches to the right handler
+// ============================================================================
+
+/**
+ * Main entry point.
+ * Dispatches based on CLI flags to the right handler.
+ *
+ * @param {object} flags — CLI flags
+ */
+async function run(flags = {}) {
+  // --postinstall-hint: silent, safe, runs after npm install
+  if (flags['postinstall-hint']) {
+    runPostinstallHint();
+    return;
+  }
+
+  // Legacy --postinstall flag (backwards compatibility)
+  if (flags.postinstall) {
+    runPostinstallHint();
+    return;
+  }
+
+  // --migrate: clean up old CLAUDE.md injection
+  if (flags.migrate) {
+    const clack = require('@clack/prompts');
+    const pc = require('picocolors');
+
+    clack.intro(pc.cyan('Migrate: Clean up old CLAUDE.md injection'));
+
+    const spin = clack.spinner();
+    spin.start('Scanning for old injection markers...');
+
+    const result = runMigration();
+
+    if (result.global || result.local) {
+      const parts = [];
+      if (result.global) parts.push('~/.claude/CLAUDE.md');
+      if (result.local) parts.push('./CLAUDE.md');
+      spin.stop(pc.green(`Cleaned up: ${parts.join(', ')}`));
+    } else {
+      spin.stop(pc.dim('No old injection markers found — nothing to clean.'));
+    }
+
+    clack.outro(pc.green('Migration complete.'));
+    return;
+  }
+
+  // --uninstall: interactive uninstall wizard
+  if (flags.uninstall) {
+    await runUninstall(flags);
+    return;
+  }
+
+  // Default: interactive setup wizard
+  await runInteractiveSetup(flags);
+}
+
+// ============================================================================
+// Direct invocation support (node bin/setup.js or ctx-setup)
+// ============================================================================
+
+// If this script is run directly (not required by cli.js),
+// parse flags and run the wizard.
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const flags = {};
+  for (const arg of args) {
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      flags[key] = true;
+    }
+  }
+  run(flags).catch((err) => {
+    console.error(`\n  Setup failed: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = { run };