@karmaniverous/jeeves-server-openclaw 0.7.1 → 0.7.3

package/dist/index.js

@@ -14,8 +14,8 @@ import 'vm';
 import require$$0$5 from 'node:events';
 import require$$1, { execSync } from 'node:child_process';
 import process$2 from 'node:process';
-import 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
+import 'node:fs/promises';
 
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
 
@@ -15490,14 +15490,14 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.5.2` placeholder is replaced by
+ * The `0.5.4` 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.4';
 
 /**
  * Workspace and config root initialization.
@@ -16344,63 +16344,6 @@ function getEffectiveServiceName(descriptor) {
     return descriptor.serviceName ?? `jeeves-${descriptor.name}`;
 }
 
-/**
- * HTTP helpers for the OpenClaw plugin SDK.
- *
- * @remarks
- * Thin wrappers around `fetch` that throw on non-OK responses
- * and handle JSON serialisation/deserialisation.
- */
-/**
- * Fetch a URL with an automatic abort timeout.
- *
- * @param url - URL to fetch.
- * @param timeoutMs - Timeout in milliseconds before aborting.
- * @param init - Optional `fetch` init options.
- * @returns The fetch Response object.
- */
-async function fetchWithTimeout(url, timeoutMs, init) {
-    const controller = new AbortController();
-    const timeout = setTimeout(() => {
-        controller.abort();
-    }, timeoutMs);
-    try {
-        return await fetch(url, { ...init, signal: controller.signal });
-    }
-    finally {
-        clearTimeout(timeout);
-    }
-}
-/**
- * Fetch JSON from a URL, throwing on non-OK responses.
- *
- * @param url - URL to fetch.
- * @param init - Optional `fetch` init options.
- * @returns Parsed JSON response body.
- * @throws Error with `HTTP {status}: {body}` message on non-OK responses.
- */
-async function fetchJson(url, init) {
-    const res = await fetch(url, init);
-    if (!res.ok) {
-        throw new Error('HTTP ' + String(res.status) + ': ' + (await res.text()));
-    }
-    return res.json();
-}
-/**
- * POST JSON to a URL and return parsed response.
- *
- * @param url - URL to POST to.
- * @param body - Request body (will be JSON-stringified).
- * @returns Parsed JSON response body.
- */
-async function postJson(url, body) {
-    return fetchJson(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-    });
-}
-
 /**
  * Platform-aware service state detection.
  *
@@ -16777,247 +16720,603 @@ function createServiceManager(descriptor) {
 }
 
 /**
- * Similarity-based cleanup detection for orphaned managed content.
+ * HTTP helpers for the OpenClaw plugin SDK.
  *
  * @remarks
- * Uses Jaccard similarity on 3-word shingles (Decision 22) to detect
- * when orphaned managed content exists in the user content zone.
+ * Thin wrappers around `fetch` that throw on non-OK responses
+ * and handle JSON serialisation/deserialisation.
  */
-/** Default similarity threshold for cleanup detection. */
-const DEFAULT_THRESHOLD = 0.15;
 /**
- * Generate a set of n-word shingles from text.
+ * Fetch a URL with an automatic abort timeout.
  *
- * @param text - Input text.
- * @param n - Shingle size (default 3).
- * @returns Set of n-word shingles.
+ * @param url - URL to fetch.
+ * @param timeoutMs - Timeout in milliseconds before aborting.
+ * @param init - Optional `fetch` init options.
+ * @returns The fetch Response object.
  */
-function shingles(text, n = 3) {
-    const words = text.toLowerCase().split(/\s+/).filter(Boolean);
-    const set = new Set();
-    for (let i = 0; i <= words.length - n; i++) {
-        set.add(words.slice(i, i + n).join(' '));
+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);
     }
-    return set;
 }
 /**
- * Compute Jaccard similarity between two sets.
+ * Fetch JSON from a URL, throwing on non-OK responses.
  *
- * @param a - First set.
- * @param b - Second set.
- * @returns Jaccard similarity coefficient (0 to 1).
+ * @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.
  */
-function jaccard(a, b) {
-    if (a.size === 0 && b.size === 0)
-        return 0;
-    let intersection = 0;
-    for (const item of a) {
-        if (b.has(item))
-            intersection++;
+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 intersection / (a.size + b.size - intersection);
+    return res.json();
 }
 /**
- * Check whether user content contains orphaned managed content.
+ * POST JSON to a URL and return parsed response.
  *
- * @param managedContent - The current managed block content.
- * @param userContent - Content below the END marker.
- * @param threshold - Jaccard threshold (default 0.15).
- * @returns `true` if cleanup is needed.
+ * @param url - URL to POST to.
+ * @param body - Request body (will be JSON-stringified).
+ * @returns Parsed JSON response body.
  */
-function needsCleanup(managedContent, userContent, threshold = DEFAULT_THRESHOLD) {
-    if (!userContent.trim())
-        return false;
-    return jaccard(shingles(managedContent), shingles(userContent)) > threshold;
+async function postJson(url, body) {
+    return fetchJson(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
 }
 
 /**
- * Strip foreign managed blocks from content.
+ * Tool result formatters for the OpenClaw plugin SDK.
  *
  * @remarks
- * Prevents cross-contamination by removing managed blocks that belong
- * to other marker sets. For example, when writing TOOLS.md with TOOLS
- * markers, any SOUL or AGENTS managed blocks found in the user content
- * zone are stripped — they don't belong there.
+ * Provides standardised helpers for building `ToolResult` objects:
+ * success, error, and connection-error variants.
+ */
+/**
+ * Format a successful tool result.
  *
- * @packageDocumentation
+ * @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) }],
+    };
+}
 /**
- * Build a regex that matches an entire managed block (BEGIN marker through END marker).
+ * Format an error tool result.
  *
- * @param markers - The marker set to match.
- * @returns A regex that matches the full block including markers.
+ * @param error - Error instance, string, or other value.
+ * @returns A `ToolResult` with `isError: true`.
  */
-function buildBlockPattern(markers) {
-    return new RegExp(`\\s*<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->[\\s\\S]*?<!--\\s*${escapeForRegex(markers.end)}\\s*-->\\s*`, 'g');
+function fail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: 'text', text: 'Error: ' + message }],
+        isError: true,
+    };
 }
 /**
- * Strip managed blocks belonging to foreign marker sets from content.
+ * Format a connection error with actionable guidance.
  *
- * @param content - The content to clean (typically user content zone).
- * @param currentMarkers - The marker set that owns this file (will NOT be stripped).
- * @returns Content with foreign managed blocks removed.
+ * @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 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 stripForeignMarkers(content, currentMarkers) {
-    let result = content;
-    for (const markers of ALL_MARKERS) {
-        // Skip the current file's own markers
-        if (markers.begin === currentMarkers.begin)
-            continue;
-        const pattern = buildBlockPattern(markers);
-        result = result.replace(pattern, '\n');
+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,
+        };
     }
-    // Clean up multiple blank lines left by removals
-    return result.replace(/\n{3,}/g, '\n\n').trim();
+    return fail(error);
 }
 
 /**
- * Generic managed-section writer with block and section modes.
+ * Factory for the standard plugin tool set.
  *
  * @remarks
- * Supports two modes:
- * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
- * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
+ * 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
  *
- * Provides file-level locking, version-stamp convergence, and atomic writes.
+ * Components add domain-specific tools separately.
  */
+/** Timeout for HTTP probes in milliseconds. */
+const PROBE_TIMEOUT_MS$1 = 5000;
 /**
- * Update a managed section in a file.
+ * Create the standard plugin tool set from a component descriptor.
  *
- * @param filePath - Absolute path to the target file.
- * @param content - New content to write.
- * @param options - Write mode and optional configuration.
+ * @param descriptor - The component descriptor.
+ * @returns Array of tool descriptors to register.
  */
-async function updateManagedSection(filePath, content, options = {}) {
-    const { mode = 'block', sectionId, markers = TOOLS_MARKERS, coreVersion = DEFAULT_CORE_VERSION, stalenessThresholdMs, } = options;
-    if (mode === 'section' && !sectionId) {
-        throw new Error('sectionId is required when mode is "section"');
-    }
-    const dir = dirname(filePath);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
-    // Create file if it doesn't exist
-    if (!existsSync(filePath)) {
-        writeFileSync(filePath, '', 'utf-8');
-    }
-    try {
-        await withFileLock(filePath, () => {
-            const fileContent = readFileSync(filePath, 'utf-8');
-            const parsed = parseManaged(fileContent, markers);
-            // Version-stamp convergence check (block mode only).
-            // In section mode, components always write their own sections — the version
-            // stamp governs shared content convergence, not component-specific sections.
-            if (mode === 'block' &&
-                !shouldWrite(coreVersion, parsed.versionStamp, stalenessThresholdMs)) {
-                return;
-            }
-            let newManagedBody;
-            if (mode === 'block') {
-                // Prepend H1 title if markers specify one
-                newManagedBody = markers.title
-                    ? `# ${markers.title}\n\n${content}`
-                    : content;
-            }
-            else {
-                // Section mode: upsert the named section
-                const sections = [...parsed.sections];
-                const existingIdx = sections.findIndex((s) => s.id === sectionId);
-                if (existingIdx >= 0) {
-                    sections[existingIdx] = { id: sectionId, content };
-                }
-                else {
-                    sections.push({ id: sectionId, content });
+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()}`);
                 }
-                sortSectionsByOrder(sections);
-                const sectionText = sections
-                    .map((s) => `## ${s.id}\n\n${s.content}`)
-                    .join('\n\n');
-                // Prepend H1 title if markers specify one
-                newManagedBody = markers.title
-                    ? `# ${markers.title}\n\n${sectionText}`
-                    : sectionText;
+                const data = await res.json();
+                return ok(data);
             }
