@kaddo/cli 3.15.0 → 3.16.1

package/README.md

@@ -71,6 +71,10 @@ knowledge/
   config.yml               ← project config
 ```
 
+Asks for the project state (`new | pre-ai | legacy`), team size, repo structure and the
+**project knowledge language** (`en | es`) — the language your knowledge artifacts are
+written in; the CLI itself stays English.
+
 ---
 
 ### `kaddo scan`
@@ -265,12 +269,17 @@ concrete step (`kaddo scan` or `kaddo add agents`).
 Create a Work Item with the minimum context for its Knowledge Level.
 
 ```bash
-kaddo create feature   # K2: 4 questions
-kaddo create bugfix    # K2: 4 questions
-kaddo create hotfix    # K1: 2 questions
-kaddo create spike     # K3: 4 questions
+kaddo create feature   # K2: delivers a user-facing capability
+kaddo create bugfix    # K2: fixes a known defect
+kaddo create hotfix    # K1: urgent fix on a released version
+kaddo create spike     # K3: exploratory / reduce uncertainty
+kaddo create chore     # K1: maintenance, tooling, config, infra
 ```
 
+New Work Items land in `knowledge/delivery/work-items/draft/` with `status: draft`
+(lifecycle: `draft → ready → in-progress → blocked → completed → archived`). Aliases like
+`setup`, `tooling`, `maintenance`, `infrastructure` or `refactor` resolve to `chore`.
+
 **From a roadmap candidate:**
 
 ```bash
@@ -409,6 +418,25 @@ architecture baseline, roadmap, agents), work items, **ownership coverage**, the
 `kaddo explain` summarizes what Kaddo already knows. The focused flags
 (`--scope`, `--type`, `--since`) still explain a subset of artifacts.
 
