@karmaniverous/jeeves-watcher 0.3.0 → 0.4.0

package/dist/mjs/index.js

@@ -2,14 +2,22 @@ import Fastify from 'fastify';
 import { readdir, stat, rm, readFile, mkdir, writeFile } from 'node:fs/promises';
 import { resolve, dirname, join, relative, extname, basename } from 'node:path';
 import picomatch from 'picomatch';
-import { omit, get } from 'radash';
+import { omit, capitalize, title, camel, snake, dash, isEqual, get } from 'radash';
 import { createHash } from 'node:crypto';
+import { existsSync, statSync, readdirSync, readFileSync } from 'node:fs';
+import ignore from 'ignore';
+import Handlebars from 'handlebars';
+import dayjs from 'dayjs';
+import { toMdast } from 'hast-util-to-mdast';
+import { fromADF } from 'mdast-util-from-adf';
+import { toMarkdown } from 'mdast-util-to-markdown';
+import rehypeParse from 'rehype-parse';
+import { unified } from 'unified';
+import chokidar from 'chokidar';
 import { cosmiconfig } from 'cosmiconfig';
 import { z, ZodError } from 'zod';
 import { jsonMapMapSchema, JsonMap } from '@karmaniverous/jsonmap';
 import { GoogleGenerativeAIEmbeddings } from '@langchain/google-genai';
-import { existsSync, statSync, readdirSync, readFileSync } from 'node:fs';
-import ignore from 'ignore';
 import pino from 'pino';
 import { v5 } from 'uuid';
 import * as cheerio from 'cheerio';
@@ -19,7 +27,6 @@ import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { MarkdownTextSplitter, RecursiveCharacterTextSplitter } from '@langchain/textsplitters';
 import { QdrantClient } from '@qdrant/js-client-rest';
-import chokidar from 'chokidar';
 
 /**
  * @module util/normalizeError
@@ -418,183 +425,663 @@ function createApiServer(options) {
 }
 
 /**
- * @module config/defaults
- * Default configuration values for jeeves-watcher. Pure data export, no I/O or side effects.
+ * @module gitignore
+ * Processor-level gitignore filtering. Scans watched paths for `.gitignore` files in git repos, caches parsed patterns, and exposes `isIgnored()` for path checking.
  */
-/** Default root-level config values. */
-const ROOT_DEFAULTS = {
-    metadataDir: '.jeeves-watcher',
-    shutdownTimeoutMs: 10000,
-};
-/** Default configWatch values. */
-const CONFIG_WATCH_DEFAULTS = {
-    enabled: true,
-    debounceMs: 1000,
-};
-/** Default API values. */
-const API_DEFAULTS = {
-    host: '127.0.0.1',
-    port: 3456,
-};
-/** Default logging values. */
-const LOGGING_DEFAULTS = {
-    level: 'info',
-};
-/** Default watch configuration. */
-const WATCH_DEFAULTS = {
-    debounceMs: 300,
-    stabilityThresholdMs: 500,
-    usePolling: false,
-    pollIntervalMs: 1000,
-    respectGitignore: true,
-};
-/** Default embedding configuration. */
-const EMBEDDING_DEFAULTS = {
-    chunkSize: 1000,
-    chunkOverlap: 200,
-    dimensions: 3072,
-    rateLimitPerMinute: 300,
-    concurrency: 5,
-};
-
 /**
- * Watch configuration for file system monitoring.
+ * Find the git repo root by walking up from `startDir` looking for `.git/`.
+ * Returns `undefined` if no repo is found.
  */
