@kaddo/cli 3.62.0 → 3.64.0

package/dist/index.js

@@ -114,9 +114,15 @@ guard:
 `;
   if (meta.role === "core") {
     yml += `
+system:
+  name: ${meta.systemName ?? meta.name}
+`;
+    yml += `
 multirepo:
   role: core
-  modules_file: knowledge/modules/modules.md
+  modules_file: .kaddo/modules.yml
+  workspace_roots:
+    - ..
 `;
   }
   if (meta.role === "module") {
@@ -212,21 +218,27 @@ _How the system is deployed: regions, environments, infrastructure._
 _Auth, observability, error handling, compliance, and other shared concerns._
 `;
 }
-function buildModulesFile(projectName) {
+function buildModulesFile(systemName3) {
   return `---
 type: modules-map
-system: ${projectName}
+system: ${systemName3}
 generated_by: kaddo-init
-template_version: 1
+template_version: 2
 ---
 
-# ${projectName} \u2014 Modules
+# ${systemName3} \u2014 Modules
 
-_List the modules that compose this system. Each module is a repository with its own \`kaddo init\` as a multirepo module._
+_No modules mapped yet. Run \`kaddo modules discover\` to find sibling modules, or \`kaddo modules map <path>\` to register one manually._
+`;
+}
+function buildModulesYml(systemName3) {
+  return `version: 1
+system: ${systemName3}
 
-## Modules
+workspace_roots:
+  - ..
 
-_No modules mapped yet. Run \`kaddo modules map\` to register one._
+modules: []
 `;
 }
 function buildKnowledge(projectName) {
@@ -302,25 +314,6 @@ async function runInit() {
     initialValue: inferredName,
     validate: (v) => v.trim().length === 0 ? "Project name is required." : void 0
   });
-  const state = await select2({
-    message: "What kind of project is this?",
-    options: [
-      { value: "new", label: "New", hint: "Starting from scratch" },
-      { value: "pre-ai", label: "Pre-AI", hint: "Existing code, not prepared for agents" },
-      { value: "legacy", label: "Legacy", hint: "Knowledge lives in people's heads" }
-    ],
-    initialValue: "pre-ai"
-  });
-  const teamSize = await select2({
-    message: "Team size",
-    options: [
-      { value: "indie", label: "Indie", hint: "1 person" },
-      { value: "small", label: "Small", hint: "2-5 people" },
-      { value: "medium", label: "Medium", hint: "6-20 people" },
-      { value: "enterprise", label: "Enterprise", hint: "20+ people" }
-    ],
-    initialValue: "small"
-  });
   const structure = await select2({
     message: "Repository structure",
     options: [
@@ -329,38 +322,65 @@ async function runInit() {
     ],
     initialValue: "monorepo"
   });
-  const language = await select2({
-    message: "Project knowledge language (the CLI stays in English)",
-    options: [
-      { value: "en", label: "English" },
-      { value: "es", label: "Spanish" }
-    ],
-    initialValue: "en"
-  });
   let role;
+  let systemName3;
   let parentSystem;
   let modId;
   if (structure === "multirepo") {
     role = await select2({
-      message: "Is this repository the core or a module?",
+      message: "What is the role of this repository?",
       options: [
         { value: "core", label: "Core / system orchestrator" },
         { value: "module", label: "Module of an existing system" }
       ]
     });
+    if (role === "core") {
+      systemName3 = await text2({
+        message: "System name",
+        placeholder: "e.g. tryckers",
+        validate: (v) => v.trim().length === 0 ? "System name is required." : void 0
+      });
+    }
     if (role === "module") {
       parentSystem = await text2({
         message: "Parent system name",
-        placeholder: "e.g. dotear-platform",
+        placeholder: "e.g. tryckers",
         validate: (v) => v.trim().length === 0 ? "Parent system name is required." : void 0
       });
       modId = await text2({
         message: "Module ID",
-        placeholder: "e.g. loyalty",
+        placeholder: "e.g. frontend",
         validate: (v) => v.trim().length === 0 ? "Module ID is required." : void 0
       });
     }
   }
+  const state = await select2({
+    message: "What kind of project is this?",
+    options: [
+      { value: "new", label: "New", hint: "Starting from scratch" },
+      { value: "pre-ai", label: "Pre-AI", hint: "Existing code, not prepared for agents" },
+      { value: "legacy", label: "Legacy", hint: "Knowledge lives in people's heads" }
+    ],
+    initialValue: "pre-ai"
+  });
+  const language = await select2({
+    message: "Project knowledge language (the CLI stays in English)",
+    options: [
+      { value: "en", label: "English" },
+      { value: "es", label: "Spanish" }
+    ],
+    initialValue: "en"
+  });
+  const teamSize = await select2({
+    message: "Team size",
+    options: [
+      { value: "indie", label: "Indie", hint: "1 person" },
+      { value: "small", label: "Small", hint: "2-5 people" },
+      { value: "medium", label: "Medium", hint: "6-20 people" },
+      { value: "enterprise", label: "Enterprise", hint: "20+ people" }
+    ],
+    initialValue: "small"
+  });
   const meta = {
     name: projectName.trim(),
     state,
@@ -368,6 +388,7 @@ async function runInit() {
     structure,
     language,
     role,
+    systemName: systemName3?.trim(),
     parentSystem: parentSystem?.trim(),
     moduleId: modId?.trim()
   };
@@ -375,36 +396,39 @@ async function runInit() {
   writeFile(kaddoConfigPath, buildConfig(meta));
   log2.success("Created .kaddo/config.yml");
   if (role === "module") {
-    ensureDir(join(dir, ARCH_DIR, "module"));
+    ensureDir(join(dir, ARCH_DIR, "tech", "module"));
     writeFile(
-      join(dir, ARCH_DIR, "module", "module-context.md"),
+      join(dir, ARCH_DIR, "tech", "module", "module-context.md"),
       buildModuleContext(modId.trim(), parentSystem.trim())
     );
-    ensureDir(join(dir, ARCH_DIR, "tech"));
     if (!exists(join(dir, ARCH_DIR, "tech", "current-state.md"))) {
       writeFile(join(dir, ARCH_DIR, "tech", "current-state.md"), buildKnowledge(projectName.trim()));
     }
     if (!exists(join(dir, ARCH_DIR, "tech", "codebase.md"))) {
       writeFile(join(dir, ARCH_DIR, "tech", "codebase.md"), buildKnowledge(projectName.trim()));
     }
-    ensureDir(join(dir, ARCH_DIR, "delivery", "work-items"));
-    log2.success("Created knowledge/module/module-context.md");
+    log2.success("Created knowledge/tech/module/module-context.md");
     log2.success("Created knowledge/tech/current-state.md");
     log2.success("Created knowledge/tech/codebase.md");
     log2.info("Next: run `kaddo scan` to detect your stack, then use module-context-agent to refine module-context.md.");
   } else if (role === "core") {
+    const sysName = systemName3?.trim() ?? projectName.trim();
     ensureDir(join(dir, ARCH_DIR, "delivery", "work-items"));
-    ensureDir(join(dir, ARCH_DIR, "system"));
-    ensureDir(join(dir, ARCH_DIR, "modules"));
+    ensureDir(join(dir, ARCH_DIR, "tech", "system"));
+    ensureDir(join(dir, ARCH_DIR, "tech", "modules"));
+    ensureDir(join(dir, ARCH_DIR, "agents"));
+    ensureDir(join(dir, ARCH_DIR, "skills"));
     writeFile(join(dir, ARCH_DIR, "knowledge.md"), buildKnowledge(projectName.trim()));
     writeFile(join(dir, ARCH_DIR, "delivery", "roadmap.md"), buildRoadmap(projectName.trim()));
-    writeFile(join(dir, ARCH_DIR, "system", "system-context.md"), buildSystemContext(projectName.trim()));
-    writeFile(join(dir, ARCH_DIR, "modules", "modules.md"), buildModulesFile(projectName.trim()));
+    writeFile(join(dir, ARCH_DIR, "tech", "system", "system-context.md"), buildSystemContext(sysName));
+    writeFile(join(dir, ARCH_DIR, "tech", "modules", "modules.md"), buildModulesFile(sysName));
+    writeFile(join(dir, KADDO_DIR, "modules.yml"), buildModulesYml(sysName));
     log2.success("Created knowledge/knowledge.md");
     log2.success("Created knowledge/delivery/roadmap.md");
-    log2.success("Created knowledge/system/system-context.md");
-    log2.success("Created knowledge/modules/modules.md");
-    log2.info("Next: run `kaddo scan` then `kaddo add agents` and `kaddo add skills`.");
+    log2.success("Created knowledge/tech/system/system-context.md");
+    log2.success("Created knowledge/tech/modules/modules.md");
+    log2.success("Created .kaddo/modules.yml");
+    log2.info("Next: run `kaddo scan` then `kaddo modules discover` to find sibling modules.");
   } else {
     ensureDir(join(dir, ARCH_DIR, "delivery", "work-items"));
     writeFile(join(dir, ARCH_DIR, "knowledge.md"), buildKnowledge(projectName.trim()));
@@ -1305,10 +1329,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()
@@ -1333,8 +1361,8 @@ function loadConfig(dir) {
   const parsed = configSchema.safeParse(raw ?? {});
   if (!parsed.success) {
     const issues = parsed.error.issues.map((i) => {
-      const path7 = i.path.join(".");
-      return path7 ? `  - ${path7}: ${i.message}` : `  - ${i.message}`;
+      const path8 = i.path.join(".");
+      return path8 ? `  - ${path8}: ${i.message}` : `  - ${i.message}`;
     }).join("\n");
     throw new ConfigError(`Invalid .kaddo/config.yml:
 ${issues}`);
@@ -1391,6 +1419,15 @@ function projectRole(config) {
 function isModule(config) {
   return projectRole(config) === "module";
 }
+function isCore(config) {
+  return projectRole(config) === "core";
+}
+function systemName(config) {
+  return config.system?.name;
+}
+function workspaceRoots(config) {
+  return config.multirepo?.workspace_roots ?? [".."];
+}
 
 // src/core/command-help.ts
 var COMMAND_HELP = {
@@ -5030,7 +5067,8 @@ var RECOMMENDED_BY_STATE = {
     "backlog-agent.md",
     "work-item-agent.md",
     "implementation-agent.md",
-    "adr-agent.md"
+    "adr-agent.md",
+    "module-context-agent.md"
   ],
   "pre-ai": [
     "business-agent.md",
@@ -5040,7 +5078,8 @@ var RECOMMENDED_BY_STATE = {
     "backlog-agent.md",
     "work-item-agent.md",
     "implementation-agent.md",
-    "ownership-agent.md"
+    "ownership-agent.md",
+    "module-context-agent.md"
   ],
   legacy: [
     "legacy-agent.md",
@@ -6550,10 +6589,10 @@ function analyzeGuard(touchedFiles, artifacts, silentWithoutOwnership) {
 import { parse as parseYaml4, stringify as stringifyYaml2 } from "yaml";
 var IGNORE_FILE = ".kaddo/ignores.yml";
 function loadIgnores(dir) {
-  const path7 = join(dir, IGNORE_FILE);
-  if (!exists(path7)) return [];
+  const path8 = join(dir, IGNORE_FILE);
+  if (!exists(path8)) return [];
   try {
-    const raw = readFile(path7);
+    const raw = readFile(path8);
     const parsed = parseYaml4(raw);
     return Array.isArray(parsed) ? parsed : [];
   } catch {
@@ -6561,7 +6600,7 @@ function loadIgnores(dir) {
   }
 }
 function saveIgnore(dir, entry) {
-  const path7 = join(dir, IGNORE_FILE);
+  const path8 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const idx = existing.findIndex((e) => e.artifact_id === entry.artifact_id);
   if (idx >= 0) {
@@ -6569,17 +6608,17 @@ function saveIgnore(dir, entry) {
   } else {
     existing.push(entry);
   }
-  writeFile(path7, stringifyYaml2(existing));
+  writeFile(path8, stringifyYaml2(existing));
 }
 function isIgnored(ignores, artifactId) {
   return ignores.find((e) => e.artifact_id === artifactId);
 }
 function removeIgnore(dir, artifactId) {
-  const path7 = join(dir, IGNORE_FILE);
+  const path8 = join(dir, IGNORE_FILE);
   const existing = loadIgnores(dir);
   const filtered = existing.filter((e) => e.artifact_id !== artifactId);
   if (filtered.length === existing.length) return false;
-  writeFile(path7, stringifyYaml2(filtered));
+  writeFile(path8, stringifyYaml2(filtered));
   return true;
 }
 
@@ -6601,11 +6640,11 @@ function moduleArtifactCoverage(dir, id) {
   };
 }
 function loadMappedModules(dir) {
-  const path7 = join(dir, DESCRIPTOR_PATH);
-  if (!exists(path7)) return [];
+  const path8 = join(dir, DESCRIPTOR_PATH);
+  if (!exists(path8)) return [];
   let parsed;
   try {
-    parsed = parseYaml5(readFile(path7));
+    parsed = parseYaml5(readFile(path8));
   } catch {
     return [];
   }
@@ -6619,7 +6658,7 @@ function loadMappedModules(dir) {
     modules.push({
       id,
       name: typeof m.name === "string" ? m.name : void 0,
-      repoPath: typeof m.repoPath === "string" ? m.repoPath : "",
+      repoPath: typeof m.repoPath === "string" ? m.repoPath : typeof m.path === "string" ? m.path : "",
       type: typeof m.type === "string" ? m.type : void 0,
       mainTechnology: typeof m.mainTechnology === "string" ? m.mainTechnology : void 0,
       owner: typeof m.owner === "string" ? m.owner : void 0,
@@ -6668,13 +6707,15 @@ function detectModuleStatus(coreDir, repoPath) {
     status: "configured",
     configured: true,
     role: "module",
-    moduleContext: exists(join(moduleDir2, "knowledge", "module", "module-context.md")),
+    moduleContext: exists(join(moduleDir2, "knowledge", "tech", "module", "module-context.md")) || exists(join(moduleDir2, "knowledge", "module", "module-context.md")),
     currentState: exists(join(moduleDir2, "knowledge", "tech", "current-state.md")),
     codebase: exists(join(moduleDir2, "knowledge", "tech", "codebase.md"))
   };
 }
 function readModuleContext(coreDir, repoPath) {
-  const p2 = 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 p2 = exists(newPath) ? newPath : legacyPath;
   if (!exists(p2)) return null;
   try {
     return readFile(p2);
@@ -7085,7 +7126,7 @@ function buildGuardHistory(dir) {
     const d = hotspotDir(t.code_path);
     hotspotMap.set(d, (hotspotMap.get(d) ?? 0) + 1);
   }
-  const hotspots = [...hotspotMap.entries()].map(([path7, warnings]) => ({ path: path7, warnings })).sort((a, b) => b.warnings - a.warnings);
+  const hotspots = [...hotspotMap.entries()].map(([path8, warnings]) => ({ path: path8, warnings })).sort((a, b) => b.warnings - a.warnings);
   return {
     available: true,
     total_runs: sorted.length,
@@ -7487,7 +7528,7 @@ function runIgnoreRemove(artifactId) {
 
 // src/commands/explain.ts
 import matter6 from "gray-matter";
-import { parse as parseYaml10 } from "yaml";
+import { parse as parseYaml12 } from "yaml";
 
 // src/core/delivery-phase.ts
 function layer(layers, name) {
@@ -7548,6 +7589,34 @@ function firstUnrefinedLayerAgent(layers) {
   return { agent: "architecture-agent", step: "Use architecture-agent to complete knowledge/tech/current-state.md" };
 }
 function assessPhase(input) {
+  if (input.isModuleRepo) {
+    const techStatus = layer(input.layers, "Tech");
+    const techReady = !NOT_READY_LAYER.includes(techStatus);
+    if (techReady) {
+      return {
+        phase: "Active Delivery",
+        reasons: ["Module repo \u2014 Tech layer ready", "Business/Product managed by core"],
+        recommendedAgents: [],
+        nextStep: "Module knowledge is ready for core orchestration.",
+        llmInstructions: [
+          "This is a module repo. Business, Product, and Delivery are managed by the core repo.",
+          "Do not create business, product, roadmap or Work Items here."
+        ]
+      };
+    }
+    return {
+      phase: "Knowledge Refinement",
+      reasons: ["Module repo \u2014 Tech layer incomplete", "Business/Product managed by core"],
+      recommendedAgents: ["module-context-agent"],
+      nextStep: "Use module-context-agent to refine knowledge/tech/module/module-context.md",
+      llmInstructions: [
+        "Use the module-context-agent to refine the module context.",
+        "Do not create business, product, roadmap or Work Items in this module.",
+        "Do not install agents or skills.",
+        "Do not write application code."
+      ]
+    };
+  }
   const phase = determinePhase(input);
   const reasons = buildReasons(input);
   const bs = input.workItems.byState;
@@ -7653,10 +7722,10 @@ function assessPhase(input) {
 
 // src/core/capsule.ts
 import matter3 from "gray-matter";
-import { parse as parseYaml9, stringify as stringifyYaml4 } from "yaml";
+import { parse as parseYaml10, stringify as stringifyYaml5 } from "yaml";
 
 // src/commands/modules-map.ts
-import { parse as parseYaml8, stringify as stringifyYaml3 } from "yaml";
+import { parse as parseYaml9, stringify as stringifyYaml4 } from "yaml";
 
 // src/templates/registry.ts
 var QUALITY = "## Quality checklist";
@@ -9143,9 +9212,373 @@ function getTemplate(id) {
   return KADDO_TEMPLATES.find((t) => t.id === id);
 }
 
+// src/commands/modules-discover.ts
+import path5 from "path";
+import { parse as parseYaml8, stringify as stringifyYaml3 } from "yaml";
+var CONFIG_PATH3 = ".kaddo/config.yml";
+var MODULES_YML = ".kaddo/modules.yml";
+var MODULES_MD = "knowledge/tech/modules/modules.md";
+var IGNORED_DIRS = /* @__PURE__ */ new Set([
+  ".git",
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  "vendor",
+  ".next",
+  "out",
+  "tmp",
+  "temp",
+  ".kaddo"
+]);
+function readModulesYml(dir) {
+  const p2 = join(dir, MODULES_YML);
+  if (!exists(p2)) return { version: 1, system: "", workspace_roots: [".."], modules: [] };
+  try {
+    const parsed = parseYaml8(readFile(p2));
+    return {
+      version: parsed.version ?? 1,
+      system: parsed.system ?? "",
+      workspace_roots: parsed.workspace_roots ?? [".."],
+      modules: Array.isArray(parsed.modules) ? parsed.modules : []
+    };
+  } catch {
+    return { version: 1, system: "", workspace_roots: [".."], modules: [] };
+  }
+}
+function writeModulesYml(dir, yml) {
+  writeFile(join(dir, MODULES_YML), stringifyYaml3(yml));
+}
+function readRepoConfig(repoDir) {
+  const configPath = join(repoDir, CONFIG_PATH3);
+  if (!exists(configPath)) return null;
+  try {
+    return parseYaml8(readFile(configPath));
+  } catch {
+    return null;
+  }
+}
+function hasKnowledgeFile(repoDir, ...segments) {
+  return exists(join(repoDir, "knowledge", ...segments));
+}
+function hasModuleContext(repoDir) {
+  return hasKnowledgeFile(repoDir, "tech", "module", "module-context.md") || hasKnowledgeFile(repoDir, "module", "module-context.md");
+}
+function hasCurrentState(repoDir) {
+  return hasKnowledgeFile(repoDir, "tech", "current-state.md");
+}
+function hasCodebase(repoDir) {
+  return hasKnowledgeFile(repoDir, "tech", "codebase.md");
+}
+function buildModuleContextPaths(repoDir) {
+  const ctx = {};
+  if (hasKnowledgeFile(repoDir, "tech", "module", "module-context.md")) {
+    ctx.module = "knowledge/tech/module/module-context.md";
+  } else if (hasKnowledgeFile(repoDir, "module", "module-context.md")) {
+    ctx.module = "knowledge/module/module-context.md";
+  }
+  if (hasCurrentState(repoDir)) ctx.current_state = "knowledge/tech/current-state.md";
+  if (hasCodebase(repoDir)) ctx.codebase = "knowledge/tech/codebase.md";
+  return ctx;
+}
+function discoverModules(dir) {
+  const config = loadConfig(dir);
+  if (!config || !isCore(config)) return [];
+  const sysName = systemName(config) ?? config.project.name;
+  const roots = workspaceRoots(config);
+  const existing = readModulesYml(dir);
+  const seenIds = /* @__PURE__ */ new Set();
+  const seenPaths = /* @__PURE__ */ new Set();
+  const results = [];
+  const coreAbsPath = path5.resolve(dir);
+  for (const root of roots) {
+    const rootAbs = path5.resolve(dir, root);
+    if (!exists(rootAbs) || !isDir(rootAbs)) continue;
+    let entries;
+    try {
+      entries = readDir(rootAbs);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (IGNORED_DIRS.has(entry)) continue;
+      const candidateAbs = path5.resolve(rootAbs, entry);
+      if (!isDir(candidateAbs)) continue;
+      if (candidateAbs === coreAbsPath) continue;
+      const relPath = path5.relative(dir, candidateAbs).replace(/\\/g, "/");
+      const repoConfig = readRepoConfig(candidateAbs);
+      if (!repoConfig) {
+        results.push({
+          id: entry,
+          name: entry,
+          path: relPath.startsWith(".") ? relPath : `./${relPath}`,
+          parentSystem: "",
+          status: "not_configured",
+          eligibleForMapping: false,
+          moduleContext: false,
+          currentState: false,
+          codebase: false
+        });
+        continue;
+      }
+      const project = repoConfig.project;
+      const multirepo = repoConfig.multirepo;
+      const module = repoConfig.module;
+      const role = project?.role ?? multirepo?.role;
+      if (role !== "module") {
+        results.push({
+          id: entry,
+          name: project?.name ?? entry,
+          path: relPath.startsWith(".") ? relPath : `./${relPath}`,
+          parentSystem: "",
+          status: "invalid",
+          eligibleForMapping: false,
+          warning: "Repository has Kaddo but is not configured as a module.",
+          moduleContext: false,
+          currentState: false,
+          codebase: false
+        });
+        continue;
+      }
+      const modId = module?.id ?? entry;
+      const modParent = multirepo?.parent_system ?? "";
+      const modName = project?.name ?? entry;
+      const modPath = relPath.startsWith(".") ? relPath : `./${relPath}`;
+      if (modParent && modParent !== sysName) {
+        results.push({
+          id: modId,
+          name: modName,
+          path: modPath,
+          parentSystem: modParent,
+          status: "foreign_system",
+          eligibleForMapping: false,
+          warning: `parent system: ${modParent}`,
+          moduleContext: hasModuleContext(candidateAbs),
+          currentState: hasCurrentState(candidateAbs),
+          codebase: hasCodebase(candidateAbs)
+        });
+        continue;
+      }
+      let status = "configured";
+      let warning;
+      let eligible = true;
+      if (seenIds.has(modId)) {
+        status = "duplicate";
+        warning = `duplicate module id: ${modId}`;
+        eligible = false;
+      } else if (seenPaths.has(modPath)) {
+        status = "duplicate";
+        warning = `duplicate path: ${modPath}`;
+        eligible = false;
+      }
+      seenIds.add(modId);
+      seenPaths.add(modPath);
+      results.push({
+        id: modId,
+        name: modName,
+        path: modPath,
+        parentSystem: modParent || sysName,
+        status,
+        eligibleForMapping: eligible,
+        warning,
+        moduleContext: hasModuleContext(candidateAbs),
+        currentState: hasCurrentState(candidateAbs),
+        codebase: hasCodebase(candidateAbs)
+      });
+    }
+  }
+  for (const m of existing.modules) {
+    const absPath = path5.resolve(dir, m.path);
+    if (!exists(absPath) && !results.some((r) => r.path === m.path)) {
+      results.push({
+        id: m.id,
+        name: m.name,
+        path: m.path,
+        parentSystem: m.parent_system,
+        status: "missing",
+        eligibleForMapping: false,
+        warning: "Previously registered but path no longer exists.",
+        moduleContext: false,
+        currentState: false,
+        codebase: false
+      });
+    }
+  }
+  return results;
+}
+function applyDiscovery(dir, discovered) {
+  const config = loadConfig(dir);
+  const sysName = systemName(config) ?? config.project.name;
+  const yml = readModulesYml(dir);
+  yml.system = sysName;
+  const eligible = discovered.filter((d) => d.eligibleForMapping && d.status === "configured");
+  for (const d of eligible) {
+    const existingIdx = yml.modules.findIndex((m) => m.id === d.id);
+    const entry = {
+      id: d.id,
+      name: d.name,
+      path: d.path,
+      parent_system: d.parentSystem,
+      status: d.status,
+      context: buildModuleContextPaths(path5.resolve(dir, d.path))
+    };
+    if (existingIdx >= 0) {
+      yml.modules[existingIdx] = entry;
+    } else {
+      yml.modules.push(entry);
+    }
+  }
+  writeModulesYml(dir, yml);
+  updateModulesMd(dir, yml);
+  return { mapped: eligible.length };
+}
+function updateModulesMd(dir, yml) {
+  const lines = [
+    "---",
+    "type: modules-map",
+    `system: ${yml.system}`,
+    "generated_by: kaddo-modules-discover",
+    "template_version: 2",
+    "---",
+    "",
+    `# ${yml.system} \u2014 Modules`,
+    ""
+  ];
+  if (yml.modules.length === 0) {
+    lines.push("_No modules mapped yet. Run `kaddo modules discover` to find sibling modules._");
+  } else {
+    for (const m of yml.modules) {
+      lines.push(`## ${m.id}`);
+      lines.push("");
+      lines.push(`- Repository: \`${m.path}\``);
+      lines.push(`- Status: ${m.status}`);
+      lines.push(`- Parent system: ${m.parent_system}`);
+      const ctxPaths = m.context ?? {};
+      lines.push(`- Module context: ${ctxPaths.module ? "available" : "missing"}`);
+      lines.push("");
+    }
+  }
+  writeFile(join(dir, MODULES_MD), lines.join("\n"));
+}
+function runModulesValidate(dir = cwd()) {
+  const yml = readModulesYml(dir);
+  if (yml.modules.length === 0) {
+    console.log("No modules registered in .kaddo/modules.yml.");
+    return;
+  }
+  const config = loadConfig(dir);
+  const sysName = systemName(config) ?? config.project.name;
+  const legacy = detectLegacyPaths(dir);
+  if (legacy.length > 0) {
+    console.log("");
+    console.log("Legacy multirepo knowledge paths detected.");
+    console.log("");
+    console.log("Recommended migration:");
+    for (const l of legacy) {
+      console.log(`- ${l.from}`);
+      console.log(`  \u2192 ${l.to}`);
+      console.log("");
+    }
+  }
+  console.log("");
+  for (const m of yml.modules) {
+    const absPath = path5.resolve(dir, m.path);
+    if (!exists(absPath)) {
+      console.log(`${m.id.padEnd(16)} missing`);
+      continue;
+    }
+    const repoConfig = readRepoConfig(absPath);
+    if (!repoConfig) {
+      console.log(`${m.id.padEnd(16)} not_configured`);
+      continue;
+    }
+    const project = repoConfig.project;
+    const multirepo = repoConfig.multirepo;
+    const role = project?.role ?? multirepo?.role;
+    if (role !== "module") {
+      console.log(`${m.id.padEnd(16)} invalid`);
+      continue;
+    }
+    const modParent = multirepo?.parent_system;
+    if (modParent && modParent !== sysName) {
+      console.log(`${m.id.padEnd(16)} foreign_system`);
+      continue;
+    }
+    console.log(`${m.id.padEnd(16)} valid`);
+  }
+  console.log("");
+}
+function detectLegacyPaths(dir) {
+  const migrations = [];
+  if (exists(join(dir, "knowledge", "system", "system-context.md"))) {
+    migrations.push({ from: "knowledge/system/system-context.md", to: "knowledge/tech/system/system-context.md" });
+  }
+  if (exists(join(dir, "knowledge", "modules", "modules.md"))) {
+    migrations.push({ from: "knowledge/modules/modules.md", to: "knowledge/tech/modules/modules.md" });
+  }
+  if (exists(join(dir, "knowledge", "module", "module-context.md"))) {
+    migrations.push({ from: "knowledge/module/module-context.md", to: "knowledge/tech/module/module-context.md" });
+  }
+  return migrations;
+}
+async function runModulesDiscover(opts = {}) {
+  const dir = cwd();
+  intro2("kaddo modules discover");
+  const config = loadConfig(dir);
+  if (!config) {
+    console.error("Kaddo is not initialized. Run `kaddo init` first.");
+    process.exit(1);
+  }
+  if (!isCore(config)) {
+    console.error("Module discovery is only available from a core repository.");
+    process.exit(1);
+  }
+  const discovered = discoverModules(dir);
+  if (discovered.length === 0) {
+    log2.info("No sibling repositories found in workspace roots.");
+    outro2("Discovery complete.");
+    return;
+  }
+  console.log("");
+  console.log("Workspace module discovery");
+  console.log("");
+  for (const d of discovered) {
+    const icon = d.status === "configured" ? "\u2713" : d.status === "not_configured" ? "\u25CB" : d.status === "foreign_system" ? "!" : d.status === "duplicate" ? "!" : d.status === "missing" ? "\u2717" : "\u2717";
+    console.log(`${icon} ${d.id}`);
+    console.log(`  ${d.path}`);
+    console.log(`  status: ${d.status}`);
+    if (d.warning) console.log(`  ${d.warning}`);
+    console.log("");
+  }
+  const eligible = discovered.filter((d) => d.eligibleForMapping && d.status === "configured");
+  console.log(`Eligible for mapping: ${eligible.length}`);
+  if (eligible.length === 0) {
+    outro2("Discovery complete.");
+    return;
+  }
+  if (opts.apply) {
+    const confirmed = await confirm2({
+      message: `Map ${eligible.length} configured Kaddo modules?`,
+      initialValue: true
+    });
+    if (!confirmed) {
+      outro2("No changes applied.");
+      return;
+    }
+    const result = applyDiscovery(dir, discovered);
+    log2.success(`Mapped ${result.mapped} configured modules.`);
+    log2.success("Updated .kaddo/modules.yml.");
+    log2.success("Updated knowledge/tech/modules/modules.md.");
+    outro2("Discovery applied.");
+  } else {
+    log2.info("Run `kaddo modules discover --apply` to persist eligible modules.");
+    outro2("Discovery complete.");
+  }
+}
+
 // src/commands/modules-map.ts
 var DESCRIPTOR_PATH2 = ".kaddo/modules.yml";
-var CONFIG_PATH3 = ".kaddo/config.yml";
+var CONFIG_PATH4 = ".kaddo/config.yml";
 var MODULE_TYPES = [
   "frontend",
   "backend",
@@ -9160,17 +9593,17 @@ function slugify2(name) {
   return name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function readModulesDescriptor(dir) {
-  const path7 = join(dir, DESCRIPTOR_PATH2);
-  if (!exists(path7)) return { version: 1, modules: [] };
+  const path8 = join(dir, DESCRIPTOR_PATH2);
+  if (!exists(path8)) return { version: 1, modules: [] };
   try {
-    const parsed = parseYaml8(readFile(path7));
+    const parsed = parseYaml9(readFile(path8));
     return { version: parsed.version ?? 1, modules: parsed.modules ?? [] };
   } catch {
     return { version: 1, modules: [] };
   }
 }
 function writeModulesDescriptor(dir, descriptor) {
-  writeFile(join(dir, DESCRIPTOR_PATH2), stringifyYaml3(descriptor));
+  writeFile(join(dir, DESCRIPTOR_PATH2), stringifyYaml4(descriptor));
 }
 function moduleDir(id) {
   return `knowledge/tech/modules/${id}`;
@@ -9301,70 +9734,74 @@ function mapModule(dir, input) {
   }
   return { module: mod, written, skipped, alreadyRegistered };
 }
-async function runModulesMap(dir = cwd()) {
+async function runModulesMap(dir = cwd(), modulePath) {
   intro2("kaddo modules map");
-  if (!exists(join(dir, CONFIG_PATH3))) {
+  if (!exists(join(dir, CONFIG_PATH4))) {
     console.error("Kaddo is not initialized in this project.");
     console.error("Run `kaddo init` first.");
     process.exit(1);
   }
-  log2.info("Register a secondary repository as a module of this system.");
+  let repoPath;
+  if (modulePath) {
+    repoPath = modulePath;
+  } else {
+    repoPath = await text2({
+      message: "Repository path (relative to this repo)",
+      placeholder: "e.g. ../frontend",
+      validate: (v) => v.trim().length === 0 ? "Repository path is required." : void 0
+    });
+  }
+  const targetDir = join(dir, repoPath.trim());
+  if (!exists(targetDir)) {
+    log2.warn(`Path "${repoPath.trim()}" does not exist.`);
+  } else {
+    const st = detectModuleStatus(dir, repoPath.trim());
+    if (st.status === "not_configured") {
+      log2.warn(`${repoPath.trim()} does not have Kaddo configured. Run \`kaddo init\` inside that repository first.`);
+    } else if (st.status === "invalid") {
+      log2.warn(`${repoPath.trim()} has Kaddo but is not configured as a module.`);
+    }
+  }
   const name = await text2({
     message: "Module name",
     placeholder: "e.g. Frontend Web",
     validate: (v) => v.trim().length === 0 ? "Name is required." : void 0
   });
-  const repoPath = await text2({
-    message: "Repository path (relative to this repo)",
-    placeholder: "e.g. ../frontend",
-    validate: (v) => v.trim().length === 0 ? "Repository path is required." : void 0
-  });
   const type = await select2({
     message: "Module type",
     options: MODULE_TYPES.map((t) => ({ value: t, label: t }))
   });
-  const mainTechnology = await text2({
-    message: "Main technology (optional)",
-    placeholder: "e.g. Next.js"
-  });
-  const owner = await text2({
-    message: "Owner (optional)",
-    placeholder: "e.g. web-team"
-  });
-  const capabilitiesRaw = await text2({
-    message: "Related capabilities (comma-separated, optional)",
-    placeholder: "e.g. customer-dashboard, loyalty-portal"
-  });
-  if (!exists(join(dir, repoPath.trim()))) {
-    log2.warn(`Path "${repoPath.trim()}" does not exist yet \u2014 registering anyway.`);
-  }
   const result = mapModule(dir, {
     name,
     repoPath,
-    type,
-    mainTechnology,
-    owner,
-    capabilities: capabilitiesRaw.split(",").map((c) => c.trim()).filter(Boolean)
+    type
   });
   for (const p2 of result.written) log2.success(`Created ${p2}`);
   for (const p2 of result.skipped) log2.info(`Kept existing ${p2}`);
   log2.success(`Module "${result.module.id}" recorded in ${DESCRIPTOR_PATH2}`);
-  outro2(
-    "Module mapped. Use the `module-design-agent` in your LLM with `.kaddo/context-pack.md` to fill in module-design.md."
-  );
+  outro2("Module mapped.");
 }
 function runModulesList(dir = cwd()) {
-  const descriptor = readModulesDescriptor(dir);
-  if (descriptor.modules.length === 0) {
-    console.log("No modules mapped. Run `kaddo modules map` to register one.");
+  const yml = readModulesYml(dir);
+  if (yml.modules.length === 0) {
+    console.log("");
+    console.log("No modules are mapped for this core repository.");
+    console.log("");
+    console.log("Run:");
+    console.log("  kaddo modules discover");
+    console.log("");
+    console.log("Or map one manually:");
+    console.log("  kaddo modules map <path>");
+    console.log("");
     return;
   }
   console.log("");
   console.log("Mapped modules:");
-  for (const m of descriptor.modules) {
-    const st = detectModuleStatus(dir, m.repoPath);
+  for (const m of yml.modules) {
+    const mPath = m.path ?? m.repoPath ?? "";
+    const st = detectModuleStatus(dir, mPath);
     const statusLabel = st.status === "configured" ? "\u2713 configured" : st.status === "not_configured" ? "\u25CB not configured" : "\u2717 invalid";
-    console.log(`  ${m.id.padEnd(16)} ${m.type.padEnd(14)} ${statusLabel.padEnd(18)} ${m.repoPath}`);
+    console.log(`  ${m.id.padEnd(16)} ${statusLabel.padEnd(18)} ${mPath}`);
     if (st.warning) console.log(`    \u26A0 ${st.warning}`);
   }
   console.log("");
@@ -9505,14 +9942,14 @@ function loadExternalRegistry(dir) {
   const p2 = join(dir, EXTERNAL_PATH);
   if (!exists(p2)) return [];
   try {
-    const parsed = parseYaml9(readFile(p2));
+    const parsed = parseYaml10(readFile(p2));
     return Array.isArray(parsed?.external) ? parsed.external : [];
   } catch {
     return [];
   }
 }
 function serializeExternalRegistry(entries) {
-  return stringifyYaml4({ external: entries });
+  return stringifyYaml5({ external: entries });
 }
 function sectionList(md, title) {
   const re = new RegExp(`^##\\s+${title}\\s*$`, "im");
@@ -9539,7 +9976,7 @@ function sectionParagraph(md, title) {
   }
   return "";
 }
-function parseCapsule(id, path7, md) {
+function parseCapsule(id, path8, md) {
   const { data } = matter3(md);
   const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
   let ageDays = null;
@@ -9549,7 +9986,7 @@ function parseCapsule(id, path7, md) {
   }
   return {
     id,
-    path: path7,
+    path: path8,
     system: data.system ? String(data.system) : id,
     owner: data.owner ? String(data.owner) : void 0,
     updatedAt,
@@ -9635,9 +10072,9 @@ function buildGraph(dir, config, opts = {}, now = /* @__PURE__ */ new Date()) {
   ];
   const presentLayers = [];
   for (const layer2 of layerDocs) {
-    const path7 = layer2.files.map((f) => `${KNOWLEDGE3}/${f}`).find((rel) => exists(join(dir, rel)));
-    if (path7) {
-      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path7 });
+    const path8 = layer2.files.map((f) => `${KNOWLEDGE3}/${f}`).find((rel) => exists(join(dir, rel)));
+    if (path8) {
+      addNode({ id: layer2.id, type: layer2.type, label: layer2.label, path: path8 });
       presentLayers.push(layer2.id);
     }
   }
@@ -10280,6 +10717,21 @@ function layerQuality(dir, layer2) {
   return worst;
 }
 function knowledgeLayers(dir) {
+  const config = loadConfig(dir);
+  if (config && isModule(config)) {
+    return [
+      { layer: "Business", status: "Not applicable", detected: [] },
+      { layer: "Product", status: "Not applicable", detected: [] },
+      ...discoverLayers(dir).filter((l) => l.layer === "Tech").map((l) => {
+        if (l.status !== "Consolidated" && l.status !== "Structured") return l;
+        const q = layerQuality(dir, l.layer);
+        if (q === "placeholder") return { ...l, status: "Placeholder" };
+        if (q === "weak") return { ...l, status: "Weak" };
+        return l;
+      }),
+      { layer: "Delivery", status: "Managed by core", detected: [] }
+    ];
+  }
   return discoverLayers(dir).map((l) => {
     if (l.status !== "Consolidated" && l.status !== "Structured") return l;
     const q = layerQuality(dir, l.layer);
@@ -10965,6 +11417,9 @@ function buildSharedFileStatuses(statuses) {
   }));
 }
 
+// src/core/next-step.ts
+import { parse as parseYaml11 } from "yaml";
+
 // src/core/decisions.ts
 var CANDIDATES_DISCOVERY = "knowledge/tech/discovery/decision-candidates.md";
 var CANDIDATES_LEGACY = "knowledge/tech/decision-candidates.md";
@@ -11080,6 +11535,14 @@ function buildDeliveryState(dir) {
     adapters_installed: adapters.length
   };
 }
+function hasRegisteredModules(modulesYmlPath) {
+  try {
+    const parsed = parseYaml11(readFile(modulesYmlPath));
+    return Array.isArray(parsed?.modules) && parsed.modules.length > 0;
+  } catch {
+    return false;
+  }
+}
 function safeRead(p2) {
   try {
     return readFile(p2);
@@ -11129,12 +11592,20 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
   }
   const state = config.project.state;
   const q = (rel) => analyzeKnowledgeArtifact(dir, rel);
+  const resolveAgent = (agent) => {
+    const file = agent.endsWith(".md") ? agent : `${agent}.md`;
+    const path8 = agentInstallPath(file);
+    const installed = isFile(join(dir, path8));
+    const group = agentGroupOf(file);
+    return { agentPath: path8, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
+  };
   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 = q(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." };
@@ -11143,15 +11614,26 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
       return { id: "context", phase: "Discovery", label: "Run `kaddo context` to prepare the LLM context pack.", command: "kaddo context", reason: "No context pack has been generated yet." };
     }
     if (qMC !== "useful") {
+      const ar = resolveAgent("module-context-agent");
       return {
         id: "refine-module-context",
         phase: "Knowledge Refinement",
-        label: "Use module-context-agent to refine `knowledge/module/module-context.md`.",
+        label: "Use module-context-agent to refine `knowledge/tech/module/module-context.md`.",
         agent: "module-context-agent",
         skill: "module-context-refinement",
         target: MC,
+        agentPath: ar.agentPath,
+        agentInstalled: ar.agentInstalled,
+        installCommand: ar.installCommand,
         reason: "Module context is still a placeholder.",
-        instructions: ["Refine the module context with real knowledge about this module.", "Do not create business.md or product.md.", "Do not write code."]
+        instructions: [
+          "Refine the module context using evidence from this repository.",
+          "Use the parent system context when available.",
+          "Do not create business, product, roadmap or Work Items in this module.",
+          "Do not install agents or skills in this module.",
+          "Do not write application code.",
+          "Preserve frontmatter and record unknowns as open questions."
+        ]
       };
     }
     const qCurrentState2 = q(CS), qCodebase2 = q(CB);
@@ -11180,12 +11662,18 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     if (!exists(join(dir, ".kaddo", "understand.md"))) {
       return { id: "understand", phase: "Discovery", label: "Run `kaddo understand` to summarize the project context.", command: "kaddo understand", reason: "No understand handoff has been generated yet." };
     }
-    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." };
+    return { id: "module-ready", phase: "Ready for Core Orchestration", label: "Module knowledge is complete. Create and manage Work Items from the core repository.", reason: "This module's knowledge is ready for core orchestration. Work Items are created and tracked in the core." };
   }
   const qBusiness = q(B), qProduct = q(P), qCap = q(CAP), qCurrentState = q(CS), qCodebase = q(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." };
@@ -11200,13 +11688,6 @@ function resolveNextStep(dir, now = /* @__PURE__ */ new Date()) {
     return { id: "context", phase: "Discovery", label: "Run `kaddo context` to prepare the LLM context pack.", command: "kaddo context", reason: "No context pack has been generated yet." };
   }
   const discovery = state === "pre-ai" || state === "legacy";
-  const resolveAgent = (agent) => {
-    const file = agent.endsWith(".md") ? agent : `${agent}.md`;
-    const path7 = agentInstallPath(file);
-    const installed = isFile(join(dir, path7));
-    const group = agentGroupOf(file);
-    return { agentPath: path7, agentInstalled: installed, installCommand: installed ? void 0 : `kaddo add agents --group ${group}` };
-  };
   const refine = (id, agent, target, quality, verb = "complete") => {
     const ar = resolveAgent(agent);
     return {
@@ -11945,6 +12426,67 @@ var identifyRisks = {
     return { status: hasLegacy ? "done" : "pending", agent: hasLegacy ? void 0 : "legacy-agent" };
   }
 };
+var refineModuleContext = {
+  id: "refine-module-context",
+  label: "Refine module context",
+  evaluate: (ctx) => {
+    const newPath = join(ctx.dir, "knowledge/tech/module/module-context.md");
+    const legacyPath = join(ctx.dir, "knowledge/module/module-context.md");
+    const mcPath = exists(newPath) ? "knowledge/tech/module/module-context.md" : exists(legacyPath) ? "knowledge/module/module-context.md" : null;
+    if (!mcPath) return { status: "pending", agent: "module-context-agent", skill: "module-context-refinement" };
+    const q = analyzeKnowledgeArtifact(ctx.dir, mcPath);
+    if (q === "useful") return { status: "done", evidence: [mcPath] };
+    return { status: "current", agent: "module-context-agent", skill: "module-context-refinement", evidence: [mcPath], reason: "Module context is still a placeholder." };
+  }
+};
+var describeModuleCurrentState = {
+  id: "describe-current-state",
+  label: "Describe current state",
+  evaluate: (ctx) => ({
+    status: isUseful(ctx.qCurrentState) ? "done" : "pending",
+    evidence: isUseful(ctx.qCurrentState) ? ["knowledge/tech/current-state.md"] : void 0,
+    agent: isUseful(ctx.qCurrentState) ? void 0 : "architecture-agent"
+  })
+};
+var mapModuleCodebase = {
+  id: "map-codebase",
+  label: "Map codebase",
+  evaluate: (ctx) => ({
+    status: isUseful(ctx.qCodebase) ? "done" : "pending",
+    evidence: isUseful(ctx.qCodebase) ? ["knowledge/tech/codebase.md"] : void 0,
+    agent: isUseful(ctx.qCodebase) ? void 0 : "architecture-agent"
+  })
+};
+var validateModuleKnowledge = {
+  id: "validate-module-knowledge",
+  label: "Validate module knowledge",
+  evaluate: (ctx) => {
+    const hasUnderstand = exists(join(ctx.dir, ".kaddo/understand.md"));
+    if (hasUnderstand) return { status: "done", evidence: [".kaddo/understand.md"] };
+    return { status: "pending", command: "kaddo understand" };
+  }
+};
+var readyForCoreOrchestration = {
+  id: "ready-for-core-orchestration",
+  label: "Ready for core orchestration",
+  evaluate: (ctx) => {
+    const newPath = join(ctx.dir, "knowledge/tech/module/module-context.md");
+    const legacyPath = join(ctx.dir, "knowledge/module/module-context.md");
+    const mcPath = exists(newPath) ? "knowledge/tech/module/module-context.md" : exists(legacyPath) ? "knowledge/module/module-context.md" : null;
+    const mcUseful = mcPath ? analyzeKnowledgeArtifact(ctx.dir, mcPath) === "useful" : false;
+    const allDone = mcUseful && isUseful(ctx.qCurrentState) && isUseful(ctx.qCodebase);
+    return { status: allDone ? "done" : "pending", reason: allDone ? void 0 : "Module knowledge is not yet complete." };
+  }
+};
+var MODULE_STEPS = [
+  enableKaddo,
+  scanRepository,
+  refineModuleContext,
+  describeModuleCurrentState,
+  mapModuleCodebase,
+  validateModuleKnowledge,
+  readyForCoreOrchestration
+];
 var NEW_STEPS = [
   enableKaddo,
   defineBusiness,
@@ -12085,17 +12627,18 @@ function mapNextStepId(id) {
     "review-work-item": "refine-work-item",
     "prepare-implementation": "prepare-implementation",
     "implement-work-item": "prepare-implementation",
-    "refine-module-context": "refine-work-item",
+    "refine-module-context": "refine-module-context",
     "init-module-context": "enable-kaddo",
-    "module-ready": "prepare-implementation",
-    "validate-work-item-modules": "prepare-implementation"
+    "module-ready": "ready-for-core-orchestration",
+    "validate-work-item-modules": "validate-module-knowledge",
+    "modules-discover": "enable-kaddo"
   };
   return MAP[id] ?? id;
 }
 function buildProjectRoute(dir) {
   const config = loadConfig(dir);
   const state = config?.project.state ?? "pre-ai";
-  const defs = stepsForState(state);
+  const defs = config && isModule(config) ? MODULE_STEPS : stepsForState(state);
   const ctx = buildRouteContext(dir);
   const steps = defs.map((d) => {
     const result = d.evaluate(ctx);
@@ -12434,7 +12977,8 @@ function buildProjectExplanation(dir) {
     roadmapQuality: buildRoadmapQuality(dir),
     projectRoute: buildProjectRoute(dir),
     scanSignals: loadScanSignals(dir),
-    metadataHealth: analyzeMetadataHealth(dir)
+    metadataHealth: analyzeMetadataHealth(dir),
+    isModuleRepo: config != null && isModule(config)
   };
 }
 function stateLabel(state) {
@@ -12759,7 +13303,7 @@ function renderExplanationAgent(exp) {
 
 // src/commands/explain.ts
 var ARCH_DIR5 = "knowledge";
-var CONFIG_PATH4 = ".kaddo/config.yml";
+var CONFIG_PATH5 = ".kaddo/config.yml";
 function readKnowledge(dir) {
   const knowledgePath = join(dir, ARCH_DIR5, "knowledge.md");
   if (!exists(knowledgePath)) return null;
@@ -12783,10 +13327,10 @@ function readRoadmap(dir) {
   }
 }
 function readConfig(dir) {
-  const configPath = join(dir, CONFIG_PATH4);
+  const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return {};
   try {
-    return parseYaml10(readFile(configPath));
+    return parseYaml12(readFile(configPath));
   } catch {
     return {};
   }
@@ -12897,7 +13441,7 @@ function explainForAgent(dir, artifacts, opts) {
   console.log(JSON.stringify(output, null, 2));
 }
 function explainProject(dir, mode) {
-  if (!exists(join(dir, CONFIG_PATH4))) {
+  if (!exists(join(dir, CONFIG_PATH5))) {
     console.error("No .kaddo/config.yml found. Run `kaddo init` first.");
     process.exit(1);
   }
@@ -13028,15 +13572,16 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
   if (!knowledgeSummary) {
     missing.push("No project knowledge summary found yet.");
   }
+  const moduleRepo = config != null && isModule(config);
   const roadmapSummary = readMarkdownSummary(dir, "delivery/roadmap.md") ?? "";
-  if (!roadmapSummary) {
+  if (!roadmapSummary && !moduleRepo) {
     missing.push("No roadmap baseline found.");
   }
   const allArtifacts = discoverKnowledge(dir);
   const workItems = allArtifacts.filter(
     (a) => isDeliveryWorkItem(a) && isActiveState(lifecycleStateOf({ status: a.status, filePath: a.filePath }))
   );
-  if (workItems.length === 0) {
+  if (workItems.length === 0 && !moduleRepo) {
     missing.push("No work items found.");
   }
   const state = config.project.state;
@@ -13068,8 +13613,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     tech: { status: layerStatusOf("Tech"), artifacts: { "knowledge/tech/codebase.md": qCodebase, "knowledge/tech/current-state.md": qCurrentState } },
     delivery: { status: layerStatusOf("Delivery"), artifacts: { "knowledge/delivery/roadmap.md": qRoadmap } }
   };
-  if (qBusiness === "placeholder") missing.push("Business context exists but still looks like a bootstrap placeholder.");
-  if (qProduct === "placeholder" || qCapabilities === "placeholder") missing.push("Product capabilities exist but still look like a bootstrap placeholder.");
+  if (qBusiness === "placeholder" && !moduleRepo) missing.push("Business context exists but still looks like a bootstrap placeholder.");
+  if ((qProduct === "placeholder" || qCapabilities === "placeholder") && !moduleRepo) missing.push("Product capabilities exist but still look like a bootstrap placeholder.");
   if (qCurrentState === "placeholder") missing.push("Current state exists but still looks like a bootstrap placeholder.");
   if (qCodebase === "placeholder") missing.push("Codebase map exists but still looks like a bootstrap placeholder.");
   const allWorkItems = allArtifacts.filter((a) => a.isWorkItem);
@@ -13092,7 +13637,8 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
       workItemsTotal: allWorkItems.length,
       workItemsWithOwnership: wiWithOwnership,
       workItemsMissingOwnership: allWorkItems.length - wiWithOwnership
-    }
+    },
+    isModuleRepo: config != null && isModule(config)
   });
   const nextStepRecommendation = resolveNextStep(dir, now);
   const techDecisions = buildTechDecisions(dir);
@@ -13613,6 +14159,16 @@ function flowForState(state) {
 }
 function buildUnderstandPlan(dir, config) {
   const state = config.project.state;
+  if (isModule(config)) {
+    return {
+      project: { name: config.project.name, state, teamSize: config.team.size, structure: config.project.structure, language: "English" },
+      steps: [],
+      missingAgents: [],
+      agentsInstalled: true,
+      scanAvailable: exists(join(dir, ".kaddo", "scan.json")),
+      contextPackPath: ".kaddo/context-pack.md"
+    };
+  }
   const flow = flowForState(state).filter((s) => !exists(join(dir, s.output)));
   const steps = flow.map((s) => {
     const installed = agentIsInstalled(dir, s.agent);
@@ -13969,7 +14525,7 @@ function renderUnderstandTerminal(plan) {
 }
 
 // src/core/delivery.ts
-import { parse as parseYaml11 } from "yaml";
+import { parse as parseYaml13 } from "yaml";
 function slugify4(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -14203,7 +14759,7 @@ function runUnderstand() {
 }
 
 // src/core/classifier.ts
-import path5 from "path";
+import path6 from "path";
 var MIGRATION_PATTERNS = [
   /supabase\/migrations\//,
   /prisma\/migrations\//,
@@ -14242,7 +14798,7 @@ var DEP_PATTERNS = [
   /^pom\.xml$/
 ];
 function normalizePath2(p2) {
-  return p2.split(path5.sep).join("/");
+  return p2.split(path6.sep).join("/");
 }
 function matchesAny2(file, patterns) {
   const normalized = normalizePath2(file);
@@ -14420,14 +14976,14 @@ async function runClassify(opts = {}) {
 }
 
 // src/commands/status.ts
-import { parse as parseYaml12 } from "yaml";
+import { parse as parseYaml14 } from "yaml";
 var ARCH_DIR8 = "knowledge";
-var CONFIG_PATH5 = ".kaddo/config.yml";
+var CONFIG_PATH6 = ".kaddo/config.yml";
 function loadConfig3(dir) {
-  const p2 = join(dir, CONFIG_PATH5);
+  const p2 = join(dir, CONFIG_PATH6);
   if (!exists(p2)) return {};
   try {
-    return parseYaml12(readFile(p2));
+    return parseYaml14(readFile(p2));
   } catch {
     return {};
   }
@@ -14629,13 +15185,13 @@ function runHistory(opts = {}) {
 }
 
 // src/commands/add.ts
-import { parse as parseYaml13, stringify as stringifyYaml5 } from "yaml";
-var CONFIG_PATH6 = ".kaddo/config.yml";
+import { parse as parseYaml15, stringify as stringifyYaml6 } from "yaml";
+var CONFIG_PATH7 = ".kaddo/config.yml";
 function readProjectState(dir) {
-  const configPath = join(dir, CONFIG_PATH6);
+  const configPath = join(dir, CONFIG_PATH7);
   if (!exists(configPath)) return void 0;
   try {
-    const config = parseYaml13(readFile(configPath));
+    const config = parseYaml15(readFile(configPath));
     return config.project?.state;
   } catch {
     return void 0;
@@ -14656,23 +15212,23 @@ function selectSkillModuleFiles(files, opts) {
   return { files: selected, label };
 }
 function markModuleInstalled(dir, configKey, moduleName) {
-  const configPath = join(dir, CONFIG_PATH6);
+  const configPath = join(dir, CONFIG_PATH7);
   if (!exists(configPath)) return;
   try {
-    const config = parseYaml13(readFile(configPath));
+    const config = parseYaml15(readFile(configPath));
     config[configKey] = { installed: true, installed_at: (/* @__PURE__ */ new Date()).toISOString().split("T")[0] };
     const modules = config.modules ?? [];
     if (!modules.includes(moduleName)) modules.push(moduleName);
     config.modules = modules;
-    writeFile(configPath, stringifyYaml5(config));
+    writeFile(configPath, stringifyYaml6(config));
   } catch {
   }
 }
 function isModuleInstalled(dir, configKey) {
-  const configPath = join(dir, CONFIG_PATH6);
+  const configPath = join(dir, CONFIG_PATH7);
   if (!exists(configPath)) return false;
   try {
-    const config = parseYaml13(readFile(configPath));
+    const config = parseYaml15(readFile(configPath));
     const moduleConfig = config[configKey];
     return moduleConfig?.installed === true;
   } catch {
@@ -14696,11 +15252,16 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
     process.exit(1);
   }
   intro2(`kaddo add ${mod.name}`);
-  if (!exists(join(dir, CONFIG_PATH6))) {
+  if (!exists(join(dir, CONFIG_PATH7))) {
     console.error("Kaddo is not initialized in this project.");
     console.error("Run `kaddo init` first.");
     process.exit(1);
   }
+  const addConfig = loadConfig(dir);
+  if ((mod.name === "agents" || mod.name === "skills") && addConfig && isModule(addConfig)) {
+    console.error(`Module repos do not use ${mod.name}. ${mod.name === "agents" ? "Agents" : "Skills"} are managed by the core repo.`);
+    process.exit(1);
+  }
   const alreadyInstalled = isModuleInstalled(dir, mod.configKey);
   for (const d of mod.dirs) {
     ensureDir(join(dir, d));
@@ -14901,11 +15462,11 @@ function applyOwnership(raw, globs, mode = "replace") {
 }
 
 // src/commands/owners.ts
-var CONFIG_PATH7 = ".kaddo/config.yml";
+var CONFIG_PATH8 = ".kaddo/config.yml";
 var CUSTOM_GLOB = "__custom__";
 function runOwners(opts) {
   const dir = cwd();
-  if (!exists(join(dir, CONFIG_PATH7))) {
+  if (!exists(join(dir, CONFIG_PATH8))) {
     console.error("No .kaddo/config.yml found. Run `kaddo init` first.");
     process.exit(1);
   }
@@ -14995,7 +15556,7 @@ async function chooseGlobs(suggested) {
 }
 async function runOwnersSuggest() {
   const dir = cwd();
-  if (!exists(join(dir, CONFIG_PATH7))) {
+  if (!exists(join(dir, CONFIG_PATH8))) {
     console.error("No .kaddo/config.yml found. Run `kaddo init` first.");
     process.exit(1);
   }
@@ -15070,113 +15631,6 @@ ${globs.map((g) => `  - ${g}`).join("\n")}`);
   outro2("Ownership declared.");
 }
 
-// src/commands/module-descriptor.ts
-import { parse as parseYaml14, stringify as stringifyYaml6 } from "yaml";
-var DESCRIPTOR_PATH3 = "knowledge/module.yml";
-function readDescriptor(dir) {
-  const path7 = join(dir, DESCRIPTOR_PATH3);
-  if (!exists(path7)) return null;
-  try {
-    return parseYaml14(readFile(path7));
-  } catch {
-    return null;
-  }
-}
-function writeDescriptor(dir, descriptor) {
-  writeFile(join(dir, DESCRIPTOR_PATH3), stringifyYaml6(descriptor));
-}
-async function runModuleDescriptor(opts) {
-  const dir = cwd();
-  if (opts.show || !opts.init && exists(join(dir, DESCRIPTOR_PATH3))) {
-    const descriptor2 = readDescriptor(dir);
-    if (!descriptor2) {
-      console.log("No module descriptor found. Run `kaddo module --init` to create one.");
-      return;
-    }
-    printDescriptor(descriptor2);
-    return;
-  }
-  intro2("kaddo module --init");
-  log2.info("Creates knowledge/module.yml \u2014 declares this repository's identity for multirepo contexts.");
-  const name = await text2({
-    message: "Module name (this repository)",
-    placeholder: "e.g. payments-service",
-    validate: (v) => v.trim().length === 0 ? "Name is required." : void 0
-  });
-  const purpose = await text2({
-    message: "Purpose \u2014 what does this module do?",
-    placeholder: "e.g. Handles subscription billing, invoicing, and payment processing",
-    validate: (v) => v.trim().length === 0 ? "Purpose is required." : void 0
-  });
-  const stack = await text2({
-    message: "Stack (comma-separated)",
-    placeholder: "e.g. TypeScript, Node.js, PostgreSQL, Stripe"
-  });
-  const responsibilities = await text2({
-    message: "Key responsibilities (comma-separated)",
-    placeholder: "e.g. Charge customers, Issue refunds, Manage subscriptions"
-  });
-  const contracts = await text2({
-    message: "Contracts exposed (APIs, events, comma-separated)",
-    placeholder: "e.g. POST /charge, event:payment.succeeded, event:payment.failed"
-  });
-  const dependencies = await text2({
-    message: "Dependencies on other modules (comma-separated)",
-    placeholder: "e.g. auth-service, user-service"
-  });
-  const boundaries = await text2({
-    message: "What does this module NOT own?",
-    placeholder: "e.g. User identity, Email delivery, Inventory"
-  });
-  const ownership = await text2({
-    message: "Team or owner",
-    placeholder: "e.g. platform-team"
-  });
-  const splitTrimmed = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
-  const descriptor = {
-    name: name.trim(),
-    purpose: purpose.trim(),
-    stack: splitTrimmed(stack),
-    responsibilities: splitTrimmed(responsibilities),
-    contracts: splitTrimmed(contracts),
-    dependencies: splitTrimmed(dependencies),
-    boundaries: splitTrimmed(boundaries),
-    ownership: ownership.trim(),
-    related_artifacts: []
-  };
-  writeDescriptor(dir, descriptor);
-  log2.success(`Created ${DESCRIPTOR_PATH3}`);
-  outro2(`Module descriptor ready. Share knowledge/module.yml with dependent repositories.`);
-}
-function printDescriptor(d) {
-  console.log("");
-  console.log(`Module: ${d.name}`);
-  console.log(`Purpose: ${d.purpose}`);
-  if (d.stack?.length) console.log(`Stack: ${d.stack.join(", ")}`);
-  if (d.ownership) console.log(`Owner: ${d.ownership}`);
-  if (d.responsibilities?.length) {
-    console.log("Responsibilities:");
-    d.responsibilities.forEach((r) => console.log(`  - ${r}`));
-  }
-  if (d.contracts?.length) {
-    console.log("Contracts:");
-    d.contracts.forEach((c) => console.log(`  - ${c}`));
-  }
-  if (d.dependencies?.length) {
-    console.log("Dependencies:");
-    d.dependencies.forEach((dep) => console.log(`  - ${dep}`));
-  }
-  if (d.boundaries?.length) {
-    console.log("Boundaries (not owned):");
-    d.boundaries.forEach((b) => console.log(`  - ${b}`));
-  }
-  if (d.related_artifacts?.length) {
-    console.log("Related artifacts:");
-    d.related_artifacts.forEach((a) => console.log(`  - ${a}`));
-  }
-  console.log("");
-}
-
 // src/core/bootstrap-templates.ts
 function fm(type, state) {
   return `---
@@ -15608,7 +16062,7 @@ function baselineTemplate(kind, state) {
 }
 
 // src/commands/bootstrap.ts
-var CONFIG_PATH8 = ".kaddo/config.yml";
+var CONFIG_PATH9 = ".kaddo/config.yml";
 var FILE_TARGETS = [
   { path: "knowledge/business/business.md", kind: "business" },
   { path: "knowledge/product/product.md", kind: "product" },
@@ -15665,7 +16119,7 @@ function bootstrap(dir) {
 }
 async function runBootstrap(dir = cwd()) {
   intro2("kaddo bootstrap");
-  if (!exists(join(dir, CONFIG_PATH8))) {
+  if (!exists(join(dir, CONFIG_PATH9))) {
     console.error("Kaddo is not initialized in this project.");
     console.error("Run `kaddo init` first.");
     process.exit(1);
@@ -16257,7 +16711,7 @@ function runReportImpact(opts = {}) {
 }
 
 // src/core/savings.ts
-import { parse as parseYaml15 } from "yaml";
+import { parse as parseYaml16 } from "yaml";
 var DEFAULT_ASSUMPTIONS = {
   currency: "USD",
   hourly_cost: 40,
@@ -16275,7 +16729,7 @@ function loadAssumptions(dir) {
   const p2 = join(dir, SAVINGS_PATH);
   if (!exists(p2)) return { assumptions: { ...DEFAULT_ASSUMPTIONS }, source: "default" };
   try {
-    const raw = parseYaml15(readFile(p2));
+    const raw = parseYaml16(readFile(p2));
     const a = raw?.assumptions ?? {};
     const t = raw?.team ?? {};
     const num = (v, d) => typeof v === "number" && Number.isFinite(v) ? v : d;
@@ -17057,7 +17511,7 @@ function runAssetsUpdate(kind, opts = {}) {
 
 // src/commands/ready.ts
 import fs4 from "fs";
-import path6 from "path";
+import path7 from "path";
 import matter11 from "gray-matter";
 function validateReadiness(content, frontmatter) {
   const warnings = [];
@@ -17120,10 +17574,10 @@ function transitionToReady(filePath) {
   const posix = filePath.replace(/\\/g, "/");
   let newPath = filePath;
   if (posix.includes("/work-items/draft/")) {
-    const readyDir = path6.dirname(filePath).replace(/[/\\]draft$/, path6.sep + "ready");
+    const readyDir = path7.dirname(filePath).replace(/[/\\]draft$/, path7.sep + "ready");
     ensureDir(readyDir);
-    const fileName = path6.basename(filePath);
-    newPath = path6.join(readyDir, fileName);
+    const fileName = path7.basename(filePath);
+    newPath = path7.join(readyDir, fileName);
   }
   return { newPath, newContent };
 }
@@ -17194,8 +17648,8 @@ async function runReady(id, opts = {}) {
     fs4.unlinkSync(wi.filePath);
     log2.success(`Updated status: ready`);
     log2.success(`Moved file:`);
-    log2.info(`  ${path6.relative(dir, wi.filePath)}`);
-    log2.info(`  \u2192 ${path6.relative(dir, newPath)}`);
+    log2.info(`  ${path7.relative(dir, wi.filePath)}`);
+    log2.info(`  \u2192 ${path7.relative(dir, newPath)}`);
   } else {
     writeFile(wi.filePath, newContent);
     log2.success(`Updated status: ready`);
@@ -17229,8 +17683,8 @@ var capsuleCmd = program.command("capsule").description("Export this project as
 capsuleCmd.command("export").description("Write a Knowledge Capsule about this project to .kaddo/exports/").option("--scope <scope>", 'Export scope: "system" includes all mapped modules').option("--module <id>", "Export a capsule for a specific mapped module").action((opts) => {
   runCapsuleExport(opts);
 });
-capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path7) => {
-  runCapsuleAdd(path7);
+capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path8) => {
+  runCapsuleAdd(path8);
 });
 var graphCmd = program.command("graph").description("Export the lightweight, file-based knowledge graph of the project");
 graphCmd.command("export").description("Write the knowledge graph to .kaddo/graph.json and .kaddo/graph.mmd").option("--scope <scope>", "Graph scope: active (default) or all").option("--format <format>", "Output format: json, mermaid (default: both)").action((opts) => {
@@ -17328,16 +17782,23 @@ program.command("owners [action]").description("List domain owners, or run `owne
     runOwners(opts);
   }
 });
-program.command("module").description("Show or initialize the multirepo module descriptor (knowledge/module.yml)").option("--init", "Create the module descriptor interactively").option("--show", "Print the current module descriptor").action(async (opts) => {
-  await runModuleDescriptor(opts);
+program.command("module").description("(deprecated) Use `kaddo modules` instead").allowUnknownOption().action(() => {
+  console.log("Unknown command `module`.");
+  console.log("Did you mean `kaddo modules list`?");
 });
-var modulesCmd = program.command("modules").description("Map and list secondary repositories as modules of the system (multirepo)");
-modulesCmd.command("map").description("Register a secondary repository as a module and generate its knowledge structure").action(async () => {
-  await runModulesMap();
+var modulesCmd = program.command("modules").description("Discover, map, list and validate multirepo modules");
+modulesCmd.command("discover").description("Discover sibling repositories configured as Kaddo modules").option("--apply", "Persist discovered modules to .kaddo/modules.yml").action(async (opts) => {
+  await runModulesDiscover(opts);
 });
-modulesCmd.command("list").description("List mapped modules").action(() => {
+modulesCmd.command("map [path]").description("Register a repository as a module manually").action(async (modulePath) => {
+  await runModulesMap(void 0, modulePath);
+});
+modulesCmd.command("list").description("List mapped modules from .kaddo/modules.yml").action(() => {
   runModulesList();
 });
+modulesCmd.command("validate").description("Validate registered modules against their current configuration").action(() => {
+  runModulesValidate();
+});
 program.command("add [module]").description("Install an optional Kaddo module (adr, incident, rfc, migration, legacy, agents, skills, standards, security, stack, git-strategy)").option("--all", "For `add agents` / `add skills`: install every item (not just the recommended set)").option("--group <name>", "For `add agents`: business|product|tech|delivery|utilities. For `add skills`: delivery|tech|integration").action((moduleName, opts) => {
   runAdd(moduleName ?? "", { all: opts.all, group: opts.group });
 });