pi-doc-injector 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# 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.
+
+## Installation
+
+### Via npm (recommended)
+
+```bash
+pi install npm:pi-doc-injector
+```
+
+### Via git
+
+```bash
+pi install git:github.com/yourname/pi-doc-injector
+```
+
+### Manual
+
+Copy this repository into your project's `.pi/extensions/doc-injector/` folder, or clone directly:
+
+```bash
+git clone https://github.com/yourname/pi-doc-injector.git .pi/extensions/doc-injector
+```
+
+## Quick Start
+
+1. Create a `docs/` folder in your project root.
+2. Add markdown files with YAML frontmatter:
+
+```md
+---
+title: "Testing Workflow"
+keywords: [test, testing, jest, vitest]
+---
+
+# Testing Workflow
+Your documentation here...
+```
+
+Keywords can also be specified in block format:
+
+```md
+---
+title: "Testing Workflow"
+keywords:
+  - test
+  - testing
+  - jest
+  - vitest
+---
+```
+
+3. Start Pi. The extension scans `docs/` on session start.
+4. When the LLM mentions keywords from your docs, the relevant document is injected into the next turn's system prompt.
+
+## Configuration
+
+Create `.pi/doc-injector.json` to customize behavior:
+
+```json
+{
+  "docsPath": "./docs",
+  "matchThreshold": 2
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `docsPath` | `./docs` | Path to your documentation folder |
+| `matchThreshold` | `2` | Minimum keyword matches before injecting |
+
+### Keyword Matching
+
+Matching is case-insensitive and respects word boundaries by default. Once a document is injected, it won't re-match until you run `/doc-inject reset`.
+
+Injection is also skipped if the current context usage exceeds 80% of the token budget.
+
+## 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 |
+
+## Development
+
+```bash
+# Run tests
+bun test
+
+# Run tests in watch mode
+bun test --watch
+```
+
+## License
+
+MIT

package/commands.ts

@@ -0,0 +1,91 @@
+/**
+ * Slash commands for the Doc Injector extension.
+ */
+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) => {
+    pi.registerCommand(name, { description: desc, handler });
+  };
+
+  cmd("doc-inject", "Doc injector: on|off|toggle|list|reset|status", (args, ctx) => {
+    const a = args.trim().toLowerCase();
+    if (a === "on") {
+      setEnabled(true);
+      ctx.ui.notify("📄 Doc injection enabled", "success");
+    } else if (a === "off") {
+      setEnabled(false);
+      ctx.ui.notify("📄 Doc injection disabled", "warning");
+    } else if (a === "toggle") {
+      const next = !getEnabled();
+      setEnabled(next);
+      ctx.ui.notify(`📄 Doc injection ${next ? "enabled" : "disabled"}`, "info");
+    } else if (a === "reset") {
+      const reg = getRegistry();
+      if (reg) {
+        reg.reset();
+        ctx.ui.notify("📄 Injection state reset", "success");
+      } else {
+        ctx.ui.notify("📄 No registry loaded", "warning");
+      }
+    } else if (a === "list") {
+      const reg = getRegistry();
+      if (!reg) {
+        ctx.ui.notify("📄 No docs loaded", "warning");
+        return;
+      }
+      const entries = reg.getEntries();
+      if (entries.length === 0) {
+        ctx.ui.notify("📄 No documents found in docs folder", "info");
+        return;
+      }
+      const lines = entries.map((e) => {
+        const status = e.injected ? "✅" : "⬜";
+        return `${status} ${e.fileName}: "${e.title}" — keywords: [${e.keywords.join(", ")}]`;
+      });
+      ctx.ui.notify(`📄 Registered docs:\n${lines.join("\n")}`, "info");
+    } else {
+      // status (default)
+      const reg = getRegistry();
+      if (!reg) {
+        ctx.ui.notify("📄 Status: No registry loaded", "warning");
+        return;
+      }
+      const entries = reg.getEntries();
+      const injected = entries.filter((e) => e.injected).length;
+      const kwCount = entries.reduce((sum, e) => sum + e.keywords.length, 0);
+      ctx.ui.notify(
+        `📄 Doc Injector Status:\n` +
+        `  Enabled: ${getEnabled() ? "✅" : "❌"}\n` +
+        `  Docs: ${entries.length}\n` +
+        `  Keywords: ${kwCount}\n` +
+        `  Injected: ${injected}`,
+        "info",
+      );
+    }
+  });
+
+  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) => {
+      ctx.ui.notify(`📄 Reload failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+    });
+  });
+}

