@karmaniverous/jeeves-watcher 0.7.1 → 0.8.0

package/config.schema.json

@@ -149,7 +149,7 @@
       "description": "Reusable named JsonMap transformations (inline definition or .json file path resolved relative to config directory).",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema75"
+          "$ref": "#/definitions/__schema77"
         }
       ]
     },
@@ -157,7 +157,7 @@
       "description": "Named reusable Handlebars templates (inline strings or .hbs/.handlebars file paths).",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema76"
+          "$ref": "#/definitions/__schema78"
         }
       ]
     },
@@ -165,7 +165,7 @@
       "description": "Custom Handlebars helper registration.",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema77"
+          "$ref": "#/definitions/__schema79"
         }
       ]
     },
@@ -173,7 +173,7 @@
       "description": "Custom JsonMap lib function registration.",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema78"
+          "$ref": "#/definitions/__schema80"
         }
       ]
     },
@@ -181,7 +181,7 @@
       "description": "Reindex configuration.",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema79"
+          "$ref": "#/definitions/__schema81"
         }
       ]
     },
@@ -189,7 +189,7 @@
       "description": "Named Qdrant filter patterns for skill-activated behaviors.",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema80"
+          "$ref": "#/definitions/__schema82"
         }
       ]
     },
@@ -197,7 +197,7 @@
       "description": "Search configuration including score thresholds and hybrid search.",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema81"
+          "$ref": "#/definitions/__schema83"
         }
       ]
     },
@@ -205,7 +205,7 @@
       "description": "Logging configuration.",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema82"
+          "$ref": "#/definitions/__schema84"
         }
       ]
     },
@@ -213,7 +213,7 @@
       "description": "Timeout in milliseconds for graceful shutdown.",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema85"
+          "$ref": "#/definitions/__schema87"
         }
       ]
     },
@@ -221,7 +221,7 @@
       "description": "Maximum consecutive system-level failures before triggering fatal error. Default: Infinity.",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema86"
+          "$ref": "#/definitions/__schema88"
         }
       ]
     },
@@ -229,7 +229,7 @@
       "description": "Maximum backoff delay in milliseconds for system errors. Default: 60000.",
       "allOf": [
         {
-          "$ref": "#/definitions/__schema87"
+          "$ref": "#/definitions/__schema89"
         }
       ]
     }
@@ -614,6 +614,9 @@
               },
               "render": {
                 "$ref": "#/definitions/__schema64"
+              },
+              "renderAs": {
+                "$ref": "#/definitions/__schema75"
               }
             },
             "required": [
@@ -922,6 +925,18 @@
       "type": "string"
     },
     "__schema75": {
+      "description": "Output file extension override (without dot). Requires template or render.",
+      "allOf": [
+        {
+          "$ref": "#/definitions/__schema76"
+        }
+      ]
+    },
+    "__schema76": {
+      "type": "string",
+      "pattern": "^[a-z0-9]{1,10}$"
+    },
+    "__schema77": {
       "type": "object",
       "propertyNames": {
         "type": "string"
@@ -958,7 +973,7 @@
         ]
       }
     },
-    "__schema76": {
+    "__schema78": {
       "type": "object",
       "propertyNames": {
         "type": "string"
@@ -985,7 +1000,7 @@
         ]
       }
     },
-    "__schema77": {
+    "__schema79": {
       "type": "object",
       "propertyNames": {
         "type": "string"
@@ -1005,7 +1020,7 @@
         ]
       }
     },
-    "__schema78": {
+    "__schema80": {
       "type": "object",
       "propertyNames": {
         "type": "string"
@@ -1025,7 +1040,7 @@
         ]
       }
     },
