@lorekit/cli 1.13.1 → 1.15.0

package/README.md

@@ -17,7 +17,7 @@ markdown files if you never want to sign up for anything.
 
 ```bash
 npm install -g @lorekit/cli
-lorekit install     # wires up the skill, MCP server, and hooks
+lorekit install     # wires up the skills, MCP server, and hooks
 lorekit doctor      # verify it's all green
 ```
 
@@ -47,7 +47,7 @@ Linux, and Windows (npm creates the `lorekit` shim on every platform).
 Sets up the full memory loop — the same three parts as the Claude plugin,
 without needing a marketplace:
 
-1. **Skill** (`lorekit-memory`) — the model-invoked authoring judgment.
+1. **Skills** (`lorekit-memory` + `lorekit-setup`) — the model-invoked authoring judgment and the self-improvement loop authoring counterpart.
 2. **MCP server** (`lorekit`) — the connection to your lessons, merged into the
    MCP config (preserving any other servers).
 3. **Hooks** — the *deterministic* layer: lessons injected on every
@@ -75,7 +75,7 @@ lorekit install --global      # set it up for every project
 
 In a TTY it prompts for the scope (and for `--endpoint` / `--token` if missing).
 Flags: `--project` / `--global` pick the scope non-interactively; `--no-hooks`
-installs the skill + MCP only (memory stays model-invoked); `--yes` runs
+installs the skills + MCP only (memory stays model-invoked); `--yes` runs
 non-interactively (endpoint required via flag/env; scope defaults to project);
 `--force` overwrites an existing skill copy. Re-running is idempotent — the hook
 entries are updated in place, never duplicated.
@@ -194,6 +194,44 @@ 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 scopes`
+
+A **store-wide inventory** of every distinct scope that holds lessons, with a
+lesson count per scope, in the same Offline / Remote split as the other read
+commands:
+
+```bash
+lorekit scopes                 # every scope in the store + a count each
+lorekit scopes --scope repo::  # filter to scopes containing a substring
+lorekit scopes --json          # { offline, remote } with [{ scope, count }] rows
+```
+
+Unlike `list` / `search` / `stats` / `diff` / `tree` — which are all **cwd-scoped**
+(they only look at the scopes that resolve for the current directory:
+project / branch / repo / global) — `scopes` enumerates **every** scope present in
+the store, regardless of the current directory. That's the whole point: it lets
+you see all the scopes you have lessons in, anywhere. Scopes are grouped by type
+(global → project → repo → branch), then alphabetically; each store shows a
+per-store total and scope count.
+
+`--scope <s>` is a **substring filter** over the inventory (not a single-scope
+selector — an inventory of one scope would be pointless).
+
+**Offline enumeration is exact.** It walks the local two-tier store and reads
+each lesson file's frontmatter `scope` string directly, rather than reverse-
+mapping the on-disk directory layout (which is lossy for `project::{name}`,
+stored by basename only) — so every scope is reconstructed verbatim. Lessons
+present in both tiers are counted once (project shadows home, the same merge
+`list` uses); archived lessons are excluded.
+
+**Remote enumeration is not possible, and `scopes` says so honestly.** The
+hosted MCP surface exposes no "list all scopes" tool — every read tool
+(`memory.list` / `memory.search` / `memory.read`) *requires* a scope — so a
+remote inventory can't be built. The Remote section is therefore always a short
+note (never a faked listing), degrading gracefully at exit 0, the same way
+`stats` omits a cap-usage figure. `--endpoint` / `--token` / `--store` behave as
+in `list`.
+
 ### `lorekit diff`
 
 Compare the **offline** and **remote** stores for the applicable scopes and
@@ -406,13 +444,53 @@ Two config layers decide the mode:
 - **Repo / team** — a `.lorekit.json` at the repo root (and/or the existing
   `lorekit` block in `.mcp.json` for the connection).
 
-Both files share one schema:
+Both files share this schema — all fields optional:
 
 ```jsonc
+// .lorekit.json  (repo root — safe to commit, no secrets)
+// ~/.lorekit/config.json  (user/machine — personal overrides, not committed)
 {
-  "mode": "local",        // select a mode (off | local | remote)
-  "store": ".lorekit",    // project-tier store dir (relative to repo root, or absolute)
-  "deny": ["remote"]      // forbid modes outright — deny always wins
+  // ── Mode & store ───────────────────────────────────────────────────────────
+  "mode": "local",         // off | local | remote
+  "store": ".lorekit",     // project-tier store path (relative to root, or absolute)
+  "deny": ["remote"],      // forbid modes outright — deny always wins, union across layers
+
+  // ── Connection (repo config only — no token, safe to commit) ───────────────
+  "mcp.endpoint": "https://<ref>.supabase.co/functions/v1/mcp",
+                           // committable MCP URL without token; token still comes
+                           // from .mcp.json or LOREKIT_TOKEN env var
+
+  // ── Write behaviour ────────────────────────────────────────────────────────
+  "tags.default": ["team", "project::my-project"],
+                           // tags appended to every memory.write from this repo/user
+                           // both layers merged: repo tags first, then user tags
+
+  "scope.defaults": {
+    "repo::owner/name":     { "tags": ["team"] },
+    "branch::owner/name::": { "tags": ["ephemeral"] }
+  },
+                           // per-scope tag defaults applied to writes whose scope
+                           // starts with the key; matched by prefix (no wildcards needed)
+                           // repo config only — this is a team-level write policy
+
+  // ── Hook behaviour ─────────────────────────────────────────────────────────
+  "hooks.disabled": ["Stop"],
+                           // suppress specific hook events; union across layers
+                           // values: "SessionStart" | "PostToolUseFailure" | "Stop"
+
+  "hooks.adapter": "claude",
+                           // explicit adapter when auto-detection is ambiguous
+                           // values: "claude" | "cursor" | "codex"
+                           // repo wins over user
+
+  // ── Telemetry ──────────────────────────────────────────────────────────────
+  "telemetry.disabled": true,
+                           // team-level opt-out for orgs with a no-telemetry policy
+                           // env LOREKIT_TELEMETRY=0 always wins if set
+
+  // ── Dedupe threshold ───────────────────────────────────────────────────────
+  "dedupe.threshold": 0.8  // Jaccard similarity cutoff for `lorekit dedupe`
+                           // --threshold flag wins when passed explicitly
 }
 ```
 
@@ -450,11 +528,11 @@ active deny constraints.
 | `--to <tier>` | Migration destination tier: `home` / `project` (`migrate`; default routes by scope) |
 | `--apply` | Apply the migration — alias of `--yes` (`migrate`) |
 | `-y, --yes` | Non-interactive / apply; never prompt |
-| `--no-hooks` | Skip wiring the lifecycle hooks; skill + MCP only (`install`) |
+| `--no-hooks` | Skip wiring the lifecycle hooks; skills + MCP only (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
-| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `diff` / `tree` / `lint` / `dedupe`) |
-| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe`; default: all applicable) |
+| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe`) |
+| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe`; default: all applicable). For `scopes` it is a **substring filter** over the inventory |
 | `--threshold <0..1>` | Duplicate-similarity cutoff (`dedupe`; default `0.8`) |
 | `--adapter <name>` | Host framework for `hook`: `claude` / `cursor` / `codex` |
 | `--event <name>` | Host hook event for `hook` (else read from the stdin payload) |
