gitmem-mcp 1.4.4 → 1.6.0

package/dist/commands/deactivate.d.ts

@@ -0,0 +1,10 @@
+/**
+ * GitMem Pro Deactivation
+ *
+ * 1. Calls gitmem_deactivate_device RPC to remove this device server-side
+ * 2. Removes api_key, supabase_url, supabase_key, openrouter_key from config.json
+ * 3. Deletes license-cache.json
+ * Does NOT remove .gitmem/ directory or local data.
+ */
+export declare function main(_args: string[]): Promise<void>;
+//# sourceMappingURL=deactivate.d.ts.map

package/dist/commands/deactivate.js

@@ -0,0 +1,95 @@
+/**
+ * GitMem Pro Deactivation
+ *
+ * 1. Calls gitmem_deactivate_device RPC to remove this device server-side
+ * 2. Removes api_key, supabase_url, supabase_key, openrouter_key from config.json
+ * 3. Deletes license-cache.json
+ * Does NOT remove .gitmem/ directory or local data.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { getGitmemDir, getInstallId } from "../services/gitmem-dir.js";
+import { clearLicenseCache, getLicenseKey, getValidationUrl, } from "../services/license.js";
+// Same infra endpoint as validation — just different RPC
+const DEACTIVATION_URL = getValidationUrl().replace("gitmem_validate_license", "gitmem_deactivate_device");
+const VALIDATION_ANON_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImNqcHR4eWV6dXhkaWludWZncnJtIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjYxODY3MDMsImV4cCI6MjA4MTc2MjcwM30.L0oZy3LYCMikmZ15IUU5DnfJmucM37DJ14nUkM3AreY";
+async function deactivateDeviceRemote(apiKey, installId) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 10000);
+        const response = await fetch(DEACTIVATION_URL, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                apikey: VALIDATION_ANON_KEY,
+                Authorization: `Bearer ${VALIDATION_ANON_KEY}`,
+            },
+            body: JSON.stringify({ p_api_key: apiKey, p_install_id: installId }),
+            signal: controller.signal,
+        });
+        clearTimeout(timeout);
+        if (!response.ok) {
+            return { success: false, message: `HTTP ${response.status}` };
+        }
+        const rows = (await response.json());
+        const data = Array.isArray(rows) ? rows[0] : rows;
+        return data || { success: false, message: "Empty response" };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Unknown error";
+        return { success: false, message: `Network error: ${message}` };
+    }
+}
+export async function main(_args) {
+    const gitmemDir = getGitmemDir();
+    const configPath = path.join(gitmemDir, "config.json");
+    if (!fs.existsSync(configPath)) {
+        console.log("No config.json found — nothing to deactivate.");
+        return;
+    }
+    let config = {};
+    try {
+        config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        console.error("Error reading config.json");
+        process.exit(1);
+    }
+    const apiKey = getLicenseKey();
+    const installId = getInstallId();
+    const hadKey = !!apiKey;
+    // Step 1: Remove device server-side (if we have both key and install_id)
+    if (apiKey && installId) {
+        const result = await deactivateDeviceRemote(apiKey, installId);
+        if (result.success) {
+            console.log(`  ✓ ${result.message}`);
+        }
+        else {
+            console.log(`  ⚠ Server deactivation failed: ${result.message}`);
+            console.log("    Local credentials will still be removed.");
+        }
+    }
+    // Step 2: Remove Pro credentials from config
+    delete config.api_key;
+    delete config.supabase_url;
+    delete config.supabase_key;
+    delete config.openrouter_key;
+    // Write back config (preserving project, install_id, feedback_enabled)
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+    // Step 3: Clear license cache
+    clearLicenseCache();
+    if (hadKey) {
+        console.log("\nPro tier deactivated.");
+        console.log("  - Device removed from license server");
+        console.log("  - License key removed from config.json");
+        console.log("  - Supabase and OpenRouter credentials removed");
+        console.log("  - License cache cleared");
+        console.log("");
+        console.log("Local data in .gitmem/ is preserved (scars, threads, sessions).");
+        console.log("Restart your editor to switch to free tier.");
+    }
+    else {
+        console.log("No active Pro license found. Already on free tier.");
+    }
+}
+//# sourceMappingURL=deactivate.js.map

package/dist/commands/migrate-local.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Local-to-Supabase Migration
+ *
+ * Migrates existing free-tier local .gitmem/ data to Supabase when
+ * a user upgrades to Pro. Called during `activate` after schema is
+ * verified and credentials are saved.
+ *
+ * Collections migrated:
+ *   - learnings (scars, wins, patterns, anti-patterns)
+ *   - sessions
+ *   - decisions
+ *   - scar_usage
+ *
+ * Threads are NOT migrated — they remain local (thread lifecycle is
+ * tied to .gitmem/threads.json and managed by session_start).
+ *
+ * Migration is idempotent: uses Supabase upsert (merge-duplicates)
+ * so re-running is safe. Existing Supabase records with same ID are
+ * updated, not duplicated.
+ */
+export interface MigrationResult {
+    migrated: Record<string, number>;
+    skipped: Record<string, number>;
+    errors: Record<string, string[]>;
+    total: number;
+    hasLocalData: boolean;
+}
+/**
+ * Check if there is local data worth migrating
+ */
+export declare function hasLocalData(gitmemDir?: string): boolean;
+/**
+ * Migrate local .gitmem data to Supabase
+ *
+ * @param supabaseUrl - User's Supabase project URL
+ * @param supabaseKey - User's service role key
+ * @param tablePrefix - Table prefix (default: "gitmem_")
+ * @param gitmemDir   - Override .gitmem directory path
+ * @param onProgress  - Callback for progress reporting
+ */
+export declare function migrateLocalToSupabase(opts: {
+    supabaseUrl: string;
+    supabaseKey: string;
+    tablePrefix?: string;
+    gitmemDir?: string;
+    onProgress?: (msg: string) => void;
+}): Promise<MigrationResult>;
+/**
+ * Rename local collection files after successful migration
+ * Adds .pre-migration suffix so data isn't lost but won't be re-read by free tier
+ */
+export declare function archiveLocalData(gitmemDir?: string): string[];
+//# sourceMappingURL=migrate-local.d.ts.map

