@karmaniverous/jeeves 0.5.3 → 0.5.4

package/dist/index.js

@@ -6,10 +6,10 @@ import { JSONPath } from 'jsonpath-plus';
 import { major, valid, gte, gt } from 'semver';
 import { z } from 'zod';
 import * as commander from 'commander';
-import { packageDirectorySync } from 'package-directory';
-import { homedir } from 'node:os';
 import cp, { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { packageDirectorySync } from 'package-directory';
 
 /**
  * Comment markers for managed content blocks.
@@ -183,14 +183,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.2` placeholder is replaced by
+ * The `0.5.3` 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.5.2';
+const CORE_VERSION = '0.5.3';
 
 /**
  * Workspace and config root initialization.
@@ -1566,969 +1566,1319 @@ function seedSkill(workspacePath) {
 }
 
 /**
- * OpenClaw configuration helpers for plugin CLI installers.
+ * Zod schema for the Jeeves component descriptor.
  *
  * @remarks
- * Provides resolution of OpenClaw home directory and config file path,
- * plus idempotent config patching for plugin install/uninstall.
+ * 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.
  */
 /**
- * Resolve the OpenClaw home directory.
+ * 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
- * Resolution order:
- * 1. `OPENCLAW_CONFIG` env var → dirname of the config file path
- * 2. `OPENCLAW_HOME` env var → resolved path
- * 3. Default: `~/.openclaw`
+ * 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({
+        input: [],
+        output: z.record(z.string(), 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({
+        input: [z.record(z.string(), z.unknown())],
+        output: z.promise(z.void()),
+    })
+        .optional(),
+    /**
+     * Custom merge function for config apply. Receives the existing config
+     * and the patch, returns the merged result. Optional — if omitted,
+     * the default deep-merge (object-recursive, array-replacing) is used.
+     *
+     * Use this to implement domain-specific merge strategies such as
+     * name-based array merging for inference rules.
+     */
+    customMerge: z
+        .function({
+        input: [
+            z.record(z.string(), z.unknown()),
+            z.record(z.string(), z.unknown()),
+        ],
+        output: z.record(z.string(), z.unknown()),
+    })
+        .optional(),
+    /**
+     * Returns command + args for launching the service process.
+     * Consumed by `service install`.
+     */
+    startCommand: z.function({
+        input: [z.string()],
+        output: z.array(z.string()),
+    }),
+    /** In-process service entry point for the CLI `start` command. */
+    run: z.function({
+        input: [z.string()],
+        output: z.promise(z.void()),
+    }),
+    /** 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({ input: [], output: z.string() }),
+    /** Component dependencies for HEARTBEAT alert suppression. */
+    dependencies: z
+        .object({
+        /** Components that must be healthy for this component to function. */
+        hard: z.array(z.string()),
+        /** Components that improve behavior but are not strictly required. */
+        soft: z.array(z.string()),
+    })
+        .optional(),
+    /** Extension point: add custom CLI commands to the service CLI. */
+    customCliCommands: z
+        .function({ input: [z.custom()], output: z.void() })
+        .optional(),
+    /** Extension point: return additional plugin tool descriptors. */
+    customPluginTools: z
+        .function({ input: [z.custom()], output: z.array(z.unknown()) })
+        .optional(),
+});
+/**
+ * Derive the effective service name from a descriptor.
  *
- * @returns Absolute path to the OpenClaw home directory.
+ * @param descriptor - The component descriptor.
+ * @returns The service name (explicit or derived from `jeeves-{name}`).
  */
-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');
+function getEffectiveServiceName(descriptor) {
+    return descriptor.serviceName ?? `jeeves-${descriptor.name}`;
 }
+
 /**
- * Resolve the OpenClaw config file path.
+ * Platform-aware service state detection.
  *
  * @remarks
- * If `OPENCLAW_CONFIG` is set, uses that directly.
- * Otherwise defaults to `{home}/openclaw.json`.
+ * 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 home - The OpenClaw home directory.
- * @returns Absolute path to the config file.
+ * @param serviceName - The service name (e.g., 'jeeves-runner').
+ * @returns The detected service state.
  */
-function resolveConfigPath(home) {
-    if (process.env.OPENCLAW_CONFIG) {
-        return resolve(process.env.OPENCLAW_CONFIG);
+function getServiceState(serviceName) {
+    switch (process.platform) {
+        case 'win32':
+            return getServiceStateWindows(serviceName);
+        case 'darwin':
+            return getServiceStateMacOS(serviceName);
+        default:
+            return getServiceStateLinux(serviceName);
     }
-    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.
+ * Windows: detect via NSSM.
+ * - Exit code 3 = service does not exist
+ * - "SERVICE_RUNNING" in output = running
+ * - Other output = stopped/paused
  */
-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}`;
-        }
+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';
     }
-    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}`;
-        }
+    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';
     }
-    return undefined;
 }
 /**
- * Patch an OpenClaw config for plugin install or uninstall.
- *
- * @remarks
- * Manages `plugins.entries.{pluginId}`, `plugins.installs.{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.
- * @param installRecord - Install provenance record (required when mode is 'add').
- * @returns Array of log messages describing changes made.
+ * 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 patchConfig(config, pluginId, mode, installRecord) {
-    const messages = [];
-    // Ensure plugins section
-    if (!config.plugins || typeof config.plugins !== 'object') {
-        config.plugins = {};
+function getServiceStateLinux(serviceName) {
+    try {
+        execSync(`systemctl --user is-enabled ${serviceName}.service`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
     }
-    const plugins = config.plugins;
-    // plugins.entries
-    if (!plugins.entries || typeof plugins.entries !== 'object') {
-        plugins.entries = {};
+    catch {
+        return 'not_installed';
     }
-    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`);
-    }
-    // plugins.installs
-    if (!plugins.installs || typeof plugins.installs !== 'object') {
-        plugins.installs = {};
-    }
-    const installs = plugins.installs;
-    if (mode === 'add' && installRecord) {
-        installs[pluginId] = {
-            source: 'path',
-            installPath: installRecord.installPath,
-            version: installRecord.version,
-            installedAt: installRecord.installedAt ?? new Date().toISOString(),
-        };
-        messages.push(`Wrote install record for "${pluginId}" to plugins.installs`);
-    }
-    else if (mode === 'remove' && pluginId in installs) {
-        Reflect.deleteProperty(installs, pluginId);
-        messages.push(`Removed install record for "${pluginId}" from plugins.installs`);
+    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';
     }
-    // tools.alsoAllow
-    if (!config.tools || typeof config.tools !== 'object') {
-        config.tools = {};
+    catch {
+        return 'stopped';
     }
-    const tools = config.tools;
-    const toolAlsoAllow = patchAllowList(tools, 'alsoAllow', 'tools.alsoAllow', pluginId, mode);
-    if (toolAlsoAllow)
-        messages.push(toolAlsoAllow);
-    return messages;
-}
-
-/**
- * Internal helpers for the plugin installer CLI.
- *
- * @module
- */
-/**
- * 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, recursively.
- *
- * @param srcDir - Source directory.
- * @param destDir - Destination directory.
+ * macOS: detect via launchctl.
+ * - `launchctl list {name}` exits non-zero = not installed
+ * - PID column is `-` or `0` = stopped
  */
-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);
+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';
         }
-        else {
-            copyFileSync(srcPath, destPath);
+        // 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');
+}
+
 /**
- * Read and parse a JSON file, returning an empty object if not found.
+ * Factory for platform-aware service lifecycle management.
  *
- * @param filePath - Path to the JSON file.
- * @returns Parsed object.
+ * @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.
  */
