@lorekit/cli 1.53.0 → 1.55.0

package/README.md

@@ -486,6 +486,39 @@ lesson link, `search foo --link` → `/lore?q="foo"` (+ scope), and `list --link
 multi-scope `list`/`tree` view maps to its primary scope. (The same JSON-encoded
 links now back the hooks' write-confirmation and retrospective nudges.)
 
+### `lorekit purge` / `lorekit purge-expired`
+
+The two maintenance sweeps. Both permanently delete rows, and neither can be undone.
+
+```bash
+lorekit purge --retention-days 30 --yes   # hard-delete archived lore older than 30 days
+lorekit purge-expired --yes               # hard-delete every TTL-expired memory
+```
+
+`purge` removes **archived** memories past a retention window — archived lore is
+hidden from reads but recoverable with `lorekit restore`, so this is the step that
+makes it unrecoverable. `purge-expired` removes memories whose `ttl_days` window
+has passed. `--retention-days` accepts 1–365 and defaults to 30; it is validated
+before any request, so an out-of-range or non-integer value fails immediately
+rather than costing a round trip.
+
+**Remote only.** They sweep server-side state and the offline store has no
+equivalent operation, so `--local` is refused with a message rather than quietly
+doing nothing.
+
+**Confirmation, not a dry run.** There is no `--dry-run`, and that is not an
+omission: the purge RPCs return their count only *after* deleting, and the REST
+dry-run header stops before the write with nothing to preview — so "would purge
+N" cannot be answered honestly. Instead an interactive terminal is prompted, and
+**`--yes` is required whenever there is nobody to ask** (a pipe, CI, or `--json`).
+An unattended agent cannot purge by omission.
+
+**Scoped tokens are refused.** A token restricted to specific scopes cannot run
+an account-wide sweep — there is no scope to check and no result set to narrow.
+The server's refusal is printed verbatim with a one-line next step; the CLI makes
+exactly one request and never retries, splits the sweep, or re-scopes around it.
+Use an unscoped `lk_rw_*` / `lk_wo_*` token for maintenance.
+
 ### `lorekit hook`
 
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
@@ -519,9 +552,20 @@ It speaks JSON-RPC 2.0 over newline-delimited stdin/stdout (the MCP stdio
 transport, hand-rolled — zero dependencies) and is **not run by hand**: only
 JSON-RPC frames reach stdout. It serves whatever mode resolves — `local` serves
 the `.lorekit/` files directly, `remote` passes calls through to the hosted
-endpoint, and `off` advertises no tools. Tools advertised: `memory.write`,
-`memory.read`, `memory.list`, `memory.search`, `memory.delete`,
-`memory.archive`.
+endpoint, and `off` advertises no tools.
+
+Tools advertised are **derived from the canonical tool catalog**
+(`packages/schemas/src/tool-catalog.ts`) rather than declared here, so this
+server and the hosted one describe each operation identically. In `local` and
+`remote` mode that is `memory.write`, `memory.read`, `memory.list`,
+`memory.search`, `memory.delete`, `memory.archive`, `memory.restore` and
+`memory.scopes`, plus `org.create`, `org.list`, `org.rename` and `org.delete`
+(which always route to the hosted API). `off` advertises the `org.*` tools only.
+
+An operation the catalog declares but this server cannot back — `memory.purge`,
+`memory.purge_expired` and `memory.list_archived` — carries a recorded reason in
+the catalog's `surfaces.localMcpExempt` field, so the gap is a stated decision
+rather than an omission.
 
 Wire it into `.mcp.json` as an alternative to the `mcp-remote <url>` transport —
 this variant needs no endpoint or token for local mode:
@@ -952,12 +996,13 @@ also returns their headroom against the plan's memory cap.
 | `--mcp-json` | Also write a committable project `.mcp.json` (auth via `${LOREKIT_TOKEN}`, no embedded token) for Claude Code on the web (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
-| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `link`) |
+| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `link` / `purge` / `purge-expired`) |
 | `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe` / `link`; default: all applicable). For `scopes` it is a **substring filter** over the inventory. On `show` / `write` it **names** the scope, overriding the positional |
 | `--key <key>` | Name the key outright (`show` / `write` / `link`) — the way to address a key that itself contains `::` |
 | `--link` | Print the equivalent dashboard deep-link URL instead of running (`show` / `search` / `list` / `tree`) |
 | `--base <url>` | Dashboard base URL for deep links (`link` / `--link`; else `LOREKIT_APP_URL`, default `https://lorekit.io`) |
 | `--threshold <0..1>` | Duplicate-similarity cutoff (`dedupe`; default `0.8`) |
