@lorekit/cli 1.67.0 → 1.69.0

package/src/commands/show.mjs

@@ -14,6 +14,12 @@
 //                            split (the shorthand already carries a namespaced
 //                            key, since the split lands at the first valid-scope
 //                            prefix — see `resolveScopeArg`)
+//   show <s1::k1> <s2::k2> [...]
+//                          — multi-ref form: two or more positionals that EACH
+//                            parse as a complete `<scope>::<key>` reference (see
+//                            `isMultiRefForm` below). Batches through each
+//                            store's `readMany`, one round-trip to the remote
+//                            store rather than one request per ref.
 //
 // 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
@@ -29,9 +35,12 @@ import {
   shortDate,
   describeError,
   recordsDiverge,
+  resolveScopeArg,
   resolveScopeKeyArgs,
+  isScopeString,
   scopeIssue,
 } from '../shared/lessons-view.mjs';
+import { SCOPE_PRECEDENCE } from '../shared/scope-precedence.mjs';
 import { resolveAppBase } from '../shared/deeplink-pure.mjs';
 import { emitLink } from './link.mjs';
 import { log, err, heading, status, c } from '../shared/util.mjs';
@@ -55,6 +64,193 @@ async function readOne(store, scope, key) {
   return { available: true, found: Boolean(record), record, error: null };
 }
 
