@kage-core/kage-graph-mcp 2.3.0 → 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]
@@ -79,6 +79,7 @@ Usage:
   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]
@@ -318,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);
@@ -341,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"));
@@ -466,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) {
@@ -487,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)");
         }
@@ -501,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;
@@ -1306,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)}), ` +
@@ -1429,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"),

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: {
@@ -193,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.",
@@ -627,6 +635,19 @@ function listTools() {
                 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.",
@@ -918,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(),
@@ -1082,8 +1106,14 @@ async function callTool(name, args) {
             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") {
@@ -1105,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 {
@@ -1266,6 +1282,15 @@ async function callTool(name, args) {
             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 {