package/config.ts

@@ -0,0 +1,35 @@
+/**
+ * Configuration loader for the Doc Injector extension.
+ * Reads from `.pi/doc-injector.json` with fallback to defaults.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_CONFIG, type DocInjectorConfig } from "./types";
+
+/**
+ * Load config from `.pi/doc-injector.json` relative to the given cwd.
+ * Falls back to DEFAULT_CONFIG if file doesn't exist or is invalid.
+ */
+export function loadConfig(cwd: string): DocInjectorConfig {
+  const configPath = join(cwd, ".pi", "doc-injector.json");
+
+  if (!existsSync(configPath)) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<DocInjectorConfig>;
+
+    return {
+      docsPath: parsed.docsPath ?? DEFAULT_CONFIG.docsPath,
+      matchThreshold: parsed.matchThreshold ?? DEFAULT_CONFIG.matchThreshold,
+    };
+  } catch (err) {
+    console.warn(
+      `[doc-injector] Failed to parse config at ${configPath}:`,
+      err instanceof Error ? err.message : String(err),
+    );
+    return { ...DEFAULT_CONFIG };
+  }
+}

package/docs/publish-md.md

@@ -0,0 +1,55 @@
+---
+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

package/docs/test-md.md

@@ -0,0 +1,58 @@
+---
+title: "Testing Workflow"
+keywords: [test, testing, unit test, integration test, tdd, jest, vitest, assert, mock, stub]
+---
+
+# Testing Workflow
+
+## Overview
+
+This document covers the testing workflow for this project. All new features must include tests.
+
+## Testing Principles
+
+1. **Test-driven development** — write tests before implementation when possible
+2. **Unit tests** for pure functions and isolated logic
+3. **Integration tests** for interactions between modules
+4. **E2E tests** for critical user flows
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## Writing Tests
+
+- Place test files next to source files with `.test.ts` extension
+- Use descriptive test names that explain the expected behavior
+- One assertion per test when possible
+- Use `describe` blocks to group related tests
+
+## Test Categories
+
+### Unit Tests
+- Test individual functions in isolation
+- Mock external dependencies
+- Fast execution (< 100ms per test)
+
+### Integration Tests
+- Test module interactions
+- May use real dependencies
+- Slower than unit tests
+
+### End-to-End Tests
+- Test complete user workflows
+- Run against a staging environment
+- Slowest but most valuable
+
+## Code Coverage Target
+
+Maintain at least 80% code coverage for all new code.

package/docs/workflow-md.md

@@ -0,0 +1,53 @@
+---
+title: "Development Workflow"
+keywords: [workflow, development, coding, git, branch, commit, pull request, review, ci, cd, pipeline]
+---
+
+# Development Workflow
+
+## Overview
+
+This document describes the standard development workflow for this project.
+
+## Git Workflow
+
+1. Create a feature branch from `main`
+2. Make atomic commits with conventional commit messages
+3. Push and create a pull request
+4. Request review from at least one team member
+5. Merge after approval
+
+## Branch Naming
+
+- `feat/short-description` — new features
+- `fix/short-description` — bug fixes
+- `refactor/short-description` — code refactoring
+- `docs/short-description` — documentation changes
+- `test/short-description` — test additions
+
+## Commit Messages
+
+Follow Conventional Commits:
+```
+type(scope): description
+
+feat(auth): add OAuth2 login support
+fix(api): handle null response gracefully
+docs(readme): update installation steps
+```
+
+## Code Review Guidelines
+
+- Review within 24 hours of PR creation
+- Focus on correctness, readability, and test coverage
+- Approve only when all CI checks pass
+- Leave constructive feedback with specific suggestions
+
+## CI/CD Pipeline
+
+The pipeline runs on every push:
+1. Lint check
+2. Type check
+3. Unit tests
+4. Integration tests
+5. Build

package/index.ts

