@karmaniverous/jeeves-watcher 0.16.3 → 0.17.0

package/dist/index.js

@@ -1,15 +1,15 @@
 import { join, dirname, resolve, relative, extname, basename, isAbsolute } from 'node:path';
-import { createConfigQueryHandler as createConfigQueryHandler$1, createStatusHandler, getBindAddress, postJson, fetchJson } from '@karmaniverous/jeeves';
+import { createConfigQueryHandler as createConfigQueryHandler$1, createStatusHandler, createConfigApplyHandler, DEFAULT_PORTS, getBindAddress, postJson, fetchJson } from '@karmaniverous/jeeves';
 import Fastify from 'fastify';
-import { readdir, stat, writeFile, readFile } from 'node:fs/promises';
+import { readdir, stat, readFile } from 'node:fs/promises';
 import { parallel, capitalize, title, camel, snake, dash, isEqual, get, omit } from 'radash';
 import { existsSync, statSync, readFileSync, readdirSync, mkdirSync, writeFileSync, rmSync, renameSync } from 'node:fs';
 import ignore from 'ignore';
 import picomatch from 'picomatch';
-import { z, ZodError } from 'zod';
-import { jsonMapMapSchema, JsonMap } from '@karmaniverous/jsonmap';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
+import { z, ZodError } from 'zod';
+import { jsonMapMapSchema, JsonMap } from '@karmaniverous/jsonmap';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import Handlebars from 'handlebars';
 import dayjs from 'dayjs';
@@ -614,10 +614,10 @@ async function fireCallback(url, payload, logger) {
 function groupByRoot(filePaths, watchPaths) {
     const byRoot = {};
     for (const fp of filePaths) {
-        const normalised = fp.replace(/\\/g, '/');
+        const normalised = normalizeSlashes(fp);
         let matched = false;
         for (const root of watchPaths) {
-            const rootNorm = root.replace(/\\/g, '/').replace(/\/?\*\*.*$/, '');
+            const rootNorm = normalizeSlashes(root).replace(/\/?\*\*.*$/, '');
             if (normalised.startsWith(rootNorm)) {
                 byRoot[rootNorm] = (byRoot[rootNorm] ?? 0) + 1;
                 matched = true;
@@ -969,579 +969,135 @@ async function getPathFileList(targetPath, config, gitignoreFilter) {
 }
 
 /**
- * @module config/schemas/base
- * Base configuration schemas: watch, logging, API.
+ * @module rules/attributes
+ * Builds file attribute objects for rule matching. Pure function: derives attributes from path, stats, and extracted data.
  */
+/** Derive the path-based file properties shared by all attribute builders. */
+function buildFileProps(filePath) {
+    const normalised = normalizeSlashes(filePath);
+    return {
+        path: normalised,
+        directory: normalizeSlashes(dirname(normalised)),
+        filename: basename(normalised),
+        extension: extname(normalised),
+    };
+}
 /**
- * Watch configuration for file system monitoring.
+ * Build {@link FileAttributes} from a file path and stat info.
+ *
+ * @param filePath - The file path.
+ * @param stats - The file stats.
+ * @param extractedFrontmatter - Optional extracted frontmatter.
+ * @param extractedJson - Optional parsed JSON content.
+ * @returns The constructed file attributes.
  */
-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.'),
-    /** Move detection configuration for correlating unlink+add as file moves. */
-    moveDetection: z
-        .object({
-        /** Enable move correlation. Default: true. */
-        enabled: z
-            .boolean()
-            .default(true)
-            .describe('Enable move detection via content hash correlation.'),
-        /** Buffer time in ms for holding unlink events before treating as deletes. Default: 2000. */
-        bufferMs: z
-            .number()
-            .int()
-            .min(100)
-            .default(2000)
-            .describe('How long (ms) to buffer unlink events before treating as deletes.'),
-    })
-        .optional()
-        .describe('Move detection: correlate unlink+add events as file moves to avoid re-embedding.'),
-});
+function buildAttributes(filePath, stats, extractedFrontmatter, extractedJson) {
+    const attrs = {
+        file: {
+            ...buildFileProps(filePath),
+            sizeBytes: stats.size,
+            modified: stats.mtime.toISOString(),
+        },
+    };
+    if (extractedFrontmatter)
+        attrs.frontmatter = extractedFrontmatter;
+    if (extractedJson)
+        attrs.json = extractedJson;
+    return attrs;
+}
 /**
- * Configuration watch settings.
+ * Build synthetic file attributes from a path string (no actual file I/O).
+ * Used by API handlers that need to match rules against paths without reading files.
+ *
+ * @param filePath - The file path.
+ * @returns Synthetic file attributes with zeroed stats.
  */
-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.'),
-    /** Reindex scope triggered on config change. */
-    reindex: z
-        .union([
-        z
-            .literal('issues')
-            .describe('Re-process only files with recorded issues.'),
-        z.literal('full').describe('Full reindex of all watched files.'),
-        z
-            .literal('rules')
-            .describe('Re-apply inference rules to existing points without re-embedding.'),
-    ])
-        .optional()
-        .describe('Reindex scope triggered on config change. Default: issues.'),
-});
+function buildSyntheticAttributes(filePath) {
+    return {
+        file: {
+            ...buildFileProps(filePath),
+            sizeBytes: 0,
+            modified: new Date(0).toISOString(),
+        },
+    };
+}
+
 /**
- * API server configuration.
+ * @module rules/ajvSetup
+ * AJV instance factory with custom glob keyword for picomatch-based pattern matching in rule schemas.
  */
-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., 1936).'),
-    /** Read endpoint cache TTL in milliseconds. */
-    cacheTtlMs: z
-        .number()
-        .optional()
-        .describe('TTL in milliseconds for caching read-heavy endpoints (e.g., /status, /config). Default: 30000.'),
-});
 /**
- * Logging configuration.
+ * Create an AJV instance with a custom `glob` format for picomatch glob matching.
+ *
+ * @returns The configured AJV instance.
  */
-const loggingConfigSchema = z.object({
-    /** Log level. */
-    level: z
-        .string()
-        .optional()
-        .describe('Logging level (trace, debug, info, warn, error, fatal).'),
-    /** Log file path. */
-    file: z
-        .string()
-        .optional()
-        .describe('Path to log file (logs to stdout if omitted).'),
-});
+function createRuleAjv() {
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    ajv.addKeyword({
+        keyword: 'glob',
+        type: 'string',
+        schemaType: 'string',
+        validate: (pattern, data) => picomatch.isMatch(data, pattern, { dot: true, nocase: true }),
+    });
+    return ajv;
+}
 
 /**
- * @module config/schemas/inference
- * Inference rule and schema configuration schemas.
+ * @module rules/compile
+ * Compiles inference rule definitions into executable AJV validators for efficient rule evaluation.
  */
 /**
- * A JSON Schema property definition with optional custom keywords.
- * Supports standard JSON Schema keywords plus custom `set` and `uiHint`.
+ * Validate that all rule names are unique.
+ * Throws if duplicate names are found.
+ *
+ * @param rules - The inference rule definitions.
  */
-const propertySchemaSchema = z.record(z.string(), z.unknown());
+function validateRuleNameUniqueness(rules) {
+    const names = new Set();
+    const duplicates = [];
+    for (const rule of rules) {
+        if (names.has(rule.name)) {
+            duplicates.push(rule.name);
+        }
+        else {
+            names.add(rule.name);
+        }
+    }
+    if (duplicates.length > 0) {
+        throw new Error(`Duplicate inference rule names found: ${duplicates.join(', ')}. Rule names must be unique.`);
+    }
+}
 /**
- * A schema object: properties with JSON Schema definitions.
+ * Compile an array of inference rules into executable validators.
+ * Validates rule name uniqueness before compilation.
+ *
+ * @param rules - The inference rule definitions.
+ * @returns An array of compiled rules.
  */
-const schemaObjectSchema = z.object({
-    type: z
-        .literal('object')
-        .optional()
-        .describe('JSON Schema type (always "object" for schema definitions).'),
-    properties: z
-        .record(z.string(), propertySchemaSchema)
-        .optional()
-        .describe('Map of property names to JSON Schema property definitions.'),
-});
+function compileRules(rules) {
+    validateRuleNameUniqueness(rules);
+    const ajv = createRuleAjv();
+    return rules.map((rule) => ({
+        rule,
+        validate: ajv.compile({
+            $id: rule.name,
+            ...rule.match,
+        }),
+    }));
+}
+
 /**
- * Global schema entry: inline object or file path.
+ * @module api/handlers/wrapHandler
+ * Generic error-handling wrapper for Fastify route handlers.
  */
