@dzhechkov/harness-cli 0.3.193 → 0.3.197

package/README.md

@@ -356,29 +356,32 @@ 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 (39)
+## All Commands (40)
 
 ```
 dz setup             --target <name> [--preset <name>] [--select id,id,...] [--skills-dir <dir>] [--memory agentdb] [--no-memory] [--no-hooks] [--install-driver] [--force]
 dz init              --target <name> [--preset <name>] [--select id,id,...] [--force]
 dz install           <npm-pkg> [--target <name>] [--project <dir>] [--force]
 dz bundle            [--preset <name> | --select id,...] [--out <dir>] [--skills-dir <dir>] [--force]
-dz teach             "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror]   # --project pins the learned store to <dir>/.dz (not the cwd) — pin to a canonical brain
-dz teach --from-json <file> [--project <dir>] [--no-mirror]   # bulk-import a `dz recall --all --json` export (share a learned store across machines)
+dz teach             "<pattern>" [--reward <0-1>] [--domain <name>] [--type rule|success-pattern|lesson-learned] [--project <dir>] [--no-mirror] [--guard]   # --project pins the learned store to <dir>/.dz (not the cwd) — pin to a canonical brain
+dz teach --reinforce "<dzId-or-exact-text>" [--project <dir>] # bump an existing learned pattern instead of writing a near-duplicate
+dz teach --from-json <file> [--project <dir>] [--no-mirror] [--harmonize]   # bulk-import a `dz recall --all --json` export; prints a harmonize dry-run advisory
 dz consolidate       [--sessions-dir <dir>] [--project <dir>] [--no-mirror]
 dz recall            "<query>" [--limit <N>] [--semantic | --no-semantic] [--project <dir>]   # hybrid lexical+vector when the vector tier is enabled
-dz recall --all      [--json]                       # export the WHOLE learned store (portable SHARING form — the input for `dz teach --from-json`)
+dz recall --all      [--json] [--stats]             # export the WHOLE learned store, or inspect learning stats/top uses
 dz recall --books    "<query>" [--book <slug>]      # digitized-book KUs; --book narrows to one book
 dz vector status     [--project <dir>] [--json]     # semantic tier: engine availability, mirrored vs lexical counts, pending queue
 dz vector export     <path> [--project <dir>]       # portable VECTOR form (.rvf checkpoint; needs the opt-in RVF engine)
 dz vector import     <file.rvf> [--project <dir>] [--json]         # RVF import — UPSERT-BY-dzId (idempotent, never overwrites; orphans skipped)
-dz vector harmonize  [--apply] [--threshold <0..1>] [--json]       # SEMANTIC dedup of the learned store (dry-run default; --apply after a restorable backup)
+dz vector harmonize  [--apply] [--threshold <0..1>] [--json]       # SEMANTIC merge of near-dups (dry-run default; --apply after a restorable backup)
 dz teach --harmonize [--apply] [--threshold <0..1>]                # alias of `dz vector harmonize`
 dz statusline        [--json] [--install]   # compact Claude Code statusline: live self-learning pattern count + brain sources
+dz usage             [--json] [--project <dir>]   # ESTIMATE Claude session (5h-block) + weekly (7d) token usage from local transcripts; exit 0 ALWAYS; pct=null when limits unconfigured
 dz brain list        [--json]                                        # the durable cross-project knowledge brain
 dz brain query       "<q>" [--source <slug>] [--limit <N>] [--any] [--rerank] [--json]  # cross-source recall (--any = OR match; --rerank reorders on-point first)
 dz brain add         [--source <slug>] [--project <dir>] [--from-slice <f>|--from-pack <p>|--from-kus <f> --slug <s> --kind <k> --license <spdx> [--override]] [--json]  # grow the brain
-dz brain ground      "<prompt>" [--k <N>] [--source <slug>] [--text] # retrieve + emit grounding citations (hook entrypoint; silent if irrelevant)
+dz brain ground      "<prompt>" [--k <N>] [--source <slug>] [--text] [--budget <N>] [--full]  # retrieve + emit grounding citations (hook entrypoint; silent if irrelevant); --budget N eager-inlines top-K KU content within ~N tokens (chars/4 approx); --full = --budget 8000
+dz brain expand      <kuId> [--source <slug>] [--json]               # full-content lookup by kuId — the command the grounding directive names; prints name/problem/pages/book + FULL content (untruncated)
 dz brain init        [--project <dir>] [--k <N>]                     # opt-in: wire the grounding UserPromptSubmit hook into settings.json
 dz brain primer      <slug> [--json]                                # print a source's capability card (histogram + top decision moments)
 dz brain export      --source <slug> --out <file>                   # write a portable per-book KB slice (ships inside the pack, §8.1)
@@ -415,6 +418,32 @@ dz import-ecc       [--local-path <dir>] [--select id,id,...] [--limit N] [--out
 dz help
 ```
 