-            // Build the full managed block
-            const beginLine = formatBeginMarker(markers.begin, coreVersion);
-            const endLine = formatEndMarker(markers.end);
-            // Combine all user content for cleanup detection
-            const rawUserContent = [parsed.beforeContent, parsed.userContent]
-                .filter(Boolean)
-                .join('\n\n')
-                .trim();
-            // Strip foreign managed blocks from user content (cross-contamination fix)
-            const userContent = stripForeignMarkers(rawUserContent, markers);
-            const cleanupNeeded = needsCleanup(newManagedBody, userContent);
-            const managedParts = [];
-            managedParts.push(beginLine);
-            if (cleanupNeeded) {
-                managedParts.push('');
-                managedParts.push(CLEANUP_FLAG);
+            catch (err) {
+                return connectionFail(err, baseUrl, `jeeves-${name}-openclaw`);
             }
-            managedParts.push('');
-            managedParts.push(newManagedBody);
-            managedParts.push('');
-            managedParts.push(endLine);
-            const managedBlock = managedParts.join('\n');
-            let newFileContent;
-            if (parsed.found) {
-                // Existing block: update in place — preserve position, don't move.
-                // Strip foreign managed blocks from both content zones (cross-contamination fix).
-                const cleanBefore = stripForeignMarkers(parsed.beforeContent, markers);
-                const cleanAfter = stripForeignMarkers(parsed.userContent, markers);
-                const fileParts = [];
-                if (cleanBefore) {
-                    fileParts.push(cleanBefore);
-                    fileParts.push('');
-                }
-                fileParts.push(managedBlock);
-                if (cleanAfter) {
-                    fileParts.push('');
-                    fileParts.push(cleanAfter);
-                }
-                fileParts.push('');
-                newFileContent = fileParts.join('\n');
+        },
+    };
+    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);
             }
