@dzhechkov/harness-cli 0.3.138 → 0.3.142

package/README.md

@@ -325,7 +325,7 @@ Get the whole set with `dz init --target claude-code --preset meta`, or pick one
 
 > **A skill and its npx toolkit are not duplicates — they're a graduation.** Several skills (e.g. `feature-adr`, `design-thinking`) exist BOTH as a skill inside a `dz` preset AND as a standalone `npx` package. The preset's SKILL.md is **fully functional on its own** (the whole methodology — modules + references — travels with it, and it auto-activates by description), and it's the only way to compile that capability to the **non-Claude platforms** (Codex/OpenCode/Hermes/OpenClaude) via `dz`. The npx package adds **project-level runtime governance** around the same skill: a slash command, governance rules, a context shard, and (for feature-adr) reward-learning + `/harvest`. So: pick the **skill/preset** for a working capability across platforms; pick the **npx toolkit** when you want it as a governed, command-driven fixture of one project.
 
-## All Commands (35)
+## All Commands (36)
 
 ```
 dz setup             --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force]
@@ -336,6 +336,11 @@ dz teach             "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule
 dz consolidate       [--sessions-dir <dir>] [--project <dir>] [--no-mirror]
 dz recall            "<query>" [--limit <N>] [--project <dir>]
 dz recall --books    "<query>" [--book <slug>]      # digitized-book KUs; --book narrows to one book
+dz brain list        [--json]                                        # the durable cross-project knowledge brain
+dz brain query       "<q>" [--source <slug>] [--limit <N>] [--json]  # cross-source lexical recall over the brain
+dz brain add         [--source <slug>] [--project <dir>] [--json]    # promote this project's digitized-book KUs into the brain
+dz brain ground      "<prompt>" [--k <N>] [--source <slug>] [--text] # retrieve + emit grounding citations (hook entrypoint; silent if irrelevant)
+dz brain init        [--project <dir>] [--k <N>]                     # opt-in: wire the grounding UserPromptSubmit hook into settings.json
 dz pretrain          [--project <dir>]
 dz recommend         "<task description>"
 dz compose           <preset1+preset2+...> [--target <name>]

package/dist/cli.d.ts

@@ -7,6 +7,12 @@
 export interface CliIo {
     readonly cwd?: string;
     readonly write?: (line: string) => void;
+    /**
+     * Pre-read STDIN content (injectable so `dz brain ground`'s hook path is testable without
+     * an actual pipe). When omitted, the CLI reads fd 0 synchronously — but only for the one
+     * command that needs it (`brain ground`), and never when stdin is a TTY (nothing piped).
+     */
+    readonly stdin?: string;
 }
 export declare function runCli(argv: string[], io?: CliIo): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA6GH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAw6DD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA0F5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsHH,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AA6xED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAsG5E"}

package/dist/cli.js

@@ -9,7 +9,7 @@ import { execSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
-import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, consolidateSessions, pruneNoisePatterns, recallPatterns, queryBookKnowledge, loadStorePatternsSync, bundleSkills, brainHome, listBrain, promoteProjectToBrain, queryBrain, } from '@dzhechkov/harness-core';
+import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, consolidateSessions, pruneNoisePatterns, recallPatterns, queryBookKnowledge, loadStorePatternsSync, bundleSkills, brainHome, listBrain, promoteProjectToBrain, queryBrain, groundPrompt, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, } from '@dzhechkov/harness-core';
 import { getPreset, PRESET_NAMES } from '@dzhechkov/harness-presets';
 import { scanGitHub, analyzeRepo, generateReport, deepAnalyze, scanAllSources, ScoutMemory } from '@dzhechkov/scout';
 const USAGE = `dz - DZ cross-platform harness CLI
