pi-doc-injector 0.1.0 → 0.1.2

package/README.md

@@ -13,7 +13,7 @@ pi install npm:pi-doc-injector
 ### Via git
 
 ```bash
-pi install git:github.com/yourname/pi-doc-injector
+pi install git:github.com/lmn451/pi-doc-injector
 ```
 
 ### Manual
@@ -36,6 +36,7 @@ keywords: [test, testing, jest, vitest]
 ---
 
 # Testing Workflow
+
 Your documentation here...
 ```
 
@@ -57,19 +58,23 @@ keywords:
 
 ## Configuration
 
-Create `.pi/doc-injector.json` to customize behavior:
+Create `.pi/doc-injector.json` in your project root to customize behavior:
 
 ```json
 {
   "docsPath": "./docs",
-  "matchThreshold": 2
+  "matchThreshold": 2,
+  "contextThreshold": 80,
+  "recursive": true
 }
 ```
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `docsPath` | `./docs` | Path to your documentation folder |
-| `matchThreshold` | `2` | Minimum keyword matches before injecting |
+| Option             | Default    | Description                                              |
+| ------------------ | ---------- | -------------------------------------------------------- |
+| `docsPath`         | `"./docs"` | Path to docs folder (relative to project root)           |
+| `matchThreshold`   | `2`        | Minimum keyword matches required to inject a doc         |
+| `contextThreshold` | `80`       | Skip injection when context usage exceeds this % (0–100) |
+| `recursive`        | `true`     | Scan docs subdirectories recursively                     |
 
 ### Keyword Matching
 
@@ -79,15 +84,24 @@ Injection is also skipped if the current context usage exceeds 80% of the token
 
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `/doc-inject on` | Enable auto-injection |
-| `/doc-inject off` | Disable auto-injection |
-| `/doc-inject toggle` | Toggle on/off |
-| `/doc-inject status` | Show injector status, doc count, keyword count |
-| `/doc-inject list` | List all registered documents |
-| `/doc-inject reset` | Reset injection state (allows re-matching docs) |
-| `/doc-reload` | Re-scan docs folder |
+| Command              | Description                                          |
+| -------------------- | ---------------------------------------------------- |
+| `/doc-inject on`     | Enable doc injection                                 |
+| `/doc-inject off`    | Disable doc injection                                |
+| `/doc-inject toggle` | Toggle doc injection on/off                          |
+| `/doc-inject list`   | List all registered docs and their injection status  |
+| `/doc-inject reset`  | Reset all injected flags (docs become re-injectable) |
+| `/doc-inject status` | Show current injection status and config             |
+| `/doc-reload`        | Re-scan docs folder and rebuild registry             |
+
+## Injection Lifecycle
+
+The extension uses a per-session injection model:
+
+- On `session_start`, the registry is rebuilt from scratch, resetting all `injected` flags.
+- Within a session, once a document is injected, it won't be re-injected automatically.
+- Use `/doc-inject reset` to manually reset all flags and allow docs to be injected again.
+- Use `/doc-inject list` to see which docs have been injected (✅) and which are pending (⬜).
 
 ## Development
 

package/commands.ts

@@ -4,38 +4,40 @@
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { DocRegistry } from "./registry";
 
-export function registerCommands(
-  pi: ExtensionAPI,
-  getRegistry: () => DocRegistry | null,
-  getEnabled: () => boolean,
-  setEnabled: (v: boolean) => void,
-): void {
-  const cmd = (name: string, desc: string, handler: (args: string, ctx: ExtensionContext) => void) => {
+export interface CommandDeps {
+  getRegistry: () => DocRegistry | null;
+  getEnabled: () => boolean;
+  setEnabled: (v: boolean) => void;
+  reloadRegistry: () => Promise<number>;
+}
+
+export function registerCommands(pi: ExtensionAPI, deps: CommandDeps): void {
+  const cmd = (name: string, desc: string, handler: (args: string, ctx: ExtensionContext) => Promise<void>) => {
     pi.registerCommand(name, { description: desc, handler });
   };
 
-  cmd("doc-inject", "Doc injector: on|off|toggle|list|reset|status", (args, ctx) => {
+  cmd("doc-inject", "Doc injector: on|off|toggle|list|reset|status", async (args, ctx) => {
     const a = args.trim().toLowerCase();
     if (a === "on") {
-      setEnabled(true);
-      ctx.ui.notify("📄 Doc injection enabled", "success");
+      deps.setEnabled(true);
+      ctx.ui.notify("📄 Doc injection enabled", "info");
     } else if (a === "off") {
-      setEnabled(false);
+      deps.setEnabled(false);
       ctx.ui.notify("📄 Doc injection disabled", "warning");
     } else if (a === "toggle") {
-      const next = !getEnabled();
-      setEnabled(next);
+      const next = !deps.getEnabled();
+      deps.setEnabled(next);
       ctx.ui.notify(`📄 Doc injection ${next ? "enabled" : "disabled"}`, "info");
     } else if (a === "reset") {
-      const reg = getRegistry();
+      const reg = deps.getRegistry();
       if (reg) {
         reg.reset();
-        ctx.ui.notify("📄 Injection state reset", "success");
+        ctx.ui.notify("📄 Injection state reset", "info");
       } else {
         ctx.ui.notify("📄 No registry loaded", "warning");
       }
     } else if (a === "list") {
-      const reg = getRegistry();
+      const reg = deps.getRegistry();
       if (!reg) {
         ctx.ui.notify("📄 No docs loaded", "warning");
         return;
@@ -47,12 +49,12 @@ export function registerCommands(
       }
       const lines = entries.map((e) => {
         const status = e.injected ? "✅" : "⬜";
-        return `${status} ${e.fileName}: "${e.title}" — keywords: [${e.keywords.join(", ")}]`;
+        return `${status} ${e.relativePath}: "${e.title}" — keywords: [${e.keywords.join(", ")}]`;
       });
       ctx.ui.notify(`📄 Registered docs:\n${lines.join("\n")}`, "info");
     } else {
       // status (default)
-      const reg = getRegistry();
+      const reg = deps.getRegistry();
       if (!reg) {
         ctx.ui.notify("📄 Status: No registry loaded", "warning");
         return;
@@ -62,7 +64,7 @@ export function registerCommands(
       const kwCount = entries.reduce((sum, e) => sum + e.keywords.length, 0);
       ctx.ui.notify(
         `📄 Doc Injector Status:\n` +
-        `  Enabled: ${getEnabled() ? "✅" : "❌"}\n` +
+        `  Enabled: ${deps.getEnabled() ? "✅" : "❌"}\n` +
         `  Docs: ${entries.length}\n` +
         `  Keywords: ${kwCount}\n` +
         `  Injected: ${injected}`,
@@ -71,21 +73,12 @@ export function registerCommands(
     }
   });
 
-  cmd("doc-reload", "Re-scan docs folder and rebuild registry", (_args, ctx) => {
-    const reg = getRegistry();
-    if (!reg) {
-      ctx.ui.notify("📄 No registry to reload", "warning");
-      return;
-    }
-    // We can't call rebuild() async from a command handler easily,
-    // so we notify and trigger via the event system
-    ctx.ui.notify("📄 Triggering docs reload…", "info");
-    // Trigger a resources_discover-like reload by rebuilding directly
-    reg.rebuild().then(() => {
-      const count = reg.getEntries().length;
-      ctx.ui.notify(`📄 Reloaded: ${count} documents found`, "success");
-    }).catch((err) => {
+  cmd("doc-reload", "Re-scan docs folder and rebuild registry", async (_args, ctx) => {
+    try {
+      const count = await deps.reloadRegistry();
+      ctx.ui.notify(`📄 Reloaded: ${count} documents found`, "info");
+    } catch (err) {
       ctx.ui.notify(`📄 Reload failed: ${err instanceof Error ? err.message : String(err)}`, "error");
-    });
+    }
   });
 }

package/config.ts

@@ -21,9 +21,25 @@ export function loadConfig(cwd: string): DocInjectorConfig {
     const raw = readFileSync(configPath, "utf-8");
     const parsed = JSON.parse(raw) as Partial<DocInjectorConfig>;
 
+    // Clamp contextThreshold to 0-100 range
+    let contextThreshold = parsed.contextThreshold ?? DEFAULT_CONFIG.contextThreshold;
+    if (typeof contextThreshold === "number" && (contextThreshold < 0 || contextThreshold > 100)) {
+      console.warn(`[doc-injector] contextThreshold must be 0-100, got ${contextThreshold}. Clamping.`);
+      contextThreshold = Math.max(0, Math.min(100, contextThreshold));
+    }
+
+    // Clamp matchThreshold to positive integers
+    let matchThreshold = parsed.matchThreshold ?? DEFAULT_CONFIG.matchThreshold;
+    if (typeof matchThreshold === "number" && matchThreshold < 1) {
+      console.warn(`[doc-injector] matchThreshold must be >= 1, got ${matchThreshold}. Using 1.`);
+      matchThreshold = 1;
+    }
+
     return {
       docsPath: parsed.docsPath ?? DEFAULT_CONFIG.docsPath,
-      matchThreshold: parsed.matchThreshold ?? DEFAULT_CONFIG.matchThreshold,
+      matchThreshold,
+      contextThreshold,
+      recursive: parsed.recursive ?? DEFAULT_CONFIG.recursive,
     };
   } catch (err) {
     console.warn(

package/docs/bun.md

@@ -0,0 +1,32 @@
+---
+title: "JavaScript Runtime & Package Manager"
+keywords: [bun, package manager, runtime, install, test, build]
+---
+
+# JavaScript Runtime & Package Manager
+
+This project uses **Bun** as its JavaScript runtime and package manager.
+
+## Why Bun?
+
+- Fast native TypeScript support (no separate tsc step needed)
+- All-in-one runtime, bundler, and test runner
+- Drop-in replacement for Node.js and npm/yarn/pnpm
+- Significantly faster installs and test executions
+
+## Common Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Run tests in watch mode (recommended for development)
+bun test --watch
+```
+
+## Version
+
+This project requires Bun >= 1.3.0. The lockfile (`bun.lock`) ensures reproducible installs.

