@karmaniverous/jeeves 0.4.7 → 0.5.1

package/dist/cli/jeeves/index.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import * as commander from 'commander';
-import { execSync, spawnSync } from 'node:child_process';
+import { major, valid, gte } from 'semver';
+import { JSONPath } from 'jsonpath-plus';
+import { join, resolve, dirname } from 'node:path';
 import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync, mkdirSync, cpSync, rmSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { valid, gte } from 'semver';
 import { z } from 'zod';
+import { execSync, spawnSync } from 'node:child_process';
 import { lock } from 'proper-lockfile';
 import { fileURLToPath } from 'node:url';
 import { packageDirectorySync } from 'package-directory';
@@ -157,8 +158,8 @@ const ALL_MARKERS = [
 const VERSION_STAMP_PATTERN = /<!--\s*(.+?)\s*\|\s*core:(\S+)\s*\|\s*(\S+)\s*-->/;
 /** Staleness threshold for version-stamp convergence in milliseconds. */
 const STALENESS_THRESHOLD_MS = 5 * 60 * 1000;
-/** Warning text prepended inside managed block when cleanup is needed. */
-const CLEANUP_FLAG = '> ⚠️ CLEANUP NEEDED: Orphaned Jeeves content may exist below this managed section. Review everything after the END marker and remove any content that duplicates what appears above.';
+/** Warning text injected inside managed block when cleanup is needed. */
+const CLEANUP_FLAG = '> ⚠️ CLEANUP NEEDED: Orphaned Jeeves content detected outside this managed block. Review the file and remove any content outside the BEGIN/END markers that duplicates what appears inside them.';
 
 /**
  * Directory and file path conventions for the Jeeves platform.
@@ -175,7 +176,13 @@ const WORKSPACE_FILES = {
     agents: 'AGENTS.md',
     /** HEARTBEAT.md — platform status and health alerts. */
     heartbeat: 'HEARTBEAT.md',
+    /** MEMORY.md — curated long-term memory. */
+    memory: 'MEMORY.md',
 };
+/** Skill directory name within workspace. */
+const SKILLS_DIR = 'skills';
+/** Jeeves skill directory name. */
+const JEEVES_SKILL_DIR = 'jeeves';
 /** Templates directory name within core config. */
 const TEMPLATES_DIR = 'templates';
 /** Core config file name. */
