@karmaniverous/jeeves-meta-openclaw 0.2.0 → 0.4.0

package/README.md

@@ -1,15 +1,19 @@
 # @karmaniverous/jeeves-meta-openclaw
 
-OpenClaw plugin for [jeeves-meta](../service/). A thin HTTP client that registers interactive tools and maintains dynamic TOOLS.md content.
+OpenClaw plugin for [jeeves-meta](../service/). A thin HTTP client that registers interactive tools and uses [`@karmaniverous/jeeves`](https://github.com/karmaniverous/jeeves) core for managed TOOLS.md content writing and platform maintenance.
 
 ## Features
 
 - **Four interactive tools** — `meta_list`, `meta_detail`, `meta_trigger`, `meta_preview`
-- **MetaServiceClient** — HTTP client delegating all operations to the running service
-- **TOOLS.md injection** — periodic refresh of entity stats and tool listing in the agent's system prompt
+- **MetaServiceClient** — typed HTTP client delegating all operations to the running service
+- **TOOLS.md injection** — periodic refresh of entity stats via `ComponentWriter` from `@karmaniverous/jeeves` (73-second prime interval)
 - **Dependency health** — shows warnings when watcher/gateway are degraded
 - **Consumer skill** — `SKILL.md` for agent integration
 
+## Plugin Lifecycle
+
+![Plugin Lifecycle](diagrams/assets/plugin-lifecycle.png)
+
 ## Install
 
 ```bash
@@ -24,10 +28,12 @@ npx @karmaniverous/jeeves-meta-openclaw install
 
 ## Configuration
 
-The plugin resolves the service URL in order:
-1. Plugin config `serviceUrl` in `openclaw.json`
-2. `JEEVES_META_URL` environment variable
-3. Default: `http://127.0.0.1:1938`
+The plugin resolves settings via a three-step fallback chain: plugin config → environment variable → default.
+
+| Setting | Plugin Config Key | Env Var | Default |
+|---------|-------------------|---------|---------|
+| Service URL | `serviceUrl` | `JEEVES_META_URL` | `http://127.0.0.1:1938` |
+| Config Root | `configRoot` | `JEEVES_CONFIG_ROOT` | `j:/config` |
 
 ```json
 {
@@ -36,7 +42,8 @@ The plugin resolves the service URL in order:
       "jeeves-meta-openclaw": {
         "enabled": true,
         "config": {
-          "serviceUrl": "http://127.0.0.1:1938"
+          "serviceUrl": "http://127.0.0.1:1938",
+          "configRoot": "j:/config"
         }
       }
     }
@@ -44,6 +51,8 @@ The plugin resolves the service URL in order:
 }
 ```
 
+The `configRoot` setting tells `@karmaniverous/jeeves` core where to find the platform config directory. Core derives `{configRoot}/jeeves-meta/` for component-specific configuration.
+
 ## Documentation
 
 - **[Plugin Setup](guides/plugin-setup.md)** — installation, config, lifecycle
@@ -54,4 +63,3 @@ The plugin resolves the service URL in order:
 ## License
 
 BSD-3-Clause
-

package/dist/cli.js

@@ -21,6 +21,7 @@ import { fileURLToPath } from 'node:url';
  *
  * @module cli
  */
+// Duplicated from helpers.ts — separate rollup bundle cannot share imports.
 const PLUGIN_ID = 'jeeves-meta-openclaw';
 /** Resolve the OpenClaw home directory. */
 function resolveOpenClawHome() {

package/dist/index.js

@@ -1,33 +1,44 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { init, createAsyncContentCache, createComponentWriter } from '@karmaniverous/jeeves';
 
 /**
  * Shared types and utilities for the OpenClaw plugin.
  *
  * @module helpers
  */
-const PLUGIN_NAME = 'jeeves-meta-openclaw';
-const DEFAULT_SERVICE_URL = 'http://127.0.0.1:1938';
-/** Get plugin config. */
+/** Plugin identifier. */
+const PLUGIN_ID = 'jeeves-meta-openclaw';
+/** Get plugin config object from the OpenClaw API. */
 function getPluginConfig(api) {
-    return api.config?.plugins?.entries?.[PLUGIN_NAME]?.config;
+    return api.config?.plugins?.entries?.[PLUGIN_ID]?.config;
 }
 /**
- * Resolve the service URL.
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → default value.
  *
- * Resolution order:
- * 1. Plugin config `serviceUrl` setting
- * 2. `JEEVES_META_URL` environment variable
- * 3. Default: http://127.0.0.1:1938
+ * @param api - Plugin API.
+ * @param configKey - Key in the plugin config object.
+ * @param envVar - Environment variable name.
+ * @param fallback - Default value if neither source provides one.
  */
-function getServiceUrl(api) {
-    const fromPlugin = getPluginConfig(api)?.serviceUrl;
+function resolvePluginSetting(api, configKey, envVar, fallback) {
+    const fromPlugin = getPluginConfig(api)?.[configKey];
     if (typeof fromPlugin === 'string')
         return fromPlugin;
-    const fromEnv = process.env['JEEVES_META_URL'];
+    const fromEnv = process.env[envVar];
     if (fromEnv)
         return fromEnv;
-    return DEFAULT_SERVICE_URL;
+    return fallback;
+}
+/** Resolve the meta service URL. */
+function getServiceUrl(api) {
+    return resolvePluginSetting(api, 'serviceUrl', 'JEEVES_META_URL', 'http://127.0.0.1:1938');
+}
+/** Resolve the platform config root. */
+function getConfigRoot(api) {
+    return resolvePluginSetting(api, 'configRoot', 'JEEVES_CONFIG_ROOT', 'j:/config');
 }
 /** Format a successful tool result. */
 function ok(data) {
@@ -44,10 +55,166 @@ function fail(error) {
     };
 }
 
+/**
+ * Tool name/description pairs — single source of truth for tool registration
+ * and placeholder content.
+ *
+ * @module toolMeta
+ */
+/** Ordered list of meta_* tools. */
+const META_TOOLS = [
+    {
+        name: 'meta_list',
+        description: 'List metas with summary stats and per-meta projection. Replaces meta_status + meta_entities.',
+    },
+    {
+        name: 'meta_detail',
+        description: 'Full detail for a single meta, with optional archive history.',
+    },
+    {
+        name: 'meta_trigger',
+        description: 'Manually trigger synthesis for a specific meta or the next-stalest candidate. Runs the full 3-step cycle (architect, builder, critic).',
+    },
+    {
+        name: 'meta_preview',
+        description: 'Dry-run: show what inputs would be gathered for the next synthesis cycle without running LLM.',
+    },
+];
+/**
+ * Render the tools table for TOOLS.md injection.
+ *
+ * Produces a Markdown table with short descriptions suitable for
+ * both the placeholder and the live menu.
+ */
+function renderToolsTable() {
+    const shortDesc = {
+        meta_list: 'List metas with summary stats and per-meta projection',
+        meta_detail: 'Full detail for a single meta with optional archive history',
+        meta_trigger: 'Manually trigger synthesis for a specific meta or next-stalest',
+        meta_preview: 'Dry-run: show what inputs would be gathered without running LLM',
+    };
+    const rows = META_TOOLS.map((t) => `| \`${t.name}\` | ${shortDesc[t.name] ?? t.description} |`);
+    return [
+        '### Tools',
+        '| Tool | Description |',
+        '|------|-------------|',
+        ...rows,
+        '',
+        'Read the `jeeves-meta` skill for usage guidance, configuration, and troubleshooting.',
+    ].join('\n');
+}
+
+/**
+ * Generate the Meta menu content for TOOLS.md injection.
+ *
+ * Queries the jeeves-meta service for entity stats and produces
+ * a Markdown section suitable for agent system prompt injection.
+ *
+ * @module promptInjection
+ */
+/**
+ * Generate the Meta menu Markdown for TOOLS.md.
+ *
+ * @param client - MetaServiceClient instance.
+ * @returns Markdown string for the Meta section.
+ */
+async function generateMetaMenu(client) {
+    let status;
+    let metas;
+    try {
+        status = await client.status();
+        metas = await client.listMetas();
+    }
+    catch {
+        return [
+            '> **ACTION REQUIRED: jeeves-meta service is unreachable.**',
+            '> The service API is down or not configured.',
+            '>',
+            '> **Troubleshooting:**',
+            '> - Verify the service is installed: `npm list -g @karmaniverous/jeeves-meta`',
+            '> - Check if running: `curl http://localhost:1938/status`',
+            '> - Verify `serviceUrl` in plugin config if using a non-default port',
+            '>',
+            "> **Read the `jeeves-meta` skill's Bootstrapping section** for full setup guidance.",
+        ].join('\n');
+    }
+    if (metas.summary.total === 0) {
+        return [
+            '> **ACTION REQUIRED: No synthesis entities found.**',
+            '> The service is running but no `.meta/` directories were discovered.',
+            '>',
+            "> **Read the `jeeves-meta` skill's Bootstrapping section** for guidance",
+            '> on creating `.meta/` directories.',
+        ].join('\n');
+    }
+    const { summary } = metas;
+    const formatAge = (seconds) => {
+        if (!isFinite(seconds))
+            return 'never synthesized';
+        if (seconds < 3600)
+            return Math.round(seconds / 60).toString() + 'm';
+        if (seconds < 86400)
+            return Math.round(seconds / 3600).toString() + 'h';
+        return Math.round(seconds / 86400).toString() + 'd';
+    };
+    // Find stalest age
+    let stalestAge = 0;
+    for (const item of metas.metas) {
+        const s = item.stalenessSeconds !== null ? item.stalenessSeconds : Infinity;
+        if (s > stalestAge)
+            stalestAge = s;
+    }
+    const stalestDisplay = summary.stalestPath
+        ? summary.stalestPath + ' (' + formatAge(stalestAge) + ')'
+        : 'n/a';
+    const lastSynthDisplay = summary.lastSynthesizedAt
+        ? (summary.lastSynthesizedPath ?? '') +
+            ' (' +
+            summary.lastSynthesizedAt +
+            ')'
+        : 'n/a';
+    // Service status + dependency health
+    const depLines = [];
+    if (status.dependencies.watcher.status === 'indexing') {
+        depLines.push('> ⏳ **Watcher indexing**: Initial filesystem scan in progress. Synthesis will resume when complete.');
+    }
+    else if (status.dependencies.watcher.status !== 'ok' &&
+        status.dependencies.watcher.status !== 'indexing') {
+        depLines.push('> ⚠️ **Watcher**: ' + status.dependencies.watcher.status);
+    }
+    if (status.dependencies.watcher.rulesRegistered === false &&
+        status.dependencies.watcher.status === 'ok') {
+        depLines.push('> ⚠️ **Watcher rules not registered**: Meta files may not render properly in search/server.');
+    }
+    if (status.dependencies.gateway.status !== 'ok') {
+        depLines.push('> ⚠️ **Gateway**: ' + status.dependencies.gateway.status);
+    }
+    return [
+        'The jeeves-meta synthesis engine manages ' +
+            summary.total.toString() +
+            ' meta entities.',
+        '',
+        '### Entity Summary',
+        '| Metric | Value |',
+        '|--------|-------|',
+        '| Total | ' + summary.total.toString() + ' |',
+        '| Stale | ' + summary.stale.toString() + ' |',
+        '| Errors | ' + summary.errors.toString() + ' |',
+        '| Never synthesized | ' + summary.neverSynthesized.toString() + ' |',
+        '| Stalest | ' + stalestDisplay + ' |',
+        '| Last synthesized | ' + lastSynthDisplay + ' |',
+        ...(depLines.length > 0 ? ['', '### Dependencies', ...depLines] : []),
+        '',
+        renderToolsTable(),
+    ].join('\n');
+}
+
 /**
  * Thin HTTP client for the jeeves-meta service.
  *
  * Plugin delegates all operations to the running service via HTTP.
+ * Response types are defined here as the single source of truth —
+ * consumers should not redefine them.
  *
  * @module serviceClient
  */
@@ -134,19 +301,67 @@ class MetaServiceClient {
     }
 }
 
+/**
+ * ServiceCommands and PluginCommands implementations for the JeevesComponent
+ * descriptor. Separated from register() for single-responsibility.
+ *
+ * @module serviceCommands
+ */
+/**
+ * Create ServiceCommands that proxy to the meta HTTP service.
+ *
+ * @param client - MetaServiceClient instance.
+ */
+function createServiceCommands(client) {
+    return {
+        async stop() {
+            // Meta service lifecycle is managed externally (NSSM).
+        },
+        async uninstall() {
+            // Service uninstall is handled by the service CLI.
+        },
+        async status() {
+            try {
+                const res = await client.status();
+                return {
+                    running: res.status !== 'stopped',
+                    version: res.version,
+                    uptimeSeconds: res.uptime,
+                };
+            }
+            catch {
+                return { running: false };
+            }
+        },
+    };
+}
+/** Create PluginCommands (uninstall handled by CLI). */
+function createPluginCommands() {
+    return {
+        async uninstall() {
+            // Plugin uninstall is handled by the CLI.
+        },
+    };
+}
+
 /**
  * Meta tool registrations for OpenClaw.
  *
  * All tools delegate to the jeeves-meta HTTP service.
+ * Tool names and descriptions are sourced from {@link META_TOOLS}.
  *
  * @module tools
  */
+/** Look up a tool's description by name. */
+function desc(name) {
+    return META_TOOLS.find((t) => t.name === name)?.description ?? name;
+}
 /** Register all meta_* tools. */
 function registerMetaTools(api, client) {
     // ─── meta_list ──────────────────────────────────────────────
     api.registerTool({
         name: 'meta_list',
-        description: 'List metas with summary stats and per-meta projection. Replaces meta_status + meta_entities.',
+        description: desc('meta_list'),
         parameters: {
             type: 'object',
             properties: {
@@ -192,7 +407,7 @@ function registerMetaTools(api, client) {
     // ─── meta_detail ────────────────────────────────────────────
     api.registerTool({
         name: 'meta_detail',
-        description: 'Full detail for a single meta, with optional archive history.',
+        description: desc('meta_detail'),
         parameters: {
             type: 'object',
             properties: {
@@ -228,7 +443,7 @@ function registerMetaTools(api, client) {
     // ─── meta_preview ────────────────────────────────────────────
     api.registerTool({
         name: 'meta_preview',
-        description: 'Dry-run: show what inputs would be gathered for the next synthesis cycle without running LLM.',
+        description: desc('meta_preview'),
         parameters: {
             type: 'object',
             properties: {
@@ -251,7 +466,7 @@ function registerMetaTools(api, client) {
     // ─── meta_trigger ────────────────────────────────────────────
     api.registerTool({
         name: 'meta_trigger',
-        description: 'Manually trigger synthesis for a specific meta or the next-stalest candidate. Runs the full 3-step cycle (architect, builder, critic).',
+        description: desc('meta_trigger'),
         parameters: {
             type: 'object',
             properties: {
@@ -274,259 +489,54 @@ function registerMetaTools(api, client) {
 }
 
 /**
- * Generate the Meta menu content for TOOLS.md injection.
- *
- * Queries the jeeves-meta service for entity stats and produces
- * a Markdown section suitable for agent system prompt injection.
- *
- * @module promptInjection
- */
-/**
- * Generate the Meta menu Markdown for TOOLS.md.
- *
- * @param client - MetaServiceClient instance.
- * @returns Markdown string for the Meta section.
- */
-async function generateMetaMenu(client) {
-    let status;
-    let metas;
-    try {
-        status = (await client.status());
-        metas = (await client.listMetas());
-    }
-    catch {
-        return [
-            '> **ACTION REQUIRED: jeeves-meta service is unreachable.**',
-            '> The service API is down or not configured.',
-            '>',
-            '> **Troubleshooting:**',
-            '> - Verify the service is installed: `npm list -g @karmaniverous/jeeves-meta`',
-            '> - Check if running: `curl http://localhost:1938/status`',
-            '> - Verify `serviceUrl` in plugin config if using a non-default port',
-            '>',
-            "> **Read the `jeeves-meta` skill's Bootstrapping section** for full setup guidance.",
-        ].join('\n');
-    }
-    if (metas.summary.total === 0) {
-        return [
-            '> **ACTION REQUIRED: No synthesis entities found.**',
-            '> The service is running but no `.meta/` directories were discovered.',
-            '>',
-            "> **Read the `jeeves-meta` skill's Bootstrapping section** for guidance",
-            '> on creating `.meta/` directories.',
-        ].join('\n');
-    }
-    const { summary } = metas;
-    const formatAge = (seconds) => {
-        if (!isFinite(seconds))
-            return 'never synthesized';
-        if (seconds < 3600)
-            return Math.round(seconds / 60).toString() + 'm';
-        if (seconds < 86400)
-            return Math.round(seconds / 3600).toString() + 'h';
-        return Math.round(seconds / 86400).toString() + 'd';
-    };
-    // Find stalest age
-    let stalestAge = 0;
-    for (const item of metas.metas) {
-        const s = item.stalenessSeconds !== null ? item.stalenessSeconds : Infinity;
-        if (s > stalestAge)
-            stalestAge = s;
-    }
-    const stalestDisplay = summary.stalestPath
-        ? summary.stalestPath + ' (' + formatAge(stalestAge) + ')'
-        : 'n/a';
-    const lastSynthDisplay = summary.lastSynthesizedAt
-        ? (summary.lastSynthesizedPath ?? '') +
-            ' (' +
-            summary.lastSynthesizedAt +
-            ')'
-        : 'n/a';
-    // Service status + dependency health
-    const depLines = [];
-    if (status.dependencies.watcher.status !== 'ok') {
-        depLines.push('> ⚠️ **Watcher**: ' + status.dependencies.watcher.status);
-    }
-    if (status.dependencies.gateway.status !== 'ok') {
-        depLines.push('> ⚠️ **Gateway**: ' + status.dependencies.gateway.status);
-    }
-    return [
-        'The jeeves-meta synthesis engine manages ' +
-            summary.total.toString() +
-            ' meta entities.',
-        '',
-        '### Entity Summary',
-        '| Metric | Value |',
-        '|--------|-------|',
-        '| Total | ' + summary.total.toString() + ' |',
-        '| Stale | ' + summary.stale.toString() + ' |',
-        '| Errors | ' + summary.errors.toString() + ' |',
-        '| Never synthesized | ' + summary.neverSynthesized.toString() + ' |',
-        '| Stalest | ' + stalestDisplay + ' |',
-        '| Last synthesized | ' + lastSynthDisplay + ' |',
-        ...(depLines.length > 0 ? ['', '### Dependencies', ...depLines] : []),
-        '',
-        '### Token Usage (cumulative)',
-        '| Step | Tokens |',
-        '|------|--------|',
-        '| Architect | ' + summary.tokens.architect.toLocaleString() + ' |',
-        '| Builder | ' + summary.tokens.builder.toLocaleString() + ' |',
-        '| Critic | ' + summary.tokens.critic.toLocaleString() + ' |',
-        '',
-        '### Tools',
-        '| Tool | Description |',
-        '|------|-------------|',
-        '| `meta_list` | List metas with summary stats and per-meta projection |',
-        '| `meta_detail` | Full detail for a single meta with optional archive history |',
-        '| `meta_trigger` | Manually trigger synthesis for a specific meta or next-stalest |',
-        '| `meta_preview` | Dry-run: show what inputs would be gathered without running LLM |',
-        '',
-        'Read the `jeeves-meta` skill for usage guidance, configuration, and troubleshooting.',
-    ].join('\n');
-}
-
-/**
- * Periodic TOOLS.md disk writer for the Meta section.
- *
- * Upserts a `## Meta` section under the shared `# Jeeves Platform Tools`
- * header. The gateway reads TOOLS.md fresh from disk on each new session.
- *
- * @module toolsWriter
- */
-const REFRESH_INTERVAL_MS = 60_000;
-const INITIAL_DELAY_MS = 5_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 Meta section in TOOLS.md content.
+ * OpenClaw plugin for jeeves-meta.
  *
- * Ordering convention: Watcher, Server, Meta.
- * - If `## Meta` exists, replace in place.
- * - Otherwise insert after `## Server` if present, after `## Watcher` if
- *   Server is absent, or after the H1.
- */
-function upsertMetaSection(existing, metaMenu) {
-    const section = '## Meta\n\n' + metaMenu;
-    // Replace existing Meta section (match from ## Meta to next ## or # or EOF)
-    // Remove ALL existing ## Meta sections (handles duplicates from prior bugs)
-    const re = /^## Meta\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/gm;
-    const cleaned = existing.replace(re, '').replace(/\n{3,}/g, '\n\n');
-    if (cleaned !== existing) {
-        // Had at least one section — re-insert at correct position
-        return upsertMetaSection(cleaned.trim() + '\n', metaMenu);
-    }
-    // No existing section. Insert in correct order.
-    const platformH1 = '# Jeeves Platform Tools';
-    // After ## Server if present
-    const serverRe = /^## Server\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m;
-    const serverMatch = serverRe.exec(existing);
-    if (serverMatch) {
-        const insertAt = serverMatch.index + serverMatch[0].length;
-        return (existing.slice(0, insertAt) + '\n\n' + section + existing.slice(insertAt));
-    }
-    // After ## Watcher if present
-    const watcherRe = /^## Watcher\n[\s\S]*?(?=\n## |\n# |$(?![\s\S]))/m;
-    const watcherMatch = watcherRe.exec(existing);
-    if (watcherMatch) {
-        const insertAt = watcherMatch.index + watcherMatch[0].length;
-        return (existing.slice(0, insertAt) + '\n\n' + section + existing.slice(insertAt));
-    }
-    // After H1 if present
-    if (existing.includes(platformH1)) {
-        const idx = existing.indexOf(platformH1) + platformH1.length;
-        return (existing.slice(0, idx) + '\n\n' + section + '\n' + existing.slice(idx));
-    }
-    // Prepend platform header + meta section
-    const trimmed = existing.trim();
-    if (trimmed.length === 0) {
-        return platformH1 + '\n\n' + section + '\n';
-    }
-    return platformH1 + '\n\n' + section + '\n\n' + trimmed + '\n';
-}
-/**
- * Fetch the current meta menu and write it to TOOLS.md if changed.
+ * Thin HTTP client — all operations delegate to the jeeves-meta service.
+ * Uses `@karmaniverous/jeeves` core for TOOLS.md and platform content.
  *
- * @param api - Plugin API.
- * @param client - MetaServiceClient instance.
- * @returns True if the file was updated.
+ * @packageDocumentation
  */
-async function refreshToolsMd(api, client) {
-    const menu = await generateMetaMenu(client);
-    if (menu === lastWrittenMenu) {
-        return false;
-    }
-    const toolsPath = resolveToolsPath(api);
-    let current = '';
+/** Plugin version derived from package.json. */
+const PLUGIN_VERSION = (() => {
     try {
-        current = await readFile(toolsPath, 'utf8');
+        const dir = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(resolve(dir, '..', 'package.json'), 'utf8'));
+        return pkg.version ?? 'unknown';
     }
     catch {
-        // File doesn't exist yet
+        return 'unknown';
     }
-    const updated = upsertMetaSection(current, menu);
-    if (updated !== current) {
-        await writeFile(toolsPath, updated, 'utf8');
-        lastWrittenMenu = menu;
-        return true;
-    }
-    lastWrittenMenu = menu;
-    return false;
-}
+})();
 /**
- * Start the periodic TOOLS.md writer.
- * Defers first write by 5s, then refreshes every 60s.
- *
- * @param api - Plugin API.
- * @param client - MetaServiceClient instance.
+ * Resolve the workspace path from the OpenClaw plugin API.
+ * Falls back to CWD if `api.resolvePath` is unavailable.
  */
-function startToolsWriter(api, client) {
-    // Deferred initial write
-    setTimeout(() => {
-        refreshToolsMd(api, client).catch((err) => {
-            console.error('[jeeves-meta] Failed to write TOOLS.md:', err);
-        });
-    }, INITIAL_DELAY_MS);
-    // Periodic refresh
-    if (intervalHandle) {
-        clearInterval(intervalHandle);
-    }
-    intervalHandle = setInterval(() => {
-        refreshToolsMd(api, client).catch((err) => {
-            console.error('[jeeves-meta] Failed to refresh TOOLS.md:', err);
-        });
-    }, REFRESH_INTERVAL_MS);
-    if (typeof intervalHandle === 'object' && 'unref' in intervalHandle) {
-        intervalHandle.unref();
-    }
+function resolveWorkspacePath(api) {
+    return api.resolvePath ? api.resolvePath('.') : process.cwd();
 }
-
-/**
- * OpenClaw plugin for jeeves-meta.
- *
- * Thin HTTP client — all operations delegate to the jeeves-meta service.
- * The plugin registers tools and starts the periodic TOOLS.md writer.
- *
- * @packageDocumentation
- */
 /** Register all jeeves-meta tools with the OpenClaw plugin API. */
 function register(api) {
-    const serviceUrl = getServiceUrl(api);
-    const client = new MetaServiceClient({ serviceUrl });
+    const client = new MetaServiceClient({ serviceUrl: getServiceUrl(api) });
     registerMetaTools(api, client);
-    // Start periodic TOOLS.md writer (fire-and-forget)
-    startToolsWriter(api, client);
+    init({
+        workspacePath: resolveWorkspacePath(api),
+        configRoot: getConfigRoot(api),
+    });
+    const getContent = createAsyncContentCache({
+        fetch: async () => generateMetaMenu(client),
+        placeholder: 'The jeeves-meta synthesis engine is initializing...\n\n' +
+            renderToolsTable(),
+    });
+    const writer = createComponentWriter({
+        name: 'meta',
+        version: PLUGIN_VERSION,
+        sectionId: 'Meta',
+        refreshIntervalSeconds: 73,
+        generateToolsContent: getContent,
+        serviceCommands: createServiceCommands(client),
+        pluginCommands: createPluginCommands(),
+    });
+    writer.start();
 }
 
 export { register as default };

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

@@ -3,9 +3,17 @@
 ## Overview
 
 jeeves-meta is the Jeeves platform's knowledge synthesis engine. It discovers
-`.meta/` directories via watcher scan, gathers context from the Qdrant vector
-index, and uses a three-step LLM process (architect, builder, critic) to
-produce structured synthesis artifacts co-located with source content.
+`.meta/` directories via the watcher's filesystem walk endpoint (`POST /walk`),
+gathers context from co-located source files, and uses a three-step LLM process
+(architect, builder, critic) to produce structured synthesis artifacts.
+
+**Requires:** jeeves-watcher ≥ 0.10.0 (provides `POST /walk` and auto
+rules-reindex on registration).
+
+Discovery is filesystem-based (no Qdrant dependency). The service registers
+virtual inference rules with the watcher for rendering and metadata tagging;
+the watcher's `/status` response includes `rulesRegistered` to surface
+registration health.
 
 ## Available Tools
 

package/dist/src/helpers.d.ts

@@ -12,6 +12,7 @@ export interface PluginApi {
             }>;
         };
     };
+    resolvePath?: (input: string) => string;
     registerTool(tool: {
         name: string;
         description: string;
@@ -30,14 +31,19 @@ export interface ToolResult {
     isError?: boolean;
 }
 /**
- * Resolve the service URL.
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → default value.
  *
- * Resolution order:
- * 1. Plugin config `serviceUrl` setting
- * 2. `JEEVES_META_URL` environment variable
- * 3. Default: http://127.0.0.1:1938
+ * @param api - Plugin API.
+ * @param configKey - Key in the plugin config object.
+ * @param envVar - Environment variable name.
+ * @param fallback - Default value if neither source provides one.
  */
+export declare function resolvePluginSetting(api: PluginApi, configKey: string, envVar: string, fallback: string): string;
+/** Resolve the meta service URL. */
 export declare function getServiceUrl(api: PluginApi): string;
+/** Resolve the platform config root. */
+export declare function getConfigRoot(api: PluginApi): string;
 /** Format a successful tool result. */
 export declare function ok(data: unknown): ToolResult;
 /** Format an error tool result. */

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

@@ -0,0 +1,6 @@
+/**
+ * Tests for helper utilities.
+ *
+ * @module helpers.test
+ */
+export {};

package/dist/src/index.d.ts

@@ -2,7 +2,7 @@
  * OpenClaw plugin for jeeves-meta.
  *
  * Thin HTTP client — all operations delegate to the jeeves-meta service.
- * The plugin registers tools and starts the periodic TOOLS.md writer.
+ * Uses `@karmaniverous/jeeves` core for TOOLS.md and platform content.
  *
  * @packageDocumentation
  */

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

@@ -0,0 +1,6 @@
+/**
+ * Tests for TOOLS.md menu generation, including rulesRegistered warning.
+ *
+ * @module promptInjection.test
+ */
+export {};

package/dist/src/serviceClient.d.ts

@@ -2,10 +2,58 @@
  * Thin HTTP client for the jeeves-meta service.
  *
  * Plugin delegates all operations to the running service via HTTP.
+ * Response types are defined here as the single source of truth —
+ * consumers should not redefine them.
  *
  * @module serviceClient
  */
-export interface MetaServiceConfig {
+/** Service status response from GET /status. */
+export interface StatusResponse {
+    /** Service uptime in seconds. */
+    uptime: number;
+    /** Current service status (idle, synthesizing, stopping, degraded). */
+    status: string;
+    /** Service version. */
+    version?: string;
+    /** Dependency health. */
+    dependencies: {
+        watcher: {
+            status: string;
+            rulesRegistered?: boolean;
+            indexing?: boolean;
+        };
+        gateway: {
+            status: string;
+        };
+    };
+}
+/** Summary block in the metas response. */
+export interface MetasSummary {
+    total: number;
+    stale: number;
+    errors: number;
+    neverSynthesized: number;
+    stalestPath: string | null;
+    lastSynthesizedPath: string | null;
+    lastSynthesizedAt: string | null;
+    tokens: {
+        architect: number;
+        builder: number;
+        critic: number;
+    };
+}
+/** Per-meta item in the metas response. */
+export interface MetasItem {
+    stalenessSeconds: number | null;
+    [key: string]: unknown;
+}
+/** Response from GET /metas. */
+export interface MetasResponse {
+    summary: MetasSummary;
+    metas: MetasItem[];
+}
+/** Constructor config. */
+interface MetaServiceConfig {
     /** Base URL of the jeeves-meta service (e.g. http://127.0.0.1:1938). */
     serviceUrl: string;
 }
@@ -17,7 +65,7 @@ export declare class MetaServiceClient {
     /** POST helper — returns parsed JSON. */
     private post;
     /** GET /status — service health + queue state. */
-    status(): Promise<unknown>;
+    status(): Promise<StatusResponse>;
     /** GET /metas — list all meta entities with summary. */
     listMetas(params?: {
         pathPrefix?: string;
@@ -26,7 +74,7 @@ export declare class MetaServiceClient {
         neverSynthesized?: boolean;
         locked?: boolean;
         fields?: string[];
-    }): Promise<unknown>;
+    }): Promise<MetasResponse>;
     /** GET /metas/:path — detail for a single meta. */
     detail(metaPath: string, options?: {
         includeArchive?: boolean | number;
@@ -43,3 +91,4 @@ export declare class MetaServiceClient {
     /** GET /config/validate — validate current config. */
     validate(): Promise<unknown>;
 }
+export {};

package/dist/src/serviceCommands.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ServiceCommands and PluginCommands implementations for the JeevesComponent
+ * descriptor. Separated from register() for single-responsibility.
+ *
+ * @module serviceCommands
+ */
+import type { PluginCommands, ServiceCommands } from '@karmaniverous/jeeves';
+import type { MetaServiceClient } from './serviceClient.js';
+/**
+ * Create ServiceCommands that proxy to the meta HTTP service.
+ *
+ * @param client - MetaServiceClient instance.
+ */
+export declare function createServiceCommands(client: MetaServiceClient): ServiceCommands;
+/** Create PluginCommands (uninstall handled by CLI). */
+export declare function createPluginCommands(): PluginCommands;

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

@@ -0,0 +1,6 @@
+/**
+ * Tests for ServiceCommands — status mapping and error handling.
+ *
+ * @module serviceCommands.test
+ */
+export {};

package/dist/src/toolMeta.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool name/description pairs — single source of truth for tool registration
+ * and placeholder content.
+ *
+ * @module toolMeta
+ */
+/** Metadata for a single meta_* tool. */
+interface ToolMeta {
+    /** Tool name as registered with OpenClaw. */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+}
+/** Ordered list of meta_* tools. */
+export declare const META_TOOLS: readonly ToolMeta[];
+/**
+ * Render the tools table for TOOLS.md injection.
+ *
+ * Produces a Markdown table with short descriptions suitable for
+ * both the placeholder and the live menu.
+ */
+export declare function renderToolsTable(): string;
+export {};

package/dist/src/tools.d.ts

@@ -2,6 +2,7 @@
  * Meta tool registrations for OpenClaw.
  *
  * All tools delegate to the jeeves-meta HTTP service.
+ * Tool names and descriptions are sourced from {@link META_TOOLS}.
  *
  * @module tools
  */

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "jeeves-meta-openclaw",
   "name": "Jeeves Meta",
   "description": "Knowledge synthesis tools — trigger synthesis, view status, manage entities.",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "skills": [
     "dist/skills/jeeves-meta"
   ],
@@ -12,6 +12,10 @@
       "serviceUrl": {
         "type": "string",
         "description": "URL of the jeeves-meta HTTP service. Defaults to http://127.0.0.1:1938. Falls back to JEEVES_META_URL env var."
+      },
+      "configRoot": {
+        "type": "string",
+        "description": "Absolute path to the platform config root (e.g. j:/config). Used by @karmaniverous/jeeves core for config directory resolution."
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-meta-openclaw",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "author": "Jason Williscroft",
   "description": "OpenClaw plugin for jeeves-meta — synthesis tools and virtual rule registration",
   "license": "BSD-3-Clause",
@@ -52,18 +52,19 @@
     "output": "CHANGELOG.md",
     "unreleased": true,
     "commitLimit": false,
-    "hideCredit": true
+    "hideCredit": true,
+    "tagPrefix": "openclaw/"
   },
   "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": "npm run build:plugin && npm run build:skills",
@@ -112,5 +113,8 @@
     "npm": {
       "publish": true
     }
+  },
+  "dependencies": {
+    "@karmaniverous/jeeves": "^0.1.1"
   }
 }

package/dist/src/toolsWriter.d.ts

@@ -1,27 +0,0 @@
-/**
- * Periodic TOOLS.md disk writer for the Meta section.
- *
- * Upserts a `## Meta` section under the shared `# Jeeves Platform Tools`
- * header. The gateway reads TOOLS.md fresh from disk on each new session.
- *
- * @module toolsWriter
- */
-import type { PluginApi } from './helpers.js';
-import type { MetaServiceClient } from './serviceClient.js';
-/**
- * Upsert the Meta section in TOOLS.md content.
- *
- * Ordering convention: Watcher, Server, Meta.
- * - If `## Meta` exists, replace in place.
- * - Otherwise insert after `## Server` if present, after `## Watcher` if
- *   Server is absent, or after the H1.
- */
-export declare function upsertMetaSection(existing: string, metaMenu: string): string;
-/**
- * Start the periodic TOOLS.md writer.
- * Defers first write by 5s, then refreshes every 60s.
- *
- * @param api - Plugin API.
- * @param client - MetaServiceClient instance.
- */
-export declare function startToolsWriter(api: PluginApi, client: MetaServiceClient): void;

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

@@ -1,6 +0,0 @@
-/**
- * Tests for the TOOLS.md upsert logic.
- *
- * @module toolsWriter.test
- */
-export {};