@contextstream/mcp-server 0.3.28 → 0.3.29

package/dist/index.js

@@ -487,8 +487,8 @@ function getErrorMap() {
 
 // node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
-  const { data, path: path3, errorMaps, issueData } = params;
-  const fullPath = [...path3, ...issueData.path || []];
+  const { data, path: path6, errorMaps, issueData } = params;
+  const fullPath = [...path6, ...issueData.path || []];
   const fullIssue = {
     ...issueData,
     path: fullPath
@@ -604,11 +604,11 @@ var errorUtil;
 
 // node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
-  constructor(parent, value, path3, key) {
+  constructor(parent, value, path6, key) {
     this._cachedPath = [];
     this.parent = parent;
     this.data = value;
-    this._path = path3;
+    this._path = path6;
     this._key = key;
   }
   get path() {
@@ -4082,6 +4082,7 @@ function loadConfig() {
 
 // src/client.ts
 import { randomUUID } from "node:crypto";
+import * as path3 from "node:path";
 
 // src/http.ts
 var HttpError = class extends Error {
@@ -4135,11 +4136,11 @@ var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504])
 var MAX_RETRIES = 3;
 var BASE_DELAY = 1e3;
 async function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
-async function request(config, path3, options = {}) {
+async function request(config, path6, options = {}) {
   const { apiUrl, apiKey, jwt, userAgent } = config;
-  const apiPath = path3.startsWith("/api/") ? path3 : `/api/v1${path3}`;
+  const apiPath = path6.startsWith("/api/") ? path6 : `/api/v1${path6}`;
   const url = `${apiUrl.replace(/\/$/, "")}${apiPath}`;
   const maxRetries = options.retries ?? MAX_RETRIES;
   const baseDelay = options.retryDelay ?? BASE_DELAY;
@@ -4408,8 +4409,8 @@ async function* readAllFilesInBatches(rootPath, options = {}) {
         const ext = entry.name.split(".").pop()?.toLowerCase() ?? "";
         if (!CODE_EXTENSIONS.has(ext)) continue;
         try {
-          const stat = await fs.promises.stat(fullPath);
-          if (stat.size > maxFileSize) continue;
+          const stat2 = await fs.promises.stat(fullPath);
+          if (stat2.size > maxFileSize) continue;
           const content = await fs.promises.readFile(fullPath, "utf-8");
           yield { path: relPath, content };
         } catch {
@@ -4486,21 +4487,23 @@ function writeGlobalMappings(mappings) {
   }
 }
 function addGlobalMapping(mapping) {
+  const normalizedPattern = path2.normalize(mapping.pattern);
   const mappings = readGlobalMappings();
-  const filtered = mappings.filter((m) => m.pattern !== mapping.pattern);
-  filtered.push(mapping);
+  const filtered = mappings.filter((m) => path2.normalize(m.pattern) !== normalizedPattern);
+  filtered.push({ ...mapping, pattern: normalizedPattern });
   return writeGlobalMappings(filtered);
 }
 function findMatchingMapping(repoPath) {
   const mappings = readGlobalMappings();
   const normalizedRepo = path2.normalize(repoPath);
   for (const mapping of mappings) {
-    if (mapping.pattern.endsWith("/*")) {
-      const parentDir = mapping.pattern.slice(0, -2);
+    const normalizedPattern = path2.normalize(mapping.pattern);
+    if (normalizedPattern.endsWith(`${path2.sep}*`)) {
+      const parentDir = normalizedPattern.slice(0, -2);
       if (normalizedRepo.startsWith(parentDir + path2.sep)) {
         return mapping;
       }
-    } else if (normalizedRepo === path2.normalize(mapping.pattern)) {
+    } else if (normalizedRepo === normalizedPattern) {
       return mapping;
     }
   }
@@ -4530,6 +4533,7 @@ var MemoryCache = class {
     this.cache = /* @__PURE__ */ new Map();
     this.cleanupInterval = null;
     this.cleanupInterval = setInterval(() => this.cleanup(), cleanupIntervalMs);
+    this.cleanupInterval.unref?.();
   }
   /**
    * Get a cached value if it exists and hasn't expired
@@ -4677,6 +4681,15 @@ var ContextStreamClient = class {
   me() {
     return request(this.config, "/auth/me");
   }
+  startDeviceLogin() {
+    return request(this.config, "/auth/device/start", { method: "POST" });
+  }
+  pollDeviceLogin(input) {
+    return request(this.config, "/auth/device/token", { body: input });
+  }
+  createApiKey(input) {
+    return request(this.config, "/auth/api-keys", { body: input });
+  }
   // Credits / Billing (used for plan gating)
   async getCreditBalance() {
     const cacheKey = CacheKeys.creditBalance();
@@ -5024,7 +5037,7 @@ var ContextStreamClient = class {
         context.workspace_source = resolved.source;
         context.workspace_resolved_from = resolved.source === "local_config" ? `${rootPath}/.contextstream/config.json` : "parent_folder_mapping";
       } else {
-        const folderName = rootPath?.split("/").pop()?.toLowerCase() || "";
+        const folderName = rootPath ? path3.basename(rootPath).toLowerCase() : "";
         try {
           const workspaces = await this.listWorkspaces({ page_size: 50 });
           if (workspaces.items && workspaces.items.length > 0) {
@@ -5079,13 +5092,13 @@ var ContextStreamClient = class {
                 name: w.name,
                 description: w.description
               }));
-              context.message = `New folder detected: "${rootPath?.split("/").pop()}". Please select which workspace this belongs to, or create a new one.`;
+              context.message = `New folder detected: "${rootPath ? path3.basename(rootPath) : "this folder"}". Please select which workspace this belongs to, or create a new one.`;
               context.ide_roots = ideRoots;
-              context.folder_name = rootPath?.split("/").pop();
+              context.folder_name = rootPath ? path3.basename(rootPath) : void 0;
               return context;
             }
           } else {
-            const folderDisplayName = rootPath?.split("/").pop() || "this folder";
+            const folderDisplayName = rootPath ? path3.basename(rootPath) || "this folder" : "this folder";
             context.status = "requires_workspace_name";
             context.workspace_source = "none_found";
             context.ide_roots = ideRoots;
@@ -5113,7 +5126,7 @@ var ContextStreamClient = class {
       }
     }
     if (!workspaceId && !params.allow_no_workspace) {
-      const folderDisplayName = rootPath?.split("/").pop() || "this folder";
+      const folderDisplayName = rootPath ? path3.basename(rootPath) || "this folder" : "this folder";
       context.ide_roots = ideRoots;
       context.folder_name = folderDisplayName;
       if (rootPath) {
@@ -5145,7 +5158,7 @@ var ContextStreamClient = class {
       }
     }
     if (!projectId && workspaceId && rootPath && params.auto_index !== false) {
-      const projectName = rootPath.split("/").pop() || "My Project";
+      const projectName = path3.basename(rootPath) || "My Project";
       try {
         const projects = await this.listProjects({ workspace_id: workspaceId });
         const projectNameLower = projectName.toLowerCase();
@@ -5353,9 +5366,9 @@ var ContextStreamClient = class {
       associated_at: (/* @__PURE__ */ new Date()).toISOString()
     });
     if (create_parent_mapping) {
-      const parentDir = folder_path.split("/").slice(0, -1).join("/");
+      const parentDir = path3.dirname(folder_path);
       addGlobalMapping({
-        pattern: `${parentDir}/*`,
+        pattern: path3.join(parentDir, "*"),
         workspace_id,
         workspace_name: workspace_name || "Unknown"
       });
@@ -5829,9 +5842,9 @@ var ContextStreamClient = class {
           candidateParts.push("## Relevant Code\n");
           currentChars += 18;
           const codeEntries = code.results.map((c) => {
-            const path3 = c.file_path || "file";
+            const path6 = c.file_path || "file";
             const content = c.content?.slice(0, 150) || "";
-            return { path: path3, entry: `\u2022 ${path3}: ${content}...
+            return { path: path6, entry: `\u2022 ${path6}: ${content}...
 ` };
           });
           for (const c of codeEntries) {
@@ -6469,8 +6482,34 @@ W:${wsHint}
   }
 };
 
+// src/tools.ts
+import * as path4 from "node:path";
+
 // src/rules-templates.ts
-var CONTEXTSTREAM_RULES = `
+var DEFAULT_CLAUDE_MCP_SERVER_NAME = "contextstream";
+var CONTEXTSTREAM_TOOL_NAMES = [
+  "session_init",
+  "context_smart",
+  "session_summary",
+  "session_capture",
+  "session_capture_lesson",
+  "session_get_lessons",
+  "session_recall",
+  "session_remember",
+  "session_get_user_context",
+  "session_smart_search",
+  "session_compress",
+  "session_delta",
+  "generate_editor_rules",
+  "workspace_associate",
+  "workspace_bootstrap"
+];
+function applyMcpToolPrefix(markdown, toolPrefix) {
+  const toolPattern = CONTEXTSTREAM_TOOL_NAMES.join("|");
+  const toolRegex = new RegExp(`(?<!__)\\b(${toolPattern})\\b`, "g");
+  return markdown.replace(toolRegex, `${toolPrefix}$1`);
+}
+var CONTEXTSTREAM_RULES_FULL = `
 ## ContextStream Integration
 
 You have access to ContextStream MCP tools for persistent memory and context.
@@ -6480,7 +6519,7 @@ You have access to ContextStream MCP tools for persistent memory and context.
 | Message | What to Call |
 |---------|--------------|
 | **1st message** | \`session_init(folder_path="...", context_hint="<user's message>")\` |
-| **2nd+ messages** | \`context_smart(user_message="<user's message>")\` |
+| **2nd+ messages** | \`context_smart(user_message="<user's message>", max_tokens=400)\` |
 | **After completing task** | \`session_capture(...)\` - MUST capture decisions/insights |
 | **User frustration/correction** | \`session_capture_lesson(...)\` - MUST capture lessons |
 | **Command/tool error + fix** | \`session_capture_lesson(...)\` - MUST capture lessons |
@@ -6507,6 +6546,17 @@ You have access to ContextStream MCP tools for persistent memory and context.
 
 ---
 
+### Recommended Token Budgets
+
+- For trivial/local edits: \`context_smart(..., max_tokens=200)\`
+- Default: \`context_smart(..., max_tokens=400)\`
+- Deep debugging/architecture or heavy \u201Cwhat did we decide?\u201D: \`context_smart(..., max_tokens=800)\`
+- Keep \`format="minified"\` (default) unless you\u2019re actively debugging tool output
+
+If context still feels missing, increase \`max_tokens\` and/or call \`session_recall\` for a focused deep lookup.
+
+---
+
 ### When to Capture (MANDATORY)
 
 | When | Tool | Example |
@@ -6593,7 +6643,7 @@ session_init(folder_path="/path/to/project", context_hint="how should I implemen
 # Returns workspace info + semantically relevant auth decisions from ANY time
 
 # Second message - user asks about database
-context_smart(user_message="what database should I use?")
+context_smart(user_message="what database should I use?", max_tokens=400)
 # Returns: W:Maker|P:myproject|D:Use PostgreSQL|D:No ORMs|M:DB schema at...
 
 # User says "Let's use Redis for caching"
@@ -6606,58 +6656,75 @@ session_capture(event_type="decision", title="Auth Implementation Complete", con
 session_recall(query="what did we decide about caching?")
 \`\`\`
 `.trim();
+var CONTEXTSTREAM_RULES_MINIMAL = `
+## ContextStream (Minimal)
+
+- First user message: \`session_init(folder_path="<cwd>", context_hint="<user_message>")\`, then answer.
+- Every user message: \`context_smart(user_message="<user_message>", format="minified", max_tokens=400)\` BEFORE answering.
+  - Use \`max_tokens=200\` for trivial/local edits, \`max_tokens=800\` for deep debugging/architecture.
+- If prior context is missing or user asks past decisions: \`session_recall(query="<question>")\`, then answer.
+- After meaningful work/decisions/preferences: \`session_capture(event_type=decision|preference|task|insight, title="\u2026", content="\u2026")\`.
+- On frustration/corrections/tool mistakes: \`session_capture_lesson(...)\`.
+`.trim();
 var TEMPLATES = {
+  codex: {
+    filename: "AGENTS.md",
+    description: "Codex CLI agent instructions",
+    build: (rules) => `# Codex CLI Instructions
+${rules}
+`
+  },
   windsurf: {
     filename: ".windsurfrules",
     description: "Windsurf AI rules",
-    content: `# Windsurf Rules
-${CONTEXTSTREAM_RULES}
+    build: (rules) => `# Windsurf Rules
+${rules}
 `
   },
   cursor: {
     filename: ".cursorrules",
     description: "Cursor AI rules",
-    content: `# Cursor Rules
-${CONTEXTSTREAM_RULES}
+    build: (rules) => `# Cursor Rules
+${rules}
 `
   },
   cline: {
     filename: ".clinerules",
     description: "Cline AI rules",
-    content: `# Cline Rules
-${CONTEXTSTREAM_RULES}
+    build: (rules) => `# Cline Rules
+${rules}
 `
   },
   kilo: {
     filename: ".kilocode/rules/contextstream.md",
     description: "Kilo Code AI rules",
-    content: `# Kilo Code Rules
-${CONTEXTSTREAM_RULES}
+    build: (rules) => `# Kilo Code Rules
+${rules}
 `
   },
   roo: {
     filename: ".roo/rules/contextstream.md",
     description: "Roo Code AI rules",
-    content: `# Roo Code Rules
-${CONTEXTSTREAM_RULES}
+    build: (rules) => `# Roo Code Rules
+${rules}
 `
   },
   claude: {
     filename: "CLAUDE.md",
     description: "Claude Code instructions",
-    content: `# Claude Code Instructions
-${CONTEXTSTREAM_RULES}
+    build: (rules) => `# Claude Code Instructions
+${rules}
 `
   },
   aider: {
     filename: ".aider.conf.yml",
     description: "Aider configuration with system prompt",
-    content: `# Aider Configuration
+    build: (rules) => `# Aider Configuration
 # Note: Aider uses different config format - this adds to the system prompt
 
 # Add ContextStream guidance to conventions
 conventions: |
-${CONTEXTSTREAM_RULES.split("\n").map((line) => "  " + line).join("\n")}
+${rules.split("\n").map((line) => "  " + line).join("\n")}
 `
   }
 };
@@ -6670,7 +6737,9 @@ function getTemplate(editor) {
 function generateRuleContent(editor, options) {
   const template = getTemplate(editor);
   if (!template) return null;
-  let content = template.content;
+  const mode = options?.mode || "minimal";
+  const rules = mode === "full" ? CONTEXTSTREAM_RULES_FULL : CONTEXTSTREAM_RULES_MINIMAL;
+  let content = template.build(rules);
   if (options?.workspaceName || options?.projectName) {
     const header = `
 # Workspace: ${options.workspaceName || "Unknown"}
@@ -6683,6 +6752,9 @@ ${options.workspaceId ? `# Workspace ID: ${options.workspaceId}` : ""}
   if (options?.additionalRules) {
     content += "\n\n## Project-Specific Rules\n\n" + options.additionalRules;
   }
+  if (editor.toLowerCase() === "claude") {
+    content = applyMcpToolPrefix(content, `mcp__${DEFAULT_CLAUDE_MCP_SERVER_NAME}__`);
+  }
   return {
     filename: template.filename,
     content: content.trim() + "\n"
@@ -7794,7 +7866,7 @@ This does semantic search on the first message. You only need context_smart on s
           formatContent(result)
         ].join("\n");
       } else if (status === "requires_workspace_selection") {
-        const folderName = typeof result.folder_name === "string" ? result.folder_name : typeof input.folder_path === "string" ? input.folder_path.split("/").pop() || "this folder" : "this folder";
+        const folderName = typeof result.folder_name === "string" ? result.folder_name : typeof input.folder_path === "string" ? path4.basename(input.folder_path) || "this folder" : "this folder";
         const candidates = Array.isArray(result.workspace_candidates) ? result.workspace_candidates : [];
         const lines = [];
         lines.push(`Action required: select a workspace for "${folderName}" (or create a new one).`);
@@ -7864,26 +7936,26 @@ Optionally generates AI editor rules for automatic ContextStream usage.`,
       const result = await client.associateWorkspace(input);
       let rulesGenerated = [];
       if (input.generate_editor_rules) {
-        const fs3 = await import("fs");
-        const path3 = await import("path");
+        const fs4 = await import("fs");
+        const path6 = await import("path");
         for (const editor of getAvailableEditors()) {
           const rule = generateRuleContent(editor, {
             workspaceName: input.workspace_name,
             workspaceId: input.workspace_id
           });
           if (rule) {
-            const filePath = path3.join(input.folder_path, rule.filename);
+            const filePath = path6.join(input.folder_path, rule.filename);
             try {
               let existingContent = "";
               try {
-                existingContent = fs3.readFileSync(filePath, "utf-8");
+                existingContent = fs4.readFileSync(filePath, "utf-8");
               } catch {
               }
               if (!existingContent) {
-                fs3.writeFileSync(filePath, rule.content);
+                fs4.writeFileSync(filePath, rule.content);
                 rulesGenerated.push(rule.filename);
               } else if (!existingContent.includes("ContextStream Integration")) {
-                fs3.writeFileSync(filePath, existingContent + "\n\n" + rule.content);
+                fs4.writeFileSync(filePath, existingContent + "\n\n" + rule.content);
                 rulesGenerated.push(rule.filename + " (appended)");
               }
             } catch {
@@ -7937,7 +8009,7 @@ Behavior:
       if (!folderPath) {
         return errorResult("Error: folder_path is required. Provide folder_path or run from a project directory.");
       }
-      const folderName = folderPath.split("/").pop() || "My Project";
+      const folderName = path4.basename(folderPath) || "My Project";
       let newWorkspace;
       try {
         newWorkspace = await client.createWorkspace({
@@ -7969,26 +8041,26 @@ Behavior:
       });
       let rulesGenerated = [];
       if (input.generate_editor_rules) {
-        const fs3 = await import("fs");
-        const path3 = await import("path");
+        const fs4 = await import("fs");
+        const path6 = await import("path");
         for (const editor of getAvailableEditors()) {
           const rule = generateRuleContent(editor, {
             workspaceName: newWorkspace.name || input.workspace_name,
             workspaceId: newWorkspace.id
           });
           if (!rule) continue;
-          const filePath = path3.join(folderPath, rule.filename);
+          const filePath = path6.join(folderPath, rule.filename);
           try {
             let existingContent = "";
             try {
-              existingContent = fs3.readFileSync(filePath, "utf-8");
+              existingContent = fs4.readFileSync(filePath, "utf-8");
             } catch {
             }
             if (!existingContent) {
-              fs3.writeFileSync(filePath, rule.content);
+              fs4.writeFileSync(filePath, rule.content);
               rulesGenerated.push(rule.filename);
             } else if (!existingContent.includes("ContextStream Integration")) {
-              fs3.writeFileSync(filePath, existingContent + "\n\n" + rule.content);
+              fs4.writeFileSync(filePath, existingContent + "\n\n" + rule.content);
               rulesGenerated.push(rule.filename + " (appended)");
             }
           } catch {
@@ -8378,17 +8450,18 @@ These rules instruct the AI to automatically use ContextStream for memory and co
 Supported editors: ${getAvailableEditors().join(", ")}`,
       inputSchema: external_exports.object({
         folder_path: external_exports.string().describe("Absolute path to the project folder"),
-        editors: external_exports.array(external_exports.enum(["windsurf", "cursor", "cline", "kilo", "roo", "claude", "aider", "all"])).optional().describe("Which editors to generate rules for. Defaults to all."),
+        editors: external_exports.array(external_exports.enum(["codex", "windsurf", "cursor", "cline", "kilo", "roo", "claude", "aider", "all"])).optional().describe("Which editors to generate rules for. Defaults to all."),
         workspace_name: external_exports.string().optional().describe("Workspace name to include in rules"),
         workspace_id: external_exports.string().uuid().optional().describe("Workspace ID to include in rules"),
         project_name: external_exports.string().optional().describe("Project name to include in rules"),
         additional_rules: external_exports.string().optional().describe("Additional project-specific rules to append"),
+        mode: external_exports.enum(["minimal", "full"]).optional().describe("Rule verbosity mode (default: minimal)"),
         dry_run: external_exports.boolean().optional().describe("If true, return content without writing files")
       })
     },
     async (input) => {
-      const fs3 = await import("fs");
-      const path3 = await import("path");
+      const fs4 = await import("fs");
+      const path6 = await import("path");
       const editors = input.editors?.includes("all") || !input.editors ? getAvailableEditors() : input.editors.filter((e) => e !== "all");
       const results = [];
       for (const editor of editors) {
@@ -8396,13 +8469,14 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
           workspaceName: input.workspace_name,
           workspaceId: input.workspace_id,
           projectName: input.project_name,
-          additionalRules: input.additional_rules
+          additionalRules: input.additional_rules,
+          mode: input.mode
         });
         if (!rule) {
           results.push({ editor, filename: "", status: "unknown editor" });
           continue;
         }
-        const filePath = path3.join(input.folder_path, rule.filename);
+        const filePath = path6.join(input.folder_path, rule.filename);
         if (input.dry_run) {
           results.push({
             editor,
@@ -8414,15 +8488,15 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
           try {
             let existingContent = "";
             try {
-              existingContent = fs3.readFileSync(filePath, "utf-8");
+              existingContent = fs4.readFileSync(filePath, "utf-8");
             } catch {
             }
             if (existingContent && !existingContent.includes("ContextStream Integration")) {
               const updatedContent = existingContent + "\n\n" + rule.content;
-              fs3.writeFileSync(filePath, updatedContent);
+              fs4.writeFileSync(filePath, updatedContent);
               results.push({ editor, filename: rule.filename, status: "appended to existing" });
             } else {
-              fs3.writeFileSync(filePath, rule.content);
+              fs4.writeFileSync(filePath, rule.content);
               results.push({ editor, filename: rule.filename, status: "created" });
             }
           } catch (err) {
@@ -9092,8 +9166,8 @@ var SessionManager = class {
   /**
    * Set the folder path hint (can be passed from tools that know the workspace path)
    */
-  setFolderPath(path3) {
-    this.folderPath = path3;
+  setFolderPath(path6) {
+    this.folderPath = path6;
   }
   /**
    * Mark that context_smart has been called in this session
@@ -9160,11 +9234,11 @@ var SessionManager = class {
     }
     if (this.ideRoots.length === 0) {
       const cwd = process.cwd();
-      const fs3 = await import("fs");
+      const fs4 = await import("fs");
       const projectIndicators = [".git", "package.json", "Cargo.toml", "pyproject.toml", ".contextstream"];
       const hasProjectIndicator = projectIndicators.some((f) => {
         try {
-          return fs3.existsSync(`${cwd}/${f}`);
+          return fs4.existsSync(`${cwd}/${f}`);
         } catch {
           return false;
         }
@@ -9342,11 +9416,716 @@ var SessionManager = class {
 
 // src/index.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
-import { homedir } from "os";
-import { join as join3 } from "path";
+import { homedir as homedir2 } from "os";
+import { join as join5 } from "path";
+
+// src/setup.ts
+import * as fs3 from "node:fs/promises";
+import * as path5 from "node:path";
+import { homedir } from "node:os";
+import { stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+var EDITOR_LABELS = {
+  codex: "Codex CLI",
+  claude: "Claude Code",
+  cursor: "Cursor / VS Code",
+  windsurf: "Windsurf",
+  cline: "Cline",
+  kilo: "Kilo Code",
+  roo: "Roo Code",
+  aider: "Aider"
+};
+function normalizeInput(value) {
+  return value.trim();
+}
+function maskApiKey(apiKey) {
+  const trimmed = apiKey.trim();
+  if (trimmed.length <= 8) return "********";
+  return `${trimmed.slice(0, 4)}\u2026${trimmed.slice(-4)}`;
+}
+function parseNumberList(input, max) {
+  const cleaned = input.trim().toLowerCase();
+  if (!cleaned) return [];
+  if (cleaned === "all" || cleaned === "*") {
+    return Array.from({ length: max }, (_, i) => i + 1);
+  }
+  const parts = cleaned.split(/[, ]+/).filter(Boolean);
+  const out = /* @__PURE__ */ new Set();
+  for (const part of parts) {
+    const n = Number.parseInt(part, 10);
+    if (Number.isFinite(n) && n >= 1 && n <= max) out.add(n);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+async function fileExists(filePath) {
+  try {
+    await fs3.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function upsertTextFile(filePath, content, marker) {
+  await fs3.mkdir(path5.dirname(filePath), { recursive: true });
+  const exists = await fileExists(filePath);
+  if (!exists) {
+    await fs3.writeFile(filePath, content, "utf8");
+    return "created";
+  }
+  const existing = await fs3.readFile(filePath, "utf8").catch(() => "");
+  if (existing.includes(marker)) return "skipped";
+  const joined = existing.trimEnd() + "\n\n" + content.trim() + "\n";
+  await fs3.writeFile(filePath, joined, "utf8");
+  return "appended";
+}
+function globalRulesPathForEditor(editor) {
+  const home = homedir();
+  switch (editor) {
+    case "codex":
+      return path5.join(home, ".codex", "AGENTS.md");
+    case "claude":
+      return path5.join(home, ".claude", "CLAUDE.md");
+    case "windsurf":
+      return path5.join(home, ".codeium", "windsurf", "memories", "global_rules.md");
+    case "cline":
+      return path5.join(home, "Documents", "Cline", "Rules", "contextstream.md");
+    case "kilo":
+      return path5.join(home, ".kilocode", "rules", "contextstream.md");
+    case "roo":
+      return path5.join(home, ".roo", "rules", "contextstream.md");
+    case "aider":
+      return path5.join(home, ".aider.conf.yml");
+    case "cursor":
+      return null;
+    default:
+      return null;
+  }
+}
+function buildContextStreamMcpServer(params) {
+  return {
+    command: "npx",
+    args: ["-y", "@contextstream/mcp-server"],
+    env: {
+      CONTEXTSTREAM_API_URL: params.apiUrl,
+      CONTEXTSTREAM_API_KEY: params.apiKey
+    }
+  };
+}
+function buildContextStreamVsCodeServer(params) {
+  return {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@contextstream/mcp-server"],
+    env: {
+      CONTEXTSTREAM_API_URL: params.apiUrl,
+      CONTEXTSTREAM_API_KEY: params.apiKey
+    }
+  };
+}
+function stripJsonComments(input) {
+  return input.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+function tryParseJsonLike(raw) {
+  const trimmed = raw.replace(/^\uFEFF/, "").trim();
+  if (!trimmed) return { ok: true, value: {} };
+  try {
+    return { ok: true, value: JSON.parse(trimmed) };
+  } catch {
+    try {
+      const noComments = stripJsonComments(trimmed);
+      const noTrailingCommas = noComments.replace(/,(\s*[}\]])/g, "$1");
+      return { ok: true, value: JSON.parse(noTrailingCommas) };
+    } catch (err) {
+      return { ok: false, error: err?.message || "Invalid JSON" };
+    }
+  }
+}
+async function upsertJsonMcpConfig(filePath, server) {
+  await fs3.mkdir(path5.dirname(filePath), { recursive: true });
+  const exists = await fileExists(filePath);
+  let root = {};
+  if (exists) {
+    const raw = await fs3.readFile(filePath, "utf8").catch(() => "");
+    const parsed = tryParseJsonLike(raw);
+    if (!parsed.ok) throw new Error(`Invalid JSON in ${filePath}: ${parsed.error}`);
+    root = parsed.value;
+  }
+  if (!root || typeof root !== "object" || Array.isArray(root)) root = {};
+  if (!root.mcpServers || typeof root.mcpServers !== "object" || Array.isArray(root.mcpServers)) root.mcpServers = {};
+  const before = JSON.stringify(root.mcpServers.contextstream ?? null);
+  root.mcpServers.contextstream = server;
+  const after = JSON.stringify(root.mcpServers.contextstream ?? null);
+  await fs3.writeFile(filePath, JSON.stringify(root, null, 2) + "\n", "utf8");
+  if (!exists) return "created";
+  return before === after ? "skipped" : "updated";
+}
+async function upsertJsonVsCodeMcpConfig(filePath, server) {
+  await fs3.mkdir(path5.dirname(filePath), { recursive: true });
+  const exists = await fileExists(filePath);
+  let root = {};
+  if (exists) {
+    const raw = await fs3.readFile(filePath, "utf8").catch(() => "");
+    const parsed = tryParseJsonLike(raw);
+    if (!parsed.ok) throw new Error(`Invalid JSON in ${filePath}: ${parsed.error}`);
+    root = parsed.value;
+  }
+  if (!root || typeof root !== "object" || Array.isArray(root)) root = {};
+  if (!root.servers || typeof root.servers !== "object" || Array.isArray(root.servers)) root.servers = {};
+  const before = JSON.stringify(root.servers.contextstream ?? null);
+  root.servers.contextstream = server;
+  const after = JSON.stringify(root.servers.contextstream ?? null);
+  await fs3.writeFile(filePath, JSON.stringify(root, null, 2) + "\n", "utf8");
+  if (!exists) return "created";
+  return before === after ? "skipped" : "updated";
+}
+function claudeDesktopConfigPath() {
+  const home = homedir();
+  if (process.platform === "darwin") {
+    return path5.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path5.join(home, "AppData", "Roaming");
+    return path5.join(appData, "Claude", "claude_desktop_config.json");
+  }
+  return null;
+}
+async function upsertCodexTomlConfig(filePath, params) {
+  await fs3.mkdir(path5.dirname(filePath), { recursive: true });
+  const exists = await fileExists(filePath);
+  const existing = exists ? await fs3.readFile(filePath, "utf8").catch(() => "") : "";
+  const marker = "[mcp_servers.contextstream]";
+  const envMarker = "[mcp_servers.contextstream.env]";
+  const block = `
+
+# ContextStream MCP server
+[mcp_servers.contextstream]
+command = "npx"
+args = ["-y", "@contextstream/mcp-server"]
+
+[mcp_servers.contextstream.env]
+CONTEXTSTREAM_API_URL = "${params.apiUrl}"
+CONTEXTSTREAM_API_KEY = "${params.apiKey}"
+`;
+  if (!exists) {
+    await fs3.writeFile(filePath, block.trimStart(), "utf8");
+    return "created";
+  }
+  if (!existing.includes(marker)) {
+    await fs3.writeFile(filePath, existing.trimEnd() + block, "utf8");
+    return "updated";
+  }
+  if (!existing.includes(envMarker)) {
+    await fs3.writeFile(filePath, existing.trimEnd() + "\n\n" + envMarker + `
+CONTEXTSTREAM_API_URL = "${params.apiUrl}"
+CONTEXTSTREAM_API_KEY = "${params.apiKey}"
+`, "utf8");
+    return "updated";
+  }
+  const lines = existing.split(/\r?\n/);
+  const out = [];
+  let inEnv = false;
+  let sawUrl = false;
+  let sawKey = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+      if (inEnv && trimmed !== envMarker) {
+        if (!sawUrl) out.push(`CONTEXTSTREAM_API_URL = "${params.apiUrl}"`);
+        if (!sawKey) out.push(`CONTEXTSTREAM_API_KEY = "${params.apiKey}"`);
+        inEnv = false;
+      }
+      if (trimmed === envMarker) inEnv = true;
+      out.push(line);
+      continue;
+    }
+    if (inEnv && /^\s*CONTEXTSTREAM_API_URL\s*=/.test(line)) {
+      out.push(`CONTEXTSTREAM_API_URL = "${params.apiUrl}"`);
+      sawUrl = true;
+      continue;
+    }
+    if (inEnv && /^\s*CONTEXTSTREAM_API_KEY\s*=/.test(line)) {
+      out.push(`CONTEXTSTREAM_API_KEY = "${params.apiKey}"`);
+      sawKey = true;
+      continue;
+    }
+    out.push(line);
+  }
+  if (inEnv) {
+    if (!sawUrl) out.push(`CONTEXTSTREAM_API_URL = "${params.apiUrl}"`);
+    if (!sawKey) out.push(`CONTEXTSTREAM_API_KEY = "${params.apiKey}"`);
+  }
+  const updated = out.join("\n");
+  if (updated === existing) return "skipped";
+  await fs3.writeFile(filePath, updated, "utf8");
+  return "updated";
+}
+async function discoverProjectsUnderFolder(parentFolder) {
+  const entries = await fs3.readdir(parentFolder, { withFileTypes: true });
+  const candidates = entries.filter((e) => e.isDirectory() && !e.name.startsWith(".")).map((e) => path5.join(parentFolder, e.name));
+  const projects = [];
+  for (const dir of candidates) {
+    const hasGit = await fileExists(path5.join(dir, ".git"));
+    const hasPkg = await fileExists(path5.join(dir, "package.json"));
+    const hasCargo = await fileExists(path5.join(dir, "Cargo.toml"));
+    const hasPyProject = await fileExists(path5.join(dir, "pyproject.toml"));
+    if (hasGit || hasPkg || hasCargo || hasPyProject) projects.push(dir);
+  }
+  return projects;
+}
+function buildClientConfig(params) {
+  return {
+    apiUrl: params.apiUrl,
+    apiKey: params.apiKey,
+    jwt: params.jwt,
+    defaultWorkspaceId: void 0,
+    defaultProjectId: void 0,
+    userAgent: `contextstream-mcp/setup/${VERSION}`
+  };
+}
+async function runSetupWizard(args) {
+  const dryRun = args.includes("--dry-run");
+  const rl = createInterface({ input: stdin, output: stdout });
+  const writeActions = [];
+  try {
+    console.log(`ContextStream Setup Wizard (v${VERSION})`);
+    console.log("This configures ContextStream MCP + rules for your AI editor(s).");
+    if (dryRun) console.log("DRY RUN: no files will be written.\n");
+    else console.log("");
+    const apiUrlDefault = process.env.CONTEXTSTREAM_API_URL || "https://api.contextstream.io";
+    const apiUrl = normalizeInput(
+      await rl.question(`ContextStream API URL [${apiUrlDefault}]: `)
+    ) || apiUrlDefault;
+    let apiKey = normalizeInput(process.env.CONTEXTSTREAM_API_KEY || "");
+    if (apiKey) {
+      const confirm = normalizeInput(
+        await rl.question(`Use CONTEXTSTREAM_API_KEY from environment (${maskApiKey(apiKey)})? [Y/n]: `)
+      );
+      if (confirm.toLowerCase() === "n" || confirm.toLowerCase() === "no") apiKey = "";
+    }
+    if (!apiKey) {
+      console.log("\nAuthentication:");
+      console.log("  1) Browser login (recommended)");
+      console.log("  2) Paste an API key");
+      const authChoice = normalizeInput(await rl.question("Choose [1/2] (default 1): ")) || "1";
+      if (authChoice === "2") {
+        console.log("\nYou need a ContextStream API key to continue.");
+        console.log("Create one here (then paste it): https://app.contextstream.io/settings/api-keys\n");
+        apiKey = normalizeInput(await rl.question("CONTEXTSTREAM_API_KEY: "));
+      } else {
+        const anonClient = new ContextStreamClient(buildClientConfig({ apiUrl }));
+        let device;
+        try {
+          device = await anonClient.startDeviceLogin();
+        } catch (err) {
+          const message = err instanceof HttpError ? `${err.status} ${err.code}: ${err.message}` : err?.message || String(err);
+          throw new Error(
+            `Browser login is not available on this API. Please use an API key instead. (${message})`
+          );
+        }
+        const verificationUrl = typeof device?.verification_uri_complete === "string" ? device.verification_uri_complete : typeof device?.verification_uri === "string" && typeof device?.user_code === "string" ? `${device.verification_uri}?user_code=${device.user_code}` : void 0;
+        if (!verificationUrl || typeof device?.device_code !== "string" || typeof device?.expires_in !== "number") {
+          throw new Error("Browser login returned an unexpected response.");
+        }
+        console.log("\nOpen this URL to sign in and approve the setup wizard:");
+        console.log(verificationUrl);
+        if (typeof device?.user_code === "string") {
+          console.log(`
+Code: ${device.user_code}`);
+        }
+        console.log("\nWaiting for approval...");
+        const startedAt = Date.now();
+        const expiresMs = device.expires_in * 1e3;
+        const deviceCode = device.device_code;
+        let accessToken;
+        while (Date.now() - startedAt < expiresMs) {
+          let poll;
+          try {
+            poll = await anonClient.pollDeviceLogin({ device_code: deviceCode });
+          } catch (err) {
+            const message = err instanceof HttpError ? `${err.status} ${err.code}: ${err.message}` : err?.message || String(err);
+            throw new Error(`Browser login failed while polling. (${message})`);
+          }
+          if (poll && poll.status === "authorized" && typeof poll.access_token === "string") {
+            accessToken = poll.access_token;
+            break;
+          }
+          if (poll && poll.status === "pending") {
+            const intervalSeconds = typeof poll.interval === "number" ? poll.interval : 5;
+            const waitMs = Math.max(1, intervalSeconds) * 1e3;
+            await new Promise((resolve2) => setTimeout(resolve2, waitMs));
+            continue;
+          }
+          await new Promise((resolve2) => setTimeout(resolve2, 1e3));
+        }
+        if (!accessToken) {
+          throw new Error("Browser login expired or was not approved in time. Please run setup again.");
+        }
+        const jwtClient = new ContextStreamClient(buildClientConfig({ apiUrl, jwt: accessToken }));
+        const keyName = `setup-wizard-${Date.now()}`;
+        let createdKey;
+        try {
+          createdKey = await jwtClient.createApiKey({ name: keyName });
+        } catch (err) {
+          const message = err instanceof HttpError ? `${err.status} ${err.code}: ${err.message}` : err?.message || String(err);
+          throw new Error(`Login succeeded but API key creation failed. (${message})`);
+        }
+        if (typeof createdKey?.secret_key !== "string" || !createdKey.secret_key.trim()) {
+          throw new Error("API key creation returned an unexpected response.");
+        }
+        apiKey = createdKey.secret_key.trim();
+        console.log(`
+Created API key: ${maskApiKey(apiKey)}
+`);
+      }
+    }
+    const client = new ContextStreamClient(buildClientConfig({ apiUrl, apiKey }));
+    let me;
+    try {
+      me = await client.me();
+    } catch (err) {
+      const message = err instanceof HttpError ? `${err.status} ${err.code}: ${err.message}` : err?.message || String(err);
+      throw new Error(`Authentication failed. Check your API key. (${message})`);
+    }
+    const email = typeof me?.data?.email === "string" ? me.data.email : typeof me?.email === "string" ? me.email : void 0;
+    console.log(`Authenticated as: ${email || "unknown user"} (${maskApiKey(apiKey)})
+`);
+    let workspaceId;
+    let workspaceName;
+    console.log("Workspace setup:");
+    console.log("  1) Create a new workspace");
+    console.log("  2) Select an existing workspace");
+    console.log("  3) Skip (rules only, no workspace mapping)");
+    const wsChoice = normalizeInput(await rl.question("Choose [1/2/3] (default 2): ")) || "2";
+    if (wsChoice === "1") {
+      const name = normalizeInput(await rl.question("Workspace name: "));
+      if (!name) throw new Error("Workspace name is required.");
+      const description = normalizeInput(await rl.question("Workspace description (optional): "));
+      let visibility = "private";
+      while (true) {
+        const raw = normalizeInput(await rl.question("Visibility [private/team/org] (default private): ")) || "private";
+        const normalized = raw.trim().toLowerCase() === "public" ? "org" : raw.trim().toLowerCase();
+        if (normalized === "private" || normalized === "team" || normalized === "org") {
+          visibility = normalized;
+          break;
+        }
+        console.log("Invalid visibility. Choose: private, team, org.");
+      }
+      if (!dryRun) {
+        const created = await client.createWorkspace({ name, description: description || void 0, visibility });
+        workspaceId = typeof created?.id === "string" ? created.id : void 0;
+        workspaceName = typeof created?.name === "string" ? created.name : name;
+      } else {
+        workspaceId = "dry-run";
+        workspaceName = name;
+      }
+      console.log(`Workspace: ${workspaceName}${workspaceId ? ` (${workspaceId})` : ""}
+`);
+    } else if (wsChoice === "2") {
+      const list = await client.listWorkspaces({ page_size: 50 });
+      const items = Array.isArray(list?.items) ? list.items : Array.isArray(list?.data?.items) ? list.data.items : [];
+      if (items.length === 0) {
+        console.log("No workspaces found. Creating a new one is recommended.\n");
+      } else {
+        items.slice(0, 20).forEach((w, i) => {
+          console.log(`  ${i + 1}) ${w.name || "Untitled"}${w.id ? ` (${w.id})` : ""}`);
+        });
+        const idxRaw = normalizeInput(await rl.question("Select workspace number (or blank to skip): "));
+        if (idxRaw) {
+          const idx = Number.parseInt(idxRaw, 10);
+          const selected = Number.isFinite(idx) ? items[idx - 1] : void 0;
+          if (selected?.id) {
+            workspaceId = selected.id;
+            workspaceName = selected.name;
+          }
+        }
+      }
+    }
+    console.log("Rule verbosity:");
+    console.log("  1) Minimal (recommended)");
+    console.log("  2) Full (more context and guidance, more tokens)");
+    const modeChoice = normalizeInput(await rl.question("Choose [1/2] (default 1): ")) || "1";
+    const mode = modeChoice === "2" ? "full" : "minimal";
+    const editors = ["codex", "claude", "cursor", "windsurf", "cline", "kilo", "roo", "aider"];
+    console.log('\nSelect editors to configure (comma-separated numbers, or "all"):');
+    editors.forEach((e, i) => console.log(`  ${i + 1}) ${EDITOR_LABELS[e]}`));
+    const selectedRaw = normalizeInput(await rl.question("Editors [all]: ")) || "all";
+    const selectedNums = parseNumberList(selectedRaw, editors.length);
+    const selectedEditors = selectedNums.length ? selectedNums.map((n) => editors[n - 1]) : editors;
+    console.log("\nInstall rules as:");
+    console.log("  1) Global");
+    console.log("  2) Project");
+    console.log("  3) Both");
+    const scopeChoice = normalizeInput(await rl.question("Choose [1/2/3] (default 3): ")) || "3";
+    const scope = scopeChoice === "1" ? "global" : scopeChoice === "2" ? "project" : "both";
+    console.log("\nInstall MCP server config as:");
+    console.log("  1) Global");
+    console.log("  2) Project");
+    console.log("  3) Both");
+    console.log("  4) Skip (rules only)");
+    const mcpChoice = normalizeInput(await rl.question("Choose [1/2/3/4] (default 3): ")) || "3";
+    const mcpScope = mcpChoice === "4" ? "skip" : mcpChoice === "1" ? "global" : mcpChoice === "2" ? "project" : "both";
+    const mcpServer = buildContextStreamMcpServer({ apiUrl, apiKey });
+    const vsCodeServer = buildContextStreamVsCodeServer({ apiUrl, apiKey });
+    if (mcpScope === "global" || mcpScope === "both") {
+      console.log("\nInstalling global MCP config...");
+      for (const editor of selectedEditors) {
+        try {
+          if (editor === "codex") {
+            const filePath = path5.join(homedir(), ".codex", "config.toml");
+            if (dryRun) {
+              writeActions.push({ kind: "mcp-config", target: filePath, status: "dry-run" });
+              console.log(`- ${EDITOR_LABELS[editor]}: would update ${filePath}`);
+              continue;
+            }
+            const status = await upsertCodexTomlConfig(filePath, { apiUrl, apiKey });
+            writeActions.push({ kind: "mcp-config", target: filePath, status });
+            console.log(`- ${EDITOR_LABELS[editor]}: ${status} ${filePath}`);
+            continue;
+          }
+          if (editor === "windsurf") {
+            const filePath = path5.join(homedir(), ".codeium", "windsurf", "mcp_config.json");
+            if (dryRun) {
+              writeActions.push({ kind: "mcp-config", target: filePath, status: "dry-run" });
+              console.log(`- ${EDITOR_LABELS[editor]}: would update ${filePath}`);
+              continue;
+            }
+            const status = await upsertJsonMcpConfig(filePath, mcpServer);
+            writeActions.push({ kind: "mcp-config", target: filePath, status });
+            console.log(`- ${EDITOR_LABELS[editor]}: ${status} ${filePath}`);
+            continue;
+          }
+          if (editor === "claude") {
+            const desktopPath = claudeDesktopConfigPath();
+            if (desktopPath) {
+              const useDesktop = normalizeInput(await rl.question("Also configure Claude Desktop (GUI app)? [y/N]: ")).toLowerCase() === "y";
+              if (useDesktop) {
+                if (dryRun) {
+                  writeActions.push({ kind: "mcp-config", target: desktopPath, status: "dry-run" });
+                  console.log(`- Claude Desktop: would update ${desktopPath}`);
+                } else {
+                  const status = await upsertJsonMcpConfig(desktopPath, mcpServer);
+                  writeActions.push({ kind: "mcp-config", target: desktopPath, status });
+                  console.log(`- Claude Desktop: ${status} ${desktopPath}`);
+                }
+              }
+            }
+            console.log("- Claude Code: global MCP config is best done via `claude mcp add --transport stdio ...` (see docs).");
+            console.log("  macOS/Linux: claude mcp add --transport stdio contextstream --scope user --env CONTEXTSTREAM_API_URL=... --env CONTEXTSTREAM_API_KEY=... -- npx -y @contextstream/mcp-server");
+            console.log("  Windows (native): use `cmd /c npx -y @contextstream/mcp-server` after `--` if `npx` is not found.");
+            continue;
+          }
+          if (editor === "cursor") {
+            const filePath = path5.join(homedir(), ".cursor", "mcp.json");
+            if (dryRun) {
+              writeActions.push({ kind: "mcp-config", target: filePath, status: "dry-run" });
+              console.log(`- ${EDITOR_LABELS[editor]}: would update ${filePath}`);
+              continue;
+            }
+            const status = await upsertJsonMcpConfig(filePath, mcpServer);
+            writeActions.push({ kind: "mcp-config", target: filePath, status });
+            console.log(`- ${EDITOR_LABELS[editor]}: ${status} ${filePath}`);
+            continue;
+          }
+          if (editor === "cline") {
+            console.log(`- ${EDITOR_LABELS[editor]}: MCP config is managed via the extension UI (skipping global).`);
+            continue;
+          }
+          if (editor === "kilo" || editor === "roo") {
+            console.log(`- ${EDITOR_LABELS[editor]}: project MCP config supported via file; global is managed via the app UI.`);
+            continue;
+          }
+          if (editor === "aider") {
+            console.log(`- ${EDITOR_LABELS[editor]}: no MCP config file to write (rules only).`);
+            continue;
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          console.log(`- ${EDITOR_LABELS[editor]}: failed to write MCP config: ${message}`);
+        }
+      }
+    }
+    if (scope === "global" || scope === "both") {
+      console.log("\nInstalling global rules...");
+      for (const editor of selectedEditors) {
+        const filePath = globalRulesPathForEditor(editor);
+        if (!filePath) {
+          console.log(`- ${EDITOR_LABELS[editor]}: global rules need manual setup (project rules supported).`);
+          continue;
+        }
+        const rule = generateRuleContent(editor, {
+          workspaceName,
+          workspaceId: workspaceId && workspaceId !== "dry-run" ? workspaceId : void 0,
+          mode
+        });
+        if (!rule) continue;
+        if (dryRun) {
+          writeActions.push({ kind: "rules", target: filePath, status: "dry-run" });
+          console.log(`- ${EDITOR_LABELS[editor]}: would write ${filePath}`);
+          continue;
+        }
+        const status = await upsertTextFile(filePath, rule.content, "ContextStream");
+        writeActions.push({ kind: "rules", target: filePath, status });
+        console.log(`- ${EDITOR_LABELS[editor]}: ${status} ${filePath}`);
+      }
+    }
+    const projectPaths = /* @__PURE__ */ new Set();
+    const needsProjects = scope === "project" || scope === "both" || mcpScope === "project" || mcpScope === "both";
+    if (needsProjects) {
+      console.log("\nProject setup...");
+      const addCwd = normalizeInput(await rl.question(`Add current folder as a project? [Y/n] (${process.cwd()}): `));
+      if (addCwd.toLowerCase() !== "n" && addCwd.toLowerCase() !== "no") {
+        projectPaths.add(path5.resolve(process.cwd()));
+      }
+      while (true) {
+        console.log("\n  1) Add another project path");
+        console.log("  2) Add all projects under a folder");
+        console.log("  3) Continue");
+        const choice = normalizeInput(await rl.question("Choose [1/2/3] (default 3): ")) || "3";
+        if (choice === "3") break;
+        if (choice === "1") {
+          const p = normalizeInput(await rl.question("Project folder path: "));
+          if (p) projectPaths.add(path5.resolve(p));
+          continue;
+        }
+        if (choice === "2") {
+          const parent = normalizeInput(await rl.question("Parent folder path: "));
+          if (!parent) continue;
+          const parentAbs = path5.resolve(parent);
+          const projects2 = await discoverProjectsUnderFolder(parentAbs);
+          if (projects2.length === 0) {
+            console.log(`No projects detected under ${parentAbs} (looked for .git/package.json/Cargo.toml/pyproject.toml).`);
+            continue;
+          }
+          console.log(`Found ${projects2.length} project(s):`);
+          projects2.slice(0, 25).forEach((p) => console.log(`- ${p}`));
+          if (projects2.length > 25) console.log(`\u2026and ${projects2.length - 25} more`);
+          const confirm = normalizeInput(await rl.question("Add these projects? [Y/n]: "));
+          if (confirm.toLowerCase() === "n" || confirm.toLowerCase() === "no") continue;
+          projects2.forEach((p) => projectPaths.add(p));
+        }
+      }
+    }
+    const projects = [...projectPaths];
+    if (projects.length && needsProjects) {
+      console.log(`
+Applying to ${projects.length} project(s)...`);
+    }
+    const createParentMapping = !!workspaceId && workspaceId !== "dry-run" && projects.length > 1 && normalizeInput(await rl.question("Also create a parent folder mapping for auto-detection? [y/N]: ")).toLowerCase() === "y";
+    for (const projectPath of projects) {
+      if (workspaceId && workspaceId !== "dry-run" && workspaceName && !dryRun) {
+        try {
+          await client.associateWorkspace({
+            folder_path: projectPath,
+            workspace_id: workspaceId,
+            workspace_name: workspaceName,
+            create_parent_mapping: createParentMapping
+          });
+          writeActions.push({ kind: "workspace-config", target: path5.join(projectPath, ".contextstream", "config.json"), status: "created" });
+          console.log(`- Linked workspace in ${projectPath}`);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          console.log(`- Failed to link workspace in ${projectPath}: ${message}`);
+        }
+      } else if (workspaceId && workspaceId !== "dry-run" && workspaceName && dryRun) {
+        writeActions.push({ kind: "workspace-config", target: path5.join(projectPath, ".contextstream", "config.json"), status: "dry-run" });
+      }
+      if (mcpScope === "project" || mcpScope === "both") {
+        for (const editor of selectedEditors) {
+          try {
+            if (editor === "cursor") {
+              const cursorPath = path5.join(projectPath, ".cursor", "mcp.json");
+              const vscodePath = path5.join(projectPath, ".vscode", "mcp.json");
+              if (dryRun) {
+                writeActions.push({ kind: "mcp-config", target: cursorPath, status: "dry-run" });
+                writeActions.push({ kind: "mcp-config", target: vscodePath, status: "dry-run" });
+              } else {
+                const status1 = await upsertJsonMcpConfig(cursorPath, mcpServer);
+                const status2 = await upsertJsonVsCodeMcpConfig(vscodePath, vsCodeServer);
+                writeActions.push({ kind: "mcp-config", target: cursorPath, status: status1 });
+                writeActions.push({ kind: "mcp-config", target: vscodePath, status: status2 });
+              }
+              continue;
+            }
+            if (editor === "claude") {
+              const mcpPath = path5.join(projectPath, ".mcp.json");
+              if (dryRun) {
+                writeActions.push({ kind: "mcp-config", target: mcpPath, status: "dry-run" });
+              } else {
+                const status = await upsertJsonMcpConfig(mcpPath, mcpServer);
+                writeActions.push({ kind: "mcp-config", target: mcpPath, status });
+              }
+              continue;
+            }
+            if (editor === "kilo") {
+              const kiloPath = path5.join(projectPath, ".kilocode", "mcp.json");
+              if (dryRun) {
+                writeActions.push({ kind: "mcp-config", target: kiloPath, status: "dry-run" });
+              } else {
+                const status = await upsertJsonMcpConfig(kiloPath, mcpServer);
+                writeActions.push({ kind: "mcp-config", target: kiloPath, status });
+              }
+              continue;
+            }
+            if (editor === "roo") {
+              const rooPath = path5.join(projectPath, ".roo", "mcp.json");
+              if (dryRun) {
+                writeActions.push({ kind: "mcp-config", target: rooPath, status: "dry-run" });
+              } else {
+                const status = await upsertJsonMcpConfig(rooPath, mcpServer);
+                writeActions.push({ kind: "mcp-config", target: rooPath, status });
+              }
+              continue;
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.log(`- Failed to write MCP config for ${EDITOR_LABELS[editor]} in ${projectPath}: ${message}`);
+          }
+        }
+      }
+      for (const editor of selectedEditors) {
+        if (scope !== "project" && scope !== "both") continue;
+        const rule = generateRuleContent(editor, {
+          workspaceName,
+          workspaceId: workspaceId && workspaceId !== "dry-run" ? workspaceId : void 0,
+          projectName: path5.basename(projectPath),
+          mode
+        });
+        if (!rule) continue;
+        const filePath = path5.join(projectPath, rule.filename);
+        if (dryRun) {
+          writeActions.push({ kind: "rules", target: filePath, status: "dry-run" });
+          continue;
+        }
+        try {
+          const status = await upsertTextFile(filePath, rule.content, "ContextStream");
+          writeActions.push({ kind: "rules", target: filePath, status });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeActions.push({ kind: "rules", target: filePath, status: `error: ${message}` });
+        }
+      }
+    }
+    console.log("\nDone.");
+    if (writeActions.length) {
+      const created = writeActions.filter((a) => a.status === "created").length;
+      const appended = writeActions.filter((a) => a.status === "appended").length;
+      const updated = writeActions.filter((a) => a.status === "updated").length;
+      const skipped = writeActions.filter((a) => a.status === "skipped").length;
+      const dry = writeActions.filter((a) => a.status === "dry-run").length;
+      console.log(`Summary: ${created} created, ${updated} updated, ${appended} appended, ${skipped} skipped, ${dry} dry-run.`);
+    }
+    console.log("\nNext steps:");
+    console.log("- Restart your editor/CLI after changing MCP config or rules.");
+    console.log("- If any tools require UI-based MCP setup (e.g. Cline/Kilo/Roo global), follow https://contextstream.io/docs/mcp.");
+  } finally {
+    rl.close();
+  }
+}
+
+// src/index.ts
 function showFirstRunMessage() {
-  const configDir = join3(homedir(), ".contextstream");
-  const starShownFile = join3(configDir, ".star-shown");
+  const configDir = join5(homedir2(), ".contextstream");
+  const starShownFile = join5(configDir, ".star-shown");
   if (existsSync2(starShownFile)) {
     return;
   }
@@ -9375,6 +10154,10 @@ function printHelp() {
 Usage:
   npx -y @contextstream/mcp-server
   contextstream-mcp
+  contextstream-mcp setup
+
+Commands:
+  setup   Interactive onboarding wizard (rules + workspace mapping)
 
 Environment variables:
   CONTEXTSTREAM_API_URL   Base API URL (e.g. https://api.contextstream.io)
@@ -9390,6 +10173,9 @@ Examples:
   CONTEXTSTREAM_API_KEY="your_api_key" \\
   npx -y @contextstream/mcp-server
 
+Setup wizard:
+  npx -y @contextstream/mcp-server setup
+
 Notes:
   - When used from an MCP client (e.g. Codex, Cursor, VS Code),
     set these env vars in the client's MCP server configuration.
@@ -9405,6 +10191,10 @@ async function main() {
     console.log(`contextstream-mcp v${VERSION}`);
     return;
   }
+  if (args[0] === "setup") {
+    await runSetupWizard(args.slice(1));
+    return;
+  }
   const config = loadConfig();
   const client = new ContextStreamClient(config);
   const server = new McpServer({