@lorekit/cli 1.7.1 → 1.9.0

package/README.md

@@ -106,6 +106,73 @@ lorekit doctor --deep     # also does a write → read → delete round-trip (ne
 
 Exit code is non-zero if any check fails, so it fits CI gates.
 
+### `lorekit list` (alias `ls`)
+
+Shows the lessons that apply to **where you are** — the scopes `deriveScope`
+resolves for the current directory (`project::{name}`, `branch::…`, `repo::…`,
+and `global`) — split into two clearly-labelled sections so you can see where
+each lesson lives:
+
+- **Offline** — the local two-tier store (`.lorekit/` in the repo + `~/.lorekit/`).
+- **Remote** — the hosted MCP store. When no token/endpoint is configured this
+  section is a short note on how to set it up; it is **never an error** (the
+  command still exits 0 and shows your offline lessons). A network/server error
+  is likewise a per-scope warning, not a crash.
+
+It is read-only — it never writes, deletes, or reveals archived lessons — and it
+independently queries both stores regardless of the resolved memory mode. A
+`LOREKIT_DENY=remote` (or `local`) ceiling suppresses that section, honoring the
+same deny-wins privacy invariant the control model enforces for agents.
+
+```bash
+lorekit list                 # both sections, grouped by scope
+lorekit ls                   # same, via the alias
+lorekit list --scope global  # narrow to a single scope
+lorekit list --json          # structured { offline, remote } payload for scripts
+```
+
+`--endpoint` / `--token` override the remote connection; `--store` overrides the
+local project-tier directory.
+
+### `lorekit search` (alias `grep`)
+
+Full-text search across the same applicable scopes and the same two stores as
+`list`, rendered in the same Offline / Remote split. A lesson matches when the
+query appears — **case-insensitively, as a literal substring** — in its **key or
+value**:
+
+```bash
+lorekit search sandbox            # both sections, only the matching lessons
+lorekit grep "flaky test"         # same, via the alias
+lorekit search migration --scope global
+lorekit search build --json       # { query, offline, remote } for scripts
+```
+
+The query is matched with a plain substring check, **never compiled as a regex**,
+so a term full of metacharacters (`a.*(b)`) matches those characters verbatim —
+no injection, no surprises. It is read-only, hides archived lessons, and degrades
+the remote section gracefully (an unconfigured remote is a note, not an error;
+the command still exits 0). An empty query is a usage error; no matches prints a
+friendly "no lessons match" note (exit 0). `--scope` narrows to one scope;
+`--endpoint` / `--token` / `--store` behave as in `list`.
+
+### `lorekit show`
+
+Inspect **one** lesson in full — its complete, **untruncated** value plus scope,
+key, updated date, tags, and which store(s) it lives in:
+
+```bash
+lorekit show global prefer-guard-clauses
+lorekit show project::widget build-flags --json
+```
+
+If the same `scope::key` exists in **both** the offline and remote stores —
+possibly with different values — both are shown and any divergence is flagged.
+When it lives in only one store, that copy is shown and the other is noted as
+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 hook`
 
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
@@ -288,6 +355,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) |
 | `--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 |
@@ -372,8 +441,9 @@ forever. This reduces manual validation to a single capture pass per tool.
 
 ## Usage telemetry
 
