@karmaniverous/jeeves-watcher-openclaw 0.16.0 → 0.17.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { DEFAULT_PORTS, resolvePluginSetting, resolveOptionalPluginSetting, fail, init, resolveWorkspacePath, registerPromptContext, jeevesComponentDescriptorSchema, postJson, fetchJson, ok, connectionFail, getPackageVersion, createPluginToolset } from '@karmaniverous/jeeves';
+import { DEFAULT_PORTS, resolvePluginSetting, resolveOptionalPluginSetting, ok, connectionFail, fail, init, resolveWorkspacePath, registerPromptContext, jeevesComponentDescriptorSchema, getPackageVersion, createPluginToolset } from '@karmaniverous/jeeves';
 import 'node:crypto';
 
 function getEnumValues$1(entries) {
@@ -165,7 +165,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 +185,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 +284,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 +308,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 +387,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 +1166,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 +1565,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 +2157,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 +2190,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 +2260,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 +2686,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 +2788,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 +3224,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 +4106,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 +4333,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 +5229,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 +6249,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 +6358,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 +6648,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 +6676,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 +24122,7 @@ const allowsEval = cached(() => {
         return false;
     }
 });
-function isPlainObject(o) {
+function isPlainObject$1(o) {
     if (isObject(o) === false)
         return false;
     // modified constructor
@@ -23920,7 +24142,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 +24238,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 +24263,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 +26004,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 +26088,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,144 +28661,871 @@ 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.
+ * @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.
  *
- * Both the CLI service and the OpenClaw plugin derive their registrations
- * from this declarative catalog, eliminating drift between the two.
+ * @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']);
+/**
+ * Whether a value is a plain object (not `null`, not an array). The one
+ * definition shared by core and the service.
  *
+ * @param value - Any value.
+ * @returns `true` for a non-null, non-array object.
  */
+const isPlainObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 /**
- * Canonical endpoint catalog for the jeeves-watcher API.
+ * 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);
+/**
+ * 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.
  *
- * 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 filter - A Qdrant filter object.
+ * @returns True when the filter restricts the points it matches.
  */
-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.',
+function hasFilterCondition(filter) {
+    if (FILTER_CLAUSES.some((clause) => clauseHasCondition(filter[clause]))) {
+        return true;
+    }
+    const minShould = filter.min_should;
+    return isPlainObject(minShould) && clauseHasCondition(minShould.conditions);
+}
+/**
+ * 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' });
+/**
+ * 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 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(),
+});
+/**
+ * Error detail attached to a per-document result or rejection (`code` is a
+ * machine-readable error code, e.g. an issue type).
+ */
+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(),
+};
+/**
+ * Refinement requiring exactly one of `path` or `source`.
+ *
+ * @param val - The object being validated.
+ * @param ctx - Zod refinement context.
+ */
+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. */
+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. */
+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. */
+object$1({
+    /** Source whose rules are removed. */
+    source: ruleSourceSchema,
+});
+/** POST /rules/reapply request body. */
+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)',
+    }),
+});
+
+/**
+ * @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`. */
+object$1(documentTargetShape)
+    .superRefine(requireExactlyOneTarget);
+/** Response body for `POST /render`. */
+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. */
+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`. */
+object$1({
+    /** Always true on success. */
+    ok: literal(true),
+    /** Rules whose schemas validated the metadata. */
+    matched_rules: array$1(string$2()),
+});
+
+/**
+ * @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()),
+});
+/**
+ * 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.
+ */
+const ISSUE_TYPES = [
+    'type_collision',
+    'interpolation_error',
+    'extraction_error',
+    'embedding_error',
+    'upsert_error',
+    'match_failed',
+    'rule_missing',
+    'no_content',
+    'source_unavailable',
+    'unsupported_content_type',
+];
+/** 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).');
+/** 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. */
+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`.
+ */
+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 a boolean or the strings
+ * `true`/`false`/`1`/`0`.
+ */
+object$1({
+    /** Process synchronously and return per-document results. */
+    wait: union$1([
+        boolean$2(),
+        stringbool({ truthy: ['true', '1'], falsy: ['false', '0'] }),
+    ])
+        .optional(),
+});
+/** 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). */
+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`. */
+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`.
+ */
+union$1([
+    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`),
+    }),
+    strictObject({
+        /** Qdrant filter selecting the documents to delete (at least one condition). */
+        filter: nonEmptyQdrantFilterSchema,
+    }),
+]);
+/** Response body for `POST /documents/delete`. */
+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
+ *   `.gitignore` entry.
+ * - `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.
+ * - `source_unavailable` (502): the source callback failed.
+ * - `not_available` (503): the feature is not available on this instance
+ *   (no source support, no filesystem watcher). 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',
+    '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(),
+});
+/** 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.
+ */
+strictObject({
+    /** Natural-language query text to embed. */
+    query: string$2().min(1, 'query must be a non-empty string'),
+    /** Maximum results to return. Default: {@link SEARCH_DEFAULT_LIMIT}. */
+    limit: number$2().int().positive().optional(),
+    /** Number of results to skip (pagination). */
+    offset: number$2().int().nonnegative().optional(),
+    /** Optional Qdrant filter. */
+    filter: qdrantFilterSchema.optional(),
+});
+/** A single search hit. */
+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()),
+});
+const SCAN_LIMIT_MESSAGE = `limit must be between 1 and ${String(SCAN_MAX_LIMIT)}`;
+/** Request body for `POST /scan`. */
+object$1({
+    /** Qdrant filter (required). */
+    filter: qdrantFilter(FILTER_REQUIRED_MESSAGE),
+    /** 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(),
+    /** Opaque cursor from a previous page. */
+    cursor: union$1([string$2(), number$2()]).optional(),
+    /** Payload fields to return (projection). */
+    fields: array$1(string$2()).optional(),
+    /** Return only `{ count }`. */
+    countOnly: boolean$2().optional(),
+});
+/** 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`. */
+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(),
+    }),
+]);
+
+/**
+ * @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`.
+ */
+object$1({
+    /** Reindex scope. Default: `issues`. */
+    scope: reindexScopeSchema.optional(),
+    /** 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(),
+})
+    .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. */
+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 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,
+};
+
+/**
+ * @module endpoints
+ * Declarative catalog of every jeeves-watcher HTTP endpoint (name, method, path, description) plus a typed lookup; the single source the service, plugin and SDK derive routes from. Pure.
+ */
+/**
+ * Canonical endpoint catalog for the jeeves-watcher API.
+ *
+ * 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.
+ */
+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 or source reference.',
+    },
+    {
+        name: 'render',
+        method: 'POST',
+        path: '/render',
+        description: 'Render a document (file path, or source reference retrieved through its callback) 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 the enrichment store from vector point payloads (file points only).',
+    },
+    {
+        name: 'reindex',
+        method: 'POST',
+        path: '/reindex',
+        description: 'Trigger a scoped reindex of watched files (scope path also accepts source references).',
+    },
+    {
+        name: 'documents',
+        method: 'POST',
+        path: '/documents',
+        description: 'Notify changed source documents ({ source, rule }); queued and coalesced (202), or processed synchronously with ?wait=true.',
+    },
+    {
+        name: 'documentsDelete',
+        method: 'POST',
+        path: '/documents/delete',
+        description: 'Delete source documents by reference or by Qdrant filter (at least one condition; constrained to points carrying source and no file_path).',
+    },
+    {
+        name: 'issues',
+        method: 'GET',
+        path: '/issues',
+        description: 'Get runtime processing failures. Shows the documents (file path or source reference) 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',
@@ -28594,7 +29543,7 @@ const WATCHER_ENDPOINTS = [
         name: 'vcsStatus',
         method: 'GET',
         path: '/vcs/status',
-        description: 'VCS state for all roots: enabled state, tracked files, last commit, remote status.',
+        description: 'VCS state for all roots: enabled state, tracked files, last commit, remote status, commit circuit breaker state.',
     },
     {
         name: 'vcsHistory',
@@ -28646,6 +29595,169 @@ function getEndpoint(name) {
     return ep;
 }
 
+/**
+ * @module httpContract
+ * The one HTTP client contract shared by the SDK, the CLI and the plugin: the API key env var, bearer header construction and the mapping of a non-2xx response (status + raw body) to `{ status, code, message, details }`. Pure.
+ */
+/** Environment variable holding the watcher API bearer key for clients (CLI, plugin). */
+const API_KEY_ENV_VAR = 'JEEVES_WATCHER_API_KEY';
+/**
+ * Request headers carrying the bearer key.
+ *
+ * @param apiKey - Bearer key; `undefined` means no key.
+ * @returns `{ Authorization: 'Bearer <apiKey>' }`, or `{}` without a key.
+ */
+function bearerHeaders(apiKey) {
+    return apiKey === undefined ? {} : { Authorization: `Bearer ${apiKey}` };
+}
+/**
+ * Parse text as JSON, returning `undefined` when it is empty or not JSON.
+ *
+ * @param text - Raw response body.
+ * @returns The parsed value, or `undefined`.
+ */
+function tryParseJson(text) {
+    if (text.length === 0)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+const stringField = (body, key) => {
+    if (typeof body !== 'object' || body === null)
+        return undefined;
+    const value = body[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+};
+/**
+ * Code and message of a 0.20.0+ error body: `code` is one of the canonical
+ * API error codes and `error` is the human-readable text (`message`, when
+ * present and different, is appended).
+ *
+ * @param body - Parsed response body.
+ * @returns Code and message, or `undefined` for any other body.
+ */
+function canonical(body) {
+    const code = apiErrorCodeSchema.safeParse(stringField(body, 'code'));
+    const error = stringField(body, 'error');
+    if (!code.success || error === undefined)
+        return undefined;
+    const extra = stringField(body, 'message');
+    return {
+        code: code.data,
+        message: extra !== undefined && extra !== error ? `${error}: ${extra}` : error,
+    };
+}
+/**
+ * Map a non-2xx response to its code, message and details.
+ *
+ * - Canonical body (`code` is an `ApiErrorCode`, `error` is a string): `code`
+ *   is `body.code`; `message` is `body.error`, plus `: <body.message>` when
+ *   present.
+ * - Otherwise (older servers, proxies): `code` is `body.code`, else
+ *   `body.error`, else `http_<status>`; `message` is `body.message`, else
+ *   `body.error`, else `HTTP <status> <statusText>`.
+ * - `details`: `body.details` when present, else the parsed body (or raw
+ *   text).
+ *
+ * @param status - HTTP status.
+ * @param statusText - HTTP status text.
+ * @param text - Raw response body.
+ * @returns The mapped error parts.
+ */
+function httpError(status, statusText, text) {
+    const body = tryParseJson(text);
+    const fallbackMessage = `HTTP ${String(status)}${statusText ? ` ${statusText}` : ''}`.trim();
+    const hasDetails = typeof body === 'object' && body !== null && 'details' in body;
+    const details = hasDetails
+        ? body.details
+        : (body ?? (text.length > 0 ? text : undefined));
+    const mapped = canonical(body) ?? {
+        code: stringField(body, 'code') ??
+            stringField(body, 'error') ??
+            `http_${String(status)}`,
+        message: stringField(body, 'message') ??
+            stringField(body, 'error') ??
+            fallbackMessage,
+    };
+    return { status, ...mapped, details };
+}
+/**
+ * One-line text for a mapped error, as the CLI and plugin report it.
+ *
+ * @param info - The mapped error.
+ * @returns `HTTP <status> <code>: <message>`.
+ */
+function formatHttpError(info) {
+    return `HTTP ${String(info.status)} ${info.code}: ${info.message}`;
+}
+/**
+ * Error text for a `401` response. Never contains the key.
+ *
+ * @param keySent - Whether the request carried a bearer key.
+ * @param keySources - Where this client reads its key from (e.g. `--api-key or the JEEVES_WATCHER_API_KEY env var`).
+ * @returns Guidance on supplying (or checking) the key.
+ */
+function unauthorizedMessage(keySent, keySources) {
+    return keySent
+        ? `HTTP 401 unauthorized: the watcher API rejected the API key. Check ${keySources} against the service's api.apiKey.`
+        : `HTTP 401 unauthorized: the watcher API requires an API key. Provide it via ${keySources}.`;
+}
+
+/**
+ * @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/vcs
  * VCS (version control system) configuration schema for git-backed content versioning.
@@ -28749,12 +29861,23 @@ const vcsConfigSchema = object$1({
         .min(5000)
         .default(60000)
         .describe('Age in ms after which an index.lock is considered stale and force-removed. Default: 60000.'),
-    /** Circuit breaker: stop re-queuing after this many consecutive commit failures. */
+    /** Circuit breaker: trip after this many consecutive commit failures. */
     maxConsecutiveFailures: number$2()
         .int()
         .min(1)
         .default(5)
-        .describe('Circuit breaker: stop re-queuing after this many consecutive commit failures. Default: 5.'),
+        .describe('Circuit breaker: trip after this many consecutive commit failures. Default: 5.'),
+    /**
+     * Circuit breaker cooldown in ms. Once tripped, pending files are
+     * retained (re-queued, never discarded) and a single half-open recovery
+     * attempt is allowed once this cooldown elapses — without requiring a
+     * new file-change event.
+     */
+    circuitBreakerCooldownMs: number$2()
+        .int()
+        .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. */
     branch: string$2()
         .min(1)
@@ -28853,13 +29976,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.'),
 });
@@ -28877,6 +29994,11 @@ 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.'),
 });
 /**
  * Logging configuration.
@@ -29024,6 +30146,104 @@ 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/services
  * Service configuration schemas: embedding and vector store.
@@ -29035,11 +30255,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()
@@ -29079,6 +30299,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.'),
 });
 
 /**
@@ -29109,10 +30333,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()
@@ -29168,8 +30392,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.'),
@@ -29200,6 +30424,8 @@ object$1({
     vcs: vcsConfigSchema
         .optional()
         .describe('VCS configuration for git-backed version control of watched content.'),
+    /** 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. */
@@ -29241,9 +30467,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 (`PluginApi`, `ToolResult`, `ok`,
+ * `connectionFail`) should be imported directly from `@karmaniverous/jeeves`;
+ * watcher API requests go through `requestJson` (`./http.js`).
  *
  * @module plugin/helpers
  */
