@contextstream/mcp-server 0.4.19 → 0.4.21

package/dist/index.js

@@ -7482,6 +7482,7 @@ var CONTEXTSTREAM_TOOL_NAMES = [
   "session_init",
   "context_smart",
   "context_feedback",
+  "generate_rules",
   // Consolidated domain tools (v0.4.x default)
   "search",
   // Modes: semantic, hybrid, keyword, pattern
@@ -7518,7 +7519,7 @@ Rules Version: ${RULES_VERSION}
 
 | Message | What to Call |
 |---------|--------------|
-| **1st message** | \`session_init(folder_path="...", context_hint="<user's message>")\` |
+| **1st message** | \`session_init(folder_path="...", context_hint="<user's message>")\`, then \`context_smart(user_message="<user's message>", format="minified", max_tokens=400)\` |
 | **2nd+ messages** | \`context_smart(user_message="<user's message>", format="minified", max_tokens=400)\` |
 | **Before risky/non-trivial work** | \`session(action="get_lessons", query="<topic>")\` |
 | **After completing task** | \`session(action="capture", event_type="decision", ...)\` - MUST capture |
@@ -7527,7 +7528,9 @@ Rules Version: ${RULES_VERSION}
 
 **NO EXCEPTIONS.** Do not skip even if you think you have enough context.
 
-**Context Pack (Pro+):** If enabled, use \`context_smart(..., mode="pack", distill=true)\` for code/file queries. If unavailable, omit \`mode\` and use standard \`context_smart\`.
+**First message rule:** After \`session_init\`, always call \`context_smart\` before any other tool or response.
+
+**Context Pack (Pro+):** If enabled, use \`context_smart(..., mode="pack", distill=true)\` for code/file queries. If unavailable or disabled, omit \`mode\` and proceed with standard \`context_smart\` (the API will fall back).
 
 **Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses \`mcp__<server>__<tool>\` where \`<server>\` matches your MCP config (often \`contextstream\`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
 
@@ -7539,7 +7542,7 @@ v0.4.x consolidates ~58 individual tools into ~11 domain tools with action/mode
 
 ### Standalone Tools (Always Call)
 - **\`session_init\`** - Initialize session with workspace detection + context
-- **\`context_smart\`** - Semantic search for relevant context (CALL EVERY MESSAGE)
+- **\`context_smart\`** - Semantic search for relevant context (CALL EVERY MESSAGE, including immediately after \`session_init\`)
 
 ### Domain Tools (Use action/mode parameter)
 
@@ -7588,7 +7591,7 @@ If context still feels missing, use \`session(action="recall", query="...")\` fo
 
 ### Rules Update Notices
 
-- If you see **[RULES_NOTICE]**, update rules via \`generate_editor_rules(folder_path="<cwd>")\` (or rerun setup).
+- If you see **[RULES_NOTICE]**, update rules via \`generate_rules()\` (or rerun setup).
 - If you see **[VERSION_NOTICE]**, tell the user to update MCP using the provided command.
 
 ---
@@ -7621,9 +7624,9 @@ Only after this preflight, proceed with search/analysis below.
 2. \`search(mode="hybrid", query="...")\` or \`search(mode="keyword", query="<filename>")\`
 3. \`project(action="files")\` - file tree/list (only when needed)
 4. \`graph(action="dependencies", ...)\` - code structure
-5. Local repo scans (rg/ls/find) - only if ContextStream returns no results or is unavailable
+5. Local repo scans (rg/ls/find) - only if ContextStream returns no results, errors, or the user explicitly asks
 
-Use ContextStream results directly; only open files if you need exact code.
+If ContextStream returns results, stop and use them. Do NOT use local Search/Explore/Read unless you need exact code edits.
 
 **Code Analysis:**
 - Dependencies: \`graph(action="dependencies", file_path="...")\`
@@ -7709,13 +7712,13 @@ Rules Version: ${RULES_VERSION}
 
 | Message | What to Call |
 |---------|--------------|
-| **1st message** | \`session_init(folder_path="<cwd>", context_hint="<user_message>")\` |
+| **1st message** | \`session_init(folder_path="<cwd>", context_hint="<user_message>")\`, then \`context_smart(user_message="<user_message>", format="minified", max_tokens=400)\` |
 | **2nd+ messages** | \`context_smart(user_message="<user_message>", format="minified", max_tokens=400)\` |
 | **Capture decisions** | \`session(action="capture", event_type="decision", title="...", content="...")\` |
 | **Before risky work** | \`session(action="get_lessons", query="<topic>")\` |
 | **On user frustration** | \`session(action="capture_lesson", title="...", trigger="...", impact="...", prevention="...")\` |
 
-**Context Pack (Pro+):** If enabled, use \`context_smart(..., mode="pack", distill=true)\` for code/file queries. If unavailable, omit \`mode\`.
+**Context Pack (Pro+):** If enabled, use \`context_smart(..., mode="pack", distill=true)\` for code/file queries. If unavailable or disabled, omit \`mode\` and proceed with standard \`context_smart\` (the API will fall back).
 
 **Tool naming:** Use the exact tool names exposed by your MCP client. Claude Code typically uses \`mcp__<server>__<tool>\` where \`<server>\` matches your MCP config (often \`contextstream\`). If a tool call fails with "No such tool available", refresh rules and match the tool list.
 
@@ -7734,13 +7737,14 @@ Rules Version: ${RULES_VERSION}
 
 ### Behavior Rules
 
-- **First message**: Always call \`session_init\` with context_hint
+- **First message**: Call \`session_init\` with context_hint, then call \`context_smart\` before any other tool or response
 - **Every message after**: Always call \`context_smart\` BEFORE responding (semantic search for relevant context)
 - **Before searching files/code**: Check \`project(action="index_status")\`; if missing/stale run \`project(action="ingest_local", path="<cwd>")\` or \`project(action="index")\`, and use \`graph(action="ingest")\` if needed
 - **For discovery**: Use \`session(action="smart_search")\` or \`search(mode="hybrid")\` before any local repo scans
 - **For file/function/config lookups**: Use \`search\`/\`graph\` first; only fall back to rg/ls/find if ContextStream returns no results
+- **If ContextStream returns results**: Do NOT use local Search/Explore/Read; only open specific files when needed for exact edits
 - **For code analysis**: Use \`graph(action="dependencies")\` or \`graph(action="impact")\` for call/dependency analysis
-- **On [RULES_NOTICE]**: Use \`generate_editor_rules(folder_path="<cwd>")\` to update rules
+- **On [RULES_NOTICE]**: Use \`generate_rules()\` to update rules
 - **After completing work**: Always capture decisions/insights with \`session(action="capture")\`
 - **On mistakes/corrections**: Immediately capture lessons with \`session(action="capture_lesson")\`
 
@@ -8054,6 +8058,7 @@ var DEFAULT_PARAM_DESCRIPTIONS = {
   recurrence: "Recurrence pattern (daily, weekly, monthly).",
   keywords: "Keywords for matching.",
   overwrite: "Allow overwriting existing files on disk.",
+  overwrite_existing: "Allow overwriting existing rule files (ContextStream block only).",
   write_to_disk: "Write ingested files to disk before indexing.",
   await_indexing: "Wait for indexing to finish before returning.",
   auto_index: "Automatically index on creation.",
@@ -8172,12 +8177,12 @@ function getRulesNotice(folderPath, clientName) {
   const candidates = resolveRulesCandidatePaths(folderPath, editorKey);
   const existing = candidates.filter((filePath) => fs3.existsSync(filePath));
   if (existing.length === 0) {
-    const updateCommand2 = folderPath ? `generate_editor_rules(folder_path="${folderPath}")` : 'generate_editor_rules(folder_path="<cwd>")';
+    const updateCommand2 = "generate_rules()";
     const notice2 = {
       status: "missing",
       latest: RULES_VERSION,
       files_checked: candidates,
-      update_tool: "generate_editor_rules",
+      update_tool: "generate_rules",
       update_args: {
         ...folderPath ? { folder_path: folderPath } : {},
         editors: editorKey ? [editorKey] : ["all"]
@@ -8211,7 +8216,7 @@ function getRulesNotice(folderPath, clientName) {
     return null;
   }
   const current = versions.sort(compareVersions2).at(-1);
-  const updateCommand = folderPath ? `generate_editor_rules(folder_path="${folderPath}")` : 'generate_editor_rules(folder_path="<cwd>")';
+  const updateCommand = "generate_rules()";
   const notice = {
     status: filesOutdated.length > 0 ? "behind" : "unknown",
     current,
@@ -8219,7 +8224,7 @@ function getRulesNotice(folderPath, clientName) {
     files_checked: existing,
     ...filesOutdated.length > 0 ? { files_outdated: filesOutdated } : {},
     ...filesMissingVersion.length > 0 ? { files_missing_version: filesMissingVersion } : {},
-    update_tool: "generate_editor_rules",
+    update_tool: "generate_rules",
     update_args: {
       ...folderPath ? { folder_path: folderPath } : {},
       editors: editorKey ? [editorKey] : ["all"]
@@ -8261,6 +8266,19 @@ var LEGACY_CONTEXTSTREAM_ALLOWED_HEADINGS = [
   "plans & tasks",
   "complete action reference"
 ];
+var CONTEXTSTREAM_PREAMBLE_PATTERNS = [
+  /^#\s+workspace:/i,
+  /^#\s+project:/i,
+  /^#\s+workspace id:/i,
+  /^#\s+codex cli instructions$/i,
+  /^#\s+claude code instructions$/i,
+  /^#\s+cursor rules$/i,
+  /^#\s+windsurf rules$/i,
+  /^#\s+cline rules$/i,
+  /^#\s+kilo code rules$/i,
+  /^#\s+roo code rules$/i,
+  /^#\s+aider configuration$/i
+];
 function wrapWithMarkers(content) {
   return `${CONTEXTSTREAM_START_MARKER}
 ${content.trim()}
@@ -8281,6 +8299,96 @@ function isLegacyContextStreamRules(content) {
   }
   return hasHeading;
 }