-The human-facing commands (`install`, `uninstall`, `doctor`, `migrate`) emit one
-OpenTelemetry span + one counter point per run so the maintainers can see which
+The human-facing commands (`install`, `uninstall`, `doctor`, `list`, `search`,
+`show`, `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
 flags (`--global`, `--deep`, …), the CLI/runtime/OS identity, and the outcome.

package/bin/lorekit.mjs

@@ -6,6 +6,9 @@ import { parseArgs, log, err, c } from '../src/util.mjs';
 import { install } from '../src/install.mjs';
 import { uninstall } from '../src/uninstall.mjs';
 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 { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
 import { mcpServer } from '../src/mcp-server.mjs';
@@ -35,6 +38,16 @@ ${c.bold('Commands')}
               other servers, hooks, and settings are left untouched. Prompts
               project vs global; --project / --global choose non-interactively.
   doctor      Verify the skill install, MCP connectivity, token, and scope.
+  list (ls)   List the lessons that apply to the current directory, split into
+              an Offline section (local .lorekit/ + ~/.lorekit/) and a Remote
+              section (hosted MCP). Groups by scope (project/branch/repo/global).
+              --json for scripting, --scope <s> to narrow.
+  search      Full-text search the applicable lessons across both stores and all
+    (grep)    scopes (case-insensitive, literal substring over key + value),
+              rendered in the same Offline/Remote split. --json, --scope <s>.
+  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>.
   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
@@ -53,6 +66,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)
       --from <path>       Source store to migrate from (migrate)
       --to <tier>         Migration destination tier: home | project (migrate;
                           default routes each entry by scope)
@@ -156,6 +171,75 @@ ${c.bold('Examples')}
   npx @lorekit/cli doctor
   npx @lorekit/cli doctor --deep
   npx @lorekit/cli doctor --mode local
+`,
+  list: `${c.bold('lorekit list')} — list the lessons that apply to the current directory ${c.dim('(alias: ls)')}
+
+${c.bold('Usage')}
+  npx @lorekit/cli list [options]
+
+Shows the lessons for the scopes that resolve for the current directory
+(project/branch/repo/global), split into an Offline section (the local
+.lorekit/ + ~/.lorekit/ two-tier store) and a Remote section (the hosted MCP
+server). When no remote token/endpoint is configured the Remote section is a
+short note on how to set it up — 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 list
+  npx @lorekit/cli list --json
+  npx @lorekit/cli list --scope global
+`,
+  search: `${c.bold('lorekit search')} — full-text search the applicable lessons ${c.dim('(alias: grep)')}
+
+${c.bold('Usage')}
+  npx @lorekit/cli search <query> [options]
+
+Searches every lesson for the current directory's scopes (project/branch/repo/
+global) across both stores, matching the query case-insensitively as a LITERAL
+substring of a lesson's key or value (regex metacharacters are matched verbatim,
+never interpreted). Results are shown in the same Offline / Remote split as
+\`list\`; 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 search sandbox
+  npx @lorekit/cli grep "flaky test" --json
+  npx @lorekit/cli search migration --scope global
+`,
+  show: `${c.bold('lorekit show')} — inspect one lesson in full
+
+${c.bold('Usage')}
+  npx @lorekit/cli show <scope> <key> [options]
+
+Prints one lesson's complete (untruncated) value, scope, key, updated date, tags,
+and which store(s) it lives in. If the same scope::key exists in both the offline
+and remote stores, both are shown and any divergence in their values is flagged.
+Exits non-zero when the key is found in neither readable store.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --json              Machine-readable output (the full normalized record(s))
+  -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 show global prefer-guard-clauses
+  npx @lorekit/cli show project::widget build-flags --json
 `,
   migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
 
@@ -209,13 +293,19 @@ ${c.bold('Options')}
 const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
   'from', 'to', 'apply', 'yes', 'no-hooks', 'force', 'deep', 'adapter',
-  'event', 'help', 'version',
+  'event', 'json', 'scope', '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', 'migrate']);
+const HUMAN_COMMANDS = new Set([
+  'install', 'uninstall', 'doctor', 'list', 'search', 'show', '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' };
 
 async function main() {
   // Load a `.env` from the current directory (if any) before anything reads the
@@ -227,11 +317,11 @@ async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
-    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'json'],
     known: KNOWN_FLAGS,
   });
 
-  const command = args._[0];
+  const command = COMMAND_ALIASES[args._[0]] || args._[0];
 
   // Help is intercepted first — before the machine-facing hook/mcp dispatch — so
   // `lorekit <command> --help` always documents the command (even hook/mcp)
