@kaddo/mcp 3.62.0 → 3.63.0

package/dist/index.js

@@ -168,7 +168,8 @@ var DERIVED_WRITE_FILES = /* @__PURE__ */ new Set([
   ".kaddo/graph.json",
   ".kaddo/graph.mmd",
   ".kaddo/graph-hints.md",
-  ".kaddo/graph-hints.json"
+  ".kaddo/graph-hints.json",
+  ".kaddo/modules.yml"
 ]);
 var DERIVED_EXPORTS_RE = /^\.kaddo\/exports\/[^/]+\.capsule\.(md|json)$/;
 var DERIVED_REPORTS_RE = /^\.kaddo\/reports\/[^/]+\.(md|json)$/;
@@ -447,10 +448,14 @@ var configSchema = z.object({
   team: z.object({
     size: teamSizeSchema.default(DEFAULTS.teamSize)
   }).passthrough().default({}),
+  system: z.object({
+    name: z.string().optional()
+  }).passthrough().optional(),
   multirepo: z.object({
     role: multirepoRoleSchema,
     modules_file: z.string().optional(),
-    parent_system: z.string().optional()
+    parent_system: z.string().optional(),
+    workspace_roots: z.array(z.string()).optional()
   }).passthrough().optional(),
   module: z.object({
     id: z.string().optional()
@@ -489,6 +494,9 @@ function projectRole(config) {
 function isModule(config) {
   return projectRole(config) === "module";
 }
+function isCore(config) {
+  return projectRole(config) === "core";
+}
 
 // ../cli/src/services/artifact-reader.ts
 import matter3 from "gray-matter";
@@ -790,7 +798,7 @@ function assessPhase(input) {
 
 // ../cli/src/core/capsule.ts
 import matter4 from "gray-matter";
-import { parse as parseYaml6, stringify as stringifyYaml2 } from "yaml";
+import { parse as parseYaml7, stringify as stringifyYaml3 } from "yaml";
 
 // ../cli/src/services/owners.ts
 import { parse as parseYaml3 } from "yaml";
@@ -847,7 +855,7 @@ function loadMappedModules(dir) {
     modules.push({
       id,
       name: typeof m2.name === "string" ? m2.name : void 0,
-      repoPath: typeof m2.repoPath === "string" ? m2.repoPath : "",
+      repoPath: typeof m2.repoPath === "string" ? m2.repoPath : typeof m2.path === "string" ? m2.path : "",
       type: typeof m2.type === "string" ? m2.type : void 0,
       mainTechnology: typeof m2.mainTechnology === "string" ? m2.mainTechnology : void 0,
       owner: typeof m2.owner === "string" ? m2.owner : void 0,
@@ -896,13 +904,15 @@ function detectModuleStatus(coreDir, repoPath) {
     status: "configured",
     configured: true,
     role: "module",
-    moduleContext: exists(join(moduleDir, "knowledge", "module", "module-context.md")),
+    moduleContext: exists(join(moduleDir, "knowledge", "tech", "module", "module-context.md")) || exists(join(moduleDir, "knowledge", "module", "module-context.md")),
     currentState: exists(join(moduleDir, "knowledge", "tech", "current-state.md")),
     codebase: exists(join(moduleDir, "knowledge", "tech", "codebase.md"))
   };
 }
 function readModuleContext(coreDir, repoPath) {
-  const p = join(coreDir, repoPath, "knowledge", "module", "module-context.md");
+  const newPath = join(coreDir, repoPath, "knowledge", "tech", "module", "module-context.md");
+  const legacyPath = join(coreDir, repoPath, "knowledge", "module", "module-context.md");
+  const p = exists(newPath) ? newPath : legacyPath;
   if (!exists(p)) return null;
   try {
     return readFile(p);
@@ -1042,7 +1052,7 @@ var Q2 = o("\u25B2", "!");
 var ee = o("\u25A0", "x");
 
 // ../cli/src/commands/modules-map.ts
-import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml6, stringify as stringifyYaml2 } from "yaml";
 
 // ../cli/src/templates/registry.ts
 var QUALITY = "## Quality checklist";
@@ -2153,6 +2163,9 @@ ${QUALITY}
 - [ ] The next step is clear.
 `;
 
+// ../cli/src/commands/modules-discover.ts
+import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
+
 // ../cli/src/core/capsule.ts
 var KNOWLEDGE2 = "knowledge";
 function today() {
@@ -2252,7 +2265,7 @@ function loadExternalRegistry(dir) {
   const p = join(dir, EXTERNAL_PATH);
   if (!exists(p)) return [];
   try {
-    const parsed = parseYaml6(readFile(p));
+    const parsed = parseYaml7(readFile(p));
     return Array.isArray(parsed?.external) ? parsed.external : [];
   } catch {
     return [];
@@ -3693,6 +3706,9 @@ function buildAdapterStatuses(dir) {
   });
 }
 
+// ../cli/src/core/next-step.ts
+import { parse as parseYaml8 } from "yaml";
+
 // ../cli/src/agents/groups.ts
 var AGENT_GROUPS = {
   business: ["business-agent.md"],
@@ -3845,6 +3861,14 @@ function buildDeliveryState(dir) {
     adapters_installed: adapters.length
   };
 }
+function hasRegisteredModules(modulesYmlPath) {
+  try {
+    const parsed = parseYaml8(readFile(modulesYmlPath));
+    return Array.isArray(parsed?.modules) && parsed.modules.length > 0;
+  } catch {
+    return false;
+  }
+}
 function safeRead(p) {
   try {
     return readFile(p);
@@ -3895,11 +3919,12 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   const state = config.project.state;
   const q3 = (rel) => analyzeKnowledgeArtifact(dir, rel);
   const moduleRepo = isModule(config);
-  const MC = "knowledge/module/module-context.md";
+  const coreRepo = isCore(config);
+  const MC = exists(join(dir, "knowledge/tech/module/module-context.md")) ? "knowledge/tech/module/module-context.md" : "knowledge/module/module-context.md";
   if (moduleRepo) {
     const qMC = q3(MC);
     if (qMC === "missing") {
-      return { id: "init-module-context", phase: "Setup", label: "Create `knowledge/module/module-context.md` for this module.", command: "kaddo init", reason: "Module context file is missing. Re-run `kaddo init` as a multirepo module." };
+      return { id: "init-module-context", phase: "Setup", label: "Create `knowledge/tech/module/module-context.md` for this module.", command: "kaddo init", reason: "Module context file is missing. Re-run `kaddo init` as a multirepo module." };
     }
     if ((state === "pre-ai" || state === "legacy") && !exists(join(dir, ".kaddo", "scan.json"))) {
       return { id: "scan", phase: "Discovery", label: "Run `kaddo scan` to capture deterministic signals from the existing code.", command: "kaddo scan", reason: "No scan baseline exists for this existing project yet." };
@@ -3948,9 +3973,15 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     return { id: "module-ready", phase: "Active Delivery", label: "Module context is complete. Create and manage Work Items from the core repository.", reason: "This module's knowledge is ready. Work Items are created and tracked in the core." };
   }
   const qBusiness = q3(B2), qProduct = q3(P2), qCap = q3(CAP), qCurrentState = q3(CS), qCodebase = q3(CB);
-  if (qBusiness === "missing" || qProduct === "missing") {
+  if (!coreRepo && (qBusiness === "missing" || qProduct === "missing")) {
     return { id: "bootstrap", phase: "Setup", label: "Run `kaddo bootstrap` to create the project knowledge baseline.", command: "kaddo bootstrap", reason: "The knowledge baseline is incomplete." };
   }
+  if (coreRepo) {
+    const modulesYmlPath = join(dir, ".kaddo", "modules.yml");
+    if (!exists(modulesYmlPath) || !hasRegisteredModules(modulesYmlPath)) {
+      return { id: "modules-discover", phase: "Setup", label: "Run `kaddo modules discover` to find sibling module repositories.", command: "kaddo modules discover", reason: "No modules are mapped for this core repository." };
+    }
+  }
   const ctx = buildCodexAdapterContext(dir);
   if (!ctx.hasAgents) {
     return { id: "add-agents", phase: "Setup", label: "Run `kaddo add agents` to install the Kaddo agent prompt packs.", command: "kaddo add agents", reason: "No Kaddo agents are installed yet." };
@@ -7714,7 +7745,8 @@ function mapNextStepId(id) {
     "refine-module-context": "refine-work-item",
     "init-module-context": "enable-kaddo",
     "module-ready": "prepare-implementation",
-    "validate-work-item-modules": "prepare-implementation"
+    "validate-work-item-modules": "prepare-implementation",
+    "modules-discover": "enable-kaddo"
   };
   return MAP[id] ?? id;
 }
@@ -8981,7 +9013,7 @@ function serializeImpactJson(r2) {
 }
 
 // ../cli/src/core/savings.ts
-import { parse as parseYaml7 } from "yaml";
+import { parse as parseYaml9 } from "yaml";
 var DEFAULT_ASSUMPTIONS = {
   currency: "USD",
   hourly_cost: 40,
@@ -8999,7 +9031,7 @@ function loadAssumptions(dir) {
   const p = join(dir, SAVINGS_PATH);
   if (!exists(p)) return { assumptions: { ...DEFAULT_ASSUMPTIONS }, source: "default" };
   try {
-    const raw = parseYaml7(readFile(p));
+    const raw = parseYaml9(readFile(p));
     const a2 = raw?.assumptions ?? {};
     const t = raw?.team ?? {};
     const num = (v, d3) => typeof v === "number" && Number.isFinite(v) ? v : d3;
@@ -9837,7 +9869,7 @@ function getWorkItem(root, id) {
   const content = readText(root, item.path);
   return ok({ ...item, content: content ?? "" });
 }
-function markWorkItemReady(root, id, confirm) {
+function markWorkItemReady(root, id, confirm2) {
   const item = listWorkItems(root).find((w3) => w3.id === id);
   if (!item) return fail(`Work Item "${id}" not found.`);
   if (item.status === "ready") {
@@ -9847,7 +9879,7 @@ function markWorkItemReady(root, id, confirm) {
     return fail(`Work Item ${item.id} is in state "${item.status}", not "draft". Only draft Work Items can be marked as ready.`);
   }
   const warnings = item.readiness?.warnings ?? [];
-  if (!confirm) {
+  if (!confirm2) {
     return ok({
       status: "needs_confirmation",
       workItem: {
@@ -9937,9 +9969,12 @@ function listGraphHints(root, filter = {}) {
 import fs3 from "fs";
 import path3 from "path";
 import matter11 from "gray-matter";
-import { parse as parseYaml8 } from "yaml";
+import { parse as parseYaml10, stringify as stringifyYaml4 } from "yaml";
 var ok2 = (data) => ({ ok: true, data });
 var fail2 = (message) => ({ ok: false, message });
+function moduleRepoPath(m2) {
+  return m2.path ?? m2.repoPath ?? "";
+}
 function loadModulesDescriptor(root) {
   return readYaml(root, ".kaddo/modules.yml") ?? { modules: [] };
 }
@@ -9949,7 +9984,7 @@ function loadConfig2(root) {
 function projectRole2(config) {
   return config.project?.role ?? config.multirepo?.role;
 }
-function isCore(config) {
+function isCore2(config) {
   return projectRole2(config) === "core";
 }
 function readModuleFile(root, repoPath, relFile) {
@@ -9970,7 +10005,7 @@ function detectModuleStatus2(root, repoPath) {
   }
   let parsed = null;
   try {
-    parsed = parseYaml8(fs3.readFileSync(configPath, "utf-8"));
+    parsed = parseYaml10(fs3.readFileSync(configPath, "utf-8"));
   } catch {
   }
   const role = parsed?.project?.role ?? parsed?.multirepo?.role;
@@ -9981,11 +10016,18 @@ function detectModuleStatus2(root, repoPath) {
     status: "configured",
     configured: true,
     role: "module",
-    moduleContext: fs3.existsSync(path3.join(moduleDir, "knowledge", "module", "module-context.md")),
+    moduleContext: fs3.existsSync(path3.join(moduleDir, "knowledge", "tech", "module", "module-context.md")) || fs3.existsSync(path3.join(moduleDir, "knowledge", "module", "module-context.md")),
     currentState: fs3.existsSync(path3.join(moduleDir, "knowledge", "tech", "current-state.md")),
     codebase: fs3.existsSync(path3.join(moduleDir, "knowledge", "tech", "codebase.md"))
   };
 }
+function resolveModuleContextPath(root, repoPath) {
+  const moduleDir = path3.resolve(root, repoPath);
+  if (fs3.existsSync(path3.join(moduleDir, "knowledge", "tech", "module", "module-context.md"))) {
+    return "knowledge/tech/module/module-context.md";
+  }
+  return "knowledge/module/module-context.md";
+}
 function isPlaceholder(content) {
   const body = content.replace(/^---[\s\S]*?---\n?/, "");
   return /^_[^_]+_$/m.test(body) && !body.split("\n").some((l2) => l2.trim().length > 0 && !l2.startsWith("#") && !l2.startsWith("_") && !l2.startsWith("-") && !l2.startsWith(">"));
@@ -10004,13 +10046,14 @@ function slugify2(s) {
 function modulesListTool(root, args) {
   const config = loadConfig2(root);
   if (!config) return fail2("No Kaddo config found. Run `kaddo init` first.");
-  if (!isCore(config)) return fail2("kaddo_modules_list can only be called from a core repository (project.role: core).");
+  if (!isCore2(config)) return fail2("kaddo_modules_list can only be called from a core repository (project.role: core).");
   const descriptor = loadModulesDescriptor(root);
   const modules = (descriptor.modules ?? []).map((m2) => {
-    const st = detectModuleStatus2(root, m2.repoPath);
+    const rp = moduleRepoPath(m2);
+    const st = detectModuleStatus2(root, rp);
     const entry = {
       id: m2.id,
-      repo: m2.repoPath,
+      repo: rp,
       status: st.status,
       kaddo: {
         configured: st.configured,
@@ -10034,7 +10077,8 @@ function getModuleContextTool(root, args) {
   const descriptor = loadModulesDescriptor(root);
   const mod = (descriptor.modules ?? []).find((m2) => m2.id === args.module);
   if (!mod) return fail2(`Module "${args.module}" not found in .kaddo/modules.yml.`);
-  const st = detectModuleStatus2(root, mod.repoPath);
+  const rp = moduleRepoPath(mod);
+  const st = detectModuleStatus2(root, rp);
   const warnings = [];
   if (st.status !== "configured") {
     if (st.warning) warnings.push(st.warning);
@@ -10045,26 +10089,27 @@ function getModuleContextTool(root, args) {
       recommendedNextStep: { label: "Initialize module repository with Kaddo.", command: "kaddo init" }
     });
   }
-  const mcContent = readModuleFile(root, mod.repoPath, "knowledge/module/module-context.md");
+  const mcRelPath = resolveModuleContextPath(root, rp);
+  const mcContent = readModuleFile(root, rp, mcRelPath);
   const context = {
-    moduleContextPath: `${mod.repoPath}/knowledge/module/module-context.md`,
+    moduleContextPath: `${rp}/${mcRelPath}`,
     moduleContext: mcContent ?? null
   };
   if (mcContent && isPlaceholder(mcContent)) {
     warnings.push("module-context.md still contains placeholder sections.");
   }
   if (args.includeTech) {
-    const cs = readModuleFile(root, mod.repoPath, "knowledge/tech/current-state.md");
-    const cb = readModuleFile(root, mod.repoPath, "knowledge/tech/codebase.md");
-    context.currentStatePath = `${mod.repoPath}/knowledge/tech/current-state.md`;
+    const cs = readModuleFile(root, rp, "knowledge/tech/current-state.md");
+    const cb = readModuleFile(root, rp, "knowledge/tech/codebase.md");
+    context.currentStatePath = `${rp}/knowledge/tech/current-state.md`;
     context.currentStateSummary = cs ? firstParagraph3(cs) : null;
-    context.codebasePath = `${mod.repoPath}/knowledge/tech/codebase.md`;
+    context.codebasePath = `${rp}/knowledge/tech/codebase.md`;
     context.codebaseSummary = cb ? firstParagraph3(cb) : null;
     if (!cs) warnings.push("current-state.md not found in module repository.");
     if (!cb) warnings.push("codebase.md not found in module repository.");
   }
   return ok2({
-    module: { id: mod.id, repo: mod.repoPath, status: "configured" },
+    module: { id: mod.id, repo: rp, status: "configured" },
     context,
     warnings: args.includeWarnings ? warnings : []
   });
@@ -10092,15 +10137,17 @@ function validateWorkItemModulesTool(root, args) {
       return { id: modId, status: "not_mapped", hasModuleContext: false, hasCurrentState: false, hasCodebase: false, hasOwnership: false };
     }
     const mod = (descriptor.modules ?? []).find((m2) => m2.id === modId);
-    const st = detectModuleStatus2(root, mod.repoPath);
+    const rp = moduleRepoPath(mod);
+    const st = detectModuleStatus2(root, rp);
     if (st.status !== "configured") {
       warnings.push(`Module "${modId}" is ${st.status}.`);
     }
-    const mcContent = st.moduleContext ? readModuleFile(root, mod.repoPath, "knowledge/module/module-context.md") : null;
+    const mcRelPath = resolveModuleContextPath(root, rp);
+    const mcContent = st.moduleContext ? readModuleFile(root, rp, mcRelPath) : null;
     if (mcContent && isPlaceholder(mcContent)) {
       warnings.push(`Module "${modId}" has placeholder module-context.`);
     }
-    const hasOwnership = codeEntries.some((c) => c.repo && (c.repo === mod.repoPath || c.repo.endsWith(`/${modId}`) || c.repo.includes(modId)));
+    const hasOwnership = codeEntries.some((c) => c.repo && (c.repo === rp || c.repo.endsWith(`/${modId}`) || c.repo.includes(modId)));
     return { id: modId, status: st.status, hasModuleContext: st.moduleContext, hasCurrentState: st.currentState, hasCodebase: st.codebase, hasOwnership };
   });
   for (const ce of codeEntries) {
@@ -10138,12 +10185,14 @@ function getWorkItemContextTool(root, args) {
       warnings.push(`Module "${modId}" not in modules.yml.`);
       return { id: modId, repo: null, moduleContext: null, currentStateSummary: null, codebaseSummary: null };
     }
-    const st = detectModuleStatus2(root, mod.repoPath);
+    const rp = moduleRepoPath(mod);
+    const st = detectModuleStatus2(root, rp);
     if (st.status !== "configured") warnings.push(`Module "${modId}" is ${st.status}.`);
-    const mc = args.includeModuleContexts !== false ? readModuleFile(root, mod.repoPath, "knowledge/module/module-context.md") : null;
-    const cs = readModuleFile(root, mod.repoPath, "knowledge/tech/current-state.md");
-    const cb = readModuleFile(root, mod.repoPath, "knowledge/tech/codebase.md");
-    return { id: modId, repo: mod.repoPath, moduleContext: mc, currentStateSummary: cs ? firstParagraph3(cs) : null, codebaseSummary: cb ? firstParagraph3(cb) : null };
+    const mcRelPath = resolveModuleContextPath(root, rp);
+    const mc = args.includeModuleContexts !== false ? readModuleFile(root, rp, mcRelPath) : null;
+    const cs = readModuleFile(root, rp, "knowledge/tech/current-state.md");
+    const cb = readModuleFile(root, rp, "knowledge/tech/codebase.md");
+    return { id: modId, repo: rp, moduleContext: mc, currentStateSummary: cs ? firstParagraph3(cs) : null, codebaseSummary: cb ? firstParagraph3(cb) : null };
   });
   const ownership = { crossRepo: codeEntries.length > 1, items: codeEntries.filter((c) => c.repo).map((c) => ({ repo: c.repo, paths: c.paths ?? [] })) };
   const result = {
@@ -10185,7 +10234,7 @@ function buildBranchStrategy(wi, affectedModules, codeEntries, descriptor) {
   const commitMessages = {};
   for (const modId of affectedModules) {
     const mod = (descriptor.modules ?? []).find((m2) => m2.id === modId);
-    const repo = mod?.repoPath ?? modId;
+    const repo = mod ? moduleRepoPath(mod) || modId : modId;
     moduleBranches[repo] = `feature/${wiLower}-${modId}-${slug4.slice(0, 20)}`;
     commitMessages[repo] = `fix(${wiLower}): update ${modId}`;
   }
@@ -10235,7 +10284,9 @@ function exportCapsuleTool(root, args) {
       const descriptor = loadModulesDescriptor(root);
       const mod = (descriptor.modules ?? []).find((m2) => m2.id === args.module);
       if (!mod) return fail2(`Module "${args.module}" not found in .kaddo/modules.yml.`);
-      const mc = readModuleFile(root, mod.repoPath, "knowledge/module/module-context.md");
+      const rp = moduleRepoPath(mod);
+      const mcRelPath = resolveModuleContextPath(root, rp);
+      const mc = readModuleFile(root, rp, mcRelPath);
       if (!mc) warnings.push("module-context.md not found for this module.");
       if (mc && isPlaceholder(mc)) warnings.push("module-context.md contains placeholder sections.");
       capsuleType = "module";
@@ -10256,7 +10307,7 @@ function exportCapsuleTool(root, args) {
         owners: mod.owner ? [mod.owner] : []
       };
     } else if (role === "module") {
-      const mc = readText(root, "knowledge/module/module-context.md");
+      const mc = readText(root, "knowledge/tech/module/module-context.md") ?? readText(root, "knowledge/module/module-context.md");
       if (!mc) warnings.push("module-context.md not found.");
       if (mc && isPlaceholder(mc)) warnings.push("module-context.md contains placeholder sections.");
       const modId = config.module?.id ?? args.module;
@@ -10283,7 +10334,9 @@ function exportCapsuleTool(root, args) {
     const descriptor = loadModulesDescriptor(root);
     const responsibilities = [];
     for (const m2 of descriptor.modules ?? []) {
-      const mc = readModuleFile(root, m2.repoPath, "knowledge/module/module-context.md");
+      const rp = moduleRepoPath(m2);
+      const mcRelPath = resolveModuleContextPath(root, rp);
+      const mc = readModuleFile(root, rp, mcRelPath);
       responsibilities.push(mc ? `[${m2.id}] ${firstParagraph3(mc) || m2.name || m2.id}` : `[${m2.id}] ${m2.name || m2.id} (no module-context)`);
     }
     capsuleType = "system";
@@ -10303,7 +10356,7 @@ function exportCapsuleTool(root, args) {
     };
   } else {
     if (role === "module") {
-      const mc = readText(root, "knowledge/module/module-context.md");
+      const mc = readText(root, "knowledge/tech/module/module-context.md") ?? readText(root, "knowledge/module/module-context.md");
       if (!mc) warnings.push("module-context.md not found.");
       if (mc && isPlaceholder(mc)) warnings.push("module-context.md contains placeholder sections.");
       const modId = config.module?.id ?? "module";
@@ -10348,6 +10401,70 @@ function exportCapsuleTool(root, args) {
   writeDerived(root, mdPath, mdContent);
   return ok2({ exported: true, type: capsuleType, module: args.module ?? void 0, paths: { json: jsonPath, md: mdPath }, warnings });
 }
+function modulesDiscoverTool(root, args) {
+  const config = loadConfig2(root);
+  if (!config) return fail2("No Kaddo config found.");
+  if (!isCore2(config)) return fail2("Module discovery is only available from a core repository.");
+  const sysName = config.system?.name ?? config.project?.name ?? "";
+  const workspaceRoots2 = config.multirepo?.workspace_roots ?? [".."];
+  const IGNORED = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", "coverage", "vendor", ".next", "out", "tmp", "temp", ".kaddo"]);
+  const coreAbs = path3.resolve(root);
+  const discovered = [];
+  for (const wr of workspaceRoots2) {
+    const rootAbs = path3.resolve(root, wr);
+    if (!fs3.existsSync(rootAbs) || !fs3.statSync(rootAbs).isDirectory()) continue;
+    let entries;
+    try {
+      entries = fs3.readdirSync(rootAbs);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (IGNORED.has(entry)) continue;
+      const candidateAbs = path3.resolve(rootAbs, entry);
+      if (!fs3.statSync(candidateAbs).isDirectory()) continue;
+      if (candidateAbs === coreAbs) continue;
+      const relPath = path3.relative(root, candidateAbs).replace(/\\/g, "/");
+      const cfgPath = path3.join(candidateAbs, ".kaddo", "config.yml");
+      if (!fs3.existsSync(cfgPath)) {
+        discovered.push({ id: entry, path: relPath, status: "not_configured", eligibleForMapping: false });
+        continue;
+      }
+      let parsed = null;
+      try {
+        parsed = parseYaml10(fs3.readFileSync(cfgPath, "utf-8"));
+      } catch {
+      }
+      const role = parsed?.project?.role ?? parsed?.multirepo?.role;
+      if (role !== "module") {
+        discovered.push({ id: entry, path: relPath, status: "invalid", eligibleForMapping: false, warning: "Not configured as module." });
+        continue;
+      }
+      const modParent = parsed?.multirepo?.parent_system ?? "";
+      if (modParent && modParent !== sysName) {
+        discovered.push({ id: parsed?.module?.id ?? entry, path: relPath, status: "foreign_system", eligibleForMapping: false, parentSystem: modParent });
+        continue;
+      }
+      discovered.push({ id: parsed?.module?.id ?? entry, path: relPath, status: "configured", eligibleForMapping: true });
+    }
+  }
+  if (args.apply) {
+    if (!args.confirm) {
+      return ok2({ discovered, applied: false, message: "Set confirm: true to apply discovered modules." });
+    }
+    const descriptor = loadModulesDescriptor(root);
+    for (const d3 of discovered.filter((dd) => dd.eligibleForMapping)) {
+      if (!(descriptor.modules ?? []).some((m2) => m2.id === d3.id)) {
+        if (!descriptor.modules) descriptor.modules = [];
+        descriptor.modules.push({ id: d3.id, name: d3.id, path: d3.path, parent_system: sysName, status: "configured" });
+      }
+    }
+    const ymlContent = stringifyYaml4({ version: descriptor.version ?? 1, system: sysName, workspace_roots: workspaceRoots2, modules: descriptor.modules ?? [] });
+    writeDerived(root, ".kaddo/modules.yml", ymlContent);
+    return ok2({ discovered, applied: true });
+  }
+  return ok2({ discovered, applied: false });
+}
 function renderCapsuleMd(data) {
   const fm = ["---", `type: knowledge-capsule`, `system: ${data.system}`, `version: ${data.version}`, `updated_at: ${data.updated_at}`, "---", ""].join("\n");
   const list2 = (items) => items.length === 0 ? "_To be completed._" : items.map((i) => `- ${i}`).join("\n");
@@ -11641,6 +11758,18 @@ function createServer(root) {
     },
     async (args) => toolText(guarded(root, () => exportCapsuleTool(root, args)))
   );
+  server.registerTool(
+    "kaddo_modules_discover",
+    {
+      title: "Discover multirepo modules",
+      description: "Discover sibling repositories configured as Kaddo modules. Does not persist without apply+confirm. Core only.",
+      inputSchema: {
+        apply: z3.boolean().optional(),
+        confirm: z3.boolean().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => modulesDiscoverTool(root, args)))
+  );
   let installedSkills = [];
   try {
     assertKaddoProject(root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/mcp",
-  "version": "3.62.0",
+  "version": "3.63.0",
   "description": "MCP server for Kaddo project knowledge: read-only resources/tools/prompts plus safe derived generation under .kaddo/.",
   "license": "MIT",
   "repository": {