@@ -29261,6 +30488,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.
  *
@@ -29281,6 +30525,164 @@ function getConfigRoot(api) {
     return resolved?.trim() ? resolved : undefined;
 }
 
+/**
+ * @module plugin/http
+ * The plugin's single HTTP helper for watcher API calls: JSON GET/POST via `fetch` with the core bearer header and the core error mapping (errors carry the server `code`; 401 adds key guidance). Never logs the key.
+ */
+/** Where the plugin reads its API key from (named in 401 guidance). */
+const PLUGIN_KEY_SOURCES = `plugins.entries.${PLUGIN_ID}.config.apiKey or the ${API_KEY_ENV_VAR} env var`;
+/**
+ * Build the `fetch` init for a request. With no key and no body this is
+ * `undefined`, exactly as an unauthenticated GET has always been sent.
+ *
+ * @param body - JSON body; `undefined` for a GET.
+ * @param apiKey - Bearer key, if any.
+ * @returns The request init.
+ */
+function buildInit(body, apiKey) {
+    const auth = bearerHeaders(apiKey);
+    if (body === undefined) {
+        return apiKey === undefined ? undefined : { headers: auth };
+    }
+    return {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...auth },
+        body: JSON.stringify(body),
+    };
+}
+/**
+ * Call the watcher API and return the parsed JSON body.
+ *
+ * @param url - Full request URL.
+ * @param body - JSON body; `undefined` sends a GET, anything else a POST.
+ * @param apiKey - Bearer key; `undefined` sends no `Authorization` header.
+ * @returns Parsed JSON response body.
+ * @throws On `401` with core `unauthorizedMessage` (naming
+ *   {@link PLUGIN_KEY_SOURCES}); on any other non-OK status with
+ *   `HTTP <status> <code>: <message>` (core `httpError`); network errors
+ *   propagate unchanged.
+ */
+async function requestJson(url, body, apiKey) {
+    const res = await fetch(url, buildInit(body, apiKey));
+    if (res.status === 401) {
+        throw new Error(unauthorizedMessage(apiKey !== undefined, PLUGIN_KEY_SOURCES));
+    }
+    if (!res.ok) {
+        const info = httpError(res.status, res.statusText, await res.text());
+        throw new Error(formatHttpError(info));
+    }
+    return res.json();
+}
+
+/**
+ * @module plugin/apiTool
+ * Generic HTTP-backed watcher tool registration: config shape, request helpers, and ok/connectionFail wrapping. Requests carry the bearer key (if configured) via `requestJson`.
+ */
+/**
+ * Register a single API tool with standard try/catch + ok/connectionFail.
+ *
+ * @remarks
+ * The bearer key is resolved from `api` ({@link getApiKey}) on every call,
+ * so a key set after registration takes effect without re-registering.
+ */
+function registerApiTool(api, baseUrlSource, config) {
+    const tool = {
+        name: config.name,
+        description: config.description,
+        parameters: config.parameters,
+        ...(config.catalogMode ? { catalogMode: config.catalogMode } : {}),
+        execute: async (_id, params) => {
+            const baseUrl = typeof baseUrlSource === 'function' ? baseUrlSource() : baseUrlSource;
+            try {
+                const [endpoint, body] = config.buildRequest(params);
+                const data = await requestJson(`${baseUrl}${endpoint}`, body, getApiKey(api));
+                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/configTools
+ * Watcher-owned `watcher_config` and `watcher_config_apply` tools: same names, parameters and requests as the core toolset's, but sent through the plugin HTTP helper so they carry the bearer key.
+ *
+ * @remarks
+ * Core's `createPluginToolset` cannot attach request headers, so its two
+ * authenticated HTTP tools are replaced by these (see {@link CORE_TOOLS_REPLACED}).
+ * `watcher_status` stays with core: `GET /status` is always open.
+ */
+/** Core toolset tools that this module replaces. */
+const CORE_TOOLS_REPLACED = new Set([
+    'watcher_config',
+    'watcher_config_apply',
+]);
+/** `watcher_config` and `watcher_config_apply`, as API tool configs. */
+const configToolConfigs = [
+    {
+        name: 'watcher_config',
+        description: 'Query watcher running configuration. Optional JSONPath filter.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'JSONPath expression (optional)',
+                },
+            },
+        },
+        buildRequest: (params) => {
+            const path = params.path;
+            const base = getEndpoint('config').path;
+            return [path ? `${base}?path=${encodeURIComponent(path)}` : base];
+        },
+    },
+    {
+        name: 'watcher_config_apply',
+        description: 'Apply a config patch to the running watcher service.',
+        parameters: {
+            type: 'object',
+            properties: {
+                config: {
+                    type: 'object',
+                    description: 'Config patch to apply',
+                },
+            },
+            required: ['config'],
+        },
+        buildRequest: (params) => {
+            const config = params.config;
+            if (!config)
+                throw new Error('Missing required parameter: config');
+            return [getEndpoint('configApply').path, { patch: config }];
+        },
+    },
+];
+
 /**
  * @module plugin/toolGating
  * Which watcher tool invocations read `configRoot`, and so must be gated on it.
@@ -29290,16 +30692,20 @@ 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` (core standard toolset, `createPluginToolset`): HTTP
+ *   only (`{apiUrl}/status`, resolved per call).
+ * - `watcher_config`, `watcher_config_apply`: implemented by the plugin
+ *   (`configTools.ts`, replacing the core ones so the request carries the
+ *   `Authorization: Bearer` key); HTTP only.
+ * - `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
- * never gated.
+ * The 14 domain tools (7 in `watcherTools.ts`, 7 VCS tools in
+ * `vcsTools.ts`) call the service API via `registerApiTool` →
+ * `requestJson` and are never gated.
  */
 /**
  * Tools whose implementation reads `configRoot`, keyed by tool name. A tool
@@ -29411,7 +30817,7 @@ const WATCHER_PROMPT_CONTEXT = [
     '- **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.',
+    '- **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_vcs_*` tools. See the jeeves-watcher skill for detail.',
 ].join('\n');
 /**
@@ -29428,8 +30834,10 @@ 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()`, of which the plugin registers
+ * `watcher_status` and `watcher_service`; its `watcher_config` and
+ * `watcher_config_apply` are replaced by the plugin's own (`configTools.ts`,
+ * which send the API key). The service descriptor
  * (`packages/service/src/descriptor.ts`) is the canonical source for the
  * config schema and CLI commands.
  */
@@ -29464,53 +30872,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.
@@ -29681,6 +31042,11 @@ const vcsToolConfigs = [
  * 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.
+ *
+ * @param api - Plugin API.
+ * @param baseUrl - API base URL, or a getter resolved on every call (so a
+ *   changed `apiUrl` takes effect without re-registering, as for the config
+ *   tools).
  */
 function registerWatcherTools(api, baseUrl) {
     const tools = [
@@ -29832,7 +31198,7 @@ function registerWatcherTools(api, baseUrl) {
         },
         {
             name: 'watcher_issues',
-            description: 'Get runtime embedding failures. Shows files that failed processing and why.',
+            description: 'Get runtime processing failures. Shows the documents (file path or source reference) that failed processing and why.',
             parameters: { type: 'object', properties: {} },
             buildRequest: () => [getEndpoint('issues').path],
         },
@@ -29879,15 +31245,21 @@ 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).
+    // 4 standard tools: watcher_status and watcher_service from the core
+    // factory; watcher_config and watcher_config_apply re-implemented here so
+    // they send the bearer key (core cannot attach headers). `apiUrl` is
+    // resolved lazily on every call by every tool (defaultPort is only core's
+    // fallback).
     for (const tool of createPluginToolset(createWatcherComponent(PLUGIN_VERSION), { apiUrl: () => getApiUrl(api) })) {
-        toolApi.registerTool(tool, { optional: true });
+        if (!CORE_TOOLS_REPLACED.has(tool.name)) {
+            toolApi.registerTool(tool, { optional: true });
+        }
+    }
+    for (const config of configToolConfigs) {
+        registerApiTool(toolApi, () => getApiUrl(api), config);
     }
     // 14 domain-specific tools (search, enrich, scan, vcs, ...).
-    registerWatcherTools(toolApi, getApiUrl(api));
+    registerWatcherTools(toolApi, () => getApiUrl(api));
     registerWatcherPromptContext(api);
 }