@@ -284,6 +374,12 @@ async function main() {
       return traceCommand('uninstall', args, VERSION, () => uninstall(args));
     case 'doctor':
       return traceCommand('doctor', args, VERSION, () => doctor(args));
+    case 'list':
+      return traceCommand('list', args, VERSION, () => list(args));
+    case 'search':
+      return traceCommand('search', args, VERSION, () => search(args));
+    case 'show':
+      return traceCommand('show', args, VERSION, () => show(args));
     case 'migrate':
       return traceCommand('migrate', args, VERSION, () => migrate(args));
     default:

package/package.json

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

package/src/list.mjs

@@ -0,0 +1,123 @@
+// `lorekit list` — show the lessons that apply to the current directory, split
+// into an Offline section (the local two-tier store) and a Remote section (the
+// hosted MCP store). Scopes searched are the ones `deriveScope` resolves for the
+// cwd: project, branch, repo, and global.
+//
+// Graceful by design: when no remote token/endpoint is configured the Remote
+// section is a short note on how to set it up — never an error (mirrors
+// `doctor`'s tone). Human-facing, so it is wrapped in `traceCommand` by the bin.
+import os from 'node:os';
+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 { resolveStores, remoteUnavailableReason } from './stores.mjs';
+import { scopeList, gather, renderSection } from './lessons-view.mjs';
+import { log, heading, c } from './util.mjs';
+
+// Abbreviate the user's home directory to `~` for readable paths.
+function prettyPath(p) {
+  const home = os.homedir();
+  return p && home && p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+
+// A human label for where the offline store reads from.
+function offlineSubtitle(local, root) {
+  const home = prettyPath(local.homeDir);
+  if (!local.projectActive()) return `${home} (home tier only — no project .lorekit/ yet)`;
+  const projRel = path.relative(root, local.projectDir) || local.projectDir;
+  return `${projRel} + ${home}`;
+}
+
+export async function list(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,
+  });
+
+  // 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 offline = localDenied ? { groups: [], total: 0 } : await gather(local, scopes);
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteResult = remoteAvailable ? await gather(remote, scopes) : { groups: [], total: 0 };
+
+  const offlineSection = localDenied
+    ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
+    : { available: true, ...offline };
+  const remoteSection = remoteAvailable
+    ? { available: true, ...remoteResult }
+    : {
+        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 lessons');
+    log(`  project: ${c.dim(root)}`);
+    log(`  scopes:  ${scopes.join('  →  ')}`);
+
+    renderSection(
+      { title: 'Offline', subtitle: localDenied ? undefined : offlineSubtitle(local, root) },
+      offlineSection,
+    );
+    renderSection(
+      { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined },
+      remoteSection,
+    );
+
+    log('');
+  }
+
+  // Bounded, non-PII telemetry extras (counts + a boolean) — never a scope
+  // string, path, key, or token.
+  return {
+    exitCode: 0,
+    'lorekit.cli.list.scope_count': scopes.length,
+    'lorekit.cli.list.offline_count': offline.total,
+    'lorekit.cli.list.remote_count': remoteResult.total,
+    'lorekit.cli.list.remote_available': remoteAvailable,
+  };
+}
+
+// The `--json` payload: normalized groups per section so a script gets the same
+// shape regardless of which store an entry 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, groups: [] };
+  }
+  return {
+    available: true,
+    total: section.total,
+    groups: (section.groups || []).map((g) => ({
+      scope: g.scope,
+      error: g.error || null,
+      // `gather()` already normalized these entries; no second pass needed.
+      entries: g.entries,
+    })),
+  };
+}

package/src/search.mjs

