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

package/dist/kernel.js

@@ -67,6 +67,8 @@ exports.valueSummary = valueSummary;
 exports.formatTokenCount = formatTokenCount;
 exports.kageFileContext = kageFileContext;
 exports.kageActivity = kageActivity;
+exports.detectContradictions = detectContradictions;
+exports.kageConflicts = kageConflicts;
 exports.kageMemoryReconciliation = kageMemoryReconciliation;
 exports.evaluateMemoryAdmission = evaluateMemoryAdmission;
 exports.validatePacket = validatePacket;
@@ -87,6 +89,9 @@ exports.writeLspSymbolIndex = writeLspSymbolIndex;
 exports.writeCodeIndex = writeCodeIndex;
 exports.buildCodeGraph = buildCodeGraph;
 exports.buildKnowledgeGraph = buildKnowledgeGraph;
+exports.buildDocsIndex = buildDocsIndex;
+exports.searchDocs = searchDocs;
+exports.docsRecallSection = docsRecallSection;
 exports.buildIndexes = buildIndexes;
 exports.indexProject = indexProject;
 exports.refreshProject = refreshProject;
@@ -105,6 +110,8 @@ exports.kageRisk = kageRisk;
 exports.kageDependencyPath = kageDependencyPath;
 exports.kageCleanupCandidates = kageCleanupCandidates;
 exports.truthReport = truthReport;
+exports.truthScorecardSvg = truthScorecardSvg;
+exports.truthScorecardMarkdown = truthScorecardMarkdown;
 exports.defaultClaudeMemStorePath = defaultClaudeMemStorePath;
 exports.claudeMemProjectKey = claudeMemProjectKey;
 exports.parseClaudeMemFileList = parseClaudeMemFileList;
@@ -175,6 +182,7 @@ exports.remediationFor = remediationFor;
 exports.approvePending = approvePending;
 exports.rejectPending = rejectPending;
 exports.changelog = changelog;
+exports.generateSkills = generateSkills;
 exports.reverifyMemory = reverifyMemory;
 exports.supersedeMemory = supersedeMemory;
 exports.kageMemoryLineage = kageMemoryLineage;
@@ -189,6 +197,7 @@ exports.capturePersonal = capturePersonal;
 exports.syncSetup = syncSetup;
 exports.syncStatus = syncStatus;
 exports.syncPersonal = syncPersonal;
+exports.kageLayers = kageLayers;
 const node_crypto_1 = require("node:crypto");
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
@@ -249,6 +258,9 @@ exports.SETUP_AGENTS = [
     "kilo-code",
     "claude-desktop",
     "aider",
+    "openclaw",
+    "copilot",
+    "hermes",
     "generic-mcp",
 ];
 const DEFAULT_CONFIDENCE = 0.7;