-const schemaEntrySchema = z.union([
-    schemaObjectSchema,
-    z.string().describe('File path to a JSON schema file.'),
-]);
 /**
- * Schema reference: either a named schema reference (string) or an inline schema object.
- */
-const schemaReferenceSchema = z.union([
-    z.string().describe('Named reference to a global schema.'),
-    schemaObjectSchema,
-]);
-/** Render body section. */
-const renderBodySectionSchema = z.object({
-    /** Key path in the template context to render. */
-    path: z.string().min(1).describe('Key path in template context to render.'),
-    /** Markdown heading level for this section (1-6). */
-    heading: z.number().min(1).max(6).describe('Markdown heading level (1-6).'),
-    /** Override heading text (default: titlecased path). */
-    label: z.string().optional().describe('Override heading text.'),
-    /** Name of a registered Handlebars helper used as a format handler. */
-    format: z
-        .string()
-        .optional()
-        .describe('Name of a registered Handlebars helper used as a format handler.'),
-    /** Additional args passed to the format helper. */
-    formatArgs: z
-        .array(z.unknown())
-        .optional()
-        .describe('Additional args passed to the format helper.'),
-    /** If true, the value at path is treated as an array and iterated. */
-    each: z
-        .boolean()
-        .optional()
-        .describe('If true, the value at path is treated as an array and iterated.'),
-    /** Handlebars template string for per-item heading text (used when each=true). */
-    headingTemplate: z
-        .string()
-        .optional()
-        .describe('Handlebars template string for per-item heading text (used when each=true).'),
-    /** Key path within each item to use as renderable content (used when each=true). */
-    contentPath: z
-        .string()
-        .optional()
-        .describe('Key path within each item to use as renderable content (used when each=true).'),
-    /** Key path within each item to sort by (used when each=true). */
-    sort: z
-        .string()
-        .optional()
-        .describe('Key path within each item to sort by (used when each=true).'),
-});
-/** Render config: YAML frontmatter + ordered body sections. */
-const renderConfigSchema = z.object({
-    /** Keys or glob patterns to extract from context and include as YAML frontmatter. */
-    frontmatter: z
-        .array(z.string().min(1))
-        .describe('Keys or glob patterns to include as YAML frontmatter. ' +
-        'Supports picomatch globs (e.g. "*") and "!"-prefixed exclusion patterns (e.g. "!_*"). ' +
-        'Explicit names preserve declaration order; glob-matched keys are sorted alphabetically.'),
-    /** Ordered markdown body sections. */
-    body: z
-        .array(renderBodySectionSchema)
-        .describe('Ordered markdown body sections.'),
-});
-/**
- * An inference rule that enriches document metadata.
- */
-const inferenceRuleSchema = z
-    .object({
-    /** Unique name for this inference rule. */
-    name: z
-        .string()
-        .min(1)
-        .describe('Unique name identifying this inference rule.'),
-    /** Human-readable description of what this rule does. */
-    description: z
-        .string()
-        .min(1)
-        .describe('Human-readable description of what this rule does.'),
-    /** JSON Schema object to match against document metadata. */
-    match: z
-        .record(z.string(), z.unknown())
-        .describe('JSON Schema object to match against file attributes.'),
-    /** Array of schema references to merge (named refs and/or inline objects). */
-    schema: z
-        .array(schemaReferenceSchema)
-        .optional()
-        .describe('Array of schema references (named schema refs or inline objects) merged left-to-right.'),
-    /** JsonMap transformation (inline or reference to named map). */
-    map: z
-        .union([jsonMapMapSchema, z.string()])
-        .optional()
-        .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).'),
-    /** Declarative structured renderer configuration (mutually exclusive with template). */
-    render: renderConfigSchema
-        .optional()
-        .describe('Declarative render configuration for frontmatter + structured Markdown output (mutually exclusive with template).'),
-    /** Output file extension override (e.g. "md", "html", "txt"). Requires template or render. */
-    renderAs: z
-        .string()
-        .regex(/^[a-z0-9]{1,10}$/, 'renderAs must be 1-10 lowercase alphanumeric characters')
-        .optional()
-        .describe('Output file extension override (without dot). Requires template or render.'),
-})
-    .superRefine((val, ctx) => {
-    if (val.render && val.template) {
-        ctx.addIssue({
-            code: 'custom',
-            path: ['render'],
-            message: 'render is mutually exclusive with template',
-        });
-    }
-    if (val.renderAs && !val.template && !val.render) {
-        ctx.addIssue({
-            code: 'custom',
-            path: ['renderAs'],
-            message: 'renderAs requires template or render',
-        });
-    }
-});
-
-/**
- * @module config/schemas/services
- * Service configuration schemas: embedding and vector store.
- */
-/**
- * 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).'),
-});
-
-/**
- * @module config/schemas/root
- * Root configuration schema combining all sub-schemas.
- */
-/**
- * Top-level configuration for jeeves-watcher.
- */
-const jeevesWatcherConfigSchema = z.object({
-    /** Optional description of this watcher deployment's organizational strategy. */
-    description: z
-        .string()
-        .optional()
-        .describe("Human-readable description of this deployment's organizational strategy and content domains."),
-    /** Global named schema collection. */
-    schemas: z
-        .record(z.string(), schemaEntrySchema)
-        .optional()
-        .describe('Global named schema definitions (inline objects or file paths) referenced by inference rules.'),
-    /** File system watch configuration. */
-    watch: watchConfigSchema.describe('File system watch configuration.'),
-    /** Configuration file watch settings. */
-    configWatch: configWatchConfigSchema
-        .optional()
-        .describe('Configuration file watch settings.'),
-    /** Embedding model configuration. */
-    embedding: embeddingConfigSchema.describe('Embedding model configuration.'),
-    /** Vector store configuration. */
-    vectorStore: vectorStoreConfigSchema.describe('Qdrant vector store configuration.'),
-    /** API server configuration. */
-    api: apiConfigSchema.optional().describe('API server configuration.'),
-    /** Directory for persistent state files (issues.json, values.json, enrichments.sqlite). */
-    stateDir: z
-        .string()
-        .optional()
-        .describe('Directory for persistent state files (issues.json, values.json, enrichments.sqlite). Defaults to .jeeves-metadata.'),
-    /** Rules for inferring metadata from document properties (inline objects or file paths). */
-    inferenceRules: z
-        .array(z.union([inferenceRuleSchema, z.string()]))
-        .optional()
-        .describe('Rules for inferring metadata from file attributes. Each entry may be an inline rule object or a file path to a JSON rule file (resolved relative to config directory).'),
-    /** Reusable named JsonMap transformations (inline objects or .json file paths). */
-    maps: z
-        .record(z.string(), z.union([
-        jsonMapMapSchema,
-        z.string(),
-        z.object({
-            /** The JsonMap definition (inline object or file path). */
-            map: jsonMapMapSchema.or(z.string()),
-            /** Optional human-readable description of this map. */
-            description: z.string().optional(),
-        }),
-    ]))
-        .optional()
-        .describe('Reusable named JsonMap transformations (inline definition or .json file path resolved relative to config directory).'),
-    /** Reusable named Handlebars templates (inline strings or .hbs/.handlebars file paths). */
-    templates: z
-        .record(z.string(), z.union([
-        z.string(),
-        z.object({
-            /** The Handlebars template source (inline string or file path). */
-            template: z.string(),
-            /** Optional human-readable description of this template. */
-            description: z.string().optional(),
-        }),
-    ]))
-        .optional()
-        .describe('Named reusable Handlebars templates (inline strings or .hbs/.handlebars file paths).'),
-    /** Custom Handlebars helper registration. */
-    templateHelpers: z
-        .record(z.string(), z.object({
-        /** File path to the helper module (resolved relative to config directory). */
-        path: z.string(),
-        /** Optional human-readable description of this helper. */
-        description: z.string().optional(),
-    }))
-        .optional()
-        .describe('Custom Handlebars helper registration.'),
-    /** Custom JsonMap lib function registration. */
-    mapHelpers: z
-        .record(z.string(), z.object({
-        /** File path to the helper module (resolved relative to config directory). */
-        path: z.string(),
-        /** Optional human-readable description of this helper. */
-        description: z.string().optional(),
-    }))
-        .optional()
-        .describe('Custom JsonMap lib function registration.'),
-    /** Reindex configuration. */
-    reindex: z
-        .object({
-        /** URL to call when reindex completes. */
-        callbackUrl: z.url().optional(),
-        /** Maximum concurrent file operations during reindex. */
-        concurrency: z
-            .number()
-            .int()
-            .min(1)
-            .default(50)
-            .describe('Maximum concurrent file operations during reindex (default 50).'),
-    })
-        .optional()
-        .describe('Reindex configuration.'),
-    /** Named Qdrant filter patterns for skill-activated behaviors. */
-    /** Search configuration including score thresholds and hybrid search. */
-    search: z
-        .object({
-        /** Score thresholds for categorizing search result quality. */
-        scoreThresholds: z
-            .object({
-            /** Minimum score for a result to be considered a strong match. */
-            strong: z.number().min(-1).max(1),
-            /** Minimum score for a result to be considered relevant. */
-            relevant: z.number().min(-1).max(1),
-            /** Maximum score below which results are considered noise. */
-            noise: z.number().min(-1).max(1),
-        })
-            .optional(),
-        /** Hybrid search configuration combining vector and full-text search. */
-        hybrid: z
-            .object({
-            /** Enable hybrid search with RRF fusion. Default: false. */
-            enabled: z.boolean().default(false),
-            /** Weight for text (BM25) results in RRF fusion. Default: 0.3. */
-            textWeight: z.number().min(0).max(1).default(0.3),
-        })
-            .optional(),
-    })
-        .optional()
-        .describe('Search configuration including score thresholds and hybrid search.'),
-    /** Logging configuration. */
-    logging: loggingConfigSchema.optional().describe('Logging configuration.'),
-    /** Timeout in milliseconds for graceful shutdown. */
-    shutdownTimeoutMs: z
-        .number()
-        .optional()
-        .describe('Timeout in milliseconds for graceful shutdown.'),
-    /** Maximum consecutive system-level failures before triggering fatal error. Default: Infinity. */
-    maxRetries: z
-        .number()
-        .optional()
-        .describe('Maximum consecutive system-level failures before triggering fatal error. Default: Infinity.'),
-    /** Maximum backoff delay in milliseconds for system errors. Default: 60000. */
-    maxBackoffMs: z
-        .number()
-        .optional()
-        .describe('Maximum backoff delay in milliseconds for system errors. Default: 60000.'),
-});
-
-/**
- * @module api/handlers/configMerge
- * Shared config merge utilities.
- */
-/**
- * Merge inference rules by name: submitted rules replace existing by name, new ones are appended.
- */
-function mergeInferenceRules(existing, incoming) {
-    if (!incoming)
-        return existing ?? [];
-    if (!existing)
-        return incoming;
-    const merged = [...existing];
-    for (const rule of incoming) {
-        const name = rule['name'];
-        if (!name) {
-            merged.push(rule);
-            continue;
-        }
-        const idx = merged.findIndex((r) => r['name'] === name);
-        if (idx >= 0) {
-            merged[idx] = rule;
-        }
-        else {
-            merged.push(rule);
-        }
-    }
-    return merged;
-}
-
-/**
- * @module api/handlers/mergeAndValidate
- * Shared config merge and validation logic used by both validate and apply handlers.
- */
-/**
- * Merge a submitted partial config into the current config and validate against schema.
- *
- * @param currentConfig - The current running config.
- * @param submittedPartial - The partial config to merge in.
- * @returns The merge/validation result.
- */
-function mergeAndValidateConfig(currentConfig, submittedPartial) {
-    let candidateRaw = {
-        ...currentConfig,
-    };
-    if (submittedPartial) {
-        const mergedRules = mergeInferenceRules(candidateRaw['inferenceRules'], submittedPartial['inferenceRules']);
-        candidateRaw = {
-            ...candidateRaw,
-            ...submittedPartial,
-            inferenceRules: mergedRules,
-        };
-    }
-    const parseResult = jeevesWatcherConfigSchema.safeParse(candidateRaw);
-    const errors = [];
-    if (!parseResult.success) {
-        for (const issue of parseResult.error.issues) {
-            errors.push({
-                path: issue.path.join('.'),
-                message: issue.message,
-            });
-        }
-        return { candidateRaw, errors };
-    }
-    // Note: When accepting external config via API, string rule references are NOT resolved
-    // (no configDir context). API-submitted rules must always be inline objects.
-    // The cast is safe because API config never contains string rule refs.
-    return {
-        candidateRaw,
-        parsed: parseResult.data,
-        errors,
-    };
-}
-
-/**
- * @module api/handlers/wrapHandler
- * Generic error-handling wrapper for Fastify route handlers.
- */
-/**
- * Wrap a Fastify route handler with standardised error handling.
- *
- * @param fn - The handler function.
- * @param logger - Logger instance.
- * @param label - Label for error log messages.
- * @returns A wrapped handler that catches errors and returns 500.
+ * Wrap a Fastify route handler with standardised error handling.
+ *
+ * @param fn - The handler function.
+ * @param logger - Logger instance.
+ * @param label - Label for error log messages.
+ * @returns A wrapped handler that catches errors and returns 500.
  */
 function wrapHandler(fn, logger, label) {
     return async (request, reply) => {
@@ -1565,467 +1121,809 @@ function wrapHandler(fn, logger, label) {
 }
 
 /**
- * @module api/handlers/configApply
- * Fastify route handler for POST /config/apply. Validates and writes config, optionally triggering reindex.
+ * @module api/handlers/configMatch
+ * Tests file paths against inference rules and watch scope.
  */
 /**
- * Create handler for POST /config/apply.
+ * Factory for POST /config/match handler.
  *
- * @param deps - Route dependencies.
+ * @param options - Handler options.
+ * @returns The handler function.
  */
-function createConfigApplyHandler(deps) {
-    return wrapHandler(async (request, reply) => {
-        const { config: submittedConfig } = request.body;
-        const config = deps.getConfig();
-        const { candidateRaw, errors } = mergeAndValidateConfig(config, submittedConfig);
-        if (errors.length > 0) {
-            return await reply.status(400).send({ valid: false, errors });
+function createConfigMatchHandler(options) {
+    const { getConfig, logger } = options;
+    // Cache compiled artifacts per config reference — recompute only on hot-reload.
+    let cachedConfig;
+    let compiledRules = [];
+    let watchMatcher;
+    let ignoreMatcher;
+    const handler = async (req, res) => {
+        const body = req.body;
+        if (!Array.isArray(body.paths)) {
+            res.code(400).send({ error: 'Request body must include "paths" array' });
+            return;
         }
-        await writeFile(deps.configPath, JSON.stringify(candidateRaw, null, 2), 'utf-8');
-        const reindexScope = config.configWatch?.reindex ?? 'issues';
-        if (deps.triggerReindex) {
-            deps.triggerReindex(reindexScope);
+        const config = getConfig();
+        if (config !== cachedConfig) {
+            compiledRules = compileRules(config.inferenceRules ?? []);
+            watchMatcher = picomatch(config.watch.paths, { dot: true });
+            ignoreMatcher = config.watch.ignored?.length
+                ? picomatch(config.watch.ignored, { dot: true })
+                : undefined;
+            cachedConfig = config;
         }
-        return {
-            applied: true,
-            reindexTriggered: !!deps.triggerReindex,
-            scope: reindexScope,
-        };
-    }, deps.logger, 'Config apply');
+        const matches = body.paths.map((path) => {
+            const attrs = buildSyntheticAttributes(path);
+            const matchingRules = [];
+            for (const compiled of compiledRules) {
+                if (compiled.validate(attrs)) {
+                    matchingRules.push(compiled.rule.name);
+                }
+            }
+            const normalised = attrs.file.path;
+            const watched = (watchMatcher?.(normalised) ?? false) &&
+                !(ignoreMatcher?.(normalised) ?? false);
+            return { rules: matchingRules, watched };
+        });
+        const response = { matches };
+        res.send(response);
+    };
+    return wrapHandler(handler, logger, 'Config match');
 }
 
 /**
- * @module rules/attributes
- * Builds file attribute objects for rule matching. Pure function: derives attributes from path, stats, and extracted data.
+ * @module api/mergedDocument
+ * Builds a merged virtual document from config, values, and issues for JSONPath querying.
  */
 /**
- * Build {@link FileAttributes} from a file path and stat info.
+ * Build a helper section for the merged document, injecting introspection exports per namespace.
+ */
+function buildHelperSection(configHelpers, legacyExports, introspection) {
+    if (!configHelpers)
+        return {};
+    const result = {};
+    for (const [name, entry] of Object.entries(configHelpers)) {
+        result[name] = {
+            ...entry,
+            ...(introspection?.[name]?.exports
+                ? { exports: introspection[name].exports }
+                : {}),
+        };
+    }
+    if (legacyExports) {
+        result['_exports'] = legacyExports;
+    }
+    return result;
+}
+/**
+ * Safely read and parse a file reference. Returns the original string on failure.
+ */
+function readFileReference(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        if (filePath.endsWith('.json')) {
+            return JSON.parse(content);
+        }
+        return content;
+    }
+    catch {
+        return filePath;
+    }
+}
+/**
+ * Build a merged virtual document combining config, values, and issues.
  *
- * @param filePath - The file path.
- * @param stats - The file stats.
- * @param extractedFrontmatter - Optional extracted frontmatter.
- * @param extractedJson - Optional parsed JSON content.
- * @returns The constructed file attributes.
+ * @param options - The build options.
+ * @returns The merged document object.
  */
-function buildAttributes(filePath, stats, extractedFrontmatter, extractedJson) {
-    const normalised = normalizeSlashes(filePath);
-    const attrs = {
-        file: {
-            path: normalised,
-            directory: normalizeSlashes(dirname(normalised)),
-            filename: basename(normalised),
-            extension: extname(normalised),
-            sizeBytes: stats.size,
-            modified: stats.mtime.toISOString(),
-        },
+function buildMergedDocument(options) {
+    const { config, valuesManager, issuesManager, helperExports, helperIntrospection, virtualRules, } = options;
+    // Merge config rules (source: 'config') and virtual rules (source: registration key)
+    const configRules = (config.inferenceRules ?? []).map((rule) => ({
+        ...rule,
+        source: 'config',
+        values: valuesManager.getForRule(rule.name),
+    }));
+    const virtualRuleEntries = [];
+    if (virtualRules) {
+        for (const [source, rules] of Object.entries(virtualRules)) {
+            for (const rule of rules) {
+                const name = typeof rule.name === 'string' ? rule.name : undefined;
+                virtualRuleEntries.push({
+                    ...rule,
+                    source,
+                    values: name ? valuesManager.getForRule(name) : {},
+                });
+            }
+        }
+    }
+    const inferenceRules = [...configRules, ...virtualRuleEntries];
+    const doc = {
+        description: config['description'] ?? '',
+        watch: config.watch,
+        configWatch: config.configWatch ?? {},
+        search: config.search ?? {},
+        schemas: config.schemas ?? {},
+        inferenceRules,
+        mapHelpers: buildHelperSection(config.mapHelpers, helperExports?.mapHelpers, helperIntrospection?.mapHelpers),
+        templateHelpers: buildHelperSection(config.templateHelpers, helperExports?.templateHelpers, helperIntrospection?.templateHelpers),
+        maps: config.maps ?? {},
+        templates: config.templates ?? {},
+        issues: issuesManager.getAll(),
     };
-    if (extractedFrontmatter)
-        attrs.frontmatter = extractedFrontmatter;
-    if (extractedJson)
-        attrs.json = extractedJson;
-    return attrs;
+    // Always resolve file references
+    return resolveReferences(doc, ['files', 'globals']);
 }
 /**
- * Build synthetic file attributes from a path string (no actual file I/O).
- * Used by API handlers that need to match rules against paths without reading files.
+ * Resolve file references in known config reference positions only.
  *
- * @param filePath - The file path.
- * @returns Synthetic file attributes with zeroed stats.
+ * Resolves strings in:
+ * - `inferenceRules[*].map` when ending in `.json` (if 'files' in resolveTypes)
+ * - `maps[*]` when a string (file path) (if 'files' in resolveTypes)
+ * - `templates[*]` when a string (file path) (if 'files' in resolveTypes)
+ * - `inferenceRules[*].schema` named references (if 'globals' in resolveTypes)
+ *
+ * @param doc - The document to resolve.
+ * @param resolveTypes - Which resolution types to apply.
+ * @returns The resolved document.
+ */
+function resolveReferences(doc, resolveTypes) {
+    const resolved = { ...doc };
+    // Resolve inferenceRules[*] references
+    if (Array.isArray(resolved['inferenceRules'])) {
+        resolved['inferenceRules'] = resolved['inferenceRules'].map((rule) => {
+            let updatedRule = { ...rule };
+            // Resolve map file references (if 'files' requested)
+            if (resolveTypes.includes('files') &&
+                typeof rule['map'] === 'string' &&
+                rule['map'].endsWith('.json')) {
+                updatedRule = { ...updatedRule, map: readFileReference(rule['map']) };
+            }
+            // Resolve schema named references (if 'globals' requested)
+            if (resolveTypes.includes('globals') &&
+                Array.isArray(rule['schema']) &&
+                typeof resolved['schemas'] === 'object') {
+                const globalSchemas = resolved['schemas'];
+                const expandedSchemas = rule['schema'].map((ref) => {
+                    if (typeof ref === 'string' && globalSchemas[ref]) {
+                        return globalSchemas[ref];
+                    }
+                    return ref;
+                });
+                updatedRule = { ...updatedRule, schema: expandedSchemas };
+            }
+            return updatedRule;
+        });
+    }
+    // Resolve maps[*] file references (if 'files' requested)
+    if (resolveTypes.includes('files') &&
+        resolved['maps'] &&
+        typeof resolved['maps'] === 'object') {
+        const maps = { ...resolved['maps'] };
+        for (const [key, value] of Object.entries(maps)) {
+            if (typeof value === 'string') {
+                maps[key] = readFileReference(value);
+            }
+        }
+        resolved['maps'] = maps;
+    }
+    // Resolve templates[*] file references (if 'files' requested)
+    if (resolveTypes.includes('files') &&
+        resolved['templates'] &&
+        typeof resolved['templates'] === 'object') {
+        const templates = {
+            ...resolved['templates'],
+        };
+        for (const [key, value] of Object.entries(templates)) {
+            if (typeof value === 'string') {
+                templates[key] = readFileReference(value);
+            }
+        }
+        resolved['templates'] = templates;
+    }
+    return resolved;
+}
+
+/**
+ * @module api/handlers/configQuery
+ * Fastify route handler for GET /config. Returns the full resolved merged document,
+ * optionally filtered by JSONPath via the `path` query parameter.
+ *
+ * Delegates JSON querying to `createConfigQueryHandler` from `@karmaniverous/jeeves` core.
+ */
+/**
+ * Create handler for GET /config.
+ *
+ * Uses `createConfigQueryHandler` from core to handle JSONPath querying.
+ * Invalid JSONPath expressions are client errors and return 400.
+ *
+ * @param deps - Route dependencies.
  */
-function buildSyntheticAttributes(filePath) {
-    const normalised = normalizeSlashes(filePath);
-    return {
-        file: {
-            path: normalised,
-            directory: normalizeSlashes(dirname(normalised)),
-            filename: basename(normalised),
-            extension: extname(normalised),
-            sizeBytes: 0,
-            modified: new Date(0).toISOString(),
-        },
+function createConfigQueryHandler(deps) {
+    const coreHandler = createConfigQueryHandler$1(() => buildMergedDocument({
+        config: deps.getConfig(),
+        valuesManager: deps.valuesManager,
+        issuesManager: deps.issuesManager,
+        helperIntrospection: deps.helperIntrospection,
+        virtualRules: deps.getVirtualRules?.(),
+    }));
+    return async (request, reply) => {
+        try {
+            const { path } = request.query;
+            const result = await coreHandler({ path });
+            if (result.status >= 400) {
+                return await reply.status(result.status).send(result.body);
+            }
+            return result.body;
+        }
+        catch (error) {
+            const err = normalizeError(error);
+            deps.logger.error({ err }, 'Config query failed');
+            return await reply.status(400).send({
+                error: err.message || 'Query failed',
+            });
+        }
     };
 }
 
 /**
- * @module rules/ajvSetup
- * AJV instance factory with custom glob keyword for picomatch-based pattern matching in rule schemas.
+ * @module api/handlers/configReindex
+ * Fastify route handler for POST /reindex. Triggers an async reindex job scoped to issues, full, rules, path, or prune processing.
  */
 /**
- * Create an AJV instance with a custom `glob` format for picomatch glob matching.
+ * Create handler for POST /reindex.
  *
- * @returns The configured AJV instance.
+ * @param deps - Route dependencies.
  */
-function createRuleAjv() {
-    const ajv = new Ajv({ allErrors: true, strict: false });
-    addFormats(ajv);
-    ajv.addKeyword({
-        keyword: 'glob',
-        type: 'string',
-        schemaType: 'string',
-        validate: (pattern, data) => picomatch.isMatch(data, pattern, { dot: true, nocase: true }),
-    });
-    return ajv;
+function createConfigReindexHandler(deps) {
+    return wrapHandler(async (request, reply) => {
+        const scope = request.body.scope ?? 'issues';
+        const dryRun = request.body.dryRun ?? false;
+        if (!VALID_REINDEX_SCOPES.includes(scope)) {
+            return await reply.status(400).send({
+                error: 'Invalid scope',
+                message: `Scope must be one of: ${VALID_REINDEX_SCOPES.join(', ')}. Got: "${scope}"`,
+            });
+        }
+        const validScope = scope;
+        if (validScope === 'path') {
+            const { path } = request.body;
+            if (!path || (Array.isArray(path) && path.length === 0)) {
+                return await reply.status(400).send({
+                    error: 'Missing path',
+                    message: 'The "path" field is required when scope is "path".',
+                });
+            }
+        }
+        if (validScope === 'prune' && !deps.vectorStore) {
+            return await reply.status(400).send({
+                error: 'Not available',
+                message: 'Prune scope requires vectorStore to be configured.',
+            });
+        }
+        const reindexDeps = {
+            config: deps.getConfig(),
+            processor: deps.processor,
+            logger: deps.logger,
+            reindexTracker: deps.reindexTracker,
+            valuesManager: deps.valuesManager,
+            issuesManager: deps.issuesManager,
+            gitignoreFilter: deps.gitignoreFilter,
+            vectorStore: deps.vectorStore,
+            queue: deps.queue,
+        };
+        // Pass path for 'path' and 'rules' scopes
+        const pathParam = validScope === 'path' || validScope === 'rules'
+            ? request.body.path
+            : undefined;
+        if (dryRun) {
+            // Dry run: compute plan synchronously and return
+            const result = await executeReindex(reindexDeps, validScope, pathParam, true);
+            return await reply.status(200).send({
+                status: 'dry_run',
+                scope,
+                plan: result.plan,
+            });
+        }
+        // Fire and forget — plan is computed inside but we need it for the response.
+        // For non-prune scopes, compute plan first then execute async.
+        const planResult = await executeReindex(reindexDeps, validScope, pathParam, true);
+        // Now fire actual reindex async
+        void executeReindex(reindexDeps, validScope, pathParam, false);
+        return await reply
+            .status(200)
+            .send({ status: 'started', scope, plan: planResult.plan });
+    }, deps.logger, 'Reindex request');
 }
 
 /**
- * @module rules/compile
- * Compiles inference rule definitions into executable AJV validators for efficient rule evaluation.
+ * @module config/schemas/base
+ * Base configuration schemas: watch, logging, API.
  */
 /**
- * Validate that all rule names are unique.
- * Throws if duplicate names are found.
- *
- * @param rules - The inference rule definitions.
+ * Watch configuration for file system monitoring.
  */
-function validateRuleNameUniqueness(rules) {
-    const names = new Set();
-    const duplicates = [];
-    for (const rule of rules) {
-        if (names.has(rule.name)) {
-            duplicates.push(rule.name);
-        }
-        else {
-            names.add(rule.name);
-        }
-    }
-    if (duplicates.length > 0) {
-        throw new Error(`Duplicate inference rule names found: ${duplicates.join(', ')}. Rule names must be unique.`);
-    }
-}
+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.'),
+    /** Move detection configuration for correlating unlink+add as file moves. */
+    moveDetection: z
+        .object({
+        /** Enable move correlation. Default: true. */
+        enabled: z
+            .boolean()
+            .default(true)
+            .describe('Enable move detection via content hash correlation.'),
+        /** Buffer time in ms for holding unlink events before treating as deletes. Default: 2000. */
+        bufferMs: z
+            .number()
+            .int()
+            .min(100)
+            .default(2000)
+            .describe('How long (ms) to buffer unlink events before treating as deletes.'),
+    })
+        .optional()
+        .describe('Move detection: correlate unlink+add events as file moves to avoid re-embedding.'),
+});
 /**
- * Compile an array of inference rules into executable validators.
- * Validates rule name uniqueness before compilation.
- *
- * @param rules - The inference rule definitions.
- * @returns An array of compiled rules.
+ * Configuration watch settings.
  */
-function compileRules(rules) {
-    validateRuleNameUniqueness(rules);
-    const ajv = createRuleAjv();
-    return rules.map((rule) => ({
-        rule,
-        validate: ajv.compile({
-            $id: rule.name,
-            ...rule.match,
-        }),
-    }));
-}
+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.'),
+    /** Reindex scope triggered on config change. */
+    reindex: z
+        .union([
+        z
+            .literal('issues')
+            .describe('Re-process only files with recorded issues.'),
+        z.literal('full').describe('Full reindex of all watched files.'),
+        z
+            .literal('rules')
+            .describe('Re-apply inference rules to existing points without re-embedding.'),
+    ])
+        .optional()
+        .describe('Reindex scope triggered on config change. Default: issues.'),
+});
+/**
+ * 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., 1936).'),
+    /** Read endpoint cache TTL in milliseconds. */
+    cacheTtlMs: z
+        .number()
+        .optional()
+        .describe('TTL in milliseconds for caching read-heavy endpoints (e.g., /status, /config). Default: 30000.'),
+});
+/**
+ * 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
+        .string()
+        .optional()
+        .describe('Path to log file (logs to stdout if omitted).'),
+});
 
 /**
- * @module api/handlers/configMatch
- * Tests file paths against inference rules and watch scope.
- */
-/**
- * Factory for POST /config/match handler.
- *
- * @param options - Handler options.
- * @returns The handler function.
+ * @module config/schemas/inference
+ * Inference rule and schema configuration schemas.
  */
-function createConfigMatchHandler(options) {
-    const { getConfig, logger } = options;
-    // Cache compiled artifacts per config reference — recompute only on hot-reload.
-    let cachedConfig;
-    let compiledRules = [];
-    let watchMatcher;
-    let ignoreMatcher;
-    const handler = async (req, res) => {
-        const body = req.body;
-        if (!Array.isArray(body.paths)) {
-            res.code(400).send({ error: 'Request body must include "paths" array' });
-            return;
-        }
-        const config = getConfig();
-        if (config !== cachedConfig) {
-            compiledRules = compileRules(config.inferenceRules ?? []);
-            watchMatcher = picomatch(config.watch.paths, { dot: true });
-            ignoreMatcher = config.watch.ignored?.length
-                ? picomatch(config.watch.ignored, { dot: true })
-                : undefined;
-            cachedConfig = config;
-        }
-        const matches = body.paths.map((path) => {
-            const attrs = buildSyntheticAttributes(path);
-            const matchingRules = [];
-            for (const compiled of compiledRules) {
-                if (compiled.validate(attrs)) {
-                    matchingRules.push(compiled.rule.name);
-                }
-            }
-            const normalised = attrs.file.path;
-            const watched = (watchMatcher?.(normalised) ?? false) &&
-                !(ignoreMatcher?.(normalised) ?? false);
-            return { rules: matchingRules, watched };
-        });
-        const response = { matches };
-        res.send(response);
-    };
-    return wrapHandler(handler, logger, 'Config match');
-}
-
 /**
- * @module api/mergedDocument
- * Builds a merged virtual document from config, values, and issues for JSONPath querying.
+ * A JSON Schema property definition with optional custom keywords.
+ * Supports standard JSON Schema keywords plus custom `set` and `uiHint`.
  */
+const propertySchemaSchema = z.record(z.string(), z.unknown());
 /**
- * Build a helper section for the merged document, injecting introspection exports per namespace.
+ * A schema object: properties with JSON Schema definitions.
  */
-function buildHelperSection(configHelpers, legacyExports, introspection) {
-    if (!configHelpers)
-        return {};
-    const result = {};
-    for (const [name, entry] of Object.entries(configHelpers)) {
-        result[name] = {
-            ...entry,
-            ...(introspection?.[name]?.exports
-                ? { exports: introspection[name].exports }
-                : {}),
-        };
-    }
-    if (legacyExports) {
-        result['_exports'] = legacyExports;
-    }
-    return result;
-}
+const schemaObjectSchema = z.object({
+    type: z
+        .literal('object')
+        .optional()
+        .describe('JSON Schema type (always "object" for schema definitions).'),
+    properties: z
+        .record(z.string(), propertySchemaSchema)
+        .optional()
+        .describe('Map of property names to JSON Schema property definitions.'),
+});
 /**
- * Safely read and parse a file reference. Returns the original string on failure.
+ * Global schema entry: inline object or file path.
  */
-function readFileReference(filePath) {
-    try {
-        const content = readFileSync(filePath, 'utf-8');
-        if (filePath.endsWith('.json')) {
-            return JSON.parse(content);
-        }
-        return content;
-    }
-    catch {
-        return filePath;
-    }
-}
+const schemaEntrySchema = z.union([
+    schemaObjectSchema,
+    z.string().describe('File path to a JSON schema file.'),
+]);
 /**
- * Build a merged virtual document combining config, values, and issues.
- *
- * @param options - The build options.
- * @returns The merged document object.
+ * Schema reference: either a named schema reference (string) or an inline schema object.
  */
-function buildMergedDocument(options) {
-    const { config, valuesManager, issuesManager, helperExports, helperIntrospection, virtualRules, } = options;
-    // Merge config rules (source: 'config') and virtual rules (source: registration key)
-    const configRules = (config.inferenceRules ?? []).map((rule) => ({
-        ...rule,
-        source: 'config',
-        values: valuesManager.getForRule(rule.name),
-    }));
-    const virtualRuleEntries = [];
-    if (virtualRules) {
-        for (const [source, rules] of Object.entries(virtualRules)) {
-            for (const rule of rules) {
-                const name = typeof rule.name === 'string' ? rule.name : undefined;
-                virtualRuleEntries.push({
-                    ...rule,
-                    source,
-                    values: name ? valuesManager.getForRule(name) : {},
-                });
-            }
-        }
-    }
-    const inferenceRules = [...configRules, ...virtualRuleEntries];
-    const doc = {
-        description: config['description'] ?? '',
-        watch: config.watch,
-        configWatch: config.configWatch ?? {},
-        search: config.search ?? {},
-        schemas: config.schemas ?? {},
-        inferenceRules,
-        mapHelpers: buildHelperSection(config.mapHelpers, helperExports?.mapHelpers, helperIntrospection?.mapHelpers),
-        templateHelpers: buildHelperSection(config.templateHelpers, helperExports?.templateHelpers, helperIntrospection?.templateHelpers),
-        maps: config.maps ?? {},
-        templates: config.templates ?? {},
-        issues: issuesManager.getAll(),
-    };
-    // Always resolve file references
-    return resolveReferences(doc, ['files', 'globals']);
-}
+const schemaReferenceSchema = z.union([
+    z.string().describe('Named reference to a global schema.'),
+    schemaObjectSchema,
+]);
+/** Render body section. */
+const renderBodySectionSchema = z.object({
+    /** Key path in the template context to render. */
+    path: z.string().min(1).describe('Key path in template context to render.'),
+    /** Markdown heading level for this section (1-6). */
+    heading: z.number().min(1).max(6).describe('Markdown heading level (1-6).'),
+    /** Override heading text (default: titlecased path). */
+    label: z.string().optional().describe('Override heading text.'),
+    /** Name of a registered Handlebars helper used as a format handler. */
+    format: z
+        .string()
+        .optional()
+        .describe('Name of a registered Handlebars helper used as a format handler.'),
+    /** Additional args passed to the format helper. */
+    formatArgs: z
+        .array(z.unknown())
+        .optional()
+        .describe('Additional args passed to the format helper.'),
+    /** If true, the value at path is treated as an array and iterated. */
+    each: z
+        .boolean()
+        .optional()
+        .describe('If true, the value at path is treated as an array and iterated.'),
+    /** Handlebars template string for per-item heading text (used when each=true). */
+    headingTemplate: z
+        .string()
+        .optional()
+        .describe('Handlebars template string for per-item heading text (used when each=true).'),
+    /** Key path within each item to use as renderable content (used when each=true). */
+    contentPath: z
+        .string()
+        .optional()
+        .describe('Key path within each item to use as renderable content (used when each=true).'),
+    /** Key path within each item to sort by (used when each=true). */
+    sort: z
+        .string()
+        .optional()
+        .describe('Key path within each item to sort by (used when each=true).'),
+});
+/** Render config: YAML frontmatter + ordered body sections. */
+const renderConfigSchema = z.object({
+    /** Keys or glob patterns to extract from context and include as YAML frontmatter. */
+    frontmatter: z
+        .array(z.string().min(1))
+        .describe('Keys or glob patterns to include as YAML frontmatter. ' +
+        'Supports picomatch globs (e.g. "*") and "!"-prefixed exclusion patterns (e.g. "!_*"). ' +
+        'Explicit names preserve declaration order; glob-matched keys are sorted alphabetically.'),
+    /** Ordered markdown body sections. */
+    body: z
+        .array(renderBodySectionSchema)
+        .describe('Ordered markdown body sections.'),
+});
 /**
- * Resolve file references in known config reference positions only.
- *
- * Resolves strings in:
- * - `inferenceRules[*].map` when ending in `.json` (if 'files' in resolveTypes)
- * - `maps[*]` when a string (file path) (if 'files' in resolveTypes)
- * - `templates[*]` when a string (file path) (if 'files' in resolveTypes)
- * - `inferenceRules[*].schema` named references (if 'globals' in resolveTypes)
- *
- * @param doc - The document to resolve.
- * @param resolveTypes - Which resolution types to apply.
- * @returns The resolved document.
+ * An inference rule that enriches document metadata.
  */
-function resolveReferences(doc, resolveTypes) {
-    const resolved = { ...doc };
-    // Resolve inferenceRules[*] references
-    if (Array.isArray(resolved['inferenceRules'])) {
-        resolved['inferenceRules'] = resolved['inferenceRules'].map((rule) => {
-            let updatedRule = { ...rule };
-            // Resolve map file references (if 'files' requested)
-            if (resolveTypes.includes('files') &&
-                typeof rule['map'] === 'string' &&
-                rule['map'].endsWith('.json')) {
-                updatedRule = { ...updatedRule, map: readFileReference(rule['map']) };
-            }
-            // Resolve schema named references (if 'globals' requested)
-            if (resolveTypes.includes('globals') &&
-                Array.isArray(rule['schema']) &&
-                typeof resolved['schemas'] === 'object') {
-                const globalSchemas = resolved['schemas'];
-                const expandedSchemas = rule['schema'].map((ref) => {
-                    if (typeof ref === 'string' && globalSchemas[ref]) {
-                        return globalSchemas[ref];
-                    }
-                    return ref;
-                });
-                updatedRule = { ...updatedRule, schema: expandedSchemas };
-            }
-            return updatedRule;
+const inferenceRuleSchema = z
+    .object({
+    /** Unique name for this inference rule. */
+    name: z
+        .string()
+        .min(1)
+        .describe('Unique name identifying this inference rule.'),
+    /** Human-readable description of what this rule does. */
+    description: z
+        .string()
+        .min(1)
+        .describe('Human-readable description of what this rule does.'),
+    /** JSON Schema object to match against document metadata. */
+    match: z
+        .record(z.string(), z.unknown())
+        .describe('JSON Schema object to match against file attributes.'),
+    /** Array of schema references to merge (named refs and/or inline objects). */
+    schema: z
+        .array(schemaReferenceSchema)
+        .optional()
+        .describe('Array of schema references (named schema refs or inline objects) merged left-to-right.'),
+    /** JsonMap transformation (inline or reference to named map). */
+    map: z
+        .union([jsonMapMapSchema, z.string()])
+        .optional()
+        .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).'),
+    /** Declarative structured renderer configuration (mutually exclusive with template). */
+    render: renderConfigSchema
+        .optional()
+        .describe('Declarative render configuration for frontmatter + structured Markdown output (mutually exclusive with template).'),
+    /** Output file extension override (e.g. "md", "html", "txt"). Requires template or render. */
+    renderAs: z
+        .string()
+        .regex(/^[a-z0-9]{1,10}$/, 'renderAs must be 1-10 lowercase alphanumeric characters')
+        .optional()
+        .describe('Output file extension override (without dot). Requires template or render.'),
+})
+    .superRefine((val, ctx) => {
+    if (val.render && val.template) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['render'],
+            message: 'render is mutually exclusive with template',
         });
     }
-    // Resolve maps[*] file references (if 'files' requested)
-    if (resolveTypes.includes('files') &&
-        resolved['maps'] &&
-        typeof resolved['maps'] === 'object') {
-        const maps = { ...resolved['maps'] };
-        for (const [key, value] of Object.entries(maps)) {
-            if (typeof value === 'string') {
-                maps[key] = readFileReference(value);
-            }
-        }
-        resolved['maps'] = maps;
-    }
-    // Resolve templates[*] file references (if 'files' requested)
-    if (resolveTypes.includes('files') &&
-        resolved['templates'] &&
-        typeof resolved['templates'] === 'object') {
-        const templates = {
-            ...resolved['templates'],
-        };
-        for (const [key, value] of Object.entries(templates)) {
-            if (typeof value === 'string') {
-                templates[key] = readFileReference(value);
-            }
-        }
-        resolved['templates'] = templates;
+    if (val.renderAs && !val.template && !val.render) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['renderAs'],
+            message: 'renderAs requires template or render',
+        });
     }
-    return resolved;
-}
+});
 
 /**
- * @module api/handlers/configQuery
- * Fastify route handler for GET /config. Returns the full resolved merged document,
- * optionally filtered by JSONPath via the `path` query parameter.
- *
- * Delegates JSON querying to `createConfigQueryHandler` from `@karmaniverous/jeeves` core.
+ * @module config/schemas/services
+ * Service configuration schemas: embedding and vector store.
  */
 /**
- * Create handler for GET /config.
- *
- * Uses `createConfigQueryHandler` from core to handle JSONPath querying.
- * Invalid JSONPath expressions are client errors and return 400.
- *
- * @param deps - Route dependencies.
+ * Embedding model configuration.
  */