-            else {
-                // No existing block: insert new block using the configured position.
-                // Strip orphaned same-type BEGIN markers from user content to prevent
-                // the parser from pairing them with the new END marker on the next cycle.
-                const orphanedBeginRe = new RegExp(`^<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$(?:\\r?\\n)?`, 'gm');
-                const cleanUserContent = userContent
-                    .replace(orphanedBeginRe, '')
-                    .replace(/\n{3,}/g, '\n\n')
-                    .trim();
-                const position = markers.position ?? 'top';
-                const fileParts = [];
-                if (position === 'bottom') {
-                    if (cleanUserContent) {
-                        fileParts.push(cleanUserContent);
-                        fileParts.push('');
-                    }
-                    fileParts.push(managedBlock);
-                }
-                else {
-                    fileParts.push(managedBlock);
-                    if (cleanUserContent) {
-                        fileParts.push('');
-                        fileParts.push(cleanUserContent);
-                    }
+            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 }));
                 }
-                fileParts.push('');
-                newFileContent = fileParts.join('\n');
+                // 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 }));
             }
-            atomicWrite(filePath, newFileContent);
-        });
+            catch (err) {
+                return Promise.resolve(fail(`Service ${action} failed: ${getErrorMessage(err)}`));
+            }
+        },
+    };
+    return [statusTool, configTool, configApplyTool, serviceTool];
+}
+
+/**
+ * Plugin resolution helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Provides workspace path resolution and plugin setting resolution
+ * with a standard three-step fallback chain:
+ * plugin config → environment variable → default value.
+ */
+/**
+ * Resolve the workspace root from the OpenClaw plugin API.
+ *
+ * @remarks
+ * Tries three sources in order:
+ * 1. `api.config.agents.defaults.workspace` — explicit config
+ * 2. `api.resolvePath('.')` — gateway-provided path resolver
+ * 3. `process.cwd()` — last resort
+ *
+ * @param api - The plugin API object provided by the gateway.
+ * @returns Absolute path to the workspace root.
+ */
+function resolveWorkspacePath(api) {
+    const configured = api.config?.agents?.defaults?.workspace;
+    if (typeof configured === 'string' && configured.trim()) {
+        return configured;
     }
-    catch (err) {
-        // Log warning but don't throw — writer cycles are periodic
-        console.warn(`jeeves-core: updateManagedSection failed for ${filePath}: ${getErrorMessage(err)}`);
+    if (typeof api.resolvePath === 'function') {
+        return api.resolvePath('.');
     }
+    return process.cwd();
 }
-
-var agentsSectionContent = `## "I'll Note This" Is Not Noting
-
+/**
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → fallback value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @param fallback - Default value if neither source provides one.
+ * @returns The resolved setting value.
+ */
+function resolvePluginSetting(api, pluginId, key, envVar, fallback) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return fallback;
+}
+/**
+ * Resolve an optional plugin setting via the two-step fallback chain:
+ * plugin config → environment variable. Returns `undefined` if neither
+ * source provides a value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @returns The resolved setting value, or `undefined`.
+ */
+function resolveOptionalPluginSetting(api, pluginId, key, envVar) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return undefined;
+}
+
+/**
+ * Similarity-based cleanup detection for orphaned managed content.
+ *
+ * @remarks
+ * Uses Jaccard similarity on 3-word shingles (Decision 22) to detect
+ * when orphaned managed content exists in the user content zone.
+ */
+/** Default similarity threshold for cleanup detection. */
+const DEFAULT_THRESHOLD = 0.15;
+/**
+ * Generate a set of n-word shingles from text.
+ *
+ * @param text - Input text.
+ * @param n - Shingle size (default 3).
+ * @returns Set of n-word shingles.
+ */
+function shingles(text, n = 3) {
+    const words = text.toLowerCase().split(/\s+/).filter(Boolean);
+    const set = new Set();
+    for (let i = 0; i <= words.length - n; i++) {
+        set.add(words.slice(i, i + n).join(' '));
+    }
+    return set;
+}
+/**
+ * Compute Jaccard similarity between two sets.
+ *
+ * @param a - First set.
+ * @param b - Second set.
+ * @returns Jaccard similarity coefficient (0 to 1).
+ */
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const item of a) {
+        if (b.has(item))
+            intersection++;
+    }
+    return intersection / (a.size + b.size - intersection);
+}
+/**
+ * Check whether user content contains orphaned managed content.
+ *
+ * @param managedContent - The current managed block content.
+ * @param userContent - Content below the END marker.
+ * @param threshold - Jaccard threshold (default 0.15).
+ * @returns `true` if cleanup is needed.
+ */
+function needsCleanup(managedContent, userContent, threshold = DEFAULT_THRESHOLD) {
+    if (!userContent.trim())
+        return false;
+    return jaccard(shingles(managedContent), shingles(userContent)) > threshold;
+}
+
+/**
+ * Strip foreign managed blocks from content.
+ *
+ * @remarks
+ * Prevents cross-contamination by removing managed blocks that belong
+ * to other marker sets. For example, when writing TOOLS.md with TOOLS
+ * markers, any SOUL or AGENTS managed blocks found in the user content
+ * zone are stripped — they don't belong there.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Build a regex that matches an entire managed block (BEGIN marker through END marker).
+ *
+ * @param markers - The marker set to match.
+ * @returns A regex that matches the full block including markers.
+ */
+function buildBlockPattern(markers) {
+    return new RegExp(`\\s*<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->[\\s\\S]*?<!--\\s*${escapeForRegex(markers.end)}\\s*-->\\s*`, 'g');
+}
+/**
+ * Strip managed blocks belonging to foreign marker sets from content.
+ *
+ * @param content - The content to clean (typically user content zone).
+ * @param currentMarkers - The marker set that owns this file (will NOT be stripped).
+ * @returns Content with foreign managed blocks removed.
+ */
+function stripForeignMarkers(content, currentMarkers) {
+    let result = content;
+    for (const markers of ALL_MARKERS) {
+        // Skip the current file's own markers
+        if (markers.begin === currentMarkers.begin)
+            continue;
+        const pattern = buildBlockPattern(markers);
+        result = result.replace(pattern, '\n');
+    }
+    // Clean up multiple blank lines left by removals
+    return result.replace(/\n{3,}/g, '\n\n').trim();
+}
+
+/**
+ * Generic managed-section writer with block and section modes.
+ *
+ * @remarks
+ * Supports two modes:
+ * - `block`: Replaces the entire managed block (SOUL.md, AGENTS.md).
+ * - `section`: Upserts a named H2 section within the managed block (TOOLS.md).
+ *
+ * Provides file-level locking, version-stamp convergence, and atomic writes.
+ */
+/**
+ * Update a managed section in a file.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param content - New content to write.
+ * @param options - Write mode and optional configuration.
+ */
+async function updateManagedSection(filePath, content, options = {}) {
+    const { mode = 'block', sectionId, markers = TOOLS_MARKERS, coreVersion = DEFAULT_CORE_VERSION, stalenessThresholdMs, } = options;
+    if (mode === 'section' && !sectionId) {
+        throw new Error('sectionId is required when mode is "section"');
+    }
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    // Create file if it doesn't exist
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, '', 'utf-8');
+    }
+    try {
+        await withFileLock(filePath, () => {
+            const fileContent = readFileSync(filePath, 'utf-8');
+            const parsed = parseManaged(fileContent, markers);
+            // Version-stamp convergence check (block mode only).
+            // In section mode, components always write their own sections — the version
+            // stamp governs shared content convergence, not component-specific sections.
+            if (mode === 'block' &&
+                !shouldWrite(coreVersion, parsed.versionStamp, stalenessThresholdMs)) {
+                return;
+            }
+            let newManagedBody;
+            if (mode === 'block') {
+                // Prepend H1 title if markers specify one
+                newManagedBody = markers.title
+                    ? `# ${markers.title}\n\n${content}`
+                    : content;
+            }
+            else {
+                // Section mode: upsert the named section
+                const sections = [...parsed.sections];
+                const existingIdx = sections.findIndex((s) => s.id === sectionId);
+                if (existingIdx >= 0) {
+                    sections[existingIdx] = { id: sectionId, content };
+                }
+                else {
+                    sections.push({ id: sectionId, content });
+                }
+                sortSectionsByOrder(sections);
+                const sectionText = sections
+                    .map((s) => `## ${s.id}\n\n${s.content}`)
+                    .join('\n\n');
+                // Prepend H1 title if markers specify one
+                newManagedBody = markers.title
+                    ? `# ${markers.title}\n\n${sectionText}`
+                    : sectionText;
+            }
+            // Build the full managed block
+            const beginLine = formatBeginMarker(markers.begin, coreVersion);
+            const endLine = formatEndMarker(markers.end);
+            // Combine all user content for cleanup detection
+            const rawUserContent = [parsed.beforeContent, parsed.userContent]
+                .filter(Boolean)
+                .join('\n\n')
+                .trim();
+            // Strip foreign managed blocks from user content (cross-contamination fix)
+            const userContent = stripForeignMarkers(rawUserContent, markers);
+            const cleanupNeeded = needsCleanup(newManagedBody, userContent);
+            const managedParts = [];
+            managedParts.push(beginLine);
+            if (cleanupNeeded) {
+                managedParts.push('');
+                managedParts.push(CLEANUP_FLAG);
+            }
+            managedParts.push('');
+            managedParts.push(newManagedBody);
+            managedParts.push('');
+            managedParts.push(endLine);
+            const managedBlock = managedParts.join('\n');
+            let newFileContent;
+            if (parsed.found) {
+                // Existing block: update in place — preserve position, don't move.
+                // Strip foreign managed blocks from both content zones (cross-contamination fix).
+                const cleanBefore = stripForeignMarkers(parsed.beforeContent, markers);
+                const cleanAfter = stripForeignMarkers(parsed.userContent, markers);
+                const fileParts = [];
+                if (cleanBefore) {
+                    fileParts.push(cleanBefore);
+                    fileParts.push('');
+                }
+                fileParts.push(managedBlock);
+                if (cleanAfter) {
+                    fileParts.push('');
+                    fileParts.push(cleanAfter);
+                }
+                fileParts.push('');
+                newFileContent = fileParts.join('\n');
+            }
+            else {
+                // No existing block: insert new block using the configured position.
+                // Strip orphaned same-type BEGIN markers from user content to prevent
+                // the parser from pairing them with the new END marker on the next cycle.
+                const orphanedBeginRe = new RegExp(`^<!--\\s*${escapeForRegex(markers.begin)}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$(?:\\r?\\n)?`, 'gm');
+                const cleanUserContent = userContent
+                    .replace(orphanedBeginRe, '')
+                    .replace(/\n{3,}/g, '\n\n')
+                    .trim();
+                const position = markers.position ?? 'top';
+                const fileParts = [];
+                if (position === 'bottom') {
+                    if (cleanUserContent) {
+                        fileParts.push(cleanUserContent);
+                        fileParts.push('');
+                    }
+                    fileParts.push(managedBlock);
+                }
+                else {
+                    fileParts.push(managedBlock);
+                    if (cleanUserContent) {
+                        fileParts.push('');
+                        fileParts.push(cleanUserContent);
+                    }
+                }
+                fileParts.push('');
+                newFileContent = fileParts.join('\n');
+            }
+            atomicWrite(filePath, newFileContent);
+        });
+    }
+    catch (err) {
+        // Log warning but don't throw — writer cycles are periodic
+        console.warn(`jeeves-core: updateManagedSection failed for ${filePath}: ${getErrorMessage(err)}`);
+    }
+}
+
+var agentsSectionContent = `## "I'll Note This" Is Not Noting
+
 **Never say "I'll note this" or "I'll add that."** It's a verbal tic that leads to nothing. If something is worth noting, **write it immediately, then confirm**.
 
 - Wrong: "I'll note this for the email path." → (conversation moves on, never written)
@@ -17308,1437 +17607,1138 @@ 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;
-    }
-}
+# 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
 
-/**
- * HEARTBEAT integration for memory hygiene.
- *
- * @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.
- */
-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'),
-    };
-}
+# Platform teardown (remove managed sections)
+npx @karmaniverous/jeeves uninstall
+\`\`\`
 
-/**
- * HEARTBEAT integration for workspace file size monitoring.
- *
- * @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.
- *
- * @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.
- *
- * @param results - Results from `checkWorkspaceFileHealth`.
- * @returns Array of `HeartbeatEntry` objects for files that exceed the
- *   warning threshold.
- */
-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,
-        };
-    });
-}
+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 -->
+`;
 
 /**
- * Core configuration schema and resolution.
+ * Internal function to maintain SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
  * @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
+ * 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`.
  */