@@ -35,7 +35,11 @@ Usage:
   dz recall "<query>" [--limit <N>] [--books [--book <slug>]] [--project <dir>] | dz recall --all [--json]
   dz brain list  [--json]                                              (the durable cross-project knowledge brain)
   dz brain query "<q>" [--source <slug>] [--limit <N>] [--json]        (cross-source lexical recall over the brain)
-  dz brain add   [--source <slug>] [--project <dir>] [--json]          (promote this project's digitized-book KUs into the brain)
+  dz brain add   [--source <slug>] [--project <dir>] [--from-slice <f>|--from-pack <p>|--from-kus <f> --slug <s>] [--kind <k>] [--license <spdx>] [--json]   (grow the brain: promote this project, or import a slice/pack/KU-array)
+  dz brain primer <slug> [--json]                                     (print a source's capability card — KU-type histogram + top decision moments)
+  dz brain export --source <slug> --out <file>                        (export ONE source as a portable, lexical-only books.sqlite slice)
+  dz brain ground [<prompt>] [--k <N>] [--source <slug>] [--text]      (UserPromptSubmit hook: inject brain citations for a prompt; reads STDIN if no prompt)
+  dz brain init  [--project <dir>] [--k <N>]                           (wire the grounding hook into .claude/settings.json — opt-in)
   dz pretrain [--project <dir>]
   dz recommend "<task description>"
   dz compose <preset1+preset2+...> [--target <name>]
@@ -906,9 +910,60 @@ async function cmdRecall(options, flags, cwd, write) {
 const BRAIN_USAGE = `dz brain — the durable, cross-project knowledge brain
 
 Usage:
-  dz brain list  [--json]
-  dz brain query "<q>" [--source <slug>] [--limit <N>] [--json]
-  dz brain add   [--source <slug>] [--project <dir>] [--json]`;
+  dz brain list   [--json]
+  dz brain query  "<q>" [--source <slug>] [--limit <N>] [--json]
+  dz brain add    [--source <slug>] [--project <dir>] [--json]
+  dz brain add    --from-slice <file.sqlite>                    [--json]
+  dz brain add    --from-pack  <pkg-or-dir>                     [--json]
+  dz brain add    --from-kus   <file.json> --slug <s> [--kind repo|book|paper] [--license <spdx>] [--override] [--json]
+  dz brain primer <slug> [--json]
+  dz brain export --source <slug> --out <file>
+  dz brain ground [<prompt>] [--k <N>] [--source <slug>] [--text]
+  dz brain init   [--project <dir>] [--k <N>]
+
+  add:    default promotes THIS project's digitized-book KUs into the brain. The three --from-* modes
+          are mutually exclusive alternate inputs:
+            --from-slice  imports a standalone per-book slice (a \`dz brain export\` output).
+            --from-pack   resolves a pack (node_modules pkg or local dir) and imports every
+                          \`brain/<slug>.sqlite\` slice it ships.
+            --from-kus    registers a JSON array of already-shaped KUs under --slug (default --kind repo).
+  primer: prints a source's capability card (the deterministic KU-type histogram + top decision moments).
+  export: writes ONE source's KUs as a portable, lexical-only \`books.sqlite\` slice (vectors re-embed on import).
+  ground: the UserPromptSubmit hook entrypoint. Grounds a prompt (positional or STDIN) against
+          the brain and, when relevant KUs are found, prints Claude-Code-injectable JSON on
+          stdout ({"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":…}}).
+          Always exits 0 — grounding is advisory and must never fail a prompt. --text prints the
+          raw citation block instead of the JSON wrapper (for manual inspection).
+  init:   wires \`brain ground\` into .claude/settings.json as an opt-in UserPromptSubmit hook.`;
+/**
+ * Extract the user prompt from a Claude Code `UserPromptSubmit` hook STDIN payload. Tries the
+ * common JSON shapes (\`.prompt\`, \`.user_prompt\`, \`.userPrompt\`); if the payload is plain
+ * non-JSON text, the whole (trimmed) text is the prompt. Empty / unrecognized → \`''\` (the caller
+ * then emits nothing and exits 0 — grounding never blocks).
+ */
+function extractPromptFromStdin(raw) {
+    const text = raw.trim();
+    if (text === '')
+        return '';
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Plain non-JSON text → treat the whole thing as the prompt.
+        return text;
+    }
+    if (parsed !== null && typeof parsed === 'object') {
+        const obj = parsed;
+        for (const key of ['prompt', 'user_prompt', 'userPrompt']) {
+            const v = obj[key];
+            if (typeof v === 'string' && v.trim() !== '')
+                return v;
+        }
+    }
+    // Valid JSON but no recognizable prompt field (or a bare scalar) → nothing to ground.
+    return '';
+}
 /**
  * Resolve the deps root — the directory whose `package.json` can resolve `better-sqlite3` **and**
  * `agentdb`, the native driver `book-kb` + `agentdb-index` load through. Try `cwd` first (a project
@@ -933,7 +988,71 @@ function resolveDepsRoot(cwd) {
     const cliDir = dirname(fileURLToPath(import.meta.url)); // .../@dzhechkov/harness-cli/dist
     return canResolve(cliDir) ? cliDir : cwd;
 }
-async function cmdBrain(options, flags, cwd, write) {
+/**
+ * Resolve a `--from-pack` spec to a pack directory: a local directory (absolute or cwd-relative)
+ * wins; otherwise resolve it as an installed node package (its `package.json` from `cwd` then the
+ * CLI's deps root). Returns the pack's root dir, or `undefined` if it is neither.
+ */
+function resolvePackDir(cwd, depsRoot, spec) {
+    const asDir = resolve(cwd, spec);
+    if (existsSync(asDir) && lstatSync(asDir).isDirectory())
+        return asDir;
+    for (const root of [cwd, depsRoot]) {
+        try {
+            const req = createRequire(join(root, 'package.json'));
+            return dirname(req.resolve(`${spec}/package.json`));
+        }
+        catch {
+            /* try the next resolution base */
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate that a parsed JSON value is an array of KU-shaped objects (the `--from-kus` backend).
+ * Every element must carry the required BookKU string fields; `book` is optional (the caller's
+ * `--slug` is authoritative). On the first bad element returns `{ error }` naming exactly what is
+ * wrong; otherwise returns clean `BookKU[]` (extra fields dropped).
+ */
+function validateKuArray(parsed) {
+    if (!Array.isArray(parsed))
+        return { error: 'expected a JSON array of KU objects at the top level' };
+    if (parsed.length === 0)
+        return { error: 'the KU array is empty' };
+    const required = ['kuId', 'corpusVersion', 'type', 'name', 'problem', 'content'];
+    const kus = [];
+    for (let i = 0; i < parsed.length; i += 1) {
+        const v = parsed[i];
+        if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+            return { error: `KU #${i} is not an object` };
+        }
+        const o = v;
+        const missing = required.filter((k) => typeof o[k] !== 'string');
+        if (missing.length > 0) {
+            return { error: `KU #${i} missing/invalid string field(s): ${missing.join(', ')}` };
+        }
+        const pages = Array.isArray(o['pages'])
+            ? o['pages'].filter((n) => typeof n === 'number')
+            : undefined;
+        const meta = o['metadata'] !== null && typeof o['metadata'] === 'object' && !Array.isArray(o['metadata'])
+            ? o['metadata']
+            : undefined;
+        kus.push({
+            book: typeof o['book'] === 'string' ? o['book'] : '',
+            kuId: o['kuId'],
+            corpusVersion: o['corpusVersion'],
+            type: o['type'],
+            name: o['name'],
+            problem: o['problem'],
+            content: o['content'],
+            ...(typeof o['chapter'] === 'string' ? { chapter: o['chapter'] } : {}),
+            ...(pages !== undefined ? { pages } : {}),
+            ...(meta !== undefined ? { metadata: meta } : {}),
+        });
+    }
+    return { kus };
+}
+async function cmdBrain(options, flags, cwd, write, readStdin) {
     const sub = options.get('_positional_0');
     const asJson = flags.has('json');
     // ── dz brain list ──────────────────────────────────────────────────────────────────────────
@@ -989,13 +1108,189 @@ async function cmdBrain(options, flags, cwd, write) {
         }
         return 0;
     }
+    // ── dz brain primer <slug> ───────────────────────────────────────────────────────────────────
+    // Print a source's capability card (KU-type histogram + top decision moments) from the brain.
+    if (sub === 'primer') {
+        const slug = options.get('_positional_1');
+        if (!slug) {
+            write('dz brain primer: a source slug is required');
+            write('  Example: dz brain primer ddia');
+            return 1;
+        }
+        const { markdown, error } = await buildPrimer({ slug, depsRoot: resolveDepsRoot(cwd) });
+        if (error !== undefined) {
+            write(`dz brain primer: ${error}`);
+            return 1;
+        }
+        if (asJson) {
+            write(JSON.stringify({ slug, markdown }));
+            return 0;
+        }
+        write(markdown);
+        return 0;
+    }
+    // ── dz brain export --source <slug> --out <file> ─────────────────────────────────────────────
+    // Export ONE source's KUs as a portable, lexical-only books.sqlite slice.
+    if (sub === 'export') {
+        const source = options.get('source');
+        const out = options.get('out') ?? (flags.has('out') ? '' : undefined);
+        if (source === undefined || source === '' || out === undefined || out === '') {
+            write('dz brain export: --source <slug> and --out <file> are both required');
+            write('  Example: dz brain export --source ddia --out ./ddia.sqlite');
+            return 1;
+        }
+        const outPath = resolve(cwd, out);
+        const { kuCount, error } = await exportBrainSlice({ slug: source, outPath, depsRoot: resolveDepsRoot(cwd) });
+        if (error !== undefined) {
+            write(`dz brain export: ${error}`);
+            return 1;
+        }
+        write(`dz brain: exported ${kuCount} KU slice → ${outPath}`);
+        return 0;
+    }
     // ── dz brain add ─────────────────────────────────────────────────────────────────────────────
+    // Default promotes THIS project's book KB. Three mutually-exclusive --from-* modes ingest a
+    // slice, a pack's shipped slices, or a raw KU array instead.
     if (sub === 'add') {
+        const depsRoot = resolveDepsRoot(cwd);
+        const addedTs = new Date().toISOString();
+        // A `--from-* ` given without a value parses as a FLAG (missing value); treat that as '' so the
+        // mode still triggers its "requires a value" guard rather than silently falling through.
+        const fromSlice = options.get('from-slice') ?? (flags.has('from-slice') ? '' : undefined);
+        const fromPack = options.get('from-pack') ?? (flags.has('from-pack') ? '' : undefined);
+        const fromKus = options.get('from-kus') ?? (flags.has('from-kus') ? '' : undefined);
+        const modes = [fromSlice, fromPack, fromKus].filter((m) => m !== undefined).length;
+        if (modes > 1) {
+            write('dz brain add: --from-slice, --from-pack, and --from-kus are mutually exclusive');
+            return 1;
+        }
+        // ── mode: --from-slice <file> → import a standalone per-book slice ──────────────────────────
+        if (fromSlice !== undefined) {
+            if (fromSlice === '') {
+                write('dz brain add: --from-slice requires a slice file path');
+                return 1;
+            }
+            const slicePath = resolve(cwd, fromSlice);
+            if (!existsSync(slicePath)) {
+                write(`dz brain add: no slice at ${slicePath}`);
+                return 1;
+            }
+            const result = await importBrainSlice({ slicePath, depsRoot, addedTs });
+            if (asJson) {
+                write(JSON.stringify(result));
+                return result.sources.length === 0 ? 1 : 0;
+            }
+            if (result.sources.length === 0) {
+                write(`dz brain add: ${result.error ?? 'nothing to import from the slice'}`);
+                return 1;
+            }
+            write(`dz brain: imported ${result.kus} KU from slice → ${result.sources.length} source(s) into ${brainHome()}: ${result.sources.join(', ')}`);
+            if (result.error !== undefined)
+                write(`  (partial: ${result.error})`);
+            return 0;
+        }
+        // ── mode: --from-pack <pkg-or-dir> → import every brain/<slug>.sqlite the pack ships ────────
+        if (fromPack !== undefined) {
+            if (fromPack === '') {
+                write('dz brain add: --from-pack requires a package name or directory');
+                return 1;
+            }
+            const packDir = resolvePackDir(cwd, depsRoot, fromPack);
+            if (packDir === undefined) {
+                write(`dz brain add: could not resolve pack '${fromPack}' (not a local directory, not an installed package)`);
+                return 1;
+            }
+            const packBrainDir = join(packDir, 'brain');
+            const slices = existsSync(packBrainDir)
+                ? readdirSync(packBrainDir).filter((f) => f.endsWith('.sqlite')).sort()
+                : [];
+            if (slices.length === 0) {
+                write(`dz brain add: no brain/<slug>.sqlite slice found in pack '${fromPack}' (${packDir})`);
+                return 1;
+            }
+            const imported = [];
+            for (const f of slices) {
+                imported.push(await importBrainSlice({ slicePath: join(packBrainDir, f), depsRoot, addedTs }));
+            }
+            const allSources = imported.flatMap((r) => r.sources);
+            const totalKus = imported.reduce((s, r) => s + r.kus, 0);
+            const firstError = imported.find((r) => r.error !== undefined)?.error;
+            if (asJson) {
+                write(JSON.stringify({ sources: allSources, kus: totalKus, ...(firstError !== undefined ? { error: firstError } : {}) }));
+                return allSources.length === 0 ? 1 : 0;
+            }
+            if (allSources.length === 0) {
+                write(`dz brain add: ${firstError ?? 'nothing imported'} from pack '${fromPack}'`);
+                return 1;
+            }
+            write(`dz brain: imported ${totalKus} KU from ${slices.length} slice(s) in pack '${fromPack}' → ${allSources.length} source(s) into ${brainHome()}: ${allSources.join(', ')}`);
+            if (firstError !== undefined)
+                write(`  (partial: ${firstError})`);
+            return 0;
+        }
+        // ── mode: --from-kus <file.json> --slug <s> → register a raw KU array ───────────────────────
+        if (fromKus !== undefined) {
+            if (fromKus === '') {
+                write('dz brain add: --from-kus requires a JSON file path');
+                return 1;
+            }
+            const slug = options.get('slug');
+            if (slug === undefined || slug === '') {
+                write('dz brain add --from-kus: --slug <s> is required (every KU is registered under it)');
+                return 1;
+            }
+            const kusPath = resolve(cwd, fromKus);
+            if (!existsSync(kusPath)) {
+                write(`dz brain add: no KU file at ${kusPath}`);
+                return 1;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(kusPath, 'utf8'));
+            }
+            catch (err) {
+                write(`dz brain add --from-kus: invalid JSON in ${kusPath}: ${err instanceof Error ? err.message : String(err)}`);
+                return 1;
+            }
+            const valid = validateKuArray(parsed);
+            if ('error' in valid) {
+                write(`dz brain add --from-kus: bad KU shape — ${valid.error}`);
+                return 1;
+            }
+            const kind = options.get('kind') ?? 'repo';
+            if (kind !== 'repo' && kind !== 'book' && kind !== 'paper') {
+                write(`dz brain add --from-kus: --kind must be one of repo|book|paper (got '${kind}')`);
+                return 1;
+            }
+            const license = options.get('license');
+            const result = await registerKusToBrain({
+                kus: valid.kus,
+                slug,
+                kind,
+                depsRoot,
+                addedTs,
+                ...(license !== undefined ? { license } : {}),
+                ...(flags.has('override') ? { override: true } : {}),
+            });
+            if (asJson) {
+                write(JSON.stringify({ slug, kind, ...result }));
+                return result.kus === 0 ? 1 : 0;
+            }
+            if (result.kus === 0) {
+                write(`dz brain add --from-kus: ${result.error ?? 'nothing registered'}`);
+                return 1;
+            }
+            write(`dz brain: registered ${result.kus} KU under '${slug}' (kind ${kind}) into ${brainHome()}`);
+            if (result.error !== undefined)
+                write(`  (partial: ${result.error})`);
+            return 0;
+        }
+        // ── default: promote THIS project's digitized book KB ──────────────────────────────────────
         const source = options.get('source');
         const result = await promoteProjectToBrain({
             projectRoot: resolve(cwd, options.get('project') ?? '.'),
-            depsRoot: resolveDepsRoot(cwd),
-            addedTs: new Date().toISOString(),
+            depsRoot,
+            addedTs,
             ...(source !== undefined ? { source } : {}),
         });
         if (asJson) {
@@ -1014,6 +1309,101 @@ async function cmdBrain(options, flags, cwd, write) {
             write(`  (partial: ${result.error})`);
         return 0;
     }
+    // ── dz brain ground [<prompt>] ───────────────────────────────────────────────────────────────
+    // The UserPromptSubmit hook entrypoint. ALWAYS exits 0 — grounding is advisory and must never
+    // fail a prompt. Emits nothing (silent) unless the brain has relevant citations for the prompt.
+    if (sub === 'ground') {
+        const positional = options.get('_positional_1');
+        // Positional prompt wins; else read the hook payload from STDIN. Empty stdin → emit nothing.
+        const prompt = positional !== undefined && positional !== ''
+            ? positional
+            : extractPromptFromStdin(readStdin());
+        if (prompt.trim() === '')
+            return 0;
+        const source = options.get('source');
+        const kRaw = options.get('k');
+        const k = kRaw !== undefined ? Math.max(1, parseInt(kRaw, 10) || 5) : undefined;
+        const gopts = {
+            prompt,
+            depsRoot: resolveDepsRoot(cwd),
+        };
+        if (k !== undefined)
+            gopts.k = k;
+        if (source !== undefined)
+            gopts.source = source;
+        const res = await groundPrompt(gopts);
+        if (!res.emitted)
+            return 0; // no relevant citations → inject nothing
+        // --text → raw block for manual inspection; default → Claude-Code-injectable additionalContext.
+        if (flags.has('text')) {
+            write(res.block);
+            return 0;
+        }
+        write(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: 'UserPromptSubmit',
+                additionalContext: res.block,
+            },
+        }));
+        return 0;
+    }
+    // ── dz brain init ────────────────────────────────────────────────────────────────────────────
+    // Opt-in: wire `dz brain ground` into .claude/settings.json as a UserPromptSubmit hook.
+    // Idempotent read-merge-write — preserve every existing hook/key (e.g. the agentic-qe route hook).
+    if (sub === 'init') {
+        const projectRoot = resolve(cwd, options.get('project') ?? '.');
+        const kRaw = options.get('k');
+        const k = kRaw !== undefined ? Math.max(1, parseInt(kRaw, 10) || 5) : 5;
+        // Invoke the SAME bin this CLI runs from: dist/bin.js sits next to dist/cli.js.
+        const dzBin = join(dirname(fileURLToPath(import.meta.url)), 'bin.js');
+        const groundCmd = `node ${JSON.stringify(dzBin)} brain ground --k ${k}`;
+        const settingsPath = join(projectRoot, '.claude', 'settings.json');
+        let settings = {};
+        if (existsSync(settingsPath)) {
+            try {
+                const parsed = JSON.parse(readFileSync(settingsPath, 'utf8'));
+                if (parsed !== null && typeof parsed === 'object')
+                    settings = parsed;
+            }
+            catch {
+                // Corrupt/unreadable settings → start fresh rather than crash (grounding is opt-in glue).
+                settings = {};
+            }
+        }
+        const hooks = (settings['hooks'] !== null && typeof settings['hooks'] === 'object'
+            ? settings['hooks']
+            : {});
+        const ups = Array.isArray(hooks['UserPromptSubmit']) ? [...hooks['UserPromptSubmit']] : [];
+        // The grounding hook, in Claude Code's matcher-group shape (UserPromptSubmit takes no matcher).
+        const entry = { hooks: [{ type: 'command', command: groundCmd, timeout: 5000 }] };
+        // Identify OUR entry by a `brain ground` command; replace in place (idempotent), else append.
+        const isGroundEntry = (e) => {
+            const ex = e;
+            return Array.isArray(ex?.hooks)
+                && ex.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('brain ground'));
+        };
+        const idx = ups.findIndex(isGroundEntry);
+        const replaced = idx >= 0;
+        if (replaced)
+            ups[idx] = entry;
+        else
+            ups.push(entry);
+        hooks['UserPromptSubmit'] = ups;
+        settings['hooks'] = hooks;
+        mkdirSync(dirname(settingsPath), { recursive: true });
+        writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+        write(`dz brain init: ${replaced ? 're-wired' : 'wired'} the grounding hook into ${settingsPath}`);
+        write(`  UserPromptSubmit → ${groundCmd}`);
+        write(`  Grounding is now ON for this project (k=${k}). Every prompt is screened against your brain;`);
+        write(`  when ≥2 content terms co-occur in a stored KU, the retrieved citations are injected as`);
+        write(`  additionalContext. The command exits 0 on any failure (empty brain, error, empty stdin),`);
+        write(`  so a grounding miss can never block or fail a prompt (continueOnError-equivalent).`);
+        write(`  Honesty: the hook only MECHANICALLY injects the retrieved citations — actually answering`);
+        write(`  FROM them (not from model memory/drift) is agent discipline (§7.2), not something the hook`);
+        write(`  can enforce.`);
+        write(`  To turn it OFF: remove the "brain ground" entry under hooks.UserPromptSubmit in ${settingsPath}.`);
+        return 0;
+    }
     // ── unknown / absent subcommand ──────────────────────────────────────────────────────────────
     write(BRAIN_USAGE);
     return sub === undefined ? 0 : 1;
@@ -1869,6 +2259,21 @@ async function cmdImportEcc(options, flags, cwd, write) {
 export async function runCli(argv, io = {}) {
     const cwd = io.cwd ?? process.cwd();
     const write = io.write ?? ((line) => { console.log(line); });
+    // Lazy STDIN reader — only `dz brain ground` reads it, and only when no positional prompt is
+    // given. Never blocks: injected `io.stdin` wins; else read fd 0 synchronously, but bail to '' on
+    // a TTY (nothing piped) or any read error. Grounding must never hang waiting on an empty pipe.
+    const readStdin = () => {
+        if (io.stdin !== undefined)
+            return io.stdin;
+        try {
+            if (process.stdin.isTTY)
+                return '';
+            return readFileSync(0, 'utf8');
+        }
+        catch {
+            return '';
+        }
+    };
     const { command, options, flags } = parseArgs(argv);
     if (command === '' || command === 'help' || flags.has('help')) {
         write(USAGE);
@@ -1908,7 +2313,7 @@ export async function runCli(argv, io = {}) {
             case 'recall':
                 return await cmdRecall(options, flags, cwd, write);
             case 'brain':
-                return await cmdBrain(options, flags, cwd, write);
+                return await cmdBrain(options, flags, cwd, write, readStdin);
             case 'setup':
                 return await cmdSetup(options, flags, cwd, write);
             case 'pretrain':