-function createConfigQueryHandler(deps) {
-    const coreHandler = createConfigQueryHandler$1(() => buildMergedDocument({
-        config: deps.getConfig(),
-        valuesManager: deps.valuesManager,
-        issuesManager: deps.issuesManager,
-        helperIntrospection: deps.helperIntrospection,
-        virtualRules: deps.getVirtualRules?.(),
-    }));
-    return async (request, reply) => {
-        try {
-            const { path } = request.query;
-            const result = await coreHandler({ path });
-            if (result.status >= 400) {
-                return await reply.status(result.status).send(result.body);
-            }
-            return result.body;
-        }
-        catch (error) {
-            const err = normalizeError(error);
-            deps.logger.error({ err }, 'Config query failed');
-            return await reply.status(400).send({
-                error: err.message || 'Query failed',
-            });
-        }
-    };
-}
+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).'),
+});
 
 /**
- * @module api/handlers/configReindex
- * Fastify route handler for POST /reindex. Triggers an async reindex job scoped to issues, full, rules, path, or prune processing.
+ * @module config/schemas/root
+ * Root configuration schema combining all sub-schemas.
  */
 /**
- * Create handler for POST /reindex.
- *
- * @param deps - Route dependencies.
+ * Top-level configuration for jeeves-watcher.
  */
