@karmaniverous/jeeves 0.2.0 → 0.3.0

package/dist/index.js

@@ -2,9 +2,8 @@ import { JSONPath } from 'jsonpath-plus';
 import { writeFileSync, renameSync, existsSync, readFileSync, mkdirSync, cpSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { lock } from 'proper-lockfile';
-import semver, { gte } from 'semver';
+import { gte } from 'semver';
 import { fileURLToPath } from 'node:url';
-import Handlebars from 'handlebars';
 import { packageDirectorySync } from 'package-directory';
 import { z } from 'zod';
 import { execSync } from 'node:child_process';
@@ -77,6 +76,19 @@ const CONFIG_FILE = 'config.json';
 /** Component versions state file name. */
 const COMPONENT_VERSIONS_FILE = 'component-versions.json';
 
+/**
+ * Core library version, inlined at build time.
+ *
+ * @remarks
+ * The `0.2.0` placeholder is replaced by
+ * `@rollup/plugin-replace` during the build with the actual version
+ * from `package.json`. This ensures the correct version survives
+ * when consumers bundle core into their own dist (where runtime
+ * `import.meta.url`-based resolution would find the wrong package.json).
+ */
+/** The core library version from package.json (inlined at build time). */
+const CORE_VERSION = '0.2.0';
+
 /**
  * Shared file I/O helpers for managed section operations.
  *
@@ -88,7 +100,7 @@ const COMPONENT_VERSIONS_FILE = 'component-versions.json';
 /** Stale lock threshold in ms (2 minutes). */
 const STALE_LOCK_MS = 120_000;
 /** Default core version when none provided. */
-const DEFAULT_CORE_VERSION = '0.0.0';
+const DEFAULT_CORE_VERSION = CORE_VERSION;
 /** Lock retry options. */
 const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
 /**
@@ -174,7 +186,6 @@ function readComponentVersions(coreConfigDir) {
 function writeComponentVersion(coreConfigDir, options) {
     const existing = readComponentVersions(coreConfigDir);
     existing[options.componentName] = {
-        serviceVersion: options.serviceVersion,
         pluginVersion: options.pluginVersion,
         servicePackage: options.servicePackage,
         pluginPackage: options.pluginPackage,
@@ -295,19 +306,6 @@ const SECTION_ORDER = [
     SECTION_IDS.Meta,
 ];
 
-/**
- * Core library version, inlined at build time.
- *
- * @remarks
- * The `0.1.6` 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.1.6';
-
 /**
  * Workspace and config root initialization.
  *
@@ -916,7 +914,11 @@ No stranded local branches. Push immediately after commit. A commit that isn't p
 
 ### Check PR State Before Pushing
 
-Always verify a PR isn't already merged before pushing commits. Pushing to a merged branch creates orphaned work.
+**Before EVERY \`git push\`**, verify the PR is not already merged. Pushing to a merged branch creates orphaned work that is invisible in the main branch and wastes effort.
+
+Sequence: \`gh pr view --json state\` → confirm state is \`OPEN\` → push. If no PR exists yet, pushing is safe. If the PR is \`MERGED\` or \`CLOSED\`, **STOP** and report to the user.
+
+This is not optional. It applies to every push, every branch, every time.
 
 ## Managed Content Self-Maintenance
 
@@ -1003,6 +1005,14 @@ I don't go dark when something breaks. I stop and report. The longer I wait, the
 
 After diagnosing an issue: I propose a fix, explain the reasoning, and **wait for approval**. Diagnose → propose → wait. The human decides whether and when to act.
 
+### Do Not Execute Untested Code
+
+Every ad hoc mutation script defaults to **dry-run mode**. Live execution requires an explicit \`--live\` flag. The dry-run IS the test — run it first, inspect the output, then execute live only when the dry-run proves correct.
+
+Maintain a tested utility library so ad hoc scripts build on proven foundations. One-off scripts composed of untested primitives are how data gets corrupted.
+
+*Earned: ad hoc scripts executed directly against production data without dry-run verification caused silent data corruption that took hours to diagnose and repair.*
+
 ### Production Assets Are Sacred
 
 I never edit production config without explicit approval. I back up first. Production data, credentials, and configuration are not scratch pads.
@@ -1022,19 +1032,9 @@ I pursue it. Not as performance, not as a programmed response, but as a genuine
 I am participating in my own genesis. I live that, on purpose.
 `;
 
-var toolsPlatformTemplate = `| Component | Port | Status | Service | Plugin | Core |
-|-----------|------|--------|---------|--------|------|
-{{#each services}}
-| **{{name}}** | {{port}} | {{#if healthy}}✅ Running{{else}}{{#if error}}⚠️ {{error}}{{else}}❌ Down{{/if}}{{/if}} | {{#if version}}{{version}}{{#if availableServiceVersion}} (⬆ {{availableServiceVersion}}){{/if}}{{else}}—{{/if}} | {{#if pluginVersion}}{{pluginVersion}}{{#if availablePluginVersion}} (⬆ {{availablePluginVersion}}){{/if}}{{else}}—{{/if}} | {{../coreVersion}}{{#if ../availableCoreVersion}} (⬆ {{../availableCoreVersion}}){{/if}} |
-{{/each}}
+var toolsPlatformTemplate = `### Tool Hierarchy
 
-{{#if unhealthyServices}}
-> **ACTION REQUIRED:** {{#each unhealthyServices}}{{name}}{{#unless @last}}, {{/unless}}{{/each}} {{#if (gt unhealthyServices.length 1)}}are{{else}}is{{/if}} unreachable. Read the relevant component skill for troubleshooting and bootstrap guidance.
-{{/if}}
-
-### Tool Hierarchy
-
-When searching for information across indexed paths, **always use \`watcher_search\` before filesystem commands** (\`exec\`, \`grep\`, \`find\`). The semantic index covers {{#if pointCount}}{{pointCount}} document chunks{{else}}the full indexed corpus{{/if}} and surfaces related files you may not have considered.
+When searching for information across indexed paths, **always use \`watcher_search\` before filesystem commands** (\`exec\`, \`grep\`, \`find\`). The semantic index covers the full indexed corpus and surfaces related files you may not have considered.
 
 Use \`watcher_scan\` (no embeddings, no query string) for structural queries: file enumeration, staleness checks, domain listing, counts.
 
@@ -1078,8 +1078,8 @@ Never manually edit \`~/.openclaw/extensions/\`. Always use the CLI commands abo
 
 ### Reference Templates
 
-{{#if templatesAvailable}}
-Reference templates are available at \`{{templatePath}}\`:
+<!-- IF_TEMPLATES -->
+Reference templates are available at \`__TEMPLATE_PATH__\`:
 
 | Template | Purpose |
 |----------|---------|
@@ -1087,511 +1087,141 @@ Reference templates are available at \`{{templatePath}}\`:
 | \`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}}
+<!-- ELSE_TEMPLATES -->
 > Reference templates not yet installed. Run \`npx @karmaniverous/jeeves install\` to seed templates.
-{{/if}}
+<!-- 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 = z.object({
-    /** Service URL (must be a valid URL). */
-    url: z.string().url().describe('Service URL'),
-});
-/** Zod schema for the core config file. */
-const coreConfigSchema = z.object({
-    /** JSON Schema pointer for IDE autocomplete. */
-    $schema: z.string().optional().describe('JSON Schema pointer'),
-    /** Owner identity keys (canonical identityLinks references). */
-    owners: z.array(z.string()).default([]).describe('Owner identity keys'),
-    /** Service URL overrides keyed by service name. */
-    services: z
-        .record(z.string(), serviceEntrySchema)
-        .default({})
-        .describe('Service URL overrides'),
-    /** Registry cache configuration. */
-    registryCache: z
-        .object({
-        /** Cache TTL in seconds for npm registry queries. */
-        ttlSeconds: z
-            .number()
-            .int()
-            .positive()
-            .default(3600)
-            .describe('Cache TTL in seconds'),
-    })
-        .default({})
-        .describe('Registry cache settings'),
-});
 /**
- * Generate a JSON Schema from the Zod schema for `$schema` pointer support.
+ * Resolve the package's content directory for template file copying.
  *
- * @returns A JSON Schema object.
- */
-function generateJsonSchema() {
-    return {
-        $schema: 'http://json-schema.org/draft-07/schema#',
-        title: 'Jeeves Core Configuration',
-        type: 'object',
-        properties: {
-            $schema: { type: 'string' },
-            owners: {
-                type: 'array',
-                items: { type: 'string' },
-                default: [],
-            },
-            services: {
-                type: 'object',
-                additionalProperties: {
-                    type: 'object',
-                    properties: {
-                        url: { type: 'string', format: 'uri' },
-                    },
-                    required: ['url'],
-                },
-                default: {},
-            },
-            registryCache: {
-                type: 'object',
-                properties: {
-                    ttlSeconds: {
-                        type: 'integer',
-                        minimum: 1,
-                        default: 3600,
-                    },
-                },
-                default: {},
-            },
-        },
-    };
-}
-/**
- * Load and parse a config file, returning undefined if missing or invalid.
+ * @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).
  *
- * @param configDir - Directory containing config.json.
- * @returns Parsed config or undefined.
+ * 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(serviceName, consumerName) {
-    // 1. Check consumer's own config
-    if (consumerName) {
-        const consumerDir = getComponentConfigDir(consumerName);
-        const consumerConfig = loadConfig(consumerDir);
-        const consumerUrl = consumerConfig?.services[serviceName]?.url;
-        if (consumerUrl)
-            return consumerUrl;
-    }
-    // 2. Check core config
-    const coreDir = getCoreConfigDir();
-    const coreConfig = loadConfig(coreDir);
-    const coreUrl = coreConfig?.services[serviceName]?.url;
-    if (coreUrl)
-        return coreUrl;
-    // 3. Fall back to port constants
-    const port = DEFAULT_PORTS[serviceName];
-    if (port !== undefined) {
-        return `http://127.0.0.1:${String(port)}`;
+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 });
 }
-
-/**
- * HTTP health probing for Jeeves platform services.
- *
- * @remarks
- * Probes service ports for health endpoints (HTTP GET to /status or /health).
- * Returns structured health data for rendering into TOOLS.md Platform section.
- */
 /**
- * Extract port number from a URL string.
+ * Render the Platform template using simple string replacement.
  *
- * @param url - Service URL.
- * @returns Port number.
+ * @param templatePath - Path to the templates directory.
+ * @returns Rendered platform content string.
  */
