pi-doc-injector 0.5.0 → 0.5.2

package/README.md

@@ -1,6 +1,6 @@
 # Pi Doc Injector
 
-A [Pi](https://pi.dev) extension that automatically injects relevant project documentation into the LLM system prompt by monitoring streaming output for keyword matches.
+A [Pi](https://pi.dev) extension that automatically injects relevant project documentation into the LLM context by monitoring streaming output for keyword matches. Docs are delivered as a `CustomMessage` so the system prompt stays untouched and the provider's prompt cache stays warm.
 
 ## Installation
 
@@ -29,8 +29,9 @@ git clone https://github.com/yourname/pi-doc-injector.git .pi/extensions/doc-inj
 1. Create a `docs/` folder in your project root.
 2. Add markdown files with frontmatter (`title` + `keywords`). See [Document Format](#document-format) for supported formats.
 3. Start Pi. The extension scans `docs/` on session start.
-4. When the user mentions a keyword, the matching doc is injected into the
-   system prompt **before the assistant responds** — no one-turn delay.
+4. When the user mentions a keyword, the matching doc is injected as a
+   `CustomMessage` into the conversation **before the assistant responds** —
+   no one-turn delay. The system prompt is never modified.
 5. If the assistant mentions a NEW keyword mid-response, generation is
    automatically aborted and restarted with the doc injected immediately.
 
@@ -208,18 +209,41 @@ The extension uses a per-session injection model:
 - **Assistant streaming**: if the assistant mentions a NEW keyword mid-response,
   generation is aborted and restarted with the doc injected immediately.
 
-### System Prompt Lifecycle
+### Injection Mechanism
 
-Pi **reconstructs the system prompt from source files each turn** (verified against pi v0.70.6).
+On match, the extension returns a `message` field from `before_agent_start`
+with `customType: "doc-injector"`. Pi appends this to the session and sends
+it to the LLM as part of the conversation. The system prompt is **never**
+mutated.
 
-When `before_agent_start` fires, the `systemPrompt` passed to the extension is a freshly rebuilt prompt from `AGENTS.md`, `SYSTEM.md`, skills, and tool snippets. It is **not** accumulated from previous turns.
+#### Why a CustomMessage, not the system prompt?
 
-This means:
+- The system prompt is the highest-value prompt-cache slot. Each unique
+  system prompt text breaks the cache (5-min TTL by default). Appending
+  per-turn doc content there would invalidate the cache on every first
+  injection.
+- A `CustomMessage` only adds to the conversation prefix, leaving the
+  system prompt byte-identical across turns and the cache warm.
 
-- Injections apply to the **current turn only** and do not persist in subsequent turns.
-- There is no risk of duplicate injection sections stacking up over time.
-- The `injected` flag alone is sufficient to prevent re-injection — no additional deduplication or marker-based stripping is needed.
+#### Double-injection prevention
 
+Two independent guards make duplicate injection impossible in a session:
+
+1. **Matcher guard** — `buildMatcher()` only includes non-injected entries
+   (via `getNonInjectedEntries()`), so already-injected docs cannot be
+   re-matched.
+2. **Mark guard** — `markInjected()` runs inside `before_agent_start` before
+   the LLM call, so even if the matcher ever produced a duplicate, the
+   mark would still prevent a second send.
+
+In practice, the matcher guard is the primary defense; the mark guard is
+defense-in-depth for race conditions (e.g. if `resources_discover` rebuilds
+the registry mid-injection).
+
+The `injected` flag is per-session: it's reset on `session_start` and can
+be manually cleared with `/doc-inject reset`.
+
+For the full source-level verification, see the JSDoc block in `index.ts`.
 For the full source-level verification, see the JSDoc block in `index.ts`.
 
 ## Development

package/cache.ts

@@ -9,6 +9,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { KeywordCache } from "./types";
+import type { Notifier } from "./notifier";
 
 const CACHE_FILENAME = ".pi/doc-injector-cache.json";
 const CACHE_VERSION = 1;
@@ -17,8 +18,11 @@ const CACHE_VERSION = 1;
  * Load the keyword cache from disk.
  * Returns an empty cache (version 1, no files) if the file doesn't exist,
  * has wrong version, or is corrupted.
+ *
+ * Recoverable issues (corrupt JSON, wrong version) emit a warning via the
+ * `notifier`. ENOENT (no cache file yet) is silent.
  */
-export async function loadCache(cwd: string): Promise<KeywordCache> {
+export async function loadCache(cwd: string, notifier: Notifier): Promise<KeywordCache> {
   const cachePath = join(cwd, CACHE_FILENAME);
 
   try {
@@ -26,7 +30,7 @@ export async function loadCache(cwd: string): Promise<KeywordCache> {
     const parsed: unknown = JSON.parse(raw);
 
     if (!isValidCache(parsed)) {
-      console.warn(
+      notifier.warn(
         `[doc-injector] Invalid cache format or version at ${cachePath}, resetting.`,
       );
       return emptyCache();
@@ -36,10 +40,8 @@ export async function loadCache(cwd: string): Promise<KeywordCache> {
   } catch (err) {
     // ENOENT = no cache file yet, that's fine
     if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-      console.warn(
-        `[doc-injector] Failed to read cache at ${cachePath}:`,
-        err instanceof Error ? err.message : String(err),
-      );
+      const detail = err instanceof Error ? err.message : String(err);
+      notifier.warn(`[doc-injector] Failed to read cache at ${cachePath}: ${detail}`);
     }
     return emptyCache();
   }

package/config.ts

@@ -5,47 +5,56 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { DEFAULT_CONFIG, type DocInjectorConfig } from "./types";
+import type { Notifier } from "./notifier";
 
 /**
  * Clamp an integer value to [min, max] range.
- * Warns and clamps if out of range. Returns the default if not a number.
+ * Warns via the `notifier` and clamps if out of range. Returns the default
+ * if not a number.
  */
 function clampInt(
-  value: unknown,
-  defaultVal: number,
-  min: number,
-  max: number,
-  fieldName: string,
+    value: unknown,
+    defaultVal: number,
+    min: number,
+    max: number,
+    fieldName: string,
+    notifier: Notifier,
 ): number {
-  if (typeof value !== "number" || Number.isNaN(value)) {
-    return defaultVal;
-  }
-  const intVal = Math.trunc(value);
-  if (intVal < min || intVal > max) {
-    const clamped = Math.max(min, Math.min(max, intVal));
-    console.warn(`[doc-injector] ${fieldName} must be ${min}-${max}, got ${intVal}. Clamping to ${clamped}.`);
-    return clamped;
-  }
-  return intVal;
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        return defaultVal;
+    }
+    const intVal = Math.trunc(value);
+    if (intVal < min || intVal > max) {
+        const clamped = Math.max(min, Math.min(max, intVal));
+        notifier.warn(`[doc-injector] ${fieldName} must be ${min}-${max}, got ${intVal}. Clamping to ${clamped}.`);
+        return clamped;
+    }
+    return intVal;
 }
 
+/**
 /**
  * Validate a glob pattern array.
  * Rejects non-array or entries that aren't strings. Returns default on error.
+ * Warns via the `notifier` for non-string entries.
  */
-function validateGlobArray(value: unknown, defaultVal: string[]): string[] {
-  if (!Array.isArray(value)) {
-    return [...defaultVal];
-  }
-  const result: string[] = [];
-  for (const item of value) {
-    if (typeof item === "string") {
-      result.push(item);
-    } else {
-      console.warn(`[doc-injector] Non-string entry in glob array ignored: ${String(item)}`);
+function validateGlobArray(
+    value: unknown,
+    defaultVal: string[],
+    notifier: Notifier,
+): string[] {
+    if (!Array.isArray(value)) {
+        return [...defaultVal];
+    }
+    const result: string[] = [];
+    for (const item of value) {
+        if (typeof item === "string") {
+            result.push(item);
+        } else {
+            notifier.warn(`[doc-injector] Non-string entry in glob array ignored: ${String(item)}`);
+        }
     }
-  }
-  return result.length > 0 ? result : [...defaultVal];
+    return result.length > 0 ? result : [...defaultVal];
 }
 
 /**
@@ -54,33 +63,37 @@ function validateGlobArray(value: unknown, defaultVal: string[]): string[] {
  * Validates and clamps all numeric fields. Falls back to DEFAULT_CONFIG
  * if file doesn't exist or is invalid.
  */
-export async function loadConfig(cwd: string): Promise<DocInjectorConfig> {
-  const configPath = join(cwd, ".pi", "doc-injector.json");
+/**
+ * Load config from `.pi/doc-injector.json` relative to the given cwd.
+ * Async — uses readFile from fs/promises. Validates and clamps all numeric
+ * fields. Falls back to DEFAULT_CONFIG if the file doesn't exist or is
+ * invalid. Warnings (clamping, invalid entries) go through the `notifier`.
+ */
+export async function loadConfig(cwd: string, notifier: Notifier): Promise<DocInjectorConfig> {
+    const configPath = join(cwd, ".pi", "doc-injector.json");
 
-  try {
-    const raw = await readFile(configPath, "utf-8");
-    const parsed = JSON.parse(raw) as Partial<DocInjectorConfig>;
+    try {
+        const raw = await readFile(configPath, "utf-8");
+        const parsed = JSON.parse(raw) as Partial<DocInjectorConfig>;
 
-    return {
-      docsPath: parsed.docsPath ?? DEFAULT_CONFIG.docsPath,
-      matchThreshold: clampInt(parsed.matchThreshold, DEFAULT_CONFIG.matchThreshold, 1, Infinity, "matchThreshold"),
-      contextThreshold: clampInt(parsed.contextThreshold, DEFAULT_CONFIG.contextThreshold, 0, 100, "contextThreshold"),
-      recursive: parsed.recursive ?? DEFAULT_CONFIG.recursive,
-      include: validateGlobArray(parsed.include, DEFAULT_CONFIG.include),
-      exclude: validateGlobArray(parsed.exclude, DEFAULT_CONFIG.exclude),
-      maxFileSize: clampInt(parsed.maxFileSize, DEFAULT_CONFIG.maxFileSize, 1024, 10 * 1024 * 1024, "maxFileSize"),
-      autoKeywords: parsed.autoKeywords ?? DEFAULT_CONFIG.autoKeywords,
-      llmKeywords: parsed.llmKeywords ?? DEFAULT_CONFIG.llmKeywords,
-      maxConcurrent: clampInt(parsed.maxConcurrent, DEFAULT_CONFIG.maxConcurrent, 1, 100, "maxConcurrent"),
-      llmBatchSize: clampInt(parsed.llmBatchSize, DEFAULT_CONFIG.llmBatchSize, 1, 100, "llmBatchSize"),
-    };
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-      console.warn(
-        `[doc-injector] Failed to parse config at ${configPath}:`,
-        err instanceof Error ? err.message : String(err),
-      );
+        return {
+            docsPath: parsed.docsPath ?? DEFAULT_CONFIG.docsPath,
+            matchThreshold: clampInt(parsed.matchThreshold, DEFAULT_CONFIG.matchThreshold, 1, Infinity, "matchThreshold", notifier),
+            contextThreshold: clampInt(parsed.contextThreshold, DEFAULT_CONFIG.contextThreshold, 0, 100, "contextThreshold", notifier),
+            recursive: parsed.recursive ?? DEFAULT_CONFIG.recursive,
+            include: validateGlobArray(parsed.include, DEFAULT_CONFIG.include, notifier),
+            exclude: validateGlobArray(parsed.exclude, DEFAULT_CONFIG.exclude, notifier),
+            maxFileSize: clampInt(parsed.maxFileSize, DEFAULT_CONFIG.maxFileSize, 1024, 10 * 1024 * 1024, "maxFileSize", notifier),
+            autoKeywords: parsed.autoKeywords ?? DEFAULT_CONFIG.autoKeywords,
+            llmKeywords: parsed.llmKeywords ?? DEFAULT_CONFIG.llmKeywords,
+            maxConcurrent: clampInt(parsed.maxConcurrent, DEFAULT_CONFIG.maxConcurrent, 1, 100, "maxConcurrent", notifier),
+            llmBatchSize: clampInt(parsed.llmBatchSize, DEFAULT_CONFIG.llmBatchSize, 1, 100, "llmBatchSize", notifier),
+        };
+    } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+            const detail = err instanceof Error ? err.message : String(err);
+            notifier.warn(`[doc-injector] Failed to parse config at ${configPath}: ${detail}`);
+        }
+        return { ...DEFAULT_CONFIG };
     }
-    return { ...DEFAULT_CONFIG };
-  }
 }

package/index.ts

@@ -71,13 +71,19 @@ import { loadConfig } from "./config";
 import { buildInjectionContent, notifyInjection } from "./injector";
 import { buildKeywordGenPrompt } from "./keyword-llm";
 import { extractText, KeywordMatcher } from "./matcher";
+import { ExtensionNotifier, type Notifier } from "./notifier";
 import { DocRegistry } from "./registry";
-import { DEFAULT_MATCHER_OPTIONS, type DocEntry, type MatchResult, type KeywordCache, type CacheEntry } from "./types";
+import { DEFAULT_MATCHER_OPTIONS, LLM_CACHE_SENTINEL, type DocEntry, type MatchResult, type KeywordCache, type CacheEntry } from "./types";
 import { registerCommands } from "./commands";
 
 export default async function docInjectorExtension(pi: ExtensionAPI) {
   // ---- State ----
-  let config = await loadConfig(process.cwd());
+  // The notifier buffers warnings emitted during startup (loadConfig,
+  // loadCache, initRegistry) and flushes them via ctx.ui.notify() in
+  // session_start. The notifier is bound to the extension lifecycle so
+  // startup messages aren't lost.
+  const notifier: Notifier = new ExtensionNotifier();
+  let config = await loadConfig(process.cwd(), notifier);
   let registry: DocRegistry | null = null;
   let initRegistryPromise: Promise<void> | null = null;
   let enabled = true;
@@ -102,7 +108,7 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
   const safeSaveCache = async (cwd: string, dirtyEntries: Record<string, CacheEntry>) => {
     // MAJOR-2 fix: before saveCache, re-read cache from disk to merge
     // LLM-written entries that may have landed during the scan.
-    const freshCache = await loadCache(cwd);
+    const freshCache = await loadCache(cwd, notifier);
     const mergedCache: KeywordCache = { version: 1, files: {} };
 
     // Start with fresh (disk) entries — includes any LLM writes during scan
@@ -119,10 +125,10 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
   };
 
   const initRegistry = async (cwd: string) => {
-    config = await loadConfig(cwd);
+    config = await loadConfig(cwd, notifier);
     const docsPath = resolve(cwd, config.docsPath);
-    cache = await loadCache(cwd);
-    registry = await DocRegistry.create(docsPath, config, cache);
+    cache = await loadCache(cwd, notifier);
+    registry = await DocRegistry.create(docsPath, config, cache, notifier);
 
     const dirty = registry.getDirtyCache();
     if (Object.keys(dirty).length > 0) {
@@ -178,7 +184,9 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
           continue;
         }
         cache.files[item.path] = {
-          mtimeMs: fileStat.mtimeMs,
+          // Use the sentinel — never the real mtime — so the next rebuild
+          // surfaces this entry as keywordSource: "llm" instead of "cache".
+          mtimeMs: LLM_CACHE_SENTINEL,
           keywords: item.keywords.map((k) => k.toLowerCase()).slice(0, 20),
         };
         saved++;
@@ -203,6 +211,12 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
     llmBatchesCompleted = 0;
     llmTotalFiles = 0;
 
+    // Bind the notifier to the live context FIRST so any warnings emitted
+    // during initRegistry below go directly to the TUI instead of being
+    // buffered. Messages buffered from earlier (e.g. the factory-body
+    // loadConfig call) are flushed here in arrival order.
+    notifier.setContext(ctx);
+
     if (event.reason === "reload") return;
 
     if (initRegistryPromise) {
@@ -223,7 +237,7 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
     const effectiveCwd = cwd ?? process.cwd();
 
     // Reload cache from disk to pick up LLM-generated entries
-    const freshCache = await loadCache(effectiveCwd);
+    const freshCache = await loadCache(effectiveCwd, notifier);
     cache = freshCache;
     registry.updateCache(cache);
 

package/notifier.ts

@@ -0,0 +1,71 @@
+/**
+ * Notifier — thin wrapper around Pi's `ctx.ui.notify()` that buffers
+ * messages until a context is available.
+ *
+ * ## Why a buffer?
+ *
+ * Several warnings fire at startup (during `loadConfig` and `initRegistry`),
+ * before any `ExtensionContext` exists — extensions are constructed first,
+ * events fire later. The `Notifier` interface accepts messages at any time:
+ *
+ * - If a context has been set, messages are forwarded to `ctx.ui.notify()`.
+ * - If not, messages are buffered in memory and flushed on the next
+ *   `setContext()` call (typically from `session_start`).
+ *
+ * Production code uses `ExtensionNotifier`. Tests inject a plain object
+ * satisfying the `Notifier` interface (or a `vi.fn()` spy) — no real
+ * extension context is needed.
+ */
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+export type NotifierLevel = "info" | "warning" | "error";
+
+export interface Notifier {
+    /** Show an informational message. */
+    info(message: string): void;
+    /** Show a warning. */
+    warn(message: string): void;
+    /** Show an error. */
+    error(message: string): void;
+    /**
+     * Bind a context. Flushes any buffered messages via `ctx.ui.notify()`
+     * in arrival order. Idempotent: re-calling replaces the context and
+     * clears the buffer (already-flushed messages are not re-sent).
+     */
+    setContext(ctx: ExtensionContext): void;
+}
+
+/** Production notifier. Buffers until a context is bound. */
+export class ExtensionNotifier implements Notifier {
+    private ctx: ExtensionContext | null = null;
+    private buffer: Array<{ level: NotifierLevel; message: string }> = [];
+
+    setContext(ctx: ExtensionContext): void {
+        this.ctx = ctx;
+        const pending = this.buffer;
+        this.buffer = [];
+        for (const { level, message } of pending) {
+            ctx.ui.notify(message, level);
+        }
+    }
+
+    info(message: string): void {
+        this.emit("info", message);
+    }
+
+    warn(message: string): void {
+        this.emit("warning", message);
+    }
+
+    error(message: string): void {
+        this.emit("error", message);
+    }
+
+    private emit(level: NotifierLevel, message: string): void {
+        if (this.ctx) {
+            this.ctx.ui.notify(message, level);
+        } else {
+            this.buffer.push({ level, message });
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-doc-injector",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Auto-inject relevant project documentation into Pi's LLM context based on keyword matching",
   "type": "module",
   "main": "./index.ts",

package/registry.ts

@@ -8,7 +8,8 @@
 import type { Dirent } from "node:fs";
 import { readdir, readFile, stat } from "node:fs/promises";
 import { basename, extname, join, relative, resolve } from "node:path";
-import type { CacheEntry, DocEntry, DocInjectorConfig, KeywordCache } from "./types";
+import { LLM_CACHE_SENTINEL, type CacheEntry, type DocEntry, type DocInjectorConfig, type KeywordCache } from "./types";
+import type { Notifier } from "./notifier";
 import { createGlobFilter } from "./globber";
 import { generateKeywords } from "./keyword-gen";
 
@@ -225,28 +226,36 @@ class PromisePool {
  * Document Registry class. Scans a docs folder and maintains an index of DocEntry.
  */
 export class DocRegistry {
-  private entries: DocEntry[] = [];
-  private docsPath: string;
-  private config: DocInjectorConfig;
-  private cache: KeywordCache | null = null;
-  private dirtyCache: KeywordCache = { version: 1, files: {} };
-
-  private constructor(docsPath: string, config: DocInjectorConfig, cache?: KeywordCache) {
-    this.docsPath = docsPath;
-    this.config = config;
-    this.cache = cache ?? null;
-  }
+    private entries: DocEntry[] = [];
+    private docsPath: string;
+    private config: DocInjectorConfig;
+    private cache: KeywordCache | null = null;
+    private dirtyCache: KeywordCache = { version: 1, files: {} };
+    private notifier: Notifier;
+
+    private constructor(
+        docsPath: string,
+        config: DocInjectorConfig,
+        cache: KeywordCache | undefined,
+        notifier: Notifier,
+    ) {
+        this.docsPath = docsPath;
+        this.config = config;
+        this.cache = cache ?? null;
+        this.notifier = notifier;
+    }
 
-  /** Create a registry by scanning the docs folder. */
-  static async create(
-    docsPath: string,
-    config: DocInjectorConfig,
-    cache?: KeywordCache,
-  ): Promise<DocRegistry> {
-    const registry = new DocRegistry(docsPath, config, cache);
-    await registry.rebuild();
-    return registry;
-  }
+    /** Create a registry by scanning the docs folder. */
+    static async create(
+        docsPath: string,
+        config: DocInjectorConfig,
+        cache: KeywordCache | undefined,
+        notifier: Notifier,
+    ): Promise<DocRegistry> {
+        const registry = new DocRegistry(docsPath, config, cache, notifier);
+        await registry.rebuild();
+        return registry;
+    }
 
   /** Re-scan the docs folder and rebuild the index. */
   async rebuild(): Promise<void> {
@@ -274,106 +283,124 @@ export class DocRegistry {
       const results = await pool.all(tasks);
       this.entries = results.filter((e): e is DocEntry => e !== null);
     } catch {
-      console.warn(`[doc-injector] Docs folder not found: ${resolved}`);
+      this.notifier.warn(`[doc-injector] Docs folder not found: ${resolved}`);
       this.entries = [];
     }
   }
 
   /**
-   * Process a single file through the full pipeline.
+   * Process a single file through the priority chain.
    * Returns a DocEntry or null if the file should be skipped.
+   *
+   * Priority (highest to lowest):
+   *   1. Frontmatter (authoritative — explicitly written by the doc author)
+   *   2. Cache (perf layer — mtime match means content hasn't changed)
+   *   3. Heuristic (free, automatic, local — filename + headings + code symbols)
+   *   4. Skip (no frontmatter, no cache, autoKeywords disabled)
+   *
+   * LLM-generated keywords populate the cache via the `_doc_injector_keywords`
+   * tool, so they surface as `keywordSource: "cache"` on the next rebuild
+   * (their `mtimeMs` is set to the file's current mtime when written).
    */
   private async processFile(
     { filePath, relativePath, fileName }: ScanResult,
     preserved: Map<string, boolean>,
   ): Promise<DocEntry | null> {
     try {
-      // ═══ METADATA + CACHE ═══
-
-      // Step 1: Stat the file for size and mtime
+      // ─── METADATA ─────────────────────────────────────────────
       const fileStat = await stat(filePath);
 
-      // Step 2: Skip files exceeding maxFileSize
       if (fileStat.size > this.config.maxFileSize) {
-        console.warn(
+        this.notifier.warn(
           `[doc-injector] Skipping ${relativePath}: size ${fileStat.size} > max ${this.config.maxFileSize}`,
         );
         return null;
       }
 
-      const cachedEntry = this.cache?.files[relativePath];
-
-      // Step 6: Cache hit — mtime matches, use cached keywords
-      if (cachedEntry && cachedEntry.mtimeMs === fileStat.mtimeMs) {
-        // Still read the file for content and title (needed for injection),
-        // but skip keyword generation entirely
-        const raw = await readFile(filePath, "utf-8");
-        const title = extractTitle(raw, fileName);
+      // Read once — needed for frontmatter parse, content, and title.
+      const raw = await readFile(filePath, "utf-8");
 
+      // ─── PRIORITY 1: Frontmatter (authoritative) ─────────────
+      const parsed = parseFrontmatter(raw);
+      if (parsed) {
+        // Frontmatter is self-caching (lives in the file), no dirty mark needed.
         return {
           filePath,
           fileName,
           relativePath,
-          title,
-          keywords: cachedEntry.keywords,
+          title: parsed.title,
+          keywords: parsed.keywords,
           content: raw,
           injected: preserved.get(filePath) ?? false,
-          keywordSource: "cache",
+          keywordSource: "frontmatter",
         };
       }
 
-      // ═══ FULL READ + PARSE (cache miss) ═══
-
-      // Step 7: Read file content
-      const raw = await readFile(filePath, "utf-8");
+      // ─── PRIORITY 2: Cache (mtime match means content unchanged) ──
+      const cachedEntry = this.cache?.files[relativePath];
+      if (cachedEntry) {
+        // LLM-generated: sentinel mtime never matches a real file
+        if (cachedEntry.mtimeMs === LLM_CACHE_SENTINEL) {
+          const title = extractTitle(raw, fileName);
+          return {
+            filePath,
+            fileName,
+            relativePath,
+            title,
+            keywords: cachedEntry.keywords,
+            content: raw,
+            injected: preserved.get(filePath) ?? false,
+            keywordSource: "llm",
+          };
+        }
+        // Real mtime match: heuristic or prior LLM-upgrade cache hit
+        if (cachedEntry.mtimeMs === fileStat.mtimeMs) {
+          const title = extractTitle(raw, fileName);
+          return {
+            filePath,
+            fileName,
+            relativePath,
+            title,
+            keywords: cachedEntry.keywords,
+            content: raw,
+            injected: preserved.get(filePath) ?? false,
+            keywordSource: "cache",
+          };
+        }
+      }
 
-      // Step 8: Try frontmatter parsing
-      const parsed = parseFrontmatter(raw);
+      // ─── PRIORITY 3: Heuristic (free, automatic fallback) ─────────
+      if (this.config.autoKeywords) {
+        const title = extractTitle(raw, fileName);
+        const keywords = generateKeywords(fileName, raw);
 
-      let title: string;
-      let keywords: string[];
-      let keywordSource: DocEntry["keywordSource"];
+        // Mark cache dirty (newly generated keywords must be persisted).
+        this.dirtyCache.files[relativePath] = {
+          mtimeMs: fileStat.mtimeMs,
+          keywords,
+        };
 
-      if (parsed) {
-        // Step 9: Frontmatter found — use its title and keywords
-        title = parsed.title;
-        keywords = parsed.keywords;
-        keywordSource = "frontmatter";
-      } else if (this.config.autoKeywords) {
-        // Step 10: No frontmatter, generate keywords heuristically
-        title = extractTitle(raw, fileName);
-        keywords = generateKeywords(fileName, raw);
-        keywordSource = "heuristic";
-      } else {
-        // Step 11: No frontmatter and autoKeywords disabled — skip
-        console.warn(
-          `[doc-injector] Skipping ${relativePath}: no valid frontmatter with keywords`,
-        );
-        return null;
+        return {
+          filePath,
+          fileName,
+          relativePath,
+          title,
+          keywords,
+          content: raw,
+          injected: preserved.get(filePath) ?? false,
+          keywordSource: "heuristic",
+        };
       }
 
-      // ═══ CACHE UPDATE ═══
-
-      // Step 12: Mark as dirty (mtime changed or keywords generated)
-      this.dirtyCache.files[relativePath] = {
-        mtimeMs: fileStat.mtimeMs,
-        keywords,
-      };
-
-      return {
-        filePath,
-        fileName,
-        relativePath,
-        title,
-        keywords,
-        content: raw,
-        injected: preserved.get(filePath) ?? false,
-        keywordSource,
-      };
+      // ─── PRIORITY 4: Skip ───────────────────────────────────────────
+      this.notifier.warn(
+        `[doc-injector] Skipping ${relativePath}: no valid frontmatter with keywords`,
+      );
+      return null;
     } catch (err) {
       // Only warn for unexpected errors, not ENOENT (file deleted/moved after scan)
       if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-        console.warn(`[doc-injector] Error reading ${relativePath}:`, err);
+        this.notifier.warn(`[doc-injector] Error reading ${relativePath}: ${err instanceof Error ? err.message : String(err)}`);
       }
       return null;
     }

package/types.ts

@@ -107,4 +107,16 @@ export const DEFAULT_CONFIG: DocInjectorConfig = {
 export const DEFAULT_MATCHER_OPTIONS: MatcherOptions = {
   matchThreshold: DEFAULT_CONFIG.matchThreshold,
   caseSensitive: false,
-};
+};
+
+/**
+ * Sentinel value used in CacheEntry.mtimeMs to mark entries written by the
+ * LLM keyword generator. -1 is chosen because Node.Stats.mtimeMs is documented
+ * as a non-negative integer (milliseconds since the Unix Epoch), so a real
+ * file can never have mtimeMs === -1. Heuristic-written entries use the real
+ * file mtime, which is always >= 0.
+ *
+ * If you find yourself writing LLM_CACHE_SENTINEL into a real cache entry
+ * from a non-LLM code path, that's a bug.
+ */
+export const LLM_CACHE_SENTINEL = -1;