-function createConfigReindexHandler(deps) {
-    return wrapHandler(async (request, reply) => {
-        const scope = request.body.scope ?? 'issues';
-        const dryRun = request.body.dryRun ?? false;
-        if (!VALID_REINDEX_SCOPES.includes(scope)) {
-            return await reply.status(400).send({
-                error: 'Invalid scope',
-                message: `Scope must be one of: ${VALID_REINDEX_SCOPES.join(', ')}. Got: "${scope}"`,
-            });
-        }
-        const validScope = scope;
-        if (validScope === 'path') {
-            const { path } = request.body;
-            if (!path || (Array.isArray(path) && path.length === 0)) {
-                return await reply.status(400).send({
-                    error: 'Missing path',
-                    message: 'The "path" field is required when scope is "path".',
-                });
-            }
-        }
-        if (validScope === 'prune' && !deps.vectorStore) {
-            return await reply.status(400).send({
-                error: 'Not available',
-                message: 'Prune scope requires vectorStore to be configured.',
-            });
-        }
-        const reindexDeps = {
-            config: deps.getConfig(),
-            processor: deps.processor,
-            logger: deps.logger,
-            reindexTracker: deps.reindexTracker,
-            valuesManager: deps.valuesManager,
-            issuesManager: deps.issuesManager,
-            gitignoreFilter: deps.gitignoreFilter,
-            vectorStore: deps.vectorStore,
-            queue: deps.queue,
-        };
-        // Pass path for 'path' and 'rules' scopes
-        const pathParam = validScope === 'path' || validScope === 'rules'
-            ? request.body.path
-            : undefined;
-        if (dryRun) {
-            // Dry run: compute plan synchronously and return
-            const result = await executeReindex(reindexDeps, validScope, pathParam, true);
-            return await reply.status(200).send({
-                status: 'dry_run',
-                scope,
-                plan: result.plan,
-            });
-        }
-        // Fire and forget — plan is computed inside but we need it for the response.
-        // For non-prune scopes, compute plan first then execute async.
-        const planResult = await executeReindex(reindexDeps, validScope, pathParam, true);
-        // Now fire actual reindex async
-        void executeReindex(reindexDeps, validScope, pathParam, false);
-        return await reply
-            .status(200)
-            .send({ status: 'started', scope, plan: planResult.plan });
-    }, deps.logger, 'Reindex request');
-}
+const jeevesWatcherConfigSchema = z.object({
+    /** Optional description of this watcher deployment's organizational strategy. */
+    description: z
+        .string()
+        .optional()
+        .describe("Human-readable description of this deployment's organizational strategy and content domains."),
+    /** Global named schema collection. */
+    schemas: z
+        .record(z.string(), schemaEntrySchema)
+        .optional()
+        .describe('Global named schema definitions (inline objects or file paths) referenced by inference rules.'),
+    /** File system watch configuration. */
+    watch: watchConfigSchema.describe('File system watch configuration.'),
+    /** Configuration file watch settings. */
+    configWatch: configWatchConfigSchema
+        .optional()
+        .describe('Configuration file watch settings.'),
+    /** Embedding model configuration. */
+    embedding: embeddingConfigSchema.describe('Embedding model configuration.'),
+    /** Vector store configuration. */
+    vectorStore: vectorStoreConfigSchema.describe('Qdrant vector store configuration.'),
+    /** API server configuration. */
+    api: apiConfigSchema.optional().describe('API server configuration.'),
+    /** Directory for persistent state files (issues.json, values.json, enrichments.sqlite). */
+    stateDir: z
+        .string()
+        .optional()
+        .describe('Directory for persistent state files (issues.json, values.json, enrichments.sqlite). Defaults to .jeeves-metadata.'),
+    /** Rules for inferring metadata from document properties (inline objects or file paths). */
+    inferenceRules: z
+        .array(z.union([inferenceRuleSchema, z.string()]))
+        .optional()
+        .describe('Rules for inferring metadata from file attributes. Each entry may be an inline rule object or a file path to a JSON rule file (resolved relative to config directory).'),
+    /** Reusable named JsonMap transformations (inline objects or .json file paths). */
+    maps: z
+        .record(z.string(), z.union([
+        jsonMapMapSchema,
+        z.string(),
+        z.object({
+            /** The JsonMap definition (inline object or file path). */
+            map: jsonMapMapSchema.or(z.string()),
+            /** Optional human-readable description of this map. */
+            description: z.string().optional(),
+        }),
+    ]))
+        .optional()
+        .describe('Reusable named JsonMap transformations (inline definition or .json file path resolved relative to config directory).'),
+    /** Reusable named Handlebars templates (inline strings or .hbs/.handlebars file paths). */
+    templates: z
+        .record(z.string(), z.union([
+        z.string(),
+        z.object({
+            /** The Handlebars template source (inline string or file path). */
+            template: z.string(),
+            /** Optional human-readable description of this template. */
+            description: z.string().optional(),
+        }),
+    ]))
+        .optional()
+        .describe('Named reusable Handlebars templates (inline strings or .hbs/.handlebars file paths).'),
+    /** Custom Handlebars helper registration. */
+    templateHelpers: z
+        .record(z.string(), z.object({
+        /** File path to the helper module (resolved relative to config directory). */
+        path: z.string(),
+        /** Optional human-readable description of this helper. */
+        description: z.string().optional(),
+    }))
+        .optional()
+        .describe('Custom Handlebars helper registration.'),
+    /** Custom JsonMap lib function registration. */
+    mapHelpers: z
+        .record(z.string(), z.object({
+        /** File path to the helper module (resolved relative to config directory). */
+        path: z.string(),
+        /** Optional human-readable description of this helper. */
+        description: z.string().optional(),
+    }))
+        .optional()
+        .describe('Custom JsonMap lib function registration.'),
+    /** Reindex configuration. */
+    reindex: z
+        .object({
+        /** URL to call when reindex completes. */
+        callbackUrl: z.url().optional(),
+        /** Maximum concurrent file operations during reindex. */
+        concurrency: z
+            .number()
+            .int()
+            .min(1)
+            .default(50)
+            .describe('Maximum concurrent file operations during reindex (default 50).'),
+    })
+        .optional()
+        .describe('Reindex configuration.'),
+    /** Named Qdrant filter patterns for skill-activated behaviors. */
+    /** Search configuration including score thresholds and hybrid search. */
+    search: z
+        .object({
+        /** Score thresholds for categorizing search result quality. */
+        scoreThresholds: z
+            .object({
+            /** Minimum score for a result to be considered a strong match. */
+            strong: z.number().min(-1).max(1),
+            /** Minimum score for a result to be considered relevant. */
+            relevant: z.number().min(-1).max(1),
+            /** Maximum score below which results are considered noise. */
+            noise: z.number().min(-1).max(1),
+        })
+            .optional(),
+        /** Hybrid search configuration combining vector and full-text search. */
+        hybrid: z
+            .object({
+            /** Enable hybrid search with RRF fusion. Default: false. */
+            enabled: z.boolean().default(false),
+            /** Weight for text (BM25) results in RRF fusion. Default: 0.3. */
+            textWeight: z.number().min(0).max(1).default(0.3),
+        })
+            .optional(),
+    })
+        .optional()
+        .describe('Search configuration including score thresholds and hybrid search.'),
+    /** Logging configuration. */
+    logging: loggingConfigSchema.optional().describe('Logging configuration.'),
+    /** Timeout in milliseconds for graceful shutdown. */
+    shutdownTimeoutMs: z
+        .number()
+        .optional()
+        .describe('Timeout in milliseconds for graceful shutdown.'),
+    /** Maximum consecutive system-level failures before triggering fatal error. Default: Infinity. */
+    maxRetries: z
+        .number()
+        .optional()
+        .describe('Maximum consecutive system-level failures before triggering fatal error. Default: Infinity.'),
+    /** Maximum backoff delay in milliseconds for system errors. Default: 60000. */
+    maxBackoffMs: z
+        .number()
+        .optional()
+        .describe('Maximum backoff delay in milliseconds for system errors. Default: 60000.'),
+});
 
 /**
  * @module api/handlers/configSchema
@@ -2610,9 +2508,10 @@ function renderDoc(context, config, hbs) {
  *
  * @param configDir - Optional config directory for resolving relative file paths in lookups.
  * @param customLib - Optional custom lib functions to merge.
+ * @param extractText - Optional callback to extract text from a file path. Returns extracted text or undefined on failure.
  * @returns The lib object.
  */
