ralph-hero-knowledge-index 0.1.53 → 0.1.55

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-knowledge",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "description": "Knowledge graph for ralph-hero: semantic search, relationship traversal, and document indexing across thoughts/ documents. Optional companion to ralph-hero.",
   "author": {
     "name": "Chad Dubiel",

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "ralph-knowledge": {
       "command": "npx",
-      "args": ["-y", "ralph-hero-knowledge-index@0.1.52"]
+      "args": ["-y", "ralph-hero-knowledge-index@0.1.53"]
     }
   }
 }

package/coverage/lcov-report/chunker.ts.html

@@ -940,7 +940,7 @@ export function chunkText(text: string, opts: ChunkerOptions = {}): Chunk[] {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/config.ts.html

@@ -385,7 +385,7 @@ export function loadConfig(): KnowledgeConfig {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/db.ts.html

@@ -1897,7 +1897,7 @@ export class KnowledgeDB {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/embedder.ts.html

@@ -763,7 +763,7 @@ export function prepareTextForEmbedding(
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/file-scanner.ts.html

@@ -199,7 +199,7 @@ export function findMarkdownFiles(dir: string, matcher?: IgnoreMatcher): string[
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/format.ts.html

@@ -295,7 +295,7 @@ export function formatTraverseResults(
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/generate-indexes.ts.html

@@ -670,7 +670,7 @@ export function writeTypeIndex(
   const superseded = docs.filter((d) => d.status === "superseded");
  
   const sortByDate = (a: ParsedDocument, b: ParsedDocument) =>
-    (b.date ?? <span class="branch-1 cbranch-no" title="branch not covered" >"").l</span>ocaleCompare(a.date ?? <span class="branch-1 cbranch-no" title="branch not covered" >"")</span>;
+    (b.date ?? <span class="branch-1 cbranch-no" title="branch not covered" >"")</span>.localeCompare(a.date ?? <span class="branch-1 cbranch-no" title="branch not covered" >"")</span>;
   active.sort(sortByDate);
   superseded.sort(sortByDate);
 &nbsp;
@@ -791,7 +791,7 @@ export function writeIssueHubs(outDir: string, allDocs: ParsedDocument[]): void
 const RECENT_LIMIT = 20;
 &nbsp;
 export function writeMasterIndex(outDir: string, allDocs: ParsedDocument[], hasUncategorized = false): void {
-  const sorted = [...allDocs].sort((a, b) =&gt; (b.date ?? <span class="branch-1 cbranch-no" title="branch not covered" >"").l</span>ocaleCompare(a.date ?? <span class="branch-1 cbranch-no" title="branch not covered" >"")</span>);
+  const sorted = [...allDocs].sort((a, b) =&gt; (b.date ?? <span class="branch-1 cbranch-no" title="branch not covered" >"")</span>.localeCompare(a.date ?? <span class="branch-1 cbranch-no" title="branch not covered" >"")</span>);
   const recent = sorted.slice(0, RECENT_LIMIT);
 &nbsp;
   const lines: string[] = [
@@ -946,7 +946,7 @@ export function generateIndexes(outDir: string, allDocs: ParsedDocument[]): void
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/graph-builder.ts.html

@@ -292,7 +292,7 @@ export class GraphBuilder {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/graph-tools.ts.html

@@ -2386,9 +2386,9 @@ export function registerGraphTools(server: McpServer, db: KnowledgeDB): void {
           // Run Louvain to partition, then extract the community subgraph
           const partition: Record<string, number> =
             graph.size > 0
-              ? louvain(graph, { rng: () =&gt; 0.5 }<span class="fstat-no" title="function not covered" ><span class="branch-1 cbranch-no" title="branch not covered" >)</span></span>
+              ? louvain(graph, { rng: () =&gt; 0.5 })
               : // No edges — each node is its own community, numbered by iteration order
-                (() =&gt; {
+                (() =&gt; <span class="fstat-no" title="function not covered" ><span class="branch-1 cbranch-no" title="branch not covered" >{</span></span>
                   const p: Record&lt;string, number&gt; = <span class="cstat-no" title="statement not covered" >{};</span>
                   let idx = <span class="cstat-no" title="statement not covered" >0;</span>
 <span class="cstat-no" title="statement not covered" >                  graph.<span class="fstat-no" title="function not covered" >forEachNode((n</span>) =&gt; { <span class="cstat-no" title="statement not covered" >p[n] = idx++; }</span>);</span>
@@ -2821,7 +2821,7 @@ export function registerGraphTools(server: McpServer, db: KnowledgeDB): void {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/hybrid-search.ts.html

@@ -1606,7 +1606,7 @@ export class HybridSearch {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/ignore.ts.html

@@ -316,7 +316,7 @@ export function loadIgnoreForRoot(
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/index.html

@@ -386,7 +386,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/index.ts.html

@@ -2052,8 +2052,8 @@ export function createServer(dbPath: string, opts: CreateServerOptions = {}) {
   // avoid touching the real dream-memories tree or paying the ONNX model
   // download in unit tests.
   const rememberFs = opts.rememberFs ?? {
-<span class="fstat-no" title="function not covered" >    mkdir: (<span class="cstat-no" title="statement not covered" >d</span>ir: string) =&gt; mkdirSync(dir, { recursive: true }),</span>
-<span class="fstat-no" title="function not covered" >    write: (p</span>ath: string, <span class="cstat-no" title="statement not covered" >body: string) =&gt; writeFileSync(path, body, "utf-8"),</span>
+<span class="fstat-no" title="function not covered" >    mkdir: (d</span>ir: string) =&gt; <span class="cstat-no" title="statement not covered" >mkdirSync(dir, { recursive: true }),</span>
+<span class="fstat-no" title="function not covered" >    write: (p</span>ath: string, body: string) =&gt; <span class="cstat-no" title="statement not covered" >writeFileSync(path, body, "utf-8"),</span>
   };
   const rememberReindexImpl = opts.rememberReindex ?? reindexPath;
   const rememberNow = opts.<span class="fstat-no" title="function not covered" ><span class="branch-1 cbranch-no" title="branch not covered" >rememberNow ?? (() =&gt; <span class="cstat-no" title="statement not covered" >n</span>ew Date());</span></span>
@@ -2065,7 +2065,7 @@ export function createServer(dbPath: string, opts: CreateServerOptions = {}) {
   // fail-open local LLM completion; tests inject a stub via `thinkComplete`.
   const thinkComplete =
     opts.<span class="fstat-no" title="function not covered" ><span class="branch-1 cbranch-no" title="branch not covered" >thinkComplete ??</span></span>
-    ((<span class="cstat-no" title="statement not covered" >prompt: string) =&gt; createLlmClient().complete(prompt, { maxTokens: 1024 }));</span>
+    ((prompt: string) =&gt; <span class="cstat-no" title="statement not covered" >createLlmClient().complete(prompt, { maxTokens: 1024 }));</span>
 &nbsp;
   server.tool(
     "knowledge_search",
@@ -2776,7 +2776,7 @@ server.connect(transport).catch(console.error);
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/llm-client.ts.html

@@ -592,7 +592,7 @@ export function createLlmClient(opts: LlmClientOptions = {}): LlmClient {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/parser.ts.html

@@ -622,7 +622,7 @@ export function parseDocument(id: string, path: string, raw: string): ParsedDocu
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/reindex.ts.html

@@ -1894,7 +1894,7 @@ export function <span class="fstat-no" title="function not covered" >resolveDirs
   const cliDb = <span class="cstat-no" title="statement not covered" >positional.<span class="fstat-no" title="function not covered" >find(a</span> =&gt; <span class="cstat-no" title="statement not covered" >a.endsWith(".db"))</span>;</span>
   const cliDirs = <span class="cstat-no" title="statement not covered" >positional.<span class="fstat-no" title="function not covered" >filter(a</span> =&gt; <span class="cstat-no" title="statement not covered" >!a.endsWith(".db"))</span>;</span>
 &nbsp;
-  const <span class="cstat-no" title="statement not covered" >config = loadConfig();</span>
+  const config = <span class="cstat-no" title="statement not covered" >loadConfig()</span>;
 &nbsp;
   const <span class="cstat-no" title="statement not covered" ><span class="fstat-no" title="function not covered" >resolveDbPath = (): string =&gt;</span></span>
 <span class="cstat-no" title="statement not covered" >    cliDb ??</span>
@@ -1978,9 +1978,9 @@ export async function <span class="fstat-no" title="function not covered" >reind
 ): Promise&lt;{ indexed: boolean }&gt; {
   let db: KnowledgeDB | undefined;
 <span class="cstat-no" title="statement not covered" >  try {</span>
-    const <span class="cstat-no" title="statement not covered" >absPath = resolve(filePath);</span>
-    const <span class="cstat-no" title="statement not covered" >raw = readFileSync(absPath, "utf-8");</span>
-    const <span class="cstat-no" title="statement not covered" >id = basename(absPath, ".md");</span>
+    const absPath = <span class="cstat-no" title="statement not covered" >resolve(filePath);</span>
+    const raw = <span class="cstat-no" title="statement not covered" >readFileSync(absPath, "utf-8");</span>
+    const id = <span class="cstat-no" title="statement not covered" >basename(absPath, ".md");</span>
     const relPath = <span class="cstat-no" title="statement not covered" >absPath; // single-path mode — use absolute path verbatim</span>
 &nbsp;
 <span class="cstat-no" title="statement not covered" >    db = new KnowledgeDB(dbPath);</span>
@@ -1989,7 +1989,7 @@ export async function <span class="fstat-no" title="function not covered" >reind
     const vec = <span class="cstat-no" title="statement not covered" >new VectorSearch(db);</span>
 <span class="cstat-no" title="statement not covered" >    vec.createIndex();</span>
 &nbsp;
-    const <span class="cstat-no" title="statement not covered" >parsed = parseDocument(id, relPath, raw);</span>
+    const parsed = <span class="cstat-no" title="statement not covered" >parseDocument(id, relPath, raw);</span>
 &nbsp;
 <span class="cstat-no" title="statement not covered" >    if (db.documentExists(parsed.id)) {</span>
 <span class="cstat-no" title="statement not covered" >      fts.deleteFtsEntry(parsed.id);</span>
@@ -2086,7 +2086,7 @@ const isMain = process.argv[1]?.endsWith("reindex.js");
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/reranker.ts.html

@@ -790,7 +790,7 @@ export class Reranker {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/search.ts.html

@@ -814,7 +814,7 @@ export class FtsSearch {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/think.ts.html

@@ -402,7 +402,7 @@ export function buildThinkPrompt(query: string, sources: ThinkSource[]): string
     .map((s) => {
       const title = s.title ? ` (${s.title})` : <span class="branch-1 cbranch-no" title="branch not covered" >"";</span>
       const tier = s.tier ? ` {${s.tier}}` : <span class="branch-1 cbranch-no" title="branch not covered" >"";</span>
-      const snippet = (s.snippet || <span class="branch-1 cbranch-no" title="branch not covered" >"").s</span>lice(0, SNIPPET_CLIP);
+      const snippet = (s.snippet || <span class="branch-1 cbranch-no" title="branch not covered" >"")</span>.slice(0, SNIPPET_CLIP);
       return `[${s.id}]${title}${tier}\n${snippet}`;
     })
     .join("\n\n");
@@ -428,7 +428,7 @@ export function buildThinkPrompt(query: string, sources: ThinkSource[]): string
 export function parseThinkResponse(
   text: string,
 ): { answer: string; gaps: string } | null {
-  let raw = (text || <span class="branch-1 cbranch-no" title="branch not covered" >"").t</span>rim();
+  let raw = (text || <span class="branch-1 cbranch-no" title="branch not covered" >"")</span>.trim();
   if (raw.startsWith("```")) {
     const firstNl = raw.indexOf("\n");
     <span class="missing-if-branch" title="else path not taken" >E</span>if (firstNl !== -1) raw = raw.slice(firstNl + 1);
@@ -514,7 +514,7 @@ export async function think(
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/traverse.ts.html

@@ -487,7 +487,7 @@ export class Traverser {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov-report/vector-search.ts.html

@@ -439,7 +439,7 @@ export class VectorSearch {
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-06-29T08:45:57.753Z
+                at 2026-07-26T13:32:06.309Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/coverage/lcov.info

@@ -973,7 +973,7 @@ FN:393,(anonymous_11)
 FN:411,(anonymous_12)
 FN:470,(anonymous_13)
 FN:490,(anonymous_14)
-FN:490,(anonymous_15)
+FN:492,(anonymous_15)
 FN:495,(anonymous_16)
 FN:500,(anonymous_17)
 FN:501,(anonymous_18)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-hero-knowledge-index",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -34,7 +34,7 @@
     "graphology-simple-path": "^0.2.0",
     "graphology-traversal": "^0.3.1",
     "graphology-types": "^0.24.8",
-    "ignore": "^7.0.5",
+    "ignore": "^7.0.6",
     "sqlite-vec": "^0.1.9",
     "yaml": "^2.9.0",
     "zod": "^3.25.0"
@@ -42,8 +42,8 @@
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.9.1",
-    "@vitest/coverage-v8": "^4.1.7",
-    "tsx": "^4.22.3",
+    "@vitest/coverage-v8": "^4.1.10",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "^4.0.0"
   }

package/skills/curate/SKILL.md

@@ -56,6 +56,8 @@ Scope matters: searching unscoped over a 3000+ document corpus dilutes the signa
 
 Use `knowledge_search` (semantic) plus `knowledge_central` (find central documents in communities) to surface 5–10 candidate atomic axioms within the chosen domain.
 
+**Also read the meta-reflection staging file** `~/projects/thoughts/wiki/_candidates.jsonl` (one JSON object per line: `axiom`, `rationale`, `source_reflection_ids`, `hash`). The weekly `meta_reflect.py` pass (GH-1513) stages pre-distilled wiki candidates here from the reflection tier — treat each as a strong, already-corroborated candidate, but still run it through the full distillation + gates below (staging is a suggestion, never a promotion). Skip any whose `hash` axiom is already an existing wiki entry or already in `_rejected.jsonl`.
+
 A candidate is high-signal if it:
 - States a principle in declarative form ("X must Y", "always X", "never X", "the rule is")
 - Recurs across 3+ documents (corroboration is the strongest durability signal)

package/skills/dream-loop/SKILL.md

@@ -1,11 +1,21 @@
 ---
-description: Run the dream-loop — the nightly memory-consolidation pipeline that ingests the last window of raw activity (Gemma lab logs, git history, llm-cli transcripts, Claude Code sessions) as memory_tier=raw documents, then clusters them and synthesizes one memory_tier=reflection per cluster. This is the memorykeepers surface that orchestrates the existing scripts/dream/ infra (ingest.py + reflect.py + logrotate.sh) on demand. Use when the user mentions "dream", "dream-loop", "consolidate memories", "run reflection", "memorykeepers", "ingest raw memories", or wants to manually trigger the memory tiers (raw to reflection) without waiting for the 03:00 launchd fire. The launchd nightly schedule and the model-gate dream-now zsh function are separate; this skill is the in-session manual entrypoint.
-argument-hint: "[--since 24h]"
+description: Run, bootstrap, or verify the dream-loop — the nightly memory-consolidation pipeline that ingests the last window of raw activity (Gemma lab logs, git history, llm-cli transcripts, Claude Code sessions) as memory_tier=raw documents, then clusters them and synthesizes one memory_tier=reflection per cluster. This is the memorykeepers surface that orchestrates the existing scripts/dream/ infra (ingest.py + reflect.py + logrotate.sh). Use when the user mentions "dream", "dream-loop", "dream-now", "consolidate memories", "run reflection", "memorykeepers", "ingest raw memories", or wants to manually trigger the memory tiers (raw to reflection) without waiting for the 03:00 launchd fire. Also use for machine wiring and health checks — "bootstrap the dream loop", "set up dream-loop", "install the nightly schedule", "check dream-loop status", "verify the dream loop ran", "did the dream loop ingest anything" — via --mode bootstrap and --mode verify.
+argument-hint: "[--since 24h | --mode bootstrap|verify]"
 ---
 
 # Dream-Loop — Memory Consolidation (memorykeepers)
 
-The dream-loop is the memory-consolidation pipeline for ralph-knowledge. It pulls raw activity into `memory_tier=raw` documents, then clusters them (UMAP/HDBSCAN) and asks a local model to synthesize one `memory_tier=reflection` per cluster. This skill is the in-session manual entrypoint that the memorykeepers team owns.
+The dream-loop is the memory-consolidation pipeline for ralph-knowledge. It pulls raw activity into `memory_tier=raw` documents, then clusters them (UMAP/HDBSCAN) and asks a local model to synthesize one `memory_tier=reflection` per cluster. This skill is the memorykeepers surface for the pipeline: a manual run entrypoint by default, plus `--mode bootstrap` (first-time machine wiring) and `--mode verify` (post-run health checks).
+
+## Modes
+
+| Mode | When | What it does |
+|------|------|--------------|
+| *(default)* run | "run the dream loop", "consolidate memories" | Steps 1–6 below: ingest → reflect → logrotate → report |
+| `--mode bootstrap` | first run on a machine, "bootstrap the dream loop" | Delegates to `scripts/dream/bootstrap.sh`; see **Bootstrap** |
+| `--mode verify` | "did it run?", "check dream-loop status" | Read-only health checks; see **Verify** |
+
+Resolve the mode from intent, not just the flag — "set up the dream loop on this machine" is bootstrap, "did last night's run work?" is verify, even without `--mode`.
 
 ## How you talk
 
@@ -25,7 +35,7 @@ You refuse to:
 3. **`~/.ralph/knowledge.config.json` authored** with the `roots` to scan and `dbPath`.
 4. **A local model reachable** at `RALPH_LLM_URL` (default `http://localhost:8000`) for the reflection synthesis step. If the model is unreachable, the pipeline fails open: empty reflections and a single stderr warning — raw ingest still succeeds.
 
-If `scripts/dream/` is absent, surface a clear error and stop: the dream-loop infra has not been set up. Direct the user to `/ralph-knowledge:setup` (which installs the launchd schedule and can bootstrap the scripts).
+If any prerequisite is missing, that is a bootstrap problem, not a run problem — switch to **Bootstrap** below rather than surfacing a bare error.
 
 ## Workflow
 
@@ -70,8 +80,47 @@ State, as facts with paths and tiers:
 - any clusters that crossed the recurring-failure thresholds and would warrant a `process-improvement` follow-up
 - whether the local model was reachable, or whether the run failed open
 
+## Bootstrap (`--mode bootstrap`)
+
+`scripts/dream/bootstrap.sh` is the single source of truth for machine wiring — it idempotently provisions `~/.ralph/knowledge.config.json`, renders + loads the templated launchd plist for the 03:00 nightly fire, and smoke-tests ingest. Never re-implement its steps inline; when wiring logic changes, it changes in `bootstrap.sh`.
+
+```bash
+cd <repo>/scripts/dream && uv sync          # python deps (one-time)
+cd <repo>/plugin/ralph-knowledge && npm install && npm run build   # indexer (one-time)
+bash <repo>/scripts/dream/bootstrap.sh      # config + launchd + smoke ingest
+```
+
+After it completes, run the **Verify** checks to confirm the wiring took. `/ralph-knowledge:setup` Step 4 invokes the same script — either surface is fine; they cannot drift because both delegate.
+
+**Machine conventions (optional):** if the machine has a model-gate checkout (`~/projects/model-gate`), prefer its surfaces for anything model-adjacent: `model-up <name>` to load the reflection model safely (stop-before-start on :8000), and the gate-aware `dream-now` zsh function as the shell-side equivalent of a full run. Registry of valid model names: `~/projects/models.yml`; setup details: `model-gate/README.md`. Absent model-gate, any OpenAI-compatible server at `RALPH_LLM_URL` works.
+
+## Verify (`--mode verify`)
+
+Read-only. Run what applies, report as facts with counts and paths:
+
+```bash
+# DB schema + tier breakdown
+sqlite3 ~/.ralph-hero/knowledge.db "SELECT * FROM meta WHERE key='schema_version'"
+sqlite3 ~/.ralph-hero/knowledge.db "SELECT memory_tier, COUNT(*) FROM documents GROUP BY memory_tier"
+
+# Files on disk vs indexed (stale index if these diverge)
+echo "On disk:  $(find ~/projects/thoughts/dream-memories -name '*.md' | wc -l)"
+echo "Indexed:  $(sqlite3 ~/.ralph-hero/knowledge.db 'SELECT COUNT(*) FROM documents WHERE path LIKE "%dream-memories%"')"
+
+# Local model reachability
+curl -fsS http://localhost:8000/v1/models | jq '.data[].id'
+
+# launchd nightly job (if installed): PID "-" when idle, exit status 0 after a clean run
+launchctl list | grep dream-loop
+```
+
+Interpretation notes:
+- `schema_version=3` is **correct, not stale** — the `wiki`-tier CHECK-constraint change is labeled "Migration v4" in `db.ts` but deliberately does not bump the meta stamp.
+- Four tiers exist: `doc` (curated), `raw` (dream ingest), `reflection` (synthesized), `wiki` (human-curated via `/ralph-knowledge:curate`; not writable by the record tool). A healthy post-run breakdown shows raw and reflection counts growing.
+- Zero reflections with nonzero raws usually means the model was unreachable at run time (the pipeline fails open) — check reachability above, then re-run reflect for the window.
+
 ## Relationship to other surfaces
 
-- **Nightly schedule** — `scripts/dream/launchd/com.dubiel.dream-loop.plist.template`, installed by `/ralph-knowledge:setup` (or `bootstrap.sh`). Fires at 03:00 daily. This skill is the manual on-demand counterpart.
-- **`dream-now`** — a model-gate zsh function that is gate-aware (loads the model first, then ingest + reflect + logrotate). Owned by model-gate, not this plugin. This skill does not call `dream-now`; it invokes the scripts directly.
+- **Nightly schedule** — `scripts/dream/launchd/com.dubiel.dream-loop.plist.template`, installed by `bootstrap.sh` (directly or via `/ralph-knowledge:setup`). Fires at 03:00 daily. This skill is the manual on-demand counterpart.
+- **`dream-now`** — a model-gate zsh function that is gate-aware (loads the model first, then ingest + reflect + logrotate). Owned by model-gate, not this plugin. The default run mode here invokes the scripts directly; point users at `dream-now` when they want the gate-managed shell path.
 - **`/ralph-knowledge:curate`** — the human-gated promotion of reflections into the personal wiki tier. The dream-loop produces reflections; curate (not this skill) decides what becomes canonical.