@@ -0,0 +1,148 @@
+/**
+ * Doc Injector Extension for Pi
+ *
+ * Automatically injects relevant project documentation into the LLM context
+ * by monitoring streaming output for keyword matches.
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { resolve } from "node:path";
+import { loadConfig } from "./config";
+import { buildSystemPromptAppend, notifyInjection } from "./injector";
+import { extractText, KeywordMatcher } from "./matcher";
+import { DocRegistry } from "./registry";
+import { DEFAULT_MATCHER_OPTIONS, type DocEntry, type MatchResult } from "./types";
+import { registerCommands } from "./commands";
+
+export default async function docInjectorExtension(pi: ExtensionAPI) {
+  // ---- State ----
+  let config = loadConfig(process.cwd());
+  let registry: DocRegistry | null = null;
+  let enabled = true;
+  let textBuffer = "";
+  let pendingMatches = new Map<string, string[]>(); // filePath → matchedKeywords
+
+  // ---- Helpers ----
+  const getRegistry = () => registry;
+  const getEnabled = () => enabled;
+  const setEnabled = (v: boolean) => {
+    enabled = v;
+  };
+
+  const initRegistry = async (cwd: string) => {
+    config = loadConfig(cwd);
+    const docsPath = resolve(cwd, config.docsPath);
+    registry = await DocRegistry.create(docsPath);
+    const count = registry.getEntries().length;
+    if (count > 0) {
+      console.log(`[doc-injector] Loaded ${count} documents from ${docsPath}`);
+    } else {
+      console.warn(`[doc-injector] No documents found at ${docsPath}`);
+    }
+  };
+
+  const buildMatcher = (): KeywordMatcher | null => {
+    if (!registry) return null;
+    return new KeywordMatcher(
+      registry.getNonInjectedEntries(),
+      { matchThreshold: config.matchThreshold },
+    );
+  };
+
+  // ---- Event: session_start ----
+  pi.on("session_start", async (_event, ctx) => {
+    await initRegistry(ctx.cwd);
+  });
+
+  // ---- 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`);
+    }
+  });
+
+  // ---- Event: message_update (streaming detection) ----
+  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;
+
+    // Replace buffer with full message text (message_update contains full content)
+    textBuffer = extractText(msg.content);
+    if (!textBuffer) return;
+
+    // Run matcher
+    const matcher = buildMatcher();
+    if (!matcher) return;
+
+    const results = matcher.match(textBuffer);
+
+    // Store matches (dedup by filePath)
+    for (const result of results) {
+      pendingMatches.set(result.entry.filePath, result.matchedKeywords);
+    }
+  });
+
+  // ---- Event: message_end (finalize matches) ----
+  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;
+
+    // Clear buffer
+    textBuffer = "";
+
+    // Notify user about pending injections
+    if (pendingMatches.size > 0) {
+      const matchedEntries: DocEntry[] = [];
+      for (const [filePath] of pendingMatches) {
+        const entry = registry.getEntries().find((e) => e.filePath === filePath);
+        if (entry) matchedEntries.push(entry);
+      }
+      notifyInjection(ctx.ui, matchedEntries, pendingMatches);
+    }
+  });
+
+  // ---- Event: before_agent_start (inject into system prompt) ----
+  pi.on("before_agent_start", async (_event, _ctx) => {
+    if (!enabled || !registry || pendingMatches.size === 0) return;
+
+    const matchedEntries: DocEntry[] = [];
+    for (const [filePath] of pendingMatches) {
+      const entry = registry.getEntries().find((e) => e.filePath === filePath);
+      if (entry) matchedEntries.push(entry);
+    }
+
+    if (matchedEntries.length === 0) {
+      pendingMatches.clear();
+      return;
+    }
+
+    // Check context budget before injecting
+    const usage = _ctx.getContextUsage();
+    if (usage && usage.tokens > 0 && usage.percentage && usage.percentage > 80) {
+      console.warn("[doc-injector] Skipping injection: context usage > 80%");
+      pendingMatches.clear();
+      return;
+    }
+
+    const append = buildSystemPromptAppend(matchedEntries, pendingMatches);
+
+    // Mark as injected only after confirming injection will happen
+    for (const entry of matchedEntries) {
+      entry.injected = true;
+    }
+    pendingMatches.clear();
+
+    return {
+      systemPrompt: (_event.systemPrompt || "") + "\n\n" + append,
+    };
+  });
+
+  // ---- Commands ----
+  registerCommands(pi, getRegistry, getEnabled, setEnabled);
+}

package/injector.ts

@@ -0,0 +1,51 @@
+/**
+ * Context Injector — formats matched docs into system prompt append
+ * and sends TUI notifications.
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { DocEntry } from "./types";
+
+/**
+ * Build a system prompt append string from matched documents.
+ */
+export function buildSystemPromptAppend(
+  entries: DocEntry[],
+  matchedKeywords: Map<string, string[]>,
+): string {
+  if (entries.length === 0) return "";
+
+  const sections: string[] = [
+    "## Relevant Context Documents\n",
+    "The following documents from the project docs folder are relevant to the current conversation context. Use them as reference when responding.",
+    "",
+  ];
+
+  for (const entry of entries) {
+    const keywords = matchedKeywords.get(entry.filePath) ?? [];
+    sections.push(`### ${entry.title}`);
+    sections.push(`Source: \`${entry.fileName}\``);
+    if (keywords.length > 0) {
+      sections.push(`Matched keywords: ${keywords.join(", ")}`);
+    }
+    sections.push("---");
+    sections.push(entry.content);
+    sections.push("");
+  }
+
+  return sections.join("\n");
+}
+
+/**
+ * Notify the user via TUI when documents are injected.
+ */
+export function notifyInjection(
+  ui: { notify: (msg: string, type?: "info" | "warning" | "error" | "success") => void },
+  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");
+  }
+}