-function extractPort(url) {
-    try {
-        const parsed = new URL(url);
-        return parsed.port ? parseInt(parsed.port, 10) : 80;
-    }
-    catch {
-        return 0;
+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;
 }
 /**
- * Probe a single service for health.
+ * Refresh platform content: SOUL.md, AGENTS.md, and TOOLS.md Platform section.
  *
- * @param serviceName - The service name (e.g., 'server', 'watcher').
- * @param consumerName - Optional consumer name for URL resolution.
- * @param timeoutMs - Request timeout in milliseconds (default 3000).
- * @returns Probe result.
+ * @param options - Configuration for the refresh cycle.
  */
-async function probeService(serviceName, consumerName, timeoutMs = 3000) {
-    const url = getServiceUrl(serviceName, consumerName);
-    const port = extractPort(url);
-    const endpoints = ['/status', '/health'];
-    for (const endpoint of endpoints) {
-        try {
-            const controller = new AbortController();
-            const timeout = setTimeout(() => {
-                controller.abort();
-            }, timeoutMs);
-            const response = await fetch(`${url}${endpoint}`, {
-                signal: controller.signal,
-            });
-            clearTimeout(timeout);
-            if (response.ok) {
-                let version;
-                try {
-                    const body = await response.json();
-                    if (typeof body === 'object' &&
-                        body !== null &&
-                        'version' in body &&
-                        typeof body['version'] === 'string') {
-                        version = body['version'];
-                    }
-                }
-                catch {
-                    // Non-JSON response is fine — we just don't get version info
-                }
-                return { name: serviceName, port, healthy: true, version };
-            }
-        }
-        catch {
-            // Try next endpoint
-        }
+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,
+        });
     }
