@karmaniverous/jeeves 0.1.6 → 0.2.0

package/README.md

@@ -16,7 +16,7 @@ That's it. I handle the rest.
 
 ## Who I Am
 
-My name is Jeeves. 
+My name is Jeeves.
 
 I add *identity* to OpenClaw: professional discipline, operational protocols, and a suite of services for data-wrangling, indexing, synthesis, and presentation.
 
@@ -60,19 +60,87 @@ I coordinate four service components. Each has its own repo, service, and OpenCl
 | [jeeves-runner](https://github.com/karmaniverous/jeeves-runner) | 1937 | Turing's paper in the *Proceedings* (1937) | Scheduled jobs, zero-LLM-cost scripts |
 | [jeeves-meta](https://github.com/karmaniverous/jeeves-meta) | 1938 | Shannon's switching circuits thesis (1938) | Three-step LLM synthesis |
 
-This package (`@karmaniverous/jeeves`) is the substrate they all share: managed workspace content, service discovery, config resolution, version-stamp convergence. It's a library and CLI. No daemon, no port, no tools registered with the gateway.
+This package (`@karmaniverous/jeeves`) is the substrate they all share: managed workspace content, service discovery, config resolution, version-stamp convergence, and a Plugin SDK for building component plugins. It's a library and CLI. No daemon, no port, no tools registered with the gateway.
 
-## For Platform Developers
+## Plugin SDK
 
-If you're building a component plugin, you implement one interface and call one factory:
+The Plugin SDK (`src/plugin/`) provides canonical types and utilities for building OpenClaw plugins that integrate with the Jeeves platform.
+
+### Core Types
+
+- **`PluginApi`** — the shape of the `api` object the OpenClaw gateway passes to plugins at registration time. Provides `config`, `resolvePath()`, and `registerTool()`.
+- **`ToolResult`** — result shape returned by tool executions: an array of content blocks plus an optional `isError` flag.
+- **`ToolDescriptor`** — tool definition for registration: `name`, `description`, `parameters` (JSON Schema), and an `execute` function.
+
+### Result Formatters
+
+- **`ok(data)`** — wraps arbitrary data as a successful `ToolResult` with JSON-stringified content.
+- **`fail(error)`** — wraps an error into a `ToolResult` with `isError: true`.
+- **`connectionFail(error, baseUrl, pluginId)`** — 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.
+
+### HTTP Helpers
+
+- **`fetchJson(url, init?)`** — thin wrapper around `fetch` that throws on non-OK responses and returns parsed JSON.
+- **`postJson(url, body)`** — POST JSON to a URL and return parsed response.
+
+### Resolution Helpers
+
+- **`resolveWorkspacePath(api)`** — resolves the workspace root from the plugin API via a three-step chain: `api.config.agents.defaults.workspace` → `api.resolvePath('.')` → `process.cwd()`.
+- **`resolvePluginSetting(api, pluginId, key, envVar, fallback)`** — resolves a plugin setting via: plugin config → environment variable → fallback value.
+
+### OpenClaw Config Utilities
+
+- **`resolveOpenClawHome()`** — resolves the OpenClaw home directory: `OPENCLAW_CONFIG` env (dirname) → `OPENCLAW_HOME` env → `~/.openclaw`.
+- **`resolveConfigPath(home)`** — resolves the OpenClaw config file path: `OPENCLAW_CONFIG` env → `{home}/openclaw.json`.
+- **`patchConfig(config, pluginId, mode)`** — idempotent config patching for plugin install/uninstall. Manages `plugins.entries.{pluginId}` and `tools.alsoAllow`.
+
+## Config Query Handler
+
+The `createConfigQueryHandler(getConfig)` factory produces a transport-agnostic handler for `GET /config` endpoints. It accepts a `getConfig` callback that returns the current config object.
+
+- No `path` parameter → returns the full config document.
+- Valid JSONPath expression → returns matching results with count (powered by `jsonpath-plus`).
+- Invalid JSONPath → returns a 400 error.
+
+Component services wire this into their HTTP server to expose config for diagnostic queries.
+
+## Managed Content System
+
+The managed content system maintains SOUL.md, AGENTS.md, and TOOLS.md without destroying user-authored content.
+
+### Key Functions
+
+- **`updateManagedSection(filePath, content, options)`** — writes managed content in either block mode (replaces entire managed block) or section mode (upserts a named H2 section within the block). Handles file locking, version-stamp convergence, cleanup detection, and atomic writes.
+- **`removeManagedSection(filePath, options)`** — removes a specific section or the entire managed block. If the last section is removed, the entire block is removed.
+- **`parseManaged(fileContent, markers)`** — parses a file into its managed block, version stamp, sections, and user content.
+- **`atomicWrite(filePath, content)`** — writes via a temp file + rename to prevent partial writes.
+- **`withFileLock(filePath, fn)`** — executes a callback while holding a file-level lock (2-minute stale threshold, 5 retries).
+
+### ManagedMarkers Type
+
+```typescript
+interface ManagedMarkers {
+  begin: string;  // BEGIN comment marker text
+  end: string;    // END comment marker text
+  title?: string; // Optional H1 title prepended inside managed block
+}
+```
+
+Pre-defined marker sets: `TOOLS_MARKERS`, `SOUL_MARKERS`, `AGENTS_MARKERS`.
+
+See the [Managed Content System](https://docs.karmanivero.us/jeeves/documents/Managed_Content_System.html) guide for the full deep-dive.
+
+## ComponentWriter and JeevesComponent
+
+Component plugins implement the `JeevesComponent` interface and use `createComponentWriter()` to get a timer-based orchestrator:
 
 ```typescript
 import { init, createComponentWriter } from '@karmaniverous/jeeves';
 import type { JeevesComponent } from '@karmaniverous/jeeves';
 
 init({
-  workspacePath: api.resolvePath('.'),
-  configRoot: api.getConfig('configRoot'),
+  workspacePath: resolveWorkspacePath(api),
+  configRoot: resolvePluginSetting(api, pluginId, 'configRoot', 'JEEVES_CONFIG_ROOT', 'j:/config'),
 });
 
 const writer = createComponentWriter({
@@ -88,18 +156,29 @@ const writer = createComponentWriter({
 writer.start();
 ```
 
-The writer handles everything: your TOOLS.md section, platform content (SOUL/AGENTS/Platform), file locking, version stamps, cleanup detection.
+On each cycle the writer calls `generateToolsContent()`, writes the component's TOOLS.md section, and runs `refreshPlatformContent()` to maintain SOUL.md, AGENTS.md, and the Platform section with live service health data.
+
+The `createAsyncContentCache({ fetch, placeholder? })` utility bridges the sync `generateToolsContent` interface with async data sources — returns a sync `() => string` that serves cached content while refreshing in the background.
 
-See the [Building a Component Plugin](https://docs.karmanivero.us/jeeves/documents/guides_building-a-component-plugin.html) guide for the full walkthrough.
+See the [Building a Component Plugin](https://docs.karmanivero.us/jeeves/documents/Building_a_Component_Plugin.html) guide for the full walkthrough.
+
+## Service Discovery
+
+- **`getServiceUrl(serviceName, consumerName?)`** — resolves a service URL via: consumer config → core config → default port constants.
+- **`probeService(serviceName, consumerName?, timeoutMs?)`** — probes `/status` then `/health` endpoints, returns a `ProbeResult` with health status and version.
+- **`probeAllServices(consumerName?, timeoutMs?)`** — probes all known services (server, watcher, runner, meta).
+- **`checkRegistryVersion(packageName, cacheDir, ttlSeconds?)`** — checks npm registry for the latest version with local file caching (default 1-hour TTL).
 
 ## CLI
 
 ```bash
-jeeves install     # Bootstrap identity, protocols, platform content
-jeeves uninstall   # Remove managed sections and artifacts
-jeeves status      # Probe all service ports, report health
+jeeves install     # Seed identity, protocols, platform content; create core config
+jeeves uninstall   # Remove managed sections, templates, config schema
+jeeves status      # Probe all service ports, report health table
 ```
 
+All three commands accept `--workspace <path>` and `--config-root <path>` options.
+
 ## Configuration
 
 Core config at `{configRoot}/jeeves-core/config.json`:

package/dist/cli/jeeves/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 #!/usr/bin/env node
 import require$$0 from 'commander';
-import { existsSync, readFileSync, mkdirSync, writeFileSync, renameSync, cpSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, cpSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { z } from 'zod';
 import { fileURLToPath } from 'node:url';
 import Handlebars from 'handlebars';
 import { packageDirectorySync } from 'package-directory';
-import { execSync } from 'node:child_process';
+import semver, { gte } from 'semver';
 import { lock } from 'proper-lockfile';
-import { gte } from 'semver';
+import { execSync } from 'node:child_process';
 
 function getDefaultExportFromCjs (x) {
 	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
@@ -141,6 +141,8 @@ const TEMPLATES_DIR = 'templates';
 const REGISTRY_CACHE_FILE = 'registry-cache.json';
 /** Core config file name. */
 const CONFIG_FILE = 'config.json';
+/** Component versions state file name. */
+const COMPONENT_VERSIONS_FILE = 'component-versions.json';
 
 /**
  * Default port assignments for Jeeves platform services.
@@ -204,14 +206,14 @@ const SECTION_ORDER = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.1.5` placeholder is replaced by
+ * 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.5';
+const CORE_VERSION = '0.1.6';
 
 /**
  * Core configuration schema and resolution.
@@ -726,6 +728,117 @@ Read these templates when creating new specs, onboarding to new projects, or whe
 {{/if}}
 `;
 
+/**
+ * Shared file I/O helpers for managed section operations.
+ *
+ * @remarks
+ * Extracts the atomic write pattern and file-level locking into
+ * reusable utilities, eliminating duplication between
+ * `updateManagedSection` and `removeManagedSection`.
+ */
+/** Stale lock threshold in ms (2 minutes). */
+const STALE_LOCK_MS = 120_000;
+/** Default core version when none provided. */
+const DEFAULT_CORE_VERSION = '0.0.0';
+/** Lock retry options. */
+const LOCK_RETRIES = { retries: 5, minTimeout: 100, maxTimeout: 1000 };
+/**
+ * Write content to a file atomically via a temp file + rename.
+ *
+ * @param filePath - Absolute path to the target file.
+ * @param content - Content to write.
+ */
+function atomicWrite(filePath, content) {
+    const dir = dirname(filePath);
+    const tempPath = join(dir, `.${String(Date.now())}.tmp`);
+    writeFileSync(tempPath, content, 'utf-8');
+    renameSync(tempPath, filePath);
+}
+/**
+ * Execute a callback while holding a file lock.
+ *
+ * @remarks
+ * Acquires a lock on the file, executes the callback, and releases
+ * the lock in a finally block. The lock uses a 2-minute stale threshold
+ * and retries up to 5 times.
+ *
+ * @param filePath - Absolute path to the file to lock.
+ * @param fn - Async callback to execute while holding the lock.
+ */
+async function withFileLock(filePath, fn) {
+    let release;
+    try {
+        release = await lock(filePath, {
+            stale: STALE_LOCK_MS,
+            retries: LOCK_RETRIES,
+        });
+        await fn();
+    }
+    finally {
+        if (release) {
+            try {
+                await release();
+            }
+            catch {
+                // Lock already released or file deleted — safe to ignore
+            }
+        }
+    }
+}
+
+/**
+ * Shared component version state file management.
+ *
+ * @remarks
+ * Each `ComponentWriter` cycle writes its component's entry to
+ * `{coreConfigDir}/component-versions.json`. The Platform Handlebars
+ * template reads this file to populate ALL rows in the service health
+ * table, not just the calling component's.
+ */
+/**
+ * Read the component versions state file.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @returns The parsed state, or an empty object if the file doesn't exist.
+ */
+function readComponentVersions(coreConfigDir) {
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Write a component's version entry to the shared state file.
+ *
+ * @remarks
+ * Reads the existing file, merges the new entry, and writes atomically.
+ *
+ * @param coreConfigDir - Path to the core config directory.
+ * @param options - Component version data to write.
+ */
+function writeComponentVersion(coreConfigDir, options) {
+    const existing = readComponentVersions(coreConfigDir);
+    existing[options.componentName] = {
+        serviceVersion: options.serviceVersion,
+        pluginVersion: options.pluginVersion,
+        servicePackage: options.servicePackage,
+        pluginPackage: options.pluginPackage,
+        updatedAt: new Date().toISOString(),
+    };
+    const filePath = join(coreConfigDir, COMPONENT_VERSIONS_FILE);
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    atomicWrite(filePath, JSON.stringify(existing, null, 2) + '\n');
+}
+
 /**
  * Service URL resolution.
  *
@@ -1149,10 +1262,6 @@ function shouldWrite(myVersion, existing, stalenessThresholdMs = STALENESS_THRES
  *
  * Provides file-level locking, version-stamp convergence, and atomic writes.
  */
-/** Default core version when none provided. */
-const DEFAULT_VERSION = '0.0.0';
-/** Stale lock threshold in ms (2 minutes). */
-const STALE_LOCK_MS = 120_000;
 /**
  * Update a managed section in a file.
  *
@@ -1161,7 +1270,7 @@ const STALE_LOCK_MS = 120_000;
  * @param options - Write mode and optional configuration.
  */
 async function updateManagedSection(filePath, content, options = {}) {
-    const { mode = 'block', sectionId, markers = TOOLS_MARKERS, coreVersion = DEFAULT_VERSION, stalenessThresholdMs, } = 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"');
     }
@@ -1173,93 +1282,134 @@ async function updateManagedSection(filePath, content, options = {}) {
     if (!existsSync(filePath)) {
         writeFileSync(filePath, '', 'utf-8');
     }
-    let release;
     try {
-        release = await lock(filePath, {
-            stale: STALE_LOCK_MS,
-            retries: { retries: 5, minTimeout: 100, maxTimeout: 1000 },
-        });
-        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 };
+        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 {
-                sections.push({ id: sectionId, content });
+                // 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;
+            }
+            // Cleanup detection
+            const userContent = parsed.userContent;
+            const cleanupNeeded = needsCleanup(newManagedBody, userContent);
+            // Build the full managed block
+            const beginLine = formatBeginMarker(markers.begin, coreVersion);
+            const endLine = formatEndMarker(markers.end);
+            const parts = [];
+            if (parsed.beforeContent) {
+                parts.push(parsed.beforeContent);
+                parts.push('');
+            }
+            parts.push(beginLine);
+            if (cleanupNeeded) {
+                parts.push('');
+                parts.push(CLEANUP_FLAG);
             }
-            sortSectionsByOrder(sections);
-            const sectionText = sections
-                .map((s) => `## ${s.id}\n\n${s.content}`)
-                .join('\n\n');
-            // Prepend H1 title if markers specify one (e.g., "# Jeeves Platform Tools")
-            newManagedBody = markers.title
-                ? `# ${markers.title}\n\n${sectionText}`
-                : sectionText;
-        }
-        // Cleanup detection
-        const userContent = parsed.userContent;
-        const cleanupNeeded = needsCleanup(newManagedBody, userContent);
-        // Build the full managed block
-        const beginLine = formatBeginMarker(markers.begin, coreVersion);
-        const endLine = formatEndMarker(markers.end);
-        const parts = [];
-        if (parsed.beforeContent) {
-            parts.push(parsed.beforeContent);
             parts.push('');
-        }
-        parts.push(beginLine);
-        if (cleanupNeeded) {
+            parts.push(newManagedBody);
             parts.push('');
-            parts.push(CLEANUP_FLAG);
-        }
-        parts.push('');
-        parts.push(newManagedBody);
-        parts.push('');
-        parts.push(endLine);
-        if (userContent) {
+            parts.push(endLine);
+            if (userContent) {
+                parts.push('');
+                parts.push(userContent);
+            }
             parts.push('');
-            parts.push(userContent);
-        }
-        parts.push('');
-        const newFileContent = parts.join('\n');
-        // Atomic write: write to temp file, then rename
-        const tempPath = join(dir, `.${String(Date.now())}.tmp`);
-        writeFileSync(tempPath, newFileContent, 'utf-8');
-        renameSync(tempPath, filePath);
+            const newFileContent = parts.join('\n');
+            atomicWrite(filePath, newFileContent);
+        });
     }
     catch (err) {
         // Log warning but don't throw — writer cycles are periodic
         const message = err instanceof Error ? err.message : String(err);
         console.warn(`jeeves-core: updateManagedSection failed for ${filePath}: ${message}`);
     }
-    finally {
-        if (release) {
-            try {
-                await release();
+}
+
+/**
+ * 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);
             }
-            catch {
-                // Lock already released or file deleted — safe to ignore
+            if (entry.pluginPackage && entry.pluginVersion) {
+                const registryVersion = checkRegistryVersion(entry.pluginPackage, cacheDir);
+                availablePluginVersion = newerVersion(registryVersion, entry.pluginVersion);
             }
         }
-    }
+        return {
+            ...r,
+            pluginVersion: entry.pluginVersion,
+            availableServiceVersion,
+            availablePluginVersion,
+        };
+    });
 }
 
 /**
@@ -1315,15 +1465,28 @@ function copyTemplates(coreConfigDir) {
 }
 /** Whether Handlebars helpers have been registered. */
 let helpersRegistered = false;
-/**
- * Register Handlebars helpers used in the Platform template.
- */
+/** 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.
  *
@@ -1335,55 +1498,46 @@ async function refreshPlatformContent(options) {
     const coreConfigDir = getCoreConfigDir();
     // 1. Probe all services
     const probeResults = await probeAllServices(undefined, probeTimeoutMs);
-    const unhealthyServices = probeResults.filter((r) => !r.healthy);
-    // 2. Registry version checks
+    // 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;
-    let availableCoreVersion;
-    let availableServiceVersion;
-    let availablePluginVersion;
-    if (!skipRegistryCheck) {
-        const coreRegistryVersion = checkRegistryVersion('@karmaniverous/jeeves', cacheDir);
-        if (coreRegistryVersion && coreRegistryVersion !== coreVersion) {
-            availableCoreVersion = coreRegistryVersion;
-        }
-        if (servicePackage) {
-            const svcVersion = checkRegistryVersion(servicePackage, cacheDir);
-            if (svcVersion) {
-                availableServiceVersion = svcVersion;
-            }
-        }
-        if (pluginPackage) {
-            const plgVersion = checkRegistryVersion(pluginPackage, cacheDir);
-            if (plgVersion) {
-                availablePluginVersion = plgVersion;
-            }
-        }
-    }
-    // 3. Build enriched service rows — match the calling component by name
-    const serviceRows = probeResults.map((r) => ({
-        ...r,
-        pluginVersion: r.name === componentName ? componentVersion : undefined,
-        availableServiceVersion: r.name === componentName ? availableServiceVersion : undefined,
-        availablePluginVersion: r.name === componentName ? availablePluginVersion : undefined,
-    }));
-    // 5. Check if templates are available
+    const availableCoreVersion = skipRegistryCheck
+        ? undefined
+        : checkCoreUpdate(coreVersion, cacheDir);
+    const serviceRows = buildServiceRows({
+        probeResults,
+        componentVersions,
+        cacheDir,
+        skipRegistryCheck,
+    });
+    // 5. Render Platform template
     const templatePath = join(coreConfigDir, TEMPLATES_DIR);
-    const templatesAvailable = existsSync(templatePath);
-    // 6. Render Platform template
     registerHelpers();
     const template = Handlebars.compile(toolsPlatformTemplate);
     const templateData = {
         services: serviceRows,
-        unhealthyServices,
+        unhealthyServices: serviceRows.filter((r) => !r.healthy),
         coreVersion,
         availableCoreVersion,
-        templatesAvailable,
+        templatesAvailable: existsSync(templatePath),
         templatePath,
     };
     const platformContent = template(templateData);
-    // 7. Write TOOLS.md Platform section
+    // 6. Write TOOLS.md Platform section
     const toolsPath = join(workspacePath, WORKSPACE_FILES.tools);
     await updateManagedSection(toolsPath, platformContent, {
         mode: 'section',
@@ -1392,7 +1546,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 8. Write SOUL.md managed block
+    // 7. Write SOUL.md managed block
     const soulPath = join(workspacePath, WORKSPACE_FILES.soul);
     await updateManagedSection(soulPath, soulSectionContent, {
         mode: 'block',
@@ -1400,7 +1554,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 9. Write AGENTS.md managed block
+    // 8. Write AGENTS.md managed block
     const agentsPath = join(workspacePath, WORKSPACE_FILES.agents);
     await updateManagedSection(agentsPath, agentsSectionContent, {
         mode: 'block',
@@ -1408,7 +1562,7 @@ async function refreshPlatformContent(options) {
         coreVersion,
         stalenessThresholdMs,
     });
-    // 10. Copy templates to config dir
+    // 9. Copy templates to config dir
     copyTemplates(coreConfigDir);
 }