-function readJsonFile(filePath) {
+/** Exec helper that returns stdout. */
+function run$1(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 {
-        const raw = readFileSync(filePath, 'utf-8');
-        return JSON.parse(raw);
+        execSync(cmd, {
+            encoding: 'utf-8',
+            timeout: 30_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
     }
     catch {
-        return {};
+        return false;
     }
 }
-
 /**
- * Factory for the standard `-openclaw` plugin installer CLI.
+ * Resolve the effective service name from options and descriptor.
  *
- * @module
+ * @param descriptor - Component descriptor.
+ * @param options - Optional overrides.
+ * @returns The service name to use.
  */
+function resolveServiceName(descriptor, options) {
+    return options?.name ?? getEffectiveServiceName(descriptor);
+}
 /**
- * Create a standard plugin installer CLI program.
+ * Resolve the config path for install.
  *
- * @param options - Plugin CLI configuration.
- * @returns A Commander program ready for `.parse()`.
+ * @param descriptor - Component descriptor.
+ * @param options - Optional overrides.
+ * @returns Absolute config file path.
  */
-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);
-        // Copy package.json and openclaw.plugin.json from package root
-        const pkgRoot = packageDirectorySync({ cwd: distDir });
-        if (pkgRoot) {
-            for (const file of ['package.json', 'openclaw.plugin.json']) {
-                const src = join(pkgRoot, file);
-                if (existsSync(src)) {
-                    copyFileSync(src, join(extensionsDir, file));
-                }
-            }
-        }
-        console.log('  ✓ Dist files copied');
-        // 2. Patch openclaw.json
-        console.log('Patching OpenClaw config...');
-        const config = readJsonFile(configPath);
-        const pkgJsonPathForVersion = join(extensionsDir, 'package.json');
-        let pluginVersionForRecord;
-        try {
-            const pkgJsonForRecord = readJsonFile(pkgJsonPathForVersion);
-            pluginVersionForRecord =
-                typeof pkgJsonForRecord.version === 'string'
-                    ? pkgJsonForRecord.version
-                    : undefined;
-        }
-        catch {
-            // best-effort: version may not be available yet
-        }
-        const messages = patchConfig(config, pluginId, 'add', {
-            installPath: extensionsDir,
-            version: pluginVersionForRecord,
-        });
-        // 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}"`);
+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$1(`nssm install ${svcName} ${appPath}`);
+            if (appArgs) {
+                run$1(`nssm set ${svcName} AppParameters ${appArgs}`);
             }
-        }
-        writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
-        for (const msg of messages) {
-            console.log(`  ✓ ${msg}`);
-        }
-        // 4. Write initial HEARTBEAT entry and seed jeeves skill
-        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}`;
-                    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');
-                }
-                try {
-                    seedSkill(ws);
-                    console.log('  ✓ Jeeves skill seeded');
-                }
-                catch {
-                    console.log('  ⚠ Could not seed Jeeves skill');
-                }
-            }
-        }
-        catch {
-            // HEARTBEAT + skill seeding are best-effort during install
-        }
-        // 5. Write component version
-        try {
-            init({
-                workspacePath: opts.workspace ?? '.',
-                configRoot: opts.configRoot,
-            });
-            const pkgJsonPath = join(extensionsDir, 'package.json');
-            const pkgJson = readJsonFile(pkgJsonPath);
-            const pluginVersion = typeof pkgJson.version === 'string' ? pkgJson.version : undefined;
-            writeComponentVersion(getCoreConfigDir(), {
-                componentName,
-                pluginPackage,
-                pluginVersion,
-            });
-            console.log('  ✓ Component version written');
-        }
-        catch {
-            console.log('  ⚠ Could not write component version');
-        }
-        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 ws = opts.workspace;
-            if (ws) {
-                init({ workspacePath: ws, configRoot: opts.configRoot });
-                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 {
-            init({
-                workspacePath: opts.workspace ?? '.',
-                configRoot: opts.configRoot,
-            });
-            removeComponentVersion(getCoreConfigDir(), componentName);
-            console.log('  ✓ Component version entry removed');
-        }
-        catch {
-            console.log('  ⚠ Could not remove component version entry');
-        }
-        console.log();
-        console.log(`✅ ${pluginPackage} uninstalled.`);
+            run$1(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
+            run$1(`nssm set ${svcName} AppRotateFiles 1`);
+            run$1(`nssm set ${svcName} AppRotateBytes 1048576`);
+        },
+        uninstall(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`nssm stop ${svcName}`);
+            run$1(`nssm remove ${svcName} confirm`);
+        },
+        start(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run$1(`nssm start ${svcName}`);
+        },
+        stop(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run$1(`nssm stop ${svcName}`);
+        },
+        restart(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run$1(`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$1('systemctl --user daemon-reload');
+            run$1(`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$1(`systemctl --user start ${svcName}.service`);
+        },
+        stop(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run$1(`systemctl --user stop ${svcName}.service`);
+        },
+        restart(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run$1(`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$1(`launchctl load ${plistPath(svcName)}`);
+        },
+        stop(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            run$1(`launchctl unload ${plistPath(svcName)}`);
+        },
+        restart(options) {
+            const svcName = resolveServiceName(descriptor, options);
+            runQuiet(`launchctl unload ${plistPath(svcName)}`);
+            run$1(`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);
+    }
+}
+
+/**
+ * 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),
     });
-    return program;
 }
 
 /**
- * Zod schema for the Jeeves component descriptor.
+ * Tool result formatters for the OpenClaw plugin SDK.
  *
  * @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.
+ * Provides standardised helpers for building `ToolResult` objects:
+ * success, error, and connection-error variants.
  */
 /**
- * Check whether a number is prime.
+ * Format a successful tool result.
+ *
+ * @param data - Arbitrary data to return as JSON.
+ * @returns A `ToolResult` with JSON-stringified content.
+ */
+function ok(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Format an error tool result.
+ *
+ * @param error - Error instance, string, or other value.
+ * @returns A `ToolResult` with `isError: true`.
+ */
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: 'text', text: 'Error: ' + message }],
+        isError: true,
+    };
+}
+/**
+ * Format a connection error with actionable guidance.
+ *
+ * @remarks
+ * Detects `ECONNREFUSED`, `ENOTFOUND`, and `ETIMEDOUT` from
+ * `error.cause.code` and returns a user-friendly message referencing
+ * the plugin's `config.apiUrl` setting. Falls back to `fail()` for
+ * non-connection errors.
  *
- * @param n - Number to check.
- * @returns `true` if n is prime.
+ * @param error - Error instance (typically from `fetch`).
+ * @param baseUrl - The URL that was being contacted.
+ * @param pluginId - The plugin identifier for config guidance.
+ * @returns A `ToolResult` with `isError: true`.
  */
-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 connectionFail(error, baseUrl, pluginId) {
+    const cause = error instanceof Error ? error.cause : undefined;
+    const code = cause && typeof cause === 'object' && 'code' in cause
+        ? String(cause.code)
+        : '';
+    const isConnectionError = code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'ETIMEDOUT';
+    if (isConnectionError) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: [
+                        `Service not reachable at ${baseUrl}.`,
+                        'Either start the service, or if it runs on a different port,',
+                        `set plugins.entries.${pluginId}.config.apiUrl in openclaw.json.`,
+                    ].join('\n'),
+                },
+            ],
+            isError: true,
+        };
     }
-    return true;
+    return fail(error);
 }
+
 /**
- * Zod schema for the Jeeves component descriptor.
+ * Factory for the standard plugin tool set.
  *
  * @remarks
- * Single source of truth for what a component must provide.
- * Factories consume this descriptor to produce CLI commands,
- * plugin tools, and HTTP handlers.
+ * 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.
  */
-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({
-        input: [],
-        output: z.record(z.string(), 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({
-        input: [z.record(z.string(), z.unknown())],
-        output: z.promise(z.void()),
-    })
-        .optional(),
-    /**
-     * Custom merge function for config apply. Receives the existing config
-     * and the patch, returns the merged result. Optional — if omitted,
-     * the default deep-merge (object-recursive, array-replacing) is used.
-     *
-     * Use this to implement domain-specific merge strategies such as
-     * name-based array merging for inference rules.
-     */
-    customMerge: z
-        .function({
-        input: [
-            z.record(z.string(), z.unknown()),
-            z.record(z.string(), z.unknown()),
-        ],
-        output: z.record(z.string(), z.unknown()),
-    })
-        .optional(),
-    /**
-     * Returns command + args for launching the service process.
-     * Consumed by `service install`.
-     */
-    startCommand: z.function({
-        input: [z.string()],
-        output: z.array(z.string()),
-    }),
-    /** In-process service entry point for the CLI `start` command. */
-    run: z.function({
-        input: [z.string()],
-        output: z.promise(z.void()),
-    }),
-    /** 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({ input: [], output: z.string() }),
-    /** Component dependencies for HEARTBEAT alert suppression. */
-    dependencies: z
-        .object({
-        /** Components that must be healthy for this component to function. */
-        hard: z.array(z.string()),
-        /** Components that improve behavior but are not strictly required. */
-        soft: z.array(z.string()),
-    })
-        .optional(),
-    /** Extension point: add custom CLI commands to the service CLI. */
-    customCliCommands: z
-        .function({ input: [z.custom()], output: z.void() })
-        .optional(),
-    /** Extension point: return additional plugin tool descriptors. */
-    customPluginTools: z
-        .function({ input: [z.custom()], output: z.array(z.unknown()) })
-        .optional(),
-});
+/** Timeout for HTTP probes in milliseconds. */
+const PROBE_TIMEOUT_MS$1 = 5000;
 /**
- * Derive the effective service name from a descriptor.
+ * Create the standard plugin tool set from a component descriptor.
  *
  * @param descriptor - The component descriptor.
- * @returns The service name (explicit or derived from `jeeves-{name}`).
+ * @returns Array of tool descriptors to register.
  */
-function getEffectiveServiceName(descriptor) {
-    return descriptor.serviceName ?? `jeeves-${descriptor.name}`;
+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$1);
+                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`, {
+                    patch: 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) {
+                return Promise.resolve(fail(`Service ${action} failed: ${getErrorMessage(err)}`));
+            }
+        },
+    };
+    return [statusTool, configTool, configApplyTool, serviceTool];
 }
 
 /**
- * HTTP helpers for the OpenClaw plugin SDK.
+ * Resolve the package root directory from a module's `import.meta.url`.
  *
- * @remarks
- * Thin wrappers around `fetch` that throw on non-OK responses
- * and handle JSON serialisation/deserialisation.
+ * @module
  */
 /**
- * Fetch a URL with an automatic abort timeout.
+ * Get the nearest package root directory relative to the calling module URL.
  *
- * @param url - URL to fetch.
- * @param timeoutMs - Timeout in milliseconds before aborting.
- * @param init - Optional `fetch` init options.
- * @returns The fetch Response object.
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @returns The absolute package root path, or `undefined` on any error.
  */