package/dist/commands/migrate-local.js

@@ -0,0 +1,177 @@
+/**
+ * Local-to-Supabase Migration
+ *
+ * Migrates existing free-tier local .gitmem/ data to Supabase when
+ * a user upgrades to Pro. Called during `activate` after schema is
+ * verified and credentials are saved.
+ *
+ * Collections migrated:
+ *   - learnings (scars, wins, patterns, anti-patterns)
+ *   - sessions
+ *   - decisions
+ *   - scar_usage
+ *
+ * Threads are NOT migrated — they remain local (thread lifecycle is
+ * tied to .gitmem/threads.json and managed by session_start).
+ *
+ * Migration is idempotent: uses Supabase upsert (merge-duplicates)
+ * so re-running is safe. Existing Supabase records with same ID are
+ * updated, not duplicated.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { getGitmemDir } from "../services/gitmem-dir.js";
+/** Collections that map to Supabase tables */
+const MIGRATABLE_COLLECTIONS = ["learnings", "sessions", "decisions", "scar_usage"];
+/** Fields that should NOT be sent to Supabase (local-only or computed) */
+const STRIP_FIELDS = new Set(["is_starter"]);
+/** Fields that Supabase will reject if null (remove instead of sending null) */
+const NULLABLE_STRIP = new Set(["embedding"]);
+/**
+ * Check if there is local data worth migrating
+ */
+export function hasLocalData(gitmemDir) {
+    const dir = gitmemDir || getGitmemDir();
+    for (const collection of MIGRATABLE_COLLECTIONS) {
+        const filePath = path.join(dir, `${collection}.json`);
+        if (fs.existsSync(filePath)) {
+            try {
+                const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+                if (Array.isArray(data) && data.length > 0)
+                    return true;
+            }
+            catch {
+                // Corrupt file — skip
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Read a local collection JSON file
+ */
+function readLocalCollection(dir, collection) {
+    const filePath = path.join(dir, `${collection}.json`);
+    if (!fs.existsSync(filePath))
+        return [];
+    try {
+        const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        return Array.isArray(data) ? data : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Clean a record for Supabase insertion:
+ * - Strip local-only fields
+ * - Remove null values for non-nullable columns
+ * - Ensure id exists
+ */
+function cleanRecord(record) {
+    if (!record.id)
+        return null;
+    const cleaned = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (STRIP_FIELDS.has(key))
+            continue;
+        if (NULLABLE_STRIP.has(key) && (value === null || value === undefined))
+            continue;
+        cleaned[key] = value;
+    }
+    return cleaned;
+}
+/**
+ * Migrate local .gitmem data to Supabase
+ *
+ * @param supabaseUrl - User's Supabase project URL
+ * @param supabaseKey - User's service role key
+ * @param tablePrefix - Table prefix (default: "gitmem_")
+ * @param gitmemDir   - Override .gitmem directory path
+ * @param onProgress  - Callback for progress reporting
+ */
+export async function migrateLocalToSupabase(opts) {
+    const { supabaseUrl, supabaseKey, tablePrefix = "gitmem_", onProgress } = opts;
+    const dir = opts.gitmemDir || getGitmemDir();
+    const log = onProgress || ((msg) => console.log(msg));
+    const result = {
+        migrated: {},
+        skipped: {},
+        errors: {},
+        total: 0,
+        hasLocalData: false,
+    };
+    const restUrl = `${supabaseUrl}/rest/v1`;
+    for (const collection of MIGRATABLE_COLLECTIONS) {
+        const records = readLocalCollection(dir, collection);
+        const tableName = `${tablePrefix}${collection}`;
+        result.migrated[collection] = 0;
+        result.skipped[collection] = 0;
+        result.errors[collection] = [];
+        if (records.length === 0)
+            continue;
+        result.hasLocalData = true;
+        log(`  Migrating ${records.length} ${collection}...`);
+        for (const record of records) {
+            const cleaned = cleanRecord(record);
+            if (!cleaned) {
+                result.skipped[collection]++;
+                continue;
+            }
+            try {
+                const response = await fetch(`${restUrl}/${tableName}`, {
+                    method: "POST",
+                    headers: {
+                        "apikey": supabaseKey,
+                        "Authorization": `Bearer ${supabaseKey}`,
+                        "Content-Type": "application/json",
+                        "Prefer": "return=minimal,resolution=merge-duplicates",
+                        "Content-Profile": "public",
+                    },
+                    body: JSON.stringify(cleaned),
+                    signal: AbortSignal.timeout(10_000),
+                });
+                if (response.ok) {
+                    result.migrated[collection]++;
+                }
+                else {
+                    const text = await response.text();
+                    // Only log first 3 errors per collection to avoid spam
+                    if (result.errors[collection].length < 3) {
+                        result.errors[collection].push(`${String(cleaned.id).substring(0, 8)}: ${response.status} - ${text.substring(0, 100)}`);
+                    }
+                    result.skipped[collection]++;
+                }
+            }
+            catch (err) {
+                if (result.errors[collection].length < 3) {
+                    result.errors[collection].push(`${String(cleaned.id).substring(0, 8)}: ${err instanceof Error ? err.message : "Unknown error"}`);
+                }
+                result.skipped[collection]++;
+            }
+            result.total++;
+        }
+    }
+    return result;
+}
+/**
+ * Rename local collection files after successful migration
+ * Adds .pre-migration suffix so data isn't lost but won't be re-read by free tier
+ */
+export function archiveLocalData(gitmemDir) {
+    const dir = gitmemDir || getGitmemDir();
+    const archived = [];
+    for (const collection of MIGRATABLE_COLLECTIONS) {
+        const filePath = path.join(dir, `${collection}.json`);
+        if (fs.existsSync(filePath)) {
+            const archivePath = `${filePath}.pre-migration`;
+            // Don't overwrite existing archive
+            if (!fs.existsSync(archivePath)) {
+                fs.renameSync(filePath, archivePath);
+                archived.push(collection);
+            }
+        }
+    }
+    return archived;
+}
+//# sourceMappingURL=migrate-local.js.map

package/dist/hooks/format-utils.js

@@ -57,6 +57,10 @@ export function formatCompact(scars, plan, maxTokens) {
         lines.push(line);
         included++;
     }
+    // Citation reminder for sub-agent context (compact — one line)
+    if (included > 0) {
+        lines.push("Cite record IDs for any factual claims from these scars.");
+    }
     return { payload: lines.join("\n"), included };
 }
 /**

package/dist/schemas/log.d.ts

@@ -13,14 +13,14 @@ export declare const LogParamsSchema: z.ZodObject<{
     since: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     limit?: number | undefined;
-    project?: string | undefined;
     learning_type?: "scar" | "win" | "pattern" | "anti_pattern" | undefined;
+    project?: string | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;
     since?: number | undefined;
 }, {
     limit?: number | undefined;
-    project?: string | undefined;
     learning_type?: "scar" | "win" | "pattern" | "anti_pattern" | undefined;
+    project?: string | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;
     since?: number | undefined;
 }>;

package/dist/schemas/search.d.ts

@@ -14,14 +14,14 @@ export declare const SearchParamsSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     query: string;
     match_count?: number | undefined;
-    project?: string | undefined;
     learning_type?: "scar" | "win" | "pattern" | "anti_pattern" | undefined;
+    project?: string | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;
 }, {
     query: string;
     match_count?: number | undefined;
-    project?: string | undefined;
     learning_type?: "scar" | "win" | "pattern" | "anti_pattern" | undefined;
+    project?: string | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;
 }>;
 export type SearchParams = z.infer<typeof SearchParamsSchema>;

package/dist/schemas/session-close.d.ts

@@ -20,20 +20,20 @@ export declare const ClosingReflectionSchema: z.ZodObject<{
     rapport_notes: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodArray<z.ZodString, "many">, string, string[]>]>>;
 }, "strip", z.ZodTypeAny, {
     what_broke: string;
-    what_took_longer: string;
-    do_differently: string;
     what_worked: string;
     wrong_assumption: string;
+    do_differently: string;
+    what_took_longer: string;
     scars_applied: string | string[];
     institutional_memory_items?: string | undefined;
     collaborative_dynamic?: string | undefined;
     rapport_notes?: string | undefined;
 }, {
     what_broke: string;
-    what_took_longer: string;
-    do_differently: string;
     what_worked: string;
     wrong_assumption: string;
+    do_differently: string;
+    what_took_longer: string;
     scars_applied: string | string[];
     institutional_memory_items?: string | string[] | undefined;
     collaborative_dynamic?: string | string[] | undefined;
@@ -161,20 +161,20 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
         rapport_notes: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodEffects<z.ZodArray<z.ZodString, "many">, string, string[]>]>>;
     }, "strip", z.ZodTypeAny, {
         what_broke: string;
-        what_took_longer: string;
-        do_differently: string;
         what_worked: string;
         wrong_assumption: string;
+        do_differently: string;
+        what_took_longer: string;
         scars_applied: string | string[];
         institutional_memory_items?: string | undefined;
         collaborative_dynamic?: string | undefined;
         rapport_notes?: string | undefined;
     }, {
         what_broke: string;
-        what_took_longer: string;
-        do_differently: string;
         what_worked: string;
         wrong_assumption: string;
+        do_differently: string;
+        what_took_longer: string;
         scars_applied: string | string[];
         institutional_memory_items?: string | string[] | undefined;
         collaborative_dynamic?: string | string[] | undefined;
@@ -281,10 +281,10 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
     linear_issue?: string | undefined;
     closing_reflection?: {
         what_broke: string;
-        what_took_longer: string;
-        do_differently: string;
         what_worked: string;
         wrong_assumption: string;
+        do_differently: string;
+        what_took_longer: string;
         scars_applied: string | string[];
         institutional_memory_items?: string | undefined;
         collaborative_dynamic?: string | undefined;
@@ -338,10 +338,10 @@ export declare const SessionCloseParamsSchema: z.ZodObject<{
     linear_issue?: string | undefined;
     closing_reflection?: {
         what_broke: string;
-        what_took_longer: string;
-        do_differently: string;
         what_worked: string;
         wrong_assumption: string;
+        do_differently: string;
+        what_took_longer: string;
         scars_applied: string | string[];
         institutional_memory_items?: string | string[] | undefined;
         collaborative_dynamic?: string | string[] | undefined;

package/dist/server.js

@@ -36,12 +36,16 @@ import { dismissSuggestion } from "./tools/dismiss-suggestion.js";
 import { cleanupThreads } from "./tools/cleanup-threads.js";
 import { archiveLearning } from "./tools/archive-learning.js";
 import { contributeFeedback } from "./tools/contribute-feedback.js";
+import { indexDocs } from "./tools/index-docs.js";
+import { searchDocsHandler } from "./tools/search-docs.js";
 import { getCacheStatus, checkCacheHealth, flushCache, startBackgroundInit, } from "./services/startup.js";
 import { getEffectTracker } from "./services/effect-tracker.js";
 import { RIPPLE, ANSI } from "./services/display-protocol.js";
 import { getProject } from "./services/session-state.js";
 import { checkEnforcement } from "./services/enforcement.js";
-import { getTier, hasSupabase, hasCacheManagement, hasBatchOperations, hasTranscripts, } from "./services/tier.js";
+import { getTier, setTier, hasSupabase, hasCacheManagement, hasBatchOperations, hasTranscripts, } from "./services/tier.js";
+import { getLicenseKey, validateLicense } from "./services/license.js";
+import { getInstallId } from "./services/gitmem-dir.js";
 import { getRegisteredTools } from "./tools/definitions.js";
 import { validateToolArgs } from "./schemas/registry.js";
 /**
@@ -246,6 +250,8 @@ export function createServer() {
                         { alias: "gitmem-al", full: "archive_learning", description: "Archive a scar/win/pattern (is_active=false)" },
                         { alias: "gitmem-graph", full: "graph_traverse", description: "Traverse knowledge graph over institutional memory" },
                         { alias: "gitmem-fb", full: "contribute_feedback", description: "Submit feedback about gitmem (10/session limit)" },
+                        { alias: "gitmem-idx", full: "index_docs", description: "Index markdown docs for semantic search" },
+                        { alias: "gitmem-sd", full: "search_docs", description: "Search indexed repository docs" },
                     ];
                     if (hasBatchOperations()) {
                         commands.push({ alias: "gitmem-rsb", full: "record_scar_usage_batch", description: "Track multiple scars (batch)" });
@@ -315,6 +321,15 @@ export function createServer() {
                 case "gm-cache-f":
                     result = await flushCache(toolArgs.project || getProject() || "default");
                     break;
+                // Doc indexing and search
+                case "index_docs":
+                case "gitmem-idx":
+                    result = await indexDocs(toolArgs);
+                    break;
+                case "search_docs":
+                case "gitmem-sd":
+                    result = await searchDocsHandler(toolArgs);
+                    break;
                 default:
                     throw new Error(`Unknown tool: ${name}`);
             }
@@ -380,13 +395,29 @@ export function createServer() {
  */
 export async function runServer() {
     const tier = getTier();
-    // Start server immediately (don't block on cache loading)
+    // Start server immediately (don't block on cache loading or license validation)
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     const toolCount = getRegisteredTools().length;
     const storage = hasSupabase() ? "supabase" : "local";
     console.error(`[gitmem] Tier: ${tier} | Storage: ${storage} | Tools: ${toolCount}`);
+    // Async license validation (non-blocking)
+    const apiKey = getLicenseKey();
+    if (apiKey) {
+        const installId = getInstallId() || "unknown";
+        validateLicense(apiKey, installId).then((result) => {
+            if (!result.valid) {
+                console.error(`[gitmem:license] Validation failed: ${result.message}`);
+                setTier("free");
+            }
+            else {
+                console.error(`[gitmem:license] Validated: ${result.tier} tier`);
+            }
+        }).catch((err) => {
+            console.error(`[gitmem:license] Validation error: ${err}`);
+        });
+    }
     if (hasSupabase()) {
         // Pro/Dev: Initialize local vector search in background (non-blocking)
         // This loads scars with embeddings directly from Supabase REST API

package/dist/services/analytics.d.ts

@@ -173,6 +173,28 @@ export declare function aggregateClosingReflections(sessions: SessionRecord[], m
     wrong_assumptions: ReflectionCategory;
     do_differently: ReflectionCategory;
 };
+/**
+ * Lightweight summary for session_start Pro insights.
+ * Returns a compact object with key 30-day metrics.
+ */
+export interface LightweightSummary {
+    total_sessions: number;
+    scars_surfaced: number;
+    scars_applied: number;
+    application_rate: number;
+    top_blindspot: {
+        title: string;
+        ignore_rate: string;
+        times: string;
+    } | null;
+}
+export declare function computeLightweightSummary(sessions: SessionRecord[], usages: ScarUsageRecord[]): LightweightSummary;
+/**
+ * Format blindspot snippet for session_close display.
+ * Returns 2-3 lines showing top 2 most-ignored scars, or null if none qualify.
+ * Threshold: ignore_rate > 50%, surfaced >= 3 times.
+ */
+export declare function formatBlindspotSnippet(usages: ScarUsageRecord[]): string | null;
 /**
  * Format summary analytics as compact markdown.
  */

package/dist/services/analytics.js

@@ -356,6 +356,74 @@ export function aggregateClosingReflections(sessions, maxPerCategory = 30, maxTe
         do_differently: truncate(all.do_differently),
     };
 }
+export function computeLightweightSummary(sessions, usages) {
+    const totalSessions = sessions.length;
+    const scarsSurfaced = new Set(usages.map(u => u.scar_id)).size;
+    const applied = usages.filter(u => u.reference_type !== "none").length;
+    const applicationRate = usages.length > 0 ? applied / usages.length : 0;
+    // Find top blindspot: most-ignored scar with >= 3 surfacings
+    const scarGroups = new Map();
+    for (const u of usages) {
+        const entry = scarGroups.get(u.scar_id) || { title: u.scar_title || "Unknown", surfaced: 0, dismissed: 0 };
+        entry.surfaced++;
+        if (u.reference_type === "none")
+            entry.dismissed++;
+        if (u.scar_title)
+            entry.title = u.scar_title;
+        scarGroups.set(u.scar_id, entry);
+    }
+    let topBlindspot = null;
+    let highestIgnoreRate = 0;
+    for (const [, stats] of scarGroups) {
+        if (stats.surfaced >= 3) {
+            const rate = stats.dismissed / stats.surfaced;
+            if (rate > highestIgnoreRate && rate > 0.5) {
+                highestIgnoreRate = rate;
+                topBlindspot = {
+                    title: stats.title,
+                    ignore_rate: `${Math.round(rate * 100)}%`,
+                    times: `${stats.dismissed}/${stats.surfaced}`,
+                };
+            }
+        }
+    }
+    return {
+        total_sessions: totalSessions,
+        scars_surfaced: scarsSurfaced,
+        scars_applied: applied,
+        application_rate: applicationRate,
+        top_blindspot: topBlindspot,
+    };
+}
+/**
+ * Format blindspot snippet for session_close display.
+ * Returns 2-3 lines showing top 2 most-ignored scars, or null if none qualify.
+ * Threshold: ignore_rate > 50%, surfaced >= 3 times.
+ */
+export function formatBlindspotSnippet(usages) {
+    const scarGroups = new Map();
+    for (const u of usages) {
+        const entry = scarGroups.get(u.scar_id) || { title: u.scar_title || "Unknown", surfaced: 0, dismissed: 0 };
+        entry.surfaced++;
+        if (u.reference_type === "none")
+            entry.dismissed++;
+        if (u.scar_title)
+            entry.title = u.scar_title;
+        scarGroups.set(u.scar_id, entry);
+    }
+    const blindspots = Array.from(scarGroups.values())
+        .filter(s => s.surfaced >= 3 && (s.dismissed / s.surfaced) > 0.5)
+        .sort((a, b) => (b.dismissed / b.surfaced) - (a.dismissed / a.surfaced))
+        .slice(0, 2);
+    if (blindspots.length === 0)
+        return null;
+    const lines = ["Blindspots (30d)"];
+    for (const b of blindspots) {
+        const pct = Math.round((b.dismissed / b.surfaced) * 100);
+        lines.push(`  "${b.title}" — ignored ${pct}% (${b.dismissed}/${b.surfaced} times)`);
+    }
+    return lines.join("\n");
+}
 // --- Formatters ---
 /**
  * Format summary analytics as compact markdown.