+function isContextStreamPreamble(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return false;
+  return CONTEXTSTREAM_PREAMBLE_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+function findContextStreamHeading(lines) {
+  const headingRegex = /^(#{1,6})\s+(.+)$/;
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = headingRegex.exec(lines[i]);
+    if (!match) continue;
+    if (match[2].toLowerCase().includes("contextstream")) {
+      return { index: i, level: match[1].length };
+    }
+  }
+  return null;
+}
+function findSectionEnd(lines, startLine, level) {
+  const headingRegex = /^(#{1,6})\s+(.+)$/;
+  for (let i = startLine + 1; i < lines.length; i += 1) {
+    const match = headingRegex.exec(lines[i]);
+    if (!match) continue;
+    if (match[1].length <= level) return i;
+  }
+  return lines.length;
+}
+function extractContextStreamBlock(content) {
+  const lines = content.split(/\r?\n/);
+  const heading = findContextStreamHeading(lines);
+  if (!heading) return content.trim();
+  const endLine = findSectionEnd(lines, heading.index, heading.level);
+  return lines.slice(heading.index, endLine).join("\n").trim();
+}
+function findLegacyContextStreamSection(content) {
+  const lines = content.split(/\r?\n/);
+  const heading = findContextStreamHeading(lines);
+  if (!heading) return null;
+  let startLine = heading.index;
+  for (let i = heading.index - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (!line.trim()) {
+      startLine = i;
+      continue;
+    }
+    if (isContextStreamPreamble(line)) {
+      startLine = i;
+      continue;
+    }
+    break;
+  }
+  const endLine = findSectionEnd(lines, heading.index, heading.level);
+  return { startLine, endLine, contextLine: heading.index };
+}
+function blockHasPreamble(block) {
+  const lines = block.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (isContextStreamPreamble(trimmed)) return true;
+    if (/^#{1,6}\s+/.test(trimmed)) return false;
+  }
+  return false;
+}
+function replaceContextStreamBlock(existing, content) {
+  const fullWrapped = wrapWithMarkers(content);
+  const blockWrapped = wrapWithMarkers(extractContextStreamBlock(content));
+  const startIdx = existing.indexOf(CONTEXTSTREAM_START_MARKER);
+  const endIdx = existing.indexOf(CONTEXTSTREAM_END_MARKER);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const existingBlock = existing.slice(startIdx + CONTEXTSTREAM_START_MARKER.length, endIdx);
+    const replacement = blockHasPreamble(existingBlock) ? fullWrapped : blockWrapped;
+    const before = existing.substring(0, startIdx).trimEnd();
+    const after = existing.substring(endIdx + CONTEXTSTREAM_END_MARKER.length).trimStart();
+    const merged = [before, replacement, after].filter((part) => part.length > 0).join("\n\n");
+    return { content: merged.trim() + "\n", status: "updated" };
+  }
+  const legacy = findLegacyContextStreamSection(existing);
+  if (legacy) {
+    const lines = existing.split(/\r?\n/);
+    const before = lines.slice(0, legacy.startLine).join("\n").trimEnd();
+    const after = lines.slice(legacy.endLine).join("\n").trimStart();
+    const replacement = legacy.startLine < legacy.contextLine ? fullWrapped : blockWrapped;
+    const merged = [before, replacement, after].filter((part) => part.length > 0).join("\n\n");
+    return { content: merged.trim() + "\n", status: "updated" };
+  }
+  if (isLegacyContextStreamRules(existing)) {
+    return { content: fullWrapped + "\n", status: "updated" };
+  }
+  const appended = existing.trimEnd() + "\n\n" + blockWrapped + "\n";
+  return { content: appended, status: "appended" };
+}
 async function upsertRuleFile(filePath, content) {
   await fs3.promises.mkdir(path4.dirname(filePath), { recursive: true });
   const wrappedContent = wrapWithMarkers(content);
@@ -8293,22 +8401,13 @@ async function upsertRuleFile(filePath, content) {
     await fs3.promises.writeFile(filePath, wrappedContent + "\n", "utf8");
     return "created";
   }
-  const startIdx = existing.indexOf(CONTEXTSTREAM_START_MARKER);
-  const endIdx = existing.indexOf(CONTEXTSTREAM_END_MARKER);
-  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    const before = existing.substring(0, startIdx);
-    const after = existing.substring(endIdx + CONTEXTSTREAM_END_MARKER.length);
-    const updated = before.trimEnd() + "\n\n" + wrappedContent + "\n" + after.trimStart();
-    await fs3.promises.writeFile(filePath, updated.trim() + "\n", "utf8");
-    return "updated";
-  }
-  if (isLegacyContextStreamRules(existing)) {
+  if (!existing.trim()) {
     await fs3.promises.writeFile(filePath, wrappedContent + "\n", "utf8");
     return "updated";
   }
-  const joined = existing.trimEnd() + "\n\n" + wrappedContent + "\n";
-  await fs3.promises.writeFile(filePath, joined, "utf8");
-  return "appended";
+  const replaced = replaceContextStreamBlock(existing, content);
+  await fs3.promises.writeFile(filePath, replaced.content, "utf8");
+  return replaced.status;
 }
 async function writeEditorRules(options) {
   const editors = options.editors && options.editors.length > 0 ? options.editors : getAvailableEditors();
@@ -8326,6 +8425,10 @@ async function writeEditorRules(options) {
       continue;
     }
     const filePath = path4.join(options.folderPath, rule.filename);
+    if (fs3.existsSync(filePath) && !options.overwriteExisting) {
+      results.push({ editor, filename: rule.filename, status: "skipped (exists)" });
+      continue;
+    }
     try {
       const status = await upsertRuleFile(filePath, rule.content);
       results.push({ editor, filename: rule.filename, status });
@@ -8344,6 +8447,55 @@ async function writeEditorRules(options) {
   }
   return results;
 }
+function listGlobalRuleTargets(editors) {
+  const targets = [];
+  for (const editor of editors) {
+    const globalPaths = RULES_GLOBAL_FILES[editor];
+    if (!globalPaths || globalPaths.length === 0) {
+      continue;
+    }
+    for (const filePath of globalPaths) {
+      targets.push({ editor, filePath });
+    }
+  }
+  return targets;
+}
+async function writeGlobalRules(options) {
+  const results = [];
+  for (const editor of options.editors) {
+    const rule = generateRuleContent(editor, {
+      mode: options.mode
+    });
+    if (!rule) {
+      results.push({ editor, filename: "", status: "unknown editor", scope: "global" });
+      continue;
+    }
+    const globalPaths = RULES_GLOBAL_FILES[editor] ?? [];
+    if (globalPaths.length === 0) {
+      results.push({ editor, filename: rule.filename, status: "skipped (no global path)", scope: "global" });
+      continue;
+    }
+    for (const filePath of globalPaths) {
+      if (fs3.existsSync(filePath) && !options.overwriteExisting) {
+        results.push({ editor, filename: filePath, status: "skipped (exists)", scope: "global" });
+        continue;
+      }
+      try {
+        const status = await upsertRuleFile(filePath, rule.content);
+        results.push({ editor, filename: filePath, status, scope: "global" });
+      } catch (err) {
+        results.push({
+          editor,
+          filename: filePath,
+          status: `error: ${err.message}`,
+          scope: "global"
+        });
+      }
+    }
+  }
+  rulesNoticeCache.clear();
+  return results;
+}
 var WRITE_VERBS = /* @__PURE__ */ new Set([
   "create",
   "update",
@@ -8545,6 +8697,7 @@ var LIGHT_TOOLSET = /* @__PURE__ */ new Set([
   "session_delta",
   // Setup and configuration (3)
   "generate_editor_rules",
+  "generate_rules",
   "workspace_associate",
   "workspace_bootstrap",
   // Project management (5)
@@ -8590,6 +8743,7 @@ var STANDARD_TOOLSET = /* @__PURE__ */ new Set([
   "session_delta",
   // Setup and configuration (3)
   "generate_editor_rules",
+  "generate_rules",
   "workspace_associate",
   "workspace_bootstrap",
   // Workspace management (2)
@@ -8798,7 +8952,8 @@ var TOOL_BUNDLES = {
     "session_compress",
     "session_delta",
     "decision_trace",
-    "generate_editor_rules"
+    "generate_editor_rules",
+    "generate_rules"
   ]),
   // Memory bundle (~12 tools) - full memory CRUD operations
   memory: /* @__PURE__ */ new Set([
@@ -8933,7 +9088,7 @@ function inferOperationCategory(name) {
   if (name.startsWith("reminder")) return "Reminders";
   if (name.startsWith("slack_") || name.startsWith("github_") || name.startsWith("integration")) return "Integrations";
   if (name.startsWith("ai_")) return "AI";
-  if (name === "auth_me" || name === "mcp_server_version" || name === "generate_editor_rules") return "Utility";
+  if (name === "auth_me" || name === "mcp_server_version" || name === "generate_editor_rules" || name === "generate_rules") return "Utility";
   if (name === "tools_enable_bundle" || name === "contextstream" || name === "contextstream_help") return "Meta";
   return "Other";
 }
@@ -9007,6 +9162,8 @@ var CONSOLIDATED_TOOLS = /* @__PURE__ */ new Set([
   // Standalone - complex initialization
   "context_smart",
   // Standalone - called every message
+  "generate_rules",
+  // Standalone - rule generation helper
   "search",
   // Consolidates search_semantic, search_hybrid, search_keyword, search_pattern
   "session",
@@ -10039,7 +10196,8 @@ Access: Free`,
         description: external_exports.string().optional().describe("Project description"),
         workspace_id: external_exports.string().uuid().optional().describe("Workspace ID (uses current session workspace if not provided)"),
         folder_path: external_exports.string().optional().describe("Optional: Local folder path to associate with this project"),
-        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules in folder_path (requires folder_path)")
+        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules in folder_path (requires folder_path)"),
+        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files when generating editor rules")
       })
     },
     async (input) => {
@@ -10054,6 +10212,7 @@ Access: Free`,
       });
       const projectData = result;
       let rulesGenerated = [];
+      let rulesSkipped = [];
       if (input.folder_path && projectData.id) {
         try {
           const configDir = path4.join(input.folder_path, ".contextstream");
@@ -10072,9 +10231,11 @@ Access: Free`,
               folderPath: input.folder_path,
               editors: getAvailableEditors(),
               workspaceId,
-              projectName: input.name
+              projectName: input.name,
+              overwriteExisting: input.overwrite_existing
             });
             rulesGenerated = ruleResults.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").map((r) => r.status === "created" ? r.filename : `${r.filename} (${r.status})`);
+            rulesSkipped = ruleResults.filter((r) => r.status.startsWith("skipped")).map((r) => r.filename);
           }
         } catch (err) {
           console.error("[ContextStream] Failed to write project config:", err);
@@ -10084,7 +10245,8 @@ Access: Free`,
         ...result && typeof result === "object" ? result : {},
         folder_path: input.folder_path,
         config_written: input.folder_path ? true : void 0,
-        editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0
+        editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0,
+        editor_rules_skipped: rulesSkipped.length > 0 ? rulesSkipped : void 0
       };
       return { content: [{ type: "text", text: formatContent(response) }], structuredContent: toStructured(response) };
     }
@@ -11208,24 +11370,29 @@ Optionally generates AI editor rules for automatic ContextStream usage.`,
         workspace_id: external_exports.string().uuid().describe("Workspace ID to associate with"),
         workspace_name: external_exports.string().optional().describe("Workspace name for reference"),
         create_parent_mapping: external_exports.boolean().optional().describe("Also create a parent folder mapping (e.g., /dev/maker/* -> workspace)"),
-        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules for Windsurf, Cursor, Cline, Kilo Code, Roo Code, Claude Code, and Aider")
+        generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules for Windsurf, Cursor, Cline, Kilo Code, Roo Code, Claude Code, and Aider"),
+        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files when generating editor rules")
       })
     },
     async (input) => {
       const result = await client.associateWorkspace(input);
       let rulesGenerated = [];
+      let rulesSkipped = [];
       if (input.generate_editor_rules) {
         const ruleResults = await writeEditorRules({
           folderPath: input.folder_path,
           editors: getAvailableEditors(),
           workspaceName: input.workspace_name,
-          workspaceId: input.workspace_id
+          workspaceId: input.workspace_id,
+          overwriteExisting: input.overwrite_existing
         });
         rulesGenerated = ruleResults.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").map((r) => r.status === "created" ? r.filename : `${r.filename} (${r.status})`);
+        rulesSkipped = ruleResults.filter((r) => r.status.startsWith("skipped")).map((r) => r.filename);
       }
       const response = {
         ...result,
-        editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0
+        editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0,
+        editor_rules_skipped: rulesSkipped.length > 0 ? rulesSkipped : void 0
       };
       return { content: [{ type: "text", text: formatContent(response) }], structuredContent: toStructured(response) };
     }
@@ -11248,6 +11415,7 @@ Behavior:
         visibility: external_exports.enum(["private", "public"]).optional().describe("Workspace visibility (default: private)"),
         create_parent_mapping: external_exports.boolean().optional().describe("Also create a parent folder mapping (e.g., /dev/company/* -> workspace)"),
         generate_editor_rules: external_exports.boolean().optional().describe("Generate AI editor rules in the folder for automatic ContextStream usage"),
+        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files when generating editor rules"),
         context_hint: external_exports.string().optional().describe("Optional context hint for session initialization"),
         auto_index: external_exports.boolean().optional().describe("Automatically create and index project from folder (default: true)")
       })
@@ -11300,14 +11468,17 @@ Behavior:
         create_parent_mapping: input.create_parent_mapping
       });
       let rulesGenerated = [];
+      let rulesSkipped = [];
       if (input.generate_editor_rules) {
         const ruleResults = await writeEditorRules({
           folderPath,
           editors: getAvailableEditors(),
           workspaceName: newWorkspace.name || input.workspace_name,
-          workspaceId: newWorkspace.id
+          workspaceId: newWorkspace.id,
+          overwriteExisting: input.overwrite_existing
         });
         rulesGenerated = ruleResults.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").map((r) => r.status === "created" ? r.filename : `${r.filename} (${r.status})`);
+        rulesSkipped = ruleResults.filter((r) => r.status.startsWith("skipped")).map((r) => r.filename);
       }
       const session = await client.initSession(
         {
@@ -11332,7 +11503,8 @@ Behavior:
             name: newWorkspace.name || input.workspace_name
           },
           association: associateResult,
-          editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0
+          editor_rules_generated: rulesGenerated.length > 0 ? rulesGenerated : void 0,
+          editor_rules_skipped: rulesSkipped.length > 0 ? rulesSkipped : void 0
         }
       };
       return { content: [{ type: "text", text: formatContent(response) }], structuredContent: toStructured(response) };
@@ -11704,6 +11876,98 @@ Example: "What were the auth decisions?" or "What are my TypeScript preferences?
       return { content: [{ type: "text", text: formatContent(result) }], structuredContent: toStructured(result) };
     }
   );
+  registerTool(
+    "generate_rules",
+    {
+      title: "Generate ContextStream rules",
+      description: `Generate AI rule files for editors (Windsurf, Cursor, Cline, Kilo Code, Roo Code, Claude Code, Aider).
+Defaults to the current project folder; no folder_path required when run from a project.
+Supported editors: ${getAvailableEditors().join(", ")}`,
+      inputSchema: external_exports.object({
+        folder_path: external_exports.string().optional().describe("Absolute path to the project folder (defaults to IDE root/cwd)"),
+        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)"),
+        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files (ContextStream block only)"),
+        apply_global: external_exports.boolean().optional().describe("Also write global rule files for supported editors"),
+        dry_run: external_exports.boolean().optional().describe("If true, return content without writing files")
+      })
+    },
+    async (input) => {
+      const folderPath = resolveFolderPath(input.folder_path, sessionManager);
+      if (!folderPath) {
+        return errorResult("Error: folder_path is required. Provide folder_path or run from a project directory.");
+      }
+      const editors = input.editors?.includes("all") || !input.editors ? getAvailableEditors() : input.editors.filter((e) => e !== "all");
+      const results = [];
+      if (input.dry_run) {
+        for (const editor of editors) {
+          const rule = generateRuleContent(editor, {
+            workspaceName: input.workspace_name,
+            workspaceId: input.workspace_id,
+            projectName: input.project_name,
+            additionalRules: input.additional_rules,
+            mode: input.mode
+          });
+          if (!rule) {
+            results.push({ editor, filename: "", status: "unknown editor" });
+            continue;
+          }
+          results.push({
+            editor,
+            filename: rule.filename,
+            status: "dry run - would update"
+          });
+        }
+      } else {
+        const writeResults = await writeEditorRules({
+          folderPath,
+          editors,
+          workspaceName: input.workspace_name,
+          workspaceId: input.workspace_id,
+          projectName: input.project_name,
+          additionalRules: input.additional_rules,
+          mode: input.mode,
+          overwriteExisting: input.overwrite_existing
+        });
+        results.push(...writeResults);
+      }
+      const globalTargets = listGlobalRuleTargets(editors);
+      let globalResults;
+      if (input.apply_global) {
+        if (input.dry_run) {
+          globalResults = globalTargets.map((target) => ({
+            editor: target.editor,
+            filename: target.filePath,
+            status: "dry run - would update",
+            scope: "global"
+          }));
+        } else {
+          globalResults = await writeGlobalRules({
+            editors,
+            mode: input.mode,
+            overwriteExisting: input.overwrite_existing
+          });
+        }
+      }
+      const createdCount = results.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").length;
+      const skippedCount = results.filter((r) => r.status.startsWith("skipped")).length;
+      const baseMessage = input.dry_run ? "Dry run complete. Use dry_run: false to write files." : skippedCount > 0 ? `Generated ${createdCount} rule files. ${skippedCount} skipped (existing files). Re-run with overwrite_existing: true to replace ContextStream blocks.` : `Generated ${createdCount} rule files.`;
+      const globalPrompt = input.apply_global ? "Global rule update complete." : globalTargets.length > 0 ? "Apply rules globally too? Re-run with apply_global: true." : "No global rule locations are known for these editors.";
+      const summary = {
+        folder: folderPath,
+        results,
+        ...globalResults ? { global_results: globalResults } : {},
+        ...globalTargets.length > 0 ? { global_targets: globalTargets } : {},
+        message: baseMessage,
+        global_prompt: globalPrompt
+      };
+      return { content: [{ type: "text", text: formatContent(summary) }], structuredContent: toStructured(summary) };
+    }
+  );
   registerTool(
     "generate_editor_rules",
     {
@@ -11719,6 +11983,7 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
         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)"),
+        overwrite_existing: external_exports.boolean().optional().describe("Allow overwriting existing rule files (ContextStream block only)"),
         dry_run: external_exports.boolean().optional().describe("If true, return content without writing files")
       })
     },
@@ -11757,14 +12022,17 @@ Supported editors: ${getAvailableEditors().join(", ")}`,
           workspaceId: input.workspace_id,
           projectName: input.project_name,
           additionalRules: input.additional_rules,
-          mode: input.mode
+          mode: input.mode,
+          overwriteExisting: input.overwrite_existing
         });
         results.push(...writeResults);
       }
+      const createdCount = results.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").length;
+      const skippedCount = results.filter((r) => r.status.startsWith("skipped")).length;
       const summary = {
         folder: folderPath,
         results,
-        message: input.dry_run ? "Dry run complete. Use dry_run: false to write files." : `Generated ${results.filter((r) => r.status === "created" || r.status === "updated" || r.status === "appended").length} rule files.`
+        message: input.dry_run ? "Dry run complete. Use dry_run: false to write files." : skippedCount > 0 ? `Generated ${createdCount} rule files. ${skippedCount} skipped (existing files). Re-run with overwrite_existing: true to replace ContextStream blocks.` : `Generated ${createdCount} rule files.`
       };
       return { content: [{ type: "text", text: formatContent(summary) }], structuredContent: toStructured(summary) };
     }
@@ -15050,7 +15318,8 @@ function registerPrompts(server) {
               "- Otherwise ask me for an absolute folder path.",
               "- Ask which editor(s) (windsurf,cursor,cline,kilo,roo,claude,aider) or default to all.",
               "",
-              "Then call `generate_editor_rules` and confirm which files were created/updated."
+              "Then call `generate_rules` and confirm which files were created/updated.",
+              "Ask if the user also wants to apply rules globally (pass apply_global: true)."
             ].join("\n")
           }
         }
@@ -15821,6 +16090,19 @@ var LEGACY_CONTEXTSTREAM_ALLOWED_HEADINGS2 = [
   "plans & tasks",
   "complete action reference"
 ];
+var CONTEXTSTREAM_PREAMBLE_PATTERNS2 = [
+  /^#\s+workspace:/i,
+  /^#\s+project:/i,
+  /^#\s+workspace id:/i,
+  /^#\s+codex cli instructions$/i,
+  /^#\s+claude code instructions$/i,
+  /^#\s+cursor rules$/i,
+  /^#\s+windsurf rules$/i,
+  /^#\s+cline rules$/i,
+  /^#\s+kilo code rules$/i,
+  /^#\s+roo code rules$/i,
+  /^#\s+aider configuration$/i
+];
 function wrapWithMarkers2(content) {
   return `${CONTEXTSTREAM_START_MARKER2}
 ${content.trim()}
@@ -15841,6 +16123,96 @@ function isLegacyContextStreamRules2(content) {
   }
   return hasHeading;
 }
+function isContextStreamPreamble2(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return false;
+  return CONTEXTSTREAM_PREAMBLE_PATTERNS2.some((pattern) => pattern.test(trimmed));
+}
+function findContextStreamHeading2(lines) {
+  const headingRegex = /^(#{1,6})\s+(.+)$/;
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = headingRegex.exec(lines[i]);
+    if (!match) continue;
+    if (match[2].toLowerCase().includes("contextstream")) {
+      return { index: i, level: match[1].length };
+    }
+  }
+  return null;
+}
+function findSectionEnd2(lines, startLine, level) {
+  const headingRegex = /^(#{1,6})\s+(.+)$/;
+  for (let i = startLine + 1; i < lines.length; i += 1) {
+    const match = headingRegex.exec(lines[i]);
+    if (!match) continue;
+    if (match[1].length <= level) return i;
+  }
+  return lines.length;
+}
+function extractContextStreamBlock2(content) {
+  const lines = content.split(/\r?\n/);
+  const heading = findContextStreamHeading2(lines);
+  if (!heading) return content.trim();
+  const endLine = findSectionEnd2(lines, heading.index, heading.level);
+  return lines.slice(heading.index, endLine).join("\n").trim();
+}
+function findLegacyContextStreamSection2(content) {
+  const lines = content.split(/\r?\n/);
+  const heading = findContextStreamHeading2(lines);
+  if (!heading) return null;
+  let startLine = heading.index;
+  for (let i = heading.index - 1; i >= 0; i -= 1) {
+    const line = lines[i];
+    if (!line.trim()) {
+      startLine = i;
+      continue;
+    }
+    if (isContextStreamPreamble2(line)) {
+      startLine = i;
+      continue;
+    }
+    break;
+  }
+  const endLine = findSectionEnd2(lines, heading.index, heading.level);
+  return { startLine, endLine, contextLine: heading.index };
+}
+function blockHasPreamble2(block) {
+  const lines = block.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (isContextStreamPreamble2(trimmed)) return true;
+    if (/^#{1,6}\s+/.test(trimmed)) return false;
+  }
+  return false;
+}
+function replaceContextStreamBlock2(existing, content) {
+  const fullWrapped = wrapWithMarkers2(content);
+  const blockWrapped = wrapWithMarkers2(extractContextStreamBlock2(content));
+  const startIdx = existing.indexOf(CONTEXTSTREAM_START_MARKER2);
+  const endIdx = existing.indexOf(CONTEXTSTREAM_END_MARKER2);
+  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+    const existingBlock = existing.slice(startIdx + CONTEXTSTREAM_START_MARKER2.length, endIdx);
+    const replacement = blockHasPreamble2(existingBlock) ? fullWrapped : blockWrapped;
+    const before = existing.substring(0, startIdx).trimEnd();
+    const after = existing.substring(endIdx + CONTEXTSTREAM_END_MARKER2.length).trimStart();
+    const merged = [before, replacement, after].filter((part) => part.length > 0).join("\n\n");
+    return { content: merged.trim() + "\n", status: "updated" };
+  }
+  const legacy = findLegacyContextStreamSection2(existing);
+  if (legacy) {
+    const lines = existing.split(/\r?\n/);
+    const before = lines.slice(0, legacy.startLine).join("\n").trimEnd();
+    const after = lines.slice(legacy.endLine).join("\n").trimStart();
+    const replacement = legacy.startLine < legacy.contextLine ? fullWrapped : blockWrapped;
+    const merged = [before, replacement, after].filter((part) => part.length > 0).join("\n\n");
+    return { content: merged.trim() + "\n", status: "updated" };
+  }
+  if (isLegacyContextStreamRules2(existing)) {
+    return { content: fullWrapped + "\n", status: "updated" };
+  }
+  const appended = existing.trimEnd() + "\n\n" + blockWrapped + "\n";
+  return { content: appended, status: "appended" };
+}
 async function upsertTextFile(filePath, content, _marker) {
   await fs5.mkdir(path6.dirname(filePath), { recursive: true });
   const exists = await fileExists(filePath);
@@ -15850,22 +16222,13 @@ async function upsertTextFile(filePath, content, _marker) {
     return "created";
   }
   const existing = await fs5.readFile(filePath, "utf8").catch(() => "");
-  const startIdx = existing.indexOf(CONTEXTSTREAM_START_MARKER2);
-  const endIdx = existing.indexOf(CONTEXTSTREAM_END_MARKER2);
-  if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
-    const before = existing.substring(0, startIdx);
-    const after = existing.substring(endIdx + CONTEXTSTREAM_END_MARKER2.length);
-    const updated = before.trimEnd() + "\n\n" + wrappedContent + "\n" + after.trimStart();
-    await fs5.writeFile(filePath, updated.trim() + "\n", "utf8");
-    return "updated";
-  }
-  if (isLegacyContextStreamRules2(existing)) {
+  if (!existing.trim()) {
     await fs5.writeFile(filePath, wrappedContent + "\n", "utf8");
     return "updated";
   }
-  const joined = existing.trimEnd() + "\n\n" + wrappedContent + "\n";
-  await fs5.writeFile(filePath, joined, "utf8");
-  return "appended";
+  const replaced = replaceContextStreamBlock2(existing, content);
+  await fs5.writeFile(filePath, replaced.content, "utf8");
+  return replaced.status;
 }
 function globalRulesPathForEditor(editor) {
   const home = homedir4();
@@ -16250,6 +16613,27 @@ async function runSetupWizard(args) {
   const dryRun = args.includes("--dry-run");
   const rl = createInterface({ input: stdin, output: stdout });
   const writeActions = [];
+  let overwriteAllRules = null;
+  let skipAllRules = false;
+  const confirmOverwriteRules = async (filePath) => {
+    if (dryRun) return true;
+    if (skipAllRules) return false;
+    if (overwriteAllRules) return true;
+    const exists = await fileExists(filePath);
+    if (!exists) return true;
+    const answer = normalizeInput(
+      await rl.question(`Rules file already exists at ${filePath}. Replace ContextStream block? [y/N/a/s]: `)
+    ).toLowerCase();
+    if (answer === "a" || answer === "all") {
+      overwriteAllRules = true;
+      return true;
+    }
+    if (answer === "s" || answer === "skip-all" || answer === "none") {
+      skipAllRules = true;
+      return false;
+    }
+    return answer === "y" || answer === "yes";
+  };
   try {
     console.log(`ContextStream Setup Wizard (v${VERSION})`);
     console.log("This configures ContextStream MCP + rules for your AI editor(s).");
@@ -16622,6 +17006,12 @@ Detected plan: ${planLabel} (graph: ${graphTierLabel})`);
           console.log(`- ${EDITOR_LABELS[editor]}: would write ${filePath}`);
           continue;
         }
+        const allowOverwrite = await confirmOverwriteRules(filePath);
+        if (!allowOverwrite) {
+          writeActions.push({ kind: "rules", target: filePath, status: "skipped" });
+          console.log(`- ${EDITOR_LABELS[editor]}: skipped ${filePath}`);
+          continue;
+        }
         const status = await upsertTextFile(filePath, rule.content, "ContextStream");
         writeActions.push({ kind: "rules", target: filePath, status });
         console.log(`- ${EDITOR_LABELS[editor]}: ${status} ${filePath}`);
@@ -16757,6 +17147,11 @@ Applying to ${projects.length} project(s)...`);
           continue;
         }
         try {
+          const allowOverwrite = await confirmOverwriteRules(filePath);
+          if (!allowOverwrite) {
+            writeActions.push({ kind: "rules", target: filePath, status: "skipped" });
+            continue;
+          }
           const status = await upsertTextFile(filePath, rule.content, "ContextStream");
           writeActions.push({ kind: "rules", target: filePath, status });
         } catch (err) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contextstream/mcp-server",
   "mcpName": "io.github.contextstreamio/mcp-server",
-  "version": "0.4.19",
+  "version": "0.4.21",
   "description": "ContextStream MCP server - v0.4.x with consolidated domain tools (~11 tools, ~75% token reduction). Code context, memory, search, and AI tools.",
   "type": "module",
   "license": "MIT",