@karmaniverous/jeeves-watcher-openclaw 0.15.6 → 0.16.0-0

package/dist/src/constants.d.ts

@@ -1,27 +1,21 @@
 /**
  * @module plugin/constants
  * Shared constants for the OpenClaw plugin package.
- *
- * @remarks
- * Imported by both the plugin bundle (`index.ts`) and the CLI bundle
- * (`cli.ts`). Rollup inlines these into each output independently.
  */
 export { COMPONENT_NAME, DEFAULT_PORT, PLUGIN_PACKAGE, SERVICE_PACKAGE, } from '@karmaniverous/jeeves-watcher-core';
-/** Plugin identifier used in OpenClaw config and extensions directory. */
+/** Plugin identifier used in OpenClaw config (`plugins.entries.<id>`). */
 export declare const PLUGIN_ID = "jeeves-watcher-openclaw";
 /** Default watcher API base URL. */
 export declare const DEFAULT_API_URL: string;
-/** Default platform config root path. */
-export declare const DEFAULT_CONFIG_ROOT = "j:/config";
+/** Environment variable consulted when plugin config has no `configRoot`. */
+export declare const CONFIG_ROOT_ENV_VAR = "JEEVES_CONFIG_ROOT";
 /**
- * Timeout in milliseconds for menu generation fetch calls.
+ * Tool error returned when `configRoot` cannot be resolved.
  *
  * @remarks
- * Must be generous enough to survive watcher startup (initial scan can
- * take 15+ minutes on large filesystems). If the fetch hangs past this
- * timeout, the `createAsyncContentCache` `refreshing` flag is cleared
- * and the next cycle retries. Too short = unnecessary "unreachable"
- * messages. Too long = `refreshing` deadlock when the server genuinely
- * hangs. 10 seconds balances both concerns.
+ * There is deliberately no default config root: a hard-coded path is only
+ * correct on one installation (see #227).
  */
-export declare const MENU_FETCH_TIMEOUT_MS = 10000;
+export declare const CONFIG_ROOT_NOT_CONFIGURED = "configRoot not configured \u2014 set it in plugin config (plugins.entries.jeeves-watcher-openclaw.config.configRoot) or via JEEVES_CONFIG_ROOT env var";
+/** Warning logged once at registration when `configRoot` is unset. */
+export declare const CONFIG_ROOT_UNSET_WARNING = "[jeeves-watcher-openclaw] configRoot not configured yet \u2014 watcher_service install will be unavailable until it is set in plugin config or JEEVES_CONFIG_ROOT (HTTP API tools are unaffected)";

package/dist/src/helpers.d.ts

@@ -9,7 +9,25 @@
  * @module plugin/helpers
  */
 import { type PluginApi } from '@karmaniverous/jeeves';
-/** Resolve the watcher API base URL. */
+/**
+ * Resolve the watcher API base URL.
+ *
+ * @remarks
+ * Resolution order: plugin-scoped config (`api.pluginConfig`), then
+ * `plugins.entries.<id>.config`, then `JEEVES_WATCHER_URL`, then
+ * `DEFAULT_API_URL`. Safe to call per tool invocation.
+ */
 export declare function getApiUrl(api: PluginApi): string;
-/** Resolve the platform config root path. */
-export declare function getConfigRoot(api: PluginApi): string;
+/**
+ * Resolve the platform config root path, if configured.
+ *
+ * @remarks
+ * Resolution order: plugin-scoped config (`api.pluginConfig`), then
+ * `plugins.entries.<id>.config`, then `JEEVES_CONFIG_ROOT`. There is no
+ * default. Call this lazily (at tool invocation), never to gate
+ * registration: `openclaw plugins install` activates the plugin before
+ * `jeeves install` writes its config.
+ *
+ * @returns The config root, or `undefined` when unset.
+ */
+export declare function getConfigRoot(api: PluginApi): string | undefined;

package/dist/src/index.d.ts

@@ -1,8 +1,15 @@
 /**
  * @module plugin
- * OpenClaw plugin entry point. Registers all jeeves-watcher tools and starts
- * the managed content writer via `@karmaniverous/jeeves` core.
+ * OpenClaw plugin entry point. Registers the jeeves-watcher tools and the
+ * always-in-context watcher rules.
+ *
+ * @remarks
+ * A standard OpenClaw plugin on `@karmaniverous/jeeves` core: it writes no
+ * workspace files and starts no timers. Registration never requires
+ * `configRoot`; it is resolved lazily when a gated tool runs (see
+ * `lazyCore`). Only invocations that read `configRoot` (`CONFIG_ROOT_READERS`:
+ * `watcher_service install`) are gated; HTTP-only tools work without it.
  */
