speclore 0.1.6 → 0.1.8

package/dist/index.js

@@ -1,12 +1,7 @@
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res, err) => function __init() {
-  if (err) throw err[0];
-  try {
-    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-  } catch (e) {
-    throw err = [e], e;
-  }
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -323,7 +318,7 @@ function detectAITools(projectRoot2) {
     detected: existsSync2(join2(projectRoot2, ".cursor")),
     configFiles: cursorConfigs
   });
-  const claudeFiles = [".claude/", ".mcp.json", "CLAUDE.md"];
+  const claudeFiles = [".claude/", "CLAUDE.md"];
   const claudeConfigs = claudeFiles.filter((f) => existsSync2(join2(projectRoot2, f)));
   tools.push({
     tool: "claude",
@@ -759,7 +754,7 @@ var init_graph_builder = __esm({
 });
 
 // src/core/context-engine/context-writer.ts
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync7, statSync as statSync2, mkdirSync as mkdirSync4 } from "fs";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync7, statSync as statSync2, mkdirSync as mkdirSync5 } from "fs";
 import { join as join10 } from "path";
 import { execFileSync } from "child_process";
 function buildContext(projectRoot2, config) {
@@ -830,7 +825,7 @@ function loadContext(specLoreDir) {
 }
 function writeContextFile(specLoreDir, context) {
   if (!existsSync7(specLoreDir)) {
-    mkdirSync4(specLoreDir, { recursive: true });
+    mkdirSync5(specLoreDir, { recursive: true });
   }
   const contextPath = join10(specLoreDir, CONTEXT_FILENAME);
   writeFileSync5(contextPath, JSON.stringify(context, null, 2), "utf-8");
@@ -1021,7 +1016,7 @@ var init_cost_tracker = __esm({
 });
 
 // src/core/state-manager/index.ts
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync5 } from "fs";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync6 } from "fs";
 import { join as join12 } from "path";
 import yaml2 from "js-yaml";
 import { globSync as globSync2 } from "glob";
