@lorekit/cli 1.9.0 → 1.10.0

package/README.md

@@ -173,6 +173,43 @@ missing. It exits **non-zero** when the key is found in no readable store, so it
 fits scripts. `--json` emits the full normalized record(s) and which store each
 came from. Both a scope and a key are required (else a usage error).
 
+### `lorekit stats`
+
+An at-a-glance overview of how many lessons apply to the current directory —
+counted **per scope** and **per store** (Offline vs Remote), with per-store and
+grand totals, in the same Offline / Remote split as `list`:
+
+```bash
+lorekit stats                 # per-scope counts + totals for both stores
+lorekit stats --scope global  # narrow to a single scope
+lorekit stats --json          # { offline, remote } with per-scope { count } rows
+```
+
+Every applicable scope prints a row (a scope with zero lessons still shows `0`,
+which is the point of an overview). An unconfigured remote degrades to a short
+note — never an error, always exit 0. `--endpoint` / `--token` / `--store`
+behave as in `list`. Remote counts reflect what the hosted `memory.list` returns
+per scope (the server's default page size); there is no cap-usage `N / limit`
+figure because the MCP surface exposes no total-count or cap tool.
+
+### `lorekit diff`
+
+Compare the **offline** and **remote** stores for the applicable scopes and
+report where they diverge, grouped by scope:
+
+```bash
+lorekit diff                  # local-only / remote-only / conflicting, per scope
+lorekit diff --scope global   # narrow to a single scope
+lorekit diff --json           # { comparable, totals, groups[] } for scripts
+```
+
+Three groups: **local-only** (key present offline, absent remote), **remote-only**
+(absent offline, present remote), and **conflicting** (same `scope::key` in both,
+but the value or tags differ). A diff needs **both** stores readable — if the
+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 hook`
 
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
@@ -355,8 +392,8 @@ 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`) |
-| `--scope <scope>` | Restrict to a single scope (`list` / `search`; default: all applicable) |
+| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `diff`) |
+| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff`; default: all applicable) |
 | `--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 |
@@ -442,7 +479,7 @@ forever. This reduces manual validation to a single capture pass per tool.
 ## Usage telemetry
 
 The human-facing commands (`install`, `uninstall`, `doctor`, `list`, `search`,
-`show`, `migrate`)
+`show`, `stats`, `diff`, `migrate`)
 emit one OpenTelemetry span + one counter point per run so the maintainers can see which
 commands people use. It is zero-dependency (OTLP/JSON over `fetch`, no SDK) and
 deliberately narrow — it carries only the command name, a bounded set of boolean

package/bin/lorekit.mjs

@@ -9,6 +9,8 @@ import { doctor } from '../src/doctor.mjs';
 import { list } from '../src/list.mjs';
 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 { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
 import { mcpServer } from '../src/mcp-server.mjs';
@@ -48,6 +50,12 @@ ${c.bold('Commands')}
   show        Inspect one lesson in full: its complete value, scope, key, updated
               date, tags, and which store(s) it lives in (noting any divergence
               when it is in both). --json. Usage: show <scope> <key>.
+  stats       Count the applicable lessons per scope and per store (offline vs
+              remote), with per-store and grand totals, in the same Offline/
+              Remote split. --json, --scope <s>.
+  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>.
   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
@@ -66,8 +74,8 @@ ${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)
-      --scope <scope>     Restrict to a single scope (list / search)
+      --json              Machine-readable output (list / search / show / stats / diff)
+      --scope <scope>     Restrict to a single scope (list / search / stats / diff)
       --from <path>       Source store to migrate from (migrate)
       --to <tier>         Migration destination tier: home | project (migrate;
                           default routes each entry by scope)
@@ -240,6 +248,53 @@ ${c.bold('Options')}
 ${c.bold('Examples')}
   npx @lorekit/cli show global prefer-guard-clauses
   npx @lorekit/cli show project::widget build-flags --json
+`,
+  stats: `${c.bold('lorekit stats')} — count the applicable lessons per scope and per store
+
+${c.bold('Usage')}
+  npx @lorekit/cli stats [options]
+
+Shows how many lessons apply to the current directory's scopes (project/branch/
+repo/global), broken down per scope and per store (Offline = the local .lorekit/
++ ~/.lorekit/ two-tier store; Remote = the hosted MCP server), with per-store and
+grand totals. An unconfigured remote degrades to a short note, never an error.
+
+${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
+  -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 stats
+  npx @lorekit/cli stats --json
+  npx @lorekit/cli stats --scope global
+`,
+  diff: `${c.bold('lorekit diff')} — compare the offline and remote stores
+
+${c.bold('Usage')}
+  npx @lorekit/cli diff [options]
+
+Compares the local (offline) store against the hosted (remote) store for the
+current directory's scopes and reports where they diverge, grouped by scope:
+local-only keys, remote-only keys, and conflicting keys (same key, different
+value or tags). A diff needs BOTH stores readable — if the remote is
+unconfigured or a store is denied, \`diff\` prints a clear note and 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
+  -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 diff
+  npx @lorekit/cli diff --json
+  npx @lorekit/cli diff --scope global
 `,
   migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
 
@@ -300,7 +355,7 @@ const KNOWN_FLAGS = [
 // 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', 'migrate',
+  'install', 'uninstall', 'doctor', 'list', 'search', 'show', 'stats', 'diff', 'migrate',
 ]);
 
 // Command aliases — canonicalized before help / dispatch so `lorekit ls --help`