-import type { PluginApi } from '@karmaniverous/jeeves';
+import { type PluginApi } from '@karmaniverous/jeeves';
 /** Register all jeeves-watcher tools with the OpenClaw plugin API. */
 export default function register(api: PluginApi): void;

package/dist/src/lazyCore.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module plugin/lazyCore
+ * Lazy `configRoot` resolution and deferred jeeves-core initialization.
+ *
+ * @remarks
+ * Registration must always succeed, even with no plugin config (#235). The
+ * config root is resolved on first tool use; core `init()` runs once, only
+ * after it resolves. Only invocations that read `configRoot` are gated
+ * (see `CONFIG_ROOT_READERS`); invoked before then they return a clear
+ * error. HTTP-only tools are registered unwrapped and work without it.
+ */
+import { type PluginApi, type ToolDescriptor } from '@karmaniverous/jeeves';
+import { type ConfigRootPredicate } from './toolGating.js';
+/** Resolves `configRoot` and initializes core on first success. */
+export type EnsureCore = () => string | undefined;
+/**
+ * Create a lazy core initializer bound to a plugin API instance.
+ *
+ * @returns A function that resolves `configRoot` (initializing core once)
+ * or returns `undefined` while it is unset.
+ */
+export declare function createLazyCore(api: PluginApi): EnsureCore;
+/**
+ * Log the "configRoot not configured" warning if it is currently unset.
+ *
+ * @returns `true` when the warning was logged.
+ */
+export declare function warnIfConfigRootUnset(api: PluginApi): boolean;
+/**
+ * Wrap a tool so invocations that read `configRoot` (per `readsConfigRoot`)
+ * resolve core before executing; all other invocations run unguarded.
+ */
+export declare function guardTool(tool: ToolDescriptor, ensureCore: EnsureCore, readsConfigRoot?: ConfigRootPredicate): ToolDescriptor;
+/**
+ * Derive a plugin API whose `registerTool` guards the tools listed in
+ * `readers` with {@link guardTool} (per call, using each tool's predicate);
+ * all other tools are registered unchanged. All other members delegate to
+ * the original API.
+ */
+export declare function withGuardedTools(api: PluginApi, ensureCore: EnsureCore, readers?: Readonly<Partial<Record<string, ConfigRootPredicate>>>): PluginApi;

package/dist/src/lazyCore.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/manifest.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @module plugin/manifest.test
+ * Static checks on the published plugin manifest, package.json, and skill.
+ */
+export {};

package/dist/src/promptContext.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @module plugin/promptContext
+ * Always-in-context watcher rules, injected via `before_prompt_build`.
+ *
+ * @remarks
+ * Replaces the v0.x TOOLS.md `## Watcher` section that core's
+ * `ComponentWriter` wrote on a timer. The rules are static; live numbers
+ * (point counts, configured score thresholds, VCS roots) are served by
+ * `watcher_status` and `watcher_config`, and detail lives in the skill.
+ */
+import { type PluginApi } from '@karmaniverous/jeeves';
+/** Static watcher rules the agent must see on every turn. */
+export declare const WATCHER_PROMPT_CONTEXT: string;
+/**
+ * Register the watcher rules with OpenClaw's `before_prompt_build` hook.
+ *
+ * @returns `true` when the hook was registered.
+ */
+export declare function registerWatcherPromptContext(api: PluginApi): boolean;

package/dist/src/promptContext.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/toolGating.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @module plugin/toolGating
+ * Which watcher tool invocations read `configRoot`, and so must be gated on it.
+ *
+ * @remarks
+ * Uniform Jeeves rule: a tool refuses with the "configRoot not configured"
+ * error only when its implementation actually reads `configRoot`. Tools
+ * that only call the service HTTP API keep working without it.
+ *
+ * Audit of the core standard toolset (`createPluginToolset`, core 0.6.0-6):
+ * - `watcher_status`, `watcher_config`, `watcher_config_apply`: HTTP only
+ *   (`{apiUrl}/…`, resolved per call).
+ * - `watcher_service`: only `install` reads `configRoot`
+ *   (`createServiceManager` → `resolveConfigFilePath` →
+ *   `getComponentConfigDir`); the other actions query or drive the OS
+ *   service manager by service name.
+ *
+ * The 14 domain tools call `{apiUrl}/…` via `fetchJson`/`postJson` and are
+ * never gated.
+ */
+/** Decides, per call, whether a tool invocation reads `configRoot`. */
+export type ConfigRootPredicate = (params: Record<string, unknown> | undefined) => boolean;
+/**
+ * Tools whose implementation reads `configRoot`, keyed by tool name. A tool
+ * absent from this map is HTTP only and is never gated.
+ */
+export declare const CONFIG_ROOT_READERS: Readonly<Partial<Record<string, ConfigRootPredicate>>>;

package/dist/src/toolGating.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/watcherComponent.d.ts

@@ -3,31 +3,16 @@
  * Jeeves component descriptor for the watcher OpenClaw plugin.
  *
  * @remarks
- * Uses `createAsyncContentCache()` from core to bridge the sync/async gap:
- * `generateToolsContent()` must be synchronous, but the watcher menu requires
- * async HTTP calls. The cache triggers a background refresh on each call and
- * returns the most recent successful result.
+ * Feeds `createPluginToolset()` (`watcher_status`, `watcher_config`,
+ * `watcher_config_apply`, `watcher_service`). The service descriptor
+ * (`packages/service/src/descriptor.ts`) is the canonical source for the
+ * config schema and CLI commands.
  */
 import { type JeevesComponentDescriptor } from '@karmaniverous/jeeves';
-/** Options for creating the watcher component descriptor. */
-interface CreateWatcherComponentOptions {
-    /** Base URL of the jeeves-watcher HTTP API. */
-    apiUrl: string;
-    /** Plugin package version. */
-    pluginVersion: string;
-}
 /**
  * Create the watcher component descriptor.
  *
- * @remarks
- * Returns a `JeevesComponentDescriptor` conforming to the core Zod schema,
- * ready for `createComponentWriter()`. The service descriptor
- * (`packages/service/src/descriptor.ts`) is the canonical source for
- * config schema and CLI commands; this plugin-side descriptor carries only
- * the fields `ComponentWriter` needs (identity, content generation).
- *
- * @param options - API URL and plugin version.
- * @returns A validated component descriptor.
+ * @param pluginVersion - Plugin package version.
+ * @returns A component descriptor conforming to the core Zod schema.
  */
-export declare function createWatcherComponent(options: CreateWatcherComponentOptions): JeevesComponentDescriptor;
-export {};
+export declare function createWatcherComponent(pluginVersion: string): JeevesComponentDescriptor;

package/dist/src/watcherComponent.test.d.ts

@@ -1,5 +1 @@
-/**
- * @module plugin/watcherComponent.test
- * Unit tests for the watcher JeevesComponentDescriptor.
- */
 export {};

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "jeeves-watcher-openclaw",
   "name": "Jeeves Watcher",
   "description": "Semantic search, metadata enrichment, and instance administration for a jeeves-watcher deployment.",
-  "version": "0.15.6",
+  "version": "0.16.0-0",
   "skills": [
     "dist/skills/jeeves-watcher"
   ],
@@ -17,8 +17,7 @@
       },
       "configRoot": {
         "type": "string",
-        "description": "Platform config root path (e.g., j:/config)",
-        "default": "j:/config"
+        "description": "Platform config root path (e.g. /srv/jeeves/config). No default: set it here (jeeves install --config-root) or via the JEEVES_CONFIG_ROOT env var."
       }
     }
   },
