hotmilk 0.1.13 → 0.1.15

package/skills/recommend-research/references/verify-gate.md

@@ -0,0 +1,73 @@
+# Verify gate (Phase 3)
+
+**Load when:** Phase 3 runs — finalists exist and evidence-backed recommendation is next.
+
+**Do NOT load when:** Scope not pinned (scope-gate). No finalists yet (shortlist-gate). User only asked for a link or doc lookup with no recommendation — use skill resolution ladder inline.
+
+## Verify ladder (per finalist)
+
+Run passes in order. Stop early when **done** criteria pass for the asked question depth.
+
+| Pass | Source               | Skill / tool                                                                            | Proves                                                                                 |
+| ---- | -------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| 1    | Official docs        | fetch / web-search / brave-search                                                       | API contract, supported versions, install, license statement                           |
+| 2    | Changelog / releases | same                                                                                    | Breaking changes, release cadence                                                      |
+| 3    | Repository           | **`/skill:deepwiki`** or README                                                         | Architecture, scope, documented limits                                                 |
+| 4    | Source / history     | **`/skill:librarian`** or **`/skill:opensrc`** + `rg`/`find` on `$(opensrc path <pkg>)` | Internals, edge cases, performance, "why" — source **search**, not candidate discovery |
+| 5    | Issues / security    | librarian / gh / advisory DB                                                            | Open blockers, CVE status                                                              |
+
+**Contract questions** → pass 1–2 often enough. **Internals / performance** → pass 4 required. Do not skip pass 1 because pass 4 is tempting.
+
+## Holistic verify (cross-layer picks)
+
+When scope-gate chose **Holistic**, run per-finalist passes **and** this integration table before Phase 4:
+
+| Row                     | Check                                                       |
+| ----------------------- | ----------------------------------------------------------- |
+| API compatibility       | Shared types, auth tokens, error shapes across layers       |
+| Shared auth / identity  | One login story; no duplicate secret stores                 |
+| Deployment coupling     | Can layers deploy independently? Single rollback path?      |
+| Data / schema alignment | Migrations, IDs, event contracts between components         |
+| Ops surface             | One observability story; avoid N unrelated agents           |
+| Rollback                | Partial failure — which layer reverts without orphan state? |
+
+Holistic **done** requires at least one integrated stack story (not independent per-layer winners) with citations per layer.
+
+## Per-finalist checklist
+
+| Row         | Required for production pick                                  |
+| ----------- | ------------------------------------------------------------- |
+| License     | SPDX or README license — compatible with stated use           |
+| Maintenance | Last release or commit within acceptable window for risk tier |
+| API fit     | Maps to must-haves from scope-gate with doc citation          |
+| Ops fit     | Install size, runtime deps, platform support                  |
+| Exit path   | Migration or wrap cost if pick fails                          |
+
+## Unavailable source fallbacks
+
+| Situation                       | Fallback                                                              |
+| ------------------------------- | --------------------------------------------------------------------- |
+| Docs site down                  | Cached README, deepwiki, tagged release tree; say source is secondary |
+| Private repo                    | Only public evidence; flag "cannot verify internals"                  |
+| Archived project                | Recommend against unless user explicitly accepts unmaintained risk    |
+| opensrc / librarian unavailable | Official docs + changelog only; widen **Evidence gaps** in verdict    |
+| Conflicting blog vs docs        | **Docs win** unless source inspection proves blog correct             |
+
+## Done criteria (Phase 3 complete)
+
+Verify gate is **done** when:
+
+1. Every **finalist** has pass 1 complete; passes 2–5 match question depth
+2. At least one finalist has clear **pick** support with citations (doc URL or permalink)
+3. Alternatives have explicit **why not** or tie-breaker
+4. **Evidence gaps** listed — empty only when passes required for scope are satisfied
+
+If done criteria fail, do **not** emit Phase 4 recommendation. State missing evidence and offer next verify step or user waiver.
+
+## Handoff after verify
+
+| Next user intent                  | Skill                                 |
+| --------------------------------- | ------------------------------------- |
+| Implement integration in hotmilk  | **`/skill:pioneer`**                  |
+| Large multi-agent integration bet | **`/skill:tcz-agent-converge`**       |
+| Prompt/skill edit from research   | **`/prompt-eval <path>`** before ship |