@@ -380,6 +435,10 @@ async function main() {
       return traceCommand('search', args, VERSION, () => search(args));
     case 'show':
       return traceCommand('show', args, VERSION, () => show(args));
+    case 'stats':
+      return traceCommand('stats', args, VERSION, () => stats(args));
+    case 'diff':
+      return traceCommand('diff', args, VERSION, () => diff(args));
     case 'migrate':
       return traceCommand('migrate', args, VERSION, () => migrate(args));
     default:

package/package.json

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

package/src/control.mjs

@@ -124,6 +124,19 @@ export function localStoreDirs(root = process.cwd(), env = process.env) {
   return { home, project: projectDirFrom({ env, userConfig, repoConfig, root }) };
 }
 
+// Resolve the deny-wins ceiling for the read commands: which section (offline /
+// remote) is forbidden outright by an active `deny` constraint. A deny is never
+// overridable (see the module header), so this is the single seam `list`,
+// `search`, `show`, `stats`, and `diff` share instead of each re-deriving the
+// same `control.denies.find(...)` block. Returns the matched deny object
+// ({ mode, source }) or null per side — the `source` explains the "why" in each
+// command's graceful note. Thin wrapper over `loadControl`, co-located with it.
+export function resolveDenies(root, { env = process.env } = {}) {
+  const control = loadControl(root, { env });
+  const find = (mode) => control.denies.find((d) => d.mode === mode) || null;
+  return { localDenied: find('local'), remoteDenied: find('remote') };
+}
+
 // IO wrapper — load env + config files, derive the connection, then resolve.
 export function loadControl(root, { env = process.env } = {}) {
   const home = userConfigDir(env);

package/src/diff.mjs

@@ -0,0 +1,180 @@
+// `lorekit diff` — compare the offline (local two-tier) store against the remote
+// (hosted MCP) store for the current directory's scopes, and report where they
+// diverge in three groups, grouped by scope:
+//   • local-only   — key present offline, absent remote;
+//   • remote-only   — absent offline, present remote;
+//   • conflicting   — same scope::key in both, but the value/tags differ.
+//
+// A diff is only meaningful when BOTH stores are readable. If either is
+// unavailable — the remote unconfigured, a `LOREKIT_DENY` ceiling, etc. — a diff
+// is impossible, so `diff` prints a clear note explaining which store is missing
+// and exits 0 (never a crash). 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, diffGroups, preview, shortDate } from './lessons-view.mjs';
+import { log, heading, status, c } from './util.mjs';
+
+export async function diff(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 localAvailable = !localDenied;
+  const remoteAvailable = !remoteDenied && remote.usable();
+
+  // Explain, per store, why it is not comparable (used for the not-comparable
+  // note below). A store that IS available reports `null`.
+  const offlineReason = localDenied
+    ? `disabled by deny constraint (${localDenied.source})`
+    : null;
+  const remoteReason = remoteDenied
+    ? `disabled by deny constraint (${remoteDenied.source})`
+    : remoteAvailable
+      ? null
+      : remoteUnavailableReason(connection);
+
+  const comparable = localAvailable && remoteAvailable;
+
+  // Only gather (and diff) when both stores are readable — a one-sided read
+  // cannot distinguish "only in the other store" from "the other store is
+  // simply unreachable".
+  const result = comparable ? diffGroups(await gather(local, scopes), await gather(remote, scopes)) : null;
+
+  if (args.json) {
+    log(JSON.stringify(buildJson({ root, scopes, comparable, offlineReason, remoteReason, result }), null, 2));
+  } else if (!comparable) {
+    renderNotComparable({ root, scopes, offlineReason, remoteReason });
+  } else {
+    renderDiff({ root, scopes, connection, remoteAvailable, result });
+  }
+
+  // Bounded, non-PII telemetry extras — counts + booleans, never a scope
+  // string, key, path, or token.
+  const totals = result ? result.totals : { localOnly: 0, remoteOnly: 0, conflicting: 0 };
+  return {
+    exitCode: 0,
+    'lorekit.cli.diff.scope_count': scopes.length,
+    'lorekit.cli.diff.comparable': comparable,
+    'lorekit.cli.diff.local_only': totals.localOnly,
+    'lorekit.cli.diff.remote_only': totals.remoteOnly,
+    'lorekit.cli.diff.conflicting': totals.conflicting,
+  };
+}
+
+// The not-comparable note: which store(s) are missing, and why a diff needs both.
+function renderNotComparable({ root, scopes, offlineReason, remoteReason }) {
+  heading('LoreKit diff');
+  log(`  project: ${c.dim(root)}`);
+  log(`  scopes:  ${scopes.join('  →  ')}`);
+  log('');
+  if (offlineReason) status('warn', 'offline unavailable', offlineReason);
+  if (remoteReason) status('warn', 'remote unavailable', remoteReason);
+  log(
+    `  ${c.dim('a diff compares the offline and remote stores side by side — both must be readable.')}`,
+  );
+  log('');
+}
+
+// The real diff: three grouped sections. Each section groups the divergent keys
+// by scope; a scope with nothing in a section is omitted from it.
+function renderDiff({ root, scopes, connection, remoteAvailable, result }) {
+  heading('LoreKit diff');
+  log(`  project: ${c.dim(root)}`);
+  log(`  scopes:  ${scopes.join('  →  ')}`);
+  if (remoteAvailable) log(`  remote:  ${c.dim(connection.endpoint)}`);
+
+  const { groups, totals } = result;
+
+  // Surface any per-scope read errors up front — a scope that failed to read on
+  // one side can't be diffed, and its keys are neither "only" nor "conflicting".
+  const errored = groups.filter((g) => g.error);
+  if (errored.length) {
+    heading('Unreadable scopes');
+    for (const g of errored) log(`  ${c.bold(g.scope)}  ${c.yellow('!')} ${c.dim(g.error)}`);
+  }
+
+  renderSet('Local-only', 'present offline, absent remote', groups, (g) => g.localOnly);
+  renderSet('Remote-only', 'absent offline, present remote', groups, (g) => g.remoteOnly);
+  renderConflicts(groups);
+
+  if (totals.localOnly + totals.remoteOnly + totals.conflicting === 0 && !errored.length) {
+    log('');
+    log(`  ${c.dim('the offline and remote stores are in sync for the applicable scopes')}`);
+  }
+  log('');
+}
+
+// One "only in store X" section: group its entries by scope, key + preview per
+// entry. Skipped entirely when no scope has any entry in it.
+function renderSet(title, subtitle, groups, pick) {
+  const present = groups.filter((g) => pick(g).length);
+  if (!present.length) return;
+  heading(title);
+  log(`  ${c.dim(subtitle)}`);
+  for (const g of present) {
+    log(`  ${c.bold(g.scope)}`);
+    for (const e of pick(g)) {
+      const when = e.updated ? `  ${c.dim(`(updated ${shortDate(e.updated)})`)}` : '';
+      log(`    ${c.cyan('•')} ${e.key}${when}`);
+      if (e.value) log(`      ${c.dim(preview(e.value))}`);
+    }
+  }
+}
+
+// The conflicting section: same key in both stores, differing value/tags. Shows
+// a short preview of each side so the divergence is visible at a glance.
+function renderConflicts(groups) {
+  const present = groups.filter((g) => g.conflicting.length);
+  if (!present.length) return;
+  heading('Conflicting');
+  log(`  ${c.dim('same key in both stores, but the value or tags differ')}`);
+  for (const g of present) {
+    log(`  ${c.bold(g.scope)}`);
+    for (const conflict of g.conflicting) {
+      log(`    ${c.yellow('•')} ${conflict.key}`);
+      log(`      ${c.dim('offline')} ${preview(conflict.local.value)}`);
+      log(`      ${c.dim('remote ')} ${preview(conflict.remote.value)}`);
+    }
+  }
+}
+
+// The `--json` payload. When not comparable:
+//   { root, scopes, comparable:false, offline:{available,reason}, remote:{...} }
+// When comparable:
+//   { root, scopes, comparable:true, totals, groups:[{ scope, localOnly,
+//     remoteOnly, conflicting, error }] } — the exact shape `diffGroups` returns.
+function buildJson({ root, scopes, comparable, offlineReason, remoteReason, result }) {
+  if (!comparable) {
+    return {
+      root,
+      scopes,
+      comparable: false,
+      offline: offlineReason ? { available: false, reason: offlineReason } : { available: true },
+      remote: remoteReason ? { available: false, reason: remoteReason } : { available: true },
+    };
+  }
+  return {
+    root,
+    scopes,
+    comparable: true,
+    totals: result.totals,
+    groups: result.groups,
+  };
+}

package/src/list.mjs

@@ -11,7 +11,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
 import { deriveScope } from './scope.mjs';
-import { loadControl } from './control.mjs';
+import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
 import { scopeList, gather, renderSection } from './lessons-view.mjs';
 import { log, heading, c } from './util.mjs';
@@ -49,10 +49,7 @@ export async function list(args) {
   // A `LOREKIT_DENY=remote|local` privacy/compliance ceiling (deny-wins, never
   // overridable) suppresses that section entirely — the same invariant the
   // agent-facing control model enforces, honored here in the human read view.
-  const control = loadControl(root, { env });
-  const deny = (mode) => control.denies.find((d) => d.mode === mode) || null;
-  const localDenied = deny('local');
-  const remoteDenied = deny('remote');
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
 
   const offline = localDenied ? { groups: [], total: 0 } : await gather(local, scopes);
   const remoteAvailable = !remoteDenied && remote.usable();

package/src/search.mjs

@@ -16,7 +16,7 @@
 import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
 import { deriveScope } from './scope.mjs';
-import { loadControl } from './control.mjs';
+import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
 import { scopeList, gather, filterGroups, renderSection } from './lessons-view.mjs';
 import { log, err, heading, c } from './util.mjs';
@@ -48,10 +48,7 @@ export async function search(args) {
   });
 
   // Deny-wins section suppression, identical to `list`.
-  const control = loadControl(root, { env });
-  const deny = (mode) => control.denies.find((d) => d.mode === mode) || null;
-  const localDenied = deny('local');
-  const remoteDenied = deny('remote');
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
 
   const offline = localDenied
     ? { groups: [], total: 0 }

package/src/show.mjs

@@ -11,7 +11,7 @@
 // so the bin wraps it in `traceCommand`.
 import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
-import { loadControl } from './control.mjs';
+import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
 import { normalizeEntry, shortDate, describeError, recordsDiverge } from './lessons-view.mjs';
 import { log, err, heading, status, c } from './util.mjs';
@@ -56,10 +56,7 @@ export async function show(args) {
   });
 
   // Deny-wins section suppression, identical to `list`/`search`.
-  const control = loadControl(root, { env });
-  const deny = (mode) => control.denies.find((d) => d.mode === mode) || null;
-  const localDenied = deny('local');
-  const remoteDenied = deny('remote');
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
 
   const offline = localDenied
     ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }

package/src/stats.mjs

@@ -0,0 +1,142 @@
+// `lorekit stats` — an at-a-glance overview of the lessons that apply to the
+// current directory: how many live in each scope, split per store (offline vs
+// remote), plus per-store and grand totals. Same Offline / Remote framing as
+// `list`, but counts-only — no lesson bodies.
+//
+// Graceful by design (mirrors `list`/`search`/`show`): a `LOREKIT_DENY` ceiling
+// suppresses a section, and an unconfigured remote degrades to a short note,
+// never an error (exit 0). Read-only. Human-facing, so the bin wraps it in
+// `traceCommand`.
+//
+// On cap usage: the hosted MCP surface exposes no tool that returns the user's
+// total active-memory count or their configured cap (the cap is enforced by a
+// DB trigger and read via `lorekit_get_limit`, neither reachable from a
+// `memory.*` tool call), so `stats` deliberately reports only observed counts
+// rather than guessing a `N / cap` ratio. Remote per-scope counts reflect what
+// `memory.list` returns for each scope (server-side default page size), the
+// same window `list` already shows.
+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, tallyGroups } from './lessons-view.mjs';
+import { log, heading, status, c } from './util.mjs';
+
+export async function stats(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 (an explicit
+  // scope outside the applicable set is honoured — the user asked for it).
+  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 `list`/`search`/`show`.
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  const offlineTally = localDenied ? { perScope: [], total: 0 } : tallyGroups(await gather(local, scopes));
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteTally = remoteAvailable
+    ? tallyGroups(await gather(remote, scopes))
+    : { perScope: [], total: 0 };
+
+  const offlineSection = localDenied
+    ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
+    : { available: true, ...offlineTally };
+  const remoteSection = remoteAvailable
+    ? { available: true, ...remoteTally }
+    : {
+        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 stats');
+    log(`  project: ${c.dim(root)}`);
+    log(`  scopes:  ${scopes.join('  →  ')}`);
+
+    renderStatsSection({ title: 'Offline' }, offlineSection, scopes);
+    renderStatsSection(
+      { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined },
+      remoteSection,
+      scopes,
+    );
+
+    log('');
+  }
+
+  // Bounded, non-PII telemetry extras (counts + a boolean) — never a scope
+  // string, path, key, or token.
+  return {
+    exitCode: 0,
+    'lorekit.cli.stats.scope_count': scopes.length,
+    'lorekit.cli.stats.offline_count': offlineSection.available ? offlineSection.total : 0,
+    'lorekit.cli.stats.remote_count': remoteSection.available ? remoteSection.total : 0,
+    'lorekit.cli.stats.remote_available': remoteAvailable,
+  };
+}
+
+// Render one store's count summary: an unavailable note, or a small right-
+// aligned table of `scope   count` rows plus a `total` line. Scopes with a read
+// error show the error in place of a count so a partial read is never mistaken
+// for an empty scope.
+function renderStatsSection(header, section, scopes) {
+  heading(header.title);
+  if (header.subtitle) log(`  ${c.dim(header.subtitle)}`);
+
+  if (!section.available) {
+    status('warn', 'unavailable', section.reason);
+    return;
+  }
+
+  // Index the tally by scope so every applicable scope prints a row (a scope
+  // with zero lessons still shows `0`, which is the point of an overview).
+  const byScope = new Map(section.perScope.map((s) => [s.scope, s]));
+  const width = Math.max(0, ...scopes.map((s) => s.length));
+  for (const scope of scopes) {
+    const row = byScope.get(scope) || { count: 0, error: null };
+    const label = scope.padEnd(width);
+    if (row.error) {
+      log(`  ${c.bold(label)}  ${c.yellow('!')} ${c.dim(row.error)}`);
+    } else {
+      log(`  ${c.bold(label)}  ${row.count}`);
+    }
+  }
+  log(`  ${c.dim('total'.padEnd(width))}  ${c.bold(String(section.total))}`);
+}
+
+// The `--json` payload: `{ root, scopes, offline, remote }` — each store a
+// `{ available, total, scopes: [{ scope, count, error }] }` record (or an
+// unavailable note), so a script gets the same shape regardless of which store
+// the counts came from.
+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, total: 0, scopes: [] };
+  }
+  return {
+    available: true,
+    total: section.total,
+    scopes: section.perScope.map((s) => ({ scope: s.scope, count: s.count, error: s.error })),
+  };
+}

package/src/telemetry.mjs

@@ -4,8 +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 / migrate), fired to
-// Dash0 so the maintainers can see which commands people actually run.
+// (install / uninstall / doctor / list / search / show / stats / diff /
+// 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
@@ -274,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 | migrate
+ * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | diff | 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