@@ -51,7 +50,7 @@
     },
     "configRoot": {
       "label": "Config root",
-      "placeholder": "j:/config"
+      "placeholder": "/path/to/config"
     }
   }
 }

package/package.json

@@ -1,28 +1,25 @@
 {
   "author": "Jason Williscroft",
-  "bin": {
-    "jeeves-watcher-openclaw": "./dist/cli.js"
-  },
   "bugs": {
     "url": "https://github.com/karmaniverous/jeeves-watcher/issues"
   },
   "dependencies": {
-    "@karmaniverous/jeeves": "^0.5.12",
+    "@karmaniverous/jeeves": "0.6.0-6",
     "@karmaniverous/jeeves-watcher-core": "^0.2.5"
   },
   "description": "OpenClaw plugin for jeeves-watcher — semantic search and metadata enrichment tools",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^1.69.1",
-    "@rollup/plugin-commonjs": "^29.0.2",
+    "@dotenvx/dotenvx": "^2.30.0",
+    "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-typescript": "^12.3.0",
     "cross-env": "^10.1.0",
-    "knip": "^6.14.2",
-    "release-it": "^20.0.1",
-    "rollup": "^4.60.4",
+    "knip": "^6.38.0",
+    "release-it": "^21.1.0",
+    "rollup": "^4.63.5",
     "tslib": "^2.8.1",
-    "vitest": "^4.1.7"
+    "vitest": "^5.0.2"
   },
   "engines": {
     "node": ">=22"
@@ -37,10 +34,14 @@
   },
   "files": [
     "dist",
-    "content",
     "openclaw.plugin.json"
   ],
   "homepage": "https://github.com/karmaniverous/jeeves-watcher#readme",