+| `--retention-days <1..365>` | Only purge archived memories older than this (`purge`; default `30`, derived from the tool catalog) |
 | `--adapter <name>` | Host framework for `hook`: `claude` / `cursor` / `codex` |
 | `--event <name>` | Host hook event for `hook` (else read from the stdin payload) |
 | `-h, --help` | Help |

package/bin/lorekit.mjs

@@ -3,26 +3,14 @@
 import process from 'node:process';
 import { readFileSync } from 'node:fs';
 import { parseArgs, log, err, c } from '../src/util.mjs';
-import { install } from '../src/install.mjs';
-import { uninstall } from '../src/uninstall.mjs';
-import { doctor } from '../src/doctor.mjs';
-import { list } from '../src/list.mjs';
-import { search } from '../src/search.mjs';
-import { show } from '../src/show.mjs';
-import { write } from '../src/write.mjs';
-import { archive, del, restore } from '../src/remove.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';
-import { dedupe } from '../src/dedupe.mjs';
-import { link } from '../src/link.mjs';
-import { hook } from '../src/hook.mjs';
-import { migrate } from '../src/migrate.mjs';
-import { bootstrap } from '../src/bootstrap.mjs';
-import { mcpServer } from '../src/mcp-server.mjs';
-import { traceCommand } from '../src/telemetry.mjs';
+// Commands, their handlers, aliases and dispatch properties all come from one
+// registry — see ../src/commands.mjs for why membership lives there and the
+// help prose stays here.
+import { COMMANDS_BY_NAME, STRICT_FLAG_COMMANDS, COMMAND_ALIASES } from '../src/commands.mjs';
+// Catalog-derived, so the default this help PROMISES is the one the server
+// applies — see src/surfaces.generated.mjs.
+import { PURGE_RETENTION_DAYS_DEFAULT } from '../src/surfaces.generated.mjs';
+import { traceCommand, meterCommand } from '../src/telemetry.mjs';
 import { loadDotEnv } from '../src/dotenv.mjs';
 
 // Read the version from package.json so it always matches the published
@@ -92,6 +80,15 @@ ${c.bold('Commands')}
               Explorer (--q / --owner / --tags / --range / --archived);
               --base or LOREKIT_APP_URL override the dashboard host. --json. Pipe it:
               lorekit link | pbcopy.
+  purge       Permanently delete ARCHIVED memories older than --retention-days
+              (default ${PURGE_RETENTION_DAYS_DEFAULT}, range 1-365). Remote only, account-wide and
+              IRREVERSIBLE: prompts for confirmation, and requires --yes when
+              there is no terminal to prompt (a pipe, CI, or --json). A token
+              restricted to specific scopes is refused by the server.
+  purge-expired
+              Permanently delete every TTL-EXPIRED memory. Same posture as
+              purge: remote only, account-wide, irreversible, --yes required
+              non-interactively. Takes no options.
   bootstrap   Apply the BYOD schema to a user-supplied Supabase database.
               Only needed when using LOREKIT_STORAGE_URL / LOREKIT_STORAGE_ANON_KEY.
               See docs/byod.md for setup instructions.