@@ -0,0 +1,132 @@
+// `lorekit search <query>` — full-text search the lessons that apply to the
+// current directory, across BOTH stores and every applicable scope, rendered in
+// the same Offline / Remote split as `list`. A lesson matches when the query
+// appears (case-insensitively, as a LITERAL substring) in its key or value.
+//
+// Why filter `gather()` rather than call each store's `search()`: the two stores
+// disagree on search semantics — the local store does a literal substring match,
+// the remote store delegates to server-side FTS (ranking, stemming). To give one
+// deterministic, spec-defined behaviour across both — and to guarantee a query
+// full of regex metacharacters is matched verbatim — the match runs here, over
+// the exact same `gather()` seam `list` uses, via the pure `matchesQuery` filter.
+//
+// Graceful by design (mirrors `list`): an unconfigured remote is a short note,
+// never an error; a per-scope read failure is a warning, not a crash. Read-only,
+// archived hidden. 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 { loadControl } 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';
+
+export async function search(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  // The query is the first positional after the command name. An empty/missing
+  // query is a usage error (non-zero exit) — searching for nothing is meaningless
+  // and would otherwise degrade to `list`.
+  const query = typeof args._[1] === 'string' ? args._[1] : '';
+  if (!query.trim()) {
+    err(`${c.red('Usage:')} lorekit search <query> [--scope <s>] [--json]`);
+    err(`Provide a search term. Run ${c.cyan('lorekit search --help')} for options.`);
+    return 1;
+  }
+
+  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`.
+  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 offline = localDenied
+    ? { groups: [], total: 0 }
+    : filterGroups(await gather(local, scopes), query);
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteResult = remoteAvailable
+    ? filterGroups(await gather(remote, scopes), query)
+    : { groups: [], total: 0 };
+
+  const offlineSection = localDenied
+    ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
+    : { available: true, ...offline };
+  const remoteSection = remoteAvailable
+    ? { available: true, ...remoteResult }
+    : {
+        available: false,
+        reason: remoteDenied
+          ? `disabled by deny constraint (${remoteDenied.source})`
+          : remoteUnavailableReason(connection),
+      };
+
+  if (args.json) {
+    log(JSON.stringify(buildJson({ root, query, scopes, offlineSection, remoteSection }), null, 2));
+  } else {
+    heading('LoreKit search');
+    log(`  query:   ${c.dim(query)}`);
+    log(`  scopes:  ${scopes.join('  →  ')}`);
+
+    const empty = 'no lessons match';
+    renderSection({ title: 'Offline', empty }, offlineSection);
+    renderSection(
+      { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined, empty },
+      remoteSection,
+    );
+
+    log('');
+  }
+
+  // Bounded, non-PII telemetry extras — counts + a boolean, never the query, a
+  // scope string, key, path, or token.
+  return {
+    exitCode: 0,
+    'lorekit.cli.search.scope_count': scopes.length,
+    'lorekit.cli.search.offline_matches': offline.total,
+    'lorekit.cli.search.remote_matches': remoteResult.total,
+    'lorekit.cli.search.remote_available': remoteAvailable,
+  };
+}
+
+// The `--json` payload: `{ query, root, scopes, offline, remote }` — normalized
+// per-scope groups per section so a script gets the same shape regardless of
+// which store a match came from (the exact shape `list --json` emits, plus the
+// query echoed back).
+function buildJson({ root, query, scopes, offlineSection, remoteSection }) {
+  return {
+    query,
+    root,
+    scopes,
+    offline: sectionJson(offlineSection),
+    remote: sectionJson(remoteSection),
+  };
+}
+
+function sectionJson(section) {
+  if (!section.available) {
+    return { available: false, reason: section.reason, total: 0, groups: [] };
+  }
+  return {
+    available: true,
+    total: section.total,
+    groups: (section.groups || []).map((g) => ({
+      scope: g.scope,
+      error: g.error || null,
+      // `gather()` already normalized these entries; the filter preserved them.
+      entries: g.entries,
+    })),
+  };
+}

package/src/show.mjs

@@ -0,0 +1,167 @@
+// `lorekit show <scope> <key>` — inspect ONE lesson in full: its complete
+// (untruncated) value, scope, key, updated timestamp, tags, and which store(s)
+// it lives in. When the same scope::key exists in BOTH the offline and remote
+// stores — possibly with different values — both are shown and the divergence is
+// flagged.
+//
+// Uses each store's real `read({scope, key})` method (both stores expose it),
+// not a filtered `list` — a single-record lookup is what `read` is for, and it
+// already hides archived entries. Graceful by design (mirrors `list`/`search`):
+// an unconfigured remote is a short note, never an error. Read-only. Human-facing,
+// so the bin wraps it in `traceCommand`.
+import process from 'node:process';
+import { resolveProjectRoot } from './config.mjs';
+import { loadControl } 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';
+
+// Read one scope::key from a store, normalizing the result into a small,
+// uniform shape: { available:true, found, record } on success, or
+// { available:true, found:false, error } when the read itself failed (network /
+// server). A per-store read failure is captured, never thrown, so one bad store
+// never aborts the other section.
+async function readOne(store, scope, key) {
+  let res;
+  try {
+    res = await store.read({ scope, key });
+  } catch (e) {
+    return { available: true, found: false, record: null, error: (e && e.message) || 'error' };
+  }
+  if (!res || res.ok === false) {
+    return { available: true, found: false, record: null, error: describeError(res) };
+  }
+  const record = res.entry ? normalizeEntry(res.entry) : null;
+  return { available: true, found: Boolean(record), record, error: null };
+}
+
+export async function show(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  // Both positionals are required: `show <scope> <key>`.
+  const scope = typeof args._[1] === 'string' ? args._[1] : '';
+  const key = typeof args._[2] === 'string' ? args._[2] : '';
+  if (!scope || !key) {
+    err(`${c.red('Usage:')} lorekit show <scope> <key> [--json]`);
+    err(`Both a scope and a key are required. Run ${c.cyan('lorekit show --help')} for options.`);
+    return 1;
+  }
+
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+
+  // 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 offline = localDenied
+    ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
+    : await readOne(local, scope, key);
+
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remote_ = remoteDenied
+    ? { available: false, reason: `disabled by deny constraint (${remoteDenied.source})` }
+    : remoteAvailable
+      ? await readOne(remote, scope, key)
+      : { available: false, reason: remoteUnavailableReason(connection) };
+
+  const foundOffline = Boolean(offline.available && offline.found);
+  const foundRemote = Boolean(remote_.available && remote_.found);
+  const diverged = foundOffline && foundRemote && recordsDiverge(offline.record, remote_.record);
+  // "Not found" is only definitive across the stores we could actually consult.
+  const found = foundOffline || foundRemote;
+
+  if (args.json) {
+    log(JSON.stringify(buildJson({ scope, key, offline, remote_, diverged }), null, 2));
+  } else {
+    heading('LoreKit lesson');
+    log(`  scope:  ${c.dim(scope)}`);
+    log(`  key:    ${c.dim(key)}`);
+
+    renderRecordSection('Offline', offline);
+    renderRecordSection(
+      'Remote',
+      remote_,
+      remoteAvailable ? connection.endpoint : undefined,
+    );
+
+    if (diverged) {
+      log('');
+      status('warn', 'divergence', 'the offline and remote values differ');
+    }
+    if (!found) {
+      log('');
+      log(`  ${c.dim(`no lesson found for ${scope}::${key} in the readable store(s)`)}`);
+    }
+    log('');
+  }
+
+  // Bounded, non-PII telemetry — booleans only, never the scope string or key.
+  return {
+    exitCode: found ? 0 : 1,
+    'lorekit.cli.show.found_offline': foundOffline,
+    'lorekit.cli.show.found_remote': foundRemote,
+    'lorekit.cli.show.diverged': diverged,
+  };
+}
+
+// Render one store's slot: an unavailable note, a "no such key here" line, or the
+// full record (untruncated value).
+function renderRecordSection(title, section, subtitle) {
+  heading(title);
+  if (subtitle) log(`  ${c.dim(subtitle)}`);
+
+  if (!section.available) {
+    status('warn', 'unavailable', section.reason);
+    return;
+  }
+  if (section.error) {
+    status('warn', 'unreadable', section.error);
+    return;
+  }
+  if (!section.found) {
+    log(`  ${c.dim('no such key in this store')}`);
+    return;
+  }
+
+  const e = section.record;
+  if (e.updated) log(`  ${c.dim('updated')} ${shortDate(e.updated)}`);
+  if (e.tags && e.tags.length) log(`  ${c.dim('tags')}    ${e.tags.join(', ')}`);
+  log(`  ${c.dim('value')}`);
+  // The full, untruncated body — indented, line by line, so multi-line lessons
+  // read as written.
+  for (const line of String(e.value ?? '').split('\n')) {
+    log(`    ${line}`);
+  }
+}
+
+// The `--json` payload: the full normalized record(s) plus which store each came
+// from and whether they diverge.
+function buildJson({ scope, key, offline, remote_, diverged }) {
+  return {
+    scope,
+    key,
+    offline: recordJson(offline),
+    remote: recordJson(remote_),
+    diverged,
+  };
+}
+
+function recordJson(section) {
+  if (!section.available) {
+    return { available: false, reason: section.reason, found: false, record: null };
+  }
+  return {
+    available: true,
+    found: Boolean(section.found),
+    record: section.record || null,
+    ...(section.error ? { error: section.error } : {}),
+  };
+}

package/src/stores.mjs

@@ -0,0 +1,49 @@
+// Resolve BOTH memory stores at once — the offline (local two-tier) store and
+// the remote (hosted MCP) store — independent of the active control mode. The
+// read commands (`list`, and the stacked `search` / `show` / `stats` / `diff`)
+// want to show whatever lives in each place side by side, so unlike
+// `createStore(control)` (which picks exactly one by mode) this builds both.
+//
+// Nothing here invents scope or connection logic: it composes the existing
+// `localStoreDirs` (two-tier dirs), `resolveProjectConnection` + `splitEndpoint`
+// (endpoint/token from .mcp.json → global → env), and the store builders.
+// Zero-dependency.
+import process from 'node:process';
+import { localStoreDirs } from './control.mjs';
+import { resolveProjectConnection } from './config.mjs';
+import { splitEndpoint } from './mcp.mjs';
+import { createTwoTierStore, createRemoteStore } from './store/index.mjs';
+
+// Build both stores for `root`. Explicit `endpoint` / `token` (e.g. from
+// `--endpoint` / `--token` flags) take precedence over the resolved connection;
+// `env` feeds the local-tier directory resolution ($LOREKIT_HOME / $LOREKIT_STORE).
+// Returns { local, remote, connection } — `connection` is the resolved
+// endpoint/token so callers can explain why remote is unusable.
+export function resolveStores(root, { env = process.env, endpoint = null, token = null } = {}) {
+  const dirs = localStoreDirs(root, env);
+  const local = createTwoTierStore(dirs);
+
+  const conn = resolveProjectConnection(root, splitEndpoint);
+  const resolvedEndpoint = endpoint || conn.endpoint || null;
+  const resolvedToken = token || conn.token || null;
+  const remote = createRemoteStore({ endpoint: resolvedEndpoint, token: resolvedToken });
+
+  return {
+    local,
+    remote,
+    connection: { endpoint: resolvedEndpoint, token: resolvedToken },
+  };
+}
+
+// A bounded, actionable reason a remote listing is unavailable — mirrors the
+// checks in `RemoteStore.usable()` so the note tells the user what to fix.
+export function remoteUnavailableReason({ endpoint, token } = {}) {
+  if (!endpoint) return 'no endpoint configured — run `lorekit install` or set LOREKIT_MCP_URL';
+  if (String(endpoint).includes('<project-ref>')) return `endpoint is still a placeholder (${endpoint})`;
+  if (!token) return 'no token configured — set LOREKIT_TOKEN or run `lorekit install`';
+  // Defensive catch-all: unreachable while this mirrors `RemoteStore.usable()` —
+  // callers only reach here when the remote is unusable, so one check above has
+  // already fired. Kept as a total return (never a throw): this helper is on the
+  // graceful read path and must never break the listing.
+  return 'not configured';
+}

package/src/telemetry.mjs

@@ -4,8 +4,8 @@
 // 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 / doctor / migrate), fired to Dash0 so the maintainers can see
-// which commands people actually run.
+// (install / uninstall / doctor / list / search / show / 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
@@ -34,7 +34,7 @@ const DEFAULT_DATASET = 'lorekit-cli';
 
 // Flags worth counting (e.g. how many installs are --global). Bounded on
 // purpose: only these booleans are ever attached, never free-form values.
-const FLAG_ATTRS = ['global', 'project', 'deep', 'yes', 'force', 'no-hooks'];
+const FLAG_ATTRS = ['global', 'project', 'deep', 'yes', 'force', 'no-hooks', 'json'];
 
 const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disable', 'disabled']);
 
@@ -274,7 +274,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 | doctor | migrate
+ * @param {string} command  bounded: install | uninstall | doctor | list | search | show | 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