-const watchConfigSchema = z.object({
-    /** Glob patterns to watch. */
-    paths: z
-        .array(z.string())
-        .min(1)
-        .describe('Glob patterns for files to watch (e.g., "**/*.md"). At least one required.'),
-    /** Glob patterns to ignore. */
-    ignored: z
-        .array(z.string())
-        .optional()
-        .describe('Glob patterns to exclude from watching (e.g., "**/node_modules/**").'),
-    /** Polling interval in milliseconds. */
-    pollIntervalMs: z
-        .number()
-        .optional()
-        .describe('Polling interval in milliseconds when usePolling is enabled.'),
-    /** Whether to use polling instead of native watchers. */
-    usePolling: z
-        .boolean()
-        .optional()
-        .describe('Use polling instead of native file system events (for network drives).'),
-    /** Debounce delay in milliseconds for file change events. */
-    debounceMs: z
-        .number()
-        .optional()
-        .describe('Debounce delay in milliseconds for file change events.'),
-    /** Time in milliseconds a file must be stable before processing. */
-    stabilityThresholdMs: z
-        .number()
-        .optional()
-        .describe('Time in milliseconds a file must remain unchanged before processing.'),
-    /** Whether to respect .gitignore files when processing. */
-    respectGitignore: z
-        .boolean()
-        .optional()
-        .describe('Skip files ignored by .gitignore in git repositories. Only applies to repos with a .git directory. Default: true.'),
-});
+function findRepoRoot(startDir) {
+    let dir = resolve(startDir);
+    const root = resolve('/');
+    while (dir !== root) {
+        if (existsSync(join(dir, '.git')) &&
+            statSync(join(dir, '.git')).isDirectory()) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
 /**
- * Configuration watch settings.
+ * Convert a watch path (directory, file path, or glob) to a concrete directory
+ * that can be scanned for a repo root.
  */
-const configWatchConfigSchema = z.object({
-    /** Whether config file watching is enabled. */
-    enabled: z
-        .boolean()
-        .optional()
-        .describe('Enable automatic reloading when config file changes.'),
-    /** Debounce delay in milliseconds for config change events. */
-    debounceMs: z
-        .number()
-        .optional()
-        .describe('Debounce delay in milliseconds for config file change detection.'),
-});
+function watchPathToScanDir(watchPath) {
+    const absPath = resolve(watchPath);
+    try {
+        return statSync(absPath).isDirectory() ? absPath : dirname(absPath);
+    }
+    catch {
+        // ignore
+    }
+    // If this is a glob, fall back to the non-glob prefix.
+    const globMatch = /[*?[{]/.exec(watchPath);
+    if (!globMatch)
+        return undefined;
+    const prefix = watchPath.slice(0, globMatch.index);
+    const trimmed = prefix.trim();
+    const baseDir = trimmed.length === 0
+        ? '.'
+        : trimmed.endsWith('/') || trimmed.endsWith('\\')
+            ? trimmed
+            : dirname(trimmed);
+    const resolved = resolve(baseDir);
+    if (!existsSync(resolved))
+        return undefined;
+    return resolved;
+}
 /**
- * Embedding model configuration.
+ * Recursively find all `.gitignore` files under `dir`.
+ * Skips `.git` and `node_modules` directories for performance.
  */
-const embeddingConfigSchema = z.object({
-    /** The embedding model provider. */
-    provider: z
-        .string()
-        .default('gemini')
-        .describe('Embedding provider name (e.g., "gemini", "openai").'),
-    /** The embedding model name. */
-    model: z
-        .string()
-        .default('gemini-embedding-001')
-        .describe('Embedding model identifier (e.g., "gemini-embedding-001", "text-embedding-3-small").'),
-    /** Maximum tokens per chunk for splitting. */
-    chunkSize: z
-        .number()
-        .optional()
-        .describe('Maximum chunk size in characters for text splitting.'),
-    /** Overlap between chunks in tokens. */
-    chunkOverlap: z
-        .number()
-        .optional()
-        .describe('Character overlap between consecutive chunks.'),
-    /** Embedding vector dimensions. */
-    dimensions: z
-        .number()
-        .optional()
-        .describe('Embedding vector dimensions (must match model output).'),
-    /** API key for the embedding provider. */
-    apiKey: z
-        .string()
-        .optional()
-        .describe('API key for embedding provider (supports ${ENV_VAR} substitution).'),
-    /** Maximum embedding requests per minute. */
-    rateLimitPerMinute: z
-        .number()
-        .optional()
-        .describe('Maximum embedding API requests per minute (rate limiting).'),
-    /** Maximum concurrent embedding requests. */
-    concurrency: z
-        .number()
-        .optional()
-        .describe('Maximum concurrent embedding requests.'),
-});
+function findGitignoreFiles(dir) {
+    const results = [];
+    const gitignorePath = join(dir, '.gitignore');
+    if (existsSync(gitignorePath)) {
+        results.push(gitignorePath);
+    }
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        if (entry === '.git' || entry === 'node_modules')
+            continue;
+        const fullPath = join(dir, entry);
+        try {
+            if (statSync(fullPath).isDirectory()) {
+                results.push(...findGitignoreFiles(fullPath));
+            }
+        }
+        catch {
+            // Skip inaccessible entries
+        }
+    }
+    return results;
+}
 /**
- * Vector store configuration for Qdrant.
+ * Parse a `.gitignore` file into an `ignore` instance.
  */
-const vectorStoreConfigSchema = z.object({
-    /** Qdrant server URL. */
-    url: z
-        .string()
-        .describe('Qdrant server URL (e.g., "http://localhost:6333").'),
-    /** Qdrant collection name. */
-    collectionName: z
-        .string()
-        .describe('Qdrant collection name for vector storage.'),
-    /** Qdrant API key. */
-    apiKey: z
-        .string()
-        .optional()
-        .describe('Qdrant API key for authentication (supports ${ENV_VAR} substitution).'),
-});
+function parseGitignore(gitignorePath) {
+    const content = readFileSync(gitignorePath, 'utf8');
+    return ignore().add(content);
+}
 /**
- * API server configuration.
+ * Normalize a path to use forward slashes (required by `ignore` package).
  */
-const apiConfigSchema = z.object({
-    /** Host to bind to. */
-    host: z
-        .string()
-        .optional()
-        .describe('Host address for API server (e.g., "127.0.0.1", "0.0.0.0").'),
-    /** Port to listen on. */
-    port: z.number().optional().describe('Port for API server (e.g., 3456).'),
-});
+function toForwardSlash(p) {
+    return p.replace(/\\/g, '/');
+}
 /**
- * Logging configuration.
+ * Processor-level gitignore filter. Checks file paths against the nearest
+ * `.gitignore` chain in git repositories.
  */
-const loggingConfigSchema = z.object({
-    /** Log level. */
-    level: z
-        .string()
-        .optional()
+class GitignoreFilter {
+    repos = new Map();
+    /**
+     * Create a GitignoreFilter by scanning watched paths for `.gitignore` files.
+     *
+     * @param watchPaths - Absolute paths being watched (directories or globs resolved to roots).
+     */
+    constructor(watchPaths) {
+        this.scan(watchPaths);
+    }
+    /**
+     * Scan paths for git repos and their `.gitignore` files.
+     */
+    scan(watchPaths) {
+        this.repos.clear();
+        const scannedDirs = new Set();
+        for (const watchPath of watchPaths) {
+            const scanDir = watchPathToScanDir(watchPath);
+            if (!scanDir)
+                continue;
+            if (scannedDirs.has(scanDir))
+                continue;
+            scannedDirs.add(scanDir);
+            const repoRoot = findRepoRoot(scanDir);
+            if (!repoRoot)
+                continue;
+            if (this.repos.has(repoRoot))
+                continue;
+            const gitignoreFiles = findGitignoreFiles(repoRoot);
+            const entries = gitignoreFiles.map((gf) => ({
+                dir: dirname(gf),
+                ig: parseGitignore(gf),
+            }));
+            // Sort deepest-first so nested `.gitignore` files are checked first
+            entries.sort((a, b) => b.dir.length - a.dir.length);
+            this.repos.set(repoRoot, { root: repoRoot, entries });
+        }
+    }
+    /**
+     * Check whether a file path is ignored by any applicable `.gitignore`.
+     *
+     * @param filePath - Absolute file path to check.
+     * @returns `true` if the file should be ignored.
+     */
+    isIgnored(filePath) {
+        const absPath = resolve(filePath);
+        for (const [, repo] of this.repos) {
+            // Check if file is within this repo
+            const relToRepo = relative(repo.root, absPath);
+            // On Windows, path.relative() across drives (e.g. D:\ → J:\) produces
+            // an absolute path with a drive letter instead of a relative one. The
+            // `ignore` library rejects these with a RangeError. Skip repos on
+            // different drives to avoid cross-drive gitignore mismatches.
+            if (relToRepo.startsWith('..') ||
+                relToRepo.startsWith(resolve('/')) ||
+                /^[a-zA-Z]:/.test(relToRepo)) {
+                continue;
+            }
+            // Check each `.gitignore` entry (deepest-first)
+            for (const entry of repo.entries) {
+                const relToEntry = relative(entry.dir, absPath);
+                if (relToEntry.startsWith('..') || /^[a-zA-Z]:/.test(relToEntry))
+                    continue;
+                const normalized = toForwardSlash(relToEntry);
+                if (entry.ig.ignores(normalized)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Invalidate and re-parse a specific `.gitignore` file.
+     * Call when a `.gitignore` file is added, changed, or removed.
+     *
+     * @param gitignorePath - Absolute path to the `.gitignore` file that changed.
+     */
+    invalidate(gitignorePath) {
+        const absPath = resolve(gitignorePath);
+        const gitignoreDir = dirname(absPath);
+        for (const [, repo] of this.repos) {
+            const relToRepo = relative(repo.root, gitignoreDir);
+            if (relToRepo.startsWith('..'))
+                continue;
+            // Remove old entry for this directory
+            repo.entries = repo.entries.filter((e) => e.dir !== gitignoreDir);
+            // Re-parse if file still exists
+            if (existsSync(absPath)) {
+                repo.entries.push({ dir: gitignoreDir, ig: parseGitignore(absPath) });
+                // Re-sort deepest-first
+                repo.entries.sort((a, b) => b.dir.length - a.dir.length);
+            }
+            return;
+        }
+        // If not in any known repo, check if it's in a repo we haven't scanned
+        const repoRoot = findRepoRoot(gitignoreDir);
+        if (repoRoot && existsSync(absPath)) {
+            const entries = [
+                { dir: gitignoreDir, ig: parseGitignore(absPath) },
+            ];
+            if (this.repos.has(repoRoot)) {
+                const repo = this.repos.get(repoRoot);
+                repo.entries.push(entries[0]);
+                repo.entries.sort((a, b) => b.dir.length - a.dir.length);
+            }
+            else {
+                this.repos.set(repoRoot, { root: repoRoot, entries });
+            }
+        }
+    }
+}
+
+/**
+ * @module templates/helpers
+ * Registers built-in Handlebars helpers for content templates.
+ */
+/** Pre-built rehype parser for HTML → hast conversion. */
+const htmlParser = unified().use(rehypeParse, { fragment: true });
+/**
+ * Register all built-in helpers on a Handlebars instance.
+ *
+ * @param hbs - The Handlebars instance.
+ */
+function registerBuiltinHelpers(hbs) {
+    // Structural: ADF → Markdown
+    hbs.registerHelper('adfToMarkdown', function (adf) {
+        if (!adf || typeof adf !== 'object')
+            return '';
+        try {
+            const mdast = fromADF(adf);
+            return new hbs.SafeString(toMarkdown(mdast).trim());
+        }
+        catch {
+            return '<!-- ADF conversion failed -->';
+        }
+    });
+    // Structural: HTML → Markdown
+    hbs.registerHelper('markdownify', function (html) {
+        if (typeof html !== 'string' || !html.trim())
+            return '';
+        try {
+            const hast = htmlParser.parse(html);
+            const mdast = toMdast(hast);
+            return new hbs.SafeString(toMarkdown(mdast).trim());
+        }
+        catch {
+            return '<!-- HTML conversion failed -->';
+        }
+    });
+    // Formatting: dateFormat
+    hbs.registerHelper('dateFormat', function (value, format) {
+        if (value === undefined || value === null)
+            return '';
+        const fmt = typeof format === 'string' ? format : 'YYYY-MM-DD';
+        return dayjs(value).format(fmt);
+    });
+    // Formatting: join
+    hbs.registerHelper('join', function (arr, separator) {
+        if (!Array.isArray(arr))
+            return '';
+        const sep = typeof separator === 'string' ? separator : ', ';
+        return arr.join(sep);
+    });
+    // Formatting: pluck
+    hbs.registerHelper('pluck', function (arr, key) {
+        if (!Array.isArray(arr) || typeof key !== 'string')
+            return [];
+        return arr.map((item) => item && typeof item === 'object'
+            ? item[key]
+            : undefined);
+    });
+    // String transforms
+    hbs.registerHelper('lowercase', (text) => typeof text === 'string' ? text.toLowerCase() : '');
+    hbs.registerHelper('uppercase', (text) => typeof text === 'string' ? text.toUpperCase() : '');
+    hbs.registerHelper('capitalize', (text) => typeof text === 'string' ? capitalize(text) : '');
+    hbs.registerHelper('title', (text) => typeof text === 'string' ? title(text) : '');
+    hbs.registerHelper('camel', (text) => typeof text === 'string' ? camel(text) : '');
+    hbs.registerHelper('snake', (text) => typeof text === 'string' ? snake(text) : '');
+    hbs.registerHelper('dash', (text) => typeof text === 'string' ? dash(text) : '');
+    // default helper
+    hbs.registerHelper('default', function (value, fallback) {
+        return value ?? fallback ?? '';
+    });
+    // eq helper (deep equality)
+    hbs.registerHelper('eq', function (a, b) {
+        return isEqual(a, b);
+    });
+    // json helper
+    hbs.registerHelper('json', function (value) {
+        return new hbs.SafeString(JSON.stringify(value, null, 2));
+    });
+}
+
+/**
+ * @module templates/engine
+ * Handlebars template compilation, caching, and resolution (file path vs named ref vs inline).
+ */
+/**
+ * Resolve a template value to its source string.
+ *
+ * Resolution order:
+ * 1. Ends in `.hbs` or `.handlebars` → file path (resolve relative to configDir)
+ * 2. Matches a key in namedTemplates → named ref (recursively resolve)
+ * 3. Otherwise → inline Handlebars template string
+ *
+ * @param value - The template reference (inline, file path, or named ref).
+ * @param namedTemplates - Named template definitions from config.
+ * @param configDir - Directory to resolve relative file paths against.
+ * @param visited - Set of visited named refs for cycle detection.
+ * @returns The resolved template source string.
+ */
+function resolveTemplateSource(value, namedTemplates, configDir, visited = new Set()) {
+    // File path detection
+    if (value.endsWith('.hbs') || value.endsWith('.handlebars')) {
+        return readFileSync(resolve(configDir, value), 'utf-8');
+    }
+    // Named ref
+    if (namedTemplates?.[value] !== undefined) {
+        if (visited.has(value)) {
+            throw new Error(`Circular template reference detected: ${value}`);
+        }
+        visited.add(value);
+        return resolveTemplateSource(namedTemplates[value], namedTemplates, configDir, visited);
+    }
+    // Inline
+    return value;
+}
+/**
+ * Create a configured Handlebars instance with built-in helpers registered.
+ *
+ * @returns A Handlebars instance with helpers.
+ */
+function createHandlebarsInstance() {
+    const hbs = Handlebars.create();
+    registerBuiltinHelpers(hbs);
+    return hbs;
+}
+/**
+ * Load custom helpers from file paths.
+ *
+ * Each file should export a default function that receives the Handlebars instance.
+ *
+ * @param hbs - The Handlebars instance.
+ * @param paths - File paths to custom helper modules.
+ * @param configDir - Directory to resolve relative paths against.
+ */
+async function loadCustomHelpers(hbs, paths, configDir) {
+    for (const p of paths) {
+        const resolved = resolve(configDir, p);
+        const mod = (await import(resolved));
+        if (typeof mod.default === 'function') {
+            mod.default(hbs);
+        }
+    }
+}
+/**
+ * The template engine: holds compiled templates and renders them against context.
+ */
+class TemplateEngine {
+    hbs;
+    compiled = new Map();
+    constructor(hbs) {
+        this.hbs = hbs;
+    }
+    /**
+     * Compile and cache a template from its source string.
+     *
+     * @param key - Cache key (rule index or named template).
+     * @param source - Handlebars template source.
+     * @returns The compiled template.
+     */
+    compile(key, source) {
+        const fn = this.hbs.compile(source);
+        this.compiled.set(key, fn);
+        return fn;
+    }
+    /**
+     * Get a previously compiled template by key.
+     *
+     * @param key - The cache key.
+     * @returns The compiled template, or undefined.
+     */
+    get(key) {
+        return this.compiled.get(key);
+    }
+    /**
+     * Render a compiled template against a context.
+     *
+     * @param key - The cache key of the compiled template.
+     * @param context - The data context for rendering.
+     * @returns The rendered string, or null if the template was not found.
+     */
+    render(key, context) {
+        const fn = this.compiled.get(key);
+        if (!fn)
+            return null;
+        return fn(context);
+    }
+}
+
+/**
+ * @module templates/buildTemplateEngine
+ * Factory to build a TemplateEngine from config, compiling all rule templates at load time.
+ */
+/**
+ * Build a TemplateEngine from configuration, pre-compiling all rule templates.
+ *
+ * @param rules - The inference rules (may contain template fields).
+ * @param namedTemplates - Named template definitions from config.
+ * @param templateHelperPaths - Paths to custom helper modules.
+ * @param configDir - Directory to resolve relative paths against.
+ * @returns The configured TemplateEngine, or undefined if no templates are used.
+ */
+async function buildTemplateEngine(rules, namedTemplates, templateHelperPaths, configDir) {
+    const rulesWithTemplates = rules.filter((r) => r.template);
+    if (rulesWithTemplates.length === 0)
+        return undefined;
+    const hbs = createHandlebarsInstance();
+    // Load custom helpers
+    if (templateHelperPaths?.length && configDir) {
+        await loadCustomHelpers(hbs, templateHelperPaths, configDir);
+    }
+    const engine = new TemplateEngine(hbs);
+    // Compile all rule templates
+    for (const [index, rule] of rules.entries()) {
+        if (!rule.template)
+            continue;
+        const source = resolveTemplateSource(rule.template, namedTemplates, configDir ?? '.');
+        engine.compile(`rule-${String(index)}`, source);
+    }
+    return engine;
+}
+
+/**
+ * @module app/configWatcher
+ * Watches the config file for changes and triggers debounced reload. Isolated I/O wrapper around chokidar.
+ */
+/**
+ * Debounced config file watcher.
+ */
+class ConfigWatcher {
+    options;
+    watcher;
+    debounce;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (!this.options.enabled)
+            return;
+        this.watcher = chokidar.watch(this.options.configPath, {
+            ignoreInitial: true,
+        });
+        this.watcher.on('change', () => {
+            if (this.debounce)
+                clearTimeout(this.debounce);
+            this.debounce = setTimeout(() => {
+                void this.options.onChange();
+            }, this.options.debounceMs);
+        });
+        this.watcher.on('error', (error) => {
+            this.options.logger.error({ err: normalizeError(error) }, 'Config watcher error');
+        });
+        this.options.logger.info({
+            configPath: this.options.configPath,
+            debounceMs: this.options.debounceMs,
+        }, 'Config watcher started');
+    }
+    async stop() {
+        if (this.debounce) {
+            clearTimeout(this.debounce);
+            this.debounce = undefined;
+        }
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = undefined;
+        }
+    }
+}
+
+/**
+ * @module config/defaults
+ * Default configuration values for jeeves-watcher. Pure data export, no I/O or side effects.
+ */
+/** Default root-level config values. */
+const ROOT_DEFAULTS = {
+    metadataDir: '.jeeves-watcher',
+    shutdownTimeoutMs: 10000,
+};
+/** Default configWatch values. */
+const CONFIG_WATCH_DEFAULTS = {
+    enabled: true,
+    debounceMs: 1000,
+};
+/** Default API values. */
+const API_DEFAULTS = {
+    host: '127.0.0.1',
+    port: 3456,
+};
+/** Default logging values. */
+const LOGGING_DEFAULTS = {
+    level: 'info',
+};
+/** Default watch configuration. */
+const WATCH_DEFAULTS = {
+    debounceMs: 300,
+    stabilityThresholdMs: 500,
+    usePolling: false,
+    pollIntervalMs: 1000,
+    respectGitignore: true,
+};
+/** Default embedding configuration. */
+const EMBEDDING_DEFAULTS = {
+    chunkSize: 1000,
+    chunkOverlap: 200,
+    dimensions: 3072,
+    rateLimitPerMinute: 300,
+    concurrency: 5,
+};
+
+/**
+ * Watch configuration for file system monitoring.
+ */
+const watchConfigSchema = z.object({
+    /** Glob patterns to watch. */
+    paths: z
+        .array(z.string())
+        .min(1)
+        .describe('Glob patterns for files to watch (e.g., "**/*.md"). At least one required.'),
+    /** Glob patterns to ignore. */
+    ignored: z
+        .array(z.string())
+        .optional()
+        .describe('Glob patterns to exclude from watching (e.g., "**/node_modules/**").'),
+    /** Polling interval in milliseconds. */
+    pollIntervalMs: z
+        .number()
+        .optional()
+        .describe('Polling interval in milliseconds when usePolling is enabled.'),
+    /** Whether to use polling instead of native watchers. */
+    usePolling: z
+        .boolean()
+        .optional()
+        .describe('Use polling instead of native file system events (for network drives).'),
+    /** Debounce delay in milliseconds for file change events. */
+    debounceMs: z
+        .number()
+        .optional()
+        .describe('Debounce delay in milliseconds for file change events.'),
+    /** Time in milliseconds a file must be stable before processing. */
+    stabilityThresholdMs: z
+        .number()
+        .optional()
+        .describe('Time in milliseconds a file must remain unchanged before processing.'),
+    /** Whether to respect .gitignore files when processing. */
+    respectGitignore: z
+        .boolean()
+        .optional()
+        .describe('Skip files ignored by .gitignore in git repositories. Only applies to repos with a .git directory. Default: true.'),
+});
+/**
+ * Configuration watch settings.
+ */
+const configWatchConfigSchema = z.object({
+    /** Whether config file watching is enabled. */
+    enabled: z
+        .boolean()
+        .optional()
+        .describe('Enable automatic reloading when config file changes.'),
+    /** Debounce delay in milliseconds for config change events. */
+    debounceMs: z
+        .number()
+        .optional()
+        .describe('Debounce delay in milliseconds for config file change detection.'),
+});
+/**
+ * Embedding model configuration.
+ */
+const embeddingConfigSchema = z.object({
+    /** The embedding model provider. */
+    provider: z
+        .string()
+        .default('gemini')
+        .describe('Embedding provider name (e.g., "gemini", "openai").'),
+    /** The embedding model name. */
+    model: z
+        .string()
+        .default('gemini-embedding-001')
+        .describe('Embedding model identifier (e.g., "gemini-embedding-001", "text-embedding-3-small").'),
+    /** Maximum tokens per chunk for splitting. */
+    chunkSize: z
+        .number()
+        .optional()
+        .describe('Maximum chunk size in characters for text splitting.'),
+    /** Overlap between chunks in tokens. */
+    chunkOverlap: z
+        .number()
+        .optional()
+        .describe('Character overlap between consecutive chunks.'),
+    /** Embedding vector dimensions. */
+    dimensions: z
+        .number()
+        .optional()
+        .describe('Embedding vector dimensions (must match model output).'),
+    /** API key for the embedding provider. */
+    apiKey: z
+        .string()
+        .optional()
+        .describe('API key for embedding provider (supports ${ENV_VAR} substitution).'),
+    /** Maximum embedding requests per minute. */
+    rateLimitPerMinute: z
+        .number()
+        .optional()
+        .describe('Maximum embedding API requests per minute (rate limiting).'),
+    /** Maximum concurrent embedding requests. */
+    concurrency: z
+        .number()
+        .optional()
+        .describe('Maximum concurrent embedding requests.'),
+});
+/**
+ * Vector store configuration for Qdrant.
+ */
+const vectorStoreConfigSchema = z.object({
+    /** Qdrant server URL. */
+    url: z
+        .string()
+        .describe('Qdrant server URL (e.g., "http://localhost:6333").'),
+    /** Qdrant collection name. */
+    collectionName: z
+        .string()
+        .describe('Qdrant collection name for vector storage.'),
+    /** Qdrant API key. */
+    apiKey: z
+        .string()
+        .optional()
+        .describe('Qdrant API key for authentication (supports ${ENV_VAR} substitution).'),
+});
+/**
+ * API server configuration.
+ */
+const apiConfigSchema = z.object({
+    /** Host to bind to. */
+    host: z
+        .string()
+        .optional()
+        .describe('Host address for API server (e.g., "127.0.0.1", "0.0.0.0").'),
+    /** Port to listen on. */
+    port: z.number().optional().describe('Port for API server (e.g., 3456).'),
+});
+/**
+ * Logging configuration.
+ */
+const loggingConfigSchema = z.object({
+    /** Log level. */
+    level: z
+        .string()
+        .optional()
         .describe('Logging level (trace, debug, info, warn, error, fatal).'),
     /** Log file path. */
     file: z
@@ -618,7 +1105,12 @@ const inferenceRuleSchema = z.object({
     map: z
         .union([jsonMapMapSchema, z.string()])
         .optional()
-        .describe('JsonMap transformation (inline definition or named map reference).'),
+        .describe('JsonMap transformation (inline definition, named map reference, or .json file path).'),
+    /** Handlebars template (inline string, named ref, or .hbs/.handlebars file path). */
+    template: z
+        .string()
+        .optional()
+        .describe('Handlebars content template (inline string, named ref, or .hbs/.handlebars file path).'),
 });
 /**
  * Top-level configuration for jeeves-watcher.
@@ -655,7 +1147,23 @@ const jeevesWatcherConfigSchema = z.object({
     maps: z
         .record(z.string(), jsonMapMapSchema)
         .optional()
-        .describe('Reusable named JsonMap transformations.'),
+        .describe('Reusable named JsonMap transformations.'),
+    /** Reusable named Handlebars templates (inline strings or .hbs/.handlebars file paths). */
+    templates: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Named reusable Handlebars templates (inline strings or .hbs/.handlebars file paths).'),
+    /** Custom Handlebars helper registration. */
+    templateHelpers: z
+        .object({
+        /** File paths to custom helper modules. */
+        paths: z
+            .array(z.string())
+            .optional()
+            .describe('File paths to custom helper modules.'),
+    })
+        .optional()
+        .describe('Custom Handlebars helper registration.'),
     /** Logging configuration. */
     logging: loggingConfigSchema.optional().describe('Logging configuration.'),
     /** Timeout in milliseconds for graceful shutdown. */
@@ -905,266 +1413,60 @@ function createGeminiProvider(config, logger) {
         dimensions,
         async embed(texts) {
             const vectors = await retry(async (attempt) => {
-                if (attempt > 1) {
-                    log.warn({ attempt, provider: 'gemini', model: config.model }, 'Retrying embedding request');
-                }
-                // embedDocuments returns vectors for multiple texts
-                return embedder.embedDocuments(texts);
-            }, {
-                attempts: 5,
-                baseDelayMs: 500,
-                maxDelayMs: 10_000,
-                jitter: 0.2,
-                onRetry: ({ attempt, delayMs, error }) => {
-                    log.warn({
-                        attempt,
-                        delayMs,
-                        provider: 'gemini',
-                        model: config.model,
-                        err: normalizeError(error),
-                    }, 'Embedding call failed; will retry');
-                },
-            });
-            // Validate dimensions
-            for (const vector of vectors) {
-                if (vector.length !== dimensions) {
-                    throw new Error(`Gemini embedding returned invalid dimensions: expected ${String(dimensions)}, got ${String(vector.length)}`);
-                }
-            }
-            return vectors;
-        },
-    };
-}
-function createMockFromConfig(config) {
-    const dimensions = config.dimensions ?? 768;
-    return createMockProvider(dimensions);
-}
-const embeddingProviderRegistry = new Map([
-    ['mock', createMockFromConfig],
-    ['gemini', createGeminiProvider],
-]);
-/**
- * Create an embedding provider based on the given configuration.
- *
- * Each provider is responsible for its own default dimensions.
- *
- * @param config - The embedding configuration.
- * @param logger - Optional pino logger for retry warnings.
- * @returns An {@link EmbeddingProvider} instance.
- * @throws If the configured provider is not supported.
- */
-function createEmbeddingProvider(config, logger) {
-    const factory = embeddingProviderRegistry.get(config.provider);
-    if (!factory) {
-        throw new Error(`Unsupported embedding provider: ${config.provider}`);
-    }
-    return factory(config, logger);
-}
-
-/**
- * @module gitignore
- * Processor-level gitignore filtering. Scans watched paths for `.gitignore` files in git repos, caches parsed patterns, and exposes `isIgnored()` for path checking.
- */
-/**
- * Find the git repo root by walking up from `startDir` looking for `.git/`.
- * Returns `undefined` if no repo is found.
- */
-function findRepoRoot(startDir) {
-    let dir = resolve(startDir);
-    const root = resolve('/');
-    while (dir !== root) {
-        if (existsSync(join(dir, '.git')) &&
-            statSync(join(dir, '.git')).isDirectory()) {
-            return dir;
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return undefined;
-}
-/**
- * Convert a watch path (directory, file path, or glob) to a concrete directory
- * that can be scanned for a repo root.
- */
-function watchPathToScanDir(watchPath) {
-    const absPath = resolve(watchPath);
-    try {
-        return statSync(absPath).isDirectory() ? absPath : dirname(absPath);
-    }
-    catch {
-        // ignore
-    }
-    // If this is a glob, fall back to the non-glob prefix.
-    const globMatch = /[*?[{]/.exec(watchPath);
-    if (!globMatch)
-        return undefined;
-    const prefix = watchPath.slice(0, globMatch.index);
-    const trimmed = prefix.trim();
-    const baseDir = trimmed.length === 0
-        ? '.'
-        : trimmed.endsWith('/') || trimmed.endsWith('\\')
-            ? trimmed
-            : dirname(trimmed);
-    const resolved = resolve(baseDir);
-    if (!existsSync(resolved))
-        return undefined;
-    return resolved;
-}
-/**
- * Recursively find all `.gitignore` files under `dir`.
- * Skips `.git` and `node_modules` directories for performance.
- */
-function findGitignoreFiles(dir) {
-    const results = [];
-    const gitignorePath = join(dir, '.gitignore');
-    if (existsSync(gitignorePath)) {
-        results.push(gitignorePath);
-    }
-    let entries;
-    try {
-        entries = readdirSync(dir);
-    }
-    catch {
-        return results;
-    }
-    for (const entry of entries) {
-        if (entry === '.git' || entry === 'node_modules')
-            continue;
-        const fullPath = join(dir, entry);
-        try {
-            if (statSync(fullPath).isDirectory()) {
-                results.push(...findGitignoreFiles(fullPath));
-            }
-        }
-        catch {
-            // Skip inaccessible entries
-        }
-    }
-    return results;
-}
-/**
- * Parse a `.gitignore` file into an `ignore` instance.
- */
-function parseGitignore(gitignorePath) {
-    const content = readFileSync(gitignorePath, 'utf8');
-    return ignore().add(content);
-}
-/**
- * Normalize a path to use forward slashes (required by `ignore` package).
- */
-function toForwardSlash(p) {
-    return p.replace(/\\/g, '/');
-}
-/**
- * Processor-level gitignore filter. Checks file paths against the nearest
- * `.gitignore` chain in git repositories.
- */
-class GitignoreFilter {
-    repos = new Map();
-    /**
-     * Create a GitignoreFilter by scanning watched paths for `.gitignore` files.
-     *
-     * @param watchPaths - Absolute paths being watched (directories or globs resolved to roots).
-     */
-    constructor(watchPaths) {
-        this.scan(watchPaths);
-    }
-    /**
-     * Scan paths for git repos and their `.gitignore` files.
-     */
-    scan(watchPaths) {
-        this.repos.clear();
-        const scannedDirs = new Set();
-        for (const watchPath of watchPaths) {
-            const scanDir = watchPathToScanDir(watchPath);
-            if (!scanDir)
-                continue;
-            if (scannedDirs.has(scanDir))
-                continue;
-            scannedDirs.add(scanDir);
-            const repoRoot = findRepoRoot(scanDir);
-            if (!repoRoot)
-                continue;
-            if (this.repos.has(repoRoot))
-                continue;
-            const gitignoreFiles = findGitignoreFiles(repoRoot);
-            const entries = gitignoreFiles.map((gf) => ({
-                dir: dirname(gf),
-                ig: parseGitignore(gf),
-            }));
-            // Sort deepest-first so nested `.gitignore` files are checked first
-            entries.sort((a, b) => b.dir.length - a.dir.length);
-            this.repos.set(repoRoot, { root: repoRoot, entries });
-        }
-    }
-    /**
-     * Check whether a file path is ignored by any applicable `.gitignore`.
-     *
-     * @param filePath - Absolute file path to check.
-     * @returns `true` if the file should be ignored.
-     */
-    isIgnored(filePath) {
-        const absPath = resolve(filePath);
-        for (const [, repo] of this.repos) {
-            // Check if file is within this repo
-            const relToRepo = relative(repo.root, absPath);
-            if (relToRepo.startsWith('..') || relToRepo.startsWith(resolve('/'))) {
-                continue;
-            }
-            // Check each `.gitignore` entry (deepest-first)
-            for (const entry of repo.entries) {
-                const relToEntry = relative(entry.dir, absPath);
-                if (relToEntry.startsWith('..'))
-                    continue;
-                const normalized = toForwardSlash(relToEntry);
-                if (entry.ig.ignores(normalized)) {
-                    return true;
-                }
-            }
-        }
-        return false;
-    }
-    /**
-     * Invalidate and re-parse a specific `.gitignore` file.
-     * Call when a `.gitignore` file is added, changed, or removed.
-     *
-     * @param gitignorePath - Absolute path to the `.gitignore` file that changed.
-     */
-    invalidate(gitignorePath) {
-        const absPath = resolve(gitignorePath);
-        const gitignoreDir = dirname(absPath);
-        for (const [, repo] of this.repos) {
-            const relToRepo = relative(repo.root, gitignoreDir);
-            if (relToRepo.startsWith('..'))
-                continue;
-            // Remove old entry for this directory
-            repo.entries = repo.entries.filter((e) => e.dir !== gitignoreDir);
-            // Re-parse if file still exists
-            if (existsSync(absPath)) {
-                repo.entries.push({ dir: gitignoreDir, ig: parseGitignore(absPath) });
-                // Re-sort deepest-first
-                repo.entries.sort((a, b) => b.dir.length - a.dir.length);
-            }
-            return;
-        }
-        // If not in any known repo, check if it's in a repo we haven't scanned
-        const repoRoot = findRepoRoot(gitignoreDir);
-        if (repoRoot && existsSync(absPath)) {
-            const entries = [
-                { dir: gitignoreDir, ig: parseGitignore(absPath) },
-            ];
-            if (this.repos.has(repoRoot)) {
-                const repo = this.repos.get(repoRoot);
-                repo.entries.push(entries[0]);
-                repo.entries.sort((a, b) => b.dir.length - a.dir.length);
-            }
-            else {
-                this.repos.set(repoRoot, { root: repoRoot, entries });
+                if (attempt > 1) {
+                    log.warn({ attempt, provider: 'gemini', model: config.model }, 'Retrying embedding request');
+                }
+                // embedDocuments returns vectors for multiple texts
+                return embedder.embedDocuments(texts);
+            }, {
+                attempts: 5,
+                baseDelayMs: 500,
+                maxDelayMs: 10_000,
+                jitter: 0.2,
+                onRetry: ({ attempt, delayMs, error }) => {
+                    log.warn({
+                        attempt,
+                        delayMs,
+                        provider: 'gemini',
+                        model: config.model,
+                        err: normalizeError(error),
+                    }, 'Embedding call failed; will retry');
+                },
+            });
+            // Validate dimensions
+            for (const vector of vectors) {
+                if (vector.length !== dimensions) {
+                    throw new Error(`Gemini embedding returned invalid dimensions: expected ${String(dimensions)}, got ${String(vector.length)}`);
+                }
             }
-        }
+            return vectors;
+        },
+    };
+}
+function createMockFromConfig(config) {
+    const dimensions = config.dimensions ?? 768;
+    return createMockProvider(dimensions);
+}
+const embeddingProviderRegistry = new Map([
+    ['mock', createMockFromConfig],
+    ['gemini', createGeminiProvider],
+]);
+/**
+ * Create an embedding provider based on the given configuration.
+ *
+ * Each provider is responsible for its own default dimensions.
+ *
+ * @param config - The embedding configuration.
+ * @param logger - Optional pino logger for retry warnings.
+ * @returns An {@link EmbeddingProvider} instance.
+ * @throws If the configured provider is not supported.
+ */
+function createEmbeddingProvider(config, logger) {
+    const factory = embeddingProviderRegistry.get(config.provider);
+    if (!factory) {
+        throw new Error(`Unsupported embedding provider: ${config.provider}`);
     }
+    return factory(config, logger);
 }
 
 /**
@@ -1396,7 +1698,7 @@ function createJsonMapLib() {
     };
 }
 /**
- * Apply compiled inference rules to file attributes, returning merged metadata.
+ * Apply compiled inference rules to file attributes, returning merged metadata and optional rendered content.
  *
  * Rules are evaluated in order; later rules override earlier ones.
  * If a rule has a `map`, the JsonMap transformation is applied after `set` resolution,
@@ -1406,15 +1708,18 @@ function createJsonMapLib() {
  * @param attributes - The file attributes to match against.
  * @param namedMaps - Optional record of named JsonMap definitions.
  * @param logger - Optional logger for warnings (falls back to console.warn).
- * @returns The merged metadata from all matching rules.
+ * @param templateEngine - Optional template engine for rendering content templates.
+ * @param configDir - Optional config directory for resolving .json map file paths.
+ * @returns The merged metadata and optional rendered content.
  */
-async function applyRules(compiledRules, attributes, namedMaps, logger) {
+async function applyRules(compiledRules, attributes, namedMaps, logger, templateEngine, configDir) {
     // JsonMap's type definitions expect a generic JsonMapLib shape with unary functions.
     // Our helper functions accept multiple args, which JsonMap supports at runtime.
     const lib = createJsonMapLib();
     let merged = {};
+    let renderedContent = null;
     const log = logger ?? console;
-    for (const { rule, validate } of compiledRules) {
+    for (const [ruleIndex, { rule, validate }] of compiledRules.entries()) {
         if (validate(attributes)) {
             // Apply set resolution
             const setOutput = resolveSet(rule.set, attributes);
@@ -1424,10 +1729,24 @@ async function applyRules(compiledRules, attributes, namedMaps, logger) {
                 let mapDef;
                 // Resolve map reference
                 if (typeof rule.map === 'string') {
-                    mapDef = namedMaps?.[rule.map];
-                    if (!mapDef) {
-                        log.warn(`Map reference "${rule.map}" not found in named maps. Skipping map transformation.`);
-                        continue;
+                    if (rule.map.endsWith('.json') && configDir) {
+                        // File path: load from .json file
+                        try {
+                            const mapPath = resolve(configDir, rule.map);
+                            const raw = readFileSync(mapPath, 'utf-8');
+                            mapDef = JSON.parse(raw);
+                        }
+                        catch (error) {
+                            log.warn(`Failed to load map file "${rule.map}": ${error instanceof Error ? error.message : String(error)}`);
+                            continue;
+                        }
+                    }
+                    else {
+                        mapDef = namedMaps?.[rule.map];
+                        if (!mapDef) {
+                            log.warn(`Map reference "${rule.map}" not found in named maps. Skipping map transformation.`);
+                            continue;
+                        }
                     }
                 }
                 else {
@@ -1450,9 +1769,31 @@ async function applyRules(compiledRules, attributes, namedMaps, logger) {
                     log.warn(`JsonMap transformation failed: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
+            // Render template if present
+            if (rule.template && templateEngine) {
+                const templateKey = `rule-${String(ruleIndex)}`;
+                // Build template context: attributes (with json spread at top) + map output
+                const context = {
+                    ...(attributes.json ?? {}),
+                    ...attributes,
+                    ...merged,
+                };
+                try {
+                    const result = templateEngine.render(templateKey, context);
+                    if (result && result.trim()) {
+                        renderedContent = result;
+                    }
+                    else {
+                        log.warn(`Template for rule ${String(ruleIndex)} rendered empty output. Falling back to raw content.`);
+                    }
+                }
+                catch (error) {
+                    log.warn(`Template render failed for rule ${String(ruleIndex)}: ${error instanceof Error ? error.message : String(error)}. Falling back to raw content.`);
+                }
+            }
         }
     }
-    return merged;
+    return { metadata: merged, renderedContent };
 }
 
 /**
@@ -1541,23 +1882,32 @@ function compileRules(rules) {
  * @param metadataDir - The metadata directory for enrichment files.
  * @param maps - Optional named JsonMap definitions.
  * @param logger - Optional logger for rule warnings.
+ * @param templateEngine - Optional template engine for content templates.
+ * @param configDir - Optional config directory for resolving file paths.
  * @returns The merged metadata and intermediate data.
  */
-async function buildMergedMetadata(filePath, compiledRules, metadataDir, maps, logger) {
+async function buildMergedMetadata(filePath, compiledRules, metadataDir, maps, logger, templateEngine, configDir) {
     const ext = extname(filePath);
     const stats = await stat(filePath);
     // 1. Extract text and structured data
     const extracted = await extractText(filePath, ext);
     // 2. Build attributes + apply rules
     const attributes = buildAttributes(filePath, stats, extracted.frontmatter, extracted.json);
-    const inferred = await applyRules(compiledRules, attributes, maps, logger);
+    const { metadata: inferred, renderedContent } = await applyRules(compiledRules, attributes, maps, logger, templateEngine, configDir);
     // 3. Read enrichment metadata (merge, enrichment wins)
     const enrichment = await readMetadata(filePath, metadataDir);
     const metadata = {
         ...inferred,
         ...(enrichment ?? {}),
     };
-    return { inferred, enrichment, metadata, attributes, extracted };
+    return {
+        inferred,
+        enrichment,
+        metadata,
+        attributes,
+        extracted,
+        renderedContent,
+    };
 }
 
 /**
@@ -1628,6 +1978,7 @@ class DocumentProcessor {
     vectorStore;
     compiledRules;
     logger;
+    templateEngine;
     /**
      * Create a new DocumentProcessor.
      *
@@ -1636,13 +1987,15 @@ class DocumentProcessor {
      * @param vectorStore - The vector store client.
      * @param compiledRules - The compiled inference rules.
      * @param logger - The logger instance.
+     * @param templateEngine - Optional template engine for content templates.
      */
-    constructor(config, embeddingProvider, vectorStore, compiledRules, logger) {
+    constructor(config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine) {
         this.config = config;
         this.embeddingProvider = embeddingProvider;
         this.vectorStore = vectorStore;
         this.compiledRules = compiledRules;
         this.logger = logger;
+        this.templateEngine = templateEngine;
     }
     /**
      * Process a file through the full pipeline: extract, hash, chunk, embed, upsert.
@@ -1653,13 +2006,15 @@ class DocumentProcessor {
         try {
             const ext = extname(filePath);
             // 1. Build merged metadata + extract text
-            const { metadata, extracted } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger);
-            if (!extracted.text.trim()) {
+            const { metadata, extracted, renderedContent } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger, this.templateEngine, this.config.configDir);
+            // Use rendered template content if available, otherwise raw extracted text
+            const textToEmbed = renderedContent ?? extracted.text;
+            if (!textToEmbed.trim()) {
                 this.logger.debug({ filePath }, 'Skipping empty file');
                 return;
             }
             // 2. Content hash check — skip if unchanged
-            const hash = contentHash(extracted.text);
+            const hash = contentHash(textToEmbed);
             const baseId = pointId(filePath, 0);
             const existingPayload = await this.vectorStore.getPayload(baseId);
             if (existingPayload && existingPayload['content_hash'] === hash) {
@@ -1671,7 +2026,7 @@ class DocumentProcessor {
             const chunkSize = this.config.chunkSize ?? 1000;
             const chunkOverlap = this.config.chunkOverlap ?? 200;
             const splitter = createSplitter(ext, chunkSize, chunkOverlap);
-            const chunks = await splitter.splitText(extracted.text);
+            const chunks = await splitter.splitText(textToEmbed);
             // 4. Embed all chunks
             const vectors = await this.embeddingProvider.embed(chunks);
             // 5. Upsert all chunk points
@@ -1765,7 +2120,7 @@ class DocumentProcessor {
                 return null;
             }
             // Build merged metadata (lightweight — no embedding)
-            const { metadata } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger);
+            const { metadata } = await buildMergedMetadata(filePath, this.compiledRules, this.config.metadataDir, this.config.maps, this.logger, this.templateEngine, this.config.configDir);
             // Update all chunk payloads
             const totalChunks = getChunkCount(existingPayload);
             const ids = chunkIds(filePath, totalChunks);
@@ -1783,8 +2138,17 @@ class DocumentProcessor {
      *
      * @param compiledRules - The newly compiled rules.
      */
-    updateRules(compiledRules) {
+    /**
+     * Update compiled inference rules and optionally the template engine.
+     *
+     * @param compiledRules - The newly compiled rules.
+     * @param templateEngine - Optional updated template engine.
+     */
+    updateRules(compiledRules, templateEngine) {
         this.compiledRules = compiledRules;
+        if (templateEngine) {
+            this.templateEngine = templateEngine;
+        }
         this.logger.info({ rules: compiledRules.length }, 'Inference rules updated');
     }
 }
@@ -2313,6 +2677,76 @@ class SystemHealth {
     }
 }
 
+/**
+ * @module watcher/globToDir
+ * Adapts glob-based watch config to chokidar v4+, which removed glob support
+ * (see paulmillr/chokidar#1350). Chokidar v4 treats glob patterns as literal
+ * strings, silently producing zero events. This module extracts static directory
+ * roots from glob patterns for chokidar to watch, then filters emitted events
+ * against the original globs via picomatch.
+ */
+/**
+ * Extract the static directory root from a glob pattern.
+ * Stops at the first segment containing glob characters (`*`, `{`, `?`, `[`).
+ *
+ * @param glob - A glob pattern (e.g., `j:/domains/**\/*.json`).
+ * @returns The static directory prefix (e.g., `j:/domains`).
+ */
+function globRoot(glob) {
+    const normalized = glob.replace(/\\/g, '/');
+    const segments = normalized.split('/');
+    const staticSegments = [];
+    for (const seg of segments) {
+        if (/[*?{[\]]/.test(seg))
+            break;
+        staticSegments.push(seg);
+    }
+    return staticSegments.join('/') || '.';
+}
+/**
+ * Deduplicate directory roots, removing paths that are subdirectories of others.
+ *
+ * @param roots - Array of directory paths.
+ * @returns Deduplicated array with subdirectories removed.
+ */
+function deduplicateRoots(roots) {
+    const normalized = roots.map((r) => r.replace(/\\/g, '/').toLowerCase());
+    const sorted = [...new Set(normalized)].sort();
+    return sorted.filter((root, _i, arr) => {
+        const withSlash = root.endsWith('/') ? root : root + '/';
+        return !arr.some((other) => other !== root && withSlash.startsWith(other + '/'));
+    });
+}
+/**
+ * Build a picomatch matcher from an array of glob patterns.
+ * Normalizes Windows paths (backslash → forward slash, lowercase drive letter)
+ * before matching.
+ *
+ * @param globs - Glob patterns to match against.
+ * @returns A function that tests whether a file path matches any of the globs.
+ */
+function buildGlobMatcher(globs) {
+    const normalizedGlobs = globs.map((g) => g.replace(/\\/g, '/'));
+    const isMatch = picomatch(normalizedGlobs, { dot: true, nocase: true });
+    return (filePath) => {
+        const normalized = filePath.replace(/\\/g, '/');
+        return isMatch(normalized);
+    };
+}
+/**
+ * Convert an array of glob patterns into chokidar-compatible directory roots
+ * and a filter function for post-hoc event filtering.
+ *
+ * @param globs - Glob patterns from the watch config.
+ * @returns Object with `roots` (directories for chokidar) and `matches` (filter function).
+ */
+function resolveWatchPaths(globs) {
+    const rawRoots = globs.map(globRoot);
+    const roots = deduplicateRoots(rawRoots);
+    const matches = buildGlobMatcher(globs);
+    return { roots, matches };
+}
+
 /**
  * @module watcher
  * Filesystem watcher wrapping chokidar. I/O: watches files/directories for add/change/unlink events, enqueues to processing queue.
@@ -2327,6 +2761,7 @@ class FileSystemWatcher {
     logger;
     health;
     gitignoreFilter;
+    globMatches;
     watcher;
     /**
      * Create a new FileSystemWatcher.
@@ -2343,6 +2778,7 @@ class FileSystemWatcher {
         this.processor = processor;
         this.logger = logger;
         this.gitignoreFilter = options.gitignoreFilter;
+        this.globMatches = () => true;
         const healthOptions = {
             maxRetries: options.maxRetries,
             maxBackoffMs: options.maxBackoffMs,
@@ -2355,7 +2791,13 @@ class FileSystemWatcher {
      * Start watching the filesystem and processing events.
      */
     start() {
-        this.watcher = chokidar.watch(this.config.paths, {
+        // Chokidar v4+ removed glob support (paulmillr/chokidar#1350).
+        // Glob patterns are silently treated as literal strings, producing zero
+        // events. We extract static directory roots for chokidar to watch, then
+        // filter emitted events against the original globs via picomatch.
+        const { roots, matches } = resolveWatchPaths(this.config.paths);
+        this.globMatches = matches;
+        this.watcher = chokidar.watch(roots, {
             ignored: this.config.ignored,
             usePolling: this.config.usePolling,
             interval: this.config.pollIntervalMs,
@@ -2366,6 +2808,8 @@ class FileSystemWatcher {
         });
         this.watcher.on('add', (path) => {
             this.handleGitignoreChange(path);
+            if (!this.globMatches(path))
+                return;
             if (this.isGitignored(path))
                 return;
             this.logger.debug({ path }, 'File added');
@@ -2373,6 +2817,8 @@ class FileSystemWatcher {
         });
         this.watcher.on('change', (path) => {
             this.handleGitignoreChange(path);
+            if (!this.globMatches(path))
+                return;
             if (this.isGitignored(path))
                 return;
             this.logger.debug({ path }, 'File changed');
@@ -2380,6 +2826,8 @@ class FileSystemWatcher {
         });
         this.watcher.on('unlink', (path) => {
             this.handleGitignoreChange(path);
+            if (!this.globMatches(path))
+                return;
             if (this.isGitignored(path))
                 return;
             this.logger.debug({ path }, 'File removed');
@@ -2452,51 +2900,21 @@ class FileSystemWatcher {
 }
 
 /**
- * @module app/configWatcher
- * Watches the config file for changes and triggers debounced reload. Isolated I/O wrapper around chokidar.
- */
-/**
- * Debounced config file watcher.
+ * @module app/factories
+ * Component factory interfaces and defaults for {@link JeevesWatcher}. Override in tests to inject mocks.
  */
-class ConfigWatcher {
-    options;
-    watcher;
-    debounce;
-    constructor(options) {
-        this.options = options;
-    }
-    start() {
-        if (!this.options.enabled)
-            return;
-        this.watcher = chokidar.watch(this.options.configPath, {
-            ignoreInitial: true,
-        });
-        this.watcher.on('change', () => {
-            if (this.debounce)
-                clearTimeout(this.debounce);
-            this.debounce = setTimeout(() => {
-                void this.options.onChange();
-            }, this.options.debounceMs);
-        });
-        this.watcher.on('error', (error) => {
-            this.options.logger.error({ err: normalizeError(error) }, 'Config watcher error');
-        });
-        this.options.logger.info({
-            configPath: this.options.configPath,
-            debounceMs: this.options.debounceMs,
-        }, 'Config watcher started');
-    }
-    async stop() {
-        if (this.debounce) {
-            clearTimeout(this.debounce);
-            this.debounce = undefined;
-        }
-        if (this.watcher) {
-            await this.watcher.close();
-            this.watcher = undefined;
-        }
-    }
-}
+/** Default component factories wiring real implementations. */
+const defaultFactories = {
+    loadConfig,
+    createLogger,
+    createEmbeddingProvider,
+    createVectorStoreClient: (config, dimensions, logger) => new VectorStoreClient(config, dimensions, logger),
+    compileRules,
+    createDocumentProcessor: (config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine) => new DocumentProcessor(config, embeddingProvider, vectorStore, compiledRules, logger, templateEngine),
+    createEventQueue: (options) => new EventQueue(options),
+    createFileSystemWatcher: (config, queue, processor, logger, options) => new FileSystemWatcher(config, queue, processor, logger, options),
+    createApiServer,
+};
 
 /**
  * @module app/shutdown
@@ -2516,17 +2934,28 @@ function installShutdownHandlers(stop) {
     process.on('SIGINT', () => void shutdown());
 }
 
-const defaultFactories = {
-    loadConfig,
-    createLogger,
-    createEmbeddingProvider,
-    createVectorStoreClient: (config, dimensions, logger) => new VectorStoreClient(config, dimensions, logger),
-    compileRules,
-    createDocumentProcessor: (config, embeddingProvider, vectorStore, compiledRules, logger) => new DocumentProcessor(config, embeddingProvider, vectorStore, compiledRules, logger),
-    createEventQueue: (options) => new EventQueue(options),
-    createFileSystemWatcher: (config, queue, processor, logger, options) => new FileSystemWatcher(config, queue, processor, logger, options),
-    createApiServer,
-};
+/**
+ * @module app/startFromConfig
+ * Convenience entry point: loads config from disk and starts a {@link JeevesWatcher}.
+ */
+/**
+ * Create and start a JeevesWatcher from a config file path.
+ *
+ * @param configPath - Optional path to the configuration file.
+ * @returns The running JeevesWatcher instance.
+ */
+async function startFromConfig(configPath) {
+    const config = await loadConfig(configPath);
+    const app = new JeevesWatcher(config, configPath);
+    installShutdownHandlers(() => app.stop());
+    await app.start();
+    return app;
+}
+
+/**
+ * @module app
+ * Main application orchestrator. Wires components, manages lifecycle (start/stop/reload).
+ */
 /**
  * Main application class that wires together all components.
  */
@@ -2561,56 +2990,26 @@ class JeevesWatcher {
     async start() {
         const logger = this.factories.createLogger(this.config.logging);
         this.logger = logger;
-        let embeddingProvider;
-        try {
-            embeddingProvider = this.factories.createEmbeddingProvider(this.config.embedding, logger);
-        }
-        catch (error) {
-            logger.fatal({ err: normalizeError(error) }, 'Failed to create embedding provider');
-            throw error;
-        }
-        const vectorStore = this.factories.createVectorStoreClient(this.config.vectorStore, embeddingProvider.dimensions, logger);
-        await vectorStore.ensureCollection();
+        const { embeddingProvider, vectorStore } = await this.initEmbeddingAndStore(logger);
         const compiledRules = this.factories.compileRules(this.config.inferenceRules ?? []);
-        const processorConfig = {
+        const configDir = this.configPath ? dirname(this.configPath) : '.';
+        const templateEngine = await buildTemplateEngine(this.config.inferenceRules ?? [], this.config.templates, this.config.templateHelpers?.paths, configDir);
+        const processor = this.factories.createDocumentProcessor({
             metadataDir: this.config.metadataDir ?? '.jeeves-metadata',
             chunkSize: this.config.embedding.chunkSize,
             chunkOverlap: this.config.embedding.chunkOverlap,
             maps: this.config.maps,
-        };
-        const processor = this.factories.createDocumentProcessor(processorConfig, embeddingProvider, vectorStore, compiledRules, logger);
+            configDir,
+        }, embeddingProvider, vectorStore, compiledRules, logger, templateEngine);
         this.processor = processor;
-        const queue = this.factories.createEventQueue({
+        this.queue = this.factories.createEventQueue({
             debounceMs: this.config.watch.debounceMs ?? 2000,
             concurrency: this.config.embedding.concurrency ?? 5,
             rateLimitPerMinute: this.config.embedding.rateLimitPerMinute,
         });
-        this.queue = queue;
-        const respectGitignore = this.config.watch.respectGitignore ?? true;
-        const gitignoreFilter = respectGitignore
-            ? new GitignoreFilter(this.config.watch.paths)
-            : undefined;
-        const watcher = this.factories.createFileSystemWatcher(this.config.watch, queue, processor, logger, {
-            maxRetries: this.config.maxRetries,
-            maxBackoffMs: this.config.maxBackoffMs,
-            onFatalError: this.runtimeOptions.onFatalError,
-            gitignoreFilter,
-        });
-        this.watcher = watcher;
-        const server = this.factories.createApiServer({
-            processor,
-            vectorStore,
-            embeddingProvider,
-            queue,
-            config: this.config,
-            logger,
-        });
-        this.server = server;
-        await server.listen({
-            host: this.config.api?.host ?? '127.0.0.1',
-            port: this.config.api?.port ?? 3456,
-        });
-        watcher.start();
+        this.watcher = this.createWatcher(this.queue, processor, logger);
+        this.server = await this.startApiServer(processor, vectorStore, embeddingProvider, logger);
+        this.watcher.start();
         this.startConfigWatch();
         logger.info('jeeves-watcher started');
     }
@@ -2641,22 +3040,61 @@ class JeevesWatcher {
         }
         this.logger?.info('jeeves-watcher stopped');
     }
+    async initEmbeddingAndStore(logger) {
+        let embeddingProvider;
+        try {
+            embeddingProvider = this.factories.createEmbeddingProvider(this.config.embedding, logger);
+        }
+        catch (error) {
+            logger.fatal({ err: normalizeError(error) }, 'Failed to create embedding provider');
+            throw error;
+        }
+        const vectorStore = this.factories.createVectorStoreClient(this.config.vectorStore, embeddingProvider.dimensions, logger);
+        await vectorStore.ensureCollection();
+        return { embeddingProvider, vectorStore };
+    }
+    createWatcher(queue, processor, logger) {
+        const respectGitignore = this.config.watch.respectGitignore ?? true;
+        const gitignoreFilter = respectGitignore
+            ? new GitignoreFilter(this.config.watch.paths)
+            : undefined;
+        return this.factories.createFileSystemWatcher(this.config.watch, queue, processor, logger, {
+            maxRetries: this.config.maxRetries,
+            maxBackoffMs: this.config.maxBackoffMs,
+            onFatalError: this.runtimeOptions.onFatalError,
+            gitignoreFilter,
+        });
+    }
+    async startApiServer(processor, vectorStore, embeddingProvider, logger) {
+        const server = this.factories.createApiServer({
+            processor,
+            vectorStore,
+            embeddingProvider,
+            queue: this.queue,
+            config: this.config,
+            logger,
+        });
+        await server.listen({
+            host: this.config.api?.host ?? '127.0.0.1',
+            port: this.config.api?.port ?? 3456,
+        });
+        return server;
+    }
     startConfigWatch() {
         const logger = this.logger;
         if (!logger)
             return;
         const enabled = this.config.configWatch?.enabled ?? true;
-        if (!enabled)
-            return;
-        if (!this.configPath) {
-            logger.debug('Config watch enabled, but no config path was provided');
+        if (!enabled || !this.configPath) {
+            if (!this.configPath) {
+                logger.debug('Config watch enabled, but no config path was provided');
+            }
             return;
         }
-        const debounceMs = this.config.configWatch?.debounceMs ?? 10000;
         this.configWatcher = new ConfigWatcher({
             configPath: this.configPath,
             enabled,
-            debounceMs,
+            debounceMs: this.config.configWatch?.debounceMs ?? 10000,
             logger,
             onChange: async () => this.reloadConfig(),
         });
@@ -2678,7 +3116,9 @@ class JeevesWatcher {
             const newConfig = await this.factories.loadConfig(this.configPath);
             this.config = newConfig;
             const compiledRules = this.factories.compileRules(newConfig.inferenceRules ?? []);
-            processor.updateRules(compiledRules);
+            const reloadConfigDir = dirname(this.configPath);
+            const newTemplateEngine = await buildTemplateEngine(newConfig.inferenceRules ?? [], newConfig.templates, newConfig.templateHelpers?.paths, reloadConfigDir);
+            processor.updateRules(compiledRules, newTemplateEngine);
             logger.info({ configPath: this.configPath, rules: compiledRules.length }, 'Config reloaded');
         }
         catch (error) {
@@ -2686,18 +3126,6 @@ class JeevesWatcher {
         }
     }
 }
-/**
- * Create and start a JeevesWatcher from a config file path.
- *
- * @param configPath - Optional path to the configuration file.
- * @returns The running JeevesWatcher instance.
- */
-async function startFromConfig(configPath) {
-    const config = await loadConfig(configPath);
-    const app = new JeevesWatcher(config, configPath);
-    installShutdownHandlers(() => app.stop());
-    await app.start();
-    return app;
-}
+// startFromConfig re-exported from ./startFromConfig
 
-export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, JeevesWatcher, SystemHealth, VectorStoreClient, apiConfigSchema, applyRules, buildAttributes, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, jeevesWatcherConfigSchema, loadConfig, loggingConfigSchema, metadataPath, pointId, readMetadata, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };
+export { DocumentProcessor, EventQueue, FileSystemWatcher, GitignoreFilter, JeevesWatcher, SystemHealth, TemplateEngine, VectorStoreClient, apiConfigSchema, applyRules, buildAttributes, buildTemplateEngine, compileRules, configWatchConfigSchema, contentHash, createApiServer, createEmbeddingProvider, createHandlebarsInstance, createLogger, deleteMetadata, embeddingConfigSchema, extractText, inferenceRuleSchema, jeevesWatcherConfigSchema, loadConfig, loadCustomHelpers, loggingConfigSchema, metadataPath, pointId, readMetadata, registerBuiltinHelpers, resolveTemplateSource, startFromConfig, vectorStoreConfigSchema, watchConfigSchema, writeMetadata };