-/** Zod schema for a service entry in core config. */
-const serviceEntrySchema = object({
-    /** Service URL (must be a valid URL). */
-    url: 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 = object({
-    /** JSON Schema pointer for IDE autocomplete. */
-    $schema: string().optional().describe('JSON Schema pointer'),
-    /** Owner identity keys (canonical identityLinks references). */
-    owners: array(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: string()
-        .default(DEFAULT_BIND_ADDRESS)
-        .describe('Bind address for all Jeeves services'),
-    /** Service URL overrides keyed by service name. */
-    services: record(string(), serviceEntrySchema)
-        .default({})
-        .describe('Service URL overrides'),
-    /** Registry cache configuration. */
-    registryCache: object({
-        /** Cache TTL in seconds for npm registry queries. */
-        ttlSeconds: number()
-            .int()
-            .positive()
-            .default(3600)
-            .describe('Cache TTL in seconds'),
-    })
-        .prefault({})
-        .describe('Registry cache settings'),
-});
 /**
- * Load and parse a config file, returning undefined if missing or invalid.
+ * Resolve the package's content directory for template file copying.
  *
- * @param configDir - Directory containing config.json.
- * @returns Parsed config or undefined.
+ * @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 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 {
+function getContentDir() {
+    const pkgDir = packageDirectorySync({
+        cwd: fileURLToPath(import.meta.url),
+    });
+    if (!pkgDir)
         return undefined;
-    }
+    const dir = join(pkgDir, 'content');
+    return existsSync(dir) ? dir : undefined;
 }
-
 /**
- * Service URL resolution.
- *
- * @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
- */
-/**
- * Resolve the URL for a named Jeeves service.
+ * Copy templates from content/templates/ to the core config directory.
  *
- * @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 coreConfigDir - Core config directory path.
  */
-function getServiceUrl$1(serviceName, consumerName) {
-    // 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)}`;
+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 });
     }
-    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
+    cpSync(sourceDir, destDir, { recursive: true });
 }