package/matcher.ts

@@ -0,0 +1,80 @@
+/**
+ * Keyword Matcher — matches streaming output text against document keywords.
+ */
+import type { DocEntry, MatchResult, MatcherOptions } from "./types";
+import { DEFAULT_MATCHER_OPTIONS } from "./types";
+
+/**
+ * Extract text from message content. Handles:
+ * - Plain string
+ * - Content array with text/thinking blocks
+ */
+export function extractText(content: unknown): string {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    return "";
+  }
+
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    const b = block as Record<string, unknown>;
+    if ((b.type === "text" || b.type === "thinking") && typeof b.text === "string") {
+      parts.push(b.text);
+    }
+  }
+  return parts.join("\n");
+}
+
+export class KeywordMatcher {
+  private options: MatcherOptions;
+
+  constructor(private entries: DocEntry[], options?: Partial<MatcherOptions>) {
+    this.options = { ...DEFAULT_MATCHER_OPTIONS, ...options };
+  }
+
+  /** Match text against keyword index. Returns matching docs with hit details. */
+  match(text: string): MatchResult[] {
+    if (!text || this.entries.length === 0) return [];
+
+    const results: MatchResult[] = [];
+
+    for (const entry of this.entries) {
+      if (entry.injected) continue;
+
+      const matchedKeywords: string[] = [];
+      for (const keyword of entry.keywords) {
+        if (this.keywordMatches(text, keyword)) {
+          matchedKeywords.push(keyword);
+        }
+      }
+
+      if (matchedKeywords.length >= this.options.matchThreshold) {
+        results.push({
+          entry,
+          matchedKeywords,
+          hitCount: matchedKeywords.length,
+        });
+      }
+    }
+
+    return results;
+  }
+
+  private keywordMatches(text: string, keyword: string): boolean {
+    const search = this.options.caseSensitive ? text : text.toLowerCase();
+    const kw = this.options.caseSensitive ? keyword : keyword.toLowerCase();
+
+    if (this.options.wordBoundary) {
+      // Escape special regex chars in keyword, then apply word boundary
+      const escaped = kw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const flags = this.options.caseSensitive ? "" : "i";
+      const regex = new RegExp(`\\b${escaped}\\b`, flags);
+      return regex.test(search);
+    }
+
+    return search.includes(kw);
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "pi-doc-injector",
+  "version": "0.1.0",
+  "description": "Auto-inject relevant project documentation into Pi's LLM context based on keyword matching",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "*.ts",
+    "docs/**/*.md",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch"
+  },
+  "keywords": ["pi-package", "pi-extension", "docs", "context", "llm"],
+  "license": "MIT",
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  }
+}