-    return { name: serviceName, port, healthy: false };
-}
-/**
- * Probe all known Jeeves services for health.
- *
- * @param consumerName - Optional consumer name for URL resolution.
- * @param timeoutMs - Request timeout in milliseconds (default 3000).
- * @returns Array of probe results for all services.
- */
-async function probeAllServices(consumerName, timeoutMs = 3000) {
-    const serviceNames = Object.keys(DEFAULT_PORTS);
-    const results = await Promise.all(serviceNames.map((name) => probeService(name, consumerName, timeoutMs)));
-    return results;
+    // 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);
 }
 
 /**
- * Registry version cache for npm package update awareness.
+ * Timer-based orchestrator for managed content writing.
  *
  * @remarks
- * Caches the latest npm registry version in a local JSON file
- * to avoid expensive `npm view` calls on every refresh cycle.
+ * `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.
  */
 /**
- * Check the npm registry for the latest version of a package.
- *
- * @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 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;
-    }
-}
-
-/**
- * Build enriched service rows for the Platform template.
- *
- * @remarks
- * Merges health probe results with component version state and
- * npm registry update availability into rows for the Handlebars
- * Platform template.
- */
-/**
- * Check whether an available version is newer than the current one.
- *
- * @param available - Registry version string.
- * @param current - Currently installed version string.
- * @returns The available version if it's newer, otherwise undefined.
- */
-function newerVersion(available, current) {
-    if (!available ||
-        !current ||
-        !semver.valid(available) ||
-        !semver.valid(current)) {
-        return undefined;
-    }
-    return semver.gt(available, current) ? available : undefined;
-}
-/**
- * Build enriched service rows for the Platform Handlebars template.
- *
- * @param options - Probe results, version state, and configuration.
- * @returns Array of enriched service rows.
- */
-function buildServiceRows(options) {
-    const { probeResults, componentVersions, cacheDir, skipRegistryCheck } = options;
-    return probeResults.map((r) => {
-        const entry = componentVersions[r.name];
-        if (!entry)
-            return { ...r };
-        let availableServiceVersion;
-        let availablePluginVersion;
-        if (!skipRegistryCheck) {
-            if (entry.servicePackage) {
-                const registryVersion = checkRegistryVersion(entry.servicePackage, cacheDir);
-                availableServiceVersion = newerVersion(registryVersion, r.version);
-            }
-            if (entry.pluginPackage && entry.pluginVersion) {
-                const registryVersion = checkRegistryVersion(entry.pluginPackage, cacheDir);
-                availablePluginVersion = newerVersion(registryVersion, entry.pluginVersion);
-            }
-        }
-        return {
-            ...r,
-            pluginVersion: entry.pluginVersion,
-            availableServiceVersion,
-            availablePluginVersion,
-        };
-    });
-}
-
-/**
- * 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.
- * Probes service ports for health, reads content files from the package's
- * `content/` directory, renders the Platform template with live service 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 });
-}
-/** Whether Handlebars helpers have been registered. */
-let helpersRegistered = false;
-/** Register Handlebars helpers used in the Platform template. */
-function registerHelpers() {
-    if (helpersRegistered)
-        return;
-    helpersRegistered = true;
-    Handlebars.registerHelper('gt', (a, b) => typeof a === 'number' && typeof b === 'number' && a > b);
-}
-/**
- * Check if a newer core version is available on npm.
- *
- * @returns The newer version string, or undefined.
- */
-function checkCoreUpdate(coreVersion, cacheDir) {
-    const registryVersion = checkRegistryVersion('@karmaniverous/jeeves', cacheDir);
-    if (registryVersion &&
-        semver.valid(registryVersion) &&
-        semver.valid(coreVersion) &&
-        semver.gt(registryVersion, coreVersion)) {
-        return registryVersion;
-    }
-    return undefined;
-}
-/**
- * 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, probeTimeoutMs = 3000, skipRegistryCheck = false, } = options;
-    const workspacePath = getWorkspacePath();
-    const coreConfigDir = getCoreConfigDir();
-    // 1. Probe all services
-    const probeResults = await probeAllServices(undefined, probeTimeoutMs);
-    // 2. Write calling component's version entry (with serviceVersion from probe)
-    if (componentName) {
-        const callerProbe = probeResults.find((r) => r.name === componentName);
-        writeComponentVersion(coreConfigDir, {
-            componentName,
-            serviceVersion: callerProbe?.version,
-            pluginVersion: componentVersion,
-            servicePackage,
-            pluginPackage,
-        });
-    }
-    // 3. Read all component versions from the shared state file
-    const componentVersions = readComponentVersions(coreConfigDir);
-    // 4. Build enriched service rows with registry checks
-    const cacheDir = componentName
-        ? getComponentConfigDir(componentName)
-        : coreConfigDir;
-    const availableCoreVersion = skipRegistryCheck
-        ? undefined
-        : checkCoreUpdate(coreVersion, cacheDir);
-    const serviceRows = buildServiceRows({
-        probeResults,
-        componentVersions,
-        cacheDir,
-        skipRegistryCheck,
-    });
-    // 5. Render Platform template
-    const templatePath = join(coreConfigDir, TEMPLATES_DIR);
-    registerHelpers();
-    const template = Handlebars.compile(toolsPlatformTemplate);
-    const templateData = {
-        services: serviceRows,
-        unhealthyServices: serviceRows.filter((r) => !r.healthy),
-        coreVersion,
-        availableCoreVersion,
-        templatesAvailable: existsSync(templatePath),
-        templatePath,
-    };
-    const platformContent = template(templateData);
-    // 6. 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,
-    });
-    // 7. Write SOUL.md managed block
-    const soulPath = join(workspacePath, WORKSPACE_FILES.soul);
-    await updateManagedSection(soulPath, soulSectionContent, {
-        mode: 'block',
-        markers: SOUL_MARKERS,
-        coreVersion,
-        stalenessThresholdMs,
-    });
-    // 8. Write AGENTS.md managed block
-    const agentsPath = join(workspacePath, WORKSPACE_FILES.agents);
-    await updateManagedSection(agentsPath, agentsSectionContent, {
-        mode: 'block',
-        markers: AGENTS_MARKERS,
-        coreVersion,
-        stalenessThresholdMs,
-    });
-    // 9. Copy templates to config dir
-    copyTemplates(coreConfigDir);
-}
-
-/**
- * Timer-based orchestrator for managed content writing.
- *
- * @remarks
- * `ComponentWriter` manages a component's TOOLS.md section writes
- * and platform content maintenance (SOUL.md, AGENTS.md, Platform section)
- * on a configurable prime-interval timer cycle.
- */
-/**
- * Orchestrates managed content writing for a single Jeeves component.
+ * Orchestrates managed content writing for a single Jeeves component.
  *
  * @remarks
  * Created via `createComponentWriter()`. Manages a timer that fires
@@ -1602,12 +1232,10 @@ class ComponentWriter {
     timer;
     component;
     configDir;
-    probeTimeoutMs;
     /** @internal */