-
 /**
- * Registry version cache for npm package update awareness.
+ * Render the Platform template using simple string replacement.
  *
- * @remarks
- * Caches the latest npm registry version in a local JSON file
- * to avoid expensive `npm view` calls on every refresh cycle.
+ * @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;
+}
 /**
- * Check the npm registry for the latest version of a package.
+ * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
- * @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 options - Configuration for the refresh cycle.
  */
-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;
-            }
-        }
-        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;
+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);
 }
 
 /**
- * HEARTBEAT health orchestration.
+ * 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.
  *
- * @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.
+ * @param filePath - Managed file requiring cleanup.
+ * @param markerIdentity - Marker identity for the file.
+ * @returns Cleanup instructions for the spawned session.
  */
-/** Derive the full service name from a component name. */
-function toServiceName(name) {
-    return `jeeves-${name}`;
+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(' ');
 }
-/** 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;
 /**
- * Check if Qdrant is reachable (watcher dependency).
+ * Request a cleanup session from the OpenClaw gateway.
  *
- * @returns True if Qdrant responds.
+ * @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 isQdrantAvailable() {
+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 {
-        await fetchWithTimeout(`${QDRANT_URL}/collections`, PROBE_TIMEOUT_MS$1);
-        return true;
+        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;
     }
 }
+
 /**
- * Determine the state of a single component.
+ * Cleanup flag scanning extracted from ComponentWriter.cycle().
  *
- * @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
+ * 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.
  */