-async function fetchWithTimeout(url, timeoutMs, init) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => {
-        controller.abort();
-    }, timeoutMs);
+function getPackageRoot(importMetaUrl) {
     try {
-        return await fetch(url, { ...init, signal: controller.signal });
+        return packageDirectorySync({ cwd: fileURLToPath(importMetaUrl) });
     }
-    finally {
-        clearTimeout(timeout);
+    catch {
+        return undefined;
     }
 }
+
 /**
- * Fetch JSON from a URL, throwing on non-OK responses.
+ * Resolve the version of a package from its `import.meta.url`.
  *
- * @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.
+ * @module
  */
-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.
+ * Get the version string from the nearest `package.json` relative to the
+ * caller's module URL.
  *
- * @param url - URL to POST to.
- * @param body - Request body (will be JSON-stringified).
- * @returns Parsed JSON response body.
+ * @param importMetaUrl - The `import.meta.url` of the calling module.
+ * @returns The `version` field, or `'unknown'` on any error.
  */
-async function postJson(url, body) {
-    return fetchJson(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-    });
+function getPackageVersion(importMetaUrl) {
+    try {
+        const pkgRoot = getPackageRoot(importMetaUrl);
+        if (!pkgRoot)
+            return 'unknown';
+        const raw = readFileSync(join(pkgRoot, 'package.json'), 'utf-8');
+        const pkg = JSON.parse(raw);
+        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
 }
 
 /**
- * Platform-aware service state detection.
+ * OpenClaw configuration helpers for plugin CLI installers.
  *
  * @remarks
- * Detects whether a system service is installed and running.
- * Delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ * Provides resolution of OpenClaw home directory and config file path,
+ * plus idempotent config patching for plugin install/uninstall.
  */
 /**
- * Detect the state of a system service by name.
+ * Resolve the OpenClaw home directory.
  *
- * @param serviceName - The service name (e.g., 'jeeves-runner').
- * @returns The detected service state.
+ * @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 getServiceState(serviceName) {
-    switch (process.platform) {
-        case 'win32':
-            return getServiceStateWindows(serviceName);
-        case 'darwin':
-            return getServiceStateMacOS(serviceName);
-        default:
-            return getServiceStateLinux(serviceName);
+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');
 }
 /**
- * Windows: detect via NSSM.
- * - Exit code 3 = service does not exist
- * - "SERVICE_RUNNING" in output = running
- * - Other output = stopped/paused
+ * 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 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';
+function resolveConfigPath(home) {
+    if (process.env.OPENCLAW_CONFIG) {
+        return resolve(process.env.OPENCLAW_CONFIG);
     }
+    return join(home, 'openclaw.json');
 }
 /**
- * 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
+ * Patch an allowlist array: add or remove the plugin ID.
+ *
+ * @returns A log message if a change was made, or undefined.
  */
-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';
+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}`;
+        }
     }
-    catch {
-        return 'stopped';
+    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;
 }
 /**
- * macOS: detect via launchctl.
- * - `launchctl list {name}` exits non-zero = not installed
- * - PID column is `-` or `0` = stopped
+ * Patch an OpenClaw config for plugin install or uninstall.
+ *
+ * @remarks
+ * Manages `plugins.entries.{pluginId}`, `plugins.installs.{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.
+ * @param installRecord - Install provenance record (required when mode is 'add').
+ * @returns Array of log messages describing changes made.
  */
-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';
+function patchConfig(config, pluginId, mode, installRecord) {
+    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`);
         }
-        // If we got output but can't parse it, assume stopped (service exists but state unclear)
-        return 'stopped';
     }
-    catch {
-        return 'not_installed';
+    else if (pluginId in entries) {
+        Reflect.deleteProperty(entries, pluginId);
+        messages.push(`Removed "${pluginId}" from plugins.entries`);
     }
-}
-/** 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');
+    // plugins.installs
+    if (!plugins.installs || typeof plugins.installs !== 'object') {
+        plugins.installs = {};
+    }
+    const installs = plugins.installs;
+    if (mode === 'add' && installRecord) {
+        installs[pluginId] = {
+            source: 'path',
+            installPath: installRecord.installPath,
+            version: installRecord.version,
+            installedAt: installRecord.installedAt ?? new Date().toISOString(),
+        };
+        messages.push(`Wrote install record for "${pluginId}" to plugins.installs`);
+    }
+    else if (mode === 'remove' && pluginId in installs) {
+        Reflect.deleteProperty(installs, pluginId);
+        messages.push(`Removed install record for "${pluginId}" from plugins.installs`);
+    }
+    // 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 platform-aware service lifecycle management.
+ * Plugin resolution helpers for the OpenClaw plugin SDK.
  *
  * @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.
+ * Provides workspace path resolution and plugin setting resolution
+ * with a standard three-step fallback chain:
+ * plugin config → environment variable → default value.
  */
-/** Exec helper that returns stdout. */
-function run$1(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;
+/**
+ * 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;
     }
-    catch {
-        return false;
+    if (typeof api.resolvePath === 'function') {
+        return api.resolvePath('.');
     }
+    return process.cwd();
 }
 /**
- * Resolve the effective service name from options and descriptor.
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → fallback value.
  *
- * @param descriptor - Component descriptor.
- * @param options - Optional overrides.
- * @returns The service name to use.
+ * @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 resolveServiceName(descriptor, options) {
-    return options?.name ?? getEffectiveServiceName(descriptor);
+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 the config path for install.
+ * Resolve an optional plugin setting via the two-step fallback chain:
+ * plugin config → environment variable. Returns `undefined` if neither
+ * source provides a value.
  *
- * @param descriptor - Component descriptor.
- * @param options - Optional overrides.
- * @returns Absolute config file path.
+ * @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 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$1(`nssm install ${svcName} ${appPath}`);
-            if (appArgs) {
-                run$1(`nssm set ${svcName} AppParameters ${appArgs}`);
-            }
-            run$1(`nssm set ${svcName} AppStdout ${join(homedir(), `${svcName}.log`)}`);
-            run$1(`nssm set ${svcName} AppStderr ${join(homedir(), `${svcName}.log`)}`);
-            run$1(`nssm set ${svcName} AppRotateFiles 1`);
-            run$1(`nssm set ${svcName} AppRotateBytes 1048576`);
-        },
-        uninstall(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            runQuiet(`nssm stop ${svcName}`);
-            run$1(`nssm remove ${svcName} confirm`);
-        },
-        start(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run$1(`nssm start ${svcName}`);
-        },
-        stop(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run$1(`nssm stop ${svcName}`);
-        },
-        restart(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run$1(`nssm restart ${svcName}`);
-        },
-        status(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            return getServiceState(svcName);
-        },
-    };
+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;
 }
+
 /**
- * Generate a systemd user unit file.
+ * Internal helpers for the plugin installer CLI.
  *
- * @param svcName - Service name.
- * @param cmdArgs - Command + args array.
- * @returns Unit file content.
+ * @module
  */
-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');
+/**
+ * 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$/, '');
 }
-/** 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$1('systemctl --user daemon-reload');
-            run$1(`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$1(`systemctl --user start ${svcName}.service`);
-        },
-        stop(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run$1(`systemctl --user stop ${svcName}.service`);
-        },
-        restart(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run$1(`systemctl --user restart ${svcName}.service`);
-        },
-        status(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            return getServiceState(svcName);
-        },
-    };
+/**
+ * Copy all files from source directory to destination, recursively.
+ *
+ * @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);
+        }
+    }
 }
 /**
- * Generate a macOS launchd plist.
+ * Read and parse a JSON file, returning an empty object if not found.
  *
- * @param svcName - Service label.
- * @param cmdArgs - Command + args array.
- * @returns Plist XML content.
+ * @param filePath - Path to the JSON file.
+ * @returns Parsed object.
  */
-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`);
+function readJsonFile(filePath) {
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
     }
-    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$1(`launchctl load ${plistPath(svcName)}`);
-        },
-        stop(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            run$1(`launchctl unload ${plistPath(svcName)}`);
-        },
-        restart(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            runQuiet(`launchctl unload ${plistPath(svcName)}`);
-            run$1(`launchctl load ${plistPath(svcName)}`);
-        },
-        status(options) {
-            const svcName = resolveServiceName(descriptor, options);
-            return getServiceState(svcName);
-        },
-    };
 }
+
 /**
- * Create a platform-aware service manager from a component descriptor.
+ * Factory for the standard `-openclaw` plugin installer CLI.
  *
- * @remarks
- * Detects the current platform and returns a `ServiceManager` that
- * delegates to NSSM (Windows), systemd (Linux), or launchd (macOS).
+ * @module
+ */
+/**
+ * Create a standard plugin installer CLI program.
  *
- * @param descriptor - The component descriptor.
- * @returns A `ServiceManager` for the current platform.
+ * @param options - Plugin CLI configuration.
+ * @returns A Commander program ready for `.parse()`.
  */
-function createServiceManager(descriptor) {
-    switch (process.platform) {
-        case 'win32':
-            return createWindowsManager(descriptor);
-        case 'darwin':
-            return createMacOSManager(descriptor);
-        default:
-            return createLinuxManager(descriptor);
+function createPluginCli(options) {
+    const { pluginId, importMetaUrl, pluginPackage, configRoot = 'j:/config', } = options;
+    const componentName = options.componentName ?? deriveComponentName(pluginId);
+    const pkgRoot = getPackageRoot(importMetaUrl);
+    if (!pkgRoot) {
+        throw new Error(`Unable to resolve package root for plugin CLI: ${pluginPackage}`);
     }
+    const distDir = join(pkgRoot, 'dist');
+    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);
+        if (!existsSync(distDir)) {
+            throw new Error(`Plugin dist directory not found: ${distDir}. Ensure the plugin is built before installing.`);
+        }
+        console.log(`Copying dist to ${extensionsDir}...`);
+        copyDistFiles(distDir, extensionsDir);
+        // Copy package.json and openclaw.plugin.json from package root
+        for (const file of ['package.json', 'openclaw.plugin.json']) {
+            const src = join(pkgRoot, file);
+            if (existsSync(src)) {
+                copyFileSync(src, join(extensionsDir, file));
+            }
+        }
+        console.log('  ✓ Dist files copied');
+        // 2. Patch openclaw.json
+        console.log('Patching OpenClaw config...');
+        const config = readJsonFile(configPath);
+        const pkgJsonPathForVersion = join(extensionsDir, 'package.json');
+        let pluginVersionForRecord;
+        try {
+            const pkgJsonForRecord = readJsonFile(pkgJsonPathForVersion);
+            pluginVersionForRecord =
+                typeof pkgJsonForRecord.version === 'string'
+                    ? pkgJsonForRecord.version
+                    : undefined;
+        }
+        catch {
+            // best-effort: version may not be available yet
+        }
+        const messages = patchConfig(config, pluginId, 'add', {
+            installPath: extensionsDir,
+            version: pluginVersionForRecord,
+        });
+        // 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 and seed jeeves skill
+        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}`;
+                    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');
+                }
+                try {
+                    seedSkill(ws);
+                    console.log('  ✓ Jeeves skill seeded');
+                }
+                catch {
+                    console.log('  ⚠ Could not seed Jeeves skill');
+                }
+            }
+        }
+        catch {
+            // HEARTBEAT + skill seeding are best-effort during install
+        }
+        // 5. Write component version
+        try {
+            init({
+                workspacePath: opts.workspace ?? '.',
+                configRoot: opts.configRoot,
+            });
+            const pkgJsonPath = join(extensionsDir, 'package.json');
+            const pkgJson = readJsonFile(pkgJsonPath);
+            const pluginVersion = typeof pkgJson.version === 'string' ? pkgJson.version : undefined;
+            writeComponentVersion(getCoreConfigDir(), {
+                componentName,
+                pluginPackage,
+                pluginVersion,
+            });
+            console.log('  ✓ Component version written');
+        }
+        catch {
+            console.log('  ⚠ Could not write component version');
+        }
+        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 ws = opts.workspace;
+            if (ws) {
+                init({ workspacePath: ws, configRoot: opts.configRoot });
+                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 {
+            init({
+                workspacePath: opts.workspace ?? '.',
+                configRoot: opts.configRoot,
+            });
+            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;
 }
 
 /**
@@ -3314,1624 +3664,1298 @@ When editing files outside the workspace, use the bridge pattern: copy in → ed
 
 ### Plugin Lifecycle
 
-\`\`\`bash
-# Platform bootstrap (content seeding)
-npx @karmaniverous/jeeves install
-
-# Component plugin install
-npx @karmaniverous/jeeves-{component}-openclaw install
-
-# Component plugin uninstall
-npx @karmaniverous/jeeves-{component}-openclaw uninstall
-
-# Platform teardown (remove managed sections)
-npx @karmaniverous/jeeves uninstall
-\`\`\`
-
-Never manually edit \`~/.openclaw/extensions/\`. Always use the CLI commands above.
-
-### Reference Templates
-
-<!-- IF_TEMPLATES -->
-Reference templates are available at \`__TEMPLATE_PATH__\`:
-
-| Template | Purpose |
-|----------|---------|
-| \`spec.md\` | Skeleton for new product specifications — all section headers, decision format, dev plan format |
-| \`spec-to-code-guide.md\` | The spec-to-code development practice — 7-stage iterative process, convergence loops, release gates |
-
-Read these templates when creating new specs, onboarding to new projects, or when asked about the development process.
-<!-- ELSE_TEMPLATES -->
-> Reference templates not yet installed. Run \`npx @karmaniverous/jeeves install\` to seed templates.
-<!-- ENDIF_TEMPLATES -->
-`;
-
-/**
- * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
- *
- * @remarks
- * Called by `ComponentWriter` on each cycle. Not directly exposed to components.
- * Reads content files from the package's `content/` directory, renders the
- * Platform template with live data, and writes managed sections using
- * `updateManagedSection`.
- */
-/**
- * Resolve the package's content directory for template file copying.
- *
- * @remarks
- * Templates are actual files that need to be copied to the config directory.
- * This only works when core is in `node_modules` (CLI install, service).
- * 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);
-}
-
-/**
- * Cleanup-session escalation for managed files with orphaned duplicated content.
- *
- * @remarks
- * When a managed file contains the cleanup flag, the writer can ask the
- * OpenClaw gateway to spawn a background session to remove orphaned content.
- * The request is best-effort: accepted requests return `true`; any transport
- * or HTTP failure returns `false` so the file warning remains the fallback.
- */
-/** Timeout for cleanup-session spawn requests. */
-const CLEANUP_REQUEST_TIMEOUT_MS = 5_000;
-/**
- * Build the cleanup task prompt sent to the gateway session API.
- *
- * @param filePath - Managed file requiring cleanup.
- * @param markerIdentity - Marker identity for the file.
- * @returns Cleanup instructions for the spawned session.
- */
-function buildCleanupTask(filePath, markerIdentity) {
-    return [
-        `Clean up orphaned managed content in ${filePath}.`,
-        `The file uses ${markerIdentity} managed comment markers.`,
-        'Review content outside the managed block and remove only duplicated managed content.',
-        'Preserve any unique user-authored content outside the managed block.',
-        'Do not modify content inside the managed block unless required to preserve valid marker structure.',
-    ].join(' ');
-}
-/**
- * Request a cleanup session from the OpenClaw gateway.
- *
- * @remarks
- * Fire-and-forget. A 200-class response means the request was accepted.
- * Any HTTP or transport failure returns `false` so the file-level cleanup
- * warning remains the only signal.
- *
- * @param options - Cleanup request configuration.
- * @returns Whether the gateway accepted the cleanup request.
- */
-async function requestCleanupSession(options) {
-    const { gatewayUrl, filePath, markerIdentity } = options;
-    const url = `${gatewayUrl.replace(/\/$/, '')}/sessions/spawn`;
-    const label = `cleanup:${basename(filePath)}`;
-    const body = {
-        task: buildCleanupTask(filePath, markerIdentity),
-        label,
-    };
-    try {
-        const response = await fetchWithTimeout(url, CLEANUP_REQUEST_TIMEOUT_MS, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(body),
-        });
-        return response.ok;
-    }
-    catch {
-        return false;
-    }
-}
+\`\`\`bash
+# Platform bootstrap (content seeding)
+npx @karmaniverous/jeeves install
 
-/**
- * Cleanup flag scanning extracted from ComponentWriter.cycle().
- *
- * @remarks
- * After writing managed files, scans each for the cleanup flag and
- * fires a best-effort escalation request when a gateway URL is configured.
- * Uses a `pendingCleanups` set to deduplicate in-flight requests.
- */
-/**
- * Scan managed files for the cleanup flag and escalate when detected.
- *
- * @param targets - Managed files to scan.
- * @param gatewayUrl - Gateway URL for session spawn.
- * @param pendingCleanups - Set tracking in-flight requests (mutated).
- */
-function scanAndEscalateCleanup(targets, gatewayUrl, pendingCleanups) {
-    for (const target of targets) {
-        try {
-            if (pendingCleanups.has(target.filePath))
-                continue;
-            const fileContent = readFileSync(target.filePath, 'utf-8');
-            if (fileContent.includes(CLEANUP_FLAG)) {
-                pendingCleanups.add(target.filePath);
-                void requestCleanupSession({
-                    gatewayUrl,
-                    filePath: target.filePath,
-                    markerIdentity: target.markerIdentity,
-                }).finally(() => {
-                    pendingCleanups.delete(target.filePath);
-                });
-            }
-        }
-        catch {
-            // Best-effort: don't fail the cycle for escalation issues.
-        }
-    }
-}
+# Component plugin install
+npx @karmaniverous/jeeves-{component}-openclaw install
 
-/**
- * Memory budget accounting and staleness detection for MEMORY.md.
- *
- * @remarks
- * Scans MEMORY.md for ISO date patterns in H2/H3 headings and bullet items.
- * Reports character count against a configured budget, warning threshold state,
- * and stale section candidates. Does not auto-delete: review remains
- * human- or agent-mediated (Decision 42).
- */
-/** ISO date pattern: YYYY-MM-DD. */
-const ISO_DATE_RE = /\b(\d{4}-\d{2}-\d{2})\b/g;
-/** H2 heading pattern used to split sections. */
-const H2_RE = /^## /m;
-/**
- * Extract the most recent ISO date from a string.
- *
- * @param text - Text to scan for dates.
- * @returns The most recent date found, or undefined.
- */
-function extractMostRecentDate(text) {
-    const matches = text.match(ISO_DATE_RE);
-    if (!matches)
-        return undefined;
-    let latest;
-    for (const match of matches) {
-        const d = new Date(match + 'T00:00:00Z');
-        if (!Number.isNaN(d.getTime())) {
-            if (!latest || d > latest)
-                latest = d;
-        }
-    }
-    return latest;
-}
-/**
- * Analyze MEMORY.md for budget and staleness.
- *
- * @param options - Analysis configuration.
- * @returns Memory hygiene result.
- */
-function analyzeMemory(options) {
-    const { workspacePath, budget, warningThreshold, staleDays } = options;
-    const memoryPath = join(workspacePath, WORKSPACE_FILES.memory);
-    if (!existsSync(memoryPath)) {
-        return {
-            exists: false,
-            charCount: 0,
-            budget,
-            usage: 0,
-            warning: false,
-            overBudget: false,
-            staleCandidates: 0,
-            staleSectionNames: [],
-        };
-    }
-    const content = readFileSync(memoryPath, 'utf-8');
-    const charCount = content.length;
-    const usage = budget > 0 ? charCount / budget : charCount > 0 ? Infinity : 0;
-    const warning = usage >= warningThreshold;
-    const overBudget = usage > 1;
-    // Split into H2 sections and scan for staleness
-    const sections = content.split(H2_RE).slice(1); // skip content before first H2
-    const now = Date.now();
-    const thresholdMs = staleDays * 24 * 60 * 60 * 1000;
-    const staleSectionNames = [];
-    for (const section of sections) {
-        const sectionName = section.split('\n')[0]?.trim() ?? '';
-        const recentDate = extractMostRecentDate(section);
-        // Sections without dates are evergreen — never flagged (Decision 47)
-        if (!recentDate)
-            continue;
-        if (now - recentDate.getTime() > thresholdMs) {
-            staleSectionNames.push(sectionName);
-        }
-    }
-    return {
-        exists: true,
-        charCount,
-        budget,
-        usage,
-        warning,
-        overBudget,
-        staleCandidates: staleSectionNames.length,
-        staleSectionNames,
-    };
-}
+# Component plugin uninstall
+npx @karmaniverous/jeeves-{component}-openclaw uninstall
+
+# Platform teardown (remove managed sections)
+npx @karmaniverous/jeeves uninstall
+\`\`\`
+
+Never manually edit \`~/.openclaw/extensions/\`. Always use the CLI commands above.
+
+### Reference Templates
+
+<!-- IF_TEMPLATES -->
+Reference templates are available at \`__TEMPLATE_PATH__\`:
+
+| Template | Purpose |
+|----------|---------|
+| \`spec.md\` | Skeleton for new product specifications — all section headers, decision format, dev plan format |
+| \`spec-to-code-guide.md\` | The spec-to-code development practice — 7-stage iterative process, convergence loops, release gates |
+
+Read these templates when creating new specs, onboarding to new projects, or when asked about the development process.
+<!-- ELSE_TEMPLATES -->
+> Reference templates not yet installed. Run \`npx @karmaniverous/jeeves install\` to seed templates.
+<!-- ENDIF_TEMPLATES -->
+`;
 
 /**
- * HEARTBEAT integration for memory hygiene.
+ * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
  * @remarks
- * Calls `analyzeMemory()` and converts the result into a `HeartbeatEntry`
- * suitable for inclusion in the HEARTBEAT.md platform status section.
- * Returns `undefined` when MEMORY.md is healthy (no alert needed).
- *
- * Uses the `## MEMORY.md` heading (Decision 50) to distinguish memory
- * alerts from component alerts (`## jeeves-{name}`).
- */
-/** The HEARTBEAT heading name for memory alerts. */
-const MEMORY_HEARTBEAT_NAME = 'MEMORY.md';
-/**
- * Check memory health and return a HEARTBEAT entry if unhealthy.
- *
- * @param options - Memory hygiene options (workspacePath, budget, etc.).
- * @returns A `HeartbeatEntry` when memory needs attention, `undefined` when healthy.
+ * Called by `ComponentWriter` on each cycle. Not directly exposed to components.
+ * Reads content files from the package's `content/` directory, renders the
+ * Platform template with live data, and writes managed sections using
+ * `updateManagedSection`.
  */
