@kage-core/kage-graph-mcp 2.2.7 → 2.3.1

package/dist/cli.js

@@ -32,7 +32,7 @@ const FULL_USAGE = `Kage — full command reference
 
 Usage:
   kage index --project <dir>
-  kage scan --project <dir> [--json]
+  kage scan --project <dir> [--json] [--scorecard [--out <file>]]
   kage demo [--project <dir>]
   kage install [--project <dir>] [--agents a,b] [--no-agents] [--json]
   kage init --project <dir> [--with-policy]
@@ -71,12 +71,15 @@ Usage:
   kage slots set --project <dir> --label <label> --content <text> [--description <text>] [--paths a,b] [--tags a,b] [--size-limit <n>] [--unpinned] [--json]
   kage slots delete --project <dir> --label <label> [--json]
   kage handoff --project <dir> [--json]
+  kage layers --project <dir> [--json]
   kage lifecycle --project <dir> [--json]
   kage reverify --project <dir> --packet <id> [--json]
   kage reconcile --project <dir> [--session <id>] [--json]
   kage timeline --project <dir> [--days <n>] [--json]
   kage lineage --project <dir> [--json]
   kage supersede --project <dir> --packet <old-id> --replacement <new-id> [--reason <text>] [--json]
+  kage conflicts --project <dir> [--json]
+  kage skills --project <dir> [--dir <path>] [--dry-run] [--json]
   kage contributors --project <dir> [--json]
   kage profile --project <dir> [--json]
   kage xray --project <dir> [--json]
@@ -108,7 +111,8 @@ Usage:
   kage graph "<query>" --project <dir> [--json]
   kage graph-registry --project <dir> [--json]
   kage embeddings build --project <dir> [--model Xenova/all-MiniLM-L6-v2] [--json]
-  kage recall "<query>" --project <dir> [--json] [--explain] [--embeddings] [--max-context-tokens <n>] [--structural-hops <n>]
+  kage recall "<query>" --project <dir> [--json] [--explain] [--embeddings] [--docs] [--max-context-tokens <n>] [--structural-hops <n>]
+  kage docs-search "<query>" --project <dir> [--limit <n>] [--json]   search this repo's own committed docs (README, docs/**, *.md)
   kage file-context --project <dir> --path <file> [--json]
   kage observe --project <dir> --event <json>
   kage sessions --project <dir> [--json]
@@ -166,6 +170,15 @@ function numberArg(args, name, fallback) {
     const value = takeArg(args, name);
     return value ? Number(value) : fallback;
 }
+function printContradictionWarning(contradictions) {
+    if (!contradictions?.length)
+        return;
+    console.log(`\n⚠ This contradicts ${contradictions.length} existing memor${contradictions.length === 1 ? "y" : "ies"}:`);
+    for (const item of contradictions) {
+        console.log(`  - ${item.packet_id} (${item.title}): ${item.reason}`);
+    }
+    console.log("  Resolve with kage supersede --packet <old> --replacement <new>, or keep both intentionally.");
+}
 function firstPositional(args) {
     return args.find((arg, index) => index > 0 && !arg.startsWith("--") && !args[index - 1]?.startsWith("--"));
 }
@@ -306,15 +319,30 @@ async function main() {
             console.log(JSON.stringify(result, null, 2));
             return;
         }
+        if (args.includes("--scorecard")) {
+            // A shareable artifact, not terminal output: write the SVG (or Markdown if
+            // --out ends in .md) and echo the Markdown table so it's pasteable now.
+            const out = takeArg(args, "--out");
+            const asMarkdown = out ? out.toLowerCase().endsWith(".md") : false;
+            const outPath = out ?? (0, node_path_1.join)(scanTarget, "kage-scorecard.svg");
+            (0, node_fs_1.writeFileSync)(outPath, asMarkdown ? (0, kernel_js_1.truthScorecardMarkdown)(result) : (0, kernel_js_1.truthScorecardSvg)(result), "utf8");
+            console.log(`Scorecard written to ${outPath}`);
+            console.log("Share it: embed the SVG in a README, screenshot it, or post it.\n");
+            console.log((0, kernel_js_1.truthScorecardMarkdown)(result));
+            return;
+        }
         console.log(`Kage Truth Report — ${result.project_dir}`);
         console.log(`Scanned ${result.totals.files_scanned} files, ${result.totals.symbols_scanned} symbols${result.totals.docs_scanned ? `, ${result.totals.docs_scanned} doc file(s)` : ""}\n`);
-        console.log(`  ${result.headline}\n`);
+        console.log(result.headline ? `  ${result.headline}\n` : "");
         const sections = [
-            { kind: "duplicate_cluster", heading: "DUPLICATE IMPLEMENTATIONS", count: result.totals.duplicate_clusters },
-            { kind: "ghost_export", heading: "GHOST KNOWLEDGE — exported, never called", count: result.totals.ghost_exports },
-            { kind: "bus_factor", heading: "BUS FACTOR 1 — one head holds it all", count: result.totals.bus_factor_files },
-            { kind: "knowledge_void", heading: "KNOWLEDGE VOID — high churn, zero memory", count: result.totals.knowledge_voids },
-            { kind: "doc_lie", heading: "DOC LIES — the README vs reality", count: result.totals.doc_lies },
+            { kind: "knowledge_void", heading: "KNOWLEDGE VOID — high churn, zero memory", clean: "no undocumented hot files", count: result.totals.knowledge_voids },
+            { kind: "untested_hot", heading: "UNTESTED HOT PATH — depended on, no test covers it", clean: "every hot path has a test", count: result.totals.untested_hot_paths },
+            { kind: "complexity_hotspot", heading: "COMPLEXITY HOTSPOT — big file, many dependents", clean: "no oversized hub files", count: result.totals.complexity_hotspots },
+            { kind: "debt_marker", heading: "KNOWN DEBT — TODO / FIXME / HACK left in code", clean: "no debt markers in code", count: result.totals.debt_markers },
+            { kind: "bus_factor", heading: "BUS FACTOR 1 — one head holds it all", clean: "no single-owner hot files", count: result.totals.bus_factor_files },
+            { kind: "duplicate_cluster", heading: "DUPLICATE IMPLEMENTATIONS", clean: "no duplicate implementations", count: result.totals.duplicate_clusters },
+            { kind: "ghost_export", heading: "GHOST KNOWLEDGE — exported, never called", clean: "no dead exports", count: result.totals.ghost_exports },
+            { kind: "doc_lie", heading: "DOC LIES — the README vs reality", clean: "docs match the code", count: result.totals.doc_lies },
         ];
         for (const section of sections) {
             const items = result.findings.filter((finding) => finding.kind === section.kind);
@@ -329,6 +357,14 @@ async function main() {
             }
             console.log("");
         }
+        // Reframe the categories that came back clean as reassurance, not emptiness.
+        // (doc checks only run when docs exist, so skip that line when none scanned.)
+        const cleanLabels = sections
+            .filter((section) => section.count === 0 && !(section.kind === "doc_lie" && !result.totals.docs_scanned))
+            .map((section) => section.clean);
+        if (result.findings.length && cleanLabels.length) {
+            console.log(`Clean: ${cleanLabels.join(" · ")}\n`);
+        }
         if (!result.findings.length) {
             const small = result.totals.files_scanned < 30;
             const noGit = result.warnings.some((warning) => warning.includes("Git history"));
@@ -454,6 +490,11 @@ async function main() {
             : null;
         const detected = requested ?? probes.filter((p) => p.paths.some((path) => (0, node_fs_1.existsSync)(path))).map((p) => p.agent);
         const init = (0, kernel_js_1.initProject)(project, { policy: false });
+        // Always write the repo policy (AGENTS.md + CLAUDE.md) — it is what instructs
+        // agents to use Kage and it travels with the repo, so teammates who clone are
+        // covered even before they wire their own agent. Decoupled from agent detection:
+        // a machine where no agent is auto-detected must still commit the policy.
+        const policy = (0, kernel_js_1.installAgentPolicy)(project);
         const wired = [];
         if (!skipAgents) {
             for (const agent of detected) {
@@ -475,6 +516,7 @@ async function main() {
         console.log(`Kage installed in ${init.index.projectDir}\n`);
         console.log("  Memory      .agent_memory/ created — packets are plain files, reviewable in git");
         console.log(`  Indexes     ${init.index.indexes.length} built (code graph, recall, structure)`);
+        console.log(`  Policy      AGENTS.md + CLAUDE.md ${policy.created ? "written" : policy.updated ? "updated" : "current"} — commit these so every teammate's agent uses Kage`);
         if (skipAgents) {
             console.log("  Agents      skipped (--no-agents)");
         }