-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$1(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 && semverExports.gt(latestVersion, entry.pluginVersion)) {
-                return 'update_available';
+/**
+ * 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);
+                });
             }
         }
-        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';
+        catch {
+            // Best-effort: don't fail the cycle for escalation issues.
+        }
     }
 }
+
 /**
- * Generate the alert text for a component in a given state.
+ * Memory budget accounting and staleness detection for MEMORY.md.
  *
- * @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.
+ * @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).
  */
-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}`;
-}
+/** 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;
 /**
- * Orchestrate HEARTBEAT entries for all platform components.
+ * Extract the most recent ISO date from a string.
  *
- * @param options - Orchestration configuration.
- * @returns Array of HeartbeatEntry for writeHeartbeatSection.
+ * @param text - Text to scan for dates.
+ * @returns The most recent date found, or undefined.
  */
-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$1(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;
+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 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)
+    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;
-        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');
+        if (now - recentDate.getTime() > thresholdMs) {
+            staleSectionNames.push(sectionName);
         }
     }
-    return entries;
+    return {
+        exists: true,
+        charCount,
+        budget,
+        usage,
+        warning,
+        overBudget,
+        staleCandidates: staleSectionNames.length,
+        staleSectionNames,
+    };
 }
 
 /**
- * HEARTBEAT orchestration extracted from ComponentWriter.cycle().
+ * HEARTBEAT integration for memory hygiene.
  *
  * @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.
+ * 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';
 /**
- * Read a file's content, returning empty string if the file does not exist.
+ * Check memory health and return a HEARTBEAT entry if unhealthy.
  *
- * @param filePath - Absolute file path.
- * @returns File content or empty string.
+ * @param options - Memory hygiene options (workspacePath, budget, etc.).
+ * @returns A `HeartbeatEntry` when memory needs attention, `undefined` when healthy.
  */
-function readFileOrEmpty(filePath) {
-    try {
-        return readFileSync(filePath, 'utf-8');
+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 (err) {
-        if (err instanceof Error &&
-            'code' in err &&
-            err.code === 'ENOENT') {
-            return '';
-        }
-        throw err;
+    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'),
+    };
 }
+
 /**
- * Run a single HEARTBEAT orchestration cycle.
+ * HEARTBEAT integration for workspace file size monitoring.
  *
- * @param options - Heartbeat cycle configuration.
+ * @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.
+ *
+ * @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.
+ *
+ * @param results - Results from `checkWorkspaceFileHealth`.
+ * @returns Array of `HeartbeatEntry` objects for files that exceed the
+ *   warning threshold.
+ */
+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,
+        };
+    });
+}
+
+/**
+ * Core configuration schema and resolution.
+ *
+ * @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
+ */
+/** Zod schema for a service entry in core config. */
+const serviceEntrySchema = object({
+    /** Service URL (must be a valid URL). */
+    url: 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 = object({
+    /** JSON Schema pointer for IDE autocomplete. */
+    $schema: string().optional().describe('JSON Schema pointer'),
+    /** Owner identity keys (canonical identityLinks references). */
+    owners: array(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: string()
+        .default(DEFAULT_BIND_ADDRESS)
+        .describe('Bind address for all Jeeves services'),
+    /** Service URL overrides keyed by service name. */
+    services: record(string(), serviceEntrySchema)
+        .default({})
+        .describe('Service URL overrides'),
+    /** Registry cache configuration. */
+    registryCache: object({
+        /** Cache TTL in seconds for npm registry queries. */
+        ttlSeconds: number()
+            .int()
+            .positive()
+            .default(3600)
+            .describe('Cache TTL in seconds'),
+    })
+        .prefault({})
+        .describe('Registry cache settings'),
+});
+/**
+ * Load and parse a config file, returning undefined if missing or invalid.
+ *
+ * @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.
+ * Resolve the URL for a named Jeeves service.
  *
- * @remarks
- * Created via {@link createComponentWriter}. Manages a timer that fires
- * at the component's prime-interval, calling `generateToolsContent()`
- * and `refreshPlatformContent()` on each cycle.
+ * @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.
  */
-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$1(),
-            });
-        }
-        catch (err) {
-            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${getErrorMessage(err)}`);
-        }
+function getServiceUrl$1(serviceName, consumerName) {
+    // 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.
+ * HEARTBEAT health orchestration.
  *
  * @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.
+ * Determines the state of each platform component and generates
+ * HEARTBEAT entries with actionable alert text. Applies the dependency
+ * graph for alert suppression and auto-decline.
  */
+/** Derive the full service name from a component name. */
+function toServiceName(name) {
+    return `jeeves-${name}`;
+}
+/** Known dependency declarations for platform components. */
+const COMPONENT_DEPS = {
+    meta: { hard: ['watcher'], soft: [] },
+    server: { hard: [], soft: ['watcher', 'runner', 'meta'] },
+    runner: { hard: [], soft: [] },
+    watcher: { hard: [], soft: [] },
+};
+/** "Not installed" alert text for each platform component. Shared with seedContent. */
+const NOT_INSTALLED_ALERTS = {
+    runner: 'Not installed. The runner is the job execution engine — it runs scheduled scripts for data fetching, transformation, and maintenance. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-runner-openclaw install`.',
+    watcher: 'Not installed. The watcher indexes documents into a vector store for semantic search. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-watcher-openclaw install`.',
+    server: 'Not installed. The server provides a web UI for document browsing, rendering, sharing, and search. Ask the user for consent to install. On approval, execute: `npx @karmaniverous/jeeves-server-openclaw install`.',
+    meta: 'Not installed. Meta is the knowledge synthesis engine. Requires jeeves-watcher. Ask the user for consent to install. On approval, install watcher first if needed, then execute: `npx @karmaniverous/jeeves-meta-openclaw install`.',
+};
+/** Alert text generators by state. */
+const ALERT_TEXT = {
+    runner: {
+        not_installed: NOT_INSTALLED_ALERTS['runner'],
+        config_missing: (configRoot) => `Plugin installed but no configuration file found at \`${configRoot}/jeeves-runner/config.json\`. The plugin installer should have created a default config. Ask the user for consent to re-run the installer: \`npx @karmaniverous/jeeves-runner-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-runner service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-runner service start`. Verify via `GET http://127.0.0.1:1937/status`.',
+    },
+    watcher: {
+        not_installed: NOT_INSTALLED_ALERTS['watcher'],
+        deps_missing: 'Plugin installed but Qdrant is not responding on `http://127.0.0.1:6333`. Qdrant is the vector database required for semantic search. Ask the user for consent to set up Qdrant. Guide them through installation for their platform — Docker is simplest: `docker run -p 6333:6333 qdrant/qdrant`. Verify via `GET http://127.0.0.1:6333/collections`.',
+        config_missing: (configRoot) => `Plugin installed, Qdrant available, but config file missing or invalid at \`${configRoot}/jeeves-watcher/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-watcher-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-watcher service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-watcher service start`. Verify via `GET http://127.0.0.1:1936/status`.',
+    },
+    server: {
+        not_installed: NOT_INSTALLED_ALERTS['server'],
+        config_missing: (configRoot) => `Plugin installed but config file missing or invalid at \`${configRoot}/jeeves-server/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-server-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-server service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-server service start`. Verify via `GET http://127.0.0.1:1934/status`.',
+    },
+    meta: {
+        not_installed: NOT_INSTALLED_ALERTS['meta'],
+        deps_missing: 'Plugin installed but required dependency jeeves-watcher is not available. The watcher must be installed and running before meta can function. Do not attempt to set up meta until jeeves-watcher is healthy.',
+        config_missing: (configRoot) => `Plugin installed, watcher available, but config file missing or invalid at \`${configRoot}/jeeves-meta/config.json\`. The plugin installer should have created a default config. If missing, re-run: \`npx @karmaniverous/jeeves-meta-openclaw install\`.`,
+        service_not_installed: 'Plugin installed and configured but the system service is not installed. Ask the user for consent. On approval, execute: `jeeves-meta service install`. Verify the service is installed.',
+        service_stopped: 'Service installed but not running. Ask the user for consent. On approval, execute: `jeeves-meta service start`. Verify via `GET http://127.0.0.1:1938/status`.',
+    },
+};
+/** Default Qdrant URL for watcher dependency check. */
+const QDRANT_URL = 'http://127.0.0.1:6333';
+/** Health probe timeout in milliseconds. */
+const PROBE_TIMEOUT_MS = 3000;
 /**
- * Create a ComponentWriter for a validated component descriptor.
+ * Check if Qdrant is reachable (watcher dependency).
  *
- * @remarks
- * The descriptor is validated via the Zod schema at runtime.
- * This replaces the v0.4.0 `createComponentWriter(JeevesComponent)`.
+ * @returns True if Qdrant responds.
+ */
+async function isQdrantAvailable() {
+    try {
+        await fetchWithTimeout(`${QDRANT_URL}/collections`, PROBE_TIMEOUT_MS);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Determine the state of a single component.
  *
- * @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.
+ * @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 createComponentWriter(descriptor, options) {
-    // Validate via Zod — throws ZodError with detailed messages on failure
-    jeevesComponentDescriptorSchema.parse(descriptor);
-    return new ComponentWriter(descriptor, options);
+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$1(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 && semverExports.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';
+    }
 }
-
 /**
- * Tool result formatters for the OpenClaw plugin SDK.
+ * Generate the alert text for a component in a given state.
  *
- * @remarks
- * Provides standardised helpers for building `ToolResult` objects:
- * success, error, and connection-error variants.
+ * @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 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}`;
+}
 /**
- * Format a successful tool result.
+ * Orchestrate HEARTBEAT entries for all platform components.
  *
- * @param data - Arbitrary data to return as JSON.
- * @returns A `ToolResult` with JSON-stringified content.
+ * @param options - Orchestration configuration.
+ * @returns Array of HeartbeatEntry for writeHeartbeatSection.
  */
-function ok(data) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-    };
+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$1(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;
 }
+
 /**
- * Format an error tool result.
+ * HEARTBEAT orchestration extracted from ComponentWriter.cycle().
  *
- * @param error - Error instance, string, or other value.
- * @returns A `ToolResult` with `isError: true`.
+ * @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.
  */
-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.
+ * Read a file's content, returning empty string if the file does not exist.
  *
- * @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 filePath - Absolute file path.
+ * @returns File content or empty string.
  */
-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,
-        };
+function readFileOrEmpty(filePath) {
+    try {
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err instanceof Error &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return '';
+        }
+        throw err;
     }
-    return fail(error);
 }