@@ -275,6 +287,13 @@ If Kage appears installed but no Kage tools are available, report that the activ
 agent session has not loaded the MCP server and ask the user to restart the
 agent. After restart, call \`kage_verify_agent\` to prove the harness is live.
 
+## Show the Value
+
+\`kage_context\` and \`kage_recall\` return a one-line gains receipt (tokens/$ saved
+this session, stale memories withheld). When it is non-trivial, relay it to the
+user in your own words — Kage's value is otherwise invisible, and a user who never
+sees it churns. Repeat only what the tool actually reported; never fabricate numbers.
+
 ## Automatic Capture
 
 When you learn something reusable, create repo-local memory with \`kage_learn\`.
@@ -1345,6 +1364,199 @@ function duplicateCandidatesWithContext(packet, context, threshold = 0.58) {
         status: entry.packet.status,
     }));
 }
+// Negation cues: a body that flips a claim. "do not use", "is not", "never",
+// "should not", "no longer", "stop using", "avoid", "instead of".
+const CONTRADICTION_NEGATION_CUES = [
+    "do not",
+    "don't",
+    "does not",
+    "doesn't",
+    "is not",
+    "isn't",
+    "are not",
+    "aren't",
+    "was not",
+    "should not",
+    "shouldn't",
+    "must not",
+    "cannot",
+    "can't",
+    "never",
+    "no longer",
+    "not idempotent",
+    "not safe",
+    "not thread-safe",
+    "not supported",
+    "not required",
+    "not needed",
+    "stop using",
+    "avoid",
+    "deprecated",
+    "removed",
+    "disable",
+    "disabled",
+];
+// Replacement cues: a body that points the claim at a different answer.
+// "use Y instead", "replaced by", "switched to", "now use", "migrate to".
+const CONTRADICTION_REPLACEMENT_CUES = [
+    "instead",
+    "instead of",
+    "replaced by",
+    "replaced with",
+    "replace with",
+    "switched to",
+    "switch to",
+    "migrated to",
+    "migrate to",
+    "now use",
+    "now uses",
+    "moved to",
+    "superseded by",
+    "in favor of",
+    "rather than",
+];
+function normalizedClaimText(packet) {
+    return `${packet.title}\n${packet.summary}\n${packet.body}`.toLowerCase();
+}
+function negationCueCount(text) {
+    let count = 0;
+    for (const cue of CONTRADICTION_NEGATION_CUES)
+        if (text.includes(cue))
+            count += 1;
+    return count;
+}
+function replacementCueCount(text) {
+    let count = 0;
+    for (const cue of CONTRADICTION_REPLACEMENT_CUES)
+        if (text.includes(cue))
+            count += 1;
+    return count;
+}
+// Tokens too generic to mean "these two packets are about the same subject".
+// In a memory repo about an agent-memory tool, words like "kage", "memory",
+// "agent", "code", "now", "use" appear in nearly every decision packet — so two
+// unrelated decisions that merely both touch mcp/index.ts would share several of
+// them and (under the old subjectOverlap<2 bypass) be flagged as contradictions.
+// The SUBJECT must be the DISTINCTIVE vocabulary, not the house style.
+const CONTRADICTION_GENERIC_SUBJECT = new Set([
+    ...STOPWORDS,
+    "use", "uses", "used", "using", "via", "per", "now", "new", "when", "then",
+    "this", "that", "these", "those", "not", "but", "also", "into", "from", "its",
+    "kage", "mcp", "memory", "memories", "agent", "agents", "packet", "packets",
+    "code", "graph", "repo", "repository", "file", "files", "path", "paths",
+    "recall", "capture", "captured", "decision", "decisions", "must", "should",
+    "report", "reports", "result", "results", "support", "supports", "supported",
+]);
+// Distinctive subject vocabulary of a packet: title+summary tokens with generic
+// / house-style words removed. Two packets share a subject only when their
+// DISTINCTIVE tokens overlap, not when they both say "kage memory decision".
+function distinctiveSubjectTokens(packet) {
+    return new Set([...tokenSet(`${packet.title}\n${packet.summary}`)].filter((token) => !CONTRADICTION_GENERIC_SUBJECT.has(token)));
+}
+// Opposing-polarity signal between two same-subject bodies. Conservative: a
+// contradiction needs one side to assert a claim and the other to negate or
+// replace it — NOT both sides carrying identical framing (that's a duplicate).
+function opposingPolarity(aText, bText) {
+    const aNeg = negationCueCount(aText);
+    const bNeg = negationCueCount(bText);
+    const aRepl = replacementCueCount(aText);
+    const bRepl = replacementCueCount(bText);
+    // (1) Negation asymmetry: one side negates the claim, the other does not.
+    // Two equally-hedged notes (both negate, or neither negates) are not flagged.
+    if (aNeg === 0 && bNeg >= 1)
+        return "one memory negates a claim the other asserts";
+    if (bNeg === 0 && aNeg >= 1)
+        return "one memory negates a claim the other asserts";
+    // (2) Replacement asymmetry: one side says "use Y instead", the other still
+    // asserts the original (no replacement framing). Same-subject + redirect.
+    if (aRepl === 0 && bRepl >= 1)
+        return "one memory replaces the approach the other still recommends";
+    if (bRepl === 0 && aRepl >= 1)
+        return "one memory replaces the approach the other still recommends";
+    return null;
+}
+// Detect existing approved packets that contradict `candidate`. Pure: takes the
+// candidate and (optionally) the existing pool, performs no writes. Returns the
+// conflicting approved packets with the shared paths and a human reason.
+function detectContradictions(projectDir, candidate, opts = {}) {
+    // Precision over recall: two packets sharing a path is NOT enough — they must
+    // be about the same distinctive subject. 0.5 (was 0.34) plus the generic-token
+    // filter is what collapses the false-positive storm (786 pairs -> ~real).
+    const subjectThreshold = opts.subjectThreshold ?? 0.5;
+    const candidatePaths = new Set(candidate.paths.filter((path) => meaningfulMemoryPath(path) && !shouldSkipRepoMemoryPath(path)));
+    if (!candidatePaths.size)
+        return [];
+    const existing = (opts.existing ?? loadApprovedPackets(projectDir)).filter((packet) => packet.id !== candidate.id && packet.status === "approved");
+    const candidateText = normalizedClaimText(candidate);
+    const candidateSubject = distinctiveSubjectTokens(candidate);
+    const findings = [];
+    for (const packet of existing) {
+        // (a) shared cited path — the structural anchor that makes a contradiction
+        //     about the SAME thing rather than two unrelated facts.
+        const sharedPaths = packet.paths.filter((path) => candidatePaths.has(path));
+        if (!sharedPaths.length)
+            continue;
+        // (b) same DISTINCTIVE subject. A genuine contradiction is the SAME claim
+        //     negated ("use X" vs "do not use X"), so the two packets must be near
+        //     paraphrases of each other's subject — measured over distinctive tokens
+        //     (jaccard). Two decisions that merely touch adjacent code in the same
+        //     file share a path and a few tokens but are NOT paraphrases, so they no
+        //     longer qualify. No token-count bypass: that was the false-positive door.
+        const packetSubject = distinctiveSubjectTokens(packet);
+        const subjectSimilarity = jaccard(candidateSubject, packetSubject);
+        if (subjectSimilarity < subjectThreshold)
+            continue;
+        // (c) opposing polarity — the claim itself is flipped/redirected.
+        const reason = opposingPolarity(candidateText, normalizedClaimText(packet));
+        if (!reason)
+            continue;
+        findings.push({
+            packet_id: packet.id,
+            title: packet.title,
+            shared_paths: sharedPaths,
+            reason: `${reason} (shared path: ${sharedPaths.join(", ")})`,
+        });
+    }
+    return findings
+        .sort((a, b) => a.title.localeCompare(b.title))
+        .slice(0, 5);
+}
+// Repo-wide pairwise contradiction scan across approved packets. Reuses
+// detectContradictions per packet against the already-loaded pool so the same
+// conservative heuristic governs both write-time surfacing and the audit view.
+function kageConflicts(projectDir) {
+    ensureMemoryDirs(projectDir);
+    const approved = loadApprovedPackets(projectDir);
+    const byId = new Map(approved.map((packet) => [packet.id, packet]));
+    const pairs = [];
+    const seen = new Set();
+    for (const packet of approved) {
+        const findings = detectContradictions(projectDir, packet, { existing: approved });
+        for (const finding of findings) {
+            const ordered = [packet.id, finding.packet_id].sort();
+            const key = ordered.join("\0");
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const firstPacket = byId.get(ordered[0]);
+            const secondPacket = byId.get(ordered[1]);
+            pairs.push({
+                a: { id: firstPacket.id, title: firstPacket.title },
+                b: { id: secondPacket.id, title: secondPacket.title },
+                shared_paths: finding.shared_paths,
+                reason: finding.reason,
+            });
+        }
+    }
+    pairs.sort((x, y) => x.a.title.localeCompare(y.a.title) || x.b.title.localeCompare(y.b.title));
+    return {
+        ok: true,
+        project_dir: projectDir,
+        generated_at: nowIso(),
+        count: pairs.length,
+        pairs,
+    };
+}
 function packetFeedbackScore(packet) {
     const quality = (packet.quality ?? {});
     return Number(quality.votes_up ?? 0) * 2 - Number(quality.votes_down ?? 0) * 3 - Number(quality.reports_stale ?? 0) * 4;
@@ -1419,15 +1631,144 @@ function memoryPathFingerprint(projectDir, path, cache) {
         return null;
     }
 }
-function memoryPathFingerprints(projectDir, paths) {
+// Symbol-anchoring is only attempted where extractSymbols (the TS/JS parser) is
+// reliable. Other languages fall back to whole-file fingerprints — no granularity
+// benefit yet, but no regression either.
+const ANCHOR_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
+function pathSupportsSymbolAnchors(path) {
+    return ANCHOR_EXTENSIONS.has((0, node_path_1.extname)(path).toLowerCase());
+}
+// Whole identifiers mentioned in a packet's text — the names of the symbols the
+// memory is talking about. camelCase / snake_case kept intact (not sub-tokenized)
+// so "detectContradictions" matches the symbol, not "detect" + "contradictions".
+function identifierTokens(text) {
+    const out = new Set();
+    for (const match of text.matchAll(/[A-Za-z_$][A-Za-z0-9_$]*/g))
+        out.add(match[0].toLowerCase());
+    return out;
+}
+// current-file symbol span hashes, keyed by `${nameLower}\0${kind}` -> [sha256...].
+// Cached by mtime+size: extraction only runs when a file actually changed.
+const anchorSymbolCache = new Map();
+function symbolSpanHashesFromText(path, text) {
+    const byKey = new Map();
+    let symbols;
+    try {
+        symbols = extractSymbols(path, text);
+    }
+    catch {
+        return byKey;
+    }
+    const lines = text.split(/\r?\n/);
+    for (const symbol of symbols) {
+        if (symbol.name.length < 4)
+            continue;
+        if (symbol.end_line == null || symbol.line < 1 || symbol.end_line < symbol.line)
+            continue;
+        const span = lines.slice(symbol.line - 1, symbol.end_line).join("\n");
+        if (!span.trim())
+            continue;
+        const key = `${symbol.name.toLowerCase()}\0${symbol.kind}`;
+        const list = byKey.get(key) ?? [];
+        list.push(sha256Hex(Buffer.from(span, "utf8")));
+        byKey.set(key, list);
+    }
+    return byKey;
+}
+function fileSymbolSpanHashes(projectDir, path) {
+    const normalized = path.replace(/\\/g, "/").replace(/^\/+/, "");
+    if (!pathSupportsSymbolAnchors(normalized))
+        return null;
+    const absolutePath = (0, node_path_1.join)(projectDir, normalized);
+    let stats;
+    try {
+        stats = (0, node_fs_1.statSync)(absolutePath);
+        if (!stats.isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const cacheKey = `${projectDir}\0${normalized}`;
+    const warm = anchorSymbolCache.get(cacheKey);
+    if (warm && warm.mtimeMs === stats.mtimeMs && warm.size === stats.size)
+        return warm.byKey;
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(absolutePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const byKey = symbolSpanHashesFromText(normalized, text);
+    anchorSymbolCache.set(cacheKey, { mtimeMs: stats.mtimeMs, size: stats.size, byKey });
+    return byKey;
+}
+// Compute fingerprints for a packet's cited paths. When anchorText (the packet's
+// title+summary+body) is supplied, anchor each TS/JS file to the symbols the
+// memory actually names, so unrelated edits in the same file do not mark it stale.
+function memoryPathFingerprints(projectDir, paths, anchorText) {
+    const idents = anchorText ? identifierTokens(anchorText) : null;
     const fingerprints = [];
     for (const path of unique(paths).filter(fingerprintableMemoryPath)) {
         const fingerprint = memoryPathFingerprint(projectDir, path);
-        if (fingerprint)
-            fingerprints.push(fingerprint);
+        if (!fingerprint)
+            continue;
+        if (idents && pathSupportsSymbolAnchors(path)) {
+            const byKey = fileSymbolSpanHashes(projectDir, path);
+            if (byKey) {
+                // extractSymbols recurses into bodies, so a generic local like `match` can
+                // appear many times. Only anchor names that resolve to EXACTLY ONE symbol
+                // span in the file — an unambiguous handle on the thing the memory means.
+                const spanCountByName = new Map();
+                for (const [key, hashes] of byKey) {
+                    const name = key.slice(0, key.indexOf("\0"));
+                    spanCountByName.set(name, (spanCountByName.get(name) ?? 0) + hashes.length);
+                }
+                const symbols = [];
+                for (const [key, hashes] of byKey) {
+                    const [name, kind] = key.split("\0");
+                    if (!idents.has(name) || spanCountByName.get(name) !== 1)
+                        continue;
+                    symbols.push({ name, kind, sha256: hashes[0] });
+                }
+                if (symbols.length) {
+                    fingerprints.push({ ...fingerprint, symbols: symbols.slice(0, 32) });
+                    continue;
+                }
+            }
+        }
+        fingerprints.push(fingerprint);
     }
     return fingerprints;
 }
+// Has the content a memory depends on changed since capture? Whole-file identical
+// is always "no". When the file differs but the memory is anchored to specific
+// symbols, it is "changed" only if one of those symbols was edited or removed —
+// edits elsewhere in the same file do not invalidate it. Unanchored fingerprints
+// (non-TS files, prose memories) keep the whole-file policy.
+function fingerprintPathContentChanged(projectDir, stored, cache) {
+    const current = memoryPathFingerprint(projectDir, stored.path, cache);
+    if (current === null)
+        return false; // missing path is handled by the dedicated check
+    if (current.sha256 === stored.sha256)
+        return false; // whole file byte-identical
+    if (stored.symbols && stored.symbols.length) {
+        const byKey = fileSymbolSpanHashes(projectDir, stored.path);
+        if (byKey) {
+            for (const symbol of stored.symbols) {
+                const currentHashes = byKey.get(`${symbol.name.toLowerCase()}\0${symbol.kind}`);
+                if (!currentHashes || !currentHashes.length)
+                    return true; // anchored symbol gone
+                if (!currentHashes.includes(symbol.sha256))
+                    return true; // anchored symbol edited
+            }
+            return false; // every anchored symbol is byte-identical; the rest of the file is irrelevant
+        }
+        // Parser unavailable for this file now — fall through to the whole-file signal.
+    }
+    return true;
+}
 function packetStoredPathFingerprints(packet) {
     const raw = (packet.freshness ?? {}).path_fingerprints;
     if (!Array.isArray(raw))
@@ -1441,9 +1782,31 @@ function packetStoredPathFingerprints(packet) {
         const size = Number(record.size ?? 0);
         if (!path || !sha256 || !Number.isFinite(size) || !fingerprintableMemoryPath(path))
             return [];
-        return [{ path, sha256, size }];
+        const symbols = Array.isArray(record.symbols)
+            ? record.symbols.flatMap((entry) => {
+                if (!entry || typeof entry !== "object")
+                    return [];
+                const sym = entry;
+                const name = typeof sym.name === "string" ? sym.name : "";
+                const kind = typeof sym.kind === "string" ? sym.kind : "";
+                const symSha = typeof sym.sha256 === "string" ? sym.sha256 : "";
+                if (!name || !symSha)
+                    return [];
+                return [{ name, kind, sha256: symSha }];
+            })
+            : undefined;
+        return [{ path, sha256, size, ...(symbols && symbols.length ? { symbols } : {}) }];
     });
 }
+// Append-only "ledger" docs (CHANGELOG, HISTORY) churn on nearly every commit.
+// Their content hash changes constantly without invalidating a memory's claim, so
+// they are excluded from content-change (soft-stale) detection — you can still
+// cite one, but appending an entry must not mark the memory stale. Deletion still
+// counts as staleness; this only suppresses the noisy "linked path changed" reason.
+const APPEND_ONLY_LEDGER_RE = /(^|\/)(change[-_ ]?log|history)(\.[a-z0-9]+)?$/i;
+function isAppendOnlyLedgerPath(path) {
+    return APPEND_ONLY_LEDGER_RE.test(normalizeRelPath(path));
+}
 function staleMemoryReasons(projectDir, packet, fingerprintCache) {
     const reasons = [];
     const quality = (packet.quality ?? {});
@@ -1473,11 +1836,9 @@ function staleMemoryReasons(projectDir, packet, fingerprintCache) {
         const storedFingerprints = packetStoredPathFingerprints(packet);
         const changedPaths = storedFingerprints
             .filter((fingerprint) => !isGroundingIgnored(projectDir, fingerprint.path))
+            .filter((fingerprint) => !isAppendOnlyLedgerPath(fingerprint.path))
             .filter((fingerprint) => (0, node_fs_1.existsSync)((0, node_path_1.join)(projectDir, fingerprint.path)))
-            .filter((fingerprint) => {
-            const current = memoryPathFingerprint(projectDir, fingerprint.path, fingerprintCache);
-            return current !== null && current.sha256 !== fingerprint.sha256;
-        })
+            .filter((fingerprint) => fingerprintPathContentChanged(projectDir, fingerprint, fingerprintCache))
             .map((fingerprint) => fingerprint.path);
         if (changedPaths.length) {
             reasons.push(`linked path changed since memory was verified: ${changedPaths.slice(0, 4).join(", ")}`);
@@ -1531,6 +1892,22 @@ function recallHardStaleReason(projectDir, packet, cache) {
     }
     return null;
 }
+// Strict recall gate: hard-stale (recallHardStaleReason) PLUS soft-stale — a cited
+// file whose content changed under the memory, or partially-deleted citations.
+// Used to keep content-changed memory out of recall, skills, and the suppressed
+// report, so the agent never acts on a claim the code has moved past. NOT used by
+// compaction: a merely-changed packet needs reverify, not auto-deprecation.
+function recallStaleReason(projectDir, packet, cache) {
+    const hard = recallHardStaleReason(projectDir, packet, cache);
+    if (hard)
+        return hard;
+    // Strict recall (task #39): also withhold memory whose cited file CONTENT changed
+    // (the fingerprint moved under it). Partial-missing citations stay served-but-
+    // flagged — only the content-drift case is suppressed here.
+    const changed = staleMemoryReasons(projectDir, packet, cache)
+        .find((reason) => reason.startsWith("linked path changed since memory was verified"));
+    return changed ?? null;
+}
 function changedPathsFromStaleReasons(reasons) {
     return unique(reasons.flatMap((reason) => {
         const match = reason.match(/^linked path changed since memory was verified: (.+)$/);
@@ -5984,6 +6361,213 @@ function hydrateKnowledgeGraphArtifact(projectDir, artifact) {
         edges: readJson(edgesPath),
     };
 }
+// --- Docs search index ---------------------------------------------------
+// Searchable index over the REPO's OWN committed documentation (project README,
+// docs/**, *.md, and common doc dirs — plus any framework/API docs that are
+// checked into this repo). It indexes nothing from the internet; only files
+// that exist on disk in this project. Recall can therefore answer from docs,
+// not just learned memory packets and code.
+const DOCS_INDEX_SCHEMA_VERSION = 1;
+// Heading-anchored chunks are capped so a single long section can't dominate the
+// BM25 length normalization or bloat the artifact.
+const DOCS_CHUNK_MAX_CHARS = 1600;
+// Directory names that commonly hold prose documentation, beyond the root README
+// and a top-level docs/ dir. These are matched as path segments.
+const DOCS_DIR_NAMES = new Set(["docs", "doc", "documentation", "guides", "guide", "wiki", "manual", "handbook"]);
+const DOCS_EXTENSIONS = new Set([".md", ".mdx", ".markdown", ".rst", ".txt"]);
+function isDocFile(relativePath) {
+    if (shouldSkipCodePath(relativePath))
+        return false;
+    if (isNoisePath(relativePath))
+        return false;
+    const segments = relativePath.split("/");
+    const name = segments[segments.length - 1];
+    if (!DOCS_EXTENSIONS.has(extensionOf(name)))
+        return false;
+    // A markdown/rst/txt file qualifies if it is the root README, sits under a
+    // recognised doc directory, or is any committed *.md anywhere in the tree.
+    if (/^readme\b/i.test(name))
+        return true;
+    if (segments.slice(0, -1).some((part) => DOCS_DIR_NAMES.has(part.toLowerCase())))
+        return true;
+    const extension = extensionOf(name);
+    return extension === ".md" || extension === ".mdx" || extension === ".markdown";
+}
+function discoverDocFiles(projectDir) {
+    const all = walkFiles(projectDir, (absolute) => {
+        const relativePath = (0, node_path_1.relative)(projectDir, absolute).replace(/\\/g, "/");
+        return isDocFile(relativePath);
+    });
+    return all.map((absolute) => (0, node_path_1.relative)(projectDir, absolute).replace(/\\/g, "/")).sort();
+}
+function headingAnchor(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}
+// Split a doc into heading-anchored chunks. Each chunk carries the heading path
+// (e.g. "Setup > Install") plus the body beneath it, capped at DOCS_CHUNK_MAX_CHARS.
+function chunkDoc(docPath, text) {
+    const lines = text.split(/\r?\n/);
+    const chunks = [];
+    const headingStack = [];
+    let bodyLines = [];
+    let chunkStartLine = 1;
+    let inFence = false;
+    const headingPath = () => headingStack.map((entry) => entry.title).join(" > ");
+    const flush = (startLine) => {
+        const body = bodyLines.join("\n").trim();
+        bodyLines = [];
+        if (!body)
+            return;
+        const heading = headingPath() || (0, node_path_1.basename)(docPath);
+        for (let offset = 0; offset < body.length; offset += DOCS_CHUNK_MAX_CHARS) {
+            const slice = body.slice(offset, offset + DOCS_CHUNK_MAX_CHARS);
+            chunks.push({
+                doc_path: docPath,
+                heading,
+                anchor: headingAnchor(headingStack[headingStack.length - 1]?.title ?? heading),
+                text: slice,
+                line: startLine,
+            });
+        }
+    };
+    lines.forEach((line, index) => {
+        const fenceMatch = line.match(/^\s*(?:```|~~~)/);
+        if (fenceMatch)
+            inFence = !inFence;
+        const headingMatch = inFence ? null : line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+        if (headingMatch) {
+            flush(chunkStartLine);
+            const level = headingMatch[1].length;
+            const title = headingMatch[2].trim();
+            while (headingStack.length && headingStack[headingStack.length - 1].level >= level)
+                headingStack.pop();
+            headingStack.push({ level, title });
+            chunkStartLine = index + 1;
+            return;
+        }
+        bodyLines.push(line);
+    });
+    flush(chunkStartLine);
+    return chunks;
+}
+function buildDocsIndex(projectDir) {
+    const docFiles = discoverDocFiles(projectDir);
+    const chunks = [];
+    for (const docPath of docFiles) {
+        const text = safeReadText((0, node_path_1.join)(projectDir, docPath));
+        if (!text)
+            continue;
+        chunks.push(...chunkDoc(docPath, text));
+    }
+    const artifact = {
+        schema_version: DOCS_INDEX_SCHEMA_VERSION,
+        generated_at: nowIso(),
+        source: "repo-docs",
+        doc_count: docFiles.length,
+        chunk_count: chunks.length,
+        chunks,
+    };
+    writeJson((0, node_path_1.join)(indexesDir(projectDir), "docs-index.json"), artifact);
+    return artifact;
+}
+function readDocsIndex(projectDir) {
+    const path = (0, node_path_1.join)(indexesDir(projectDir), "docs-index.json");
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const artifact = readJson(path);
+        if (!Array.isArray(artifact?.chunks))
+            return null;
+        return artifact;
+    }
+    catch {
+        return null;
+    }
+}
+// BM25 over doc chunks, reusing the same lexical scorer (tokenize + stemming +
+// IDF) as packet recall. Heading text is weighted above body, mirroring how the
+// packet scorer weights titles.
+function scoreDocsBm25(queryTerms, chunks) {
+    const terms = expandQueryTerms(queryTerms);
+    const result = new Map();
+    if (!terms.length || !chunks.length)
+        return result;
+    const HEADING_WEIGHT = 3;
+    const documents = chunks.map((chunk) => {
+        const termFrequency = new Map();
+        let length = 0;
+        const add = (textValue, weight) => {
+            for (const token of tokenize(textValue)) {
+                termFrequency.set(token, (termFrequency.get(token) ?? 0) + weight);
+                length += weight;
+            }
+        };
+        add(chunk.heading, HEADING_WEIGHT);
+        add(chunk.text, 1);
+        return { termFrequency, length: Math.max(1, length) };
+    });
+    const averageLength = documents.reduce((sum, document) => sum + document.length, 0) / documents.length || 1;
+    const documentFrequency = new Map();
+    for (const term of terms) {
+        documentFrequency.set(term, documents.filter((document) => document.termFrequency.has(term)).length);
+    }
+    documents.forEach((document, index) => {
+        let score = 0;
+        for (const term of terms) {
+            const termFrequency = document.termFrequency.get(term) ?? 0;
+            if (termFrequency <= 0)
+                continue;
+            const df = documentFrequency.get(term) ?? 0;
+            const idf = Math.log(1 + (documents.length - df + 0.5) / (df + 0.5));
+            const denominator = termFrequency + BM25_K1 * (1 - BM25_B + BM25_B * (document.length / averageLength));
+            score += idf * ((termFrequency * (BM25_K1 + 1)) / denominator);
+        }
+        if (score > 0)
+            result.set(index, Number(score.toFixed(2)));
+    });
+    return result;
+}
+function docsSnippet(text) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > 200 ? `${collapsed.slice(0, 197)}...` : collapsed;
+}
+function searchDocs(projectDir, query, limit = 5) {
+    // Use the persisted index when present; rebuild on the fly otherwise so the
+    // search works even before the first refresh.
+    const artifact = readDocsIndex(projectDir) ?? buildDocsIndex(projectDir);
+    const chunks = artifact.chunks;
+    const scores = scoreDocsBm25(tokenize(query), chunks);
+    return [...scores.entries()]
+        .sort((a, b) => b[1] - a[1] || chunks[a[0]].doc_path.localeCompare(chunks[b[0]].doc_path) || chunks[a[0]].line - chunks[b[0]].line)
+        .slice(0, Math.max(0, limit))
+        .map(([index, score]) => {
+        const chunk = chunks[index];
+        return {
+            doc_path: chunk.doc_path,
+            heading: chunk.heading,
+            line: chunk.line,
+            snippet: docsSnippet(chunk.text),
+            score,
+        };
+    });
+}
+// Renders a "Docs" section appended to recall output. Honest framing: these are
+// the repo's own committed docs, not the internet.
+function docsRecallSection(projectDir, query, limit = 3) {
+    const hits = searchDocs(projectDir, query, limit);
+    if (!hits.length)
+        return null;
+    const lines = ["Docs (from this repo's own committed documentation):"];
+    for (const hit of hits) {
+        lines.push(`- ${hit.doc_path}:${hit.line} — ${hit.heading}`);
+        lines.push(`  ${hit.snippet}`);
+    }
+    return lines.join("\n");
+}
 function buildPacketIndexes(projectDir) {
     ensureMemoryDirs(projectDir);
     const packets = loadPacketsFromDir(packetsDir(projectDir)).sort((a, b) => a.id.localeCompare(b.id));
@@ -6029,6 +6613,10 @@ function buildPacketIndexes(projectDir) {
     writeJson(written[2], byTag);
     writeJson(written[3], byType);
     written.push(writeSparseVectorIndex(projectDir, packets));
+    // Docs search index over the repo's own committed documentation. Built here so
+    // it stays current through both indexProject and refreshProject.
+    buildDocsIndex(projectDir);
+    written.push((0, node_path_1.join)(indexesDir(projectDir), "docs-index.json"));
     return written;
 }
 function readCurrentCodeGraph(projectDir, expectedInputHash) {
@@ -6130,6 +6718,7 @@ function currentOrBuildGraphs(projectDir) {
                 (0, node_path_1.join)(indexesDir(projectDir), "by-tag.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "by-type.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "vector-local.json"),
+                (0, node_path_1.join)(indexesDir(projectDir), "docs-index.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "structural.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "graph.json"),
                 (0, node_path_1.join)(indexesDir(projectDir), "code-graph.json"),
@@ -6422,7 +7011,7 @@ function kageSuppressedMemory(projectDir) {
     const cache = new Map();
     const items = loadApprovedPackets(projectDir)
         .map((packet) => {
-        const reason = recallHardStaleReason(projectDir, packet, cache);
+        const reason = recallStaleReason(projectDir, packet, cache);
         return reason ? { id: packet.id, title: packet.title, type: packet.type, reason, paths: packet.paths } : null;
     })
         .filter((entry) => entry !== null);
@@ -6497,7 +7086,7 @@ function compactProject(projectDir, options = {}) {
                     paths: keptPaths,
                     freshness: {
                         ...(packet.freshness ?? {}),
-                        path_fingerprints: memoryPathFingerprints(projectDir, keptPaths),
+                        path_fingerprints: memoryPathFingerprints(projectDir, keptPaths, `${packet.title}\n${packet.summary}\n${packet.body}`),
                         last_verified_at: nowIso(),
                     },
                     updated_at: nowIso(),
@@ -7312,7 +7901,7 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
     const approvedPackets = includeStale
         ? allApprovedPackets
         : allApprovedPackets.filter((packet) => {
-            const reason = recallHardStaleReason(projectDir, packet, staleFingerprintCache);
+            const reason = recallStaleReason(projectDir, packet, staleFingerprintCache);
             if (reason) {
                 suppressed.push({ id: packet.id, title: packet.title, reason });
                 return false;
@@ -7404,13 +7993,20 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
             ? [`## Structural Blast Radius (${structuralHops}-hop)`, ...blastRadius.map((path, index) => `${index + 1}. ${path}`), ""]
             : []),
         scored.length ? "## Relevant Memory" : "No relevant repo memory found.",
-        ...scored.flatMap((entry, index) => [
-            "",
-            `${index + 1}. [${entry.packet.type} | ${entry.packet.scope} | confidence ${entry.packet.confidence.toFixed(2)}] ${entry.packet.title}`,
-            `   Summary: ${entry.packet.summary}`,
-            `   Why matched: ${entry.why_matched.join(", ") || "text relevance"}`,
-            `   Source: ${sourceLabel(entry.packet)}`,
-        ]),
+        ...scored.flatMap((entry, index) => {
+            const contradicts = (entry.packet.quality ?? {}).contradicts;
+            const contested = Array.isArray(contradicts) && contradicts.length > 0;
+            return [
+                "",
+                `${index + 1}. [${entry.packet.type} | ${entry.packet.scope} | confidence ${entry.packet.confidence.toFixed(2)}] ${entry.packet.title}`,
+                `   Summary: ${entry.packet.summary}`,
+                `   Why matched: ${entry.why_matched.join(", ") || "text relevance"}`,
+                `   Source: ${sourceLabel(entry.packet)}`,
+                ...(contested
+                    ? [`   ⚠ Contested: this memory contradicts ${contradicts.length} other packet(s) (${contradicts.join(", ")}). Resolve with kage conflicts / kage supersede before relying on it.`]
+                    : []),
+            ];
+        }),
         "",
         pendingScored.length ? "## Working Memory (Pending Review)" : "",
         ...pendingScored.flatMap((entry, index) => [
@@ -7424,7 +8020,12 @@ function recallWithVectorScores(projectDir, query, limit = 5, explain = false, i
         graphContext.edges.length ? "## Related Graph Facts" : "",
         ...graphContext.edges.slice(0, 5).map((edge, index) => `${index + 1}. ${edge.fact} (evidence: ${edge.evidence.join(", ")})`),
         ...(suppressed.length
-            ? ["", `_${suppressed.length} stale memory packet(s) excluded from recall. Run kage verify for details._`]
+            ? [
+                "",
+                "## Withheld (stale — not served)",
+                `_${suppressed.length} memory packet(s) excluded from recall because the cited code moved under them. The claim may still hold — reverify to restore, or supersede if it changed. Do not act on these as-is._`,
+                ...suppressed.slice(0, 5).map((s) => `- ${s.title} — ${s.reason} (kage reverify --packet ${s.id})`),
+            ]
             : []),
         ...(personalEntries.length
             ? [
@@ -8530,7 +9131,7 @@ function kageCleanupCandidates(projectDir) {
         summary: `${candidates.length} conservative cleanup candidate(s), ${skippedEntryPoints.length} entrypoint-like source file(s) skipped, ${skippedRuntimeReferences.length} runtime reference(s) skipped.`,
     };
 }
-const TRUTH_REPORT_MAX_FINDINGS = 12;
+const TRUTH_REPORT_MAX_FINDINGS = 16;
 const TRUTH_REPORT_AI_ERA_DAYS = 120;
 // Symbol names too generic to mean "two teams built the same thing".
 const TRUTH_COMMON_SYMBOL_NAMES = new Set([
@@ -8814,6 +9415,106 @@ function truthReport(projectDir) {
         }
     }
     voidFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
+    // 1e. Untested hot paths: central, churned source files no test exercises.
+    // Build the set of source paths some test covers — directly (covers_path /
+    // covers_symbol) or indirectly (a test file imports it). When the repo has no
+    // tests at all, "untested" is the baseline, not a finding, so we skip it.
+    const hasTests = graph.tests.length > 0 || graph.files.some((file) => file.kind === "test");
+    const testedPaths = new Set();
+    if (hasTests) {
+        const symbolPathById = new Map(graph.symbols.map((symbol) => [symbol.id, symbol.path]));
+        const symbolPathsByName = new Map();
+        for (const symbol of graph.symbols) {
+            const list = symbolPathsByName.get(symbol.name) ?? [];
+            list.push(symbol.path);
+            symbolPathsByName.set(symbol.name, list);
+        }
+        for (const test of graph.tests) {
+            if (test.covers_path)
+                testedPaths.add(test.covers_path.replace(/\\/g, "/").replace(/^\/+/, ""));
+            if (test.covers_symbol) {
+                const byId = symbolPathById.get(test.covers_symbol);
+                if (byId)
+                    testedPaths.add(byId);
+                for (const path of symbolPathsByName.get(test.covers_symbol) ?? [])
+                    testedPaths.add(path);
+            }
+        }
+        for (const edge of graph.imports) {
+            if (edge.to_path && fileByPath.get(edge.from_path)?.kind === "test")
+                testedPaths.add(edge.to_path);
+        }
+    }
+    const untestedFindings = [];
+    if (hasTests) {
+        for (const file of sourceFiles) {
+            if (isEntrypointLike(file.path))
+                continue;
+            const fileCentrality = centrality.get(file.path) ?? 0;
+            const commits = fileCommits.get(file.path) ?? 0;
+            if (fileCentrality < 5)
+                continue;
+            if (hasGit && commits < 2)
+                continue;
+            if (testedPaths.has(file.path))
+                continue;
+            untestedFindings.push({
+                kind: "untested_hot",
+                title: `${file.path} — untested hot path`,
+                detail: `${fileCentrality} other file(s)/call(s) depend on it${commits ? ` and it has changed ${commits} time(s)` : ""}, yet no test imports or directly targets it. Coverage gaps on a hub file like this are where regressions hide.`,
+                evidence: [`${file.path}:1  centrality ${fileCentrality}, tests directly covering it: 0`],
+                surprise: Math.min(100, 30 + Math.min(45, fileCentrality * 3) + (hasGit ? Math.min(15, commits) : 0)),
+            });
+        }
+    }
+    untestedFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
+    // 1f. Complexity hotspots: very large source files many things depend on —
+    // where knowledge concentrates and onboarding stalls.
+    const complexityFindings = [];
+    for (const file of sourceFiles) {
+        const fileCentrality = centrality.get(file.path) ?? 0;
+        if (file.line_count < 400)
+            continue;
+        if (fileCentrality < 3 && file.line_count < 800)
+            continue;
+        complexityFindings.push({
+            kind: "complexity_hotspot",
+            title: `${file.path} — ${file.line_count} lines, ${fileCentrality} dependent(s)`,
+            detail: `A ${file.line_count}-line file that ${fileCentrality} other file(s) depend on. The biggest, most-connected files are exactly where undocumented knowledge piles up.`,
+            evidence: [`${file.path}:1  ${file.line_count} lines, centrality ${fileCentrality}`],
+            surprise: Math.min(100, 25 + Math.min(40, Math.round(file.line_count / 40)) + Math.min(25, fileCentrality * 2)),
+        });
+    }
+    complexityFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
+    // 1g. Known debt: TODO/FIXME/HACK/deprecation markers left in code. Each is a
+    // decision deferred and undocumented. Scan the most-connected files first and
+    // bound the walk so a huge repo stays fast.
+    const debtFindings = [];
+    const DEBT_RE = /(?:^|[^A-Za-z0-9_])(TODO|FIXME|HACK|XXX|@deprecated|@todo)(?:[^A-Za-z0-9_]|$)/gi;
+    const debtScanTargets = [...sourceFiles]
+        .sort((a, b) => (centrality.get(b.path) ?? 0) - (centrality.get(a.path) ?? 0))
+        .slice(0, 400);
+    for (const file of debtScanTargets) {
+        const text = truthFileText(file.path);
+        if (!text)
+            continue;
+        const matches = text.match(DEBT_RE);
+        const count = matches ? matches.length : 0;
+        if (count < 1)
+            continue;
+        const fileCentrality = centrality.get(file.path) ?? 0;
+        // A lone marker in a leaf file is noise; require either repetition or reach.
+        if (count < 2 && fileCentrality < 2)
+            continue;
+        debtFindings.push({
+            kind: "debt_marker",
+            title: `${file.path} — ${count} unresolved debt marker${count === 1 ? "" : "s"}`,
+            detail: `TODO/FIXME/HACK/deprecation note(s) left in code${fileCentrality ? `, in a file ${fileCentrality} other(s) depend on` : ""}. Each is a decision deferred and undocumented.`,
+            evidence: [`${file.path}:1  ${count} marker(s), centrality ${fileCentrality}`],
+            surprise: Math.min(100, 20 + Math.min(35, count * 6) + Math.min(20, fileCentrality * 2)),
+        });
+    }
+    debtFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
     // 2. Doc-truth: checkable claims in README/docs vs reality.
     const docLieFindings = [];
     if (docLines.length) {
@@ -8900,19 +9601,29 @@ function truthReport(projectDir) {
     docLieFindings.sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title));
     // Cap per category so one noisy category cannot drown the report, then rank globally.
     const findings = [
+        ...voidFindings.slice(0, 4),
+        ...untestedFindings.slice(0, 4),
+        ...complexityFindings.slice(0, 4),
+        ...debtFindings.slice(0, 4),
+        ...busFindings.slice(0, 4),
         ...duplicateFindings.slice(0, 4),
         ...ghostFindings.slice(0, 4),
-        ...busFindings.slice(0, 4),
-        ...voidFindings.slice(0, 4),
         ...docLieFindings.slice(0, 4),
     ].sort((a, b) => b.surprise - a.surprise || a.title.localeCompare(b.title)).slice(0, TRUTH_REPORT_MAX_FINDINGS);
-    const headlineParts = [
-        `${duplicateFindings.length} duplicate cluster${duplicateFindings.length === 1 ? "" : "s"}`,
-        `${ghostFindings.length} ghost export${ghostFindings.length === 1 ? "" : "s"}`,
-        `${busFindings.length} bus-factor-1 hot file${busFindings.length === 1 ? "" : "s"}`,
-        `${voidFindings.length} knowledge void${voidFindings.length === 1 ? "" : "s"}`,
-        ...(docLines.length ? [`${docLieFindings.length} doc lie${docLieFindings.length === 1 ? "" : "s"}`] : []),
+    // Lead the headline with what we actually found; categories that came back
+    // clean are reported separately (see CLI "Clean:" line) so zeros never read
+    // as "scan found nothing".
+    const headlineCandidates = [
+        [voidFindings.length, `${voidFindings.length} knowledge void${voidFindings.length === 1 ? "" : "s"}`],
+        [untestedFindings.length, `${untestedFindings.length} untested hot path${untestedFindings.length === 1 ? "" : "s"}`],
+        [complexityFindings.length, `${complexityFindings.length} complexity hotspot${complexityFindings.length === 1 ? "" : "s"}`],
+        [debtFindings.length, `${debtFindings.length} debt marker file${debtFindings.length === 1 ? "" : "s"}`],
+        [busFindings.length, `${busFindings.length} bus-factor-1 hot file${busFindings.length === 1 ? "" : "s"}`],
+        [duplicateFindings.length, `${duplicateFindings.length} duplicate cluster${duplicateFindings.length === 1 ? "" : "s"}`],
+        [ghostFindings.length, `${ghostFindings.length} ghost export${ghostFindings.length === 1 ? "" : "s"}`],
+        ...(docLines.length ? [[docLieFindings.length, `${docLieFindings.length} doc lie${docLieFindings.length === 1 ? "" : "s"}`]] : []),
     ];
+    const headlineParts = headlineCandidates.filter(([count]) => count > 0).map(([, label]) => label);
     return {
         schema_version: 1,
         project_dir: projectDir,
@@ -8924,6 +9635,9 @@ function truthReport(projectDir) {
             ghost_exports: ghostFindings.length,
             bus_factor_files: busFindings.length,
             knowledge_voids: voidFindings.length,
+            untested_hot_paths: untestedFindings.length,
+            complexity_hotspots: complexityFindings.length,
+            debt_markers: debtFindings.length,
             doc_lies: docLieFindings.length,
             docs_scanned: docFiles.length,
         },
@@ -8937,6 +9651,118 @@ function truthReport(projectDir) {
         ],
     };
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Shareable Truth Report scorecard. `kage scan --scorecard` turns a TruthReport
+// into a screenshot-able SVG (and a Markdown variant) so the 60-second scan
+// becomes something people post — a repo scorecard, not just terminal output.
+// This is the top-of-funnel artifact: a stranger runs it on any repo, gets a
+// shareable card, and the memory loop is what they install afterwards.
+// ─────────────────────────────────────────────────────────────────────────────
+const SCORECARD_CARDS = [
+    { key: "knowledge_voids", label: "KNOWLEDGE VOIDS" },
+    { key: "untested_hot_paths", label: "UNTESTED HOT PATHS" },
+    { key: "complexity_hotspots", label: "COMPLEXITY HOTSPOTS" },
+    { key: "debt_markers", label: "KNOWN DEBT" },
+    { key: "bus_factor_files", label: "BUS-FACTOR-1 FILES" },
+    { key: "duplicate_clusters", label: "DUPLICATE IMPLS" },
+    { key: "ghost_exports", label: "GHOST EXPORTS" },
+    { key: "doc_lies", label: "DOC LIES" },
+];
+function scorecardRepoName(projectDir) {
+    const parts = projectDir.split(/[\\/]+/).filter(Boolean);
+    return parts.length ? parts[parts.length - 1] : projectDir;
+}
+function svgEscape(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+// 0 findings is good (green); a few is worth a look (amber); a pile is red.
+function scorecardColor(count) {
+    if (count === 0)
+        return "#1a7f37";
+    if (count < 5)
+        return "#bc4c00";
+    return "#cf222e";
+}
+function truthScorecardSvg(report) {
+    const repo = scorecardRepoName(report.project_dir);
+    const totalFindings = SCORECARD_CARDS.reduce((sum, card) => sum + (report.totals[card.key] || 0), 0);
+    const width = 820;
+    const pad = 24;
+    const gap = 16;
+    const cols = 4;
+    const cardW = Math.round((width - pad * 2 - gap * (cols - 1)) / cols);
+    const cardH = 96;
+    const gridTop = 104;
+    const rows = Math.ceil(SCORECARD_CARDS.length / cols);
+    const footerTop = gridTop + rows * cardH + (rows - 1) * gap + 20;
+    const height = footerTop + 56;
+    const subtitle = `${repo} · ${report.totals.files_scanned} files · ${report.totals.symbols_scanned} symbols scanned`;
+    const headline = report.headline
+        ? report.headline.length > 92
+            ? `${report.headline.slice(0, 89)}…`
+            : report.headline
+        : totalFindings === 0
+            ? "No surprising findings — this repo's knowledge is well distributed."
+            : `${totalFindings} knowledge risk${totalFindings === 1 ? "" : "s"} surfaced`;
+    const cards = SCORECARD_CARDS.map((card, i) => {
+        const count = report.totals[card.key] || 0;
+        const x = pad + (i % cols) * (cardW + gap);
+        const y = gridTop + Math.floor(i / cols) * (cardH + gap);
+        const cx = x + cardW / 2;
+        return [
+            `  <g>`,
+            `    <rect x="${x}" y="${y}" width="${cardW}" height="${cardH}" rx="12" fill="#ffffff" stroke="#d0d7de" stroke-width="1"/>`,
+            `    <text x="${cx}" y="${y + 50}" text-anchor="middle" font-size="34" font-weight="700" fill="${scorecardColor(count)}">${count}</text>`,
+            `    <text x="${cx}" y="${y + 76}" text-anchor="middle" font-size="10.5" font-weight="600" letter-spacing="0.8" fill="#57606a">${svgEscape(card.label)}</text>`,
+            `  </g>`,
+        ].join("\n");
+    }).join("\n");
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif">`,
+        `  <rect x="0" y="0" width="${width}" height="${height}" rx="16" fill="#0d1117"/>`,
+        `  <text x="${pad}" y="46" font-size="22" font-weight="700" fill="#41ff8f">Kage Truth Report</text>`,
+        `  <text x="${pad}" y="72" font-size="13" fill="#8b949e">${svgEscape(subtitle)}</text>`,
+        `  <text x="${pad}" y="${gridTop - 14}" font-size="13" font-weight="600" fill="#c9d1d9">${svgEscape(headline)}</text>`,
+        cards,
+        `  <text x="${pad}" y="${footerTop + 22}" font-size="12.5" fill="#8b949e">Run it on your repo:</text>`,
+        `  <text x="${pad + 130}" y="${footerTop + 22}" font-size="12.5" font-weight="600" fill="#41ff8f">npx -y @kage-core/kage-graph-mcp install</text>`,
+        `  <text x="${width - pad}" y="${footerTop + 22}" text-anchor="end" font-size="12.5" fill="#57606a">kage-core.com</text>`,
+        `</svg>`,
+    ].join("\n");
+}
+function truthScorecardMarkdown(report) {
+    const repo = scorecardRepoName(report.project_dir);
+    const totalFindings = SCORECARD_CARDS.reduce((sum, card) => sum + (report.totals[card.key] || 0), 0);
+    const rows = SCORECARD_CARDS.map((card) => {
+        const count = report.totals[card.key] || 0;
+        const mark = count === 0 ? "✅" : count < 5 ? "⚠️" : "🔴";
+        const label = card.label.toLowerCase().replace(/\b\w/g, (c) => c.toUpperCase()).replace(/\bImpls\b/, "Implementations");
+        return `| ${label} | ${count} ${mark} |`;
+    }).join("\n");
+    const headline = report.headline || (totalFindings === 0
+        ? "No surprising findings — this repo's knowledge is well distributed."
+        : `${totalFindings} knowledge risk${totalFindings === 1 ? "" : "s"} surfaced`);
+    return [
+        `## Kage Truth Report — ${repo}`,
+        ``,
+        `Scanned ${report.totals.files_scanned} files, ${report.totals.symbols_scanned} symbols.`,
+        ``,
+        `> ${headline}`,
+        ``,
+        `| Signal | Count |`,
+        `| --- | --- |`,
+        rows,
+        ``,
+        `Each signal is a place an agent loses time re-learning what your team already knows — [what these mean](https://github.com/kage-core/Kage/blob/master/docs/scorecard-metrics.md).`,
+        ``,
+        `Run it on your repo: \`npx -y @kage-core/kage-graph-mcp install\` · [kage-core.com](https://kage-core.com)`,
+        ``,
+    ].join("\n");
+}
 function defaultClaudeMemStorePath() {
     const dataDir = process.env.CLAUDE_MEM_DATA_DIR || (0, node_path_1.join)((0, node_os_1.homedir)(), ".claude-mem");
     return (0, node_path_1.join)(dataDir, "claude-mem.db");
@@ -12521,6 +13347,7 @@ function learn(input) {
         strictCitations: input.strictCitations,
         graphNodes: input.graphNodes,
         pendingReview: input.pendingReview,
+        strictContradictions: input.strictContradictions,
         discoveryTokens: input.discoveryTokens,
     });
 }
@@ -12602,7 +13429,7 @@ function capture(input) {
         freshness: {
             ttl_days: 365,
             last_verified_at: createdAt,
-            path_fingerprints: memoryPathFingerprints(input.projectDir, groundedPaths),
+            path_fingerprints: memoryPathFingerprints(input.projectDir, groundedPaths, `${input.title}\n${input.summary ?? ""}\n${input.body}`),
             path_fingerprint_policy: "source_hash_staleness",
             verification: "repo_local_agent_capture",
         },
@@ -12630,9 +13457,26 @@ function capture(input) {
     const validation = validatePacket(packet);
     if (!validation.ok)
         return { ok: false, errors: validation.errors, warnings };
+    // Memory-vs-memory contradiction detection: surface (and optionally refuse)
+    // a capture that directly opposes an existing approved packet on a shared
+    // path, instead of silently storing two conflicting facts.
+    const contradictions = detectContradictions(input.projectDir, packet);
+    if (contradictions.length && input.strictContradictions) {
+        return {
+            ok: false,
+            errors: [
+                `Contradiction blocked: this memory contradicts ${contradictions.length} existing approved ` +
+                    `packet(s): ${contradictions.map((c) => `${c.packet_id} (${c.title})`).join("; ")}. ` +
+                    `Resolve with kage supersede --packet <old> --replacement <new>, or drop --strict-contradictions to keep both.`,
+            ],
+            warnings,
+            contradictions,
+        };
+    }
     packet.quality = {
         ...packet.quality,
         ...evaluateMemoryQuality(input.projectDir, packet),
+        ...(contradictions.length ? { contradicts: contradictions.map((c) => c.packet_id) } : {}),
     };
     const path = writePacket(input.projectDir, packet, input.pendingReview ? "pending" : "packets");
     recordMemoryAudit(input.projectDir, "capture", [packet], {
@@ -12641,7 +13485,7 @@ function capture(input) {
         path: (0, node_path_1.relative)(input.projectDir, path),
         source_kind: packet.source_refs[0]?.kind ?? "explicit_capture",
     });
-    return { ok: true, packet, path, errors: [], warnings };
+    return { ok: true, packet, path, errors: [], warnings, ...(contradictions.length ? { contradictions } : {}) };
 }
 function createPublicCandidate(projectDir, id) {
     ensureMemoryDirs(projectDir);
@@ -12884,6 +13728,8 @@ PAYLOAD="$(cat || true)"
 CWD="$(printf "%s" "$PAYLOAD" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('cwd',''))" 2>/dev/null || echo "")"
 
 [[ -d "$CWD/.agent_memory" ]] || exit 0
+# Resolve a repo-local install too, so hooks work without a global kage on PATH.
+export PATH="$CWD/node_modules/.bin:$PATH"
 command -v kage >/dev/null 2>&1 || exit 0
 
 if git -C "$CWD" status --porcelain -uall >/dev/null 2>&1 && [[ -n "$(git -C "$CWD" status --porcelain -uall)" ]]; then
@@ -12940,6 +13786,8 @@ print(d.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or "")
 ' 2>/dev/null || echo "")"
 
 [[ -d "$CWD/.agent_memory" ]] || exit 0
+# Resolve a repo-local install too, so hooks work without a global kage on PATH.
+export PATH="$CWD/node_modules/.bin:$PATH"
 command -v kage >/dev/null 2>&1 || exit 0
 
 EVENT="$(PAYLOAD="$PAYLOAD" python3 -c 'import json, os
@@ -13066,6 +13914,8 @@ print(d.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or "")
 ' 2>/dev/null || echo "")"
 
 [[ -d "$CWD/.agent_memory" ]] || exit 0
+# Resolve a repo-local install too, so hooks work without a global kage on PATH.
+export PATH="$CWD/node_modules/.bin:$PATH"
 command -v kage >/dev/null 2>&1 || exit 0
 
 FILE_PATH="$(PAYLOAD="$PAYLOAD" python3 -c 'import json, os
@@ -13115,6 +13965,15 @@ fi
 
 exit 0
 `;
+        // PreToolUse(Edit/Write) — the enforcement counterpart to the Read hook. Before
+        // the agent MODIFIES a file, inject the verified memory about it (and surface what
+        // Kage is withholding as stale), so "recall before you edit" is not optional. CLI
+        // only (kage file-context), so it works even when the MCP server is not loaded.
+        const editContextHookScript = readContextHookScript
+            .replace("PreToolUse(Read) hook — injects verified file-linked memory right before the agent reads a file.", "PreToolUse(Edit/Write) hook — injects verified file-linked memory right before the agent edits a file, so recall precedes every change.")
+            .replace("Never blocks the Read.", "Never blocks the edit.")
+            .replace('STATE_DIR="/tmp/kage-read-context"', 'STATE_DIR="/tmp/kage-edit-context"')
+            .replace("never block the Read.", "never block the edit.");
         const settingsPath = (0, node_path_1.join)(home, ".claude", "settings.json");
         const hookEntry = {
             hooks: {
@@ -13124,6 +13983,9 @@ exit 0
                     { matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] },
                     // Verified memory at the moment of relevance: short timeout, never blocks the Read.
                     { matcher: "Read", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/kage-read-context.sh", timeout: 6 }] },
+                    // Enforcement: recall before an edit. Injects verified memory + withheld-stale
+                    // for the file the agent is about to change. Never blocks the edit.
+                    { matcher: "Edit|Write|MultiEdit", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/kage-edit-context.sh", timeout: 6 }] },
                 ],
                 PostToolUse: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] }],
                 PostToolUseFailure: [{ matcher: "", hooks: [{ type: "command", command: "bash ~/.claude/kage/hooks/observe.sh", timeout: 5 }] }],
@@ -13136,7 +13998,7 @@ exit 0
         setSnippet(path, JSON.stringify({ mcpServers: { kage: server } }, null, 2), [
             "Add the MCP server to ~/.claude.json, then restart Claude Code.",
             "alwaysLoad: true makes Kage tools immediately visible without requiring ToolSearch.",
-            `Also create ${hookDir}/session-start.sh, observe.sh, kage-read-context.sh, and stop.sh with the hook scripts and add SessionStart/UserPromptSubmit/PreToolUse/PostToolUse/PostToolUseFailure/PreCompact/Stop/SessionEnd hooks to ~/.claude/settings.json.`,
+            `Also create ${hookDir}/session-start.sh, observe.sh, kage-read-context.sh, kage-edit-context.sh, and stop.sh with the hook scripts and add SessionStart/UserPromptSubmit/PreToolUse/PostToolUse/PostToolUseFailure/PreCompact/Stop/SessionEnd hooks to ~/.claude/settings.json.`,
             "Run `kage init --project <repo>` inside each repo to install the ambient memory policy.",
         ], true);
         if (options.write) {
@@ -13146,6 +14008,7 @@ exit 0
             (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "session-start.sh"), hookScript, { mode: 0o755 });
             (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "observe.sh"), observeHookScript, { mode: 0o755 });
             (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "kage-read-context.sh"), readContextHookScript, { mode: 0o755 });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "kage-edit-context.sh"), editContextHookScript, { mode: 0o755 });
             (0, node_fs_1.writeFileSync)((0, node_path_1.join)(hookDir, "stop.sh"), stopHookScript, { mode: 0o755 });
             upsertJsonSettings(settingsPath, hookEntry);
             result.wrote = true;
@@ -13175,6 +14038,9 @@ exit 0
         "roo-code": (0, node_path_1.join)(home, ".roo", "mcp_settings.json"),
         "kilo-code": (0, node_path_1.join)(home, ".kilo", "mcp_settings.json"),
         "claude-desktop": (0, node_path_1.join)(home, ".config", "claude", "claude_desktop_config.json"),
+        openclaw: (0, node_path_1.join)(home, ".openclaw", "mcp.json"),
+        copilot: (0, node_path_1.join)(home, ".config", "github-copilot", "mcp.json"),
+        hermes: (0, node_path_1.join)(home, ".hermes", "mcp.json"),
         "generic-mcp": "",
     };
     setSnippet(paths[agent] || null, universal, [`Merge this MCP stdio config into ${agent}'s MCP settings.`, "Restart the agent after updating config."]);
@@ -14632,7 +15498,9 @@ function staleCatch(projectDir, changedFiles) {
                 if (current === null) {
                     invalidated.push({ packet_id: packet.id, packet_title: packet.title, cited_path: stored.path, reason: "cited file was deleted" });
                 }
-                else if (current.sha256 !== stored.sha256) {
+                else if (fingerprintPathContentChanged(projectDir, stored, fpCache)) {
+                    // Anchored memories are only invalidated when the symbols they cite change,
+                    // not when something unrelated in the same file moves.
                     invalidated.push({ packet_id: packet.id, packet_title: packet.title, cited_path: stored.path, reason: "content changed since this memory was verified" });
                 }
             }
@@ -14705,6 +15573,12 @@ function prCheck(projectDir) {
     if (reconciliation.unresolved_count > 0) {
         warnings.push(`${reconciliation.unresolved_count} memory reconciliation item(s) may need update after recent code changes (review on handoff; not blocking).`);
     }
+    // Surface unresolved memory-vs-memory contradictions (not a hard fail —
+    // resolving them is an agent/human decision via supersede or keep-both).
+    const conflicts = kageConflicts(projectDir);
+    if (conflicts.count > 0) {
+        warnings.push(`${conflicts.count} memory contradiction pair(s) unresolved — run kage conflicts, then kage supersede the wrong one (not blocking).`);
+    }
     if (!codeGraphCurrent || !memoryGraphCurrent) {
         errors.push("Generated graph artifacts are missing or not current for this working tree content.");
         requiredActions.push("Run kage refresh --project <dir> before merge.");
@@ -15733,6 +16607,141 @@ function packetSupersessionReason(packet) {
     const evidence = edge ? packetEdgeValue(edge, "evidence") : "";
     return evidence || "This memory was superseded by newer repo knowledge.";
 }
+// The whole value of generated skills is that the team shares them via git. If
+// the output dir is git-ignored, they silently won't be — so we surface it.
+function pathIsGitIgnored(projectDir, relPath) {
+    try {
+        (0, node_child_process_1.execFileSync)("git", ["-C", projectDir, "check-ignore", "-q", relPath], { stdio: "ignore" });
+        return true; // exit 0 = path is ignored
+    }
+    catch {
+        return false; // non-zero = not ignored (or not a git repo)
+    }
+}
+// A SKILL.md is a reusable *procedure*. Runbooks and workflows are procedures by
+// nature; rationale-only decisions and per-diff change-memory are not skills.
+const SKILL_ELIGIBLE_TYPES = ["runbook", "workflow"];
+// Auto-distilled junk sometimes lands a raw hook/tool payload as a "runbook".
+// Those must never become skills the agent loads as instructions.
+const SKILL_PAYLOAD_MARKERS = [
+    "task-notification", "tool-use-id", "toolu_", "hookspecificoutput",
+    "nooutputexpected", "isimage", "stop_hook_active", '"interrupted"', "interrupted:",
+];
+function looksLikePayloadMemory(packet) {
+    const haystack = `${packet.title} ${packet.summary} ${packet.body}`.toLowerCase();
+    return SKILL_PAYLOAD_MARKERS.some((marker) => haystack.includes(marker));
+}
+function packetSkillBody(packet) {
+    const ctx = packet.context ?? {};
+    const lines = [`# ${packet.title}`, ""];
+    if (packet.summary)
+        lines.push(packet.summary, "");
+    if (ctx.fact && ctx.fact !== packet.summary)
+        lines.push(ctx.fact, "");
+    if (ctx.why)
+        lines.push(`**Why it matters:** ${ctx.why}`, "");
+    if (ctx.trigger)
+        lines.push(`**Use this when:** ${ctx.trigger}`, "");
+    if (ctx.action)
+        lines.push("## What to do", "", ctx.action, "");
+    else if (packet.body && packet.body !== packet.summary)
+        lines.push("## Detail", "", packet.body.trim(), "");
+    if (ctx.verification)
+        lines.push("## Verify", "", ctx.verification, "");
+    if (ctx.risk_if_forgotten)
+        lines.push(`**If you skip this:** ${ctx.risk_if_forgotten}`, "");
+    const citedPaths = (packet.paths ?? []).filter((p) => meaningfulMemoryPath(p));
+    if (citedPaths.length) {
+        lines.push("## Grounded in", "");
+        for (const p of citedPaths.slice(0, 12))
+            lines.push(`- \`${p}\``);
+        lines.push("");
+    }
+    lines.push("---", `_Generated by \`kage skills\` from verified repo memory (packet \`${packet.id}\`). Checked against the code it cites; regenerate with \`kage skills\`._`);
+    return lines.join("\n");
+}
+function skillDescription(packet) {
+    const ctx = packet.context ?? {};
+    const base = (packet.summary || ctx.fact || packet.title).replace(/\s+/g, " ").trim();
+    const when = ctx.trigger ? ` Use when: ${ctx.trigger.replace(/\s+/g, " ").trim()}` : "";
+    const full = `${base}${when}`;
+    return full.length > 480 ? `${full.slice(0, 477)}...` : full;
+}
+// A packet earns a skill only if it is a genuine, self-contained procedure:
+// right type, not a per-diff change-memory packet, not a leaked payload, and
+// carrying an actual action or a substantive body.
+function isSkillWorthy(packet) {
+    if (!SKILL_ELIGIBLE_TYPES.includes(packet.type))
+        return false;
+    if (isGeneratedChangeMemory(packet))
+        return false;
+    if (looksLikePayloadMemory(packet))
+        return false;
+    const ctx = packet.context ?? {};
+    const hasProcedure = Boolean(ctx.action) || (packet.body ?? "").trim().length >= 120;
+    return hasProcedure;
+}
+function generateSkills(projectDir, options = {}) {
+    ensureMemoryDirs(projectDir);
+    const dryRun = options.dryRun === true;
+    const relDir = options.dir ?? (0, node_path_1.join)(".claude", "skills");
+    const result = {
+        ok: true,
+        project_dir: projectDir,
+        dir: relDir,
+        dry_run: dryRun,
+        generated: [],
+        skipped: [],
+        total_eligible: 0,
+        git_ignored: pathIsGitIgnored(projectDir, relDir),
+        errors: [],
+    };
+    const cache = new Map();
+    const candidates = loadApprovedPackets(projectDir)
+        .filter((packet) => SKILL_ELIGIBLE_TYPES.includes(packet.type))
+        .sort((a, b) => a.title.localeCompare(b.title));
+    const usedSlugs = new Set();
+    for (const packet of candidates) {
+        if (!isSkillWorthy(packet)) {
+            result.skipped.push({ title: packet.title, reason: "no actionable procedure (rationale-only)" });
+            continue;
+        }
+        const staleReason = recallStaleReason(projectDir, packet, cache);
+        if (staleReason) {
+            result.skipped.push({ title: packet.title, reason: `not grounded: ${staleReason}` });
+            continue;
+        }
+        result.total_eligible += 1;
+        let slug = slugify(packet.title).slice(0, 60).replace(/-+$/, "") || `skill-${result.total_eligible}`;
+        while (usedSlugs.has(slug))
+            slug = `${slug}-2`;
+        usedSlugs.add(slug);
+        const skillDir = (0, node_path_1.join)(projectDir, relDir, slug);
+        const skillPath = (0, node_path_1.join)(skillDir, "SKILL.md");
+        const content = [
+            "---",
+            `name: ${slug}`,
+            `description: ${skillDescription(packet).replace(/\n/g, " ")}`,
+            "---",
+            "",
+            packetSkillBody(packet),
+            "",
+        ].join("\n");
+        if (!dryRun) {
+            try {
+                (0, node_fs_1.mkdirSync)(skillDir, { recursive: true });
+                (0, node_fs_1.writeFileSync)(skillPath, content, "utf8");
+            }
+            catch (error) {
+                result.errors.push(`failed to write ${slug}: ${error.message}`);
+                continue;
+            }
+        }
+        result.generated.push({ slug, title: packet.title, path: (0, node_path_1.join)(relDir, slug, "SKILL.md"), packet_id: packet.id, type: packet.type });
+    }
+    result.ok = result.errors.length === 0;
+    return result;
+}
 // Re-verify a still-true packet in place: re-check cited paths, refresh
 // fingerprints and last_verified_at, and clear stale flags. The alternative to
 // supersede churn when code changed but the memory's claim did not. Refuses
@@ -15770,7 +16779,7 @@ function reverifyMemory(projectDir, packetId) {
     const presentPaths = citedPaths.filter((path) => !result.missing_paths.includes(path));
     const now = nowIso();
     const freshness = { ...(packet.freshness ?? {}) };
-    freshness.path_fingerprints = memoryPathFingerprints(projectDir, presentPaths);
+    freshness.path_fingerprints = memoryPathFingerprints(projectDir, presentPaths, `${packet.title}\n${packet.summary}\n${packet.body}`);
     freshness.last_verified_at = now;
     const { stale: _stale, stale_reasons: _staleReasons, suggested_action: _suggestedAction, ...nextQuality } = quality;
     writeJson(entry.path, {
@@ -15840,8 +16849,35 @@ function supersedeMemory(projectDir, oldPacketId, replacementPacketId, reason =
     upsertPacketEdge(oldPacket, "superseded_by", replacementPacket.id, trimmedReason, at);
     replacementPacket.updated_at = at;
     upsertPacketEdge(replacementPacket, "supersedes", oldPacket.id, trimmedReason, at);
+    // Superseding resolves any recorded contradiction involving the retired
+    // packet: drop the old id from every other packet's quality.contradicts, and
+    // clear the old packet's own contradicts list (it is no longer live memory).
+    const clearContradiction = (packet) => {
+        const quality = (packet.quality ?? {});
+        const existing = Array.isArray(quality.contradicts) ? quality.contradicts : [];
+        if (!existing.length)
+            return false;
+        const next = existing.filter((id) => id !== oldPacket.id && id !== replacementPacket.id);
+        if (next.length === existing.length)
+            return false;
+        if (next.length)
+            quality.contradicts = next;
+        else
+            delete quality.contradicts;
+        packet.quality = quality;
+        packet.updated_at = at;
+        return true;
+    };
+    clearContradiction(oldPacket);
+    clearContradiction(replacementPacket);
     writeJson(oldEntry.path, oldPacket);
     writeJson(replacementEntry.path, replacementPacket);
+    for (const entry of entries) {
+        if (entry.packet.id === oldPacket.id || entry.packet.id === replacementPacket.id)
+            continue;
+        if (clearContradiction(entry.packet))
+            writeJson(entry.path, entry.packet);
+    }
     recordMemoryAudit(projectDir, "supersede", [oldPacket, replacementPacket], {
         old_packet_id: oldPacket.id,
         replacement_packet_id: replacementPacket.id,
@@ -16155,7 +17191,7 @@ function personalRecallEntries(projectDir, terms, limit = 3) {
     if (!packets.length)
         return [];
     const cache = new Map();
-    const eligible = packets.filter((packet) => recallHardStaleReason(projectDir, packet, cache) === null);
+    const eligible = packets.filter((packet) => recallStaleReason(projectDir, packet, cache) === null);
     if (!eligible.length)
         return [];
     const scores = scorePacketsBm25(terms, eligible);
@@ -16507,3 +17543,36 @@ function syncPersonal() {
     result.ok = true;
     return result;
 }
+// Kage's memory is hierarchical by construction:
+//   L0 raw       — session observations captured by hooks (unreviewed signal)
+//   L1 reviewed  — verified memory packets (the trusted store)
+//   L2 synthesis — generated overviews: repo maps, project profile, branch/change summaries
+// This surfaces that existing structure rather than inventing a field.
+function kageLayers(projectDir) {
+    const L2_TYPES = new Set(["repo_map"]);
+    const isSynthesis = (p) => {
+        const q = (p.quality ?? {});
+        return L2_TYPES.has(p.type) || q.candidate_kind === "change_memory";
+    };
+    const entries = (0, node_fs_1.existsSync)(packetsDir(projectDir)) ? loadPacketEntriesFromDir(packetsDir(projectDir)) : [];
+    const l2 = entries.filter((e) => isSynthesis(e.packet));
+    const l1 = entries.filter((e) => !isSynthesis(e.packet));
+    let observationCount = 0;
+    const obsDir = observationsDir(projectDir);
+    if ((0, node_fs_1.existsSync)(obsDir)) {
+        try {
+            observationCount = (0, node_fs_1.readdirSync)(obsDir).filter((f) => f.endsWith(".jsonl") || f.endsWith(".json")).length;
+        }
+        catch {
+            observationCount = 0;
+        }
+    }
+    return {
+        project_dir: projectDir,
+        layers: [
+            { layer: "L0", label: "Raw observations", description: "Session signal captured by hooks; unreviewed, feeds auto-distill.", count: observationCount, examples: [] },
+            { layer: "L1", label: "Reviewed memory", description: "Verified packets — cited, fingerprinted, the trusted recall store.", count: l1.length, examples: l1.slice(0, 3).map((e) => e.packet.title) },
+            { layer: "L2", label: "Synthesis", description: "Generated overviews: repo maps and branch/change summaries.", count: l2.length, examples: l2.slice(0, 3).map((e) => e.packet.title) },
+        ],
+    };
+}