@@ -489,13 +531,27 @@ async function main() {
                     console.log(`  Agents      ${w.agent} ✗ ${w.error ?? "print-only; run kage setup " + w.agent + " --project . --write"}`);
             }
         }
-        console.log("\nNext:");
-        console.log("  restart your agent — memory now recalls automatically at session start");
-        console.log("  kage scan --project .      60-second Truth Report on this repo");
-        console.log("  kage viewer --project .    local dashboard (gains, packets, graph)");
-        console.log("\nVersion control: commit .agent_memory/packets/, ignore .agent_memory/indexes/ and reports/.");
-        console.log("Enable the packet merge driver once per clone:");
-        console.log(`  ${kernel_js_1.PACKET_MERGE_DRIVER_CONFIG}`);
+        // Do the version-control housekeeping instead of telling the user to. Both are
+        // idempotent and safe to skip if this isn't a git repo.
+        let vcDone = false;
+        try {
+            const gitignorePath = (0, node_path_1.join)(project, ".gitignore");
+            const want = [".agent_memory/indexes/", ".agent_memory/reports/"];
+            const current = (0, node_fs_1.existsSync)(gitignorePath) ? (0, node_fs_1.readFileSync)(gitignorePath, "utf8") : "";
+            const missing = want.filter((line) => !current.split("\n").some((l) => l.trim() === line));
+            if (missing.length) {
+                const prefix = current && !current.endsWith("\n") ? "\n" : "";
+                (0, node_fs_1.writeFileSync)(gitignorePath, `${current}${prefix}${current ? "" : "# Kage: regenerated, not committed\n"}${missing.join("\n")}\n`, "utf8");
+            }
+            (0, node_child_process_1.execFileSync)("git", ["-C", project, "config", "merge.kage-packet.driver", "npx -y @kage-core/kage-graph-mcp merge-packet %A %O %B"], { stdio: "ignore" });
+            vcDone = true;
+        }
+        catch { /* not a git repo or no git — fall back to a hint */ }
+        console.log(`  Git         ${vcDone ? ".gitignore + packet merge driver configured" : "skipped (not a git repo)"}`);
+        console.log("\nNext:  restart your agent — Kage then recalls automatically every session.");
+        console.log("       kage scan      a 60-second Truth Report on this repo");
+        if (!vcDone)
+            console.log(`\nWhen this becomes a git repo, run once: ${kernel_js_1.PACKET_MERGE_DRIVER_CONFIG}`);
         if (!init.validation.ok)
             process.exit(2);
         return;