-    "__schema79": {
+    "__schema81": {
       "type": "object",
       "properties": {
         "callbackUrl": {
@@ -1034,14 +1049,14 @@
         }
       }
     },
-    "__schema80": {
+    "__schema82": {
       "type": "object",
       "propertyNames": {
         "type": "string"
       },
       "additionalProperties": {}
     },
-    "__schema81": {
+    "__schema83": {
       "type": "object",
       "properties": {
         "scoreThresholds": {
@@ -1086,14 +1101,14 @@
         }
       }
     },
-    "__schema82": {
+    "__schema84": {
       "type": "object",
       "properties": {
         "level": {
           "description": "Logging level (trace, debug, info, warn, error, fatal).",
           "allOf": [
             {
-              "$ref": "#/definitions/__schema83"
+              "$ref": "#/definitions/__schema85"
             }
           ]
         },
@@ -1101,25 +1116,25 @@
           "description": "Path to log file (logs to stdout if omitted).",
           "allOf": [
             {
-              "$ref": "#/definitions/__schema84"
+              "$ref": "#/definitions/__schema86"
             }
           ]
         }
       }
     },
-    "__schema83": {
+    "__schema85": {
       "type": "string"
     },
-    "__schema84": {
+    "__schema86": {
       "type": "string"
     },
-    "__schema85": {
+    "__schema87": {
       "type": "number"
     },
-    "__schema86": {
+    "__schema88": {
       "type": "number"
     },
-    "__schema87": {
+    "__schema89": {
       "type": "number"
     }
   }

package/dist/cli/jeeves-watcher/index.js

@@ -1537,11 +1537,16 @@ async function applyRules(compiledRules, attributes, options = {}) {
     const lib = createJsonMapLib(configDir, customMapLib);
     let merged = {};
     let renderedContent = null;
+    let renderAs = null;
     const matchedRules = [];
     const log = logger ?? console;
     for (const [, { rule, validate }] of compiledRules.entries()) {
         if (validate(attributes)) {
             matchedRules.push(rule.name);
+            // Resolve renderAs (last-match-wins)
+            if (rule.renderAs) {
+                renderAs = rule.renderAs;
+            }
             // Apply schema-based metadata extraction
             if (rule.schema && rule.schema.length > 0) {
                 try {
@@ -1645,7 +1650,7 @@ async function applyRules(compiledRules, attributes, options = {}) {
             }
         }
     }
-    return { metadata: merged, renderedContent, matchedRules };
+    return { metadata: merged, renderedContent, matchedRules, renderAs };
 }
 
 /**
@@ -1926,6 +1931,12 @@ const inferenceRuleSchema = z
     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) {
@@ -1935,6 +1946,13 @@ const inferenceRuleSchema = z
             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',
+        });
+    }
 });
 
 /**
@@ -2711,6 +2729,107 @@ function createConfigValidateHandler(deps) {
     }, deps.logger, 'Config validate');
 }
 
+/**
+ * @module api/handlers/facets
+ * GET /search/facets route handler. Returns schema-derived facet definitions with live values.
+ */
+/** Compute a simple hash of rule names + schema refs for cache invalidation. */
+function computeRulesHash(rules) {
+    if (!rules)
+        return '';
+    return rules
+        .map((r) => `${r.name}:${JSON.stringify(r.schema ?? [])}`)
+        .join('|');
+}
+/**
+ * Check whether a resolved property should be exposed as a facet.
+ * A property is facetable if it declares `uiHint` or `enum`.
+ */
+function isFacetable(prop) {
+    return prop.uiHint !== undefined || prop.enum !== undefined;
+}
+/**
+ * Build the schema-derived facet structure from inference rules.
+ *
+ * Iterates all rules, resolves their schemas via `mergeSchemas`, and extracts
+ * properties that have `uiHint` or `enum` defined. Deduplicates across rules.
+ */
+function buildFacetSchema(rules, mergeOptions) {
+    const fields = new Map();
+    for (const rule of rules ?? []) {
+        if (!rule.schema?.length)
+            continue;
+        const resolved = mergeSchemas(rule.schema, mergeOptions);
+        for (const [propName, propDef] of Object.entries(resolved.properties)) {
+            if (!isFacetable(propDef))
+                continue;
+            const existing = fields.get(propName);
+            if (existing) {
+                existing.rules.push(rule.name);
+                if (propDef.enum)
+                    existing.enumValues = propDef.enum;
+                if (propDef.uiHint)
+                    existing.uiHint = propDef.uiHint;
+            }
+            else {
+                fields.set(propName, {
+                    type: propDef.type ?? 'string',
+                    uiHint: propDef.uiHint ?? 'dropdown',
+                    enumValues: propDef.enum,
+                    rules: [rule.name],
+                });
+            }
+        }
+    }
+    return { fields, rulesHash: computeRulesHash(rules) };
+}
+/**
+ * Create the GET /search/facets route handler.
+ *
+ * Returns facet definitions derived from inference rule schemas, enriched
+ * with live values from the ValuesManager.
+ *
+ * @param deps - Handler dependencies.
+ * @returns Fastify route handler (plain return, compatible with `withCache`).
+ */
+function createFacetsHandler(deps) {
+    const { config, valuesManager, configDir } = deps;
+    let cached;
+    const mergeOptions = {
+        globalSchemas: config.schemas,
+        configDir,
+    };
+    return () => {
+        // Rebuild schema cache if rules changed
+        const currentHash = computeRulesHash(config.inferenceRules);
+        if (!cached || cached.rulesHash !== currentHash) {
+            cached = buildFacetSchema(config.inferenceRules, mergeOptions);
+        }
+        // Merge with live values
+        const allValues = valuesManager.getAll();
+        const facets = [];
+        for (const [field, schema] of cached.fields) {
+            // Collect live values from all rules that define this field
+            const liveValues = new Set();
+            for (const ruleName of schema.rules) {
+                const fieldValues = allValues[ruleName]?.[field];
+                if (fieldValues) {
+                    for (const v of fieldValues)
+                        liveValues.add(v);
+                }
+            }
+            facets.push({
+                field,
+                type: schema.type,
+                uiHint: schema.uiHint,
+                values: schema.enumValues ?? [...liveValues].sort(),
+                rules: schema.rules,
+            });
+        }
+        return { facets };
+    };
+}
+
 /**
  * @module api/handlers/issues
  * Fastify route handler for GET /issues. Returns current processing issues.
@@ -3037,6 +3156,79 @@ function createReindexHandler(deps) {
     }, deps.logger, 'Reindex');
 }
 
+/**
+ * @module util/isPathWatched
+ * Checks whether a file path falls within the watched scope defined by watch config globs.
+ */
+/**
+ * Check whether a file path matches the watched scope.
+ * A path is watched if it matches at least one `paths` glob
+ * AND does not match any `ignored` glob. Mirrors chokidar's
+ * inclusion/exclusion logic.
+ *
+ * @param filePath - The file path to check.
+ * @param watchPaths - Glob patterns that define watched paths.
+ * @param ignoredPaths - Glob patterns that exclude paths (optional).
+ * @returns `true` if the file is within watched scope.
+ */
+function isPathWatched(filePath, watchPaths, ignoredPaths) {
+    const normalised = normalizeSlashes(filePath);
+    const isIncluded = picomatch(watchPaths, { dot: true });
+    if (!isIncluded(normalised))
+        return false;
+    if (ignoredPaths && ignoredPaths.length > 0) {
+        const isExcluded = picomatch(ignoredPaths, { dot: true });
+        if (isExcluded(normalised))
+            return false;
+    }
+    return true;
+}
+
+/**
+ * @module api/handlers/render
+ * POST /render route handler. Runs a file through the inference rule engine and returns rendered content.
+ */
+/**
+ * Create the POST /render route handler.
+ *
+ * @param deps - Handler dependencies.
+ * @returns Fastify route handler.
+ */
+function createRenderHandler(deps) {
+    const { processor, watch, logger } = deps;
+    return async (request, reply) => {
+        const { path: filePath } = request.body;
+        if (!filePath || typeof filePath !== 'string') {
+            return reply.status(400).send({ error: 'Missing required field: path' });
+        }
+        // Validate path is within watched scope
+        if (!isPathWatched(filePath, watch.paths, watch.ignored)) {
+            return reply.status(403).send({ error: 'Path is outside watched scope' });
+        }
+        try {
+            const result = await processor.renderFile(filePath);
+            // Passthrough responses should not be cached
+            if (!result.transformed) {
+                void reply.header('Cache-Control', 'no-cache');
+            }
+            return await reply.send({
+                renderAs: result.renderAs,
+                content: result.content,
+                rules: result.rules,
+                metadata: result.metadata,
+            });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown render 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');
+            return reply.status(422).send({ error: msg });
+        }
+    };
+}
+
 /**
  * @module api/handlers/rulesReapply
  * Fastify route handler for POST /rules/reapply.
@@ -3231,6 +3423,11 @@ function withCache(ttlMs, handler) {
         if (fReply.statusCode >= 400) {
             return result;
         }
+        // Skip cache for responses with Cache-Control: no-cache
+        const cacheControl = fReply.getHeader('Cache-Control');
+        if (cacheControl === 'no-cache') {
+            return result;
+        }
         // Store in cache
         cache.set(key, {
             value: result,
@@ -3308,6 +3505,12 @@ function createApiServer(options) {
         reindexTracker,
     })));
     app.post('/metadata', createMetadataHandler({ processor, config, logger }));
+    app.post('/render', withCache(cacheTtlMs, createRenderHandler({ processor, watch: config.watch, logger })));
+    app.get('/search/facets', createFacetsHandler({
+        config,
+        valuesManager,
+        configDir: dirname(configPath),
+    }));
     const hybridConfig = config.search?.hybrid
         ? {
             enabled: config.search.hybrid.enabled,
@@ -3925,7 +4128,7 @@ async function buildMergedMetadata(options) {
     const extracted = await extractText(filePath, ext);
     // 2. Build attributes + apply rules
     const attributes = buildAttributes(filePath, stats, extracted.frontmatter, extracted.json);
-    const { metadata: inferred, renderedContent, matchedRules, } = await applyRules(compiledRules, attributes, {
+    const { metadata: inferred, renderedContent, matchedRules, renderAs, } = await applyRules(compiledRules, attributes, {
         namedMaps: maps,
         logger,
         templateEngine,
@@ -3947,6 +4150,7 @@ async function buildMergedMetadata(options) {
         extracted,
         renderedContent,
         matchedRules,
+        renderAs,
     };
 }
 
@@ -4162,7 +4366,7 @@ class DocumentProcessor {
             ...result.metadata,
             matched_rules: result.matchedRules,
         };
-        return { ...result, metadataWithRules };
+        return { ...result, metadataWithRules, renderAs: result.renderAs };
     }
     /**
      * Execute an async operation with standardized file error handling.
@@ -4283,6 +4487,26 @@ class DocumentProcessor {
             return metadataWithRules;
         }, null);
     }
+    /**
+     * Render a file through the rule engine without embedding.
+     * Returns rendered content, renderAs, matched rules, and metadata.
+     *
+     * @param filePath - The file to render.
+     * @returns The render result.
+     */
+    async renderFile(filePath) {
+        const ext = extname(filePath);
+        const { renderedContent, extracted, matchedRules, metadataWithRules, renderAs, } = await this.buildMetadataWithRules(filePath);
+        const content = renderedContent ?? extracted.text;
+        const resolved = renderAs ?? (ext.slice(1) || 'txt');
+        return {
+            renderAs: resolved,
+            content,
+            rules: matchedRules,
+            metadata: metadataWithRules,
+            transformed: renderedContent !== null,
+        };
+    }
     /**
      * Update compiled inference rules, template engine, and custom map lib.
      *

package/dist/index.d.ts

@@ -91,6 +91,7 @@ declare const inferenceRuleSchema: z.ZodObject<{
             sort: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    renderAs: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** An inference rule: JSON Schema match condition, schema array, and optional JsonMap transformation. */
 type InferenceRule = z.infer<typeof inferenceRuleSchema>;
@@ -165,6 +166,7 @@ declare const jeevesWatcherConfigSchema: z.ZodObject<{
                 sort: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>>;
+        renderAs: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodString]>>>;
     maps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString, z.ZodObject<{
         map: z.ZodUnion<[z.ZodType<_karmaniverous_jsonmap.JsonMapMap, unknown, z.core.$ZodTypeInternals<_karmaniverous_jsonmap.JsonMapMap, unknown>>, z.ZodString]>;
@@ -580,6 +582,8 @@ interface ApplyRulesResult {
     renderedContent: string | null;
     /** Names of rules that matched. */
     matchedRules: string[];
+    /** The renderAs value from the last matching rule that declares it, or null. */
+    renderAs: string | null;
 }
 /**
  * Optional parameters for applyRules beyond the required compiledRules and attributes.
@@ -908,6 +912,26 @@ interface ProcessorConfig {
     globalSchemas?: Record<string, SchemaEntry>;
 }
 
+/**
+ * @module processor/renderResult
+ * Type definition for the render endpoint result.
+ */
+/**
+ * Result returned by {@link DocumentProcessorInterface.renderFile}.
+ */
+interface RenderResult {
+    /** Output content type (file extension without dot). Always present. */
+    renderAs: string;
+    /** Rendered content (if a transform ran) or extracted text (passthrough). */
+    content: string;
+    /** Names of matched inference rules (diagnostic). */
+    rules: string[];
+    /** Composed embedding properties from matched rules. */
+    metadata: Record<string, unknown>;
+    /** Whether a template or render transform produced the content. */
+    transformed: boolean;
+}
+
 /**
  * @module processor/types
  * Document processor interface definitions.
@@ -927,6 +951,8 @@ interface DocumentProcessorInterface {
     processMetadataUpdate(filePath: string, metadata: Record<string, unknown>): Promise<Record<string, unknown> | null>;
     /** Process a rules update for a file (rebuild merged metadata, payload update only). */
     processRulesUpdate(filePath: string): Promise<Record<string, unknown> | null>;
+    /** Render a file through the rule engine without embedding. */
+    renderFile(filePath: string): Promise<RenderResult>;
     /** Update compiled inference rules and associated engines. */
     updateRules(compiledRules: CompiledRule[], templateEngine?: TemplateEngine, customMapLib?: Record<string, (...args: unknown[]) => unknown>): void;
 }
@@ -1017,6 +1043,14 @@ declare class DocumentProcessor implements DocumentProcessorInterface {
      * @returns The merged metadata, or `null` if the file is not indexed.
      */
     processRulesUpdate(filePath: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Render a file through the rule engine without embedding.
+     * Returns rendered content, renderAs, matched rules, and metadata.
+     *
+     * @param filePath - The file to render.
+     * @returns The render result.
+     */
+    renderFile(filePath: string): Promise<RenderResult>;
     /**
      * Update compiled inference rules, template engine, and custom map lib.
      *

package/dist/index.js

@@ -892,11 +892,16 @@ async function applyRules(compiledRules, attributes, options = {}) {
     const lib = createJsonMapLib(configDir, customMapLib);
     let merged = {};
     let renderedContent = null;
+    let renderAs = null;
     const matchedRules = [];
     const log = logger ?? console;
     for (const [, { rule, validate }] of compiledRules.entries()) {
         if (validate(attributes)) {
             matchedRules.push(rule.name);
+            // Resolve renderAs (last-match-wins)
+            if (rule.renderAs) {
+                renderAs = rule.renderAs;
+            }
             // Apply schema-based metadata extraction
             if (rule.schema && rule.schema.length > 0) {
                 try {
@@ -1000,7 +1005,7 @@ async function applyRules(compiledRules, attributes, options = {}) {
             }
         }
     }
-    return { metadata: merged, renderedContent, matchedRules };
+    return { metadata: merged, renderedContent, matchedRules, renderAs };
 }
 
 /**
@@ -1617,6 +1622,12 @@ const inferenceRuleSchema = z
     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) {
@@ -1626,6 +1637,13 @@ const inferenceRuleSchema = z
             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',
+        });
+    }
 });
 
 /**
@@ -2402,6 +2420,107 @@ function createConfigValidateHandler(deps) {
     }, deps.logger, 'Config validate');
 }
 
+/**
+ * @module api/handlers/facets
+ * GET /search/facets route handler. Returns schema-derived facet definitions with live values.
+ */
+/** Compute a simple hash of rule names + schema refs for cache invalidation. */
+function computeRulesHash(rules) {
+    if (!rules)
+        return '';
+    return rules
+        .map((r) => `${r.name}:${JSON.stringify(r.schema ?? [])}`)
+        .join('|');
+}
+/**
+ * Check whether a resolved property should be exposed as a facet.
+ * A property is facetable if it declares `uiHint` or `enum`.
+ */
+function isFacetable(prop) {
+    return prop.uiHint !== undefined || prop.enum !== undefined;
+}
+/**
+ * Build the schema-derived facet structure from inference rules.
+ *
+ * Iterates all rules, resolves their schemas via `mergeSchemas`, and extracts
+ * properties that have `uiHint` or `enum` defined. Deduplicates across rules.
+ */
+function buildFacetSchema(rules, mergeOptions) {
+    const fields = new Map();
+    for (const rule of rules ?? []) {
+        if (!rule.schema?.length)
+            continue;
+        const resolved = mergeSchemas(rule.schema, mergeOptions);
+        for (const [propName, propDef] of Object.entries(resolved.properties)) {
+            if (!isFacetable(propDef))
+                continue;
+            const existing = fields.get(propName);
+            if (existing) {
+                existing.rules.push(rule.name);
+                if (propDef.enum)
+                    existing.enumValues = propDef.enum;
+                if (propDef.uiHint)
+                    existing.uiHint = propDef.uiHint;
+            }
+            else {
+                fields.set(propName, {
+                    type: propDef.type ?? 'string',
+                    uiHint: propDef.uiHint ?? 'dropdown',
+                    enumValues: propDef.enum,
+                    rules: [rule.name],
+                });
+            }
+        }
+    }
+    return { fields, rulesHash: computeRulesHash(rules) };
+}
+/**
+ * Create the GET /search/facets route handler.
+ *
+ * Returns facet definitions derived from inference rule schemas, enriched
+ * with live values from the ValuesManager.
+ *
+ * @param deps - Handler dependencies.
+ * @returns Fastify route handler (plain return, compatible with `withCache`).
+ */
+function createFacetsHandler(deps) {
+    const { config, valuesManager, configDir } = deps;
+    let cached;
+    const mergeOptions = {
+        globalSchemas: config.schemas,
+        configDir,
+    };
+    return () => {
+        // Rebuild schema cache if rules changed
+        const currentHash = computeRulesHash(config.inferenceRules);
+        if (!cached || cached.rulesHash !== currentHash) {
+            cached = buildFacetSchema(config.inferenceRules, mergeOptions);
+        }
+        // Merge with live values
+        const allValues = valuesManager.getAll();
+        const facets = [];
+        for (const [field, schema] of cached.fields) {
+            // Collect live values from all rules that define this field
+            const liveValues = new Set();
+            for (const ruleName of schema.rules) {
+                const fieldValues = allValues[ruleName]?.[field];
+                if (fieldValues) {
+                    for (const v of fieldValues)
+                        liveValues.add(v);
+                }
+            }
+            facets.push({
+                field,
+                type: schema.type,
+                uiHint: schema.uiHint,
+                values: schema.enumValues ?? [...liveValues].sort(),
+                rules: schema.rules,
+            });
+        }
+        return { facets };
+    };
+}
+
 /**
  * @module api/handlers/issues
  * Fastify route handler for GET /issues. Returns current processing issues.
@@ -2728,6 +2847,79 @@ function createReindexHandler(deps) {
     }, deps.logger, 'Reindex');
 }
 
+/**
+ * @module util/isPathWatched
+ * Checks whether a file path falls within the watched scope defined by watch config globs.
+ */
+/**
+ * Check whether a file path matches the watched scope.
+ * A path is watched if it matches at least one `paths` glob
+ * AND does not match any `ignored` glob. Mirrors chokidar's
+ * inclusion/exclusion logic.
+ *
+ * @param filePath - The file path to check.
+ * @param watchPaths - Glob patterns that define watched paths.
+ * @param ignoredPaths - Glob patterns that exclude paths (optional).
+ * @returns `true` if the file is within watched scope.
+ */
+function isPathWatched(filePath, watchPaths, ignoredPaths) {
+    const normalised = normalizeSlashes(filePath);
+    const isIncluded = picomatch(watchPaths, { dot: true });
+    if (!isIncluded(normalised))
+        return false;
+    if (ignoredPaths && ignoredPaths.length > 0) {
+        const isExcluded = picomatch(ignoredPaths, { dot: true });
+        if (isExcluded(normalised))
+            return false;
+    }
+    return true;
+}
+
+/**
+ * @module api/handlers/render
+ * POST /render route handler. Runs a file through the inference rule engine and returns rendered content.
+ */
+/**
+ * Create the POST /render route handler.
+ *
+ * @param deps - Handler dependencies.
+ * @returns Fastify route handler.
+ */
+function createRenderHandler(deps) {
+    const { processor, watch, logger } = deps;
+    return async (request, reply) => {
+        const { path: filePath } = request.body;
+        if (!filePath || typeof filePath !== 'string') {
+            return reply.status(400).send({ error: 'Missing required field: path' });
+        }
+        // Validate path is within watched scope
+        if (!isPathWatched(filePath, watch.paths, watch.ignored)) {
+            return reply.status(403).send({ error: 'Path is outside watched scope' });
+        }
+        try {
+            const result = await processor.renderFile(filePath);
+            // Passthrough responses should not be cached
+            if (!result.transformed) {
+                void reply.header('Cache-Control', 'no-cache');
+            }
+            return await reply.send({
+                renderAs: result.renderAs,
+                content: result.content,
+                rules: result.rules,
+                metadata: result.metadata,
+            });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown render 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');
+            return reply.status(422).send({ error: msg });
+        }
+    };
+}
+
 /**
  * @module api/handlers/rulesReapply
  * Fastify route handler for POST /rules/reapply.
@@ -2922,6 +3114,11 @@ function withCache(ttlMs, handler) {
         if (fReply.statusCode >= 400) {
             return result;
         }
+        // Skip cache for responses with Cache-Control: no-cache
+        const cacheControl = fReply.getHeader('Cache-Control');
+        if (cacheControl === 'no-cache') {
+            return result;
+        }
         // Store in cache
         cache.set(key, {
             value: result,
@@ -2999,6 +3196,12 @@ function createApiServer(options) {
         reindexTracker,
     })));
     app.post('/metadata', createMetadataHandler({ processor, config, logger }));
+    app.post('/render', withCache(cacheTtlMs, createRenderHandler({ processor, watch: config.watch, logger })));
+    app.get('/search/facets', createFacetsHandler({
+        config,
+        valuesManager,
+        configDir: dirname(configPath),
+    }));
     const hybridConfig = config.search?.hybrid
         ? {
             enabled: config.search.hybrid.enabled,
@@ -3903,7 +4106,7 @@ async function buildMergedMetadata(options) {
     const extracted = await extractText(filePath, ext);
     // 2. Build attributes + apply rules
     const attributes = buildAttributes(filePath, stats, extracted.frontmatter, extracted.json);
-    const { metadata: inferred, renderedContent, matchedRules, } = await applyRules(compiledRules, attributes, {
+    const { metadata: inferred, renderedContent, matchedRules, renderAs, } = await applyRules(compiledRules, attributes, {
         namedMaps: maps,
         logger,
         templateEngine,
@@ -3925,6 +4128,7 @@ async function buildMergedMetadata(options) {
         extracted,
         renderedContent,
         matchedRules,
+        renderAs,
     };
 }
 
@@ -4140,7 +4344,7 @@ class DocumentProcessor {
             ...result.metadata,
             matched_rules: result.matchedRules,
         };
-        return { ...result, metadataWithRules };
+        return { ...result, metadataWithRules, renderAs: result.renderAs };
     }
     /**
      * Execute an async operation with standardized file error handling.
@@ -4261,6 +4465,26 @@ class DocumentProcessor {
             return metadataWithRules;
         }, null);
     }
+    /**
+     * Render a file through the rule engine without embedding.
+     * Returns rendered content, renderAs, matched rules, and metadata.
+     *
+     * @param filePath - The file to render.
+     * @returns The render result.
+     */
+    async renderFile(filePath) {
+        const ext = extname(filePath);
+        const { renderedContent, extracted, matchedRules, metadataWithRules, renderAs, } = await this.buildMetadataWithRules(filePath);
+        const content = renderedContent ?? extracted.text;
+        const resolved = renderAs ?? (ext.slice(1) || 'txt');
+        return {
+            renderAs: resolved,
+            content,
+            rules: matchedRules,
+            metadata: metadataWithRules,
+            transformed: renderedContent !== null,
+        };
+    }
     /**
      * Update compiled inference rules, template engine, and custom map lib.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-watcher",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "author": "Jason Williscroft",
   "description": "Filesystem watcher that keeps a Qdrant vector store in sync with document changes",
   "license": "BSD-3-Clause",
@@ -73,7 +73,7 @@
     "mammoth": "^1.11.0",
     "mdast-util-from-adf": "^2.2.0",
     "mdast-util-to-markdown": "^2.1.2",
-    "picomatch": "*",
+    "picomatch": "^4.0.3",
     "pino": "*",
     "radash": "^12.1.1",
     "rehype-parse": "^9.0.1",
@@ -93,7 +93,7 @@
     "@types/fs-extra": "^11.0.4",
     "@types/js-yaml": "*",
     "@types/node": "^25.3.0",
-    "@types/picomatch": "*",
+    "@types/picomatch": "^4.0.2",
     "@types/uuid": "*",
     "@vitest/coverage-v8": "^4.0.18",
     "auto-changelog": "^2.5.0",