+### Grounding: three tiers + the token trade-off (`dz brain ground` / `dz brain expand`)
+
+The `dz brain ground` hook fires on **every turn**, so what it injects is a token trade-off. There are
+three tiers — the default costs nothing extra every turn, and expansion is always opt-in and bounded:
+
+- **Pointer (default, no flags)** — one compact `[Kn] book гл.N с.X–Y — name: snippet` line per KU.
+  Zero overhead every turn. Backward-compatible (byte-identical to prior releases). A pointer tells the
+  model *where* the knowledge is, not *what* it is.
+- **Model-driven expand (`--budget N > 0` or `--full`)** — the grounding directive additionally tells
+  the model it can pull any citation's FULL content **on demand** by running `dz brain expand <kuId>`.
+  Each citation shows its `kuId` as the first field so the model knows what to pass. Cost: ~1 directive
+  sentence + a `kuId` per citation — latency is paid only when the model actually expands a KU.
+- **Budgeted eager (`--budget N`)** — eagerly inlines the full `content` of the top-K KUs within ~N
+  tokens (approximate: chars/4 for Latin, chars/2 for Cyrillic — a multilingual tokenizer emits ~2
+  tokens per Cyrillic char, so a naive chars/4 would undercount Russian content and overshoot the
+  budget). KUs are worth-ranked (high → medium → **unset → low**: an explicit `low` ranks below an
+  unrated KU). A KU whose content would overflow the budget **stays a pointer** (never truncated — atomic KUs). `--full`
+  = `--budget 8000` (inlines everything the top-K recall holds in practice). `--budget 0` / absent =
+  pointers-only (the default).
+
+```bash
+# The model can turn a citation like `ddia-ch05-ku01 (с.188–189)` into the actual knowledge:
+dz brain expand ddia-ch05-ku01           # prints name, problem, pages, book + FULL content
+echo "how do I handle replication lag?" | dz brain ground --budget 2000   # eager-inline top KUs ≤ ~2000 tokens
+```
+
 ### Live self-learning panel (`dz statusline`)
 
 `dz statusline` renders a compact Claude Code statusline that surfaces dz's learning at a glance:
@@ -436,6 +465,32 @@ distills new learnings. It's **opt-in** and **non-clobbering**: `--install` merg
 existing `statusLine` config rather than overwriting it, and nothing changes until you run it.
 Modeled on the Agentic QE statusline pattern (e.g. AQE's `🎓 12 patterns`).
 
+### Usage estimate (`dz usage`)
+
+`dz usage` prints a READONLY, never-throw ESTIMATE of Claude SESSION (active 5h-block) and WEEKLY
+(rolling 7d) token usage, aggregated from your local `~/.claude/projects/**/*.jsonl` transcripts:
+
+```bash
+dz usage           # session ~74% (resets 19:00) · week ~52% (resets Sat) · estimated
+dz usage --json    # {"sessionPct":74,"weeklyPct":52,"sessionTokens":…,"resetsAt":{…},"limits":{…},"estimated":true}
+```
+
+**Exit code is 0 ALWAYS** (even unconfigured/error → all-null JSON) — a probe must never distinguish
+"usage unknown" from "command failed" via a non-zero exit. Percentages are **ESTIMATES** (there is no
+official usage API); they are `null` until you configure the plan-dependent limits in `.dz/config.json`:
+
+```json
+{ "memory": { "usage": { "sessionTokenLimit": 200000000, "weeklyTokenLimit": 1000000000 } } }
+```
+
+Both keys are OPTIONAL — absent ⇒ that `pct` is `null` (unknown, never `0`). **Calibrate** by scaling a
+limit by `X/100` when a real limit-hit lands at an estimated `X%` (observed-exhaustion calibration).
+This feeds `/feature-adr`'s **usage-adaptive routing** — the pipeline probes `dz usage --json` at each
+phase boundary and pre-emptively routes the remaining stages to Codex when usage crosses the threshold
+(default 70%). **Honest caveat:** at TRUE exhaustion even the Codex dispatch dies (`codex:codex-rescue`
+is a Claude wrapper), so the switch must happen BEFORE — the pre-emptive probe, not reactive detection,
+is the real defense.
+
 ### Targets (10 platforms — 5 lossless + Copilot + AGENTS.md + Cursor + Gemini + Windsurf)
 
 Five platforms natively support the [agentskills.io](https://agentskills.io) `SKILL.md` format:
@@ -1087,7 +1142,9 @@ The learned store round-trips across machines in **two** formats, and de-duplica
 
 **Does `dz vector import` overwrite my store? NO.** Import is **upsert-by-dzId** (our vectors are keyed by the content-addressed `dzId`), so re-importing the *same* `.rvf` twice adds **zero** duplicates and **deletes nothing** — it only inserts new dzIds and replaces the embedding of dzIds it already knows. A dzId with no local pattern is an **orphan**: skipped + counted, with a hint to import the *text* first (`dz teach --from-json`), because embeddings are model-locked but text is not. (Grounded in RuVector's own upsert-by-id merge model — see [rUv RVF](https://github.com/ruvnet/ruvector); the shipped `@ruvector/rvf` SDK exposes no vector read-out, so import reads the `.rvf.idmap.json` dzId sidecar and re-embeds the local text under a **manifest guard** that refuses a foreign model/dim.)
 
-**`dz vector harmonize` — semantic dedup.** `dz teach --from-json` only dedups by *exact* text, so paraphrases survive: *"use DataLoader to batch queries"* and *"batch DB round-trips with a dataloader"* are two rows forever. Harmonize finds near-duplicate **clusters** by cosine similarity (θ default `0.92`, `--threshold`), keeps the **highest-reward** member of each (tie-break: longer/more-specific text, then newer `ts`), and drops the rest — **dry-run by default** (previews, writes nothing), reversible on `--apply` (writes a restorable backup first). It **never** drops a unique (non-duplicated) pattern. With no vector engine it degrades to **exact-text dedup + an honest note** — never throws.
+**`dz vector harmonize` — semantic merge.** `dz teach --from-json` only dedups by *exact* text, so paraphrases survive: *"use DataLoader to batch queries"* and *"batch DB round-trips with a dataloader"* are separate rows. Harmonize finds near-duplicate **clusters** by cosine similarity (θ default `0.92`, `--threshold`), keeps the **highest-reward** member of each (tie-break: longer/more-specific text, then newer `ts`), folds reinforcement signal into the keeper (`uses = Σ member uses + drops`, `avgReward` = honest mean of observed member rewards, `mergedFrom` = dropped ids), then removes the rest only on `--apply`. Dry-run previews and writes nothing; apply writes a restorable backup first. It **never** drops a unique pattern. With no vector engine it degrades to **exact-text dedup + an honest note** — never throws.
+
+**Learning signal seam.** Ranking reinforcement is behind `memory.learning.backend`: default `native` (bounded uses/recency/reward signal), kill switch `off`, and reserved `ruvector-gnn` (accepted by config with an honest fallback to native; no RuVector dependency is installed). `memory.learning.onRecallHits:false` disables the default recall-hit auto-bump. `dz teach --reinforce "<id-or-text>"` records an explicit use; `dz teach --guard` is opt-in and only reinforces near-duplicates at θ ≥ `0.95`, while a different reward still writes a new record. `dz recall --all --stats` shows store size, domains, top uses, duplicate groups, and re-teach/reinforce trend counters.
 
 **Before → after** (one near-dup cluster):
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiJH,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;AAggGD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8G5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyJH,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;AA6sGD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,KAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAgH5E"}

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, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, consolidateSessions, pruneNoisePatterns, recallHybrid, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, queryBookKnowledge, loadStorePatternsSync, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, reindexBrainVectors, buildPrimer, exportBrainSlice, importBrainSlice, registerKusToBrain, } from '@dzhechkov/harness-core';
+import { createSkill, getSkillInfo, getWorkflow, isTargetName, listSkills, runDoctor, runInit, benchmarkSkill, benchmarkSkills, scanMcp, reconcileCapabilities, RECONCILE_BANNER, buildRegistry, discoverSkillPackDirs, checkUpstream, compareSkills, checkAllUpstream, sweepSkillDrift, syncCanonicalSkill, checkUpgrades, discoverPackages, discoverSourcePackages, fetchAllDownloads, filterByCategory, pretrain, recommend, generatePlugin, publishPackages, runSetup, runMigrate, searchRegistry, runSync, runVerify, runInitAgentsMd, runInitGeminiMd, TARGET_NAMES, WORKFLOW_NAMES, importEcc, recordPattern, resolveLearningBackend, storeStats, consolidateSessions, pruneNoisePatterns, recallHybrid, teachGuard, mirrorPatternsToVector, vectorMirrorEnabled, vectorTierStatus, resolveVectorEngine, reindexVectorStore, harmonizeVectorStore, importRvfCheckpoint, statuslineData, writeFeatureAdrState, computeUsage, readUsageLimits, queryBookKnowledge, loadStorePatternsSync, bundleSkills, brainHome, listBrain, promoteProjectToBrain, updateBrainSource, queryBrain, groundPrompt, expandKu, reindexBrainVectors, 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
@@ -46,10 +46,12 @@ Usage:
   dz brain reindex [--json]                                            (snapshot, re-embed book-KU brain vectors, stamp current model)
   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 ground [<prompt>] [--k <N>] [--source <slug>] [--text] [--budget <N>] [--full]  (UserPromptSubmit hook; --budget inlines top-K KUs within ~N tokens; --full = ~8000)
+  dz brain expand <kuId> [--source <slug>] [--json]                    (full-content lookup for a citation kuId; --json emits the full KU object)
   dz brain init  [--project <dir>] [--k <N>]                           (wire the grounding hook into .claude/settings.json — opt-in)
   dz statusline [--json] [--install] [--project <dir>]                 (live self-learning panel for Claude Code's status bar; reads the CC JSON payload from STDIN)
   dz statusline --fa-record --slug <s> --step "<label>" [--recalled <n>] [--stored <n>] [--mode <m>]   (feature-adr: record live per-run learning state → 📐 panel segment)
+  dz usage [--json] [--project <dir>]                                  (ESTIMATE Claude session (5h-block) + weekly (7d) token usage from local transcripts; exit 0 ALWAYS; pct=null when memory.usage.{sessionTokenLimit,weeklyTokenLimit} unconfigured in .dz/config.json)
   dz pretrain [--project <dir>]
   dz recommend "<task description>"
   dz compose <preset1+preset2+...> [--target <name>]
@@ -885,17 +887,21 @@ function cmdStatuslineFaRecord(options, cwd, write) {
     const stored = parseCount('stored');
     if (stored === undefined)
         return 1;
+    const reinforced = parseCount('reinforced');
+    if (reinforced === undefined)
+        return 1;
     const mode = options.get('mode');
     const projectRoot = resolve(cwd, options.get('project') ?? '.');
     const state = writeFeatureAdrState(projectRoot, {
         slug, step, recalled, stored,
+        ...(reinforced > 0 ? { reinforced } : {}),
         ...(mode !== undefined && mode.trim() !== '' ? { mode: mode.trim() } : {}),
     });
     if (state === undefined) {
         write(`dz statusline --fa-record: could not write learning state under ${projectRoot}/.dz/feature-adr/`);
         return 1;
     }
-    write(`dz statusline: recorded /feature-adr learning state for "${slug}" (${step}) — 🎓 ${state.pool} pool · ↑${state.recalled} used · +${state.stored} new`);
+    write(`dz statusline: recorded /feature-adr learning state for "${slug}" (${step}) — 🎓 ${state.pool} pool · ↑${state.recalled} used · +${state.stored} new · ↻${state.reinforced ?? 0} reinforced`);
     return 0;
 }
 /**
@@ -930,7 +936,7 @@ function cmdStatusline(options, flags, cwd, write, readStdin) {
         // Live /feature-adr run in flight → PREPEND the pipeline learning segment to the base dz line.
         const fa = data.featureAdr;
         if (fa !== undefined) {
-            line = `📐 feature-adr ${fa.step} · 🎓 ${fa.pool} pool · ↑${fa.recalled} used · +${fa.stored} new · ${line}`;
+            line = `📐 feature-adr ${fa.step} · 🎓 ${fa.pool} pool · ↑${fa.recalled} used · +${fa.stored} new · ↻${fa.reinforced ?? 0} reinforced · ${line}`;
         }
         write(line);
         return 0;
@@ -941,6 +947,72 @@ function cmdStatusline(options, flags, cwd, write, readStdin) {
         return 0;
     }
 }
+/**
+ * `dz usage` — print an ESTIMATE of Claude session (active 5h-block) + weekly (rolling 7d) token
+ * usage, aggregated READONLY from the local transcript store (see {@link computeUsage}). `--json`
+ * emits the single-line contract the feature-adr usage-probe agent parses; the human path prints a
+ * compact `session ~74% (resets 19:00) · week ~52% (resets Sat)` or an unconfigured hint.
+ *
+ * **Exit code is 0 ALWAYS** — including on internal error the whole body is guarded and prints the
+ * all-null JSON, so a probe can NEVER distinguish "usage unknown" from "command failed" via a
+ * non-zero exit (unknown is a first-class value, INV-3). `--project <dir>` scopes ONLY the
+ * `.dz/config.json` limits read; the measurement is account-wide (all projects, FR-1.6).
+ */
+function cmdUsage(options, flags, cwd, write) {
+    const projectRoot = resolve(cwd, options.get('project') ?? '.');
+    const nullContract = () => JSON.stringify({
+        sessionPct: null,
+        weeklyPct: null,
+        sessionTokens: 0,
+        weeklyTokens: 0,
+        resetsAt: { session: null, weekly: null },
+        limits: { session: null, weekly: null },
+        estimated: true,
+    });
+    try {
+        const u = computeUsage(projectRoot);
+        const lim = readUsageLimits(projectRoot);
+        if (flags.has('json')) {
+            write(JSON.stringify({
+                sessionPct: u.sessionPct,
+                weeklyPct: u.weeklyPct,
+                sessionTokens: u.sessionTokens,
+                weeklyTokens: u.weeklyTokens,
+                resetsAt: { session: u.sessionResetsAt, weekly: u.weeklyResetsAt },
+                limits: { session: lim.sessionTokenLimit ?? null, weekly: lim.weeklyTokenLimit ?? null },
+                estimated: true,
+            }));
+            return 0;
+        }
+        if (u.sessionPct === null && u.weeklyPct === null) {
+            write('usage: unconfigured — set memory.usage.sessionTokenLimit / weeklyTokenLimit in .dz/config.json (percentages are ESTIMATES calibrated from observed exhaustion)');
+            return 0;
+        }
+        // Compact human line — a short HH:MM / weekday hint on the resets, best-effort.
+        const clock = (iso) => {
+            if (!iso)
+                return '?';
+            try {
+                return new Date(iso).toISOString().slice(11, 16);
+            }
+            catch {
+                return '?';
+            }
+        };
+        const s = u.sessionPct === null ? 'n/a' : '~' + u.sessionPct + '%';
+        const w = u.weeklyPct === null ? 'n/a' : '~' + u.weeklyPct + '%';
+        write('usage: session ' + s + ' (resets ' + clock(u.sessionResetsAt) + ') · week ' + w + ' (resets ' + clock(u.weeklyResetsAt) + ') · estimated');
+        return 0;
+    }
+    catch {
+        // never let a probe see a non-zero exit — print the all-null contract and exit 0.
+        if (flags.has('json'))
+            write(nullContract());
+        else
+            write('usage: unconfigured — set memory.usage.sessionTokenLimit / weeklyTokenLimit in .dz/config.json');
+        return 0;
+    }
+}
 async function cmdTeach(options, flags, cwd, write) {
     const projectRoot = options.get('project') ?? cwd;
     // Vector tier (dz-rvf-vector-bridge FR-1): best-effort mirror AFTER the lexical write is
@@ -1015,8 +1087,35 @@ async function cmdTeach(options, flags, cwd, write) {
         write(`  Backend: memory (@dzhechkov/memory)  Total now: ${loadStorePatternsSync(projectRoot).length}`);
         // ONE batched mirror call through the same seam as single-teach (QR-6 — no bespoke path).
         await emitMirror(projectRoot, importedRecs, 'dz-teach-import');
+        if (imported > 0) {
+            const report = await harmonizeVectorStore(projectRoot, {});
+            write(`  ℹ ${imported} imported — ${report.clusters.length} near-duplicate cluster(s): review with dz vector harmonize (dry-run); merge with dz vector harmonize --apply after backup`);
+        }
         return 0;
     }
+    const reinforce = options.get('reinforce');
+    if (reinforce !== undefined && reinforce.trim() !== '') {
+        const backend = resolveLearningBackend(projectRoot);
+        const sampleReward = options.has('reward') ? parseFloat(options.get('reward') ?? '0.8') : undefined;
+        backend.addSample({
+            dzId: reinforce,
+            kind: 'reinforce',
+            ts: new Date().toISOString(),
+            ...(sampleReward !== undefined ? { reward: sampleReward } : {}),
+        });
+        const trained = await backend.train();
+        if (trained.flushed > 0) {
+            write(`↳ reinforced ${reinforce}`);
+            return 0;
+        }
+        // HIGH-fix: a no-match must NOT auto-teach the raw argument — callers pass dzIds or truncated
+        // text, so auto-teach minted garbage lessons (observed live). Fail with an honest advisory:
+        // if the lesson is genuinely new, the caller teaches it EXPLICITLY with the full text.
+        write(`dz teach --reinforce: no existing pattern matched ${JSON.stringify(reinforce)} — nothing reinforced`);
+        write('  If this is a genuinely NEW lesson, teach it explicitly:  dz teach "<full lesson text>" --reward <0-1> --domain <area>');
+        write('  To find the exact pattern to reinforce:  dz recall "<terms>"  (match by its full text)');
+        return 1;
+    }
     const pattern = options.get('_positional_0');
     if (!pattern) {
         write('dz teach: pattern description required');
@@ -1027,6 +1126,22 @@ async function cmdTeach(options, flags, cwd, write) {
     }
     const reward = parseFloat(options.get('reward') ?? '0.8');
     const domain = options.get('domain') ?? 'general';
+    if (flags.has('guard')) {
+        const verdict = await teachGuard(projectRoot, pattern, { reward: Math.max(0, Math.min(1, reward)) });
+        if (verdict.action === 'reinforce') {
+            const backend = resolveLearningBackend(projectRoot);
+            backend.addSample({ dzId: verdict.dzId, kind: 'reinforce', reward: Math.max(0, Math.min(1, reward)), ts: new Date().toISOString() });
+            const trained = await backend.train();
+            // HIGH-fix: only claim success when the reinforce actually FLUSHED. With backend 'off'
+            // (NoopLearningBackend) or a flush failure, flushed === 0 — falling through to the plain
+            // teach below so the lesson is NEVER silently discarded (the exact silent-drop the ADR forbids).
+            if (trained.flushed > 0) {
+                write(`↳ reinforced existing pattern ${verdict.dzId} (cos=${verdict.cosine.toFixed(2)}) — not re-added`);
+                return 0;
+            }
+            write(`dz teach --guard: reinforce of ${verdict.dzId} did not flush (backend off or write failure) — teaching the lesson normally instead`);
+        }
+    }
     // Distill pattern into actionable rule (claude-smart inspired)
     // Convert "what happened" into "what to do next time"
     const isRule = pattern.toLowerCase().startsWith('always') || pattern.toLowerCase().startsWith('never') ||
@@ -1130,6 +1245,24 @@ async function cmdRecall(options, flags, cwd, write) {
     // With --json this is the portable export the agentdb-memory MCP bridge consumes.
     if (all) {
         const patterns = loadStorePatternsSync(projectRoot);
+        if (flags.has('stats')) {
+            const stats = storeStats(projectRoot);
+            const backendStats = resolveLearningBackend(projectRoot).getStats();
+            if (asJson) {
+                write(JSON.stringify({ patterns, stats, learning: backendStats }));
+                return 0;
+            }
+            write(`dz recall --all --stats  —  ${patterns.length} learned pattern(s)`);
+            write(`  backend: ${backendStats.backend}${backendStats.advisory !== undefined ? ` (${backendStats.advisory})` : ''}`);
+            write(`  domains: ${Object.entries(stats.perDomain).map(([k, v]) => `${k}=${v}`).join(', ') || 'none'}`);
+            write(`  exact-dup groups: ${stats.exactDupGroups}`);
+            write(`  re-teach trend: ${stats.teachEvents} teach event(s), ${stats.reinforceEvents} reinforce event(s)`);
+            write('  top uses:');
+            for (const row of stats.topUses)
+                write(`    ${row.uses}× [${row.reward.toFixed(2)}] (${row.domain}) ${row.pattern.slice(0, 80)}`);
+            write('  near-dup density: run dz vector harmonize (dry-run)');
+            return 0;
+        }
         if (asJson) {
             write(JSON.stringify(patterns));
         }
@@ -1386,6 +1519,12 @@ async function cmdVector(options, flags, cwd, write) {
 /* ------------------------------------------------------------------ */
 /*  brain — the durable, cross-project knowledge brain (ADR §5.2 P0)    */
 /* ------------------------------------------------------------------ */
+/**
+ * Token budget used when `dz brain ground --full` is specified (chars/4 heuristic, approximate). A
+ * typical DDIA-scale KU is ~500–750 tokens; at k=5 the sum is well under 8000, so `--full` inlines
+ * everything the top-K recall returns in practice. Documented in the brain usage + wiki.
+ */
+const GROUND_FULL_BUDGET = 8_000;
 const BRAIN_USAGE = `dz brain — the durable, cross-project knowledge brain
 
 Usage:
@@ -1399,7 +1538,8 @@ Usage:
   dz brain reindex [--json]
   dz brain primer <slug> [--json]
   dz brain export --source <slug> --out <file>
-  dz brain ground [<prompt>] [--k <N>] [--source <slug>] [--text]
+  dz brain ground [<prompt>] [--k <N>] [--source <slug>] [--text] [--budget <N>] [--full]
+  dz brain expand <kuId>  [--source <slug>] [--json]
   dz brain init   [--project <dir>] [--k <N>]
 
   add:    default promotes THIS project's digitized-book KUs into the brain. The three --from-* modes
@@ -1421,6 +1561,15 @@ Usage:
           Always exits 0 — grounding is advisory and must never fail a prompt. Reranking is ON by
           default here (grounding wants the most on-point citation first). --text prints the raw
           citation block instead of the JSON wrapper (for manual inspection).
+          Three grounding tiers: (1) pointer (default, no flags) — one compact citation line per KU,
+          cheap every-turn; (2) model-driven expand (--budget N>0 / --full) — each citation carries
+          its kuId and the directive tells the model to pull full content via \`dz brain expand\`;
+          (3) budgeted eager (--budget N) — eager-inlines full content of the top-K KUs within ~N
+          tokens (chars/4 approx), worth-ranked; a KU that would overflow stays a pointer. --full =
+          --budget 8000. --budget 0 / absent = pointers-only.
+  expand: full-content lookup by kuId — the command the grounding directive names when --budget/--full
+          is used. Prints name, problem, pages, book, and the FULL content (untruncated); --json emits
+          the whole KU object. Exit 1 if the kuId is not found.
   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
@@ -1869,6 +2018,21 @@ async function cmdBrain(options, flags, cwd, write, readStdin) {
         const source = options.get('source');
         const kRaw = options.get('k');
         const k = kRaw !== undefined ? Math.max(1, parseInt(kRaw, 10) || 5) : undefined;
+        // brain-ground-expand: --budget N eager-inlines top-K KU content within ~N tokens (chars/4);
+        // --full = --budget GROUND_FULL_BUDGET; --budget 0 / absent ⇒ pointers-only (byte-identical).
+        const budgetRaw = options.get('budget');
+        let contentBudget;
+        if (budgetRaw !== undefined) {
+            const parsed = parseInt(budgetRaw, 10);
+            if (isNaN(parsed) || parsed < 0) {
+                write('dz brain ground: --budget must be a non-negative integer');
+                return 1;
+            }
+            contentBudget = parsed === 0 ? undefined : parsed; // 0 → pointer-only (FR-03.6)
+        }
+        else if (flags.has('full')) {
+            contentBudget = GROUND_FULL_BUDGET;
+        }
         const gopts = {
             prompt,
             depsRoot: resolveDepsRoot(cwd),
@@ -1877,6 +2041,8 @@ async function cmdBrain(options, flags, cwd, write, readStdin) {
             gopts.k = k;
         if (source !== undefined)
             gopts.source = source;
+        if (contentBudget !== undefined)
+            gopts.contentBudget = contentBudget;
         const res = await groundPrompt(gopts);
         if (!res.emitted)
             return 0; // no relevant citations → inject nothing
@@ -1893,6 +2059,47 @@ async function cmdBrain(options, flags, cwd, write, readStdin) {
         }));
         return 0;
     }
+    // ── dz brain expand <kuId> ───────────────────────────────────────────────────────────────────
+    // Full-content lookup by kuId — the command named in GROUNDING_DIRECTIVE_EXPAND (brain-ground-expand
+    // Tier 1). Prints the FULL `content` (+ name/problem/pages/book) for one citation the model wants
+    // to read; --json emits the whole KU object. Exit 1 on missing kuId / not-found.
+    if (sub === 'expand') {
+        const kuId = options.get('_positional_1');
+        if (!kuId) {
+            write('dz brain expand: a kuId is required');
+            write('  Example: dz brain expand ddia-ch05-ku01');
+            return 1;
+        }
+        const source = options.get('source');
+        const res = expandKu({
+            kuId,
+            depsRoot: resolveDepsRoot(cwd),
+            ...(source !== undefined ? { source } : {}),
+        });
+        if (res.error !== undefined) {
+            write(`dz brain expand: ${res.error}`);
+            return 1;
+        }
+        const ku = res.ku;
+        if (asJson) {
+            write(JSON.stringify(ku, null, 2));
+            return 0;
+        }
+        const ch = ku.chapter !== undefined && ku.chapter !== '' ? `гл.${ku.chapter}` : '';
+        const pg = ku.pages !== undefined && ku.pages.length > 0 ? `с.${ku.pages.join('–')}` : '';
+        write(`kuId:    ${ku.kuId}`);
+        write(`book:    ${ku.book}`);
+        if (ch)
+            write(`chapter: ${ch}`);
+        if (pg)
+            write(`pages:   ${pg}`);
+        write(`name:    ${ku.name}`);
+        write(`problem: ${ku.problem}`);
+        write('');
+        write('content:');
+        write(ku.content);
+        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).
@@ -3037,6 +3244,8 @@ export async function runCli(argv, io = {}) {
                 return await cmdBrain(options, flags, cwd, write, readStdin);
             case 'statusline':
                 return cmdStatusline(options, flags, cwd, write, readStdin);
+            case 'usage':
+                return cmdUsage(options, flags, cwd, write);
             case 'setup':
                 return await cmdSetup(options, flags, cwd, write);
             case 'pretrain':