@lorekit/cli 1.10.0 → 1.12.0

package/README.md

@@ -51,9 +51,11 @@ without needing a marketplace:
 2. **MCP server** (`lorekit`) — the connection to your lessons, merged into the
    MCP config (preserving any other servers).
 3. **Hooks** — the *deterministic* layer: lessons injected on every
-   `SessionStart`, a nudge on tool failure (`PostToolUseFailure`), and a
-   retrospective nudge on `Stop`. These fire the shared `lorekit hook` engine
-   and are merged into `settings.json` (existing hooks preserved).
+   `SessionStart`, and on a tool failure (`PostToolUseFailure`) any lessons that
+   look **relevant to that failure** ("you've hit this before") plus a nudge to
+   record the fix, and a retrospective nudge on `Stop`. These fire the shared
+   `lorekit hook` engine and are merged into `settings.json` (existing hooks
+   preserved).
 
 It first asks **where** to install:
 
@@ -210,13 +212,72 @@ remote is unconfigured (or a store is denied), a meaningful diff is impossible,
 so `diff` prints a clear note (`comparable: false` in `--json`) and exits 0
 rather than crashing. `--endpoint` / `--token` / `--store` behave as in `list`.
 
+### `lorekit tree` (alias `resolve`)
+
+Show the scopes the hooks actually **inject** — project → branch → repo →
+global, in precedence order (most-specific first) — as a resolution hierarchy,
+and mark for any key present at more than one scope which scope's lesson **wins**
+and which are **shadowed**:
+
+```bash
+lorekit tree                  # the injected hierarchy with ✓ winning / ↳ shadowed marks
+lorekit tree --scope global   # narrow to a single scope
+lorekit tree --json           # per-entry { winning, shadowedBy } + a winners[] list
+```
+
+This mirrors the SessionStart hook's resolution **exactly**: it reads the scopes
+in `readOrder` (project → branch → repo → global) and keeps the first value seen
+per key, so a more-specific scope overrides a broader scope's same-key lesson. It
+answers "which lesson actually applies here, and what is being overridden?". The
+`project::` scope **is** part of the injected set (project is the most-specific
+scope), so `tree`, the hooks, and every read command's `scopeList` now share one
+ordering. Each store is resolved independently, in the same Offline / Remote split.
+
+### `lorekit lint`
+
+Flag low-quality lessons across the applicable scopes and both stores. Each
+finding names the rule it violated:
+
+```bash
+lorekit lint                  # findings grouped by scope; exits non-zero if any
+lorekit lint --scope global   # narrow to a single scope
+lorekit lint --json           # { total, offline, remote } structured findings
+```
+
+Rules: **empty-value** (blank/whitespace-only body), **short-value** (a non-empty
+body below a small length threshold), **untrimmed-value** (real content with
+surrounding whitespace), **empty-key** (blank key), and **malformed-scope** (e.g.
+a single `:` where `::` is expected). `lint` **exits non-zero (1) when any issue
+is found**, so it is usable as a CI gate (`lorekit lint || exit 1`); a clean run —
+or one where only a store is unavailable — exits 0. The pure rule predicates live
+in `lessons-view.mjs` and are unit-tested one rule at a time.
+
+### `lorekit dedupe`
+
+Find likely-duplicate lessons and group them into clusters — per store, across
+the applicable scopes:
+
+```bash
+lorekit dedupe                    # clusters of near-duplicate lessons per store
+lorekit dedupe --threshold 0.6    # loosen the similarity cutoff (default 0.8)
+lorekit dedupe --json             # { threshold, offline, remote } clusters + signal
+```
+
+The similarity signal is a zero-dependency **heuristic** — Jaccard overlap of
+lowercased word tokens, **not** a semantic/embedding measure — so it surfaces
+candidates for a human to review and can both miss paraphrases and group
+coincidental overlaps. Any pair scoring at or above `--threshold` links (transitively)
+into one cluster; only clusters of 2+ members are reported, each with a similarity
+range. Cross-**store** divergence is `diff`'s job; `dedupe` looks within a store.
+
 ### `lorekit hook`
 
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
 It is not run by hand — the plugins wire it into their hook config. It reads
 the host framework's JSON on stdin and prints that host's injection format on