@@ -1294,7 +1350,13 @@ async function main() {
         const plural = (count, singular, pluralForm) => (count === 1 ? singular : pluralForm);
         const week = summary.last_7d;
         if (!summary.all_time.recalls && !summary.all_time.stale_withheld && !summary.all_time.stale_caught && !summary.all_time.caller_answers) {
-            console.log("No value events recorded yet. Run kage recall (or let your agent call kage_context) and check back.");
+            console.log("No value events recorded yet — this ledger fills up as your agent works.");
+            console.log("Every recall logs the tokens it saved (by not re-reading cited files) and every");
+            console.log("stale memory it withheld. Come back after a session and you'll see a receipt here.\n");
+            console.log("Start now:");
+            console.log("  kage scan --project .                  a 60-second Truth Report on this repo");
+            console.log("  kage scan --project . --scorecard      a shareable scorecard you can post");
+            console.log("  then just work — your agent captures and recalls, verified against this code.");
             return;
         }
         console.log(`This week Kage saved you ~${(0, kernel_js_1.formatTokenCount)(week.tokens_saved)} tokens (~$${week.estimated_dollars.toFixed(2)}), ` +
@@ -1363,6 +1425,21 @@ async function main() {
         }
         return;
     }
+    if (command === "layers" || command === "memory-layers") {
+        const result = (0, kernel_js_1.kageLayers)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log("Kage memory layers");
+        for (const layer of result.layers) {
+            console.log(`  ${layer.layer} ${layer.label} (${layer.count})`);
+            console.log(`     ${layer.description}`);
+            for (const ex of layer.examples)
+                console.log(`     · ${ex}`);
+        }
+        return;
+    }
     if (command === "lifecycle" || command === "memory-lifecycle") {
         const result = (0, kernel_js_1.kageMemoryLifecycle)(projectArg(args));
         if (args.includes("--json")) {
@@ -1402,6 +1479,36 @@ async function main() {
             process.exit(2);
         return;
     }
+    if (command === "skills" || command === "skills-build") {
+        const result = (0, kernel_js_1.generateSkills)(projectArg(args), {
+            dryRun: args.includes("--dry-run"),
+            dir: takeArg(args, "--dir"),
+        });
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            const verb = result.dry_run ? "Would generate" : "Generated";
+            console.log(`Kage skills: ${verb} ${result.generated.length} skill file(s) in ${result.dir}/ from verified memory`);
+            for (const skill of result.generated)
+                console.log(`  ${result.dry_run ? "·" : "✓"} ${skill.path}  (${skill.type})`);
+            if (result.skipped.length)
+                console.log(`  skipped ${result.skipped.length} packet(s) not skill-worthy or not grounded`);
+            if (result.errors.length)
+                console.log(`  errors: ${result.errors.join("; ")}`);
+            if (!result.dry_run && result.generated.length) {
+                if (result.git_ignored) {
+                    console.log(`\n⚠ ${result.dir}/ is git-ignored, so these skills won't reach your team. Un-ignore it (or run with --dir <tracked-path>) and commit them.`);
+                }
+                else {
+                    console.log(`\nThese are plain files in ${result.dir}/ — commit them so every teammate's agent loads the same skills.`);
+                }
+            }
+        }
+        if (!result.ok)
+            process.exit(2);
+        return;
+    }
     if (command === "reconcile" || command === "memory-reconcile" || command === "memory-reconciliation") {
         const result = (0, kernel_js_1.kageMemoryReconciliation)(projectArg(args), {
             sessionId: takeArg(args, "--session"),
@@ -1604,6 +1711,27 @@ async function main() {
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         return;
     }
+    if (command === "conflicts") {
+        const result = (0, kernel_js_1.kageConflicts)(projectArg(args));
+        if (args.includes("--json")) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        if (!result.count) {
+            console.log("Memory conflicts: none — no contradicting packet pairs found.");
+            return;
+        }
+        console.log(`Memory conflicts: ${result.count} contradicting packet pair${result.count === 1 ? "" : "s"}`);
+        for (const pair of result.pairs) {
+            console.log(`\n  ⚠ ${pair.a.title}  <-->  ${pair.b.title}`);
+            console.log(`    ${pair.a.id}`);
+            console.log(`    ${pair.b.id}`);
+            console.log(`    shared paths: ${pair.shared_paths.join(", ")}`);
+            console.log(`    ${pair.reason}`);
+        }
+        console.log("\nResolve each with: kage supersede --packet <old> --replacement <new>");
+        return;
+    }
     if (command === "module-health") {
         const result = (0, kernel_js_1.kageModuleHealth)(projectArg(args));
         if (args.includes("--json")) {
@@ -1918,6 +2046,7 @@ async function main() {
             graphNodes: listArg(takeArg(args, "--graph-nodes")),
             allowMissingPaths: args.includes("--allow-missing-paths"),
             strictCitations: true,
+            strictContradictions: args.includes("--strict-contradictions"),
             discoveryTokens: args.includes("--discovery-tokens") ? numberArg(args, "--discovery-tokens", 0) : undefined,
         });
         if (!result.ok) {
@@ -1925,6 +2054,7 @@ async function main() {
             process.exit(2);
         }
         console.log(`Captured ${personal ? "personal" : "session"} learning: ${result.path}`);
+        printContradictionWarning(result.contradictions);
         if (result.warnings?.length)
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         console.log(personal
@@ -2003,6 +2133,11 @@ async function main() {
         const result = args.includes("--embeddings")
             ? await (0, kernel_js_1.recallWithEmbeddings)(projectArg(args), query, 5, args.includes("--explain"))
             : (0, kernel_js_1.recall)(projectArg(args), query, 5, args.includes("--explain"), { maxContextTokens, structuralHops });
+        if (args.includes("--docs")) {
+            const docsSection = (0, kernel_js_1.docsRecallSection)(projectArg(args), query, 3);
+            if (docsSection)
+                result.context_block = `${result.context_block}\n\n${docsSection}`;
+        }
         if (args.includes("--json"))
             console.log(JSON.stringify(result, null, 2));
         else {
@@ -2034,6 +2169,27 @@ async function main() {
         console.log(`Packets: ${result.packet_count}`);
         return;
     }
+    if (command === "docs-search") {
+        const query = firstPositional(args);
+        if (!query)
+            usage();
+        const limit = numberArg(args, "--limit", 5);
+        const hits = (0, kernel_js_1.searchDocs)(projectArg(args), query, limit);
+        if (args.includes("--json")) {
+            console.log(JSON.stringify({ query, source: "repo-docs", hits }, null, 2));
+            return;
+        }
+        if (!hits.length) {
+            console.log("No matching docs found in this repo's own committed documentation.");
+            return;
+        }
+        console.log(`Docs search (this repo's own committed documentation) — "${query}":`);
+        for (const hit of hits) {
+            console.log(`\n${hit.doc_path}:${hit.line}  [${hit.score}]  ${hit.heading}`);
+            console.log(`  ${hit.snippet}`);
+        }
+        return;
+    }
     if (command === "observe") {
         const event = takeArg(args, "--event");
         if (!event)
@@ -2173,6 +2329,7 @@ async function main() {
             graphNodes: listArg(takeArg(args, "--graph-nodes")),
             allowMissingPaths: args.includes("--allow-missing-paths"),
             strictCitations: true,
+            strictContradictions: args.includes("--strict-contradictions"),
         };
         const result = (0, kernel_js_1.capture)(input);
         if (!result.ok) {
@@ -2180,6 +2337,7 @@ async function main() {
             process.exit(2);
         }
         console.log(`Captured repo-local packet: ${result.path}`);
+        printContradictionWarning(result.contradictions);
         if (result.warnings?.length)
             console.log(`Warnings:\n${result.warnings.map((warning) => `  - ${warning}`).join("\n")}`);
         console.log("Repo-local memory is written immediately. Promotion to org/global still requires explicit review.");

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORE_TOOLS = void 0;
 exports.listTools = listTools;
 exports.callTool = callTool;
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
@@ -84,14 +85,35 @@ const KAGE_WORKFLOW_TEXT = "Kage memory workflow (this tool performs no action;
     "4) After meaningful file changes, call kage_refresh so indexes, graphs, and stale-memory checks stay current. " +
     "5) Before finishing a branch, call kage_pr_summarize then kage_pr_check. " +
     "Recall receipts show estimated tokens saved versus rediscovery; report memory quality with kage_feedback (helpful/wrong/stale).";
+// Agent-facing core: the verbs an agent actually uses in the loop (recall,
+// capture, stay-honest, refresh, codify). Everything else is operator/diagnostic
+// and must not bloat the model's default tool list — it stays reachable in full
+// mode (KAGE_TOOLS=full) or via the CLI. Keeping the default small enough that
+// the client always-loads it removes the per-call ToolSearch round-trip.
+exports.CORE_TOOLS = new Set([
+    "kage_context",
+    "kage_learn",
+    "kage_supersede",
+    "kage_feedback",
+    "kage_pr_check",
+    "kage_refresh",
+    "kage_skills",
+    // Promoted after the agent-trajectory eval showed a real agent reaches for
+    // these on natural tasks (risk before a change, listing decisions, tracing a
+    // dependency path, searching the repo's own docs).
+    "kage_risk",
+    "kage_decisions",
+    "kage_dependency_path",
+    "kage_docs_search",
+]);
 function listTools() {
-    return [
+    const all = [
         {
             // Combined entry-point tool: validate + recall + code_graph + graph in one call.
             // Agents should load this schema first (one ToolSearch) instead of loading four
             // separate deferred schemas. Cuts session start from 4 schema loads to 1.
             name: "kage_context",
-            description: "Primary kage entry point. Validates memory health, recalls relevant packets, and queries both the code graph and knowledge graph — all in one call. Call this at the start of every task instead of calling kage_validate, kage_recall, kage_code_graph, and kage_graph separately.",
+            description: "Primary kage entry point. Validates memory health, recalls relevant packets, and queries both the code graph and knowledge graph — all in one call. Call this at the start of every task; it answers caller/usage questions from the code graph too, so you rarely need a separate graph tool.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -160,6 +182,7 @@ function listTools() {
                     limit: { type: "number" },
                     explain: { type: "boolean" },
                     embeddings: { type: "boolean" },
+                    docs: { type: "boolean", description: "If true, append a Docs section (<=3 hits) drawn from this repo's own committed documentation." },
                     json: { type: "boolean" },
                     max_context_tokens: { type: "number" },
                     structural_hops: { type: "number", description: "If >0, append a bounded N-hop code-graph blast radius seeded from the recalled memory's files." },
@@ -192,20 +215,6 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
-        {
-            name: "kage_code_graph",
-            description: "Query the source-derived codebase graph: files, symbols, imports, calls, routes, tests, package scripts. This is generated from code, not learned memory.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project_dir: { type: "string" },
-                    query: { type: "string" },
-                    limit: { type: "number" },
-                    json: { type: "boolean" },
-                },
-                required: ["project_dir"],
-            },
-        },
         {
             name: "kage_risk",
             description: "Assess modification risk for files using Kage's code graph plus local git history: dependents, impact surface, churn, ownership, co-change partners, and test gaps. Use before editing hotspot or shared files.",
@@ -374,6 +383,19 @@ function listTools() {
                 required: ["project_dir"],
             },
         },
+        {
+            name: "kage_docs_search",
+            description: "Search this repo's OWN committed documentation (README, docs/**, *.md, common doc dirs — including any framework/API docs checked into the repo). BM25 over heading-anchored chunks from .agent_memory/indexes/docs-index.json. Returns ranked doc hits with doc_path, heading, line, and snippet. This indexes only files on disk in the project, never the internet.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string" },
+                    project_dir: { type: "string" },
+                    limit: { type: "number" },
+                },
+                required: ["query", "project_dir"],
+            },
+        },
         {
             name: "kage_metrics",
             description: "Return concise Kage adoption and quality metrics: code graph counts, language/parser coverage, memory graph evidence coverage, pending/approved packets, validation state, and readiness score.",
@@ -602,6 +624,30 @@ function listTools() {
                 required: ["project_dir", "packet_id", "replacement_packet_id"],
             },
         },
+        {
+            name: "kage_conflicts",
+            description: "List repo-local memory packet pairs that contradict each other (same cited path, same subject, opposing claim). Resolve each with kage_supersede, or keep both intentionally.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
+        {
+            name: "kage_skills",
+            description: "Codify durable, verified repo memory (runbooks, workflows, actionable decisions) into git-native SKILL.md files under .claude/skills/ that every teammate's agent auto-loads. Only grounded, non-stale packets become skills. Pass dry_run to preview without writing. dir overrides the output directory.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project_dir: { type: "string" },
+                    dry_run: { type: "boolean" },
+                    dir: { type: "string" },
+                },
+                required: ["project_dir"],
+            },
+        },
         {
             name: "kage_benchmark",
             description: "Return Kage proof metrics, or set mode=memory_quality / memory_scale for synthetic memory retrieval benchmarks.",
@@ -893,6 +939,9 @@ function listTools() {
             },
         },
     ];
+    if (process.env.KAGE_TOOLS === "full" || process.env.KAGE_ALL_TOOLS === "1")
+        return all;
+    return all.filter((tool) => exports.CORE_TOOLS.has(tool.name));
 }
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools: listTools(),
@@ -1052,8 +1101,25 @@ async function callTool(name, args) {
         const result = args?.embeddings
             ? await (0, kernel_js_1.recallWithEmbeddings)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain))
             : (0, kernel_js_1.recall)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5), Boolean(args?.explain), { maxContextTokens, structuralHops });
+        if (args?.docs) {
+            const docsSection = (0, kernel_js_1.docsRecallSection)(String(args?.project_dir ?? ""), String(args?.query ?? ""), 3);
+            if (docsSection)
+                result.context_block = `${result.context_block}\n\n${docsSection}`;
+        }
+        // Visible receipt: in text mode, surface what this recall saved so the agent
+        // can relay it. Value is otherwise invisible; an unseen win is a churned user.
+        const receipt = result.value_receipt;
+        const gainsLine = receipt && (receipt.tokens_saved > 0 || receipt.stale_withheld > 0)
+            ? `\n\nGains: ~${(0, kernel_js_1.formatTokenCount)(receipt.tokens_saved)} tokens saved by this recall${receipt.stale_withheld ? ` · stale memories withheld: ${receipt.stale_withheld}` : ""}`
+            : "";
         return {
-            content: [{ type: "text", text: args?.json || args?.explain ? JSON.stringify(result, null, 2) : result.context_block }],
+            content: [{ type: "text", text: args?.json || args?.explain ? JSON.stringify(result, null, 2) : `${result.context_block}${gainsLine}` }],
+        };
+    }
+    if (name === "kage_docs_search") {
+        const hits = (0, kernel_js_1.searchDocs)(String(args?.project_dir ?? ""), String(args?.query ?? ""), Number(args?.limit ?? 5));
+        return {
+            content: [{ type: "text", text: JSON.stringify({ query: String(args?.query ?? ""), source: "repo-docs", hits }, null, 2) }],
         };
     }
     if (name === "kage_graph") {
@@ -1069,20 +1135,6 @@ async function callTool(name, args) {
             isError: !result.ok,
         };
     }
-    if (name === "kage_code_graph") {
-        const projectDir = String(args?.project_dir ?? "");
-        const query = typeof args?.query === "string" ? args.query : "";
-        if (query) {
-            const result = (0, kernel_js_1.queryCodeGraph)(projectDir, query, Number(args?.limit ?? 10));
-            return {
-                content: [{ type: "text", text: args?.json ? JSON.stringify(result, null, 2) : result.context_block }],
-            };
-        }
-        const result = (0, kernel_js_1.buildCodeGraph)(projectDir);
-        return {
-            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-        };
-    }
     if (name === "kage_risk") {
         const result = (0, kernel_js_1.kageRisk)(String(args?.project_dir ?? ""), arrayArg(args?.targets), arrayArg(args?.changed_files));
         return {
@@ -1224,6 +1276,21 @@ async function callTool(name, args) {
             content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
         };
     }
+    if (name === "kage_conflicts") {
+        const result = (0, kernel_js_1.kageConflicts)(String(args?.project_dir ?? ""));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    if (name === "kage_skills") {
+        const result = (0, kernel_js_1.generateSkills)(String(args?.project_dir ?? ""), {
+            dryRun: args?.dry_run === true,
+            dir: typeof args?.dir === "string" ? args.dir : undefined,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
     if (name === "kage_module_health") {
         const result = (0, kernel_js_1.kageModuleHealth)(String(args?.project_dir ?? ""));
         return {