package/docs/publish.md

@@ -0,0 +1,80 @@
+---
+title: "Publishing Workflow"
+keywords: [publish, release, npm, version, tag, semantic versioning]
+---
+
+# Publishing Workflow
+
+## Versioning
+
+We follow [Semantic Versioning](https://semver.org/):
+- **MAJOR** — incompatible API changes
+- **MINOR** — backwards-compatible functionality additions
+- **PATCH** — backwards-compatible bug fixes
+
+## Publishing a New Version
+
+### 1. Bump the version
+
+```bash
+npm version patch  # 0.1.1 → 0.1.2
+npm version minor  # 0.1.1 → 0.2.0
+npm version major  # 0.1.1 → 1.0.0
+```
+
+This updates `package.json` and creates a local tag.
+
+### 2. Push the tag to trigger the workflow
+
+```bash
+git push origin v0.1.1
+```
+
+Or push all tags:
+
+```bash
+git push origin --tags
+```
+
+**Important:** The publish workflow triggers on tags pushed to remote, not just locally created tags. The tag must match the pattern `v*` (e.g., `v0.1.1`, `v0.2.0`).
+
+### 3. GitHub Actions Publish workflow
+
+Once the tag is pushed, the `Publish` workflow automatically:
+- Runs tests
+- Publishes to npm registry
+
+Monitor the workflow at: `https://github.com/lmn451/pi-docs/actions`
+
+## Verify the Publish
+
+Check if the package was published:
+
+```bash
+npm view pi-doc-injector
+```
+
+## Manual Publish
+
+If needed, you can publish manually:
+
+```bash
+npm publish
+```
+
+## Setup
+
+Ensure your npm token is configured as a GitHub secret:
+- Go to repository Settings → Secrets and variables → Actions
+- Add a new secret named `NPM_TOKEN` with your npm access token
+
+## Troubleshooting
+
+**Workflow didn't run?**
+- Verify the tag exists remotely: `git ls-remote origin refs/tags/v0.1.1`
+- Check that the tag matches the pattern `v*`
+- Check GitHub Actions runs at: `https://github.com/lmn451/pi-docs/actions`
+
+**npm publish failed?**
+- Ensure `NPM_TOKEN` secret is set
+- Verify the version hasn't already been published

package/index.ts

@@ -3,6 +3,32 @@
  *
  * Automatically injects relevant project documentation into the LLM context
  * by monitoring streaming output for keyword matches.
+ *
+ * ## Streaming Model
+ *
+ * This extension relies on Pi's streaming event contract:
+ * - `message_update`: Fires with the FULL accumulated assistant content on each
+ *   streaming chunk. The extension replaces (not appends to) its text buffer
+ *   on each update.
+ * - `message_end`: Fires once when the assistant's response is complete.
+ *   The extension finalizes matches and notifies the user.
+ * - `before_agent_start`: Fires before the next agent turn. The extension
+ *   injects matched docs into the system prompt, then marks them as injected.
+ *
+ * ## Injection Lifecycle
+ *
+ * The `injected` flag is per-session: when `session_start` fires, the registry
+ * is recreated from scratch (via initRegistry), resetting all flags. Within a
+ * session, once a doc is injected, it won't be re-injected unless the user
+ * manually runs `/doc-inject reset`.
+ *
+ * ## Race Condition Note
+ *
+ * If `resources_discover` (rebuild) fires while `before_agent_start` is running,
+ * `registry.entries` gets replaced. The `matchedEntries` array would hold stale
+ * references. The current code is safe because `pendingMatches` (a Map by filePath)
+ * is cleared after injection, and `markInjected()` operates on the registry's
+ * current entries, not the stale array.
  */
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { resolve } from "node:path";
@@ -31,7 +57,7 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
   const initRegistry = async (cwd: string) => {
     config = loadConfig(cwd);
     const docsPath = resolve(cwd, config.docsPath);
-    registry = await DocRegistry.create(docsPath);
+    registry = await DocRegistry.create(docsPath, config.recursive);
     const count = registry.getEntries().length;
     if (count > 0) {
       console.log(`[doc-injector] Loaded ${count} documents from ${docsPath}`);
@@ -53,25 +79,34 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
     await initRegistry(ctx.cwd);
   });
 
+  const reloadRegistry = async (): Promise<number> => {
+    if (!registry) throw new Error("No registry loaded");
+    await registry.rebuild();
+    const count = registry.getEntries().length;
+    console.log(`[doc-injector] Reloaded: ${count} documents`);
+    return count;
+  };
+
   // ---- Event: resources_discover (reload) ----
-  pi.on("resources_discover", async (_event, ctx) => {
-    if (registry) {
-      await registry.rebuild();
-      const count = registry.getEntries().length;
-      console.log(`[doc-injector] Reloaded: ${count} documents`);
-    }
+  pi.on("resources_discover", async (_event, _ctx) => {
+    await reloadRegistry();
   });
 
   // ---- Event: message_update (streaming detection) ----
+  // NOTE: Pi's message_update event sends the full accumulated content of the
+  // assistant message on each update, not just the delta. We therefore REPLACE
+  // (not append to) the text buffer on each event, ensuring we always match
+  // against the complete message text.
   pi.on("message_update", async (event, _ctx) => {
     if (!enabled || !registry) return;
 
     // Only process assistant messages
-    const msg = event.message as Record<string, unknown> | undefined;
-    if (!msg || msg.role !== "assistant") return;
+    const msg = event.message;
+    if (msg.role !== "assistant") return;
 
     // Replace buffer with full message text (message_update contains full content)
-    textBuffer = extractText(msg.content);
+    const content = (msg as unknown as { content: unknown }).content;
+    textBuffer = extractText(content);
     if (!textBuffer) return;
 
     // Run matcher
@@ -90,8 +125,8 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
   pi.on("message_end", async (event, ctx) => {
     if (!enabled || !registry) return;
 
-    const msg = event.message as Record<string, unknown> | undefined;
-    if (!msg || msg.role !== "assistant") return;
+    const msg = event.message;
+    if (msg.role !== "assistant") return;
 
     // Clear buffer
     textBuffer = "";
@@ -122,10 +157,12 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
       return;
     }
 
-    // Check context budget before injecting
+    // Skip injection if context usage exceeds the configured threshold
+    // (default: 80%). This prevents doc injection from pushing the context
+    // past the model's limit.
     const usage = _ctx.getContextUsage();
-    if (usage && usage.tokens > 0 && usage.percentage && usage.percentage > 80) {
-      console.warn("[doc-injector] Skipping injection: context usage > 80%");
+    if (usage && usage.tokens && usage.tokens > 0 && usage.percent && usage.percent > config.contextThreshold) {
+      console.warn(`[doc-injector] Skipping injection: context usage > ${config.contextThreshold}%`);
       pendingMatches.clear();
       return;
     }
@@ -133,9 +170,7 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
     const append = buildSystemPromptAppend(matchedEntries, pendingMatches);
 
     // Mark as injected only after confirming injection will happen
-    for (const entry of matchedEntries) {
-      entry.injected = true;
-    }
+    registry.markInjected(matchedEntries.map((e) => e.filePath));
     pendingMatches.clear();
 
     return {
@@ -144,5 +179,10 @@ export default async function docInjectorExtension(pi: ExtensionAPI) {
   });
 
   // ---- Commands ----
-  registerCommands(pi, getRegistry, getEnabled, setEnabled);
+  registerCommands(pi, {
+    getRegistry,
+    getEnabled,
+    setEnabled,
+    reloadRegistry,
+  });
 }

package/injector.ts

@@ -5,6 +5,14 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { DocEntry } from "./types";
 
+/**
+ * Interface for the UI notification capability needed by the injector.
+ * Matches Pi's ExtensionContext['ui'] notify signature.
+ */
+export interface NotifyCapability {
+  notify: (msg: string, type?: "info" | "warning" | "error") => void;
+}
+
 /**
  * Build a system prompt append string from matched documents.
  */
@@ -23,7 +31,7 @@ export function buildSystemPromptAppend(
   for (const entry of entries) {
     const keywords = matchedKeywords.get(entry.filePath) ?? [];
     sections.push(`### ${entry.title}`);
-    sections.push(`Source: \`${entry.fileName}\``);
+    sections.push(`Source: \`${entry.relativePath}\``);
     if (keywords.length > 0) {
       sections.push(`Matched keywords: ${keywords.join(", ")}`);
     }
@@ -39,13 +47,13 @@ export function buildSystemPromptAppend(
  * Notify the user via TUI when documents are injected.
  */
 export function notifyInjection(
-  ui: { notify: (msg: string, type?: "info" | "warning" | "error" | "success") => void },
+  ui: NotifyCapability,
   entries: DocEntry[],
   matchedKeywords: Map<string, string[]>,
 ): void {
   for (const entry of entries) {
     const keywords = matchedKeywords.get(entry.filePath) ?? [];
     const kwList = keywords.join(", ");
-    ui.notify(`📄 Injected: ${entry.fileName} (matched: ${kwList})`, "info");
+    ui.notify(`📄 Injected: ${entry.relativePath} (matched: ${kwList})`, "info");
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-doc-injector",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Auto-inject relevant project documentation into Pi's LLM context based on keyword matching",
   "type": "module",
   "main": "./index.ts",
@@ -16,12 +16,31 @@
     "test": "bun test",
     "test:watch": "bun test --watch"
   },
-  "keywords": ["pi-package", "pi-extension", "docs", "context", "llm"],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "docs",
+    "context",
+    "llm"
+  ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lmn451/pi-docs"
+  },
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./index.ts"
+    ]
   },
   "peerDependencies": {
     "@mariozechner/pi-coding-agent": "*"
-  }
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.13"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "bun@1.3.11"
 }

package/registry.ts

@@ -1,8 +1,8 @@
 /**
  * Document Registry — scans a docs folder, parses frontmatter, maintains index.
  */
-import { readdirSync, readFileSync } from "node:fs";
-import { basename, join, resolve } from "node:path";
+import { type Dirent, readdirSync, readFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
 import type { DocEntry } from "./types";
 
 /**
@@ -65,14 +65,16 @@ export function parseFrontmatter(
 export class DocRegistry {
   private entries: DocEntry[] = [];
   private docsPath: string;
+  private recursive: boolean;
 
-  private constructor(docsPath: string) {
+  private constructor(docsPath: string, recursive: boolean = true) {
     this.docsPath = docsPath;
+    this.recursive = recursive;
   }
 
   /** Create a registry by scanning the docs folder. */
-  static async create(docsPath: string): Promise<DocRegistry> {
-    const registry = new DocRegistry(docsPath);
+  static async create(docsPath: string, recursive: boolean = true): Promise<DocRegistry> {
+    const registry = new DocRegistry(docsPath, recursive);
     await registry.rebuild();
     return registry;
   }
@@ -86,28 +88,30 @@ export class DocRegistry {
     }
 
     try {
-      const files = readdirSync(resolved).filter((f) => f.endsWith(".md"));
+      const scanResults = this.recursive
+        ? this.scanRecursive(resolved)
+        : this.scanFlat(resolved);
 
       const newEntries: DocEntry[] = [];
-      for (const file of files) {
-        const filePath = join(resolved, file);
+      for (const { filePath, relativePath, fileName } of scanResults) {
         try {
           const raw = readFileSync(filePath, "utf-8");
           const parsed = parseFrontmatter(raw);
           if (!parsed) {
-            console.warn(`[doc-injector] Skipping ${file}: no valid frontmatter with keywords`);
+            console.warn(`[doc-injector] Skipping ${relativePath}: no valid frontmatter with keywords`);
             continue;
           }
           newEntries.push({
             filePath,
-            fileName: file,
+            fileName,
+            relativePath,
             title: parsed.title,
             keywords: parsed.keywords,
             content: raw,
             injected: preserved.get(filePath) ?? false,
           });
         } catch (err) {
-          console.warn(`[doc-injector] Error reading ${file}:`, err);
+          console.warn(`[doc-injector] Error reading ${relativePath}:`, err);
         }
       }
 
@@ -118,7 +122,48 @@ export class DocRegistry {
     }
   }
 
-  /** Get all registered entries. */
+  /** Scan top-level .md files only (non-recursive). */
+  private scanFlat(dir: string): Array<{ filePath: string; relativePath: string; fileName: string }> {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => ({
+        filePath: join(dir, f),
+        relativePath: f,
+        fileName: f,
+      }));
+  }
+
+  /** Scan .md files recursively, including subdirectories. */
+  private scanRecursive(dir: string): Array<{ filePath: string; relativePath: string; fileName: string }> {
+    const results: Array<{ filePath: string; relativePath: string; fileName: string }> = [];
+    const dirents = readdirSync(dir, { recursive: true, withFileTypes: true }) as Dirent[];
+
+    for (const dirent of dirents) {
+      if (!dirent.isFile() || !dirent.name.endsWith(".md")) continue;
+
+      // Build relative path from the directory tree
+      const parentPath = (dirent as Dirent & { path?: string }).path ?? "";
+      const relPath = parentPath
+        ? relative(dir, join(parentPath, dirent.name))
+        : dirent.name;
+
+      results.push({
+        filePath: join(dir, relPath),
+        relativePath: relPath,
+        fileName: dirent.name,
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * Get all registered entries.
+   *
+   * NOTE: Returned DocEntry objects share references with the internal registry.
+   * Mutating `injected` on returned objects will affect the registry's internal state.
+   * Prefer using markInjected() / markAllNotInjected() for explicit state changes.
+   */
   getEntries(): DocEntry[] {
     return [...this.entries];
   }
@@ -128,10 +173,25 @@ export class DocRegistry {
     return this.entries.filter((e) => !e.injected);
   }
 
-  /** Reset all injected flags. */
-  reset(): void {
+  /** Mark entries matching the given file paths as injected. */
+  markInjected(filePaths: string[]): void {
+    const pathSet = new Set(filePaths);
+    for (const e of this.entries) {
+      if (pathSet.has(e.filePath)) {
+        e.injected = true;
+      }
+    }
+  }
+
+  /** Reset all entries to not-injected state. */
+  markAllNotInjected(): void {
     for (const e of this.entries) {
       e.injected = false;
     }
   }
+
+  /** @deprecated Use markAllNotInjected() for clarity. */
+  reset(): void {
+    this.markAllNotInjected();
+  }
 }

package/types.ts

@@ -6,6 +6,7 @@
 export interface DocEntry {
   filePath: string;
   fileName: string;
+  relativePath: string;
   title: string;
   keywords: string[];
   content: string;
@@ -30,12 +31,16 @@ export interface MatchResult {
 export interface DocInjectorConfig {
   docsPath: string;
   matchThreshold: number;
+  contextThreshold: number;
+  recursive: boolean;
 }
 
 /** Default configuration values. */
 export const DEFAULT_CONFIG: DocInjectorConfig = {
   docsPath: "./docs",
   matchThreshold: 2,
+  contextThreshold: 80,
+  recursive: true,
 };
 
 /** Default matcher options derived from config. */

package/docs/publish-md.md

@@ -1,55 +0,0 @@
----
-title: "Publishing Workflow"
-keywords: [publish, release, deploy, version, npm, changelog, tag, semantic versioning, production, staging]
----
-
-# Publishing Workflow
-
-## Overview
-
-This document covers the process for publishing releases and deploying to production.
-
-## Versioning
-
-We follow [Semantic Versioning](https://semver.org/):
-- **MAJOR** — incompatible API changes
-- **MINOR** — backwards-compatible functionality additions
-- **PATCH** — backwards-compatible bug fixes
-
-## Release Process
-
-1. Update `CHANGELOG.md` with all changes since last release
-2. Bump version in `package.json`
-3. Create a git tag: `git tag -a v1.2.3 -m "Release v1.2.3"`
-4. Push tags: `git push origin --tags`
-5. CI will automatically build and publish
-
-## Publishing to npm
-
-```bash
-# Dry run first
-npm publish --dry-run
-
-# Actual publish
-npm publish
-```
-
-## Deployment
-
-### Staging
-- Deployed automatically on merge to `main`
-- URL: staging.example.com
-- Used for QA and integration testing
-
-### Production
-- Deployed from release tags only
-- URL: app.example.com
-- Requires manual approval in CI pipeline
-
-## Rollback Procedure
-
-If a release causes issues:
-1. Identify the problematic version
-2. Revert the git tag
-3. Re-deploy the previous version
-4. Post-mortem within 48 hours