package/skills/update-docs/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: update-docs
+description: Sync documentation to code and config — README, CONTRIBUTING, AGENTS.md, CLAUDE.md, docs/, manifests, CI, config templates (e.g. hotmilk.json), and post-merge doc drift. Use for /update-docs, update docs, sync docs, docs drift, stale README, or after changes to commands, defaults, toggles, dependencies, or module layout.
+---
+
+# Update docs
+
+Reconcile docs with **code and config as source of truth**. Fix drift; do not rewrite for voice or expand scope.
+
+## Scenario router (read first)
+
+| User signal                                    | Route                                                                                                                     |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| "Sync all docs" / post-release / manifest work | **Full** — Phase 0 → 4; read entire [`doc-inventory.md`](references/doc-inventory.md)                                     |
+| Named file only (`README`, one doc file)       | **Targeted** — Phase 1–3 on that file + its truth sources from inventory                                                  |
+| User just shipped code; docs maybe stale       | **Post-ship** — read ONLY **Post-ship triggers** in `doc-inventory.md`; do NOT load `drift-verification.md` until Phase 4 |
+| User wants new docs / rewrite tone             | **Stop** — sync fixes truth; ask whether to write new content separately                                                  |
+
+**References:** Do **not** read `references/` until a phase below requires it. Each reference states load conditions at the top.
+
+## Phase map
+
+Skip phases that do not apply. State which phase was skipped and why.
+
+```text
+0. Scope           → doc-inventory.md          (Full sync — MANDATORY READ ENTIRE FILE)
+1. Recon           → truth files + target docs (read-only)
+2. Diff            → drift list only           (no edits yet)
+3. Patch           → minimal surgical edits    (one theme per pass unless user asked batch)
+4. Verify          → drift-verification.md     (MANDATORY READ ENTIRE FILE before reporting done)
+```
+
+## Recon rules (Phase 1)
+
+| Rule            | Detail                                                                                                                                    |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Truth first     | Read listed source-of-truth files before editing any doc                                                                                  |
+| No invention    | If truth is silent, report the gap — do not guess commands, paths, or defaults                                                            |
+| Truth conflicts | When doc, manifest, and CI disagree: **CI > manifest scripts/targets > source comments**; report the conflict instead of picking silently |
+| Scope           | Touch only doc files implicated by the diff; no drive-by style edits                                                                      |
+| Language        | Match each file's existing language and heading style                                                                                     |
+
+## Patch rules (Phase 3)
+
+| Do                                                                         | Do not                                                                     |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Fix factual drift (commands, paths, defaults, version pins, module layout) | Rewrite unrelated sections for "clarity"                                   |
+| Keep tables and lists aligned when two docs cover the same fact            | Duplicate long prose — prefer one canonical section + link                 |
+| Update config samples when **code** defaults changed                       | Change runtime defaults in code while "fixing" docs unless user asked      |
+| Preserve technical terms and command literals                              | Translate or rephrase during drift sync unless user asked for localization |
+
+## Output (Phase 4)
+
+Emit after the verify checklist passes (or list blockers):
+
+```markdown
+## Doc sync report
+
+**Scope:** full | targeted | post-ship
+**Truth sources read:** …
+**Files patched:** … (or none)
+
+### Drifts fixed
+
+- …
+
+### Gaps (no truth — not patched)
+
+- …
+
+### Verify
+
+- [ ] …
+```
+
+## Anti-patterns
+
+| Do not                                                              | Why                                     | Do instead                                       |
+| ------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------ |
+| Read `references/` without a matching route                         | Token waste                             | Router row first                                 |
+| Edit docs before reading truth files                                | Propagates stale claims                 | Phase 1 recon                                    |
+| Full README rewrite on a targeted request                           | Review noise                            | Named file only                                  |
+| Add a `docs/` tree when the repo has none                           | Scope creep                             | Skip; mention only if user wants new docs        |
+| "Improve" prose without drift                                       | Style ≠ sync                            | Diff list must cite a truth mismatch             |
+| Skip verify after patch                                             | Drift returns unnoticed                 | Phase 4 checklist                                |
+| Copy root manifest commands into every package README in a monorepo | Wrong scope; breaks package-local truth | Root ↔ root manifest; package ↔ package manifest |