@@ -122,6 +119,9 @@ ${c.bold('Options')}
       --link              Print the equivalent dashboard deep-link URL instead of running (show / search / list / tree)
       --base <url>        Dashboard base URL for deep links (link / --link; else LOREKIT_APP_URL, default https://lorekit.io)
       --threshold <0..1>  Duplicate-similarity cutoff (dedupe; default 0.8)
+      --retention-days <1..365>
+                          Only purge archived memories older than this (purge;
+                          default ${PURGE_RETENTION_DAYS_DEFAULT})
       --from <path>       Source store to migrate from (migrate)
       --to <dest>         Migration destination: home | project | remote (migrate;
                           default routes each entry by scope across the local tiers)
@@ -645,6 +645,149 @@ ${c.bold('Examples')}
   npx @lorekit/cli migrate --from .lorekit --to remote        # preview the push
   npx @lorekit/cli migrate --from .lorekit --to remote --yes  # push local lore up
 `,
+  archive: `${c.bold('lorekit archive')} — hide a memory without losing it
+
+${c.bold('Usage')}
+  lorekit archive <scope::key>
+  lorekit archive <scope> <key>
+  lorekit archive --scope <scope> --key <key>
+
+Soft-archives one memory: it stops appearing in reads and in the hooks' injected
+context, but it is still there and ${c.cyan('lorekit restore')} brings it back. Reach for
+this rather than ${c.cyan('delete')} when a lesson has stopped being true — the record of
+having learned it is usually worth keeping.
+
+Addresses a memory the same three ways ${c.cyan('write')} / ${c.cyan('show')} do, and picks a store with
+the same precedence (remote when usable, else local; ${c.cyan('--remote')} / ${c.cyan('--local')} force it).
+
+${c.bold('Scoped API tokens')}
+Server-side this is scope-authorized: a token restricted to a scope may archive
+every writer's row in that scope, while an unscoped token may only archive its
+own. A no-match is reported as not-found rather than a silent success.
+
+${c.bold('Options')}
+      --scope <scope>     Name the scope explicitly
+      --key <key>         Name the key explicitly — for a key containing \`::\`
+      --remote / --local  Force a store instead of the usual precedence
+      --json              Machine-readable result
+`,
+
+  delete: `${c.bold('lorekit delete')} — archive a memory, or destroy it with --force ${c.dim('(alias: rm)')}
+
+${c.bold('Usage')}
+  lorekit delete <scope::key>            # soft-archive (reversible)
+  lorekit delete <scope::key> --force    # hard-delete (unrecoverable)
+
+Without ${c.cyan('--force')} this is exactly ${c.cyan('lorekit archive')} — the memory is hidden and
+restorable. With ${c.cyan('--force')} the row is gone and no restore can bring it back.
+
+${c.bold('Scoped API tokens')}
+Same scope authorization as ${c.cyan('archive')}: a scope-restricted token may act on any
+writer's row within its scopes, an unscoped one only on its own, and a 0-row
+result is reported as not-found rather than as success.
+
+${c.bold('Options')}
+      --force             Hard-delete instead of archiving. Unrecoverable
+      --scope <scope>     Name the scope explicitly
+      --key <key>         Name the key explicitly — for a key containing \`::\`
+      --remote / --local  Force a store instead of the usual precedence
+      --json              Machine-readable result
+`,
+
+  restore: `${c.bold('lorekit restore')} — bring an archived memory back
+
+${c.bold('Usage')}
+  lorekit restore <scope::key>
+  lorekit restore <scope> <key>
+
+Un-archives a memory so it appears in reads again. The counterpart to
+${c.cyan('archive')} (and to ${c.cyan('delete')} without ${c.cyan('--force')}). A memory that was hard-deleted
+cannot be restored — there is nothing left to restore.
+
+Restoring something that is already active is not an error; it reports that
+nothing changed.
+
+${c.bold('Options')}
+      --scope <scope>     Name the scope explicitly
+      --key <key>         Name the key explicitly — for a key containing \`::\`
+      --remote / --local  Force a store instead of the usual precedence
+      --json              Machine-readable result
+`,
+
+  bootstrap: `${c.bold('lorekit bootstrap')} — apply the LoreKit schema to your own Supabase database
+
+${c.bold('Usage')}
+  lorekit bootstrap [--yes]
+
+For BYOD ("bring your own database") only: creates the tables, functions and
+policies LoreKit needs in a Supabase project you control, so lore never leaves
+your infrastructure. You only need this if you are pointing the CLI at your own
+database via ${c.cyan('LOREKIT_STORAGE_URL')} / ${c.cyan('LOREKIT_STORAGE_ANON_KEY')} — the hosted
+service and the offline store both need nothing here.
+
+See ${c.cyan('docs/byod.md')} for the full setup, including which key to use and what the
+schema contains.
+
+${c.bold('Options')}
+  -y, --yes                Apply without prompting
+      --endpoint <url>     Target endpoint
+      --token <token>      Token for the target
+`,
+
+  purge: `${c.bold('lorekit purge')} — permanently delete archived memories past a retention window
+
+${c.bold('Usage')}
+  lorekit purge [--retention-days <1..365>] [--yes] [--json]
+
+Hard-deletes ARCHIVED memories older than the retention window. Archived lore is
+hidden from reads but recoverable with ${c.cyan('lorekit restore')} — this is what makes it
+unrecoverable, so it is the one step in the lifecycle that cannot be walked back.
+
+${c.bold('Remote only')}
+It sweeps server-side state; the offline store has no equivalent, so ${c.cyan('--local')} is
+refused rather than quietly doing nothing.
+
+${c.bold('Confirmation')}
+There is no dry run: the purge RPC returns its count only AFTER deleting, so
+"would purge N" cannot be answered honestly. Instead you are asked to confirm,
+and ${c.cyan('--yes')} is REQUIRED when there is no terminal to ask (a pipe, CI, or --json)
+— an unattended agent must not be able to purge by omission.
+
+${c.bold('Scoped tokens')}
+A token restricted to specific scopes is refused by the server: an account-wide
+sweep has no scope to check and no result set to narrow. Use an unscoped token
+for maintenance.
+
+${c.bold('Options')}
+      --retention-days <n>  Only purge archived memories older than n days
+                            (1-365, default ${PURGE_RETENTION_DAYS_DEFAULT})
+  -y, --yes                 Confirm; required when non-interactive
+      --json                Machine-readable result ({ ok, purged, error })
+  -e, --endpoint <url>      LoreKit endpoint (else LOREKIT_MCP_URL)
+  -t, --token <token>       LoreKit token (needs write permission, unscoped)
+`,
+
+  'purge-expired': `${c.bold('lorekit purge-expired')} — permanently delete every TTL-expired memory
+
+${c.bold('Usage')}
+  lorekit purge-expired [--yes] [--json]
+
+Hard-deletes memories whose ${c.cyan('ttl_days')} window has passed. Complementary to
+${c.cyan('lorekit purge')}, which removes archived rows: this one removes rows that expired
+on their own. Takes no options of its own — the row set is every expired memory
+you own.
+
+Same posture as ${c.cyan('purge')}: remote only, account-wide, irreversible, confirmation
+required (${c.cyan('--yes')} when non-interactive), and refused for a token restricted to
+specific scopes.
+
+${c.bold('Options')}
+  -y, --yes               Confirm; required when non-interactive
+      --json              Machine-readable result ({ ok, purged, error })
+  -e, --endpoint <url>    LoreKit endpoint (else LOREKIT_MCP_URL)
+  -t, --token <token>     LoreKit token (needs write permission, unscoped)
+`,
+
   hook: `${c.bold('lorekit hook')} — hook engine for Claude Code / Cursor / Codex
 
 ${c.bold('Usage')}
@@ -688,24 +831,12 @@ const KNOWN_FLAGS = [
   // error. It is parsed and discarded (nothing reads `args.view`). Remove it once
   // 1.x links have aged out.
   'link', 'base', 'q', 'owner', 'range', 'archived', 'view',
+  'retention-days',
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
   // Scale-aware survey flags
   'all', 'max', 'since', 'until', 'key-prefix', 'cluster-by-key',
 ];
 
-// Commands that write to disk / talk to the network on a human's behalf. These
-// reject unknown flags; the machine-facing `hook` / `mcp` do not (they must
-// never fail on a stray flag, and only ever receive flags we control).
-const HUMAN_COMMANDS = new Set([
-  'install', 'uninstall', 'doctor', 'list', 'search', 'show', 'stats', 'scopes',
-  'diff', 'tree', 'lint', 'dedupe', 'link', 'migrate', 'write',
-  'archive', 'delete', 'restore',
-]);
-
-// Command aliases — canonicalized before help / dispatch so `lorekit ls --help`
-// and telemetry both resolve to the real command name.
-const COMMAND_ALIASES = { ls: 'list', grep: 'search', resolve: 'tree', url: 'link', rm: 'delete' };
-
 async function main() {
   // Load a `.env` from the current directory (if any) before anything reads the
   // environment — so telemetry config, tokens, and endpoints can come from a
@@ -730,17 +861,25 @@ async function main() {
     return 0;
   }
 
-  // `hook` is machine-facing: it must never print help/errors to stdout
-  // (that would corrupt the JSON the host parses). Handle it before the
-  // usage branch and always resolve to exit 0.
-  if (command === 'hook') {
-    return hook(args);
-  }
-
-  // `mcp` is machine-facing too: only JSON-RPC frames may reach stdout, so it
-  // must bypass the usage branch. It serves stdio until the client closes.
-  if (command === 'mcp') {
-    return mcpServer(args);
+  // Machine-facing commands (`hook`, `mcp`) own their stdout — a host's JSON
+  // contract and JSON-RPC frames respectively — so they must bypass the usage
+  // and version branches, which print. `machine` in the registry is the single
+  // statement of that.
+  //
+  // They stay UNTRACED — a span per agent event is a firehose of near-identical
+  // traces, and these fire several times per turn — but they are no longer
+  // SILENT. `meterCommand` emits the invocation COUNTER only, carrying the same
+  // identity attributes the traced commands do, on a much tighter export budget
+  // (see `METERED_TIMEOUT_MS`). Without it the durable telemetry identity would
+  // differentiate users across `list`/`search`/`stats` while the traffic that
+  // actually dominates — the hooks on every turn — stayed invisible.
+  //
+  // The command runs FIRST and its exit code is returned unchanged: the host's
+  // stdout contract is written by `run` before any export is attempted, and a
+  // telemetry failure can neither alter the exit code nor corrupt the frame.
+  const machineEntry = COMMANDS_BY_NAME.get(command);
+  if (machineEntry?.machine) {
+    return meterCommand(machineEntry.name, VERSION, () => machineEntry.run(args));
   }
 
   if (args.version) {
@@ -755,61 +894,30 @@ async function main() {
 
   // Reject unrecognized flags on human-facing commands with an actionable
   // pointer, rather than silently ignoring a typo that would change behavior.
-  if (HUMAN_COMMANDS.has(command) && args._unknown.length > 0) {
+  if (STRICT_FLAG_COMMANDS.has(command) && args._unknown.length > 0) {
     const plural = args._unknown.length > 1 ? 's' : '';
     err(`${c.red(`Unknown option${plural}:`)} ${args._unknown.join(', ')}`);
     err(`Run ${c.cyan(`lorekit ${command} --help`)} to see valid options.`);
     return 1;
   }
 
-  // Human-facing commands are wrapped so we can see which commands people run
-  // (one OTel span + counter per invocation). `hook` and `mcp` are handled
-  // above and stay uninstrumented — they are machine-facing, fire on every
-  // agent event, and must keep stdout to their host protocol.
-  switch (command) {
-    case 'install':
-      return traceCommand('install', args, VERSION, () => install(args));
-    case 'uninstall':
-      return traceCommand('uninstall', args, VERSION, () => uninstall(args));
-    case 'doctor':
-      return traceCommand('doctor', args, VERSION, () => doctor(args));
-    case 'list':
-      return traceCommand('list', args, VERSION, () => list(args));
-    case 'search':
-      return traceCommand('search', args, VERSION, () => search(args));
-    case 'show':
-      return traceCommand('show', args, VERSION, () => show(args));
-    case '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':
-      return traceCommand('tree', args, VERSION, () => tree(args));
-    case 'lint':
-      return traceCommand('lint', args, VERSION, () => lint(args));
-    case 'dedupe':
-      return traceCommand('dedupe', args, VERSION, () => dedupe(args));
-    case 'link':
-      return traceCommand('link', args, VERSION, () => link(args));
-    case 'migrate':
-      return traceCommand('migrate', args, VERSION, () => migrate(args));
-    case 'bootstrap':
-      return traceCommand('bootstrap', args, VERSION, () => bootstrap(args));
-    case 'write':
-      return traceCommand('write', args, VERSION, () => write(args));
-    case 'archive':
-      return traceCommand('archive', args, VERSION, () => archive(args));
-    case 'delete':
-      return traceCommand('delete', args, VERSION, () => del(args));
-    case 'restore':
-      return traceCommand('restore', args, VERSION, () => restore(args));
-    default:
-      err(`${c.red('Unknown command:')} ${command}\n`);
-      log(HELP);
-      return 1;
+  // Every remaining command is dispatched through `traceCommand`, so one OTel
+  // span and one counter are emitted per invocation without any command wiring
+  // its own — telemetry is INHERITED from this single call site. `hook` and
+  // `mcp` returned above and stay uninstrumented by design.
+  //
+  // This replaced nineteen identical `case` clauses whose only job was to
+  // repeat the command name three times. The registry already knows the name
+  // and the handler, so adding a command needs no edit here at all — which is
+  // what stops the dispatch list and the membership set drifting apart again.
+  const entry = COMMANDS_BY_NAME.get(command);
+  if (!entry) {
+    err(`${c.red('Unknown command:')} ${command}\n`);
+    log(HELP);
+    return 1;
   }
+
+  return traceCommand(entry.name, args, VERSION, () => entry.run(args));
 }
 
 main()

package/package.json

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

package/src/commands.mjs

@@ -0,0 +1,112 @@
+// The command registry — the ONE hand-written statement of what commands exist.
+//
+// Before this file the same list was spelled out four independent times in
+// `bin/lorekit.mjs`: a `switch` with one `case` per command, a `HUMAN_COMMANDS`
+// set, a `COMMAND_ALIASES` map, and the `COMMAND_HELP` keys. Nothing
+// cross-checked them, and they had already disagreed — `bootstrap` was
+// dispatched by the `switch` but missing from `HUMAN_COMMANDS`, so it silently
+// accepted unknown flags where every sibling rejects them.
+//
+// What this file does NOT own: the help prose. `HELP` and `COMMAND_HELP` stay in
+// `bin/lorekit.mjs`, because they are already in exactly one place — moving ~640
+// lines of editorial text here would relocate risk without removing any
+// duplication. What was duplicated is MEMBERSHIP, and membership is what lives
+// here; a guard asserts every entry below has a help entry there.
+//
+// Two independent properties, deliberately not one `human` flag:
+//
+//   traced       — dispatched through `traceCommand`, so one OTel span and one
+//                  counter are emitted per invocation. Telemetry is INHERITED
+//                  from the dispatcher; a command never wires its own.
+//   strictFlags  — rejects unknown options with an actionable pointer instead of
+//                  silently ignoring what might be a typo.
+//
+// `hook` and `mcp` are neither: they are machine-facing, fire on every agent
+// event, and own their stdout (a host's JSON contract / JSON-RPC frames), so a
+// span's cost and an error message's bytes are both unacceptable there. They are
+// marked `machine` and dispatched before the usage branches.
+//
+// `traced: false` does NOT mean unmeasured. The dispatcher routes `machine`
+// commands through `meterCommand`, which emits the invocation COUNTER (with the
+// same identity attributes the traced commands carry) and no span, on a tighter
+// export budget. These two are the highest-volume entry points in the CLI, so
+// leaving them entirely silent meant the usage that dominates was the usage
+// nobody could see — a span each is still the wrong trade, a counter is not.
+
+import { install } from './install.mjs';
+import { uninstall } from './uninstall.mjs';
+import { doctor } from './doctor.mjs';
+import { list } from './list.mjs';
+import { search } from './search.mjs';
+import { show } from './show.mjs';
+import { write } from './write.mjs';
+import { archive, del, restore } from './remove.mjs';
+import { stats } from './stats.mjs';
+import { scopes } from './scopes.mjs';
+import { diff } from './diff.mjs';
+import { tree } from './tree.mjs';
+import { lint } from './lint.mjs';
+import { dedupe } from './dedupe.mjs';
+import { link } from './link.mjs';
+import { hook } from './hook.mjs';
+import { migrate } from './migrate.mjs';
+import { bootstrap } from './bootstrap.mjs';
+import { mcpServer } from './mcp-server.mjs';
+import { purge, purgeExpired } from './purge.mjs';
+
+/**
+ * Every command, in the order the top-level help lists them.
+ *
+ * `tool` binds a command to a catalog operation (`surfaces.cli` in
+ * `packages/schemas/src/tool-catalog.ts`) — the two are cross-checked, so a
+ * catalog op claiming a CLI command that does not exist here fails a test.
+ * `native` marks a command with no catalog operation and says why, which is
+ * most of them: installing, diagnosing and grooming are CLI concerns that no
+ * MCP tool corresponds to.
+ */
+export const COMMANDS = [
+  { name: 'install', run: install, traced: true, strictFlags: true, native: 'scaffolds skills, hooks and MCP config on disk' },
+  { name: 'uninstall', run: uninstall, traced: true, strictFlags: true, native: 'removes what install wrote' },
+  { name: 'doctor', run: doctor, traced: true, strictFlags: true, native: 'connectivity / token / scope health check' },
+  { name: 'list', run: list, traced: true, strictFlags: true, tool: 'memory.list', aliases: ['ls'] },
+  { name: 'search', run: search, traced: true, strictFlags: true, tool: 'memory.search', aliases: ['grep'] },
+  { name: 'show', run: show, traced: true, strictFlags: true, tool: 'memory.read' },
+  { name: 'stats', run: stats, traced: true, strictFlags: true, native: 'local rollup over the resolved store' },
+  { name: 'scopes', run: scopes, traced: true, strictFlags: true, tool: 'memory.scopes' },
+  { name: 'diff', run: diff, traced: true, strictFlags: true, native: 'compares two scopes' },
+  { name: 'tree', run: tree, traced: true, strictFlags: true, native: 'resolves the scope hierarchy for a directory', aliases: ['resolve'] },
+  { name: 'lint', run: lint, traced: true, strictFlags: true, native: 'quality pass over stored lessons' },
+  { name: 'dedupe', run: dedupe, traced: true, strictFlags: true, native: 'near-duplicate detection across a scope' },
+  { name: 'link', run: link, traced: true, strictFlags: true, native: 'builds a dashboard deep link', aliases: ['url'] },
+  { name: 'migrate', run: migrate, traced: true, strictFlags: true, native: 'moves lore between local and remote stores' },
+  { name: 'bootstrap', run: bootstrap, traced: true, strictFlags: true, native: 'seeds a fresh store from a template' },
+  { name: 'write', run: write, traced: true, strictFlags: true, tool: 'memory.write' },
+  { name: 'archive', run: archive, traced: true, strictFlags: true, tool: 'memory.archive' },
+  { name: 'delete', run: del, traced: true, strictFlags: true, tool: 'memory.delete', aliases: ['rm'] },
+  { name: 'restore', run: restore, traced: true, strictFlags: true, tool: 'memory.restore' },
+  { name: 'purge', run: purge, traced: true, strictFlags: true, tool: 'memory.purge' },
+  { name: 'purge-expired', run: purgeExpired, traced: true, strictFlags: true, tool: 'memory.purge_expired' },
+
+  // ── Machine-facing ──────────────────────────────────────────────────────────
+  { name: 'hook', run: hook, traced: false, strictFlags: false, machine: true, native: 'host hook engine — stdout is the host\'s JSON contract' },
+  { name: 'mcp', run: mcpServer, traced: false, strictFlags: false, machine: true, native: 'local stdio MCP server — stdout is JSON-RPC frames' },
+];
+
+/** Command name -> its registry entry. */
+export const COMMANDS_BY_NAME = new Map(COMMANDS.map((entry) => [entry.name, entry]));
+
+/**
+ * Commands that reject unknown options.
+ *
+ * They write to disk or talk to the network on a human's behalf, so a typo'd
+ * flag must be an error rather than a silently ignored argument that changes
+ * what the command does.
+ */
+export const STRICT_FLAG_COMMANDS = new Set(
+  COMMANDS.filter((entry) => entry.strictFlags).map((entry) => entry.name),
+);
+
+/** Alias -> canonical command name, resolved before help, dispatch and telemetry. */
+export const COMMAND_ALIASES = Object.fromEntries(
+  COMMANDS.flatMap((entry) => (entry.aliases ?? []).map((alias) => [alias, entry.name])),
+);

package/src/control.mjs

@@ -513,7 +513,7 @@ function projectDirFrom({ env, userConfig, repoConfig, root }) {
 // `store` override). Used by `migrate` so it works regardless of the active
 // mode. `home` is the per-user tier root; `project` is the opt-in repo tier.
 export function localStoreDirs(root = process.cwd(), env = process.env) {
-  const home = userConfigDir(env);
+  const home = homeRoot(env);
   const userConfig = readJson(path.join(home, 'config.json'));
   const repoConfig = readJson(path.join(root, '.lorekit.json'));
   return { home, project: projectDirFrom({ env, userConfig, repoConfig, root }) };
@@ -534,7 +534,7 @@ export function resolveDenies(root, { env = process.env } = {}) {
 
 // IO wrapper — load env + config files, derive the connection, then resolve.
 export function loadControl(root, { env = process.env } = {}) {
-  const home = userConfigDir(env);
+  const home = homeRoot(env);
   const userConfig = readJson(path.join(home, 'config.json'));
   const repoConfig = readJson(path.join(root, '.lorekit.json'));
   const conn = resolveProjectConnection(root, splitEndpoint);
@@ -545,9 +545,19 @@ export function loadControl(root, { env = process.env } = {}) {
   return resolveControl({ env, userConfig, repoConfig, connection, root, home });
 }
 
-// The per-user home tier root (also holds config.json): $LOREKIT_HOME, default
-// `~/.lorekit`. Moved from the old `~/.agent-memory` location.
-function userConfigDir(env) {
+/**
+ * The per-user home tier root (also holds config.json and telemetry-id.json):
+ * $LOREKIT_HOME, default `~/.lorekit`. Moved from the old `~/.agent-memory`
+ * location.
+ *
+ * Exported because `telemetry-identity.mjs` stores the install id in the same
+ * directory and must resolve it the SAME way. Re-deriving
+ * `LOREKIT_HOME || ~/.lorekit` there would put a second copy of this rule in
+ * the tree, and a drift between them would not fail loudly — it would mint a
+ * fresh "install" for a user who already had one, in a directory unrelated to
+ * their store.
+ */
+export function homeRoot(env = process.env) {
   return env.LOREKIT_HOME || path.join(os.homedir(), '.lorekit');
 }
 

package/src/doctor.mjs

@@ -23,6 +23,7 @@ import {
   resolveTelemetryTokenSource,
   probeTelemetryExport,
 } from './telemetry.mjs';
+import { describeIdentity } from './telemetry-identity.mjs';
 import { deriveScope } from './scope.mjs';
 import { loadControl, HOOK_INSTRUCTION_EVENTS } from './control.mjs';
 import { createStore } from './store/index.mjs';
@@ -537,6 +538,23 @@ async function checkTelemetryExport(args, root, record) {
 
   record('info', 'telemetry', `export on → ${config.endpoint} ${c.dim(`(credential from ${source})`)}`);
 
+  // What identity the exported telemetry carries, and where it lives. Reported
+  // because the id is otherwise invisible: it is minted silently on first run,
+  // and a user who wants to see or reset it needs the path. `describeIdentity`
+  // never mints, so running `doctor` cannot itself create the file — the line
+  // below reads "not yet minted" on a machine that has only ever run `doctor`.
+  const identity = describeIdentity();
+  const linked = identity.accountId
+    ? `account ${identity.accountId}`
+    : 'no account linked yet — any authenticated command links it';
+  record(
+    'info',
+    'telemetry',
+    identity.installId
+      ? `identity: install ${identity.installId} · ${linked} ${c.dim(`(${identity.file} — delete to reset)`)}`
+      : `identity: not yet minted ${c.dim(`(will be written to ${identity.file})`)}`,
+  );
+
   // The probe writes a real span to a real backend — only on explicit request.
   if (!required) return;