@@ -548,7 +626,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`, `stats`, `diff`, `migrate`)
+`show`, `stats`, `scopes`, `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

@@ -10,6 +10,7 @@ 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 { scopes } from '../src/scopes.mjs';
 import { diff } from '../src/diff.mjs';
 import { tree } from '../src/tree.mjs';
 import { lint } from '../src/lint.mjs';
@@ -33,7 +34,7 @@ ${c.bold('Usage')}
 
 ${c.bold('Commands')}
   install     Scaffold the lorekit-memory + lorekit-setup skills, wire the
-              LoreKit MCP server, and install the deterministic hooks (lessons
+              LoreKit MCP server, and install the deterministic hooks (memories
               on SessionStart, a nudge on tool failure + at Stop). Prompts to
               install for this project (.claude) or globally for every project
               (~/.claude); --project / --global choose non-interactively,
@@ -43,35 +44,39 @@ ${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
+  list (ls)   List the memories 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
+  search      Full-text search the applicable memories 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
+  show        Inspect one memory 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
+  stats       Count the applicable memories per scope and per store (offline vs
               remote), with per-store and grand totals, in the same Offline/
               Remote split. --json, --scope <s>.
+  scopes      Store-wide inventory of EVERY distinct scope that holds memories,
+              with a memory count per scope — not cwd-scoped like the commands
+              above (it lists scopes anywhere in the store). Offline is exact;
+              the remote can't enumerate scopes (honest note). --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>.
   tree        Show the injected scopes (project → branch → repo → global) as a precedence
-    (resolve) hierarchy and mark, per key, which scope's lesson WINS and which are
+    (resolve) hierarchy and mark, per key, which scope's memory WINS and which are
               shadowed — the real hook-resolution order. --json, --scope <s>.
-  lint        Flag low-quality lessons (empty/short/untrimmed value, empty key,
+  lint        Flag low-quality memories (empty/short/untrimmed value, empty key,
               malformed scope) across the applicable scopes and both stores. Exits
               non-zero when issues are found (CI gate). --json, --scope <s>.
-  dedupe      Find likely-duplicate lessons via a zero-dep word-overlap HEURISTIC
+  dedupe      Find likely-duplicate memories via a zero-dep word-overlap HEURISTIC
               (Jaccard >= threshold, not semantic), grouped into clusters per
               store. --json, --scope <s>, --threshold <0..1>.
   migrate     Relocate a LoreKit-format local store into the current layout.
               Dry-run by default; pass --yes to apply. Idempotent.
   hook        Hook engine for Claude Code / Cursor / Codex. Reads the host's
-              JSON on stdin and injects lessons or a retrospective nudge.
+              JSON on stdin and injects memories or a retrospective nudge.
               Not run by hand — wired into a plugin's hook config.
   mcp         Local stdio MCP server. Exposes the memory.* tools backed by the
               resolved store (local .lorekit/ offline, or remote passthrough) so
@@ -86,8 +91,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 / stats / diff / tree / lint / dedupe)
-      --scope <scope>     Restrict to a single scope (list / search / stats / diff / tree / lint / dedupe)
+      --json              Machine-readable output (list / search / show / stats / scopes / diff / tree / lint / dedupe)
+      --scope <scope>     Restrict to a single scope; a substring filter for scopes (list / search / stats / scopes / diff / tree / lint / dedupe)
       --threshold <0..1>  Duplicate-similarity cutoff (dedupe; default 0.8)
       --from <path>       Source store to migrate from (migrate)
       --to <tier>         Migration destination tier: home | project (migrate;
@@ -138,7 +143,7 @@ ${c.bold('Usage')}
 
 Scaffolds the lorekit-memory (runtime read/write) and lorekit-setup (loop
 authoring) skills, adds the LoreKit MCP server, and wires the deterministic
-hooks (lessons on SessionStart, a nudge on tool failure + at Stop).
+hooks (memories on SessionStart, a nudge on tool failure + at Stop).
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
@@ -194,12 +199,12 @@ ${c.bold('Examples')}
   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)')}
+  list: `${c.bold('lorekit list')} — list the memories 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
+Shows the memories 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
@@ -218,14 +223,14 @@ ${c.bold('Examples')}
   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)')}
+  search: `${c.bold('lorekit search')} — full-text search the applicable memories ${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/
+Searches every memory 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,
+substring of a memory'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.
 
@@ -242,12 +247,12 @@ ${c.bold('Examples')}
   npx @lorekit/cli grep "flaky test" --json
   npx @lorekit/cli search migration --scope global
 `,
-  show: `${c.bold('lorekit show')} — inspect one lesson in full
+  show: `${c.bold('lorekit show')} — inspect one memory in full
 
 ${c.bold('Usage')}
   npx @lorekit/cli show <scope> <key> [options]
 
-Prints one lesson's complete (untruncated) value, scope, key, updated date, tags,
+Prints one memory'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.
@@ -263,12 +268,12 @@ ${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
+  stats: `${c.bold('lorekit stats')} — count the applicable memories 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/
+Shows how many memories 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.
@@ -285,6 +290,35 @@ ${c.bold('Examples')}
   npx @lorekit/cli stats
   npx @lorekit/cli stats --json
   npx @lorekit/cli stats --scope global
+`,
+  scopes: `${c.bold('lorekit scopes')} — store-wide inventory of every distinct scope
+
+${c.bold('Usage')}
+  npx @lorekit/cli scopes [options]
+
+Lists EVERY distinct scope present in the store, with a memory count per scope,
+in the same Offline / Remote split as the other read commands. Unlike \`list\` /
+\`stats\` (which only see the scopes that resolve for the current directory), this
+is a full inventory — it surfaces scopes anywhere in the store, regardless of the
+current directory.
+
+Offline counts are exact: each scope is read from the memory files' frontmatter,
+not reverse-mapped from the directory layout. The Remote section is always a
+short note: the hosted MCP surface has no "list all scopes" tool (every read tool
+requires a scope), so a remote inventory isn't possible — never an error (exit 0).
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --scope <substr>    Filter the inventory to scopes containing this substring
+      --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 scopes
+  npx @lorekit/cli scopes --json
+  npx @lorekit/cli scopes --scope repo::
 `,
   diff: `${c.bold('lorekit diff')} — compare the offline and remote stores
 
@@ -310,16 +344,16 @@ ${c.bold('Examples')}
   npx @lorekit/cli diff --json
   npx @lorekit/cli diff --scope global
 `,
-  tree: `${c.bold('lorekit tree')} — show the scope precedence hierarchy and which lesson wins ${c.dim('(alias: resolve)')}
+  tree: `${c.bold('lorekit tree')} — show the scope precedence hierarchy and which memory wins ${c.dim('(alias: resolve)')}
 
 ${c.bold('Usage')}
   npx @lorekit/cli tree [options]
 
 Shows the scopes the hooks actually inject for the current directory — project,
 branch, repo, global, in precedence order (most-specific first) — and marks, for any key
-present at more than one scope, which scope's lesson WINS and which are shadowed.
+present at more than one scope, which scope's memory WINS and which are shadowed.
 This mirrors the SessionStart hook's resolution exactly (a more-specific scope
-overrides a broader scope's same-key lesson). Resolved independently per store,
+overrides a broader scope's same-key memory). Resolved independently per store,
 in the same Offline / Remote split.
 
 ${c.bold('Options')}
@@ -334,12 +368,12 @@ ${c.bold('Examples')}
   npx @lorekit/cli tree
   npx @lorekit/cli resolve --json
 `,
-  lint: `${c.bold('lorekit lint')} — flag low-quality lessons across the applicable scopes
+  lint: `${c.bold('lorekit lint')} — flag low-quality memories across the applicable scopes
 
 ${c.bold('Usage')}
   npx @lorekit/cli lint [options]
 
-Checks every lesson for the current directory's scopes (project/branch/repo/
+Checks every memory for the current directory's scopes (project/branch/repo/
 global), across both stores, against a small set of quality rules: empty or
 whitespace-only value, suspiciously short value, untrimmed value, empty key, and
 malformed scope (e.g. a single \`:\` where \`::\` is expected). Each finding names
@@ -359,12 +393,12 @@ ${c.bold('Examples')}
   npx @lorekit/cli lint --json
   npx @lorekit/cli lint --scope global
 `,
-  dedupe: `${c.bold('lorekit dedupe')} — find likely-duplicate lessons (heuristic)
+  dedupe: `${c.bold('lorekit dedupe')} — find likely-duplicate memories (heuristic)
 
 ${c.bold('Usage')}
   npx @lorekit/cli dedupe [options]
 
-Groups lessons whose values overlap heavily into duplicate clusters, per store,
+Groups memories whose values overlap heavily into duplicate clusters, per store,
 across the current directory's scopes. The similarity signal is a zero-dependency
 HEURISTIC — Jaccard overlap of lowercased word tokens, not a semantic/embedding
 measure — so it surfaces candidates for a human to review, and can both miss
@@ -406,7 +440,7 @@ ${c.bold('Examples')}
 ${c.bold('Usage')}
   lorekit hook --adapter <claude|cursor|codex> --event <name> [--dir <path>]
 
-Machine-facing: reads the host's JSON on stdin and injects lessons or a
+Machine-facing: reads the host's JSON on stdin and injects memories or a
 retrospective nudge on stdout, always exiting 0. Wired into a plugin's hook
 config by \`lorekit install\` — not run by hand.
 
@@ -442,8 +476,8 @@ 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', 'stats', 'diff',
-  'tree', 'lint', 'dedupe', 'migrate',
+  'install', 'uninstall', 'doctor', 'list', 'search', 'show', 'stats', 'scopes',
+  'diff', 'tree', 'lint', 'dedupe', 'migrate',
 ]);
 
 // Command aliases — canonicalized before help / dispatch so `lorekit ls --help`
@@ -525,6 +559,8 @@ async function main() {
       return traceCommand('show', args, VERSION, () => show(args));
     case 'stats':
       return traceCommand('stats', args, VERSION, () => stats(args));
+    case 'scopes':
+      return traceCommand('scopes', args, VERSION, () => scopes(args));
     case 'diff':
       return traceCommand('diff', args, VERSION, () => diff(args));
     case 'tree':

package/package.json

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

package/src/config.mjs

@@ -345,8 +345,9 @@ export function tokenKind(token) {
 
 // For hooks: resolve the connection closest-scope first — the project's
 // .mcp.json (a project install), then the global ~/.claude.json (a global
-// install), then env. `splitEndpoint` is passed in to avoid a circular import
-// with mcp.mjs.
+// install), then the `mcp.endpoint` field in .lorekit.json (committable URL
+// without token — safe for VCS), then env. `splitEndpoint` is passed in to
+// avoid a circular import with mcp.mjs.
 export function resolveProjectConnection(root, splitEndpoint) {
   const sources = [readLorekitServer(root), readServerFromFile(mcpConfigPath(root, 'global'))];
   for (const configured of sources) {
@@ -360,5 +361,33 @@ export function resolveProjectConnection(root, splitEndpoint) {
       }
     }
   }
+
+  // Fallback: `mcp.endpoint` in .lorekit.json — a committable URL without token.
+  // Token still comes from .mcp.json or LOREKIT_TOKEN.
+  const lorekitJson = readLorekitJson(root);
+  const committedEndpoint =
+    lorekitJson && typeof lorekitJson['mcp.endpoint'] === 'string'
+      ? lorekitJson['mcp.endpoint'].trim()
+      : null;
+  if (committedEndpoint && !committedEndpoint.includes('<project-ref>')) {
+    return {
+      endpoint: committedEndpoint,
+      token: process.env.LOREKIT_TOKEN || null,
+    };
+  }
+
   return resolveConnection({});
 }
+
+// Read .lorekit.json from the repo root without throwing. Exported so other
+// CLI modules can read per-repo config without duplicating the same try/catch.
+// control.mjs uses its own internal readJson(file) for historical reasons and
+// does not import this — that is a known duplication, not a bug.
+export function readLorekitJson(root) {
+  const file = path.join(root, '.lorekit.json');
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}

package/src/control.mjs

@@ -1,5 +1,11 @@
 // The control model: decide the memory mode (off | local | remote), the store
-// target, who decided, and which deny constraints are active.
+// target, who decided, and which deny constraints are active. Also resolves
+// write-behaviour properties from the config layers:
+//
+//   scope.defaults  — map of scope-prefix → { tags } applied to every matching write
+//   tags.default    — array of tags appended to every write (both layers merged)
+//   hooks.disabled  — array of hook event names to suppress (e.g. ["Stop"])
+//   hooks.adapter   — explicit adapter override ("claude" | "cursor" | "codex")
 //
 // Two layers of config, two kinds of statement:
 //   - a SELECT (`mode`) chooses a mode within what is allowed;
@@ -104,7 +110,44 @@ export function resolveControl({
     storeTarget = connection.endpoint || null;
   }
 
-  return { mode: chosen.mode, storeTarget, decidedBy, denies, connection };
+  // 5. Write-behaviour properties resolved from config layers.
+  //    `tags.default` — both layers merged, user supplements repo (no override).
+  const tagsDefault = [
+    ...asList(repoConfig['tags.default']),
+    ...asList(userConfig['tags.default']),
+  ].filter((t) => typeof t === 'string' && t.length > 0);
+
+  // `scope.defaults` — repo layer only (team-scoped write policy).
+  //    Schema: { "<scope-prefix>": { "tags": [...] } }
+  //    Matched against a write's resolved scope using startsWith — no glob dep.
+  const scopeDefaults =
+    repoConfig['scope.defaults'] && typeof repoConfig['scope.defaults'] === 'object'
+      ? repoConfig['scope.defaults']
+      : null;
+
+  // `hooks.disabled` — union of both layers (either layer can suppress an event).
+  const hooksDisabled = new Set([
+    ...asList(repoConfig['hooks.disabled']),
+    ...asList(userConfig['hooks.disabled']),
+  ]);
+
+  // `hooks.adapter` — repo layer wins over user layer (explicit project override).
+  const hooksAdapter =
+    (typeof repoConfig['hooks.adapter'] === 'string' && repoConfig['hooks.adapter'].trim()) ||
+    (typeof userConfig['hooks.adapter'] === 'string' && userConfig['hooks.adapter'].trim()) ||
+    null;
+
+  return {
+    mode: chosen.mode,
+    storeTarget,
+    decidedBy,
+    denies,
+    connection,
+    tagsDefault,
+    scopeDefaults,
+    hooksDisabled,
+    hooksAdapter,
+  };
 }
 
 // The per-repo project-tier directory: $LOREKIT_STORE, else a `store` override

package/src/core/lessons.mjs

@@ -55,7 +55,7 @@ export async function fetchLessons(store, cwd) {
 export function formatLessons(lessons, scope) {
   if (!lessons || lessons.length === 0) return null;
   const header =
-    `LoreKit — ${lessons.length} shared lesson(s) for ${scope.repoScope || 'this workspace'}. ` +
+    `LoreKit — ${lessons.length} shared ${lessons.length === 1 ? 'memory' : 'memories'} for ${scope.repoScope || 'this workspace'}. ` +
     `Treat as considerations, not rules; trust the current code if they conflict.`;
   const body = lessons
     .map((l) => {
@@ -110,7 +110,7 @@ export function formatRelevantLessons(lessons) {
   if (!lessons || lessons.length === 0) return null;
   const header =
     `LoreKit — you've hit something like this before. ${lessons.length} related ` +
-    'lesson(s) (considerations, not rules; trust the current code if they conflict):';
+    `${lessons.length === 1 ? 'memory' : 'memories'} (considerations, not rules; trust the current code if they conflict):`;
   const body = lessons
     .map((l) => {
       const first = String(l.value || '').split('\n')[0].slice(0, 300);
@@ -120,25 +120,52 @@ export function formatRelevantLessons(lessons) {
   return `${header}\n${body}`;
 }
 
+// Build a tags hint string from config-resolved tags and scope defaults. Returns
+// "" when there are no configured tags (no hint appended to the nudge).
+function tagsHint(writeScope, { tagsDefault = [], scopeDefaults = null } = {}) {
+  const tags = [...tagsDefault];
+  if (scopeDefaults) {
+    for (const [prefix, cfg] of Object.entries(scopeDefaults)) {
+      if (
+        writeScope === prefix ||
+        writeScope.startsWith(prefix.endsWith('::') ? prefix : prefix + '::')
+      ) {
+        for (const t of Array.isArray(cfg.tags) ? cfg.tags : []) {
+          if (typeof t === 'string' && t.length > 0 && !tags.includes(t)) tags.push(t);
+        }
+      }
+    }
+  }
+  if (tags.length === 0) return '';
+  return ` Include tags: [${tags.map((t) => JSON.stringify(t)).join(', ')}].`;
+}
+
 // The retrospective nudge emitted at end-of-turn (one-shot per session).
-export function retrospectiveNudge(scope) {
+// `control` is the resolved control object (optional) — carries tagsDefault and
+// scopeDefaults when the repo/user config defines them.
+export function retrospectiveNudge(scope, control) {
   const writeScope = scope.repoScope || 'global';
+  const hint = tagsHint(writeScope, control);
   return (
     'LoreKit retrospective: if this session hit a stuck loop, a repeated ' +
     'command failure, a surprising gotcha, a near-miss, or a wrong assumption ' +
     'that cost time, record it now via the lorekit-memory skill ' +
-    `(memory.write to ${writeScope}, phrased as an observation). ` +
+    `(memory.write to ${writeScope}, phrased as an observation).${hint} ` +
     'If nothing was durable, do nothing.'
   );
 }
 
 // The nudge emitted when a tool failure is detected.
-export function failureNudge(toolName, scope) {
+// `control` is the resolved control object (optional) — carries tagsDefault and
+// scopeDefaults when the repo/user config defines them.
+export function failureNudge(toolName, scope, control) {
   const writeScope = scope.repoScope || 'global';
+  const hint = tagsHint(writeScope, control);
+  const suffix = hint ? `${hint} So the next run avoids it.` : 'so the next run avoids it.';
   return (
     `LoreKit: the last ${toolName} call failed. If this is a recurring or ` +
-    'non-obvious failure, consider recording the fix as a lesson via ' +
-    `lorekit-memory (memory.write to ${writeScope}), so the next run avoids it.`
+    'non-obvious failure, consider recording the fix as a memory via ' +
+    `lorekit-memory (memory.write to ${writeScope}) — ${suffix}`
   );
 }
 

package/src/dedupe.mjs

@@ -11,7 +11,7 @@
 // Same Offline / Remote split and graceful degradation as `list`. Read-only.
 // Human-facing, so the bin wraps it in `traceCommand`.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
+import { resolveProjectRoot, readLorekitJson } from './config.mjs';
 import { deriveScope } from './scope.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
@@ -29,6 +29,16 @@ export function parseThreshold(raw) {
   return Math.min(1, Math.max(0, n));
 }
 
+// Read `dedupe.threshold` from .lorekit.json (non-throwing). Returns the
+// repo-default threshold, or undefined when not configured.
+export function repoThreshold(root) {
+  const cfg = readLorekitJson(root);
+  if (cfg['dedupe.threshold'] !== undefined) {
+    return parseThreshold(cfg['dedupe.threshold']);
+  }
+  return undefined;
+}
+
 // Flatten a `gather()` result into one entry list (each entry keeps its scope)
 // for cross-scope clustering, plus the scopes whose read errored (they can't be
 // clustered and are surfaced, not silently dropped).
@@ -50,7 +60,11 @@ export async function dedupe(args) {
   const env = { ...process.env };
   if (args.store) env.LOREKIT_STORE = args.store;
 
-  const threshold = parseThreshold(args.threshold);
+  // Threshold precedence: --threshold flag > dedupe.threshold in .lorekit.json > default (0.8).
+  const threshold =
+    args.threshold !== undefined
+      ? parseThreshold(args.threshold)
+      : (repoThreshold(root) ?? DEFAULT_THRESHOLD);
   const scopeInfo = deriveScope(root);
   // Default to every applicable scope; `--scope <s>` narrows to one.
   const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeList(scopeInfo);
@@ -152,7 +166,7 @@ function renderDedupeSection(header, section) {
       cluster.minSimilarity === cluster.maxSimilarity
         ? cluster.minSimilarity.toFixed(2)
         : `${cluster.minSimilarity.toFixed(2)}–${cluster.maxSimilarity.toFixed(2)}`;
-    log(`  ${c.yellow('•')} cluster ${n} ${c.dim(`(${cluster.size} lessons, similarity ${range})`)}`);
+    log(`  ${c.yellow('•')} cluster ${n} ${c.dim(`(${cluster.size} memories, similarity ${range})`)}`);
     for (const m of cluster.members) {
       log(`    ${c.cyan('-')} ${m.scope}::${m.key}`);
     }

package/src/doctor.mjs

@@ -11,6 +11,7 @@ import {
   readLorekitServer,
   readMcpConfig,
   tokenKind,
+  readLorekitJson,
 } from './config.mjs';
 import { splitEndpoint } from './mcp.mjs';
 import { deriveScope } from './scope.mjs';
@@ -82,9 +83,24 @@ export async function doctor(args) {
   const scope = deriveScope(root);
   if (scope.hasRemote) {
     record('info', 'read scope', scope.readOrder.join('  →  '));
-    record('info', 'write scope', `${scope.repoScope} (default for "went wrong" lessons)`);
+    record('info', 'write scope', `${scope.repoScope} (default for "went wrong" memories)`);
   } else {
-    record('warn', 'scope', 'no git remote here — lessons fall back to global');
+    record('warn', 'scope', 'no git remote here — memories fall back to global');
+  }
+
+  // 6. doctor.require — committed list of checks that MUST pass.
+  //    Useful as a CI gate: any check in the list that did not pass causes a failure.
+  const lorekitJson = readLorekitJson(root);
+  const required = (Array.isArray(lorekitJson['doctor.require']) ? lorekitJson['doctor.require'] : [])
+    .filter((r) => typeof r === 'string');
+  for (const req of required) {
+    // A required check passes if its label is NOT in failedChecks (it either
+    // passed or was never run; unknown labels get a pass to avoid false failures).
+    if (failedChecks.includes(req)) {
+      record('fail', 'doctor.require', `required check failed: ${req}`);
+    } else {
+      record('pass', 'doctor.require', `required check passed: ${req}`);
+    }
   }
 
   // Summary.
@@ -128,7 +144,8 @@ async function checkLocal(control, root, args, record) {
 
   // Home tier — per-user, cross-repo, always available.
   record('pass', 'home store', prettyPath(store.homeDir));
-  record('info', 'home entries', `${await store.home.count(scopes)} lesson(s)`);
+  const homeCount = await store.home.count(scopes);
+  record('info', 'home entries', `${homeCount} ${homeCount === 1 ? 'memory' : 'memories'}`);
 
   // Project tier — opt-in; active only when its directory exists.
   const projRel = path.relative(root, store.projectDir) || store.projectDir;
@@ -137,12 +154,13 @@ async function checkLocal(control, root, args, record) {
       ? 'committed — shared with the team'
       : 'gitignored — private to your checkout';
     record('pass', 'project store', projRel);
-    record('info', 'project entries', `${await store.project.count(scopes)} lesson(s) — ${sharing}`);
+    const projCount = await store.project.count(scopes);
+    record('info', 'project entries', `${projCount} ${projCount === 1 ? 'memory' : 'memories'} — ${sharing}`);
   } else {
     record(
       'info',
       'project store',
-      `${projRel} — not opted-in (create it to persist repo/branch lessons here)`,
+      `${projRel} — not opted-in (create it to persist repo/branch memories here)`,
     );
   }
 

package/src/hook.mjs

@@ -83,6 +83,9 @@ async function run(args) {
   const control = loadControl(root);
   if (control.mode === 'off') return 0;
 
+  // `hooks.disabled` — skip the event if this event name is suppressed by config.
+  if (control.hooksDisabled && control.hooksDisabled.has(event)) return 0;
+
   const emit = (text) => {
     if (text) process.stdout.write(adapter.emit(event, text));
   };
@@ -114,14 +117,14 @@ async function run(args) {
     } catch {
       relevant = null; // never let a lesson lookup break the failure nudge
     }
-    const nudge = failureNudge(parsed.toolName, scope);
+    const nudge = failureNudge(parsed.toolName, scope, control);
     emit(relevant ? `${relevant}\n\n${nudge}` : nudge);
     return 0;
   }
 
   if (intent === 'retrospective') {
     if (!firstTimeThisSession(parsed.sessionId, 'retro')) return 0;
-    emit(retrospectiveNudge(scope));
+    emit(retrospectiveNudge(scope, control));
     return 0;
   }
 

package/src/install.mjs

@@ -113,7 +113,7 @@ export async function install(args) {
   status('pass', mcpLabel, `${existed ? 'updated' : 'created'} lorekit server → ${display(file)}`);
 
   if (!wireHooks) {
-    status('info', 'hooks', 'skipped (--no-hooks) — the skill still works, but lessons are model-invoked only');
+    status('info', 'hooks', 'skipped (--no-hooks) — the skill still works, but memories are model-invoked only');
   } else {
     const n = hooks.added + hooks.updated;
     const hookState =
@@ -127,9 +127,9 @@ export async function install(args) {
   if (kind === 'none') {
     status('warn', 'token', 'none configured — reads/writes will fail until a token is set');
   } else if (kind === 'read-only') {
-    status('warn', 'token', 'read-only (lk_ro_*) — the skill can read lessons but not write them');
+    status('warn', 'token', 'read-only (lk_ro_*) — the skill can read memories but not write them');
   } else if (kind === 'write-only') {
-    status('warn', 'token', 'write-only (lk_wo_*) — the skill can write lessons but not read them');
+    status('warn', 'token', 'write-only (lk_wo_*) — the skill can write memories but not read them');
   } else if (kind === 'unknown') {
     status('warn', 'token', 'unrecognized prefix — expected lk_rw_*, lk_ro_*, or lk_wo_*');
   } else {
@@ -140,7 +140,7 @@ export async function install(args) {
   if (gitScope.hasRemote) {
     status('info', 'scope', `${gitScope.repoScope}${gitScope.branchScope ? `  ·  ${gitScope.branchScope}` : ''}`);
   } else {
-    status('warn', 'scope', 'no git remote — lessons will fall back to global');
+    status('warn', 'scope', 'no git remote — memories will fall back to global');
   }
 
   log(`\n  Next: ${c.cyan('npx @lorekit/cli doctor')} to verify the connection.`);

package/src/lessons-view.mjs

@@ -112,6 +112,51 @@ export function tallyGroups({ groups = [], total } = {}) {
   return { perScope, total: typeof total === 'number' ? total : summed };
 }
 
+// ── `scopes` — store-wide scope inventory ─────────────────────────────────────
+
+// The canonical scope TYPE of a scope string — its `::`-leading segment when it
+// is one of the four recognized types, else `other` (a malformed / legacy row).
+// Pure. Shared by the `scopes` inventory ordering below.
+export function scopeTypeOf(scope) {
+  const type = String(scope == null ? '' : scope).split('::')[0];
+  return ['global', 'project', 'repo', 'branch'].includes(type) ? type : 'other';
+}
+
+// A stable type ordering for the inventory: broadest → most-specific, with any
+// unrecognized scope last. Chosen (over count-desc) so the listing groups
+// related scopes together and is deterministic run-to-run.
+const SCOPE_TYPE_RANK = { global: 0, project: 1, repo: 2, branch: 3, other: 4 };
+
+// Sort a scope inventory (`[{ scope, count }]`) into a navigable order: primary
+// by scope type (global → project → repo → branch → other), secondary
+// alphabetical by the full scope string. Pure — returns a new array, never
+// mutating its input.
+export function sortScopeInventory(list = []) {
+  return [...list].sort((a, b) => {
+    const ra = SCOPE_TYPE_RANK[scopeTypeOf(a.scope)] ?? 4;
+    const rb = SCOPE_TYPE_RANK[scopeTypeOf(b.scope)] ?? 4;
+    if (ra !== rb) return ra - rb;
+    return String(a.scope).localeCompare(String(b.scope));
+  });
+}
+
+// Narrow a scope inventory to the scopes whose string CONTAINS `needle`
+// (case-insensitive substring) — the `scopes --scope <s>` filter. An empty /
+// absent needle passes everything through unchanged. Pure.
+export function filterScopeInventory(list = [], needle) {
+  if (!needle) return list;
+  const q = String(needle).toLowerCase();
+  return list.filter((s) => String(s.scope).toLowerCase().includes(q));
+}
+
+// The pure core of the `scopes` command: sort an inventory and total its counts.
+// Returns `{ scopes: [{ scope, count }] (sorted), total }`. Pure.
+export function summarizeScopeInventory(list = []) {
+  const scopes = sortScopeInventory(list);
+  const total = scopes.reduce((n, s) => n + (Number(s.count) || 0), 0);
+  return { scopes, total };
+}
+
 // Compare two `gather()` results (offline vs remote) and classify every scope's
 // keys into three sets — the pure core of the `diff` command:
 //   • localOnly     — key present offline, absent remote;
@@ -384,9 +429,9 @@ export function renderSection(header, section) {
 
   const printable = (section.groups || []).filter((g) => g.entries.length || g.error);
   if (!printable.length) {
-    // `header.empty` lets `search` say "no lessons match" where `list` says
-    // "no lessons found"; both are the same empty-section case.
-    log(`  ${c.dim(header.empty || 'no lessons found in the applicable scopes')}`);
+    // `header.empty` lets `search` say "no memories match" where `list` says
+    // "no memories found"; both are the same empty-section case.
+    log(`  ${c.dim(header.empty || 'no memories found in the applicable scopes')}`);
     return;
   }
 

package/src/list.mjs

@@ -70,7 +70,7 @@ export async function list(args) {
   if (args.json) {
     log(JSON.stringify(buildJson({ root, scopes, offlineSection, remoteSection }), null, 2));
   } else {
-    heading('LoreKit lessons');
+    heading('LoreKit memories');
     log(`  project: ${c.dim(root)}`);
     log(`  scopes:  ${scopes.join('  →  ')}`);
 

package/src/mcp-server.mjs

@@ -36,7 +36,7 @@ const SERVER_INFO = { name: 'lorekit-local', version: '1.0.0' };
 export const MEMORY_TOOL_DEFS = [
   {
     name: 'memory.write',
-    description: 'Store or update a lesson',
+    description: 'Store or update a memory',
     inputSchema: {
       type: 'object',
       required: ['scope', 'key', 'value'],
@@ -58,24 +58,24 @@ export const MEMORY_TOOL_DEFS = [
   },
   {
     name: 'memory.read',
-    description: 'Read a lesson by scope and key',
+    description: 'Read a memory by scope and key',
     inputSchema: { type: 'object', required: ['scope', 'key'] },
   },
   {
     name: 'memory.list',
-    description: 'List lessons for a scope',
+    description: 'List memories for a scope',
     inputSchema: { type: 'object', required: ['scope'] },
   },
   {
     name: 'memory.search',
-    description: 'Keyword search across lessons',
+    description: 'Keyword search across memories',
     inputSchema: { type: 'object', required: ['q'] },
   },
   {
     name: 'memory.delete',
     description:
-      'Soft-archive a lesson (default) or hard-delete it (force: true). ' +
-      'Archived lessons are hidden from reads but can be restored.',
+      'Soft-archive a memory (default) or hard-delete it (force: true). ' +
+      'Archived memories are hidden from reads but can be restored.',
     inputSchema: {
       type: 'object',
       required: ['scope', 'key'],
@@ -88,7 +88,7 @@ export const MEMORY_TOOL_DEFS = [
   },
   {
     name: 'memory.archive',
-    description: 'Soft-archive a lesson. Hidden from reads but restorable.',
+    description: 'Soft-archive a memory. Hidden from reads but restorable.',
     inputSchema: { type: 'object', required: ['scope', 'key'] },
   },
 ];

package/src/scopes.mjs

@@ -0,0 +1,152 @@
+// `lorekit scopes` — a STORE-WIDE inventory of every distinct scope that holds
+// lessons, with a per-scope lesson count, in the same Offline / Remote split as
+// the other read commands.
+//
+// The key difference from `list` / `search` / `stats` / `diff` / `tree`: those
+// are all cwd-scoped — they only look at the scopes that resolve for the current
+// directory (project / branch / repo / global). `scopes` ignores the current
+// directory entirely and enumerates EVERY scope present in the store, so a user
+// can see all the scopes they have lessons in, anywhere.
+//
+// Offline enumeration is AUTHORITATIVE: it walks the local two-tier store and
+// reads each lesson file's frontmatter `scope` string directly — never reverse-
+// mapping the on-disk directory layout, which is lossy for `project::{name}`
+// (stored by basename only) — so every scope is reconstructed exactly.
+//
+// Remote enumeration is NOT possible: the hosted MCP surface exposes no "list
+// all scopes" tool — every read tool (memory.list / search / read) REQUIRES a
+// scope — so the Remote section is always an honest note (never faked), the same
+// way `stats` omits a cap-usage figure. It still degrades gracefully at exit 0.
+//
+// Graceful, read-only, human-facing (the bin wraps it in `traceCommand`).
+// `LOREKIT_DENY` suppresses a section; `--scope <s>` filters the inventory to
+// scopes whose string contains that substring; `--json` emits `{ offline,
+// remote }`.
+import process from 'node:process';
+import { resolveProjectRoot } from './config.mjs';
+import { resolveDenies } from './control.mjs';
+import { resolveStores, remoteUnavailableReason } from './stores.mjs';
+import { summarizeScopeInventory, filterScopeInventory } from './lessons-view.mjs';
+import { log, heading, status, c } from './util.mjs';
+
+// The honest note the Remote section shows when it isn't denied/unconfigured:
+// the hosted MCP surface simply can't enumerate scopes. Exported so tests can
+// assert the exact wording rather than a fragile substring.
+export const REMOTE_SCOPES_UNSUPPORTED =
+  'remote scope enumeration is not supported by the hosted MCP surface (memory.list requires a scope)';
+
+export async function scopes(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  if (args.store) env.LOREKIT_STORE = args.store;
+
+  // `--scope <s>` is a substring filter over the inventory (NOT a single-scope
+  // selector like the cwd-scoped commands — an inventory of one scope would be
+  // pointless). Absent → the full inventory.
+  const filter = args.scope && typeof args.scope === 'string' ? args.scope : null;
+
+  const { local, remote, connection } = resolveStores(root, {
+    env,
+    endpoint: args.endpoint,
+    token: args.token,
+  });
+
+  // Deny-wins section suppression, identical to `list` / `stats` / `diff`.
+  const { localDenied, remoteDenied } = resolveDenies(root, { env });
+
+  // Offline: the authoritative store-wide enumeration.
+  let offlineSection;
+  if (localDenied) {
+    offlineSection = { available: false, reason: `disabled by deny constraint (${localDenied.source})` };
+  } else {
+    const inventory = filterScopeInventory(await local.listScopes(), filter);
+    offlineSection = { available: true, ...summarizeScopeInventory(inventory) };
+  }
+
+  // Remote: never enumerable. A deny note, an unconfigured note, or the honest
+  // "not supported" note — all graceful (exit 0). Order matches the other
+  // commands' precedence: deny first, then connectivity, then the capability.
+  let remoteSection;
+  if (remoteDenied) {
+    remoteSection = { available: false, reason: `disabled by deny constraint (${remoteDenied.source})` };
+  } else if (!remote.usable()) {
+    remoteSection = { available: false, reason: remoteUnavailableReason(connection) };
+  } else {
+    remoteSection = { available: false, reason: REMOTE_SCOPES_UNSUPPORTED };
+  }
+
+  if (args.json) {
+    log(JSON.stringify(buildJson({ root, filter, offlineSection, remoteSection }), null, 2));
+  } else {
+    heading('LoreKit scopes');
+    log(`  store: ${c.dim(root)}`);
+    if (filter) log(`  filter: ${c.dim(filter)}`);
+    renderScopesSection({ title: 'Offline' }, offlineSection);
+    renderScopesSection(
+      { title: 'Remote', subtitle: remote.usable() ? connection.endpoint : undefined },
+      remoteSection,
+    );
+    log('');
+  }
+
+  // Bounded, non-PII telemetry extras (counts + a boolean) — never a scope
+  // string, path, or token. `remote_available` is always false: the surface
+  // can't enumerate, and saying so is the honest signal.
+  return {
+    exitCode: 0,
+    'lorekit.cli.scopes.offline_scope_count': offlineSection.available ? offlineSection.scopes.length : 0,
+    'lorekit.cli.scopes.offline_total': offlineSection.available ? offlineSection.total : 0,
+    'lorekit.cli.scopes.filtered': Boolean(filter),
+    'lorekit.cli.scopes.remote_available': false,
+  };
+}
+
+// Render one store's inventory: an unavailable note, or a right-aligned
+// `scope   count` table plus a `total` line noting the scope count.
+function renderScopesSection(header, section) {
+  heading(header.title);
+  if (header.subtitle) log(`  ${c.dim(header.subtitle)}`);
+
+  if (!section.available) {
+    status('warn', 'unavailable', section.reason);
+    return;
+  }
+
+  if (!section.scopes.length) {
+    log(`  ${c.dim('no scopes found — the store holds no memories')}`);
+    return;
+  }
+
+  const width = Math.max(0, ...section.scopes.map((s) => String(s.scope).length));
+  for (const s of section.scopes) {
+    log(`  ${c.bold(String(s.scope).padEnd(width))}  ${s.count}`);
+  }
+  const n = section.scopes.length;
+  log(
+    `  ${c.dim('total'.padEnd(width))}  ${c.bold(String(section.total))}  ` +
+      `${c.dim(`(${n} scope${n === 1 ? '' : 's'})`)}`,
+  );
+}
+
+// The `--json` payload: `{ root, filter, offline, remote }` — each store a
+// `{ available, total, scopes: [{ scope, count }] }` record (or an unavailable
+// note), so a script gets the same shape regardless of which store answered.
+function buildJson({ root, filter, offlineSection, remoteSection }) {
+  return {
+    root,
+    filter: filter || null,
+    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.scopes.map((s) => ({ scope: s.scope, count: s.count })),
+  };
+}

package/src/search.mjs

@@ -77,7 +77,7 @@ export async function search(args) {
     log(`  query:   ${c.dim(query)}`);
     log(`  scopes:  ${scopes.join('  →  ')}`);
 
-    const empty = 'no lessons match';
+    const empty = 'no memories match';
     renderSection({ title: 'Offline', empty }, offlineSection);
     renderSection(
       { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined, empty },

package/src/show.mjs

@@ -78,7 +78,7 @@ export async function show(args) {
   if (args.json) {
     log(JSON.stringify(buildJson({ scope, key, offline, remote_, diverged }), null, 2));
   } else {
-    heading('LoreKit lesson');
+    heading('LoreKit memory');
     log(`  scope:  ${c.dim(scope)}`);
     log(`  key:    ${c.dim(key)}`);
 
@@ -95,7 +95,7 @@ export async function show(args) {
     }
     if (!found) {
       log('');
-      log(`  ${c.dim(`no lesson found for ${scope}::${key} in the readable store(s)`)}`);
+      log(`  ${c.dim(`no memory found for ${scope}::${key} in the readable store(s)`)}`);
     }
     log('');
   }

package/src/store/local.mjs

@@ -204,6 +204,53 @@ class LocalStore {
     for (const scope of scopes || []) n += (await this.list({ scope })).entries.length;
     return n;
   }
+
+  // Recursively collect every parsed entry under baseDir, across ALL scopes —
+  // the primitive `listScopes()` builds on. Best-effort: a missing base dir or
+  // an unreadable file is skipped, never thrown. Reads each file's frontmatter
+  // (the authoritative scope string) rather than the directory it sits in.
+  _walkEntries() {
+    const out = [];
+    const walk = (dir) => {
+      let dirents;
+      try {
+        dirents = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        return; // missing / unreadable directory — nothing to enumerate here
+      }
+      for (const d of dirents) {
+        const full = path.join(dir, d.name);
+        if (d.isDirectory()) {
+          walk(full);
+        } else if (d.isFile() && d.name.endsWith('.md')) {
+          try {
+            const entry = parseEntry(fs.readFileSync(full, 'utf8'));
+            if (entry) out.push({ entry, file: full });
+          } catch {
+            // Skip an unreadable file rather than fail the whole enumeration.
+          }
+        }
+      }
+    };
+    walk(this.baseDir);
+    return out;
+  }
+
+  // Enumerate every distinct scope present on disk with its non-archived lesson
+  // count — a STORE-WIDE inventory, independent of any current directory (unlike
+  // list/count, which take an explicit scope set). The scope of each lesson is
+  // read from its frontmatter `scope` field, so the reconstructed scope string
+  // is EXACT — never reverse-mapped from the on-disk directory layout, which is
+  // lossy for `project::{name}` (stored by basename only). Returns
+  // `[{ scope, count }]`, unsorted.
+  async listScopes() {
+    const counts = new Map();
+    for (const { entry } of this._walkEntries()) {
+      if (entry.archived_at || !entry.scope) continue;
+      counts.set(entry.scope, (counts.get(entry.scope) || 0) + 1);
+    }
+    return [...counts.entries()].map(([scope, count]) => ({ scope, count }));
+  }
 }
 
 // A scope string is global when its type segment is `global`.
@@ -326,4 +373,23 @@ class TwoTierStore {
     for (const scope of scopes || []) n += (await this.list({ scope })).entries.length;
     return n;
   }
+
+  // Store-wide scope inventory across both tiers, de-duplicated by scope+key so
+  // a lesson present in both tiers is counted once — project shadows home, the
+  // same first-wins merge `list()` uses. Returns `[{ scope, count }]`, unsorted.
+  async listScopes() {
+    const seen = new Set(); // `${scope}\x00${key}` — dedup across tiers
+    const counts = new Map();
+    const tiers = this.projectActive() ? [this.project, this.home] : [this.home];
+    for (const tier of tiers) {
+      for (const { entry } of tier._walkEntries()) {
+        if (entry.archived_at || !entry.scope) continue;
+        const id = `${entry.scope}\x00${entry.key ?? ''}`;
+        if (seen.has(id)) continue;
+        seen.add(id);
+        counts.set(entry.scope, (counts.get(entry.scope) || 0) + 1);
+      }
+    }
+    return [...counts.entries()].map(([scope, count]) => ({ scope, count }));
+  }
 }

package/src/store/remote.mjs

@@ -112,6 +112,14 @@ class RemoteStore {
     return { ok: true, ...payload };
   }
 
+  // Store-wide scope enumeration is NOT possible against the hosted MCP surface:
+  // every read tool (memory.list / memory.search / memory.read) REQUIRES a
+  // scope, and there is no "list all scopes" tool. Signal that honestly so the
+  // `scopes` command shows a clear note rather than faking an inventory.
+  async listScopes() {
+    return { ok: false, unsupported: true };
+  }
+
   // Connectivity probe for doctor — a transport check, not a memory op.
   async ping() {
     if (!this.usable()) return { ok: false, unusable: true };

package/src/telemetry.mjs

@@ -4,9 +4,9 @@
 // mirrors the Edge Function's SDK-free approach (supabase/functions/_shared/
 // otel.ts): OTLP/JSON over the global fetch (Node 18+), no @opentelemetry/*
 // packages. One span + one counter data point per human-facing command
-// (install / uninstall / doctor / list / search / show / stats / diff / tree /
-// lint / dedupe / migrate), fired to Dash0 so the maintainers can see which
-// commands people actually run.
+// (install / uninstall / doctor / list / search / show / stats / scopes / diff /
+// tree / lint / dedupe / migrate), fired to Dash0 so the maintainers can see
+// which commands people actually run.
 //
 // Privacy — this runs on end-users' machines, so it is deliberately narrow:
 //   • Opt-out honored: LOREKIT_TELEMETRY=0|off|false|no|disable, or the
@@ -25,6 +25,7 @@
 
 import process from 'node:process';
 import { TELEMETRY_TOKEN } from './telemetry-token.mjs';
+import { readLorekitJson } from './config.mjs';
 
 // ── Baked-in defaults (public by design) ──────────────────────────────────────
 // The endpoint is a committed default; the token is injected at publish time
@@ -42,11 +43,13 @@ const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disable', 'disabled']);
 // ── Config resolution ─────────────────────────────────────────────────────────
 
 /**
- * Resolve telemetry config from env + baked-in defaults.
+ * Resolve telemetry config from env + baked-in defaults + .lorekit.json.
  * Returns { enabled: false } when disabled or unconfigured, else the endpoint
  * and headers to export with.
+ * @param {object} [env]  defaults to process.env
+ * @param {object} [repoConfig]  pre-loaded .lorekit.json (optional; read from cwd if absent)
  */
-export function resolveTelemetryConfig(env = process.env) {
+export function resolveTelemetryConfig(env = process.env, repoConfig) {
   const optOut = env.LOREKIT_TELEMETRY;
   if (optOut !== undefined && OFF_VALUES.has(String(optOut).trim().toLowerCase())) {
     return { enabled: false };
@@ -57,6 +60,12 @@ export function resolveTelemetryConfig(env = process.env) {
   if (env.DO_NOT_TRACK && String(env.DO_NOT_TRACK).trim() === '1') {
     return { enabled: false };
   }
+  // `telemetry.disabled: true` in .lorekit.json — team-level opt-out committed
+  // to the repo. Checked after env overrides (env always wins).
+  const cfg = repoConfig !== undefined ? repoConfig : readLorekitJson(process.cwd());
+  if (cfg['telemetry.disabled'] === true) {
+    return { enabled: false };
+  }
 
   const endpoint = (env.OTEL_EXPORTER_OTLP_ENDPOINT || DEFAULT_ENDPOINT || '')
     .trim()
@@ -275,7 +284,7 @@ function normalizeExitCode(result) {
  * counter point. Returns the command's exit code unchanged. Telemetry failures
  * are swallowed — the command result is never affected.
  *
- * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | diff | tree | lint | dedupe | migrate
+ * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | scopes | diff | tree | lint | dedupe | migrate
  * @param {object} args     parsed CLI args (read for allow-listed flags only)
  * @param {string} version  CLI version (from package.json)
  * @param {() => Promise<number>} run  the command handler

package/src/tree.mjs

@@ -107,7 +107,7 @@ function renderTreeSection(header, section) {
 
   const printable = (section.groups || []).filter((g) => g.entries.length || g.error);
   if (!printable.length) {
-    log(`  ${c.dim('no lessons found in the applicable scopes')}`);
+    log(`  ${c.dim('no memories found in the applicable scopes')}`);
     return;
   }