-function checkMemoryHealth(options) {
-    const result = analyzeMemory(options);
-    if (!result.exists)
-        return undefined;
-    if (!result.warning && result.staleCandidates === 0)
-        return undefined;
-    const lines = [];
-    if (result.warning) {
-        const pct = Math.round(result.usage * 100);
-        lines.push(`- Budget: ${result.charCount.toLocaleString()} / ${result.budget.toLocaleString()} chars (${String(pct)}%).${result.overBudget ? ' **Over budget.**' : ' Consider reviewing.'}`);
-    }
-    if (result.staleCandidates > 0) {
-        lines.push(`- ${String(result.staleCandidates)} stale section${result.staleCandidates === 1 ? '' : 's'}: ${result.staleSectionNames.join(', ')}`);
-    }
-    return {
-        name: MEMORY_HEARTBEAT_NAME,
-        declined: false,
-        content: lines.join('\n'),
-    };
-}
-
 /**
- * HEARTBEAT integration for workspace file size monitoring.
+ * Resolve the package's content directory for template file copying.
  *
  * @remarks
- * Checks all injected workspace files (AGENTS.md, SOUL.md, TOOLS.md,
- * MEMORY.md, USER.md) against the OpenClaw ~20,000-char injection limit.
- * Files exceeding the warning threshold generate HEARTBEAT entries with
- * trimming guidance.
- */
-/** Workspace files monitored for size budget. */
-const WORKSPACE_SIZE_FILES = [
-    'AGENTS.md',
-    'SOUL.md',
-    'TOOLS.md',
-    'MEMORY.md',
-    'USER.md',
-];
-/** Trimming guidance lines emitted in HEARTBEAT entries. */
-const TRIMMING_GUIDANCE = [
-    '  1. Move domain-specific content to a local skill',
-    '  2. Extract reference material to companion files with a pointer',
-    '  3. Summarize verbose instructions',
-    '  4. Remove stale content',
-].join('\n');
-/**
- * Check all workspace files against the character budget.
+ * Templates are actual files that need to be copied to the config directory.
+ * This only works when core is in `node_modules` (CLI install, service).
+ * When bundled into a consumer plugin, returns undefined and template
+ * copying is skipped (templates are seeded by `jeeves install`, not plugins).
  *
- * @param options - Health check options.
- * @returns Array of results, one per checked file (skips non-existent files
- *   unless they breach the budget, which they cannot by definition).
- */
-function checkWorkspaceFileHealth(options) {
-    const { workspacePath, budgetChars = 20_000, warningThreshold = 0.8, } = options;
-    return WORKSPACE_SIZE_FILES.map((file) => {
-        const filePath = join(workspacePath, file);
-        if (!existsSync(filePath)) {
-            return {
-                file,
-                exists: false,
-                charCount: 0,
-                budget: budgetChars,
-                usage: 0,
-                warning: false,
-                overBudget: false,
-            };
-        }
-        const content = readFileSync(filePath, 'utf-8');
-        const charCount = content.length;
-        const usage = charCount / budgetChars;
-        return {
-            file,
-            exists: true,
-            charCount,
-            budget: budgetChars,
-            usage,
-            warning: usage >= warningThreshold,
-            overBudget: charCount > budgetChars,
-        };
-    });
-}
-/**
- * Convert workspace file health results into HEARTBEAT entries.
+ * 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.
  *
- * @param results - Results from `checkWorkspaceFileHealth`.
- * @returns Array of `HeartbeatEntry` objects for files that exceed the
- *   warning threshold.
+ * @returns Absolute path to the content/ directory, or undefined.
  */
-function workspaceFileHealthEntries(results) {
-    return results
-        .filter((r) => r.exists && r.warning)
-        .map((r) => {
-        const pct = Math.round(r.usage * 100);
-        const overBudgetNote = r.overBudget ? ' **Over budget.**' : '';
-        const content = [
-            `- Budget: ${r.charCount.toLocaleString()} / ${r.budget.toLocaleString()} chars (${String(pct)}%).${overBudgetNote} Trim to stay under the OpenClaw injection limit.`,
-            `- Suggested trimming priority:\n${TRIMMING_GUIDANCE}`,
-        ].join('\n');
-        return {
-            name: r.file,
-            declined: false,
-            content,
-        };
+function getContentDir() {
+    const pkgDir = packageDirectorySync({
+        cwd: fileURLToPath(import.meta.url),
     });
+    if (!pkgDir)
+        return undefined;
+    const dir = join(pkgDir, 'content');
+    return existsSync(dir) ? dir : undefined;
 }
-
 /**
- * Core configuration schema and resolution.
+ * Copy templates from content/templates/ to the core config directory.
  *
- * @remarks
- * Core config lives at `{configRoot}/jeeves-core/config.json`.
- * Config resolution order:
- * 1. Component's own config file
- * 2. Core config file
- * 3. Hardcoded library defaults
+ * @param coreConfigDir - Core config directory path.
  */
-/** Zod schema for a service entry in core config. */
-const serviceEntrySchema = z.object({
-    /** Service URL (must be a valid URL). */
-    url: z.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)
-        .default({})
-        .describe('Service URL overrides'),
-    /** Registry cache configuration. */
-    registryCache: z
-        .object({
-        /** Cache TTL in seconds for npm registry queries. */
-        ttlSeconds: z
-            .number()
-            .int()
-            .positive()
-            .default(3600)
-            .describe('Cache TTL in seconds'),
-    })
-        .prefault({})
-        .describe('Registry cache settings'),
-});
+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 });
+}
 /**
- * Generate a JSON Schema from the Zod schema for `$schema` pointer support.
+ * Render the Platform template using simple string replacement.
  *
- * @returns A JSON Schema object.
+ * @param templatePath - Path to the templates directory.
+ * @returns Rendered platform content string.
  */