-stdout (lessons at session start; a nudge on failure or at end of turn),
-always exiting 0 so it can never block the host agent.
+stdout (lessons at session start; relevant lessons plus a write-nudge on a tool
+failure; a retrospective nudge at end of turn), always exiting 0 so it can never
+block the host agent.
 
 ```bash
 lorekit hook --adapter <claude|cursor|codex> --event <SessionStart|Stop|…>
@@ -392,8 +453,9 @@ active deny constraints.
 | `--no-hooks` | Skip wiring the lifecycle hooks; skill + MCP only (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
-| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `diff`) |
-| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff`; default: all applicable) |
+| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `diff` / `tree` / `lint` / `dedupe`) |
+| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe`; default: all applicable) |
+| `--threshold <0..1>` | Duplicate-similarity cutoff (`dedupe`; default `0.8`) |
 | `--adapter <name>` | Host framework for `hook`: `claude` / `cursor` / `codex` |
 | `--event <name>` | Host hook event for `hook` (else read from the stdin payload) |
 | `-h, --help` | Help |

package/bin/lorekit.mjs

@@ -11,6 +11,9 @@ import { search } from '../src/search.mjs';
 import { show } from '../src/show.mjs';
 import { stats } from '../src/stats.mjs';
 import { diff } from '../src/diff.mjs';
+import { tree } from '../src/tree.mjs';
+import { lint } from '../src/lint.mjs';
+import { dedupe } from '../src/dedupe.mjs';
 import { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
 import { mcpServer } from '../src/mcp-server.mjs';
@@ -56,6 +59,15 @@ ${c.bold('Commands')}
   diff        Compare the offline and remote stores for the applicable scopes and
               report divergence: local-only, remote-only, and conflicting keys
               (grouped by scope). Needs both stores readable. --json, --scope <s>.
+  tree        Show the injected scopes (branch → repo → global) as a precedence
+    (resolve) hierarchy and mark, per key, which scope's lesson WINS and which are
+              shadowed — the real hook-resolution order. --json, --scope <s>.
+  lint        Flag low-quality lessons (empty/short/untrimmed value, empty key,
+              malformed scope) across the applicable scopes and both stores. Exits
+              non-zero when issues are found (CI gate). --json, --scope <s>.
+  dedupe      Find likely-duplicate lessons via a zero-dep word-overlap HEURISTIC
+              (Jaccard >= threshold, not semantic), grouped into clusters per
+              store. --json, --scope <s>, --threshold <0..1>.
   migrate     Relocate a LoreKit-format local store into the current layout.
               Dry-run by default; pass --yes to apply. Idempotent.
   hook        Hook engine for Claude Code / Cursor / Codex. Reads the host's
@@ -74,8 +86,9 @@ ${c.bold('Options')}
   -t, --token <token>     LoreKit token (lk_rw_* to allow writes, lk_ro_* read-only)
       --mode <mode>       Memory mode: off | local | remote (doctor override)
       --store <path>      Local project-tier store directory (default: .lorekit)
-      --json              Machine-readable output (list / search / show / stats / diff)
-      --scope <scope>     Restrict to a single scope (list / search / stats / diff)
+      --json              Machine-readable output (list / search / show / stats / diff / tree / lint / dedupe)
+      --scope <scope>     Restrict to a single scope (list / search / stats / diff / tree / lint / dedupe)
+      --threshold <0..1>  Duplicate-similarity cutoff (dedupe; default 0.8)
       --from <path>       Source store to migrate from (migrate)
       --to <tier>         Migration destination tier: home | project (migrate;
                           default routes each entry by scope)
@@ -295,6 +308,80 @@ ${c.bold('Examples')}
   npx @lorekit/cli diff
   npx @lorekit/cli diff --json
   npx @lorekit/cli diff --scope global
+`,
+  tree: `${c.bold('lorekit tree')} — show the scope precedence hierarchy and which lesson wins ${c.dim('(alias: resolve)')}
+
+${c.bold('Usage')}
+  npx @lorekit/cli tree [options]
+
+Shows the scopes the hooks actually inject for the current directory — branch,
+repo, global, in precedence order (most-specific first) — and marks, for any key
+present at more than one scope, which scope's lesson WINS and which are shadowed.
+This mirrors the SessionStart hook's resolution exactly (a more-specific scope
+overrides a broader scope's same-key lesson). Project-scope lessons are NOT
+injected by the hooks, so they are not shown here — browse them with \`lorekit list\`.
+Resolved independently per store, in the same Offline / Remote split.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --scope <scope>     Restrict to a single scope (default: the injected set)
+      --json              Machine-readable output (per-entry winning/shadowedBy tags)
+  -e, --endpoint <url>    Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
+  -t, --token <token>     Remote token override (else .mcp.json / LOREKIT_TOKEN)
+      --store <path>      Local project-tier store directory (default: .lorekit)
+
+${c.bold('Examples')}
+  npx @lorekit/cli tree
+  npx @lorekit/cli resolve --json
+`,
+  lint: `${c.bold('lorekit lint')} — flag low-quality lessons across the applicable scopes
+
+${c.bold('Usage')}
+  npx @lorekit/cli lint [options]
+
+Checks every lesson for the current directory's scopes (project/branch/repo/
+global), across both stores, against a small set of quality rules: empty or
+whitespace-only value, suspiciously short value, untrimmed value, empty key, and
+malformed scope (e.g. a single \`:\` where \`::\` is expected). Each finding names
+the rule it violated. Exits NON-ZERO when any issue is found, so it works as a CI
+gate; a clean run — or one where only a store is unavailable — exits 0.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --scope <scope>     Restrict to a single scope (default: all applicable)
+      --json              Machine-readable output (structured findings list)
+  -e, --endpoint <url>    Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
+  -t, --token <token>     Remote token override (else .mcp.json / LOREKIT_TOKEN)
+      --store <path>      Local project-tier store directory (default: .lorekit)
+
+${c.bold('Examples')}
+  npx @lorekit/cli lint
+  npx @lorekit/cli lint --json
+  npx @lorekit/cli lint --scope global
+`,
+  dedupe: `${c.bold('lorekit dedupe')} — find likely-duplicate lessons (heuristic)
+
+${c.bold('Usage')}
+  npx @lorekit/cli dedupe [options]
+
+Groups lessons whose values overlap heavily into duplicate clusters, per store,
+across the current directory's scopes. The similarity signal is a zero-dependency
+HEURISTIC — Jaccard overlap of lowercased word tokens, not a semantic/embedding
+measure — so it surfaces candidates for a human to review, and can both miss
+paraphrases and group coincidental overlaps. Tune the cutoff with --threshold.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --scope <scope>     Restrict to a single scope (default: all applicable)
+      --threshold <0..1>  Similarity cutoff to cluster a pair (default: 0.8)
+      --json              Machine-readable output (clusters + similarity signal)
+  -e, --endpoint <url>    Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
+  -t, --token <token>     Remote token override (else .mcp.json / LOREKIT_TOKEN)
+      --store <path>      Local project-tier store directory (default: .lorekit)
+
+${c.bold('Examples')}
+  npx @lorekit/cli dedupe
+  npx @lorekit/cli dedupe --threshold 0.6 --json
 `,
   migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
 
@@ -348,19 +435,20 @@ ${c.bold('Options')}
 const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
   'from', 'to', 'apply', 'yes', 'no-hooks', 'force', 'deep', 'adapter',
