@karmaniverous/jeeves-watcher-openclaw 0.6.2 → 0.8.0

package/README.md

@@ -34,17 +34,30 @@ After install or uninstall, restart the OpenClaw gateway to apply changes.
 
 ## Configuration
 
-Set the `apiUrl` in the plugin configuration to point at your jeeves-watcher service:
+Set the plugin config in `openclaw.json` under `plugins.entries.jeeves-watcher-openclaw.config`:
 
 ```json
 {
-  "apiUrl": "http://127.0.0.1:1936"
+  "apiUrl": "http://127.0.0.1:1936",
+  "configRoot": "j:/config"
 }
 ```
 
-## Dynamic TOOLS.md Injection
+- **`apiUrl`** — jeeves-watcher API base URL (default: `http://127.0.0.1:1936`)
+- **`configRoot`** — platform config root path, used by `@karmaniverous/jeeves` core to derive `{configRoot}/jeeves-watcher/` for component config (default: `j:/config`)
 
-On startup, the plugin writes a `## Watcher` section to `TOOLS.md` in the agent's workspace, providing a live menu of indexed content, score thresholds, and escalation rules. This refreshes every 60 seconds. On uninstall, the CLI removes the section.
+## Architecture
+
+![Plugin Architecture](assets/plugin-architecture.png)
+
+## Jeeves Platform Integration
+
+This plugin integrates with [`@karmaniverous/jeeves`](https://www.npmjs.com/package/@karmaniverous/jeeves) to manage workspace content:
+
+- **TOOLS.md** — writes a `## Watcher` section with a live menu of indexed content, score thresholds, and escalation rules (refreshes every 71 seconds)
+- **SOUL.md / AGENTS.md** — maintains shared platform content via managed sections
+- **Service commands** — exposes `stop`, `uninstall`, and `status` for the watcher service
+- **Plugin commands** — exposes `uninstall` for the plugin itself
 
 ## Tools
 
@@ -53,10 +66,11 @@ On startup, the plugin writes a `## Watcher` section to `TOOLS.md` in the agent'
 | `watcher_status` | Service health, uptime, and collection stats |
 | `watcher_search` | Semantic search across indexed documents |
 | `watcher_enrich` | Enrich document metadata via rules engine |
-| `watcher_query` | Query the merged virtual document via JSONPath |
+| `watcher_config` | Query the effective runtime config via JSONPath |
+| `watcher_walk` | Walk watched filesystem paths with glob intersection |
 | `watcher_validate` | Validate a watcher configuration |
 | `watcher_config_apply` | Apply a new configuration |
-| `watcher_reindex` | Trigger a full reindex |
+| `watcher_reindex` | Trigger a scoped reindex with blast area plan |
 | `watcher_scan` | Filter-only point query with cursor pagination |
 | `watcher_issues` | List indexing issues and errors |
 

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { parseManaged, TOOLS_MARKERS, updateManagedSection } from '@karmaniverous/jeeves';
 import { existsSync, rmSync, mkdirSync, cpSync, readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join, dirname, resolve } from 'path';
@@ -174,7 +175,7 @@ function install() {
     console.log('   Restart the OpenClaw gateway to load the plugin.');
 }
 /** Uninstall the plugin from OpenClaw's extensions directory. */
-function uninstall() {
+async function uninstall() {
     const home = resolveOpenClawHome();
     const configPath = resolveConfigPath(home);
     const extDir = join(home, 'extensions', PLUGIN_ID);
@@ -200,7 +201,7 @@ function uninstall() {
         }
     }
     // Clean up TOOLS.md watcher section
-    cleanupToolsMd(home, configPath);
+    await cleanupToolsMd(home, configPath);
     console.log();
     console.log('✅ Plugin uninstalled successfully.');
     console.log('   Restart the OpenClaw gateway to complete removal.');
@@ -220,39 +221,57 @@ function resolveWorkspaceDir(home, configPath) {
     // Default workspace location
     return join(home, 'workspace');
 }
-/** Remove the ## Watcher section from TOOLS.md on uninstall. */
-function cleanupToolsMd(home, configPath) {
+/**
+ * Remove the Watcher section from TOOLS.md on uninstall.
+ *
+ * @remarks
+ * Uses core's `parseManaged` to locate the managed block and its sections,
+ * then rewrites without the Watcher section via `updateManagedSection`.
+ * If the Watcher section is the only one, removes the entire managed block.
+ */
+async function cleanupToolsMd(home, configPath) {
     const workspaceDir = resolveWorkspaceDir(home, configPath);
     if (!workspaceDir)
         return;
     const toolsPath = join(workspaceDir, 'TOOLS.md');
     if (!existsSync(toolsPath))
         return;
-    let content = readFileSync(toolsPath, 'utf8');
-    // Remove ## Watcher section (from ## Watcher to next ## or # or EOF)
-    const watcherRe = /^## Watcher\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m;
-    if (!watcherRe.test(content))
+    const content = readFileSync(toolsPath, 'utf8');
+    const parsed = parseManaged(content, TOOLS_MARKERS);
+    if (!parsed.found)
         return;
-    content = content.replace(watcherRe, '').replace(/\n{3,}/g, '\n\n');
-    // If # Jeeves Platform Tools has no remaining ## sections, remove it too
-    const platformH1 = '# Jeeves Platform Tools';
-    if (content.includes(platformH1)) {
-        const h1Idx = content.indexOf(platformH1);
-        const afterH1 = content.slice(h1Idx + platformH1.length);
-        // Check if there's a ## before the next # or EOF
-        const nextH2Match = afterH1.match(/^## /m);
-        const nextH1Match = afterH1.match(/^# /m);
-        const h2Pos = nextH2Match ? afterH1.indexOf(nextH2Match[0]) : Infinity;
-        const h1Pos = nextH1Match ? afterH1.indexOf(nextH1Match[0]) : Infinity;
-        if (h2Pos >= h1Pos) {
-            // No child ## sections remain — remove the empty H1
-            content =
-                content.slice(0, h1Idx) + content.slice(h1Idx + platformH1.length);
-            content = content.replace(/^\n{2,}/, '').replace(/\n{3,}/g, '\n\n');
+    const watcherSection = parsed.sections.find((s) => s.id === 'Watcher');
+    if (!watcherSection)
+        return;
+    const remaining = parsed.sections.filter((s) => s.id !== 'Watcher');
+    if (remaining.length === 0) {
+        // No sections left — remove the entire managed block.
+        const parts = [];
+        if (parsed.beforeContent)
+            parts.push(parsed.beforeContent);
+        if (parsed.userContent) {
+            if (parts.length > 0)
+                parts.push('');
+            parts.push(parsed.userContent);
         }
+        const newContent = parts.join('\n').trim() + '\n';
+        writeFileSync(toolsPath, newContent);
+    }
+    else {
+        // Rewrite the managed block without the Watcher section.
+        // We write an empty string for the Watcher section; core's
+        // updateManagedSection will rebuild from the remaining sections.
+        // Actually, the cleanest approach is to rebuild the section text
+        // from the remaining sections and write the entire block.
+        const sectionText = remaining
+            .map((s) => `## ${s.id}\n\n${s.content}`)
+            .join('\n\n');
+        const body = `# ${TOOLS_MARKERS.title}\n\n${sectionText}`;
+        await updateManagedSection(toolsPath, body, {
+            mode: 'block',
+            markers: TOOLS_MARKERS,
+        });
     }
-    content = content.trim() + '\n';
-    writeFileSync(toolsPath, content);
     console.log('\u2713 Cleaned up TOOLS.md (removed Watcher section)');
 }
 // Main
@@ -262,7 +281,7 @@ switch (command) {
         install();
         break;
     case 'uninstall':
-        uninstall();
+        void uninstall();
         break;
     default:
         console.log(`@karmaniverous/jeeves-watcher-openclaw — OpenClaw plugin installer`);

package/dist/index.js

@@ -1,20 +1,45 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { createAsyncContentCache, init, createComponentWriter } from '@karmaniverous/jeeves';
+import { execFile as execFile$1 } from 'node:child_process';
+import { promisify } from 'node:util';
+
+/**
+ * @module plugin/constants
+ * Shared constants for the OpenClaw plugin package.
+ *
+ * @remarks
+ * Imported by both the plugin bundle (`index.ts`) and the CLI bundle
+ * (`cli.ts`). Rollup inlines these into each output independently.
+ */
+/** Plugin identifier used in OpenClaw config and extensions directory. */
+const PLUGIN_ID = 'jeeves-watcher-openclaw';
+/** Default watcher API base URL. */
+const DEFAULT_API_URL = 'http://127.0.0.1:1936';
+/** Default platform config root path. */
+const DEFAULT_CONFIG_ROOT = 'j:/config';
+/** Default Qdrant health check URL (used in diagnostic output). */
+const DEFAULT_QDRANT_URL = 'http://127.0.0.1:6333';
+/** Timeout in milliseconds for service health probes. */
+const PROBE_TIMEOUT_MS = 1500;
 
 /**
  * @module plugin/helpers
  * Shared types and utility functions for the OpenClaw plugin tool registrations.
  */
-const DEFAULT_API_URL = 'http://127.0.0.1:1936';
-/** Extract plugin config from the API object */
+/** Extract plugin config from the API object. */
 function getPluginConfig(api) {
-    return api.config?.plugins?.entries?.['jeeves-watcher-openclaw']?.config;
+    return api.config?.plugins?.entries?.[PLUGIN_ID]?.config;
 }
 /** Resolve the watcher API base URL from plugin config. */
 function getApiUrl(api) {
     const url = getPluginConfig(api)?.apiUrl;
     return typeof url === 'string' ? url : DEFAULT_API_URL;
 }
+/** Resolve the platform config root path from plugin config. */
+function getConfigRoot(api) {
+    const root = getPluginConfig(api)?.configRoot;
+    return typeof root === 'string' ? root : DEFAULT_CONFIG_ROOT;
+}
 /** Format a successful tool result. */
 function ok(data) {
     return {
@@ -79,24 +104,14 @@ async function generateWatcherMenu(apiUrl) {
     const activeRules = [];
     const watchPaths = [];
     const ignoredPaths = [];
+    const scoreThresholds = { strong: 0.75, relevant: 0.5, noise: 0.25 };
     try {
-        const [statusRes, rulesRes, pathsRes, ignoredRes] = (await Promise.all([
+        const [statusRes, rulesRes, pathsRes, thresholdsRes, ignoredRes] = (await Promise.all([
             fetchJson(`${apiUrl}/status`),
-            fetchJson(`${apiUrl}/config/query`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ path: '$.inferenceRules[*]' }),
-            }),
-            fetchJson(`${apiUrl}/config/query`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ path: '$.watch.paths[*]' }),
-            }),
-            fetchJson(`${apiUrl}/config/query`, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ path: '$.watch.ignored[*]' }),
-            }),
+            fetchJson(`${apiUrl}/config?path=${encodeURIComponent('$.inferenceRules[*]')}`),
+            fetchJson(`${apiUrl}/config?path=${encodeURIComponent('$.watch.paths[*]')}`),
+            fetchJson(`${apiUrl}/config?path=${encodeURIComponent('$.search.scoreThresholds')}`),
+            fetchJson(`${apiUrl}/config?path=${encodeURIComponent('$.watch.ignored[*]')}`),
         ]));
         pointCount = statusRes.collection?.pointCount ?? 0;
         if (Array.isArray(rulesRes.result)) {
@@ -119,12 +134,22 @@ async function generateWatcherMenu(apiUrl) {
                     ignoredPaths.push(p);
             }
         }
+        if (Array.isArray(thresholdsRes.result) &&
+            thresholdsRes.result.length > 0) {
+            const t = thresholdsRes.result[0];
+            if (typeof t.strong === 'number')
+                scoreThresholds.strong = t.strong;
+            if (typeof t.relevant === 'number')
+                scoreThresholds.relevant = t.relevant;
+            if (typeof t.noise === 'number')
+                scoreThresholds.noise = t.noise;
+        }
     }
     catch {
         let qdrantStatus = '*Unknown*';
         try {
             // Assuming Qdrant runs locally on the default port
-            const res = await fetch('http://127.0.0.1:6333/healthz', {
+            const res = await fetch(`${DEFAULT_QDRANT_URL}/healthz`, {
                 signal: AbortSignal.timeout(1000),
             });
             qdrantStatus = res.ok ? 'Running' : 'Error';
@@ -136,7 +161,7 @@ async function generateWatcherMenu(apiUrl) {
 > The jeeves-watcher service API at ${apiUrl} is down or not installed.
 > **Diagnostic Info:**
 > - Watcher API (${apiUrl}): Unreachable
-> - Qdrant (http://127.0.0.1:6333): ${qdrantStatus}
+> - Qdrant (${DEFAULT_QDRANT_URL}): ${qdrantStatus}
 >
 > **DO NOT** ignore this. Read the \`jeeves-watcher\` skill's **Bootstrap** section immediately and walk the user through the setup process. Use the diagnostic info above to determine if Qdrant needs installing/starting, or if only the watcher service needs attention.`;
     }
@@ -153,10 +178,10 @@ async function generateWatcherMenu(apiUrl) {
         '**Scan-first rule:** When a task involves structural queries (file enumeration, staleness checks, domain listing, counts), use `watcher_scan` instead of `watcher_search`. Scan does NOT use embeddings and does NOT accept a query string.',
         '**Search-first rule:** When a task involves finding, reading, or modifying files in indexed paths, run `watcher_search` FIRST — even if you already know the file path. Search surfaces related files you may not have considered and catches stale artifacts. Direct filesystem access is for acting on search results, not bypassing them.',
         '',
-        '### Score Interpretation:',
-        '* **Strong:** >= 0.75',
-        '* **Relevant:** >= 0.50',
-        '* **Noise:** < 0.25',
+        '### Score Interpretation (see skill for detail):',
+        `* **Strong:** >= ${String(scoreThresholds.strong)} — High confidence. Use directly.`,
+        `* **Relevant:** >= ${String(scoreThresholds.relevant)} — Likely useful. Verify context before relying on it.`,
+        `* **Noise:** < ${String(scoreThresholds.noise)} — Discard. If all results are noise, broaden your query or try different terms.`,
         '',
         "### What's on the menu:",
     ];
@@ -187,104 +212,79 @@ async function generateWatcherMenu(apiUrl) {
 }
 
 /**
- * @module plugin/toolsWriter
- * Writes the Watcher menu section directly to TOOLS.md on disk.
- * Replaces the agent:bootstrap hook approach which was unreliable due to
- * OpenClaw's clearInternalHooks() wiping plugin-registered hooks on startup.
- */
-const REFRESH_INTERVAL_MS = 60_000;
-let intervalHandle = null;
-let lastWrittenMenu = '';
-/**
- * Resolve the workspace TOOLS.md path.
- * Uses api.resolvePath if available, otherwise falls back to CWD.
- */
-function resolveToolsPath(api) {
-    const resolvePath = api
-        .resolvePath;
-    if (typeof resolvePath === 'function') {
-        return resolvePath('TOOLS.md');
-    }
-    return resolve(process.cwd(), 'TOOLS.md');
-}
-/**
- * Upsert the watcher section in TOOLS.md content.
+ * @module plugin/watcherComponent
+ * Jeeves component integration for the watcher OpenClaw plugin.
  *
- * Strategy:
- * - If a `## Watcher` section already exists, replace it in place.
- * - Otherwise, prepend `# Jeeves Platform Tools\n\n## Watcher\n\n...`
- *   before any existing content.
+ * @remarks
+ * Uses `createAsyncContentCache()` from core to bridge the sync/async gap:
+ * `generateToolsContent()` must be synchronous, but the watcher menu requires
+ * async HTTP calls. The cache triggers a background refresh on each call and
+ * returns the most recent successful result.
  */
-function upsertWatcherContent(existing, watcherMenu) {
-    const section = `## Watcher\n\n${watcherMenu}`;
-    // Replace existing watcher section (match from ## Watcher to next ## or # or EOF)
-    const re = /^## Watcher\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m;
-    if (re.test(existing)) {
-        return existing.replace(re, section);
-    }
-    // No existing section. Prepend under a platform tools H1.
-    const platformH1 = '# Jeeves Platform Tools';
-    if (existing.includes(platformH1)) {
-        // Insert after the H1
-        const idx = existing.indexOf(platformH1) + platformH1.length;
-        return existing.slice(0, idx) + `\n\n${section}\n` + existing.slice(idx);
-    }
-    // Prepend platform header + watcher section before existing content
-    const trimmed = existing.trim();
-    if (trimmed.length === 0) {
-        return `${platformH1}\n\n${section}\n`;
-    }
-    return `${platformH1}\n\n${section}\n\n${trimmed}\n`;
-}
+const execFile = promisify(execFile$1);
 /**
- * Fetch the current watcher menu and write it to TOOLS.md if changed.
- * Returns true if the file was updated.
+ * Probe the watcher HTTP API for service health.
+ *
+ * @param apiUrl - Base URL of the watcher API.
+ * @returns Service status with running flag, optional version and uptime.
  */
-async function refreshToolsMd(api) {
-    const apiUrl = getApiUrl(api);
-    const menu = await generateWatcherMenu(apiUrl);
-    if (menu === lastWrittenMenu) {
-        return false;
-    }
-    const toolsPath = resolveToolsPath(api);
-    let current = '';
+async function getServiceStatus(apiUrl) {
     try {
-        current = await readFile(toolsPath, 'utf8');
+        const res = await fetch(`${apiUrl}/status`, {
+            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return { running: false };
+        const json = (await res.json());
+        return {
+            running: true,
+            version: typeof json.version === 'string' ? json.version : undefined,
+            uptimeSeconds: typeof json.uptime === 'number' ? json.uptime : undefined,
+        };
     }
     catch {
-        // File doesn't exist yet — we'll create it
+        return { running: false };
     }
-    const updated = upsertWatcherContent(current, menu);
-    if (updated !== current) {
-        await writeFile(toolsPath, updated, 'utf8');
-        lastWrittenMenu = menu;
-        return true;
-    }
-    lastWrittenMenu = menu;
-    return false;
 }
 /**
- * Start the periodic TOOLS.md writer.
- * Writes immediately on startup, then refreshes every REFRESH_INTERVAL_MS.
+ * Create the watcher `JeevesComponent` descriptor.
+ *
+ * @param options - API URL and plugin version.
+ * @returns A fully configured component descriptor ready for `createComponentWriter()`.
  */
-function startToolsWriter(api) {
-    // Initial write (fire and forget — errors logged but not thrown)
-    refreshToolsMd(api).catch((err) => {
-        console.error('[jeeves-watcher] Failed to write TOOLS.md:', err);
+function createWatcherComponent(options) {
+    const { apiUrl, pluginVersion } = options;
+    const getContent = createAsyncContentCache({
+        fetch: async () => generateWatcherMenu(apiUrl),
+        placeholder: '> Initializing watcher menu...',
     });
-    // Periodic refresh
-    if (intervalHandle) {
-        clearInterval(intervalHandle);
-    }
-    intervalHandle = setInterval(() => {
-        refreshToolsMd(api).catch((err) => {
-            console.error('[jeeves-watcher] Failed to refresh TOOLS.md:', err);
-        });
-    }, REFRESH_INTERVAL_MS);
-    // Don't keep the process alive just for this interval
-    if (typeof intervalHandle === 'object' && 'unref' in intervalHandle) {
-        intervalHandle.unref();
-    }
+    return {
+        name: 'watcher',
+        version: pluginVersion,
+        sectionId: 'Watcher',
+        refreshIntervalSeconds: 71,
+        generateToolsContent: getContent,
+        serviceCommands: {
+            async stop() {
+                await execFile('jeeves-watcher', ['service', 'stop']);
+            },
+            async uninstall() {
+                await execFile('jeeves-watcher', ['service', 'uninstall']);
+            },
+            async status() {
+                return getServiceStatus(apiUrl);
+            },
+        },
+        pluginCommands: {
+            async uninstall() {
+                await execFile('npx', [
+                    '-y',
+                    `@karmaniverous/${PLUGIN_ID}`,
+                    'uninstall',
+                ]);
+            },
+        },
+    };
 }
 
 /**
@@ -379,23 +379,23 @@ function registerWatcherTools(api, baseUrl) {
             ],
         },
         {
-            name: 'watcher_query',
-            description: 'Query the merged virtual document via JSONPath.',
+            name: 'watcher_config',
+            description: 'Query the effective runtime config via JSONPath. Returns the full resolved merged document when no path is provided.',
             parameters: {
                 type: 'object',
-                required: ['path'],
                 properties: {
-                    path: { type: 'string', description: 'JSONPath expression.' },
-                    resolve: {
-                        type: 'array',
-                        items: { type: 'string', enum: ['files', 'globals'] },
-                        description: 'Resolution scopes to include (e.g., ["files"], ["globals"], or both).',
+                    path: {
+                        type: 'string',
+                        description: 'JSONPath expression (optional).',
                     },
                 },
             },
             buildRequest: (params) => {
-                const body = pickDefined(params, ['path', 'resolve']);
-                return ['/config/query', body];
+                const path = params.path;
+                if (path) {
+                    return [`/config?path=${encodeURIComponent(path)}`];
+                }
+                return ['/config'];
             },
         },
         {
@@ -443,14 +443,29 @@ function registerWatcherTools(api, baseUrl) {
                 properties: {
                     scope: {
                         type: 'string',
-                        enum: ['rules', 'full'],
-                        description: 'Reindex scope: "rules" (default) re-applies inference rules; "full" re-embeds everything.',
+                        enum: ['rules', 'full', 'issues', 'path', 'prune'],
+                        description: 'Reindex scope: "rules" (default) re-applies inference rules; "full" re-embeds everything; "issues" re-processes files with errors; "path" reindexes a specific file or directory (requires path parameter); "prune" deletes points for files no longer in watch scope.',
+                    },
+                    path: {
+                        oneOf: [
+                            { type: 'string' },
+                            { type: 'array', items: { type: 'string' } },
+                        ],
+                        description: 'Target file or directory path (required when scope is "path"). Accepts a single path or array of paths.',
+                    },
+                    dryRun: {
+                        type: 'boolean',
+                        description: 'When true, compute and return the blast area plan without executing. Returns counts by root showing impact.',
                     },
                 },
             },
             buildRequest: (params) => [
-                '/config-reindex',
-                { scope: params.scope ?? 'rules' },
+                '/reindex',
+                {
+                    scope: params.scope ?? 'rules',
+                    ...(params.path ? { path: params.path } : {}),
+                    ...(params.dryRun ? { dryRun: true } : {}),
+                },
             ],
         },
         {
@@ -500,6 +515,22 @@ function registerWatcherTools(api, baseUrl) {
             parameters: { type: 'object', properties: {} },
             buildRequest: () => ['/issues'],
         },
+        {
+            name: 'watcher_walk',
+            description: 'Walk watched filesystem paths with glob intersection. Returns matching file paths from all configured watch roots, applying watch.ignored and gitignore filtering.',
+            parameters: {
+                type: 'object',
+                required: ['globs'],
+                properties: {
+                    globs: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Glob patterns to intersect with watch paths (e.g., ["**/.meta/meta.json"]).',
+                    },
+                },
+            },
+            buildRequest: (params) => ['/walk', { globs: params.globs }],
+        },
     ];
     for (const tool of tools) {
         registerApiTool(api, baseUrl, tool);
@@ -508,17 +539,52 @@ function registerWatcherTools(api, baseUrl) {
 
 /**
  * @module plugin
- * OpenClaw plugin entry point. Registers all jeeves-watcher tools.
+ * OpenClaw plugin entry point. Registers all jeeves-watcher tools and starts
+ * the managed content writer via `@karmaniverous/jeeves` core.
  */
+/**
+ * Read the plugin version from the nearest package.json.
+ *
+ * @remarks
+ * Uses `createRequire(import.meta.url)` — the same pattern as
+ * `@karmaniverous/jeeves` core. Works whether executed from
+ * `src/index.ts` (dev/test) or `dist/index.js` (built), since
+ * both are exactly one directory level below `package.json`.
+ */
+const require$1 = createRequire(import.meta.url);
+const pkg = require$1('../package.json');
+const PLUGIN_VERSION = pkg.version;
+/** Resolve the workspace root from the OpenClaw plugin API. */
+function resolveWorkspacePath(api) {
+    if (typeof api.resolvePath === 'function') {
+        return api.resolvePath('.');
+    }
+    return process.cwd();
+}
+/** Detect test environments to avoid timers and filesystem writes. */
+function isTestEnv() {
+    return process.env.NODE_ENV === 'test' || process.env.VITEST !== undefined;
+}
 /** Register all jeeves-watcher tools with the OpenClaw plugin API. */
 function register(api) {
-    const baseUrl = getApiUrl(api);
-    registerWatcherTools(api, baseUrl);
-    // Write the watcher menu to TOOLS.md on disk, refreshing periodically.
-    // This replaces the agent:bootstrap hook approach which was unreliable
-    // because OpenClaw's clearInternalHooks() wipes plugin-registered hooks
-    // during the async startup sequence.
-    startToolsWriter(api);
+    const apiUrl = getApiUrl(api);
+    registerWatcherTools(api, apiUrl);
+    // Avoid timers + filesystem writes in unit tests.
+    if (isTestEnv())
+        return;
+    // Initialize jeeves-core for managed content writing.
+    init({
+        workspacePath: resolveWorkspacePath(api),
+        configRoot: getConfigRoot(api),
+    });
+    const component = createWatcherComponent({
+        apiUrl,
+        pluginVersion: PLUGIN_VERSION,
+    });
+    const writer = createComponentWriter(component, {
+        probeTimeoutMs: PROBE_TIMEOUT_MS,
+    });
+    writer.start();
 }
 
 export { register as default };

package/dist/skills/jeeves-watcher/SKILL.md

@@ -30,9 +30,7 @@ curl -X POST http://127.0.0.1:<PORT>/search \
   -d '{"query": "search text", "limit": 5}'
 
 # Query config
-curl -X POST http://127.0.0.1:<PORT>/config/query \
-  -H "Content-Type: application/json" \
-  -d '{"path": "$.inferenceRules[*].name"}'
+curl http://127.0.0.1:<PORT>/config
 ```
 
 **Key endpoints:**
@@ -40,14 +38,15 @@ curl -X POST http://127.0.0.1:<PORT>/config/query \
 |----------|--------|---------|
 | `/status` | GET | Health check, uptime, collection stats |
 | `/search` | POST | Semantic search (main query interface) |
-| `/config/query` | POST | JSONPath query over merged virtual document |
+| `/config` | GET | Full resolved config; optional `?path=<jsonpath>` filter |
 | `/config/validate` | POST | Validate candidate config |
 | `/config/apply` | POST | Apply config changes |
-| `/config-reindex` | POST | Trigger reindex |
+| `/reindex` | POST | Trigger reindex |
 | `/metadata` | POST | Enrich document metadata |
 | `/scan` | POST | Filter-only point query (no embeddings) |
+| `/walk` | POST | Filesystem walk with glob intersection |
 | `/issues` | GET | Runtime embedding failures |
-| `/rules/register` | POST | Register virtual inference rules |
+| `/rules/register` | POST | Register virtual inference rules (auto-triggers rules reindex) |
 | `/rules/unregister` | DELETE | Remove virtual rules by source |
 | `/points/delete` | POST | Delete points matching a Qdrant filter |
 
@@ -73,6 +72,21 @@ You have access to a **semantic archive** of your human's working world. Documen
 
 **The principle:** Memory-core is your curated highlights. The watcher archive is your perfect recall. Use memory first for speed and signal, but never let its narrow scope be the ceiling of what you can remember.
 
+## ⚠️ Embedding Cost — Hard Behavioral Gate
+
+**The watcher embeds every file it sees.** Embedding is the most expensive operation in the pipeline — each file triggers a Gemini API call. The index may contain hundreds of thousands of points. Any action that causes the watcher to process a large number of files has real, potentially significant cost.
+
+**STOP and ask for a human decision before:**
+
+- **Renaming, moving, or reorganizing watched directories.** A directory rename at the filesystem level is cheap — chokidar sees unlink + add events, but the content hasn't changed. However, if a rename is blocked (e.g., by a file lock from the watcher or another service), **do NOT work around it by creating new directories and copying/moving files**. That creates duplicate embeddings at the new paths while the old paths still exist. Instead: stop the blocking service, perform the rename, restart. This is a 30-second operation. The workaround can cost thousands of API calls.
+- **Changing `watch.paths` to add large directory trees.** Adding a new watch root triggers initial indexing of every matching file under it.
+- **Running `scope: "full"` reindex.** This re-embeds the entire index. Use `scope: "rules"` for inference rule changes (zero embedding cost — only metadata reapplication).
+- **Any bulk file operation** (mass copy, mass move, template-based file generation) under watched paths.
+
+**The right instinct when blocked:** If a filesystem operation fails because a service has a lock, the correct response is to stop the service, do the operation, and restart — NOT to find a creative workaround. Creative workarounds in the presence of a live watcher are how you accidentally trigger re-embedding of tens of thousands of files.
+
+**Cost context:** A single file embedding costs a Gemini API call. 1,000 unnecessary embeddings is a noticeable cost. 100,000 unnecessary embeddings (e.g., copying an entire domain directory to a new path) is a billing event worth flagging.
+
 ## Plugin Installation
 
 ```
@@ -350,12 +364,17 @@ Set or update metadata on a document.
 - `metadata` (object, required) — key-value metadata to merge
 
 ### `watcher_status`
-Service health check. Returns uptime, collection stats, reindex status.
+Service health check. Returns uptime, version, collection stats, reindex status, and initial scan progress.
 
-### `watcher_query`
-Query the merged virtual document via JSONPath.
-- `path` (string, required) — JSONPath expression
-- `resolve` (string[], optional) — `["files"]`, `["globals"]`, or `["files","globals"]`
+After a service restart, the `initialScan` field shows scan progress:
+- `active: true` — filesystem walk in progress; `filesMatched` and `filesEnqueued` grow until chokidar completes
+- `active: false` with `completedAt`/`durationMs` — scan finished
+
+Use this to determine if the service is still initializing after a restart.
+
+### `watcher_config`
+Query the effective runtime config via JSONPath. Returns the full resolved merged document when no path is provided.
+- `path` (string, optional) — JSONPath expression
 
 ### `watcher_validate`
 Validate config and optionally test file paths.
@@ -371,10 +390,38 @@ Apply config changes atomically.
 Validates, writes to disk, and triggers configured reindex behavior. Returns validation errors if invalid.
 
 ### `watcher_reindex`
-Trigger a reindex.
-- `scope` (string, optional) — `"rules"` (default) or `"full"`
+Trigger a reindex operation. All scopes return a `plan` object showing blast area before execution begins.
+
+**Parameters:**
+- `scope` (string, optional) — Reindex scope. Default: `"rules"`. One of:
+  - `"rules"` — Re-apply inference rules to all watched files. No re-embedding. Lightweight.
+  - `"full"` — Re-extract text, re-embed, and re-apply rules for all watched files. Expensive.
+  - `"issues"` — Re-process only files that previously failed embedding (from `watcher_issues`).
+  - `"path"` — Re-embed a specific file or all files under a directory. Requires `path` parameter.
+  - `"prune"` — Delete Qdrant points for files no longer in watch scope (removed paths, gitignored files, stale data). No re-embedding. Pure cleanup.
+- `path` (string, required when scope is `"path"`) — Target file or directory path.
+- `dryRun` (boolean, optional) — When `true`, compute and return the blast area plan without executing. Returns synchronously.
 
-Rules scope re-applies inference rules without re-embedding (lightweight). Full scope re-processes all files.
+**Response (normal):**
+```json
+{ "status": "started", "scope": "rules", "plan": { "total": 148000, "toProcess": 148000, "toDelete": 0, "byRoot": { "j:/domains": 95000, "j:/config": 3000 } } }
+```
+
+**Response (dryRun):**
+```json
+{ "status": "dry_run", "scope": "prune", "plan": { "total": 562000, "toProcess": 0, "toDelete": 2300, "byRoot": { "j:/jeeves/node_modules": 1800, "j:/jeeves/.bridge": 500 } } }
+```
+
+**Plan fields:**
+- `total` — Total points (prune) or files (other scopes) examined.
+- `toProcess` — Items to embed/re-apply rules (0 for prune).
+- `toDelete` — Points to delete (prune only, 0 for others).
+- `byRoot` — Counts grouped by watch root prefix. Shows where the impact concentrates.
+
+**Guidance:**
+- Use `dryRun: true` before any large-blast operation to preview impact.
+- `prune` is safe — it only deletes orphaned points, never re-embeds. Use after changing watch paths, fixing gitignore, or cleaning up stale data.
+- `prune` is NOT triggered by config-watch auto-reindex (too dangerous for auto-trigger).
 
 
 ### `watcher_scan`
@@ -417,6 +464,30 @@ do {
 ### `watcher_issues`
 Get runtime embedding failures. Returns `{ filePath: IssueRecord }` showing files that failed and why.
 
+### `watcher_walk`
+Walk watched filesystem paths with glob intersection. Returns matching file paths from all configured watch roots.
+- `globs` (string[], required) — glob patterns to intersect with watch paths
+
+**Response:**
+```json
+{
+  "paths": ["j:/domains/foo/.meta/meta.json", "j:/domains/bar/.meta/meta.json"],
+  "matchedCount": 2,
+  "scannedRoots": ["j:/domains", "j:/config"]
+}
+```
+
+**Use cases:**
+- Discover files matching a pattern across all watched directories (e.g., `["**/.meta/meta.json"]`)
+- Enumerate files before rule registration to understand scope
+- Find files that aren't yet indexed (no Qdrant dependency — works even before first embedding)
+
+**Key differences from `watcher_scan`:**
+- Walks the actual filesystem, not the Qdrant index
+- No embedding or indexing required — works immediately after service start
+- Returns file paths only (no metadata, no vectors)
+- Applies `watch.ignored` and gitignore filtering automatically
+
 ## Query Planning: Scan vs Search
 
 **Decision rule:** If the query has no semantic/natural-language dimension, use `watcher_scan`. If you need meaning-based similarity, use `watcher_search`.
@@ -523,7 +594,7 @@ Each result from `watcher_search` contains:
 | `payload.content_hash` | string | Hash of the full document content |
 | `payload.matched_rules` | string[] | Names of inference rules that matched |
 
-Additional metadata fields depend on the deployment's inference rules (e.g., `domain`, `status`, `author`). Use `watcher_query` to discover available fields.
+Additional metadata fields depend on the deployment's inference rules (e.g., `domain`, `status`, `author`). Use `watcher_config` to discover available fields.
 
 ## Query Planning (Per Search Task)
 
@@ -531,7 +602,7 @@ Identify relevant rule(s) from the orientation model, then retrieve their schema
 
 **Retrieve complete schema for a rule:**
 ```
-watcher_query: path="$.inferenceRules[?(@.name=='jira-issue')].schema"
+watcher_config: path="$.inferenceRules[?(@.name=='jira-issue')].schema"
               resolve=["files","globals"]
 ```
 
@@ -539,7 +610,7 @@ Returns the fully merged schema with properties, types, `set` provenance, `uiHin
 
 **For select/multiselect fields without `enum` in schema:**
 ```
-watcher_query: path="$.inferenceRules[?(@.name=='jira-issue')].values.status"
+watcher_config: path="$.inferenceRules[?(@.name=='jira-issue')].values.status"
 ```
 
 Retrieves valid filter values from the runtime values index (distinct values accumulated during embedding).
@@ -613,9 +684,9 @@ A consuming UI will necessarily compose simple single-field filters. The assista
 
 ### Score Interpretation
 Use `scoreThresholds` from config (queried during orientation). Values are deployment-specific, constrained to [-1, 1]:
-- `strong` — minimum score for a strong match
-- `relevant` — minimum score for relevance
-- `noise` — maximum score below which results are noise
+- `strong` — minimum score for a strong match. **Action:** High confidence. Use these results directly.
+- `relevant` — minimum score for relevance. **Action:** Likely useful but verify context before relying on them.
+- `noise` — maximum score below which results are noise. **Action:** Discard. If all results fall below this threshold, broaden your query or try different terms.
 
 ### Chunk Grouping
 Multiple results with the same `file_path` are chunks of one document. Read the full file for complete context.
@@ -623,7 +694,7 @@ Multiple results with the same `file_path` are chunks of one document. Read the
 ### Schema Lookup
 Use `matched_rules` on results to look up applicable schemas for metadata interpretation:
 ```
-watcher_query: path="$.inferenceRules[?(@.name=='jira-issue')].schema"
+watcher_config: path="$.inferenceRules[?(@.name=='jira-issue')].schema"
               resolve=["files","globals"]
 ```
 
@@ -636,7 +707,7 @@ Search gives you chunks; use `read` with `file_path` for the complete document.
 
 When uncertain whether a file is indexed, use the path test endpoint:
 ```
-watcher_query: path="$.inferenceRules[?(@.name=='<rule>')].match"
+watcher_config: path="$.inferenceRules[?(@.name=='<rule>')].match"
 ```
 
 Or check if a specific path would match:
@@ -672,15 +743,18 @@ Progress is reported via `watcher_status` (`reindex.filesProcessed` / `reindex.t
 ### When to Reindex
 - **Rules scope** (`"rules"`): Changed rule matching patterns, set expressions, schema mappings. No re-embedding needed.
 - **Full scope** (`"full"`): Changed embedding config, added watch paths, broad schema restructuring. Re-embeds everything.
+- **Issues scope** (`"issues"`): After fixing the root cause of embedding failures (permissions, encoding, file format). Re-processes only failed files.
+- **Path scope** (`"path"`): Edited files in a specific directory and want to force re-embedding without a full reindex. Or a single file's embedding looks wrong.
+- **Prune scope** (`"prune"`): After changing `watch.paths`, adding gitignore rules, or discovering stale/orphaned points (e.g., indexed `node_modules`). Deletes points for out-of-scope files. Always `dryRun: true` first to preview.
 
 ---
 
 ## Diagnostics
 
 ### Escalation Path
-1. `watcher_status` — is the service healthy? Is a reindex running?
+1. `watcher_status` — is the service healthy? Is a reindex running? Is the initial scan still active?
 2. `watcher_issues` — what files are failing and why?
-3. `watcher_query` with `$.issues` — same data via JSONPath
+3. `watcher_config` with `$.issues` — same data via JSONPath
 4. Check logs at the configured log path
 
 ### Error Categories

package/dist/src/constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @module plugin/constants
+ * Shared constants for the OpenClaw plugin package.
+ *
+ * @remarks
+ * Imported by both the plugin bundle (`index.ts`) and the CLI bundle
+ * (`cli.ts`). Rollup inlines these into each output independently.
+ */
+/** Plugin identifier used in OpenClaw config and extensions directory. */
+export declare const PLUGIN_ID = "jeeves-watcher-openclaw";
+/** Default watcher API base URL. */
+export declare const DEFAULT_API_URL = "http://127.0.0.1:1936";
+/** Default platform config root path. */
+export declare const DEFAULT_CONFIG_ROOT = "j:/config";
+/** Default Qdrant health check URL (used in diagnostic output). */
+export declare const DEFAULT_QDRANT_URL = "http://127.0.0.1:6333";
+/** Timeout in milliseconds for service health probes. */
+export declare const PROBE_TIMEOUT_MS = 1500;

package/dist/src/helpers.d.ts

@@ -11,6 +11,13 @@ export interface PluginApi {
             }>;
         };
     };
+    /**
+     * Resolve a path relative to the OpenClaw workspace.
+     *
+     * @remarks
+     * Present on newer OpenClaw builds; optional for backwards compatibility.
+     */
+    resolvePath?: (input: string) => string;
     registerTool(tool: {
         name: string;
         description: string;
@@ -19,15 +26,6 @@ export interface PluginApi {
     }, options?: {
         optional?: boolean;
     }): void;
-    /**
-     * Optional internal hook registration (available on newer OpenClaw builds).
-     * We keep this optional to preserve compatibility.
-     */
-    registerHook?: (event: string | string[], handler: (event: unknown) => Promise<void> | void, opts?: {
-        name?: string;
-        description?: string;
-        register?: boolean;
-    }) => void;
 }
 /** Result shape returned by each tool execution. */
 export interface ToolResult {
@@ -39,12 +37,10 @@ export interface ToolResult {
 }
 /** Resolve the watcher API base URL from plugin config. */
 export declare function getApiUrl(api: PluginApi): string;
-/** Resolve the cache TTL for plugin hooks from config. */
-export declare function getCacheTtlMs(api: PluginApi): number;
+/** Resolve the platform config root path from plugin config. */
+export declare function getConfigRoot(api: PluginApi): string;
 /** Format a successful tool result. */
 export declare function ok(data: unknown): ToolResult;
-/** Format an error tool result. */
-export declare function fail(error: unknown): ToolResult;
 /** Format a connection error with actionable guidance. */
 export declare function connectionFail(error: unknown, baseUrl: string): ToolResult;
 /** Fetch JSON from a URL, throwing on non-OK responses. */

package/dist/src/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * @module plugin
- * OpenClaw plugin entry point. Registers all jeeves-watcher tools.
+ * OpenClaw plugin entry point. Registers all jeeves-watcher tools and starts
+ * the managed content writer via `@karmaniverous/jeeves` core.
  */
 import type { PluginApi } from './helpers.js';
 /** Register all jeeves-watcher tools with the OpenClaw plugin API. */

package/dist/src/promptInjection.d.ts

@@ -1,11 +1,5 @@
-import { type PluginApi } from './helpers.js';
 /**
  * Fetches data from the watcher API and generates a Markdown menu string.
  * The string is platform-agnostic and safe to inject into TOOLS.md.
  */
 export declare function generateWatcherMenu(apiUrl: string): Promise<string>;
-/**
- * Hook handler for agent:bootstrap.
- * Injects/updates the Watcher Menu into the TOOLS.md payload.
- */
-export declare function handleAgentBootstrap(event: unknown, api: PluginApi): Promise<void>;

package/dist/src/watcherComponent.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @module plugin/watcherComponent
+ * Jeeves component integration for the watcher OpenClaw plugin.
+ *
+ * @remarks
+ * Uses `createAsyncContentCache()` from core to bridge the sync/async gap:
+ * `generateToolsContent()` must be synchronous, but the watcher menu requires
+ * async HTTP calls. The cache triggers a background refresh on each call and
+ * returns the most recent successful result.
+ */
+import { type JeevesComponent } from '@karmaniverous/jeeves';
+/** Options for creating the watcher component descriptor. */
+interface CreateWatcherComponentOptions {
+    /** Base URL of the jeeves-watcher HTTP API. */
+    apiUrl: string;
+    /** Plugin package version. */
+    pluginVersion: string;
+}
+/**
+ * Create the watcher `JeevesComponent` descriptor.
+ *
+ * @param options - API URL and plugin version.
+ * @returns A fully configured component descriptor ready for `createComponentWriter()`.
+ */
+export declare function createWatcherComponent(options: CreateWatcherComponentOptions): JeevesComponent;
+export {};

package/dist/src/watcherComponent.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @module plugin/watcherComponent.test
+ * Unit tests for the watcher JeevesComponent implementation.
+ */
+export {};

package/dist/src/writerIntegration.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @module plugin/writerIntegration.test
+ * Integration tests for the ComponentWriter lifecycle via jeeves-core.
+ */
+export {};

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "jeeves-watcher-openclaw",
   "name": "Jeeves Watcher",
   "description": "Semantic search, metadata enrichment, and instance administration for a jeeves-watcher deployment.",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "skills": [
     "dist/skills/jeeves-watcher"
   ],
@@ -14,6 +14,11 @@
         "type": "string",
         "description": "jeeves-watcher API base URL",
         "default": "http://127.0.0.1:1936"
+      },
+      "configRoot": {
+        "type": "string",
+        "description": "Platform config root path (e.g., j:/config)",
+        "default": "j:/config"
       }
     }
   },
@@ -21,6 +26,10 @@
     "apiUrl": {
       "label": "Watcher API URL",
       "placeholder": "http://127.0.0.1:1936"
+    },
+    "configRoot": {
+      "label": "Config root",
+      "placeholder": "j:/config"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-watcher-openclaw",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "author": "Jason Williscroft",
   "description": "OpenClaw plugin for jeeves-watcher — semantic search and metadata enrichment tools",
   "license": "BSD-3-Clause",
@@ -50,20 +50,24 @@
   },
   "auto-changelog": {
     "output": "CHANGELOG.md",
+    "tagPrefix": "openclaw/",
     "unreleased": true,
     "commitLimit": false,
     "hideCredit": true
   },
+  "dependencies": {
+    "@karmaniverous/jeeves": "^0.1.1"
+  },
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.54.1",
+    "@dotenvx/dotenvx": "^1.55.1",
     "@rollup/plugin-typescript": "^12.3.0",
     "auto-changelog": "^2.5.0",
     "cross-env": "^10.1.0",
-    "knip": "^5.85.0",
+    "knip": "^5.87.0",
     "release-it": "^19.2.4",
     "rollup": "^4.59.0",
     "tslib": "^2.8.1",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   },
   "scripts": {
     "build:plugin": "rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",

package/dist/src/toolsWriter.d.ts

@@ -1,20 +0,0 @@
-/**
- * @module plugin/toolsWriter
- * Writes the Watcher menu section directly to TOOLS.md on disk.
- * Replaces the agent:bootstrap hook approach which was unreliable due to
- * OpenClaw's clearInternalHooks() wiping plugin-registered hooks on startup.
- */
-import { type PluginApi } from './helpers.js';
-/**
- * Start the periodic TOOLS.md writer.
- * Writes immediately on startup, then refreshes every REFRESH_INTERVAL_MS.
- */
-export declare function startToolsWriter(api: PluginApi): void;
-/**
- * Force an immediate refresh (e.g., after watcher_config_apply).
- */
-export declare function forceRefreshToolsMd(api: PluginApi): Promise<void>;
-/**
- * Stop the periodic writer (for cleanup).
- */
-export declare function stopToolsWriter(): void;