-function createJsonMapLib(configDir, customLib) {
+function createJsonMapLib(configDir, customLib, extractText) {
     // Cache loaded JSON files within a single applyRules invocation.
     const jsonCache = new Map();
     const loadJson = (filePath) => {
@@ -2683,6 +2582,66 @@ function createJsonMapLib(configDir, customLib) {
             }
             return results;
         },
+        /**
+         * Retrieve extracted text from neighboring files in the same directory.
+         *
+         * @param filePath - The current file path.
+         * @param options - Optional windowing and sort options.
+         * @returns Flat array of extracted text from siblings, in sort order.
+         */
+        fetchSiblings: (filePath, options) => {
+            if (!extractText)
+                return [];
+            const { before = 3, after = 1, sort = 'name' } = options ?? {};
+            const dir = dirname(filePath);
+            const ext = extname(filePath);
+            // List all files in the directory with the same extension
+            let entries;
+            try {
+                entries = readdirSync(dir).filter((name) => extname(name) === ext);
+            }
+            catch {
+                return [];
+            }
+            // Sort by filename (default) or mtime
+            if (sort === 'mtime') {
+                entries.sort((a, b) => {
+                    try {
+                        const aStat = statSync(join(dir, a));
+                        const bStat = statSync(join(dir, b));
+                        return aStat.mtimeMs - bStat.mtimeMs;
+                    }
+                    catch {
+                        return 0;
+                    }
+                });
+            }
+            else {
+                entries.sort();
+            }
+            // Find current file's position
+            const currentName = basename(filePath);
+            const currentIndex = entries.indexOf(currentName);
+            if (currentIndex === -1)
+                return [];
+            // Slice before/after window (excluding current file)
+            const beforeEntries = entries.slice(Math.max(0, currentIndex - before), currentIndex);
+            const afterEntries = entries.slice(currentIndex + 1, currentIndex + 1 + after);
+            const window = [...beforeEntries, ...afterEntries];
+            // Extract text from each sibling, silently skipping failures
+            const results = [];
+            for (const name of window) {
+                try {
+                    const text = extractText(join(dir, name));
+                    if (text !== undefined)
+                        results.push(text);
+                }
+                catch {
+                    // Silently skip files that fail extraction
+                }
+            }
+            return results;
+        },
         ...customLib,
     };
 }