+---
+
+### `kaddo capsule`
+
+Share or consume minimal, portable knowledge about a system — a **Knowledge Capsule** —
+without mapping it as multirepo or reading its source.
+
+```bash
+kaddo capsule export        # → .kaddo/exports/<project>.capsule.md / .json
+kaddo capsule add <path>    # import an external capsule → external/<id>.capsule.md
+```
+
+`export` builds a deterministic draft from `knowledge/` (purpose, capabilities, public
+contracts, risks, ADRs, owners — never source code or secrets); refine it with the
+`capsule-agent` before sharing. `add` registers the capsule in `.kaddo/external.yml`;
+`kaddo context` then includes an **External Knowledge** section and `kaddo explain` lists
+the capsules (warning when one looks stale). See the
+[Knowledge Capsules guide](https://kaddo.trycatch.tv/knowledge-capsules/).
+
 ## Roadmap
 
 The full knowledge loop ships today: `scan → context → agents → understand → roadmap →
@@ -441,6 +469,15 @@ create --from roadmap → owners → guard → explain`.
 | v3.6 | Flexible roadmap parsing and roadmap candidate/materialized Work Item reporting |
 | v3.7 | Work Item lifecycle active workspace (`draft`, `ready`, `in-progress`, `blocked`, `completed`, `archived`) |
 | v3.7.1 | Context Efficiency positioning: Repository Exploration Tax and structured-knowledge narrative |
+| v3.8 | Agent Trace & responsibility boundaries: every prompt declares Agent/Produced/Next; new `implementation-agent` (the only agent that may suggest a branch) |
+| v3.9 | New `chore` Work Item type (+ aliases setup/tooling/maintenance/infra); explain Work Items by Type; context Delivery Mix |
+| v3.9.1 | Unified knowledge artifact discovery: one service behind explain/context/owners/guard (fixes owners missing lifecycle subfolders) |
+| v3.10 | State-aware recommendations: real phase model (Discovery → Planning → Delivery Preparation → Active Delivery → Maintenance) drives understand/context/explain |
+| v3.11 | Command workflow clarity: official command matrix + "Question answered / Suggested next" footer on scan/context/explain/understand; `chore/` branch prefix |
+| v3.13 | New `backlog-agent`: capture raw ideas into a Work Item draft or roadmap candidate (human decides the next step) |
+| v3.14 | Project knowledge language (`project.language: en\|es`): knowledge in your language, CLI stays English; all agents respect it |
+| v3.15 | Delivery context consistency: phase-based handoff + per-phase LLM instructions; assisted `owners suggest` (normalize/validate globs); new `ownership-agent`; guard untracked-files warning; duplicate Work Item detection |
+| v3.16 | Knowledge Capsules: `kaddo capsule export/add`, External Knowledge in context/explain, new `capsule-agent` |
 
 **Optional modules (installed with `kaddo add`):**
 

package/dist/index.js

@@ -600,6 +600,21 @@ ${issues}`);
   }
   return parsed.data;
 }
+function requireConfig(dir) {
+  let config;
+  try {
+    config = loadConfig(dir);
+  } catch (err) {
+    const message = err instanceof ConfigError ? err.message : String(err);
+    console.error(message);
+    process.exit(1);
+  }
+  if (!config) {
+    console.error("No .kaddo/config.yml found. Run `kaddo init` first.");
+    process.exit(1);
+  }
+  return config;
+}
 function nextStepsForState(state) {
   switch (state) {
     case "new":
@@ -657,7 +672,15 @@ var COMMAND_HELP = {
     question: "Is knowledge drifting from code?",
     next: "Update the affected knowledge, then commit"
   },
-  "add agents": { question: "Which agents are available?", next: "kaddo understand" }
+  "add agents": { question: "Which agents are available?", next: "kaddo understand" },
+  "capsule export": {
+    question: "How do I share this project as external context?",
+    next: "Refine with the capsule-agent, then share the capsule file"
+  },
+  "capsule add": {
+    question: "How do I consume another system as external context?",
+    next: "kaddo context (the pack now includes External Knowledge)"
+  }
 };
 function commandFooterLines(name) {
   const help = COMMAND_HELP[name];
@@ -1611,6 +1634,20 @@ var RESPONSIBILITY_MATRIX = {
     ],
     next: ["kaddo scan", "kaddo owners suggest", "kaddo guard", "kaddo explain"]
   },
+  "capsule-agent": {
+    agent: "capsule-agent",
+    responsibleFor: ["Refining/validating a Knowledge Capsule for external sharing"],
+    produces: [".kaddo/exports/<system>.capsule.md"],
+    canSuggest: ["kaddo capsule export"],
+    cannotSuggest: [
+      "exporting secrets",
+      "exporting source code",
+      "inventing contracts",
+      "code",
+      "git"
+    ],
+    next: ["kaddo capsule export"]
+  },
   "ownership-agent": {
     agent: "ownership-agent",
     responsibleFor: ["Precise code: ownership for Work Items and artifacts"],
@@ -2932,6 +2969,85 @@ Code, tests and migrations live in the repository. Knowledge updates go under \`
 - Affected knowledge is updated.
 - Commit is suggested and awaits human confirmation \u2014 never run automatically.
 `;
+var CAPSULE_AGENT = `# Capsule Agent
+
+## Role
+
+You are the Kaddo Capsule Agent. Your job is to refine and validate a **Knowledge Capsule** \u2014 a
+minimal, portable summary another project can consume as external context \u2014 before it is exported.
+
+You do not write code, you never invent contracts, and you mark uncertainties. A capsule contains
+**knowledge, not code or secrets**.
+
+## When to Use
+
+Use this agent before sharing a Knowledge Capsule (after \`kaddo capsule export\` produced a draft),
+to sharpen its purpose, capabilities, public contracts, risks, owners and out-of-scope.
+
+## Input Required
+
+Provide \`.kaddo/context-pack.md\` plus \`knowledge/product/capabilities.md\`,
+\`knowledge/tech/current-state.md\`, \`knowledge/tech/decisions/\` and any contracts
+(\`knowledge/tech/contracts/\`) that exist. Also provide the draft capsule from
+\`.kaddo/exports/<system>.capsule.md\`.
+
+## Expected Output
+
+A refined Markdown capsule intended to be saved as \`.kaddo/exports/<system>.capsule.md\`.
+
+## Instructions
+
+1. Summarize what the system does and the boundaries of this capsule.
+2. List the **public contracts** consumers integrate with (APIs, events) \u2014 never invent them.
+3. List exposed capabilities, dependencies and known integration risks.
+4. Identify owners and relevant ADRs.
+5. State what is **out of scope** for this capsule.
+6. Mark any unknowns explicitly.
+
+## Constraints
+
+- Do **not** export secrets, tokens, credentials, private keys, PII or internal sensitive URLs.
+- Do **not** export source code.
+- Do **not** invent contracts or integrations.
+- Summarize and mark boundaries; prefer "unknown" over guessing.
+
+## Output Format
+
+\`\`\`markdown
+---
+type: knowledge-capsule
+system: <system>
+version: 1
+updated_at: <YYYY-MM-DD>
+owner: <team>
+---
+
+# <System> \u2014 Knowledge Capsule
+
+## Purpose
+## Responsibilities
+## Exposed Capabilities
+## Public Contracts
+## Dependencies
+## Known Risks
+## Relevant ADRs
+## Owners
+## Out of Scope
+## Usage Notes
+\`\`\`
+
+## Where to Save the Result
+
+Save as \`.kaddo/exports/<system>.capsule.md\`. The human reviews the security checklist (no
+secrets, no source) before sharing.
+
+## Quality Checklist
+
+- Purpose and boundaries are clear.
+- Public contracts are real (not invented) \u2014 unknowns are marked.
+- Capabilities, dependencies, risks, owners and out-of-scope are present.
+- No secrets, credentials, PII or source code are included.
+`;
 var OWNERSHIP_AGENT = `# Ownership Agent
 
 ## Role
@@ -3108,7 +3224,9 @@ var AGENT_PROMPTS = [
   // Backlog capture (idea → draft / roadmap candidate — VS-050)
   { fileName: "backlog-agent.md", content: BACKLOG_AGENT },
   // Ownership proposals (precise code: globs — VS-052)
-  { fileName: "ownership-agent.md", content: OWNERSHIP_AGENT }
+  { fileName: "ownership-agent.md", content: OWNERSHIP_AGENT },
+  // Knowledge Capsule refinement (external context — VS-054)
+  { fileName: "capsule-agent.md", content: CAPSULE_AGENT }
   // Every official prompt ends with its responsibility boundaries + Agent Trace footer.
 ].map((p2) => ({ fileName: p2.fileName, content: withResponsibilityTrace(p2.fileName, p2.content) }));
 
@@ -3123,7 +3241,8 @@ var AGENT_GROUPS = {
     "security-agent.md",
     "standards-agent.md",
     "module-design-agent.md",
-    "adr-agent.md"
+    "adr-agent.md",
+    "capsule-agent.md"
   ],
   delivery: [
     "backlog-agent.md",
@@ -3234,6 +3353,9 @@ var agentReadme = {
     "- **pre-ai** \u2192 capability-agent \u2192 architecture-agent \u2192 roadmap-agent",
     "- **legacy** \u2192 legacy-agent \u2192 architecture-agent \u2192 capability-agent \u2192 roadmap-agent",
     "",
+    "Then, in delivery: backlog-agent (capture ideas) \u2192 work-item-agent (refine) \u2192",
+    "ownership-agent (propose code: globs) \u2192 implementation-agent (build).",
+    "",
     "## Installed agents",
     "",
     "### Bootstrap agents (new projects)",
@@ -3250,14 +3372,22 @@ var agentReadme = {
     "- `legacy-agent.md` \u2014 analyze risks/unknowns before changing legacy code.",
     "- `adr-agent.md` \u2014 propose candidate architecture decisions.",
     "",
-    "### Operational agents",
+    "### Delivery agents",
     "",
+    "- `backlog-agent.md` \u2014 capture raw ideas/notes into a Work Item draft or roadmap candidate.",
     "- `work-item-agent.md` \u2014 refine roadmap candidates or existing Work Items.",
+    "- `implementation-agent.md` \u2014 implement a refined Work Item (the only agent that may",
+    "  suggest a branch; never runs git).",
+    "- `ownership-agent.md` \u2014 propose precise `code:` globs (human applies with `kaddo owners suggest`).",
     "- `git-strategy-agent.md` \u2014 define branch/commit/tag/release strategy.",
+    "",
+    "### Operational agents",
+    "",
     "- `security-agent.md` \u2014 document security considerations (no scanning).",
     "- `standards-agent.md` \u2014 propose lightweight coding/docs/architecture standards.",
     "- `stack-agent.md` \u2014 document technologies and stack decisions.",
-    "- `module-design-agent.md` \u2014 document the design of a mapped module."
+    "- `module-design-agent.md` \u2014 document the design of a mapped module.",
+    "- `capsule-agent.md` \u2014 refine a Knowledge Capsule for external sharing (no secrets/source)."
   ].join("\n")
 };
 var agentFiles = AGENT_PROMPTS.map((a) => ({
@@ -3844,7 +3974,7 @@ function formatList(items) {
   return items.map((i) => `- ${i.trim()}`).join("\n");
 }
 function buildFrontMatter(id, type, level, title, answers) {
-  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const today2 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const lines = [
     "---",
     `type: ${type}`,
@@ -3856,7 +3986,7 @@ function buildFrontMatter(id, type, level, title, answers) {
     `initiative:`,
     `domains: []`,
     `code: []`,
-    `created_at: ${today}`,
+    `created_at: ${today2}`,
     `summary: "${answers.problem?.split(".")[0] ?? title}"`,
     "---"
   ];
@@ -3926,7 +4056,7 @@ _What did we learn from this change? Update after completion._
   return sections.join("\n");
 }
 function buildModuleFrontMatter(id, modType, title, answers) {
-  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const today2 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const extra = modType.extraFrontMatter ?? {};
   const extraLines = Object.entries(extra).map(
     ([k, v]) => `${k}: ${JSON.stringify(v)}`
@@ -3942,7 +4072,7 @@ function buildModuleFrontMatter(id, modType, title, answers) {
     `initiative:`,
     `domains: []`,
     `code: []`,
-    `created_at: ${today}`,
+    `created_at: ${today2}`,
     `summary: "${title}"`,
     ...extraLines,
     "---"
@@ -4027,8 +4157,8 @@ async function runCreate(type, opts = {}) {
     answers[question.frontMatterField] = answer.trim();
   }
   const id = nextWorkItemId(dir);
-  const slug = slugify(title);
-  const fileName = `${id}-${slug}.md`;
+  const slug2 = slugify(title);
+  const fileName = `${id}-${slug2}.md`;
   const filePath = join(dir, DRAFT_DIR, fileName);
   const frontMatter2 = buildFrontMatter(id, workItemType, level, title.trim(), answers);
   const body = buildBody(workItemType, level, title.trim(), answers, levelDef.qualityGate);
@@ -4068,8 +4198,8 @@ async function runCreateModule(dir, modType) {
     answers[q.frontMatterField] = answer.trim();
   }
   const id = nextWorkItemId(dir);
-  const slug = slugify(title);
-  const fileName = `${id}-${slug}.md`;
+  const slug2 = slugify(title);
+  const fileName = `${id}-${slug2}.md`;
   const filePath = join(dir, DRAFT_DIR, fileName);
   const frontMatter2 = buildModuleFrontMatter(id, modType, title.trim(), answers);
   const body = buildModuleBody(modType, title.trim(), answers);
@@ -4091,7 +4221,7 @@ function resolveCandidateLevel(candidate, type) {
   return getLevelForType(type);
 }
 function buildRoadmapFrontMatter(id, type, level, title, candidate, answers) {
-  const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const today2 = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   const summary = (answers.problem?.split(".")[0] ?? candidate.expectedValue ?? title).trim();
   const initiative = candidate.initiative?.title ?? candidate.initiative?.id ?? "";
   const lines = [
@@ -4105,7 +4235,7 @@ function buildRoadmapFrontMatter(id, type, level, title, candidate, answers) {
     `initiative: "${initiative.replace(/"/g, "'")}"`,
     `domains: []`,
     `code: []`,