-function generateJsonSchema() {
-    return {
-        $schema: 'http://json-schema.org/draft-07/schema#',
-        title: 'Jeeves Core Configuration',
-        type: 'object',
-        properties: {
-            $schema: { type: 'string' },
-            owners: {
-                type: 'array',
-                items: { type: 'string' },
-                default: [],
-            },
-            bindAddress: {
-                type: 'string',
-                default: '0.0.0.0',
-                description: 'Bind address for all Jeeves services',
-            },
-            services: {
-                type: 'object',
-                additionalProperties: {
-                    type: 'object',
-                    properties: {
-                        url: { type: 'string', format: 'uri' },
-                    },
-                    required: ['url'],
-                },
-                default: {},
-            },
-            registryCache: {
-                type: 'object',
-                properties: {
-                    ttlSeconds: {
-                        type: 'integer',
-                        minimum: 1,
-                        default: 3600,
-                    },
-                },
-                default: {},
-            },
-        },
-    };
+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;
 }
 /**
- * Load and parse a config file, returning undefined if missing or invalid.
+ * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
- * @param configDir - Directory containing config.json.
- * @returns Parsed config or undefined.
+ * @param options - Configuration for the refresh cycle.
  */
-function loadConfig(configDir) {
-    const configPath = join(configDir, CONFIG_FILE);
-    if (!existsSync(configPath))
-        return undefined;
-    try {
-        const raw = readFileSync(configPath, 'utf-8');
-        const parsed = JSON.parse(raw);
-        return coreConfigSchema.parse(parsed);
-    }
-    catch {
-        return undefined;
+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);
 }
 
 /**
- * Service URL resolution.
+ * Cleanup-session escalation for managed files with orphaned duplicated content.
  *
  * @remarks
- * Resolves the URL for a named Jeeves service using the following
- * resolution order:
- * 1. Consumer's own component config
- * 2. Core config (`{configRoot}/jeeves-core/config.json`)
- * 3. Default port constants
+ * When a managed file contains the cleanup flag, the writer can ask the
+ * OpenClaw gateway to spawn a background session to remove orphaned content.
+ * The request is best-effort: accepted requests return `true`; any transport
+ * or HTTP failure returns `false` so the file warning remains the fallback.
  */
+/** Timeout for cleanup-session spawn requests. */
+const CLEANUP_REQUEST_TIMEOUT_MS = 5_000;
 /**
- * Resolve the URL for a named Jeeves service.
+ * Build the cleanup task prompt sent to the gateway session API.
  *
- * @param serviceName - The service name (e.g., 'watcher', 'runner').
- * @param consumerName - Optional consumer component name for config override.
- * @returns The resolved service URL.
- * @throws Error if `init()` has not been called or the service is unknown.
+ * @param filePath - Managed file requiring cleanup.
+ * @param markerIdentity - Marker identity for the file.
+ * @returns Cleanup instructions for the spawned session.
  */