@@ -2703,9 +2662,12 @@ function coerceType(value, type) {
     if (value === null || value === undefined) {
         return undefined;
     }
+    // Empty strings are only valid for the 'string' type
+    if (value === '' && type !== 'string') {
+        return undefined;
+    }
     switch (type) {
         case 'string': {
-            // Empty strings are valid for string type
             if (typeof value === 'string')
                 return value;
             if (typeof value === 'number' || typeof value === 'boolean') {
@@ -2719,9 +2681,6 @@ function coerceType(value, type) {
             return undefined;
         }
         case 'integer': {
-            // Empty strings are not valid integers
-            if (value === '')
-                return undefined;
             if (typeof value === 'string') {
                 // For strings, check that parsing yields an integer that matches the trimmed input
                 const trimmed = value.trim();
@@ -2737,16 +2696,10 @@ function coerceType(value, type) {
             return undefined;
         }
         case 'number': {
-            // Empty strings are not valid numbers
-            if (value === '')
-                return undefined;
             const num = typeof value === 'string' ? parseFloat(value) : Number(value);
             return Number.isFinite(num) ? num : undefined;
         }
         case 'boolean': {
-            // Empty strings are not valid booleans
-            if (value === '')
-                return undefined;
             if (typeof value === 'boolean')
                 return value;
             if (typeof value === 'string') {
@@ -2759,9 +2712,6 @@ function coerceType(value, type) {
             return undefined;
         }
         case 'array': {
-            // Empty strings are not valid arrays
-            if (value === '')
-                return undefined;
             if (Array.isArray(value))
                 return value;
             if (typeof value === 'string') {
@@ -2777,9 +2727,6 @@ function coerceType(value, type) {
             return undefined;
         }
         case 'object': {
-            // Empty strings are not valid objects
-            if (value === '')
-                return undefined;
             if (typeof value === 'string') {
                 try {
                     const parsed = JSON.parse(value);
@@ -3011,11 +2958,11 @@ async function loadCustomMapHelpers(helpers, configDir) {
  * @returns The merged metadata and optional rendered content.
  */
 async function applyRules(compiledRules, attributes, options = {}) {
-    const { namedMaps, logger, templateEngine, configDir, customMapLib, globalSchemas, } = options;
+    const { namedMaps, logger, templateEngine, configDir, customMapLib, globalSchemas, extractText, } = options;
     const hbs = templateEngine?.hbs ?? createHandlebarsInstance();
     // 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(configDir, customMapLib);
+    const lib = createJsonMapLib(configDir, customMapLib, extractText);
     let merged = {};
     let renderedContent = null;
     let renderAs = null;
@@ -3135,6 +3082,80 @@ async function applyRules(compiledRules, attributes, options = {}) {
     return { metadata: merged, renderedContent, matchedRules, renderAs };
 }
 
+/**
+ * @module api/handlers/configMerge
+ * Shared config merge utilities.
+ */
+/**
+ * Merge inference rules by name: submitted rules replace existing by name, new ones are appended.
+ */
+function mergeInferenceRules(existing, incoming) {
+    if (!incoming)
+        return existing ?? [];
+    if (!existing)
+        return incoming;
+    const merged = [...existing];
+    for (const rule of incoming) {
+        const name = rule['name'];
+        if (!name) {
+            merged.push(rule);
+            continue;
+        }
+        const idx = merged.findIndex((r) => r['name'] === name);
+        if (idx >= 0) {
+            merged[idx] = rule;
+        }
+        else {
+            merged.push(rule);
+        }
+    }
+    return merged;
+}
+
+/**
+ * @module api/handlers/mergeAndValidate
+ * Shared config merge and validation logic used by both validate and apply handlers.
+ */
+/**
+ * Merge a submitted partial config into the current config and validate against schema.
+ *
+ * @param currentConfig - The current running config.
+ * @param submittedPartial - The partial config to merge in.
+ * @returns The merge/validation result.
+ */
+function mergeAndValidateConfig(currentConfig, submittedPartial) {
+    let candidateRaw = {
+        ...currentConfig,
+    };
+    if (submittedPartial) {
+        const mergedRules = mergeInferenceRules(candidateRaw['inferenceRules'], submittedPartial['inferenceRules']);
+        candidateRaw = {
+            ...candidateRaw,
+            ...submittedPartial,
+            inferenceRules: mergedRules,
+        };
+    }
+    const parseResult = jeevesWatcherConfigSchema.safeParse(candidateRaw);
+    const errors = [];
+    if (!parseResult.success) {
+        for (const issue of parseResult.error.issues) {
+            errors.push({
+                path: issue.path.join('.'),
+                message: issue.message,
+            });
+        }
+        return { candidateRaw, errors };
+    }
+    // Note: When accepting external config via API, string rule references are NOT resolved
+    // (no configDir context). API-submitted rules must always be inline objects.
+    // The cast is safe because API config never contains string rule refs.
+    return {
+        candidateRaw,
+        parsed: parseResult.data,
+        errors,
+    };
+}
+
 /**
  * @module api/handlers/configValidate
  * Fastify route handler for POST /config/validate. Validates config against schema with optional test paths.
@@ -3651,11 +3672,11 @@ function createRenderHandler(deps) {
             });
         }
         catch (error) {
-            const msg = error instanceof Error ? error.message : 'Unknown render error';
+            const { message: msg } = normalizeError(error);
             if (msg.includes('ENOENT') || msg.includes('no such file')) {
                 return reply.status(404).send({ error: 'File not found' });
             }
-            logger.error({ filePath, error: msg }, 'Render failed');
+            logger.error({ filePath, err: normalizeError(error) }, 'Render failed');
             return reply.status(422).send({ error: msg });
         }
     };
@@ -3715,7 +3736,7 @@ function createRulesReapplyHandler(deps) {
  * Create handler for POST /rules/register.
  */
 function createRulesRegisterHandler(deps) {
-    return wrapHandler(async (request) => {
+    return wrapHandler((request) => {
         const { source, rules } = request.body;
         if (!source || typeof source !== 'string') {
             throw new Error('Missing required field: source');
@@ -3726,11 +3747,11 @@ function createRulesRegisterHandler(deps) {
         deps.virtualRuleStore.register(source, rules);
         deps.onRulesChanged();
         deps.logger.info({ source, ruleCount: rules.length }, 'Virtual rules registered');
-        return await Promise.resolve({
+        return {
             source,
             registered: rules.length,
             totalVirtualRules: deps.virtualRuleStore.size,
-        });
+        };
     }, deps.logger, 'RulesRegister');
 }
 
@@ -3755,16 +3776,16 @@ function unregisterSource(deps, source) {
  * Create handler for DELETE /rules/unregister (body-based).
  */
 function createRulesUnregisterHandler(deps) {
-    return wrapHandler(async (request) => {
-        return Promise.resolve(unregisterSource(deps, request.body.source));
+    return wrapHandler((request) => {
+        return unregisterSource(deps, request.body.source);
     }, deps.logger, 'RulesUnregister');
 }
 /**
  * Create handler for DELETE /rules/unregister/:source (param-based).
  */
 function createRulesUnregisterParamHandler(deps) {
-    return wrapHandler(async (request) => {
-        return Promise.resolve(unregisterSource(deps, request.params.source));
+    return wrapHandler((request) => {
+        return unregisterSource(deps, request.params.source);
     }, deps.logger, 'RulesUnregister');
 }
 
@@ -4444,7 +4465,7 @@ class InitialScanTracker {
  * @returns A configured Fastify instance.
  */
 function createApiServer(options) {
-    const { processor, vectorStore, embeddingProvider, queue, logger, config, issuesManager, valuesManager, configPath, helperIntrospection, virtualRuleStore, gitignoreFilter, version, initialScanTracker, } = options;
+    const { descriptor, processor, vectorStore, embeddingProvider, queue, logger, config, issuesManager, valuesManager, configPath, helperIntrospection, virtualRuleStore, gitignoreFilter, version, initialScanTracker, } = options;
     const getConfig = options.getConfig ?? (() => config);
     const getFileSystemWatcher = options.getFileSystemWatcher ?? (() => options.fileSystemWatcher);
     const reindexTracker = options.reindexTracker ?? new ReindexTracker();
@@ -4559,13 +4580,20 @@ function createApiServer(options) {
         logger,
         configDir: dirname(configPath),
     }));
-    app.post('/config/apply', createConfigApplyHandler({
-        getConfig,
-        configPath,
-        reindexTracker,
-        logger,
-        triggerReindex,
-    }));
+    const coreConfigApplyHandler = createConfigApplyHandler({
+        ...descriptor,
+        onConfigApply: () => {
+            const cfg = getConfig();
+            const reindexScope = cfg.configWatch?.reindex ?? 'issues';
+            triggerReindex(reindexScope);
+            return Promise.resolve();
+        },
+    });
+    app.post('/config/apply', async (request, reply) => {
+        const { patch, replace } = request.body;
+        const result = await coreConfigApplyHandler({ patch, replace });
+        return reply.status(result.status).send(result.body);
+    });
     // Virtual rules and points deletion routes
     if (virtualRuleStore) {
         const onRulesChanged = createOnRulesChanged({
@@ -4613,7 +4641,7 @@ function createApiServer(options) {
  * @returns The normalized path string.
  */
 function normalizePath(filePath, stripDriveLetter = false) {
-    let result = filePath.replace(/\\/g, '/').toLowerCase();
+    let result = normalizeSlashes(filePath).toLowerCase();
     if (stripDriveLetter) {
         result = result.replace(/^([a-z]):/, (_m, letter) => letter);
     }
@@ -5214,7 +5242,7 @@ const CONFIG_WATCH_DEFAULTS = {
 /** Default API values. */
 const API_DEFAULTS = {
     host: '127.0.0.1',
-    port: 1936,
+    port: DEFAULT_PORTS.watcher,
     cacheTtlMs: 30000,
 };
 /** Default logging values. */
@@ -5682,6 +5710,7 @@ function extractMarkdownFrontmatter(markdown) {
         : undefined;
     return { frontmatter, body };
 }
+/** Well-known JSON fields that contain meaningful text content. */
 const JSON_TEXT_FIELDS = [
     'content',
     'body',
@@ -5782,6 +5811,25 @@ async function extractText(filePath, extension, additionalExtractors) {
  * @module processor/buildMetadata
  * Builds merged metadata from file content, inference rules, and enrichment store. I/O: reads files, extracts text, queries SQLite enrichment.
  */
+/**
+ * Synchronously extract text from a file. Returns undefined on failure.
+ * Used by fetchSiblings in JsonMap lib for sibling context extraction.
+ */
+function syncExtractText(filePath) {
+    try {
+        const raw = readFileSync(filePath, 'utf-8').replace(/^\uFEFF/, '');
+        const ext = extname(filePath).toLowerCase();
+        if (ext === '.json') {
+            const parsed = JSON.parse(raw);
+            return extractJsonText(parsed);
+        }
+        // All other supported text formats: return raw content
+        return raw;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Build merged metadata for a file by applying inference rules and merging with enrichment metadata.
  *
@@ -5803,6 +5851,7 @@ async function buildMergedMetadata(options) {
         configDir,
         customMapLib,
         globalSchemas,
+        extractText: syncExtractText,
     });
     // 3. Read enrichment metadata from store (composable merge)
     const enrichment = enrichmentStore?.get(filePath) ?? null;
@@ -7701,7 +7750,7 @@ function installShutdownHandlers(stop) {
  *   When provided, the file is loaded as-is (no migration).
  * @returns The running JeevesWatcher instance.
  */
-async function startFromConfig(configPath) {
+async function startFromConfig(configPath, descriptor) {
     let resolvedPath = configPath;
     // Auto-migrate only when no explicit path was given.
     if (!configPath) {
@@ -7724,7 +7773,10 @@ async function startFromConfig(configPath) {
         }
     }
     const config = await loadConfig(resolvedPath);
-    const app = new JeevesWatcher(config, resolvedPath);
+    // Dynamic import breaks the circular dependency between this module
+    // and app/index.ts (which defines JeevesWatcher and re-exports startFromConfig).
+    const { JeevesWatcher } = await Promise.resolve().then(function () { return index; });
+    const app = new JeevesWatcher(config, resolvedPath, descriptor);
     installShutdownHandlers(() => app.stop());
     await app.start();
     return app;
@@ -7740,6 +7792,7 @@ async function startFromConfig(configPath) {
 class JeevesWatcher {
     config;
     configPath;
+    descriptor;
     factories;
     runtimeOptions;
     logger;
@@ -7760,9 +7813,13 @@ class JeevesWatcher {
     initialScanTracker;
     version;
     /** Create a new JeevesWatcher instance. */
-    constructor(config, configPath, factories = {}, runtimeOptions = {}) {
+    constructor(config, configPath, descriptor, factories = {}, runtimeOptions = {}) {
+        if (!descriptor) {
+            throw new Error('JeevesWatcher requires a component descriptor. Pass watcherDescriptor from the descriptor module.');
+        }
         this.config = config;
         this.configPath = configPath;
+        this.descriptor = descriptor;
         this.factories = { ...defaultFactories, ...factories };
         this.runtimeOptions = runtimeOptions;
         this.virtualRuleStore = new VirtualRuleStore();
@@ -7852,6 +7909,7 @@ class JeevesWatcher {
     }
     async startApiServer() {
         const server = this.factories.createApiServer({
+            descriptor: this.descriptor,
             processor: this.processor,
             vectorStore: this.vectorStore,
             embeddingProvider: this.embeddingProvider,
@@ -7873,7 +7931,7 @@ class JeevesWatcher {
         });
         await server.listen({
             host: this.config.api?.host ?? getBindAddress('watcher'),
-            port: this.config.api?.port ?? 1936,
+            port: this.config.api?.port ?? DEFAULT_PORTS.watcher,
         });
         return server;
     }
@@ -7931,12 +7989,18 @@ class JeevesWatcher {
     }
 }
 
+var index = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    JeevesWatcher: JeevesWatcher,
+    startFromConfig: startFromConfig
+});
+
 /**
  * @module cli/jeeves-watcher/customCommands
  * Domain-specific CLI commands registered via the descriptor's customCliCommands.
  * Uses fetchJson/postJson from core instead of hand-rolled API helpers.
  */
-const DEFAULT_PORT = '1936';
+const DEFAULT_PORT = String(DEFAULT_PORTS.watcher);
 const DEFAULT_HOST = '127.0.0.1';
 /** Build the API base URL from host and port options. */
 function baseUrl(opts) {
@@ -8032,8 +8096,8 @@ function registerCustomCommands(program) {
         .option('-s, --scope <scope>', 'Reindex scope (issues|full|rules|path|prune)', 'rules')
         .option('-t, --path <paths...>', 'Target path(s) for path or rules scope')).action(async (opts) => {
         await handleErrors(async () => {
-            if (!VALID_SCOPES.includes(opts.scope)) {
-                console.error(`Invalid scope "${opts.scope}". Must be one of: ${VALID_SCOPES.join(', ')}`);
+            if (!VALID_REINDEX_SCOPES.includes(opts.scope)) {
+                console.error(`Invalid scope "${opts.scope}". Must be one of: ${VALID_REINDEX_SCOPES.join(', ')}`);
                 process.exitCode = 1;
                 return;
             }
@@ -8091,8 +8155,6 @@ function registerCustomCommands(program) {
         })();
     });
 }
-// --- shared constants and helpers ---
-const VALID_SCOPES = ['issues', 'full', 'rules', 'path', 'prune'];
 /** Parse --json and --key options into a metadata object. Returns null on validation failure. */
 function parseMetadataArgs(json, keys) {
     let metadata = {};
@@ -8176,16 +8238,14 @@ const watcherDescriptor = {
     version,
     servicePackage: '@karmaniverous/jeeves-watcher',
     pluginPackage: '@karmaniverous/jeeves-watcher-openclaw',
-    defaultPort: 1936,
+    defaultPort: DEFAULT_PORTS.watcher,
     // Config
     configSchema: jeevesWatcherConfigSchema,
     configFileName: 'config.json',
     initTemplate: () => ({ ...INIT_CONFIG_TEMPLATE }),
-    // Service behavior — onConfigApply wired at the Fastify layer (api/index.ts)
-    // where it has access to the live reindex tracker and config getter.
-    onConfigApply: async (config) => {
-        await Promise.resolve();
-    },
+    // onConfigApply is overridden in createApiServer (api/index.ts) via the
+    // descriptor passed as a dependency, where it has access to the live
+    // reindex tracker and config getter.
     customMerge: (target, source) => {
         const mergedRules = mergeInferenceRules(target['inferenceRules'], source['inferenceRules']);
         return {
@@ -8202,7 +8262,7 @@ const watcherDescriptor = {
         configPath,
     ],
     run: async (configPath) => {
-        await startFromConfig(configPath);
+        await startFromConfig(configPath, watcherDescriptor);
     },
     // Content — generateToolsContent is wired in the plugin package
     // (watcherComponent.ts) where it has access to the API URL for menu generation.