@karmaniverous/jeeves-watcher 0.19.1 → 0.21.0-0

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

@@ -1,32 +1,41 @@
 #!/usr/bin/env node
-import { substituteEnvVars, DEFAULT_PORTS, postJson, fetchJson, getPackageVersion, createServiceCli } from '@karmaniverous/jeeves';
-import { dirname, resolve, join, relative } from 'node:path';
+import { substituteEnvVars, getPackageVersion, createServiceCli } from '@karmaniverous/jeeves';
+import { resolve, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { jeevesWatcherConfigSchema, LOGGING_DEFAULTS, API_DEFAULTS, EMBEDDING_DEFAULTS, CONFIG_WATCH_DEFAULTS, WATCH_DEFAULTS, ROOT_DEFAULTS, extractWatchPathStrings, INIT_CONFIG_TEMPLATE, DEFAULT_PORT as DEFAULT_PORT$1, PLUGIN_PACKAGE, SERVICE_PACKAGE, COMPONENT_NAME } from '@karmaniverous/jeeves-watcher-core';
+import { isPlainObject as isPlainObject$1, findReservedPropertyNames, sourceConfigSchema, jeevesWatcherConfigSchema, LOGGING_DEFAULTS, API_DEFAULTS, EMBEDDING_DEFAULTS, CONFIG_WATCH_DEFAULTS, WATCH_DEFAULTS, ROOT_DEFAULTS, WATCHER_CATALOG, API_KEY_ENV_VAR, VCS_EXCLUDE_CONFIRM_THRESHOLD, reindexScopeSchema, WATCHER_SKILL, WATCHER_PROMPT_RULES, INIT_CONFIG_TEMPLATE, DEFAULT_PORT as DEFAULT_PORT$1, PLUGIN_PACKAGE, SERVICE_PACKAGE, COMPONENT_NAME } from '@karmaniverous/jeeves-watcher-core';
 import { packageDirectorySync } from 'package-directory';
-import { readFileSync, existsSync, mkdirSync, renameSync, statSync, readdirSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
 import { cosmiconfig } from 'cosmiconfig';
-import { ZodError } from 'zod';
-import { readdir, stat, access } from 'node:fs/promises';
-import { parallel } from 'radash';
-import ignore from 'ignore';
-import picomatch from 'picomatch';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { ZodError, z } from 'zod';
+import { createCatalogClient, CatalogClientError } from '@karmaniverous/jeeves/catalog';
 
 /**
- * @module api/handlers/configMerge
- * Shared config merge utilities.
+ * @module util/threadpool
+ * The libuv threadpool size the service runs with (D170). Pure: edits the given environment object.
  */
+/** `UV_THREADPOOL_SIZE` the service uses unless the environment sets one. */
+const SERVICE_THREADPOOL_SIZE = '16';
 /**
- * Check whether a value is a plain object (not null, not an array).
+ * Default `UV_THREADPOOL_SIZE` to 16, keeping a value already set. libuv
+ * reads it when the threadpool first starts, so this must run before any
+ * threadpool work: the CLI entry imports it first.
  *
- * @param value - Value to check.
- * @returns True for plain objects.
+ * @param env - The environment to edit (`process.env` in the entry).
  */
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
+function ensureThreadpoolSize(env) {
+    env.UV_THREADPOOL_SIZE ??= SERVICE_THREADPOOL_SIZE;
 }
+
+/**
+ * @module cli/jeeves-watcher/threadpool
+ * Side effect only: sets `UV_THREADPOOL_SIZE` (D170) before anything else in the CLI loads. Imported first by the entry point.
+ */
+ensureThreadpoolSize(process.env);
+
+/**
+ * @module api/handlers/configMerge
+ * Shared config merge utilities.
+ */
 /**
  * Deep-merge a config patch into a base config.
  *
@@ -48,7 +57,7 @@ function deepMergeConfig(base, patch) {
                 ? current
                 : undefined, value);
         }
-        else if (isPlainObject(current) && isPlainObject(value)) {
+        else if (isPlainObject$1(current) && isPlainObject$1(value)) {
             result[key] = deepMergeConfig(current, value);
         }
         else {
@@ -83,6 +92,401 @@ function mergeInferenceRules(existing, incoming) {
     return merged;
 }
 
+/**
+ * @module rules/coerceType
+ * Coerces values to target JSON Schema types.
+ */
+/**
+ * Coerce a value to a target type based on JSON Schema type.
+ *
+ * @param value - The value to coerce (typically a string from template interpolation).
+ * @param type - The target JSON Schema type.
+ * @returns The coerced value, or undefined if coercion fails.
+ */
+function coerceType(value, type) {
+    // Null and undefined always coerce to undefined
+    if (value === null || value === undefined) {
+        return undefined;
+    }
+    // Empty strings are only valid for the 'string' type
+    if (value === '' && type !== 'string') {
+        return undefined;
+    }
+    switch (type) {
+        case 'string': {
+            if (typeof value === 'string')
+                return value;
+            if (typeof value === 'number' || typeof value === 'boolean') {
+                return String(value);
+            }
+            if (typeof value === 'object') {
+                // Stringify objects and arrays
+                return JSON.stringify(value);
+            }
+            // Unsupported types (symbol, function, etc.) - undefined
+            return undefined;
+        }
+        case 'integer': {
+            if (typeof value === 'string') {
+                // For strings, check that parsing yields an integer that matches the trimmed input
+                const trimmed = value.trim();
+                const num = parseInt(trimmed, 10);
+                if (Number.isInteger(num) && num.toString() === trimmed) {
+                    return num;
+                }
+                return undefined;
+            }
+            if (typeof value === 'number') {
+                return Number.isInteger(value) ? value : undefined;
+            }
+            return undefined;
+        }
+        case 'number': {
+            const num = typeof value === 'string' ? parseFloat(value) : Number(value);
+            return Number.isFinite(num) ? num : undefined;
+        }
+        case 'boolean': {
+            if (typeof value === 'boolean')
+                return value;
+            if (typeof value === 'string') {
+                const lower = value.toLowerCase();
+                if (lower === 'true')
+                    return true;
+                if (lower === 'false')
+                    return false;
+            }
+            return undefined;
+        }
+        case 'array': {
+            if (Array.isArray(value))
+                return value;
+            if (typeof value === 'string') {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (Array.isArray(parsed))
+                        return parsed;
+                }
+                catch {
+                    // Invalid JSON
+                }
+            }
+            return undefined;
+        }
+        case 'object': {
+            if (typeof value === 'string') {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (typeof parsed === 'object' &&
+                        parsed !== null &&
+                        !Array.isArray(parsed)) {
+                        return parsed;
+                    }
+                }
+                catch {
+                    // Invalid JSON
+                }
+                return undefined;
+            }
+            // Check for plain objects (not array) - null already filtered at top
+            if (typeof value === 'object' && !Array.isArray(value)) {
+                return value;
+            }
+            return undefined;
+        }
+        default:
+            return value;
+    }
+}
+
+/**
+ * @module rules/templates
+ * Resolves Handlebars template expressions in rule `set` objects against file attributes.
+ */
+/**
+ * Resolve a Handlebars template expression against file attributes.
+ *
+ * @param value - The value to resolve (strings are compiled as Handlebars templates).
+ * @param attributes - The file or source attributes for variable lookup.
+ * @param hbs - Handlebars instance with registered helpers.
+ * @returns The resolved value.
+ */
+function resolveTemplateVars(value, attributes, hbs) {
+    if (typeof value !== 'string')
+        return value;
+    return hbs.compile(value, { noEscape: true })(attributes);
+}
+
+/**
+ * @module rules/schemaMerge
+ * Merges schema references into a resolved property schema with set extraction and type coercion.
+ */
+/**
+ * Resolve a schema entry (inline object or file path) to a schema object.
+ *
+ * @param entry - Schema entry (inline object or file path).
+ * @param configDir - Config directory for resolving file paths.
+ * @returns The resolved schema object.
+ */
+function resolveSchemaEntry(entry, configDir) {
+    if (typeof entry === 'string') {
+        // File path - load and parse JSON
+        const resolvedPath = configDir ? resolve(configDir, entry) : entry;
+        const raw = readFileSync(resolvedPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    return entry;
+}
+/**
+ * Merge an array of schema references into a single resolved schema.
+ * Later entries override earlier ones at the property level.
+ *
+ * @param refs - Array of schema references (named strings or inline objects).
+ * @param options - Options for schema merging.
+ * @returns The merged resolved schema.
+ */
+function mergeSchemas(refs, options = {}) {
+    const { globalSchemas = {}, configDir } = options;
+    const merged = { properties: {} };
+    for (const ref of refs) {
+        let schema;
+        if (typeof ref === 'string') {
+            // Named reference - resolve from global schemas
+            const globalEntry = globalSchemas[ref];
+            if (!globalEntry) {
+                throw new Error(`Schema reference "${ref}" not found in global schemas`);
+            }
+            schema = resolveSchemaEntry(globalEntry, configDir);
+        }
+        else {
+            // Inline object
+            schema = ref;
+        }
+        // Merge properties at the property level
+        if (schema.properties) {
+            for (const [propName, propDef] of Object.entries(schema.properties)) {
+                const existing = merged.properties[propName];
+                if (existing) {
+                    const incoming = propDef;
+                    // For array-typed properties, concatenate set values instead of replacing
+                    if (existing.type === 'array' &&
+                        Array.isArray(existing.set) &&
+                        incoming.set !== undefined) {
+                        const existingSet = existing.set;
+                        const incomingSet = Array.isArray(incoming.set)
+                            ? incoming.set
+                            : [incoming.set];
+                        merged.properties[propName] = {
+                            ...existing,
+                            ...propDef,
+                            set: existingSet.concat(incomingSet),
+                        };
+                    }
+                    else {
+                        merged.properties[propName] = {
+                            ...existing,
+                            ...propDef,
+                        };
+                    }
+                }
+                else {
+                    merged.properties[propName] = propDef;
+                }
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Resolve set templates against file attributes and coerce to declared types.
+ *
+ * @param schema - Resolved schema with type information.
+ * @param attributes - File attributes for template variable resolution.
+ * @returns Resolved and type-coerced metadata.
+ */
+function resolveAndCoerce(schema, attributes, hbs) {
+    const result = {};
+    for (const [propName, propDef] of Object.entries(schema.properties)) {
+        const setTemplate = propDef.set;
+        if (setTemplate === undefined)
+            continue;
+        // For array-typed properties with array set values, resolve each element
+        if (Array.isArray(setTemplate)) {
+            const resolved = setTemplate.map((item) => resolveTemplateVars(item, attributes, hbs));
+            result[propName] = resolved;
+            continue;
+        }
+        // Resolve template
+        const rawValue = resolveTemplateVars(setTemplate, attributes, hbs);
+        // Coerce to declared type - returns undefined on failure
+        const coerced = coerceType(rawValue, propDef.type);
+        // Only include if coercion succeeded
+        if (coerced !== undefined) {
+            result[propName] = coerced;
+        }
+    }
+    return result;
+}
+/**
+ * Validate that all properties in a schema have a declared type.
+ * Throws if any property lacks a type.
+ *
+ * @param schema - Resolved schema to validate.
+ * @param ruleName - Name of the rule (for error messages).
+ */
+function validateSchemaCompleteness(schema, ruleName) {
+    for (const [propName, propDef] of Object.entries(schema.properties)) {
+        if (!propDef.type) {
+            throw new Error(`Property "${propName}" in rule "${ruleName}" has no declared type. Every property must have a type.`);
+        }
+    }
+}
+/** Types that can produce trackable facet values. */
+const FACETABLE_TYPES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'integer',
+    'array',
+]);
+/**
+ * Validate that uiHint and enum are only applied to facetable property types.
+ * Throws if a non-facetable type (e.g. object) declares uiHint or enum.
+ *
+ * @param schema - Resolved schema to validate.
+ * @param ruleName - Name of the rule (for error messages).
+ */
+function validateFacetTypes(schema, ruleName) {
+    for (const [propName, propDef] of Object.entries(schema.properties)) {
+        if (!propDef.type)
+            continue;
+        if (!FACETABLE_TYPES.has(propDef.type) &&
+            (propDef.uiHint !== undefined || propDef.enum !== undefined)) {
+            throw new Error(`Property "${propName}" in rule "${ruleName}" has type "${propDef.type}" with uiHint/enum. Facet hints are only valid on string, number, boolean, integer, or array types.`);
+        }
+    }
+}
+
+/**
+ * @module rules/reservedFieldWarnings
+ * Detects inference-rule schema properties named like reserved system payload fields and reports them as non-fatal config warnings (emitted by loadConfig and `/config/validate`). Reads file-based schemas via mergeSchemas.
+ */
+/**
+ * Find rule schema properties that use a reserved system field name.
+ *
+ * Rules whose schemas cannot be resolved are skipped: schema resolution
+ * failures are reported as errors by validation, not as warnings here.
+ *
+ * @param config - Config (or candidate config) with rules and global schemas.
+ * @param configDir - Directory used to resolve file-based schema paths.
+ * @returns One warning per offending rule property.
+ */
+function findReservedFieldWarnings(config, configDir) {
+    const warnings = [];
+    for (const rule of config.inferenceRules ?? []) {
+        if (typeof rule === 'string' || !rule.schema?.length)
+            continue;
+        let properties;
+        try {
+            properties = mergeSchemas(rule.schema, {
+                globalSchemas: config.schemas,
+                configDir,
+            }).properties;
+        }
+        catch {
+            continue;
+        }
+        for (const name of findReservedPropertyNames(properties)) {
+            warnings.push({
+                path: `inferenceRules[${rule.name}].schema.${name}`,
+                message: `Property "${name}" is a reserved system payload field; the system value overwrites rule metadata on upsert. Rename the property.`,
+            });
+        }
+    }
+    return warnings;
+}
+
+/**
+ * @module config/assertResolvedSecrets
+ * Fail-fast check that secret-bearing config values (api.apiKey, sources.*.url and headers) contain no unresolved `${VAR}` after env substitution, and that api.apiKey is not empty. Pure; throws.
+ */
+const UNRESOLVED_PATTERN = /\$\{[^}]*\}/;
+/**
+ * Collect config paths whose secret-bearing value still contains an
+ * unresolved `${…}` reference. Values themselves are never returned.
+ *
+ * @param config - Config after environment-variable substitution.
+ * @returns Dotted paths of offending values.
+ */
+function findUnresolvedSecrets(config) {
+    const paths = [];
+    const check = (path, value) => {
+        if (value !== undefined && UNRESOLVED_PATTERN.test(value))
+            paths.push(path);
+    };
+    check('api.apiKey', config.api?.apiKey);
+    for (const [name, source] of Object.entries(config.sources ?? {})) {
+        check(`sources.${name}.url`, source.url);
+        for (const [header, value] of Object.entries(source.headers ?? {})) {
+            check(`sources.${name}.headers.${header}`, value);
+        }
+    }
+    return paths;
+}
+/**
+ * Throw when any secret-bearing value still contains an unresolved `${…}`,
+ * or when `api.apiKey` is empty after substitution (e.g. its variable is set
+ * to an empty string). Errors name config paths only, never values.
+ *
+ * @param config - Config after environment-variable substitution.
+ * @throws Error listing the offending config paths.
+ */
+function assertResolvedSecrets(config) {
+    const paths = findUnresolvedSecrets(config);
+    if (paths.length > 0) {
+        throw new Error(`Unresolved environment variable reference in: ${paths.join(', ')}. Set the referenced environment variables before starting jeeves-watcher.`);
+    }
+    if (config.api?.apiKey === '') {
+        throw new Error('api.apiKey is empty after environment variable substitution. Set a non-empty key, or remove api.apiKey to disable authentication.');
+    }
+}
+
+/**
+ * @module config/sourceKeyWarnings
+ * Finds unknown keys under `sources.<name>` in a raw (unparsed) config, e.g. a misspelt or unsupported `batchUrl`, which the schema would silently drop. Pure.
+ */
+/** Keys a source entry may carry. */
+const KNOWN_SOURCE_KEYS = new Set(Object.keys(sourceConfigSchema.shape));
+/**
+ * Find keys under `sources.<name>` that the source schema does not define.
+ * Validation strips them, so without this warning a setting such as
+ * `batchUrl` would be ignored without notice.
+ *
+ * @param rawConfig - The config as written (before schema parsing).
+ * @returns One warning per unknown key, in config order.
+ */
+function findUnknownSourceKeys(rawConfig) {
+    if (!isPlainObject$1(rawConfig) || !isPlainObject$1(rawConfig.sources))
+        return [];
+    const warnings = [];
+    for (const [name, source] of Object.entries(rawConfig.sources)) {
+        if (!isPlainObject$1(source))
+            continue;
+        for (const key of Object.keys(source)) {
+            if (KNOWN_SOURCE_KEYS.has(key))
+                continue;
+            warnings.push({
+                path: `sources.${name}.${key}`,
+                message: `Unknown source setting "${key}" is ignored (supported: ${[...KNOWN_SOURCE_KEYS].join(', ')}).`,
+            });
+        }
+    }
+    return warnings;
+}
+
+/**
+ * @module config/loadConfig
+ * Loads the watcher config via cosmiconfig: schema validation, rule/map file resolution, defaults, env substitution and secret checks; reports non-fatal warnings (unknown source keys, reserved rule field names) through onWarning. Reads files.
+ */
 const MODULE_NAME = 'jeeves-watcher';
 /**
  * Merge sensible defaults into a loaded configuration.
@@ -105,10 +509,11 @@ function applyDefaults(raw) {
  * Load the jeeves-watcher configuration.
  *
  * @param configPath - Optional explicit path to a config file.
+ * @param options - Optional warning sink.
  * @returns The loaded configuration.
  * @throws If no configuration is found or validation fails.
  */
-async function loadConfig(configPath) {
+async function loadConfig(configPath, options = {}) {
     const explorer = cosmiconfig(MODULE_NAME);
     const result = configPath
         ? await explorer.load(configPath)
@@ -145,7 +550,15 @@ async function loadConfig(configPath) {
             }
         }
         const withDefaults = applyDefaults(validated);
-        return substituteEnvVars(withDefaults);
+        const substituted = substituteEnvVars(withDefaults);
+        assertResolvedSecrets(substituted);
+        const warnings = [
+            ...findUnknownSourceKeys(result.config),
+            ...findReservedFieldWarnings(substituted, configDir),
+        ];
+        for (const warning of warnings)
+            options.onWarning?.(warning);
+        return substituted;
     }
     catch (error) {
         if (error instanceof ZodError) {
@@ -209,8 +622,102 @@ function migrateConfigPath(configDir) {
 
 /**
  * @module app/shutdown
- * Process signal shutdown orchestration. Installs SIGINT/SIGTERM handlers that invoke a provided async stop function.
+ * Shutdown orchestration: closes the API server first (no new notifies), stops producers, drains and stops queues with timeouts, and closes stores only when no abandoned run is still in flight. Installs SIGINT/SIGTERM handlers.
+ */
+/**
+ * Wait for a promise, giving up after `timeoutMs`.
+ *
+ * @param promise - The work to wait for (its rejection counts as settled).
+ * @param timeoutMs - Maximum wait in milliseconds.
+ * @returns `true` when settled in time, `false` on timeout.
+ */
+async function settlesWithin(promise, timeoutMs) {
+    let timer;
+    const settled = await Promise.race([
+        promise.then(() => true, () => true),
+        new Promise((resolve) => {
+            timer = setTimeout(() => {
+                resolve(false);
+            }, timeoutMs);
+        }),
+    ]);
+    clearTimeout(timer);
+    return settled;
+}
+/**
+ * Wait for a step, warning when it times out.
+ *
+ * @returns `true` when the step settled in time.
+ */
+async function step(label, work, timeoutMs, logger) {
+    const done = await settlesWithin(work, timeoutMs);
+    if (!done) {
+        logger?.warn({ timeoutMs, step: label }, `${label} timeout hit, forcing shutdown`);
+    }
+    return done;
+}
+/**
+ * Drain a queue, then stop it (whatever the drain did); each step bounded.
+ *
+ * @returns `true` when the stop finished, i.e. no run is still in flight.
+ */
+async function drainThenStop(label, queue, timeoutMs, logger) {
+    await step(`${label} drain`, queue.drain(), timeoutMs, logger);
+    return step(`${label} stop`, queue.stop(), timeoutMs, logger);
+}
+/**
+ * Drain and stop the file queue, then the source notify queue. Stopping
+ * drops work the drain did not reach, refuses new work and waits for
+ * in-flight runs; each step is bounded by `timeoutMs`.
+ *
+ * @param queues - The queues (absent ones are skipped).
+ * @param timeoutMs - Per-step timeout in milliseconds.
+ * @param logger - Logger for timeout warnings.
+ * @returns `true` when every stop finished, i.e. no run is still in flight.
+ */
+async function drainQueues(queues, timeoutMs, logger) {
+    let idle = true;
+    if (queues.queue) {
+        idle = await drainThenStop('Queue', queues.queue, timeoutMs, logger);
+    }
+    if (queues.sourceQueue) {
+        const { sourceQueue } = queues;
+        const stopped = await drainThenStop('Source queue', sourceQueue, timeoutMs, logger);
+        idle = stopped && idle;
+    }
+    return idle;
+}
+/**
+ * Stop every component in a safe order: close the API server (bounded), stop
+ * producers, drain and stop the queues (bounded), flush the values index, and
+ * close stores. When a queue step or a producer's bounded stop timed out, runs may still be in flight, so
+ * stores are left open (the process exits) rather than closed under them.
+ *
+ * @param components - The components.
+ * @param timeoutMs - Per-step timeout in milliseconds.
+ * @param logger - Logger for warnings.
  */
+async function shutdownComponents(components, timeoutMs, logger) {
+    const { server, producers = [], valuesManager, stores = [] } = components;
+    if (server)
+        await step('API server close', server.close(), timeoutMs, logger);
+    let producersIdle = true;
+    for (const producer of producers) {
+        if ((await producer?.stop()) === false)
+            producersIdle = false;
+    }
+    const queuesIdle = await drainQueues(components, timeoutMs, logger);
+    const idle = producersIdle && queuesIdle;
+    valuesManager?.stopAutoFlush();
+    valuesManager?.flush();
+    if (idle) {
+        for (const store of stores)
+            store?.close();
+    }
+    else {
+        logger?.warn('Runs still in flight after shutdown timeout; stores left open');
+    }
+}
 /**
  * Install process signal handlers.
  *
@@ -262,10 +769,16 @@ async function startFromConfig(configPath, descriptor) {
             resolvedPath = undefined;
         }
     }
-    const config = await loadConfig(resolvedPath);
+    // The logger is built from the config, so load-time warnings go to the
+    // console like the migration warnings above.
+    const config = await loadConfig(resolvedPath, {
+        onWarning: (warning) => {
+            console.warn(`[jeeves-watcher] ${warning.path}: ${warning.message}`);
+        },
+    });
     // Dynamic import breaks the circular dependency between this module
     // and app/index.ts (which defines JeevesWatcher and re-exports startFromConfig).
-    const { JeevesWatcher } = await import('./index-C_bf9c9m.js');
+    const { JeevesWatcher } = await import('./index-CGVLEt3K.js');
     const app = new JeevesWatcher(config, resolvedPath, descriptor);
     installShutdownHandlers(() => app.stop());
     await app.start();
@@ -273,1183 +786,748 @@ async function startFromConfig(configPath, descriptor) {
 }
 
 /**
- * @module gitignore
- * Processor-level gitignore filtering. Scans watched paths for `.gitignore` files in git repos, caches parsed patterns, and exposes `isIgnored()` for path checking.
+ * @module WatcherError
+ * The single error class thrown by the SDK: client-side validation, timeouts, network failures, non-2xx responses and unparseable responses. No I/O.
  */
 /**
- * Find the git repo root by walking up from `startDir` looking for `.git/`.
- * Returns `undefined` if no repo is found.
+ * The one error type thrown by every SDK call. The SDK never retries; inspect
+ * `status` and `code` to decide whether to.
  */
-function findRepoRoot(startDir) {
-    let dir = resolve(startDir);
-    const root = resolve('/');
-    while (dir !== root) {
-        if (existsSync(join(dir, '.git')) &&
-            statSync(join(dir, '.git')).isDirectory()) {
-            return dir;
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
+class WatcherError extends Error {
+    /** Machine-readable code: a {@link WatcherClientErrorCode} or a server code. */
+    code;
+    /** HTTP status, when a response was received. */
+    status;
+    /** Structured details (Zod issues, server `details`, or the raw body). */
+    details;
+    /**
+     * Delay the server asked for before a retry (`Retry-After` on a `503` or
+     * `429`), in milliseconds, clamped to 0..3,600,000 (D78). The SDK never
+     * waits or retries itself.
+     */
+    retryAfterMs;
+    /**
+     * Create a watcher error.
+     *
+     * @param init - Code, message and optional status, details, retry delay and cause.
+     */
+    constructor(init) {
+        super(init.message, init.cause === undefined ? {} : { cause: init.cause });
+        this.name = 'WatcherError';
+        this.code = init.code;
+        this.status = init.status;
+        this.details = init.details;
+        this.retryAfterMs = init.retryAfterMs;
     }
-    return undefined;
 }
 /**
- * Convert a watch path (directory, file path, or glob) to a concrete directory
- * that can be scanned for a repo root.
+ * Type guard for {@link WatcherError}.
+ *
+ * @param value - Any value (typically a caught error).
+ * @returns `true` when `value` is a {@link WatcherError}.
  */
-function watchPathToScanDir(watchPath) {
-    const absPath = resolve(watchPath);
-    try {
-        return statSync(absPath).isDirectory() ? absPath : dirname(absPath);
-    }
-    catch {
-        // ignore
-    }
-    // If this is a glob, fall back to the non-glob prefix.
-    const globMatch = /[*?[{]/.exec(watchPath);
-    if (!globMatch)
-        return undefined;
-    const prefix = watchPath.slice(0, globMatch.index);
-    const trimmed = prefix.trim();
-    const baseDir = trimmed.length === 0
-        ? '.'
-        : trimmed.endsWith('/') || trimmed.endsWith('\\')
-            ? trimmed
-            : dirname(trimmed);
-    const resolved = resolve(baseDir);
-    if (!existsSync(resolved))
-        return undefined;
-    return resolved;
+function isWatcherError(value) {
+    return value instanceof WatcherError;
 }
+
 /**
- * Recursively find all `.gitignore` files under `dir`.
- * Skips `.git` and `node_modules` directories for performance.
+ * @module documents
+ * The `documents` method group over the catalog's `notifyDocuments` (POST /documents, 202 or ?wait=true) and `deleteDocuments` (POST /documents/delete) entries (D60). Network I/O via the client methods it wraps.
  */
-function findGitignoreFiles(dir) {
-    const results = [];
-    const gitignorePath = join(dir, '.gitignore');
-    if (existsSync(gitignorePath)) {
-        results.push(gitignorePath);
-    }
-    let entries;
-    try {
-        entries = readdirSync(dir);
-    }
-    catch {
-        return results;
-    }
-    for (const entry of entries) {
-        if (entry === '.git' || entry === 'node_modules')
-            continue;
-        const fullPath = join(dir, entry);
-        try {
-            if (statSync(fullPath).isDirectory()) {
-                results.push(...findGitignoreFiles(fullPath));
+/**
+ * Build the `documents` method group.
+ *
+ * @param notifyDocuments - Client method of the `notifyDocuments` entry.
+ * @param deleteDocuments - Client method of the `deleteDocuments` entry.
+ * @returns The {@link DocumentsApi}.
+ */
+function createDocumentsApi(notifyDocuments, deleteDocuments) {
+    return {
+        notify: (async (documents, options) => {
+            const wait = options?.wait === true;
+            const body = await notifyDocuments(wait ? { documents, wait: 'true' } : { documents });
+            if (wait !== 'results' in body) {
+                throw new WatcherError({
+                    code: 'invalid_response',
+                    message: `notifyDocuments answered without ${wait ? 'per-document results' : 'accepted references'}`,
+                    details: body,
+                });
             }
-        }
-        catch {
-            // Skip inaccessible entries
-        }
-    }
-    return results;
+            return body;
+        }),
+        delete: (request) => deleteDocuments(request),
+    };
 }
+
 /**
- * Parse a `.gitignore` file into an `ignore` instance.
+ * @module options
+ * Client options for createWatcherClient and their validation/normalisation (base URL, API key, timeout, fetch injection). Pure; throws WatcherError invalid_options.
  */
-function parseGitignore(gitignorePath) {
-    const content = readFileSync(gitignorePath, 'utf8');
-    return ignore().add(content);
-}
 /**
- * Normalize a path to use forward slashes (required by `ignore` package).
+ * Default request timeout in milliseconds. Shorter than the server's
+ * longest waits (`RootGitLock` 30 s, document lock 10 s): raise `timeoutMs`
+ * for state-changing VCS calls and `documents.notify(..., { wait: true })`.
  */
-function toForwardSlash(p) {
-    return p.replace(/\\/g, '/');
-}
+const DEFAULT_TIMEOUT_MS = 10_000;
+const invalid = (message) => new WatcherError({ code: 'invalid_options', message });
 /**
- * Create an `isGitignored` callback from an optional {@link GitignoreFilter}.
- *
- * Eliminates the repeated inline pattern:
- * ```ts
- * gitignoreFilter ? (filePath: string) => gitignoreFilter!.isIgnored(filePath) : undefined
- * ```
+ * Adapt a {@link FetchLike} to the `fetch` signature jeeves's catalog client
+ * takes. The client always passes a URL string and an init object.
  *
- * @param filter - Optional gitignore filter instance.
- * @returns A callback that checks gitignore status, or `undefined` when no filter is available.
+ * @param fetchImpl - The caller's fetch.
+ * @returns A `typeof fetch` that calls `fetchImpl`.
  */
-function createIsGitignored(filter) {
-    return filter ? (filePath) => filter.isIgnored(filePath) : undefined;
+function adaptFetch(fetchImpl) {
+    return (input, init) => fetchImpl(typeof input === 'string'
+        ? input
+        : input instanceof URL
+            ? input.href
+            : input.url, init ?? {});
 }
 /**
- * Processor-level gitignore filter. Checks file paths against the nearest
- * `.gitignore` chain in git repositories.
+ * Validate and normalise client options.
+ *
+ * @param options - Caller options.
+ * @returns Resolved options.
+ * @throws {@link WatcherError} `invalid_options` on a bad base URL (not http(s), or carrying a query string or fragment), empty API key, non-positive timeout or missing `fetch`.
  */
-class GitignoreFilter {
-    repos = new Map();
-    /**
-     * Create a GitignoreFilter by scanning watched paths for `.gitignore` files.
-     *
-     * @param watchPaths - Absolute paths being watched (directories or globs resolved to roots).
-     */
-    constructor(watchPaths) {
-        this.scan(watchPaths);
+function resolveClientOptions(options) {
+    const { baseUrl, apiKey, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    if (!URL.canParse(baseUrl) || !/^https?:$/.test(new URL(baseUrl).protocol)) {
+        throw invalid(`baseUrl must be an http(s) URL, got "${baseUrl}"`);
     }
-    /**
-     * Scan paths for git repos and their `.gitignore` files.
-     */
-    scan(watchPaths) {
-        this.repos.clear();
-        const scannedDirs = new Set();
-        for (const watchPath of watchPaths) {
-            const scanDir = watchPathToScanDir(watchPath);
-            if (!scanDir)
-                continue;
-            if (scannedDirs.has(scanDir))
-                continue;
-            scannedDirs.add(scanDir);
-            const repoRoot = findRepoRoot(scanDir);
-            if (!repoRoot) {
-                // No git repo found. Check for a standalone .gitignore at the scan dir.
-                // This handles directories like OpenClaw workspaces that have .gitignore
-                // but no .git directory.
-                const standaloneGitignore = join(scanDir, '.gitignore');
-                if (existsSync(standaloneGitignore) && !this.repos.has(scanDir)) {
-                    const entry = {
-                        dir: scanDir,
-                        ig: parseGitignore(standaloneGitignore),
-                    };
-                    this.repos.set(scanDir, { root: scanDir, entries: [entry] });
-                }
-                continue;
-            }
-            if (this.repos.has(repoRoot))
-                continue;
-            const gitignoreFiles = findGitignoreFiles(repoRoot);
-            const entries = gitignoreFiles.map((gf) => ({
-                dir: dirname(gf),
-                ig: parseGitignore(gf),
-            }));
-            // Sort deepest-first so nested `.gitignore` files are checked first
-            entries.sort((a, b) => b.dir.length - a.dir.length);
-            this.repos.set(repoRoot, { root: repoRoot, entries });
-        }
+    // Entry paths are appended to baseUrl, so a query or fragment would
+    // swallow them. Check the raw string: URL drops an empty `?` or `#`.
+    if (/[?#]/.test(baseUrl)) {
+        throw invalid(`baseUrl must not contain a query string or fragment, got "${baseUrl}"`);
     }
-    /**
-     * Check whether a file path is ignored by any applicable `.gitignore`.
-     *
-     * @param filePath - Absolute file path to check.
-     * @returns `true` if the file should be ignored.
-     */
-    isIgnored(filePath) {
-        const absPath = resolve(filePath);
-        for (const [, repo] of this.repos) {
-            // Check if file is within this repo
-            const relToRepo = relative(repo.root, absPath);
-            // On Windows, path.relative() across drives (e.g. D:\ → J:\) produces
-            // an absolute path with a drive letter instead of a relative one. The
-            // `ignore` library rejects these with a RangeError. Skip repos on
-            // different drives to avoid cross-drive gitignore mismatches.
-            if (relToRepo.startsWith('..') ||
-                relToRepo.startsWith(resolve('/')) ||
-                /^[a-zA-Z]:/.test(relToRepo)) {
-                continue;
-            }
-            // Check each `.gitignore` entry (deepest-first)
-            for (const entry of repo.entries) {
-                const relToEntry = relative(entry.dir, absPath);
-                if (relToEntry.startsWith('..') || /^[a-zA-Z]:/.test(relToEntry))
-                    continue;
-                const normalized = toForwardSlash(relToEntry);
-                if (entry.ig.ignores(normalized)) {
-                    return true;
-                }
-            }
-        }
-        return false;
+    if (apiKey?.length === 0) {
+        throw invalid('apiKey must be a non-empty string when set');
     }
-    /**
-     * Invalidate and re-parse a specific `.gitignore` file.
-     * Call when a `.gitignore` file is added, changed, or removed.
-     *
-     * @param gitignorePath - Absolute path to the `.gitignore` file that changed.
-     */
-    invalidate(gitignorePath) {
-        const absPath = resolve(gitignorePath);
-        const gitignoreDir = dirname(absPath);
-        for (const [, repo] of this.repos) {
-            const relToRepo = relative(repo.root, gitignoreDir);
-            if (relToRepo.startsWith('..'))
-                continue;
-            // Remove old entry for this directory
-            repo.entries = repo.entries.filter((e) => e.dir !== gitignoreDir);
-            // Re-parse if file still exists
-            if (existsSync(absPath)) {
-                repo.entries.push({ dir: gitignoreDir, ig: parseGitignore(absPath) });
-                // Re-sort deepest-first
-                repo.entries.sort((a, b) => b.dir.length - a.dir.length);
-            }
-            return;
-        }
-        // If not in any known repo, check if it's in a repo we haven't scanned
-        const repoRoot = findRepoRoot(gitignoreDir);
-        if (repoRoot && existsSync(absPath)) {
-            const entries = [
-                { dir: gitignoreDir, ig: parseGitignore(absPath) },
-            ];
-            if (this.repos.has(repoRoot)) {
-                const repo = this.repos.get(repoRoot);
-                repo.entries.push(entries[0]);
-                repo.entries.sort((a, b) => b.dir.length - a.dir.length);
-            }
-            else {
-                this.repos.set(repoRoot, { root: repoRoot, entries });
-            }
-        }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw invalid('timeoutMs must be a positive number');
+    }
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (fetchImpl === undefined) {
+        throw invalid('No fetch implementation available; pass options.fetch');
     }
+    return {
+        baseUrl: baseUrl.replace(/\/+$/, ''),
+        apiKey,
+        timeoutMs,
+        fetch: adaptFetch(fetchImpl),
+    };
 }
 
 /**
- * @module util/normalizeSlashes
- * Converts backslashes to forward slashes in paths without other transformations.
+ * @module toWatcherError
+ * The one mapping from jeeves's `CatalogClientError` to {@link WatcherError}: the server body's `code` wins; client-side failures get the SDK's own codes; `retryAfterMs` is clamped. Pure.
  */
+/** Largest `retryAfterMs` the SDK reports: one hour (D78). */
+const MAX_RETRY_AFTER_MS = 3_600_000;
 /**
- * Normalize path separators: replace backslashes with forward slashes.
+ * Clamp a server-requested delay to 0..{@link MAX_RETRY_AFTER_MS}.
  *
- * Does NOT lowercase or strip drive letters — use `normalizePath()` if you need that.
- *
- * @param path - The path string to normalize.
- * @returns The path with forward slashes.
+ * @param ms - jeeves's `CatalogClientError.retryAfterMs` (uncapped).
+ * @returns The clamped delay, or `undefined` when the server sent none.
  */
-function normalizeSlashes(path) {
-    return path.replace(/\\/g, '/');
+function clampRetryAfter(ms) {
+    return ms === undefined
+        ? undefined
+        : Math.min(Math.max(ms, 0), MAX_RETRY_AFTER_MS);
 }
-
+const stringField = (body, key) => {
+    const value = body?.[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+};
+/** Longest message kept from a body without a `code` (a proxy's error page, say); the whole body stays in `details`. */
+const MAX_UNCODED_MESSAGE_LENGTH = 200;
 /**
- * @module util/isPathWatched
- * Checks whether a file path falls within the watched scope defined by watch config globs.
+ * Code, message and details of a non-2xx response body.
+ *
+ * @param status - HTTP status.
+ * @param body - jeeves's parsed error body (`{ error, ... }`).
+ * @returns The mapped parts.
  */
+function serverError(status, body) {
+    const error = stringField(body, 'error');
+    const extra = stringField(body, 'message');
+    const message = error === undefined
+        ? (extra ?? `HTTP ${String(status)}`)
+        : extra !== undefined && extra !== error
+            ? `${error}: ${extra}`
+            : error;
+    const code = stringField(body, 'code');
+    return {
+        code: code ?? `http_${String(status)}`,
+        message: code === undefined && message.length > MAX_UNCODED_MESSAGE_LENGTH
+            ? `${message.slice(0, MAX_UNCODED_MESSAGE_LENGTH)}...`
+            : message,
+        details: body !== undefined && 'details' in body ? body.details : body,
+    };
+}
 /**
- * Check whether a file path matches the watched scope.
- * A path is watched if it matches at least one `paths` glob
- * AND does not match any `ignored` glob. Mirrors chokidar's
- * inclusion/exclusion logic.
+ * The SDK code of a failure that produced no response.
  *
- * @param filePath - The file path to check.
- * @param watchPaths - Glob patterns that define watched paths.
- * @param ignoredPaths - Glob patterns that exclude paths (optional).
- * @returns `true` if the file is within watched scope.
- */
-function isPathWatched(filePath, watchPaths, ignoredPaths) {
-    const normalised = normalizeSlashes(filePath);
-    const opts = { dot: true, nocase: process.platform === 'win32' };
-    const isIncluded = picomatch(watchPaths, opts);
-    if (!isIncluded(normalised))
-        return false;
-    if (ignoredPaths && ignoredPaths.length > 0) {
-        const isExcluded = picomatch(ignoredPaths, opts);
-        if (isExcluded(normalised))
-            return false;
-    }
-    return true;
-}
-
-/**
- * @module util/normalizeError
+ * @param cause - The underlying error.
+ * @returns `timeout`, `invalid_response` (an unparseable 2xx body) or `network_error`.
  *
- * Normalizes unknown thrown values into proper Error objects for pino serialization.
+ * @remarks
+ * Assumes jeeves's client wraps a `SyntaxError` only from parsing a 2xx
+ * body; a caller's own `fetch` throwing one before any response would also
+ * read as `invalid_response`.
  */
+function noResponseCode(cause) {
+    if (cause instanceof Error && cause.name === 'TimeoutError')
+        return 'timeout';
+    if (cause instanceof SyntaxError)
+        return 'invalid_response';
+    return 'network_error';
+}
 /**
- * Convert an unknown thrown value into a proper Error with message, stack, and cause.
- * Pino's built-in `err` serializer requires an Error instance to extract message/stack.
+ * Convert a failed catalog call to a {@link WatcherError}.
  *
- * @param error - The caught value (may not be an Error).
- * @returns A proper Error instance.
- */
-function normalizeError(error) {
-    if (error instanceof Error)
-        return error;
-    if (typeof error === 'string')
-        return new Error(error);
-    const message = typeof error === 'object' && error !== null && 'message' in error
-        ? String(error.message)
-        : String(error);
-    const normalized = new Error(message);
-    normalized.cause = error;
-    return normalized;
+ * @param error - What the catalog client threw.
+ * @param operation - Catalog entry name (used in messages).
+ * @param timeoutMs - The client's timeout (used in the timeout message).
+ * @returns The error to throw.
+ */
+function toWatcherError(error, operation, timeoutMs) {
+    if (!(error instanceof CatalogClientError)) {
+        return new WatcherError({
+            code: 'network_error',
+            message: `${operation} request failed: ${String(error)}`,
+            cause: error,
+        });
+    }
+    const retryAfterMs = clampRetryAfter(error.retryAfterMs);
+    const common = {
+        cause: error,
+        ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+    };
+    if (error.status >= 300) {
+        return new WatcherError({
+            ...serverError(error.status, error.body),
+            status: error.status,
+            ...common,
+        });
+    }
+    if (error.issues !== undefined) {
+        const responded = error.status > 0;
+        return new WatcherError({
+            code: responded ? 'invalid_response' : 'invalid_request',
+            message: responded
+                ? `${operation} response did not match the expected shape`
+                : error.message,
+            details: error.issues,
+            ...(responded ? { status: error.status } : {}),
+            ...common,
+        });
+    }
+    const code = noResponseCode(error.cause);
+    const message = code === 'timeout'
+        ? `${operation} timed out after ${String(timeoutMs)} ms`
+        : code === 'invalid_response'
+            ? `${operation} returned a response that is not JSON`
+            : `${operation} request failed: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}`;
+    return new WatcherError({ code, message, ...common });
 }
 
 /**
- * @module util/sleep
- * Abort-aware async sleep.
+ * @module createWatcherClient
+ * Typed watcher API client built on jeeves's catalog client: one method per `WATCHER_CATALOG` entry, named by the entry, plus the `documents` group; every failure is a {@link WatcherError}. Network I/O via fetch.
  */
 /**
- * Sleep for a given duration with optional abort support.
+ * Create a watcher API client.
  *
- * @param ms - Duration in milliseconds.
- * @param signal - Optional abort signal.
- */
-function sleep(ms, signal) {
-    if (ms <= 0)
-        return Promise.resolve();
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            cleanup();
-            resolve();
-        }, ms);
-        const onAbort = () => {
-            cleanup();
-            reject(new Error('Sleep aborted'));
-        };
-        const cleanup = () => {
-            clearTimeout(timer);
-            if (signal)
-                signal.removeEventListener('abort', onAbort);
-        };
-        if (signal) {
-            if (signal.aborted) {
-                onAbort();
-                return;
-            }
-            signal.addEventListener('abort', onAbort, { once: true });
-        }
+ * @example
+ * ```ts
+ * const watcher = createWatcherClient({
+ *   baseUrl: 'http://watcher.internal.example:1936',
+ *   apiKey: process.env.WATCHER_API_KEY,
+ * });
+ * await watcher.documents.notify([{ source: 'app://chat/thread/123', rule: 'chat-thread' }]);
+ * ```
+ *
+ * @param options - Base URL, optional API key, timeout (default 10000 ms) and `fetch`.
+ * @returns A {@link WatcherClient}.
+ * @throws {@link WatcherError} `invalid_options` when the options are invalid.
+ */
+function createWatcherClient(options) {
+    const resolved = resolveClientOptions(options);
+    const catalogClient = createCatalogClient(WATCHER_CATALOG, {
+        baseUrl: resolved.baseUrl,
+        ...(resolved.apiKey === undefined
+            ? {}
+            : { auth: { bearer: resolved.apiKey } }),
+        timeoutMs: resolved.timeoutMs,
+        fetch: resolved.fetch,
     });
+    const methods = Object.fromEntries(WATCHER_CATALOG.entries.map(({ name }) => {
+        const call = catalogClient[name];
+        const method = (input) => call(input).catch((error) => {
+            throw toWatcherError(error, name, resolved.timeoutMs);
+        });
+        return [name, method];
+    }));
+    const { notifyDocuments, deleteDocuments, ...rest } = methods;
+    return {
+        ...rest,
+        documents: createDocumentsApi(notifyDocuments, deleteDocuments),
+    };
 }
 
 /**
- * @module util/retry
- * Small async retry helper with exponential backoff. Side effects: sleeps between attempts; can invoke onRetry callback for logging.
- */
-function computeDelayMs(attempt, baseDelayMs, maxDelayMs, jitter = 0) {
-    const exp = Math.max(0, attempt - 1);
-    const raw = Math.min(maxDelayMs, baseDelayMs * 2 ** exp);
-    const factor = jitter > 0 ? 1 + Math.random() * jitter : 1;
-    return Math.round(raw * factor);
-}
-/**
- * Retry an async operation using exponential backoff.
+ * @module cli/jeeves-watcher/cliClient
+ * The SDK client every API-calling CLI command uses (D37): `http://<host>:<port>`, the resolved bearer key, and a 60 s timeout (D119). Also the key resolution and the key hint printed after a 401. No I/O until a method is called.
  *
- * @param fn - Operation to execute.
- * @param options - Retry policy.
- * @returns The operation result.
- */
-async function retry(fn, options) {
-    const attempts = Math.max(1, options.attempts);
-    const shouldRetry = options.shouldRetry ?? (() => true);
-    let lastError;
-    for (let attempt = 1; attempt <= attempts; attempt++) {
-        try {
-            return await fn(attempt);
-        }
-        catch (error) {
-            lastError = error;
-            const isLast = attempt >= attempts;
-            if (isLast || !shouldRetry(error))
-                break;
-            const delayMs = computeDelayMs(attempt, options.baseDelayMs, options.maxDelayMs, options.jitter);
-            options.onRetry?.({ attempt, attempts, delayMs, error });
-            await sleep(delayMs, options.signal);
-        }
-    }
-    throw lastError;
-}
-
-/**
- * @module vcs/gitExec
- * Shared git execution utilities: the pinned argv prefix, timeouts, error
- * field extraction and classification, and path comparison helpers.
+ * @remarks
+ * Key resolution ({@link resolveApiKey}): the `--api-key` flag, then the
+ * `JEEVES_WATCHER_API_KEY` environment variable (core `API_KEY_ENV_VAR`). The
+ * API commands do not load the watcher config file, so `api.apiKey` from
+ * config is not consulted.
  */
-/** Promisified execFile for git commands. */
-const execFileAsync = promisify(execFile);
 /**
- * Leading git arguments applied to every VCS-owned git invocation.
- *
- * `-c core.longpaths=true` lets Windows checkouts handle paths beyond the
- * legacy MAX_PATH limit (260 chars) without requiring a machine-wide
- * `core.longpaths` git config or registry change. See #249.
+ * Request timeout of every CLI command, in milliseconds (D119): longer than
+ * any server-side wait (`RootGitLock` 30 s, document lock 10 s), so a busy
+ * server's `503` reaches the user instead of a timeout.
  */
-const GIT_BASE_ARGS = ['-c', 'core.longpaths=true'];
+const CLI_TIMEOUT_MS = 60_000;
+/** Where the CLI reads its API key from (named in the 401 hint). */
+const CLI_KEY_SOURCES = `--api-key or the ${API_KEY_ENV_VAR} env var`;
+/** Treat missing and blank values as unset. */
+function nonBlank(value) {
+    return value !== undefined && value.trim() !== '' ? value : undefined;
+}
 /**
- * Build a git argv array with {@link GIT_BASE_ARGS} prefixed.
+ * Resolve the API key for a CLI invocation. Pure.
  *
- * @param args - The subcommand and its arguments (e.g. `'commit', '-m', msg`).
- * @returns The full argv array, base args first.
+ * @param flag - Value of the `--api-key` option, if given.
+ * @param env - Environment to read `API_KEY_ENV_VAR` from.
+ * @returns The first non-blank of `flag` and the env var, or `undefined`.
  */
-function gitArgs(...args) {
-    return [...GIT_BASE_ARGS, ...args];
-}
-/** Standard timeout (ms) for most git operations. */
-const GIT_TIMEOUT_STANDARD = 30_000;
-/** Extended timeout (ms) for cherry-pick operations. */
-const GIT_TIMEOUT_CHERRY_PICK = 120_000;
-/** Timeout (ms) for push operations. */
-const GIT_TIMEOUT_PUSH = 60_000;
-/**
- * Extract string fields from a child-process error.
- * Node's execFile wraps failures in an Error with `stderr`, `stdout`, and
- * `code` properties that aren't part of the Error type.
- */
-function getExecErrorFields(error) {
-    if (!(error instanceof Error)) {
-        return { message: String(error), stderr: '', stdout: '' };
-    }
-    const rec = error;
-    const stderr = typeof rec['stderr'] === 'string' ? rec['stderr'] : '';
-    const stdout = typeof rec['stdout'] === 'string' ? rec['stdout'] : '';
-    return { message: error.message || '', stderr, stdout };
+function resolveApiKey(flag, env = process.env) {
+    return nonBlank(flag) ?? nonBlank(env[API_KEY_ENV_VAR]);
 }
 /**
- * Read the `code` property of an unknown rejection value, if present.
- * execFile rejects with the child's numeric exit status in `code`; fs calls
- * reject with a string errno code (e.g. `'ENOENT'`).
+ * The hint printed after a `401`. Never contains the key. Pure.
  *
- * @param error - The caught value.
- * @returns The code, or undefined if the value has none.
+ * @param keySent - Whether the request carried a bearer key.
+ * @returns Guidance on supplying (or checking) the key.
  */
-function getErrorCode(error) {
-    if (typeof error !== 'object' || error === null || !('code' in error)) {
-        return undefined;
-    }
-    const { code } = error;
-    return typeof code === 'string' || typeof code === 'number'
-        ? code
-        : undefined;
+function unauthorizedHint(keySent) {
+    return keySent
+        ? `The watcher API rejected the API key. Check ${CLI_KEY_SOURCES} against the service's api.apiKey.`
+        : `The watcher API requires an API key. Provide it via ${CLI_KEY_SOURCES}.`;
 }
 /**
- * Check whether an error is caused by `index.lock` contention.
- *
- * Requires the literal `index.lock` in the message or stderr: a bare
- * `EEXIST` (any file that already exists) is not lock contention and must
- * not be retried as if it were. Only Error instances qualify.
+ * The SDK client for a command invocation.
  *
- * @param error - The caught value.
- * @returns true if the error names `index.lock`.
- */
-function isIndexLockError(error) {
-    if (!(error instanceof Error))
-        return false;
-    const { message, stderr } = getExecErrorFields(error);
-    return message.includes('index.lock') || stderr.includes('index.lock');
+ * @param opts - Parsed command options.
+ * @returns A client for `http://<host>:<port>` with the resolved key and
+ *   {@link CLI_TIMEOUT_MS}.
+ */
+function cliClient(opts) {
+    const apiKey = resolveApiKey(opts.apiKey);
+    return createWatcherClient({
+        baseUrl: `http://${opts.host}:${opts.port}`,
+        ...(apiKey === undefined ? {} : { apiKey }),
+        timeoutMs: CLI_TIMEOUT_MS,
+    });
 }
+
 /**
- * Normalize a path for case-insensitive comparison on Windows.
- * On Windows, lowercases the entire path; on other platforms, returns as-is.
- *
- * @param p - The path string to normalize.
- * @param platform - The platform to check against (default: `process.platform`).
- * @returns The normalized path.
+ * @module cli/jeeves-watcher/apiOptions
+ * Commander plumbing shared by the API-calling CLI commands: --port/--host/--api-key, running a command against the SDK client, error reporting (`<code>: <message>` on stderr, exit code 1) and output (pretty JSON or raw text on stdout).
  */
-function normalizePathCase(p, platform = process.platform) {
-    return platform === 'win32' ? p.toLowerCase() : p;
-}
+const DEFAULT_PORT = String(API_DEFAULTS.port);
+const DEFAULT_HOST = API_DEFAULTS.host;
 /**
- * Build a comparison key for an absolute path: resolved, forward slashes,
- * and lowercased on Windows.
+ * Add the standard `--port`, `--host` and `--api-key` options to a command.
+ * The key has no default, so it never appears in `--help` output.
  *
- * @param p - The path.
- * @param platform - The platform to check against (default: `process.platform`).
- * @returns The comparison key.
+ * @param cmd - The command.
+ * @returns The command with the options added.
  */
-function pathKey(p, platform = process.platform) {
-    return normalizePathCase(normalizeSlashes(resolve(p)), platform);
+function withApiOptions(cmd) {
+    return cmd
+        .option('-p, --port <port>', 'API port', DEFAULT_PORT)
+        .option('-H, --host <host>', 'API host', DEFAULT_HOST)
+        .option('--api-key <key>', `API bearer key (defaults to the ${API_KEY_ENV_VAR} environment variable)`);
 }
 /**
- * Find the longest-prefix-match root for a normalized path.
- * Roots must be sorted longest-first for correct nested matching.
+ * Describe a failure as `<code>: <message>`. A 401 adds the key hint; a
+ * timeout of a state-changing command adds that the operation may still
+ * complete on the server, and how to check (D119).
  *
- * @param roots - Root paths sorted longest-first.
- * @param normalizedPath - Normalized absolute path (forward slashes).
- * @param platform - The platform to check against (default: `process.platform`).
- * @returns The matching root, or undefined.
- */
-function findRootForPath(roots, normalizedPath, platform = process.platform) {
-    const comparePath = normalizePathCase(normalizedPath, platform);
-    for (const root of roots) {
-        const compareRoot = normalizePathCase(root, platform);
-        if (comparePath === compareRoot ||
-            comparePath.startsWith(compareRoot + '/')) {
-            return root;
-        }
+ * @param err - What the command threw.
+ * @param apiKey - `--api-key` value, to tell "no key" from "wrong key".
+ * @param checkAfterTimeout - How to check a timed-out state change.
+ * @returns The text to print (one or more lines).
+ */
+function describeError(err, apiKey, checkAfterTimeout) {
+    if (!isWatcherError(err)) {
+        return err instanceof Error ? err.message : String(err);
+    }
+    const lines = [`${err.code}: ${err.message}`];
+    if (err.status === 401) {
+        lines.push(unauthorizedHint(resolveApiKey(apiKey) !== undefined));
+    }
+    if (err.code === 'timeout' && checkAfterTimeout !== undefined) {
+        lines.push(`The operation may still complete on the server; check with ${checkAfterTimeout}.`);
     }
-    return undefined;
+    return lines.join('\n');
 }
-
 /**
- * Best-effort base directory inference for a glob pattern.
+ * Run a command against the SDK client: any failure is printed with
+ * {@link describeError} and sets exit code 1.
  *
- * For our use (watch paths in config), this only needs to be good enough
- * to scan the directory tree in integration tests.
- */
-function globBase(pattern) {
-    const normalised = normalizeSlashes(pattern);
-    const globIdx = normalised.search(/[*?[]/);
-    if (globIdx === -1)
-        return resolve(pattern);
-    const prefix = normalised.slice(0, globIdx);
-    // If prefix ends mid-segment, dirname to get a real directory
-    const base = prefix.endsWith('/') ? prefix.slice(0, -1) : dirname(prefix);
-    return resolve(base);
-}
-async function* walk(dir) {
-    let entries;
+ * @param opts - The command's connection options.
+ * @param fn - The command body.
+ * @param checkAfterTimeout - For state-changing commands: how to check
+ *   whether a timed-out call completed.
+ */
+async function runApiCommand(opts, fn, checkAfterTimeout) {
     try {
-        const dirents = await readdir(dir, { withFileTypes: true });
-        entries = dirents.map((d) => ({
-            name: d.name,
-            isDirectory: d.isDirectory(),
-        }));
+        await fn(cliClient(opts));
     }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        const full = resolve(dir, entry.name);
-        if (entry.isDirectory) {
-            yield* walk(full);
-        }
-        else {
-            // ensure it's a file
-            try {
-                const st = await stat(full);
-                if (st.isFile())
-                    yield full;
-            }
-            catch {
-                // ignore
-            }
-        }
-    }
-}
-/**
- * Walk filesystem trees rooted at the base directories of `patterns`,
- * applying ignore globs, a primary match filter, an optional extra filter,
- * and gitignore filtering. Returns a deduplicated array of matching files.
- */
-async function walkAndFilter(params) {
-    const { patterns, ignored, isGitignored, extraFilter } = params;
-    const normPatterns = patterns.map((p) => normalizeSlashes(p));
-    const normIgnored = ignored.map((p) => normalizeSlashes(p));
-    const match = picomatch(normPatterns, { dot: true, nocase: true });
-    const ignore = normIgnored.length
-        ? picomatch(normIgnored, { dot: true, nocase: true })
-        : () => false;
-    const bases = Array.from(new Set(patterns.map(globBase)));
-    const seen = new Set();
-    for (const base of bases) {
-        for await (const file of walk(base)) {
-            const rel = normalizeSlashes(file);
-            if (ignore(rel))
-                continue;
-            if (!match(rel))
-                continue;
-            if (extraFilter && !extraFilter(rel))
-                continue;
-            if (isGitignored?.(file))
-                continue;
-            seen.add(file);
-        }
+    catch (err) {
+        console.error(describeError(err, opts.apiKey, checkAfterTimeout));
+        process.exitCode = 1;
     }
-    return Array.from(seen);
 }
 /**
- * List files matching a set of globs, with optional ignore globs and gitignore filter.
+ * Print a JSON response to stdout, pretty-printed.
  *
- * @param patterns - Glob patterns to match.
- * @param ignored - Glob patterns to exclude (optional).
- * @param isGitignored - Optional callback to check gitignore status per file.
+ * @param data - The response.
  */
-async function listFilesFromGlobs(patterns, ignored = [], isGitignored) {
-    return walkAndFilter({ patterns, ignored, isGitignored });
+function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
 }
 /**
- * List files from watch root base directories, applying watch extension globs,
- * ignored globs, gitignore, and an additional caller-provided glob intersection filter.
+ * Print a text response to stdout as received.
  *
- * Unlike `listFilesFromGlobs` (which derives walk roots from the glob patterns themselves),
- * this function always walks from watch root base directories and applies the caller's
- * globs as an additional intersection filter within the watched universe.
- *
- * @param watchPatterns - The configured watch path globs (defines the watched universe).
- * @param ignored - Glob patterns to exclude.
- * @param callerGlobs - Additional globs to intersect with. Only files matching both
- *   the watch patterns AND the caller globs are returned.
- * @param isGitignored - Optional callback to check gitignore status per file.
- */
-async function listFilesFromWatchRoots(watchPatterns, ignored, callerGlobs, isGitignored) {
-    const normCaller = callerGlobs.map((p) => normalizeSlashes(p));
-    const matchCaller = picomatch(normCaller, { dot: true, nocase: true });
-    return walkAndFilter({
-        patterns: watchPatterns,
-        ignored,
-        isGitignored,
-        extraFilter: (normalizedPath) => matchCaller(normalizedPath),
-    });
-}
-/**
- * Get the base directories of the configured watch paths.
+ * @param text - The response.
  */
-function getWatchRootBases(watchPatterns) {
-    return Array.from(new Set(watchPatterns.map(globBase)));
+function printText(text) {
+    process.stdout.write(text);
 }
 
 /**
- * @module processAllFiles
+ * @module cli/jeeves-watcher/configCommands
+ * Re-wires core's `config` and `config apply` CLI commands through the SDK client (`config`, `configApply`), adding `--api-key` so they send the bearer key. Reads patches from a file or stdin.
  *
- * Shared helper for processing all files matching configured globs.
+ * @remarks
+ * Core's `createServiceCli` registers both commands with an HTTP helper that
+ * cannot attach headers. This module keeps their names, arguments, options and
+ * output, adds `--api-key` and replaces only the action handlers, which call
+ * the SDK with the CLI's 60 s timeout. Failures print core's prefix, then
+ * `<code>: <message>`. When the commands are absent (e.g. a bare test
+ * program) it does nothing.
  */
-/** Default concurrency limit for reindex operations. */
-const DEFAULT_REINDEX_CONCURRENCY = 50;
-/**
- * Process all files from globs using the specified processor method.
- *
- * @param watchPaths - The glob patterns to match.
- * @param ignoredPaths - The glob patterns to ignore.
- * @param processor - The document processor instance.
- * @param method - The processor method to call ('processFile' or 'processRulesUpdate').
- * @param concurrency - Maximum concurrent file operations (default 50).
- * @param callbacks - Optional progress tracking callbacks.
- * @param isGitignored - Optional callback to check gitignore status per file.
- * @param preComputedFiles - Optional pre-computed file list (skips listFilesFromGlobs).
- * @returns The number of files processed.
- */
-async function processAllFiles(watchPaths, ignoredPaths, processor, method, concurrency = DEFAULT_REINDEX_CONCURRENCY, callbacks, isGitignored, preComputedFiles) {
-    const files = preComputedFiles ??
-        (await listFilesFromGlobs(watchPaths, ignoredPaths, isGitignored));
-    callbacks?.onTotal?.(files.length);
-    await parallel(concurrency, files, async (file) => {
-        await processor[method](file);
-        callbacks?.onFileProcessed?.();
-    });
-    return files.length;
+/** Host core's config commands always address. */
+const CONFIG_HOST = API_DEFAULTS.host;
+/** Parsed options of the re-wired commands; Zod is the source of truth. */
+const configOptsSchema = z.object({
+    port: z.string(),
+    apiKey: z.string().optional(),
+    file: z.string().optional(),
+    replace: z.boolean().optional(),
+});
+/** Find a direct subcommand by name. */
+function findCommand(parent, name) {
+    return parent.commands.find((cmd) => cmd.name() === name);
 }
-
-/**
- * @module api/executeReindex
- * Shared reindex execution logic used by both the reindex handler and the triggerReindex lambda.
- */
-/** Ordered list of valid reindex scopes for validation. */
-const VALID_REINDEX_SCOPES = [
-    'issues',
-    'full',
-    'rules',
-    'path',
-    'prune',
-];
-/**
- * Valid scopes for config-watch auto-trigger.
- * `prune` is excluded - auto-pruning on config change is dangerous.
- */
-const CONFIG_WATCH_VALID_SCOPES = [
-    'issues',
-    'full',
-    'rules',
-];
-/** Fire reindex callback with exponential backoff retry. */
-async function fireCallback(url, payload, logger) {
-    await retry(async () => {
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(payload),
-        });
-        if (!response.ok) {
-            throw new Error(`Non-OK response: ${String(response.status)}`);
-        }
-    }, {
-        attempts: 3,
-        baseDelayMs: 1000,
-        maxDelayMs: 4000,
-        onRetry: ({ attempt, error }) => {
-            logger.warn({ attempt, err: normalizeError(error), url }, 'Reindex callback failed; will retry');
-        },
-    });
+/** Add `--api-key` to a command (no default, so it never shows in help). */
+function addApiKeyOption(cmd) {
+    cmd.option('--api-key <key>', `API bearer key (defaults to the ${API_KEY_ENV_VAR} environment variable)`);
 }
-/**
- * Group file paths by their watch root prefix.
- * Each file is matched against `watchPaths` and grouped under the first matching root.
- * Files that don't match any root are grouped under `'(unmatched)'`.
- */
-function groupByRoot(filePaths, watchPaths) {
-    const byRoot = {};
-    for (const fp of filePaths) {
-        const normalised = normalizeSlashes(fp);
-        let matched = false;
-        for (const root of watchPaths) {
-            const rootNorm = normalizeSlashes(root).replace(/\/?\*\*.*$/, '');
-            if (normalised.startsWith(rootNorm)) {
-                byRoot[rootNorm] = (byRoot[rootNorm] ?? 0) + 1;
-                matched = true;
-                break;
-            }
-        }
-        if (!matched) {
-            byRoot['(unmatched)'] = (byRoot['(unmatched)'] ?? 0) + 1;
-        }
-    }
-    return byRoot;
+/** Print an error with core's prefix and set exit code 1. */
+function reportFailure(prefix, err, apiKey) {
+    console.error(`${prefix}: ${describeError(err, apiKey)}`);
+    process.exitCode = 1;
 }
-/** Default page size for prune scroll (smaller than search to reduce connection strain). */
-const PRUNE_SCROLL_PAGE_SIZE = 500;
-/** Max retry attempts for scroll page failures. */
-const SCROLL_RETRY_ATTEMPTS = 5;
-/** Base delay for scroll retry backoff (ms). */
-const SCROLL_RETRY_BASE_DELAY_MS = 1000;
-/**
- * Scroll one page with retry/resume on connection failure.
- * On failure, retries with exponential backoff from the same cursor.
- */
-async function scrollPageWithRetry(vectorStore, cursor, logger) {
-    let lastError;
-    for (let attempt = 1; attempt <= SCROLL_RETRY_ATTEMPTS; attempt++) {
+/**
+ * Read a config patch from `file`, else from stdin (empty input = `{}`).
+ *
+ * @throws With a one-line message when the file cannot be read, the input
+ *   is not JSON, or it is not a JSON object.
+ */
+async function readPatch(file) {
+    let input;
+    if (file) {
         try {
-            const page = await vectorStore.scrollPage(undefined, PRUNE_SCROLL_PAGE_SIZE, cursor, ['file_path']);
-            return { points: page.points, nextCursor: page.nextCursor };
+            input = readFileSync(file, 'utf-8');
         }
-        catch (error) {
-            lastError = error;
-            if (attempt < SCROLL_RETRY_ATTEMPTS) {
-                const delay = SCROLL_RETRY_BASE_DELAY_MS * Math.pow(2, attempt - 1) +
-                    Math.random() * 500;
-                logger.warn({ attempt, err: normalizeError(error) }, `Prune scroll page failed; retrying in ${String(Math.round(delay))}ms`);
-                await new Promise((resolve) => setTimeout(resolve, delay));
-            }
+        catch (err) {
+            const { code } = err;
+            throw new Error(`cannot read patch file ${file}${typeof code === 'string' ? ` (${code})` : ''}`, { cause: err });
         }
     }
-    throw lastError;
-}
-/** Concurrency limit for fs.access() disk-existence checks. */
-const FS_ACCESS_CONCURRENCY = 100;
-/**
- * Compute the plan for a prune operation using a filter-first approach.
- *
- * 1. Enumerate all watched files from the filesystem → `watchedFiles` set.
- * 2. Scroll Qdrant points. For each point:
- *    - No `file_path` → orphan.
- *    - `file_path` not in `watchedFiles` → orphan (out of watch scope).
- *    - `file_path` in `watchedFiles` → check disk existence via `fs.access()`.
- *      If missing from disk → orphan (deleted file still in index).
- * 3. Batch `fs.access()` checks with bounded concurrency.
- */
-async function computePrunePlan(deps) {
-    const { config, vectorStore, gitignoreFilter, logger } = deps;
-    if (!vectorStore) {
-        throw new Error('vectorStore is required for prune scope');
+    else {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        input = Buffer.concat(chunks).toString('utf-8');
     }
-    // Step 1: Build set of watched files from filesystem
-    const isGitignored = createIsGitignored(gitignoreFilter);
-    const watchedFileList = await listFilesFromGlobs(extractWatchPathStrings(config.watch.paths), config.watch.ignored, isGitignored);
-    const watchedFiles = new Set(watchedFileList.map((f) => normalizePathCase(normalizeSlashes(f))));
-    logger.info({ watchedFileCount: watchedFiles.size }, 'Prune: enumerated watched files from filesystem');
-    // Step 2: Scroll Qdrant and classify points
-    const seenFiles = new Set();
-    const orphanedFiles = new Set();
-    const diskCheckFiles = new Set();
-    const orphanedIds = [];
-    // Map from file_path → point IDs, for points needing disk-existence check
-    const diskCheckPointIds = new Map();
-    let totalPoints = 0;
-    let incomplete = false;
-    let cursor;
+    if (!input.trim())
+        return {};
+    let patch;
     try {
-        let hasMore = true;
-        while (hasMore) {
-            const page = await scrollPageWithRetry(vectorStore, cursor, logger);
-            for (const point of page.points) {
-                totalPoints++;
-                const filePath = point.payload.file_path;
-                if (!filePath) {
-                    orphanedIds.push(point.id);
-                    continue;
-                }
-                const normalized = normalizePathCase(normalizeSlashes(filePath));
-                if (seenFiles.has(normalized)) {
-                    if (orphanedFiles.has(normalized)) {
-                        orphanedIds.push(point.id);
-                    }
-                    else if (diskCheckFiles.has(normalized)) {
-                        // Already queued for disk check — track its ID
-                        const ids = diskCheckPointIds.get(normalized);
-                        if (ids)
-                            ids.push(point.id);
-                    }
-                    continue;
-                }
-                seenFiles.add(normalized);
-                if (!watchedFiles.has(normalized)) {
-                    // Not in watch scope → definitely orphaned
-                    orphanedFiles.add(normalized);
-                    orphanedIds.push(point.id);
-                }
-                else {
-                    // In watch scope → needs disk-existence check
-                    diskCheckFiles.add(normalized);
-                    diskCheckPointIds.set(normalized, [point.id]);
-                }
-            }
-            // Progress logging every 100K points
-            if (totalPoints > 0 && totalPoints % 100000 === 0) {
-                logger.info({ totalPoints, orphanedCount: orphanedIds.length }, 'Prune scroll progress');
-            }
-            if (!page.nextCursor) {
-                hasMore = false;
-            }
-            else {
-                cursor = page.nextCursor;
-            }
-        }
+        patch = JSON.parse(input);
     }
-    catch (error) {
-        logger.error({ err: normalizeError(error), totalPoints, cursor }, 'Prune scroll failed after retries; returning partial plan');
-        incomplete = true;
+    catch (err) {
+        throw new Error(`patch is not valid JSON (${err instanceof Error ? err.message : String(err)})`, { cause: err });
     }
-    // Step 3: Batch fs.access() checks for files in watch scope
-    const filesToCheck = [...diskCheckFiles];
-    await parallel(FS_ACCESS_CONCURRENCY, filesToCheck, async (filePath) => {
-        try {
-            await access(filePath);
-        }
-        catch {
-            // File doesn't exist on disk → orphaned
-            orphanedFiles.add(filePath);
-            const pointIds = diskCheckPointIds.get(filePath);
-            if (pointIds) {
-                orphanedIds.push(...pointIds);
-            }
-        }
-    });
-    const orphanedFileList = [...orphanedFiles];
-    const byRoot = groupByRoot(orphanedFileList, extractWatchPathStrings(config.watch.paths));
-    return {
-        plan: {
-            total: totalPoints,
-            toProcess: 0,
-            toDelete: orphanedIds.length,
-            byRoot,
-            ...(incomplete ? { incomplete: true } : {}),
-        },
-        orphanedIds,
-    };
+    if (!isPlainObject$1(patch))
+        throw new Error('patch must be a JSON object');
+    return patch;
 }
 /**
- * Execute a reindex operation: process files, track progress, and fire callback if configured.
+ * Make core's `config` and `config apply` commands send the bearer key.
  *
- * @param deps - Dependencies.
- * @param scope - Reindex scope: 'issues', 'full', 'rules', 'path', or 'prune'.
- * @param path - Target path (required when scope is 'path').
- * @param dryRun - When true, compute and return the plan without executing.
- * @returns The reindex result including the blast area plan.
- */
-async function executeReindex(deps, scope, path, dryRun = false) {
-    const { config, processor, logger, reindexTracker, valuesManager, gitignoreFilter, } = deps;
-    const isGitignored = createIsGitignored(gitignoreFilter);
-    if (!VALID_REINDEX_SCOPES.includes(scope)) {
-        throw new Error(`Invalid reindex scope: "${scope}". Valid scopes: ${VALID_REINDEX_SCOPES.join(', ')}`);
-    }
-    const pathArray = path
-        ? Array.isArray(path)
-            ? path
-            : [path]
-        : undefined;
-    if (scope === 'path' && (!pathArray || pathArray.length === 0)) {
-        throw new Error('The "path" parameter is required when scope is "path".');
-    }
-    if (scope === 'prune' && !deps.vectorStore) {
-        throw new Error('vectorStore is required for prune scope.');
-    }
-    // Compute plan before starting async work
-    let plan;
-    if (scope === 'prune') {
-        deps.queue?.pause();
-        await deps.queue?.waitForIdleWorkers();
-        let pruneResult;
+ * @param program - The service CLI program, after core registered its commands.
+ */
+function authenticateConfigCommands(program) {
+    const configCmd = findCommand(program, 'config');
+    if (!configCmd)
+        return;
+    addApiKeyOption(configCmd);
+    configCmd.action(async () => {
+        const opts = configOptsSchema.parse(configCmd.opts());
+        const jsonpath = configCmd.args[0];
         try {
-            pruneResult = await computePrunePlan(deps);
+            const client = cliClient({ ...opts, host: CONFIG_HOST });
+            printJson(await client.config(jsonpath ? { path: jsonpath } : {}));
         }
         catch (err) {
-            deps.queue?.resume();
-            throw err;
+            reportFailure('Config query failed', err, opts.apiKey);
         }
-        plan = pruneResult.plan;
-        if (dryRun) {
-            deps.queue?.resume();
-            return { filesProcessed: 0, durationMs: 0, errors: 0, plan };
+    });
+    const applyCmd = findCommand(configCmd, 'apply');
+    if (!applyCmd)
+        return;
+    addApiKeyOption(applyCmd);
+    applyCmd.action(async () => {
+        const opts = configOptsSchema.parse(applyCmd.opts());
+        try {
+            const patch = await readPatch(opts.file);
+            const client = cliClient({ ...opts, host: CONFIG_HOST });
+            printJson(await client.configApply({
+                patch,
+                ...(opts.replace ? { replace: true } : {}),
+            }));
         }
-        // Abort live prune when plan is incomplete — never silently delete partial data
-        if (plan.incomplete) {
-            deps.queue?.resume();
-            logger.error({ totalPoints: plan.total, pointsToDelete: plan.toDelete }, 'Aborting live prune — scroll was incomplete; partial deletes are unsafe');
-            return { filesProcessed: 0, durationMs: 0, errors: 1, plan };
+        catch (err) {
+            reportFailure('Config apply failed', err, opts.apiKey);
         }
-        // Execute prune
-        reindexTracker?.start(scope);
-        const startTime = Date.now();
-        try {
-            if (pruneResult.orphanedIds.length > 0) {
-                const batchSize = 500;
-                for (let i = 0; i < pruneResult.orphanedIds.length; i += batchSize) {
-                    const batch = pruneResult.orphanedIds.slice(i, i + batchSize);
-                    await deps.vectorStore.delete(batch);
-                }
-            }
-            const durationMs = Date.now() - startTime;
-            logger.info({ scope, pointsDeleted: pruneResult.orphanedIds.length, durationMs }, `Reindex (prune) completed`);
-            reindexTracker?.complete();
-            if (config.reindex?.callbackUrl) {
-                await fireCallback(config.reindex.callbackUrl, {
-                    scope,
-                    filesProcessed: 0,
-                    durationMs,
-                    pointsDeleted: pruneResult.orphanedIds.length,
-                    errors: [],
-                }, logger);
-            }
-            return {
-                filesProcessed: 0,
-                durationMs,
-                errors: 0,
-                plan,
-            };
+    });
+}
+
+/**
+ * @module cli/jeeves-watcher/helperFormat
+ * Pure formatting for the `helpers` CLI command: renders JsonMap and Handlebars helper namespaces from GET /config query results as text.
+ */
+/**
+ * Format a helpers section for display. Pure.
+ *
+ * @param title - Section heading.
+ * @param data - Helper namespaces keyed by name.
+ * @returns The rendered section, or `''` when there are no helpers.
+ */
+function formatHelperSection(title, data) {
+    if (!data || Object.keys(data).length === 0)
+        return '';
+    const lines = [`${title}:`];
+    for (const [namespace, entry] of Object.entries(data)) {
+        if (entry.description) {
+            lines.push(`  [${namespace}] ${entry.description}`);
         }
-        catch (error) {
-            const durationMs = Date.now() - startTime;
-            logger.error({ err: normalizeError(error), scope }, 'Prune failed');
-            reindexTracker?.complete();
-            if (config.reindex?.callbackUrl) {
-                await fireCallback(config.reindex.callbackUrl, {
-                    scope,
-                    filesProcessed: 0,
-                    durationMs,
-                    errors: [normalizeError(error).message],
-                }, logger);
+        if (entry.exports) {
+            for (const [name, desc] of Object.entries(entry.exports)) {
+                const descPart = desc ? ` - ${desc}` : '';
+                lines.push(`  ${name.padEnd(40)}${descPart}`);
             }
-            return { filesProcessed: 0, durationMs, errors: 1, plan };
         }
-        finally {
-            deps.queue?.resume();
-        }
-    }
-    // Non-prune scopes: compute plan from file lists
-    let fileList;
-    if (scope === 'issues' && deps.issuesManager) {
-        const issues = deps.issuesManager.getAll();
-        fileList = Object.keys(issues);
-    }
-    else if (scope === 'path' && pathArray) {
-        // Path plan computed inline in the execution block below
-        fileList = undefined;
-    }
-    else if (scope === 'rules' && pathArray && pathArray.length > 0) {
-        // Rules scope with path filter: list from watch roots intersected with caller globs
-        fileList = await listFilesFromWatchRoots(extractWatchPathStrings(config.watch.paths), config.watch.ignored, pathArray, isGitignored);
-    }
-    else {
-        // rules or full: list files from globs
-        fileList = await listFilesFromGlobs(extractWatchPathStrings(config.watch.paths), config.watch.ignored, isGitignored);
-    }
-    if (fileList !== undefined) {
-        plan = {
-            total: fileList.length,
-            toProcess: fileList.length,
-            toDelete: 0,
-            byRoot: groupByRoot(fileList, extractWatchPathStrings(config.watch.paths)),
-        };
-    }
-    if (dryRun) {
-        // For path scope without pre-computed plan, compute it now
-        if (plan === undefined && scope === 'path' && pathArray) {
-            const pathFiles = await collectPathFiles(pathArray, config, deps.gitignoreFilter);
-            plan = {
-                total: pathFiles.length,
-                toProcess: pathFiles.length,
-                toDelete: 0,
-                byRoot: groupByRoot(pathFiles, extractWatchPathStrings(config.watch.paths)),
-            };
+        else {
+            lines.push(`  (no exports introspected)`);
         }
-        return { filesProcessed: 0, durationMs: 0, errors: 0, plan };
     }
-    reindexTracker?.start(scope);
-    const startTime = Date.now();
-    let filesProcessed = 0;
-    let errors = 0;
-    const concurrency = config.reindex?.concurrency ?? 50;
-    try {
-        if (scope === 'full' && valuesManager) {
-            valuesManager.clearAll();
-        }
-        if (scope === 'issues' && fileList) {
-            await parallel(concurrency, fileList, async (filePath) => {
-                try {
-                    await processor.processFile(filePath);
-                    filesProcessed++;
-                }
-                catch (error) {
-                    errors++;
-                    logger.warn({ filePath, err: normalizeError(error) }, 'Failed to reprocess issue file');
-                }
-            });
-        }
-        else if (scope === 'rules') {
-            filesProcessed = await processAllFiles(extractWatchPathStrings(config.watch.paths), config.watch.ignored, processor, 'processRulesUpdate', concurrency, {
-                onTotal: (total) => reindexTracker?.setTotal(total),
-                onFileProcessed: () => reindexTracker?.incrementProcessed(),
-            }, isGitignored, fileList);
-        }
-        else if (scope === 'path' && pathArray) {
-            const uniqueFiles = await collectPathFiles(pathArray, config, deps.gitignoreFilter);
-            plan = {
-                total: uniqueFiles.length,
-                toProcess: uniqueFiles.length,
-                toDelete: 0,
-                byRoot: groupByRoot(uniqueFiles, extractWatchPathStrings(config.watch.paths)),
-            };
-            reindexTracker?.setTotal(uniqueFiles.length);
-            await parallel(concurrency, uniqueFiles, async (filePath) => {
-                await processor.processFile(filePath);
-                reindexTracker?.incrementProcessed();
-                filesProcessed++;
-            });
+    return lines.join('\n');
+}
+
+/**
+ * @module cli/jeeves-watcher/metadataArgs
+ * Parses the `enrich` command's --json and --key options into a metadata object; reports validation errors on stderr and sets the exit code.
+ */
+/** Whether a parsed JSON value is a plain object (not null, an array or a primitive). */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse `--json` and `--key` options into a metadata object.
+ * `--json` must be a JSON object; null, arrays and primitives are rejected.
+ *
+ * @param json - Metadata as a JSON string, if given.
+ * @param keys - `key=value` pairs (applied after `json`).
+ * @returns The metadata, or `null` on validation failure (already reported).
+ */
+function parseMetadataArgs(json, keys) {
+    let metadata = {};
+    if (json) {
+        let parsed;
+        try {
+            parsed = JSON.parse(json);
         }
-        else {
-            // Full reindex
-            filesProcessed = await processAllFiles(extractWatchPathStrings(config.watch.paths), config.watch.ignored, processor, 'processFile', concurrency, {
-                onTotal: (total) => reindexTracker?.setTotal(total),
-                onFileProcessed: () => reindexTracker?.incrementProcessed(),
-            }, isGitignored, fileList);
+        catch {
+            console.error('Invalid JSON:', json);
+            process.exitCode = 1;
+            return null;
         }
-        const durationMs = Date.now() - startTime;
-        logger.info({ scope, filesProcessed, durationMs }, `Reindex (${scope}) completed`);
-        reindexTracker?.complete();
-        if (config.reindex?.callbackUrl) {
-            await fireCallback(config.reindex.callbackUrl, { scope, filesProcessed, durationMs, errors: [] }, logger);
+        if (!isPlainObject(parsed)) {
+            console.error('JSON metadata must be an object:', json);
+            process.exitCode = 1;
+            return null;
         }
-        return { filesProcessed, durationMs, errors, plan };
+        metadata = parsed;
     }
-    catch (error) {
-        errors = 1;
-        const durationMs = Date.now() - startTime;
-        logger.error({ err: normalizeError(error), scope }, 'Reindex failed');
-        reindexTracker?.complete();
-        if (config.reindex?.callbackUrl) {
-            await fireCallback(config.reindex.callbackUrl, {
-                scope,
-                filesProcessed: 0,
-                durationMs,
-                errors: [normalizeError(error).message],
-            }, logger);
+    if (Array.isArray(keys) && keys.length > 0) {
+        for (const pair of keys) {
+            const eqIndex = pair.indexOf('=');
+            if (eqIndex === -1) {
+                console.error(`Invalid key-value pair: ${pair}`);
+                process.exitCode = 1;
+                return null;
+            }
+            metadata[pair.slice(0, eqIndex)] = pair.slice(eqIndex + 1);
         }
-        return { filesProcessed: 0, durationMs, errors, plan };
     }
-}
-/**
- * Collect and deduplicate files for a path-scoped reindex.
- *
- * Iterates over each target path, resolves its file list, and returns a
- * deduplicated array. This eliminates the duplicate iteration + `new Set()`
- * that previously appeared in both the dryRun plan and execution branches.
- */
-async function collectPathFiles(pathArray, config, gitignoreFilter) {
-    const allFiles = [];
-    for (const p of pathArray) {
-        const files = await getPathFileList(p, config, gitignoreFilter);
-        allFiles.push(...files);
+    if (Object.keys(metadata).length === 0) {
+        console.error('No metadata provided. Use --key or --json.');
+        process.exitCode = 1;
+        return null;
     }
-    return [...new Set(allFiles)];
+    return metadata;
 }
+
 /**
- * Get the file list for a path-scoped reindex (for plan computation).
+ * @module cli/jeeves-watcher/vcsCommands
+ * The `vcs` command group (#213): status, history, show, diff, revert, check and exclude, each one SDK call (`getVcsStatus`, `listVcsHistory`, `showVcsFile`, `diffVcs`, `revertVcs`, `checkVcsExclusion`, `excludeVcsPath`). JSON replies print as pretty JSON; `show` and `diff` print the raw text.
  */
-async function getPathFileList(targetPath, config, gitignoreFilter) {
-    const watched = isPathWatched(targetPath, extractWatchPathStrings(config.watch.paths), config.watch.ignored);
-    if (!watched) {
-        throw new Error(`Path is outside watch scope: ${targetPath}`);
-    }
-    if (gitignoreFilter?.isIgnored(targetPath)) {
-        throw new Error(`Path is gitignored: ${targetPath}`);
-    }
-    const stats = await stat(targetPath);
-    if (stats.isFile())
-        return [targetPath];
-    if (stats.isDirectory()) {
-        const isGitignored = createIsGitignored(gitignoreFilter);
-        const allWatchedFiles = await listFilesFromGlobs(extractWatchPathStrings(config.watch.paths), config.watch.ignored, isGitignored);
-        const targetAbsPath = resolve(targetPath);
-        return allWatchedFiles.filter((f) => resolve(f).startsWith(targetAbsPath));
-    }
-    throw new Error(`Path is neither a file nor a directory: ${targetPath}`);
+/** How to check whether a timed-out exclusion completed (D119). */
+const CHECK_EXCLUDE = '`jeeves-watcher vcs check <path>` or `vcs status`';
+/** How to check whether a timed-out revert completed (D119). */
+const CHECK_REVERT = '`jeeves-watcher vcs history <glob>`';
+/**
+ * Register the `vcs` command group.
+ *
+ * @param program - The Commander program.
+ */
+function registerVcsCommands(program) {
+    const vcs = program
+        .command('vcs')
+        .description('Version history of the watched files (/vcs/*)');
+    withApiOptions(vcs
+        .command('status')
+        .description('VCS state of every root (GET /vcs/status)')).action((opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.getVcsStatus());
+    }));
+    withApiOptions(vcs
+        .command('history')
+        .description('Change history of a path or glob (GET /vcs/history)')
+        .argument('<glob>', 'Path or glob inside a VCS root')
+        .option('--since <date>', 'Only commits after this date')
+        .option('--until <date>', 'Only commits before this date')
+        .option('--limit <n>', 'Most commits to return (server default 20)')).action((glob, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.listVcsHistory({
+            glob,
+            since: opts.since,
+            until: opts.until,
+            limit: opts.limit,
+        }));
+    }));
+    withApiOptions(vcs
+        .command('show')
+        .description('File content at a commit (GET /vcs/show)')
+        .argument('<path>', 'File path inside a VCS root')
+        .argument('<commit>', 'Commit to read the file from')).action((path, commit, opts) => runApiCommand(opts, async (client) => {
+        printText(await client.showVcsFile({ path, commit }));
+    }));
+    withApiOptions(vcs
+        .command('diff')
+        .description('Unified diff from a commit (GET /vcs/diff)')
+        .argument('<glob>', 'Path or glob inside a VCS root')
+        .argument('<commit>', 'Commit to diff from')
+        .option('--to <commit>', 'Commit to diff to (default: the working tree)')).action((glob, commit, opts) => runApiCommand(opts, async (client) => {
+        printText(await client.diffVcs({ glob, commit, commitEnd: opts.to }));
+    }));
+    withApiOptions(vcs
+        .command('revert')
+        .description('Restore files from a commit, as a new commit (POST /vcs/revert)')
+        .argument('<glob>', 'Path or glob inside a VCS root')
+        .argument('<commit>', 'Commit to restore from')
+        .option('--existing-only', 'Restore only files that exist now')).action((glob, commit, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.revertVcs({
+            glob,
+            commit,
+            ...(opts.existingOnly ? { existingOnly: true } : {}),
+        }));
+    }, CHECK_REVERT));
+    withApiOptions(vcs
+        .command('check')
+        .description('Whether git ignores a path, and the rule, file and line (GET /vcs/check-exclusion)')
+        .argument('<path>', 'Path inside a VCS root')).action((path, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.checkVcsExclusion({ path }));
+    }));
+    withApiOptions(vcs
+        .command('exclude')
+        .description('Exclude a gitignore pattern from version history (it stays in search) and untrack the files it matches, or remove the exclusion (POST /vcs/exclude)')
+        .argument('<glob>', 'One gitignore pattern (escape brackets to name a file: Report \\[draft\\].docx)')
+        .option('--remove', 'Remove the exclusion instead of adding it')
+        .option('--root <root>', 'VCS root the glob is relative to')
+        .option('--confirm', `Allow untracking more than ${String(VCS_EXCLUDE_CONFIRM_THRESHOLD)} files`)).action((glob, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.excludeVcsPath({
+            glob,
+            root: opts.root,
+            ...(opts.remove ? { remove: true } : {}),
+            ...(opts.confirm ? { confirm: true } : {}),
+        }));
+    }, CHECK_EXCLUDE));
 }
 
 /**
  * @module cli/jeeves-watcher/customCommands
  * Domain-specific CLI commands registered via the descriptor's customCliCommands.
- * Uses fetchJson/postJson from core instead of hand-rolled API helpers.
+ * Every API call is one SDK client call (D37) with a 60 s timeout (`cliClient`), sending the bearer key when one is resolved.
  */
-const DEFAULT_PORT = String(DEFAULT_PORTS.watcher);
-const DEFAULT_HOST = '127.0.0.1';
-/** Build the API base URL from host and port options. */
-function baseUrl(opts) {
-    return `http://${opts.host}:${opts.port}`;
-}
-/** Add standard --port and --host options to a command. */
-function withApiOptions(cmd) {
-    return cmd
-        .option('-p, --port <port>', 'API port', DEFAULT_PORT)
-        .option('-H, --host <host>', 'API host', DEFAULT_HOST);
-}
-/** Wrap an async action with standard error handling. */
-function handleErrors(fn) {
-    return async () => {
-        try {
-            await fn();
-        }
-        catch (err) {
-            console.error(err instanceof Error ? err.message : String(err));
-            process.exitCode = 1;
-        }
-    };
-}
-/** Print JSON response to stdout. */
-function printJson(data) {
-    console.log(JSON.stringify(data, null, 2));
-}
 /**
  * Register all domain-specific commands on the given Commander program.
  *
  * @param program - The Commander program from createServiceCli.
  */
 function registerCustomCommands(program) {
+    // Core's `config` / `config apply` call the API too: give them the key.
+    authenticateConfigCommands(program);
     // --- search ---
     withApiOptions(program
         .command('search')
         .description('Search the vector store (POST /search)')
         .argument('<query>', 'Search query')
-        .option('-l, --limit <limit>', 'Max results', '10')).action(async (query, opts) => {
-        await handleErrors(async () => {
-            const result = await postJson(`${baseUrl(opts)}/search`, {
-                query,
-                limit: Number(opts.limit),
-            });
-            printJson(result);
-        })();
-    });
+        .option('-l, --limit <limit>', 'Max results', '10')).action((query, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.search({ query, limit: Number(opts.limit) }));
+    }));
     // --- enrich ---
     withApiOptions(program
         .command('enrich')
         .description('Enrich document metadata (POST /metadata)')
         .argument('<path>', 'File path to enrich')
         .option('-k, --key <key=value...>', 'Metadata key-value pairs (repeatable)', [])
-        .option('-j, --json <json>', 'Metadata as JSON string (e.g., \'{"key":"value"}\')')).action(async (path, opts) => {
-        await handleErrors(async () => {
-            const metadata = parseMetadataArgs(opts.json, opts.key);
-            if (!metadata)
-                return;
-            const result = await postJson(`${baseUrl(opts)}/metadata`, {
-                path,
-                metadata,
-            });
-            printJson(result);
-        })();
-    });
+        .option('-j, --json <json>', 'Metadata as JSON string (e.g., \'{"key":"value"}\')')).action((path, opts) => runApiCommand(opts, async (client) => {
+        const metadata = parseMetadataArgs(opts.json, opts.key);
+        if (!metadata)
+            return;
+        printJson(await client.setMetadata({ path, metadata }));
+    }));
     // --- scan ---
     withApiOptions(program
         .command('scan')
@@ -1458,138 +1536,80 @@ function registerCustomCommands(program) {
         .option('-l, --limit <limit>', 'Max results', '100')
         .option('-c, --cursor <cursor>', 'Cursor from previous response')
         .option('--fields <fields>', 'Fields to return (comma-separated)')
-        .option('--count-only', 'Return count only')).action(async (opts) => {
-        await handleErrors(async () => {
-            const filterObj = JSON.parse(opts.filter);
-            const result = await postJson(`${baseUrl(opts)}/scan`, {
-                filter: filterObj,
-                limit: Number(opts.limit),
-                cursor: opts.cursor,
-                fields: opts.fields
-                    ? opts.fields.split(',').map((f) => f.trim())
-                    : undefined,
-                countOnly: opts.countOnly,
-            });
-            printJson(result);
-        })();
-    });
+        .option('--count-only', 'Return count only')).action((opts) => runApiCommand(opts, async (client) => {
+        const filter = JSON.parse(opts.filter);
+        printJson(await client.scan({
+            filter,
+            limit: Number(opts.limit),
+            cursor: opts.cursor,
+            fields: opts.fields
+                ? opts.fields.split(',').map((f) => f.trim())
+                : undefined,
+            countOnly: opts.countOnly,
+        }));
+    }));
+    // --- walk ---
+    withApiOptions(program
+        .command('walk')
+        .description('List watched files matching globs (POST /walk)')
+        .argument('<globs...>', 'Glob patterns to intersect with watch paths')).action((globs, opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.walk({ globs }));
+    }));
     // --- reindex ---
     withApiOptions(program
         .command('reindex')
         .description('Trigger a reindex operation (POST /reindex)')
         .option('-s, --scope <scope>', 'Reindex scope (issues|full|rules|path|prune)', 'rules')
-        .option('-t, --path <paths...>', 'Target path(s) for path or rules scope')).action(async (opts) => {
-        await handleErrors(async () => {
-            if (!VALID_REINDEX_SCOPES.includes(opts.scope)) {
-                console.error(`Invalid scope "${opts.scope}". Must be one of: ${VALID_REINDEX_SCOPES.join(', ')}`);
-                process.exitCode = 1;
-                return;
-            }
-            const body = { scope: opts.scope };
-            if (opts.path) {
-                body.path = opts.path.length === 1 ? opts.path[0] : opts.path;
-            }
-            const result = await postJson(`${baseUrl(opts)}/reindex`, body);
-            printJson(result);
-        })();
-    });
+        .option('-t, --path <paths...>', 'Target path(s) for path or rules scope')
+        .option('--dry-run', 'Return the plan without running it')).action((opts) => runApiCommand(opts, async (client) => {
+        const scope = reindexScopeSchema.safeParse(opts.scope);
+        if (!scope.success) {
+            console.error(`Invalid scope "${opts.scope}". Must be one of: ${reindexScopeSchema.options.join(', ')}`);
+            process.exitCode = 1;
+            return;
+        }
+        printJson(await client.reindex({
+            scope: scope.data,
+            ...(opts.path
+                ? { path: opts.path.length === 1 ? opts.path[0] : opts.path }
+                : {}),
+            ...(opts.dryRun ? { dryRun: true } : {}),
+        }));
+    }));
     // --- rebuild-metadata ---
     withApiOptions(program
         .command('rebuild-metadata')
-        .description('Rebuild metadata store from Qdrant (POST /rebuild-metadata)')).action(async (opts) => {
-        await handleErrors(async () => {
-            const result = await postJson(`${baseUrl(opts)}/rebuild-metadata`, {});
-            printJson(result);
-        })();
-    });
+        .description('Rebuild metadata store from Qdrant (POST /rebuild-metadata)')).action((opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.rebuildMetadata({}));
+    }));
     // --- issues ---
     withApiOptions(program
         .command('issues')
-        .description('List current processing issues (GET /issues)')).action(async (opts) => {
-        await handleErrors(async () => {
-            const result = await fetchJson(`${baseUrl(opts)}/issues`);
-            printJson(result);
-        })();
-    });
+        .description('List current processing issues (GET /issues)')).action((opts) => runApiCommand(opts, async (client) => {
+        printJson(await client.listIssues());
+    }));
     // --- helpers ---
-    withApiOptions(program.command('helpers').description('List available helper functions')).action(async (opts) => {
-        await handleErrors(async () => {
-            const base = baseUrl(opts);
-            const mapPath = encodeURIComponent('$.mapHelpers');
-            const tplPath = encodeURIComponent('$.templateHelpers');
-            const [mapResult, tplResult] = await Promise.all([
-                fetchJson(`${base}/config?path=${mapPath}`),
-                fetchJson(`${base}/config?path=${tplPath}`),
-            ]);
-            const mapData = mapResult.result[0];
-            const tplData = tplResult.result[0];
-            const sections = [];
-            const mapSection = formatHelperSection('JsonMap lib functions', mapData);
-            if (mapSection)
-                sections.push(mapSection);
-            const tplSection = formatHelperSection('Handlebars helpers', tplData);
-            if (tplSection)
-                sections.push(tplSection);
-            if (sections.length === 0) {
-                console.log('No helpers configured.');
-            }
-            else {
-                console.log(sections.join('\n\n'));
-            }
-        })();
-    });
-}
-/** Parse --json and --key options into a metadata object. Returns null on validation failure. */
-function parseMetadataArgs(json, keys) {
-    let metadata = {};
-    if (json) {
-        try {
-            metadata = JSON.parse(json);
-        }
-        catch {
-            console.error('Invalid JSON:', json);
-            process.exitCode = 1;
-            return null;
-        }
-    }
-    if (Array.isArray(keys) && keys.length > 0) {
-        for (const pair of keys) {
-            const eqIndex = pair.indexOf('=');
-            if (eqIndex === -1) {
-                console.error(`Invalid key-value pair: ${pair}`);
-                process.exitCode = 1;
-                return null;
-            }
-            metadata[pair.slice(0, eqIndex)] = pair.slice(eqIndex + 1);
-        }
-    }
-    if (Object.keys(metadata).length === 0) {
-        console.error('No metadata provided. Use --key or --json.');
-        process.exitCode = 1;
-        return null;
-    }
-    return metadata;
-}
-/** Format a helpers section for display. */
-function formatHelperSection(title, data) {
-    if (!data || Object.keys(data).length === 0)
-        return '';
-    const lines = [`${title}:`];
-    for (const [namespace, entry] of Object.entries(data)) {
-        if (entry.description) {
-            lines.push(`  [${namespace}] ${entry.description}`);
-        }
-        if (entry.exports) {
-            for (const [name, desc] of Object.entries(entry.exports)) {
-                const descPart = desc ? ` - ${desc}` : '';
-                lines.push(`  ${name.padEnd(40)}${descPart}`);
-            }
-        }
-        else {
-            lines.push(`  (no exports introspected)`);
-        }
-    }
-    return lines.join('\n');
+    withApiOptions(program.command('helpers').description('List available helper functions')).action((opts) => runApiCommand(opts, async (client) => {
+        const query = (path) => client.config({ path });
+        const [mapResult, tplResult] = await Promise.all([
+            query('$.mapHelpers'),
+            query('$.templateHelpers'),
+        ]);
+        const mapData = mapResult.result[0];
+        const tplData = tplResult.result[0];
+        const sections = [];
+        const mapSection = formatHelperSection('JsonMap lib functions', mapData);
+        if (mapSection)
+            sections.push(mapSection);
+        const tplSection = formatHelperSection('Handlebars helpers', tplData);
+        if (tplSection)
+            sections.push(tplSection);
+        console.log(sections.length === 0
+            ? 'No helpers configured.'
+            : sections.join('\n\n'));
+    }));
+    // --- vcs ---
+    registerVcsCommands(program);
 }
 
 /**
@@ -1626,6 +1646,9 @@ const watcherDescriptor = {
     configSchema: jeevesWatcherConfigSchema,
     configFileName: 'config.json',
     initTemplate: () => ({ ...INIT_CONFIG_TEMPLATE }),
+    // Agent-facing text, shared with the plugin through watcher-core.
+    promptRules: WATCHER_PROMPT_RULES,
+    skill: WATCHER_SKILL,
     // onConfigApply is overridden in createApiServer (api/index.ts) via the
     // descriptor passed as a dependency, where it has access to the live
     // reindex tracker and config getter.
@@ -1654,7 +1677,8 @@ const watcherDescriptor = {
  * jeeves-watcher CLI entrypoint.
  * Uses core's createServiceCli factory with the watcher descriptor.
  */
+// First: libuv reads UV_THREADPOOL_SIZE when its threadpool starts (D170).
 const program = createServiceCli(watcherDescriptor);
 program.parse();
 
-export { CONFIG_WATCH_VALID_SCOPES as C, GIT_TIMEOUT_STANDARD as G, VALID_REINDEX_SCOPES as V, normalizeError as a, getErrorCode as b, GIT_TIMEOUT_CHERRY_PICK as c, GIT_TIMEOUT_PUSH as d, execFileAsync as e, normalizePathCase as f, gitArgs as g, findRootForPath as h, isIndexLockError as i, GitignoreFilter as j, executeReindex as k, isPathWatched as l, mergeInferenceRules as m, normalizeSlashes as n, getWatchRootBases as o, pathKey as p, loadConfig as q, retry as r, sleep as s, startFromConfig as t };
+export { validateFacetTypes as a, mergeInferenceRules as b, findReservedFieldWarnings as c, shutdownComponents as d, startFromConfig as e, findUnknownSourceKeys as f, loadConfig as l, mergeSchemas as m, resolveAndCoerce as r, settlesWithin as s, validateSchemaCompleteness as v };