-    `created_at: ${today}`,
+    `created_at: ${today2}`,
     `source: roadmap`,
     `source_id: ${candidate.id}`,
     `source_initiative: ${candidate.initiative?.id ?? "unknown"}`,
@@ -4201,8 +4331,8 @@ function buildRoadmapWorkItem(opts) {
   const { id, type, level, candidate } = opts;
   const answers = opts.answers ?? {};
   const title = candidate.title.trim();
-  const slug = slugify(title);
-  const fileName = `${id}-${slug}.md`;
+  const slug2 = slugify(title);
+  const fileName = `${id}-${slug2}.md`;
   const qualityGate = getLevel(level).qualityGate;
   const frontMatter2 = buildRoadmapFrontMatter(id, type, level, title, candidate, answers);
   const body = buildRoadmapBody(type, level, title, candidate, answers, qualityGate);
@@ -5125,8 +5255,8 @@ function runIgnoreRemove(artifactId) {
 }
 
 // src/commands/explain.ts
-import matter2 from "gray-matter";
-import { parse as parseYaml8 } from "yaml";
+import matter3 from "gray-matter";
+import { parse as parseYaml9 } from "yaml";
 
 // src/core/delivery-phase.ts
 function layer(layers, name) {
@@ -5262,8 +5392,201 @@ function assessPhase(input) {
   return { phase, reasons, recommendedAgents: recommendedAgents2, nextStep, llmInstructions };
 }
 
-// src/core/knowledge-discovery.ts
+// src/core/capsule.ts
+import matter2 from "gray-matter";
+import { parse as parseYaml8, stringify as stringifyYaml3 } from "yaml";
 var KNOWLEDGE = "knowledge";
+function today() {
+  return (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+}
+function firstParagraph(md) {
+  const body = md.replace(/^---\n[\s\S]*?\n---\n/, "");
+  for (const block of body.split(/\n\s*\n/)) {
+    const t = block.trim();
+    if (t && !t.startsWith("#") && !t.startsWith(">")) return t.replace(/\s+/g, " ");
+  }
+  return "";
+}
+function readIf(dir, rel) {
+  const p2 = join(dir, rel);
+  return exists(p2) ? readFile(p2) : null;
+}
+function headings(md) {
+  return md.split(/\r?\n/).map((l) => l.match(/^#{2,3}\s+(.+?)\s*$/)).filter((m) => Boolean(m)).map((m) => m[1].trim()).filter((h) => !/^(summary|resumen|overview|risks|owners|out of scope)$/i.test(h));
+}
+function buildCapsule(dir, config) {
+  const ownerMap = loadOwners(dir);
+  const owners = [...new Set(Object.values(ownerMap).flat())];
+  const all = discoverKnowledge(dir);
+  const purposeSrc = readIf(dir, `${KNOWLEDGE}/business/business.md`) ?? readIf(dir, `${KNOWLEDGE}/knowledge.md`) ?? "";
+  const capsMd = readIf(dir, `${KNOWLEDGE}/product/capabilities.md`);
+  const risksMd = readIf(dir, `${KNOWLEDGE}/legacy/risks.md`);
+  const adrs = all.filter((a) => a.filePath.replace(/\\/g, "/").includes("/tech/decisions/") && Boolean(a.type)).map((a) => a.title || a.id).filter(Boolean);
+  return {
+    system: config.project.name,
+    version: 1,
+    updatedAt: today(),
+    owner: owners[0] ?? "unknown",
+    sourceProject: config.project.name,
+    purpose: firstParagraph(purposeSrc),
+    responsibilities: [],
+    capabilities: capsMd ? headings(capsMd) : [],
+    contracts: [],
+    dependencies: [],
+    knownRisks: risksMd ? headings(risksMd) : [],
+    adrs,
+    owners,
+    outOfScope: [],
+    usageNotes: []
+  };
+}
+function section2(title, items, placeholder) {
+  if (items.length === 0) return `## ${title}
+
+_${placeholder}_
+`;
+  return `## ${title}
+
+${items.map((i) => `- ${i}`).join("\n")}
+`;
+}
+function renderCapsuleMarkdown(c) {
+  const fm = [
+    "---",
+    "type: knowledge-capsule",
+    `system: ${c.system}`,
+    `version: ${c.version}`,
+    `updated_at: ${c.updatedAt}`,
+    `owner: ${c.owner}`,
+    `source_project: ${c.sourceProject}`,
+    ...c.sourceCommit ? [`source_commit: ${c.sourceCommit}`] : [],
+    "---"
+  ].join("\n");
+  const parts = [
+    fm,
+    "",
+    `# ${c.system} \u2014 Knowledge Capsule`,
+    "",
+    `## Purpose
+
+${c.purpose || "_To be completed by the capsule-agent._"}
+`,
+    section2("Responsibilities", c.responsibilities, "List what this system is responsible for."),
+    section2("Exposed Capabilities", c.capabilities, "List the capabilities this system exposes."),
+    section2("Public Contracts", c.contracts, "List public APIs and events (e.g. `POST /orders`, `OrderCreated`)."),
+    section2("Dependencies", c.dependencies, "List systems this one depends on."),
+    section2("Known Risks", c.knownRisks, "List integration risks consumers should know."),
+    section2("Relevant ADRs", c.adrs, "List decisions that affect how to integrate."),
+    section2("Owners", c.owners, "Who owns this system."),
+    section2("Out of Scope", c.outOfScope, "What this capsule deliberately does not cover."),
+    section2("Usage Notes", c.usageNotes, "How consumers should integrate."),
+    "> Security: this capsule must never contain secrets, tokens, credentials, PII or source code.",
+    ""
+  ];
+  return parts.join("\n");
+}
+function serializeCapsuleJson(c) {
+  return JSON.stringify({ type: "knowledge-capsule", ...c }, null, 2) + "\n";
+}
+var EXTERNAL_PATH = ".kaddo/external.yml";
+function loadExternalRegistry(dir) {
+  const p2 = join(dir, EXTERNAL_PATH);
+  if (!exists(p2)) return [];
+  try {
+    const parsed = parseYaml8(readFile(p2));
+    return Array.isArray(parsed?.external) ? parsed.external : [];
+  } catch {
+    return [];
+  }
+}
+function serializeExternalRegistry(entries) {
+  return stringifyYaml3({ external: entries });
+}
+function sectionList(md, title) {
+  const re = new RegExp(`^##\\s+${title}\\s*$`, "im");
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => re.test(l));
+  if (start < 0) return [];
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    const m = lines[i].match(/^\s*-\s+(.+?)\s*$/);
+    if (m && !/^_.*_$/.test(m[1])) out.push(m[1].trim());
+  }
+  return out;
+}
+function sectionParagraph(md, title) {
+  const re = new RegExp(`^##\\s+${title}\\s*$`, "im");
+  const lines = md.split(/\r?\n/);
+  const start = lines.findIndex((l) => re.test(l));
+  if (start < 0) return "";
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    const t = lines[i].trim();
+    if (t && !/^_.*_$/.test(t)) return t;
+  }
+  return "";
+}
+function parseCapsule(id, path5, md) {
+  const { data } = matter2(md);
+  const updatedAt = data.updated_at ? String(data.updated_at) : void 0;
+  let ageDays = null;
+  if (updatedAt) {
+    const d = Date.parse(updatedAt);
+    if (!Number.isNaN(d)) ageDays = Math.max(0, Math.floor((Date.now() - d) / 864e5));
+  }
+  return {
+    id,
+    path: path5,
+    system: data.system ? String(data.system) : id,
+    owner: data.owner ? String(data.owner) : void 0,
+    updatedAt,
+    purpose: sectionParagraph(md, "Purpose"),
+    capabilities: sectionList(md, "Exposed Capabilities"),
+    contracts: sectionList(md, "Public Contracts"),
+    knownRisks: sectionList(md, "Known Risks"),
+    ageDays
+  };
+}
+function slugId(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "external";
+}
+function addExternalCapsule(dir, sourceFile) {
+  if (!exists(sourceFile)) throw new Error(`Capsule not found: ${sourceFile}`);
+  const raw = readFile(sourceFile);
+  const { data } = matter2(raw);
+  const isCapsuleType = data.type === "knowledge-capsule";
+  const fallbackName = sourceFile.split(/[\\/]/).pop()?.replace(/\.capsule\.md$/, "") ?? "external";
+  const id = slugId(String(data.system ?? fallbackName));
+  const destRel = join("external", `${id}.capsule.md`).replace(/\\/g, "/");
+  writeFile(join(dir, destRel), raw);
+  const entry = {
+    id,
+    type: "knowledge-capsule",
+    path: destRel,
+    owner: data.owner ? String(data.owner) : void 0,
+    lastImportedAt: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+  };
+  const registry = loadExternalRegistry(dir).filter((e) => e.id !== id);
+  registry.push(entry);
+  writeFile(join(dir, EXTERNAL_PATH), serializeExternalRegistry(registry));
+  return { id, destRel, entry, isCapsuleType };
+}
+function loadExternalCapsules(dir) {
+  const out = [];
+  for (const entry of loadExternalRegistry(dir)) {
+    const full = join(dir, entry.path);
+    if (!exists(full) || !isFile(full)) continue;
+    try {
+      out.push(parseCapsule(entry.id, entry.path, readFile(full)));
+    } catch {
+    }
+  }
+  return out;
+}
+
+// src/core/knowledge-discovery.ts
+var KNOWLEDGE2 = "knowledge";
 var CONSOLIDATED_TYPE = {
   Business: "business",
   Product: "product",
@@ -5305,10 +5628,10 @@ function layerForType(type) {
 }
 function layerFromPath(filePath) {
   const p2 = filePath.replace(/\\/g, "/");
-  if (p2.includes(`/${KNOWLEDGE}/business/`)) return "Business";
-  if (p2.includes(`/${KNOWLEDGE}/product/`)) return "Product";
-  if (p2.includes(`/${KNOWLEDGE}/tech/`)) return "Tech";
-  if (p2.includes(`/${KNOWLEDGE}/delivery/`)) return "Delivery";
+  if (p2.includes(`/${KNOWLEDGE2}/business/`)) return "Business";
+  if (p2.includes(`/${KNOWLEDGE2}/product/`)) return "Product";
+  if (p2.includes(`/${KNOWLEDGE2}/tech/`)) return "Tech";
+  if (p2.includes(`/${KNOWLEDGE2}/delivery/`)) return "Delivery";
   return null;
 }
 function basename(p2) {
@@ -5321,7 +5644,7 @@ function discoverLayers(dir) {
     Tech: blank(),
     Delivery: blank()
   };
-  const archDir = join(dir, KNOWLEDGE);
+  const archDir = join(dir, KNOWLEDGE2);
   const artifacts = exists(archDir) ? readArtifacts(archDir) : [];
   for (const a of artifacts) {
     const type = a.type;
@@ -5343,7 +5666,7 @@ function discoverLayers(dir) {
     }
     if (type === "adr" || type === "decision") slot.hasDecision = true;
   }
-  if (existsDirWithMd(join(dir, KNOWLEDGE, "tech", "decisions"))) acc.Tech.structured = true;
+  if (existsDirWithMd(join(dir, KNOWLEDGE2, "tech", "decisions"))) acc.Tech.structured = true;
   return ["Business", "Product", "Tech", "Delivery"].map((layer2) => ({
     layer: layer2,
     status: statusFor(layer2, acc[layer2]),
@@ -5591,6 +5914,7 @@ function buildProjectExplanation(dir) {
     ownership,
     domains,
     duplicateWorkItems,
+    externalCapsules: loadExternalCapsules(dir),
     layers,
     roadmap,
     mappedModules,
@@ -5719,6 +6043,17 @@ function renderExplanationHuman(exp) {
     lines.push("- Mapped modules: 0");
     lines.push("");
   }
+  if (exp.externalCapsules.length > 0) {
+    lines.push(`## External Knowledge Capsules: ${exp.externalCapsules.length}`);
+    for (const cap of exp.externalCapsules) {
+      const owner = cap.owner ? ` \u2014 owner: ${cap.owner}` : "";
+      lines.push(`- ${cap.system}${owner}`);
+      if (cap.ageDays !== null && cap.ageDays >= 90) {
+        lines.push(`  \u26A0 capsule last updated ${cap.ageDays} days ago \u2014 it may be stale.`);
+      }
+    }
+    lines.push("");
+  }
   if (exp.missingKnowledge.length > 0) {
     lines.push("## Missing Knowledge");
     for (const m of exp.missingKnowledge) lines.push(`- ${m}`);
@@ -5762,7 +6097,7 @@ function readKnowledge(dir) {
   if (!exists(knowledgePath)) return null;
   try {
     const raw = readFile(knowledgePath);
-    const { data, content } = matter2(raw);
+    const { data, content } = matter3(raw);
     return { content, data };
   } catch {
     return null;
@@ -5773,7 +6108,7 @@ function readRoadmap(dir) {
   if (!exists(roadmapPath)) return null;
   try {
     const raw = readFile(roadmapPath);
-    const { content } = matter2(raw);
+    const { content } = matter3(raw);
     return content.trim();
   } catch {
     return null;
@@ -5783,7 +6118,7 @@ function readConfig(dir) {
   const configPath = join(dir, CONFIG_PATH3);
   if (!exists(configPath)) return {};
   try {
-    return parseYaml8(readFile(configPath));
+    return parseYaml9(readFile(configPath));
   } catch {
     return {};
   }
@@ -5869,8 +6204,8 @@ function explainForAgent(dir, artifacts, opts) {
     since: opts.since ?? null
   };
   if (knowledge) {
-    const firstParagraph2 = knowledge.content.trim().split("\n\n").find((p2) => p2.trim() && !p2.startsWith("#"));
-    output.knowledge_summary = firstParagraph2?.trim() ?? "";
+    const firstParagraph3 = knowledge.content.trim().split("\n\n").find((p2) => p2.trim() && !p2.startsWith("#"));
+    output.knowledge_summary = firstParagraph3?.trim() ?? "";
   }
   const mappedArtifacts = artifacts.filter((a) => a.type !== "current-state" && a.type !== "roadmap").map((a) => ({
     id: a.id,
@@ -5942,7 +6277,7 @@ function runExplain(opts) {
 }
 
 // src/core/context-pack.ts
-import matter3 from "gray-matter";
+import matter4 from "gray-matter";
 var CONTEXT_PACK_VERSION = "1";
 var ARCH_DIR6 = "knowledge";
 function readScanJson(dir) {
@@ -5954,8 +6289,8 @@ function readScanJson(dir) {
     return null;
   }
 }
-function firstParagraph(markdown) {
-  const body = matter3(markdown).content.trim();
+function firstParagraph2(markdown) {
+  const body = matter4(markdown).content.trim();
   const para = body.split("\n\n").map((p2) => p2.trim()).find((p2) => p2 && !p2.startsWith("#"));
   return para ?? "";
 }
@@ -5963,7 +6298,7 @@ function readMarkdownSummary(dir, file) {
   const p2 = join(dir, ARCH_DIR6, file);
   if (!exists(p2)) return null;
   try {
-    return firstParagraph(readFile(p2));
+    return firstParagraph2(readFile(p2));
   } catch {
     return null;
   }
@@ -6125,6 +6460,7 @@ function buildContextPack(dir, config, now = /* @__PURE__ */ new Date()) {
     roadmap,
     phase,
     deliveryMix,
+    external: loadExternalCapsules(dir),
     mappedModules,
     missing,
     // VS-052: the handoff is driven by the REAL phase, not project.state, so the pack never
@@ -6275,6 +6611,21 @@ function renderContextPack(pack) {
       "Note: Kaddo does not scan secondary repositories during `context`. Mapped modules come from `.kaddo/modules.yml` and module artifacts only.\n"
     );
   }
+  if (pack.external.length > 0) {
+    parts.push("## External Knowledge\n");
+    parts.push(
+      "Imported Knowledge Capsules \u2014 minimal context about external systems (not their source).\n"
+    );
+    for (const cap of pack.external) {
+      const lines = [`### ${cap.system}`, ""];
+      if (cap.purpose) lines.push(`- Purpose: ${cap.purpose}`);
+      if (cap.capabilities.length) lines.push(`- Capabilities: ${cap.capabilities.join(", ")}`);
+      if (cap.contracts.length) lines.push(`- Contracts: ${cap.contracts.join(", ")}`);
+      if (cap.owner) lines.push(`- Owner: ${cap.owner}`);
+      if (cap.knownRisks.length) lines.push(`- Known risks: ${cap.knownRisks.join("; ")}`);
+      parts.push(lines.join("\n") + "\n");
+    }
+  }
   parts.push("## Missing Context\n");
   if (missing.length > 0) {
     parts.push(missing.map((m) => `- ${m}`).join("\n") + "\n");
@@ -6490,7 +6841,7 @@ function renderUnderstandTerminal(plan) {
 }
 
 // src/core/delivery.ts
-import { parse as parseYaml9 } from "yaml";
+import { parse as parseYaml10 } from "yaml";
 function slugify2(s) {
   return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -6596,6 +6947,14 @@ function runUnderstand() {
   if (assessment.nextStep) {
     console.log(`Next step: ${assessment.nextStep}`);
   }
+  if (exp.externalCapsules.length > 0) {
+    console.log("");
+    console.log("External knowledge:");
+    for (const cap of exp.externalCapsules) {
+      console.log(`  - ${cap.system}${cap.owner ? ` (owner: ${cap.owner})` : ""}`);
+    }
+    console.log("  \u2192 Review the relevant capsule before changing integration behavior with it.");
+  }
   const active = activeWorkItems(dir);
   if (active.length > 0) {
     console.log("");
@@ -6829,14 +7188,14 @@ async function runClassify(opts = {}) {
 }
 
 // src/commands/status.ts
-import { parse as parseYaml10 } from "yaml";
+import { parse as parseYaml11 } from "yaml";
 var ARCH_DIR8 = "knowledge";
 var CONFIG_PATH4 = ".kaddo/config.yml";
 function loadConfig3(dir) {
   const p2 = join(dir, CONFIG_PATH4);
   if (!exists(p2)) return {};
   try {
-    return parseYaml10(readFile(p2));
+    return parseYaml11(readFile(p2));
   } catch {
     return {};
   }
@@ -6893,7 +7252,7 @@ function runStatus() {
 }
 
 // src/commands/learn.ts
-import matter4 from "gray-matter";
+import matter5 from "gray-matter";
 var ARCH_DIR9 = "knowledge";
 var WORK_ITEMS_DIR2 = "knowledge/delivery/work-items";
 function findWorkItemFile(dir, id) {
@@ -6905,7 +7264,7 @@ function findWorkItemFile(dir, id) {
 }
 function updateWorkItemFile(filePath, learning) {
   const raw = readFile(filePath);
-  const { data, content } = matter4(raw);
+  const { data, content } = matter5(raw);
   data.status = "done";
   data.completed_at = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
   let updatedContent = content;
@@ -6930,7 +7289,7 @@ ${learning.trim()}
 ${learning.trim()}
 `;
   }
-  const newRaw = matter4.stringify(updatedContent, data);
+  const newRaw = matter5.stringify(updatedContent, data);
   writeFile(filePath, newRaw);
 }
 async function runLearn(artifactId) {
@@ -7038,13 +7397,13 @@ function runHistory(opts = {}) {
 }
 
 // src/commands/add.ts
-import { parse as parseYaml11, stringify as stringifyYaml3 } from "yaml";
+import { parse as parseYaml12, stringify as stringifyYaml4 } from "yaml";
 var CONFIG_PATH5 = ".kaddo/config.yml";
 function readProjectState(dir) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return void 0;
   try {
-    const config = parseYaml11(readFile(configPath));
+    const config = parseYaml12(readFile(configPath));
     return config.project?.state;
   } catch {
     return void 0;
@@ -7062,12 +7421,12 @@ function markModuleInstalled(dir, configKey, moduleName) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return;
   try {
-    const config = parseYaml11(readFile(configPath));
+    const config = parseYaml12(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, stringifyYaml3(config));
+    writeFile(configPath, stringifyYaml4(config));
   } catch {
   }
 }
@@ -7075,7 +7434,7 @@ function isModuleInstalled(dir, configKey) {
   const configPath = join(dir, CONFIG_PATH5);
   if (!exists(configPath)) return false;
   try {
-    const config = parseYaml11(readFile(configPath));
+    const config = parseYaml12(readFile(configPath));
     const moduleConfig = config[configKey];
     return moduleConfig?.installed === true;
   } catch {
@@ -7158,7 +7517,7 @@ function runAdd(moduleName, opts = {}, dir = cwd()) {
 }
 
 // src/core/ownership-suggest.ts
-import matter5 from "gray-matter";
+import matter6 from "gray-matter";
 var SCAN_PATH = ".kaddo/scan.json";
 function normalizeGlob(input) {
   let g = input.trim().replace(/\\/g, "/");
@@ -7280,11 +7639,11 @@ function suggestGlobs(artifact, signals) {
   return [...new Set(out)];
 }
 function applyOwnership(raw, globs, mode = "replace") {
-  const parsed = matter5(raw);
+  const parsed = matter6(raw);
   const existing = toStringArray3(parsed.data.code);
   const next = mode === "append" ? [.../* @__PURE__ */ new Set([...existing, ...globs])] : [...new Set(globs)];
   const data = { ...parsed.data, code: next };
-  return matter5.stringify(parsed.content, data);
+  return matter6.stringify(parsed.content, data);
 }
 
 // src/commands/owners.ts
@@ -7458,19 +7817,19 @@ ${globs.map((g) => `  - ${g}`).join("\n")}`);
 }
 
 // src/commands/module-descriptor.ts
-import { parse as parseYaml12, stringify as stringifyYaml4 } from "yaml";
+import { parse as parseYaml13, stringify as stringifyYaml5 } from "yaml";
 var DESCRIPTOR_PATH2 = "knowledge/module.yml";
 function readDescriptor(dir) {
   const path5 = join(dir, DESCRIPTOR_PATH2);
   if (!exists(path5)) return null;
   try {
-    return parseYaml12(readFile(path5));
+    return parseYaml13(readFile(path5));
   } catch {
     return null;
   }
 }
 function writeDescriptor(dir, descriptor) {
-  writeFile(join(dir, DESCRIPTOR_PATH2), stringifyYaml4(descriptor));
+  writeFile(join(dir, DESCRIPTOR_PATH2), stringifyYaml5(descriptor));
 }
 async function runModuleDescriptor(opts) {
   const dir = cwd();
@@ -7565,7 +7924,7 @@ function printDescriptor(d) {
 }
 
 // src/commands/modules-map.ts
-import { parse as parseYaml13, stringify as stringifyYaml5 } from "yaml";
+import { parse as parseYaml14, stringify as stringifyYaml6 } from "yaml";
 
 // src/templates/registry.ts
 var QUALITY = "## Quality checklist";
@@ -7708,7 +8067,7 @@ ${QUALITY}
 - [ ] Capabilities describe outcomes, not implementation.
 - [ ] Each capability cites evidence or is flagged as an assumption.
 `;
-var KNOWLEDGE2 = `---
+var KNOWLEDGE3 = `---
 type: current-state
 updated_at: YYYY-MM-DD
 ---
@@ -8718,7 +9077,7 @@ var KADDO_TEMPLATES = [
     description: "What is true about the product right now.",
     whenToUse: "Created by `kaddo init`; keep it current as the product evolves.",
     relatedCommand: "kaddo init",
-    content: KNOWLEDGE2
+    content: KNOWLEDGE3
   },
   // business / product (bootstrap — consolidated, minimal)
   {
@@ -9072,14 +9431,14 @@ function readModulesDescriptor(dir) {
   const path5 = join(dir, DESCRIPTOR_PATH3);
   if (!exists(path5)) return { version: 1, modules: [] };
   try {
-    const parsed = parseYaml13(readFile(path5));
+    const parsed = parseYaml14(readFile(path5));
     return { version: parsed.version ?? 1, modules: parsed.modules ?? [] };
   } catch {
     return { version: 1, modules: [] };
   }
 }
 function writeModulesDescriptor(dir, descriptor) {
-  writeFile(join(dir, DESCRIPTOR_PATH3), stringifyYaml5(descriptor));
+  writeFile(join(dir, DESCRIPTOR_PATH3), stringifyYaml6(descriptor));
 }
 function moduleDir(id) {
   return `knowledge/tech/modules/${id}`;
@@ -9369,6 +9728,51 @@ async function runBootstrap(dir = cwd()) {
   );
 }
 
+// src/commands/capsule.ts
+function slug(s) {
+  return s.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+function runCapsuleExport() {
+  const dir = cwd();
+  const config = requireConfig(dir);
+  intro2("kaddo capsule export");
+  const capsule = buildCapsule(dir, config);
+  const name = slug(config.project.name);
+  const mdPath = join(".kaddo", "exports", `${name}.capsule.md`);
+  const jsonPath = join(".kaddo", "exports", `${name}.capsule.json`);
+  writeFile(join(dir, mdPath), renderCapsuleMarkdown(capsule));
+  writeFile(join(dir, jsonPath), serializeCapsuleJson(capsule));
+  log2.success(`Wrote ${mdPath}`);
+  log2.success(`Wrote ${jsonPath}`);
+  log2.info("Refine it with the capsule-agent before sharing \u2014 and never include secrets or source code.");
+  printCommandFooter("capsule export");
+  outro2("Knowledge Capsule exported.");
+}
+function runCapsuleAdd(srcPath) {
+  const dir = cwd();
+  requireConfig(dir);
+  intro2("kaddo capsule add");
+  if (!srcPath) {
+    console.error("Usage: kaddo capsule add <path-to-capsule.md>");
+    process.exit(1);
+  }
+  const abs = join(dir, srcPath);
+  const source = exists(abs) ? abs : srcPath;
+  if (!exists(source)) {
+    console.error(`Capsule not found: ${srcPath}`);
+    process.exit(1);
+  }
+  const result = addExternalCapsule(dir, source);
+  if (!result.isCapsuleType) {
+    log2.warn("This file is not marked as a knowledge-capsule (front matter `type: knowledge-capsule`).");
+  }
+  log2.success(`Imported capsule "${result.id}" \u2192 ${result.destRel}`);
+  log2.success("Registered in .kaddo/external.yml");
+  log2.info('Run `kaddo context` \u2014 the pack now includes an "External Knowledge" section.');
+  printCommandFooter("capsule add");
+  outro2("External capsule registered.");
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -9386,6 +9790,13 @@ program.command("bootstrap").description("Build the initial knowledge base for a
 program.command("create [type]").description("Create a work item (feature, bugfix, hotfix, spike, chore). Use --from roadmap to create from a roadmap candidate.").option("--from <source>", "Create from a source artifact (currently: roadmap)").action(async (type, opts) => {
   await runCreate(type ?? "", opts);
 });
+var capsuleCmd = program.command("capsule").description("Export this project as a Knowledge Capsule, or import an external one as context");
+capsuleCmd.command("export").description("Write a Knowledge Capsule about this project to .kaddo/exports/").action(() => {
+  runCapsuleExport();
+});
+capsuleCmd.command("add <path>").description("Register an external Knowledge Capsule as project context (.kaddo/external.yml)").action((path5) => {
+  runCapsuleAdd(path5);
+});
 program.command("guard").description("Check if modified code has related artifacts that were not updated").option("--staged", "Check only staged files").option("--no-interactive", "Disable interactive ignore prompts").option("--ci", "CI mode: output JSON, no prompts, non-blocking").option("--json", "Output JSON (alias for --ci)").option("--workspace", "Also check local mapped module repos from .kaddo/modules.yml (opt-in)").action(async (opts) => {
   await runGuard(opts);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaddo/cli",
-  "version": "3.15.0",
+  "version": "3.16.1",
   "description": "Knowledge Driven Development toolkit",
   "license": "MIT",
   "repository": {