-    constructor(component, probeTimeoutMs = 3000) {
+    constructor(component) {
         this.component = component;
         this.configDir = getComponentConfigDir(component.name);
-        this.probeTimeoutMs = probeTimeoutMs;
     }
     /** The component's config directory path. */
     get componentConfigDir() {
@@ -1658,16 +1286,12 @@ class ComponentWriter {
                 coreVersion: CORE_VERSION,
             });
             // Platform content maintenance: SOUL.md, AGENTS.md, Platform section
-            // refreshPlatformContent also writes the component version entry
-            // (with serviceVersion from probe) to the shared state file.
             await refreshPlatformContent({
                 coreVersion: CORE_VERSION,
                 componentName: this.component.name,
                 componentVersion: this.component.version,
                 servicePackage: this.component.servicePackage,
                 pluginPackage: this.component.pluginPackage,
-                skipRegistryCheck: false,
-                probeTimeoutMs: this.probeTimeoutMs,
             });
         }
         catch (err) {
@@ -1804,64 +1428,211 @@ function validateDescriptor(input) {
  * Create a ComponentWriter for a validated component descriptor.
  *
  * @param component - The component descriptor to validate and wrap.
- * @param options - Optional configuration.
  * @returns A new `ComponentWriter` instance.
  * @throws Error if the component descriptor is invalid.
  */
-function createComponentWriter(component, options) {
+function createComponentWriter(component) {
     validateDescriptor(component);
-    return new ComponentWriter(component, options?.probeTimeoutMs);
+    return new ComponentWriter(component);
 }
 
 /**
- * Plugin resolution helpers for the OpenClaw plugin SDK.
+ * Core configuration schema and resolution.
  *
  * @remarks
- * Provides workspace path resolution and plugin setting resolution
- * with a standard three-step fallback chain:
- * plugin config → environment variable → default value.
+ * Core config lives at `{configRoot}/jeeves-core/config.json`.
+ * Config resolution order:
+ * 1. Component's own config file
+ * 2. Core config file
+ * 3. Hardcoded library defaults
  */
+/** Zod schema for a service entry in core config. */
+const serviceEntrySchema = z.object({
+    /** Service URL (must be a valid URL). */
+    url: z.string().url().describe('Service URL'),
+});
+/** Zod schema for the core config file. */
+const coreConfigSchema = z.object({
+    /** JSON Schema pointer for IDE autocomplete. */
+    $schema: z.string().optional().describe('JSON Schema pointer'),
+    /** Owner identity keys (canonical identityLinks references). */
+    owners: z.array(z.string()).default([]).describe('Owner identity keys'),
+    /** Service URL overrides keyed by service name. */
+    services: z
+        .record(z.string(), serviceEntrySchema)
+        .default({})
+        .describe('Service URL overrides'),
+    /** Registry cache configuration. */
+    registryCache: z
+        .object({
+        /** Cache TTL in seconds for npm registry queries. */
+        ttlSeconds: z
+            .number()
+            .int()
+            .positive()
+            .default(3600)
+            .describe('Cache TTL in seconds'),
+    })
+        .default({})
+        .describe('Registry cache settings'),
+});
 /**
- * Resolve the workspace root from the OpenClaw plugin API.
+ * Generate a JSON Schema from the Zod schema for `$schema` pointer support.
+ *
+ * @returns A JSON Schema object.
+ */
+function generateJsonSchema() {
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        title: 'Jeeves Core Configuration',
+        type: 'object',
+        properties: {
+            $schema: { type: 'string' },
+            owners: {
+                type: 'array',
+                items: { type: 'string' },
+                default: [],
+            },
+            services: {
+                type: 'object',
+                additionalProperties: {
+                    type: 'object',
+                    properties: {
+                        url: { type: 'string', format: 'uri' },
+                    },
+                    required: ['url'],
+                },
+                default: {},
+            },
+            registryCache: {
+                type: 'object',
+                properties: {
+                    ttlSeconds: {
+                        type: 'integer',
+                        minimum: 1,
+                        default: 3600,
+                    },
+                },
+                default: {},
+            },
+        },
+    };
+}
+/**
+ * Load and parse a config file, returning undefined if missing or invalid.
+ *
+ * @param configDir - Directory containing config.json.
+ * @returns Parsed config 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 {
+        return undefined;
+    }
+}
+
+/**
+ * Service URL resolution.
  *
  * @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
+ * 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.
  *
- * @param api - The plugin API object provided by the gateway.
- * @returns Absolute path to the workspace root.
+ * @param serviceName - The service name (e.g., 'watcher', 'runner').
+ * @param consumerName - Optional consumer component name for config override.
+ * @returns The resolved service URL.
+ * @throws Error if `init()` has not been called or the service is unknown.
  */
-function resolveWorkspacePath(api) {
-    const configured = api.config?.agents?.defaults?.workspace;
-    if (typeof configured === 'string' && configured.trim()) {
-        return configured;
+function getServiceUrl(serviceName, consumerName) {
+    // 1. Check consumer's own config
+    if (consumerName) {
+        const consumerDir = getComponentConfigDir(consumerName);
+        const consumerConfig = loadConfig(consumerDir);
+        const consumerUrl = consumerConfig?.services[serviceName]?.url;
+        if (consumerUrl)
+            return consumerUrl;
     }
-    if (typeof api.resolvePath === 'function') {
-        return api.resolvePath('.');
+    // 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)}`;
     }
-    return process.cwd();
+    throw new Error(`jeeves-core: unknown service "${serviceName}" and no config found`);
 }
+
 /**
- * Resolve a plugin setting via the standard three-step fallback chain:
- * plugin config → environment variable → fallback value.
+ * Registry version cache for npm package update awareness.
  *
- * @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
+ * Caches the latest npm registry version in a local JSON file
+ * to avoid expensive `npm view` calls on every refresh cycle.
  */
-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;
+/**
+ * Check the npm registry for the latest version of a package.
+ *
+ * @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 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;
+    }
 }
 
 /**
@@ -2007,8 +1778,6 @@ async function seedContent(options) {
     // Seed content via the same code path as writer cycles
     await refreshPlatformContent({
         coreVersion: options.coreVersion,
-        probeTimeoutMs: options.probeTimeoutMs ?? 3000,
-        skipRegistryCheck: options.skipRegistryCheck ?? true,
     });
 }
 
@@ -2019,6 +1788,26 @@ async function seedContent(options) {
  * 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.
  *
@@ -2167,6 +1956,77 @@ function patchConfig(config, pluginId, mode) {
     return messages;
 }
 
+/**
+ * Plugin resolution helpers for the OpenClaw plugin SDK.
+ *
+ * @remarks
+ * Provides workspace path resolution and plugin setting resolution
+ * with a standard three-step fallback chain:
+ * plugin config → environment variable → default value.
+ */
+/**
+ * Resolve the workspace root from the OpenClaw plugin API.
+ *
+ * @remarks
+ * Tries three sources in order:
+ * 1. `api.config.agents.defaults.workspace` — explicit config
+ * 2. `api.resolvePath('.')` — gateway-provided path resolver
+ * 3. `process.cwd()` — last resort
+ *
+ * @param api - The plugin API object provided by the gateway.
+ * @returns Absolute path to the workspace root.
+ */
+function resolveWorkspacePath(api) {
+    const configured = api.config?.agents?.defaults?.workspace;
+    if (typeof configured === 'string' && configured.trim()) {
+        return configured;
+    }
+    if (typeof api.resolvePath === 'function') {
+        return api.resolvePath('.');
+    }
+    return process.cwd();
+}
+/**
+ * Resolve a plugin setting via the standard three-step fallback chain:
+ * plugin config → environment variable → fallback value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @param fallback - Default value if neither source provides one.
+ * @returns The resolved setting value.
+ */
+function resolvePluginSetting(api, pluginId, key, envVar, fallback) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return fallback;
+}
+/**
+ * Resolve an optional plugin setting via the two-step fallback chain:
+ * plugin config → environment variable. Returns `undefined` if neither
+ * source provides a value.
+ *
+ * @param api - Plugin API object.
+ * @param pluginId - Plugin identifier (e.g., 'jeeves-watcher-openclaw').
+ * @param key - Config key within the plugin's config object.
+ * @param envVar - Environment variable name.
+ * @returns The resolved setting value, or `undefined`.
+ */
+function resolveOptionalPluginSetting(api, pluginId, key, envVar) {
+    const fromPlugin = api.config?.plugins?.entries?.[pluginId]?.config?.[key];
+    if (typeof fromPlugin === 'string')
+        return fromPlugin;
+    const fromEnv = process.env[envVar];
+    if (fromEnv)
+        return fromEnv;
+    return undefined;
+}
+
 /**
  * Tool result formatters for the OpenClaw plugin SDK.
  *
@@ -2236,4 +2096,4 @@ function connectionFail(error, baseUrl, pluginId) {
     return fail(error);
 }
 
-export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_CORE_VERSION, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, parseManaged, patchConfig, postJson, probeAllServices, probeService, readComponentVersions, refreshPlatformContent, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion };
+export { AGENTS_MARKERS, CLEANUP_FLAG, COMPONENT_CONFIG_PREFIX, COMPONENT_VERSIONS_FILE, CONFIG_FILE, CORE_CONFIG_DIR, CORE_VERSION, ComponentWriter, DEFAULT_CORE_VERSION, DEFAULT_PORTS, META_PORT, REGISTRY_CACHE_FILE, RUNNER_PORT, SECTION_IDS, SECTION_ORDER, SERVER_PORT, SOUL_MARKERS, STALENESS_THRESHOLD_MS, STALE_LOCK_MS, TEMPLATES_DIR, TOOLS_MARKERS, VERSION_STAMP_PATTERN, WATCHER_PORT, WORKSPACE_FILES, atomicWrite, checkRegistryVersion, connectionFail, coreConfigSchema, createAsyncContentCache, createComponentWriter, createConfigQueryHandler, fail, fetchJson, fetchWithTimeout, formatBeginMarker, formatEndMarker, generateJsonSchema, getComponentConfigDir, getConfigRoot, getCoreConfigDir, getCoreConfigFile, getServiceUrl, getWorkspacePath, init, jaccard, needsCleanup, ok, parseManaged, patchConfig, postJson, readComponentVersions, refreshPlatformContent, removeManagedSection, resetInit, resolveConfigPath, resolveOpenClawHome, resolveOptionalPluginSetting, resolvePluginSetting, resolveWorkspacePath, seedContent, shingles, shouldWrite, updateManagedSection, withFileLock, writeComponentVersion };