@velvetmonkey/flywheel-memory 2.0.33 → 2.0.35

package/dist/index.js

@@ -832,7 +832,8 @@ function createContext(variables = {}) {
       today: formatDate2(now),
       time: formatTime(now),
       date: formatDate2(now)
-    }
+    },
+    steps: {}
   };
 }
 function resolvePath(obj, path30) {
@@ -878,6 +879,9 @@ function resolveExpression(expr, context) {
   if (trimmed.startsWith("builtins.")) {
     return resolvePath(context.builtins, trimmed.slice("builtins.".length));
   }
+  if (trimmed.startsWith("steps.")) {
+    return resolvePath(context.steps, trimmed.slice("steps.".length));
+  }
   return resolvePath(context.variables, trimmed);
 }
 function interpolate(template, context) {
@@ -1056,7 +1060,7 @@ function validatePolicySchema(policy) {
         const match = ref.match(/\{\{(?:variables\.)?(\w+)/);
         if (match) {
           const varName = match[1];
-          if (["now", "today", "time", "date", "conditions"].includes(varName)) {
+          if (["now", "today", "time", "date", "conditions", "steps"].includes(varName)) {
             continue;
           }
           if (!varNames.has(varName)) {
@@ -1549,6 +1553,9 @@ var init_taskHelpers = __esm({
 
 // src/index.ts
 import * as path29 from "path";
+import { readFileSync as readFileSync4, realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname as dirname4, join as join16 } from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -2260,7 +2267,10 @@ async function buildVaultIndexInternal(vaultPath2, startTime, onProgress) {
     }
   }
   if (parseErrors.length > 0) {
-    console.error(`Failed to parse ${parseErrors.length} files`);
+    console.error(`Failed to parse ${parseErrors.length} files:`);
+    for (const errorPath of parseErrors) {
+      console.error(`  - ${errorPath}`);
+    }
   }
   const entities = /* @__PURE__ */ new Map();
   for (const note of notes.values()) {
@@ -2487,7 +2497,10 @@ var DEFAULT_CONFIG = {
   exclude_task_tags: [],
   exclude_analysis_tags: [],
   exclude_entities: [],
-  exclude_entity_folders: []
+  exclude_entity_folders: [],
+  wikilink_strictness: "balanced",
+  implicit_detection: true,
+  adaptive_strictness: true
 };
 function loadConfig(stateDb2) {
   if (stateDb2) {
@@ -3238,9 +3251,14 @@ var FEEDBACK_BOOST_TIERS = [
   { minAccuracy: 0, minSamples: 5, boost: -4 }
 ];
 function recordFeedback(stateDb2, entity, context, notePath, correct) {
-  stateDb2.db.prepare(
-    "INSERT INTO wikilink_feedback (entity, context, note_path, correct) VALUES (?, ?, ?, ?)"
-  ).run(entity, context, notePath, correct ? 1 : 0);
+  try {
+    stateDb2.db.prepare(
+      "INSERT INTO wikilink_feedback (entity, context, note_path, correct) VALUES (?, ?, ?, ?)"
+    ).run(entity, context, notePath, correct ? 1 : 0);
+  } catch (e) {
+    console.error(`[Flywheel] recordFeedback failed for entity="${entity}": ${e}`);
+    throw e;
+  }
 }
 function getFeedback(stateDb2, entity, limit = 20) {
   let rows;
@@ -3551,6 +3569,159 @@ function getDashboardData(stateDb2) {
     }))
   };
 }
+function getEntityScoreTimeline(stateDb2, entityName, daysBack = 30, limit = 100) {
+  const cutoff = Date.now() - daysBack * 24 * 60 * 60 * 1e3;
+  const rows = stateDb2.db.prepare(`
+    SELECT timestamp, total_score, breakdown_json, note_path, passed, threshold
+    FROM suggestion_events
+    WHERE entity = ? AND timestamp >= ?
+    ORDER BY timestamp ASC
+    LIMIT ?
+  `).all(entityName, cutoff, limit);
+  return rows.map((r) => ({
+    timestamp: r.timestamp,
+    score: r.total_score,
+    breakdown: JSON.parse(r.breakdown_json),
+    notePath: r.note_path,
+    passed: r.passed === 1,
+    threshold: r.threshold
+  }));
+}
+function getLayerContributionTimeseries(stateDb2, granularity = "day", daysBack = 30) {
+  const cutoff = Date.now() - daysBack * 24 * 60 * 60 * 1e3;
+  const rows = stateDb2.db.prepare(`
+    SELECT timestamp, breakdown_json
+    FROM suggestion_events
+    WHERE timestamp >= ?
+    ORDER BY timestamp ASC
+  `).all(cutoff);
+  const buckets = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const date = new Date(row.timestamp);
+    let bucket;
+    if (granularity === "week") {
+      const jan4 = new Date(date.getFullYear(), 0, 4);
+      const weekNum = Math.ceil(((date.getTime() - jan4.getTime()) / 864e5 + jan4.getDay() + 1) / 7);
+      bucket = `${date.getFullYear()}-W${String(weekNum).padStart(2, "0")}`;
+    } else {
+      bucket = date.toISOString().slice(0, 10);
+    }
+    if (!buckets.has(bucket)) {
+      buckets.set(bucket, { count: 0, layers: {} });
+    }
+    const acc = buckets.get(bucket);
+    acc.count++;
+    const breakdown = JSON.parse(row.breakdown_json);
+    const layerMap = {
+      contentMatch: breakdown.contentMatch,
+      cooccurrenceBoost: breakdown.cooccurrenceBoost,
+      typeBoost: breakdown.typeBoost,
+      contextBoost: breakdown.contextBoost,
+      recencyBoost: breakdown.recencyBoost,
+      crossFolderBoost: breakdown.crossFolderBoost,
+      hubBoost: breakdown.hubBoost,
+      feedbackAdjustment: breakdown.feedbackAdjustment
+    };
+    if (breakdown.semanticBoost !== void 0) {
+      layerMap.semanticBoost = breakdown.semanticBoost;
+    }
+    for (const [layer, value] of Object.entries(layerMap)) {
+      acc.layers[layer] = (acc.layers[layer] ?? 0) + value;
+    }
+  }
+  const result = [];
+  for (const [bucket, acc] of buckets) {
+    const avgLayers = {};
+    for (const [layer, sum] of Object.entries(acc.layers)) {
+      avgLayers[layer] = Math.round(sum / acc.count * 1e3) / 1e3;
+    }
+    result.push({ bucket, layers: avgLayers });
+  }
+  return result;
+}
+function getExtendedDashboardData(stateDb2) {
+  const base = getDashboardData(stateDb2);
+  const recentCutoff = Date.now() - 7 * 24 * 60 * 60 * 1e3;
+  const eventRows = stateDb2.db.prepare(`
+    SELECT breakdown_json FROM suggestion_events WHERE timestamp >= ?
+  `).all(recentCutoff);
+  const layerSums = {};
+  const LAYER_NAMES = [
+    "contentMatch",
+    "cooccurrenceBoost",
+    "typeBoost",
+    "contextBoost",
+    "recencyBoost",
+    "crossFolderBoost",
+    "hubBoost",
+    "feedbackAdjustment",
+    "semanticBoost"
+  ];
+  for (const name of LAYER_NAMES) {
+    layerSums[name] = { sum: 0, count: 0 };
+  }
+  for (const row of eventRows) {
+    const breakdown = JSON.parse(row.breakdown_json);
+    for (const name of LAYER_NAMES) {
+      const val = breakdown[name];
+      if (val !== void 0) {
+        layerSums[name].sum += Math.abs(val);
+        layerSums[name].count++;
+      }
+    }
+  }
+  const layerHealth = LAYER_NAMES.map((layer) => {
+    const s = layerSums[layer];
+    const avg = s.count > 0 ? Math.round(s.sum / s.count * 1e3) / 1e3 : 0;
+    let status;
+    if (s.count === 0) status = "zero-data";
+    else if (avg > 0) status = "contributing";
+    else status = "dormant";
+    return { layer, status, avgContribution: avg, eventCount: s.count };
+  });
+  const topEntityRows = stateDb2.db.prepare(`
+    SELECT entity, COUNT(*) as cnt, AVG(total_score) as avg_score,
+           SUM(CASE WHEN passed = 1 THEN 1 ELSE 0 END) * 1.0 / COUNT(*) as pass_rate
+    FROM suggestion_events
+    GROUP BY entity
+    ORDER BY cnt DESC
+    LIMIT 10
+  `).all();
+  const topEntities = topEntityRows.map((r) => ({
+    entity: r.entity,
+    suggestionCount: r.cnt,
+    avgScore: Math.round(r.avg_score * 100) / 100,
+    passRate: Math.round(r.pass_rate * 1e3) / 1e3
+  }));
+  const feedbackTrendRows = stateDb2.db.prepare(`
+    SELECT date(created_at) as day, COUNT(*) as count
+    FROM wikilink_feedback
+    WHERE created_at >= datetime('now', '-30 days')
+    GROUP BY day
+    ORDER BY day
+  `).all();
+  const feedbackTrend = feedbackTrendRows.map((r) => ({
+    day: r.day,
+    count: r.count
+  }));
+  const suppressionRows = stateDb2.db.prepare(`
+    SELECT entity, false_positive_rate, updated_at
+    FROM wikilink_suppressions
+    ORDER BY updated_at DESC
+  `).all();
+  const suppressionChanges = suppressionRows.map((r) => ({
+    entity: r.entity,
+    falsePositiveRate: r.false_positive_rate,
+    updatedAt: r.updated_at
+  }));
+  return {
+    ...base,
+    layerHealth,
+    topEntities,
+    feedbackTrend,
+    suppressionChanges
+  };
+}
 
 // src/core/write/git.ts
 import { simpleGit, CheckRepoActions } from "simple-git";
@@ -3983,14 +4154,16 @@ function loadRecencyFromStateDb() {
 }
 function saveRecencyToStateDb(index) {
   if (!moduleStateDb3) {
-    console.error("[Flywheel] No StateDb available for saving recency");
+    console.error("[Flywheel] saveRecencyToStateDb: No StateDb available (moduleStateDb is null)");
     return;
   }
+  console.error(`[Flywheel] saveRecencyToStateDb: Saving ${index.lastMentioned.size} entries...`);
   try {
     for (const [entityNameLower, timestamp] of index.lastMentioned) {
       recordEntityMention(moduleStateDb3, entityNameLower, new Date(timestamp));
     }
-    console.error(`[Flywheel] Saved ${index.lastMentioned.size} recency entries to StateDb`);
+    const count = moduleStateDb3.db.prepare("SELECT COUNT(*) as cnt FROM recency").get();
+    console.error(`[Flywheel] Saved recency: ${index.lastMentioned.size} entries \u2192 ${count.cnt} rows in table`);
   } catch (e) {
     console.error("[Flywheel] Failed to save recency to StateDb:", e);
   }
@@ -4902,6 +5075,24 @@ function setWriteStateDb(stateDb2) {
 function getWriteStateDb() {
   return moduleStateDb4;
 }
+var moduleConfig = null;
+var ALL_IMPLICIT_PATTERNS = ["proper-nouns", "single-caps", "quoted-terms", "camel-case", "acronyms"];
+function setWikilinkConfig(config) {
+  moduleConfig = config;
+}
+function getWikilinkStrictness() {
+  return moduleConfig?.wikilink_strictness ?? "balanced";
+}
+function getEffectiveStrictness(notePath) {
+  const base = getWikilinkStrictness();
+  if (moduleConfig?.adaptive_strictness === false) return base;
+  const context = notePath ? getNoteContext(notePath) : "general";
+  if (context === "daily") return "aggressive";
+  return base;
+}
+function getCooccurrenceIndex() {
+  return cooccurrenceIndex;
+}
 var entityIndex = null;
 var indexReady = false;
 var indexError2 = null;
@@ -5062,9 +5253,12 @@ function processWikilinks(content, notePath) {
     firstOccurrenceOnly: true,
     caseInsensitive: true
   });
+  const implicitEnabled = moduleConfig?.implicit_detection !== false;
+  const validPatterns = new Set(ALL_IMPLICIT_PATTERNS);
+  const implicitPatterns = moduleConfig?.implicit_patterns?.length ? moduleConfig.implicit_patterns.filter((p) => validPatterns.has(p)) : [...ALL_IMPLICIT_PATTERNS];
   const implicitMatches = detectImplicitEntities(result.content, {
-    detectImplicit: true,
-    implicitPatterns: ["proper-nouns", "single-caps", "quoted-terms", "camel-case", "acronyms"],
+    detectImplicit: implicitEnabled,
+    implicitPatterns,
     minEntityLength: 3
   });
   const alreadyLinked = new Set(
@@ -5294,7 +5488,6 @@ var STRICTNESS_CONFIGS = {
     // Standard bonus for exact matches
   }
 };
-var DEFAULT_STRICTNESS = "conservative";
 var TYPE_BOOST = {
   people: 5,
   // Names are high value for connections
@@ -5481,10 +5674,12 @@ async function suggestRelatedLinks(content, options = {}) {
   const {
     maxSuggestions = 3,
     excludeLinked = true,
-    strictness = DEFAULT_STRICTNESS,
+    strictness = getEffectiveStrictness(options.notePath),
     notePath,
-    detail = false
+    detail = false,
+    disabledLayers = []
   } = options;
+  const disabled = new Set(disabledLayers);
   const config = STRICTNESS_CONFIGS[strictness];
   const adaptiveMinScore = getAdaptiveMinScore(content.length, config.minSuggestionScore);
   const noteContext = notePath ? getNoteContext(notePath) : "general";
@@ -5525,31 +5720,31 @@ async function suggestRelatedLinks(content, options = {}) {
   for (const { entity, category } of entitiesWithTypes) {
     const entityName = entity.name;
     if (!entityName) continue;
-    if (entityName.length > MAX_ENTITY_LENGTH) {
+    if (!disabled.has("length_filter") && entityName.length > MAX_ENTITY_LENGTH) {
       continue;
     }
-    if (isLikelyArticleTitle(entityName)) {
+    if (!disabled.has("article_filter") && isLikelyArticleTitle(entityName)) {
       continue;
     }
     if (linkedEntities.has(entityName.toLowerCase())) {
       continue;
     }
-    const contentScore = scoreEntity(entity, contentTokens, contentStems, config);
+    const contentScore = disabled.has("exact_match") && disabled.has("stem_match") ? 0 : scoreEntity(entity, contentTokens, contentStems, config);
     let score = contentScore;
     if (contentScore > 0) {
       entitiesWithContentMatch.add(entityName);
     }
-    const layerTypeBoost = TYPE_BOOST[category] || 0;
+    const layerTypeBoost = disabled.has("type_boost") ? 0 : TYPE_BOOST[category] || 0;
     score += layerTypeBoost;
-    const layerContextBoost = contextBoosts[category] || 0;
+    const layerContextBoost = disabled.has("context_boost") ? 0 : contextBoosts[category] || 0;
     score += layerContextBoost;
-    const layerRecencyBoost = recencyIndex ? getRecencyBoost(entityName, recencyIndex) : 0;
+    const layerRecencyBoost = disabled.has("recency") ? 0 : recencyIndex ? getRecencyBoost(entityName, recencyIndex) : 0;
     score += layerRecencyBoost;
-    const layerCrossFolderBoost = notePath && entity.path ? getCrossFolderBoost(entity.path, notePath) : 0;
+    const layerCrossFolderBoost = disabled.has("cross_folder") ? 0 : notePath && entity.path ? getCrossFolderBoost(entity.path, notePath) : 0;
     score += layerCrossFolderBoost;
-    const layerHubBoost = getHubBoost(entity);
+    const layerHubBoost = disabled.has("hub_boost") ? 0 : getHubBoost(entity);
     score += layerHubBoost;
-    const layerFeedbackAdj = feedbackBoosts.get(entityName) ?? 0;
+    const layerFeedbackAdj = disabled.has("feedback") ? 0 : feedbackBoosts.get(entityName) ?? 0;
     score += layerFeedbackAdj;
     if (score > 0) {
       directlyMatchedEntities.add(entityName);
@@ -5573,12 +5768,12 @@ async function suggestRelatedLinks(content, options = {}) {
       });
     }
   }
-  if (cooccurrenceIndex && directlyMatchedEntities.size > 0) {
+  if (!disabled.has("cooccurrence") && cooccurrenceIndex && directlyMatchedEntities.size > 0) {
     for (const { entity, category } of entitiesWithTypes) {
       const entityName = entity.name;
       if (!entityName) continue;
-      if (entityName.length > MAX_ENTITY_LENGTH) continue;
-      if (isLikelyArticleTitle(entityName)) continue;
+      if (!disabled.has("length_filter") && entityName.length > MAX_ENTITY_LENGTH) continue;
+      if (!disabled.has("article_filter") && isLikelyArticleTitle(entityName)) continue;
       if (linkedEntities.has(entityName.toLowerCase())) continue;
       const boost = getCooccurrenceBoost(entityName, directlyMatchedEntities, cooccurrenceIndex, recencyIndex);
       if (boost > 0) {
@@ -5595,12 +5790,12 @@ async function suggestRelatedLinks(content, options = {}) {
             continue;
           }
           entitiesWithContentMatch.add(entityName);
-          const typeBoost = TYPE_BOOST[category] || 0;
-          const contextBoost = contextBoosts[category] || 0;
-          const recencyBoostVal = recencyIndex ? getRecencyBoost(entityName, recencyIndex) : 0;
-          const crossFolderBoost = notePath && entity.path ? getCrossFolderBoost(entity.path, notePath) : 0;
-          const hubBoost = getHubBoost(entity);
-          const feedbackAdj = feedbackBoosts.get(entityName) ?? 0;
+          const typeBoost = disabled.has("type_boost") ? 0 : TYPE_BOOST[category] || 0;
+          const contextBoost = disabled.has("context_boost") ? 0 : contextBoosts[category] || 0;
+          const recencyBoostVal = disabled.has("recency") ? 0 : recencyIndex ? getRecencyBoost(entityName, recencyIndex) : 0;
+          const crossFolderBoost = disabled.has("cross_folder") ? 0 : notePath && entity.path ? getCrossFolderBoost(entity.path, notePath) : 0;
+          const hubBoost = disabled.has("hub_boost") ? 0 : getHubBoost(entity);
+          const feedbackAdj = disabled.has("feedback") ? 0 : feedbackBoosts.get(entityName) ?? 0;
           const totalBoost = boost + typeBoost + contextBoost + recencyBoostVal + crossFolderBoost + hubBoost + feedbackAdj;
           if (totalBoost >= adaptiveMinScore) {
             scoredEntities.push({
@@ -5624,7 +5819,7 @@ async function suggestRelatedLinks(content, options = {}) {
       }
     }
   }
-  if (content.length >= 20 && hasEntityEmbeddingsIndex()) {
+  if (!disabled.has("semantic") && content.length >= 20 && hasEntityEmbeddingsIndex()) {
     try {
       const contentEmbedding = await embedTextCached(content);
       const alreadyScoredNames = new Set(scoredEntities.map((e) => e.name));
@@ -5646,14 +5841,14 @@ async function suggestRelatedLinks(content, options = {}) {
             (et) => et.entity.name === match.entityName
           );
           if (!entityWithType) continue;
-          if (match.entityName.length > MAX_ENTITY_LENGTH) continue;
-          if (isLikelyArticleTitle(match.entityName)) continue;
+          if (!disabled.has("length_filter") && match.entityName.length > MAX_ENTITY_LENGTH) continue;
+          if (!disabled.has("article_filter") && isLikelyArticleTitle(match.entityName)) continue;
           const { entity, category } = entityWithType;
-          const layerTypeBoost = TYPE_BOOST[category] || 0;
-          const layerContextBoost = contextBoosts[category] || 0;
-          const layerHubBoost = getHubBoost(entity);
-          const layerCrossFolderBoost = notePath && entity.path ? getCrossFolderBoost(entity.path, notePath) : 0;
-          const layerFeedbackAdj = feedbackBoosts.get(match.entityName) ?? 0;
+          const layerTypeBoost = disabled.has("type_boost") ? 0 : TYPE_BOOST[category] || 0;
+          const layerContextBoost = disabled.has("context_boost") ? 0 : contextBoosts[category] || 0;
+          const layerHubBoost = disabled.has("hub_boost") ? 0 : getHubBoost(entity);
+          const layerCrossFolderBoost = disabled.has("cross_folder") ? 0 : notePath && entity.path ? getCrossFolderBoost(entity.path, notePath) : 0;
+          const layerFeedbackAdj = disabled.has("feedback") ? 0 : feedbackBoosts.get(match.entityName) ?? 0;
           const totalScore = boost + layerTypeBoost + layerContextBoost + layerHubBoost + layerCrossFolderBoost + layerFeedbackAdj;
           if (totalScore >= adaptiveMinScore) {
             scoredEntities.push({
@@ -5695,7 +5890,51 @@ async function suggestRelatedLinks(content, options = {}) {
     }
     return 0;
   });
-  const topEntries = relevantEntities.slice(0, maxSuggestions);
+  if (moduleStateDb4 && notePath) {
+    try {
+      const now = Date.now();
+      const insertStmt = moduleStateDb4.db.prepare(`
+        INSERT OR IGNORE INTO suggestion_events
+          (timestamp, note_path, entity, total_score, breakdown_json, threshold, passed, strictness, applied, pipeline_event_id)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, NULL)
+      `);
+      const persistTransaction = moduleStateDb4.db.transaction(() => {
+        for (const e of relevantEntities) {
+          insertStmt.run(
+            now,
+            notePath,
+            e.name,
+            e.score,
+            JSON.stringify(e.breakdown),
+            adaptiveMinScore,
+            1,
+            // passed threshold (these are relevantEntities)
+            strictness
+          );
+        }
+        for (const e of scoredEntities) {
+          if (!entitiesWithContentMatch.has(e.name)) continue;
+          if (relevantEntities.some((r) => r.name === e.name)) continue;
+          insertStmt.run(
+            now,
+            notePath,
+            e.name,
+            e.score,
+            JSON.stringify(e.breakdown),
+            adaptiveMinScore,
+            0,
+            // did not pass threshold
+            strictness
+          );
+        }
+      });
+      persistTransaction();
+    } catch {
+    }
+  }
+  const currentNoteStem = notePath ? notePath.replace(/\.md$/, "").split("/").pop()?.toLowerCase() : null;
+  const filtered = currentNoteStem ? relevantEntities.filter((e) => e.name.toLowerCase() !== currentNoteStem) : relevantEntities;
+  const topEntries = filtered.slice(0, maxSuggestions);
   const topSuggestions = topEntries.map((e) => e.name);
   if (topSuggestions.length === 0) {
     return emptyResult;
@@ -6046,6 +6285,17 @@ function searchFTS5(_vaultPath, query, limit = 10) {
 function getFTS5State() {
   return { ...state };
 }
+function countFTS5Mentions(term) {
+  if (!db2) return 0;
+  try {
+    const result = db2.prepare(
+      "SELECT COUNT(*) as cnt FROM notes_fts WHERE content MATCH ?"
+    ).get(`"${term}"`);
+    return result?.cnt ?? 0;
+  } catch {
+    return 0;
+  }
+}
 
 // src/core/read/taskCache.ts
 import * as path10 from "path";
@@ -7057,12 +7307,13 @@ function registerWikilinkTools(server2, getIndex, getVaultPath) {
       inputSchema: {
         path: z2.string().optional().describe("Path to a specific note to validate. If omitted, validates all notes."),
         typos_only: z2.boolean().default(false).describe("If true, only report broken links that have a similar existing note (likely typos)"),
+        group_by_target: z2.boolean().default(false).describe("If true, aggregate dead links by target and rank by mention frequency. Returns targets[] instead of broken[]."),
         limit: z2.coerce.number().default(50).describe("Maximum number of broken links to return"),
         offset: z2.coerce.number().default(0).describe("Number of broken links to skip (for pagination)")
       },
       outputSchema: ValidateLinksOutputSchema
     },
-    async ({ path: notePath, typos_only, limit: requestedLimit, offset }) => {
+    async ({ path: notePath, typos_only, group_by_target, limit: requestedLimit, offset }) => {
       const limit = Math.min(requestedLimit ?? 50, MAX_LIMIT);
       const index = getIndex();
       const allBroken = [];
@@ -7103,6 +7354,41 @@ function registerWikilinkTools(server2, getIndex, getVaultPath) {
           }
         }
       }
+      if (group_by_target) {
+        const targetMap = /* @__PURE__ */ new Map();
+        for (const broken2 of allBroken) {
+          const key = broken2.target.toLowerCase();
+          const existing = targetMap.get(key);
+          if (existing) {
+            existing.count++;
+            if (existing.sources.size < 5) existing.sources.add(broken2.source);
+            if (!existing.suggestion && broken2.suggestion) existing.suggestion = broken2.suggestion;
+          } else {
+            targetMap.set(key, {
+              count: 1,
+              sources: /* @__PURE__ */ new Set([broken2.source]),
+              suggestion: broken2.suggestion
+            });
+          }
+        }
+        const targets = Array.from(targetMap.entries()).map(([target, data]) => ({
+          target,
+          mention_count: data.count,
+          sources: Array.from(data.sources),
+          ...data.suggestion ? { suggestion: data.suggestion } : {}
+        })).sort((a, b) => b.mention_count - a.mention_count).slice(offset, offset + limit);
+        const grouped = {
+          scope: notePath || "all",
+          total_dead_targets: targetMap.size,
+          total_broken_links: allBroken.length,
+          returned_count: targets.length,
+          targets
+        };
+        return {
+          content: [{ type: "text", text: JSON.stringify(grouped, null, 2) }],
+          structuredContent: grouped
+        };
+      }
       const broken = allBroken.slice(offset, offset + limit);
       const output = {
         scope: notePath || "all",
@@ -7123,6 +7409,106 @@ function registerWikilinkTools(server2, getIndex, getVaultPath) {
       };
     }
   );
+  server2.registerTool(
+    "discover_stub_candidates",
+    {
+      title: "Discover Stub Candidates",
+      description: `Find terms referenced via dead wikilinks across the vault that have no backing note. These are "invisible concepts" \u2014 topics your vault considers important enough to link to but that don't have their own notes yet. Ranked by reference frequency.`,
+      inputSchema: {
+        min_frequency: z2.coerce.number().default(2).describe("Minimum number of references to include (default 2)"),
+        limit: z2.coerce.number().default(20).describe("Maximum candidates to return (default 20)")
+      }
+    },
+    async ({ min_frequency, limit: requestedLimit }) => {
+      const index = getIndex();
+      const limit = Math.min(requestedLimit ?? 20, 100);
+      const minFreq = min_frequency ?? 2;
+      const targetMap = /* @__PURE__ */ new Map();
+      for (const note of index.notes.values()) {
+        for (const link of note.outlinks) {
+          if (!resolveTarget(index, link.target)) {
+            const key = link.target.toLowerCase();
+            const existing = targetMap.get(key);
+            if (existing) {
+              existing.count++;
+              if (existing.sources.size < 3) existing.sources.add(note.path);
+            } else {
+              targetMap.set(key, { count: 1, sources: /* @__PURE__ */ new Set([note.path]) });
+            }
+          }
+        }
+      }
+      const candidates = Array.from(targetMap.entries()).filter(([, data]) => data.count >= minFreq).map(([target, data]) => {
+        const fts5Mentions = countFTS5Mentions(target);
+        return {
+          term: target,
+          wikilink_references: data.count,
+          content_mentions: fts5Mentions,
+          sample_notes: Array.from(data.sources)
+        };
+      }).sort((a, b) => b.wikilink_references - a.wikilink_references).slice(0, limit);
+      const output = {
+        total_dead_targets: targetMap.size,
+        candidates_above_threshold: candidates.length,
+        candidates
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+      };
+    }
+  );
+  server2.registerTool(
+    "discover_cooccurrence_gaps",
+    {
+      title: "Discover Co-occurrence Gaps",
+      description: "Find entity pairs that frequently co-occur across vault notes but where one or both entities lack a backing note. These represent relationship patterns worth making explicit with hub notes or links.",
+      inputSchema: {
+        min_cooccurrence: z2.coerce.number().default(3).describe("Minimum co-occurrence count to include (default 3)"),
+        limit: z2.coerce.number().default(20).describe("Maximum gaps to return (default 20)")
+      }
+    },
+    async ({ min_cooccurrence, limit: requestedLimit }) => {
+      const index = getIndex();
+      const coocIndex = getCooccurrenceIndex();
+      const limit = Math.min(requestedLimit ?? 20, 100);
+      const minCount = min_cooccurrence ?? 3;
+      if (!coocIndex) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: "Co-occurrence index not built yet. Wait for entity index initialization." }) }]
+        };
+      }
+      const gaps = [];
+      const seenPairs = /* @__PURE__ */ new Set();
+      for (const [entityA, associations] of Object.entries(coocIndex.associations)) {
+        for (const [entityB, count] of associations) {
+          if (count < minCount) continue;
+          const pairKey = [entityA, entityB].sort().join("||");
+          if (seenPairs.has(pairKey)) continue;
+          seenPairs.add(pairKey);
+          const aHasNote = resolveTarget(index, entityA) !== null;
+          const bHasNote = resolveTarget(index, entityB) !== null;
+          if (aHasNote && bHasNote) continue;
+          gaps.push({
+            entity_a: entityA,
+            entity_b: entityB,
+            cooccurrence_count: count,
+            a_has_note: aHasNote,
+            b_has_note: bHasNote
+          });
+        }
+      }
+      gaps.sort((a, b) => b.cooccurrence_count - a.cooccurrence_count);
+      const top = gaps.slice(0, limit);
+      const output = {
+        total_gaps: gaps.length,
+        returned_count: top.length,
+        gaps: top
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+      };
+    }
+  );
 }
 
 // src/tools/read/health.ts
@@ -7488,6 +7874,93 @@ function purgeOldIndexEvents(stateDb2, retentionDays = 90) {
   return result.changes;
 }
 
+// src/core/read/sweep.ts
+var DEFAULT_SWEEP_INTERVAL_MS = 5 * 60 * 1e3;
+var MIN_SWEEP_INTERVAL_MS = 30 * 1e3;
+var cachedResults = null;
+var sweepTimer = null;
+var sweepRunning = false;
+function runSweep(index) {
+  const start = Date.now();
+  let deadLinkCount = 0;
+  const deadTargetCounts = /* @__PURE__ */ new Map();
+  for (const note of index.notes.values()) {
+    for (const link of note.outlinks) {
+      if (!resolveTarget(index, link.target)) {
+        deadLinkCount++;
+        const key = link.target.toLowerCase();
+        deadTargetCounts.set(key, (deadTargetCounts.get(key) || 0) + 1);
+      }
+    }
+  }
+  const topDeadTargets = Array.from(deadTargetCounts.entries()).filter(([, count]) => count >= 2).map(([target, wikilink_references]) => ({
+    target,
+    wikilink_references,
+    content_mentions: countFTS5Mentions(target)
+  })).sort((a, b) => b.wikilink_references - a.wikilink_references).slice(0, 10);
+  const linkedCounts = /* @__PURE__ */ new Map();
+  for (const note of index.notes.values()) {
+    for (const link of note.outlinks) {
+      const key = link.target.toLowerCase();
+      linkedCounts.set(key, (linkedCounts.get(key) || 0) + 1);
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const unlinkedEntities = [];
+  for (const [name, entityPath] of index.entities) {
+    if (seen.has(entityPath)) continue;
+    seen.add(entityPath);
+    const totalMentions = countFTS5Mentions(name);
+    if (totalMentions === 0) continue;
+    const pathKey = entityPath.toLowerCase().replace(/\.md$/, "");
+    const linked = Math.max(linkedCounts.get(name) || 0, linkedCounts.get(pathKey) || 0);
+    const unlinked = Math.max(0, totalMentions - linked - 1);
+    if (unlinked <= 0) continue;
+    const note = index.notes.get(entityPath);
+    const displayName = note?.title || name;
+    unlinkedEntities.push({ entity: displayName, path: entityPath, unlinked_mentions: unlinked });
+  }
+  unlinkedEntities.sort((a, b) => b.unlinked_mentions - a.unlinked_mentions);
+  const results = {
+    last_sweep_at: Date.now(),
+    sweep_duration_ms: Date.now() - start,
+    dead_link_count: deadLinkCount,
+    top_dead_targets: topDeadTargets,
+    top_unlinked_entities: unlinkedEntities.slice(0, 10)
+  };
+  cachedResults = results;
+  return results;
+}
+function startSweepTimer(getIndex, intervalMs) {
+  const interval = Math.max(intervalMs ?? DEFAULT_SWEEP_INTERVAL_MS, MIN_SWEEP_INTERVAL_MS);
+  setTimeout(() => {
+    doSweep(getIndex);
+  }, 5e3);
+  sweepTimer = setInterval(() => {
+    doSweep(getIndex);
+  }, interval);
+  if (sweepTimer && typeof sweepTimer === "object" && "unref" in sweepTimer) {
+    sweepTimer.unref();
+  }
+}
+function doSweep(getIndex) {
+  if (sweepRunning) return;
+  sweepRunning = true;
+  try {
+    const index = getIndex();
+    if (index && index.notes && index.notes.size > 0) {
+      runSweep(index);
+    }
+  } catch (err) {
+    console.error("[Flywheel] Sweep error:", err);
+  } finally {
+    sweepRunning = false;
+  }
+}
+function getSweepResults() {
+  return cachedResults;
+}
+
 // src/tools/read/health.ts
 var STALE_THRESHOLD_SECONDS = 300;
 function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () => ({}), getStateDb = () => null) {
@@ -7563,6 +8036,26 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
     embeddings_count: z3.coerce.number().describe("Number of notes with semantic embeddings"),
     tasks_ready: z3.boolean().describe("Whether the task cache is ready to serve queries"),
     tasks_building: z3.boolean().describe("Whether the task cache is currently rebuilding"),
+    dead_link_count: z3.coerce.number().describe("Total number of broken/dead wikilinks across the vault"),
+    top_dead_link_targets: z3.array(z3.object({
+      target: z3.string().describe("The dead link target"),
+      mention_count: z3.coerce.number().describe("How many notes reference this dead target")
+    })).describe("Top 5 most-referenced dead link targets (highest-ROI candidates to create)"),
+    sweep: z3.object({
+      last_sweep_at: z3.number().describe("When the last background sweep completed (ms epoch)"),
+      sweep_duration_ms: z3.number().describe("How long the last sweep took"),
+      dead_link_count: z3.number().describe("Dead links found by sweep"),
+      top_dead_targets: z3.array(z3.object({
+        target: z3.string(),
+        wikilink_references: z3.number(),
+        content_mentions: z3.number()
+      })).describe("Top dead link targets with FTS5 content mention counts"),
+      top_unlinked_entities: z3.array(z3.object({
+        entity: z3.string(),
+        path: z3.string(),
+        unlinked_mentions: z3.number()
+      })).describe("Entities with the most unlinked plain-text mentions")
+    }).optional().describe("Background sweep results (graph hygiene metrics, updated every 5 min)"),
     recommendations: z3.array(z3.string()).describe("Suggested actions if any issues detected")
   };
   server2.registerTool(
@@ -7685,6 +8178,20 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
         }
       }
       const ftsState = getFTS5State();
+      let deadLinkCount = 0;
+      const deadTargetCounts = /* @__PURE__ */ new Map();
+      if (indexBuilt) {
+        for (const note of index.notes.values()) {
+          for (const link of note.outlinks) {
+            if (!resolveTarget(index, link.target)) {
+              deadLinkCount++;
+              const key = link.target.toLowerCase();
+              deadTargetCounts.set(key, (deadTargetCounts.get(key) || 0) + 1);
+            }
+          }
+        }
+      }
+      const topDeadLinkTargets = Array.from(deadTargetCounts.entries()).map(([target, mention_count]) => ({ target, mention_count })).sort((a, b) => b.mention_count - a.mention_count).slice(0, 5);
       const output = {
         status,
         schema_version: SCHEMA_VERSION,
@@ -7712,6 +8219,9 @@ function registerHealthTools(server2, getIndex, getVaultPath, getConfig = () =>
         embeddings_count: getEmbeddingsCount(),
         tasks_ready: isTaskCacheReady(),
         tasks_building: isTaskCacheBuilding(),
+        dead_link_count: deadLinkCount,
+        top_dead_link_targets: topDeadLinkTargets,
+        sweep: getSweepResults() ?? void 0,
         recommendations
       };
       return {
@@ -8205,6 +8715,14 @@ function generateAliasCandidates(entityName, existingAliases) {
         candidates.push({ candidate: short, type: "short_form" });
       }
     }
+    const STOPWORDS2 = /* @__PURE__ */ new Set(["the", "and", "for", "with", "from", "into", "that", "this", "are", "was", "has", "its"]);
+    for (const word of words) {
+      if (word.length < 4) continue;
+      if (STOPWORDS2.has(word.toLowerCase())) continue;
+      if (existing.has(word.toLowerCase())) continue;
+      if (words.length >= 3 && word === words[0]) continue;
+      candidates.push({ candidate: word, type: "name_fragment" });
+    }
   }
   return candidates;
 }
@@ -8231,6 +8749,7 @@ function suggestEntityAliases(stateDb2, folder) {
         mentions = result?.cnt ?? 0;
       } catch {
       }
+      if (type === "name_fragment" && mentions < 5) continue;
       suggestions.push({
         entity: row.name,
         entity_path: row.path,
@@ -8761,6 +9280,61 @@ function registerSystemTools(server2, getIndex, setIndex, getVaultPath, setConfi
       };
     }
   );
+  server2.registerTool(
+    "unlinked_mentions_report",
+    {
+      title: "Unlinked Mentions Report",
+      description: "Find which entities have the most unlinked mentions across the vault \u2014 highest-ROI linking opportunities. Uses FTS5 to count mentions and subtracts known wikilinks.",
+      inputSchema: {
+        limit: z5.coerce.number().default(20).describe("Maximum entities to return (default 20)")
+      }
+    },
+    async ({ limit: requestedLimit }) => {
+      requireIndex();
+      const index = getIndex();
+      const limit = Math.min(requestedLimit ?? 20, 100);
+      const linkedCounts = /* @__PURE__ */ new Map();
+      for (const note of index.notes.values()) {
+        for (const link of note.outlinks) {
+          const key = link.target.toLowerCase();
+          linkedCounts.set(key, (linkedCounts.get(key) || 0) + 1);
+        }
+      }
+      const results = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const [name, entityPath] of index.entities) {
+        if (seen.has(entityPath)) continue;
+        seen.add(entityPath);
+        const totalMentions = countFTS5Mentions(name);
+        if (totalMentions === 0) continue;
+        const pathKey = entityPath.toLowerCase().replace(/\.md$/, "");
+        const linkedByName = linkedCounts.get(name) || 0;
+        const linkedByPath = linkedCounts.get(pathKey) || 0;
+        const linked = Math.max(linkedByName, linkedByPath);
+        const unlinked = Math.max(0, totalMentions - linked - 1);
+        if (unlinked <= 0) continue;
+        const note = index.notes.get(entityPath);
+        const displayName = note?.title || name;
+        results.push({
+          entity: displayName,
+          path: entityPath,
+          total_mentions: totalMentions,
+          linked_mentions: linked,
+          unlinked_mentions: unlinked
+        });
+      }
+      results.sort((a, b) => b.unlinked_mentions - a.unlinked_mentions);
+      const top = results.slice(0, limit);
+      const output = {
+        total_entities_checked: seen.size,
+        entities_with_unlinked: results.length,
+        top_entities: top
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+      };
+    }
+  );
 }
 
 // src/tools/read/primitives.ts
@@ -9938,6 +10512,49 @@ function getEmergingHubs(stateDb2, daysBack = 30) {
   emerging.sort((a, b) => b.growth - a.growth);
   return emerging;
 }
+function compareGraphSnapshots(stateDb2, timestampBefore, timestampAfter) {
+  const SCALAR_METRICS = ["avg_degree", "max_degree", "cluster_count", "largest_cluster_size"];
+  function getSnapshotAt(ts) {
+    const row = stateDb2.db.prepare(
+      `SELECT DISTINCT timestamp FROM graph_snapshots WHERE timestamp <= ? ORDER BY timestamp DESC LIMIT 1`
+    ).get(ts);
+    if (!row) return null;
+    const rows = stateDb2.db.prepare(
+      `SELECT metric, value, details FROM graph_snapshots WHERE timestamp = ?`
+    ).all(row.timestamp);
+    return rows;
+  }
+  const beforeRows = getSnapshotAt(timestampBefore) ?? [];
+  const afterRows = getSnapshotAt(timestampAfter) ?? [];
+  const beforeMap = /* @__PURE__ */ new Map();
+  const afterMap = /* @__PURE__ */ new Map();
+  for (const r of beforeRows) beforeMap.set(r.metric, { value: r.value, details: r.details });
+  for (const r of afterRows) afterMap.set(r.metric, { value: r.value, details: r.details });
+  const metricChanges = SCALAR_METRICS.map((metric) => {
+    const before = beforeMap.get(metric)?.value ?? 0;
+    const after = afterMap.get(metric)?.value ?? 0;
+    const delta = after - before;
+    const deltaPercent = before !== 0 ? Math.round(delta / before * 1e4) / 100 : delta !== 0 ? 100 : 0;
+    return { metric, before, after, delta, deltaPercent };
+  });
+  const beforeHubs = beforeMap.get("hub_scores_top10")?.details ? JSON.parse(beforeMap.get("hub_scores_top10").details) : [];
+  const afterHubs = afterMap.get("hub_scores_top10")?.details ? JSON.parse(afterMap.get("hub_scores_top10").details) : [];
+  const beforeHubMap = /* @__PURE__ */ new Map();
+  for (const h of beforeHubs) beforeHubMap.set(h.entity, h.degree);
+  const afterHubMap = /* @__PURE__ */ new Map();
+  for (const h of afterHubs) afterHubMap.set(h.entity, h.degree);
+  const allHubEntities = /* @__PURE__ */ new Set([...beforeHubMap.keys(), ...afterHubMap.keys()]);
+  const hubScoreChanges = [];
+  for (const entity of allHubEntities) {
+    const before = beforeHubMap.get(entity) ?? 0;
+    const after = afterHubMap.get(entity) ?? 0;
+    if (before !== after) {
+      hubScoreChanges.push({ entity, before, after, delta: after - before });
+    }
+  }
+  hubScoreChanges.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+  return { metricChanges, hubScoreChanges };
+}
 function purgeOldSnapshots(stateDb2, retentionDays = 90) {
   const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1e3;
   const result = stateDb2.db.prepare(
@@ -11609,10 +12226,11 @@ Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", con
       validate: z11.boolean().default(true).describe("Check input for common issues (double timestamps, non-markdown bullets, etc.)"),
       normalize: z11.boolean().default(true).describe("Auto-fix common issues before formatting (replace \u2022 with -, trim excessive whitespace, etc.)"),
       guardrails: z11.enum(["warn", "strict", "off"]).default("warn").describe('Output validation mode: "warn" returns issues but proceeds, "strict" blocks on errors, "off" disables'),
+      linkedEntities: z11.array(z11.string()).optional().describe("Entity names already linked in the content. When skipWikilinks=true, these are tracked for feedback without re-processing the content."),
       agent_id: z11.string().optional().describe('Agent identifier for multi-agent scoping (e.g., "claude-opus", "planning-agent")'),
       session_id: z11.string().optional().describe('Session identifier for conversation scoping (e.g., "sess-abc123")')
     },
-    async ({ path: notePath, section, content, create_if_missing, position, format, commit, skipWikilinks, preserveListNesting, bumpHeadings, suggestOutgoingLinks, maxSuggestions, validate, normalize, guardrails, agent_id, session_id }) => {
+    async ({ path: notePath, section, content, create_if_missing, position, format, commit, skipWikilinks, preserveListNesting, bumpHeadings, suggestOutgoingLinks, maxSuggestions, validate, normalize, guardrails, linkedEntities, agent_id, session_id }) => {
       let noteCreated = false;
       let templateUsed;
       if (create_if_missing) {
@@ -11647,6 +12265,12 @@ Example: vault_add_to_section({ path: "daily/2026-02-15.md", section: "Log", con
           }
           let workingContent = validationResult.content;
           let { content: processedContent, wikilinkInfo } = maybeApplyWikilinks(workingContent, skipWikilinks, notePath);
+          if (linkedEntities?.length) {
+            const stateDb2 = getWriteStateDb();
+            if (stateDb2) {
+              trackWikilinkApplications(stateDb2, notePath, linkedEntities);
+            }
+          }
           const _debug = {
             entityCount: getEntityIndexStats().totalEntities,
             indexReady: getEntityIndexStats().ready,
@@ -12082,7 +12706,7 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
       overwrite: z14.boolean().default(false).describe("If true, overwrite existing file"),
       commit: z14.boolean().default(false).describe("If true, commit this change to git (creates undo point)"),
       skipWikilinks: z14.boolean().default(false).describe("If true, skip auto-wikilink application (wikilinks are applied by default)"),
-      suggestOutgoingLinks: z14.boolean().default(false).describe('Append suggested outgoing wikilinks based on content (e.g., "\u2192 [[AI]], [[Philosophy]]"). Disabled by default for templates; enable for content-rich notes.'),
+      suggestOutgoingLinks: z14.boolean().default(true).describe('Append suggested outgoing wikilinks based on content (e.g., "\u2192 [[AI]], [[Philosophy]]").'),
       maxSuggestions: z14.number().min(1).max(10).default(3).describe("Maximum number of suggested wikilinks to append (1-10, default: 3)"),
       agent_id: z14.string().optional().describe("Agent identifier for multi-agent scoping"),
       session_id: z14.string().optional().describe("Session identifier for conversation scoping")
@@ -12119,8 +12743,12 @@ function registerNoteTools(server2, vaultPath2, getIndex) {
             return formatMcpResult(errorResult(notePath, `Template not found: ${template}`));
           }
         }
+        const now = /* @__PURE__ */ new Date();
         if (!effectiveFrontmatter.date) {
-          effectiveFrontmatter.date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+          effectiveFrontmatter.date = now.toISOString().split("T")[0];
+        }
+        if (!effectiveFrontmatter.created) {
+          effectiveFrontmatter.created = now.toISOString();
         }
         const warnings = [];
         const noteName = path21.basename(notePath, ".md");
@@ -13095,12 +13723,17 @@ async function executeStep(step, vaultPath2, context, conditionResults) {
   const resolvedParams = interpolateObject(step.params, context);
   try {
     const result = await executeToolCall(step.tool, resolvedParams, vaultPath2, context);
+    const outputs = {};
+    if (result.path) {
+      outputs.path = result.path;
+    }
     return {
       stepId: step.id,
       success: result.success,
       message: result.message,
       path: result.path,
-      preview: result.preview
+      preview: result.preview,
+      outputs
     };
   } catch (error) {
     return {
@@ -13491,6 +14124,9 @@ async function executePolicy(policy, vaultPath2, variables, commit = false) {
     if (result.path && result.success && !result.skipped) {
       filesModified.add(result.path);
     }
+    if (result.success && !result.skipped && result.outputs) {
+      context.steps[step.id] = result.outputs;
+    }
     if (!result.success && !result.skipped) {
       if (commit && filesModified.size > 0) {
         await rollbackChanges(vaultPath2, originalContents, filesModified);
@@ -14451,21 +15087,26 @@ function registerWikilinkFeedbackTools(server2, getStateDb) {
     "wikilink_feedback",
     {
       title: "Wikilink Feedback",
-      description: 'Report and query wikilink accuracy feedback. Modes: "report" (record feedback), "list" (view recent feedback), "stats" (entity accuracy statistics), "dashboard" (full feedback loop data for visualization). Entities with >=30% false positive rate (and >=10 samples) are auto-suppressed from future wikilink application.',
+      description: 'Report and query wikilink accuracy feedback. Modes: "report" (record feedback), "list" (view recent feedback), "stats" (entity accuracy statistics), "dashboard" (full feedback loop data), "entity_timeline" (score history for an entity), "layer_timeseries" (per-layer contribution over time), "snapshot_diff" (compare two graph snapshots).',
       inputSchema: {
-        mode: z21.enum(["report", "list", "stats", "dashboard"]).describe("Operation mode"),
-        entity: z21.string().optional().describe("Entity name (required for report mode, optional filter for list/stats)"),
+        mode: z21.enum(["report", "list", "stats", "dashboard", "entity_timeline", "layer_timeseries", "snapshot_diff"]).describe("Operation mode"),
+        entity: z21.string().optional().describe("Entity name (required for report and entity_timeline modes, optional filter for list/stats)"),
         note_path: z21.string().optional().describe("Note path where the wikilink appeared (for report mode)"),
         context: z21.string().optional().describe("Surrounding text context (for report mode)"),
         correct: z21.boolean().optional().describe("Whether the wikilink was correct (for report mode)"),
-        limit: z21.number().optional().describe("Max entries to return for list mode (default: 20)")
+        limit: z21.number().optional().describe("Max entries to return (default: 20 for list, 100 for entity_timeline)"),
+        days_back: z21.number().optional().describe("Days to look back (default: 30)"),
+        granularity: z21.enum(["day", "week"]).optional().describe("Time bucket granularity for layer_timeseries (default: day)"),
+        timestamp_before: z21.number().optional().describe("Earlier timestamp for snapshot_diff"),
+        timestamp_after: z21.number().optional().describe("Later timestamp for snapshot_diff")
       }
     },
-    async ({ mode, entity, note_path, context, correct, limit }) => {
+    async ({ mode, entity, note_path, context, correct, limit, days_back, granularity, timestamp_before, timestamp_after }) => {
       const stateDb2 = getStateDb();
       if (!stateDb2) {
         return {
-          content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available" }) }]
+          content: [{ type: "text", text: JSON.stringify({ error: "StateDb not available \u2014 database not initialized yet" }) }],
+          isError: true
         };
       }
       let result;
@@ -14476,7 +15117,15 @@ function registerWikilinkFeedbackTools(server2, getStateDb) {
               content: [{ type: "text", text: JSON.stringify({ error: "entity and correct are required for report mode" }) }]
             };
           }
-          recordFeedback(stateDb2, entity, context || "", note_path || "", correct);
+          try {
+            recordFeedback(stateDb2, entity, context || "", note_path || "", correct);
+          } catch (e) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({
+                error: `Failed to record feedback: ${e instanceof Error ? e.message : String(e)}`
+              }) }]
+            };
+          }
           const suppressionUpdated = updateSuppressionList(stateDb2) > 0;
           result = {
             mode: "report",
@@ -14509,7 +15158,7 @@ function registerWikilinkFeedbackTools(server2, getStateDb) {
           break;
         }
         case "dashboard": {
-          const dashboard = getDashboardData(stateDb2);
+          const dashboard = getExtendedDashboardData(stateDb2);
           result = {
             mode: "dashboard",
             dashboard,
@@ -14518,6 +15167,44 @@ function registerWikilinkFeedbackTools(server2, getStateDb) {
           };
           break;
         }
+        case "entity_timeline": {
+          if (!entity) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: "entity is required for entity_timeline mode" }) }]
+            };
+          }
+          const timeline = getEntityScoreTimeline(stateDb2, entity, days_back ?? 30, limit ?? 100);
+          result = {
+            mode: "entity_timeline",
+            entity,
+            timeline,
+            count: timeline.length
+          };
+          break;
+        }
+        case "layer_timeseries": {
+          const timeseries = getLayerContributionTimeseries(stateDb2, granularity ?? "day", days_back ?? 30);
+          result = {
+            mode: "layer_timeseries",
+            granularity: granularity ?? "day",
+            timeseries,
+            buckets: timeseries.length
+          };
+          break;
+        }
+        case "snapshot_diff": {
+          if (!timestamp_before || !timestamp_after) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: "timestamp_before and timestamp_after are required for snapshot_diff mode" }) }]
+            };
+          }
+          const diff = compareGraphSnapshots(stateDb2, timestamp_before, timestamp_after);
+          result = {
+            mode: "snapshot_diff",
+            diff
+          };
+          break;
+        }
       }
       return {
         content: [
@@ -15693,7 +16380,16 @@ function registerVaultResources(server2, getIndex) {
 }
 
 // src/index.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname4(__filename);
+var pkg = JSON.parse(readFileSync4(join16(__dirname, "../package.json"), "utf-8"));
 var vaultPath = process.env.PROJECT_PATH || process.env.VAULT_PATH || findVaultRoot();
+var resolvedVaultPath;
+try {
+  resolvedVaultPath = realpathSync(vaultPath).replace(/\\/g, "/");
+} catch {
+  resolvedVaultPath = vaultPath.replace(/\\/g, "/");
+}
 var vaultIndex;
 var flywheelConfig = {};
 var stateDb = null;
@@ -15847,7 +16543,7 @@ var TOOL_CATEGORY = {
 };
 var server = new McpServer({
   name: "flywheel-memory",
-  version: "2.0.0"
+  version: pkg.version
 });
 var _registeredCount = 0;
 var _skippedCount = 0;
@@ -15931,6 +16627,7 @@ registerSystemTools(
   () => vaultPath,
   (newConfig) => {
     flywheelConfig = newConfig;
+    setWikilinkConfig(newConfig);
   },
   () => stateDb
 );
@@ -15957,6 +16654,7 @@ registerConfigTools(
   () => flywheelConfig,
   (newConfig) => {
     flywheelConfig = newConfig;
+    setWikilinkConfig(newConfig);
   },
   () => stateDb
 );
@@ -15974,7 +16672,7 @@ registerMergeTools2(server, () => stateDb);
 registerVaultResources(server, () => vaultIndex ?? null);
 serverLog("server", `Registered ${_registeredCount} tools, skipped ${_skippedCount}`);
 async function main() {
-  serverLog("server", "Starting Flywheel Memory server...");
+  serverLog("server", `Starting Flywheel Memory v${pkg.version}...`);
   serverLog("server", `Vault: ${vaultPath}`);
   const startTime = Date.now();
   try {
@@ -15986,6 +16684,7 @@ async function main() {
     serverLog("statedb", "Injected FTS5, embeddings, task cache handles");
     loadEntityEmbeddingsToMemory();
     setWriteStateDb(stateDb);
+    setRecencyStateDb(stateDb);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     serverLog("statedb", `StateDb initialization failed: ${msg}`, "error");
@@ -16139,6 +16838,7 @@ async function runPostIndexWork(index) {
     saveConfig(stateDb, inferred, existing);
   }
   flywheelConfig = loadConfig(stateDb);
+  setWikilinkConfig(flywheelConfig);
   const configKeys = Object.keys(flywheelConfig).filter((k) => flywheelConfig[k] != null);
   serverLog("config", `Config inferred: ${configKeys.join(", ")}`);
   if (stateDb) {
@@ -16190,6 +16890,48 @@ async function runPostIndexWork(index) {
       vaultPath,
       config,
       onBatch: async (batch) => {
+        const vaultPrefixes = /* @__PURE__ */ new Set([
+          vaultPath.replace(/\\/g, "/"),
+          resolvedVaultPath
+        ]);
+        for (const event of batch.events) {
+          const normalized = event.path.replace(/\\/g, "/");
+          let matched = false;
+          for (const prefix of vaultPrefixes) {
+            if (normalized.startsWith(prefix + "/")) {
+              event.path = normalized.slice(prefix.length + 1);
+              matched = true;
+              break;
+            }
+          }
+          if (!matched) {
+            try {
+              const resolved = realpathSync(event.path).replace(/\\/g, "/");
+              for (const prefix of vaultPrefixes) {
+                if (resolved.startsWith(prefix + "/")) {
+                  event.path = resolved.slice(prefix.length + 1);
+                  matched = true;
+                  break;
+                }
+              }
+            } catch {
+              try {
+                const dir = path29.dirname(event.path);
+                const base = path29.basename(event.path);
+                const resolvedDir = realpathSync(dir).replace(/\\/g, "/");
+                for (const prefix of vaultPrefixes) {
+                  if (resolvedDir.startsWith(prefix + "/") || resolvedDir === prefix) {
+                    const relDir = resolvedDir === prefix ? "" : resolvedDir.slice(prefix.length + 1);
+                    event.path = relDir ? `${relDir}/${base}` : base;
+                    matched = true;
+                    break;
+                  }
+                }
+              } catch {
+              }
+            }
+          }
+        }
         serverLog("watcher", `Processing ${batch.events.length} file changes`);
         const batchStart = Date.now();
         const changedPaths = batch.events.map((e) => e.path);
@@ -16200,6 +16942,11 @@ async function runPostIndexWork(index) {
           setIndexState("ready");
           tracker.end({ note_count: vaultIndex.notes.size, entity_count: vaultIndex.entities.size, tag_count: vaultIndex.tags.size });
           serverLog("watcher", `Index rebuilt: ${vaultIndex.notes.size} notes, ${vaultIndex.entities.size} entities`);
+          const hubBefore = /* @__PURE__ */ new Map();
+          if (stateDb) {
+            const rows = stateDb.db.prepare("SELECT name, hub_score FROM entities").all();
+            for (const r of rows) hubBefore.set(r.name, r.hub_score);
+          }
           const entitiesBefore = stateDb ? getAllEntitiesFromDb3(stateDb) : [];
           tracker.start("entity_scan", { note_count: vaultIndex.notes.size });
           await updateEntitiesInStateDb();
@@ -16207,11 +16954,6 @@ async function runPostIndexWork(index) {
           const entityDiff = computeEntityDiff(entitiesBefore, entitiesAfter);
           tracker.end({ entity_count: entitiesAfter.length, ...entityDiff });
           serverLog("watcher", `Entity scan: ${entitiesAfter.length} entities`);
-          const hubBefore = /* @__PURE__ */ new Map();
-          if (stateDb) {
-            const rows = stateDb.db.prepare("SELECT name, hub_score FROM entities").all();
-            for (const r of rows) hubBefore.set(r.name, r.hub_score);
-          }
           tracker.start("hub_scores", { entity_count: entitiesAfter.length });
           const hubUpdated = await exportHubScores(vaultIndex, stateDb);
           const hubDiffs = [];
@@ -16224,6 +16966,24 @@ async function runPostIndexWork(index) {
           }
           tracker.end({ updated: hubUpdated ?? 0, diffs: hubDiffs.slice(0, 10) });
           serverLog("watcher", `Hub scores: ${hubUpdated ?? 0} updated`);
+          tracker.start("recency", { entity_count: entitiesAfter.length });
+          try {
+            const cachedRecency = loadRecencyFromStateDb();
+            const cacheAgeMs = cachedRecency ? Date.now() - (cachedRecency.lastUpdated ?? 0) : Infinity;
+            if (cacheAgeMs >= 60 * 60 * 1e3) {
+              const entities = entitiesAfter.map((e) => ({ name: e.name, path: e.path, aliases: e.aliases }));
+              const recencyIndex2 = await buildRecencyIndex(vaultPath, entities);
+              saveRecencyToStateDb(recencyIndex2);
+              tracker.end({ rebuilt: true, entities: recencyIndex2.lastMentioned.size });
+              serverLog("watcher", `Recency: rebuilt ${recencyIndex2.lastMentioned.size} entities`);
+            } else {
+              tracker.end({ rebuilt: false, cached_age_ms: cacheAgeMs });
+              serverLog("watcher", `Recency: cache valid (${Math.round(cacheAgeMs / 1e3)}s old)`);
+            }
+          } catch (e) {
+            tracker.end({ error: String(e) });
+            serverLog("watcher", `Recency: failed: ${e}`);
+          }
           if (hasEmbeddingsIndex()) {
             tracker.start("note_embeddings", { files: batch.events.length });
             let embUpdated = 0;
@@ -16303,6 +17063,38 @@ async function runPostIndexWork(index) {
           }
           tracker.end({ updated: taskUpdated, removed: taskRemoved });
           serverLog("watcher", `Task cache: ${taskUpdated} updated, ${taskRemoved} removed`);
+          tracker.start("forward_links", { files: batch.events.length });
+          const forwardLinkResults = [];
+          let totalResolved = 0;
+          let totalDead = 0;
+          for (const event of batch.events) {
+            if (event.type === "delete" || !event.path.endsWith(".md")) continue;
+            try {
+              const links = getForwardLinksForNote(vaultIndex, event.path);
+              const resolved = [];
+              const dead = [];
+              const seen = /* @__PURE__ */ new Set();
+              for (const link of links) {
+                const name = link.target;
+                if (seen.has(name.toLowerCase())) continue;
+                seen.add(name.toLowerCase());
+                if (link.exists) resolved.push(name);
+                else dead.push(name);
+              }
+              if (resolved.length > 0 || dead.length > 0) {
+                forwardLinkResults.push({ file: event.path, resolved, dead });
+              }
+              totalResolved += resolved.length;
+              totalDead += dead.length;
+            } catch {
+            }
+          }
+          tracker.end({
+            total_resolved: totalResolved,
+            total_dead: totalDead,
+            links: forwardLinkResults
+          });
+          serverLog("watcher", `Forward links: ${totalResolved} resolved, ${totalDead} dead`);
           tracker.start("wikilink_check", { files: batch.events.length });
           const trackedLinks = [];
           if (stateDb) {
@@ -16376,6 +17168,8 @@ async function runPostIndexWork(index) {
     watcher.start();
     serverLog("watcher", "File watcher started");
   }
+  startSweepTimer(() => vaultIndex);
+  serverLog("server", "Sweep timer started (5 min interval)");
   const postDuration = Date.now() - postStart;
   serverLog("server", `Post-index work complete in ${postDuration}ms`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velvetmonkey/flywheel-memory",
-  "version": "2.0.33",
+  "version": "2.0.35",
   "description": "MCP server that gives Claude full read/write access to your Obsidian vault. 42 tools for search, backlinks, graph queries, mutations, and hybrid semantic search.",
   "type": "module",
   "main": "dist/index.js",
@@ -42,6 +42,8 @@
     "test:write": "vitest run test/write/",
     "test:security": "vitest run test/write/security/",
     "test:stress": "vitest run test/write/stress/ test/write/battle-hardening/",
+    "test:quality": "vitest run test/graph-quality/",
+    "test:quality:report": "tsx test/graph-quality/generate-proof.ts",
     "test:coverage": "vitest run --coverage",
     "test:ci": "vitest run --reporter=github-actions",
     "lint": "tsc --noEmit",
@@ -50,7 +52,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "@velvetmonkey/vault-core": "^2.0.33",
+    "@velvetmonkey/vault-core": "^2.0.34",
     "better-sqlite3": "^11.0.0",
     "chokidar": "^4.0.0",
     "gray-matter": "^4.0.3",