-
-/**
- * Factory for the standard plugin tool set.
- *
- * @remarks
- * Produces four standard tools from a component descriptor:
- * - `{name}_status` - Probe service health + version + uptime
- * - `{name}_config` - Query running config with optional JSONPath
- * - `{name}_config_apply` - Push config patch to running service
- * - `{name}_service` - Service lifecycle management
- *
- * Components add domain-specific tools separately.
- */
-/** Timeout for HTTP probes in milliseconds. */
-const PROBE_TIMEOUT_MS = 5000;
 /**
- * Create the standard plugin tool set from a component descriptor.
+ * Run a single HEARTBEAT orchestration cycle.
  *
- * @param descriptor - The component descriptor.
- * @returns Array of tool descriptors to register.
+ * @param options - Heartbeat cycle configuration.
  */
-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();
-                    },
-                    restart: () => {
-                        svcManager.restart();
-                    },
-                };
-                methodMap[action]();
-                return Promise.resolve(ok({ service: name, action, success: 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: '' });
             }
-            catch (err) {
-                return Promise.resolve(fail(`Service ${action} failed: ${getErrorMessage(err)}`));
+            else {
+                entries.push(alert);
             }
-        },
-    };
-    return [statusTool, configTool, configApplyTool, serviceTool];
+        }
+        await writeHeartbeatSection(heartbeatPath, entries);
+    }
+    catch (err) {
+        console.warn(`jeeves-core: HEARTBEAT orchestration failed: ${getErrorMessage(err)}`);
+    }
 }
 
 /**
- * Plugin resolution helpers for the OpenClaw plugin SDK.
+ * Timer-based orchestrator for managed content writing.
  *
  * @remarks
- * Provides workspace path resolution and plugin setting resolution
- * with a standard three-step fallback chain:
- * plugin config → environment variable → default value.
+ * `ComponentWriter` manages a component's TOOLS.md section writes
+ * and platform content maintenance (SOUL.md, AGENTS.md, Platform section)
+ * on a configurable prime-interval timer cycle.
  */
 /**
- * Resolve the workspace root from the OpenClaw plugin API.
+ * Orchestrates managed content writing for a single Jeeves component.
  *
  * @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.
+ * Created via {@link createComponentWriter}. Manages a timer that fires
+ * at the component's prime-interval, calling `generateToolsContent()`
+ * and `refreshPlatformContent()` on each cycle.
  */
