@karmaniverous/jeeves-watcher-openclaw 0.16.1 → 0.18.0-0

package/dist/index.js

@@ -1,4 +1,5 @@
-import { DEFAULT_PORTS, resolvePluginSetting, resolveOptionalPluginSetting, fail, init, resolveWorkspacePath, registerPromptContext, jeevesComponentDescriptorSchema, postJson, fetchJson, ok, connectionFail, getPackageVersion, createPluginToolset } from '@karmaniverous/jeeves';
+import { DEFAULT_PORTS, resolveOptionalPluginSetting, resolvePluginSetting, createPluginToolset, fail, init, resolveWorkspacePath, registerPromptContext, jeevesComponentDescriptorSchema, getPackageVersion } from '@karmaniverous/jeeves';
+import { defineCatalog, standardEntries, toToolName } from '@karmaniverous/jeeves/catalog';
 import 'node:crypto';
 
 function getEnumValues$1(entries) {
@@ -165,7 +166,7 @@ const allowsEval$1 = /* @__PURE__*/ cached$1(() => {
         return false;
     }
 });
-function isPlainObject$1(o) {
+function isPlainObject$2(o) {
     if (isObject$1(o) === false)
         return false;
     // modified constructor
@@ -185,7 +186,7 @@ function isPlainObject$1(o) {
     return true;
 }
 function shallowClone$1(o) {
-    if (isPlainObject$1(o))
+    if (isPlainObject$2(o))
         return { ...o };
     if (Array.isArray(o))
         return [...o];
@@ -284,7 +285,7 @@ function omit$1(schema, mask) {
     return clone$1(schema, mergeDefs$1(currDef, { shape: newShape, checks: [] }));
 }
 function extend$1(schema, shape) {
-    if (!isPlainObject$1(shape)) {
+    if (!isPlainObject$2(shape)) {
         throw new Error("Invalid input to extend: expected a plain object");
     }
     const checks = schema._zod.def.checks;
@@ -308,7 +309,7 @@ function extended(schema, shape) {
     return newShape;
 }
 function safeExtend$1(schema, shape) {
-    if (!isPlainObject$1(shape)) {
+    if (!isPlainObject$2(shape)) {
         throw new Error("Invalid input to safeExtend: expected a plain object");
     }
     return clone$1(schema, mergeDefs$1(schema._zod.def, { shape: extended(schema, shape) }));
@@ -387,6 +388,20 @@ function unwrapMessage$1(message) {
     return typeof message === "string" ? message : message?.message;
 }
 /* A check holds no link back to the schema it is attached to — the same check instance is shared by every clone of that schema — so the owner is stamped onto the issues a check just raised, at the only point where both are in scope. Runs on the failure path only; `start` is the issue count from before the check ran. */
+/** The leading size checks of `defChecks` that set an upper bound, each paired with it. */
+function sizeCaps(defChecks) {
+    const caps = [];
+    for (const ch of defChecks ?? []) {
+        const d = ch._zod.def;
+        // a later check may rewrite the value
+        if (!/_(length|size)$|_equals$/.test(d.check))
+            break;
+        const max = d.maximum ?? d.length ?? d.size;
+        if (max >= 0)
+            caps.push([max, ch]);
+    }
+    return caps;
+}
 function attachSchema(issues, start, inst) {
     var _a;
     for (let i = start; i < issues.length; i++) {
@@ -1152,6 +1167,7 @@ const anyString = /^[\s\S]{0,}$/;
 const integer$1 = /^-?\d+$/;
 const number$3 = /^-?\d+(?:\.\d+)?$/;
 const boolean$3 = /^(?:true|false)$/i;
+const _null$5 = /^null$/i;
 // regex for string with no uppercase letters
 const lowercase$1 = /^[^A-Z]*$/;
 // regex for string with no lowercase letters
@@ -1550,7 +1566,7 @@ let Doc$1 = class Doc {
 const version$1 = {
     major: 4,
     minor: 6,
-    patch: 5,
+    patch: 7,
 };
 
 const $ZodType$1 = /*@__PURE__*/ $constructor$1("$ZodType", (inst, def) => {
@@ -2142,6 +2158,23 @@ const $ZodBoolean$1 = /*@__PURE__*/ $constructor$1("$ZodBoolean", (inst, def) =>
         return payload;
     };
 });
+const $ZodNull$1 = /*@__PURE__*/ $constructor$1("$ZodNull", (inst, def) => {
+    $ZodType$1.init(inst, def);
+    inst._zod.pattern = _null$5;
+    inst._zod.values = new Set([null]);
+    inst._zod.parse = (payload, _ctx) => {
+        const input = payload.value;
+        if (input === null)
+            return payload;
+        payload.issues.push({
+            expected: "null",
+            code: "invalid_type",
+            input,
+            inst,
+        });
+        return payload;
+    };
+});
 const $ZodUnknown$1 = /*@__PURE__*/ $constructor$1("$ZodUnknown", (inst, def) => {
     $ZodType$1.init(inst, def);
     inst._zod.parse = (payload) => payload;
@@ -2158,6 +2191,31 @@ const $ZodNever$1 = /*@__PURE__*/ $constructor$1("$ZodNever", (inst, def) => {
         return payload;
     };
 });
+// an oversized container fails its leading size checks before any element is parsed
+function capSize(inst, size) {
+    const caps = sizeCaps(inst._zod.def.checks);
+    if (!caps.length)
+        return;
+    const cap = Math.min(...caps.map((c) => c[0]));
+    const parse = inst._zod.parse;
+    inst._zod.parse = (payload, ctx) => {
+        const n = size(payload.value);
+        if (n > cap && !ctx?.skipChecks && ctx?.direction !== "backward") {
+            for (const [max, ch] of sizeCaps(inst._zod.def.checks)) {
+                if (n > max && ch._zod.def.when(payload)) {
+                    const start = payload.issues.length;
+                    ch._zod.check(payload);
+                    // the value is still the raw input, so no later check may read it
+                    payload.issues[start].continue = false;
+                    attachSchema(payload.issues, start, inst);
+                    return payload;
+                }
+            }
+        }
+        return parse(payload, ctx);
+    };
+}
+const arraySize = (input) => (Array.isArray(input) ? input.length : -1);
 function handleArrayResult$1(result, final, index) {
     if (result.issues.length) {
         final.issues.push(...prefixIssues$1(index, result.issues));
@@ -2203,6 +2261,7 @@ const $ZodArray$1 = /*@__PURE__*/ $constructor$1("$ZodArray", (inst, def) => {
         }
         return payload; //handleArrayResultsAsync(parseResults, final);
     };
+    capSize(inst, arraySize);
 });
 function handlePropertyResult$1(result, final, key, input, optin, optout) {
     const isPresent = key in input;
@@ -2628,7 +2687,7 @@ function mergeValues$1(a, b) {
     if (a instanceof Date && b instanceof Date && +a === +b) {
         return { valid: true, data: a };
     }
-    if (isPlainObject$1(a) && isPlainObject$1(b)) {
+    if (isPlainObject$2(a) && isPlainObject$2(b)) {
         const bKeys = Object.keys(b);
         const sharedKeys = Object.keys(a).filter((key) => bKeys.indexOf(key) !== -1);
         const newObj = { ...a, ...b };
@@ -2730,7 +2789,7 @@ const $ZodRecord$1 = /*@__PURE__*/ $constructor$1("$ZodRecord", (inst, def) => {
     memo?.attach(inst);
     inst._zod.parse = (payload, ctx) => {
         const input = payload.value;
-        if (!isPlainObject$1(input)) {
+        if (!isPlainObject$2(input)) {
             payload.issues.push({
                 expected: "record",
                 code: "invalid_type",
@@ -3166,6 +3225,60 @@ function handlePipeResult$1(left, next, ctx) {
     }
     return next._zod.run({ value: left.value, issues: left.issues }, ctx);
 }
+const $ZodCodec = /*@__PURE__*/ $constructor$1("$ZodCodec", (inst, def) => {
+    $ZodType$1.init(inst, def);
+    defineLazyInternal(inst, "values", (zod) => zod.def.in._zod.values);
+    defineLazyInternal(inst, "optin", (zod) => zod.def.in._zod.optin);
+    defineLazyInternal(inst, "optout", (zod) => zod.def.out._zod.optout);
+    defineLazyInternal(inst, "propValues", (zod) => zod.def.in._zod.propValues);
+    inst._zod.parse = (payload, ctx) => {
+        const direction = ctx.direction || "forward";
+        if (direction === "forward") {
+            const left = def.in._zod.run(payload, ctx);
+            if (left instanceof Promise) {
+                return left.then((left) => handleCodecAResult(left, def, ctx));
+            }
+            return handleCodecAResult(left, def, ctx);
+        }
+        else {
+            const right = def.out._zod.run(payload, ctx);
+            if (right instanceof Promise) {
+                return right.then((right) => handleCodecAResult(right, def, ctx));
+            }
+            return handleCodecAResult(right, def, ctx);
+        }
+    };
+});
+function handleCodecAResult(result, def, ctx) {
+    if (result.issues.length) {
+        // prevent further checks
+        result.aborted = true;
+        return result;
+    }
+    const direction = ctx.direction || "forward";
+    if (direction === "forward") {
+        const transformed = def.transform(result.value, result);
+        if (transformed instanceof Promise) {
+            return transformed.then((value) => handleCodecTxResult(result, value, def.out, ctx));
+        }
+        return handleCodecTxResult(result, transformed, def.out, ctx);
+    }
+    else {
+        const transformed = def.reverseTransform(result.value, result);
+        if (transformed instanceof Promise) {
+            return transformed.then((value) => handleCodecTxResult(result, value, def.in, ctx));
+        }
+        return handleCodecTxResult(result, transformed, def.in, ctx);
+    }
+}
+function handleCodecTxResult(left, value, nextSchema, ctx) {
+    // Check if transform added any issues
+    if (left.issues.length) {
+        left.aborted = true;
+        return left;
+    }
+    return nextSchema._zod.run({ value, issues: left.issues }, ctx);
+}
 const $ZodReadonly$1 = /*@__PURE__*/ $constructor$1("$ZodReadonly", (inst, def) => {
     $ZodType$1.init(inst, def);
     defineLazyInternal(inst, "propValues", (zod) => zod.def.innerType._zod.propValues);
@@ -3994,6 +4107,13 @@ function _boolean$1(Class, params) {
     });
 }
 // @__NO_SIDE_EFFECTS__
+function _null$4(Class, params) {
+    return new Class({
+        type: "null",
+        ...normalizeParams$1(params),
+    });
+}
+// @__NO_SIDE_EFFECTS__
 function _unknown$1(Class) {
     return new Class({
         type: "unknown",
@@ -4214,6 +4334,63 @@ function _check$1(fn, params) {
     ch._zod.check = fn;
     return ch;
 }
+// @__NO_SIDE_EFFECTS__
+function _stringbool(Classes, _params) {
+    const params = normalizeParams$1(_params);
+    let truthyArray = params.truthy ?? ["true", "1", "yes", "on", "y", "enabled"];
+    let falsyArray = params.falsy ?? ["false", "0", "no", "off", "n", "disabled"];
+    if (params.case !== "sensitive") {
+        truthyArray = truthyArray.map((v) => (typeof v === "string" ? v.toLowerCase() : v));
+        falsyArray = falsyArray.map((v) => (typeof v === "string" ? v.toLowerCase() : v));
+    }
+    const truthySet = new Set(truthyArray);
+    const falsySet = new Set(falsyArray);
+    const _Codec = Classes.Codec ?? $ZodCodec;
+    const _Boolean = Classes.Boolean ?? $ZodBoolean$1;
+    const _String = Classes.String ?? $ZodString$1;
+    const stringSchema = new _String({ type: "string", error: params.error });
+    const booleanSchema = new _Boolean({ type: "boolean", error: params.error });
+    const codec = new _Codec({
+        type: "pipe",
+        in: stringSchema,
+        out: booleanSchema,
+        transform: ((input, payload) => {
+            let data = input;
+            if (params.case !== "sensitive")
+                data = data.toLowerCase();
+            if (truthySet.has(data)) {
+                return true;
+            }
+            else if (falsySet.has(data)) {
+                return false;
+            }
+            else {
+                payload.issues.push({
+                    code: "invalid_value",
+                    expected: "stringbool",
+                    values: [...truthySet, ...falsySet],
+                    input: payload.value,
+                    inst: codec,
+                    continue: false,
+                });
+                return {};
+            }
+        }),
+        reverseTransform: ((input, _payload) => {
+            if (input === true) {
+                return truthyArray[0] || "true";
+            }
+            else {
+                return falsyArray[0] || "false";
+            }
+        }),
+        error: params.error,
+    });
+    codec._zod.bag.truthy = truthyArray;
+    codec._zod.bag.falsy = falsyArray;
+    codec._zod.bag.case = params.case ?? "insensitive";
+    return codec;
+}
 
 function assignProps(target, ...sources) {
     for (const source of sources) {
@@ -5053,6 +5230,16 @@ const numberProcessor$1 = (schema, ctx, _json, params) => {
 const booleanProcessor$1 = (_schema, _ctx, json, _params) => {
     json.type = "boolean";
 };
+const nullProcessor$1 = (_schema, ctx, json, _params) => {
+    if (ctx.target === "openapi-3.0") {
+        json.type = "string";
+        json.nullable = true;
+        json.enum = [null];
+    }
+    else {
+        json.type = "null";
+    }
+};
 const neverProcessor$1 = (_schema, _ctx, json, _params) => {
     json.not = {};
 };
@@ -6063,6 +6250,14 @@ const ZodBoolean$1 = /*@__PURE__*/ $constructor$1("ZodBoolean", (inst, def) => {
 function boolean$2(params) {
     return _boolean$1(ZodBoolean$1, params);
 }
+const ZodNull$1 = /*@__PURE__*/ $constructor$1("ZodNull", (inst, def) => {
+    $ZodNull$1.init(inst, def);
+    ZodType$1.init(inst, def);
+    inst._zod.processJSONSchema = (ctx, json, params) => nullProcessor$1(inst, ctx, json);
+});
+function _null$3(params) {
+    return _null$4(ZodNull$1, params);
+}
 const ZodUnknown$1 = /*@__PURE__*/ $constructor$1("ZodUnknown", (inst, def) => {
     $ZodUnknown$1.init(inst, def);
     ZodType$1.init(inst, def);
@@ -6164,6 +6359,24 @@ function object$1(shape, params) {
     };
     return new ZodObject$1(def);
 }
+// strictObject
+function strictObject(shape, params) {
+    return new ZodObject$1({
+        type: "object",
+        shape,
+        catchall: never$1(),
+        ...normalizeParams$1(params),
+    });
+}
+// looseObject
+function looseObject(shape, params) {
+    return new ZodObject$1({
+        type: "object",
+        shape,
+        catchall: unknown$1(),
+        ...normalizeParams$1(params),
+    });
+}
 const ZodUnion$1 = /*@__PURE__*/ $constructor$1("ZodUnion", (inst, def) => {
     $ZodUnion$1.init(inst, def);
     ZodType$1.init(inst, def);
@@ -6436,6 +6649,10 @@ function pipe$1(in_, out) {
         // ...util.normalizeParams(params),
     });
 }
+const ZodCodec = /*@__PURE__*/ $constructor$1("ZodCodec", (inst, def) => {
+    ZodPipe$1.init(inst, def);
+    $ZodCodec.init(inst, def);
+});
 const ZodReadonly$1 = /*@__PURE__*/ $constructor$1("ZodReadonly", (inst, def) => {
     $ZodReadonly$1.init(inst, def);
     ZodType$1.init(inst, def);
@@ -6460,6 +6677,12 @@ function refine$1(fn, _params = {}) {
 function superRefine$1(fn, params) {
     return _superRefine$1(fn, params);
 }
+// stringbool
+const stringbool = (...args) => _stringbool({
+    Codec: ZodCodec,
+    Boolean: ZodBoolean$1,
+    String: ZodString$1,
+}, ...args);
 
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
 
@@ -23900,7 +24123,7 @@ const allowsEval = cached(() => {
         return false;
     }
 });
-function isPlainObject(o) {
+function isPlainObject$1(o) {
     if (isObject(o) === false)
         return false;
     // modified constructor
@@ -23920,7 +24143,7 @@ function isPlainObject(o) {
     return true;
 }
 function shallowClone(o) {
-    if (isPlainObject(o))
+    if (isPlainObject$1(o))
         return { ...o };
     if (Array.isArray(o))
         return [...o];
@@ -24016,7 +24239,7 @@ function omit(schema, mask) {
     return clone(schema, def);
 }
 function extend(schema, shape) {
-    if (!isPlainObject(shape)) {
+    if (!isPlainObject$1(shape)) {
         throw new Error("Invalid input to extend: expected a plain object");
     }
     const checks = schema._zod.def.checks;
@@ -24041,7 +24264,7 @@ function extend(schema, shape) {
     return clone(schema, def);
 }
 function safeExtend(schema, shape) {
-    if (!isPlainObject(shape)) {
+    if (!isPlainObject$1(shape)) {
         throw new Error("Invalid input to safeExtend: expected a plain object");
     }
     const def = mergeDefs(schema._zod.def, {
@@ -25782,7 +26005,7 @@ function mergeValues(a, b) {
     if (a instanceof Date && b instanceof Date && +a === +b) {
         return { valid: true, data: a };
     }
-    if (isPlainObject(a) && isPlainObject(b)) {
+    if (isPlainObject$1(a) && isPlainObject$1(b)) {
         const bKeys = Object.keys(b);
         const sharedKeys = Object.keys(a).filter((key) => bKeys.indexOf(key) !== -1);
         const newObj = { ...a, ...b };
@@ -25866,7 +26089,7 @@ const $ZodRecord = /*@__PURE__*/ $constructor("$ZodRecord", (inst, def) => {
     $ZodType.init(inst, def);
     inst._zod.parse = (payload, ctx) => {
         const input = payload.value;
-        if (!isPlainObject(input)) {
+        if (!isPlainObject$1(input)) {
             payload.issues.push({
                 expected: "record",
                 code: "invalid_type",
@@ -28439,270 +28662,1735 @@ object({
 });
 
 /**
- * @module constants
- * Shared identity constants for the jeeves-watcher ecosystem.
- * Consumed by both the service and plugin packages.
+ * @module schemas/sources
+ * Zod schemas for configured `sources` (named callback endpoints for non-file documents), source references and the callback contract. No I/O.
  */
-/** Component name shared across service and plugin descriptors. */
-const COMPONENT_NAME = 'watcher';
-/** npm package name for the service. */
-const SERVICE_PACKAGE = '@karmaniverous/jeeves-watcher';
-/** npm package name for the plugin. */
-const PLUGIN_PACKAGE = '@karmaniverous/jeeves-watcher-openclaw';
-/** Default watcher API port. */
-const DEFAULT_PORT = DEFAULT_PORTS.watcher;
-/** Default API values. */
-({
-    port: DEFAULT_PORTS.watcher});
+/**
+ * Body of a source name pattern (shared by the name and reference
+ * patterns): a lowercase letter, then 1-31 of `[a-z0-9-]`.
+ */
+const SOURCE_NAME_BODY = '[a-z][a-z0-9-]{1,31}';
+/** Pattern every source name must match (≥ 2 chars, so never a drive letter). */
+const SOURCE_NAME_PATTERN = new RegExp(`^${SOURCE_NAME_BODY}$`);
+/**
+ * Pattern of a source reference: `<name>://<id>`, where `<id>` is 1–512
+ * non-whitespace characters (`/`-separated segments allowed).
+ */
+const SOURCE_REFERENCE_PATTERN = new RegExp(`^${SOURCE_NAME_BODY}://\\S{1,512}$`);
+/** Placeholder in a source `url` template that is replaced with the document id. */
+const SOURCE_ID_PLACEHOLDER = '{id}';
+/** A source name, e.g. `app`. */
+const sourceNameSchema = string$2()
+    .regex(SOURCE_NAME_PATTERN, `Source name must match ${SOURCE_NAME_PATTERN.source}`)
+    .describe('Source name: lowercase letter, then 1-31 of [a-z0-9-].');
+/** A source reference, e.g. `app://chat/thread/123`. */
+const sourceReferenceSchema = string$2()
+    .regex(SOURCE_REFERENCE_PATTERN, `Source reference must match <name>://<id> (name ${SOURCE_NAME_PATTERN.source}, id 1-512 non-whitespace characters)`)
+    .describe('Source document reference: <name>://<id>.');
+/** Configuration of a single named source. */
+const sourceConfigSchema = object$1({
+    /** Callback URL template; must contain `{id}`. */
+    url: string$2()
+        .min(1)
+        .refine((url) => url.includes(SOURCE_ID_PLACEHOLDER), {
+        message: `url must contain the ${SOURCE_ID_PLACEHOLDER} placeholder`,
+    })
+        .describe('Callback URL template. {id} is replaced with the document id (each /-segment URL-encoded, slashes kept). Supports ${ENV_VAR} substitution.'),
+    /** Request headers sent with every callback (e.g. Authorization). */
+    headers: record$1(string$2(), string$2())
+        .optional()
+        .describe('Headers sent with every callback request (supports ${ENV_VAR} substitution).'),
+    /** Callback timeout in milliseconds. */
+    timeoutMs: number$2()
+        .int()
+        .positive()
+        .default(10000)
+        .describe('Callback timeout in milliseconds. Default: 10000.'),
+    /** Maximum parallel callbacks for this source. */
+    concurrency: number$2()
+        .int()
+        .positive()
+        .default(8)
+        .describe('Maximum parallel callbacks for this source (e.g. during reindex). Default: 8.'),
+});
+/** The `sources` config section: source name → source configuration. */
+const sourcesConfigSchema = record$1(sourceNameSchema, sourceConfigSchema)
+    .describe('Named sources for non-file documents, retrieved by callback. Keys are source names used in <name>://<id> references. Read at startup only.');
+/**
+ * A source document as returned by a source callback: a `GET` to the
+ * configured URL answered with `200` and an `application/json` body. The body
+ * is the record itself, as the owner stores it, with no envelope: any JSON
+ * object. A `404` means the document no longer exists (see
+ * {@link SOURCE_DOCUMENT_GONE_STATUS}); any other status is a transient failure.
+ */
+record$1(string$2(), unknown$1())
+    .describe('A source document: any JSON object returned by the callback.');
 
 /**
- * Shared endpoint catalog — single source of truth for the jeeves-watcher API.
- *
- * Both the CLI service and the OpenClaw plugin derive their registrations
- * from this declarative catalog, eliminating drift between the two.
+ * @module api/common
+ * Shared Zod building blocks for API request/response schemas: Qdrant filters, error bodies and path-or-source document targets. No I/O.
+ */
+/**
+ * A native Qdrant filter object schema (passed through to Qdrant
+ * unchanged), optionally with the message reported for a missing or
+ * non-object value.
  *
+ * @param error - Message for a missing or non-object filter.
+ * @returns The filter schema.
  */
+const qdrantFilter = (error) => record$1(string$2(), unknown$1(), error === undefined ? undefined : { error })
+    .describe('Native Qdrant filter object.');
+/** A native Qdrant filter object (passed through to Qdrant unchanged). */
+const qdrantFilterSchema = qdrantFilter();
+/** Message for a missing or non-object required `filter` (scan, points delete). */
+const FILTER_REQUIRED_MESSAGE = 'Missing required field: filter (object)';
+/** Boolean clauses of a Qdrant filter whose value is a condition list. */
+const FILTER_CLAUSES = ['must', 'should', 'must_not'];
+/** Every key a Qdrant filter object may carry (clauses plus `min_should`). */
+const FILTER_KEYS = new Set([...FILTER_CLAUSES, 'min_should']);
 /**
- * Canonical endpoint catalog for the jeeves-watcher API.
+ * Whether a value is a plain object (not `null`, not an array). The one
+ * definition shared by core and the service.
  *
- * Every entry describes a single HTTP endpoint exposed by the service.
- * Route handlers, plugin tools, and HTTP clients should reference these
- * descriptors rather than hard-coding paths and descriptions.
+ * @param value - Any value.
+ * @returns `true` for a non-null, non-array object.
  */
-const WATCHER_ENDPOINTS = [
-    {
-        name: 'status',
-        method: 'GET',
-        path: '/status',
-        description: 'Service health and status overview.',
-    },
-    {
-        name: 'metadata',
-        method: 'POST',
-        path: '/metadata',
-        description: 'Set or update metadata on a document by file path.',
-    },
-    {
-        name: 'render',
-        method: 'POST',
-        path: '/render',
-        description: 'Render a document through the template pipeline.',
-    },
-    {
-        name: 'searchFacets',
-        method: 'GET',
-        path: '/search/facets',
-        description: 'List available search facets and their values.',
-    },
-    {
-        name: 'scan',
-        method: 'POST',
-        path: '/scan',
-        description: 'Filter-only point query without vector search. Returns metadata for points matching a Qdrant filter.',
-    },
-    {
-        name: 'walk',
-        method: 'POST',
-        path: '/walk',
-        description: 'Walk watched filesystem paths with glob intersection. Returns matching file paths.',
-    },
-    {
-        name: 'search',
-        method: 'POST',
-        path: '/search',
-        description: 'Semantic search over indexed documents. Supports Qdrant filters.',
-    },
-    {
-        name: 'rebuildMetadata',
-        method: 'POST',
-        path: '/rebuild-metadata',
-        description: 'Rebuild metadata from enrichment store into vector points.',
-    },
-    {
-        name: 'reindex',
-        method: 'POST',
-        path: '/reindex',
-        description: 'Trigger a scoped reindex of watched files.',
-    },
-    {
-        name: 'issues',
-        method: 'GET',
-        path: '/issues',
-        description: 'Get runtime embedding failures. Shows files that failed processing and why.',
-    },
-    {
-        name: 'configSchema',
-        method: 'GET',
-        path: '/config/schema',
-        description: 'Get the JSON Schema for the configuration file.',
-    },
-    {
-        name: 'configMatch',
-        method: 'POST',
-        path: '/config/match',
-        description: 'Test file paths against config inference rules.',
-    },
-    {
-        name: 'config',
-        method: 'GET',
-        path: '/config',
-        description: 'Query service configuration with optional JSONPath.',
-    },
-    {
-        name: 'configValidate',
-        method: 'POST',
-        path: '/config/validate',
-        description: 'Validate a candidate config. Optionally test file paths against the config.',
-    },
-    {
-        name: 'configApply',
-        method: 'POST',
-        path: '/config/apply',
-        description: 'Apply a configuration patch.',
-    },
-    {
-        name: 'rulesRegister',
-        method: 'POST',
-        path: '/rules/register',
-        description: 'Register external inference rules.',
-    },
-    {
-        name: 'rulesUnregister',
-        method: 'DELETE',
-        path: '/rules/unregister',
-        description: 'Unregister external inference rules.',
-    },
-    {
-        name: 'rulesUnregisterBySource',
-        method: 'DELETE',
-        path: '/rules/unregister/:source',
-        description: 'Unregister all external inference rules from a source.',
-    },
-    {
-        name: 'pointsDelete',
-        method: 'POST',
-        path: '/points/delete',
-        description: 'Delete points from the vector store by filter.',
-    },
-    {
-        name: 'rulesReapply',
-        method: 'POST',
-        path: '/rules/reapply',
-        description: 'Re-apply inference rules to existing vector points.',
-    },
-    {
-        name: 'vcsStatus',
-        method: 'GET',
-        path: '/vcs/status',
-        description: 'VCS state for all roots: enabled state, tracked files, last commit, remote status, commit circuit breaker state.',
-    },
-    {
-        name: 'vcsHistory',
-        method: 'GET',
-        path: '/vcs/history',
-        description: 'Query change history by path or glob with optional date range.',
-    },
-    {
-        name: 'vcsShow',
-        method: 'GET',
-        path: '/vcs/show',
-        description: 'Retrieve file content at a specific version.',
-    },
-    {
-        name: 'vcsDiff',
-        method: 'GET',
-        path: '/vcs/diff',
-        description: 'Show what changed between two versions, or between a version and current.',
-    },
-    {
-        name: 'vcsCheckExclusion',
-        method: 'GET',
-        path: '/vcs/check-exclusion',
-        description: 'Check whether a path is excluded from version tracking and why.',
-    },
-    {
-        name: 'vcsRevert',
-        method: 'POST',
-        path: '/vcs/revert',
-        description: 'Restore files from a historical commit (forward-only reversion).',
-    },
-    {
-        name: 'vcsExclude',
-        method: 'POST',
-        path: '/vcs/exclude',
-        description: 'Manage .gitignore entries for version tracking exclusion.',
-    },
-];
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Whether a condition restricts anything. `{}` (an empty nested filter)
+ * does not; a nested filter (only clause keys) restricts when it has a
+ * condition itself; anything else (field, `is_empty`, `has_id`, `nested`, …,
+ * or a malformed value Qdrant will reject) counts as a condition.
+ */
+function isEffectiveCondition(condition) {
+    if (!isPlainObject(condition))
+        return true;
+    const keys = Object.keys(condition);
+    if (keys.length === 0)
+        return false;
+    return keys.every((key) => FILTER_KEYS.has(key))
+        ? hasFilterCondition(condition)
+        : true;
+}
+/** Whether a clause value (a condition or a list of them) has a condition. */
+const clauseHasCondition = (value) => Array.isArray(value)
+    ? value.some(isEffectiveCondition)
+    : isPlainObject(value) && isEffectiveCondition(value);
 /**
- * Look up an endpoint descriptor by name.
+ * Whether a Qdrant filter contains at least one condition. `{}`,
+ * `{ must: [] }`, filters whose clauses are all empty (recursively) and
+ * filters with only unknown keys are condition-free: they would match every
+ * point.
  *
- * @param name - The endpoint identifier.
- * @returns The matching {@link EndpointDescriptor}.
+ * @param filter - A Qdrant filter object.
+ * @returns True when the filter restricts the points it matches.
  */
-function getEndpoint(name) {
-    const ep = WATCHER_ENDPOINTS.find((e) => e.name === name);
-    if (!ep)
-        throw new Error(`Unknown endpoint: ${name}`);
-    return ep;
+function hasFilterCondition(filter) {
+    if (FILTER_CLAUSES.some((clause) => clauseHasCondition(filter[clause]))) {
+        return true;
+    }
+    const minShould = filter.min_should;
+    return isPlainObject(minShould) && clauseHasCondition(minShould.conditions);
 }
-
 /**
- * @module schemas/vcs
- * VCS (version control system) configuration schema for git-backed content versioning.
+ * A Qdrant filter that must contain at least one condition (see
+ * {@link hasFilterCondition}); used where a match-everything filter would be
+ * destructive (`POST /documents/delete`).
  */
+const nonEmptyQdrantFilterSchema = qdrantFilterSchema.refine(hasFilterCondition, { message: 'filter must contain at least one condition' });
 /**
- * Commit message generation configuration.
+ * Error body shape common to every watcher version: `error` plus optional
+ * `message` and `details`, no `code`. Responses from 0.20.0+ also carry a
+ * machine-readable `code`; `apiErrorBodySchema` (module `api/errors`)
+ * extends this schema with it.
  */
-const vcsCommitMessageConfigSchema = object$1({
-    /** Whether AI-generated commit messages are enabled. */
-    enabled: boolean$2()
-        .default(true)
-        .describe('Enable AI-generated commit messages. Default: true.'),
-    /** AI provider for commit message generation. */
-    provider: string$2()
-        .default('anthropic')
-        .describe('AI provider for commit message generation. Default: "anthropic".'),
-    /** AI model for commit message generation. */
-    model: string$2()
-        .default('claude-haiku-4-0')
-        .describe('AI model for commit message generation. Default: "claude-haiku-4-0".'),
-    /** API key for commit message provider. Supports env var substitution. */
-    apiKey: string$2()
-        .optional()
-        .describe('API key for commit message provider. Supports env var substitution (e.g., "${ANTHROPIC_API_KEY}").'),
+const apiErrorResponseSchema = object$1({
+    /** Short error description. */
+    error: string$2(),
+    /** Optional longer explanation. */
+    message: string$2().optional(),
+    /** Optional structured details (e.g. Zod issues for a 400). */
+    details: unknown$1().optional(),
 });
 /**
- * VCS retention policy configuration.
+ * Error detail attached to a per-document result or rejection (`code` is a
+ * machine-readable error code, e.g. an issue type).
  */
-const vcsRetentionConfigSchema = object$1({
-    /** Maximum age in days for retained versions. */
-    maxAgeDays: number$2()
-        .int()
-        .min(1)
-        .default(30)
-        .describe('Maximum age in days for retained versions. Default: 30.'),
-    /** Maximum number of versions to retain per file. */
-    maxVersions: number$2()
-        .int()
-        .min(1)
-        .default(100)
-        .describe('Maximum number of versions to retain per file. Default: 100.'),
-    /** Cron expression for squash schedule. */
-    squashCron: string$2()
-        .default('0 0 * * *')
-        .describe('Cron expression for squash schedule. Default: "0 0 * * *" (daily at midnight).'),
-});
+const documentErrorSchema = object$1({
+    /** Machine-readable error code. */
+    code: string$2(),
+    /** Human-readable error message. */
+    message: string$2(),
+    /** Optional structured details (e.g. AJV errors). */
+    details: unknown$1().optional(),
+});
+/** A file path target (non-empty). */
+const filePathSchema = string$2()
+    .min(1, 'path must be a non-empty string')
+    .describe('Absolute or watched file path.');
+/** Fields addressing a single document by file path or source reference. */
+const documentTargetShape = {
+    /** File path of a file document. */
+    path: filePathSchema.optional(),
+    /** Source reference of a source document (`<name>://<id>`). */
+    source: sourceReferenceSchema.optional(),
+};
 /**
- * Git commit author identity configuration.
+ * Refinement requiring exactly one of `path` or `source`.
+ *
+ * @param val - The object being validated.
+ * @param ctx - Zod refinement context.
  */
-const vcsAuthorConfigSchema = object$1({
-    /** Author name for git commits. */
-    name: string$2()
-        .min(1)
-        .default('jeeves-watcher')
-        .describe('Author name for git commits. Default: "jeeves-watcher".'),
-    /** Author email for git commits. */
-    email: string$2()
+function requireExactlyOneTarget(val, ctx) {
+    if ((val.path === undefined) === (val.source === undefined)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: val.path === undefined ? ['path'] : [],
+            message: 'Exactly one of path or source is required',
+        });
+    }
+}
+
+/**
+ * @module api/admin
+ * Request schemas of the administrative endpoints: POST /points/delete, POST /rules/register, DELETE /rules/unregister, POST /rules/reapply. The service parses their bodies with these, like every other route. No I/O.
+ */
+/** POST /points/delete request body. */
+const pointsDeleteRequestSchema = object$1({
+    /** Native Qdrant filter selecting the points to delete. */
+    filter: qdrantFilter(FILTER_REQUIRED_MESSAGE),
+});
+/** A virtual-rule source name: a non-empty string. */
+const ruleSourceSchema = string$2({ error: 'Missing required field: source' })
+    .min(1, { error: 'Missing required field: source' });
+const RULE_NAME_REQUIRED = 'Every rule must be an object with a name';
+/** POST /rules/register request body. */
+const rulesRegisterRequestSchema = object$1({
+    /** Registering source (e.g. a plugin name). */
+    source: ruleSourceSchema,
+    /** Inference rules; each needs a non-empty `name` (the rest is validated on registration). */
+    rules: array$1(looseObject({
+        name: string$2({ error: RULE_NAME_REQUIRED })
+            .min(1, { error: RULE_NAME_REQUIRED }),
+    }, { error: RULE_NAME_REQUIRED }), { error: 'Missing required field: rules (array)' }),
+});
+/** DELETE /rules/unregister request body. */
+const rulesUnregisterRequestSchema = object$1({
+    /** Source whose rules are removed. */
+    source: ruleSourceSchema,
+});
+/** POST /rules/reapply request body. */
+const rulesReapplyRequestSchema = object$1({
+    /** Globs selecting the indexed files to re-apply rules to. */
+    globs: array$1(string$2().min(1), {
+        error: 'Missing required field: globs (non-empty string array)',
+    })
+        .min(1, {
+        error: 'Missing required field: globs (non-empty string array)',
+    }),
+});
+/** POST /points/delete response body: how many points were deleted. */
+const pointsDeleteResponseSchema = object$1({
+    deleted: number$2().int().nonnegative(),
+});
+/** POST /rules/register response body. */
+const rulesRegisterResponseSchema = object$1({
+    source: string$2(),
+    registered: number$2().int().nonnegative(),
+    totalVirtualRules: number$2().int().nonnegative(),
+});
+/** Response body of both rule unregister routes. */
+const rulesUnregisterResponseSchema = object$1({
+    source: string$2(),
+    removed: boolean$2(),
+});
+/** Path parameters of DELETE /rules/unregister/:source. */
+const rulesUnregisterParamsSchema = object$1({
+    source: ruleSourceSchema,
+});
+/** POST /rules/reapply response body. */
+const rulesReapplyResponseSchema = object$1({
+    matched: number$2().int().nonnegative(),
+    updated: number$2().int().nonnegative(),
+});
+/** POST /rebuild-metadata request body: takes no fields. */
+const rebuildMetadataRequestSchema = object$1({});
+/** POST /rebuild-metadata response body. */
+const rebuildMetadataResponseSchema = object$1({ ok: literal(true) });
+
+/**
+ * @module api/changeSource
+ * Zod schema and type of `GET /status` `health.changeSource` (D133, D157): the change source and reconciliation counters. No I/O.
+ */
+/**
+ * Why a process exited for a service-manager restart (D196): a watch config
+ * change that needs a watcher rebuild, an error on a live parcel
+ * subscription, or a watched root gone. Windows parcel only.
+ */
+const restartCauseSchema = _enum$1(['watch-config-changed', 'subscription-error', 'root-gone'])
+    .describe('Why the previous process exited for a service-manager restart (D196).');
+/**
+ * Change-source health in `GET /status` `health.changeSource` (D133, D157):
+ * counts and timestamps only, never paths (D89).
+ */
+const changeSourceHealthSchema = object$1({
+    /** The running change source. */
+    source: _enum$1(['chokidar', 'parcel'])
+        .describe('The running change source.'),
+    /** Subscriptions re-created after an error since start (D131). */
+    resubscribes: number$2()
+        .describe('Subscriptions re-created after an error since start (D131); scheduled renewals are not counted. Always 0 under chokidar.'),
+    /** Roots currently unavailable (D109). */
+    unavailableRoots: number$2()
+        .describe('Roots currently marked unavailable (D109).'),
+    /** Synthetic events reconciliation has emitted since start (D90). */
+    reconcileEvents: number$2()
+        .describe('Synthetic events reconciliation has emitted since start (D90): a rising value means the source is missing events.'),
+    /** Reconciles that errored and emitted nothing since start (D90). */
+    reconcileErrors: number$2()
+        .describe('Reconciles that errored (walk failure, unreachable root, empty root walk against a non-empty inventory) and emitted nothing, since start (D90).'),
+    /** End of the most recent reconcile. */
+    lastReconcileAt: string$2()
+        .nullable()
+        .describe('End of the most recent reconcile (ISO), null before the first.'),
+    /** Duration of the most recent reconcile (walk and compare). */
+    lastReconcileDurationMs: number$2()
+        .nullable()
+        .describe('Duration of the most recent reconcile, walk and compare (ms), null before the first.'),
+    /** Paths in the stability ticker's pending set (D128). */
+    pendingStability: number$2()
+        .describe("Paths in the stability ticker's pending set (D128); a backlog that keeps growing means the ticker is falling behind."),
+    /** Duration of the most recent subscription renewal (D129). */
+    lastRenewDurationMs: number$2()
+        .nullable()
+        .describe('Duration of the most recent subscription renewal (ms, D129); null until the first, and always null under chokidar and on Windows.'),
+    /** Renewals that forced a source rebuild since start (D165). */
+    renewFailures: number$2()
+        .describe('Renewals whose unsubscribe rejected and forced a source rebuild, plus rejections during a rebuild, since start (D165, D176). Always 0 under chokidar.'),
+    /** Why the previous process exited for a restart (D196). */
+    lastRestartCause: restartCauseSchema
+        .nullable()
+        .describe('Why the previous process exited for a service-manager restart (D196: on Windows parcel never unsubscribes, so a watcher rebuild or a subscription recovery restarts the process); null when this process did not start after such an exit.'),
+    /** When the previous process asked for that restart. */
+    lastRestartAt: string$2()
+        .nullable()
+        .describe('When the previous process asked for that restart (ISO); null with lastRestartCause.'),
+})
+    .describe('Change-source health (D133, D157, D196).');
+
+/**
+ * @module api/configRoutes
+ * Request and response schemas for the config inspection routes: `GET /config/schema`, `POST /config/match` and `POST /config/validate`. Envelopes are closed objects; user content (the JSON Schema document, test-path metadata, a candidate config) is an open record (spec D51). No I/O.
+ */
+/** A config location and what is wrong (or notable) there. */
+const configIssueSchema = object$1({
+    path: string$2(),
+    message: string$2(),
+});
+/** Response body of `GET /config/schema`: the merged config JSON Schema document. */
+const getConfigSchemaResponseSchema = record$1(string$2(), unknown$1())
+    .describe('JSON Schema (draft 2020-12) for the watcher config.');
+/** Request body of `POST /config/match`. */
+const matchConfigRequestSchema = object$1({
+    paths: array$1(string$2(), { error: 'Request body must include "paths" array' })
+        .describe('File paths to test against the watch scope and rules.'),
+});
+/** Response body of `POST /config/match`: one entry per requested path, in order. */
+const matchConfigResponseSchema = object$1({
+    matches: array$1(object$1({
+        rules: array$1(string$2()),
+        watched: boolean$2(),
+    })),
+});
+/** Request body of `POST /config/validate`. */
+const validateConfigRequestSchema = object$1({
+    config: record$1(string$2(), unknown$1())
+        .optional()
+        .describe('Partial config merged over the current one; omit to check it.'),
+    testPaths: array$1(string$2())
+        .optional()
+        .describe('Paths to run through the candidate config.'),
+});
+/** Response body of `POST /config/validate`. */
+const validateConfigResponseSchema = object$1({
+    valid: boolean$2(),
+    errors: array$1(configIssueSchema).optional(),
+    warnings: array$1(configIssueSchema).optional(),
+    testResults: array$1(object$1({
+        path: string$2(),
+        matchedRules: array$1(string$2()),
+        metadata: record$1(string$2(), unknown$1()),
+        error: string$2().optional(),
+    }))
+        .optional(),
+});
+
+/**
+ * @module api/documentOps
+ * Zod request/response schemas for single-document operations POST /render and POST /metadata (path or source target). No I/O.
+ */
+/** Request body for `POST /render`: exactly one of `path` or `source`. */
+const renderRequestSchema = object$1(documentTargetShape)
+    .superRefine(requireExactlyOneTarget);
+/** Response body for `POST /render`. */
+const renderResponseSchema = object$1({
+    /** Output format (file extension without dot). */
+    renderAs: string$2(),
+    /** Rendered (or passthrough) content. */
+    content: string$2(),
+    /** Names of the rules that matched. */
+    rules: array$1(string$2()),
+    /** Resulting metadata. */
+    metadata: record$1(string$2(), unknown$1()),
+});
+/** Request body for `POST /metadata`: exactly one of `path` or `source`, plus metadata. */
+const metadataRequestSchema = object$1({
+    ...documentTargetShape,
+    /** Enrichment metadata to merge into the document's points. */
+    metadata: record$1(string$2(), unknown$1(), {
+        error: 'Missing required field: metadata (object)',
+    }),
+})
+    .superRefine(requireExactlyOneTarget);
+/** Response body for `POST /metadata`. */
+const metadataResponseSchema = object$1({
+    /** Always true on success. */
+    ok: literal(true),
+    /** Rules whose schemas validated the metadata. */
+    matched_rules: array$1(string$2()),
+});
+
+/**
+ * @module api/indexCheck
+ * Zod schema and type of `GET /status` `health.indexCheck` (D197): the state and counts of the index check that runs once after the start walk. No I/O.
+ */
+/**
+ * State of the index check at start (D197): `pending` until the start walk
+ * completes, `running`, then `done` or `failed` (the index could not be
+ * listed, or the watcher stopped or was rebuilt first; nothing more is
+ * deleted); `off` when `watch.indexCheckOnStart` is `false`.
+ */
+const indexCheckStateSchema = _enum$1(['pending', 'running', 'done', 'failed', 'off'])
+    .describe('Index check state: pending (the start walk is still running), running, done, failed (the index could not be listed, or the watcher stopped or was rebuilt first; nothing more is deleted) or off (watch.indexCheckOnStart is false).');
+/**
+ * Index-check health in `GET /status` `health.indexCheck` (D197): counts
+ * and timestamps only, never paths (D89).
+ */
+const indexCheckHealthSchema = object$1({
+    /** Where the check is. */
+    state: indexCheckStateSchema,
+    /** When it ended. */
+    at: string$2()
+        .nullable()
+        .describe('When the check ended (ISO), null until it is done or failed.'),
+    /** How long it took. */
+    durationMs: number$2()
+        .nullable()
+        .describe('How long the check took, listing and deletes (ms), null until it is done or failed.'),
+    /** File documents compared with the inventory. */
+    checked: number$2()
+        .describe('Indexed file documents compared with the inventory, under the roots that were checked.'),
+    /** Documents deleted. */
+    removed: number$2()
+        .describe('Indexed file documents deleted because their file is gone (deleted or moved away while the service was down).'),
+    /** Roots not checked. */
+    skippedRoots: number$2()
+        .describe('Watch roots not checked: unavailable, gone, unwatched, or whose start walk failed.'),
+    /** Roots over the cap. */
+    capped: number$2()
+        .describe('Watch roots where more than 10% of the indexed documents (once more than 20 are missing) or more than 1,000 were missing from the inventory: nothing was deleted there; run reindex prune deliberately.'),
+})
+    .describe('Index check at start (D197).');
+
+/**
+ * @module api/monitoring
+ * Zod response schemas for the read-only monitoring endpoints GET /status and GET /issues, including the issue record. No I/O.
+ */
+/** Response body for `GET /status` (standard Jeeves component status). */
+object$1({
+    /** Component name (`watcher`). */
+    name: string$2(),
+    /** Service version. */
+    version: string$2(),
+    /** Whole seconds since the API server (its status handler) was created. */
+    uptime: number$2(),
+    /** Overall status. */
+    status: _enum$1(['healthy', 'degraded', 'unhealthy']),
+    /** Component health: collection, reindex and initial-scan state. */
+    health: record$1(string$2(), unknown$1()),
+});
+/** Reindex state in `GET /status` `health.reindex`. */
+const reindexStatusSchema = object$1({
+    /** Whether a reindex is in progress. */
+    active: boolean$2(),
+    /** Active reindex scope (while active). */
+    scope: string$2().optional(),
+    /** ISO 8601 start time (while active). */
+    startedAt: string$2().optional(),
+    /** Files processed so far (while active). */
+    filesProcessed: number$2().optional(),
+    /** Files to process (while active). */
+    totalFiles: number$2().optional(),
+});
+/** Initial filesystem scan state in `GET /status` `health.initialScan`. */
+const initialScanStatusSchema = object$1({
+    /** Whether the initial scan is in progress. */
+    active: boolean$2(),
+    /** Files matched by the watch globs. */
+    filesMatched: number$2().optional(),
+    /** Files enqueued so far. */
+    filesEnqueued: number$2().optional(),
+    /** ISO 8601 start time. */
+    startedAt: string$2().optional(),
+    /** ISO 8601 completion time. */
+    completedAt: string$2().optional(),
+    /** Scan duration in milliseconds. */
+    durationMs: number$2().optional(),
+});
+/** VCS state in `GET /status` `health.vcs` (D86): roots, backlog, tripped breakers. */
+const vcsHealthSchema = object$1({
+    /** VCS-enabled roots. */
+    roots: number$2(),
+    /** Files queued or in flight, not yet committed, across roots. */
+    pending: number$2(),
+    /** Roots whose commit circuit breaker is tripped. */
+    trippedRoots: number$2(),
+    /** ISO 8601 time the longest-tripped breaker tripped, or null. */
+    oldestTrippedAt: string$2().nullable(),
+});
+/**
+ * State of one system payload index (D74, D154, D155): `building` until its
+ * background creation returns, then `ready`; `conflict` when the field
+ * already has another index type (left alone); `failed` when creation
+ * failed (retried at the next start).
+ */
+const systemIndexStateSchema = _enum$1(['building', 'ready', 'conflict', 'failed'])
+    .describe('System payload index state: building (background creation running), ready, conflict (the field has another index type; left alone) or failed (creation failed; retried at the next start).');
+/** System payload index states by field, in `health.collection.systemIndexes`. */
+const systemIndexesSchema = record$1(string$2(), systemIndexStateSchema)
+    .describe('System payload indexes the service creates whatever payloadIndexes says (chunk_index integer, file_path and matched_rules keyword), by field.');
+/**
+ * Embedding health in `GET /status` `health.embedding` (D88, D89): state and
+ * timestamps with error codes only, never provider text or paths.
+ */
+const embeddingHealthSchema = object$1({
+    /** `ok`, or `failing` (3+ failures and 60 s without a success). */
+    state: _enum$1(['ok', 'failing'])
+        .describe('ok, or failing: at least 3 embedding failures since the last success and 60 s without one. The first success returns it to ok.'),
+    /** Last successful call. */
+    lastSuccessAt: string$2()
+        .nullable()
+        .describe('Last successful embedding call (ISO), null before the first.'),
+    /** Most recent error. */
+    lastError: object$1({
+        at: string$2().describe('When (ISO).'),
+        code: string$2()
+            .describe('rate_limited, timeout, http_<status>, network or error (no provider text).'),
+    })
+        .nullable()
+        .describe('Most recent embedding error, null if none yet.'),
+    /** When the state turned failing. */
+    failingSince: string$2()
+        .nullable()
+        .describe('When the state turned failing (ISO), null while ok.'),
+    /** End of the stored provider back-off. */
+    backoffUntil: string$2()
+        .nullable()
+        .describe('End of the stored provider back-off (ISO, at most 5 minutes ahead), null if none.'),
+})
+    .describe('Embedding provider health (D88, D89).');
+/**
+ * `GET /status` `health`: collection, reindex and initial-scan state, or
+ * `{ error }` when the vector store is unreachable (status `degraded`).
+ * Loose and optional throughout, so new health keys pass through.
+ */
+const watcherHealthSchema = looseObject({
+    /** Vector store collection. */
+    collection: object$1({
+        /** Collection name. */
+        name: string$2(),
+        /** Indexed points. */
+        pointCount: number$2(),
+        /** Vector dimensions. */
+        dimensions: number$2(),
+        /** System payload index states (D74, D154, D155). */
+        systemIndexes: systemIndexesSchema.optional(),
+    })
+        .optional(),
+    /** Reindex state. */
+    reindex: reindexStatusSchema.optional(),
+    /** Initial scan state (once the scan tracker exists). */
+    initialScan: initialScanStatusSchema.optional(),
+    /** VCS state (when VCS is enabled on any root). */
+    vcs: vcsHealthSchema.optional(),
+    /** Embedding health (D88, D89). */
+    embedding: embeddingHealthSchema.optional(),
+    /** Change-source health (D133, D157). */
+    changeSource: changeSourceHealthSchema.optional(),
+    /** Index check at start (D197). */
+    indexCheck: indexCheckHealthSchema.optional(),
+    /** Why health could not be read (degraded). */
+    error: string$2().optional(),
+});
+/**
+ * Canonical issue codes, in one list (spec Decision 16.4).
+ *
+ * `type_collision` and `interpolation_error` predate 0.20.0; the rest cover
+ * processing failures (#255) and source documents; `too_large` marks a
+ * document over a `processing` ceiling (D44).
+ */
+const ISSUE_TYPES = [
+    'type_collision',
+    'interpolation_error',
+    'extraction_error',
+    'embedding_error',
+    'upsert_error',
+    'match_failed',
+    'rule_missing',
+    'no_content',
+    'source_unavailable',
+    'unsupported_content_type',
+    'too_large',
+];
+/** Schema for the canonical issue code carried by every issue record. */
+const issueTypeSchema = _enum$1(ISSUE_TYPES)
+    .describe('Issue code: type_collision (conflicting metadata types), interpolation_error (template rendering failure), extraction_error (reading, rule application or chunking failed), embedding_error (embedding provider failed), upsert_error (vector store write failed), match_failed (designated rule did not match), rule_missing (designated rule not found), no_content (nothing to embed), source_unavailable (source callback failed), unsupported_content_type (callback returned a non-JSON body), too_large (over a processing ceiling; its points were deleted).');
+/** Schema for a single issue record tracking a processing failure. */
+const issueRecordSchema = object$1({
+    /** Canonical issue code. */
+    type: issueTypeSchema,
+    /** Operation that failed (e.g. `Failed to process file`). */
+    operation: string$2().optional(),
+    /** Property name where the issue occurred. */
+    property: string$2().optional(),
+    /** Name(s) of the rule(s) involved in the issue. */
+    rules: array$1(string$2()).optional(),
+    /**
+     * Rule name for single-rule issues; for a source document, its designated
+     * rule (so an `issues` reindex can retry a document that has no points).
+     */
+    rule: string$2().optional(),
+    /** Declared types for type collision issues. */
+    types: array$1(string$2()).optional(),
+    /** Error message describing the failure. */
+    message: string$2(),
+    /** Optional structured details (e.g. the AJV errors of `match_failed`); JSON. */
+    details: unknown$1().optional(),
+    /** Unix timestamp (seconds) or ISO string of the last occurrence. */
+    timestamp: union$1([number$2(), string$2()]),
+});
+/** Response body for `GET /issues`: issue records keyed by document key. */
+const issuesResponseSchema = object$1({
+    /** Number of documents with issues. */
+    count: number$2().int().nonnegative(),
+    /** Issue records keyed by document key (file path or source reference). */
+    issues: record$1(string$2(), array$1(issueRecordSchema)),
+});
+
+/**
+ * @module api/documents
+ * Zod request/response schemas for source-document notification (POST /documents, 202 or ?wait=true) and deletion (POST /documents/delete). No I/O.
+ */
+/** Maximum number of documents in one `POST /documents` request. */
+const MAX_DOCUMENTS_PER_REQUEST = 100;
+/** Maximum number of references in one `POST /documents/delete` request. */
+const MAX_DELETE_SOURCES_PER_REQUEST = 1000;
+/**
+ * The `documents` array of a notify request: 1 to
+ * {@link MAX_DOCUMENTS_PER_REQUEST} items of the given schema.
+ *
+ * @param item - Schema of one document.
+ * @returns The bounded array schema.
+ */
+const documentsArray = (item) => array$1(item)
+    .min(1, 'documents must contain at least one entry')
+    .max(MAX_DOCUMENTS_PER_REQUEST, `documents must contain at most ${String(MAX_DOCUMENTS_PER_REQUEST)} entries`);
+/**
+ * A document notification: the reference of a changed source document and
+ * the rule that indexes it. Notify only: content is always retrieved through
+ * the source callback, so unknown keys (e.g. inline content) are rejected.
+ */
+const documentNotificationSchema = strictObject({
+    /** Source reference (`<name>://<id>`). */
+    source: sourceReferenceSchema,
+    /** Name of the inference rule that indexes the document. */
+    rule: string$2().min(1, 'rule must be a non-empty string'),
+});
+/** Request body for `POST /documents`. */
+object$1({
+    /** Documents to (re)index: 1 to {@link MAX_DOCUMENTS_PER_REQUEST}. */
+    documents: documentsArray(documentNotificationSchema),
+});
+/**
+ * Envelope the service parses `POST /documents` with: the shape of
+ * {@link documentsRequestSchema}, but `source` is any non-empty string, so a
+ * malformed reference rejects only its own document (`invalid_reference` in
+ * `rejected`) instead of the whole request. Shape errors (count, missing or
+ * empty `rule`, unknown keys) still fail the request with `400`.
+ */
+const documentsEnvelopeSchema = object$1({
+    /** Documents to (re)index: 1 to {@link MAX_DOCUMENTS_PER_REQUEST}. */
+    documents: documentsArray(documentNotificationSchema.extend({
+        /** Reference as submitted; validated per document. */
+        source: string$2().min(1, 'source must be a non-empty string'),
+    })),
+});
+/**
+ * Codes of notifications rejected by synchronous validation:
+ * `invalid_reference` (not `<name>://<id>`), `unknown_source` (name not in
+ * config `sources`), `invalid_id` (empty, `.` or `..` id segment),
+ * `rule_missing` (no rule of that name in the merged rule set) and
+ * `queue_stopped` (the service is shutting down).
+ */
+const documentRejectionCodeSchema = _enum$1([
+    'invalid_reference',
+    'unknown_source',
+    'invalid_id',
+    'rule_missing',
+    'queue_stopped',
+]);
+/**
+ * Query string for `POST /documents`. `wait` accepts the strings
+ * `true`/`false`/`1`/`0` (a query string never carries a JSON boolean).
+ */
+const documentsQuerySchema = object$1({
+    /** Process synchronously and return per-document results. */
+    wait: stringbool({ truthy: ['true', '1'], falsy: ['false', '0'] })
+        .optional()
+        .describe('Process synchronously and answer 200 with per-document results: true or 1 (false or 0, the default, answers 202).'),
+});
+/** Why a notification was rejected: a typed code plus a message. */
+const documentRejectionErrorSchema = documentErrorSchema
+    .omit({ details: true })
+    .extend({
+    /** Rejection code. */
+    code: documentRejectionCodeSchema,
+});
+/** A notification rejected by synchronous validation. */
+const documentRejectionSchema = object$1({
+    /** The reference as submitted. */
+    source: string$2(),
+    /** Why it was rejected. */
+    error: documentRejectionErrorSchema,
+});
+/** `202` response body for `POST /documents` (asynchronous, the default). */
+const documentsAcceptedResponseSchema = object$1({
+    /** References enqueued for processing. */
+    accepted: array$1(string$2()),
+    /** Notifications rejected by synchronous validation. */
+    rejected: array$1(documentRejectionSchema),
+});
+/** Outcome of processing one document synchronously. */
+const documentResultStatusSchema = _enum$1([
+    'indexed',
+    'unchanged',
+    'deleted',
+    'failed',
+]);
+/**
+ * Code of a failed per-document result: the issue type of a processing
+ * failure, or (with `?wait=true`) the rejection code of a notification that
+ * failed synchronous validation.
+ */
+const documentFailureCodeSchema = union$1([
+    issueTypeSchema,
+    documentRejectionCodeSchema,
+]);
+/** Failure detail of a per-document result: typed code, message, optional details. */
+const documentFailureSchema = documentErrorSchema.extend({
+    /** Issue type or rejection code. */
+    code: documentFailureCodeSchema,
+});
+/** Per-document result of `POST /documents?wait=true`. */
+const documentResultSchema = object$1({
+    /** The reference processed. */
+    source: string$2(),
+    /** Outcome. */
+    status: documentResultStatusSchema,
+    /** Number of chunks written (when indexed). */
+    chunks: number$2().int().nonnegative().optional(),
+    /** Rules that matched (when indexed or unchanged). */
+    matched_rules: array$1(string$2()).optional(),
+    /** Failure detail (when failed). */
+    error: documentFailureSchema.optional(),
+});
+/** `200` response body for `POST /documents?wait=true`. */
+const documentsResultsResponseSchema = object$1({
+    /** One result per submitted document. */
+    results: array$1(documentResultSchema),
+});
+/**
+ * Request body for `POST /documents/delete`: either explicit references or a
+ * Qdrant filter with at least one condition (a condition-free filter such as
+ * `{}` or `{ must: [] }` is rejected). The server constrains the filter to
+ * points carrying `source` and no `file_path`.
+ *
+ * One strict object with both selectors optional and a refinement requiring
+ * exactly one, because a catalog body must be a single Zod object (spec
+ * Design 3). It accepts exactly the requests 0.20.0's two-shape union did.
+ */
+const documentsDeleteRequestSchema = strictObject({
+    /** References of the documents to delete: 1 to {@link MAX_DELETE_SOURCES_PER_REQUEST}. */
+    sources: array$1(sourceReferenceSchema)
+        .min(1, 'sources must contain at least one reference')
+        .max(MAX_DELETE_SOURCES_PER_REQUEST, `sources must contain at most ${String(MAX_DELETE_SOURCES_PER_REQUEST)} references`)
+        .optional(),
+    /** Qdrant filter selecting the documents to delete (at least one condition). */
+    filter: nonEmptyQdrantFilterSchema.optional(),
+})
+    .superRefine((val, ctx) => {
+    if ((val.sources === undefined) === (val.filter === undefined)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [],
+            message: 'Exactly one of sources or filter is required',
+        });
+    }
+});
+/** Response body for `POST /documents/delete`. */
+const documentsDeleteResponseSchema = object$1({
+    /** Number of documents (not points) removed. */
+    deleted: number$2().int().nonnegative(),
+});
+
+/**
+ * @module api/errors
+ * Canonical machine-readable API error codes (`apiErrorCodeSchema`) and the error body every non-2xx watcher response carries (`apiErrorBodySchema`). No I/O.
+ */
+/**
+ * Every machine-readable code a non-2xx response can carry, in one list.
+ * Codes are stable: new codes may be added, existing ones never change
+ * meaning. The usual HTTP status is in {@link API_ERROR_STATUS}.
+ *
+ * - `invalid_request` (400): the body, query or parameters failed validation
+ *   (`details` holds the Zod issues when available), or the framework rejected
+ *   the request (malformed JSON, unsupported media type, body too large).
+ * - `unauthorized` (401): `api.apiKey` is set and the bearer token is missing
+ *   or wrong.
+ * - `path_not_watched` (403): the file path is outside the watched scope.
+ * - `not_found` (404): no such route, file, VCS root, commit content or
+ *   exclude pattern.
+ * - `source_not_indexed` (404): no stored point for the source reference, so
+ *   no designated rule is known.
+ * - `source_not_found` (404): the source callback answered `404`.
+ * - `unsupported_content_type` (422): the source callback returned a non-JSON
+ *   body.
+ * - `pipeline_error` (422): rendering or extraction failed; for a source
+ *   document `issueType` names the failing stage.
+ * - `confirm_required` (409): `POST /vcs/exclude` would untrack more than
+ *   100 files; nothing was written, and `untracked` holds the count. Repeat
+ *   with `confirm: true`.
+ * - `source_unavailable` (502): the source callback failed.
+ * - `not_available` (503): the feature is not available on this instance
+ *   (no source support, no filesystem watcher), or `POST /vcs/exclude`
+ *   waited 30 s for the root's git lock (`Retry-After: 30`). A prune reindex
+ *   (`POST /reindex`) without a vector store keeps its 0.19 status `400`.
+ * - `scan_in_progress` (503): the initial filesystem scan is still running;
+ *   retry later.
+ * - `embedding_unavailable` (503): the embedding provider's retry budget ran
+ *   out; honour `Retry-After`.
+ * - `internal_error` (500): an unexpected server-side failure.
+ */
+const API_ERROR_CODES = [
+    'invalid_request',
+    'unauthorized',
+    'path_not_watched',
+    'not_found',
+    'source_not_indexed',
+    'source_not_found',
+    'unsupported_content_type',
+    'pipeline_error',
+    'confirm_required',
+    'source_unavailable',
+    'not_available',
+    'scan_in_progress',
+    'embedding_unavailable',
+    'internal_error',
+];
+/** Schema for the machine-readable code of an API error response. */
+const apiErrorCodeSchema = _enum$1(API_ERROR_CODES)
+    .describe('Machine-readable API error code.');
+/**
+ * Body of every non-2xx watcher response (0.20.0+): the version-independent
+ * `apiErrorResponseSchema` (`error`, `message`, `details`) extended with
+ * `code` and `issueType`. `error` is the human-readable text earlier
+ * versions sent, kept unchanged for backward compatibility; branch on
+ * `code`, never on `error`. Endpoints may add further fields (e.g. `issues`
+ * on `POST /config/apply`).
+ */
+apiErrorResponseSchema.extend({
+    /** Machine-readable error code. */
+    code: apiErrorCodeSchema,
+    /** Issue type of the pipeline failure behind a source render error. */
+    issueType: issueTypeSchema.optional(),
+});
+
+/**
+ * @module api/facets
+ * Zod schemas for the facet endpoints: `GET /search/facets` (definitions, optionally scoped by `rules`) and `POST /search/facets/counts` (per-field value counts or ranges for a filter; spec Design 12). No I/O.
+ */
+/** Most fields one `POST /search/facets/counts` request may name. */
+const COUNT_FACETS_MAX_FIELDS = 20;
+/** Values per counted field when `limit` is omitted. */
+const COUNT_FACETS_DEFAULT_LIMIT = 100;
+/** Largest `limit` of `POST /search/facets/counts`. */
+const COUNT_FACETS_MAX_LIMIT = 1000;
+/** Query for `GET /search/facets`. */
+const listFacetsQuerySchema = object$1({
+    /** Comma-separated rule names that scope the list. */
+    rules: string$2()
+        .optional()
+        .describe('Comma-separated rule names (configured or registered at runtime): only fields those rules declare, with values recorded for their documents. Unknown names answer 400. Without it, every configured rule.'),
+});
+/** Response body for `GET /search/facets`: the facetable fields and their values. */
+const listFacetsResponseSchema = object$1({
+    facets: array$1(object$1({
+        field: string$2(),
+        type: string$2(),
+        uiHint: string$2(),
+        values: array$1(unknown$1()),
+        rules: array$1(string$2()),
+    })),
+});
+const FIELDS_MESSAGE = `fields must name 1 to ${String(COUNT_FACETS_MAX_FIELDS)} fields`;
+const LIMIT_MESSAGE = `limit must be between 1 and ${String(COUNT_FACETS_MAX_LIMIT)}`;
+/**
+ * Request body for `POST /search/facets/counts`. Unknown keys are rejected,
+ * so a misspelt option fails with `400` instead of being ignored.
+ */
+const countFacetsRequestSchema = strictObject({
+    /** Qdrant filter scoping the counts (e.g. a tenant condition). */
+    filter: qdrantFilterSchema
+        .optional()
+        .describe('Qdrant filter scoping the counts, as for search (e.g. a tenant condition).'),
+    /** Rule names: only documents of at least one of them are counted. */
+    rules: array$1(string$2().min(1, 'rule names must be non-empty'))
+        .min(1, 'rules must name at least one rule')
+        .optional()
+        .describe('Rule names (configured or registered at runtime): only documents that matched at least one of them are counted, each once. Unknown names answer 400.'),
+    /** Fields to count (each needs a payload index). */
+    fields: array$1(string$2().min(1, 'field names must be non-empty'), {
+        error: FIELDS_MESSAGE,
+    })
+        .min(1, FIELDS_MESSAGE)
+        .max(COUNT_FACETS_MAX_FIELDS, FIELDS_MESSAGE)
+        .describe(`Payload fields to count (1 to ${String(COUNT_FACETS_MAX_FIELDS)}). Each needs a payload index: keyword, integer or bool for value counts; integer, float or datetime for a range.`),
+    /** Most values returned per counted field. */
+    limit: number$2({ error: LIMIT_MESSAGE })
+        .int('limit must be an integer')
+        .min(1, LIMIT_MESSAGE)
+        .max(COUNT_FACETS_MAX_LIMIT, LIMIT_MESSAGE)
+        .optional()
+        .describe(`Most values per counted field, highest counts first (default ${String(COUNT_FACETS_DEFAULT_LIMIT)}, max ${String(COUNT_FACETS_MAX_LIMIT)}).`),
+});
+/** One counted value: how many documents hold it. */
+const facetValueCountSchema = object$1({
+    /** The payload value. */
+    value: union$1([string$2(), number$2(), boolean$2()]),
+    /** Documents (not chunks) holding the value. */
+    count: number$2().int().nonnegative(),
+});
+/** A bound of a range: a number, a date string, or null when nothing matched. */
+const rangeBoundSchema = union$1([number$2(), string$2(), _null$3()]);
+/** Range of a numeric or date field over the matching documents. */
+const facetRangeSchema = object$1({
+    /** Smallest value, or null when no matching document holds the field. */
+    min: rangeBoundSchema,
+    /** Largest value, or null when no matching document holds the field. */
+    max: rangeBoundSchema,
+});
+/** Response body for `POST /search/facets/counts`. */
+const countFacetsResponseSchema = object$1({
+    /** Per field: value counts (highest first), or a range. */
+    counts: record$1(string$2(), union$1([array$1(facetValueCountSchema), facetRangeSchema]))
+        .describe('Per requested field: value counts (documents, highest first), or { min, max } for a numeric or date field.'),
+});
+
+/**
+ * @module api/query
+ * Zod request/response schemas for the read endpoints POST /search, POST /scan and POST /walk. No I/O.
+ */
+/** Results `POST /search` returns when `limit` is omitted. */
+const SEARCH_DEFAULT_LIMIT = 10;
+/** Page size of `POST /scan` when `limit` is omitted. */
+const SCAN_DEFAULT_LIMIT = 100;
+/** Largest `POST /scan` page size. */
+const SCAN_MAX_LIMIT = 1000;
+/**
+ * Request body for `POST /search`. Unknown keys are rejected, so an
+ * unsupported option (e.g. `collapse`) fails with `400` instead of being
+ * silently ignored.
+ */
+const searchRequestSchema = strictObject({
+    /** Natural-language query text to embed. */
+    query: string$2()
+        .min(1, 'query must be a non-empty string')
+        .describe('Search query text.'),
+    /** Maximum results to return. Default: {@link SEARCH_DEFAULT_LIMIT}. */
+    limit: number$2()
+        .int()
+        .positive()
+        .optional()
+        .describe(`Max results (default ${String(SEARCH_DEFAULT_LIMIT)}).`),
+    /** Number of results to skip (pagination). */
+    offset: number$2()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe('Number of results to skip for pagination.'),
+    /** Optional Qdrant filter. */
+    filter: qdrantFilterSchema.optional().describe('Qdrant filter object.'),
+});
+/** A single search hit. */
+const searchResultSchema = object$1({
+    /** Point ID. */
+    id: string$2(),
+    /** Similarity (or fused) score. */
+    score: number$2(),
+    /** Point payload (system fields plus rule metadata). */
+    payload: record$1(string$2(), unknown$1()),
+});
+/** Response body for `POST /search`: hits ordered by score. */
+const searchResponseSchema = array$1(searchResultSchema);
+const SCAN_LIMIT_MESSAGE = `limit must be between 1 and ${String(SCAN_MAX_LIMIT)}`;
+/** Request body for `POST /scan`. */
+const scanRequestSchema = object$1({
+    /** Qdrant filter (required). */
+    filter: qdrantFilter(FILTER_REQUIRED_MESSAGE).describe('Qdrant filter object (required).'),
+    /** Page size (1 to {@link SCAN_MAX_LIMIT}). Default: {@link SCAN_DEFAULT_LIMIT}. */
+    limit: number$2({ error: SCAN_LIMIT_MESSAGE })
+        .int('limit must be an integer')
+        .min(1, SCAN_LIMIT_MESSAGE)
+        .max(SCAN_MAX_LIMIT, SCAN_LIMIT_MESSAGE)
+        .optional()
+        .describe(`Page size (default ${String(SCAN_DEFAULT_LIMIT)}, max ${String(SCAN_MAX_LIMIT)}).`),
+    /** Opaque cursor from a previous page. */
+    cursor: union$1([string$2(), number$2()])
+        .optional()
+        .describe('Opaque cursor from previous response for pagination.'),
+    /** Payload fields to return (projection). */
+    fields: array$1(string$2())
+        .optional()
+        .describe('Payload fields to return (projection).'),
+    /** Return only `{ count }`. */
+    countOnly: boolean$2()
+        .optional()
+        .describe('If true, return { count } instead of points.'),
+});
+/** A scrolled point (one entry of the `POST /scan` `points` page). */
+const scanPointSchema = object$1({
+    /** Point ID. */
+    id: string$2(),
+    /** Point payload (projected when `fields` is given). */
+    payload: record$1(string$2(), unknown$1()),
+});
+/** Response body for `POST /scan`: a page of points, or a count when `countOnly`. */
+const scanResponseSchema = union$1([
+    object$1({
+        /** Matched points. */
+        points: array$1(scanPointSchema),
+        /** Cursor for the next page, or null when exhausted. */
+        cursor: union$1([string$2(), number$2(), _null$3()]),
+    }),
+    object$1({
+        /** Number of matching points. */
+        count: number$2().int().nonnegative(),
+    }),
+]);
+/** Request body for `POST /walk`. */
+const walkRequestSchema = object$1({
+    globs: array$1(string$2())
+        .min(1)
+        .describe('Globs matched against the watched files.'),
+});
+/** Response body for `POST /walk`. */
+const walkResponseSchema = object$1({
+    paths: array$1(string$2()),
+    matchedCount: number$2().int().nonnegative(),
+    scannedRoots: array$1(string$2()),
+});
+
+/**
+ * @module api/reindex
+ * Zod request/response schemas for POST /reindex (scopes issues, full, rules, path, prune; path scope targets file paths or source references). No I/O.
+ */
+/** Reindex scopes, in documentation order. */
+const reindexScopeSchema = _enum$1(['issues', 'full', 'rules', 'path', 'prune'], {
+    error: 'Scope must be one of: issues, full, rules, path, prune',
+})
+    .describe('Reindex scope.');
+/**
+ * Scopes `configWatch.reindex` may trigger on a config change: `issues`,
+ * `full` and `rules` (`path` needs targets; auto-pruning is never
+ * allowed).
+ */
+const configWatchReindexScopeSchema = reindexScopeSchema.extract(['issues', 'full', 'rules'], { error: 'configWatch.reindex must be one of: issues, full, rules' });
+/** One or more file paths (a non-empty array or a single path). */
+const pathTargetsSchema = union$1([
+    filePathSchema,
+    array$1(filePathSchema).min(1, 'path must not be an empty array'),
+]);
+/** Maximum number of source references in one `POST /reindex` request. */
+const MAX_REINDEX_SOURCES_PER_REQUEST = 1000;
+/**
+ * One or more source references (a single reference, or an array of 1 to
+ * {@link MAX_REINDEX_SOURCES_PER_REQUEST}).
+ */
+const sourceTargetsSchema = union$1([
+    sourceReferenceSchema,
+    array$1(sourceReferenceSchema)
+        .min(1, 'source must not be an empty array')
+        .max(MAX_REINDEX_SOURCES_PER_REQUEST, `source must contain at most ${String(MAX_REINDEX_SOURCES_PER_REQUEST)} references`),
+]);
+/**
+ * Request body for `POST /reindex`.
+ *
+ * `scope` defaults to `issues`. Scope `path` requires exactly one of `path`
+ * or `source`; `rules` optionally narrows to `path`; `source` is only valid
+ * with scope `path`.
+ */
+const reindexRequestSchema = object$1({
+    /** Reindex scope. Default: `issues`. */
+    scope: reindexScopeSchema
+        .optional()
+        .describe('Reindex scope: "issues" re-processes documents that failed; "rules" re-applies inference rules without re-embedding; "full" re-embeds everything; "path" reindexes the given files or directories (`path`) or source references (`source`); "prune" deletes points for files no longer in watch scope.'),
+    /** File path(s) or globs for scopes `path` and `rules`. */
+    path: pathTargetsSchema.optional(),
+    /** Source reference(s) for scope `path`. */
+    source: sourceTargetsSchema.optional(),
+    /** Compute and return the plan without executing. */
+    dryRun: boolean$2()
+        .optional()
+        .describe('Return the blast-area plan (counts by root) without running the reindex.'),
+})
+    .superRefine((val, ctx) => {
+    if (val.scope === 'path') {
+        if ((val.path === undefined) === (val.source === undefined)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: val.path === undefined ? ['path'] : [],
+                message: 'Exactly one of path or source is required when scope is "path"',
+            });
+        }
+    }
+    else if (val.source !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['source'],
+            message: 'source is only valid when scope is "path"',
+        });
+    }
+});
+/** Blast-radius plan for a reindex operation. */
+const reindexPlanSchema = object$1({
+    /** Total points (prune) or files and source documents (other scopes) examined. */
+    total: number$2().int().nonnegative(),
+    /** Number of items to process. */
+    toProcess: number$2().int().nonnegative(),
+    /** Number of points to delete (prune only). */
+    toDelete: number$2().int().nonnegative(),
+    /** Counts grouped by watch root (files) or source name (source documents). */
+    byRoot: record$1(string$2(), number$2()),
+    /** True when results are partial. */
+    incomplete: boolean$2().optional(),
+});
+/** Response body for `POST /reindex`: started (async) or dry-run plan. */
+const reindexResponseSchema = object$1({
+    /** `started` (executing asynchronously) or `dry_run` (plan only). */
+    status: _enum$1(['started', 'dry_run']),
+    /** The scope requested. */
+    scope: reindexScopeSchema,
+    /** Plan (omitted for a live prune). */
+    plan: reindexPlanSchema.optional(),
+});
+
+/**
+ * @module api/vcs
+ * Zod request schemas for the version-history endpoints in the endpoint catalog (`GET /vcs/show`). No I/O.
+ */
+/**
+ * A required, non-empty string whose missing or empty value is reported as
+ * `error` (a schema-level `error` also words the schema's own checks, here
+ * `min(1)`).
+ *
+ * @param error - Message for a missing, non-string or empty value.
+ * @param description - Field description (OpenAPI and tool text).
+ * @returns The field schema.
+ */
+function requiredString(error, description) {
+    return string$2({ error }).min(1).describe(description);
+}
+/**
+ * A required, non-empty query parameter, reported as
+ * `Missing required query parameter: <name>`.
+ *
+ * @param name - Parameter name.
+ * @param description - Parameter description (OpenAPI and tool text).
+ * @returns The parameter schema.
+ */
+function requiredQueryParam(name, description) {
+    return requiredString(`Missing required query parameter: ${name}`, description);
+}
+/** Query string of `GET /vcs/show`. */
+const vcsShowQuerySchema = object$1({
+    /** Absolute path of the file inside a VCS-enabled watch root. */
+    path: requiredQueryParam('path', 'File path to retrieve.'),
+    /** Version identifier (a commit). */
+    commit: requiredQueryParam('commit', 'Version identifier.'),
+});
+/** Response body of `GET /vcs/status`. */
+const vcsStatusResponseSchema = object$1({
+    enabled: boolean$2(),
+    roots: array$1(object$1({
+        path: string$2(),
+        tracked: number$2().int().nonnegative(),
+        lastCommit: object$1({
+            hash: string$2(),
+            message: string$2(),
+            timestamp: string$2(),
+        })
+            .nullable(),
+        remoteUrl: string$2().nullable(),
+        lastPush: string$2().nullable(),
+        pushErrors: array$1(object$1({
+            /** ISO 8601 time of the failed push. */
+            timestamp: string$2(),
+            /** Why the push failed (credentials redacted). */
+            message: string$2(),
+        })),
+        /** The root's commit circuit breaker (null without a manager). */
+        breaker: object$1({
+            /** Consecutive commit failures since the last success. */
+            consecutiveFailures: number$2().int().nonnegative(),
+            /** Whether the breaker is tripped. */
+            tripped: boolean$2(),
+            /** ISO 8601 time of the current trip, or null. */
+            trippedAt: string$2().nullable(),
+            /** Message of the most recent failure, or null. */
+            lastError: string$2().nullable(),
+            /** Files queued or in flight, not yet committed. */
+            pendingCount: number$2().int().nonnegative(),
+        })
+            .nullable(),
+    })),
+});
+/** Query string of `GET /vcs/history`. */
+const vcsHistoryQuerySchema = object$1({
+    glob: requiredQueryParam('glob', 'Glob inside a VCS-enabled watch root.'),
+    since: string$2()
+        .optional()
+        .describe('Only commits after this date (any date git log accepts).'),
+    until: string$2()
+        .optional()
+        .describe('Only commits before this date (any date git log accepts).'),
+    limit: string$2().optional().describe('Most commits to return (default 20).'),
+});
+/** Response body of `GET /vcs/history`: commits touching the glob, newest first. */
+const vcsHistoryResponseSchema = array$1(object$1({
+    commit: string$2(),
+    message: string$2(),
+    timestamp: string$2(),
+    files: array$1(string$2()),
+}));
+/** Query string of `GET /vcs/diff`. */
+const vcsDiffQuerySchema = object$1({
+    glob: requiredQueryParam('glob', 'Glob inside a VCS-enabled watch root.'),
+    commit: requiredQueryParam('commit', 'Version to diff from.'),
+    commitEnd: string$2()
+        .optional()
+        .describe('Version to diff to (default: the working tree).'),
+});
+/** Response body of `GET /vcs/diff`: a unified diff, `text/plain`. */
+const vcsDiffResponseSchema = string$2();
+/** Query string of `GET /vcs/check-exclusion`. */
+const vcsCheckExclusionQuerySchema = object$1({
+    path: requiredQueryParam('path', 'Path inside a VCS-enabled watch root.'),
+});
+/**
+ * Response body of `GET /vcs/check-exclusion` (D82): whether git ignores the
+ * path and, when it does, the matching pattern, the file holding it
+ * (`.git/info/exclude` for a VCS-only exclusion) and its line number.
+ */
+const vcsCheckExclusionResponseSchema = object$1({
+    /** Whether git ignores the path (a tracked path never is). */
+    excluded: boolean$2(),
+    /** The matching pattern. */
+    rule: string$2().optional(),
+    /** The file holding the pattern, as git names it. */
+    source: string$2().optional(),
+    /** The pattern's 1-based line number in `source`. */
+    line: number$2().int().positive().optional(),
+});
+/** Request body of `POST /vcs/revert`. */
+const vcsRevertRequestSchema = object$1({
+    glob: requiredString('Missing required body parameters: glob, commit', 'Glob of files to restore.'),
+    commit: requiredString('Missing required body parameters: glob, commit', 'Version to restore from.'),
+    existingOnly: boolean$2()
+        .optional()
+        .describe('Restore only files that exist in the working tree.'),
+});
+/** Response body of `POST /vcs/revert`. */
+const vcsRevertResponseSchema = object$1({
+    restored: number$2().int().nonnegative(),
+    files: array$1(string$2()),
+});
+/** Most files `POST /vcs/exclude` untracks without `confirm: true` (D103). */
+const VCS_EXCLUDE_CONFIRM_THRESHOLD = 100;
+/** Request body of `POST /vcs/exclude` (Design 5, D81, D103). */
+const vcsExcludeRequestSchema = object$1({
+    glob: requiredString('Missing required body parameter: glob', "One gitignore pattern, absolute (under a VCS root) or relative to `root`. It is written root-anchored (`/` + the root-relative pattern) to the root's `.git/info/exclude`. Brackets are a character class: escape them to name a file literally (`Report \\[draft\\].docx`). A newline, a leading `!` or `#`, braces, or a pattern matching the whole root is refused."),
+    remove: boolean$2()
+        .optional()
+        .describe('Remove the pattern instead of adding it (from `.git/info/exclude`, else from the `.gitignore` a 0.20.0 exclude wrote). Files are not re-added; their next change is versioned again.'),
+    root: string$2()
+        .optional()
+        .describe('VCS root to write under (default: the root containing the glob); a glob outside it is refused.'),
+    confirm: boolean$2()
+        .optional()
+        .describe(`Required (true) when adding the pattern would untrack more than ${String(VCS_EXCLUDE_CONFIRM_THRESHOLD)} files.`),
+});
+/** Response body of `POST /vcs/exclude`. */
+const vcsExcludeResponseSchema = object$1({
+    ok: literal(true),
+    /** The file written: the root's `.git/info/exclude`, or the `.gitignore` a removed 0.20.0 pattern was in. */
+    file: string$2(),
+    action: _enum$1(['added', 'removed']),
+    /** Paths removed from the index (in HEAD or staged); 0 for `removed`. */
+    untracked: number$2().int().nonnegative(),
+});
+
+/**
+ * @module catalog/routes
+ * Shared parts of the watcher catalog entries: the bearer auth every entry but `status` takes, and the `route`/`vcsRoute` helpers giving an entry its name, method, path, description and auth. No I/O.
+ */
+/** Bearer-key auth (`api.apiKey`) required by every entry except `status`. */
+const bearer = { schemes: [{ in: 'bearer' }] };
+/**
+ * Name, method, path, description and auth of a bearer-protected entry.
+ *
+ * @param name - Entry name: verb-first (D77), the operation's one name.
+ * @param method - HTTP method.
+ * @param path - Route path.
+ * @param description - What the operation does.
+ */
+function route(name, method, path, description) {
+    return { name, method, path, description, auth: bearer };
+}
+/**
+ * Description suffix of every entry the service serves only while version
+ * control is on (spec Design 3): with VCS off, the route answers the
+ * not-found 404 an unregistered route sends.
+ */
+const VCS_DISABLED_NOTE = 'Answers 404 `not_found` when version control is disabled (`vcs.enabled: false`).';
+/**
+ * {@link route} for a version-control entry: its description ends with
+ * {@link VCS_DISABLED_NOTE}.
+ *
+ * @param name - Entry name.
+ * @param method - HTTP method.
+ * @param path - Route path.
+ * @param description - What the operation does.
+ */
+function vcsRoute(name, method, path, description) {
+    return route(name, method, path, `${description} ${VCS_DISABLED_NOTE}`);
+}
+
+/**
+ * @module catalog/destructiveEntries
+ * The watcher catalog's `destructive` entries, in catalog order (spec Design 3 kinds). No I/O.
+ */
+/** The `destructive` entries. */
+const DESTRUCTIVE_ENTRIES = [
+    {
+        ...route('deleteDocuments', 'POST', '/documents/delete', 'Delete source documents by reference or by Qdrant filter (at least one condition; constrained to points carrying source and no file_path). The route waits at most 10 s for each document lock; if one stays busy it answers 503 `not_available` with `Retry-After: 10`, and documents already deleted stay deleted (retry to finish).'),
+        body: documentsDeleteRequestSchema,
+        response: documentsDeleteResponseSchema,
+        kind: 'destructive',
+    },
+    {
+        ...route('deletePoints', 'POST', '/points/delete', 'Delete points from the vector store by filter.'),
+        body: pointsDeleteRequestSchema,
+        response: pointsDeleteResponseSchema,
+        kind: 'destructive',
+    },
+    {
+        ...route('unregisterRules', 'DELETE', '/rules/unregister', 'Unregister external inference rules.'),
+        body: rulesUnregisterRequestSchema,
+        response: rulesUnregisterResponseSchema,
+        kind: 'destructive',
+    },
+    {
+        ...route('unregisterRulesBySource', 'DELETE', '/rules/unregister/:source', 'Unregister all external inference rules from a source.'),
+        params: rulesUnregisterParamsSchema,
+        response: rulesUnregisterResponseSchema,
+        kind: 'destructive',
+    },
+    {
+        ...vcsRoute('revertVcs', 'POST', '/vcs/revert', 'Restore files from a historical commit (forward-only reversion).'),
+        body: vcsRevertRequestSchema,
+        response: vcsRevertResponseSchema,
+        kind: 'destructive',
+    },
+    {
+        // D103: it untracks files, ending their history.
+        ...vcsRoute('excludeVcsPath', 'POST', '/vcs/exclude', 'Exclude a path from version history (VCS-only: it stays in search) or remove the exclusion. The glob is a gitignore pattern, so brackets are a character class: escape them to name a file literally (`Report \\[draft\\].docx`). Adding a pattern also untracks the tracked files it matches, in one commit (history stops for them; the files stay on disk and in search); `remove` does not restore that history. More than ' +
+            String(VCS_EXCLUDE_CONFIRM_THRESHOLD) +
+            " files to untrack need `confirm: true` (else 409 `confirm_required` with `untracked`, nothing written). The route waits at most 30 s for the root's git lock, then answers 503 `not_available` with `Retry-After: 30`, nothing written. A glob outside an explicit `root` is 400; a glob under no VCS root is 404."),
+        body: vcsExcludeRequestSchema,
+        response: vcsExcludeResponseSchema,
+        kind: 'destructive',
+    },
+];
+
+/**
+ * @module catalog/readEntries
+ * The watcher catalog's `read` entries, in catalog order (spec Design 3 kinds). No I/O.
+ */
+/** The `read` entries. */
+const READ_ENTRIES = [
+    {
+        ...route('getConfigSchema', 'GET', '/config/schema', 'Get the JSON Schema for the configuration file.'),
+        response: getConfigSchemaResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...route('matchConfig', 'POST', '/config/match', 'Test file paths against config inference rules.'),
+        body: matchConfigRequestSchema,
+        response: matchConfigResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...route('validateConfig', 'POST', '/config/validate', 'Validate a candidate config. Optionally test file paths against the config.'),
+        body: validateConfigRequestSchema,
+        response: validateConfigResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...route('search', 'POST', '/search', 'Semantic search over indexed documents. Supports Qdrant filters.'),
+        body: searchRequestSchema,
+        response: searchResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...route('scan', 'POST', '/scan', 'Filter-only point query without vector search. Returns metadata for points matching a Qdrant filter.'),
+        body: scanRequestSchema,
+        response: scanResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...route('listFacets', 'GET', '/search/facets', 'List available search facets and their values: every field a rule schema gives a uiHint or enum, with its declared or recorded values. With `rules`, only the fields and values of those rules.'),
+        query: listFacetsQuerySchema,
+        response: listFacetsResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...route('countFacets', 'POST', '/search/facets/counts', 'Count the values of payload fields over the documents matching a filter (each document once, not each chunk), or give { min, max } for a numeric or date field. Counts are approximate (Qdrant facet estimates); ranges are exact. `rules` keeps only documents of those rules. Each field needs a payload index (else 400). Fields are counted 4 at a time within a 10 s budget; past it the route answers 503 `not_available` naming the fields not counted. It also answers 503 until the `chunk_index` system index is ready, and with `rules` until `matched_rules` is.'),
+        body: countFacetsRequestSchema,
+        response: countFacetsResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...route('render', 'POST', '/render', 'Render a document (file path, or source reference retrieved through its callback) through the template pipeline.'),
+        body: renderRequestSchema,
+        response: renderResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...route('walk', 'POST', '/walk', 'Walk watched filesystem paths with glob intersection. Returns matching file paths.'),
+        body: walkRequestSchema,
+        response: walkResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...route('listIssues', 'GET', '/issues', 'Get runtime processing failures. Shows the documents (file path or source reference) that failed processing and why.'),
+        response: issuesResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...vcsRoute('getVcsStatus', 'GET', '/vcs/status', 'VCS state for all roots: enabled state, tracked files, last commit, remote status, commit circuit breaker state.'),
+        response: vcsStatusResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...vcsRoute('listVcsHistory', 'GET', '/vcs/history', 'Query change history by path or glob with optional date range.'),
+        query: vcsHistoryQuerySchema,
+        response: vcsHistoryResponseSchema,
+        kind: 'read',
+    },
+    {
+        ...vcsRoute('showVcsFile', 'GET', '/vcs/show', 'Retrieve file content at a specific version. The reply is the raw file content; its content-type follows the file extension.'),
+        query: vcsShowQuerySchema,
+        response: string$2(),
+        contentType: 'text/plain',
+        kind: 'read',
+    },
+    {
+        ...vcsRoute('diffVcs', 'GET', '/vcs/diff', 'Show what changed between two versions, or between a version and current. The reply is a unified diff.'),
+        query: vcsDiffQuerySchema,
+        response: vcsDiffResponseSchema,
+        contentType: 'text/plain',
+        kind: 'read',
+    },
+    {
+        ...vcsRoute('checkVcsExclusion', 'GET', '/vcs/check-exclusion', 'Check whether a path is excluded from version tracking and why.'),
+        query: vcsCheckExclusionQuerySchema,
+        response: vcsCheckExclusionResponseSchema,
+        kind: 'read',
+    },
+];
+
+/**
+ * @module catalog/writeEntries
+ * The watcher catalog's `write` entries, in catalog order (spec Design 3 kinds). No I/O.
+ */
+/** The `write` entries. */
+const WRITE_ENTRIES = [
+    {
+        ...route('setMetadata', 'POST', '/metadata', 'Set or update metadata on a document by file path or source reference. While the document is being processed the route waits at most 10 s for its lock, then answers 503 `not_available` with `Retry-After: 10`, nothing changed (retry).'),
+        body: metadataRequestSchema,
+        response: metadataResponseSchema,
+        kind: 'write',
+    },
+    {
+        ...route('reindex', 'POST', '/reindex', 'Trigger a scoped reindex of watched files (scope path also accepts source references).'),
+        body: reindexRequestSchema,
+        response: reindexResponseSchema,
+        kind: 'write',
+    },
+    {
+        ...route('notifyDocuments', 'POST', '/documents', 'Notify changed source documents ({ source, rule }); queued and coalesced (202), or processed synchronously with ?wait=true. Answers 202 with accepted and rejected references, or with `wait=true` 200 with per-document results.'),
+        query: documentsQuerySchema,
+        body: documentsEnvelopeSchema,
+        response: union$1([
+            documentsAcceptedResponseSchema,
+            documentsResultsResponseSchema,
+        ]),
+        kind: 'write',
+    },
+    {
+        ...route('registerRules', 'POST', '/rules/register', 'Register external inference rules.'),
+        body: rulesRegisterRequestSchema,
+        response: rulesRegisterResponseSchema,
+        kind: 'write',
+    },
+    {
+        ...route('reapplyRules', 'POST', '/rules/reapply', 'Re-apply inference rules to existing vector points. The route waits at most 10 s for each document lock; if one stays busy it answers 503 `not_available` with `Retry-After: 10`, and documents already updated keep their update (retry to finish).'),
+        body: rulesReapplyRequestSchema,
+        response: rulesReapplyResponseSchema,
+        kind: 'write',
+    },
+    {
+        ...route('rebuildMetadata', 'POST', '/rebuild-metadata', 'Rebuild the enrichment store from vector point payloads (file points only).'),
+        body: rebuildMetadataRequestSchema,
+        response: rebuildMetadataResponseSchema,
+        kind: 'write',
+    },
+];
+
+/**
+ * @module catalog
+ * The watcher's endpoint catalog (`WATCHER_CATALOG`): one Zod-described entry per route, from which the service's routes and validation, the OpenAPI document, the SDK client, the CLI and the plugin's tools are derived. No I/O.
+ *
+ * @remarks
+ * Holds every route (30 entries; spec Design 3, `countFacets` from Design
+ * 12), each with its `kind`, listed by kind in `catalog/`. Entry
+ * names are verb-first (D77, Design 14), and each is its operation's one
+ * name: catalog entry, SDK method, OpenAPI `operationId` and, through
+ * `toToolName`, plugin tool name. The catalog is the only route list
+ * (D41).
+ */
+/** The watcher endpoint catalog. */
+const WATCHER_CATALOG = defineCatalog([
+    ...standardEntries('watcher', {
+        auth: { config: bearer },
+        healthSchema: watcherHealthSchema,
+    }),
+    ...READ_ENTRIES,
+    ...WRITE_ENTRIES,
+    ...DESTRUCTIVE_ENTRIES,
+]);
+
+/**
+ * @module constants
+ * Shared identity constants for the jeeves-watcher ecosystem.
+ * Consumed by both the service and plugin packages.
+ */
+/** Component name shared across service and plugin descriptors. */
+const COMPONENT_NAME = 'watcher';
+/** npm package name for the service. */
+const SERVICE_PACKAGE = '@karmaniverous/jeeves-watcher';
+/** npm package name for the plugin. */
+const PLUGIN_PACKAGE = '@karmaniverous/jeeves-watcher-openclaw';
+/** Default watcher API port. */
+const DEFAULT_PORT = DEFAULT_PORTS.watcher;
+/** Default API values. */
+({
+    port: DEFAULT_PORTS.watcher});
+/** Default reindex values. */
+const REINDEX_DEFAULTS = {
+    /** Files (and source documents, and stored-rule lookups) in flight at once. */
+    concurrency: 50,
+};
+/**
+ * Default processing ceilings (D44, D64): from the 2026-10-31 corpus survey,
+ * which only the single largest document exceeded.
+ */
+const PROCESSING_DEFAULTS = {
+    /** 64 MiB, checked with `stat` before extraction. */
+    maxFileBytes: '64m',
+    maxChunksPerFile: 5000,
+    /** 8 MiB of extracted text (UTF-8 bytes). */
+    maxTextBytes: '8m',
+};
+
+/**
+ * @module httpContract
+ * The HTTP client constant the CLI and the plugin share: the environment variable holding the watcher API bearer key. Request building and error mapping live in jeeves's catalog client and the SDK's `WatcherError` (spec #281 D36, D53). Pure.
+ */
+/** Environment variable holding the watcher API bearer key for clients (CLI, plugin). */
+const API_KEY_ENV_VAR = 'JEEVES_WATCHER_API_KEY';
+
+/**
+ * @module promptRules
+ * Always-in-context watcher rules (descriptor `promptRules`), injected by the plugin through `before_prompt_build`. Static text; no side effects.
+ *
+ * @remarks
+ * Live numbers (point counts, configured score thresholds, VCS roots) are
+ * served by `watcher_status` and `watcher_config`, and detail lives in the
+ * skill ({@link WATCHER_SKILL}).
+ */
+/** Static watcher rules the agent must see on every turn. */
+const WATCHER_PROMPT_RULES = [
+    '## Watcher',
+    'This environment includes a semantic search index over the document archive (`watcher_search`).',
+    '- **Escalation rule:** Use `memory_search` for personal operational notes, decisions, and rules. Escalate to `watcher_search` when memory is thin, or when searching the broader archive (tickets, docs, code). ALWAYS use `watcher_search` BEFORE filesystem commands (exec, grep) when looking for information in indexed paths.',
+    '- **Scan-first rule:** For structural queries (file enumeration, staleness checks, domain listing, counts), use `watcher_scan` instead of `watcher_search`. Scan does not use embeddings and does not accept a query string.',
+    '- **Search-first rule:** When finding, reading, or modifying files in indexed paths, run `watcher_search` FIRST, even if you already know the file path. Direct filesystem access is for acting on search results, not bypassing them.',
+    '- **Scores:** strong / relevant / noise thresholds apply only when configured at `$.search.scoreThresholds` (query with `watcher_config`); there are no defaults. When configured, discard noise; if all results are noise, broaden the query.',
+    '- **Inventory on demand (`watcher_config`):** inference rules `$.inferenceRules[*]`, watched paths `$.watch.paths[*]`, ignored paths `$.watch.ignored[*]`. Version history: `watcher_list_vcs_history`, `watcher_diff_vcs`, `watcher_show_vcs_file`. See the jeeves-watcher skill for detail.',
+].join('\n');
+
+/**
+ * @module reservedFields
+ * Reserved system payload field names (named constants plus the full list) that rule schema properties should not use, and the system payload indexes. Pure helpers, no I/O.
+ */
+/**
+ * Payload fields written by the watcher itself, by role. The single
+ * definition of these names: the service's pipeline constants and
+ * {@link RESERVED_PAYLOAD_FIELDS} derive from it.
+ */
+const PAYLOAD_FIELD = {
+    /** Normalized file path (file points only). */
+    filePath: 'file_path',
+    /** Source reference `<name>://<id>` (source points only). */
+    source: 'source',
+    /** Designated rule of a source document (source points only). */
+    sourceRule: 'source_rule',
+    /** Zero-based chunk index. */
+    chunkIndex: 'chunk_index',
+    /** The chunk text. */
+    chunkText: 'chunk_text',
+    /** Total number of chunks of the document. */
+    totalChunks: 'total_chunks',
+    /** SHA-256 hash of the embedded text. */
+    contentHash: 'content_hash',
+    /** Names of the rules that matched. */
+    matchedRules: 'matched_rules',
+    /** 1-indexed line where the chunk starts. */
+    lineStart: 'line_start',
+    /** 1-indexed line where the chunk ends. */
+    lineEnd: 'line_end',
+    /** Creation timestamp (unix seconds). */
+    createdAt: 'created_at',
+    /** Modification timestamp (unix seconds). */
+    modifiedAt: 'modified_at',
+};
+/**
+ * Payload fields written by the watcher itself. System fields overwrite rule
+ * metadata on upsert, so a rule schema property with one of these names is
+ * silently shadowed; config validation warns about it.
+ */
+const RESERVED_PAYLOAD_FIELDS = Object.values(PAYLOAD_FIELD);
+/**
+ * Fields the watcher always keeps a keyword payload index on. They cannot be
+ * configured in `vectorStore.payloadIndexes`.
+ */
+const SYSTEM_PAYLOAD_INDEX_FIELDS = [
+    PAYLOAD_FIELD.source,
+    PAYLOAD_FIELD.sourceRule,
+];
+new Set(RESERVED_PAYLOAD_FIELDS);
+
+/**
+ * @module schemas/byteSize
+ * Byte-size settings (Design 10): a number of bytes, or a string with a `k`, `m` or `g` suffix read as binary units (`10m` = 10,485,760 bytes). One schema and one parser for every byte-size key.
+ */
+/** A byte-size string: digits (optionally with a decimal part) and an optional k, m or g suffix. */
+const BYTE_SIZE_PATTERN = /^\s*(\d+(?:\.\d+)?)\s*([kmg]?)\s*$/i;
+/** A byte-size setting: bytes, or a string such as `10m` (binary units). */
+const byteSizeSchema = union$1([
+    number$2().int().min(0),
+    string$2()
+        .regex(BYTE_SIZE_PATTERN, 'Expected a byte size: a number, or a number with a k, m or g suffix (binary units)'),
+]);
+
+/**
+ * @module schemas/vcs
+ * VCS (version control system) configuration schema for git-backed content versioning.
+ */
+/**
+ * Commit message generation configuration.
+ */
+const vcsCommitMessageConfigSchema = object$1({
+    /** Whether AI-generated commit messages are enabled. */
+    enabled: boolean$2()
+        .default(true)
+        .describe('Enable AI-generated commit messages. Default: true.'),
+    /** AI provider for commit message generation. */
+    provider: string$2()
+        .default('anthropic')
+        .describe('AI provider for commit message generation. Default: "anthropic".'),
+    /** AI model for commit message generation. */
+    model: string$2()
+        .default('claude-haiku-4-0')
+        .describe('AI model for commit message generation. Default: "claude-haiku-4-0".'),
+    /** API key for commit message provider. Supports env var substitution. */
+    apiKey: string$2()
+        .optional()
+        .describe('API key for commit message provider. Supports env var substitution (e.g., "${ANTHROPIC_API_KEY}").'),
+});
+/**
+ * VCS retention policy configuration.
+ */
+const vcsRetentionConfigSchema = object$1({
+    /** Maximum age in days for retained versions. */
+    maxAgeDays: number$2()
+        .int()
+        .min(1)
+        .default(30)
+        .describe('Maximum age in days for retained versions. Default: 30.'),
+    /** Maximum number of versions to retain per file. */
+    maxVersions: number$2()
+        .int()
+        .min(1)
+        .default(100)
+        .describe('Maximum number of versions to retain per file. Default: 100.'),
+    /** Cron expression for squash schedule. */
+    squashCron: string$2()
+        .default('0 0 * * *')
+        .describe('Cron expression for squash schedule. Default: "0 0 * * *" (daily at midnight).'),
+});
+/**
+ * Git commit author identity configuration.
+ */
+const vcsAuthorConfigSchema = object$1({
+    /** Author name for git commits. */
+    name: string$2()
+        .min(1)
+        .default('jeeves-watcher')
+        .describe('Author name for git commits. Default: "jeeves-watcher".'),
+    /** Author email for git commits. */
+    email: string$2()
         .min(1)
         .default('watcher@localhost')
         .describe('Author email for git commits. Default: "watcher@localhost".'),
@@ -28766,11 +30454,19 @@ const vcsConfigSchema = object$1({
         .min(1000)
         .default(300000)
         .describe('Circuit breaker cooldown in ms before a half-open recovery attempt. Default: 300000 (5 minutes).'),
-    /** Git branch name for VCS operations. SquashManager and startup recovery use this instead of dynamic detection. */
+    /** Git branch name for VCS operations. Squash and the startup branch check use this instead of dynamic detection. */
     branch: string$2()
         .min(1)
         .default('master')
         .describe('Git branch name for VCS operations. Default: "master".'),
+    /**
+     * Size cap for versioned files (D80). A new file over it is not staged;
+     * a tracked file that grows past it is untracked in its own commit.
+     * `0` disables the cap. Read at each staging (no restart needed).
+     */
+    maxFileBytes: byteSizeSchema
+        .optional()
+        .describe("Size cap for versioned files: bytes, or a string with a k, m or g suffix (binary units). A new file over it is not staged; a tracked file that grows past it is untracked (its history ends at its last committed version). 0 disables the cap. Default: 100000000 (100 MB, under GitHub's 100 MiB file limit)."),
 });
 /**
  * Per-root VCS overrides extending the root-level VCS config.
@@ -28823,6 +30519,10 @@ const watchConfigSchema = object$1({
     usePolling: boolean$2()
         .optional()
         .describe('Use polling instead of native file system events (for network drives).'),
+    /** The local change source (D125); `usePolling: true` forces chokidar. */
+    changeSource: _enum$1(['parcel', 'chokidar'])
+        .optional()
+        .describe('Local change source: "parcel" (@parcel/watcher, one native subscription per watch root; the default) or "chokidar" (the manual switch). usePolling: true forces chokidar. A reload that changes it rebuilds the watcher; if @parcel/watcher cannot load, the service refuses to start (or a reload refuses the rebuild) naming this switch.'),
     /** Debounce delay in milliseconds for file change events. */
     debounceMs: number$2()
         .optional()
@@ -28831,6 +30531,16 @@ const watchConfigSchema = object$1({
     stabilityThresholdMs: number$2()
         .optional()
         .describe('Time in milliseconds a file must remain unchanged before processing.'),
+    /** Periodic reconciliation interval (D111); 0 disables it. */
+    reconcileIntervalMs: number$2()
+        .int()
+        .min(0)
+        .optional()
+        .describe('Interval in milliseconds between periodic reconciliations of each watch root against the inventory (default 900000, 15 minutes); 0 disables them. A reload changes it without rebuilding the watcher.'),
+    /** Index check at start (D197). */
+    indexCheckOnStart: boolean$2()
+        .optional()
+        .describe('After the start walk, delete the indexed file documents under each available watch root whose files are gone (deleted or moved away while the service was down). Default: true. A root where more than 10% of its indexed documents (once more than 20 are missing) or more than 1,000 are missing is left alone (run reindex prune deliberately). Read at start.'),
     /** Whether to respect .gitignore files when processing. */
     respectGitignore: boolean$2()
         .optional()
@@ -28864,13 +30574,7 @@ const configWatchConfigSchema = object$1({
         .optional()
         .describe('Debounce delay in milliseconds for config file change detection.'),
     /** Reindex scope triggered on config change. */
-    reindex: union$1([
-        literal('issues')
-            .describe('Re-process only files with recorded issues.'),
-        literal('full').describe('Full reindex of all watched files.'),
-        literal('rules')
-            .describe('Re-apply inference rules to existing points without re-embedding.'),
-    ])
+    reindex: configWatchReindexScopeSchema
         .optional()
         .describe('Reindex scope triggered on config change. Default: issues.'),
 });
@@ -28888,6 +30592,30 @@ const apiConfigSchema = object$1({
     cacheTtlMs: number$2()
         .optional()
         .describe('TTL in milliseconds for caching read-heavy endpoints (e.g., /status, /config). Default: 30000.'),
+    /** Bearer API key required on every route except GET /status. */
+    apiKey: string$2()
+        .min(1, 'api.apiKey must be a non-empty string (remove it to disable authentication)')
+        .optional()
+        .describe('Bearer API key required on every route except GET /status (supports ${ENV_VAR} substitution). Must be non-empty. Unset: no authentication. Read at startup only.'),
+});
+/**
+ * Log file rotation (D171). Every key falls back to its default.
+ */
+const logRotationConfigSchema = object$1({
+    /** Rotate when the file reaches this size. */
+    maxSize: byteSizeSchema
+        .optional()
+        .describe('Rotate when the log file reaches this size: bytes, or a string with a k, m or g suffix (binary units). Default: "10m".'),
+    /** Rotate on this schedule too. */
+    frequency: union$1([_enum$1(['daily', 'hourly']), number$2().int().positive()])
+        .optional()
+        .describe('Also rotate "daily", "hourly", or every N milliseconds. Default: "daily".'),
+    /** Rotated files kept in addition to the active one (up to N + 1 files, D184). */
+    maxFiles: number$2()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Number of rotated log files kept in addition to the active one, so up to maxFiles + 1 files remain. Default: 14.'),
 });
 /**
  * Logging configuration.
@@ -28901,6 +30629,10 @@ const loggingConfigSchema = object$1({
     file: string$2()
         .optional()
         .describe('Path to log file (logs to stdout if omitted).'),
+    /** Rotation of the log file (D171). */
+    rotation: union$1([literal(false), logRotationConfigSchema])
+        .optional()
+        .describe('Rotation of logging.file: false to disable, or { maxSize, frequency, maxFiles }. Default when logging.file is set: { maxSize: "10m", frequency: "daily", maxFiles: 14 }.'),
 });
 
 /**
@@ -29035,6 +30767,126 @@ const inferenceRuleSchema = object$1({
     }
 });
 
+/**
+ * @module schemas/payloadIndexes
+ * Zod schema for `vectorStore.payloadIndexes`: configured Qdrant payload indexes, including tenant and principal flags. No I/O.
+ */
+/** Qdrant payload index types supported by `vectorStore.payloadIndexes`. */
+const payloadIndexTypeSchema = _enum$1(['keyword', 'integer', 'float', 'bool', 'datetime', 'uuid', 'text'])
+    .describe('Qdrant payload index type.');
+/** Index types that may carry `isTenant: true` (Qdrant `is_tenant`). */
+const TENANT_INDEX_TYPES = ['keyword', 'uuid'];
+/** Index types that may carry `isPrincipal: true` (Qdrant `is_principal`). */
+const PRINCIPAL_INDEX_TYPES = [
+    'integer',
+    'float',
+    'datetime',
+];
+/**
+ * Whether an index type may carry `isTenant: true` (Qdrant `is_tenant`).
+ *
+ * @param type - Payload index type.
+ * @returns `true` for `keyword` and `uuid`.
+ */
+function isTenantIndexType(type) {
+    return TENANT_INDEX_TYPES.includes(type);
+}
+/**
+ * Whether an index type may carry `isPrincipal: true` (Qdrant
+ * `is_principal`).
+ *
+ * @param type - Payload index type.
+ * @returns `true` for `integer`, `float` and `datetime`.
+ */
+function isPrincipalIndexType(type) {
+    return PRINCIPAL_INDEX_TYPES.includes(type);
+}
+/**
+ * A single configured payload index.
+ *
+ * `isTenant` is valid only for `keyword`/`uuid`; `isPrincipal` only for
+ * `integer`/`float`/`datetime`. Both constraints are enforced by refinement.
+ */
+const payloadIndexSchema = object$1({
+    /** Payload field to index. */
+    field: string$2().min(1).describe('Payload field name to index.'),
+    /** Qdrant index type. */
+    type: payloadIndexTypeSchema,
+    /** Mark the index as a tenant index (keyword/uuid only). */
+    isTenant: boolean$2()
+        .optional()
+        .describe('Qdrant is_tenant: optimise storage for per-tenant filtering (keyword/uuid only).'),
+    /** Mark the index as a principal index (integer/float/datetime only). */
+    isPrincipal: boolean$2()
+        .optional()
+        .describe('Qdrant is_principal: optimise storage for range filtering (integer/float/datetime only).'),
+})
+    .superRefine((val, ctx) => {
+    if (val.isTenant && !isTenantIndexType(val.type)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['isTenant'],
+            message: `isTenant is only valid for ${TENANT_INDEX_TYPES.join('/')} indexes (got "${val.type}")`,
+        });
+    }
+    if (val.isPrincipal && !isPrincipalIndexType(val.type)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['isPrincipal'],
+            message: `isPrincipal is only valid for ${PRINCIPAL_INDEX_TYPES.join('/')} indexes (got "${val.type}")`,
+        });
+    }
+});
+const systemIndexFields = new Set(SYSTEM_PAYLOAD_INDEX_FIELDS);
+/**
+ * The `vectorStore.payloadIndexes` list. Each `field` may appear once, and
+ * the system-indexed fields (`source`, `source_rule`) are rejected: the
+ * watcher always keeps a keyword index on them.
+ */
+const payloadIndexesSchema = array$1(payloadIndexSchema)
+    .superRefine((indexes, ctx) => {
+    const seen = new Set();
+    indexes.forEach(({ field }, i) => {
+        if (systemIndexFields.has(field)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: [i, 'field'],
+                message: `"${field}" is a system field the watcher always indexes (keyword); remove this entry`,
+            });
+        }
+        else if (seen.has(field)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: [i, 'field'],
+                message: `Duplicate payload index for field "${field}"; each field may be indexed once`,
+            });
+        }
+        seen.add(field);
+    });
+});
+
+/**
+ * @module schemas/processing
+ * `processing` config: the per-document ceilings (file size before extraction, extracted text bytes, chunk count) past which a document is `too_large` (D44, D64).
+ */
+/** Processing ceilings, read per document (a reload applies to the next one). */
+const processingConfigSchema = object$1({
+    /** File size cap, checked with `stat` before extraction (files only). */
+    maxFileBytes: byteSizeSchema
+        .optional()
+        .describe(`Largest file processed, checked with stat before extraction (files only; source documents keep the 10 MiB response cap): bytes, or a string with a k, m or g suffix (binary units). A larger file has its points deleted and a too_large issue recorded. Default: '${PROCESSING_DEFAULTS.maxFileBytes}'.`),
+    /** Most chunks one document may split into. */
+    maxChunksPerFile: number$2()
+        .int()
+        .min(1)
+        .optional()
+        .describe(`Most chunks one document (file or source) may split into; more has its points deleted and a too_large issue recorded. Default: ${String(PROCESSING_DEFAULTS.maxChunksPerFile)}.`),
+    /** Extracted text cap (UTF-8 bytes). */
+    maxTextBytes: byteSizeSchema
+        .optional()
+        .describe(`Largest extracted text of one document (file or source), in UTF-8 bytes: bytes, or a string with a k, m or g suffix (binary units). More has its points deleted and a too_large issue recorded. Default: '${PROCESSING_DEFAULTS.maxTextBytes}'.`),
+});
+
 /**
  * @module schemas/services
  * Service configuration schemas: embedding and vector store.
@@ -29046,11 +30898,11 @@ const embeddingConfigSchema = object$1({
     /** The embedding model provider. */
     provider: string$2()
         .default('gemini')
-        .describe('Embedding provider name (e.g., "gemini", "openai").'),
+        .describe('Embedding provider name. Default: "gemini".'),
     /** The embedding model name. */
     model: string$2()
         .default('gemini-embedding-001')
-        .describe('Embedding model identifier (e.g., "gemini-embedding-001", "text-embedding-3-small").'),
+        .describe('Embedding model identifier for the provider. Default: "gemini-embedding-001".'),
     /** Maximum tokens per chunk for splitting. */
     chunkSize: number$2()
         .optional()
@@ -29075,6 +30927,10 @@ const embeddingConfigSchema = object$1({
     concurrency: number$2()
         .optional()
         .describe('Maximum concurrent embedding requests.'),
+    /** URL POSTed when embedding health changes state (unsigned body). */
+    alertUrl: url()
+        .optional()
+        .describe('URL that receives a POST when embedding health turns failing (embedding_failed) or recovers (embedding_recovered). The body is unsigned and sent without credentials: use a private endpoint. Read at each transition.'),
 });
 /**
  * Vector store configuration for Qdrant.
@@ -29090,6 +30946,10 @@ const vectorStoreConfigSchema = object$1({
     apiKey: string$2()
         .optional()
         .describe('Qdrant API key for authentication (supports ${ENV_VAR} substitution).'),
+    /** Payload indexes created at startup when missing (never dropped). */
+    payloadIndexes: payloadIndexesSchema
+        .optional()
+        .describe('Qdrant payload indexes created at startup when missing (never dropped). Each field at most once; source and source_rule are always indexed and cannot be listed. Default: none.'),
 });
 
 /**
@@ -29120,10 +30980,10 @@ object$1({
     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). */
+    /** Directory for persistent state files (issues.json, values.v8, enrichments.sqlite). */
     stateDir: string$2()
         .optional()
-        .describe('Directory for persistent state files (issues.json, values.json, enrichments.sqlite). Defaults to .jeeves-metadata.'),
+        .describe('Directory for persistent state files (issues.json, values.v8, enrichments.sqlite). Defaults to .jeeves-metadata.'),
     /** Rules for inferring metadata from document properties (inline objects or file paths). */
     inferenceRules: array$1(union$1([inferenceRuleSchema, string$2()]))
         .optional()
@@ -29179,8 +31039,8 @@ object$1({
         concurrency: number$2()
             .int()
             .min(1)
-            .default(50)
-            .describe('Maximum concurrent file operations during reindex (default 50).'),
+            .default(REINDEX_DEFAULTS.concurrency)
+            .describe(`Maximum concurrent file operations during reindex (default ${String(REINDEX_DEFAULTS.concurrency)}).`),
     })
         .optional()
         .describe('Reindex configuration.'),
@@ -29211,6 +31071,12 @@ object$1({
     vcs: vcsConfigSchema
         .optional()
         .describe('VCS configuration for git-backed version control of watched content.'),
+    /** Processing ceilings (D44, D64). */
+    processing: processingConfigSchema
+        .optional()
+        .describe('Processing ceilings: a document over one has its points deleted and a too_large issue recorded. Read per document.'),
+    /** Named sources for non-file documents (callback retrieval). */
+    sources: sourcesConfigSchema.optional(),
     /** Logging configuration. */
     logging: loggingConfigSchema.optional().describe('Logging configuration.'),
     /** Timeout in milliseconds for graceful shutdown. */
@@ -29227,6 +31093,13 @@ object$1({
         .describe('Maximum backoff delay in milliseconds for system errors. Default: 60000.'),
 });
 
+/**
+ * @module skill.generated
+ * The jeeves-watcher skill (descriptor `skill`), compiled from `skills/jeeves-watcher/SKILL.md` by `npm run skill`. Generated; do not edit.
+ */
+/** Contents of the jeeves-watcher `SKILL.md`. */
+const WATCHER_SKILL = '---\nname: jeeves-watcher\ndescription: >\n  Semantic search of the indexed archive: recall prior context, find documents, scan, enrich metadata, watcher config, reindex, indexing issues, file history.\n---\n\n# jeeves-watcher — Search, Discovery & Administration\n\n## Service Architecture\n\nThe watcher is an HTTP API running as a background service (typically NSSM on Windows, systemd on Linux).\n\n**Default port:** 1936 (configurable via `api.port` in watcher config) **Non-default port:** If the watcher runs on a different port, the user must set `plugins.entries.jeeves-watcher-openclaw.config.apiUrl` in `openclaw.json`. The plugin cannot auto-discover a non-default port.\n\n**API key:** If the watcher sets `api.apiKey`, every route except `GET /status` and `GET /openapi.json` needs `Authorization: Bearer <key>`. The tools send it from `plugins.entries.jeeves-watcher-openclaw.config.apiKey` (or the `JEEVES_WATCHER_API_KEY` env var). From `watcher_config`, `watcher_config_apply`, `watcher_search`, `watcher_scan` and `watcher_show_vcs_file`, a missing or wrong key comes back as `HTTP 401: {"error":"Unauthorized","code":"unauthorized"}` (see [Error Handling](#error-handling) for the fix). From the other tools it reads `HTTP 401 unauthorized: the watcher API requires an API key. Provide it via plugins.entries.jeeves-watcher-openclaw.config.apiKey or the JEEVES_WATCHER_API_KEY env var.` (or, when a key was sent, `... rejected the API key. Check ... against the service\'s api.apiKey.`). When calling the API directly, add the header yourself. Never echo the key.\n\n**Tool errors:** Tool error text is prefixed `Error: `. Every `watcher_*` tool is built from the watcher\'s endpoint catalog and reports a non-2xx response as `HTTP <status>: <body>`, with the server\'s JSON body verbatim: read its `code` (and `details` or `issues`) there, e.g. `HTTP 400: {"error":"Validation failed","code":"invalid_request",...}` or `HTTP 503: {"error":"Scan in progress","code":"scan_in_progress"}`. Branch on the code, not the message. The tools reject parameters that don\'t match their schema before sending anything. Each call waits up to 120 s; a timeout does not cancel a state change on the service, so check the outcome (e.g. `watcher_check_vcs_exclusion` after `watcher_exclude_vcs_path`) before retrying. An unreachable service reads `Service not reachable at <url>.` with a hint to set `apiUrl`. (`watcher_service` comes from the shared Jeeves core toolset and words its own errors.)\n\n**Health check:** `GET /status` returns `name`, `version`, `uptime`, `status` (`healthy`/`degraded`/`unhealthy`), and a `health` object containing `collection` (`name`, `pointCount`, `dimensions`, `systemIndexes`), `reindex` progress, `initialScan` progress, `embedding` (provider health), and (when version tracking is on) `vcs` (`roots`, `pending`, `trippedRoots`, `oldestTrippedAt`). `status` is `degraded` (still HTTP 200) when embeddings are failing or a version-control root has tripped.\n\n**Mental model:** The `watcher_*` tools are thin HTTP wrappers. Each tool call translates to an HTTP request to the watcher API. When tools are available, use them. When they\'re not (e.g., different session, plugin not loaded), you can hit the API directly. Replace `<PORT>` below with the configured port (default 1936; check `plugins.entries.jeeves-watcher-openclaw.config.apiUrl` in `openclaw.json` if overridden), and add `-H "Authorization: Bearer <key>"` when the service sets `api.apiKey`:\n\n```\n# Health check\ncurl http://127.0.0.1:<PORT>/status\n\n# Search\ncurl -X POST http://127.0.0.1:<PORT>/search \\\n  -H "Content-Type: application/json" \\\n  -d \'{"query": "search text", "limit": 5}\'\n\n# Query config\ncurl http://127.0.0.1:<PORT>/config\n```\n\n**Key endpoints:**\n\n| Endpoint | Method | Purpose |\n| --- | --- | --- |\n| `/status` | GET | Health check, uptime, collection stats |\n| `/openapi.json` | GET | OpenAPI 3.1 document of the catalog routes (no key needed) |\n| `/search` | POST | Semantic search (main query interface) |\n| `/config` | GET | Public resolved config (allow-listed keys plus `issues`); optional `?path=<jsonpath>` filter |\n| `/config/validate` | POST | Validate candidate config |\n| `/config/apply` | POST | Apply config changes |\n| `/reindex` | POST | Trigger reindex |\n| `/metadata` | POST | Enrich document metadata (file path or source reference) |\n| `/scan` | POST | Filter-only point query (no embeddings) |\n| `/walk` | POST | Watched-file listing with glob intersection |\n| `/issues` | GET | Runtime processing failures (file paths and source references) |\n| `/documents` | POST | Notify changed source documents (`{ source, rule }`) |\n| `/documents/delete` | POST | Delete source documents by reference or filter |\n| `/rules/register` | POST | Register virtual inference rules (auto-triggers rules reindex) |\n| `/rules/unregister` | DELETE | Remove virtual rules by source (`{ source }` body) |\n| `/rules/unregister/:source` | DELETE | Remove virtual rules by source (parameterized) |\n| `/rules/reapply` | POST | Re-apply rules to indexed files matching `globs` |\n| `/points/delete` | POST | Delete points matching a Qdrant filter |\n| `/render` | POST | Render a document (file path or source reference) through its rule |\n| `/search/facets` | GET | Get search facet definitions and values (`?rules=a,b` scopes them to those rules) |\n| `/search/facets/counts` | POST | Count values of indexed fields over a filter, each document once; counts are approximate (`{ fields, filter?, rules?, limit? }`); `{ min, max }` for number/date fields; `503 not_available` while its system indexes build or past its 10 s budget |\n| `/rebuild-metadata` | POST | Rebuild the enrichment store from Qdrant file point payloads |\n| `/config/schema` | GET | Get config JSON schema |\n| `/config/match` | POST | Test file paths against inference rules and watch scope |\n| `/vcs/*` | GET/POST | Version tracking (`status`, `history`, `show`, `diff`, `check-exclusion`, `revert`, `exclude`) |\n\n**If the watcher is unreachable:** Check the service status (`nssm status jeeves-watcher` on Windows), check the configured port in the watcher config file, and check logs for startup errors.\n\n## Theory of Operation\n\nYou have access to a **semantic archive** of your human\'s working world. Documents, messages, tickets, notes, code, and other artifacts are indexed, chunked, embedded, and searchable. This is your long-term recall for anything beyond the current conversation.\n\n**When to reach for the watcher:**\n\n- **Someone asks about something that happened.** A meeting, a decision, a conversation, a ticket, a message. You weren\'t there, but the archive was. Search it.\n- **You need context you don\'t have.** Before asking the human "what\'s the status of X?", search for X. The answer is probably already indexed.\n- **You\'re working on something and need background.** Prior discussions, related records, relevant documents. Search by topic, filter by domain.\n- **You need to verify something.** Don\'t guess from stale memory. Search for the current state.\n- **You want to connect dots across domains.** The same topic might appear in multiple domains. A single semantic search surfaces all of them.\n\n**When NOT to use it:**\n\n- You already have the information in the current conversation\n- The question is about general knowledge, not the human\'s specific context\n- The watcher is unreachable (fall back to filesystem browsing)\n\n**The principle:** Memory-core is your curated highlights. The watcher archive is your perfect recall. Use memory first for speed and signal, but never let its narrow scope be the ceiling of what you can remember.\n\n## ⚠️ Embedding Cost — Hard Behavioral Gate\n\n**The watcher embeds every file it sees.** Embedding is the most expensive operation in the pipeline — each file triggers a Gemini API call. The index may contain hundreds of thousands of points. Any action that causes the watcher to process a large number of files has real, potentially significant cost.\n\n**STOP and ask for a human decision before:**\n\n- **Renaming, moving, or reorganizing watched directories.** The watcher has **move detection** enabled by default (`watch.moveDetection.enabled: true`). When a file is moved, the change source reports an unlink and an add; the `MoveCorrelator` buffers the unlink, matches it with the add via content hash, and processes it as a zero-embedding move (point ID remap, metadata re-inference, enrichment migration). Under the default parcel source, a renamed or moved directory is paired as a whole (at least 90% of its files at the same relative path and size) and each file becomes such a move. **No re-embedding cost for moves.** However, if a rename is blocked (e.g., by a file lock from the watcher or another service), **do NOT work around it by creating new directories and copying/moving files**. That creates duplicate embeddings at the new paths while the old paths still exist. Instead: stop the blocking service, perform the rename, restart.\n- **Changing `watch.paths` to add large directory trees.** Adding a new watch root triggers initial indexing of every matching file under it.\n- **Running `scope: "full"` reindex.** Every watched file is re-extracted (a file whose text to embed changed, or that was never indexed, is re-embedded) and every indexed source document is retrieved through its callback and always re-embedded. Use `scope: "rules"` for inference rule changes (no file re-embedding; only metadata reapplication).\n- **Any bulk file operation** (mass copy, mass move, template-based file generation) under watched paths.\n\n**The right instinct when blocked:** If a filesystem operation fails because a service has a lock, the correct response is to stop the service, do the operation, and restart — NOT to find a creative workaround. Creative workarounds in the presence of a live watcher are how you accidentally trigger re-embedding of tens of thousands of files.\n\n**Cost context:** A single file embedding costs a Gemini API call. 1,000 unnecessary embeddings is a noticeable cost. 100,000 unnecessary embeddings (e.g., copying an entire domain directory to a new path) is a billing event worth flagging.\n\n## Plugin Installation\n\nThe plugin is a standard OpenClaw plugin. On a Jeeves box, `jeeves install watcher --config-root <path>` installs it and writes its config; otherwise use `openclaw plugins install npm:@karmaniverous/jeeves-watcher-openclaw@<version> --pin --accept-capabilities` and set `plugins.entries.jeeves-watcher-openclaw.config` yourself. Restart the gateway to load it.\n\n`configRoot` has no default. Only `watcher_service` with `action: "install"` needs it; other `watcher_service` actions and all HTTP API tools work without it. If `watcher_service install` returns "configRoot not configured", set `configRoot` in the plugin config or the `JEEVES_CONFIG_ROOT` env var.\n\n## Quick Start (Existing Deployment)\n\nIf the watcher service is already running and healthy:\n\n1. **Search** — use `watcher_search` with a natural language query and optional metadata filters\n2. **Read source** — use `read` (standard file read) with `file_path` from search results for full document content. Source documents (points carrying `source`, such as `app://chat/thread/42`, and no `file_path`) are not files: their content comes from the source\'s callback (`POST /render` with `{ "source": "<ref>" }`).\n\n## Bootstrap (First-Time Setup)\n\nWhen the plugin loads and the watcher service is NOT yet set up, drive the entire setup proactively. The user should be able to install the plugin with nothing else in place and the bootstrap process gets them to a working system.\n\n**The agent drives this process.** Don\'t hand the user CLI commands and wait. Check each prerequisite, explain what\'s needed, execute what you can, and prompt the user only for decisions that require human judgment.\n\n### Step 1: Check Node.js\n\nVerify Node.js is installed and version ≥ 24.22.2:\n\n```bash\nnode --version\n```\n\nIf missing or too old, guide the user to install Node.js 24.22.2 or later from https://nodejs.org or via their package manager.\n\n### Step 2: Install Qdrant\n\nCheck if Qdrant is already running:\n\n```bash\ncurl -s http://localhost:6333/healthz\n```\n\nIf not running, install it. **Prefer native installation** (especially on cloud instances where Docker may not be available):\n\n**Linux (recommended for servers):**\n\n```bash\n# Download and install binary\ncurl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-musl.tar.gz -o /tmp/qdrant.tar.gz\nsudo tar xzf /tmp/qdrant.tar.gz -C /usr/local/bin/\n\n# Create qdrant user and directories\nsudo useradd -r -s /bin/false qdrant\nsudo mkdir -p /var/lib/qdrant/storage /var/lib/qdrant/snapshots /etc/qdrant\nsudo chown -R qdrant:qdrant /var/lib/qdrant\n\n# Create config\nsudo tee /etc/qdrant/config.yaml > /dev/null <<EOF\nstorage:\n  storage_path: /var/lib/qdrant/storage\n  snapshots_path: /var/lib/qdrant/snapshots\nservice:\n  host: 0.0.0.0\n  http_port: 6333\n  grpc_port: 6334\nEOF\n\n# Create systemd service\nsudo tee /etc/systemd/system/qdrant.service > /dev/null <<EOF\n[Unit]\nDescription=Qdrant Vector Database\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=/usr/local/bin/qdrant --config-path /etc/qdrant/config.yaml\nWorkingDirectory=/var/lib/qdrant\nRestart=always\nUser=qdrant\n\n[Install]\nWantedBy=multi-user.target\nEOF\nsudo systemctl daemon-reload\nsudo systemctl enable --now qdrant\n```\n\n**Windows:**\n\n```powershell\n# Download from GitHub releases page\n# https://github.com/qdrant/qdrant/releases\n# Extract and run, or register as NSSM service:\nnssm install Qdrant <path-to-qdrant.exe>\nnssm start Qdrant\n```\n\n**Docker (fallback, if available):**\n\n```bash\ndocker run -d -p 6333:6333 -v qdrant_data:/qdrant/storage qdrant/qdrant\n```\n\nAfter installation, verify:\n\n```bash\ncurl -s http://localhost:6333/healthz\n```\n\n### Step 3: Install Watcher Service\n\nInstall the watcher CLI globally:\n\n```bash\nnpm install -g @karmaniverous/jeeves-watcher\n```\n\nVerify:\n\n```bash\njeeves-watcher --version\n```\n\n### Step 4: Set Up Embedding Provider\n\nThe watcher uses Google Gemini for embeddings by default (`gemini-embedding-001`, 3072 dimensions).\n\nCheck for an existing API key:\n\n```bash\necho $GOOGLE_API_KEY    # Linux/Mac\necho %GOOGLE_API_KEY%   # Windows cmd\n$env:GOOGLE_API_KEY     # PowerShell\n```\n\nIf not set, guide the user:\n\n1. Go to https://aistudio.google.com/apikey\n2. Create an API key (free tier supports 1,000 embedding requests/minute)\n3. Set it as a persistent environment variable:\n   - **Linux:** Add `export GOOGLE_API_KEY=<key>` to `~/.bashrc` or `~/.profile`\n   - **Windows:** `setx GOOGLE_API_KEY "<key>"` (new shell sessions only) or set via System Properties → Environment Variables\n   - **macOS:** Add to `~/.zshrc` or use `launchctl setenv`\n\nVerify the key works by testing a Gemini API call:\n\n```bash\ncurl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=$GOOGLE_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"model":"models/gemini-embedding-001","content":{"parts":[{"text":"test"}]}}\'\n```\n\nA successful response contains an `embedding.values` array.\n\n### Step 5: Author Initial Config\n\nAsk the user these questions:\n\n- **What directories should the watcher index?** (e.g., `~/documents`, `~/projects`, a workspace path)\n- **What types of files matter?** (helps determine file extensions for watch globs)\n- **Are there directories to exclude?** (node_modules, .git, build outputs, etc.)\n\nThen generate a starter config file. Example minimal config:\n\n```json\n{\n  "description": "Personal knowledge base indexing",\n  "api": { "port": 1936 },\n  "watch": {\n    "paths": ["/home/user/documents/**/*.{md,txt,json,pdf,html,docx}"],\n    "ignored": ["**/node_modules/**", "**/.git/**", "**/dist/**"]\n  },\n  "embedding": {\n    "provider": "gemini",\n    "model": "gemini-embedding-001",\n    "dimensions": 3072,\n    "apiKey": "${GOOGLE_API_KEY}",\n    "chunkSize": 1000,\n    "chunkOverlap": 200,\n    "rateLimitPerMinute": 1000,\n    "concurrency": 5\n  },\n  "vectorStore": {\n    "url": "http://localhost:6333",\n    "collectionName": "jeeves_archive"\n  },\n  "search": {\n    "scoreThresholds": { "strong": 0.75, "relevant": 0.5, "noise": 0.25 },\n    "hybrid": { "enabled": true }\n  },\n  "logging": { "level": "info" },\n  "inferenceRules": []\n}\n```\n\nWrite the config to a sensible location (e.g., `~/.config/jeeves-watcher.config.json` on Linux, or alongside the user\'s workspace). Validate it against the config schema (offline; no running service needed) with:\n\n```bash\njeeves-watcher config validate -c <config-path>\n```\n\n### Step 6: Register and Start as a Service\n\n**The watcher should run as a persistent service, not a foreground process.**\n\n**Linux (systemd):**\n\n```bash\nsudo tee /etc/systemd/system/jeeves-watcher.service > /dev/null <<EOF\n[Unit]\nDescription=Jeeves Watcher - Filesystem Indexing Service\nAfter=network.target qdrant.service\n\n[Service]\nType=simple\nExecStart=$(which jeeves-watcher) start -c <config-path>\nWorkingDirectory=%h\nRestart=always\nEnvironment=GOOGLE_API_KEY=<key>\nUser=$USER\n\n[Install]\nWantedBy=multi-user.target\nEOF\nsudo systemctl enable --now jeeves-watcher\n```\n\n**Windows (NSSM):**\n\n```powershell\njeeves-watcher service install -c <config-path>\n# Or manually:\nnssm install jeeves-watcher (Get-Command jeeves-watcher).Source start -c <config-path>\nnssm set jeeves-watcher AppEnvironmentExtra GOOGLE_API_KEY=<key>\nnssm start jeeves-watcher\n```\n\nVerify the service started:\n\n```bash\ncurl -s http://127.0.0.1:1936/status\n```\n\n### Step 7: Verify Health\n\nCall `watcher_status` (or `curl http://127.0.0.1:1936/status`). Confirm:\n\n- Service is running\n- Qdrant collection exists with expected dimensions (3072)\n- Point count is increasing (initial indexing in progress)\n\nIf the point count is 0 after a minute, check `watcher_list_issues` for processing failures.\n\n### Step 8: Orientation\n\nOnce health is confirmed and initial indexing has started:\n\n1. Query `$.[\'description\',\'search\']` for the deployment\'s organizational strategy and score thresholds.\n2. Query `$.inferenceRules[*].[\'name\',\'description\']` for available record types.\n3. Report to the user: how many points indexed so far, which domains are available, estimated time to complete initial indexing (based on file count and embedding rate).\n\n### On Subsequent Sessions\n\nOn sessions after bootstrap is complete:\n\n1. Call `watcher_status` silently.\n2. Run the orientation queries silently.\n3. Only report if something changed (service down, point count dropped significantly, new domains appeared).\n\n**Key principle:** The agent drives discovery. The user shouldn\'t have to explain their archive to you — the archive explains itself through its config.\n\n## Tools\n\nThe plugin registers 18 tools: `watcher_status`, `watcher_config`, `watcher_config_apply`, `watcher_service`, `watcher_search`, `watcher_set_metadata`, `watcher_validate_config`, `watcher_reindex`, `watcher_scan`, `watcher_list_issues`, `watcher_walk`, and the seven version-control tools (see [Version Tracking](#version-tracking)).\n\n### `watcher_search`\n\nSemantic search over indexed documents (`POST /search`).\n\n- `query` (string, required) — natural language search query (non-empty)\n- `limit` (number, optional) — max results (positive integer), default 10\n- `offset` (number, optional) — skip N results for pagination (non-negative integer)\n- `filter` (object, optional) — Qdrant filter for metadata filtering\n\nReturns an array of `{ id, score, payload }` ordered by score (see [Search Result Shape](#search-result-shape)). A filter Qdrant rejects is `400 invalid_request`; an exhausted embedding budget is `503 embedding_unavailable`.\n\n### `watcher_set_metadata`\n\nSet or update metadata on a document (`POST /metadata`).\n\n- `path` (string, required) — file path of the document (absolute or watched path)\n- `metadata` (object, required) — key-value metadata to merge\n\nReturns `{ ok: true, matched_rules }`. If the document is busy (being indexed) for 10 s, the tool reports `503 not_available` with `Retry-After: 10` and changes nothing; retry after 10 s. The tool addresses files only; to enrich a source document, call `POST /metadata` directly with `{ "source": "<name>://<id>", "metadata": { ... } }` (exactly one of `path` or `source`).\n\n### `watcher_status`\n\nService health check (`GET /status`, never needs the API key). Returns `name`, `version`, `uptime`, `status`, and a `health` object: `collection` (`name`, `pointCount`, `dimensions`, and `systemIndexes`: the state of each index the service creates itself, e.g. `{ "chunk_index": "ready", "file_path": "ready", "matched_rules": "building" }`; `building`, `ready`, `conflict` or `failed`), `embedding` (`state` `ok` or `failing`, `lastSuccessAt`, `lastError` `{ at, code }`, `failingSince`, `backoffUntil`; codes only, never provider text), `reindex` (`active`; while active also `scope`, `startedAt`, `filesProcessed`, `totalFiles`), `initialScan`, and `vcs` when version tracking is on: `roots`, `pending` (changes not yet committed), `trippedRoots` (roots whose commits keep failing) and `oldestTrippedAt`.\n\nAfter a service restart, the `health.initialScan` field shows scan progress:\n\n- `active: true` — filesystem walk in progress; `filesMatched` and `filesEnqueued` grow until the initial walk (or chokidar\'s scan) completes\n- `active: false` with `completedAt`/`durationMs` — scan finished\n\nUse this to determine if the service is still initializing after a restart.\n\n### `watcher_config`\n\nQuery the effective runtime config via JSONPath (`GET /config`). Returns the full resolved merged document when no path is provided.\n\n- `path` (string, optional) — JSONPath expression\n\nThe document holds only the allow-listed keys `description`, `watch`, `configWatch`, `search`, `schemas`, `inferenceRules`, `mapHelpers`, `templateHelpers`, `maps`, `templates`, plus `issues` (the current issues). `api`, `sources`, `embedding`, `vectorStore` (and their keys) are never included. Each rule carries `source` (`config`, or the registering source of a virtual rule) and `values` (the runtime values index). File references (`map`, `maps`, `templates`) and named schema references are always resolved. An invalid JSONPath is `400 invalid_request`.\n\n### `watcher_validate_config`\n\nValidate config and optionally test file paths (`POST /config/validate`).\n\n- `config` (object, optional) — candidate config (partial or full). Omit to validate current config.\n- `testPaths` (string[], optional) — file paths to test against the config\n\nPartial configs are merged into the running config shallowly: each top-level key replaces the running value, except `inferenceRules`, which merge by rule name. This differs from `watcher_config_apply` (deep merge), so pass a whole top-level object (e.g. all of `watch`) when validating a change inside it. Returns `{ valid: false, errors: [{ path, message }] }`, or `{ valid: true, warnings?, testResults? }`, where each test result is `{ path, matchedRules, metadata, error? }` (`error: "File not found"` when the path cannot be read). Validation problems come back in a `200` body, so this is the place to see them in full.\n\n### `watcher_config_apply`\n\nApply config changes (`POST /config/apply`, sent as `{ patch: config }`).\n\n- `config` (object, required) — full or partial config to apply\n- `replace` (boolean, optional) — replace the whole config with `config` instead of merging\n\nPartial configs are deep-merged into the config file the service runs from (objects recursively, arrays replaced, `inferenceRules` by rule name), so `{}` or a single key is valid. The merged result is validated and written to disk, then the `configWatch.reindex` scope (default `issues`) runs; that reindex covers files only. With `configWatch.enabled` (default `true`) the service picks up the written file without a restart, including new/removed watch paths (the filesystem watcher is rebuilt), inference rule changes, move detection settings, and gitignore filter updates.\n\nReturns `{ applied: true, config }`. `config` is redacted through the same allow-list as `GET /config`: `api`, `sources` and provider keys are never echoed. When the file was written but the post-write apply step failed, the body also carries `warning` (a string describing the failure). An invalid merged config is a tool error reading `HTTP 400: {"error":"Config validation failed","code":"invalid_request","issues":[...]}`, so run `watcher_validate_config` first. A config file the service cannot read or write is `HTTP 500` with the generic `internal_error` body, the cause in the service log.\n\n### `watcher_reindex`\n\nTrigger a reindex operation (`POST /reindex`). Non-prune scopes return a `plan` object showing the blast area; the live run reuses the same targets. A live prune (non-dry-run) returns immediately without a plan.\n\n**Parameters:**\n\n- `scope` (string, optional) — Reindex scope. The tool sends `"rules"` when omitted (the HTTP API\'s own default is `"issues"`). One of:\n  - `"rules"` — Re-apply inference rules to every watched file (no re-embedding; changed values written, keys the rules no longer project removed). With `path`, only files matching those globs. Without `path`, every indexed source document is also retrieved through its callback and its stored rule re-applied: unchanged content gets a metadata-only update, and a document is re-embedded only if its rendered text changed.\n  - `"full"` — Re-extract and re-process every watched file (a file is re-embedded when the text to embed changed or it was never indexed), and retrieve and always re-embed every indexed source document. Clears the runtime values index first.\n  - `"issues"` — Re-process the documents in `watcher_list_issues`: failed files, and failed source references (with their stored rule, or the `rule` recorded on the issue when the document was never indexed).\n  - `"path"` — Re-process a specific file or all files under a directory. Requires `path`. Each target must be watched and not gitignored (`403 path_not_watched`) and must exist (`404 not_found`). Files only.\n  - `"prune"` — Delete Qdrant points for files no longer in watch scope (removed paths, gitignored files, deleted files). No re-embedding. Pure cleanup. Never selects source points (`source` set, no `file_path`).\n- `path` (string | string[], optional) — Target file(s) or directories for `"path"` (required there), or globs narrowing `"rules"`. Ignored by other scopes.\n- `dryRun` (boolean, optional) — When `true`, compute and return the plan without executing.\n\nThe tool has no `source` parameter. To re-process specific source references, call `POST /reindex` directly with `{ "scope": "path", "source": ["<name>://<id>", ...] }` (at most 1000): they are enqueued on the notify queue, are not tracked by `GET /status`, and send no completion callback. A reindex triggered by a config change (`watcher_config_apply`, config-file reload, rule registration) covers files only.\n\n**Response (normal):**\n\n```json\n{\n  "status": "started",\n  "scope": "rules",\n  "plan": {\n    "total": 148000,\n    "toProcess": 148000,\n    "toDelete": 0,\n    "byRoot": { "/data": 95000, "/srv/config": 3000 }\n  }\n}\n```\n\n**Response (dryRun):**\n\n```json\n{\n  "status": "dry_run",\n  "scope": "prune",\n  "plan": {\n    "total": 562000,\n    "toProcess": 0,\n    "toDelete": 2300,\n    "byRoot": { "/srv/app/node_modules": 1800, "/srv/app/.cache": 500 }\n  }\n}\n```\n\n**Plan fields:**\n\n- `total` — Points scrolled (prune), or files plus source documents covered (other scopes).\n- `toProcess` — Files plus source documents to process (0 for prune).\n- `toDelete` — Points to delete (prune only, 0 for others).\n- `byRoot` — Files grouped by watch root (for prune: orphaned files), plus one entry per source name for source documents. Shows where the impact concentrates.\n- `incomplete` — `true` when the prune scroll failed part-way and the plan is partial.\n\n**Progress:** a live run (every scope except `path` with `source`) is tracked in `watcher_status` under `health.reindex` (`filesProcessed` / `totalFiles`, counting files plus source documents). A failing file or source document is logged and recorded; the rest of the run continues.\n\n**Guidance:**\n\n- Use `dryRun: true` before any large-blast operation to preview impact.\n- `prune` is safe — it only deletes orphaned file points, never re-embeds. Use after changing watch paths, fixing gitignore, or cleaning up stale data.\n- `prune` is NOT triggered by config-watch auto-reindex (too dangerous for auto-trigger).\n\n### `watcher_scan`\n\nFilter-only point query without vector search (`POST /scan`). Use for structural queries where the question has no semantic dimension.\n\n- `filter` (object, required) — Qdrant filter object. Required to prevent accidental full-collection scans.\n- `limit` (number, optional) — page size (integer 1 to 1000), default 100\n- `cursor` (string or number, optional) — opaque cursor from previous response for pagination\n- `fields` (string[], optional) — payload fields to return (projection)\n- `countOnly` (boolean, optional) — if true, return `{ count }` instead of points\n\n**Response (normal):**\n\n```json\n{\n  "points": [\n    {\n      "id": "uuid",\n      "payload": { "file_path": "/data/tickets/PROJ-123.json" }\n    }\n  ],\n  "cursor": "opaque string, number or null"\n}\n```\n\n**Response (countOnly):**\n\n```json\n{ "count": 1234 }\n```\n\n**Key differences from `watcher_search`:**\n\n- No `query` parameter — does NOT use embeddings\n- No `score` field — results are unranked filter matches\n- Cursor-based pagination (not offset-based); `cursor` is `null` on the last page\n- Zero cost per call beyond Qdrant\'s filtered scroll\n\n**Pagination pattern:**\n\n```\nlet cursor = undefined;\ndo {\n  const result = await watcher_scan({ filter, limit: 100, cursor });\n  // process result.points\n  cursor = result.cursor;\n} while (cursor);\n```\n\n### `watcher_service`\n\nManage the watcher background service (install, uninstall, start, stop, restart, check status). No HTTP call.\n\n- `action` (string, required) — one of: `install`, `uninstall`, `start`, `stop`, `restart`, `status`\n\nReturns the service manager\'s response. On Windows uses NSSM, on Linux systemd, on macOS launchd. Only `install` needs `configRoot` (see [Plugin Installation](#plugin-installation)).\n\n### `watcher_list_issues`\n\nGet runtime processing failures (`GET /issues`). Returns `{ count, issues: { [key]: IssueRecord[] } }`: `count` is the number of documents with issues, and each key is a file path or a source reference (`<name>://<id>`). Each `IssueRecord` has `type` (one of the [issue codes](#error-categories)), `message`, `timestamp`, and optionally `operation`, `property`, `rule`, `rules`, `types`, `details`.\n\n### `watcher_walk`\n\nList watched files matching globs (`POST /walk`). Returns matching file paths from the watcher\'s in-memory list of watched files across all configured watch roots.\n\n- `globs` (string[], required) — glob patterns to intersect with watch paths (non-empty; matched case-insensitively, dotfiles included)\n\n**Response:**\n\n```json\n{\n  "paths": ["/data/foo/.meta/meta.json", "/data/bar/.meta/meta.json"],\n  "matchedCount": 2,\n  "scannedRoots": ["/data", "/srv/config"]\n}\n```\n\n**Use cases:**\n\n- Discover files matching a pattern across all watched directories (e.g., `["**/.meta/meta.json"]`)\n- Enumerate files before rule registration to understand scope\n- Find files that aren\'t yet indexed (no Qdrant dependency)\n\n**Key differences from `watcher_scan`:**\n\n- Lists the files the filesystem watcher tracks, not the Qdrant index\n- No embedding or indexing required, but the initial filesystem scan must be complete: until then the tool returns `HTTP 503 scan_in_progress` (check `health.initialScan` in `watcher_status`)\n- Returns file paths only (no metadata, no vectors)\n- Applies `watch.ignored` and gitignore filtering automatically\n\n## Query Planning: Scan vs Search\n\n**Decision rule:** If the query has no semantic/natural-language dimension, use `watcher_scan`. If you need meaning-based similarity, use `watcher_search`.\n\n| Use `watcher_scan` | Use `watcher_search` |\n| --- | --- |\n| "List all files in domain X" | "Find documents about authentication" |\n| "Files modified after timestamp T" | "What discusses rate limiting?" |\n| "Enumerate paths under prefix P" | "Prior conversations about deployment" |\n| "Count files matching a condition" | "Related tickets to this issue" |\n| "Staleness detection / delta computation" | "What happened in last week\'s meetings?" |\n\n**Scan-specific filter examples:**\n\n**Domain enumeration:**\n\n```json\n{ "must": [{ "key": "domains", "match": { "value": "email" } }] }\n```\n\n**Modified after timestamp:**\n\n```json\n{ "must": [{ "key": "modified_at", "range": { "gte": 1772800000 } }] }\n```\n\n**Path prefix matching:**\n\n```json\n{ "must": [{ "key": "file_path", "match": { "text": "/data/tickets" } }] }\n```\n\n**Count files in a domain (no point data transferred):**\n\n```\nwatcher_scan: filter={"must":[{"key":"domains","match":{"value":"github"}}]}, countOnly=true\n```\n\n---\n\n## Qdrant Filter Syntax\n\nFilters use Qdrant\'s native JSON filter format, passed as the `filter` parameter to `watcher_search`.\n\n### Basic Patterns\n\n**Match exact value:**\n\n```json\n{ "must": [{ "key": "domain", "match": { "value": "email" } }] }\n```\n\n**Match text (full-text search within field):**\n\n```json\n{ "must": [{ "key": "chunk_text", "match": { "text": "authentication" } }] }\n```\n\n**Combine conditions (AND):**\n\n```json\n{\n  "must": [\n    { "key": "domain", "match": { "value": "jira" } },\n    { "key": "status", "match": { "value": "In Progress" } }\n  ]\n}\n```\n\n**Exclude (NOT):**\n\n```json\n{\n  "must_not": [{ "key": "domain", "match": { "value": "repos" } }]\n}\n```\n\n**Any of (OR):**\n\n```json\n{\n  "should": [\n    { "key": "domain", "match": { "value": "email" } },\n    { "key": "domain", "match": { "value": "slack" } }\n  ]\n}\n```\n\n**Nested (combine AND + NOT):**\n\n```json\n{\n  "must": [{ "key": "domain", "match": { "value": "jira" } }],\n  "must_not": [{ "key": "status", "match": { "value": "Done" } }]\n}\n```\n\n### Key Differences\n\n- `match.value` — exact match (case-sensitive, for keyword fields like `domain`, `status`)\n- `match.text` — full-text match (for text fields like `chunk_text`)\n\n## Search Result Shape\n\nEach result from `watcher_search` contains:\n\n| Field | Type | Description |\n| --- | --- | --- |\n| `id` | string | Qdrant point ID |\n| `score` | number | Similarity (or hybrid fused) score; higher = more relevant |\n| `payload.file_path` | string | Normalized file path (file points only) |\n| `payload.source` | string | Source reference `<name>://<id>` (source points only) |\n| `payload.source_rule` | string | Designated rule of a source document (source points only) |\n| `payload.chunk_text` | string | The matched text chunk |\n| `payload.chunk_index` | number | Zero-based chunk position within the document |\n| `payload.total_chunks` | number | Total chunks for this document |\n| `payload.line_start` | number | 1-indexed line where the chunk starts |\n| `payload.line_end` | number | 1-indexed line where the chunk ends |\n| `payload.created_at` | number | Creation timestamp (unix seconds) |\n| `payload.modified_at` | number | Modification timestamp (unix seconds) |\n| `payload.content_hash` | string | SHA-256 hash of the embedded text |\n| `payload.matched_rules` | string[] | Names of inference rules that matched |\n\n`file_path` is not always present: a source point (a document indexed through a source callback) carries a non-empty `source` and no `file_path`. A file point may also carry a `source` written by its own rules; it is still a file point. Additional metadata fields depend on the deployment\'s inference rules (e.g., `domain`, `status`, `author`). Use `watcher_config` to discover available fields.\n\n## Query Planning (Per Search Task)\n\nIdentify relevant rule(s) from the orientation model, then retrieve their schemas:\n\n**Retrieve complete schema for a rule:**\n\n```\nwatcher_config: path="$.inferenceRules[?(@.name==\'jira-issue\')].schema"\n```\n\nReturns the rule\'s schema array with named schema references and file references already resolved: properties, types, `set` expressions, `uiHint`, `enum`, etc.\n\n**For select/multiselect fields without `enum` in schema:**\n\n```\nwatcher_config: path="$.inferenceRules[?(@.name==\'jira-issue\')].values.status"\n```\n\nRetrieves valid filter values from the runtime values index (distinct values accumulated during embedding).\n\n**When search results span multiple rules** (indicated by `matched_rules` on results): query each unique rule\'s schema separately and merge mentally. Most result sets share the same rule combination, so this is typically one or two queries, not one per result.\n\n---\n\n## uiHint → Filter Mapping\n\nUse `uiHint` to determine filter construction strategy. **This table is explicit, not intuited:**\n\n| `uiHint` | Qdrant filter | Notes |\n| --- | --- | --- |\n| `text` | `{ "key": "<field>", "match": { "text": "<value>" } }` | Substring/keyword match |\n| `select` | `{ "key": "<field>", "match": { "value": "<enum_value>" } }` | Exact match; use `enum` values from schema or runtime values index |\n| `multiselect` | `{ "key": "<field>", "match": { "value": "<enum_value>" } }` | Any-element match on array field; use `enum` or runtime values index |\n| `date` | `{ "key": "<field>", "range": { "gte": <unix_ts>, "lt": <unix_ts> } }` | Range filter against integer fields holding Unix timestamps (seconds). Source dates should be normalized in config via `{{toUnix ...}}` in `set` expressions. Either bound optional for open-ended ranges (e.g., "after January" → `gte` only) |\n| `number` | `{ "key": "<field>", "range": { "gte": <n>, "lte": <n> } }` | Either bound optional for open-ended ranges |\n| `check` | `{ "key": "<field>", "match": { "value": true } }` | Boolean match |\n| _(absent)_ | Do not use in filters | Internal bookkeeping field, not intended for search |\n\n**Fallback:** If a `select`/`multiselect` field has neither `enum` in schema nor values in the index, treat it as `text` (substring match instead of exact match).\n\n---\n\n## Qdrant Filter Combinators\n\nCompose individual field conditions into complex queries using three combinators:\n\n| Combinator | Semantics | Use case |\n| --- | --- | --- |\n| `must` | AND — all conditions required | Intersecting constraints (domain + date range + assignee) |\n| `should` | OR — at least one must match | Alternative values, fuzzy criteria ("assigned to X or Y") |\n| `must_not` | Exclusion — any match triggers exclude | Filtering out noise (exclude Done, exclude codebase domain) |\n\n**Combinators nest arbitrarily for complex boolean logic:**\n\n```json\n{\n  "must": [\n    { "key": "domain", "match": { "value": "jira" } },\n    { "key": "created", "range": { "gte": 1735689600 } }\n  ],\n  "should": [\n    { "key": "assignee", "match": { "value": "Jane Doe" } },\n    { "key": "assignee", "match": { "value": null } }\n  ],\n  "must_not": [{ "key": "status", "match": { "value": "Done" } }]\n}\n```\n\nA consuming UI will necessarily compose simple single-field filters. The assistant can compose deeply complex queries combining multiple fields, nested boolean logic, and open-ended ranges to precisely target what it needs.\n\n---\n\n## Search Execution\n\n**Plain semantic search is valid and often sufficient.** Not every query needs metadata filters. When the user\'s question is broad or exploratory, a natural language query with no filter object is the right starting point. Add filters to narrow, not as a default.\n\n**Result limit guidance:**\n\n- Default: 10 results\n- Broad discovery / exploratory: 20–30, apply score threshold cutoff from config\n- Targeted retrieval with tight filters: 5\n- Cross-domain sweep: 15–20, no domain filter, use score to separate signal from noise\n\n---\n\n## Post-Processing Guidance\n\n### Score Interpretation\n\nUse `scoreThresholds` from config (queried during orientation). Values are deployment-specific, constrained to [-1, 1]:\n\n- `strong` — minimum score for a strong match. **Action:** High confidence. Use these results directly.\n- `relevant` — minimum score for relevance. **Action:** Likely useful but verify context before relying on them.\n- `noise` — maximum score below which results are noise. **Action:** Discard. If all results fall below this threshold, broaden your query or try different terms.\n\n### Chunk Grouping\n\nMultiple results with the same `file_path` (or, for source documents, the same `source`) are chunks of one document. Read the full file for complete context.\n\n### Schema Lookup\n\nUse `matched_rules` on results to look up applicable schemas for metadata interpretation:\n\n```\nwatcher_config: path="$.inferenceRules[?(@.name==\'jira-issue\')].schema"\n```\n\n### Full Context\n\nSearch gives you chunks; use `read` with `file_path` for the complete document. A source document has no file: render it with `POST /render` and `{ "source": "<ref>" }`, which retrieves it through its callback.\n\n---\n\n## Path Testing\n\nWhen uncertain whether a file would be indexed, test it against the rules. `watcher_validate_config` with `testPaths` (and no `config`) runs the current rules against each path and returns `{ path, matchedRules, metadata }` per path (`error: "File not found"` when the file cannot be read):\n\n```\nwatcher_validate_config: testPaths=["/data/tickets/PROJ-123.json"]\n```\n\nOr call `POST /config/match` directly with `{ "paths": [...] }`. It returns `{ matches: [{ rules, watched }] }`, one entry per path, without reading the files:\n\n- `rules` lists the matching rule names; an empty array means no inference rules match\n- `watched: false` means the path falls outside watch paths or is excluded by ignore patterns\n\n---\n\n## Config Authoring\n\n### Rule Structure\n\nEach inference rule has:\n\n- `name` (required) — unique identifier\n- `description` (required) — human-readable purpose\n- `match` (required) — JSON Schema matched against file attributes (e.g. a picomatch `glob` on `file.path`)\n- `schema` (optional) — array of named schema references and/or inline schema objects with `set` templates\n- `map` (optional) — JsonMap transform (inline, named map, or `.json` file path)\n- `template` (optional) — Handlebars template (inline, named template, or `.hbs`/`.handlebars` file path)\n- `render` (optional) — declarative frontmatter + Markdown renderer (mutually exclusive with `template`)\n- `renderAs` (optional) — output extension (1-10 lowercase alphanumerics); requires `template` or `render`\n\n### Authoring Notes\n\n- **`maps` entries are bare strings or inline maps.** A string value is a file path, loaded and parsed as a JsonMap at startup. A `{ path, description }` object is kept as-is and never loaded from the file, so it silently does nothing useful. (`mapHelpers` and `templateHelpers` are different: `{ path, description }` objects are their documented form.)\n- **Metadata is derived with `set`, not `attributes`.** Each schema property\'s `set` template produces its value. There is no `attributes` key in the config schema; older configs and examples that use one need rewriting.\n- **`render.frontmatter` accepts picomatch globs and `!` exclusions** alongside explicit keys, e.g. `["meta_id", "*", "!_*", "!chunk_*"]`. Explicit names keep their listed order; keys matched by a glob follow, sorted alphabetically; a key matching an exclusion is dropped.\n- **Virtual rules have a startup window.** Virtual rules are registered at runtime by other services (`POST /rules/register`, e.g. jeeves-meta), so they are absent during the initial file scan after a watcher start. Files indexed in that window lack virtual-rule metadata until the registration\'s automatic rules reindex runs, or until `POST /rules/reapply` covers them. If metadata from a virtual rule is missing right after a restart, check whether its service has registered yet.\n\n### Config Workflow\n\n1. Edit config (or build partial config object)\n2. Validate: `watcher_validate_config` with optional `testPaths` for dry-run preview\n3. Apply: `watcher_config_apply` — validates, writes, triggers the `configWatch.reindex` reindex\n4. Monitor: `watcher_list_issues` for runtime processing failures\n\n### Reindex Concurrency\n\nReindex operations process files and source documents concurrently using `reindex.concurrency` (default 50). This applies to every scope, to issue-source discovery, and to the stored-rule lookups of `POST /reindex` with `source`. The watcher\'s incremental processing (file events and source notifications) uses a separate `embedding.concurrency` setting.\n\nProgress is reported via `watcher_status` (`health.reindex.filesProcessed` / `health.reindex.totalFiles`, counting files plus source documents).\n\n### When to Reindex\n\n- **Rules scope** (`"rules"`): Changed rule matching patterns, set expressions, schema mappings. No file re-embedding needed.\n- **Full scope** (`"full"`): Added watch paths, broad schema restructuring, or source documents whose vectors must be rebuilt. Re-extracts every file (re-embedding the ones whose text to embed changed) and re-embeds every source document.\n- **Issues scope** (`"issues"`): After fixing the root cause of processing failures (permissions, encoding, file format, a source outage). Re-processes only the failed files and source documents.\n- **Path scope** (`"path"`): Edited files in a specific directory, or a single file looks stale, and you want them re-processed without a full reindex. A file whose text to embed is unchanged is not re-embedded.\n- **Prune scope** (`"prune"`): After changing `watch.paths`, adding gitignore rules, or discovering stale/orphaned points (e.g., indexed `node_modules`). Deletes points for out-of-scope or deleted files. Always `dryRun: true` first to preview.\n\n---\n\n## Diagnostics\n\n### Escalation Path\n\n1. `watcher_status` — is the service healthy? Is a reindex running? Is the initial scan still active?\n2. `watcher_list_issues` — which documents are failing and why?\n3. `watcher_config` with `$.issues` — the same issue records via JSONPath\n4. Check logs at the configured log path\n\n### Error Categories\n\nEvery issue record\'s `type` is one of these codes:\n\n- `type_collision` — conflicting metadata types across rules (includes `property`, `rules[]`, `types[]`)\n- `interpolation_error` — template or `set` expression rendering failed (includes `property`, `rule`; `details` holds per-step failures)\n- `extraction_error` — reading, rule application or chunking failed\n- `embedding_error` — the embedding provider failed\n- `upsert_error` — the vector store write failed\n- `match_failed` — a source document\'s designated rule did not match (`details` holds the AJV errors)\n- `rule_missing` — a source document\'s designated rule was not found\n- `no_content` — nothing to embed\n- `source_unavailable` — the source callback failed\n- `unsupported_content_type` — the source callback returned a non-JSON body\n- `too_large` — the document is over a `processing` ceiling (`maxFileBytes`, `maxChunksPerFile` or `maxTextBytes`); it is not embedded and its points are deleted. Raise the ceiling and run `reindex` with scope `issues` to restore it\n\nSource-document issues always carry `rule` (the designated rule of the failed run).\n\n**Issues are self-healing:** resolved on successful re-process. The issues file always represents the current set of unresolved problems: a live todo list.\n\n### Change Source\n\n`watcher_status` reports the change source under `health.changeSource` (`@parcel/watcher` by default, chokidar on request or when polling):\n\n- **Service refuses to start, log names `@parcel/watcher failed to load`:** the platform binary is missing or broken. Reinstall without `--omit=optional`, or set `watch.changeSource: chokidar` (the manual switch; a reload rebuilds the watcher with one full initial scan).\n- **Rising `reconcileEvents`:** the source is missing events and reconciliation is finding them. **Rising `resubscribes`:** subscriptions keep failing (Linux). **Rising `renewFailures`:** a Linux renewal could not unsubscribe; restart the service. **`unavailableRoots` above 0:** a watch root is missing or unreadable (an unmounted share); its files keep their points until it returns. **High `pendingStability`, or a long `lastReconcileDurationMs` / `lastRenewDurationMs`:** a large write burst or a slow disk; a long renewal pauses event handling for every root.\n- **Linux, a file in a moved-in or renamed folder is indexed late:** changes inside folders nested in a newly created or moved-in tree, or in a directory renamed within a root, are missed until the root\'s subscription is renewed at the next periodic reconcile, up to `watch.reconcileIntervalMs` (15 minutes by default) late. Expected; shorten the interval if the latency matters. The files moved in with the tree are indexed at once.\n- **Linux, events lost under a write burst with nothing in the log:** parcel cannot detect an inotify queue overflow. Check `sysctl fs.inotify.max_queued_events` (recommended 1048576) and `fs.inotify.max_user_watches` (the start log warns at 90%); the periodic reconcile finds what was lost (`reconcileEvents` rises).\n- **Windows, files in deep folders indexed only by reconciliation:** expected. Under parcel, creating or changing a file whose path is 260 characters or more produces no change event at either `LongPathsEnabled` setting, so it is indexed at the next periodic reconcile, up to `watch.reconcileIntervalMs` late. Nothing to fix; check that `watch.reconcileIntervalMs` is not 0. (`LongPathsEnabled = 1` is still recommended for other tools; it is a host change for the owner.)\n- **Windows, `lastRestartCause` set:** under parcel the service never unsubscribes on Windows (`@parcel/watcher` 2.6.0 crashes the process there), so a reload that rebuilds the watcher, a subscription error or a vanished watch root exits with code 75 and the service manager restarts it. `watch-config-changed`, `subscription-error` or `root-gone` says why, `lastRestartAt` when. If the service stays down after such an exit, its service manager is not restarting it on exit (NSSM: `AppExit Default Restart`).\n\n### Index Check at Start\n\nAfter the start walk the service deletes the indexed documents of files gone from disk (deleted or moved while it was down). `watcher_status` reports it under `health.indexCheck` (`state`, `at`, `durationMs`, `checked`, `removed`, `skippedRoots`, `capped`):\n\n- **`capped` above 0:** under some watch root more than 10% of the indexed documents (once more than 20 are missing) or more than 1,000 were missing from disk or filters, so nothing was deleted there; the log names the root. Run `watcher_reindex` with scope `prune` and `dryRun: true`, check the plan, then run it.\n- **`state: failed`:** the index could not be listed (Qdrant down), or the service stopped first; it runs again at the next start.\n- **`skippedRoots` above 0:** a root was unavailable, unwatched, gone, or its start walk failed; its deletions wait for the next start or a `prune`.\n- **Files that still exist but are now ignored** keep their points: that is `prune`\'s job. `watch.indexCheckOnStart: false` turns the check off.\n\n---\n\n## Helper Management\n\nHelpers use namespace prefixing: config key becomes prefix. A helper named `slack` exports `slack_extractParticipants`.\n\nEnumerate loaded helpers:\n\n```\n$.mapHelpers              — JsonMap helper namespaces with exports\n$.templateHelpers         — Handlebars helper namespaces with exports\n```\n\n### Built-in JsonMap Helpers\n\nThe following helpers are available in every JsonMap `lib` context without any helper config:\n\n#### `fetchSiblings(filePath, options?)`\n\nRetrieve extracted text from neighboring files in the same directory with the same extension. Useful for contextual embedding — e.g., injecting surrounding email messages into a thread member\'s embedding for better semantic search.\n\n**Parameters:**\n\n- `filePath` (string) — the current file path (in a rule\'s `map`, `$.input.file.path`)\n- `options` (object, optional; JsonMap `params` are path strings, so a call from a config `map` uses the defaults):\n  - `before` (number, default 3) — number of preceding siblings to include\n  - `after` (number, default 1) — number of following siblings to include\n  - `sort` (`"name"` | `"mtime"`, default `"name"`) — sort order for determining neighbor position\n\n**Returns:** `string[]` — extracted text from sibling files, in sort order. Files that fail extraction are silently skipped. For a source document (a source rule\'s `map`) there is no file reader, so it returns `[]`.\n\n**Example** (in a rule\'s `map`):\n\n```json\n{\n  "context": {\n    "$": { "method": "$.lib.fetchSiblings", "params": "$.input.file.path" }\n  }\n}\n```\n\n---\n\n## Enrichment\n\nUse `watcher_set_metadata` to tag documents after analysis (e.g., `reviewed: true`, project labels).\n\n**Enrichments are durable.** Stored in a SQLite database (`<stateDir>/enrichments.sqlite`, default `stateDir` `.jeeves-metadata`), enrichments survive full reindexes. Enriching a file that is not indexed yet stores the enrichment, which applies once the file is indexed. When the watcher re-processes a file, enrichments are merged with inference rule output using composable semantics: scalar fields overwrite, array fields union+deduplicate.\n\n**Metadata is validated against the file\'s matched rule schemas** (for a source document, its designated rule\'s schema). Only declared property types are checked; unknown properties and `null` values pass. The tool reports a failure as `HTTP 400 invalid_request: Validation failed`; the structured `details` are in the HTTP response body:\n\n```json\n{\n  "code": "invalid_request",\n  "error": "Validation failed",\n  "details": [\n    {\n      "property": "priority",\n      "expected": "string",\n      "received": "number",\n      "rule": "jira-issue",\n      "message": "Property \'priority\' is declared as string in jira-issue schema, received number"\n    }\n  ]\n}\n```\n\n---\n\n## Version Tracking\n\nThe watcher includes built-in history and undo for your watched files. When enabled, every change to a watched file is automatically versioned. You can view the history of any file or folder, see exactly what changed between versions, retrieve old versions, and undo changes — all through the version-control tools below.\n\n### Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `watcher_get_vcs_status` | Check version tracking health: enabled state, tracked roots, remote sync status |\n| `watcher_list_vcs_history` | View change history for a file or folder, with optional date range and limit |\n| `watcher_show_vcs_file` | Retrieve the content of a file at a specific past version |\n| `watcher_diff_vcs` | Show what changed between two versions, or between a past version and now |\n| `watcher_revert_vcs` | Undo changes by restoring files to a specific past version |\n| `watcher_exclude_vcs_path` | Exclude a path from version history (it stays in search), or remove the exclusion; untracks matching files |\n| `watcher_check_vcs_exclusion` | Check whether git ignores a path and why (rule, file, line) |\n\n### Usage Patterns\n\n**View recent changes to a file:**\n\n```\nwatcher_list_vcs_history: glob="/data/tickets/PROJ-123.json", limit=10\n```\n\n**See what changed between two versions:**\n\n```\nwatcher_diff_vcs: glob="/data/tickets/PROJ-123.json", commit="abc1234"\n```\n\n**Restore a file to a previous version:**\n\n```\nwatcher_revert_vcs: glob="/data/tickets/PROJ-123.json", commit="abc1234"\n```\n\n**View old content without restoring:**\n\n```\nwatcher_show_vcs_file: path="/data/tickets/PROJ-123.json", commit="abc1234"\n```\n\n**Exclude files that don\'t need versioning** (e.g., Jira issues that are read-only syncs):\n\n```\nwatcher_exclude_vcs_path: glob="/data/tickets/**/*.json"\n```\n\n**Check if a file is excluded and why:**\n\n```\nwatcher_check_vcs_exclusion: path="/data/tickets/PROJ-123.json"\n```\n\n### Enabling Version Tracking\n\nVersion tracking is controlled by the `vcs.enabled` config setting. When set to `true`, the watcher automatically versions all watched files. No additional setup is required — just enable it and history starts accumulating.\n\nSquash retention activates by default when VCS is enabled, even without explicit `retention` config. The defaults are: 30 days max age, 100 versions max, and a daily midnight cron schedule (`0 0 * * *`). These defaults prevent unbounded commit history growth.\n\n### Excluding Paths\n\nNot all watched files need version history. For example, if Jira issues are synced read-only, there\'s nothing to "undo." Use `watcher_exclude_vcs_path` to stop tracking specific paths.\n\nThe exclusion is VCS-only: the pattern goes to the root\'s `.git/info/exclude`, so the files stop being versioned but stay indexed and searchable.\n\n- **Destructive.** Adding a pattern untracks the tracked files it matches, in one commit: their history ends at their last committed version (the files stay on disk). `remove: true` deletes the pattern but does not restore history; the files are versioned again from their next change.\n- **One gitignore pattern, root-anchored.** The pattern is written as `/` plus the glob relative to the root, so `/data/tickets/*.json` (root `/data`) matches only directly under `tickets/`; use `**/` for any depth. Pass `root` to give a root-relative glob (`tickets/**/*.json`, without a leading `/`: with `root`, a glob starting with `/` is a filesystem path and must lie under the root).\n- **Brackets are a character class.** `Report [draft].docx` matches `Report d.docx`; escape them to name the file: `Report \\[draft\\].docx`.\n- **Refused (`400`):** a newline, a leading `!` or `#`, braces, a pattern matching the whole root (`*`, `**`, `**/*`, ...), or a glob outside the given `root`.\n- **More than 100 files** to untrack need `confirm: true`; without it the tool reports `409 confirm_required` with the count and changes nothing. Check the count with the user before confirming.\n- **Busy root.** If version control is busy on the root for 30 s the tool reports `503 not_available`; retry after 30 s.\n- `watcher_check_vcs_exclusion` reports `excluded: false` for a tracked file even when a human `.gitignore` matches it (git never reports tracked paths as ignored); exclude it to untrack it.\n\n### Score Interpretation\n\nVCS tools do not use vector search. There are no relevance scores to interpret — results are exact history lookups, diffs, and file retrievals.\n\n---\n\n## Error Handling\n\nIf the watcher is unreachable:\n\n- Inform the user that semantic search is temporarily unavailable\n- Fall back to direct `read` for known file paths\n- Do not retry silently in a loop\n\nIf a tool fails with `HTTP 401` (`unauthorized`):\n\n- The watcher sets `api.apiKey` and the plugin sent no key, or a different one.\n- Ask the user to set `plugins.entries.jeeves-watcher-openclaw.config.apiKey` in `openclaw.json` (or the `JEEVES_WATCHER_API_KEY` environment variable of the gateway) to the service\'s `api.apiKey`. The tools read it on every call, so no restart is needed.\n- Never ask for, print or guess the key. `GET /status` and `GET /openapi.json` never need it.\n\nIf a tool or call fails with `HTTP 503` (`not_available`) and a `Retry-After` header:\n\n- `POST /metadata` (`watcher_set_metadata`), `POST /rules/reapply` and `POST /documents/delete` wait at most 10 s for a document that is being indexed, then answer `503` with `Retry-After: 10`. A single-document request changed nothing; a multi-document request kept the documents it already changed. All three are idempotent: retry the same request after 10 s.\n- `watcher_exclude_vcs_path` waits 30 s for a busy version-control root.\n\nIf a tool fails with `HTTP 500: {"error":"Response validation failed","code":"internal_error"}`, the watcher produced a response that doesn\'t match its own schema: a server bug. Report it with the request you made; retrying won\'t help.\n\nIf tools are unavailable (plugin not loaded in this session):\n\n- The watcher API is still accessible via direct HTTP calls\n- Use `exec` to call the endpoints listed in Service Architecture\n- Default: `http://127.0.0.1:1936`\n\n**CLI Fallbacks:**\n\n- `jeeves-watcher status [-p <port>]` — check if the service is running (`GET /status`)\n- `jeeves-watcher config validate -c <path>` — validate a config file against the schema (offline)\n- Restart via NSSM (Windows) or systemctl (Linux)\n\n---\n\n## References\n\n- [JSONPath Plus documentation](https://www.npmjs.com/package/jsonpath-plus) for JSONPath syntax\n- [Qdrant filtering documentation](https://qdrant.tech/documentation/concepts/filtering/) for advanced query patterns and search response format\n';
+
 /**
  * @module plugin/constants
  * Shared constants for the OpenClaw plugin package.
@@ -29252,9 +31125,10 @@ const CONFIG_ROOT_UNSET_WARNING = `[${PLUGIN_ID}] configRoot not configured yet
  * Watcher-specific convenience wrappers over `@karmaniverous/jeeves` core SDK.
  *
  * @remarks
- * Only watcher-specific resolution logic lives here. Core SDK types and
- * utilities (`PluginApi`, `ToolResult`, `ok`, `connectionFail`, `fetchJson`,
- * `postJson`) should be imported directly from `@karmaniverous/jeeves`.
+ * Only watcher-specific resolution logic (API URL, API key, config root)
+ * lives here. Core SDK types and utilities should be imported directly from
+ * `@karmaniverous/jeeves`; every watcher API request goes through core's
+ * catalog toolset (`catalogTools.ts`).
  *
  * @module plugin/helpers
  */
@@ -29272,6 +31146,23 @@ function getApiUrl(api) {
         return scoped;
     return resolvePluginSetting(api, PLUGIN_ID, 'apiUrl', 'JEEVES_WATCHER_URL', DEFAULT_API_URL);
 }
+/**
+ * Resolve the watcher API bearer key, if configured.
+ *
+ * @remarks
+ * Resolution order: plugin-scoped config (`api.pluginConfig.apiKey`), then
+ * `plugins.entries.<id>.config.apiKey`, then `JEEVES_WATCHER_API_KEY`. Blank
+ * values count as unset. Resolved per request; never logged.
+ *
+ * @returns The key, or `undefined` when unset (requests carry no header).
+ */
+function getApiKey(api) {
+    const scoped = api.pluginConfig?.apiKey;
+    if (typeof scoped === 'string' && scoped.trim() !== '')
+        return scoped;
+    const resolved = resolveOptionalPluginSetting(api, PLUGIN_ID, 'apiKey', API_KEY_ENV_VAR);
+    return resolved?.trim() ? resolved : undefined;
+}
 /**
  * Resolve the platform config root path, if configured.
  *
@@ -29292,6 +31183,134 @@ function getConfigRoot(api) {
     return resolved?.trim() ? resolved : undefined;
 }
 
+/**
+ * @module plugin/catalogTools
+ * Every watcher tool, built from `WATCHER_CATALOG` by core's toolset (D38): the four standard tools (`watcher_status`, `watcher_service`, `watcher_config`, `watcher_config_apply`) and the 14 domain tools, all sending the bearer key where their entry requires it; `registerCatalogTool` registers one of them as an optional tool.
+ *
+ * @remarks
+ * Each tool is named `watcher_` plus its entry's verb-first name in
+ * snake_case (D77, `toToolName`). Parameters come from the entry's request
+ * schemas; descriptions keep the 0.17.0 wording where it is still true
+ * (`WATCHER_TOOL_SELECTION`). `watcher_search` and `watcher_scan` are
+ * `catalogMode: 'direct-only'`, so OpenClaw Tool Search keeps them
+ * model-visible: semantic search must be a direct tool or the model reaches
+ * for grep first. Every call runs on core's 120 s default timeout
+ * (`DEFAULT_FETCH_TIMEOUT_MS`, D137), the status probe on 5 s. Errors are
+ * reported as core's `HTTP <status>: <body>`; API-key guidance lives in the
+ * skill's troubleshooting section (spec #281 D31).
+ */
+/** `watcher_exclude_vcs_path` description (D103, D137). */
+const VCS_EXCLUDE_DESCRIPTION = `Exclude a path from version history (VCS-only: it stays in search), or remove the exclusion. Adding untracks the files the pattern matches, ending their history; more than ${String(VCS_EXCLUDE_CONFIRM_THRESHOLD)} files need confirm: true. A timeout does not cancel the exclusion: check the outcome with watcher_check_vcs_exclusion before retrying.`;
+/** `watcher_check_vcs_exclusion` description (0.21.0, spec B4). */
+const VCS_CHECK_DESCRIPTION = 'Check whether git ignores a path and why: the rule, the file holding it and its line';
+/** The scope `watcher_reindex` sends when the caller omits one: 0.17.0's default (owner ruling, 2026-11-04). */
+const REINDEX_DEFAULT_SCOPE = 'rules';
+/** `watcher_reindex` description. */
+const REINDEX_DESCRIPTION = `Trigger a reindex of the watched files. Without scope, re-applies inference rules (scope "${REINDEX_DEFAULT_SCOPE}"); the HTTP API's own default is "issues".`;
+/**
+ * The 14 domain tools, in their 0.17.0 registration order, by catalog entry.
+ * Descriptions keep the 0.17.0 text unless it changed with the tool.
+ */
+const WATCHER_TOOL_SELECTION = {
+    search: {
+        description: 'Semantic search over indexed documents. Supports Qdrant filters. This is a direct tool: call it directly, never through tool_call.',
+        catalogMode: 'direct-only',
+    },
+    setMetadata: {
+        description: 'Set or update metadata on a document by file path or source reference.',
+    },
+    validateConfig: {
+        description: 'Validate a candidate config (or current config if omitted). Optionally test file paths against the config to preview rule matching and metadata output.',
+    },
+    reindex: { description: REINDEX_DESCRIPTION },
+    scan: {
+        description: 'Filter-only point query without vector search. Returns metadata for points matching a Qdrant filter. Use for structural queries: file enumeration, staleness checks, delta computation. Use watcher_search for semantic/similarity queries. This is a direct tool: call it directly, never through tool_call.',
+        catalogMode: 'direct-only',
+    },
+    listIssues: {
+        description: 'Get runtime processing failures. Shows the documents (file path or source reference) that failed processing and why.',
+    },
+    walk: {
+        description: 'Walk watched filesystem paths with glob intersection. Returns matching file paths from all configured watch roots, applying watch.ignored and gitignore filtering.',
+    },
+    getVcsStatus: {
+        description: 'Get version tracking health: enabled state, tracked roots, remote status, last activity',
+    },
+    listVcsHistory: {
+        description: 'Query change history by path or glob with optional date range',
+    },
+    showVcsFile: { description: 'Retrieve file content at a specific version' },
+    diffVcs: {
+        description: 'Show what changed between two versions, or between a version and current',
+    },
+    revertVcs: {
+        description: 'Undo changes by restoring files to a specific version',
+    },
+    excludeVcsPath: { description: VCS_EXCLUDE_DESCRIPTION },
+    checkVcsExclusion: { description: VCS_CHECK_DESCRIPTION },
+};
+/** The standard tools, in their 0.17.0 registration order. */
+const STANDARD_TOOLS = [
+    'watcher_status',
+    'watcher_service',
+    'watcher_config',
+    'watcher_config_apply',
+];
+/** Every tool the plugin registers, in registration order (0.17.0 order). */
+const WATCHER_TOOL_NAMES = [
+    ...STANDARD_TOOLS,
+    ...Object.keys(WATCHER_TOOL_SELECTION).map((entry) => toToolName('watcher', entry)),
+];
+/**
+ * Core's toolset for the watcher: the four standard tools and the 14 domain
+ * tools. The base URL and the bearer key are resolved from `api` on every
+ * call.
+ *
+ * @param api - Plugin API (config source).
+ * @param component - Plugin-side component descriptor.
+ * @returns The tools, keyed by name.
+ */
+function createCatalogTools(api, component) {
+    const auth = { bearer: () => getApiKey(api) };
+    const tools = createPluginToolset(component, {
+        apiUrl: () => getApiUrl(api),
+        catalog: WATCHER_CATALOG,
+        auth,
+        tools: WATCHER_TOOL_SELECTION,
+    });
+    return new Map(tools.map((tool) => [
+        tool.name,
+        tool.name === 'watcher_reindex' ? withDefaultScope(tool) : tool,
+    ]));
+}
+/**
+ * `watcher_reindex` with 0.17.0's default scope: a call without `scope` sends
+ * {@link REINDEX_DEFAULT_SCOPE}, so agents see no change from 0.17.0.
+ *
+ * @param tool - The catalog-built reindex tool.
+ * @returns The same tool, defaulting `scope`.
+ */
+function withDefaultScope(tool) {
+    return {
+        ...tool,
+        execute: (id, params) => tool.execute(id, { scope: REINDEX_DEFAULT_SCOPE, ...params }),
+    };
+}
+/**
+ * Register one catalog-built tool as an optional tool.
+ *
+ * @param api - Plugin API (tool registration target).
+ * @param catalogTools - Catalog-built tools, by name ({@link createCatalogTools}).
+ * @param name - Tool name.
+ * @throws When no tool of that name was built.
+ */
+function registerCatalogTool(api, catalogTools, name) {
+    const tool = catalogTools.get(name);
+    if (!tool)
+        throw new Error(`Catalog tool not built: ${name}`);
+    api.registerTool(tool, { optional: true });
+}
+
 /**
  * @module plugin/toolGating
  * Which watcher tool invocations read `configRoot`, and so must be gated on it.
@@ -29301,15 +31320,17 @@ function getConfigRoot(api) {
  * error only when its implementation actually reads `configRoot`. Tools
  * that only call the service HTTP API keep working without it.
  *
- * Audit of the core standard toolset (`createPluginToolset`, core 0.6.0-7):
- * - `watcher_status`, `watcher_config`, `watcher_config_apply`: HTTP only
- *   (`{apiUrl}/…`, resolved per call).
- * - `watcher_service`: only `install` reads `configRoot`
- *   (`createServiceManager` → `resolveConfigFilePath` →
+ * Audit of the tools the plugin registers:
+ * - `watcher_status`, `watcher_config`, `watcher_config_apply` (core
+ *   toolset from `WATCHER_CATALOG`, `catalogTools.ts`): HTTP only
+ *   (`{apiUrl}` resolved per call; the bearer key sent where the entry
+ *   requires it).
+ * - `watcher_service` (core standard toolset): only `install` reads
+ *   `configRoot` (`createServiceManager` → `resolveConfigFilePath` →
  *   `getComponentConfigDir`); the other actions query or drive the OS
  *   service manager by service name.
  *
- * The 14 domain tools call `{apiUrl}/…` via `fetchJson`/`postJson` and are
+ * The 14 domain tools come from the same core toolset (D38): HTTP only,
  * never gated.
  */
 /**
@@ -29407,31 +31428,25 @@ function withGuardedTools(api, ensureCore, readers = CONFIG_ROOT_READERS) {
 
 /**
  * @module plugin/promptContext
- * Always-in-context watcher rules, injected via `before_prompt_build`.
+ * Injects the descriptor's always-in-context rules (`promptRules`, from watcher-core) via `before_prompt_build`.
  *
  * @remarks
  * Replaces the v0.x TOOLS.md `## Watcher` section that core's
- * `ComponentWriter` wrote on a timer. The rules are static; live numbers
- * (point counts, configured score thresholds, VCS roots) are served by
- * `watcher_status` and `watcher_config`, and detail lives in the skill.
+ * `ComponentWriter` wrote on a timer. Core registers nothing itself: the
+ * plugin passes the descriptor's `promptRules` to `registerPromptContext`.
  */
-/** Static watcher rules the agent must see on every turn. */
-const WATCHER_PROMPT_CONTEXT = [
-    '## Watcher',
-    'This environment includes a semantic search index over the document archive (`watcher_search`).',
-    '- **Escalation rule:** Use `memory_search` for personal operational notes, decisions, and rules. Escalate to `watcher_search` when memory is thin, or when searching the broader archive (tickets, docs, code). ALWAYS use `watcher_search` BEFORE filesystem commands (exec, grep) when looking for information in indexed paths.',
-    '- **Scan-first rule:** For structural queries (file enumeration, staleness checks, domain listing, counts), use `watcher_scan` instead of `watcher_search`. Scan does not use embeddings and does not accept a query string.',
-    '- **Search-first rule:** When finding, reading, or modifying files in indexed paths, run `watcher_search` FIRST, even if you already know the file path. Direct filesystem access is for acting on search results, not bypassing them.',
-    '- **Scores:** strong / relevant / noise thresholds are configured at `$.search.scoreThresholds` (query with `watcher_config`; defaults 0.75 / 0.5 / 0.25). Discard noise; if all results are noise, broaden the query.',
-    '- **Inventory on demand (`watcher_config`):** inference rules `$.inferenceRules[*]`, watched paths `$.watch.paths[*]`, ignored paths `$.watch.ignored[*]`. Version history: `watcher_vcs_*` tools. See the jeeves-watcher skill for detail.',
-].join('\n');
 /**
- * Register the watcher rules with OpenClaw's `before_prompt_build` hook.
+ * Register the component's prompt rules with OpenClaw's `before_prompt_build` hook.
  *
- * @returns `true` when the hook was registered.
+ * @param api - Plugin API.
+ * @param component - Descriptor carrying `promptRules`.
+ * @returns `true` when the hook was registered; `false` when the host has no
+ * `api.on` or the descriptor has no rules.
  */
-function registerWatcherPromptContext(api) {
-    return registerPromptContext(api, { content: WATCHER_PROMPT_CONTEXT });
+function registerWatcherPromptContext(api, component) {
+    if (!component.promptRules)
+        return false;
+    return registerPromptContext(api, { content: component.promptRules });
 }
 
 /**
@@ -29439,8 +31454,9 @@ function registerWatcherPromptContext(api) {
  * Jeeves component descriptor for the watcher OpenClaw plugin.
  *
  * @remarks
- * Feeds `createPluginToolset()` (`watcher_status`, `watcher_config`,
- * `watcher_config_apply`, `watcher_service`). The service descriptor
+ * Feeds `createPluginToolset()` (with `WATCHER_CATALOG`, `catalogTools.ts`),
+ * which builds the four standard tools and the catalog-built domain tools.
+ * The service descriptor
  * (`packages/service/src/descriptor.ts`) is the canonical source for the
  * config schema and CLI commands.
  */
@@ -29462,6 +31478,9 @@ function createWatcherComponent(pluginVersion) {
         configSchema: jeevesComponentDescriptorSchema.shape.name,
         configFileName: 'config.json',
         initTemplate: () => ({}),
+        // Injected by the plugin (prompt rules) and written by its build (skill).
+        promptRules: WATCHER_PROMPT_RULES,
+        skill: WATCHER_SKILL,
         startCommand: (configPath) => [
             'jeeves-watcher',
             'start',
@@ -29475,404 +31494,6 @@ function createWatcherComponent(pluginVersion) {
     };
 }
 
-/**
- * @module plugin/apiTool
- * Generic HTTP-backed watcher tool registration: config shape, request helpers, and ok/connectionFail wrapping.
- */
-/** Register a single API tool with standard try/catch + ok/connectionFail. */
-function registerApiTool(api, baseUrl, config) {
-    const tool = {
-        name: config.name,
-        description: config.description,
-        parameters: config.parameters,
-        ...(config.catalogMode ? { catalogMode: config.catalogMode } : {}),
-        execute: async (_id, params) => {
-            try {
-                const [endpoint, body] = config.buildRequest(params);
-                const url = `${baseUrl}${endpoint}`;
-                const data = body !== undefined ? await postJson(url, body) : await fetchJson(url);
-                return ok(data);
-            }
-            catch (error) {
-                return connectionFail(error, baseUrl, PLUGIN_ID);
-            }
-        },
-    };
-    api.registerTool(tool, { optional: true });
-}
-/** Build a query string from defined params. */
-function buildQuery(params, keys) {
-    const parts = [];
-    for (const key of keys) {
-        const val = params[key];
-        if (val !== undefined) {
-            const s = typeof val === 'string' ? val : JSON.stringify(val);
-            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(s)}`);
-        }
-    }
-    return parts.length > 0 ? `?${parts.join('&')}` : '';
-}
-/** Pick defined keys from params into a body object. */
-function pickDefined(params, keys) {
-    const body = {};
-    for (const key of keys) {
-        if (params[key] !== undefined)
-            body[key] = params[key];
-    }
-    return body;
-}
-
-/**
- * @module plugin/vcsTools
- * Version-tracking (watcher_vcs_*) tool configs for the OpenClaw plugin; each maps tool params to a watcher VCS endpoint.
- */
-/** The 7 watcher_vcs_* tool configs. */
-const vcsToolConfigs = [
-    {
-        name: 'watcher_vcs_status',
-        description: 'Get version tracking health: enabled state, tracked roots, remote status, last activity',
-        parameters: { type: 'object', properties: {} },
-        buildRequest: () => [getEndpoint('vcsStatus').path],
-    },
-    {
-        name: 'watcher_vcs_history',
-        description: 'Query change history by path or glob with optional date range',
-        parameters: {
-            type: 'object',
-            required: ['glob'],
-            properties: {
-                glob: {
-                    type: 'string',
-                    description: 'Path or glob pattern to query history for.',
-                },
-                since: {
-                    type: 'string',
-                    description: 'Start date (ISO 8601 or git date string).',
-                },
-                until: {
-                    type: 'string',
-                    description: 'End date (ISO 8601 or git date string).',
-                },
-                limit: {
-                    type: 'number',
-                    description: 'Maximum number of history entries to return.',
-                },
-            },
-        },
-        buildRequest: (params) => [
-            `${getEndpoint('vcsHistory').path}${buildQuery(params, ['glob', 'since', 'until', 'limit'])}`,
-        ],
-    },
-    {
-        name: 'watcher_vcs_show',
-        description: 'Retrieve file content at a specific version',
-        parameters: {
-            type: 'object',
-            required: ['path', 'commit'],
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'File path to retrieve.',
-                },
-                commit: {
-                    type: 'string',
-                    description: 'Version identifier.',
-                },
-            },
-        },
-        buildRequest: (params) => [
-            `${getEndpoint('vcsShow').path}${buildQuery(params, ['path', 'commit'])}`,
-        ],
-    },
-    {
-        name: 'watcher_vcs_diff',
-        description: 'Show what changed between two versions, or between a version and current',
-        parameters: {
-            type: 'object',
-            required: ['glob', 'commit'],
-            properties: {
-                glob: {
-                    type: 'string',
-                    description: 'Path or glob pattern to diff.',
-                },
-                commit: {
-                    type: 'string',
-                    description: 'Start version identifier.',
-                },
-                commitEnd: {
-                    type: 'string',
-                    description: 'End version identifier (defaults to current if omitted).',
-                },
-            },
-        },
-        buildRequest: (params) => [
-            `${getEndpoint('vcsDiff').path}${buildQuery(params, ['glob', 'commit', 'commitEnd'])}`,
-        ],
-    },
-    {
-        name: 'watcher_vcs_revert',
-        description: 'Undo changes by restoring files to a specific version',
-        parameters: {
-            type: 'object',
-            required: ['glob', 'commit'],
-            properties: {
-                glob: {
-                    type: 'string',
-                    description: 'Path or glob pattern to revert.',
-                },
-                commit: {
-                    type: 'string',
-                    description: 'Version to restore files to.',
-                },
-                existingOnly: {
-                    type: 'boolean',
-                    description: 'When true, only revert files that currently exist (skip deleted files).',
-                },
-            },
-        },
-        buildRequest: (params) => {
-            const body = pickDefined(params, ['glob', 'commit', 'existingOnly']);
-            return [getEndpoint('vcsRevert').path, body];
-        },
-    },
-    {
-        name: 'watcher_vcs_exclude',
-        description: 'Exclude or re-include paths from version tracking',
-        parameters: {
-            type: 'object',
-            required: ['glob'],
-            properties: {
-                glob: {
-                    type: 'string',
-                    description: 'Glob pattern to exclude or re-include.',
-                },
-                root: {
-                    type: 'string',
-                    description: 'Tracked root to target (defaults to auto-detect).',
-                },
-                remove: {
-                    type: 'boolean',
-                    description: 'When true, remove the exclusion rule (re-include the path).',
-                },
-            },
-        },
-        buildRequest: (params) => {
-            const body = pickDefined(params, ['glob', 'root', 'remove']);
-            return [getEndpoint('vcsExclude').path, body];
-        },
-    },
-    {
-        name: 'watcher_vcs_check',
-        description: 'Check whether a path is excluded from version tracking and why',
-        parameters: {
-            type: 'object',
-            required: ['path'],
-            properties: {
-                path: {
-                    type: 'string',
-                    description: 'File path to check exclusion status for.',
-                },
-            },
-        },
-        buildRequest: (params) => [
-            `${getEndpoint('vcsCheckExclusion').path}${buildQuery(params, ['path'])}`,
-        ],
-    },
-];
-
-/**
- * @module plugin/watcherTools
- * Domain-specific watcher tool registrations (14 tools) for the OpenClaw plugin.
- */
-/**
- * Register the 14 domain-specific watcher_* tools with the OpenClaw plugin API.
- *
- * @remarks
- * `watcher_search` and `watcher_scan` are `catalogMode: 'direct-only'` so
- * OpenClaw Tool Search keeps them model-visible: semantic search must be a
- * direct tool or the model reaches for grep first. All other tools remain
- * catalog-eligible.
- */
-function registerWatcherTools(api, baseUrl) {
-    const tools = [
-        {
-            name: 'watcher_search',
-            description: 'Semantic search over indexed documents. Supports Qdrant filters. This is a direct tool: call it directly, never through tool_call.',
-            catalogMode: 'direct-only',
-            parameters: {
-                type: 'object',
-                required: ['query'],
-                properties: {
-                    query: { type: 'string', description: 'Search query text.' },
-                    limit: { type: 'number', description: 'Max results (default 10).' },
-                    offset: {
-                        type: 'number',
-                        description: 'Number of results to skip for pagination.',
-                    },
-                    filter: { type: 'object', description: 'Qdrant filter object.' },
-                },
-            },
-            buildRequest: (params) => {
-                const body = pickDefined(params, [
-                    'query',
-                    'limit',
-                    'offset',
-                    'filter',
-                ]);
-                return [getEndpoint('search').path, body];
-            },
-        },
-        {
-            name: 'watcher_enrich',
-            description: 'Set or update metadata on a document by file path.',
-            parameters: {
-                type: 'object',
-                required: ['path', 'metadata'],
-                properties: {
-                    path: {
-                        type: 'string',
-                        description: 'Relative file path of the document.',
-                    },
-                    metadata: {
-                        type: 'object',
-                        description: 'Key-value metadata to set on the document.',
-                    },
-                },
-            },
-            buildRequest: (params) => [
-                getEndpoint('metadata').path,
-                { path: params.path, metadata: params.metadata },
-            ],
-        },
-        {
-            name: 'watcher_validate',
-            description: 'Validate a candidate config (or current config if omitted). Optionally test file paths against the config to preview rule matching and metadata output.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    config: {
-                        type: 'object',
-                        description: 'Candidate config (partial or full). Omit to validate current config.',
-                    },
-                    testPaths: {
-                        type: 'array',
-                        items: { type: 'string' },
-                        description: 'File paths to test against the config for dry-run preview.',
-                    },
-                },
-            },
-            buildRequest: (params) => {
-                const body = pickDefined(params, ['config', 'testPaths']);
-                return [getEndpoint('configValidate').path, body];
-            },
-        },
-        {
-            name: 'watcher_reindex',
-            description: 'Trigger a reindex of the watched files.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    scope: {
-                        type: 'string',
-                        enum: ['rules', 'full', 'issues', 'path', 'prune'],
-                        description: 'Reindex scope: "rules" (default) re-applies inference rules; "full" re-embeds everything; "issues" re-processes files with errors; "path" reindexes a specific file or directory (requires path parameter); "prune" deletes points for files no longer in watch scope.',
-                    },
-                    path: {
-                        oneOf: [
-                            { type: 'string' },
-                            { type: 'array', items: { type: 'string' } },
-                        ],
-                        description: 'Target file or directory path (required when scope is "path"). Accepts a single path or array of paths.',
-                    },
-                    dryRun: {
-                        type: 'boolean',
-                        description: 'When true, compute and return the blast area plan without executing. Returns counts by root showing impact.',
-                    },
-                },
-            },
-            buildRequest: (params) => [
-                getEndpoint('reindex').path,
-                {
-                    scope: params.scope ?? 'rules',
-                    ...(params.path ? { path: params.path } : {}),
-                    ...(params.dryRun ? { dryRun: true } : {}),
-                },
-            ],
-        },
-        {
-            name: 'watcher_scan',
-            description: 'Filter-only point query without vector search. Returns metadata for points matching a Qdrant filter. Use for structural queries: file enumeration, staleness checks, delta computation. Use watcher_search for semantic/similarity queries. This is a direct tool: call it directly, never through tool_call.',
-            catalogMode: 'direct-only',
-            parameters: {
-                type: 'object',
-                required: ['filter'],
-                properties: {
-                    filter: {
-                        type: 'object',
-                        description: 'Qdrant filter object (required).',
-                    },
-                    limit: {
-                        type: 'number',
-                        description: 'Page size (default 100, max 1000).',
-                    },
-                    cursor: {
-                        type: 'string',
-                        description: 'Opaque cursor from previous response for pagination.',
-                    },
-                    fields: {
-                        type: 'array',
-                        items: { type: 'string' },
-                        description: 'Payload fields to return (projection).',
-                    },
-                    countOnly: {
-                        type: 'boolean',
-                        description: 'If true, return { count } instead of points.',
-                    },
-                },
-            },
-            buildRequest: (params) => {
-                const body = pickDefined(params, [
-                    'filter',
-                    'limit',
-                    'cursor',
-                    'fields',
-                    'countOnly',
-                ]);
-                return [getEndpoint('scan').path, body];
-            },
-        },
-        {
-            name: 'watcher_issues',
-            description: 'Get runtime embedding failures. Shows files that failed processing and why.',
-            parameters: { type: 'object', properties: {} },
-            buildRequest: () => [getEndpoint('issues').path],
-        },
-        {
-            name: 'watcher_walk',
-            description: 'Walk watched filesystem paths with glob intersection. Returns matching file paths from all configured watch roots, applying watch.ignored and gitignore filtering.',
-            parameters: {
-                type: 'object',
-                required: ['globs'],
-                properties: {
-                    globs: {
-                        type: 'array',
-                        items: { type: 'string' },
-                        description: 'Glob patterns to intersect with watch paths (e.g., ["**/.meta/meta.json"]).',
-                    },
-                },
-            },
-            buildRequest: (params) => [
-                getEndpoint('walk').path,
-                { globs: params.globs },
-            ],
-        },
-        ...vcsToolConfigs,
-    ];
-    for (const tool of tools) {
-        registerApiTool(api, baseUrl, tool);
-    }
-}
-
 /**
  * @module plugin
  * OpenClaw plugin entry point. Registers the jeeves-watcher tools and the
@@ -29890,16 +31511,16 @@ const PLUGIN_VERSION = getPackageVersion(import.meta.url);
 function register(api) {
     warnIfConfigRootUnset(api);
     const toolApi = withGuardedTools(api, createLazyCore(api));
-    // 4 standard tools from core factory: watcher_status, watcher_config,
-    // watcher_config_apply, watcher_service. `apiUrl` is resolved lazily on
-    // every call, so the HTTP tools honour the configured URL (defaultPort is
-    // only core's fallback).
-    for (const tool of createPluginToolset(createWatcherComponent(PLUGIN_VERSION), { apiUrl: () => getApiUrl(api) })) {
-        toolApi.registerTool(tool, { optional: true });
-    }
-    // 14 domain-specific tools (search, enrich, scan, vcs, ...).
-    registerWatcherTools(toolApi, getApiUrl(api));
-    registerWatcherPromptContext(api);
+    const component = createWatcherComponent(PLUGIN_VERSION);
+    // Every tool comes from core's toolset over WATCHER_CATALOG (D38): the 4
+    // standard tools and the 14 domain tools, in their 0.17.0 order. Each
+    // resolves the base URL (and, where its entry requires it, the bearer key)
+    // on every call.
+    const catalogTools = createCatalogTools(api, component);
+    for (const name of WATCHER_TOOL_NAMES) {
+        registerCatalogTool(toolApi, catalogTools, name);
+    }
+    registerWatcherPromptContext(api, component);
 }
 
 export { register as default };