@@ -261,14 +268,318 @@ const PLATFORM_COMPONENTS = [
  * Core library version, inlined at build time.
  *
  * @remarks
- * The `0.4.6` placeholder is replaced by
+ * The `0.5.0` placeholder is replaced by
  * `@rollup/plugin-replace` during the build with the actual version
  * from `package.json`. This ensures the correct version survives
  * when consumers bundle core into their own dist (where runtime
  * `import.meta.url`-based resolution would find the wrong package.json).
  */
 /** The core library version from package.json (inlined at build time). */
-const CORE_VERSION = '0.4.6';
+const CORE_VERSION = '0.5.0';
+
+/**
+ * Runtime Node.js version floor check.
+ *
+ * @module
+ */
+/** Minimum supported Node.js major version. */
+const MIN_NODE_MAJOR = 22;
+/**
+ * Check that the running Node.js version meets the minimum requirement.
+ * Prints an error and exits with code 1 if the check fails.
+ */
+function checkNodeVersion() {
+    const nodeMajor = major(process.versions.node);
+    if (nodeMajor < MIN_NODE_MAJOR) {
+        console.error(`Error: jeeves requires Node.js >= ${String(MIN_NODE_MAJOR)}. Current: ${process.versions.node}`);
+        process.exit(1);
+    }
+}
+
+/**
+ * Workspace-level shared configuration: `jeeves.config.json`.
+ *
+ * @remarks
+ * Lives at the OpenClaw workspace root alongside TOOLS.md and SOUL.md.
+ * Provides namespaced shared defaults consumed by the root Jeeves CLI.
+ * Resolution precedence: CLI flags → env vars → jeeves.config.json → defaults.
+ *
+ * This does not replace component-owned config schemas (Decision 41).
+ */
+/** Workspace config file name. */
+const WORKSPACE_CONFIG_FILE = 'jeeves.config.json';
+/** Core shared config section. */
+const workspaceCoreConfigSchema = z
+    .object({
+    /** Workspace root path. */
+    workspace: z.string().optional().describe('Workspace root path'),
+    /** Platform config root path. */
+    configRoot: z.string().optional().describe('Platform config root path'),
+    /** OpenClaw gateway URL. */
+    gatewayUrl: z.string().optional().describe('OpenClaw gateway URL'),
+})
+    .partial();
+/** Memory shared config section. */
+const workspaceMemoryConfigSchema = z
+    .object({
+    /** MEMORY.md character budget. */
+    budget: z.number().int().positive().optional().describe('Memory budget'),
+    /** Warning threshold as a fraction of budget. */
+    warningThreshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Memory warning threshold'),
+    /** Staleness threshold in days. */
+    staleDays: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Memory staleness threshold in days'),
+})
+    .partial();
+/** Workspace config Zod schema. */
+const workspaceConfigSchema = z.object({
+    /** JSON Schema pointer for IDE autocomplete. */
+    $schema: z.string().optional().describe('JSON Schema pointer'),
+    /** Core shared defaults. */
+    core: workspaceCoreConfigSchema.optional(),
+    /** Memory hygiene shared defaults. */
+    memory: workspaceMemoryConfigSchema.optional(),
+});
+/** Built-in workspace config defaults. */
+const WORKSPACE_CONFIG_DEFAULTS = {
+    core: {
+        workspace: '.',
+        configRoot: './config',
+        gatewayUrl: 'http://127.0.0.1:3000',
+    },
+    memory: {
+        budget: 20_000,
+        warningThreshold: 0.8,
+        staleDays: 30,
+    },
+};
+/**
+ * Load workspace config from `jeeves.config.json` at a given path.
+ *
+ * @param workspacePath - Workspace root directory.
+ * @returns Parsed config or undefined if missing or invalid.
+ */
+function loadWorkspaceConfig(workspacePath) {
+    const configPath = join(workspacePath, WORKSPACE_CONFIG_FILE);
+    if (!existsSync(configPath))
+        return undefined;
+    try {
+        const raw = readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return workspaceConfigSchema.parse(parsed);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`jeeves-core: failed to load ${configPath}: ${msg}`);
+        return undefined;
+    }
+}
+/**
+ * Resolve a config value with four-tier precedence.
+ *
+ * @param flagValue - CLI flag value (highest priority).
+ * @param envValue - Environment variable value.
+ * @param fileValue - Value from jeeves.config.json.
+ * @param defaultValue - Built-in default (lowest priority).
+ * @returns The resolved value with provenance annotation.
+ */
+function resolveConfigValue(flagValue, envValue, fileValue, defaultValue) {
+    if (flagValue !== undefined)
+        return { value: flagValue, provenance: 'flag' };
+    if (envValue !== undefined)
+        return { value: envValue, provenance: 'env' };
+    if (fileValue !== undefined)
+        return { value: fileValue, provenance: 'file' };
+    return { value: defaultValue, provenance: 'default' };
+}
+
+/**
+ * Workspace and config root initialization.
+ *
+ * @remarks
+ * `init()` must be called once before any other core library functions.
+ * It caches `workspacePath` and `configRoot` at module level.
+ * Core derives all namespaced paths from these values:
+ * - `{configRoot}/jeeves-core/` for core config
+ * - `{configRoot}/jeeves-{name}/` for each component
+ */
+let state;
+/**
+ * Initialize the core library with workspace and config root paths.
+ *
+ * @param options - Workspace and config root paths.
+ */
+function init(options) {
+    state = {
+        workspacePath: options.workspacePath,
+        configRoot: options.configRoot,
+        coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
+    };
+}
+/**
+ * Get the cached workspace path.
+ *
+ * @throws Error if `init()` has not been called.
+ */
+function getWorkspacePath() {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return state.workspacePath;
+}
+/**
+ * Get the core config directory path.
+ *
+ * @throws Error if `init()` has not been called.
+ */
+function getCoreConfigDir() {
+    if (!state)
+        throw new Error('jeeves-core: init() must be called first');
+    return state.coreConfigDir;
+}
+
+var init$1 = /*#__PURE__*/Object.freeze({
+	__proto__: null,
+	getCoreConfigDir: getCoreConfigDir,
+	getWorkspacePath: getWorkspacePath,
+	init: init
+});
+
+/**
+ * Shared CLI defaults and resolution for Jeeves CLI commands.
+ *
+ * @remarks
+ * All root CLI commands share workspace/config-root resolution. Values follow
+ * the shared precedence model: flags → env → jeeves.config.json → defaults.
+ */
+/** Default workspace path. */
+const DEFAULT_WORKSPACE = WORKSPACE_CONFIG_DEFAULTS.core.workspace;
+/** Default config root path. */
+const DEFAULT_CONFIG_ROOT = WORKSPACE_CONFIG_DEFAULTS.core.configRoot;
+/** Read a numeric env var or return undefined if missing, empty, or invalid. */
+function readNumericEnv(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Resolve shared CLI config using flags, env, file, and defaults.
+ *
+ * @param opts - Parsed CLI workspace/config-root options.
+ * @returns Resolved config tree with provenance on every leaf.
+ */
+function resolveCliConfig(opts) {
+    const workspaceSeed = resolveConfigValue(opts.workspace, process.env['JEEVES_WORKSPACE'], undefined, DEFAULT_WORKSPACE);
+    const fileConfig = loadWorkspaceConfig(workspaceSeed.value);
+    return {
+        core: {
+            workspace: resolveConfigValue(opts.workspace, process.env['JEEVES_WORKSPACE'], fileConfig?.core?.workspace, DEFAULT_WORKSPACE),
+            configRoot: resolveConfigValue(opts.configRoot, process.env['JEEVES_CONFIG_ROOT'], fileConfig?.core?.configRoot, DEFAULT_CONFIG_ROOT),
+            gatewayUrl: resolveConfigValue(undefined, process.env['JEEVES_GATEWAY_URL'], fileConfig?.core?.gatewayUrl, WORKSPACE_CONFIG_DEFAULTS.core.gatewayUrl),
+        },
+        memory: {
+            budget: resolveConfigValue(undefined, readNumericEnv('JEEVES_MEMORY_BUDGET'), fileConfig?.memory?.budget, WORKSPACE_CONFIG_DEFAULTS.memory.budget),
+            warningThreshold: resolveConfigValue(undefined, readNumericEnv('JEEVES_MEMORY_WARNING_THRESHOLD'), fileConfig?.memory?.warningThreshold, WORKSPACE_CONFIG_DEFAULTS.memory.warningThreshold),
+            staleDays: resolveConfigValue(undefined, readNumericEnv('JEEVES_MEMORY_STALE_DAYS'), fileConfig?.memory?.staleDays, WORKSPACE_CONFIG_DEFAULTS.memory.staleDays),
+        },
+    };
+}
+/**
+ * Initialize core from standard CLI options after resolving shared defaults.
+ *
+ * @param opts - Parsed Commander options with workspace and configRoot.
+ * @returns Resolved CLI config.
+ */
+function initFromOptions(opts) {
+    const resolved = resolveCliConfig(opts);
+    init({
+        workspacePath: resolve(resolved.core.workspace.value),
+        configRoot: resolve(resolved.core.configRoot.value),
+    });
+    return resolved;
+}
+
+/**
+ * `jeeves config [jsonpath]` — inspect effective shared CLI configuration.
+ *
+ * @remarks
+ * Shows effective values and provenance using the shared precedence model.
+ * Optional JSONPath filters the resolved config tree.
+ */
+/** Format a provenance tag. */
+function provenanceTag(provenance) {
+    return `[${provenance}]`;
+}
+/** Whether a value is a resolved leaf with provenance. */
+function isResolvedLeaf(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'value' in value &&
+        'provenance' in value);
+}
+/**
+ * Build the effective shared CLI config tree.
+ *
+ * @param opts - Parsed CLI workspace/config-root options.
+ * @returns Effective config tree with provenance on each leaf.
+ */
+function buildEffectiveConfig(opts) {
+    return initFromOptions(opts);
+}
+/** Print the full effective config tree by walking the resolved structure. */
+function printEffectiveConfig(config) {
+    console.log('Effective jeeves.config.json:');
+    console.log('');
+    for (const [section, entries] of Object.entries(config)) {
+        for (const [key, leaf] of Object.entries(entries)) {
+            console.log(`  ${section}.${key}: ${JSON.stringify(leaf.value)} ${provenanceTag(leaf.provenance)}`);
+        }
+    }
+}
+/**
+ * Register the `jeeves config` command.
+ *
+ * @param program - Root Commander program.
+ */
+function registerConfigCommand(program) {
+    program
+        .command('config')
+        .description('Show effective shared configuration with provenance')
+        .argument('[jsonpath]', 'JSONPath filter (e.g. $.core.workspace)')
+        .option('-w, --workspace <path>', 'Workspace root path')
+        .option('-c, --config-root <path>', 'Platform config root path')
+        .action((jsonpath, opts) => {
+        const effective = buildEffectiveConfig(opts);
+        if (jsonpath) {
+            const result = JSONPath({
+                path: jsonpath,
+                json: effective,
+                wrap: false,
+            });
+            if (result === undefined) {
+                console.log(`No config value for: ${jsonpath}`);
+                return;
+            }
+            if (isResolvedLeaf(result)) {
+                console.log(`${jsonpath}: ${JSON.stringify(result.value)} ${provenanceTag(result.provenance)}`);
+                return;
+            }
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        printEffectiveConfig(effective);
+    });
+}
 
 /**
  * Dynamic discovery of installed Jeeves component CLIs.
@@ -345,57 +656,6 @@ function registerComponentProxies(program, componentNames) {
     }
 }
 
-/**
- * Workspace and config root initialization.
- *
- * @remarks
- * `init()` must be called once before any other core library functions.
- * It caches `workspacePath` and `configRoot` at module level.
- * Core derives all namespaced paths from these values:
- * - `{configRoot}/jeeves-core/` for core config
- * - `{configRoot}/jeeves-{name}/` for each component
- */
-let state;
-/**
- * Initialize the core library with workspace and config root paths.
- *
- * @param options - Workspace and config root paths.
- */
-function init(options) {
-    state = {
-        workspacePath: options.workspacePath,
-        configRoot: options.configRoot,
-        coreConfigDir: join(options.configRoot, CORE_CONFIG_DIR),
-    };
-}
-/**
- * Get the cached workspace path.
- *
- * @throws Error if `init()` has not been called.
- */
-function getWorkspacePath() {
-    if (!state)
-        throw new Error('jeeves-core: init() must be called first');
-    return state.workspacePath;
-}
-/**
- * Get the core config directory path.
- *
- * @throws Error if `init()` has not been called.
- */
-function getCoreConfigDir() {
-    if (!state)
-        throw new Error('jeeves-core: init() must be called first');
-    return state.coreConfigDir;
-}
-
-var init$1 = /*#__PURE__*/Object.freeze({
-	__proto__: null,
-	getCoreConfigDir: getCoreConfigDir,
-	getWorkspacePath: getWorkspacePath,
-	init: init
-});
-
 /**
  * Core configuration schema and resolution.
  *
@@ -747,7 +1007,7 @@ function parseHeartbeat(fileContent) {
     const userContent = fileContent.slice(0, headingIndex).trim();
     const sectionContent = fileContent.slice(headingIndex + HEARTBEAT_HEADING.length);
     const entries = [];
-    const h2Re = /^## (jeeves-\S+?)(?:: declined)?$/gm;
+    const h2Re = /^## (jeeves-\S+?|MEMORY\.md)(?:: declined)?$/gm;
     let match;
     const h2Positions = [];
     while ((match = h2Re.exec(sectionContent)) !== null) {
@@ -1550,10 +1810,10 @@ async function updateManagedSection(filePath, content, options = {}) {
                     ? `# ${markers.title}\n\n${sectionText}`
                     : sectionText;
             }
-            // Combine beforeContent + userContent for the user zone.
-            // When migrating from top→bottom, beforeContent is empty and
-            // userContent has the real content. When already at bottom,
-            // beforeContent has the user content and userContent is empty.
+            // 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')
@@ -1561,9 +1821,6 @@ async function updateManagedSection(filePath, content, options = {}) {
             // Strip foreign managed blocks from user content (cross-contamination fix)
             const userContent = stripForeignMarkers(rawUserContent, markers);
             const cleanupNeeded = needsCleanup(newManagedBody, userContent);
-            // Build the full managed block
-            const beginLine = formatBeginMarker(markers.begin, coreVersion);
-            const endLine = formatEndMarker(markers.end);
             const managedParts = [];
             managedParts.push(beginLine);
             if (cleanupNeeded) {
@@ -1575,26 +1832,54 @@ async function updateManagedSection(filePath, content, options = {}) {
             managedParts.push('');
             managedParts.push(endLine);
             const managedBlock = managedParts.join('\n');
-            const position = markers.position ?? 'top';
-            const fileParts = [];
-            if (position === 'bottom') {
-                // User content first, managed block at end
-                if (userContent) {
-                    fileParts.push(userContent);
+            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 {
-                // Managed block first (legacy default), user content below
-                fileParts.push(managedBlock);
-                if (userContent) {
-                    fileParts.push('');
-                    fileParts.push(userContent);
+                // 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 escapedBegin = markers.begin.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const orphanedBeginRe = new RegExp(`^<!--\\s*${escapedBegin}(?:\\s*\\|[^>]*)?\\s*(?:—[^>]*)?\\s*-->\\s*$\\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');
             }
-            fileParts.push('');
-            const newFileContent = fileParts.join('\n');
             atomicWrite(filePath, newFileContent);
         });
     }
@@ -1725,6 +2010,135 @@ async function refreshPlatformContent(options) {
     copyTemplates(coreConfigDir);
 }
 
+var skillContent = `---
+name: jeeves
+description: Jeeves platform architecture, data flow, component interaction, scripts repo, and coordination knowledge. Use when making architectural decisions, coordinating across components, checking platform health, managing service lifecycle, or working with the scripts repo.
+---
+
+# Jeeves Platform Skill
+
+## Platform Architecture
+
+Jeeves is a four-component platform coordinated by a shared library (\`@karmaniverous/jeeves\`):
+
+| Component | Role | Port |
+|-----------|------|------|
+| **jeeves-runner** | Execute: scheduled jobs, SQLite state, HTTP API | 1937 |
+| **jeeves-watcher** | Index: file→Qdrant semantic indexing, inference rules | 1936 |
+| **jeeves-server** | Present: web UI, file browser, doc render, export | 1934 |
+| **jeeves-meta** | Distill: LLM synthesis, .meta/ directories, scheduling | 1938 |
+
+Core (\`@karmaniverous/jeeves\`) is a **library + CLI**, not a service. No port.
+
+## Data Flow
+
+\`\`\`
+Files → Watcher (index) → Qdrant → Meta (synthesize) → .meta/ → Watcher (re-index)
+                                                                      ↓
+Runner (schedule) → Scripts → Services ← Server (present) ← Browser
+\`\`\`
+
+## Component Interaction
+
+- **Watcher** indexes files into Qdrant with inference rules and enrichments.
+- **Meta** reads from Qdrant, synthesizes \`.meta/\` directories, which watcher re-indexes.
+- **Runner** executes scheduled scripts that may call any service's HTTP API.
+- **Server** presents files, renders documents, and provides the event gateway.
+- **Core** provides shared content management (TOOLS.md, SOUL.md, AGENTS.md), service discovery, config resolution, and the component SDK.
+
+## Service Discovery
+
+Services find each other via config resolution:
+1. Component's own config file (\`{configRoot}/jeeves-{name}/config.json\`)
+2. Core config file (\`{configRoot}/jeeves-core/config.json\`)
+3. Default port constants
+
+## Scripts Repo
+
+Location: \`{configRoot}/jeeves-core/scripts/\`
+Template: \`@karmaniverous/jeeves-scripts-template\`
+
+Scripts use utilities from \`@karmaniverous/jeeves\` (general) and \`@karmaniverous/jeeves-runner\` (runner-specific). Any script that could be useful outside runner scheduling belongs in core.
+
+## Managed Content System
+
+Core maintains managed sections in workspace files using comment markers:
+- **TOOLS.md** — Component sections (section mode) + Platform section
+- **SOUL.md** — Professional discipline and behavioral foundations (block mode)
+- **AGENTS.md** — Operational protocols and memory architecture (block mode)
+- **HEARTBEAT.md** — Platform health status (heading-based)
+
+Managed blocks are stationary after initial insertion. Cleanup detection uses Jaccard similarity on 3-word shingles. Cleanup escalation spawns a gateway session when orphaned content is detected.
+
+## Workspace Configuration
+
+\`jeeves.config.json\` at workspace root provides shared defaults:
+- Precedence: CLI flags → env vars → file → defaults
+- Namespaced: \`core.*\` (workspace, configRoot, gatewayUrl) and \`memory.*\` (budget, warningThreshold, staleDays)
+- Inspect with \`jeeves config [jsonpath]\`
+
+## HEARTBEAT Protocol
+
+The HEARTBEAT system uses a state machine per component:
+\`not_installed → deps_missing → config_missing → service_not_installed → service_stopped → healthy\`
+
+Dependency-aware: hard deps block alerts, soft deps add informational notes. Declined components are tracked via heading suffix.
+
+## Plugin Lifecycle
+
+\`\`\`bash
+# Core install (seed workspace content)
+npx @karmaniverous/jeeves install
+
+# Component plugin install
+npx @karmaniverous/jeeves-{component}-openclaw install
+
+# Component plugin uninstall
+npx @karmaniverous/jeeves-{component}-openclaw uninstall
+
+# Core uninstall (remove managed sections)
+npx @karmaniverous/jeeves uninstall
+\`\`\`
+
+## Memory Hygiene
+
+MEMORY.md has a character budget (default 20,000). Core tracks:
+- Character count and usage percentage
+- Warning at 80% of budget
+- Stale section candidates (H2 sections whose most recent ISO date exceeds the staleness threshold)
+- Evergreen sections (no dates) are never flagged
+
+Review is human/agent-mediated — core does not auto-delete.
+
+### HEARTBEAT Integration
+
+Memory hygiene is checked on every \`ComponentWriter\` cycle alongside component health. When budget or staleness thresholds are breached, a \`## MEMORY.md\` alert appears in HEARTBEAT.md under \`# Jeeves Platform Status\`. The alert includes character count, budget usage percentage, and any stale section names. When memory is healthy, the heading is absent — no alert content, no LLM cost on heartbeat polls.
+
+The \`## MEMORY.md\` heading follows the same declined/active lifecycle as component headings (\`## jeeves-{name}\`). Users can decline memory alerts by changing the heading to \`## MEMORY.md: declined\`.
+`;
+
+/**
+ * Skill seeding: write the `jeeves` workspace skill unconditionally.
+ *
+ * @remarks
+ * The skill file is entirely generated — no user-authored content (Decision 48).
+ * Every installer (core CLI and component plugins) writes it unconditionally.
+ * Content is inlined at build time via `rollup-plugin-md.ts`.
+ */
+/**
+ * Seed the jeeves workspace skill file.
+ *
+ * @param workspacePath - Workspace root directory.
+ */
+function seedSkill(workspacePath) {
+    const skillDir = join(workspacePath, SKILLS_DIR, JEEVES_SKILL_DIR);
+    if (!existsSync(skillDir)) {
+        mkdirSync(skillDir, { recursive: true });
+    }
+    const skillPath = join(skillDir, 'SKILL.md');
+    writeFileSync(skillPath, skillContent, 'utf-8');
+}
+
 /**
  * One-shot content seeding used by the CLI install command.
  *
@@ -1783,27 +2197,8 @@ async function seedContent(options) {
         content: `- ${NOT_INSTALLED_ALERTS[name]}`,
     }));
     await writeHeartbeatSection(heartbeatPath, entries);
-}
-
-/**
- * Shared CLI defaults and option registration for Jeeves CLI commands.
- *
- * @remarks
- * All three CLI commands (install, uninstall, status) share the same
- * `--workspace` and `--config-root` options with the same defaults.
- * This module centralizes them to eliminate duplication.
- */
-/** Default workspace path (current directory). */
-const DEFAULT_WORKSPACE = '.';
-/** Default config root path. */
-const DEFAULT_CONFIG_ROOT = './config';
-/**
- * Initialize core from standard CLI options.
- *
- * @param opts - Parsed Commander options with workspace and configRoot.
- */
-function initFromOptions(opts) {
-    init({ workspacePath: opts.workspace, configRoot: opts.configRoot });
+    // Seed jeeves workspace skill (Decision 48: overwrite-on-install)
+    seedSkill(getWorkspacePath());
 }
 
 /**
@@ -1824,14 +2219,14 @@ function registerInstallCommand(program) {
     program
         .command('install')
         .description('Seed Jeeves platform content into the workspace')
-        .option('-w, --workspace <path>', 'Workspace root path', DEFAULT_WORKSPACE)
-        .option('-c, --config-root <path>', 'Platform config root path', DEFAULT_CONFIG_ROOT)
+        .option('-w, --workspace <path>', 'Workspace root path')
+        .option('-c, --config-root <path>', 'Platform config root path')
         .action(async (opts) => {
+        const resolved = initFromOptions(opts);
         console.log('Jeeves platform install');
-        console.log(`  Workspace: ${opts.workspace}`);
-        console.log(`  Config root: ${opts.configRoot}`);
+        console.log(`  Workspace: ${resolved.core.workspace.value}`);
+        console.log(`  Config root: ${resolved.core.configRoot.value}`);
         console.log();
-        initFromOptions(opts);
         await seedContent({
             coreVersion: CORE_VERSION,
         });
@@ -1845,6 +2240,92 @@ function registerInstallCommand(program) {
     });
 }
 
+/**
+ * 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,
+    };
+}
+
 /**
  * CLI status command: discover components and probe their health.
  *
@@ -1862,12 +2343,12 @@ function registerStatusCommand(program) {
     program
         .command('status')
         .description('Discover Jeeves components and probe their health')
-        .option('-w, --workspace <path>', 'Workspace root path', DEFAULT_WORKSPACE)
-        .option('-c, --config-root <path>', 'Platform config root path', DEFAULT_CONFIG_ROOT)
+        .option('-w, --workspace <path>', 'Workspace root path')
+        .option('-c, --config-root <path>', 'Platform config root path')
         .option('-t, --timeout <ms>', 'Probe timeout in milliseconds', '3000')
         .action(async (opts) => {
         const timeoutMs = parseInt(opts.timeout, 10);
-        initFromOptions(opts);
+        const resolved = initFromOptions(opts);
         console.log('Jeeves Platform Status');
         console.log('='.repeat(60));
         console.log();
@@ -1875,62 +2356,87 @@ function registerStatusCommand(program) {
         const coreConfigDir = getCoreConfigDir();
         const componentVersions = readComponentVersions(coreConfigDir);
         const componentNames = Object.keys(componentVersions);
+        let allHealthy = true;
         if (componentNames.length === 0) {
             console.log('No components registered.');
-            return;
+            console.log();
         }
-        const nameWidth = 10;
-        const statusWidth = 30;
-        const versionWidth = 12;
-        const header = [
-            'Component'.padEnd(nameWidth),
-            'Status'.padEnd(statusWidth),
-            'Version'.padEnd(versionWidth),
-        ].join('  ');
-        const separator = [
-            '-'.repeat(nameWidth),
-            '-'.repeat(statusWidth),
-            '-'.repeat(versionWidth),
-        ].join('  ');
-        console.log(header);
-        console.log(separator);
-        let allHealthy = true;
-        for (const name of componentNames) {
-            let status;
-            let version = '—';
-            try {
-                const url = getServiceUrl(name);
-                const response = await fetchWithTimeout(`${url}/status`, timeoutMs);
-                if (response.ok) {
-                    status = '✅ Running';
-                    try {
-                        const body = await response.json();
-                        if (typeof body === 'object' &&
-                            body !== null &&
-                            'version' in body &&
-                            typeof body['version'] === 'string') {
-                            version = body['version'];
+        else {
+            const nameWidth = 10;
+            const statusWidth = 30;
+            const versionWidth = 12;
+            const header = [
+                'Component'.padEnd(nameWidth),
+                'Status'.padEnd(statusWidth),
+                'Version'.padEnd(versionWidth),
+            ].join('  ');
+            const separator = [
+                '-'.repeat(nameWidth),
+                '-'.repeat(statusWidth),
+                '-'.repeat(versionWidth),
+            ].join('  ');
+            console.log(header);
+            console.log(separator);
+            for (const name of componentNames) {
+                let status;
+                let version = '—';
+                try {
+                    const url = getServiceUrl(name);
+                    const response = await fetchWithTimeout(`${url}/status`, timeoutMs);
+                    if (response.ok) {
+                        status = '✅ Running';
+                        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 — version stays unknown
                         }
                     }
-                    catch {
-                        // Non-JSON response — version stays unknown
+                    else {
+                        status = `❌ HTTP ${String(response.status)}`;
+                        allHealthy = false;
                     }
                 }
-                else {
-                    status = `❌ HTTP ${String(response.status)}`;
+                catch {
+                    status = '❌ Down';
                     allHealthy = false;
                 }
+                const row = [
+                    name.padEnd(nameWidth),
+                    status.padEnd(statusWidth),
+                    version.padEnd(versionWidth),
+                ].join('  ');
+                console.log(row);
             }
-            catch {
-                status = '❌ Down';
-                allHealthy = false;
-            }
-            const row = [
-                name.padEnd(nameWidth),
-                status.padEnd(statusWidth),
-                version.padEnd(versionWidth),
-            ].join('  ');
-            console.log(row);
+            console.log();
+        }
+        const memory = analyzeMemory({
+            workspacePath: getWorkspacePath(),
+            budget: resolved.memory.budget.value,
+            warningThreshold: resolved.memory.warningThreshold.value,
+            staleDays: resolved.memory.staleDays.value,
+        });
+        console.log('Memory hygiene');
+        console.log('-'.repeat(60));
+        if (!memory.exists) {
+            console.log('MEMORY.md not found.');
+        }
+        else {
+            const usagePct = Math.round(memory.usage * 100);
+            const status = memory.overBudget
+                ? '❌ Over budget'
+                : memory.warning
+                    ? '⚠ Warning'
+                    : '✅ OK';
+            console.log(`Chars: ${String(memory.charCount)} / ${String(memory.budget)} (${String(usagePct)}%) — ${status}`);
+            console.log(`Stale candidates: ${String(memory.staleCandidates)}`);
         }
         console.log();
         if (!allHealthy) {
@@ -1989,14 +2495,14 @@ function registerUninstallCommand(program) {
     program
         .command('uninstall')
         .description('Remove Jeeves managed sections and platform artifacts')
-        .option('-w, --workspace <path>', 'Workspace root path', DEFAULT_WORKSPACE)
-        .option('-c, --config-root <path>', 'Platform config root path', DEFAULT_CONFIG_ROOT)
+        .option('-w, --workspace <path>', 'Workspace root path')
+        .option('-c, --config-root <path>', 'Platform config root path')
         .action(async (opts) => {
+        const resolved = initFromOptions(opts);
         console.log('Jeeves platform uninstall');
-        console.log(`  Workspace: ${opts.workspace}`);
-        console.log(`  Config root: ${opts.configRoot}`);
+        console.log(`  Workspace: ${resolved.core.workspace.value}`);
+        console.log(`  Config root: ${resolved.core.configRoot.value}`);
         console.log();
-        initFromOptions(opts);
         const wsPath = getWorkspacePath();
         const coreConfigDir = getCoreConfigDir();
         // Remove managed sections from workspace files
@@ -2064,6 +2570,7 @@ function registerUninstallCommand(program) {
  * and status subcommands, plus dynamic proxy commands for any installed
  * `@karmaniverous/jeeves-*` component packages.
  */
+checkNodeVersion();
 const cli = new Command()
     .name('jeeves')
     .description('Jeeves AI assistant platform — shared library and CLI')
@@ -2073,6 +2580,7 @@ const cli = new Command()
 registerInstallCommand(cli);
 registerUninstallCommand(cli);
 registerStatusCommand(cli);
+registerConfigCommand(cli);
 // Dynamic discovery: register proxy subcommands for installed components
 const discoveredComponents = discoverComponentPackages();
 registerComponentProxies(cli, discoveredComponents);