+// Is this a multi-ref invocation? Two or more positionals, no `--scope`/`--key`
+// override (a flag is an explicit single-ref assertion — see
+// `resolveScopeKeyArgs`), and EVERY positional parses as a complete
+// `<scope>::<key>` reference via `resolveScopeArg`.
+//
+// This is what keeps the existing `show <scope> <key>` two-positional form
+// unambiguous: its first positional is a BARE scope with no `::`, so
+// `resolveScopeArg` reports it with a null key and the predicate below is
+// false — the single-ref path runs unchanged, exactly as `show <scope::key>`
+// (one positional) always has.
+function isMultiRefForm(positionals, args) {
+  if (positionals.length < 2 || args.scope || args.key) return false;
+  return positionals.every((p) => resolveScopeArg(p, isScopeString).key !== null);
+}
+
+// Batch-read `refs` ({scope,key}[]) from one store via its `readMany`, and
+// project the result back into ONE `{available, found, record, error}` slot
+// per ref, in the SAME order the refs were given — mirroring what `readOne`
+// answers for a single ref, so the per-ref renderer and `--json` builder don't
+// need to know whether they are looking at a single read or a batch one.
+//
+// A transport-level failure (throw, or `{ ok:false }`) degrades EVERY ref in
+// the batch to the same error note, exactly as a per-store outage would if
+// each ref were read one at a time — a batch call doesn't get to fail more
+// silently than the single-ref path it replaces.
+async function readManyFrom(store, refs) {
+  let res;
+  try {
+    res = await store.readMany(refs);
+  } catch (e) {
+    const msg = (e && e.message) || 'error';
+    return refs.map(() => ({ available: true, found: false, record: null, error: msg }));
+  }
+  if (!res || res.ok === false) {
+    const msg = describeError(res);
+    return refs.map(() => ({ available: true, found: false, record: null, error: msg }));
+  }
+  return projectBatchResult(refs, res);
+}
+
+/**
+ * The line printed under a ref no store returned a record for — `null` when the
+ * ref WAS found, since the caller only asks about unresolved ones. Pure and
+ * exported so the three answers below are unit-testable.
+ *
+ * Three answers, not two. A slot carrying an `error` NEVER LOOKED — either the
+ * store dropped the ref (`REF_DROPPED_ERROR`) or the read itself failed — so
+ * its silence is not a "not found", and lumping it in with a store that did
+ * look states as absent something nobody checked. The mixed case is the whole
+ * reason this is not a boolean: the local store answers every ref it is given
+ * and never truncates, so past the remote's 32-ref cap the offline store says
+ * "no" while the remote never looked, and only naming both halves is accurate.
+ */
+export function unresolvedReason(ref, slots) {
+  const readable = slots.filter((s) => s.available);
+  const dropped = readable.filter((s) => Boolean(s.error));
+  const answered = readable.length - dropped.length;
+  if (answered === 0) return `no store looked up ${ref} — it may exist`;
+  if (dropped.length > 0) {
+    return `${ref} not found in the store(s) that looked; ${dropped.length} did not look — it may exist there`;
+  }
+  return `no memory found for ${ref} in the readable store(s)`;
+}
+
+/** The message a ref the store never looked up carries. Exported for the spec. */
+export const REF_DROPPED_ERROR =
+  'not looked up — the store dropped this reference (past the 32-reference cap, or a scope it does not accept)';
+
+/**
+ * Project a `readMany` result back onto the requested refs, in request order.
+ * Pure — no store, no IO — so the three outcomes below are unit-testable
+ * without a mock REST server (see CLAUDE.md on the loopback-HTTP flakiness).
+ *
+ * A ref the store ANSWERED is in exactly one of `entries` or `missing`. One in
+ * NEITHER was never looked up: the remote store drops refs past the 32-reference
+ * cap and refs whose scope its stricter grammar rejects, and neither loss
+ * reaches `missing`, which is a not-found list by design. Reporting those as
+ * `found: false` would print "no such key in this store" for a lesson that may
+ * well be there, so they carry an explicit error instead. The local store
+ * answers every ref it is given, so that branch is unreachable for it by
+ * construction rather than by a transport check.
+ */
+export function projectBatchResult(refs, res) {
+  const byRef = new Map();
+  for (const entry of res.entries || []) {
+    const record = normalizeEntry(entry);
+    byRef.set(`${record.scope}::${record.key}`, record);
+  }
+  const answered = new Set(res.missing || []);
+  return refs.map(({ scope, key }) => {
+    const ref = `${scope}::${key}`;
+    const record = byRef.get(ref) || null;
+    if (!record && !answered.has(ref)) {
+      return { available: true, found: false, record: null, error: REF_DROPPED_ERROR };
+    }
+    return { available: true, found: Boolean(record), record, error: null };
+  });
+}
+
+// The multi-ref path: resolve every ref against both stores (one `readMany`
+// round-trip per store, not one per ref) and report each in request order.
+async function showRefs(refs, args, root, env) {
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  const offlineList = localDenied
+    ? refs.map(() => ({ available: false, reason: `disabled by deny constraint (${localDenied.source})` }))
+    : await readManyFrom(local, refs);
+
+  const remoteAvailable = !remoteDenied && remote.usable();
+  const remoteList = remoteDenied
+    ? refs.map(() => ({ available: false, reason: `disabled by deny constraint (${remoteDenied.source})` }))
+    : remoteAvailable
+      ? await readManyFrom(remote, refs)
+      : refs.map(() => ({ available: false, reason: remoteUnavailableReason(connection) }));
+
+  const results = refs.map(({ scope, key }, i) => {
+    const offline = offlineList[i];
+    const remote_ = remoteList[i];
+    const foundOffline = Boolean(offline.available && offline.found);
+    const foundRemote = Boolean(remote_.available && remote_.found);
+    const diverged = foundOffline && foundRemote && recordsDiverge(offline.record, remote_.record);
+    const found = foundOffline || foundRemote;
+    // Which stores actually looked decides what a "not found" may claim.
+    const unresolved = found ? null : unresolvedReason(`${scope}::${key}`, [offline, remote_]);
+    const dropped = [offline, remote_].some((s) => s.available && Boolean(s.error));
+    return { scope, key, offline, remote_, foundOffline, foundRemote, diverged, found, unresolved, dropped };
+  });
+
+  if (args.json) {
+    log(JSON.stringify({
+      results: results.map((r) => buildJson({
+        scope: r.scope, key: r.key, offline: r.offline, remote_: r.remote_, diverged: r.diverged,
+      })),
+    }, null, 2));
+  } else {
+    heading('LoreKit memory');
+    log(`  ${c.dim(`${results.length} references`)}`);
+    for (const r of results) {
+      log('');
+      log(`  ${c.cyan(`${r.scope}::${r.key}`)}`);
+      renderRecordSection('Offline', r.offline);
+      renderRecordSection('Remote', r.remote_, remoteAvailable ? connection.endpoint : undefined);
+      if (r.diverged) status('warn', 'divergence', 'the offline and remote values differ');
+      // "not found" and "nobody looked" are different answers: say which.
+      if (r.unresolved) log(`    ${c.dim(r.unresolved)}`);
+    }
+    log('');
+  }
+
+  const foundCount = results.filter((r) => r.found).length;
+  // Bounded, non-PII telemetry — counts only, never a scope or key string.
+  return {
+    exitCode: foundCount === results.length ? 0 : 1,
+    'lorekit.cli.show.ref_count': results.length,
+    'lorekit.cli.show.found_count': foundCount,
+    'lorekit.cli.show.diverged_count': results.filter((r) => r.diverged).length,
+    // Refs at least one readable store never looked up — the batch hit the
+    // 32-ref cap, met a scope that store's grammar rejects, or the store
+    // errored. Without it a truncated batch is indistinguishable from a
+    // genuinely empty one: both report `found_count` below `ref_count`.
+    'lorekit.cli.show.dropped_count': results.filter((r) => r.dropped).length,
+  };
+}
+
+/**
+ * Was this argument MEANT as a scope, even though it is not a valid one?
+ *
+ * The discriminator is the segment before the first `:` — if it is one of the
+ * four scope types, the caller was reaching for scope syntax and got it wrong
+ * (`global::`, `repo:noslash`, `branch::o/r`), and naming the scope is more
+ * useful than silently looking up a lesson keyed on that exact string.
+ *
+ * The case this must NOT catch is the reason the unscoped read exists:
+ * `pre-exec-lessons::automation-network-no-cli-blocks-everything` is a KEY that
+ * happens to contain `::`. Its first segment is not a scope type, so it reads
+ * as the key it is. A test for "does it contain `::`" would get that backwards.
+ */
+function looksLikeScopeAttempt(token) {
+  const head = String(token).split(':')[0].toLowerCase();
+  return SCOPE_PRECEDENCE.includes(head);
+}
+
 export async function show(args) {
   const root = resolveProjectRoot(args.dir);
   const env = { ...process.env };
@@ -67,10 +263,42 @@ export async function show(args) {
   //                                  the `::` split (the shorthand handles a
   //                                  namespaced key on its own now)
   const positionals = args._.slice(1);
-  const { scope, key, consumed } = resolveScopeKeyArgs(positionals, {
+
+  if (isMultiRefForm(positionals, args)) {
+    const refs = positionals.map((p) => resolveScopeArg(p, isScopeString));
+    return showRefs(refs, args, root, env);
+  }
+
+  let { scope, key, consumed } = resolveScopeKeyArgs(positionals, {
     scope: args.scope,
     key: args.key,
   });
+  // A LONE positional that is neither a valid scope nor an ATTEMPT at one is a
+  // KEY, not a malformed scope.
+  //
+  // `resolveScopeKeyArgs` reports an unparseable first positional as the scope
+  // (with a null key) so its callers can name it as the malformed scope it is —
+  // right for `write`, which cannot proceed without knowing where to put the
+  // lesson. `show` can: a key alone resolves across every scope. So
+  // `lorekit show my-key` is a key-only lookup rather than "invalid scope
+  // my-key", which is what it used to say.
+  //
+  // Reinterpreted HERE rather than inside the shared parser: `write` and `link`
+  // must keep the strict reading, and the difference is about what each command
+  // can DO without a scope, not about how the arguments are spelled.
+  //
+  // Three things switch it off, each because the argument was plainly meant as
+  // a scope and a silent re-read would bury the user's actual mistake:
+  //   - an explicit `--scope` (a flag is an assertion, so a bad one is an error)
+  //   - MORE THAN ONE positional (`show foo bar` is the `<scope> <key>` form —
+  //     `foo` is a scope that failed to parse, not a key with a stray argument)
+  //   - a token that LOOKS like a scope attempt (`global::`, `repo:noslash`) —
+  //     see `looksLikeScopeAttempt`.
+  if (!key && scope && !args.scope && positionals.length === 1
+      && !isScopeString(scope) && !looksLikeScopeAttempt(scope)) {
+    key = scope;
+    scope = '';
+  }
   // Scope validity is checked FIRST, for the same reason as in `write`: a bad
   // scope is the root cause, and "a key is required" is downstream noise.
   const badScope = scope ? scopeIssue(scope) : null;
@@ -80,10 +308,11 @@ export async function show(args) {
     err(`Run ${c.cyan('lorekit show --help')} for options.`);
     return 1;
   }
-  if (!scope || !key) {
+  if (!key) {
     err(`${c.red('Usage:')} lorekit show <scope::key> [--json]`);
     err(`       lorekit show <scope> <key> [--json]`);
-    err(`Both a scope and a key are required. Run ${c.cyan('lorekit show --help')} for options.`);
+    err(`       lorekit show <key> [--json]        (searches every scope)`);
+    err(`A key is required. Run ${c.cyan('lorekit show --help')} for options.`);
     return 1;
   }
   // `show` consumes every positional it is given — unlike `write`, it has no
@@ -96,6 +325,18 @@ export async function show(args) {
     return 1;
   }
 
+  // `--link` is the one form that still needs a scope up front. It deliberately
+  // touches no store, and the deep link it prints is `?scope=…&lesson=…` — so
+  // without a scope there is nothing to resolve the key against and the URL
+  // would open the dashboard on an empty scope. Say so rather than emitting a
+  // link that goes nowhere.
+  if (args.link && !scope) {
+    err(`${c.red('Error:')} --link needs a scope — it builds a URL without reading any store.`);
+    err(`Pass ${c.cyan('lorekit show <scope>::' + key + ' --link')} or add ${c.cyan('--scope <s>')}.`);
+    err(`Run ${c.cyan('lorekit show ' + key)} to find which scope holds it.`);
+    return 1;
+  }
+
   // `--link` short-circuits: print the deep link that opens THIS lesson's detail
   // sheet (`?scope=…&lesson=…`) for the current args, without touching a store.
   if (args.link) {

package/src/shared/candidates-pure.mjs

@@ -44,6 +44,89 @@ export function parseMetaComment(value) {
   return out;
 }
 
+const STATUS_TAG_PREFIX = 'status::';
+
+/**
+ * A member's declared status. The canonical home is a `status::<value>` tag —
+ * first-class, filterable, and visible to a human reading the lesson — which is
+ * what the lorekit-setup skill now prescribes. A legacy `<!-- meta: status=… -->`
+ * comment in the body is still honoured so lessons written under the older
+ * convention keep their signal; the tag wins when both are present. Returns `''`
+ * when neither declares one.
+ */
+export function statusOf(member) {
+  const tags = Array.isArray(member?.tags) ? member.tags : [];
+  for (const t of tags) {
+    if (typeof t === 'string' && t.startsWith(STATUS_TAG_PREFIX)) {
+      const v = t.slice(STATUS_TAG_PREFIX.length).trim();
+      if (v) return v;
+    }
+  }
+  const fromMeta = parseMetaComment(member?.value).status;
+  return typeof fromMeta === 'string' ? fromMeta.trim() : '';
+}
+
+// Is this line a bold LABEL, and which one? Returns `{ name, rest }` or null.
+//
+// Deliberately a line test rather than another alternative in a lookahead. Four
+// separate defects in this function were one paragraph-terminating lookahead
+// failing a different way each time — truncating at the first newline, then at
+// any bold token, then failing to stop at a label whose colon sits OUTSIDE the
+// bold (`**Why**:` rather than `**Why:**`). Each fix narrowed the failure
+// without ending the class, because "where does this paragraph stop" is a
+// line-level question and a single pattern answering it has to encode every
+// spelling at once. Asked per line it is four lines of obvious code, and a new
+// spelling is a new case here rather than a new branch inside a lookahead.
+//
+// A label carries a colon; bold alone does not. `**foo()** in the parser.` is
+// prose continuing the paragraph, `**Why:**` and `**Why**:` both end it.
+const BOLD_LEAD_RE = /^[ \t]*\*\*([^\n*]+?)\*\*[ \t]*(:?)[ \t]*/;
+
+function boldLabel(line) {
+  const m = BOLD_LEAD_RE.exec(line);
+  if (!m) return null;
+  const [matched, inner, trailingColon] = m;
+  const innerColon = inner.endsWith(':');
+  if (trailingColon !== ':' && !innerColon) return null;
+  return {
+    name: (innerColon ? inner.slice(0, -1) : inner).trim().toLowerCase(),
+    rest: line.slice(matched.length),
+  };
+}
+
+/**
+ * A member's applicability signal, printed verbatim and never interpreted. The
+ * canonical home is the visible `**Applies when:**` paragraph the lorekit-setup
+ * skill prescribes; a legacy `trigger-context` meta field is the fallback.
+ * Returns `''` when the lesson declares neither.
+ *
+ * Internal newlines are collapsed to single spaces — the only transformation,
+ * and a presentational one: the caller prints this as one field on one line, so
+ * a wrapped source paragraph must re-flow rather than break the record. No word
+ * is added, removed, or reordered, which is the sense in which it stays verbatim.
+ */
+export function appliesWhenOf(member) {
+  const value = member?.value;
+  if (typeof value === 'string') {
+    const lines = value.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const label = boldLabel(lines[i]);
+      if (!label || label.name !== 'applies when') continue;
+      // The paragraph runs until a blank line, the next label, or the end.
+      const paragraph = [label.rest];
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].trim() === '' || boldLabel(lines[j])) break;
+        paragraph.push(lines[j]);
+      }
+      const text = paragraph.join(' ').replace(/\s+/g, ' ').trim();
+      if (text) return text;
+      break; // declared but empty — fall through to the legacy field
+    }
+  }
+  const fromMeta = parseMetaComment(value)['trigger-context'];
+  return typeof fromMeta === 'string' ? fromMeta.trim() : '';
+}
+
 function totalSeen(members) {
   return (members || []).reduce((n, m) => n + (Number.isFinite(m.seenCount) ? m.seenCount : 0), 0);
 }
@@ -57,14 +140,15 @@ function distinctScopeCount(members) {
  * summed `seenCount` across members crosses `minSeenCount` (default 3 — the
  * kickoff's "seen_count >= 3" criterion, applied to the SUM across the
  * cluster's members rather than any single one, since the whole pitch of a
- * candidate is "these N sightings are really one entry"), or a member's own
- * meta comment already declares a non-"active" status.
+ * candidate is "these N sightings are really one entry"), or a member already
+ * declares a non-"active" status (a `status::<value>` tag, or a legacy meta
+ * comment — see `statusOf`).
  */
 export function isCandidate(members, { minSeenCount = 3 } = {}) {
   if (totalSeen(members) >= minSeenCount) return true;
   return (members || []).some((m) => {
-    const status = parseMetaComment(m.value).status;
-    return typeof status === 'string' && status.length > 0 && status !== 'active';
+    const status = statusOf(m);
+    return status.length > 0 && status !== 'active';
   });
 }
 
@@ -90,7 +174,12 @@ export function rankCandidates(clusters, { minSeenCount = 3, resolveClass } = {}
   return (clusters || [])
     .filter((cl) => isCandidate(cl.members, { minSeenCount }))
     .map((cl) => {
-      const members = (cl.members || []).map((m) => ({ ...m, meta: parseMetaComment(m.value) }));
+      const members = (cl.members || []).map((m) => ({
+        ...m,
+        meta: parseMetaComment(m.value),
+        status: statusOf(m),
+        appliesWhen: appliesWhenOf(m),
+      }));
       return {
         members,
         size: cl.size ?? members.length,

package/src/shared/mirror-pairs.mjs

@@ -75,6 +75,11 @@ export const mirrorPairs = [
   { core: 'packages/mcp-core/src/limits/expiring-window.ts', edge: 'supabase/functions/_shared/limits/expiring-window.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/rest/cors-origins.ts', edge: 'supabase/functions/_shared/api/cors-origins.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/scope/scope-type-attribute.ts', edge: 'supabase/functions/_shared/scope/scope-type-attribute.ts', driftChecked: true },
+  // Which row an UNSCOPED read resolves to. Import-free on both sides (it only
+  // parses the scope prefix and compares strings), so the byte comparison
+  // applies — which is the point: a precedence that drifted between MCP and
+  // REST would hand the same key-only read two different lessons.
+  { core: 'packages/mcp-core/src/scope/scope-precedence.ts', edge: 'supabase/functions/_shared/scope/scope-precedence.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/auth/account-wide-tools.ts', edge: 'supabase/functions/_shared/auth/account-wide-tools.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/telemetry/io-ledger.ts', edge: 'supabase/functions/_shared/telemetry/io-ledger.ts', driftChecked: true },
   { core: 'packages/mcp-core/src/telemetry/db-query-metrics.ts', edge: 'supabase/functions/_shared/telemetry/db-query-metrics.ts', driftChecked: true },
@@ -91,6 +96,10 @@ export const mirrorPairs = [
   // `lessons-view.mjs` clustering, which is what `lorekit dedupe` runs — guarded
   // behaviourally by `duplicate-clusters-parity.spec.ts` instead.
   { core: 'packages/mcp-core/src/clusters/duplicate-clusters.ts', edge: 'supabase/functions/_shared/clusters/duplicate-clusters.ts', driftChecked: true },
+  // Batch `memory.read` (`refs`) core — grouping-by-scope, the key charset
+  // guard, and the found/missing set difference shared by MCP's `toolRead`
+  // and REST's `handleRead`. Import-free, so the byte comparison applies.
+  { core: 'packages/mcp-core/src/memory/read-refs.ts', edge: 'supabase/functions/_shared/memory/read-refs.ts', driftChecked: true },
   // Excluded from the byte-comparison drift check: the edge copy types the
   // client as `ReturnType<typeof createClient>` off an `npm:` specifier where
   // mcp-core imports a typed `SupabaseClient`, and additionally carries

package/src/shared/scope-precedence.mjs

@@ -0,0 +1,82 @@
+// Which entry wins when a read named NO scope — the CLI's twin of
+// `packages/mcp-core/src/scope/scope-precedence.ts` (and its edge mirror,
+// `supabase/functions/_shared/scope/scope-precedence.ts`).
+//
+// Kept as a separate zero-dep module rather than imported: this package has no
+// dependency on `@lorekit/core`, and the pair is a CROSS-LANGUAGE one (this
+// `.mjs` vs that `.ts`), so it is guarded for BEHAVIOURAL parity by
+// `scope-precedence-parity.spec.ts` rather than the byte comparison
+// `mirror-pairs.mjs` runs over the two TypeScript copies — the same
+// arrangement `session-kind-parity.spec.ts` uses.
+//
+// Distinct from `resolvePrecedence` in `lessons-pure.mjs`, which resolves a
+// key across the CALLER'S OWN scope list (`deriveScope().readOrder`,
+// narrow-to-broad). That one answers "the agent is standing in this repo, on
+// this branch — whose lesson wins?". This one answers the question that only
+// arises once NO scope was named at all, where the caller's own scopes are not
+// the candidate set: every scope the account can see is. The server has no
+// working directory to derive `readOrder` from, so this is the only definition
+// MCP, REST and the CLI can all compute — which is why `show <key>` uses it
+// too, instead of quietly resolving differently from the hosted surfaces.
+
+/**
+ * Scope types in resolution order, most-specific first. The SAME order as
+ * `readOrder` — see the TS twin for why it is a list rather than a segment
+ * count.
+ */
+export const SCOPE_PRECEDENCE = ['project', 'branch', 'repo', 'global'];
+
+/**
+ * Rank a scope by type: 0 for the most specific, higher for broader. An
+ * unrecognised scope ranks LAST rather than throwing.
+ */
+export function scopePrecedenceRank(scope) {
+  const raw = typeof scope === 'string' ? scope.trim().toLowerCase() : '';
+  const sep = raw.indexOf('::');
+  const prefix = sep === -1 ? raw : raw.slice(0, sep);
+  const at = SCOPE_PRECEDENCE.indexOf(prefix);
+  return at === -1 ? SCOPE_PRECEDENCE.length : at;
+}
+
+/**
+ * Order two candidates: precedence band, then most-recently-updated, then
+ * scope ascending. Total and deterministic — see the TS twin for why the last
+ * two tie-breaks are load-bearing rather than decoration.
+ */
+export function compareScopePrecedence(a, b) {
+  const byRank = scopePrecedenceRank(a?.scope) - scopePrecedenceRank(b?.scope);
+  if (byRank !== 0) return byRank;
+  const at = typeof a?.updated_at === 'string' ? a.updated_at : '';
+  const bt = typeof b?.updated_at === 'string' ? b.updated_at : '';
+  if (at !== bt) return at < bt ? 1 : -1;
+  const as = typeof a?.scope === 'string' ? a.scope : '';
+  const bs = typeof b?.scope === 'string' ? b.scope : '';
+  return as < bs ? -1 : as > bs ? 1 : 0;
+}
+
+/** The entry an unscoped read resolves to, or `null` when there were none. */
+export function pickScopeWinner(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) return null;
+  let winner = rows[0];
+  for (let i = 1; i < rows.length; i += 1) {
+    if (compareScopePrecedence(rows[i], winner) < 0) winner = rows[i];
+  }
+  return winner;
+}
+
+/**
+ * Every scope the candidates cover EXCEPT the winner's, in precedence order,
+ * de-duplicated — what an unscoped read reports so the caller can see its key
+ * was ambiguous and pass an explicit scope next time.
+ */
+export function shadowedScopes(rows, winner) {
+  if (!Array.isArray(rows) || !winner) return [];
+  const seen = new Set([winner.scope]);
+  const out = [];
+  for (const row of [...rows].sort(compareScopePrecedence)) {
+    if (seen.has(row.scope)) continue;
+    seen.add(row.scope);
+    out.push(row.scope);
+  }
+  return out;
+}

package/src/store/local.mjs

@@ -10,7 +10,8 @@ import path from 'node:path';
 import { serializeEntry, parseEntry, slugify, scopeToDir } from './format.mjs';
 import { normalizeCreatedAt } from './created-at.mjs';
 import { isLive, resolveExpiresAt } from './ttl.mjs';
-import { seenCountOf, withReadFields } from './entry-fields.mjs';
+import { seenCountOf, withReadFields, updatedAtOf } from './entry-fields.mjs';
+import { pickScopeWinner } from '../shared/scope-precedence.mjs';
 
 export function createLocalStore(baseDir) {
   return new LocalStore(baseDir);
@@ -54,6 +55,20 @@ class LocalStore {
     return this._readAll(scope).find((r) => r.entry.key === key) || null;
   }
 
+  // Every LIVE entry carrying `key`, across every scope in this store — the
+  // candidate set for a read that named no scope.
+  //
+  // Walks the whole tree rather than one scope directory, because `_files`
+  // resolves a single scope→directory and there is no directory for "any".
+  // That is more IO than a scoped read, which is exactly why a caller that
+  // knows its scope should still pass it.
+  _findAllByKey(key) {
+    const now = new Date();
+    return this._walkEntries()
+      .map((r) => r.entry)
+      .filter((e) => e && e.key === key && e.scope && isLive(e, now));
+  }
+
   // Raw lookup by scope+key — returns the stored entry regardless of archived
   // state (unlike read(), which hides archived). Synchronous; used by migrate
   // to classify ADD / UPDATE / NOOP without reviving archived entries.
@@ -80,7 +95,14 @@ class LocalStore {
   }
 
   // read({ scope, key }) → { ok, entry } — null when absent, archived, or expired.
+  //
+  // `scope` is OPTIONAL. Without one the key is resolved across every scope in
+  // this store and the winner picked by the shared `scope-precedence` rule —
+  // the SAME rule the hosted MCP and REST surfaces apply, so `lorekit show
+  // <key>` offline and `memory.read { key }` online cannot resolve the same key
+  // to different lessons.
   async read({ scope, key } = {}) {
+    if (!scope) return { ok: true, entry: this._readUnscoped(key) };
     const found = this._findByKey(scope, key);
     return {
       ok: true,
@@ -88,6 +110,34 @@ class LocalStore {
     };
   }
 
+  // The unscoped half of `read`, split out so `TwoTierStore` can reuse the
+  // candidate gathering without re-deciding the precedence rule.
+  _readUnscoped(key) {
+    const winner = pickScopeWinner(this._findAllByKey(key).map(scopeCandidate));
+    return winner ? withReadFields(winner.entry) : null;
+  }
+
+  // readMany(refs) → { ok, entries, missing } — batch lookup for an array of
+  // `{ scope, key }` refs, mirroring the REST/MCP batch read's shape: found
+  // entries in `entries` (same projection `read()` applies), unresolved refs
+  // (absent, archived, or expired) reported as `scope::key` strings in
+  // `missing` rather than silently dropped. A thin loop over `_findByKey` —
+  // this store has no query engine to batch against, so there is no cheaper
+  // shape than one lookup per ref.
+  async readMany(refs = []) {
+    const entries = [];
+    const missing = [];
+    for (const { scope, key } of refs) {
+      const found = this._findByKey(scope, key);
+      if (found && isLive(found.entry)) {
+        entries.push(withReadFields(found.entry));
+      } else {
+        missing.push(`${scope}::${key}`);
+      }
+    }
+    return { ok: true, entries, missing };
+  }
+
   // write(...) → { ok, entry } — upsert by scope+key. Preserves `created` and
   // refreshes `updated`; writing an archived key revives it.
   //
@@ -328,6 +378,19 @@ class LocalStore {
   }
 }
 
+/**
+ * Project a stored entry into the `{ scope, updated_at }` shape
+ * `scope-precedence` compares, keeping the entry itself alongside so the winner
+ * can be returned without a second lookup.
+ *
+ * `updatedAtOf` is what maps the local `updated` spelling onto the `updated_at`
+ * the shared rule expects — without it every local candidate would compare as
+ * having no timestamp and the tie-break would collapse to scope-ascending.
+ */
+function scopeCandidate(entry) {
+  return { scope: entry.scope, updated_at: updatedAtOf(entry), entry };
+}
+
 // A scope string is global when its type segment is `global`.
 function isGlobalScope(scope) {
   return String(scope).split('::')[0] === 'global';
@@ -394,6 +457,23 @@ class TwoTierStore {
   }
 
   async read({ scope, key } = {}) {
+    // Unscoped: precedence has to be decided over BOTH tiers at once, not tier
+    // by tier. Asking the project tier first and taking any hit would let a
+    // `global` lesson in the project tier beat a `repo::…` one in the home
+    // tier — tier order standing in for scope precedence, which is not what it
+    // means. Within ONE scope the project tier still shadows home, exactly as
+    // the scoped path below does.
+    if (!scope) {
+      const tiers = this.projectActive() ? [this.project, this.home] : [this.home];
+      const byScope = new Map();
+      for (const tier of tiers) {
+        for (const entry of tier._findAllByKey(key)) {
+          if (!byScope.has(entry.scope)) byScope.set(entry.scope, entry);
+        }
+      }
+      const winner = pickScopeWinner([...byScope.values()].map(scopeCandidate));
+      return { ok: true, entry: winner ? withReadFields(winner.entry) : null };
+    }
     if (this.projectActive()) {
       const r = await this.project.read({ scope, key });
       if (r.entry) return r;
@@ -401,6 +481,20 @@ class TwoTierStore {
     return this.home.read({ scope, key });
   }
 
+  // readMany(refs) → { ok, entries, missing } — per-ref `read()`, so the same
+  // project-shadows-home precedence applies to every ref individually rather
+  // than to the batch as a whole.
+  async readMany(refs = []) {
+    const entries = [];
+    const missing = [];
+    for (const { scope, key } of refs) {
+      const r = await this.read({ scope, key });
+      if (r.entry) entries.push(r.entry);
+      else missing.push(`${scope}::${key}`);
+    }
+    return { ok: true, entries, missing };
+  }
+
   async write(args = {}) {
     return this.tierFor(args.scope).write(args);
   }