-function getServiceUrl(serviceName, consumerName) {
-    // 1. Check consumer's own config
-    if (consumerName) {
-        const consumerDir = getComponentConfigDir(consumerName);
-        const consumerConfig = loadConfig(consumerDir);
-        const consumerUrl = consumerConfig?.services[serviceName]?.url;
-        if (consumerUrl)
-            return consumerUrl;
+function buildCleanupTask(filePath, markerIdentity) {
+    return [
+        `Clean up orphaned managed content in ${filePath}.`,
+        `The file uses ${markerIdentity} managed comment markers.`,
+        'Review content outside the managed block and remove only duplicated managed content.',
+        'Preserve any unique user-authored content outside the managed block.',
+        'Do not modify content inside the managed block unless required to preserve valid marker structure.',
+    ].join(' ');
+}
+/**
+ * Request a cleanup session from the OpenClaw gateway.
+ *
+ * @remarks
+ * Fire-and-forget. A 200-class response means the request was accepted.
+ * Any HTTP or transport failure returns `false` so the file-level cleanup
+ * warning remains the only signal.
+ *
+ * @param options - Cleanup request configuration.
+ * @returns Whether the gateway accepted the cleanup request.
+ */
+async function requestCleanupSession(options) {
+    const { gatewayUrl, filePath, markerIdentity } = options;
+    const url = `${gatewayUrl.replace(/\/$/, '')}/sessions/spawn`;
+    const label = `cleanup:${basename(filePath)}`;
+    const body = {
+        task: buildCleanupTask(filePath, markerIdentity),
+        label,
+    };
+    try {
+        const response = await fetchWithTimeout(url, CLEANUP_REQUEST_TIMEOUT_MS, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        return response.ok;
     }
-    // 2. Check core config
-    const coreDir = getCoreConfigDir();
-    const coreConfig = loadConfig(coreDir);
-    const coreUrl = coreConfig?.services[serviceName]?.url;
-    if (coreUrl)
-        return coreUrl;
-    // 3. Fall back to port constants
-    const port = DEFAULT_PORTS[serviceName];
-    if (port !== undefined) {
-        return `http://127.0.0.1:${String(port)}`;
+    catch {
+        return false;
     }
-    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
 }
 
 /**
- * Registry version cache for npm package update awareness.
+ * Cleanup flag scanning extracted from ComponentWriter.cycle().
  *
  * @remarks
- * Caches the latest npm registry version in a local JSON file
- * to avoid expensive `npm view` calls on every refresh cycle.
+ * After writing managed files, scans each for the cleanup flag and
+ * fires a best-effort escalation request when a gateway URL is configured.
+ * Uses a `pendingCleanups` set to deduplicate in-flight requests.
  */
 /**
- * Check the npm registry for the latest version of a package.
+ * Scan managed files for the cleanup flag and escalate when detected.
  *
- * @param packageName - The npm package name (e.g., '\@karmaniverous/jeeves').
- * @param cacheDir - Directory to store the cache file.
- * @param ttlSeconds - Cache TTL in seconds (default 3600).
- * @returns The latest version string, or undefined if the check fails.
+ * @param targets - Managed files to scan.
+ * @param gatewayUrl - Gateway URL for session spawn.
+ * @param pendingCleanups - Set tracking in-flight requests (mutated).
  */
-function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
-    const cachePath = join(cacheDir, REGISTRY_CACHE_FILE);
-    // Check cache first
-    if (existsSync(cachePath)) {
+function scanAndEscalateCleanup(targets, gatewayUrl, pendingCleanups) {
+    for (const target of targets) {
         try {
-            const raw = readFileSync(cachePath, 'utf-8');
-            const entry = JSON.parse(raw);
-            const age = Date.now() - new Date(entry.checkedAt).getTime();
-            if (age < ttlSeconds * 1000) {
-                return entry.version;
+            if (pendingCleanups.has(target.filePath))
+                continue;
+            const fileContent = readFileSync(target.filePath, 'utf-8');
+            if (fileContent.includes(CLEANUP_FLAG)) {
+                pendingCleanups.add(target.filePath);
+                void requestCleanupSession({
+                    gatewayUrl,
+                    filePath: target.filePath,
+                    markerIdentity: target.markerIdentity,
+                }).finally(() => {
+                    pendingCleanups.delete(target.filePath);
+                });
             }
         }
         catch {
-            // Cache corrupt — proceed with fresh check
+            // Best-effort: don't fail the cycle for escalation issues.
         }
     }
-    // Query npm registry
-    try {
-        const result = execSync(`npm view ${packageName} version`, {
-            encoding: 'utf-8',
-            timeout: 15_000,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        }).trim();
-        if (!result)
-            return undefined;
-        // Write cache
-        if (!existsSync(cacheDir)) {
-            mkdirSync(cacheDir, { recursive: true });
+}
+
+/**
+ * Memory budget accounting and staleness detection for MEMORY.md.
+ *
+ * @remarks
+ * Scans MEMORY.md for ISO date patterns in H2/H3 headings and bullet items.
+ * Reports character count against a configured budget, warning threshold state,
+ * and stale section candidates. Does not auto-delete: review remains
+ * human- or agent-mediated (Decision 42).
+ */
+/** ISO date pattern: YYYY-MM-DD. */
+const ISO_DATE_RE = /\b(\d{4}-\d{2}-\d{2})\b/g;
+/** H2 heading pattern used to split sections. */
+const H2_RE = /^## /m;
+/**
+ * Extract the most recent ISO date from a string.
+ *
+ * @param text - Text to scan for dates.
+ * @returns The most recent date found, or undefined.
+ */
+function extractMostRecentDate(text) {
+    const matches = text.match(ISO_DATE_RE);
+    if (!matches)
+        return undefined;
+    let latest;
+    for (const match of matches) {
+        const d = new Date(match + 'T00:00:00Z');
+        if (!Number.isNaN(d.getTime())) {
+            if (!latest || d > latest)
+                latest = d;
         }
-        const entry = {
-            version: result,
-            checkedAt: new Date().toISOString(),
+    }
+    return latest;
+}
+/**
+ * Analyze MEMORY.md for budget and staleness.
+ *
+ * @param options - Analysis configuration.
+ * @returns Memory hygiene result.
+ */
+function analyzeMemory(options) {
+    const { workspacePath, budget, warningThreshold, staleDays } = options;
+    const memoryPath = join(workspacePath, WORKSPACE_FILES.memory);
+    if (!existsSync(memoryPath)) {
+        return {
+            exists: false,
+            charCount: 0,
+            budget,
+            usage: 0,
+            warning: false,
+            overBudget: false,
+            staleCandidates: 0,
+            staleSectionNames: [],
         };
-        writeFileSync(cachePath, JSON.stringify(entry, null, 2), 'utf-8');
-        return result;
     }
-    catch {
-        return undefined;
+    const content = readFileSync(memoryPath, 'utf-8');
+    const charCount = content.length;
+    const usage = budget > 0 ? charCount / budget : charCount > 0 ? Infinity : 0;
+    const warning = usage >= warningThreshold;
+    const overBudget = usage > 1;
+    // Split into H2 sections and scan for staleness
+    const sections = content.split(H2_RE).slice(1); // skip content before first H2
+    const now = Date.now();
+    const thresholdMs = staleDays * 24 * 60 * 60 * 1000;
+    const staleSectionNames = [];
+    for (const section of sections) {
+        const sectionName = section.split('\n')[0]?.trim() ?? '';
+        const recentDate = extractMostRecentDate(section);
+        // Sections without dates are evergreen — never flagged (Decision 47)
+        if (!recentDate)
+            continue;
+        if (now - recentDate.getTime() > thresholdMs) {
+            staleSectionNames.push(sectionName);
+        }
     }
+    return {
+        exists: true,
+        charCount,
+        budget,
+        usage,
+        warning,
+        overBudget,
+        staleCandidates: staleSectionNames.length,
+        staleSectionNames,
+    };
 }
 
 /**
- * HEARTBEAT health orchestration.
+ * HEARTBEAT integration for memory hygiene.
  *
  * @remarks
- * 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.
+ * Calls `analyzeMemory()` and converts the result into a `HeartbeatEntry`
+ * suitable for inclusion in the HEARTBEAT.md platform status section.
+ * Returns `undefined` when MEMORY.md is healthy (no alert needed).
+ *
+ * Uses the `## MEMORY.md` heading (Decision 50) to distinguish memory
+ * alerts from component alerts (`## jeeves-{name}`).
  */
-/** 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;
+/** The HEARTBEAT heading name for memory alerts. */
+const MEMORY_HEARTBEAT_NAME = 'MEMORY.md';
 /**
- * Check if Qdrant is reachable (watcher dependency).
+ * Check memory health and return a HEARTBEAT entry if unhealthy.
  *
- * @returns True if Qdrant responds.
+ * @param options - Memory hygiene options (workspacePath, budget, etc.).
+ * @returns A `HeartbeatEntry` when memory needs attention, `undefined` when healthy.
  */
-async function isQdrantAvailable() {
-    try {
-        await fetchWithTimeout(`${QDRANT_URL}/collections`, PROBE_TIMEOUT_MS$1);
-        return true;
+function checkMemoryHealth(options) {
+    const result = analyzeMemory(options);
+    if (!result.exists)
+        return undefined;
+    if (!result.warning && result.staleCandidates === 0)
+        return undefined;
+    const lines = [];
+    if (result.warning) {
+        const pct = Math.round(result.usage * 100);
+        lines.push(`- Budget: ${result.charCount.toLocaleString()} / ${result.budget.toLocaleString()} chars (${String(pct)}%).${result.overBudget ? ' **Over budget.**' : ' Consider reviewing.'}`);
     }
-    catch {
-        return false;
+    if (result.staleCandidates > 0) {
+        lines.push(`- ${String(result.staleCandidates)} stale section${result.staleCandidates === 1 ? '' : 's'}: ${result.staleSectionNames.join(', ')}`);
     }
+    return {
+        name: MEMORY_HEARTBEAT_NAME,
+        declined: false,
+        content: lines.join('\n'),
+    };
 }
+
 /**
- * Determine the state of a single component.
+ * HEARTBEAT integration for workspace file size monitoring.
  *
- * @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.
+ * @remarks
+ * Checks all injected workspace files (AGENTS.md, SOUL.md, TOOLS.md,
+ * MEMORY.md, USER.md) against the OpenClaw ~20,000-char injection limit.
+ * Files exceeding the warning threshold generate HEARTBEAT entries with
+ * trimming guidance.
  */
-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';
-    }
-}
+/** Workspace files monitored for size budget. */
+const WORKSPACE_SIZE_FILES = [
+    'AGENTS.md',
+    'SOUL.md',
+    'TOOLS.md',
+    'MEMORY.md',
+    'USER.md',
+];
+/** Trimming guidance lines emitted in HEARTBEAT entries. */
+const TRIMMING_GUIDANCE = [
+    '  1. Move domain-specific content to a local skill',
+    '  2. Extract reference material to companion files with a pointer',
+    '  3. Summarize verbose instructions',
+    '  4. Remove stale content',
+].join('\n');
 /**
- * Generate the alert text for a component in a given state.
+ * Check all workspace files against the character budget.
  *
- * @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.
+ * @param options - Health check options.
+ * @returns Array of results, one per checked file (skips non-existent files
+ *   unless they breach the budget, which they cannot by definition).
  */
-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}.`;
-    }
-    const componentAlerts = ALERT_TEXT[name];
-    const alertOrFn = componentAlerts[state];
-    if (!alertOrFn)
-        return '';
-    const text = typeof alertOrFn === 'function' ? alertOrFn(configRoot) : alertOrFn;
-    return `- ${text}`;
+function checkWorkspaceFileHealth(options) {
+    const { workspacePath, budgetChars = 20_000, warningThreshold = 0.8, } = options;
+    return WORKSPACE_SIZE_FILES.map((file) => {
+        const filePath = join(workspacePath, file);
+        if (!existsSync(filePath)) {
+            return {
+                file,
+                exists: false,
+                charCount: 0,
+                budget: budgetChars,
+                usage: 0,
+                warning: false,
+                overBudget: false,
+            };
+        }
+        const content = readFileSync(filePath, 'utf-8');
+        const charCount = content.length;
+        const usage = charCount / budgetChars;
+        return {
+            file,
+            exists: true,
+            charCount,
+            budget: budgetChars,
+            usage,
+            warning: usage >= warningThreshold,
+            overBudget: charCount > budgetChars,
+        };
+    });
 }
 /**
- * Orchestrate HEARTBEAT entries for all platform components.
+ * Convert workspace file health results into HEARTBEAT entries.
  *
- * @param options - Orchestration configuration.
- * @returns Array of HeartbeatEntry for writeHeartbeatSection.
+ * @param results - Results from `checkWorkspaceFileHealth`.
+ * @returns Array of `HeartbeatEntry` objects for files that exceed the
+ *   warning threshold.
  */
-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;
+function workspaceFileHealthEntries(results) {
+    return results
+        .filter((r) => r.exists && r.warning)
+        .map((r) => {
+        const pct = Math.round(r.usage * 100);
+        const overBudgetNote = r.overBudget ? ' **Over budget.**' : '';
+        const content = [
+            `- Budget: ${r.charCount.toLocaleString()} / ${r.budget.toLocaleString()} chars (${String(pct)}%).${overBudgetNote} Trim to stay under the OpenClaw injection limit.`,
+            `- Suggested trimming priority:\n${TRIMMING_GUIDANCE}`,
+        ].join('\n');
+        return {
+            name: r.file,
+            declined: false,
+            content,
+        };
+    });
 }
 
 /**
- * HEARTBEAT orchestration extracted from ComponentWriter.cycle().
+ * Core configuration schema and resolution.
  *
  * @remarks
- * Reads existing HEARTBEAT.md, resolves declined components, runs the
- * heartbeat state machine, and writes the result. Best-effort: failures
- * are logged but do not propagate.
+ * Core config lives at `{configRoot}/jeeves-core/config.json`.
+ * Config resolution order:
+ * 1. Component's own config file
+ * 2. Core config file
+ * 3. Hardcoded library defaults
  */
+/** Zod schema for a service entry in core config. */
+const serviceEntrySchema = z.object({
+    /** Service URL (must be a valid URL). */
+    url: z.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)
+        .default({})
+        .describe('Service URL overrides'),
+    /** Registry cache configuration. */
+    registryCache: z
+        .object({
+        /** Cache TTL in seconds for npm registry queries. */
+        ttlSeconds: z
+            .number()
+            .int()
+            .positive()
+            .default(3600)
+            .describe('Cache TTL in seconds'),
+    })
+        .prefault({})
+        .describe('Registry cache settings'),
+});
 /**
- * Read a file's content, returning empty string if the file does not exist.
+ * Generate a JSON Schema from the Zod schema for `$schema` pointer support.
  *
- * @param filePath - Absolute file path.
- * @returns File content or empty string.
+ * @returns A JSON Schema object.
  */
-function readFileOrEmpty(filePath) {
-    try {
-        return readFileSync(filePath, 'utf-8');
-    }
-    catch (err) {
-        if (err instanceof Error &&
-            'code' in err &&
-            err.code === 'ENOENT') {
-            return '';
-        }
-        throw err;
-    }
+function generateJsonSchema() {
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        title: 'Jeeves Core Configuration',
+        type: 'object',
+        properties: {
+            $schema: { type: 'string' },
+            owners: {
+                type: 'array',
+                items: { type: 'string' },
+                default: [],
+            },
+            bindAddress: {
+                type: 'string',
+                default: '0.0.0.0',
+                description: 'Bind address for all Jeeves services',
+            },
+            services: {
+                type: 'object',
+                additionalProperties: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', format: 'uri' },
+                    },
+                    required: ['url'],
+                },
+                default: {},
+            },
+            registryCache: {
+                type: 'object',
+                properties: {
+                    ttlSeconds: {
+                        type: 'integer',
+                        minimum: 1,
+                        default: 3600,
+                    },
+                },
+                default: {},
+            },
+        },
+    };
 }
 /**
- * Run a single HEARTBEAT orchestration cycle.
+ * Load and parse a config file, returning undefined if missing or invalid.
  *
- * @param options - Heartbeat cycle configuration.
+ * @param configDir - Directory containing config.json.
+ * @returns Parsed config or undefined.
  */
-async function runHeartbeatCycle(options) {
-    const { workspacePath, coreConfigDir, configRoot } = options;
-    const heartbeatPath = join(workspacePath, WORKSPACE_FILES.heartbeat);
+function loadConfig(configDir) {
+    const configPath = join(configDir, CONFIG_FILE);
+    if (!existsSync(configPath))
+        return undefined;
     try {
-        const existingContent = readFileOrEmpty(heartbeatPath);
-        const parsed = parseHeartbeat(existingContent);
-        const declinedNames = new Set(parsed.entries.filter((e) => e.declined).map((e) => e.name));
-        const entries = await orchestrateHeartbeat({
-            coreConfigDir,
-            configRoot,
-            declinedNames,
-        });
-        // Memory hygiene check (Decision 49)
-        if (!declinedNames.has(MEMORY_HEARTBEAT_NAME)) {
-            const wsConfig = loadWorkspaceConfig(workspacePath);
-            const memoryEntry = checkMemoryHealth({
-                workspacePath,
-                budget: wsConfig?.memory?.budget ?? WORKSPACE_CONFIG_DEFAULTS.memory.budget,
-                warningThreshold: wsConfig?.memory?.warningThreshold ??
-                    WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold,
-                staleDays: wsConfig?.memory?.staleDays ??
-                    WORKSPACE_CONFIG_DEFAULTS.memory.staleDays,
-            });
-            if (memoryEntry)
-                entries.push(memoryEntry);
-        }
-        else {
-            entries.push({
-                name: MEMORY_HEARTBEAT_NAME,
-                declined: true,
-                content: '',
-            });
-        }
-        // Workspace file size health check (Decision 70)
-        const wsFileResults = checkWorkspaceFileHealth({ workspacePath });
-        const wsFileAlerts = workspaceFileHealthEntries(wsFileResults);
-        for (const alert of wsFileAlerts) {
-            if (declinedNames.has(alert.name)) {
-                entries.push({ name: alert.name, declined: true, content: '' });
-            }
-            else {
-                entries.push(alert);
-            }
-        }
-        await writeHeartbeatSection(heartbeatPath, entries);
+        const raw = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return coreConfigSchema.parse(parsed);
     }
-    catch (err) {
-        console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${getErrorMessage(err)}`);
+    catch {
+        return undefined;
     }
 }
 
 /**
- * Timer-based orchestrator for managed content writing.
+ * Service URL resolution.
  *
  * @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.
+ * Resolves the URL for a named Jeeves service using the following
+ * resolution order:
+ * 1. Consumer's own component config
+ * 2. Core config (`{configRoot}/jeeves-core/config.json`)
+ * 3. Default port constants
  */
 /**
- * Orchestrates managed content writing for a single Jeeves component.
- *
- * @remarks
- * Created via {@link createComponentWriter}. Manages a timer that fires
- * at the component's prime-interval, calling `generateToolsContent()`
- * and `refreshPlatformContent()` on each cycle.
- */
-class ComponentWriter {
-    timer;
-    jitterTimeout;
-    component;
-    configDir;
-    gatewayUrl;
-    pendingCleanups = new Set();
-    /** @internal */
-    constructor(component, options) {
-        this.component = component;
-        this.configDir = getComponentConfigDir(component.name);
-        this.gatewayUrl = options?.gatewayUrl;
-    }
-    /** The component's config directory path. */
-    get componentConfigDir() {
-        return this.configDir;
-    }
-    /** Whether the writer timer is currently running or pending its first cycle. */
-    get isRunning() {
-        return this.jitterTimeout !== undefined || this.timer !== undefined;
-    }
-    /**
-     * Start the writer timer.
-     *
-     * @remarks
-     * Delays the first cycle by a random jitter (0 to one full interval) to
-     * spread initial writes across all component plugins and reduce EPERM
-     * contention on startup.
-     */
-    start() {
-        if (this.isRunning)
-            return;
-        // Random jitter up to one full interval to spread initial writes
-        const intervalMs = this.component.refreshIntervalSeconds * 1000;
-        const jitterMs = Math.floor(Math.random() * intervalMs);
-        this.jitterTimeout = setTimeout(() => {
-            this.jitterTimeout = undefined;
-            void this.cycle();
-            this.timer = setInterval(() => void this.cycle(), intervalMs);
-        }, jitterMs);
-    }
-    /** Stop the writer timer. */
-    stop() {
-        if (this.jitterTimeout) {
-            clearTimeout(this.jitterTimeout);
-            this.jitterTimeout = undefined;
-        }
-        if (this.timer) {
-            clearInterval(this.timer);
-            this.timer = undefined;
-        }
-    }
-    /**
-     * Execute a single write cycle.
-     *
-     * @remarks
-     * 1. Write the component's TOOLS.md section.
-     * 2. Refresh shared platform content (SOUL.md, AGENTS.md, Platform section).
-     * 3. Scan for cleanup flags and escalate if a gateway URL is configured.
-     * 4. Run HEARTBEAT health orchestration.
-     */
-    async cycle() {
-        try {
-            const workspacePath = getWorkspacePath();
-            const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
-            // 1. 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,
-            });
-            // 2. Platform content maintenance
-            await refreshPlatformContent({
-                coreVersion: CORE_VERSION,
-                componentName: this.component.name,
-                componentVersion: this.component.version,
-                servicePackage: this.component.servicePackage,
-                pluginPackage: this.component.pluginPackage,
-            });
-            // 3. Cleanup escalation
-            if (this.gatewayUrl) {
-                scanAndEscalateCleanup([
-                    { filePath: toolsPath, markerIdentity: 'TOOLS' },
-                    {
-                        filePath: join(workspacePath, WORKSPACE_FILES.soul),
-                        markerIdentity: 'SOUL',
-                    },
-                    {
-                        filePath: join(workspacePath, WORKSPACE_FILES.agents),
-                        markerIdentity: 'AGENTS',
-                    },
-                ], this.gatewayUrl, this.pendingCleanups);
-            }
-            // 4. HEARTBEAT orchestration
-            await runHeartbeatCycle({
-                workspacePath,
-                coreConfigDir: getCoreConfigDir(),
-                configRoot: getConfigRoot(),
-            });
-        }
-        catch (err) {
-            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${getErrorMessage(err)}`);
-        }
+ * Resolve the URL for a named Jeeves service.
+ *
+ * @param serviceName - The service name (e.g., 'watcher', 'runner').
+ * @param consumerName - Optional consumer component name for config override.
+ * @returns The resolved service URL.
+ * @throws Error if `init()` has not been called or the service is unknown.
+ */
+function getServiceUrl(serviceName, consumerName) {
+    // 1. Check consumer's own config
+    if (consumerName) {
+        const consumerDir = getComponentConfigDir(consumerName);
+        const consumerConfig = loadConfig(consumerDir);
+        const consumerUrl = consumerConfig?.services[serviceName]?.url;
+        if (consumerUrl)
+            return consumerUrl;
+    }
+    // 2. Check core config
+    const coreDir = getCoreConfigDir();
+    const coreConfig = loadConfig(coreDir);
+    const coreUrl = coreConfig?.services[serviceName]?.url;
+    if (coreUrl)
+        return coreUrl;
+    // 3. Fall back to port constants
+    const port = DEFAULT_PORTS[serviceName];
+    if (port !== undefined) {
+        return `http://127.0.0.1:${String(port)}`;
     }
+    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
 }
 
 /**
- * Creates a synchronous content accessor backed by an async data source.
+ * Registry version cache for npm package update awareness.
  *
  * @remarks
- * 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.
- *
- * 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,
- * });
- * ```
+ * Caches the latest npm registry version in a local JSON file
+ * to avoid expensive `npm view` calls on every refresh cycle.
  */
 /**
- * Creates a synchronous content accessor backed by an async data source.
+ * Check the npm registry for the latest version of a package.
  *
- * @param options - Cache configuration.
- * @returns A sync `() => string` suitable for `generateToolsContent`.
+ * @param packageName - The npm package name (e.g., '\@karmaniverous/jeeves').
+ * @param cacheDir - Directory to store the cache file.
+ * @param ttlSeconds - Cache TTL in seconds (default 3600).
+ * @returns The latest version string, or undefined if the check fails.
  */
-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;
-            });
+function checkRegistryVersion(packageName, cacheDir, ttlSeconds = 3600) {
+    const cachePath = join(cacheDir, REGISTRY_CACHE_FILE);
+    // Check cache first
+    if (existsSync(cachePath)) {
+        try {
+            const raw = readFileSync(cachePath, 'utf-8');
+            const entry = JSON.parse(raw);
+            const age = Date.now() - new Date(entry.checkedAt).getTime();
+            if (age < ttlSeconds * 1000) {
+                return entry.version;
+            }
         }
-        return cached;
-    };
+        catch {
+            // Cache corrupt — proceed with fresh check
+        }
+    }
+    // Query npm registry
+    try {
+        const result = execSync(`npm view ${packageName} version`, {
+            encoding: 'utf-8',
+            timeout: 15_000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (!result)
+            return undefined;
+        // Write cache
+        if (!existsSync(cacheDir)) {
+            mkdirSync(cacheDir, { recursive: true });
+        }
+        const entry = {
+            version: result,
+            checkedAt: new Date().toISOString(),
+        };
+        writeFileSync(cachePath, JSON.stringify(entry, null, 2), 'utf-8');
+        return result;
+    }
+    catch {
+        return undefined;
+    }
 }
 
 /**
- * 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.
+ * HEARTBEAT health orchestration.
  *
  * @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.
- * @param options - Optional writer configuration (e.g., gatewayUrl for cleanup escalation).
- * @returns A new `ComponentWriter` instance.
- * @throws ZodError if the descriptor is invalid.
+ * 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.
  */
-function createComponentWriter(descriptor, options) {
-    // Validate via Zod — throws ZodError with detailed messages on failure
-    jeevesComponentDescriptorSchema.parse(descriptor);
-    return new ComponentWriter(descriptor, options);
+/** 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 = 3000;
 /**
- * Resolve the bind address for a Jeeves service.
+ * Check if Qdrant is reachable (watcher dependency).
  *
- * @remarks
- * 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`
+ * @returns True if Qdrant responds.
  */
+async function isQdrantAvailable() {
+    try {
+        await fetchWithTimeout(`${QDRANT_URL}/collections`, PROBE_TIMEOUT_MS);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * Resolve the bind address for a Jeeves service.
+ * Determine the state of a single component.
  *
- * @param componentName - Optional component name for component-specific override.
- * @returns The resolved bind address.
+ * @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.
  */
-function getBindAddress(componentName) {
-    // Tier 1: Component config (if provided)
-    if (componentName) {
-        const componentConfig = loadConfig(getComponentConfigDir(componentName));
-        if (componentConfig?.bindAddress) {
-            return componentConfig.bindAddress;
-        }
+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';
     }
-    // Tier 2: Core config
-    const coreConfig = loadConfig(getCoreConfigDir());
-    if (coreConfig?.bindAddress) {
-        return coreConfig.bindAddress;
+    // 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);
+        // 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';
     }
-    // Tier 3: Environment variable
-    const envValue = process.env['JEEVES_BIND_ADDRESS'];
-    if (envValue) {
-        return envValue;
+    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';
     }
-    // Tier 4: Default
-    return DEFAULT_BIND_ADDRESS;
 }
-
-/**
- * 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.
+ * Generate the alert text for a component in a given state.
  *
- * @param coreConfigDir - Path to the core config directory.
+ * @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.
  */
-function ensureCoreConfig(coreConfigDir) {
-    if (!existsSync(coreConfigDir)) {
-        mkdirSync(coreConfigDir, { recursive: true });
+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}.`;
     }
-    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');
+    const componentAlerts = ALERT_TEXT[name];
+    const alertOrFn = componentAlerts[state];
+    if (!alertOrFn)
+        return '';
+    const text = typeof alertOrFn === 'function' ? alertOrFn(configRoot) : alertOrFn;
+    return `- ${text}`;
 }
 /**
- * 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.
- * Writes initial HEARTBEAT with "Not installed" alerts for all platform components.
- * Jaccard cleanup detection runs automatically via `updateManagedSection`.
+ * Orchestrate HEARTBEAT entries for all platform components.
  *
- * @param options - Seeding configuration.
+ * @param options - Orchestration configuration.
+ * @returns Array of HeartbeatEntry for writeHeartbeatSection.
  */
-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);
-    // Seed jeeves workspace skill (Decision 48: overwrite-on-install)
-    seedSkill(getWorkspacePath());
+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);
+            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;
 }
 
 /**
- * Tool result formatters for the OpenClaw plugin SDK.
+ * HEARTBEAT orchestration extracted from ComponentWriter.cycle().
  *
  * @remarks
- * Provides standardised helpers for building `ToolResult` objects:
- * success, error, and connection-error variants.
- */
-/**
- * Format a successful tool result.
- *
- * @param data - Arbitrary data to return as JSON.
- * @returns A `ToolResult` with JSON-stringified content.
+ * Reads existing HEARTBEAT.md, resolves declined components, runs the
+ * heartbeat state machine, and writes the result. Best-effort: failures
+ * are logged but do not propagate.
  */
-function ok(data) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-    };
-}
 /**
- * Format an error tool result.
+ * Read a file's content, returning empty string if the file does not exist.
  *
- * @param error - Error instance, string, or other value.
- * @returns A `ToolResult` with `isError: true`.
+ * @param filePath - Absolute file path.
+ * @returns File content or empty string.
  */
-function fail(error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return {
-        content: [{ type: 'text', text: 'Error: ' + message }],
-        isError: true,
-    };
+function readFileOrEmpty(filePath) {
+    try {
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return '';
+        }
+        throw err;
+    }
 }
 /**
- * Format a connection error with actionable guidance.
- *
- * @remarks
- * Detects `ECONNREFUSED`, `ENOTFOUND`, and `ETIMEDOUT` from
- * `error.cause.code` and returns a user-friendly message referencing
- * the plugin's `config.apiUrl` setting. Falls back to `fail()` for
- * non-connection errors.
+ * Run a single HEARTBEAT orchestration cycle.
  *
- * @param error - Error instance (typically from `fetch`).
- * @param baseUrl - The URL that was being contacted.
- * @param pluginId - The plugin identifier for config guidance.
- * @returns A `ToolResult` with `isError: true`.
+ * @param options - Heartbeat cycle configuration.
  */
-function connectionFail(error, baseUrl, pluginId) {
-    const cause = error instanceof Error ? error.cause : undefined;
-    const code = cause && typeof cause === 'object' && 'code' in cause
-        ? String(cause.code)
-        : '';
-    const isConnectionError = code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'ETIMEDOUT';
-    if (isConnectionError) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: [
-                        `Service not reachable at ${baseUrl}.`,
-                        'Either start the service, or if it runs on a different port,',
-                        `set plugins.entries.${pluginId}.config.apiUrl in openclaw.json.`,
-                    ].join('\n'),
-                },
-            ],
-            isError: true,
-        };
+async function runHeartbeatCycle(options) {
+    const { workspacePath, coreConfigDir, configRoot } = options;
+    const heartbeatPath = join(workspacePath, WORKSPACE_FILES.heartbeat);
+    try {
+        const existingContent = readFileOrEmpty(heartbeatPath);
+        const parsed = parseHeartbeat(existingContent);
+        const declinedNames = new Set(parsed.entries.filter((e) => e.declined).map((e) => e.name));
+        const entries = await orchestrateHeartbeat({
+            coreConfigDir,
+            configRoot,
+            declinedNames,
+        });
+        // Memory hygiene check (Decision 49)
+        if (!declinedNames.has(MEMORY_HEARTBEAT_NAME)) {
+            const wsConfig = loadWorkspaceConfig(workspacePath);
+            const memoryEntry = checkMemoryHealth({
+                workspacePath,
+                budget: wsConfig?.memory?.budget ?? WORKSPACE_CONFIG_DEFAULTS.memory.budget,
+                warningThreshold: wsConfig?.memory?.warningThreshold ??
+                    WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold,
+                staleDays: wsConfig?.memory?.staleDays ??
+                    WORKSPACE_CONFIG_DEFAULTS.memory.staleDays,
+            });
+            if (memoryEntry)
+                entries.push(memoryEntry);
+        }
+        else {
+            entries.push({
+                name: MEMORY_HEARTBEAT_NAME,
+                declined: true,
+                content: '',
+            });
+        }
+        // Workspace file size health check (Decision 70)
+        const wsFileResults = checkWorkspaceFileHealth({ workspacePath });
+        const wsFileAlerts = workspaceFileHealthEntries(wsFileResults);
+        for (const alert of wsFileAlerts) {
+            if (declinedNames.has(alert.name)) {
+                entries.push({ name: alert.name, declined: true, content: '' });
+            }
+            else {
+                entries.push(alert);
+            }
+        }
+        await writeHeartbeatSection(heartbeatPath, entries);
+    }
+    catch (err) {
+        console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${getErrorMessage(err)}`);
     }
-    return fail(error);
 }
 
 /**
- * Factory for the standard plugin tool set.
+ * Timer-based orchestrator for managed content writing.
  *
  * @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.
+ * `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.
  */
-/** Timeout for HTTP probes in milliseconds. */
-const PROBE_TIMEOUT_MS = 5000;
 /**
- * Create the standard plugin tool set from a component descriptor.
+ * Orchestrates managed content writing for a single Jeeves component.
  *
- * @param descriptor - The component descriptor.
- * @returns Array of tool descriptors to register.
+ * @remarks
+ * Created via {@link createComponentWriter}. Manages a timer that fires
+ * at the component's prime-interval, calling `generateToolsContent()`
+ * and `refreshPlatformContent()` on each cycle.
  */
-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`, {
-                    patch: 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();
+class ComponentWriter {
+    timer;
+    jitterTimeout;
+    component;
+    configDir;
+    gatewayUrl;
+    pendingCleanups = new Set();
+    /** @internal */
+    constructor(component, options) {
+        this.component = component;
+        this.configDir = getComponentConfigDir(component.name);
+        this.gatewayUrl = options?.gatewayUrl;
+    }
+    /** The component's config directory path. */
+    get componentConfigDir() {
+        return this.configDir;
+    }
+    /** Whether the writer timer is currently running or pending its first cycle. */
+    get isRunning() {
+        return this.jitterTimeout !== undefined || this.timer !== undefined;
+    }
+    /**
+     * Start the writer timer.
+     *
+     * @remarks
+     * Delays the first cycle by a random jitter (0 to one full interval) to
+     * spread initial writes across all component plugins and reduce EPERM
+     * contention on startup.
+     */
+    start() {
+        if (this.isRunning)
+            return;
+        // Random jitter up to one full interval to spread initial writes
+        const intervalMs = this.component.refreshIntervalSeconds * 1000;
+        const jitterMs = Math.floor(Math.random() * intervalMs);
+        this.jitterTimeout = setTimeout(() => {
+            this.jitterTimeout = undefined;
+            void this.cycle();
+            this.timer = setInterval(() => void this.cycle(), intervalMs);
+        }, jitterMs);
+    }
+    /** Stop the writer timer. */
+    stop() {
+        if (this.jitterTimeout) {
+            clearTimeout(this.jitterTimeout);
+            this.jitterTimeout = undefined;
+        }
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+    /**
+     * Execute a single write cycle.
+     *
+     * @remarks
+     * 1. Write the component's TOOLS.md section.
+     * 2. Refresh shared platform content (SOUL.md, AGENTS.md, Platform section).
+     * 3. Scan for cleanup flags and escalate if a gateway URL is configured.
+     * 4. Run HEARTBEAT health orchestration.
+     */
+    async cycle() {
+        try {
+            const workspacePath = getWorkspacePath();
+            const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
+            // 1. 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,
+            });
+            // 2. Platform content maintenance
+            await refreshPlatformContent({
+                coreVersion: CORE_VERSION,
+                componentName: this.component.name,
+                componentVersion: this.component.version,
+                servicePackage: this.component.servicePackage,
+                pluginPackage: this.component.pluginPackage,
+            });
+            // 3. Cleanup escalation
+            if (this.gatewayUrl) {
+                scanAndEscalateCleanup([
+                    { filePath: toolsPath, markerIdentity: 'TOOLS' },
+                    {
+                        filePath: join(workspacePath, WORKSPACE_FILES.soul),
+                        markerIdentity: 'SOUL',
                     },
-                    restart: () => {
-                        svcManager.restart();
+                    {
+                        filePath: join(workspacePath, WORKSPACE_FILES.agents),
+                        markerIdentity: 'AGENTS',
                     },
-                };
-                methodMap[action]();
-                return Promise.resolve(ok({ service: name, action, success: true }));
-            }
-            catch (err) {
-                return Promise.resolve(fail(`Service ${action} failed: ${getErrorMessage(err)}`));
+                ], this.gatewayUrl, this.pendingCleanups);
             }
-        },
-    };
-    return [statusTool, configTool, configApplyTool, serviceTool];
+            // 4. HEARTBEAT orchestration
+            await runHeartbeatCycle({
+                workspacePath,
+                coreConfigDir: getCoreConfigDir(),
+                configRoot: getConfigRoot(),
+            });
+        }
+        catch (err) {
+            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${getErrorMessage(err)}`);
+        }
+    }
 }
 
 /**
- * Resolve the version of a package from its `import.meta.url`.
+ * Creates a synchronous content accessor backed by an async data source.
  *
- * @module
+ * @remarks
+ * 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.
+ *
+ * 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,
+ * });
+ * ```
  */
 /**
- * Get the version string from the nearest `package.json` relative to the
- * caller's module URL.
+ * Creates a synchronous content accessor backed by an async data source.
  *
- * @param importMetaUrl - The `import.meta.url` of the calling module.
- * @returns The `version` field, or `'unknown'` on any error.
+ * @param options - Cache configuration.
+ * @returns A sync `() => string` suitable for `generateToolsContent`.
  */
-function getPackageVersion(importMetaUrl) {
-    try {
-        const dir = fileURLToPath(importMetaUrl);
-        const pkgRoot = packageDirectorySync({ cwd: dir });
-        if (!pkgRoot)
-            return 'unknown';
-        const raw = readFileSync(join(pkgRoot, 'package.json'), 'utf-8');
-        const pkg = JSON.parse(raw);
-        return typeof pkg.version === 'string' ? pkg.version : 'unknown';
-    }
-    catch {
-        return 'unknown';
-    }
+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;
+    };
 }
 
 /**
- * Plugin resolution helpers for the OpenClaw plugin SDK.
+ * Factory function for creating a ComponentWriter from a descriptor.
  *
  * @remarks
- * Provides workspace path resolution and plugin setting resolution
- * with a standard three-step fallback chain:
- * plugin config → environment variable → default value.
+ * 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.
  */
 /**
- * Resolve the workspace root from the OpenClaw plugin API.
+ * Create a ComponentWriter for a validated component descriptor.
  *
  * @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
+ * The descriptor is validated via the Zod schema at runtime.
+ * This replaces the v0.4.0 `createComponentWriter(JeevesComponent)`.
  *
- * @param api - The plugin API object provided by the gateway.
- * @returns Absolute path to the workspace root.
+ * @param descriptor - The component descriptor to validate and wrap.
+ * @param options - Optional writer configuration (e.g., gatewayUrl for cleanup escalation).
+ * @returns A new `ComponentWriter` instance.
+ * @throws ZodError if the descriptor is invalid.
  */
-function resolveWorkspacePath(api) {
-    const configured = api.config?.agents?.defaults?.workspace;
-    if (typeof configured === 'string' && configured.trim()) {
-        return configured;
+function createComponentWriter(descriptor, options) {
+    // Validate via Zod — throws ZodError with detailed messages on failure
+    jeevesComponentDescriptorSchema.parse(descriptor);
+    return new ComponentWriter(descriptor, options);
+}
+
+/**
+ * Resolve the bind address for a Jeeves service.
+ *
+ * @remarks
+ * 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 componentName - Optional component name for component-specific override.
+ * @returns The resolved bind address.
+ */
+function getBindAddress(componentName) {
+    // Tier 1: Component config (if provided)
+    if (componentName) {
+        const componentConfig = loadConfig(getComponentConfigDir(componentName));
+        if (componentConfig?.bindAddress) {
+            return componentConfig.bindAddress;
+        }
     }
-    if (typeof api.resolvePath === 'function') {
-        return api.resolvePath('.');
+    // Tier 2: Core config
+    const coreConfig = loadConfig(getCoreConfigDir());
+    if (coreConfig?.bindAddress) {
+        return coreConfig.bindAddress;
     }
-    return process.cwd();
+    // Tier 3: Environment variable
+    const envValue = process.env['JEEVES_BIND_ADDRESS'];
+    if (envValue) {
+        return envValue;
+    }
+    // Tier 4: Default
+    return DEFAULT_BIND_ADDRESS;
 }
+
 /**
- * Resolve a plugin setting via the standard three-step fallback chain:
- * plugin config → environment variable → fallback value.
+ * One-shot content seeding used by the CLI install command.
  *
- * @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.
+ * @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.
  */
-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;
+/**
+ * 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');
 }
 /**
- * Resolve an optional plugin setting via the two-step fallback chain:
- * plugin config → environment variable. Returns `undefined` if neither
- * source provides a 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.
- * @returns The resolved setting value, or `undefined`.
+ * @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 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);
+    // Seed jeeves workspace skill (Decision 48: overwrite-on-install)
+    seedSkill(getWorkspacePath());
 }
 
 /**
@@ -5308,4 +5332,4 @@ async function getChannelWorkspace(channelId, token, options) {
     return teamId;
 }
 
-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, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };
+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, JEEVES_SKILL_DIR, MEMORY_HEARTBEAT_NAME, META_PORT, PLATFORM_COMPONENTS, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SKILLS_DIR, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_CONFIG_DEFAULTS, WORKSPACE_CONFIG_FILE, WORKSPACE_FILES, analyzeMemory, appendJsonl, atomicWrite, buildEffectiveConfig, buildHeartbeatSection, checkMemoryHealth, checkNodeVersion, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigApplyHandler, createConfigQueryHandler, createGoogleAuth, createPluginCli, createPluginToolset, createServiceCli, createServiceManager, createStatusHandler, ensureDir, extractMostRecentDate, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, generateWorkspaceJsonSchema, getArg, getBindAddress, getChannelWorkspace, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getEffectiveServiceName, getPackageRoot, getPackageVersion, getServiceState, getServiceUrl, getWorkspacePath, init, isPrime, jaccard, jeevesComponentDescriptorSchema, loadEnvFile, loadWorkspaceConfig, needsCleanup, nowIso, ok, orchestrateHeartbeat, parseArgs, parseHeartbeat, parseManaged, patchConfig, postJson, readComponentVersions, readJson, readJsonl, refreshPlatformContent, removeComponentVersion, removeManagedSection, resetInit, resolveConfigPath, resolveConfigValue, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, run, runScript, runWithRetry, saveCache, seedContent, seedSkill, shingles, shouldWrite, sleepAsync, sleepMs, updateManagedSection, uuid, withFileLock, workspaceConfigSchema, writeComponentVersion, writeHeartbeatSection, writeJsonAtomic, writeJsonl };