-function resolveWorkspacePath(api) {
-    const configured = api.config?.agents?.defaults?.workspace;
-    if (typeof configured === 'string' && configured.trim()) {
-        return configured;
+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;
     }
-    if (typeof api.resolvePath === 'function') {
-        return api.resolvePath('.');
+    /** 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$1(),
+            });
+        }
+        catch (err) {
+            console.warn(`jeeves-core: ComponentWriter cycle failed for ${this.component.name}: ${getErrorMessage(err)}`);
+        }
     }
-    return process.cwd();
 }
+
 /**
- * Resolve a plugin setting via the standard three-step fallback chain:
- * plugin config → environment variable → fallback value.
+ * Creates a synchronous content accessor backed by an async data source.
  *
- * @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
+ * 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,
+ * });
+ * ```
  */
-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;
+/**
+ * Creates a synchronous content accessor backed by an async data source.
+ *
+ * @param options - Cache configuration.
+ * @returns A sync `() => string` suitable for `generateToolsContent`.
+ */
+function createAsyncContentCache(options) {
+    const { fetch: fetchContent, placeholder = '> Initializing...', onError = (err) => {
+        console.warn('[jeeves] async content cache refresh failed:', err);
+    }, } = options;
+    let cached = placeholder;
+    let refreshing = false;
+    return () => {
+        if (!refreshing) {
+            refreshing = true;
+            fetchContent()
+                .then((content) => {
+                cached = content;
+            })
+                .catch(onError)
+                .finally(() => {
+                refreshing = false;
+            });
+        }
+        return cached;
+    };
 }
+
 /**
- * Resolve an optional plugin setting via the two-step fallback chain:
- * plugin config → environment variable. Returns `undefined` if neither
- * source provides a value.
+ * Factory function for creating a ComponentWriter from a descriptor.
  *
- * @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
+ * 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.
  */
-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;
+/**
+ * Create a ComponentWriter for a validated component descriptor.
+ *
+ * @remarks
+ * The descriptor is validated via the Zod schema at runtime.
+ * This replaces the v0.4.0 `createComponentWriter(JeevesComponent)`.
+ *
+ * @param descriptor - The component descriptor to validate and wrap.
+ * @param options - Optional writer configuration (e.g., gatewayUrl for cleanup escalation).
+ * @returns A new `ComponentWriter` instance.
+ * @throws ZodError if the descriptor is invalid.
+ */
+function createComponentWriter(descriptor, options) {
+    // Validate via Zod — throws ZodError with detailed messages on failure
+    jeevesComponentDescriptorSchema.parse(descriptor);
+    return new ComponentWriter(descriptor, options);
 }
 
 /**