-  'event', 'json', 'scope', 'help', 'version',
+  'event', 'json', 'scope', 'threshold', 'help', 'version',
 ];
 
 // Commands that write to disk / talk to the network on a human's behalf. These
 // reject unknown flags; the machine-facing `hook` / `mcp` do not (they must
 // never fail on a stray flag, and only ever receive flags we control).
 const HUMAN_COMMANDS = new Set([
-  'install', 'uninstall', 'doctor', 'list', 'search', 'show', 'stats', 'diff', 'migrate',
+  'install', 'uninstall', 'doctor', 'list', 'search', 'show', 'stats', 'diff',
+  'tree', 'lint', 'dedupe', 'migrate',
 ]);
 
 // Command aliases — canonicalized before help / dispatch so `lorekit ls --help`
 // and telemetry both resolve to the real command name.
-const COMMAND_ALIASES = { ls: 'list', grep: 'search' };
+const COMMAND_ALIASES = { ls: 'list', grep: 'search', resolve: 'tree' };
 
 async function main() {
   // Load a `.env` from the current directory (if any) before anything reads the
@@ -439,6 +527,12 @@ async function main() {
       return traceCommand('stats', args, VERSION, () => stats(args));
     case 'diff':
       return traceCommand('diff', args, VERSION, () => diff(args));
+    case 'tree':
+      return traceCommand('tree', args, VERSION, () => tree(args));
+    case 'lint':
+      return traceCommand('lint', args, VERSION, () => lint(args));
+    case 'dedupe':
+      return traceCommand('dedupe', args, VERSION, () => dedupe(args));
     case 'migrate':
       return traceCommand('migrate', args, VERSION, () => migrate(args));
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/core/lessons.mjs

@@ -3,23 +3,52 @@
 // Storage is reached through the resolved store (local | remote), never a
 // backend directly, so the same read path serves every mode.
 import { deriveScope } from '../scope.mjs';
+// The precedence merge and the literal substring matcher come from the
+// dependency-free `lessons-pure.mjs` — the SAME primitives `tree` and `search`
+// use, so the hook can't drift from them, and the hot path never pulls in the
+// `lessons-view.mjs` render/`util` stack.
+import { resolvePrecedence, matchesQuery } from '../lessons-pure.mjs';
 
 const MAX_LESSONS = 15;
+// Cap on lessons injected on a failure — a small, focused "you've seen this
+// before" set, never the whole applicable corpus.
+const MAX_RELEVANT = 3;
+// Cap on the terms distilled from a failure — bounds the relevance scan so a
+// huge error blob can never turn into an unbounded match loop.
+const MAX_TERMS = 12;
+// Terms shorter than this are dropped: too generic to make a match meaningful.
+const MIN_TERM_LEN = 4;
+// Cap on how much failure text is scanned for terms. A tool can dump a
+// multi-megabyte stderr/stdout; the salient error words are always near the
+// front, so we bound the input BEFORE lowercasing/splitting it — otherwise a
+// giant blob would materialise a giant token array (a CPU/memory spike) even
+// though the term COUNT is capped. Generous enough to never clip a real error.
+const MAX_SCAN_CHARS = 4096;
 
-// Read lessons narrow-to-broad through the store and merge; more specific
-// scope wins on key. Any per-scope failure is skipped (memory is best-effort).
+// Read lessons narrow-to-broad through the store and resolve cross-scope
+// precedence via the shared pure `resolvePrecedence` (the SAME first-seen /
+// more-specific-wins merge `tree` renders) — so the hook and `tree` provably
+// can't drift. Any per-scope failure is skipped (memory is best-effort).
 export async function fetchLessons(store, cwd) {
   const scope = deriveScope(cwd);
-  const byKey = new Map();
+  const groups = [];
   for (const s of scope.readOrder) {
     const res = await store.list({ scope: s, limit: 25 });
-    if (!res || !res.ok) continue;
-    const entries = Array.isArray(res.entries) ? res.entries : [];
-    for (const e of entries) {
-      if (e && e.key && !byKey.has(e.key)) byKey.set(e.key, { ...e, scope: s });
-    }
+    if (!res || !res.ok) continue; // best-effort: a failed scope contributes nothing
+    const entries = (Array.isArray(res.entries) ? res.entries : [])
+      .filter((e) => e && e.key)
+      .map((e) => ({ ...e, scope: s }));
+    groups.push({ scope: s, error: null, entries });
   }
-  return { scope, lessons: [...byKey.values()].slice(0, MAX_LESSONS) };
+  // First value per key wins (most-specific scope, since `readOrder` is
+  // narrow→broad) — exactly what the old inline `byKey` merge did, now via the
+  // one shared resolver. The winners, in group order, are the injected set.
+  const { groups: resolved } = resolvePrecedence({ groups });
+  const lessons = [];
+  for (const g of resolved) {
+    for (const e of g.entries) if (e.winning) lessons.push(e);
+  }
+  return { scope, lessons: lessons.slice(0, MAX_LESSONS) };
 }
 
 // Render lessons as a compact markdown block, or null when there are none.
@@ -37,6 +66,60 @@ export function formatLessons(lessons, scope) {
   return `${header}\n${body}`;
 }
 
+// Distil a small set of significant, lowercased search TERMS from a tool
+// failure — the tool name plus the salient words of its error text — used to
+// look up lessons that might already cover this failure. Pure and total: any
+// shape of `toolResponse` (object, string, null, malformed) is handled without
+// throwing. Terms are de-duplicated, stopword- and length-filtered so a match
+// stays meaningful, and the count is capped (`MAX_TERMS`) so a huge error blob
+// can't blow up the downstream scan.
+export function failureQuery(toolName, toolResponse) {
+  const text = `${toolName ? String(toolName) : ''} ${errorText(toolResponse)}`.slice(0, MAX_SCAN_CHARS);
+  const seen = new Set();
+  const terms = [];
+  for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+    if (raw.length < MIN_TERM_LEN || STOPWORDS.has(raw) || seen.has(raw)) continue;
+    seen.add(raw);
+    terms.push(raw);
+    if (terms.length >= MAX_TERMS) break;
+  }
+  return terms;
+}
+
+// Lessons whose key OR value literally contains ANY of the failure `terms`
+// (case-insensitive, via the shared `matchesQuery` — never a regex), capped at
+// `cap`. Pure and best-effort: no terms or no lessons → empty (the caller then
+// falls back to the write-nudge alone). Preserves `lessons` order, so the
+// most-specific scope's relevant lesson surfaces first.
+export function relevantLessons(lessons, terms, cap = MAX_RELEVANT) {
+  if (!Array.isArray(lessons) || !lessons.length || !Array.isArray(terms) || !terms.length) {
+    return [];
+  }
+  const out = [];
+  for (const l of lessons) {
+    if (terms.some((t) => matchesQuery(l, t))) out.push(l);
+    if (out.length >= cap) break;
+  }
+  return out;
+}
+
+// Render the relevant-lessons block injected alongside the failure nudge, or
+// null when nothing matched. Framed as prior art, not a directive — same
+// "considerations, not rules" stance as `formatLessons`.
+export function formatRelevantLessons(lessons) {
+  if (!lessons || lessons.length === 0) return null;
+  const header =
+    `LoreKit — you've hit something like this before. ${lessons.length} related ` +
+    'lesson(s) (considerations, not rules; trust the current code if they conflict):';
+  const body = lessons
+    .map((l) => {
+      const first = String(l.value || '').split('\n')[0].slice(0, 300);
+      return `- (${l.scope}) ${l.key}: ${first}`;
+    })
+    .join('\n');
+  return `${header}\n${body}`;
+}
+
 // The retrospective nudge emitted at end-of-turn (one-shot per session).
 export function retrospectiveNudge(scope) {
   const writeScope = scope.repoScope || 'global';
@@ -58,3 +141,64 @@ export function failureNudge(toolName, scope) {
     `lorekit-memory (memory.write to ${writeScope}), so the next run avoids it.`
   );
 }
+
+// Pull the human-readable error text out of a tool_response of any shape. Total:
+// null/primitive/string/object all yield a (possibly empty) string, never a
+// throw — the relevance lookup is best-effort and must not break the host.
+function errorText(response) {
+  if (response == null) return '';
+  if (typeof response === 'string') return response;
+  if (typeof response !== 'object') return String(response);
+  const parts = [];
+  for (const f of TEXT_FIELDS) {
+    const v = response[f];
+    if (typeof v === 'string') parts.push(v);
+    else if (v && typeof v === 'object') parts.push(safeStringify(v));
+  }
+  return parts.length ? parts.join(' ') : safeStringify(response);
+}
+
+function safeStringify(v) {
+  try {
+    return JSON.stringify(v) || '';
+  } catch {
+    return '';
+  }
+}
+
+// The tool_response fields that commonly carry error text, across frameworks.
+const TEXT_FIELDS = [
+  'stderr',
+  'error',
+  'message',
+  'stdout',
+  'output',
+  'content',
+  'reason',
+  'detail',
+  'details',
+];
+
+// Generic words dropped from a failure query: too common to make a lesson match
+// meaningful (they'd match almost anything). Kept small and hand-picked.
+const STOPWORDS = new Set([
+  'error',
+  'errors',
+  'failed',
+  'failure',
+  'tool',
+  'call',
+  'code',
+  'exit',
+  'with',
+  'this',
+  'that',
+  'from',
+  'null',
+  'true',
+  'false',
+  'undefined',
+  'command',
+  'response',
+  'status',
+]);

package/src/dedupe.mjs

@@ -0,0 +1,184 @@
+// `lorekit dedupe` — detect likely-duplicate lessons across the applicable
+// scopes within each store. ZERO-DEP means a HEURISTIC, never embeddings: it
+// clusters lessons whose values share a high Jaccard word-token overlap (default
+// 0.8, tunable with `--threshold`). It flags candidates worth a human's eye — it
+// is NOT a semantic judge and can both miss paraphrases and group coincidental
+// overlaps. The pure core (`tokenize` / `similarity` / `clusterDuplicates`) lives
+// in `lessons-view.mjs` and is thoroughly unit-tested.
+//
+// Clustering is per-store, across all applicable scopes (an offline cluster may
+// span project + global; cross-STORE divergence is `diff`'s job, not this one).
+// Same Offline / Remote split and graceful degradation as `list`. Read-only.
+// Human-facing, so the bin wraps it in `traceCommand`.
+import process from 'node:process';
+import { resolveProjectRoot } from './config.mjs';
+import { deriveScope } from './scope.mjs';
+import { resolveDenies } from './control.mjs';
+import { resolveStores, remoteUnavailableReason } from './stores.mjs';
+import { scopeList, gather, clusterDuplicates } from './lessons-view.mjs';
+import { log, heading, status, c } from './util.mjs';
+
+const DEFAULT_THRESHOLD = 0.8;
+
+// Parse `--threshold` into a number in [0, 1]; anything unparseable or out of
+// range falls back to the default (never a crash on bad input). Pure-ish helper.
+export function parseThreshold(raw) {
+  if (raw === undefined || raw === true) return DEFAULT_THRESHOLD;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return DEFAULT_THRESHOLD;
+  return Math.min(1, Math.max(0, n));
+}
+
+// Flatten a `gather()` result into one entry list (each entry keeps its scope)
+// for cross-scope clustering, plus the scopes whose read errored (they can't be
+// clustered and are surfaced, not silently dropped).
+function flatten(gathered) {
+  const entries = [];
+  const errored = [];
+  for (const g of gathered.groups || []) {
+    if (g.error) {
+      errored.push({ scope: g.scope, error: g.error });
+      continue;
+    }
+    for (const e of g.entries || []) entries.push(e);
+  }
+  return { entries, errored };
+}
+
+export async function dedupe(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  const threshold = parseThreshold(args.threshold);
+  const scopeInfo = deriveScope(root);
+  // Default to every applicable scope; `--scope <s>` narrows to one.
+  const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeList(scopeInfo);
+
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+
+  // Deny-wins section suppression, identical to the other read commands.
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  const buildSection = (flat) => ({
+    available: true,
+    clusters: clusterDuplicates(flat.entries, threshold),
+    errored: flat.errored,
+  });
+
+  const offlineSection = localDenied
+    ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
+    : buildSection(flatten(await gather(local, scopes)));
+
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteSection = remoteAvailable
+    ? buildSection(flatten(await gather(remote, scopes)))
+    : {
+        available: false,
+        reason: remoteDenied
+          ? `disabled by deny constraint (${remoteDenied.source})`
+          : remoteUnavailableReason(connection),
+      };
+
+  const offlineClusters = offlineSection.available ? offlineSection.clusters.length : 0;
+  const remoteClusters = remoteSection.available ? remoteSection.clusters.length : 0;
+
+  if (args.json) {
+    log(JSON.stringify(buildJson({ root, scopes, threshold, offlineSection, remoteSection }), null, 2));
+  } else {
+    heading('LoreKit dedupe');
+    log(`  project: ${c.dim(root)}`);
+    log(`  scopes:  ${scopes.join('  →  ')}`);
+    log(`  ${c.dim(`heuristic: Jaccard word-token overlap >= ${threshold} (not semantic)`)}`);
+
+    renderDedupeSection({ title: 'Offline' }, offlineSection);
+    renderDedupeSection(
+      { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined },
+      remoteSection,
+    );
+
+    log('');
+    const total = offlineClusters + remoteClusters;
+    if (total === 0) {
+      log(`  ${c.green('✓')} no likely-duplicate clusters at this threshold`);
+    } else {
+      const plural = total === 1 ? '' : 's';
+      log(`  ${c.yellow('!')} ${total} duplicate cluster${plural} found`);
+    }
+    log('');
+  }
+
+  // Bounded, non-PII telemetry extras — counts + a boolean, never a scope
+  // string, key, path, or token.
+  return {
+    exitCode: 0,
+    'lorekit.cli.dedupe.scope_count': scopes.length,
+    'lorekit.cli.dedupe.threshold': threshold,
+    'lorekit.cli.dedupe.offline_clusters': offlineClusters,
+    'lorekit.cli.dedupe.remote_clusters': remoteClusters,
+    'lorekit.cli.dedupe.remote_available': remoteAvailable,
+  };
+}
+
+// Render one store's clusters: each cluster lists its member scope::key lines
+// and a similarity signal. A read error (a scope that couldn't be gathered) is
+// surfaced up front so a partial read is never mistaken for "no duplicates".
+function renderDedupeSection(header, section) {
+  heading(header.title);
+  if (header.subtitle) log(`  ${c.dim(header.subtitle)}`);
+
+  if (!section.available) {
+    status('warn', 'unavailable', section.reason);
+    return;
+  }
+
+  for (const e of section.errored || []) {
+    log(`  ${c.bold(e.scope)}  ${c.yellow('!')} ${c.dim(e.error)}`);
+  }
+
+  if (!section.clusters.length) {
+    if (!(section.errored || []).length) log(`  ${c.dim('no likely-duplicate clusters')}`);
+    return;
+  }
+
+  let n = 0;
+  for (const cluster of section.clusters) {
+    n += 1;
+    const range =
+      cluster.minSimilarity === cluster.maxSimilarity
+        ? cluster.minSimilarity.toFixed(2)
+        : `${cluster.minSimilarity.toFixed(2)}–${cluster.maxSimilarity.toFixed(2)}`;
+    log(`  ${c.yellow('•')} cluster ${n} ${c.dim(`(${cluster.size} lessons, similarity ${range})`)}`);
+    for (const m of cluster.members) {
+      log(`    ${c.cyan('-')} ${m.scope}::${m.key}`);
+    }
+  }
+}
+
+// The `--json` payload: `{ root, scopes, threshold, offline, remote }` — each
+// store a `{ available, clusters: [{ members, size, minSimilarity,
+// maxSimilarity }], errored }` record (or an unavailable note).
+function buildJson({ root, scopes, threshold, offlineSection, remoteSection }) {
+  return {
+    root,
+    scopes,
+    threshold,
+    offline: sectionJson(offlineSection),
+    remote: sectionJson(remoteSection),
+  };
+}
+
+function sectionJson(section) {
+  if (!section.available) {
+    return { available: false, reason: section.reason, clusters: [], errored: [] };
+  }
+  return {
+    available: true,
+    clusters: section.clusters,
+    errored: section.errored || [],
+  };
+}

package/src/hook.mjs

@@ -7,7 +7,15 @@ import { resolveProjectRoot } from './config.mjs';
 import { deriveScope } from './scope.mjs';
 import { loadControl } from './control.mjs';
 import { createStore } from './store/index.mjs';
-import { fetchLessons, formatLessons, retrospectiveNudge, failureNudge } from './core/lessons.mjs';
+import {
+  fetchLessons,
+  formatLessons,
+  retrospectiveNudge,
+  failureNudge,
+  failureQuery,
+  relevantLessons,
+  formatRelevantLessons,
+} from './core/lessons.mjs';
 import { isFailure } from './core/failure.mjs';
 import { firstTimeThisSession } from './core/state.mjs';
 import { recordFixture } from './core/record.mjs';
@@ -92,7 +100,22 @@ async function run(args) {
     const known = adapter.guaranteedFailure ? adapter.guaranteedFailure(event) : false;
     if (!known && !isFailure(parsed.toolName, parsed.toolResponse)) return 0;
     if (!firstTimeThisSession(parsed.sessionId, 'failure')) return 0;
-    emit(failureNudge(parsed.toolName, scope));
+    // Best-effort: surface any existing lessons that look relevant to THIS
+    // failure ("you've hit this before"), then the write-nudge. A missing /
+    // unusable store, or no match, silently falls back to the nudge alone.
+    let relevant = null;
+    try {
+      const store = createStore(control);
+      if (store) {
+        const { lessons } = await fetchLessons(store, root);
+        const terms = failureQuery(parsed.toolName, parsed.toolResponse);
+        relevant = formatRelevantLessons(relevantLessons(lessons, terms));
+      }
+    } catch {
+      relevant = null; // never let a lesson lookup break the failure nudge
+    }
+    const nudge = failureNudge(parsed.toolName, scope);
+    emit(relevant ? `${relevant}\n\n${nudge}` : nudge);
     return 0;
   }
 

package/src/lessons-pure.mjs

@@ -0,0 +1,65 @@
+// Pure, DEPENDENCY-FREE lesson primitives shared by the hook engine
+// (`core/lessons.mjs`, the hot path) and the read-command view layer
+// (`lessons-view.mjs`, which re-exports these). Kept in its own module so the
+// hook can import the exact precedence + match logic the read commands use —
+// one source of truth, no drift — WITHOUT dragging in the rendering/`util`
+// stack (`heading`/`log`/`c`, plus the lint/dedupe/diff cores) that the rest of
+// `lessons-view.mjs` carries. Zero imports on purpose.
+
+// ── cross-scope precedence resolution (the `tree` + hook merge core) ──────────
+
+// Given per-scope groups in RESOLUTION ORDER — most-specific first, exactly the
+// order `deriveScope().readOrder` produces — compute which scope's lesson WINS
+// each key and which are shadowed. This is the hook engine's merge: it iterates
+// the scopes narrow-to-broad and keeps the FIRST value seen per key (`if
+// (!winnerScopeByKey.has(key)) set`), so a more-specific scope shadows a broader
+// scope's same-key lesson. Returns the same groups with every entry tagged
+// `{ winning, shadowedBy }` (`shadowedBy` = the scope that won the key, or null
+// for a winner), plus the resolved `winners` list (`{ scope, key }`, one per
+// key) and winning/shadowed counts. A per-scope read error is passed through
+// untouched (empty entries), so one unreadable scope never derails resolution.
+// Pure — consumed by both `tree` (display) and `fetchLessons` (injection).
+export function resolvePrecedence({ groups = [] } = {}) {
+  const winnerScopeByKey = new Map(); // key → the scope that first claimed it
+  const outGroups = [];
+  let winningTotal = 0;
+  let shadowedTotal = 0;
+  for (const g of groups) {
+    if (g.error) {
+      outGroups.push({ scope: g.scope, error: g.error, entries: [] });
+      continue;
+    }
+    const entries = [];
+    for (const e of g.entries || []) {
+      const prior = winnerScopeByKey.get(e.key);
+      if (prior === undefined) {
+        winnerScopeByKey.set(e.key, g.scope);
+        entries.push({ ...e, winning: true, shadowedBy: null });
+        winningTotal += 1;
+      } else {
+        entries.push({ ...e, winning: false, shadowedBy: prior });
+        shadowedTotal += 1;
+      }
+    }
+    outGroups.push({ scope: g.scope, error: null, entries });
+  }
+  const winners = [...winnerScopeByKey.entries()].map(([key, scope]) => ({ scope, key }));
+  return { groups: outGroups, winners, winningTotal, shadowedTotal };
+}
+
+// ── literal, case-insensitive substring matching (the `search` + hook core) ───
+
+// Case-insensitive, LITERAL substring match of `query` against a normalized
+// entry's key OR value — the `search` command's matcher, and the hook's
+// failure-relevance matcher. Deliberately a plain `String.includes` (never
+// `new RegExp(query)`) so a query full of regex metacharacters like `a.*(b)`
+// matches those characters verbatim, never as a pattern. An empty query matches
+// everything (the command guards emptiness as a usage error before ever calling
+// this). Pure — trivially unit-testable.
+export function matchesQuery(entry, query) {
+  const needle = String(query == null ? '' : query).toLowerCase();
+  if (!needle) return true;
+  const key = String(entry?.key ?? '').toLowerCase();
+  const value = String(entry?.value ?? '').toLowerCase();
+  return key.includes(needle) || value.includes(needle);
+}

package/src/lint.mjs

@@ -0,0 +1,152 @@
+// `lorekit lint` — flag low-quality lessons across the applicable scopes and
+// both stores. Each finding names the rule it violated (empty/whitespace value,
+// suspiciously short value, untrimmed value, empty key, malformed scope). The
+// rules are pure predicates in `lessons-view.mjs` (`LINT_RULES` / `lintEntry`),
+// each independently unit-tested.
+//
+// Exit convention: `lint` exits NON-ZERO (1) when any finding exists, so it is
+// usable as a CI gate (`lorekit lint || fail`); a clean run — or a run where the
+// only issue is an unavailable store — exits 0. `--json` carries the structured
+// findings either way. Same Offline / Remote split and graceful degradation as
+// `list`; a `LOREKIT_DENY` ceiling or an unconfigured remote is a note, not an
+// error. Read-only. Human-facing, so the bin wraps it in `traceCommand`.
+import process from 'node:process';
+import { resolveProjectRoot } from './config.mjs';
+import { deriveScope } from './scope.mjs';
+import { resolveDenies } from './control.mjs';
+import { resolveStores, remoteUnavailableReason } from './stores.mjs';
+import { scopeList, gather, lintGroups } from './lessons-view.mjs';
+import { log, heading, status, c } from './util.mjs';
+
+export async function lint(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  const scopeInfo = deriveScope(root);
+  // Default to every applicable scope; `--scope <s>` narrows to one.
+  const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeList(scopeInfo);
+
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+
+  // Deny-wins section suppression, identical to the other read commands.
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  const offlineResult = localDenied ? { groups: [], total: 0 } : lintGroups(await gather(local, scopes));
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteResult = remoteAvailable ? lintGroups(await gather(remote, scopes)) : { groups: [], total: 0 };
+
+  const offlineSection = localDenied
+    ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
+    : { available: true, ...offlineResult };
+  const remoteSection = remoteAvailable
+    ? { available: true, ...remoteResult }
+    : {
+        available: false,
+        reason: remoteDenied
+          ? `disabled by deny constraint (${remoteDenied.source})`
+          : remoteUnavailableReason(connection),
+      };
+
+  const totalFindings =
+    (offlineSection.available ? offlineSection.total : 0) +
+    (remoteSection.available ? remoteSection.total : 0);
+
+  if (args.json) {
+    log(JSON.stringify(buildJson({ root, scopes, offlineSection, remoteSection, totalFindings }), null, 2));
+  } else {
+    heading('LoreKit lint');
+    log(`  project: ${c.dim(root)}`);
+    log(`  scopes:  ${scopes.join('  →  ')}`);
+
+    renderLintSection({ title: 'Offline' }, offlineSection);
+    renderLintSection(
+      { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined },
+      remoteSection,
+    );
+
+    log('');
+    if (totalFindings === 0) {
+      log(`  ${c.green('✓')} no lint issues in the applicable scopes`);
+    } else {
+      const plural = totalFindings === 1 ? '' : 's';
+      log(`  ${c.yellow('!')} ${totalFindings} lint issue${plural} found`);
+    }
+    log('');
+  }
+
+  // Exit non-zero when findings exist so `lint` is usable as a CI gate. An
+  // unavailable store is never itself a failure — only actual findings are.
+  // Bounded, non-PII telemetry extras — counts + a boolean.
+  return {
+    exitCode: totalFindings > 0 ? 1 : 0,
+    'lorekit.cli.lint.scope_count': scopes.length,
+    'lorekit.cli.lint.offline_findings': offlineSection.available ? offlineSection.total : 0,
+    'lorekit.cli.lint.remote_findings': remoteSection.available ? remoteSection.total : 0,
+    'lorekit.cli.lint.total_findings': totalFindings,
+    'lorekit.cli.lint.remote_available': remoteAvailable,
+  };
+}
+
+// Render one store's findings, grouped by scope: `key  rule — message` per
+// finding. A scope with no findings and no error is omitted; a read error is
+// surfaced in place (its entries couldn't be linted).
+function renderLintSection(header, section) {
+  heading(header.title);
+  if (header.subtitle) log(`  ${c.dim(header.subtitle)}`);
+
+  if (!section.available) {
+    status('warn', 'unavailable', section.reason);
+    return;
+  }
+
+  const printable = (section.groups || []).filter((g) => g.findings.length || g.error);
+  if (!printable.length) {
+    log(`  ${c.dim('no lint issues in the applicable scopes')}`);
+    return;
+  }
+
+  for (const g of printable) {
+    log(`  ${c.bold(g.scope)}`);
+    if (g.error) {
+      log(`    ${c.yellow('!')} ${c.dim(g.error)}`);
+      continue;
+    }
+    for (const f of g.findings) {
+      log(`    ${c.yellow('•')} ${f.key}  ${c.dim(`[${f.rule}]`)} ${f.message}`);
+    }
+  }
+}
+
+// The `--json` payload: `{ root, scopes, total, offline, remote }` — each store
+// a `{ available, total, scopes: [{ scope, error, findings: [{ key, rule,
+// message }] }] }` record (or an unavailable note), so a script gets the same
+// structured finding list regardless of which store it came from.
+function buildJson({ root, scopes, offlineSection, remoteSection, totalFindings }) {
+  return {
+    root,
+    scopes,
+    total: totalFindings,
+    offline: sectionJson(offlineSection),
+    remote: sectionJson(remoteSection),
+  };
+}
+
+function sectionJson(section) {
+  if (!section.available) {
+    return { available: false, reason: section.reason, total: 0, scopes: [] };
+  }
+  return {
+    available: true,
+    total: section.total,
+    scopes: (section.groups || []).map((g) => ({
+      scope: g.scope,
+      error: g.error || null,
+      findings: g.findings,
+    })),
+  };
+}

package/src/scope.mjs

@@ -44,7 +44,11 @@ export function deriveScope(cwd = process.cwd()) {
       : null;
   const projectScope = `project::${projectName}`;
 
-  const readOrder = [branchScope, repoScope, 'global'].filter(Boolean);
+  // Injection / resolution order, most-specific → broadest. Matches the read
+  // commands' `scopeList` exactly (`lessons-view.mjs`) — project is FIRST, so a
+  // project-scoped lesson wins and IS injected. De-duplicated (a project whose
+  // basename collides with a scope, or a repo with no branch, never repeats).
+  const readOrder = [...new Set([projectScope, branchScope, repoScope, 'global'].filter(Boolean))];
 
   return {
     ownerRepo,

package/src/telemetry.mjs

@@ -4,9 +4,9 @@
 // mirrors the Edge Function's SDK-free approach (supabase/functions/_shared/
 // otel.ts): OTLP/JSON over the global fetch (Node 18+), no @opentelemetry/*
 // packages. One span + one counter data point per human-facing command
-// (install / uninstall / doctor / list / search / show / stats / diff /
-// migrate), fired to Dash0 so the maintainers can see which commands people
-// actually run.
+// (install / uninstall / doctor / list / search / show / stats / diff / tree /
+// lint / dedupe / migrate), fired to Dash0 so the maintainers can see which
+// commands people actually run.
 //
 // Privacy — this runs on end-users' machines, so it is deliberately narrow:
 //   • Opt-out honored: LOREKIT_TELEMETRY=0|off|false|no|disable, or the
@@ -275,7 +275,7 @@ function normalizeExitCode(result) {
  * counter point. Returns the command's exit code unchanged. Telemetry failures
  * are swallowed — the command result is never affected.
  *
- * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | diff | migrate
+ * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | diff | tree | lint | dedupe | migrate
  * @param {object} args     parsed CLI args (read for allow-listed flags only)
  * @param {string} version  CLI version (from package.json)
  * @param {() => Promise<number>} run  the command handler

package/src/tree.mjs

@@ -0,0 +1,157 @@
+// `lorekit tree` (alias `resolve`) — show the applicable scopes as a precedence
+// hierarchy and mark, for any key that lives at MORE THAN ONE scope, which
+// scope's lesson actually WINS and which are shadowed. This answers "which
+// lesson applies here, and what is being overridden?".
+//
+// Precedence is not an assumption — it mirrors the hook engine exactly. The
+// SessionStart hook (`core/lessons.mjs → fetchLessons`) reads the scopes in
+// `deriveScope().readOrder` (project → branch → repo → global, most-specific
+// first) and keeps the FIRST value seen per key, so a more-specific scope
+// shadows a broader scope's same-key lesson. `tree` resolves over that same
+// `readOrder` set via the pure `resolvePrecedence`, so it shows the same
+// resolution order the agent is injected with (the hook additionally caps the
+// injected set at MAX_LESSONS; `tree` is uncapped, so a large workspace may list
+// more winners than the hook injects).
+//
+// NOTE on scope coverage: `readOrder` is the injected set. As of the smart-hooks
+// PR it INCLUDES `project::` (project is the most-specific scope and now wins /
+// is injected), so `tree` shows it too — the ordering is now unified across the
+// hook, `tree`, and every read command's `scopeList`. Both stores are resolved
+// independently (precedence is per-store — the hook reads one resolved store),
+// in the same Offline / Remote split as `list`. Graceful, read-only, wrapped in
+// `traceCommand` by the bin.
+import process from 'node:process';
+import { resolveProjectRoot } from './config.mjs';
+import { deriveScope } from './scope.mjs';
+import { resolveDenies } from './control.mjs';
+import { resolveStores, remoteUnavailableReason } from './stores.mjs';
+import { resolvePrecedence } from './lessons-pure.mjs';
+import { gather, preview, shortDate } from './lessons-view.mjs';
+import { log, heading, status, c } from './util.mjs';
+
+export async function tree(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  const scopeInfo = deriveScope(root);
+  // Default to the injected resolution set (`readOrder`, most-specific first);
+  // `--scope <s>` narrows to one (honored even outside the set — the user asked).
+  const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeInfo.readOrder;
+
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+
+  // Deny-wins section suppression, identical to the other read commands.
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  const offlineResolved = localDenied ? null : resolvePrecedence(await gather(local, scopes));
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteResolved = remoteAvailable ? resolvePrecedence(await gather(remote, scopes)) : null;
+
+  const offlineSection = localDenied
+    ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
+    : { available: true, ...offlineResolved };
+  const remoteSection = remoteAvailable
+    ? { available: true, ...remoteResolved }
+    : {
+        available: false,
+        reason: remoteDenied
+          ? `disabled by deny constraint (${remoteDenied.source})`
+          : remoteUnavailableReason(connection),
+      };
+
+  if (args.json) {
+    log(JSON.stringify(buildJson({ root, scopes, offlineSection, remoteSection }), null, 2));
+  } else {
+    heading('LoreKit resolution tree');
+    log(`  project: ${c.dim(root)}`);
+    log(`  scopes:  ${scopes.join('  →  ')}`);
+    log(`  ${c.dim('precedence order (most-specific first); a more-specific scope wins a duplicate key')}`);
+
+    renderTreeSection({ title: 'Offline' }, offlineSection);
+    renderTreeSection(
+      { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined },
+      remoteSection,
+    );
+
+    log('');
+  }
+
+  // Bounded, non-PII telemetry extras — counts + a boolean, never a scope
+  // string, key, path, or token.
+  return {
+    exitCode: 0,
+    'lorekit.cli.tree.scope_count': scopes.length,
+    'lorekit.cli.tree.offline_winning': offlineSection.available ? offlineSection.winningTotal : 0,
+    'lorekit.cli.tree.offline_shadowed': offlineSection.available ? offlineSection.shadowedTotal : 0,
+    'lorekit.cli.tree.remote_shadowed': remoteSection.available ? remoteSection.shadowedTotal : 0,
+    'lorekit.cli.tree.remote_available': remoteAvailable,
+  };
+}
+
+// Render one store's resolution: each scope in precedence order with its entries
+// tagged winning (✓) or shadowed (↳ shadowed by <scope>). A scope with no
+// entries and no error is omitted; a read error is surfaced in place.
+function renderTreeSection(header, section) {
+  heading(header.title);
+  if (header.subtitle) log(`  ${c.dim(header.subtitle)}`);
+
+  if (!section.available) {
+    status('warn', 'unavailable', section.reason);
+    return;
+  }
+
+  const printable = (section.groups || []).filter((g) => g.entries.length || g.error);
+  if (!printable.length) {
+    log(`  ${c.dim('no lessons found in the applicable scopes')}`);
+    return;
+  }
+
+  for (const g of printable) {
+    log(`  ${c.bold(g.scope)}`);
+    if (g.error) {
+      log(`    ${c.yellow('!')} ${c.dim(g.error)}`);
+      continue;
+    }
+    for (const e of g.entries) {
+      const when = e.updated ? `  ${c.dim(`(updated ${shortDate(e.updated)})`)}` : '';
+      const mark = e.winning ? c.green('✓') : c.yellow('↳');
+      const tag = e.winning ? '' : `  ${c.dim(`shadowed by ${e.shadowedBy}`)}`;
+      log(`    ${mark} ${e.key}${tag}${when}`);
+      if (e.value) log(`      ${c.dim(preview(e.value))}`);
+    }
+  }
+
+  log(
+    `  ${c.dim(`${section.winningTotal} winning, ${section.shadowedTotal} shadowed`)}`,
+  );
+}
+
+// The `--json` payload: per-section resolved groups (each entry carrying its
+// `winning` / `shadowedBy` tags), the flat `winners` list, and the counts — so a
+// script gets the resolution verdict directly, in the same shape per store.
+function buildJson({ root, scopes, offlineSection, remoteSection }) {
+  return {
+    root,
+    scopes,
+    offline: sectionJson(offlineSection),
+    remote: sectionJson(remoteSection),
+  };
+}
+
+function sectionJson(section) {
+  if (!section.available) {
+    return { available: false, reason: section.reason, winners: [], groups: [] };
+  }
+  return {
+    available: true,
+    winningTotal: section.winningTotal,
+    shadowedTotal: section.shadowedTotal,
+    winners: section.winners,
+    groups: section.groups,
+  };
+}