@@ -1070,7 +1065,7 @@ var init_state_manager = __esm({
       save(state) {
         const dir = join12(this.projectRoot, ".speclore");
         if (!existsSync8(dir)) {
-          mkdirSync5(dir, { recursive: true });
+          mkdirSync6(dir, { recursive: true });
         }
         writeFileSync6(this.statePath, yaml2.dump(state, { lineWidth: 120 }), "utf-8");
       }
@@ -1427,7 +1422,43 @@ var init_excel_utils = __esm({
 });
 
 // src/plugins/builtin/xlsx-reader.ts
-import { readFile, utils } from "xlsx";
+import { readFile, read, utils } from "xlsx";
+function parseWorkbook(workbook) {
+  const requirements = [];
+  for (const sheetName of workbook.SheetNames) {
+    const sheet = workbook.Sheets[sheetName];
+    if (!sheet) continue;
+    const allRows = utils.sheet_to_json(sheet, { header: 1, defval: "" });
+    if (allRows.length === 0) continue;
+    const headers = allRows[0].map((cell) => formatCellValue(cell));
+    const dataRows = allRows.slice(1);
+    const rows = dataRows.map((row) => {
+      const obj = {};
+      row.forEach((cell, colNumber) => {
+        const key = headers[colNumber] ?? `Col${colNumber + 1}`;
+        obj[key] = formatCellValue(cell);
+      });
+      return obj;
+    });
+    for (let i = 0; i < rows.length; i++) {
+      const row = rows[i];
+      const title = row["Title"] ?? row["title"] ?? row["Name"] ?? row["name"] ?? row["ID"] ?? `Row ${i + 1}`;
+      const description = row["Description"] ?? row["description"] ?? row["Desc"] ?? "";
+      const ac = row["Acceptance Criteria"] ?? row["acceptance"] ?? row["AC"] ?? "";
+      if (description || title) {
+        requirements.push({
+          id: `${sheetName}/${i + 1}`,
+          title: String(title),
+          description: String(description),
+          acceptanceCriteria: ac ? String(ac).split("\n").filter(Boolean) : void 0,
+          rawContent: JSON.stringify(row),
+          confidence: 0.7
+        });
+      }
+    }
+  }
+  return requirements;
+}
 var XlsxReader;
 var init_xlsx_reader = __esm({
   "src/plugins/builtin/xlsx-reader.ts"() {
@@ -1441,40 +1472,7 @@ var init_xlsx_reader = __esm({
       }
       read(source) {
         const workbook = readFile(source);
-        const requirements = [];
-        for (const sheetName of workbook.SheetNames) {
-          const sheet = workbook.Sheets[sheetName];
-          if (!sheet) continue;
-          const allRows = utils.sheet_to_json(sheet, { header: 1, defval: "" });
-          if (allRows.length === 0) continue;
-          const headers = allRows[0].map((cell) => formatCellValue(cell));
-          const dataRows = allRows.slice(1);
-          const rows = dataRows.map((row) => {
-            const obj = {};
-            row.forEach((cell, colNumber) => {
-              const key = headers[colNumber] ?? `Col${colNumber + 1}`;
-              obj[key] = formatCellValue(cell);
-            });
-            return obj;
-          });
-          for (let i = 0; i < rows.length; i++) {
-            const row = rows[i];
-            const title = row["Title"] ?? row["title"] ?? row["Name"] ?? row["name"] ?? row["ID"] ?? `Row ${i + 1}`;
-            const description = row["Description"] ?? row["description"] ?? row["Desc"] ?? "";
-            const ac = row["Acceptance Criteria"] ?? row["acceptance"] ?? row["AC"] ?? "";
-            if (description || title) {
-              requirements.push({
-                id: `${sheetName}/${i + 1}`,
-                title: String(title),
-                description: String(description),
-                acceptanceCriteria: ac ? String(ac).split("\n").filter(Boolean) : void 0,
-                rawContent: JSON.stringify(row),
-                confidence: 0.7
-              });
-            }
-          }
-        }
-        return Promise.resolve(requirements);
+        return Promise.resolve(parseWorkbook(workbook));
       }
     };
   }
@@ -1492,21 +1490,33 @@ var init_pdf_reader = __esm({
         return /\.pdf$/i.test(source);
       }
       async read(source) {
-        let pdfParse;
+        let pdfjsLib;
         try {
-          const mod = await import("pdf-parse");
-          pdfParse = mod.default ?? mod;
+          pdfjsLib = await import("pdfjs-dist/legacy/build/pdf.mjs");
         } catch {
-          throw new Error("pdf-parse package is required for PDF support. Install: npm i pdf-parse");
+          throw new Error("pdfjs-dist package is required for PDF support. Install: npm i pdfjs-dist");
+        }
+        const { readFileSync: readFileSync24 } = await import("fs");
+        const buffer = readFileSync24(source);
+        const uint8 = new Uint8Array(buffer);
+        const doc = await pdfjsLib.getDocument({
+          data: uint8,
+          useWorkerFetch: false
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        }).promise;
+        const textParts = [];
+        for (let i = 1; i <= doc.numPages; i++) {
+          const page = await doc.getPage(i);
+          const textContent = await page.getTextContent();
+          const pageText = textContent.items.map((item) => item.str).join("");
+          if (pageText) textParts.push(pageText);
         }
-        const { readFileSync: readFileSync22 } = await import("fs");
-        const buffer = readFileSync22(source);
-        const data = await pdfParse(buffer);
+        const text = textParts.join("\n");
         return [{
           id: source.replace(/\\/g, "/").replace(/\.pdf$/i, ""),
           title: source.split("/").pop()?.replace(/\.pdf$/i, "") ?? "Untitled",
-          description: data.text,
-          rawContent: data.text,
+          description: text,
+          rawContent: text,
           confidence: 0.75
         }];
       }
@@ -2102,13 +2112,13 @@ var init_image_reader = __esm({
         return /\.(png|jpe?g|webp)$/i.test(source);
       }
       async read(source) {
-        const { existsSync: existsSync30, readFileSync: readFileSync22 } = await import("fs");
-        if (!existsSync30(source)) {
+        const { existsSync: existsSync31, readFileSync: readFileSync24 } = await import("fs");
+        if (!existsSync31(source)) {
           throw new Error(`Image file not found: ${source}`);
         }
         const ext = source.split(".").pop()?.toLowerCase() ?? "png";
         const mimeType = ext === "jpg" ? "image/jpeg" : `image/${ext}`;
-        const buffer = readFileSync22(source);
+        const buffer = readFileSync24(source);
         let text;
         try {
           const { createProvider: createProvider2 } = await Promise.resolve().then(() => (init_provider(), provider_exports));
@@ -2137,7 +2147,7 @@ var init_image_reader = __esm({
 });
 
 // src/plugins/builtin/cursor-writer.ts
-import { writeFileSync as writeFileSync7, mkdirSync as mkdirSync6, existsSync as existsSync11, rmSync } from "fs";
+import { writeFileSync as writeFileSync7, mkdirSync as mkdirSync7, existsSync as existsSync11, rmSync } from "fs";
 import { join as join14 } from "path";
 var CursorWriter;
 var init_cursor_writer = __esm({
@@ -2153,7 +2163,7 @@ var init_cursor_writer = __esm({
       write(constraints) {
         this.projectRoot = constraints.projectRoot;
         const rulesDir = join14(constraints.projectRoot, ".cursor", "rules");
-        mkdirSync6(rulesDir, { recursive: true });
+        mkdirSync7(rulesDir, { recursive: true });
         const frontmatter = [
           "---",
           "description: SpecLore coding constraints \u2014 auto-generated",
@@ -2232,7 +2242,7 @@ var init_cursor_writer = __esm({
 });
 
 // src/plugins/builtin/claude-writer.ts
-import { writeFileSync as writeFileSync8, mkdirSync as mkdirSync7, existsSync as existsSync12, rmSync as rmSync2 } from "fs";
+import { writeFileSync as writeFileSync8, mkdirSync as mkdirSync8, existsSync as existsSync12, rmSync as rmSync2 } from "fs";
 import { join as join15 } from "path";
 var ClaudeWriter;
 var init_claude_writer = __esm({
@@ -2248,7 +2258,7 @@ var init_claude_writer = __esm({
       write(constraints) {
         this.projectRoot = constraints.projectRoot;
         const rulesDir = join15(constraints.projectRoot, ".claude", "rules");
-        mkdirSync7(rulesDir, { recursive: true });
+        mkdirSync8(rulesDir, { recursive: true });
         const content = this.buildMarkdown(constraints);
         writeFileSync8(join15(rulesDir, "speclore.md"), content, "utf-8");
         return Promise.resolve();
@@ -2314,7 +2324,7 @@ var init_claude_writer = __esm({
 });
 
 // src/plugins/builtin/qoder-writer.ts
-import { writeFileSync as writeFileSync9, mkdirSync as mkdirSync8, existsSync as existsSync13, rmSync as rmSync3 } from "fs";
+import { writeFileSync as writeFileSync9, mkdirSync as mkdirSync9, existsSync as existsSync13, rmSync as rmSync3 } from "fs";
 import { join as join16 } from "path";
 var QoderWriter;
 var init_qoder_writer = __esm({
@@ -2330,7 +2340,7 @@ var init_qoder_writer = __esm({
       write(constraints) {
         this.projectRoot = constraints.projectRoot;
         const rulesDir = join16(constraints.projectRoot, ".qoder", "rules");
-        mkdirSync8(rulesDir, { recursive: true });
+        mkdirSync9(rulesDir, { recursive: true });
         const content = this.buildMarkdown(constraints);
         writeFileSync9(join16(rulesDir, "speclore.md"), content, "utf-8");
         return Promise.resolve();
@@ -2763,11 +2773,12 @@ var init_markdown_reader = __esm({
 
 // src/core/requirement-reader/docx-reader.ts
 import { basename as basename3, extname as extname3 } from "path";
+import { readFileSync as readFileSync10 } from "fs";
 import mammoth from "mammoth";
-async function readDocxFile(filePath) {
-  const result = await mammoth.extractRawText({ path: filePath });
+async function parseDocxBuffer(buffer, idHint = "document") {
+  const result = await mammoth.extractRawText({ buffer });
   const content = result.value;
-  const id = basename3(filePath, extname3(filePath)).toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff-]/g, "-").replace(/-+/g, "-");
+  const id = idHint.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff-]/g, "-").replace(/-+/g, "-");
   const lines = content.split("\n").filter((l) => l.trim());
   const title = lines[0]?.trim() ?? id;
   return {
@@ -2778,6 +2789,11 @@ async function readDocxFile(filePath) {
     confidence: 0.9
   };
 }
+async function readDocxFile(filePath) {
+  const buffer = readFileSync10(filePath);
+  const name = basename3(filePath, extname3(filePath));
+  return parseDocxBuffer(buffer, name);
+}
 var init_docx_reader2 = __esm({
   "src/core/requirement-reader/docx-reader.ts"() {
     "use strict";
@@ -2786,17 +2802,16 @@ var init_docx_reader2 = __esm({
 
 // src/core/requirement-reader/xlsx-reader.ts
 import { basename as basename4, extname as extname4 } from "path";
-import { readFile as readFile2, utils as utils2 } from "xlsx";
-function readXlsxFile(filePath) {
-  const workbook = readFile2(filePath);
-  const id = basename4(filePath, extname4(filePath)).toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff-]/g, "-").replace(/-+/g, "-");
+import { readFile as readFile2, read as read2, utils as utils2 } from "xlsx";
+function parseWorkbook2(workbook, idHint) {
+  const id = idHint.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff-]/g, "-").replace(/-+/g, "-");
   const firstSheetName = workbook.SheetNames[0];
   if (!firstSheetName) {
-    return Promise.reject(new Error(`No sheets found in ${filePath}`));
+    return Promise.reject(new Error("No sheets found in workbook"));
   }
   const sheet = workbook.Sheets[firstSheetName];
   if (!sheet) {
-    return Promise.reject(new Error(`Sheet "${firstSheetName}" not found in ${filePath}`));
+    return Promise.reject(new Error(`Sheet "${firstSheetName}" not found`));
   }
   const title = firstSheetName;
   const rows = utils2.sheet_to_json(sheet, { header: 1, defval: "" });
@@ -2832,6 +2847,11 @@ function readXlsxFile(filePath) {
     confidence: 0.85
   });
 }
+function readXlsxFile(filePath) {
+  const workbook = readFile2(filePath);
+  const idHint = basename4(filePath, extname4(filePath));
+  return parseWorkbook2(workbook, idHint);
+}
 var init_xlsx_reader2 = __esm({
   "src/core/requirement-reader/xlsx-reader.ts"() {
     "use strict";
@@ -2842,21 +2862,40 @@ var init_xlsx_reader2 = __esm({
 // src/core/requirement-reader/pdf-reader.ts
 import { basename as basename5, extname as extname5 } from "path";
 import { readFile as readFile3 } from "fs/promises";
-async function readPdfFile(filePath) {
-  const pdfParse = (await import("pdf-parse")).default;
-  const dataBuffer = await readFile3(filePath);
-  const data = await pdfParse(dataBuffer);
-  const id = basename5(filePath, extname5(filePath)).toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff-]/g, "-").replace(/-+/g, "-");
-  const lines = data.text.split("\n").filter((l) => l.trim());
+async function extractPdfText(dataBuffer) {
+  const pdfjsLib = await import("pdfjs-dist/legacy/build/pdf.mjs");
+  const uint8 = new Uint8Array(dataBuffer);
+  const doc = await pdfjsLib.getDocument({
+    data: uint8,
+    useWorkerFetch: false
+  }).promise;
+  const textParts = [];
+  for (let i = 1; i <= doc.numPages; i++) {
+    const page = await doc.getPage(i);
+    const textContent = await page.getTextContent();
+    const pageText = textContent.items.map((item) => item.str).join("");
+    if (pageText) textParts.push(pageText);
+  }
+  return textParts.join("\n");
+}
+async function parsePdfBuffer(dataBuffer, idHint = "document") {
+  const text = await extractPdfText(dataBuffer);
+  const id = idHint.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff-]/g, "-").replace(/-+/g, "-");
+  const lines = text.split("\n").filter((l) => l.trim());
   const title = lines[0]?.trim() ?? id;
   return {
     id,
     title,
-    description: data.text,
-    rawContent: data.text,
+    description: text,
+    rawContent: text,
     confidence: 0.8
   };
 }
+async function readPdfFile(filePath) {
+  const dataBuffer = await readFile3(filePath);
+  const name = basename5(filePath, extname5(filePath));
+  return parsePdfBuffer(dataBuffer, name);
+}
 var init_pdf_reader2 = __esm({
   "src/core/requirement-reader/pdf-reader.ts"() {
     "use strict";
@@ -2865,14 +2904,14 @@ var init_pdf_reader2 = __esm({
 
 // src/core/requirement-reader/image-reader.ts
 import { basename as basename6, extname as extname6 } from "path";
-import { readFileSync as readFileSync10 } from "fs";
-async function readImageFile(filePath) {
+import { readFileSync as readFileSync11 } from "fs";
+async function readImageFile(filePath, providerOverride) {
   const id = basename6(filePath, extname6(filePath)).toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff-]/g, "-").replace(/-+/g, "-");
   logger.info(`Reading image via AI Vision: ${filePath}`);
   const ext = extname6(filePath).toLowerCase();
   const mimeType = MIME_MAP[ext] ?? "image/png";
-  const buffer = readFileSync10(filePath);
-  const provider = await createProvider();
+  const buffer = readFileSync11(filePath);
+  const provider = providerOverride ?? await createProvider();
   const prompt = `Please extract all text content from this image. Return the text as-is, preserving structure and formatting. If the image contains a table, convert it to a structured text format.`;
   if (!provider.generateWithImage) {
     throw new Error(`AI provider '${provider.name}' does not support image/vision input. Use a vision-capable model.`);
@@ -3317,11 +3356,11 @@ var init_prompt_builder = __esm({
 });
 
 // src/core/feature-generator/generator.ts
-import { writeFileSync as writeFileSync10, mkdirSync as mkdirSync9, existsSync as existsSync15 } from "fs";
+import { writeFileSync as writeFileSync10, mkdirSync as mkdirSync10, existsSync as existsSync15 } from "fs";
 import { join as join17, dirname as dirname2 } from "path";
 import { Parser as Parser2, GherkinClassicTokenMatcher as GherkinClassicTokenMatcher2, AstBuilder as AstBuilder2 } from "@cucumber/gherkin";
 import { IdGenerator as IdGenerator2 } from "@cucumber/messages";
-async function generateFeature(requirement, context, config, projectRoot2) {
+async function generateFeature(requirement, context, config, projectRoot2, providerOverride) {
   logger.info(`Generating feature for: ${requirement.title}`);
   const registry = getRegistry();
   await registry.invokeLifecycle("beforeSpec", requirement);
@@ -3329,7 +3368,7 @@ async function generateFeature(requirement, context, config, projectRoot2) {
   const aiConfig = config.ai;
   const fallbackConfigs = aiConfig?.fallbackProviders ?? [];
   const providerConfigs = aiConfig ? [aiConfig, ...fallbackConfigs] : [];
-  const provider = providerConfigs.length > 1 ? await createProviderChain(providerConfigs) : await createProvider(aiConfig);
+  const provider = providerOverride ?? (providerConfigs.length > 1 ? await createProviderChain(providerConfigs) : await createProvider(aiConfig));
   if (!provider.isAvailable()) {
     throw new Error("AI provider not available. Set API key in environment or config.yaml.");
   }
@@ -3386,7 +3425,7 @@ Please fix these issues and regenerate the complete Feature file.`;
   const moduleDir = inferModule(requirement, context);
   const filePath = join17(outputDir, moduleDir, `${requirement.id}.feature`);
   if (!existsSync15(dirname2(filePath))) {
-    mkdirSync9(dirname2(filePath), { recursive: true });
+    mkdirSync10(dirname2(filePath), { recursive: true });
   }
   writeFileSync10(filePath, featureContent, "utf-8");
   logger.info(`Feature written: ${toPosixPath(filePath)}`);
@@ -3552,9 +3591,9 @@ function detectAITools2(projectRoot2) {
     tools.push("cursor");
     logger.debug("Detected Cursor (.cursor/)");
   }
-  if (existsSync16(join19(projectRoot2, ".claude")) || existsSync16(join19(projectRoot2, "CLAUDE.md")) || existsSync16(join19(projectRoot2, ".mcp.json"))) {
+  if (existsSync16(join19(projectRoot2, ".claude")) || existsSync16(join19(projectRoot2, "CLAUDE.md"))) {
     tools.push("claude");
-    logger.debug("Detected Claude Code (.claude/ or CLAUDE.md or .mcp.json)");
+    logger.debug("Detected Claude Code (.claude/ or CLAUDE.md)");
   }
   if (existsSync16(join19(projectRoot2, ".qoder"))) {
     tools.push("qoder");
@@ -3571,7 +3610,7 @@ var init_ai_tool_detector = __esm({
 });
 
 // src/core/constraint-coder/constraint-writer.ts
-import { writeFileSync as writeFileSync11, mkdirSync as mkdirSync10, existsSync as existsSync17 } from "fs";
+import { writeFileSync as writeFileSync11, mkdirSync as mkdirSync11, existsSync as existsSync17 } from "fs";
 import { join as join20 } from "path";
 function writeConstraints(projectRoot2, tools, content) {
   const writtenFiles = [];
@@ -3645,7 +3684,7 @@ function buildConstraintText(content) {
 }
 function writeCursorRule2(projectRoot2, text) {
   const dir = join20(projectRoot2, ".cursor", "rules");
-  if (!existsSync17(dir)) mkdirSync10(dir, { recursive: true });
+  if (!existsSync17(dir)) mkdirSync11(dir, { recursive: true });
   const filePath = join20(dir, "speclore.mdc");
   const frontmatter = [
     "---",
@@ -3660,14 +3699,14 @@ function writeCursorRule2(projectRoot2, text) {
 }
 function writeClaudeRule2(projectRoot2, text) {
   const dir = join20(projectRoot2, ".claude", "rules");
-  if (!existsSync17(dir)) mkdirSync10(dir, { recursive: true });
+  if (!existsSync17(dir)) mkdirSync11(dir, { recursive: true });
   const filePath = join20(dir, "speclore.md");
   writeFileSync11(filePath, text, "utf-8");
   return filePath;
 }
 function writeQoderRule2(projectRoot2, text) {
   const dir = join20(projectRoot2, ".qoder", "rules");
-  if (!existsSync17(dir)) mkdirSync10(dir, { recursive: true });
+  if (!existsSync17(dir)) mkdirSync11(dir, { recursive: true });
   const filePath = join20(dir, "speclore.md");
   writeFileSync11(filePath, text, "utf-8");
   return filePath;
@@ -3747,14 +3786,14 @@ var init_constraint_coder = __esm({
     init_logger();
     init_ai_tool_detector();
     init_constraint_writer();
-    MAPPING_INSTRUCTIONS = `\u4E3A\u6BCF\u4E2A\u6D4B\u8BD5\u6587\u4EF6\u751F\u6210\u5BF9\u5E94\u7684\u6620\u5C04\u6587\u4EF6\u5230 .speclore/mappings/{module}/{feature-name}.json\u3002
-\u683C\u5F0F\uFF1A{ "feature": "specs/...", "scenarios": { "Scenario\u540D\u79F0": { "testFile": "...", "testMethod": "..." } } }
-\u6BCF\u6B21\u4FEE\u6539\u6D4B\u8BD5\u65F6\u540C\u6B65\u66F4\u65B0\u6620\u5C04\u6587\u4EF6\u3002`;
+    MAPPING_INSTRUCTIONS = `Generate a mapping file for each test file at .speclore/mappings/{module}/{feature-name}.json.
+Format: { "feature": "specs/...", "scenarios": { "Scenario name": { "testFile": "...", "testMethod": "..." } } }
+Keep mapping files in sync whenever tests are modified.`;
   }
 });
 
 // src/core/test-scaffolder/framework-detector.ts
-import { readFileSync as readFileSync11, existsSync as existsSync18 } from "fs";
+import { readFileSync as readFileSync12, existsSync as existsSync18 } from "fs";
 import { join as join21 } from "path";
 function detectTestFramework(projectRoot2) {
   const pkgPath = join21(projectRoot2, "package.json");
@@ -3762,7 +3801,7 @@ function detectTestFramework(projectRoot2) {
     return "vitest";
   }
   try {
-    const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync12(pkgPath, "utf-8"));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     if ("vitest" in deps) return "vitest";
     if ("jest" in deps || "@jest/core" in deps) return "jest";
@@ -3778,7 +3817,7 @@ var init_framework_detector = __esm({
 });
 
 // src/core/test-scaffolder/index.ts
-import { readFileSync as readFileSync12, writeFileSync as writeFileSync12, existsSync as existsSync19, mkdirSync as mkdirSync11 } from "fs";
+import { readFileSync as readFileSync13, writeFileSync as writeFileSync12, existsSync as existsSync19, mkdirSync as mkdirSync12 } from "fs";
 import { join as join22, relative as relative3, dirname as dirname3, basename as basename8 } from "path";
 function generateTestScaffolding(projectRoot2, features, config) {
   const framework = detectTestFramework(projectRoot2);
@@ -3801,7 +3840,7 @@ function generateTestScaffolding(projectRoot2, features, config) {
       const content = generateTestFileContent(feature.featureName, scenarios, framework);
       const dir = dirname3(absTestPath);
       if (!existsSync19(dir)) {
-        mkdirSync11(dir, { recursive: true });
+        mkdirSync12(dir, { recursive: true });
       }
       writeFileSync12(absTestPath, content, "utf-8");
       results.push({ testFile: testFilePath, framework, scenarios: scenarios.length });
@@ -3874,7 +3913,7 @@ function generateTestFileContent(featureName, scenarios, framework) {
   return lines.join("\n");
 }
 function appendMissingScenarios(testFilePath, scenarios, _framework) {
-  const content = readFileSync12(testFilePath, "utf-8");
+  const content = readFileSync13(testFilePath, "utf-8");
   const missing = [];
   for (const scenario of scenarios) {
     if (!content.includes(`Scenario: ${scenario.name}`)) {
@@ -3915,7 +3954,7 @@ var init_test_scaffolder = __esm({
 });
 
 // src/core/verifier/mapping-resolver.ts
-import { readFileSync as readFileSync14, existsSync as existsSync21, readdirSync as readdirSync2 } from "fs";
+import { readFileSync as readFileSync15, existsSync as existsSync21, readdirSync as readdirSync2 } from "fs";
 import { join as join24 } from "path";
 function resolveMappings(projectRoot2, features, testOutput) {
   const results = [];
@@ -3945,7 +3984,7 @@ function resolveFromMappingFile(projectRoot2, _feature, scenario) {
     const files = findMappingFiles(mappingsDir);
     for (const file of files) {
       try {
-        const content = readFileSync14(file, "utf-8");
+        const content = readFileSync15(file, "utf-8");
         const mapping = JSON.parse(content);
         if (mapping.scenarios && scenario.name in mapping.scenarios) {
           const entry = mapping.scenarios[scenario.name];
@@ -3975,7 +4014,7 @@ function resolveFromTag(projectRoot2, _feature, scenario) {
     const files = findTestFiles(testsDir);
     for (const file of files) {
       try {
-        const content = readFileSync14(file, "utf-8");
+        const content = readFileSync15(file, "utf-8");
         const tagRegex = /@speclore-scenario:\s*(.+)/g;
         let match;
         while ((match = tagRegex.exec(content)) !== null) {
@@ -4155,13 +4194,13 @@ var report_generator_exports = {};
 __export(report_generator_exports, {
   generateReport: () => generateReport
 });
-import { writeFileSync as writeFileSync13, mkdirSync as mkdirSync12, existsSync as existsSync22, readFileSync as readFileSync15 } from "fs";
+import { writeFileSync as writeFileSync13, mkdirSync as mkdirSync13, existsSync as existsSync22, readFileSync as readFileSync16 } from "fs";
 import { join as join25, dirname as dirname4 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function generateReport(report, projectRoot2, config) {
   const reportsDir = join25(projectRoot2, ".speclore", "reports");
   if (!existsSync22(reportsDir)) {
-    mkdirSync12(reportsDir, { recursive: true });
+    mkdirSync13(reportsDir, { recursive: true });
   }
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
   const writtenFiles = [];
@@ -4218,7 +4257,7 @@ function renderHtmlReport(report) {
   const templatePath = join25(dirname4(fileURLToPath2(import.meta.url)), "..", "..", "cli", "templates", "report.html");
   let template;
   try {
-    template = readFileSync15(templatePath, "utf-8");
+    template = readFileSync16(templatePath, "utf-8");
   } catch {
     template = getInlineTemplate();
   }
@@ -4297,7 +4336,7 @@ var init_verifier = __esm({
 });
 
 // src/core/analyzer/rdg-builder.ts
-import { readFileSync as readFileSync16, existsSync as existsSync23, readdirSync as readdirSync3 } from "fs";
+import { readFileSync as readFileSync17, existsSync as existsSync23, readdirSync as readdirSync3 } from "fs";
 import { join as join26 } from "path";
 var init_rdg_builder = __esm({
   "src/core/analyzer/rdg-builder.ts"() {
@@ -4327,6 +4366,9 @@ import { execFileSync as execFileSync3 } from "child_process";
 import { globSync as globSync5 } from "glob";
 function analyzeImpact(projectRoot2, context, config) {
   const changedFiles = getChangedFiles(projectRoot2);
+  return analyzeImpactWithChanges(changedFiles, context, config, projectRoot2);
+}
+function analyzeImpactWithChanges(changedFiles, context, config, projectRoot2) {
   const affectedModules = determineAffectedModules(changedFiles, context);
   const affectedFeatures = determineAffectedFeatures(affectedModules, projectRoot2, config.spec.outputDir);
   logger.info(
@@ -4402,11 +4444,11 @@ var init_analyzer = __esm({
 });
 
 // src/infra/file-lock.ts
-import { readFileSync as readFileSync19, writeFileSync as writeFileSync15, unlinkSync, existsSync as existsSync27, statSync as statSync3 } from "fs";
-import { join as join30 } from "path";
+import { readFileSync as readFileSync21, writeFileSync as writeFileSync16, unlinkSync, existsSync as existsSync28, statSync as statSync3 } from "fs";
+import { join as join31 } from "path";
 function acquireLock(specLoreDir) {
-  const lockPath = join30(specLoreDir, LOCK_FILENAME);
-  if (existsSync27(lockPath)) {
+  const lockPath = join31(specLoreDir, LOCK_FILENAME);
+  if (existsSync28(lockPath)) {
     const existing = readLockInfo(lockPath);
     if (existing && !isLockExpired(existing)) {
       logger.debug(`Lock already held by PID ${existing.pid}, not expired`);
@@ -4420,7 +4462,7 @@ function acquireLock(specLoreDir) {
     timestamp: Date.now()
   };
   try {
-    writeFileSync15(lockPath, JSON.stringify(lockInfo), { flag: "wx", encoding: "utf-8" });
+    writeFileSync16(lockPath, JSON.stringify(lockInfo), { flag: "wx", encoding: "utf-8" });
   } catch {
     logger.debug("Lock write failed \u2014 another process may have acquired it");
     return false;
@@ -4429,8 +4471,8 @@ function acquireLock(specLoreDir) {
   return true;
 }
 function releaseLock(specLoreDir) {
-  const lockPath = join30(specLoreDir, LOCK_FILENAME);
-  if (!existsSync27(lockPath)) {
+  const lockPath = join31(specLoreDir, LOCK_FILENAME);
+  if (!existsSync28(lockPath)) {
     return;
   }
   const existing = readLockInfo(lockPath);
@@ -4441,7 +4483,7 @@ function releaseLock(specLoreDir) {
 }
 function readLockInfo(lockPath) {
   try {
-    const content = readFileSync19(lockPath, "utf-8");
+    const content = readFileSync21(lockPath, "utf-8");
     const parsed = JSON.parse(content);
     if (typeof parsed.pid === "number" && typeof parsed.timestamp === "number") {
       return parsed;
@@ -4511,8 +4553,8 @@ var init_schemas = __esm({
 });
 
 // src/mcp/tools.ts
-import { join as join31 } from "path";
-import { readFileSync as readFileSync20, existsSync as existsSync28, mkdirSync as mkdirSync13, writeFileSync as writeFileSync16 } from "fs";
+import { join as join32 } from "path";
+import { readFileSync as readFileSync22, existsSync as existsSync29, mkdirSync as mkdirSync14, writeFileSync as writeFileSync17 } from "fs";
 import { globSync as globSync7 } from "glob";
 import { toJSONSchema } from "zod";
 async function executeSpecTool(args, projectRoot2) {
@@ -4523,7 +4565,7 @@ async function executeSpecTool(args, projectRoot2) {
   const config = loadConfig(projectRoot2);
   logger.info(`Reading requirement from: ${args.source.slice(0, 80)}...`);
   const req = await readRequirement(args.source);
-  const specLoreDir = join31(projectRoot2, ".speclore");
+  const specLoreDir = join32(projectRoot2, ".speclore");
   const context = loadContext(specLoreDir) ?? buildContext(projectRoot2, config);
   const feature = await generateFeature(req, context, config, projectRoot2);
   const createdFiles = [feature.path];
@@ -4555,7 +4597,7 @@ async function executeCodeTool(args, projectRoot2) {
   }
   ensureProjectReady(projectRoot2);
   const config = loadConfig(projectRoot2);
-  const specLoreDir = join31(projectRoot2, ".speclore");
+  const specLoreDir = join32(projectRoot2, ".speclore");
   const context = loadContext(specLoreDir) ?? buildContext(projectRoot2, config);
   const featureFiles = resolveFeatureFiles(args.features, projectRoot2, config);
   if (featureFiles.length === 0) {
@@ -4608,7 +4650,7 @@ async function executeCodeTool(args, projectRoot2) {
 async function executeVerifyTool(args, projectRoot2) {
   ensureProjectReady(projectRoot2);
   const config = loadConfig(projectRoot2);
-  const specLoreDir = join31(projectRoot2, ".speclore");
+  const specLoreDir = join32(projectRoot2, ".speclore");
   const context = loadContext(specLoreDir) ?? buildContext(projectRoot2, config);
   const featureFiles = resolveFeatureFiles(args.features, projectRoot2, config);
   const stateManager = new StateManager(projectRoot2);
@@ -4670,22 +4712,22 @@ async function executeVerifyTool(args, projectRoot2) {
   };
 }
 function ensureProjectReady(projectRoot2) {
-  const specLoreDir = join31(projectRoot2, ".speclore");
-  const configPath = join31(specLoreDir, "config.yaml");
+  const specLoreDir = join32(projectRoot2, ".speclore");
+  const configPath = join32(specLoreDir, "config.yaml");
   let configCreated = false;
-  if (!existsSync28(specLoreDir)) {
-    mkdirSync13(specLoreDir, { recursive: true });
+  if (!existsSync29(specLoreDir)) {
+    mkdirSync14(specLoreDir, { recursive: true });
   }
-  if (!existsSync28(configPath)) {
+  if (!existsSync29(configPath)) {
     const projectName = projectRoot2.split(/[/\\]/).pop() ?? "my-project";
-    writeFileSync16(configPath, generateDefaultConfigYaml(projectName), "utf-8");
+    writeFileSync17(configPath, generateDefaultConfigYaml(projectName), "utf-8");
     configCreated = true;
     logger.info(`Auto-created default config: ${configPath}`);
   }
   const stateManager = new StateManager(projectRoot2);
   stateManager.ensureInitialized();
   const config = loadConfig(projectRoot2);
-  const specsDir = join31(projectRoot2, config.spec.outputDir);
+  const specsDir = join32(projectRoot2, config.spec.outputDir);
   const migrated = stateManager.migrateFeatures(specsDir);
   if (migrated > 0) {
     logger.info(`Migrated ${migrated} existing .feature file(s) into state tracking.`);
@@ -4722,14 +4764,14 @@ function resolveNextStep(currentState, _summary) {
   }
 }
 function resolveFeatureFiles(patterns, projectRoot2, config) {
-  const specsDir = join31(projectRoot2, config.spec.outputDir);
+  const specsDir = join32(projectRoot2, config.spec.outputDir);
   const searchPatterns = patterns && patterns.length > 0 ? patterns : [`${specsDir}/**/*.feature`];
   const files = [];
   for (const pattern of searchPatterns) {
     const matches = globSync7(pattern, { cwd: projectRoot2, absolute: true });
     for (const filePath of matches) {
-      if (existsSync28(filePath)) {
-        const content = readFileSync20(filePath, "utf-8");
+      if (existsSync29(filePath)) {
+        const content = readFileSync22(filePath, "utf-8");
         files.push(parseFeatureFile(filePath, content));
       }
     }
@@ -4837,8 +4879,8 @@ var init_tools = __esm({
 });
 
 // src/mcp/status.ts
-import { readFileSync as readFileSync21, existsSync as existsSync29, mkdirSync as mkdirSync14, writeFileSync as writeFileSync17 } from "fs";
-import { join as join32 } from "path";
+import { readFileSync as readFileSync23, existsSync as existsSync30, mkdirSync as mkdirSync15, writeFileSync as writeFileSync18 } from "fs";
+import { join as join33 } from "path";
 import { globSync as globSync8 } from "glob";
 function executeStatusTool(args, projectRoot2) {
   const { configCreated } = ensureProjectReadyForStatus(projectRoot2);
@@ -4854,9 +4896,9 @@ function executeStatusTool(args, projectRoot2) {
       continue;
     }
     let scenarioCount = 0;
-    if (existsSync29(path)) {
+    if (existsSync30(path)) {
       try {
-        const content = readFileSync21(path, "utf-8");
+        const content = readFileSync23(path, "utf-8");
         const matches = content.match(/Scenario(?: Outline)?:/g);
         scenarioCount = matches?.length ?? 0;
       } catch {
@@ -4871,7 +4913,7 @@ function executeStatusTool(args, projectRoot2) {
       lastVerify: entry.lastVerify ? { passed: entry.lastVerify.passed, failed: entry.lastVerify.failed, timestamp: entry.lastVerify.timestamp } : void 0
     });
   }
-  const specsDir = join32(projectRoot2, config.spec.outputDir);
+  const specsDir = join33(projectRoot2, config.spec.outputDir);
   const allFeatureFiles = globSync8(`${specsDir}/**/*.feature`, { cwd: projectRoot2, absolute: true });
   const trackedPaths = new Set(featureEntries.map((f) => f.path));
   for (const filePath of allFeatureFiles) {
@@ -4879,7 +4921,7 @@ function executeStatusTool(args, projectRoot2) {
     if (args.feature && !filePath.includes(args.feature)) continue;
     let scenarioCount = 0;
     try {
-      const content = readFileSync21(filePath, "utf-8");
+      const content = readFileSync23(filePath, "utf-8");
       const matches = content.match(/Scenario(?: Outline)?:/g);
       scenarioCount = matches?.length ?? 0;
     } catch {
@@ -4936,22 +4978,22 @@ function buildRecommendedActions(features, summary, testCommand) {
   return actions;
 }
 function ensureProjectReadyForStatus(projectRoot2) {
-  const specLoreDir = join32(projectRoot2, ".speclore");
-  const configPath = join32(specLoreDir, "config.yaml");
+  const specLoreDir = join33(projectRoot2, ".speclore");
+  const configPath = join33(specLoreDir, "config.yaml");
   let configCreated = false;
-  if (!existsSync29(specLoreDir)) {
-    mkdirSync14(specLoreDir, { recursive: true });
+  if (!existsSync30(specLoreDir)) {
+    mkdirSync15(specLoreDir, { recursive: true });
   }
-  if (!existsSync29(configPath)) {
+  if (!existsSync30(configPath)) {
     const projectName = projectRoot2.split(/[/\\]/).pop() ?? "my-project";
-    writeFileSync17(configPath, generateDefaultConfigYaml(projectName), "utf-8");
+    writeFileSync18(configPath, generateDefaultConfigYaml(projectName), "utf-8");
     configCreated = true;
     logger.info(`Auto-created default config: ${configPath}`);
   }
   const stateManager = new StateManager(projectRoot2);
   stateManager.ensureInitialized();
   const config = loadConfig(projectRoot2);
-  const specsDir = join32(projectRoot2, config.spec.outputDir);
+  const specsDir = join33(projectRoot2, config.spec.outputDir);
   const migrated = stateManager.migrateFeatures(specsDir);
   if (migrated > 0) {
     logger.info(`Migrated ${migrated} existing .feature file(s) into state tracking.`);
@@ -4975,7 +5017,7 @@ __export(server_exports, {
 });
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { mkdirSync as mkdirSync15 } from "fs";
+import { mkdirSync as mkdirSync16 } from "fs";
 function getProjectRoot() {
   return projectRoot;
 }
@@ -4983,7 +5025,7 @@ async function startMcpServer() {
   projectRoot = process.env.SPECLORE_PROJECT_ROOT ?? process.cwd();
   const specLoreDir = `${projectRoot}/.speclore`;
   try {
-    mkdirSync15(specLoreDir, { recursive: true });
+    mkdirSync16(specLoreDir, { recursive: true });
     const locked = acquireLock(specLoreDir);
     if (!locked) {
       logger.warn("Could not acquire lock \u2014 another SpecLore instance may be running.");
@@ -5096,11 +5138,11 @@ import { Command } from "commander";
 init_logger();
 init_config2();
 init_detector();
-import { existsSync as existsSync5, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
 import { join as join7 } from "path";
 
 // src/setup/config-writer.ts
-import { writeFileSync as writeFileSync2, existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import { writeFileSync as writeFileSync2, existsSync as existsSync4, readFileSync as readFileSync4, mkdirSync as mkdirSync2 } from "fs";
 import { join as join5 } from "path";
 
 // src/infra/install-detector.ts
@@ -5151,13 +5193,42 @@ function detectCloneInstall(projectRoot2) {
 
 // src/setup/config-writer.ts
 init_logger();
-function writeMcpConfig(projectRoot2, _globalMode) {
+function writeMcpConfig(projectRoot2, tools, _globalMode) {
+  const installInfo = detectInstallMethod(projectRoot2);
+  const serverCommand = getServerCommand(installInfo);
+  const detectedToolNames = tools.map((t) => t.tool);
+  if (detectedToolNames.includes("cursor")) {
+    writeCursorMcp(projectRoot2, serverCommand);
+  }
+  if (detectedToolNames.includes("claude")) {
+    writeClaudeMcp(projectRoot2, serverCommand);
+  }
+  if (detectedToolNames.includes("qoder")) {
+    writeQoderMcp(projectRoot2, serverCommand);
+  }
+  if (detectedToolNames.length > 0) {
+    logger.info(`MCP configuration written for: ${detectedToolNames.join(", ")}`);
+  }
+}
+function writeMcpForClient(projectRoot2, client) {
   const installInfo = detectInstallMethod(projectRoot2);
   const serverCommand = getServerCommand(installInfo);
-  writeCursorMcp(projectRoot2, serverCommand);
-  writeClaudeMcp(projectRoot2, serverCommand);
-  writeQoderMcp(projectRoot2, serverCommand);
-  logger.info("MCP configuration written for all detected AI clients.");
+  switch (client) {
+    case "cursor":
+      mkdirSync2(join5(projectRoot2, ".cursor"), { recursive: true });
+      writeCursorMcp(projectRoot2, serverCommand);
+      break;
+    case "claude":
+      if (!existsSync4(join5(projectRoot2, ".claude"))) {
+        mkdirSync2(join5(projectRoot2, ".claude"), { recursive: true });
+      }
+      writeClaudeMcp(projectRoot2, serverCommand);
+      break;
+    case "qoder":
+      mkdirSync2(join5(projectRoot2, ".qoder"), { recursive: true });
+      writeQoderMcp(projectRoot2, serverCommand);
+      break;
+  }
 }
 function getServerCommand(installInfo) {
   if (installInfo.mode === "npm") {
@@ -5181,6 +5252,9 @@ function writeCursorMcp(projectRoot2, serverCmd) {
   logger.info(`  Cursor: ${mcpPath}`);
 }
 function writeClaudeMcp(projectRoot2, serverCmd) {
+  const hasClaudeDir = existsSync4(join5(projectRoot2, ".claude"));
+  const hasClaudeMd = existsSync4(join5(projectRoot2, "CLAUDE.md"));
+  if (!hasClaudeDir && !hasClaudeMd) return;
   const mcpPath = join5(projectRoot2, ".mcp.json");
   const existing = readExistingJson(mcpPath);
   if (!existing.mcpServers) existing.mcpServers = {};
@@ -5219,7 +5293,7 @@ function readExistingJson(filePath) {
 
 // src/setup/rule-writer.ts
 init_logger();
-import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync2 } from "fs";
+import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
 import { join as join6 } from "path";
 function writeRuleFiles(projectRoot2, tools) {
   for (const tool of tools) {
@@ -5238,7 +5312,7 @@ function writeRuleFiles(projectRoot2, tools) {
 }
 function writeCursorRule(projectRoot2) {
   const rulesDir = join6(projectRoot2, ".cursor", "rules");
-  mkdirSync2(rulesDir, { recursive: true });
+  mkdirSync3(rulesDir, { recursive: true });
   const content = `---
 description: SpecLore \u2014 AI coding constraints (setup placeholder)
 globs:
@@ -5260,7 +5334,7 @@ SpecLore is configured for this project. When the \`speclore.spec\` MCP tool is
 }
 function writeClaudeRule(projectRoot2) {
   const rulesDir = join6(projectRoot2, ".claude", "rules");
-  mkdirSync2(rulesDir, { recursive: true });
+  mkdirSync3(rulesDir, { recursive: true });
   const content = `# SpecLore
 
 SpecLore is configured for this project. When the \`speclore.spec\` MCP tool is available:
@@ -5276,7 +5350,7 @@ SpecLore is configured for this project. When the \`speclore.spec\` MCP tool is
 }
 function writeQoderRule(projectRoot2) {
   const rulesDir = join6(projectRoot2, ".qoder", "rules");
-  mkdirSync2(rulesDir, { recursive: true });
+  mkdirSync3(rulesDir, { recursive: true });
   const content = `# SpecLore
 
 SpecLore is configured for this project. When the \`speclore.spec\` MCP tool is available:
@@ -5300,13 +5374,20 @@ function registerSetupCommand(program) {
     logger.info("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
     const tools = detectAITools(projectRoot2);
     if (tools.length === 0) {
-      logger.warn("No supported AI tools detected. Continuing anyway...");
+      logger.warn("No supported AI tools detected.");
+      logger.info("");
+      logger.info("  To enable MCP integration, open your AI client in this project first,");
+      logger.info("  then re-run setup. Or use manual configuration:");
+      logger.info("    speclore mcp add cursor   \u2014 configure for Cursor");
+      logger.info("    speclore mcp add claude   \u2014 configure for Claude Code");
+      logger.info("    speclore mcp add qoder    \u2014 configure for Qoder");
+      logger.info("");
     } else {
       logger.info(`Detected AI tools: ${tools.map((t) => t.tool).join(", ")}`);
     }
     const specLoreDir = opts.global ? join7(process.env.HOME ?? process.env.USERPROFILE ?? "~", ".speclore") : join7(projectRoot2, ".speclore");
     if (!existsSync5(specLoreDir)) {
-      mkdirSync3(specLoreDir, { recursive: true });
+      mkdirSync4(specLoreDir, { recursive: true });
     }
     const configPath = join7(specLoreDir, "config.yaml");
     if (!existsSync5(configPath)) {
@@ -5314,12 +5395,23 @@ function registerSetupCommand(program) {
       writeFileSync4(configPath, generateDefaultConfigYaml(projectName), "utf-8");
       logger.info(`Created config: ${configPath}`);
     }
-    writeMcpConfig(projectRoot2, opts.global ?? false);
+    writeMcpConfig(projectRoot2, tools, opts.global ?? false);
     writeRuleFiles(projectRoot2, tools);
     logger.info("");
-    logger.info("Setup complete! You can now:");
-    logger.info("  \u2022 Run `speclore init` to initialize project context");
-    logger.info("  \u2022 Or just start talking to your AI client about requirements");
+    logger.info("Setup complete! Next steps:");
+    logger.info("");
+    logger.info("  Option A \u2014 CLI workflow (terminal users):");
+    logger.info('    speclore spec "your requirement"   \u2192 generate .feature');
+    logger.info("    speclore code                      \u2192 generate constraints + tests");
+    logger.info("    speclore verify                    \u2192 run acceptance");
+    logger.info("");
+    logger.info("  Option B \u2014 AI client workflow (recommended):");
+    logger.info("    Open Cursor / Qoder / Claude Code and start chatting.");
+    logger.info("    MCP is already configured \u2014 AI handles the full pipeline.");
+    logger.info("");
+    logger.info("  Optional \u2014 Pre-scan project context:");
+    logger.info("    speclore init   \u2192 scan modules/entities/APIs for better AI context");
+    logger.info("    (Not required \u2014 context is auto-built on first spec/code call)");
   });
 }
 
@@ -5329,7 +5421,7 @@ init_logger();
 init_context_engine();
 import { join as join11 } from "path";
 function registerInitCommand(program) {
-  program.command("init").description("Initialize project: scan structure, detect modules, generate context.json").option("-v, --verbose", "Enable debug logging").action((opts) => {
+  program.command("init").description("Scan project structure and generate context.json (optional \u2014 auto-runs on first spec/code call)").option("-v, --verbose", "Enable debug logging").action((opts) => {
     if (opts.verbose) logger.setLevel("debug");
     const projectRoot2 = process.cwd();
     logger.info("SpecLore Init");
@@ -5393,7 +5485,7 @@ init_test_scaffolder();
 init_context_engine();
 init_state_manager();
 import { join as join23 } from "path";
-import { readFileSync as readFileSync13, existsSync as existsSync20 } from "fs";
+import { readFileSync as readFileSync14, existsSync as existsSync20 } from "fs";
 import { globSync as globSync4 } from "glob";
 function registerCodeCommand(program) {
   program.command("code").description("Generate AI coding constraint files from .feature specs").argument("[features...]", "Feature file paths or glob patterns (all if omitted)").option("-v, --verbose", "Enable debug logging").action(async (features, opts) => {
@@ -5449,7 +5541,7 @@ function resolveFeatures(patterns, projectRoot2, config) {
     const matches = globSync4(pattern, { cwd: projectRoot2, absolute: true });
     for (const filePath of matches) {
       if (existsSync20(filePath)) {
-        const content = readFileSync13(filePath, "utf-8");
+        const content = readFileSync14(filePath, "utf-8");
         const featureMatch = content.match(/Feature:\s*(.+)/);
         files.push({
           path: filePath,
@@ -5473,7 +5565,7 @@ init_context_engine();
 init_analyzer();
 init_state_manager();
 import { join as join27 } from "path";
-import { readFileSync as readFileSync17, existsSync as existsSync24 } from "fs";
+import { readFileSync as readFileSync18, existsSync as existsSync24 } from "fs";
 import { globSync as globSync6 } from "glob";
 function registerVerifyCommand(program) {
   program.command("verify").description("Run tests and map results to .feature scenarios").argument("[features...]", "Feature file paths or glob patterns (all if omitted)").option("--impact", "Enable change impact analysis").option("--watch", "Watch for .feature file changes and re-run").option("--timeout <minutes>", "Watch timeout in minutes (default: 30)", "30").option("-v, --verbose", "Enable debug logging").action(async (features, opts) => {
@@ -5560,7 +5652,7 @@ function resolveFeatures2(patterns, projectRoot2, config) {
     const matches = globSync6(pattern, { cwd: projectRoot2, absolute: true });
     for (const filePath of matches) {
       if (existsSync24(filePath)) {
-        const content = readFileSync17(filePath, "utf-8");
+        const content = readFileSync18(filePath, "utf-8");
         const featureMatch = content.match(/Feature:\s*(.+)/);
         files.push({
           path: filePath,
@@ -5581,7 +5673,7 @@ init_logger();
 
 // src/setup/cleanup.ts
 init_logger();
-import { rmSync as rmSync4, existsSync as existsSync25, readFileSync as readFileSync18, writeFileSync as writeFileSync14 } from "fs";
+import { rmSync as rmSync4, existsSync as existsSync25, readFileSync as readFileSync19, writeFileSync as writeFileSync14 } from "fs";
 import { join as join28 } from "path";
 function runTeardown(projectRoot2, globalMode) {
   if (globalMode) {
@@ -5610,7 +5702,7 @@ function runTeardown(projectRoot2, globalMode) {
 function removeMcpEntry(mcpPath, serverName) {
   if (!existsSync25(mcpPath)) return;
   try {
-    const config = JSON.parse(readFileSync18(mcpPath, "utf-8"));
+    const config = JSON.parse(readFileSync19(mcpPath, "utf-8"));
     if (config.mcpServers?.[serverName]) {
       delete config.mcpServers[serverName];
       writeFileSync14(mcpPath, JSON.stringify(config, null, 2), "utf-8");
@@ -5706,6 +5798,114 @@ function registerMigrateCommand(program) {
   });
 }
 
+// src/cli/commands/mcp-config.ts
+init_logger();
+import { existsSync as existsSync27, readFileSync as readFileSync20, writeFileSync as writeFileSync15, rmSync as rmSync5 } from "fs";
+import { join as join30 } from "path";
+var VALID_CLIENTS = ["cursor", "claude", "qoder"];
+function getMcpPath(projectRoot2, client) {
+  switch (client) {
+    case "cursor":
+      return join30(projectRoot2, ".cursor", "mcp.json");
+    case "claude":
+      return join30(projectRoot2, ".mcp.json");
+    case "qoder":
+      return join30(projectRoot2, ".qoder", "mcp.json");
+  }
+}
+function clientLabel(client) {
+  switch (client) {
+    case "cursor":
+      return "Cursor";
+    case "claude":
+      return "Claude Code";
+    case "qoder":
+      return "Qoder";
+  }
+}
+function registerMcpConfigCommands(program) {
+  const mcpCmd = program.commands.find((c) => c.name() === "mcp");
+  if (!mcpCmd) return;
+  mcpCmd.command("add <client>").description("Manually write SpecLore MCP config for a specific AI client (cursor | claude | qoder)").action((clientArg) => {
+    const projectRoot2 = process.cwd();
+    const client = validateClient(clientArg);
+    if (!client) return;
+    logger.info(`Configuring MCP for ${clientLabel(client)}...`);
+    writeMcpForClient(projectRoot2, client);
+    logger.info(`\u2713 ${clientLabel(client)} MCP configured at ${getMcpPath(projectRoot2, client)}`);
+  });
+  mcpCmd.command("remove <client>").description("Remove SpecLore MCP config from a specific AI client (cursor | claude | qoder)").action((clientArg) => {
+    const projectRoot2 = process.cwd();
+    const client = validateClient(clientArg);
+    if (!client) return;
+    const mcpPath = getMcpPath(projectRoot2, client);
+    if (!existsSync27(mcpPath)) {
+      logger.info(`${clientLabel(client)}: no MCP config file found at ${mcpPath}`);
+      return;
+    }
+    const removed = removeMcpServerEntry(mcpPath, "speclore");
+    if (removed) {
+      logger.info(`\u2713 Removed speclore from ${clientLabel(client)}: ${mcpPath}`);
+    } else {
+      logger.info(`${clientLabel(client)}: speclore entry not found in ${mcpPath}`);
+    }
+  });
+  mcpCmd.command("list").description("Show current SpecLore MCP configuration status for all clients").action(() => {
+    const projectRoot2 = process.cwd();
+    logger.info("SpecLore MCP Configuration Status");
+    logger.info("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
+    let anyFound = false;
+    for (const client of VALID_CLIENTS) {
+      const mcpPath = getMcpPath(projectRoot2, client);
+      if (!existsSync27(mcpPath)) {
+        logger.info(`  \u25CB ${clientLabel(client)}: no config file (${mcpPath})`);
+        continue;
+      }
+      try {
+        const config = JSON.parse(readFileSync20(mcpPath, "utf-8"));
+        if (config.mcpServers?.["speclore"]) {
+          logger.info(`  \u2713 ${clientLabel(client)}: configured \u2192 ${mcpPath}`);
+          anyFound = true;
+        } else {
+          logger.info(`  \u25CB ${clientLabel(client)}: config file exists but speclore not registered \u2192 ${mcpPath}`);
+        }
+      } catch {
+        logger.info(`  \u2717 ${clientLabel(client)}: failed to parse ${mcpPath}`);
+      }
+    }
+    if (!anyFound) {
+      logger.info("");
+      logger.info("  No SpecLore MCP configurations found.");
+      logger.info("  Run `speclore setup` or `speclore mcp add <client>` to configure.");
+    }
+  });
+}
+function validateClient(arg) {
+  const normalised = arg.toLowerCase().trim();
+  if (!VALID_CLIENTS.includes(normalised)) {
+    logger.error(`Unknown client "${arg}". Supported: ${VALID_CLIENTS.join(", ")}`);
+    return null;
+  }
+  return normalised;
+}
+function removeMcpServerEntry(mcpPath, serverName) {
+  if (!existsSync27(mcpPath)) return false;
+  try {
+    const config = JSON.parse(readFileSync20(mcpPath, "utf-8"));
+    if (!config.mcpServers?.[serverName]) return false;
+    delete config.mcpServers[serverName];
+    const remainingServers = Object.keys(config.mcpServers ?? {});
+    if (remainingServers.length === 0) {
+      rmSync5(mcpPath);
+    } else {
+      writeFileSync15(mcpPath, JSON.stringify(config, null, 2), "utf-8");
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/cli/index.ts
 init_version();
 function createProgram() {
@@ -5725,6 +5925,7 @@ function createProgram() {
     const { startMcpServer: startMcpServer2 } = await Promise.resolve().then(() => (init_server(), server_exports));
     await startMcpServer2();
   });
+  registerMcpConfigCommands(program);
   program.argument("[text...]", "Quick requirement text \u2192 .feature").action(async (text) => {
     if (text.length > 0) {
       const { loadConfig: loadConfig2 } = await Promise.resolve().then(() => (init_config2(), config_exports));