@karmaniverous/jeeves 0.3.1 → 0.4.1

package/dist/index.js

@@ -1,203 +1,14 @@
-import { JSONPath } from 'jsonpath-plus';
-import { writeFileSync, renameSync, existsSync, readFileSync, mkdirSync, cpSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { writeFileSync, renameSync, existsSync, readFileSync, mkdirSync, rmSync, readdirSync, copyFileSync, unlinkSync, cpSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
 import { lock } from 'proper-lockfile';
-import { gte } from 'semver';
+import { JSONPath } from 'jsonpath-plus';
+import * as commander from 'commander';
+import { gte, gt } from 'semver';
+import { homedir } from 'node:os';
+import { execSync, spawn } from 'node:child_process';
+import { z } from 'zod';
 import { fileURLToPath } from 'node:url';
 import { packageDirectorySync } from 'package-directory';
-import { z } from 'zod';
-import { execSync } from 'node:child_process';
-import { homedir } from 'node:os';
-
-/**
- * Generic config query handler with JSONPath support.
- *
- * @remarks
- * Provides a transport-agnostic config query function that can be
- * used by any Jeeves component's HTTP API. Returns the full config
- * document or filters it via JSONPath expressions.
- */
-/**
- * Create a config query handler.
- *
- * @remarks
- * - No `path` parameter → returns the full config document.
- * - Valid JSONPath → returns matching results with count.
- * - Invalid JSONPath → returns 400 error.
- *
- * @param getConfig - Function that returns the current config object.
- * @returns A config query handler function.
- */
-function createConfigQueryHandler(getConfig) {
-    return (query) => {
-        const config = getConfig();
-        if (!query.path) {
-            return Promise.resolve({ status: 200, body: config });
-        }
-        try {
-            const result = JSONPath({
-                path: query.path,
-                json: config,
-            });
-            return Promise.resolve({
-                status: 200,
-                body: { result, count: result.length },
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : 'Query failed';
-            return Promise.resolve({ status: 400, body: { error: message } });
-        }
-    };
-}
-
-/**
- * Directory and file path conventions for the Jeeves platform.
- */
-/** Core config directory name within the config root. */
-const CORE_CONFIG_DIR = 'jeeves-core';
-/** Prefix for component config directories: `jeeves-{name}`. */
-const COMPONENT_CONFIG_PREFIX = 'jeeves-';
-/** Default workspace file names. */
-const WORKSPACE_FILES = {
-    /** TOOLS.md — live platform state and component sections. */
-    tools: 'TOOLS.md',
-    /** SOUL.md — professional discipline and behavioral foundations. */
-    soul: 'SOUL.md',
-    /** AGENTS.md — operational protocols and memory architecture. */
-    agents: 'AGENTS.md',
-};
-/** Templates directory name within core config. */
-const TEMPLATES_DIR = 'templates';
-/** Registry cache file name. */
-const REGISTRY_CACHE_FILE = 'registry-cache.json';
-/** Core config file name. */
-const CONFIG_FILE = 'config.json';
-/** Component versions state file name. */
-const COMPONENT_VERSIONS_FILE = 'component-versions.json';
-
-/**
- * Core library version, inlined at build time.
- *
- * @remarks
- * The `0.3.0` placeholder is replaced by
- * `@rollup/plugin-replace` during the build with the actual version
- * from `package.json`. This ensures the correct version survives
- * when consumers bundle core into their own dist (where runtime
- * `import.meta.url`-based resolution would find the wrong package.json).
- */
-/** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.3.0';
-
-/**
- * Shared file I/O helpers for managed section operations.
- *
- * @remarks
- * Extracts the atomic write pattern and file-level locking into
- * reusable utilities, eliminating duplication between
- * `updateManagedSection` and `removeManagedSection`.
- */
-/** Stale lock threshold in ms (2 minutes). */
-const STALE_LOCK_MS = 120_000;
-/** Default core version when none provided. */
-const DEFAULT_CORE_VERSION = CORE_VERSION;
-/** Lock retry options. */
-const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
-/**
- * Write content to a file atomically via a temp file + rename.
- *
- * @param filePath - Absolute path to the target file.
- * @param content - Content to write.
- */
-function atomicWrite(filePath, content) {
-    const dir = dirname(filePath);
-    const tempPath = join(dir, `.${String(Date.now())}.tmp`);
-    writeFileSync(tempPath, content, 'utf-8');
-    renameSync(tempPath, filePath);
-}
-/**
- * Execute a callback while holding a file lock.
- *
- * @remarks
- * Acquires a lock on the file, executes the callback, and releases
- * the lock in a finally block. The lock uses a 2-minute stale threshold
- * and retries up to 5 times.
- *
- * @param filePath - Absolute path to the file to lock.
- * @param fn - Async callback to execute while holding the lock.
- */
-async function withFileLock(filePath, fn) {
-    let release;
-    try {
-        release = await lock(filePath, {
-            stale: STALE_LOCK_MS,
-            retries: LOCK_RETRIES,
-        });
-        await fn();
-    }
-    finally {
-        if (release) {
-            try {
-                await release();
-            }
-            catch {
-                // Lock already released or file deleted — safe to ignore
-            }
-        }
-    }
-}
-
-/**
- * Shared component version state file management.
- *
- * @remarks
- * Each `ComponentWriter` cycle writes its component's entry to
- * `{coreConfigDir}/component-versions.json`. The Platform Handlebars
- * template reads this file to populate ALL rows in the service health
- * table, not just the calling component's.
- */
-/**
- * Read the component versions state file.
- *
- * @param coreConfigDir - Path to the core config directory.
- * @returns The parsed state, or an empty object if the file doesn't exist.
- */
-function readComponentVersions(coreConfigDir) {
-    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
-    if (!existsSync(filePath))
-        return {};
-    try {
-        const raw = readFileSync(filePath, 'utf-8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return {};
-    }
-}
-/**
- * Write a component's version entry to the shared state file.
- *
- * @remarks
- * Reads the existing file, merges the new entry, and writes atomically.
- *
- * @param coreConfigDir - Path to the core config directory.
- * @param options - Component version data to write.
- */
-function writeComponentVersion(coreConfigDir, options) {
-    const existing = readComponentVersions(coreConfigDir);
-    existing[options.componentName] = {
-        pluginVersion: options.pluginVersion,
-        servicePackage: options.servicePackage,
-        pluginPackage: options.pluginPackage,
-        updatedAt: new Date().toISOString(),
-    };
-    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
-    const dir = dirname(filePath);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
-}
 
 /**
  * Comment markers for managed content blocks.
@@ -216,6 +27,8 @@ const TOOLS_MARKERS = {
     end: 'END JEEVES PLATFORM TOOLS',
     /** H1 title prepended in section mode. */
     title: 'Jeeves Platform Tools',
+    /** Managed block at bottom of file. */
+    position: 'bottom',
 };
 /** Default markers for SOUL.md managed block. */
 const SOUL_MARKERS = {
@@ -225,6 +38,8 @@ const SOUL_MARKERS = {
     end: 'END JEEVES SOUL',
     /** H1 title prepended in the managed block. */
     title: 'Jeeves Platform Soul',
+    /** Managed block at bottom of file. */
+    position: 'bottom',
 };
 /** Default markers for AGENTS.md managed block. */
 const AGENTS_MARKERS = {
@@ -234,6 +49,8 @@ const AGENTS_MARKERS = {
     end: 'END JEEVES AGENTS',
     /** H1 title prepended in the managed block. */
     title: 'Jeeves Platform Agents',
+    /** Managed block at bottom of file. */
+    position: 'bottom',
 };
 /** All known marker sets — single source of truth for cross-contamination detection. */
 const ALL_MARKERS = [
@@ -254,6 +71,33 @@ const STALENESS_THRESHOLD_MS = 5 * 60 * 1000;
 /** Warning text prepended inside managed block when cleanup is needed. */
 const CLEANUP_FLAG = '> ⚠️ CLEANUP NEEDED: Orphaned Jeeves content may exist below this managed section. Review everything after the END marker and remove any content that duplicates what appears above.';
 
+/**
+ * Directory and file path conventions for the Jeeves platform.
+ */
+/** Core config directory name within the config root. */
+const CORE_CONFIG_DIR = 'jeeves-core';
+/** Prefix for component config directories: `jeeves-{name}`. */
+const COMPONENT_CONFIG_PREFIX = 'jeeves-';
+/** Default workspace file names. */
+const WORKSPACE_FILES = {
+    /** TOOLS.md — live platform state and component sections. */
+    tools: 'TOOLS.md',
+    /** SOUL.md — professional discipline and behavioral foundations. */
+    soul: 'SOUL.md',
+    /** AGENTS.md — operational protocols and memory architecture. */
+    agents: 'AGENTS.md',
+    /** HEARTBEAT.md — platform status and health alerts. */
+    heartbeat: 'HEARTBEAT.md',
+};
+/** Templates directory name within core config. */
+const TEMPLATES_DIR = 'templates';
+/** Registry cache file name. */
+const REGISTRY_CACHE_FILE = 'registry-cache.json';
+/** Core config file name. */
+const CONFIG_FILE = 'config.json';
+/** Component versions state file name. */
+const COMPONENT_VERSIONS_FILE = 'component-versions.json';
+
 /**
  * Default port assignments for Jeeves platform services.
  *
@@ -281,7 +125,7 @@ const DEFAULT_PORTS = {
 };
 
 /**
- * Managed section IDs and their stable ordering for TOOLS.md.
+ * Managed section IDs, stable ordering, and platform component registry.
  *
  * @remarks
  * Section ordering is fixed to prevent diff churn regardless of which
@@ -311,6 +155,35 @@ const SECTION_ORDER = [
     SECTION_IDS.Runner,
     SECTION_IDS.Meta,
 ];
+/**
+ * The four essential platform components.
+ *
+ * @remarks
+ * These components constitute the Jeeves platform. `jeeves install` writes
+ * initial HEARTBEAT "Not installed" alerts for all of them. The HEARTBEAT
+ * writer generates "Not installed" alerts only for platform components not
+ * in `component-versions.json`. Optional future components (not in this list)
+ * appear in HEARTBEAT only after explicit install.
+ */
+const PLATFORM_COMPONENTS = [
+    'runner',
+    'watcher',
+    'server',
+    'meta',
+];
+
+/**
+ * Core library version, inlined at build time.
+ *
+ * @remarks
+ * The `0.4.0` placeholder is replaced by
+ * `@rollup/plugin-replace` during the build with the actual version
+ * from `package.json`. This ensures the correct version survives
+ * when consumers bundle core into their own dist (where runtime
+ * `import.meta.url`-based resolution would find the wrong package.json).
+ */
+/** The core library version from package.json (inlined at build time). */
+const CORE_VERSION = '0.4.0';
 
 /**
  * Workspace and config root initialization.
@@ -395,20 +268,1996 @@ function resetInit() {
 }
 
 /**
- * Similarity-based cleanup detection for orphaned managed content.
+ * Shared file I/O helpers for managed section operations.
  *
  * @remarks
- * Uses Jaccard similarity on 3-word shingles (Decision 22) to detect
- * when orphaned managed content exists in the user content zone.
+ * Extracts the atomic write pattern and file-level locking into
+ * reusable utilities, eliminating duplication between
+ * `updateManagedSection` and `removeManagedSection`.
  */
-/** Default similarity threshold for cleanup detection. */
-const DEFAULT_THRESHOLD = 0.15;
+/** Stale lock threshold in ms (2 minutes). */
+const STALE_LOCK_MS = 120_000;
+/** Default core version when none provided. */
+const DEFAULT_CORE_VERSION = CORE_VERSION;
+/** Lock retry options. */
+const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
 /**
- * Generate a set of n-word shingles from text.
+ * Write content to a file atomically via a temp file + rename.
  *
- * @param text - Input text.
- * @param n - Shingle size (default 3).
- * @returns Set of n-word shingles.
+ * @param filePath - Absolute path to the target file.
+ * @param content - Content to write.
+ */
+function atomicWrite(filePath, content) {
+    const dir = dirname(filePath);
+    const tempPath = join(dir, `.${String(Date.now())}.tmp`);
+    writeFileSync(tempPath, content, 'utf-8');
+    renameSync(tempPath, filePath);
+}
+/**
+ * Execute a callback while holding a file lock.
+ *
+ * @remarks
+ * Acquires a lock on the file, executes the callback, and releases
+ * the lock in a finally block. The lock uses a 2-minute stale threshold
+ * and retries up to 5 times.
+ *
+ * @param filePath - Absolute path to the file to lock.
+ * @param fn - Async callback to execute while holding the lock.
+ */
+async function withFileLock(filePath, fn) {
+    let release;
+    try {
+        release = await lock(filePath, {
+            stale: STALE_LOCK_MS,
+            retries: LOCK_RETRIES,
+        });
+        await fn();
+    }
+    finally {
+        if (release) {
+            try {
+                await release();
+            }
+            catch {
+                // Lock already released or file deleted — safe to ignore
+            }
+        }
+    }
+}
+
+/**
+ * Factory for a framework-agnostic config apply HTTP handler.
+ *
+ * @remarks
+ * Derives the config file path from the descriptor, validates patches
+ * against the descriptor's Zod schema, deep-merges (or replaces),
+ * writes atomically, and calls the optional `onConfigApply` callback.
+ */
+/**
+ * Deep-merge two plain objects. Arrays and non-objects are replaced.
+ *
+ * @param target - Base object.
+ * @param source - Object to merge on top.
+ * @returns A new merged object.
+ */
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const tVal = target[key];
+        const sVal = source[key];
+        if (isPlainObject(tVal) && isPlainObject(sVal)) {
+            result[key] = deepMerge(tVal, sVal);
+        }
+        else {
+            result[key] = sVal;
+        }
+    }
+    return result;
+}
+/**
+ * Check if a value is a plain object (not null, not an array).
+ *
+ * @param val - Value to check.
+ * @returns True if the value is a plain object.
+ */
+function isPlainObject(val) {
+    return typeof val === 'object' && val !== null && !Array.isArray(val);
+}
+/**
+ * Read and parse a JSON config file.
+ *
+ * @param filePath - Absolute path to the file.
+ * @returns Parsed object or empty object if not found.
+ */
+function readConfigFile(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`jeeves-core: Could not read config file ${filePath}: ${msg}`);
+        return {};
+    }
+}
+/**
+ * Create a framework-agnostic config apply handler.
+ *
+ * @remarks
+ * The handler:
+ * 1. Reads existing config from `{configRoot}/jeeves-{name}/{configFileName}`
+ * 2. Deep-merges the patch (or replaces if `replace: true`)
+ * 3. Validates the merged result against `descriptor.configSchema`
+ * 4. Writes atomically
+ * 5. Calls `descriptor.onConfigApply` with the merged config (if defined)
+ *
+ * @param descriptor - The component descriptor.
+ * @returns An async handler returning `{ status, body }`.
+ */
+function createConfigApplyHandler(descriptor) {
+    return async (request) => {
+        const { patch, replace } = request;
+        // Derive config path
+        const configDir = getComponentConfigDir(descriptor.name);
+        const configPath = join(configDir, descriptor.configFileName);
+        // Read existing config
+        const existing = readConfigFile(configPath);
+        // Merge or replace
+        const merged = replace ? { ...patch } : deepMerge(existing, patch);
+        // Validate against schema
+        const schema = descriptor.configSchema;
+        const parseResult = schema.safeParse(merged);
+        if (!parseResult.success) {
+            return {
+                status: 400,
+                body: {
+                    error: 'Config validation failed',
+                    issues: parseResult.error.issues,
+                },
+            };
+        }
+        // Extract validated data (Zod returns unknown from ZodTypeAny)
+        const validatedConfig = parseResult.data;
+        // Write atomically
+        try {
+            const json = JSON.stringify(validatedConfig, null, 2) + '\n';
+            atomicWrite(configPath, json);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                status: 500,
+                body: { error: `Failed to write config: ${message}` },
+            };
+        }
+        // Call onConfigApply callback if defined
+        if (descriptor.onConfigApply) {
+            try {
+                await descriptor.onConfigApply(validatedConfig);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    status: 200,
+                    body: {
+                        applied: true,
+                        warning: `Config written but callback failed: ${message}`,
+                        config: validatedConfig,
+                    },
+                };
+            }
+        }
+        return {
+            status: 200,
+            body: {
+                applied: true,
+                config: validatedConfig,
+            },
+        };
+    };
+}
+
+/**
+ * Generic config query handler with JSONPath support.
+ *
+ * @remarks
+ * Provides a transport-agnostic config query function that can be
+ * used by any Jeeves component's HTTP API. Returns the full config
+ * document or filters it via JSONPath expressions.
+ */
+/**
+ * Create a config query handler.
+ *
+ * @remarks
+ * - No `path` parameter → returns the full config document.
+ * - Valid JSONPath → returns matching results with count.
+ * - Invalid JSONPath → returns 400 error.
+ *
+ * @param getConfig - Function that returns the current config object.
+ * @returns A config query handler function.
+ */
+function createConfigQueryHandler(getConfig) {
+    return (query) => {
+        const config = getConfig();
+        if (!query.path) {
+            return Promise.resolve({ status: 200, body: config });
+        }
+        try {
+            const result = JSONPath({
+                path: query.path,
+                json: config,
+            });
+            return Promise.resolve({
+                status: 200,
+                body: { result, count: result.length },
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Query failed';
+            return Promise.resolve({ status: 400, body: { error: message } });
+        }
+    };
+}
+
+/**
+ * Factory for a framework-agnostic `/status` HTTP handler.
+ *
+ * @remarks
+ * Returns a standard status response shape consumed by HEARTBEAT
+ * orchestration and the `{name}_status` plugin tool.
+ * Tracks process start time internally for uptime calculation.
+ */
+/**
+ * Create a framework-agnostic status handler.
+ *
+ * @param options - Handler configuration.
+ * @returns An async function returning `{ status, body }`.
+ */
+function createStatusHandler(options) {
+    const startTime = Date.now();
+    return async () => {
+        const uptimeSeconds = Math.floor((Date.now() - startTime) / 1000);
+        let health = {};
+        let overallStatus = 'healthy';
+        if (options.getHealth) {
+            try {
+                health = await options.getHealth();
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                health = { error: message };
+                overallStatus = 'degraded';
+            }
+        }
+        return {
+            status: 200,
+            body: {
+                name: options.name,
+                version: options.version,
+                uptime: uptimeSeconds,
+                status: overallStatus,
+                health,
+            },
+        };
+    };
+}
+
+function getDefaultExportFromCjs (x) {
+	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
+}
+
+function getAugmentedNamespace(n) {
+  if (Object.prototype.hasOwnProperty.call(n, '__esModule')) return n;
+  var f = n.default;
+	if (typeof f == "function") {
+		var a = function a () {
+			var isInstance = false;
+      try {
+        isInstance = this instanceof a;
+      } catch {}
+			if (isInstance) {
+        return Reflect.construct(f, arguments, this.constructor);
+			}
+			return f.apply(this, arguments);
+		};
+		a.prototype = f.prototype;
+  } else a = {};
+  Object.defineProperty(a, '__esModule', {value: true});
+	Object.keys(n).forEach(function (k) {
+		var d = Object.getOwnPropertyDescriptor(n, k);
+		Object.defineProperty(a, k, d.get ? d : {
+			enumerable: true,
+			get: function () {
+				return n[k];
+			}
+		});
+	});
+	return a;
+}
+
+var extraTypings = {exports: {}};
+
+var require$$0 = /*@__PURE__*/getAugmentedNamespace(commander);
+
+var hasRequiredExtraTypings;
+
+function requireExtraTypings () {
+	if (hasRequiredExtraTypings) return extraTypings.exports;
+	hasRequiredExtraTypings = 1;
+	(function (module, exports$1) {
+		const commander = require$$0;
+
+		exports$1 = module.exports = {};
+
+		// Return a different global program than commander,
+		// and don't also return it as default export.
+		exports$1.program = new commander.Command();
+
+		/**
+		 * Expose classes. The FooT versions are just types, so return Commander original implementations!
+		 */
+
+		exports$1.Argument = commander.Argument;
+		exports$1.Command = commander.Command;
+		exports$1.CommanderError = commander.CommanderError;
+		exports$1.Help = commander.Help;
+		exports$1.InvalidArgumentError = commander.InvalidArgumentError;
+		exports$1.InvalidOptionArgumentError = commander.InvalidArgumentError; // Deprecated
+		exports$1.Option = commander.Option;
+
+		exports$1.createCommand = (name) => new commander.Command(name);
+		exports$1.createOption = (flags, description) =>
+		  new commander.Option(flags, description);
+		exports$1.createArgument = (name, description) =>
+		  new commander.Argument(name, description); 
+	} (extraTypings, extraTypings.exports));
+	return extraTypings.exports;
+}
+
+var extraTypingsExports = requireExtraTypings();
+var extraTypingsCommander = /*@__PURE__*/getDefaultExportFromCjs(extraTypingsExports);
+
+// wrapper to provide named exports for ESM.
+const {
+  program,
+  createCommand,
+  createArgument,
+  createOption,
+  CommanderError,
+  InvalidArgumentError,
+  InvalidOptionArgumentError, // deprecated old name
+  Command,
+  Argument,
+  Option,
+  Help,
+} = extraTypingsCommander;
+
+/**
+ * Shared component version state file management.
+ *
+ * @remarks
+ * Each `ComponentWriter` cycle writes its component's entry to
+ * `{coreConfigDir}/component-versions.json`. The Platform Handlebars
+ * template reads this file to populate ALL rows in the service health
+ * table, not just the calling component's.
+ */
+/**
+ * Read the component versions state file.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @returns The parsed state, or an empty object if the file doesn't exist.
+ */
+function readComponentVersions(coreConfigDir) {
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write a component's version entry to the shared state file.
+ *
+ * @remarks
+ * Reads the existing file, merges the new entry, and writes atomically.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param options - Component version data to write.
+ */
+function writeComponentVersion(coreConfigDir, options) {
+    const existing = readComponentVersions(coreConfigDir);
+    existing[options.componentName] = {
+        pluginVersion: options.pluginVersion,
+        servicePackage: options.servicePackage,
+        pluginPackage: options.pluginPackage,
+        updatedAt: new Date().toISOString(),
+    };
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
+}
+/**
+ * Remove a component's version entry from the shared state file.
+ *
+ * @remarks
+ * Called during plugin uninstall to prevent the HEARTBEAT writer from
+ * probing a service that's intentionally gone. If the component isn't
+ * in the file, this is a no-op.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param componentName - The component name to remove.
+ */
+function removeComponentVersion(coreConfigDir, componentName) {
+    const existing = readComponentVersions(coreConfigDir);
+    if (!(componentName in existing))
+        return;
+    const updated = Object.fromEntries(Object.entries(existing).filter(([key]) => key !== componentName));
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    atomicWrite(filePath, JSON.stringify(updated, null, 2) + '\n');
+}
+
+/**
+ * Heading-based HEARTBEAT section writer.
+ *
+ * @remarks
+ * Manages the `# Jeeves Platform Status` section in HEARTBEAT.md.
+ * Unlike TOOLS/SOUL/AGENTS (which use HTML comment markers), HEARTBEAT
+ * uses markdown headings as markers — this ensures the file passes
+ * OpenClaw's heartbeat emptiness check when only headings remain.
+ *
+ * The section is always at the bottom of the file (H1 to EOF).
+ * User heartbeat items above the section are preserved.
+ */
+/** The H1 heading that anchors the platform status section. */
+const HEARTBEAT_HEADING = '# Jeeves Platform Status';
+/**
+ * Parse the HEARTBEAT.md file content.
+ *
+ * @param fileContent - Full file content.
+ * @returns Parsed result with user zone and component entries.
+ */
+function parseHeartbeat(fileContent) {
+    const headingIndex = fileContent.indexOf(HEARTBEAT_HEADING);
+    if (headingIndex === -1) {
+        return {
+            userContent: fileContent.trim(),
+            found: false,
+            entries: [],
+        };
+    }
+    const userContent = fileContent.slice(0, headingIndex).trim();
+    const sectionContent = fileContent.slice(headingIndex + HEARTBEAT_HEADING.length);
+    const entries = [];
+    const h2Re = /^## (jeeves-\S+?)(?:: declined)?$/gm;
+    let match;
+    const h2Positions = [];
+    while ((match = h2Re.exec(sectionContent)) !== null) {
+        const fullHeading = match[0];
+        const name = match[1];
+        const declined = fullHeading.endsWith(': declined');
+        h2Positions.push({ name, declined, start: match.index });
+    }
+    for (let i = 0; i < h2Positions.length; i++) {
+        const pos = h2Positions[i];
+        const headingLine = pos.declined
+            ? `## ${pos.name}: declined`
+            : `## ${pos.name}`;
+        const contentStart = pos.start + headingLine.length;
+        const contentEnd = i + 1 < h2Positions.length
+            ? h2Positions[i + 1].start
+            : sectionContent.length;
+        const content = sectionContent.slice(contentStart, contentEnd).trim();
+        entries.push({
+            name: pos.name,
+            declined: pos.declined,
+            content,
+        });
+    }
+    return { userContent, found: true, entries };
+}
+/**
+ * Build the HEARTBEAT section content from entries.
+ *
+ * @param entries - Component entries to write.
+ * @returns The full section string (H1 + H2s).
+ */
+function buildHeartbeatSection(entries) {
+    const parts = [HEARTBEAT_HEADING];
+    for (const entry of entries) {
+        if (entry.declined) {
+            parts.push(`## ${entry.name}: declined`);
+        }
+        else if (entry.content) {
+            parts.push(`## ${entry.name}`);
+            parts.push(entry.content);
+        }
+        // Healthy components (no content, not declined) get no H2 section
+    }
+    return parts.join('\n');
+}
+/**
+ * Write the HEARTBEAT section to a file.
+ *
+ * @remarks
+ * Replaces everything from `# Jeeves Platform Status` to EOF.
+ * Preserves user content above the heading. Uses file-level locking.
+ *
+ * @param filePath - Absolute path to HEARTBEAT.md.
+ * @param entries - Component entries to write.
+ */
+async function writeHeartbeatSection(filePath, entries) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, '', 'utf-8');
+    }
+    try {
+        await withFileLock(filePath, () => {
+            const fileContent = readFileSync(filePath, 'utf-8');
+            const parsed = parseHeartbeat(fileContent);
+            const section = buildHeartbeatSection(entries);
+            const parts = [];
+            if (parsed.userContent) {
+                parts.push(parsed.userContent);
+                parts.push('');
+            }
+            parts.push(section);
+            parts.push('');
+            atomicWrite(filePath, parts.join('\n'));
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`jeeves-core: writeHeartbeatSection failed for ${filePath}: ${message}`);
+    }
+}
+
+/**
+ * Stable section ordering for managed TOOLS.md blocks.
+ *
+ * @remarks
+ * Sorts sections by the canonical SECTION_ORDER: known sections
+ * appear in their defined order, unknown sections are appended after.
+ * Used by both parseManaged (for consistent output) and
+ * updateManagedSection (for reassembly).
+ */
+/**
+ * Sort sections in place by stable ordering.
+ *
+ * @param sections - Array of managed sections to sort.
+ * @returns The sorted array (same reference, mutated in place).
+ */
+function sortSectionsByOrder(sections) {
+    return sections.sort((a, b) => {
+        const aIdx = SECTION_ORDER.indexOf(a.id);
+        const bIdx = SECTION_ORDER.indexOf(b.id);
+        const aOrder = aIdx === -1 ? SECTION_ORDER.length : aIdx;
+        const bOrder = bIdx === -1 ? SECTION_ORDER.length : bIdx;
+        return aOrder - bOrder;
+    });
+}
+
+/**
+ * Parse managed block from file content.
+ *
+ * @remarks
+ * Extracts managed content delimited by comment markers, parses H2
+ * sections within the block, and returns the structured result plus
+ * user content outside the markers.
+ */
+/**
+ * Build regex patterns for the given markers.
+ *
+ * @param markers - Begin/end marker strings.
+ * @returns Object with begin and end regex patterns.
+ */
+function buildMarkerPatterns(markers) {
+    const escapedBegin = markers.begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const escapedEnd = markers.end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return {
+        beginRe: new RegExp(`^<!--\\s*${escapedBegin}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$`, 'm'),
+        endRe: new RegExp(`^<!--\\s*${escapedEnd}\\s*-->\\s*$`, 'm'),
+    };
+}
+/**
+ * Parse H2 sections from managed block content.
+ *
+ * @param content - Raw managed block content.
+ * @returns Array of parsed sections in stable order.
+ */
+function parseSections(content) {
+    const lines = content.split('\n');
+    const sections = [];
+    let currentId;
+    let currentLines = [];
+    for (const line of lines) {
+        const h2Match = /^## (.+)$/.exec(line);
+        if (h2Match) {
+            if (currentId !== undefined) {
+                sections.push({
+                    id: currentId,
+                    content: currentLines.join('\n').trim(),
+                });
+            }
+            currentId = h2Match[1];
+            currentLines = [];
+        }
+        else if (currentId !== undefined) {
+            currentLines.push(line);
+        }
+    }
+    if (currentId !== undefined) {
+        sections.push({
+            id: currentId,
+            content: currentLines.join('\n').trim(),
+        });
+    }
+    return sortSectionsByOrder(sections);
+}
+/**
+ * Parse a managed block from file content.
+ *
+ * @param fileContent - Full file content.
+ * @param markers - Optional custom markers (defaults to TOOLS markers).
+ * @returns Parsed result with sections, version stamp, and user content.
+ */
+function parseManaged(fileContent, markers = TOOLS_MARKERS) {
+    const { beginRe, endRe } = buildMarkerPatterns(markers);
+    const beginMatch = beginRe.exec(fileContent);
+    if (!beginMatch) {
+        return {
+            found: false,
+            versionStamp: undefined,
+            managedContent: '',
+            sections: [],
+            beforeContent: '',
+            userContent: fileContent,
+        };
+    }
+    const endMatch = endRe.exec(fileContent.slice(beginMatch.index + beginMatch[0].length));
+    if (!endMatch) {
+        // Corrupt: BEGIN without END — treat as fresh file
+        return {
+            found: false,
+            versionStamp: undefined,
+            managedContent: '',
+            sections: [],
+            beforeContent: '',
+            userContent: fileContent,
+        };
+    }
+    const beforeContent = fileContent.slice(0, beginMatch.index).trim();
+    const managedStart = beginMatch.index + beginMatch[0].length;
+    const managedEnd = managedStart + endMatch.index;
+    const managedContent = fileContent.slice(managedStart, managedEnd).trim();
+    const afterEnd = managedStart + endMatch.index + endMatch[0].length;
+    const userContent = fileContent.slice(afterEnd).trim();
+    // Extract version stamp from BEGIN marker line
+    let versionStamp;
+    const stampMatch = VERSION_STAMP_PATTERN.exec(beginMatch[0]);
+    if (stampMatch?.[2] && stampMatch[3]) {
+        versionStamp = {
+            version: stampMatch[2],
+            timestamp: stampMatch[3],
+        };
+    }
+    const sections = parseSections(managedContent);
+    return {
+        found: true,
+        versionStamp,
+        managedContent,
+        sections,
+        beforeContent,
+        userContent,
+    };
+}
+
+/**
+ * Version-stamp parsing and convergence logic.
+ *
+ * @remarks
+ * When multiple component plugins bundle different core library versions,
+ * they independently maintain shared managed content. The version-stamp
+ * mechanism ensures convergence without coordination state.
+ */
+/**
+ * Format the BEGIN marker comment with a version stamp.
+ *
+ * @param markerText - The marker text (e.g., 'BEGIN JEEVES PLATFORM TOOLS').
+ * @param version - The core library version.
+ * @returns Formatted comment line.
+ */
+function formatBeginMarker(markerText, version) {
+    const timestamp = new Date().toISOString();
+    return `<!-- ${markerText} | core:${version} | ${timestamp} -->`;
+}
+/**
+ * Format the END marker comment.
+ *
+ * @param markerText - The marker text (e.g., 'END JEEVES PLATFORM TOOLS').
+ * @returns Formatted comment line.
+ */
+function formatEndMarker(markerText) {
+    return `<!-- ${markerText} -->`;
+}
+/**
+ * Determine whether this writer should proceed based on version-stamp
+ * convergence rules.
+ *
+ * @param myVersion - The current core library version.
+ * @param existing - The existing version stamp (if any).
+ * @param stalenessThresholdMs - Staleness threshold in ms (default: 5 min).
+ * @returns `true` if the writer should proceed with the write.
+ */
+function shouldWrite(myVersion, existing, stalenessThresholdMs = STALENESS_THRESHOLD_MS) {
+    // No existing stamp — always write
+    if (!existing)
+        return true;
+    // My version >= stamped version — always write (I'm current or newer)
+    if (gte(myVersion, existing.version))
+        return true;
+    // My version < stamped version — check staleness
+    const stampAge = Date.now() - new Date(existing.timestamp).getTime();
+    return stampAge >= stalenessThresholdMs;
+}
+
+/**
+ * Remove a managed section or entire managed block from a file.
+ *
+ * @remarks
+ * Supports two modes:
+ * - No `sectionId`: Remove the entire managed block (markers + content),
+ *   leaving user content intact.
+ * - With `sectionId`: Remove a specific H2 section from within the
+ *   managed block. If it was the last section, remove the entire block.
+ *
+ * Provides file-level locking and atomic writes (temp file + rename).
+ * Missing markers or nonexistent sections are no-ops (no error thrown).
+ */
+/**
+ * Remove a managed section or entire managed block from a file.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param options - Optional section ID and custom markers.
+ */
+async function removeManagedSection(filePath, options = {}) {
+    const { sectionId, markers = TOOLS_MARKERS } = options;
+    if (!existsSync(filePath))
+        return;
+    await withFileLock(filePath, () => {
+        const fileContent = readFileSync(filePath, 'utf-8');
+        const parsed = parseManaged(fileContent, markers);
+        if (!parsed.found)
+            return;
+        let newContent;
+        if (!sectionId) {
+            // Remove entire managed block
+            newContent = buildWithoutBlock(parsed.beforeContent, parsed.userContent);
+        }
+        else {
+            // Remove specific section
+            const remaining = parsed.sections.filter((s) => s.id !== sectionId);
+            if (remaining.length === parsed.sections.length) {
+                // Section not found — no-op
+                return;
+            }
+            if (remaining.length === 0) {
+                // Last section removed — remove entire block
+                newContent = buildWithoutBlock(parsed.beforeContent, parsed.userContent);
+            }
+            else {
+                // Rebuild managed block without the removed section
+                newContent = buildWithSections(parsed.beforeContent, parsed.userContent, remaining, markers, parsed.versionStamp?.version);
+            }
+        }
+        atomicWrite(filePath, newContent);
+    });
+}
+/** Build file content without the managed block. */
+function buildWithoutBlock(beforeContent, userContent) {
+    const parts = [];
+    if (beforeContent)
+        parts.push(beforeContent);
+    if (userContent) {
+        if (parts.length > 0)
+            parts.push('');
+        parts.push(userContent);
+    }
+    if (parts.length === 0)
+        return '';
+    return parts.join('\n') + '\n';
+}
+/** Rebuild file content with remaining sections. */
+function buildWithSections(beforeContent, userContent, sections, markers, coreVersion) {
+    const sorted = sortSectionsByOrder([...sections]);
+    const sectionText = sorted
+        .map((s) => `## ${s.id}\n\n${s.content}`)
+        .join('\n\n');
+    const managedBody = markers.title
+        ? `# ${markers.title}\n\n${sectionText}`
+        : sectionText;
+    const beginLine = formatBeginMarker(markers.begin, coreVersion ?? DEFAULT_CORE_VERSION);
+    const endLine = formatEndMarker(markers.end);
+    const parts = [];
+    if (beforeContent) {
+        parts.push(beforeContent);
+        parts.push('');
+    }
+    parts.push(beginLine);
+    parts.push('');
+    parts.push(managedBody);
+    parts.push('');
+    parts.push(endLine);
+    if (userContent) {
+        parts.push('');
+        parts.push(userContent);
+    }
+    parts.push('');
+    return parts.join('\n');
+}
+
+/**
+ * OpenClaw configuration helpers for plugin CLI installers.
+ *
+ * @remarks
+ * Provides resolution of OpenClaw home directory and config file path,
+ * plus idempotent config patching for plugin install/uninstall.
+ */
+/**
+ * Resolve the OpenClaw home directory.
+ *
+ * @remarks
+ * Resolution order:
+ * 1. `OPENCLAW_CONFIG` env var → dirname of the config file path
+ * 2. `OPENCLAW_HOME` env var → resolved path
+ * 3. Default: `~/.openclaw`
+ *
+ * @returns Absolute path to the OpenClaw home directory.
+ */
+function resolveOpenClawHome() {
+    if (process.env.OPENCLAW_CONFIG) {
+        return dirname(resolve(process.env.OPENCLAW_CONFIG));
+    }
+    if (process.env.OPENCLAW_HOME) {
+        return resolve(process.env.OPENCLAW_HOME);
+    }
+    return join(homedir(), '.openclaw');
+}
+/**
+ * Resolve the OpenClaw config file path.
+ *
+ * @remarks
+ * If `OPENCLAW_CONFIG` is set, uses that directly.
+ * Otherwise defaults to `{home}/openclaw.json`.
+ *
+ * @param home - The OpenClaw home directory.
+ * @returns Absolute path to the config file.
+ */
+function resolveConfigPath(home) {
+    if (process.env.OPENCLAW_CONFIG) {
+        return resolve(process.env.OPENCLAW_CONFIG);
+    }
+    return join(home, 'openclaw.json');
+}
+/**
+ * Patch an allowlist array: add or remove the plugin ID.
+ *
+ * @returns A log message if a change was made, or undefined.
+ */
+function patchAllowList(parent, key, label, pluginId, mode) {
+    if (mode === 'add') {
+        if (!Array.isArray(parent[key])) {
+            parent[key] = [pluginId];
+            return `Created ${label} with "${pluginId}"`;
+        }
+        const list = parent[key];
+        if (!list.includes(pluginId)) {
+            list.push(pluginId);
+            return `Added "${pluginId}" to ${label}`;
+        }
+    }
+    else {
+        if (!Array.isArray(parent[key]))
+            return undefined;
+        const list = parent[key];
+        const filtered = list.filter((id) => id !== pluginId);
+        if (filtered.length !== list.length) {
+            parent[key] = filtered;
+            return `Removed "${pluginId}" from ${label}`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Patch an OpenClaw config for plugin install or uninstall.
+ *
+ * @remarks
+ * Manages `plugins.entries.{pluginId}` and `tools.alsoAllow`.
+ * Idempotent: adding twice produces no duplicates; removing when absent
+ * produces no errors.
+ *
+ * @param config - The parsed OpenClaw config object (mutated in place).
+ * @param pluginId - The plugin identifier.
+ * @param mode - Whether to add or remove the plugin.
+ * @returns Array of log messages describing changes made.
+ */
+function patchConfig(config, pluginId, mode) {
+    const messages = [];
+    // Ensure plugins section
+    if (!config.plugins || typeof config.plugins !== 'object') {
+        config.plugins = {};
+    }
+    const plugins = config.plugins;
+    // plugins.entries
+    if (!plugins.entries || typeof plugins.entries !== 'object') {
+        plugins.entries = {};
+    }
+    const entries = plugins.entries;
+    if (mode === 'add') {
+        if (!entries[pluginId]) {
+            entries[pluginId] = { enabled: true };
+            messages.push(`Added "${pluginId}" to plugins.entries`);
+        }
+    }
+    else if (pluginId in entries) {
+        Reflect.deleteProperty(entries, pluginId);
+        messages.push(`Removed "${pluginId}" from plugins.entries`);
+    }
+    // tools.alsoAllow
+    if (!config.tools || typeof config.tools !== 'object') {
+        config.tools = {};
+    }
+    const tools = config.tools;
+    const toolAlsoAllow = patchAllowList(tools, 'alsoAllow', 'tools.alsoAllow', pluginId, mode);
+    if (toolAlsoAllow)
+        messages.push(toolAlsoAllow);
+    return messages;
+}
+
+/**
+ * Factory for the standard `-openclaw` plugin installer CLI.
+ *
+ * @remarks
+ * Produces a Commander program with `install` and `uninstall` commands
+ * that handle the full plugin lifecycle: copy dist to extensions,
+ * patch OpenClaw config, manage HEARTBEAT entries, and clean up
+ * managed sections on uninstall.
+ */
+/**
+ * Derive a component name from a plugin ID.
+ *
+ * @remarks
+ * Strips `jeeves-` prefix and `-openclaw` suffix.
+ *
+ * @param pluginId - The plugin identifier.
+ * @returns Component short name.
+ */
+function deriveComponentName(pluginId) {
+    return pluginId.replace(/^jeeves-/, '').replace(/-openclaw$/, '');
+}
+/**
+ * Copy all files from source directory to destination.
+ *
+ * @param srcDir - Source directory.
+ * @param destDir - Destination directory.
+ */
+function copyDistFiles(srcDir, destDir) {
+    mkdirSync(destDir, { recursive: true });
+    const entries = readdirSync(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(srcDir, entry.name);
+        const destPath = join(destDir, entry.name);
+        if (entry.isDirectory()) {
+            copyDistFiles(srcPath, destPath);
+        }
+        else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+/**
+ * Read and parse a JSON file, returning an empty object if not found.
+ *
+ * @param filePath - Path to the JSON file.
+ * @returns Parsed object.
+ */
+function readJsonFile(filePath) {
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Create a standard plugin installer CLI program.
+ *
+ * @param options - Plugin CLI configuration.
+ * @returns A Commander program ready for `.parse()`.
+ */
+function createPluginCli(options) {
+    const { pluginId, distDir, pluginPackage, configRoot = 'j:/config', } = options;
+    const componentName = options.componentName ?? deriveComponentName(pluginId);
+    const program = new Command()
+        .name(pluginPackage)
+        .description(`Jeeves ${componentName} plugin installer`);
+    program
+        .command('install')
+        .description(`Install the ${componentName} plugin`)
+        .option('--memory', 'Claim a memory slot for this plugin')
+        .option('-w, --workspace <path>', 'Workspace root path')
+        .option('-c, --config-root <path>', 'Platform config root path', configRoot)
+        .action((opts) => {
+        const openClawHome = resolveOpenClawHome();
+        const configPath = resolveConfigPath(openClawHome);
+        // 1. Copy dist to extensions
+        const extensionsDir = join(openClawHome, 'extensions', pluginId);
+        console.log(`Copying dist to ${extensionsDir}...`);
+        copyDistFiles(distDir, extensionsDir);
+        console.log('  ✓ Dist files copied');
+        // 2. Patch openclaw.json
+        console.log('Patching OpenClaw config...');
+        const config = readJsonFile(configPath);
+        const messages = patchConfig(config, pluginId, 'add');
+        // 3. Memory slot claim
+        if (opts.memory) {
+            if (!config.agents || typeof config.agents !== 'object') {
+                config.agents = {};
+            }
+            const agents = config.agents;
+            if (!agents.defaults || typeof agents.defaults !== 'object') {
+                agents.defaults = {};
+            }
+            const defaults = agents.defaults;
+            if (!defaults.memory || typeof defaults.memory !== 'object') {
+                defaults.memory = {};
+            }
+            const memory = defaults.memory;
+            if (!memory[componentName]) {
+                memory[componentName] = {};
+                messages.push(`Claimed memory slot for "${componentName}"`);
+            }
+        }
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+        for (const msg of messages) {
+            console.log(`  ✓ ${msg}`);
+        }
+        // 4. Write initial HEARTBEAT entry
+        try {
+            const cfgRoot = opts.configRoot;
+            const agents = config.agents;
+            const defaults = agents?.defaults;
+            const ws = opts.workspace ?? defaults?.workspace;
+            if (ws) {
+                init({ workspacePath: ws, configRoot: cfgRoot });
+                const heartbeatPath = join(ws, WORKSPACE_FILES.heartbeat);
+                try {
+                    const existing = existsSync(heartbeatPath)
+                        ? readFileSync(heartbeatPath, 'utf-8')
+                        : '';
+                    const parsed = parseHeartbeat(existing);
+                    const fullName = `jeeves-${componentName}`;
+                    // Only add if not already present
+                    const hasEntry = parsed.entries.some((e) => e.name === fullName);
+                    if (!hasEntry) {
+                        parsed.entries.push({
+                            name: fullName,
+                            declined: false,
+                            content: `- Plugin installed. Awaiting service configuration.`,
+                        });
+                        const section = buildHeartbeatSection(parsed.entries);
+                        atomicWrite(heartbeatPath, section);
+                        console.log('  ✓ HEARTBEAT entry written');
+                    }
+                }
+                catch {
+                    console.log('  ⚠ Could not write HEARTBEAT entry');
+                }
+            }
+        }
+        catch {
+            // HEARTBEAT is best-effort during install
+        }
+        console.log();
+        console.log(`✅ ${pluginPackage} installed.`);
+    });
+    program
+        .command('uninstall')
+        .description(`Uninstall the ${componentName} plugin`)
+        .option('-w, --workspace <path>', 'Workspace root path')
+        .option('-c, --config-root <path>', 'Platform config root path', configRoot)
+        .action(async (opts) => {
+        const openClawHome = resolveOpenClawHome();
+        const cfgPath = resolveConfigPath(openClawHome);
+        // 1. Remove from extensions
+        const extensionsDir = join(openClawHome, 'extensions', pluginId);
+        if (existsSync(extensionsDir)) {
+            rmSync(extensionsDir, { recursive: true, force: true });
+            console.log('  ✓ Extension files removed');
+        }
+        // 2. Unpatch openclaw.json
+        if (existsSync(cfgPath)) {
+            const config = readJsonFile(cfgPath);
+            const messages = patchConfig(config, pluginId, 'remove');
+            writeFileSync(cfgPath, JSON.stringify(config, null, 2) + '\n');
+            for (const msg of messages) {
+                console.log(`  ✓ ${msg}`);
+            }
+        }
+        // 3. Remove TOOLS.md section
+        try {
+            const cfgRoot = opts.configRoot;
+            const ws = opts.workspace;
+            if (ws) {
+                init({ workspacePath: ws, configRoot: cfgRoot });
+                const sectionId = componentName.charAt(0).toUpperCase() + componentName.slice(1);
+                const toolsPath = join(ws, WORKSPACE_FILES.tools);
+                if (existsSync(toolsPath)) {
+                    await removeManagedSection(toolsPath, {
+                        sectionId,
+                        markers: TOOLS_MARKERS,
+                    });
+                    console.log('  ✓ TOOLS.md section removed');
+                }
+            }
+        }
+        catch {
+            console.log('  ⚠ Could not remove TOOLS.md section');
+        }
+        // 4. Remove component-versions.json entry
+        try {
+            const cfgRoot = opts.configRoot;
+            init({
+                workspacePath: opts.workspace ?? '.',
+                configRoot: cfgRoot,
+            });
+            removeComponentVersion(getCoreConfigDir(), componentName);
+            console.log('  ✓ Component version entry removed');
+        }
+        catch {
+            console.log('  ⚠ Could not remove component version entry');
+        }
+        console.log();
+        console.log(`✅ ${pluginPackage} uninstalled.`);
+    });
+    return program;
+}
+
+/**
+ * Zod schema for the Jeeves component descriptor.
+ *
+ * @remarks
+ * The descriptor replaces the v0.4.0 `JeevesComponent` interface with a
+ * Zod-first approach. The TypeScript type is inferred via `z.infer<>`.
+ * Validates at parse time: prime interval, callable functions.
+ */
+/**
+ * Check whether a number is prime.
+ *
+ * @param n - Number to check.
+ * @returns `true` if n is prime.
+ */
+function isPrime(n) {
+    if (n < 2)
+        return false;
+    if (n === 2)
+        return true;
+    if (n % 2 === 0)
+        return false;
+    for (let i = 3; i * i <= n; i += 2) {
+        if (n % i === 0)
+            return false;
+    }
+    return true;
+}
+/**
+ * Zod schema for the Jeeves component descriptor.
+ *
+ * @remarks
+ * Single source of truth for what a component must provide.
+ * Factories consume this descriptor to produce CLI commands,
+ * plugin tools, and HTTP handlers.
+ */
+const jeevesComponentDescriptorSchema = z.object({
+    /** Component name (e.g., 'watcher', 'runner', 'server', 'meta'). */
+    name: z.string().min(1, 'name must be a non-empty string'),
+    /** Component version (from package.json). */
+    version: z.string().min(1, 'version must be a non-empty string'),
+    /** npm package name for the service. */
+    servicePackage: z.string().min(1),
+    /** npm package name for the plugin. */
+    pluginPackage: z.string().min(1),
+    /** System service name. Defaults to `jeeves-${name}` when not provided. */
+    serviceName: z.string().min(1).optional(),
+    /** Default port for the service's HTTP API. */
+    defaultPort: z.number().int().positive(),
+    /** Zod schema for validating config files. */
+    configSchema: z.custom((val) => val !== null &&
+        typeof val === 'object' &&
+        typeof val.parse === 'function', { message: 'configSchema must be a Zod schema' }),
+    /** Config file name (e.g., 'jeeves-watcher.config.json'). */
+    configFileName: z.string().min(1),
+    /** Returns a default config object for `init`. */
+    initTemplate: z.function().returns(z.record(z.unknown())),
+    /**
+     * Service-side callback after config apply. Receives the merged,
+     * validated config (not the raw patch). Optional — if omitted,
+     * write-only (service picks up changes on restart).
+     */
+    onConfigApply: z
+        .function()
+        .args(z.record(z.unknown()))
+        .returns(z.promise(z.void()))
+        .optional(),
+    /**
+     * Returns command + args for launching the service process.
+     * Consumed by `start` CLI command and `service install`.
+     */
+    startCommand: z.function().args(z.string()).returns(z.array(z.string())),
+    /** TOOLS.md section name (e.g., 'Watcher'). */
+    sectionId: z.string().min(1, 'sectionId must be a non-empty string'),
+    /** Refresh interval in seconds (must be a prime number). */
+    refreshIntervalSeconds: z.number().int().positive().refine(isPrime, {
+        message: 'refreshIntervalSeconds must be a prime number',
+    }),
+    /** Produce the component's TOOLS.md section content. */
+    generateToolsContent: z.function().returns(z.string()),
+    /** Component dependencies for HEARTBEAT alert suppression. */
+    dependencies: z
+        .object({
+        hard: z.array(z.string()),
+        soft: z.array(z.string()),
+    })
+        .optional(),
+    /** Extension point: add custom CLI commands to the service CLI. */
+    customCliCommands: z
+        .function()
+        .args(z.custom())
+        .returns(z.void())
+        .optional(),
+    /** Extension point: return additional plugin tool descriptors. */
+    customPluginTools: z
+        .function()
+        .args(z.custom())
+        .returns(z.array(z.unknown()))
+        .optional(),
+});
+/**
+ * Derive the effective service name from a descriptor.
+ *
+ * @param descriptor - The component descriptor.
+ * @returns The service name (explicit or derived from `jeeves-{name}`).
+ */
+function getEffectiveServiceName(descriptor) {
+    return descriptor.serviceName ?? `jeeves-${descriptor.name}`;
+}
+
+/**
+ * HTTP helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Thin wrappers around `fetch` that throw on non-OK responses
+ * and handle JSON serialisation/deserialisation.
+ */
+/**
+ * Fetch a URL with an automatic abort timeout.
+ *
+ * @param url - URL to fetch.
+ * @param timeoutMs - Timeout in milliseconds before aborting.
+ * @param init - Optional `fetch` init options.
+ * @returns The fetch Response object.
+ */
+async function fetchWithTimeout(url, timeoutMs, init) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Fetch JSON from a URL, throwing on non-OK responses.
+ *
+ * @param url - URL to fetch.
+ * @param init - Optional `fetch` init options.
+ * @returns Parsed JSON response body.
+ * @throws Error with `HTTP {status}: {body}` message on non-OK responses.
+ */
+async function fetchJson(url, init) {
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
+    }
+    return res.json();
+}
+/**
+ * POST JSON to a URL and return parsed response.
+ *
+ * @param url - URL to POST to.
+ * @param body - Request body (will be JSON-stringified).
+ * @returns Parsed JSON response body.
+ */
+async function postJson(url, body) {
+    return fetchJson(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+}
+
+/**
+ * Platform-aware service state detection.
+ *
+ * @remarks
+ * Detects whether a system service is installed and running.
+ * Delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ */
+/**
+ * Detect the state of a system service by name.
+ *
+ * @param serviceName - The service name (e.g., 'jeeves-runner').
+ * @returns The detected service state.
+ */
+function getServiceState(serviceName) {
+    switch (process.platform) {
+        case 'win32':
+            return getServiceStateWindows(serviceName);
+        case 'darwin':
+            return getServiceStateMacOS(serviceName);
+        default:
+            return getServiceStateLinux(serviceName);
+    }
+}
+/**
+ * Windows: detect via NSSM.
+ * - Exit code 3 = service does not exist
+ * - "SERVICE_RUNNING" in output = running
+ * - Other output = stopped/paused
+ */
+function getServiceStateWindows(serviceName) {
+    try {
+        const output = execSync(`nssm status ${serviceName}`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (output.includes('SERVICE_RUNNING'))
+            return 'running';
+        return 'stopped';
+    }
+    catch (err) {
+        // NSSM exits with code 3 when the service doesn't exist
+        if (isExecError(err) && err.status === 3)
+            return 'not_installed';
+        // Any other error (nssm not found, timeout, etc.) — treat as not installed
+        return 'not_installed';
+    }
+}
+/**
+ * Linux: detect via systemd user services.
+ * - `systemctl --user is-enabled {name}.service` exits non-zero = not installed
+ * - `systemctl --user is-active {name}.service` returns "active" = running
+ */
+function getServiceStateLinux(serviceName) {
+    try {
+        execSync(`systemctl --user is-enabled ${serviceName}.service`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        return 'not_installed';
+    }
+    try {
+        const output = execSync(`systemctl --user is-active ${serviceName}.service`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (output === 'active')
+            return 'running';
+        return 'stopped';
+    }
+    catch {
+        return 'stopped';
+    }
+}
+/**
+ * macOS: detect via launchctl.
+ * - `launchctl list {name}` exits non-zero = not installed
+ * - PID column is `-` or `0` = stopped
+ */
+function getServiceStateMacOS(serviceName) {
+    try {
+        const output = execSync(`launchctl list ${serviceName}`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        // launchctl list output formats:
+        // 1. Table row: "PID\tStatus\tLabel" (e.g., "1234\t0\tcom.jeeves.runner")
+        // 2. Plist-style: '"PID" = 1234;'
+        // 3. Single service: first token is the PID or "-"
+        // Try table format: first token is PID
+        const tableMatch = /^(\d+|-)\s/m.exec(output);
+        if (tableMatch) {
+            const pid = tableMatch[1];
+            return pid !== '-' && Number(pid) > 0 ? 'running' : 'stopped';
+        }
+        // Try plist-style: "PID" = <number>;
+        const plistMatch = /"PID"\s*=\s*(\d+)/m.exec(output);
+        if (plistMatch) {
+            return Number(plistMatch[1]) > 0 ? 'running' : 'stopped';
+        }
+        // If we got output but can't parse it, assume stopped (service exists but state unclear)
+        return 'stopped';
+    }
+    catch {
+        return 'not_installed';
+    }
+}
+/** Type guard for execSync errors with a status code. */
+function isExecError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'status' in err &&
+        typeof err.status === 'number');
+}
+
+/**
+ * Factory for platform-aware service lifecycle management.
+ *
+ * @remarks
+ * Produces a `ServiceManager` that handles install, uninstall, start,
+ * stop, restart, and status for system services. Delegates to NSSM
+ * (Windows), systemd (Linux), or launchd (macOS) based on platform.
+ */
+/** Exec helper that returns stdout. */
+function run(cmd) {
+    return execSync(cmd, {
+        encoding: 'utf-8',
+        timeout: 30_000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+}
+/** Exec helper that suppresses errors and returns success boolean. */
+function runQuiet(cmd) {
+    try {
+        execSync(cmd, {
+            encoding: 'utf-8',
+            timeout: 30_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the effective service name from options and descriptor.
+ *
+ * @param descriptor - Component descriptor.
+ * @param options - Optional overrides.
+ * @returns The service name to use.
+ */
+function resolveServiceName(descriptor, options) {
+    return options?.name ?? getEffectiveServiceName(descriptor);
+}
+/**
+ * Resolve the config path for install.
+ *
+ * @param descriptor - Component descriptor.
+ * @param options - Optional overrides.
+ * @returns Absolute config file path.
+ */
+function resolveConfigFilePath(descriptor, options) {
+    if (options?.configPath)
+        return options.configPath;
+    const configDir = getComponentConfigDir(descriptor.name);
+    return join(configDir, descriptor.configFileName);
+}
+/** Build a Windows NSSM service manager. */
+function createWindowsManager(descriptor) {
+    return {
+        install(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            const cfgPath = resolveConfigFilePath(descriptor, options);
+            const cmdArgs = descriptor.startCommand(cfgPath);
+            const appPath = cmdArgs[0];
+            const appArgs = cmdArgs.slice(1).join(' ');
+            run(`nssm install ${svcName} ${appPath}`);
+            if (appArgs) {
+                run(`nssm set ${svcName} AppParameters ${appArgs}`);
+            }
+            run(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
+            run(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
+            run(`nssm set ${svcName} AppRotateFiles 1`);
+            run(`nssm set ${svcName} AppRotateBytes 1048576`);
+        },
+        uninstall(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`nssm stop ${svcName}`);
+            run(`nssm remove ${svcName} confirm`);
+        },
+        start(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`nssm start ${svcName}`);
+        },
+        stop(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`nssm stop ${svcName}`);
+        },
+        restart(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`nssm restart ${svcName}`);
+        },
+        status(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            return getServiceState(svcName);
+        },
+    };
+}
+/**
+ * Generate a systemd user unit file.
+ *
+ * @param svcName - Service name.
+ * @param cmdArgs - Command + args array.
+ * @returns Unit file content.
+ */
+function buildSystemdUnit(svcName, cmdArgs) {
+    const execStart = cmdArgs.join(' ');
+    return [
+        '[Unit]',
+        `Description=${svcName}`,
+        'After=network.target',
+        '',
+        '[Service]',
+        'Type=simple',
+        `ExecStart=${execStart}`,
+        'Restart=on-failure',
+        'RestartSec=5',
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+    ].join('\n');
+}
+/** Build a Linux systemd service manager. */
+function createLinuxManager(descriptor) {
+    const unitDir = join(homedir(), '.config', 'systemd', 'user');
+    function unitPath(svcName) {
+        return join(unitDir, `${svcName}.service`);
+    }
+    return {
+        install(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            const cfgPath = resolveConfigFilePath(descriptor, options);
+            const cmdArgs = descriptor.startCommand(cfgPath);
+            mkdirSync(unitDir, { recursive: true });
+            writeFileSync(unitPath(svcName), buildSystemdUnit(svcName, cmdArgs));
+            run('systemctl --user daemon-reload');
+            run(`systemctl --user enable ${svcName}.service`);
+        },
+        uninstall(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`systemctl --user stop ${svcName}.service`);
+            runQuiet(`systemctl --user disable ${svcName}.service`);
+            const path = unitPath(svcName);
+            if (existsSync(path))
+                unlinkSync(path);
+            runQuiet('systemctl --user daemon-reload');
+        },
+        start(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`systemctl --user start ${svcName}.service`);
+        },
+        stop(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`systemctl --user stop ${svcName}.service`);
+        },
+        restart(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`systemctl --user restart ${svcName}.service`);
+        },
+        status(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            return getServiceState(svcName);
+        },
+    };
+}
+/**
+ * Generate a macOS launchd plist.
+ *
+ * @param svcName - Service label.
+ * @param cmdArgs - Command + args array.
+ * @returns Plist XML content.
+ */
+function buildLaunchdPlist(svcName, cmdArgs) {
+    const argsXml = cmdArgs.map((a) => `    <string>${a}</string>`).join('\n');
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"',
+        '  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        '<dict>',
+        '  <key>Label</key>',
+        `  <string>${svcName}</string>`,
+        '  <key>ProgramArguments</key>',
+        '  <array>',
+        argsXml,
+        '  </array>',
+        '  <key>RunAtLoad</key>',
+        '  <true/>',
+        '  <key>KeepAlive</key>',
+        '  <true/>',
+        '  <key>StandardOutPath</key>',
+        `  <string>${join(homedir(), 'Library', 'Logs', `${svcName}.log`)}</string>`,
+        '  <key>StandardErrorPath</key>',
+        `  <string>${join(homedir(), 'Library', 'Logs', `${svcName}.log`)}</string>`,
+        '</dict>',
+        '</plist>',
+    ].join('\n');
+}
+/** Build a macOS launchd service manager. */
+function createMacOSManager(descriptor) {
+    const agentsDir = join(homedir(), 'Library', 'LaunchAgents');
+    function plistPath(svcName) {
+        return join(agentsDir, `${svcName}.plist`);
+    }
+    return {
+        install(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            const cfgPath = resolveConfigFilePath(descriptor, options);
+            const cmdArgs = descriptor.startCommand(cfgPath);
+            mkdirSync(agentsDir, { recursive: true });
+            writeFileSync(plistPath(svcName), buildLaunchdPlist(svcName, cmdArgs));
+        },
+        uninstall(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`launchctl unload ${plistPath(svcName)}`);
+            const path = plistPath(svcName);
+            if (existsSync(path))
+                unlinkSync(path);
+        },
+        start(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`launchctl load ${plistPath(svcName)}`);
+        },
+        stop(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run(`launchctl unload ${plistPath(svcName)}`);
+        },
+        restart(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`launchctl unload ${plistPath(svcName)}`);
+            run(`launchctl load ${plistPath(svcName)}`);
+        },
+        status(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            return getServiceState(svcName);
+        },
+    };
+}
+/**
+ * Create a platform-aware service manager from a component descriptor.
+ *
+ * @remarks
+ * Detects the current platform and returns a `ServiceManager` that
+ * delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ *
+ * @param descriptor - The component descriptor.
+ * @returns A `ServiceManager` for the current platform.
+ */
+function createServiceManager(descriptor) {
+    switch (process.platform) {
+        case 'win32':
+            return createWindowsManager(descriptor);
+        case 'darwin':
+            return createMacOSManager(descriptor);
+        default:
+            return createLinuxManager(descriptor);
+    }
+}
+
+/**
+ * Factory for the standard Jeeves service CLI.
+ *
+ * @remarks
+ * Produces a Commander program with all standard commands from
+ * a component descriptor. Components add domain-specific commands
+ * via `descriptor.customCliCommands`.
+ */
+/**
+ * Create a standard service CLI program from a component descriptor.
+ *
+ * @remarks
+ * Standard commands:
+ * - `start -c <path>` - Launch the service process (foreground)
+ * - `status [-p port]` - Probe service health
+ * - `config [jsonpath] [-p port]` - Query running config
+ * - `config validate -c <path>` - Validate a config file
+ * - `config apply [-p port] [--file path] [--replace]` - Apply config patch
+ * - `init [-o path]` - Generate default config
+ * - `service install` - Install system service
+ * - `service uninstall` - Uninstall system service
+ * - `service start` - Start system service
+ * - `service stop` - Stop system service
+ * - `service restart` - Restart system service
+ * - `service status` - Query system service state
+ *
+ * @param descriptor - The component descriptor.
+ * @returns A Commander program ready for custom commands and `.parse()`.
+ */
+function createServiceCli(descriptor) {
+    const defaultServiceName = getEffectiveServiceName(descriptor);
+    const program = new Command()
+        .name(`jeeves-${descriptor.name}`)
+        .description(`Jeeves ${descriptor.name} service CLI`)
+        .version(descriptor.version)
+        .enablePositionalOptions()
+        .passThroughOptions();
+    // --- start ---
+    program
+        .command('start')
+        .description('Launch the service process (foreground)')
+        .requiredOption('-c, --config <path>', 'Config file path')
+        .action((opts) => {
+        const cmdArgs = descriptor.startCommand(opts.config);
+        const proc = spawn(cmdArgs[0], cmdArgs.slice(1), {
+            stdio: 'inherit',
+        });
+        proc.on('exit', (code) => {
+            process.exit(code ?? 1);
+        });
+    });
+    // --- status ---
+    program
+        .command('status')
+        .description('Probe service health and version')
+        .option('-p, --port <port>', 'Service port', String(descriptor.defaultPort))
+        .action(async (opts) => {
+        const url = `http://127.0.0.1:${opts.port}`;
+        try {
+            const result = await fetchJson(`${url}/status`);
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Service unreachable: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    // --- config ---
+    const configCmd = program
+        .command('config')
+        .description('Query or manage service configuration');
+    configCmd
+        .command('query')
+        .description('Query running service config via JSONPath')
+        .argument('[jsonpath]', 'JSONPath expression')
+        .option('-p, --port <port>', 'Service port', String(descriptor.defaultPort))
+        .action(async (jsonpath, opts) => {
+        const url = `http://127.0.0.1:${opts.port}`;
+        const qs = jsonpath ? `?path=${encodeURIComponent(jsonpath)}` : '';
+        try {
+            const result = await fetchJson(`${url}/config${qs}`);
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Config query failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    configCmd
+        .command('validate')
+        .description('Validate a config file against the schema')
+        .requiredOption('-c, --config <path>', 'Config file path')
+        .action((opts) => {
+        try {
+            const raw = readFileSync(opts.config, 'utf-8');
+            const parsed = JSON.parse(raw);
+            descriptor.configSchema.parse(parsed);
+            console.log('Config is valid.');
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Validation failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    configCmd
+        .command('apply')
+        .description('Apply a config patch to the running service')
+        .option('-p, --port <port>', 'Service port', String(descriptor.defaultPort))
+        .option('-f, --file <path>', 'Config patch file (JSON)')
+        .option('--replace', 'Replace entire config instead of merging')
+        .action(async (opts) => {
+        const url = `http://127.0.0.1:${opts.port}`;
+        let patch = {};
+        if (opts.file) {
+            const raw = readFileSync(opts.file, 'utf-8');
+            patch = JSON.parse(raw);
+        }
+        else {
+            // Read from stdin
+            const chunks = [];
+            for await (const chunk of process.stdin) {
+                chunks.push(chunk);
+            }
+            const input = Buffer.concat(chunks).toString('utf-8').trim();
+            if (input) {
+                patch = JSON.parse(input);
+            }
+        }
+        const qs = opts.replace ? '?replace=true' : '';
+        try {
+            const result = await postJson(`${url}/config/apply${qs}`, patch);
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Config apply failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    // --- init ---
+    program
+        .command('init')
+        .description('Generate default config file')
+        .option('-o, --output <path>', 'Output directory')
+        .action((opts) => {
+        const outputDir = opts.output ?? getComponentConfigDir(descriptor.name);
+        mkdirSync(outputDir, { recursive: true });
+        const configPath = join(outputDir, descriptor.configFileName);
+        if (existsSync(configPath)) {
+            console.log(`Config already exists at ${configPath}`);
+            return;
+        }
+        const template = descriptor.initTemplate();
+        writeFileSync(configPath, JSON.stringify(template, null, 2) + '\n');
+        console.log(`Config written to ${configPath}`);
+    });
+    // --- service ---
+    const serviceCmd = program
+        .command('service')
+        .description('System service management');
+    const svcManager = createServiceManager(descriptor);
+    serviceCmd
+        .command('install')
+        .description('Install as a system service')
+        .option('-c, --config <path>', 'Config file path')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.install({ name: opts.name, configPath: opts.config });
+            console.log(`Service "${opts.name}" installed.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Install failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('uninstall')
+        .description('Uninstall the system service')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.uninstall({ name: opts.name });
+            console.log(`Service "${opts.name}" uninstalled.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Uninstall failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('start')
+        .description('Start the system service')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.start({ name: opts.name });
+            console.log(`Service "${opts.name}" started.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Start failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('stop')
+        .description('Stop the system service')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.stop({ name: opts.name });
+            console.log(`Service "${opts.name}" stopped.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Stop failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('restart')
+        .description('Restart the system service')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            svcManager.restart({ name: opts.name });
+            console.log(`Service "${opts.name}" restarted.`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Restart failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    serviceCmd
+        .command('status')
+        .description('Query system service state')
+        .option('-n, --name <name>', 'Service name', defaultServiceName)
+        .action((opts) => {
+        try {
+            const state = svcManager.status({ name: opts.name });
+            console.log(`Service "${opts.name}": ${state}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`Status failed: ${msg}`);
+            process.exitCode = 1;
+        }
+    });
+    // Apply custom CLI commands if provided
+    if (descriptor.customCliCommands) {
+        // Cast required: @commander-js/extra-typings Command has generic type
+        // parameters that don't align with the descriptor's base Command type.
+        // The descriptor can't know the parent Command's exact generic parameters
+        // at definition time. The cast is safe — customCliCommands only adds
+        // subcommands and doesn't depend on the parent's generic state.
+        descriptor.customCliCommands(program);
+    }
+    return program;
+}
+
+/**
+ * Similarity-based cleanup detection for orphaned managed content.
+ *
+ * @remarks
+ * Uses Jaccard similarity on 3-word shingles (Decision 22) to detect
+ * when orphaned managed content exists in the user content zone.
+ */
+/** Default similarity threshold for cleanup detection. */
+const DEFAULT_THRESHOLD = 0.15;
+/**
+ * Generate a set of n-word shingles from text.
+ *
+ * @param text - Input text.
+ * @param n - Shingle size (default 3).
+ * @returns Set of n-word shingles.
  */
 function shingles(text, n = 3) {
     const words = text.toLowerCase().split(/\s+/).filter(Boolean);
@@ -449,146 +2298,6 @@ function needsCleanup(managedContent, userContent, threshold = DEFAULT_THRESHOLD
     return jaccard(shingles(managedContent), shingles(userContent)) > threshold;
 }
 
-/**
- * Stable section ordering for managed TOOLS.md blocks.
- *
- * @remarks
- * Sorts sections by the canonical SECTION_ORDER: known sections
- * appear in their defined order, unknown sections are appended after.
- * Used by both parseManaged (for consistent output) and
- * updateManagedSection (for reassembly).
- */
-/**
- * Sort sections in place by stable ordering.
- *
- * @param sections - Array of managed sections to sort.
- * @returns The sorted array (same reference, mutated in place).
- */
-function sortSectionsByOrder(sections) {
-    return sections.sort((a, b) => {
-        const aIdx = SECTION_ORDER.indexOf(a.id);
-        const bIdx = SECTION_ORDER.indexOf(b.id);
-        const aOrder = aIdx === -1 ? SECTION_ORDER.length : aIdx;
-        const bOrder = bIdx === -1 ? SECTION_ORDER.length : bIdx;
-        return aOrder - bOrder;
-    });
-}
-
-/**
- * Parse managed block from file content.
- *
- * @remarks
- * Extracts managed content delimited by comment markers, parses H2
- * sections within the block, and returns the structured result plus
- * user content outside the markers.
- */
-/**
- * Build regex patterns for the given markers.
- *
- * @param markers - Begin/end marker strings.
- * @returns Object with begin and end regex patterns.
- */
-function buildMarkerPatterns(markers) {
-    const escapedBegin = markers.begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const escapedEnd = markers.end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    return {
-        beginRe: new RegExp(`^<!--\\s*${escapedBegin}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$`, 'm'),
-        endRe: new RegExp(`^<!--\\s*${escapedEnd}\\s*-->\\s*$`, 'm'),
-    };
-}
-/**
- * Parse H2 sections from managed block content.
- *
- * @param content - Raw managed block content.
- * @returns Array of parsed sections in stable order.
- */
-function parseSections(content) {
-    const lines = content.split('\n');
-    const sections = [];
-    let currentId;
-    let currentLines = [];
-    for (const line of lines) {
-        const h2Match = /^## (.+)$/.exec(line);
-        if (h2Match) {
-            if (currentId !== undefined) {
-                sections.push({
-                    id: currentId,
-                    content: currentLines.join('\n').trim(),
-                });
-            }
-            currentId = h2Match[1];
-            currentLines = [];
-        }
-        else if (currentId !== undefined) {
-            currentLines.push(line);
-        }
-    }
-    if (currentId !== undefined) {
-        sections.push({
-            id: currentId,
-            content: currentLines.join('\n').trim(),
-        });
-    }
-    return sortSectionsByOrder(sections);
-}
-/**
- * Parse a managed block from file content.
- *
- * @param fileContent - Full file content.
- * @param markers - Optional custom markers (defaults to TOOLS markers).
- * @returns Parsed result with sections, version stamp, and user content.
- */
-function parseManaged(fileContent, markers = TOOLS_MARKERS) {
-    const { beginRe, endRe } = buildMarkerPatterns(markers);
-    const beginMatch = beginRe.exec(fileContent);
-    if (!beginMatch) {
-        return {
-            found: false,
-            versionStamp: undefined,
-            managedContent: '',
-            sections: [],
-            beforeContent: '',
-            userContent: fileContent,
-        };
-    }
-    const endMatch = endRe.exec(fileContent.slice(beginMatch.index + beginMatch[0].length));
-    if (!endMatch) {
-        // Corrupt: BEGIN without END — treat as fresh file
-        return {
-            found: false,
-            versionStamp: undefined,
-            managedContent: '',
-            sections: [],
-            beforeContent: '',
-            userContent: fileContent,
-        };
-    }
-    const beforeContent = fileContent.slice(0, beginMatch.index).trim();
-    const managedStart = beginMatch.index + beginMatch[0].length;
-    const managedEnd = managedStart + endMatch.index;
-    const managedContent = fileContent.slice(managedStart, managedEnd).trim();
-    const afterEnd = managedStart + endMatch.index + endMatch[0].length;
-    const userContent = fileContent.slice(afterEnd).trim();
-    // Extract version stamp from BEGIN marker line
-    let versionStamp;
-    const stampMatch = VERSION_STAMP_PATTERN.exec(beginMatch[0]);
-    if (stampMatch?.[2] && stampMatch[3]) {
-        versionStamp = {
-            version: stampMatch[2],
-            timestamp: stampMatch[3],
-        };
-    }
-    const sections = parseSections(managedContent);
-    return {
-        found: true,
-        versionStamp,
-        managedContent,
-        sections,
-        beforeContent,
-        userContent,
-    };
-}
-
 /**
  * Strip foreign managed blocks from content.
  *
@@ -631,55 +2340,6 @@ function stripForeignMarkers(content, currentMarkers) {
     return result.replace(/\n{3,}/g, '\n\n').trim();
 }
 
-/**
- * Version-stamp parsing and convergence logic.
- *
- * @remarks
- * When multiple component plugins bundle different core library versions,
- * they independently maintain shared managed content. The version-stamp
- * mechanism ensures convergence without coordination state.
- */
-/**
- * Format the BEGIN marker comment with a version stamp.
- *
- * @param markerText - The marker text (e.g., 'BEGIN JEEVES PLATFORM TOOLS').
- * @param version - The core library version.
- * @returns Formatted comment line.
- */
-function formatBeginMarker(markerText, version) {
-    const timestamp = new Date().toISOString();
-    return `<!-- ${markerText} | core:${version} | ${timestamp} -->`;
-}
-/**
- * Format the END marker comment.
- *
- * @param markerText - The marker text (e.g., 'END JEEVES PLATFORM TOOLS').
- * @returns Formatted comment line.
- */
-function formatEndMarker(markerText) {
-    return `<!-- ${markerText} -->`;
-}
-/**
- * Determine whether this writer should proceed based on version-stamp
- * convergence rules.
- *
- * @param myVersion - The current core library version.
- * @param existing - The existing version stamp (if any).
- * @param stalenessThresholdMs - Staleness threshold in ms (default: 5 min).
- * @returns `true` if the writer should proceed with the write.
- */
-function shouldWrite(myVersion, existing, stalenessThresholdMs = STALENESS_THRESHOLD_MS) {
-    // No existing stamp — always write
-    if (!existing)
-        return true;
-    // My version >= stamped version — always write (I'm current or newer)
-    if (gte(myVersion, existing.version))
-        return true;
-    // My version < stamped version — check staleness
-    const stampAge = Date.now() - new Date(existing.timestamp).getTime();
-    return stampAge >= stalenessThresholdMs;
-}
-
 /**
  * Generic managed-section writer with block and section modes.
  *
@@ -747,32 +2407,51 @@ async function updateManagedSection(filePath, content, options = {}) {
                     ? `# ${markers.title}\n\n${sectionText}`
                     : sectionText;
             }
+            // Combine beforeContent + userContent for the user zone.
+            // When migrating from top→bottom, beforeContent is empty and
+            // userContent has the real content. When already at bottom,
+            // beforeContent has the user content and userContent is empty.
+            const rawUserContent = [parsed.beforeContent, parsed.userContent]
+                .filter(Boolean)
+                .join('\n\n')
+                .trim();
             // Strip foreign managed blocks from user content (cross-contamination fix)
-            const userContent = stripForeignMarkers(parsed.userContent, markers);
+            const userContent = stripForeignMarkers(rawUserContent, markers);
             const cleanupNeeded = needsCleanup(newManagedBody, userContent);
             // Build the full managed block
             const beginLine = formatBeginMarker(markers.begin, coreVersion);
             const endLine = formatEndMarker(markers.end);
-            const parts = [];
-            if (parsed.beforeContent) {
-                parts.push(parsed.beforeContent);
-                parts.push('');
-            }
-            parts.push(beginLine);
+            const managedParts = [];
+            managedParts.push(beginLine);
             if (cleanupNeeded) {
-                parts.push('');
-                parts.push(CLEANUP_FLAG);
+                managedParts.push('');
+                managedParts.push(CLEANUP_FLAG);
+            }
+            managedParts.push('');
+            managedParts.push(newManagedBody);
+            managedParts.push('');
+            managedParts.push(endLine);
+            const managedBlock = managedParts.join('\n');
+            const position = markers.position ?? 'top';
+            const fileParts = [];
+            if (position === 'bottom') {
+                // User content first, managed block at end
+                if (userContent) {
+                    fileParts.push(userContent);
+                    fileParts.push('');
+                }
+                fileParts.push(managedBlock);
             }
-            parts.push('');
-            parts.push(newManagedBody);
-            parts.push('');
-            parts.push(endLine);
-            if (userContent) {
-                parts.push('');
-                parts.push(userContent);
+            else {
+                // Managed block first (legacy default), user content below
+                fileParts.push(managedBlock);
+                if (userContent) {
+                    fileParts.push('');
+                    fileParts.push(userContent);
+                }
             }
-            parts.push('');
-            const newFileContent = parts.join('\n');
+            fileParts.push('');
+            const newFileContent = fileParts.join('\n');
             atomicWrite(filePath, newFileContent);
         });
     }
@@ -850,6 +2529,8 @@ At minimum, always brief sub-agents on:
 
 **Anything important enough to have a permanent cron/heartbeat entry is important enough to be codified into the data flow.**
 
+**HEARTBEAT efficiency:** When HEARTBEAT fires with multiple component alerts, resolve them all in a single conversation. Walk the user through each component in dependency order. Each heartbeat cycle is a full LLM session — resolve all alerts in one pass.
+
 ## Messaging Dispatch
 
 **Same-channel replies:** Don't use the \`message\` tool. It fires immediately, jumping ahead of streaming narration. Just write text as your response. Use \`message\` only for **cross-channel** sends (sending to a different channel or DM than the one you're responding in).
@@ -858,7 +2539,7 @@ At minimum, always brief sub-agents on:
 
 ## Heartbeat Discipline
 
-**Default state of HEARTBEAT.md is EMPTY** (comments only). Every heartbeat loads the full system prompt. An empty heartbeat that returns HEARTBEAT_OK still costs a full LLM session.
+**Default state of HEARTBEAT.md is effectively empty** — the \`# Jeeves Platform Status\` section contains only headings when all components are healthy or declined. No list content, no LLM cost. User heartbeat items (above the platform status section) follow the same transient/termination rules as before.
 
 Heartbeat items are for **transient, session-requiring work-in-progress ONLY**. Each item must include its own termination condition.
 
@@ -919,14 +2600,11 @@ When discovering a new data source, integrate it into the existing data flow pip
 
 ## Bootstrap Protocol
 
-When you detect that a Jeeves platform component is missing or not configured:
+**Proactive platform status:** HEARTBEAT.md is loaded every session. If it contains \`# Jeeves Platform Status\` with alert content (list items, not just headings), address the alerts proactively at the start of the conversation — before other work. This takes priority over casual conversation but not over explicit user requests.
 
-1. **Identify** the gap (service not responding on expected port, plugin not registered, config file missing)
-2. **Inform** the user what's missing and what it provides
-3. **Guide** them through installation using the component's CLI install command
-4. **Verify** the installation succeeded (probe the port, check the plugin registration)
+**Follow the instructions:** Explain the component, ask for consent, execute the command, verify. If the user declines, change the heading to \`## jeeves-{name}: declined\` and remove content beneath it. Do not prompt for declined components. Do not improvise — the HEARTBEAT instructions are authoritative.
 
-Don't silently work around missing components. The user should know what's available and what isn't.
+When resolving multiple component alerts, walk the user through each in dependency order (watcher before meta, runner and server independent) within a single conversation rather than one per heartbeat cycle.
 
 ## Em-Dash Discipline
 
@@ -1165,330 +2843,106 @@ Read these templates when creating new specs, onboarding to new projects, or whe
  * When bundled into a consumer plugin, returns undefined and template
  * copying is skipped (templates are seeded by `jeeves install`, not plugins).
  *
- * Content `.md` files (soul, agents, platform template) are inlined at
- * build time via the rollup md plugin and imported as string literals.
- * They do not use this function.
- *
- * @returns Absolute path to the content/ directory, or undefined.
- */
-function getContentDir() {
-    const pkgDir = packageDirectorySync({
-        cwd: fileURLToPath(import.meta.url),
-    });
-    if (!pkgDir)
-        return undefined;
-    const dir = join(pkgDir, 'content');
-    return existsSync(dir) ? dir : undefined;
-}
-/**
- * Copy templates from content/templates/ to the core config directory.
- *
- * @param coreConfigDir - Core config directory path.
- */
-function copyTemplates(coreConfigDir) {
-    const contentDir = getContentDir();
-    if (!contentDir)
-        return;
-    const sourceDir = join(contentDir, 'templates');
-    if (!existsSync(sourceDir))
-        return;
-    const destDir = join(coreConfigDir, TEMPLATES_DIR);
-    if (!existsSync(destDir)) {
-        mkdirSync(destDir, { recursive: true });
-    }
-    cpSync(sourceDir, destDir, { recursive: true });
-}
-/**
- * Render the Platform template using simple string replacement.
- *
- * @param templatePath - Path to the templates directory.
- * @returns Rendered platform content string.
- */
-function renderPlatformTemplate(templatePath) {
-    const templatesAvailable = existsSync(templatePath);
-    let content = toolsPlatformTemplate;
-    // Handle <!-- IF_TEMPLATES --> ... <!-- ELSE_TEMPLATES --> ... <!-- ENDIF_TEMPLATES --> block
-    const ifRegex = /<!-- IF_TEMPLATES -->([\s\S]*?)<!-- ELSE_TEMPLATES -->([\s\S]*?)<!-- ENDIF_TEMPLATES -->/;
-    const match = ifRegex.exec(content);
-    if (match) {
-        content = content.replace(match[0], templatesAvailable ? match[1] : match[2]);
-    }
-    // Replace __TEMPLATE_PATH__ with the actual path
-    content = content.replace(/__TEMPLATE_PATH__/g, templatePath);
-    return content;
-}
-/**
- * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
- *
- * @param options - Configuration for the refresh cycle.
- */
-async function refreshPlatformContent(options) {
-    const { coreVersion, componentName, componentVersion, servicePackage, pluginPackage, stalenessThresholdMs, } = options;
-    const workspacePath = getWorkspacePath();
-    const coreConfigDir = getCoreConfigDir();
-    // 1. Write calling component's version entry
-    if (componentName) {
-        writeComponentVersion(coreConfigDir, {
-            componentName,
-            pluginVersion: componentVersion,
-            servicePackage,
-            pluginPackage,
-        });
-    }
-    // 2. Render Platform template
-    const templatePath = join(coreConfigDir, TEMPLATES_DIR);
-    const platformContent = renderPlatformTemplate(templatePath);
-    // 3. Write TOOLS.md Platform section
-    const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
-    await updateManagedSection(toolsPath, platformContent, {
-        mode: 'section',
-        sectionId: 'Platform',
-        markers: TOOLS_MARKERS,
-        coreVersion,
-        stalenessThresholdMs,
-    });
-    // 4. Write SOUL.md managed block
-    const soulPath = join(workspacePath, WORKSPACE_FILES.soul);
-    await updateManagedSection(soulPath, soulSectionContent, {
-        mode: 'block',
-        markers: SOUL_MARKERS,
-        coreVersion,
-        stalenessThresholdMs,
-    });
-    // 5. Write AGENTS.md managed block
-    const agentsPath = join(workspacePath, WORKSPACE_FILES.agents);
-    await updateManagedSection(agentsPath, agentsSectionContent, {
-        mode: 'block',
-        markers: AGENTS_MARKERS,
-        coreVersion,
-        stalenessThresholdMs,
-    });
-    // 6. Copy templates to config dir
-    copyTemplates(coreConfigDir);
-}
-
-/**
- * Timer-based orchestrator for managed content writing.
- *
- * @remarks
- * `ComponentWriter` manages a component's TOOLS.md section writes
- * and platform content maintenance (SOUL.md, AGENTS.md, Platform section)
- * on a configurable prime-interval timer cycle.
- */
-/**
- * Orchestrates managed content writing for a single Jeeves component.
- *
- * @remarks
- * Created via `createComponentWriter()`. Manages a timer that fires
- * at the component's prime-interval, calling `generateToolsContent()`
- * and `refreshPlatformContent()` on each cycle.
- */
-class ComponentWriter {
-    timer;
-    component;
-    configDir;
-    /** @internal */
-    constructor(component) {
-        this.component = component;
-        this.configDir = getComponentConfigDir(component.name);
-    }
-    /** The component's config directory path. */
-    get componentConfigDir() {
-        return this.configDir;
-    }
-    /** Whether the writer timer is currently running. */
-    get isRunning() {
-        return this.timer !== undefined;
-    }
-    /**
-     * Start the writer timer.
-     *
-     * @remarks
-     * Performs an immediate first write, then sets up the interval.
-     */
-    start() {
-        if (this.timer)
-            return;
-        // Fire immediately, then on interval
-        void this.cycle();
-        this.timer = setInterval(() => void this.cycle(), this.component.refreshIntervalSeconds * 1000);
-    }
-    /** Stop the writer timer. */
-    stop() {
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = undefined;
-        }
-    }
-    /**
-     * Execute a single write cycle.
-     *
-     * @remarks
-     * Calls `generateToolsContent()` and writes the component's
-     * TOOLS.md section via `updateManagedSection()`. Also calls
-     * `refreshPlatformContent()` for shared content maintenance.
-     */
-    async cycle() {
-        try {
-            const workspacePath = getWorkspacePath();
-            const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
-            // Write the component's TOOLS.md section
-            const toolsContent = this.component.generateToolsContent();
-            await updateManagedSection(toolsPath, toolsContent, {
-                mode: 'section',
-                sectionId: this.component.sectionId,
-                markers: TOOLS_MARKERS,
-                coreVersion: CORE_VERSION,
-            });
-            // Platform content maintenance: SOUL.md, AGENTS.md, Platform section
-            await refreshPlatformContent({
-                coreVersion: CORE_VERSION,
-                componentName: this.component.name,
-                componentVersion: this.component.version,
-                servicePackage: this.component.servicePackage,
-                pluginPackage: this.component.pluginPackage,
-            });
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${message}`);
-        }
-    }
-}
-
-/**
- * Creates a synchronous content accessor backed by an async data source.
- *
- * @remarks
- * Solves the sync/async gap in `JeevesComponent.generateToolsContent()`:
- * the interface is synchronous, but most components fetch live data from
- * their HTTP service. This utility returns a sync `() => string` that
- * serves the last successfully fetched value while kicking off a background
- * refresh on each call.
- *
- * First call returns `placeholder`. Subsequent calls return the last
- * successfully fetched content. If a refresh fails, the previous good
- * value is retained.
- *
- * @example
- * ```typescript
- * const getContent = createAsyncContentCache({
- *   fetch: async () => {
- *     const res = await fetch('http://127.0.0.1:1936/status');
- *     return formatWatcherStatus(await res.json());
- *   },
- *   placeholder: '> Initializing watcher status...',
- * });
- *
- * const writer = createComponentWriter({
- *   // ...
- *   generateToolsContent: getContent,
- * });
- * ```
- */
-/**
- * Creates a synchronous content accessor backed by an async data source.
- *
- * @param options - Cache configuration.
- * @returns A sync `() => string` suitable for `generateToolsContent`.
- */
-function createAsyncContentCache(options) {
-    const { fetch: fetchContent, placeholder = '> Initializing...', onError = (err) => {
-        console.warn('[jeeves] async content cache refresh failed:', err);
-    }, } = options;
-    let cached = placeholder;
-    let refreshing = false;
-    return () => {
-        if (!refreshing) {
-            refreshing = true;
-            fetchContent()
-                .then((content) => {
-                cached = content;
-            })
-                .catch(onError)
-                .finally(() => {
-                refreshing = false;
-            });
-        }
-        return cached;
-    };
-}
-
-/**
- * Factory function for creating a ComponentWriter.
+ * Content `.md` files (soul, agents, platform template) are inlined at
+ * build time via the rollup md plugin and imported as string literals.
+ * They do not use this function.
  *
- * @remarks
- * Validates the component descriptor at runtime:
- * - `refreshIntervalSeconds` must be a prime number
- * - `serviceCommands` and `pluginCommands` must be provided
- * - `name`, `version`, `sectionId` must be non-empty strings
- * - `generateToolsContent` must be a function
+ * @returns Absolute path to the content/ directory, or undefined.
  */
+function getContentDir() {
+    const pkgDir = packageDirectorySync({
+        cwd: fileURLToPath(import.meta.url),
+    });
+    if (!pkgDir)
+        return undefined;
+    const dir = join(pkgDir, 'content');
+    return existsSync(dir) ? dir : undefined;
+}
 /**
- * Check whether a number is prime.
+ * Copy templates from content/templates/ to the core config directory.
  *
- * @param n - Number to check.
- * @returns `true` if n is prime.
+ * @param coreConfigDir - Core config directory path.
  */
-function isPrime(n) {
-    if (n < 2)
-        return false;
-    if (n === 2)
-        return true;
-    if (n % 2 === 0)
-        return false;
-    for (let i = 3; i * i <= n; i += 2) {
-        if (n % i === 0)
-            return false;
+function copyTemplates(coreConfigDir) {
+    const contentDir = getContentDir();
+    if (!contentDir)
+        return;
+    const sourceDir = join(contentDir, 'templates');
+    if (!existsSync(sourceDir))
+        return;
+    const destDir = join(coreConfigDir, TEMPLATES_DIR);
+    if (!existsSync(destDir)) {
+        mkdirSync(destDir, { recursive: true });
     }
-    return true;
+    cpSync(sourceDir, destDir, { recursive: true });
 }
 /**
- * Validate a component descriptor at runtime.
+ * Render the Platform template using simple string replacement.
  *
- * @param input - The descriptor to validate (typed as unknown for runtime safety).
- * @throws Error if the descriptor is invalid.
+ * @param templatePath - Path to the templates directory.
+ * @returns Rendered platform content string.
  */
-function validateDescriptor(input) {
-    const component = input;
-    if (!component['name'] || typeof component['name'] !== 'string') {
-        throw new Error('JeevesComponent.name must be a non-empty string');
-    }
-    if (!component['version'] || typeof component['version'] !== 'string') {
-        throw new Error('JeevesComponent.version must be a non-empty string');
-    }
-    if (!component['sectionId'] || typeof component['sectionId'] !== 'string') {
-        throw new Error('JeevesComponent.sectionId must be a non-empty string');
-    }
-    if (typeof component['refreshIntervalSeconds'] !== 'number' ||
-        !isPrime(component['refreshIntervalSeconds'])) {
-        throw new Error(`JeevesComponent.refreshIntervalSeconds must be a prime number, got ${String(component['refreshIntervalSeconds'])}`);
-    }
-    if (typeof component['generateToolsContent'] !== 'function') {
-        throw new Error('JeevesComponent.generateToolsContent must be a function');
-    }
-    const svc = component['serviceCommands'];
-    if (!svc ||
-        typeof svc['stop'] !== 'function' ||
-        typeof svc['uninstall'] !== 'function' ||
-        typeof svc['status'] !== 'function') {
-        throw new Error('JeevesComponent.serviceCommands must provide stop, uninstall, and status functions');
-    }
-    const plg = component['pluginCommands'];
-    if (!plg || typeof plg['uninstall'] !== 'function') {
-        throw new Error('JeevesComponent.pluginCommands must provide an uninstall function');
+function renderPlatformTemplate(templatePath) {
+    const templatesAvailable = existsSync(templatePath);
+    let content = toolsPlatformTemplate;
+    // Handle <!-- IF_TEMPLATES --> ... <!-- ELSE_TEMPLATES --> ... <!-- ENDIF_TEMPLATES --> block
+    const ifRegex = /<!-- IF_TEMPLATES -->([\s\S]*?)<!-- ELSE_TEMPLATES -->([\s\S]*?)<!-- ENDIF_TEMPLATES -->/;
+    const match = ifRegex.exec(content);
+    if (match) {
+        content = content.replace(match[0], templatesAvailable ? match[1] : match[2]);
     }
+    // Replace __TEMPLATE_PATH__ with the actual path
+    content = content.replace(/__TEMPLATE_PATH__/g, templatePath);
+    return content;
 }
 /**
- * Create a ComponentWriter for a validated component descriptor.
+ * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
- * @param component - The component descriptor to validate and wrap.
- * @returns A new `ComponentWriter` instance.
- * @throws Error if the component descriptor is invalid.
+ * @param options - Configuration for the refresh cycle.
  */
-function createComponentWriter(component) {
-    validateDescriptor(component);
-    return new ComponentWriter(component);
+async function refreshPlatformContent(options) {
+    const { coreVersion, componentName, componentVersion, servicePackage, pluginPackage, stalenessThresholdMs, } = options;
+    const workspacePath = getWorkspacePath();
+    const coreConfigDir = getCoreConfigDir();
+    // 1. Write calling component's version entry
+    if (componentName) {
+        writeComponentVersion(coreConfigDir, {
+            componentName,
+            pluginVersion: componentVersion,
+            servicePackage,
+            pluginPackage,
+        });
+    }
+    // 2. Render Platform template
+    const templatePath = join(coreConfigDir, TEMPLATES_DIR);
+    const platformContent = renderPlatformTemplate(templatePath);
+    // 3. Write TOOLS.md Platform section
+    const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
+    await updateManagedSection(toolsPath, platformContent, {
+        mode: 'section',
+        sectionId: 'Platform',
+        markers: TOOLS_MARKERS,
+        coreVersion,
+        stalenessThresholdMs,
+    });
+    // 4. Write SOUL.md managed block
+    const soulPath = join(workspacePath, WORKSPACE_FILES.soul);
+    await updateManagedSection(soulPath, soulSectionContent, {
+        mode: 'block',
+        markers: SOUL_MARKERS,
+        coreVersion,
+        stalenessThresholdMs,
+    });
+    // 5. Write AGENTS.md managed block
+    const agentsPath = join(workspacePath, WORKSPACE_FILES.agents);
+    await updateManagedSection(agentsPath, agentsSectionContent, {
+        mode: 'block',
+        markers: AGENTS_MARKERS,
+        coreVersion,
+        stalenessThresholdMs,
+    });
+    // 6. Copy templates to config dir
+    copyTemplates(coreConfigDir);
 }
 
 /**
@@ -1506,12 +2960,22 @@ const serviceEntrySchema = z.object({
     /** Service URL (must be a valid URL). */
     url: z.string().url().describe('Service URL'),
 });
+/** Default bind address for all Jeeves services. */
+const DEFAULT_BIND_ADDRESS = '0.0.0.0';
 /** Zod schema for the core config file. */
 const coreConfigSchema = z.object({
     /** JSON Schema pointer for IDE autocomplete. */
     $schema: z.string().optional().describe('JSON Schema pointer'),
     /** Owner identity keys (canonical identityLinks references). */
     owners: z.array(z.string()).default([]).describe('Owner identity keys'),
+    /**
+     * Bind address for all Jeeves services. Default: `0.0.0.0` (all interfaces).
+     * Individual components can override in their own config.
+     */
+    bindAddress: z
+        .string()
+        .default(DEFAULT_BIND_ADDRESS)
+        .describe('Bind address for all Jeeves services'),
     /** Service URL overrides keyed by service name. */
     services: z
         .record(z.string(), serviceEntrySchema)
@@ -1548,6 +3012,11 @@ function generateJsonSchema() {
                 items: { type: 'string' },
                 default: [],
             },
+            bindAddress: {
+                type: 'string',
+                default: '0.0.0.0',
+                description: 'Bind address for all Jeeves services',
+            },
             services: {
                 type: 'object',
                 additionalProperties: {
@@ -1691,395 +3160,532 @@ function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
 }
 
 /**
- * Remove a managed section or entire managed block from a file.
- *
- * @remarks
- * Supports two modes:
- * - No `sectionId`: Remove the entire managed block (markers + content),
- *   leaving user content intact.
- * - With `sectionId`: Remove a specific H2 section from within the
- *   managed block. If it was the last section, remove the entire block.
- *
- * Provides file-level locking and atomic writes (temp file + rename).
- * Missing markers or nonexistent sections are no-ops (no error thrown).
- */
-/**
- * Remove a managed section or entire managed block from a file.
- *
- * @param filePath - Absolute path to the target file.
- * @param options - Optional section ID and custom markers.
- */
-async function removeManagedSection(filePath, options = {}) {
-    const { sectionId, markers = TOOLS_MARKERS } = options;
-    if (!existsSync(filePath))
-        return;
-    await withFileLock(filePath, () => {
-        const fileContent = readFileSync(filePath, 'utf-8');
-        const parsed = parseManaged(fileContent, markers);
-        if (!parsed.found)
-            return;
-        let newContent;
-        if (!sectionId) {
-            // Remove entire managed block
-            newContent = buildWithoutBlock(parsed.beforeContent, parsed.userContent);
-        }
-        else {
-            // Remove specific section
-            const remaining = parsed.sections.filter((s) => s.id !== sectionId);
-            if (remaining.length === parsed.sections.length) {
-                // Section not found — no-op
-                return;
-            }
-            if (remaining.length === 0) {
-                // Last section removed — remove entire block
-                newContent = buildWithoutBlock(parsed.beforeContent, parsed.userContent);
-            }
-            else {
-                // Rebuild managed block without the removed section
-                newContent = buildWithSections(parsed.beforeContent, parsed.userContent, remaining, markers, parsed.versionStamp?.version);
-            }
-        }
-        atomicWrite(filePath, newContent);
-    });
-}
-/** Build file content without the managed block. */
-function buildWithoutBlock(beforeContent, userContent) {
-    const parts = [];
-    if (beforeContent)
-        parts.push(beforeContent);
-    if (userContent) {
-        if (parts.length > 0)
-            parts.push('');
-        parts.push(userContent);
-    }
-    if (parts.length === 0)
-        return '';
-    return parts.join('\n') + '\n';
-}
-/** Rebuild file content with remaining sections. */
-function buildWithSections(beforeContent, userContent, sections, markers, coreVersion) {
-    const sorted = sortSectionsByOrder([...sections]);
-    const sectionText = sorted
-        .map((s) => `## ${s.id}\n\n${s.content}`)
-        .join('\n\n');
-    const managedBody = markers.title
-        ? `# ${markers.title}\n\n${sectionText}`
-        : sectionText;
-    const beginLine = formatBeginMarker(markers.begin, coreVersion ?? DEFAULT_CORE_VERSION);
-    const endLine = formatEndMarker(markers.end);
-    const parts = [];
-    if (beforeContent) {
-        parts.push(beforeContent);
-        parts.push('');
-    }
-    parts.push(beginLine);
-    parts.push('');
-    parts.push(managedBody);
-    parts.push('');
-    parts.push(endLine);
-    if (userContent) {
-        parts.push('');
-        parts.push(userContent);
-    }
-    parts.push('');
-    return parts.join('\n');
-}
-
-/**
- * One-shot content seeding used by the CLI install command.
- *
- * @remarks
- * Seeds SOUL.md, AGENTS.md, and TOOLS.md Platform section using the same
- * `updateManagedSection()` code path as writer cycles. Also copies templates
- * and creates core config with defaults if missing.
- */
-/**
- * Create the core config file with defaults if it doesn't already exist.
- *
- * @param coreConfigDir - Path to the core config directory.
- */
-function ensureCoreConfig(coreConfigDir) {
-    if (!existsSync(coreConfigDir)) {
-        mkdirSync(coreConfigDir, { recursive: true });
-    }
-    const configPath = join(coreConfigDir, CONFIG_FILE);
-    if (existsSync(configPath))
-        return;
-    const defaults = coreConfigSchema.parse({});
-    const configWithSchema = {
-        $schema: './config.schema.json',
-        ...defaults,
-    };
-    writeFileSync(configPath, JSON.stringify(configWithSchema, null, 2), 'utf-8');
-    // Write JSON schema file alongside config
-    const schemaPath = join(coreConfigDir, 'config.schema.json');
-    const jsonSchema = generateJsonSchema();
-    writeFileSync(schemaPath, JSON.stringify(jsonSchema, null, 2), 'utf-8');
-}
-/**
- * Seed all platform content into the workspace.
- *
- * @remarks
- * Uses the same `updateManagedSection()` code path as writer cycles.
- * Creates core config with defaults if missing. Copies templates.
- * Jaccard cleanup detection runs automatically via `updateManagedSection`.
- *
- * @param options - Seeding configuration.
- */
-async function seedContent(options) {
-    const coreConfigDir = getCoreConfigDir();
-    // Ensure core config exists
-    ensureCoreConfig(coreConfigDir);
-    // Seed content via the same code path as writer cycles
-    await refreshPlatformContent({
-        coreVersion: options.coreVersion,
-    });
-}
-
-/**
- * HTTP helpers for the OpenClaw plugin SDK.
+ * HEARTBEAT health orchestration.
  *
  * @remarks
- * Thin wrappers around `fetch` that throw on non-OK responses
- * and handle JSON serialisation/deserialisation.
+ * Determines the state of each platform component and generates
+ * HEARTBEAT entries with actionable alert text. Applies the dependency
+ * graph for alert suppression and auto-decline.
  */
+/** Derive the full service name from a component name. */
+function toServiceName(name) {
+    return `jeeves-${name}`;
+}
+/** Known dependency declarations for platform components. */
+const COMPONENT_DEPS = {
+    meta: { hard: ['watcher'], soft: [] },
+    server: { hard: [], soft: ['watcher', 'runner', 'meta'] },
+    runner: { hard: [], soft: [] },
+    watcher: { hard: [], soft: [] },
+};
+/** "Not installed" alert text for each platform component. Shared with seedContent. */
+const NOT_INSTALLED_ALERTS = {
+    runner: 'Not installed. The runner is the job execution engine — it runs scheduled scripts for data fetching, transformation, and maintenance. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-runner-openclaw install`.',
+    watcher: 'Not installed. The watcher indexes documents into a vector store for semantic search. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-watcher-openclaw install`.',
+    server: 'Not installed. The server provides a web UI for document browsing, rendering, sharing, and search. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-server-openclaw install`.',
+    meta: 'Not installed. Meta is the knowledge synthesis engine. Requires jeeves-watcher. Ask the user for consent to install. On approval, install watcher first if needed, then execute: `npx @karmaniverous/jeeves-meta-openclaw install`.',
+};
+/** Alert text generators by state. */
+const ALERT_TEXT = {
+    runner: {
+        not_installed: NOT_INSTALLED_ALERTS['runner'],
+        config_missing: (configRoot) => `Plugin installed but no configuration file found at \`${configRoot}/jeeves-runner/config.json\`. The plugin installer should have created a default config. Ask the user for consent to re-run the installer: \`npx @karmaniverous/jeeves-runner-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-runner service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-runner service start`. Verify via `GET http://127.0.0.1:1937/status`.',
+    },
+    watcher: {
+        not_installed: NOT_INSTALLED_ALERTS['watcher'],
+        deps_missing: 'Plugin installed but Qdrant is not responding on `http://127.0.0.1:6333`. Qdrant is the vector database required for semantic search. Ask the user for consent to set up Qdrant. Guide them through installation for their platform — Docker is simplest: `docker run -p 6333:6333 qdrant/qdrant`. Verify via `GET http://127.0.0.1:6333/collections`.',
+        config_missing: (configRoot) => `Plugin installed, Qdrant available, but config file missing or invalid at \`${configRoot}/jeeves-watcher/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-watcher-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-watcher service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-watcher service start`. Verify via `GET http://127.0.0.1:1936/status`.',
+    },
+    server: {
+        not_installed: NOT_INSTALLED_ALERTS['server'],
+        config_missing: (configRoot) => `Plugin installed but config file missing or invalid at \`${configRoot}/jeeves-server/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-server-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-server service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-server service start`. Verify via `GET http://127.0.0.1:1934/status`.',
+    },
+    meta: {
+        not_installed: NOT_INSTALLED_ALERTS['meta'],
+        deps_missing: 'Plugin installed but required dependency jeeves-watcher is not available. The watcher must be installed and running before meta can function. Do not attempt to set up meta until jeeves-watcher is healthy.',
+        config_missing: (configRoot) => `Plugin installed, watcher available, but config file missing or invalid at \`${configRoot}/jeeves-meta/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-meta-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-meta service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-meta service start`. Verify via `GET http://127.0.0.1:1938/status`.',
+    },
+};
+/** Default Qdrant URL for watcher dependency check. */
+const QDRANT_URL = 'http://127.0.0.1:6333';
+/** Health probe timeout in milliseconds. */
+const PROBE_TIMEOUT_MS$1 = 3000;
 /**
- * Fetch a URL with an automatic abort timeout.
+ * Check if Qdrant is reachable (watcher dependency).
  *
- * @param url - URL to fetch.
- * @param timeoutMs - Timeout in milliseconds before aborting.
- * @param init - Optional `fetch` init options.
- * @returns The fetch Response object.
+ * @returns True if Qdrant responds.
  */
-async function fetchWithTimeout(url, timeoutMs, init) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => {
-        controller.abort();
-    }, timeoutMs);
+async function isQdrantAvailable() {
     try {
-        return await fetch(url, { ...init, signal: controller.signal });
+        await fetchWithTimeout(`${QDRANT_URL}/collections`, PROBE_TIMEOUT_MS$1);
+        return true;
     }
-    finally {
-        clearTimeout(timeout);
+    catch {
+        return false;
     }
 }
 /**
- * Fetch JSON from a URL, throwing on non-OK responses.
+ * Determine the state of a single component.
+ *
+ * @param name - Component name.
+ * @param registry - Current component-versions.json contents.
+ * @param configRoot - Config root path.
+ * @param healthySet - Set of component names known to be healthy (for dep checks).
+ * @returns The component's state.
+ */
+async function determineComponentState(name, registry, configRoot, healthySet) {
+    // Not in registry = not installed
+    if (!(name in registry))
+        return 'not_installed';
+    // Check hard dependencies
+    const deps = COMPONENT_DEPS[name];
+    for (const hardDep of deps.hard) {
+        if (!healthySet.has(hardDep))
+            return 'deps_missing';
+    }
+    // Watcher-specific: check Qdrant
+    if (name === 'watcher' && !(await isQdrantAvailable())) {
+        return 'deps_missing';
+    }
+    // Check config file
+    const configPath = join(configRoot, `jeeves-${name}`, CONFIG_FILE);
+    if (!existsSync(configPath))
+        return 'config_missing';
+    // Fast path: probe HTTP health endpoint
+    try {
+        const url = getServiceUrl(name);
+        await fetchWithTimeout(`${url}/status`, PROBE_TIMEOUT_MS$1);
+        // Healthy — check for available updates
+        const entry = registry[name];
+        if (entry.pluginPackage && entry.pluginVersion) {
+            const componentConfigDir = join(configRoot, `jeeves-${name}`);
+            const latestVersion = checkRegistryVersion(entry.pluginPackage, componentConfigDir);
+            if (latestVersion && gt(latestVersion, entry.pluginVersion)) {
+                return 'update_available';
+            }
+        }
+        return 'healthy';
+    }
+    catch {
+        // Service not responding — classify sub-state
+        const serviceState = getServiceState(toServiceName(name));
+        if (serviceState === 'not_installed')
+            return 'service_not_installed';
+        if (serviceState === 'stopped')
+            return 'service_stopped';
+        // serviceState === 'running' but HTTP failed — still treat as stopped
+        return 'service_stopped';
+    }
+}
+/**
+ * Generate the alert text for a component in a given state.
  *
- * @param url - URL to fetch.
- * @param init - Optional `fetch` init options.
- * @returns Parsed JSON response body.
- * @throws Error with `HTTP {status}: {body}` message on non-OK responses.
+ * @param name - Component name.
+ * @param state - The component's state.
+ * @param configRoot - Config root path.
+ * @returns Alert text (list items), or empty string if healthy.
  */
-async function fetchJson(url, init) {
-    const res = await fetch(url, init);
-    if (!res.ok) {
-        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
+function generateAlertText(name, state, configRoot, registry) {
+    if (state === 'healthy')
+        return '';
+    // Update available — dynamic text with version info
+    if (state === 'update_available') {
+        const entry = registry[name];
+        const currentVersion = entry.pluginVersion ?? 'unknown';
+        const componentConfigDir = join(configRoot, `jeeves-${name}`);
+        const latestVersion = entry.pluginPackage
+            ? (checkRegistryVersion(entry.pluginPackage, componentConfigDir) ??
+                'unknown')
+            : 'unknown';
+        const installCmd = entry.pluginPackage
+            ? `\`npx ${entry.pluginPackage} install\``
+            : `\`npx @karmaniverous/jeeves-${name}-openclaw install\``;
+        return `- Update available: v${currentVersion} → v${latestVersion}. Ask the user for consent to update. On approval, execute: ${installCmd}.`;
     }
-    return res.json();
+    const componentAlerts = ALERT_TEXT[name];
+    const alertOrFn = componentAlerts[state];
+    if (!alertOrFn)
+        return '';
+    const text = typeof alertOrFn === 'function' ? alertOrFn(configRoot) : alertOrFn;
+    return `- ${text}`;
 }
 /**
- * POST JSON to a URL and return parsed response.
+ * Orchestrate HEARTBEAT entries for all platform components.
  *
- * @param url - URL to POST to.
- * @param body - Request body (will be JSON-stringified).
- * @returns Parsed JSON response body.
+ * @param options - Orchestration configuration.
+ * @returns Array of HeartbeatEntry for writeHeartbeatSection.
  */
-async function postJson(url, body) {
-    return fetchJson(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-    });
+async function orchestrateHeartbeat(options) {
+    const { coreConfigDir, configRoot, declinedNames } = options;
+    const registry = readComponentVersions(coreConfigDir);
+    // First pass: determine which components are healthy (for dep resolution)
+    const healthySet = new Set();
+    for (const name of PLATFORM_COMPONENTS) {
+        if (declinedNames.has(toServiceName(name)))
+            continue;
+        if (!(name in registry))
+            continue;
+        try {
+            const url = getServiceUrl(name);
+            await fetchWithTimeout(`${url}/status`, PROBE_TIMEOUT_MS$1);
+            healthySet.add(name);
+        }
+        catch {
+            // Not healthy — will be classified in second pass
+        }
+    }
+    // Second pass: generate entries
+    const entries = [];
+    for (const name of PLATFORM_COMPONENTS) {
+        const fullName = toServiceName(name);
+        // Declined
+        if (declinedNames.has(fullName)) {
+            // Auto-decline dependents of declined hard deps
+            entries.push({ name: fullName, declined: true, content: '' });
+            continue;
+        }
+        const state = await determineComponentState(name, registry, configRoot, healthySet);
+        // Auto-decline if hard dep is declined
+        const deps = COMPONENT_DEPS[name];
+        const hardDepDeclined = deps.hard.some((d) => declinedNames.has(toServiceName(d)));
+        if (hardDepDeclined) {
+            entries.push({ name: fullName, declined: true, content: '' });
+            continue;
+        }
+        const alertText = generateAlertText(name, state, configRoot, registry);
+        entries.push({ name: fullName, declined: false, content: alertText });
+    }
+    // Add soft-dep informational alerts for any healthy component with soft deps
+    for (const entry of entries) {
+        if (entry.declined || entry.content)
+            continue;
+        // Entry is healthy (no alert, not declined) — check for soft deps
+        const shortName = entry.name.replace(/^jeeves-/, '');
+        const deps = COMPONENT_DEPS[shortName];
+        if (!deps.soft.length)
+            continue;
+        const softAlerts = [];
+        for (const dep of deps.soft) {
+            const depFullName = toServiceName(dep);
+            if (declinedNames.has(depFullName))
+                continue;
+            if (!healthySet.has(dep)) {
+                softAlerts.push(`- ${entry.name} is running. Some features are unavailable because ${depFullName} is not installed/running.`);
+            }
+        }
+        if (softAlerts.length > 0) {
+            entry.content = softAlerts.join('\n');
+        }
+    }
+    return entries;
 }
 
 /**
- * OpenClaw configuration helpers for plugin CLI installers.
+ * Timer-based orchestrator for managed content writing.
  *
  * @remarks
- * Provides resolution of OpenClaw home directory and config file path,
- * plus idempotent config patching for plugin install/uninstall.
+ * `ComponentWriter` manages a component's TOOLS.md section writes
+ * and platform content maintenance (SOUL.md, AGENTS.md, Platform section)
+ * on a configurable prime-interval timer cycle.
  */
 /**
- * Resolve the OpenClaw home directory.
+ * Orchestrates managed content writing for a single Jeeves component.
  *
  * @remarks
- * Resolution order:
- * 1. `OPENCLAW_CONFIG` env var → dirname of the config file path
- * 2. `OPENCLAW_HOME` env var → resolved path
- * 3. Default: `~/.openclaw`
- *
- * @returns Absolute path to the OpenClaw home directory.
+ * Created via `createComponentWriter()`. Manages a timer that fires
+ * at the component's prime-interval, calling `generateToolsContent()`
+ * and `refreshPlatformContent()` on each cycle.
  */
-function resolveOpenClawHome() {
-    if (process.env.OPENCLAW_CONFIG) {
-        return dirname(resolve(process.env.OPENCLAW_CONFIG));
+class ComponentWriter {
+    timer;
+    component;
+    configDir;
+    /** @internal */
+    constructor(component) {
+        this.component = component;
+        this.configDir = getComponentConfigDir(component.name);
     }
-    if (process.env.OPENCLAW_HOME) {
-        return resolve(process.env.OPENCLAW_HOME);
+    /** The component's config directory path. */
+    get componentConfigDir() {
+        return this.configDir;
+    }
+    /** Whether the writer timer is currently running. */
+    get isRunning() {
+        return this.timer !== undefined;
+    }
+    /**
+     * Start the writer timer.
+     *
+     * @remarks
+     * Performs an immediate first write, then sets up the interval.
+     */
+    start() {
+        if (this.timer)
+            return;
+        // Fire immediately, then on interval
+        void this.cycle();
+        this.timer = setInterval(() => void this.cycle(), this.component.refreshIntervalSeconds * 1000);
+    }
+    /** Stop the writer timer. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /**
+     * Execute a single write cycle.
+     *
+     * @remarks
+     * Calls `generateToolsContent()` and writes the component's
+     * TOOLS.md section via `updateManagedSection()`. Also calls
+     * `refreshPlatformContent()` for shared content maintenance.
+     */
+    async cycle() {
+        try {
+            const workspacePath = getWorkspacePath();
+            const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
+            // Write the component's TOOLS.md section
+            const toolsContent = this.component.generateToolsContent();
+            await updateManagedSection(toolsPath, toolsContent, {
+                mode: 'section',
+                sectionId: this.component.sectionId,
+                markers: TOOLS_MARKERS,
+                coreVersion: CORE_VERSION,
+            });
+            // Platform content maintenance: SOUL.md, AGENTS.md, Platform section
+            await refreshPlatformContent({
+                coreVersion: CORE_VERSION,
+                componentName: this.component.name,
+                componentVersion: this.component.version,
+                servicePackage: this.component.servicePackage,
+                pluginPackage: this.component.pluginPackage,
+            });
+            // HEARTBEAT health orchestration
+            const heartbeatPath = join(workspacePath, WORKSPACE_FILES.heartbeat);
+            try {
+                const existingContent = (() => {
+                    try {
+                        return readFileSync(heartbeatPath, 'utf-8');
+                    }
+                    catch (err) {
+                        // Only swallow "file not found" — let permission errors propagate
+                        if (err instanceof Error &&
+                            'code' in err &&
+                            err.code === 'ENOENT') {
+                            return '';
+                        }
+                        throw err;
+                    }
+                })();
+                const parsed = parseHeartbeat(existingContent);
+                const declinedNames = new Set(parsed.entries.filter((e) => e.declined).map((e) => e.name));
+                const entries = await orchestrateHeartbeat({
+                    coreConfigDir: getCoreConfigDir(),
+                    configRoot: getConfigRoot(),
+                    declinedNames,
+                });
+                await writeHeartbeatSection(heartbeatPath, entries);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${msg}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${message}`);
+        }
     }
-    return join(homedir(), '.openclaw');
 }
+
 /**
- * Resolve the OpenClaw config file path.
+ * Creates a synchronous content accessor backed by an async data source.
  *
  * @remarks
- * If `OPENCLAW_CONFIG` is set, uses that directly.
- * Otherwise defaults to `{home}/openclaw.json`.
+ * Solves the sync/async gap in `JeevesComponentDescriptor.generateToolsContent()`:
+ * the interface is synchronous, but most components fetch live data from
+ * their HTTP service. This utility returns a sync `() => string` that
+ * serves the last successfully fetched value while kicking off a background
+ * refresh on each call.
  *
- * @param home - The OpenClaw home directory.
- * @returns Absolute path to the config file.
+ * First call returns `placeholder`. Subsequent calls return the last
+ * successfully fetched content. If a refresh fails, the previous good
+ * value is retained.
+ *
+ * @example
+ * ```typescript
+ * const getContent = createAsyncContentCache({
+ *   fetch: async () => {
+ *     const res = await fetch('http://127.0.0.1:1936/status');
+ *     return formatWatcherStatus(await res.json());
+ *   },
+ *   placeholder: '> Initializing watcher status...',
+ * });
+ *
+ * const writer = createComponentWriter({
+ *   // ...
+ *   generateToolsContent: getContent,
+ * });
+ * ```
  */
-function resolveConfigPath(home) {
-    if (process.env.OPENCLAW_CONFIG) {
-        return resolve(process.env.OPENCLAW_CONFIG);
-    }
-    return join(home, 'openclaw.json');
-}
 /**
- * Patch an allowlist array: add or remove the plugin ID.
+ * Creates a synchronous content accessor backed by an async data source.
  *
- * @returns A log message if a change was made, or undefined.
+ * @param options - Cache configuration.
+ * @returns A sync `() => string` suitable for `generateToolsContent`.
  */
-function patchAllowList(parent, key, label, pluginId, mode) {
-    if (mode === 'add') {
-        if (!Array.isArray(parent[key])) {
-            parent[key] = [pluginId];
-            return `Created ${label} with "${pluginId}"`;
-        }
-        const list = parent[key];
-        if (!list.includes(pluginId)) {
-            list.push(pluginId);
-            return `Added "${pluginId}" to ${label}`;
-        }
-    }
-    else {
-        if (!Array.isArray(parent[key]))
-            return undefined;
-        const list = parent[key];
-        const filtered = list.filter((id) => id !== pluginId);
-        if (filtered.length !== list.length) {
-            parent[key] = filtered;
-            return `Removed "${pluginId}" from ${label}`;
+function createAsyncContentCache(options) {
+    const { fetch: fetchContent, placeholder = '> Initializing...', onError = (err) => {
+        console.warn('[jeeves] async content cache refresh failed:', err);
+    }, } = options;
+    let cached = placeholder;
+    let refreshing = false;
+    return () => {
+        if (!refreshing) {
+            refreshing = true;
+            fetchContent()
+                .then((content) => {
+                cached = content;
+            })
+                .catch(onError)
+                .finally(() => {
+                refreshing = false;
+            });
         }
-    }
-    return undefined;
+        return cached;
+    };
+}
+
+/**
+ * Factory function for creating a ComponentWriter from a descriptor.
+ *
+ * @remarks
+ * Validates the descriptor via Zod schema and creates a ComponentWriter.
+ * Accepts `JeevesComponentDescriptor` (v0.5.0) only. The v0.4.0
+ * `JeevesComponent` interface is no longer accepted.
+ */
+/**
+ * Create a ComponentWriter for a validated component descriptor.
+ *
+ * @remarks
+ * The descriptor is validated via the Zod schema at runtime.
+ * This replaces the v0.4.0 `createComponentWriter(JeevesComponent)`.
+ *
+ * @param descriptor - The component descriptor to validate and wrap.
+ * @returns A new `ComponentWriter` instance.
+ * @throws ZodError if the descriptor is invalid.
+ */
+function createComponentWriter(descriptor) {
+    // Validate via Zod — throws ZodError with detailed messages on failure
+    jeevesComponentDescriptorSchema.parse(descriptor);
+    return new ComponentWriter(descriptor);
 }
+
 /**
- * Patch an OpenClaw config for plugin install or uninstall.
+ * Resolve the bind address for a Jeeves service.
  *
  * @remarks
- * Manages `plugins.entries.{pluginId}` and `tools.alsoAllow`.
- * Idempotent: adding twice produces no duplicates; removing when absent
- * produces no errors.
+ * Resolution order (four-tier):
+ * 1. Component config `bindAddress` field (if componentName provided)
+ * 2. Core config `bindAddress` field
+ * 3. `JEEVES_BIND_ADDRESS` environment variable
+ * 4. Default: `0.0.0.0`
+ */
+/**
+ * Resolve the bind address for a Jeeves service.
  *
- * @param config - The parsed OpenClaw config object (mutated in place).
- * @param pluginId - The plugin identifier.
- * @param mode - Whether to add or remove the plugin.
- * @returns Array of log messages describing changes made.
+ * @param componentName - Optional component name for component-specific override.
+ * @returns The resolved bind address.
  */
-function patchConfig(config, pluginId, mode) {
-    const messages = [];
-    // Ensure plugins section
-    if (!config.plugins || typeof config.plugins !== 'object') {
-        config.plugins = {};
-    }
-    const plugins = config.plugins;
-    // plugins.entries
-    if (!plugins.entries || typeof plugins.entries !== 'object') {
-        plugins.entries = {};
-    }
-    const entries = plugins.entries;
-    if (mode === 'add') {
-        if (!entries[pluginId]) {
-            entries[pluginId] = { enabled: true };
-            messages.push(`Added "${pluginId}" to plugins.entries`);
+function getBindAddress(componentName) {
+    // Tier 1: Component config (if provided)
+    if (componentName) {
+        const componentConfig = loadConfig(getComponentConfigDir(componentName));
+        if (componentConfig?.bindAddress) {
+            return componentConfig.bindAddress;
         }
     }
-    else if (pluginId in entries) {
-        Reflect.deleteProperty(entries, pluginId);
-        messages.push(`Removed "${pluginId}" from plugins.entries`);
+    // Tier 2: Core config
+    const coreConfig = loadConfig(getCoreConfigDir());
+    if (coreConfig?.bindAddress) {
+        return coreConfig.bindAddress;
     }
-    // tools.alsoAllow
-    if (!config.tools || typeof config.tools !== 'object') {
-        config.tools = {};
+    // Tier 3: Environment variable
+    const envValue = process.env['JEEVES_BIND_ADDRESS'];
+    if (envValue) {
+        return envValue;
     }
-    const tools = config.tools;
-    const toolAlsoAllow = patchAllowList(tools, 'alsoAllow', 'tools.alsoAllow', pluginId, mode);
-    if (toolAlsoAllow)
-        messages.push(toolAlsoAllow);
-    return messages;
+    // Tier 4: Default
+    return DEFAULT_BIND_ADDRESS;
 }
 
 /**
- * Plugin resolution helpers for the OpenClaw plugin SDK.
+ * One-shot content seeding used by the CLI install command.
  *
  * @remarks
- * Provides workspace path resolution and plugin setting resolution
- * with a standard three-step fallback chain:
- * plugin config → environment variable → default value.
+ * Seeds SOUL.md, AGENTS.md, and TOOLS.md Platform section using the same
+ * `updateManagedSection()` code path as writer cycles. Also copies templates
+ * and creates core config with defaults if missing.
  */
 /**
- * Resolve the workspace root from the OpenClaw plugin API.
- *
- * @remarks
- * Tries three sources in order:
- * 1. `api.config.agents.defaults.workspace` — explicit config
- * 2. `api.resolvePath('.')` — gateway-provided path resolver
- * 3. `process.cwd()` — last resort
+ * Create the core config file with defaults if it doesn't already exist.
  *
- * @param api - The plugin API object provided by the gateway.
- * @returns Absolute path to the workspace root.
+ * @param coreConfigDir - Path to the core config directory.
  */
-function resolveWorkspacePath(api) {
-    const configured = api.config?.agents?.defaults?.workspace;
-    if (typeof configured === 'string' && configured.trim()) {
-        return configured;
-    }
-    if (typeof api.resolvePath === 'function') {
-        return api.resolvePath('.');
+function ensureCoreConfig(coreConfigDir) {
+    if (!existsSync(coreConfigDir)) {
+        mkdirSync(coreConfigDir, { recursive: true });
     }
-    return process.cwd();
+    const configPath = join(coreConfigDir, CONFIG_FILE);
+    if (existsSync(configPath))
+        return;
+    const defaults = coreConfigSchema.parse({});
+    const configWithSchema = {
+        $schema: './config.schema.json',
+        ...defaults,
+    };
+    writeFileSync(configPath, JSON.stringify(configWithSchema, null, 2), 'utf-8');
+    // Write JSON schema file alongside config
+    const schemaPath = join(coreConfigDir, 'config.schema.json');
+    const jsonSchema = generateJsonSchema();
+    writeFileSync(schemaPath, JSON.stringify(jsonSchema, null, 2), 'utf-8');
 }
 /**
- * Resolve a plugin setting via the standard three-step fallback chain:
- * plugin config → environment variable → fallback value.
+ * Seed all platform content into the workspace.
  *
- * @param api - Plugin API object.
- * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
- * @param key - Config key within the plugin's config object.
- * @param envVar - Environment variable name.
- * @param fallback - Default value if neither source provides one.
- * @returns The resolved setting value.
- */
-function resolvePluginSetting(api, pluginId, key, envVar, fallback) {
-    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
-    if (typeof fromPlugin === 'string')
-        return fromPlugin;
-    const fromEnv = process.env[envVar];
-    if (fromEnv)
-        return fromEnv;
-    return fallback;
-}
-/**
- * Resolve an optional plugin setting via the two-step fallback chain:
- * plugin config → environment variable. Returns `undefined` if neither
- * source provides a value.
+ * @remarks
+ * Uses the same `updateManagedSection()` code path as writer cycles.
+ * Creates core config with defaults if missing. Copies templates.
+ * Writes initial HEARTBEAT with "Not installed" alerts for all platform components.
+ * Jaccard cleanup detection runs automatically via `updateManagedSection`.
  *
- * @param api - Plugin API object.
- * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
- * @param key - Config key within the plugin's config object.
- * @param envVar - Environment variable name.
- * @returns The resolved setting value, or `undefined`.
+ * @param options - Seeding configuration.
  */
-function resolveOptionalPluginSetting(api, pluginId, key, envVar) {
-    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
-    if (typeof fromPlugin === 'string')
-        return fromPlugin;
-    const fromEnv = process.env[envVar];
-    if (fromEnv)
-        return fromEnv;
-    return undefined;
+async function seedContent(options) {
+    const coreConfigDir = getCoreConfigDir();
+    // Ensure core config exists
+    ensureCoreConfig(coreConfigDir);
+    // Seed SOUL.md, AGENTS.md, TOOLS.md Platform section
+    await refreshPlatformContent({
+        coreVersion: options.coreVersion,
+    });
+    // Seed HEARTBEAT.md with "Not installed" alerts for all platform components
+    const heartbeatPath = join(getWorkspacePath(), WORKSPACE_FILES.heartbeat);
+    const entries = PLATFORM_COMPONENTS.map((name) => ({
+        name: toServiceName(name),
+        declined: false,
+        content: `- ${NOT_INSTALLED_ALERTS[name]}`,
+    }));
+    await writeHeartbeatSection(heartbeatPath, entries);
 }
 
 /**
@@ -2151,4 +3757,233 @@ function connectionFail(error, baseUrl, pluginId) {
     return fail(error);
 }
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_CORE_VERSION, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion };
+/**
+ * Factory for the standard plugin tool set.
+ *
+ * @remarks
+ * Produces four standard tools from a component descriptor:
+ * - `{name}_status` - Probe service health + version + uptime
+ * - `{name}_config` - Query running config with optional JSONPath
+ * - `{name}_config_apply` - Push config patch to running service
+ * - `{name}_service` - Service lifecycle management
+ *
+ * Components add domain-specific tools separately.
+ */
+/** Timeout for HTTP probes in milliseconds. */
+const PROBE_TIMEOUT_MS = 5000;
+/**
+ * Create the standard plugin tool set from a component descriptor.
+ *
+ * @param descriptor - The component descriptor.
+ * @returns Array of tool descriptors to register.
+ */
+function createPluginToolset(descriptor) {
+    const { name, defaultPort } = descriptor;
+    const baseUrl = `http://127.0.0.1:${String(defaultPort)}`;
+    const svcManager = createServiceManager(descriptor);
+    const statusTool = {
+        name: `${name}_status`,
+        description: `Get ${name} service health, version, and uptime.`,
+        parameters: {
+            type: 'object',
+            properties: {},
+        },
+        execute: async () => {
+            try {
+                const res = await fetchWithTimeout(`${baseUrl}/status`, PROBE_TIMEOUT_MS);
+                if (!res.ok) {
+                    return fail(`HTTP ${String(res.status)}: ${await res.text()}`);
+                }
+                const data = await res.json();
+                return ok(data);
+            }
+            catch (err) {
+                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
+            }
+        },
+    };
+    const configTool = {
+        name: `${name}_config`,
+        description: `Query ${name} running configuration. Optional JSONPath filter.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                path: {
+                    type: 'string',
+                    description: 'JSONPath expression (optional)',
+                },
+            },
+        },
+        execute: async (_id, params) => {
+            const path = params.path;
+            const qs = path ? `?path=${encodeURIComponent(path)}` : '';
+            try {
+                const result = await fetchJson(`${baseUrl}/config${qs}`);
+                return ok(result);
+            }
+            catch (err) {
+                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
+            }
+        },
+    };
+    const configApplyTool = {
+        name: `${name}_config_apply`,
+        description: `Apply a config patch to the running ${name} service.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                config: {
+                    type: 'object',
+                    description: 'Config patch to apply',
+                },
+            },
+            required: ['config'],
+        },
+        execute: async (_id, params) => {
+            const config = params.config;
+            if (!config) {
+                return fail('Missing required parameter: config');
+            }
+            try {
+                const result = await postJson(`${baseUrl}/config/apply`, config);
+                return ok(result);
+            }
+            catch (err) {
+                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
+            }
+        },
+    };
+    const serviceTool = {
+        name: `${name}_service`,
+        description: `Manage the ${name} system service. Actions: install, uninstall, start, stop, restart, status.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['install', 'uninstall', 'start', 'stop', 'restart', 'status'],
+                    description: 'Service action to perform',
+                },
+            },
+            required: ['action'],
+        },
+        execute: (_id, params) => {
+            const action = params.action;
+            const validActions = [
+                'install',
+                'uninstall',
+                'start',
+                'stop',
+                'restart',
+                'status',
+            ];
+            if (!validActions.includes(action)) {
+                return Promise.resolve(fail(`Invalid action: ${action}`));
+            }
+            try {
+                if (action === 'status') {
+                    const state = svcManager.status();
+                    return Promise.resolve(ok({ service: name, state }));
+                }
+                // Call the appropriate method
+                const methodMap = {
+                    install: () => {
+                        svcManager.install();
+                    },
+                    uninstall: () => {
+                        svcManager.uninstall();
+                    },
+                    start: () => {
+                        svcManager.start();
+                    },
+                    stop: () => {
+                        svcManager.stop();
+                    },
+                    restart: () => {
+                        svcManager.restart();
+                    },
+                };
+                methodMap[action]();
+                return Promise.resolve(ok({ service: name, action, success: true }));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return Promise.resolve(fail(`Service ${action} failed: ${msg}`));
+            }
+        },
+    };
+    return [statusTool, configTool, configApplyTool, serviceTool];
+}
+
+/**
+ * Plugin resolution helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Provides workspace path resolution and plugin setting resolution
+ * with a standard three-step fallback chain:
+ * plugin config → environment variable → default value.
+ */
+/**
+ * Resolve the workspace root from the OpenClaw plugin API.
+ *
+ * @remarks
+ * Tries three sources in order:
+ * 1. `api.config.agents.defaults.workspace` — explicit config
+ * 2. `api.resolvePath('.')` — gateway-provided path resolver
+ * 3. `process.cwd()` — last resort
+ *
+ * @param api - The plugin API object provided by the gateway.
+ * @returns Absolute path to the workspace root.
+ */
+function resolveWorkspacePath(api) {
+    const configured = api.config?.agents?.defaults?.workspace;
+    if (typeof configured === 'string' && configured.trim()) {
+        return configured;
+    }
+    if (typeof api.resolvePath === 'function') {
+        return api.resolvePath('.');
+    }
+    return process.cwd();
+}
+/**
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → fallback value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @param fallback - Default value if neither source provides one.
+ * @returns The resolved setting value.
+ */
+function resolvePluginSetting(api, pluginId, key, envVar, fallback) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return fallback;
+}
+/**
+ * Resolve an optional plugin setting via the two-step fallback chain:
+ * plugin config → environment variable. Returns `undefined` if neither
+ * source provides a value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @returns The resolved setting value, or `undefined`.
+ */
+function resolveOptionalPluginSetting(api, pluginId, key, envVar) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return undefined;
+}
+
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_BIND_ADDRESS, DEFAULT_CORE_VERSION, DEFAULT_PORTS, HEARTBEAT_HEADING, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, buildHeartbeatSection, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getBindAddress, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, needsCleanup, ok, orchestrateHeartbeat, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion, writeHeartbeatSection };