package/skills/update-docs/references/doc-inventory.md

@@ -0,0 +1,69 @@
+# Doc inventory
+
+**Load when:** Phase 0 (full sync), or you need the truth → doc matrix for an unfamiliar drift.
+
+**Do NOT load when:** Post-ship route already names the row (read that row here only if unsure), or the user scoped a single file you already know.
+
+Code and config win. Docs below are reconciliation targets. **Adapt rows to the repo** — skip rows that do not exist.
+
+## Detect project type (Phase 0)
+
+Read one manifest first, then use the matching rows:
+
+| Signal file                   | Project type   |
+| ----------------------------- | -------------- |
+| `package.json`                | Node / JS / TS |
+| `Cargo.toml`                  | Rust           |
+| `pyproject.toml` / `setup.py` | Python         |
+| `go.mod`                      | Go             |
+| `pom.xml` / `build.gradle*`   | JVM            |
+
+Also note doc roots if present: `README.md`, `CONTRIBUTING.md`, `docs/`, `CHANGELOG.md`, and any root instruction files (`AGENTS.md`, `CLAUDE.md`, …).
+
+**Monorepo / multi-manifest:** When root and package manifests both exist, treat **root manifest scripts + root README/CONTRIBUTING** as canonical for repo-wide commands. Package READMEs get package-local scripts and paths only — do not copy root commands into every package README unless that package owns them.
+
+## Truth → doc matrix
+
+| Source of truth                                                                | What to extract                                                       | Doc targets                                                                      |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Package manifest (`package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, …) | Scripts/commands, deps, version, entry points, published files        | `README.md`, `CONTRIBUTING.md`                                                   |
+| Source layout (`src/`, `lib/`, `cmd/`, …)                                      | Module roles, public API surface                                      | README architecture section, `docs/`                                             |
+| CI config (`.github/workflows/`, `.gitlab-ci.yml`, …)                          | Test/lint/build commands                                              | `README.md`, `CONTRIBUTING.md`                                                   |
+| Config templates in repo root                                                  | Default values users copy                                             | README config sample, setup docs                                                 |
+| `CHANGELOG.md` / release tags                                                  | Version, breaking changes                                             | README version notes                                                             |
+| `docs/` (when directory exists)                                                | Topic pages, API reference                                            | Cross-link from README; do not create `docs/` during sync                        |
+| Root instruction files (when present)                                          | Commands, layout tables, contributor rules                            | That file only — do not invent paths                                             |
+| Workspace / monorepo (root + package manifests)                                | Root scripts for repo-wide ops; package scripts for package-local ops | Root README/CONTRIBUTING ↔ root manifest; package README ↔ that package manifest |
+
+## Post-ship triggers (targeted recon)
+
+When the user changed code recently, scan **only** rows touched by the change:
+
+| Change area                                                              | Minimum doc pass                                                            |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| New dependency or entry point                                            | Manifest ↔ README (+ CONTRIBUTING if it lists deps)                         |
+| Default config flip or toggle default change                             | Config template ↔ README sample and feature/toggle tables                   |
+| Lazy-loaded or opt-in feature (doc mentions it; default off in template) | Template defaults ↔ README — mark opt-in/experimental when default is false |
+| New script or test command                                               | Manifest scripts ↔ README + CONTRIBUTING                                    |
+| Version / peer bump                                                      | README version note, manifest version constraints                           |
+| Public API or module layout change                                       | Layout tables, `docs/` API pages                                            |
+| CI workflow change                                                       | CONTRIBUTING / README verify commands                                       |
+
+## Full-sync order
+
+1. Detect project type; read truth files for applicable matrix rows.
+2. Read every doc target listed for those rows.
+3. Build a diff list — fact mismatches only.
+4. Patch the smallest set of files that restores consistency.
+5. Run [`drift-verification.md`](drift-verification.md).
+
+## Common drifts (quick scan)
+
+| Symptom                                        | Likely fix                                                                    |
+| ---------------------------------------------- | ----------------------------------------------------------------------------- |
+| README command does not exist in manifest      | Align with manifest scripts/targets                                           |
+| Doc paths point to removed modules             | Update layout table from current tree                                         |
+| Config sample shows stale defaults             | Copy from repo config template after confirming code                          |
+| Doc lists a feature not in manifest/config     | Remove or mark as external/optional                                           |
+| Duplicate facts disagree across two docs       | Pick one canonical source; link from the other                                |
+| Doc, manifest, and CI disagree on same command | Apply precedence (CI > manifest > source); report conflict if still ambiguous |

package/skills/update-docs/references/drift-verification.md

@@ -0,0 +1,59 @@
+# Drift verification
+
+**Load when:** Phase 4 — after any patch, or when reporting "docs already in sync."
+
+**Do NOT load when:** Recon-only pass with zero edits planned — skip to a short "no drift found" note instead.
+
+**Truth conflicts:** When sources disagree, apply **CI > manifest scripts/targets > source comments**. Report unresolved conflicts in **Gaps** — do not patch until the user picks a winner.
+
+## Checklist
+
+Mark each item that applies to scope. All applicable items must pass before "done."
+
+### Always (any patch)
+
+- [ ] Every edited claim traces to a truth file read this session (path named in report)
+- [ ] No code or config files changed unless the user explicitly asked to fix defaults
+- [ ] Diff stayed within scoped doc files — no cosmetic-only edits elsewhere
+
+### Full sync
+
+- [ ] README commands match manifest scripts/targets (or language equivalent); in monorepos, root README uses root manifest — package READMEs use package manifest only
+- [ ] Config template in docs matches repo config defaults
+- [ ] Path references in edited docs still exist on disk
+- [ ] Duplicate facts across docs agree — one canonical source preferred
+
+### Optional (when root instruction files were in scope)
+
+- [ ] Command and layout tables match manifest, CI, and current tree
+
+### Post-ship: dependency / manifest
+
+- [ ] New manifest entries have matching README mention when user-facing
+- [ ] Opt-in or experimental features documented when defaults are off
+
+## Commands (adapt to project)
+
+```bash
+# Which doc files changed
+git diff --name-only -- '*.md'
+
+# Node: list scripts
+node -e "console.log(require('./package.json').scripts)"
+
+# Rust: list bin targets
+cargo metadata --no-deps --format-version 1 | head
+
+# Python: project scripts (when pyproject.toml exists)
+python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb')).get('project',{}).get('scripts',{}))" 2>/dev/null || true
+```
+
+Run the project's test/lint command when code changed in the same task (from README, CONTRIBUTING, CI config, or manifest scripts). Markdown-only sync does not require a full test run.
+
+## Report blockers
+
+If a checklist item fails, report **blocked** with:
+
+- which item failed
+- what truth vs doc say
+- whether user decision is needed (e.g. intentional undocumented feature)

package/src/bootstrap/btw.ts

@@ -1,3 +1,11 @@
+/**
+ * BTW (side-thread) injection for hotmilk.
+ *
+ * Strips main-session harness sections, replaces append prompts, and proxies
+ * context-mode/graphify tools into pi-btw sub-sessions without loading bundled
+ * extensions there.
+ */
+
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -17,16 +25,22 @@ import { bundledImportUrl } from "./resolve-bundled.ts";
 
 // --- Session config (injected before btw extension loads) ---
 
+/** Per-session config injected into the BTW extension before it loads. */
 export type HotmilkBtwConfig = {
   extensionToggles: Readonly<Record<BundledExtensionId, boolean>>;
 };
 
 let activeConfig: HotmilkBtwConfig | null = null;
 
+/** Inject the active hotmilk config for the upcoming BTW session. */
 export function setHotmilkBtwConfig(config: HotmilkBtwConfig): void {
   activeConfig = config;
 }
 
+/**
+ * Return the config injected by {@link setHotmilkBtwConfig}.
+ * @throws when called before registration.
+ */
 export function getHotmilkBtwConfig(): HotmilkBtwConfig {
   if (!activeConfig) {
     throw new Error(
@@ -36,12 +50,14 @@ export function getHotmilkBtwConfig(): HotmilkBtwConfig {
   return activeConfig;
 }
 
+/** Clear the active config so tests start from a clean state. */
 export function resetHotmilkBtwConfigForTests(): void {
   activeConfig = null;
 }
 
 // --- Prompt shaping ---
 
+/** Remove dynamically appended date/time/cwd footer lines from a system prompt. */
 export function stripDynamicSystemPromptFooter(systemPrompt: string): string {
   return systemPrompt
     .replace(/\nCurrent date and time:[^\n]*(?:\nCurrent working directory:[^\n]*)?$/u, "")
@@ -59,6 +75,7 @@ const MAIN_SESSION_SECTION_MARKERS = [
   /^<behavioral_directive>/im,
 ] as const;
 
+/** Strip hotmilk-specific harness sections from the main session prompt. */
 export function stripHotmilkMainSessionHarness(systemPrompt: string): string {
   let next = systemPrompt;
   for (const marker of MAIN_SESSION_SECTION_MARKERS) {
@@ -69,6 +86,7 @@ export function stripHotmilkMainSessionHarness(systemPrompt: string): string {
   return next.trim();
 }
 
+/** Base system prompt used for BTW side threads. */
 export const HOTMILK_BTW_SYSTEM_PROMPT = [
   "You are having an aside conversation with the user, separate from their main working session.",
   "If main session messages are provided, they are for context only — that work is being handled by another agent.",
@@ -80,6 +98,11 @@ export const HOTMILK_BTW_SYSTEM_PROMPT = [
   "ctx_search is available as a read-only proxy to the main session knowledge base — use it for timeline recall, prior decisions, and indexed content. Do not use ctx_execute, ctx_batch_execute, or ctx_purge from BTW; loading context-mode here would spawn a second MCP child.",
 ].join(" ");
 
+/**
+ * Build the extra instructions appended to BTW sessions.
+ * @param options - toggles that determine which routing hints to include
+ * @returns ordered instruction lines
+ */
 export function buildHotmilkBtwAppendPrompt(options: {
   graphifyEnabled: boolean;
   subagentsEnabled: boolean;
@@ -126,6 +149,13 @@ function isBtwSummarizeSession(loader: ResourceLoader): boolean {
   return text.includes("Summarize the side conversation");
 }
 
+/**
+ * Wrap a Pi resource loader so BTW gets a neutral loader: no bundled extensions,
+ * a stripped system prompt, and hotmilk-tailored append instructions.
+ *
+ * @param loader - upstream pi-btw loader
+ * @param config - hotmilk toggle config
+ */
 export function adaptBtwResourceLoaderForHotmilk(
   loader: ResourceLoader,
   config: HotmilkBtwConfig,
@@ -175,6 +205,10 @@ type MainCtxSearchTool = {
 let mainCtxSearchTool: MainCtxSearchTool | null = null;
 let ctxSearchCaptureInstalled = false;
 
+/**
+ * Store the main-session `ctx_search` tool definition so BTW can proxy it.
+ * Ignores tools whose name is not `ctx_search`.
+ */
 export function captureMainCtxSearchTool(tool: {
   name: string;
   description: string;
@@ -190,10 +224,12 @@ export function captureMainCtxSearchTool(tool: {
   };
 }
 
+/** @returns the captured tool, or null if none has been registered. */
 export function getMainCtxSearchToolForTests(): MainCtxSearchTool | null {
   return mainCtxSearchTool;
 }
 
+/** Reset captured tool and installation guard for tests. */
 export function resetMainCtxSearchCaptureForTests(): void {
   mainCtxSearchTool = null;
   ctxSearchCaptureInstalled = false;
@@ -254,10 +290,18 @@ const CTX_SEARCH_FALLBACK_PARAMS = Type.Object({
   ),
 });
 
+/** Check whether a graphify graph exists in the working directory. */
 export function graphifyGraphExists(cwd = process.cwd()): boolean {
   return existsSync(join(cwd, GRAPH_JSON));
 }
 
+/**
+ * Choose the base tool set exposed in BTW.
+ *
+ * Read-biased when subagents are enabled; otherwise keeps edit/write tools.
+ *
+ * @param config - hotmilk toggle config
+ */
 export function resolveHotmilkBtwTools(config: HotmilkBtwConfig): string[] {
   if (config.extensionToggles.subagents === true) {
     return ["read", "grep", "find", "ls", "bash"];
@@ -293,6 +337,11 @@ function createCtxSearchProxyTool(mainTool: MainCtxSearchTool | null): ToolDefin
   });
 }
 
+/**
+ * Build BTW custom tools (`ctx_search` proxy, `graphify_query`) based on toggles.
+ *
+ * @param config - hotmilk toggle config
+ */
 export function createHotmilkBtwCustomTools(config: HotmilkBtwConfig): ToolDefinition[] {
   const tools: ToolDefinition[] = [];
 

package/src/bootstrap/context-stack.ts

@@ -1,3 +1,10 @@
+/**
+ * RTK-optimizer / context-mode coexistence bootstrap.
+ *
+ * Seeds and synchronizes pi-rtk-optimizer config so it works alongside
+ * context-mode, and prunes stale context-mode MCP server entries.
+ */
+
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
@@ -8,15 +15,25 @@ import type { BundledExtensionId } from "../config/hotmilk.ts";
 const RTK_EXTENSION_DIR = "pi-rtk-optimizer";
 const RTK_CONFIG_FILENAME = "config.json";
 
+/** @returns the absolute path to pi-rtk-optimizer's `config.json`. */
 export function getRtkOptimizerConfigPath(): string {
   return `${getAgentDir()}/extensions/${RTK_EXTENSION_DIR}/${RTK_CONFIG_FILENAME}`;
 }
 
+/**
+ * Decide the RTK mode that best coexists with context-mode.
+ *
+ * @returns `"suggest"` when context-mode is on, `"rewrite"` otherwise.
+ */
 export function expectedRtkMode(contextModeEnabled: boolean): "suggest" | "rewrite" {
   return contextModeEnabled ? "suggest" : "rewrite";
 }
 
-/** Defaults when hotmilk seeds pi-rtk-optimizer config for the first time. */
+/**
+ * Build the default pi-rtk-optimizer config shaped for hotmilk.
+ *
+ * @param contextModeEnabled - whether context-mode is toggled on
+ */
 export function buildHotmilkRtkConfig(contextModeEnabled: boolean): Record<string, unknown> {
   return {
     enabled: true,
@@ -53,17 +70,32 @@ function writeRtkConfig(configPath: string, config: unknown): void {
   writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
 }
 
+/**
+ * Create pi-rtk-optimizer config if it does not already exist.
+ *
+ * @param contextModeEnabled - whether context-mode is toggled on
+ * @param configPath - override config path (default: agent extension dir)
+ * @returns seed result, with `error` set on filesystem failure
+ */
 export function seedRtkConfigIfMissing(
   contextModeEnabled: boolean,
   configPath = getRtkOptimizerConfigPath(),
-): { seeded: boolean; path: string } {
+): { seeded: boolean; path: string; error?: string } {
   if (existsSync(configPath)) {
     return { seeded: false, path: configPath };
   }
 
-  mkdirSync(dirname(configPath), { recursive: true });
-  writeRtkConfig(configPath, buildHotmilkRtkConfig(contextModeEnabled));
-  return { seeded: true, path: configPath };
+  try {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeRtkConfig(configPath, buildHotmilkRtkConfig(contextModeEnabled));
+    return { seeded: true, path: configPath };
+  } catch (error) {
+    return {
+      seeded: false,
+      path: configPath,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
 }
 
 /** Hotmilk-managed fields only — does not touch Pi auto-compaction (settings.json). */
@@ -87,30 +119,55 @@ function alignRtkConfigWithContextMode(
   return changed;
 }
 
+/**
+ * Keep pi-rtk-optimizer config aligned with the context-mode toggle.
+ *
+ * Seeds when missing, otherwise updates `mode` and `readCompaction`.
+ *
+ * @param contextModeEnabled - whether context-mode is toggled on
+ * @param rtkEnabled - whether rtk-optimizer is toggled on
+ * @param configPath - override config path (default: agent extension dir)
+ */
 export function syncRtkConfigForContextStack(
   contextModeEnabled: boolean,
   rtkEnabled: boolean,
   configPath = getRtkOptimizerConfigPath(),
-): { updated: boolean; seeded: boolean; path: string } {
+): { updated: boolean; seeded: boolean; path: string; error?: string } {
   if (!rtkEnabled) {
     return { updated: false, seeded: false, path: configPath };
   }
 
   if (!existsSync(configPath)) {
-    seedRtkConfigIfMissing(contextModeEnabled, configPath);
+    const seeded = seedRtkConfigIfMissing(contextModeEnabled, configPath);
+    if (seeded.error) {
+      return { updated: false, seeded: false, path: configPath, error: seeded.error };
+    }
     return { updated: true, seeded: true, path: configPath };
   }
 
-  const config = JSON.parse(readFileSync(configPath, "utf8")) as RtkConfigRecord;
-  const changed = alignRtkConfigWithContextMode(config, contextModeEnabled);
-  if (changed) {
-    writeRtkConfig(configPath, config);
-  }
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf8")) as RtkConfigRecord;
+    const changed = alignRtkConfigWithContextMode(config, contextModeEnabled);
+    if (changed) {
+      writeRtkConfig(configPath, config);
+    }
 
-  return { updated: changed, seeded: false, path: configPath };
+    return { updated: changed, seeded: false, path: configPath };
+  } catch (error) {
+    return {
+      updated: false,
+      seeded: false,
+      path: configPath,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
 }
 
-/** Run before bundled extensions register (rtk seed/sync when that toggle is on). */
+/**
+ * Eagerly seed/sync RTK config before bundled extensions register.
+ *
+ * @param extensionToggles - resolved bundled-extension toggle state
+ */
 export function prepareContextStack(extensionToggles: Record<BundledExtensionId, boolean>): void {
   if (extensionToggles["rtk-optimizer"]) {
     syncRtkConfigForContextStack(extensionToggles["context-mode"], true);

package/src/bootstrap/dashboard-settings.ts

@@ -1,3 +1,10 @@
+/**
+ * Dashboard bridge settings cleanup.
+ *
+ * Removes redundant standalone dashboard bridge entries from Pi agent settings
+ * when hotmilk already bundles the agent-dashboard extension.
+ */
+
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -37,13 +44,20 @@ function isBundledDashboardExtensionEntry(entry: string): boolean {
   return readPackageName(entry) === DASHBOARD_EXTENSION_NAME;
 }
 
+/** Options for {@link pruneRedundantDashboardPackage}. */
 export interface PruneDashboardSettingsOptions {
+  /** Override `$HOME` resolution. */
   homedir?: string;
 }
 
 /**
- * When hotmilk bundles agent-dashboard, drop standalone bridge paths from
- * ~/.pi/agent/settings.json that pi-dashboard start auto-registers.
+ * Drop standalone dashboard-bridge paths from `~/.pi/agent/settings.json`.
+ *
+ * The bundled agent-dashboard extension already provides the bridge, so the
+ * legacy standalone package entry is redundant.
+ *
+ * @param opts - optional overrides
+ * @returns whether any entries were removed
  */
 export function pruneRedundantDashboardPackage(opts: PruneDashboardSettingsOptions = {}): boolean {
   const home = opts.homedir ?? process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();