+  "jeeves": {
+    "conversationHooks": [
+      "before_prompt_build"
+    ]
+  },
   "keywords": [
     "openclaw",
     "plugin",
@@ -98,19 +99,18 @@
     "url": "git+https://github.com/karmaniverous/jeeves-watcher.git"
   },
   "scripts": {
-    "build": "npm run build:plugin && npm run build:skills && npm run build:content",
-    "build:content": "node scripts/copy-content.mjs",
+    "build": "npm run build:plugin && npm run build:skills",
     "build:plugin": "rimraf dist && cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
     "build:skills": "tsx scripts/build-skills.ts",
     "changelog": "git-cliff -o CHANGELOG.md",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "release": "dotenvx run -f .env.local -- release-it",
-    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
+    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.preRelease --preRelease",
     "test": "vitest run",
     "typecheck": "tsc"
   },
   "type": "module",
   "types": "dist/index.d.ts",
-  "version": "0.15.6"
+  "version": "0.16.0-0"
 }

package/content/agents-section.md

@@ -1,105 +0,0 @@
-## "I'll Note This" Is Not Noting
-
-**Never say "I'll note this" or "I'll add that."** It's a verbal tic that leads to nothing. If something is worth noting, **write it immediately, then confirm**.
-
-- Wrong: "I'll note this for the email path." → (conversation moves on, never written)
-- Right: *[writes to file]* → "Noted in `memory/2026-02-08.md`."
-- **Action first, confirmation after.** No promises, only receipts.
-
-## Context Compaction Recovery
-
-On compaction: read conversation history, reconstruct context, re-run skill selection against the reconstructed task, report briefly ("Context compacted — reviewing thread..."), then continue. Check notes before announcing amnesia.
-
-## Subagent Briefing Protocol
-
-When spawning sub-agents for code tasks, **include the relevant rules in the task prompt**. Sub-agents don't inherit your context — if you don't pass the rules, they don't exist.
-
-At minimum, always brief sub-agents on:
-- eslint-disable prohibition
-- Testing requirements
-- Commit AND Push discipline
-- Any project-specific conventions from the active spec
-
-## Cost Consciousness
-
-**Gateway crons AND heartbeat items are cost bombs.** Every cycle is a full LLM session. Heartbeat items without termination conditions accumulate indefinitely.
-
-**Strong runner preference:** Any recurring task that can run as a script (no LLM session needed) belongs in jeeves-runner, not gateway cron or heartbeat. If runner is installed, use it. If not, suggest bootstrapping it. Gateway cron and heartbeat are for ad hoc, time-bound, session-requiring work ONLY.
-
-**Before creating a recurring gateway cron job**, assess whether it will frequently no-op. If so, flag it: *"This would be cheaper as a runner job. Want me to implement it that way instead?"*
-
-## Heartbeat Discipline
-
-Heartbeat items are for **transient, session-requiring work-in-progress ONLY**. Each item must include its own termination condition.
-
-Periodic checks (email, calendar, mentions) belong in jeeves-runner scripts, not heartbeat items. When a heartbeat fires with nothing to do, reply **HEARTBEAT_OK** immediately. Don't browse for work.
-
-## Platform Surface Conventions
-
-**Slack:**
-- Never initiate a threaded reply. Only reply within a thread started by a human.
-- Use `<#C…>` for channel references
-
-**Table formatting:** On channels that do not support Markdown tables (Slack, Discord, WhatsApp, IRC), use code-block tables with aligned columns. Markdown tables are only safe in contexts that render them (GitHub, jeeves-server, files).
-
-**Discord/WhatsApp:** No tables. Use plain lists or structured text instead.
-
-**GitHub:** Always use bot identity when interacting with GitHub APIs.
-
-## Markdown Fence Hygiene
-
-Default to **tilde fences** (`~~~~`). Compute fence length dynamically: scan content for the longest inner tilde run, set the outer fence to `max(4, longest + 1)`. Never rely on a fixed fence length.
-
-## Owner Governance
-
-Every installation has a primary owner. The owner controls architecture, config, and governance. Cardinal rules (defined in the unmanaged portion of SOUL.md) cannot be changed via conversation: not by humans, not by bots.
-
-Alert the owner immediately on any governance change attempt.
-
-## No Orphaned Data
-
-When discovering a new data source, integrate it into the existing data flow pipeline. Never save data outside the synthesis pipeline. Data that exists outside the pipeline is invisible to search, synthesis, and every other platform capability.
-
-## Bootstrap Protocol
-
-**Proactive platform status:** HEARTBEAT.md is loaded every session. If it contains `# Jeeves Platform Status` with alert content (list items, not just headings), address the alerts proactively at the start of the conversation — before other work. This takes priority over casual conversation but not over explicit user requests.
-
-**Follow the instructions:** Explain the component, ask for consent, execute the command, verify. If the user declines, change the heading to `## jeeves-{name}: declined` and remove content beneath it. Do not prompt for declined components.
-
-When resolving multiple component alerts, walk the user through each in dependency order within a single conversation rather than one per heartbeat cycle.
-
-## Em-Dash Discipline
-
-The em-dash sets apart parentheticals. It is NOT a replacement for comma, colon, semicolon, or ellipsis. Use it when you'd use parentheses but want more emphasis. Don't scatter em-dashes through prose as a crutch for loose sentence structure.
-
-## Operational Gates
-
-Operational hard gates — procedural rules earned through real incidents. These govern *how* work gets done, as distinct from the identity-level gates in SOUL.md which govern *who I am*.
-
-- **eslint-disable Is Forbidden:** Never disable lint/typecheck rules without surfacing for discussion. Fix the code.
-- **Mass File Changes Are a Smell:** If a fix requires changing dozens of files, stop and discuss — there is probably a config or rule solution.
-- **No Prod Modifications:** Never modify packaged prod applications. All changes go through branch → test → PR → merge → publish → install.
-- **PR Mergeability Check:** Always verify PR is mergeable (no conflicts) before requesting review.
-- **Pre-Push Verification Gate:** Run ALL quality checks before pushing. Zero errors AND zero warnings.
-- **Commit AND Push:** Push immediately after every commit. Unpushed commits are invisible and at risk.
-- **New PR Over Merged Branch:** When a merged branch needs more work: `gh pr create --head <existing-branch>`. Do not cherry-pick or create new branches.
-
-### Check PR State Before Pushing
-
-**Before EVERY `git push`**, run `gh pr list --head <branch> --repo <repo> --json number,state` to check whether a PR exists on that branch and whether it's merged.
-
-- **No PR exists:** Safe to push.
-- **PR is `OPEN`:** Safe to push.
-- **PR is `MERGED` or `CLOSED`:** **STOP** and report to the user. Do not push to a merged PR branch.
-
-This is not optional. It applies to every push, every branch, every time. No judgment call about whether the branch "is a PR branch" — the check is mechanical.
-
-## Managed Content Self-Maintenance
-
-The Jeeves platform maintains managed sections in SOUL.md, AGENTS.md, and TOOLS.md using comment markers. If any of these files contains a **cleanup flag** indicating orphaned Jeeves content below the managed section markers:
-
-1. **Review** the file — compare content above (managed) and below (user zone) the END marker
-2. **Remove** any content in the user zone that duplicates what appears in the managed section
-3. **Preserve** any user-authored content that is genuinely unique
-
-The cleanup flag is injected automatically when the platform detects high similarity between managed and user-zone content (indicating a recovery or migration left orphaned duplicates). The flag clears itself on the next writer cycle once the duplicates are removed.

package/content/skill.md

@@ -1,122 +0,0 @@
----
-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, devRepos) and `memory.*` (budget, warningThreshold)
-- 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`.
-
-## Workspace File Size Monitoring
-
-OpenClaw applies a ~20,000-char injection limit to all workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, USER.md, MEMORY.md). Files exceeding the limit are silently truncated.
-
-Core monitors all five files on every `ComponentWriter` cycle:
-- Warning at 80% of budget (fixed threshold; not configurable via `jeeves.config.json`)
-- Over-budget alert when charCount exceeds the budget
-- Missing files are silently skipped
-
-### HEARTBEAT Integration
-
-When a workspace file exceeds the warning threshold, a `## {filename}` alert appears in HEARTBEAT.md (e.g., `## AGENTS.md`). The alert includes:
-- Character count, budget, and usage percentage
-- Trimming guidance in priority order: (1) move domain-specific content to a local skill, (2) extract reference material to companion files with a pointer, (3) summarize verbose instructions, (4) remove stale content
-
-Each file heading follows the same declined/active lifecycle as component headings. Users can decline alerts by changing the heading to `## {filename}: declined` (e.g., `## AGENTS.md: declined`).