package/registry.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 { DocEntry } from "./types";
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Returns { title, keywords, body } or null if no valid frontmatter found.
+ */
+export function parseFrontmatter(
+  content: string,
+): { title: string; keywords: string[]; body: string } | null {
+  if (!content.startsWith("---")) {
+    return null;
+  }
+
+  const secondDash = content.indexOf("---", 3);
+  if (secondDash === -1) {
+    return null;
+  }
+
+  const frontmatterBlock = content.slice(3, secondDash).trim();
+  const body = content.slice(secondDash + 3).trim();
+
+  // Extract title
+  const titleMatch = frontmatterBlock.match(/^title:\s*["']?([^"'\n]+)["']?$/m);
+  const title = titleMatch ? titleMatch[1].trim() : "";
+
+  // Extract keywords — supports both flow array [a, b] and block array
+  const keywords: string[] = [];
+
+  // Try flow array: keywords: [a, b, c]
+  const flowMatch = frontmatterBlock.match(/keywords:\s*\[([^\]]*)\]/);
+  if (flowMatch) {
+    keywords.push(
+      ...flowMatch[1]
+        .split(",")
+        .map((k) => k.trim().replace(/^["']|["']$/g, ""))
+        .filter(Boolean),
+    );
+  } else {
+    // Try block array: keywords:\n  - a\n  - b
+    const blockMatches = frontmatterBlock.matchAll(/keywords:\s*\n((?:\s*-\s*.+\n?)+)/g);
+    for (const bm of blockMatches) {
+      const items = bm[1].matchAll(/^\s*-\s*["']?([^"'\n]+)["']?$/gm);
+      for (const im of items) {
+        const k = im[1].trim();
+        if (k) keywords.push(k);
+      }
+    }
+  }
+
+  if (keywords.length === 0) {
+    return null;
+  }
+
+  return { title: title || "Untitled", keywords, body };
+}
+
+/**
+ * Document Registry class. Scans a docs folder and maintains an index of DocEntry.
+ */
+export class DocRegistry {
+  private entries: DocEntry[] = [];
+  private docsPath: string;
+
+  private constructor(docsPath: string) {
+    this.docsPath = docsPath;
+  }
+
+  /** Create a registry by scanning the docs folder. */
+  static async create(docsPath: string): Promise<DocRegistry> {
+    const registry = new DocRegistry(docsPath);
+    await registry.rebuild();
+    return registry;
+  }
+
+  /** Re-scan the docs folder and rebuild the index. */
+  async rebuild(): Promise<void> {
+    const resolved = resolve(this.docsPath);
+    const preserved = new Map<string, boolean>();
+    for (const e of this.entries) {
+      preserved.set(e.filePath, e.injected);
+    }
+
+    try {
+      const files = readdirSync(resolved).filter((f) => f.endsWith(".md"));
+
+      const newEntries: DocEntry[] = [];
+      for (const file of files) {
+        const filePath = join(resolved, file);
+        try {
+          const raw = readFileSync(filePath, "utf-8");
+          const parsed = parseFrontmatter(raw);
+          if (!parsed) {
+            console.warn(`[doc-injector] Skipping ${file}: no valid frontmatter with keywords`);
+            continue;
+          }
+          newEntries.push({
+            filePath,
+            fileName: file,
+            title: parsed.title,
+            keywords: parsed.keywords,
+            content: raw,
+            injected: preserved.get(filePath) ?? false,
+          });
+        } catch (err) {
+          console.warn(`[doc-injector] Error reading ${file}:`, err);
+        }
+      }
+
+      this.entries = newEntries;
+    } catch {
+      console.warn(`[doc-injector] Docs folder not found: ${resolved}`);
+      this.entries = [];
+    }
+  }
+
+  /** Get all registered entries. */
+  getEntries(): DocEntry[] {
+    return [...this.entries];
+  }
+
+  /** Get entries that haven't been injected yet. */
+  getNonInjectedEntries(): DocEntry[] {
+    return this.entries.filter((e) => !e.injected);
+  }
+
+  /** Reset all injected flags. */
+  reset(): void {
+    for (const e of this.entries) {
+      e.injected = false;
+    }
+  }
+}

package/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared type definitions for the Doc Injector extension.
+ */
+
+/** A parsed document from the docs folder. */
+export interface DocEntry {
+  filePath: string;
+  fileName: string;
+  title: string;
+  keywords: string[];
+  content: string;
+  injected: boolean;
+}
+
+/** Options for the keyword matcher. */
+export interface MatcherOptions {
+  matchThreshold: number;
+  caseSensitive: boolean;
+  wordBoundary: boolean;
+}
+
+/** Result from a keyword match. */
+export interface MatchResult {
+  entry: DocEntry;
+  matchedKeywords: string[];
+  hitCount: number;
+}
+
+/** Extension configuration. */
+export interface DocInjectorConfig {
+  docsPath: string;
+  matchThreshold: number;
+}
+
+/** Default configuration values. */
+export const DEFAULT_CONFIG: DocInjectorConfig = {
+  docsPath: "./docs",
+  matchThreshold: 2,
+};
+
+/** Default matcher options derived from config. */
+export const DEFAULT_MATCHER_OPTIONS: MatcherOptions = {
+  matchThreshold: DEFAULT_CONFIG.matchThreshold,
+  caseSensitive: false,
+  wordBoundary: true,
+};