@lorekit/cli 1.56.0 → 1.57.0

package/bin/lorekit.mjs

@@ -110,6 +110,10 @@ ${c.bold('Commands')}
               resolved store (local .lorekit/ offline, or remote passthrough) so
               .mcp.json can point at the CLI instead of mcp-remote. Speaks
               JSON-RPC on stdin/stdout — not run by hand.
+  completion  Print a shell completion script for zsh or fish. Pipe it to your
+              shell's completion dir, or let \`install --completions\` wire it for
+              you. Completes commands, per-command flags, and — from the local
+              store — scopes and scope::key addresses.
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
@@ -141,6 +145,7 @@ ${c.bold('Options')}
       --no-hooks          Skip wiring the lifecycle hooks (install)
       --mcp-json          Also write a committable project .mcp.json for Claude Code on
                           the web — auth via \${LOREKIT_TOKEN}, no embedded secret (install)
+      --completions <s>   Install shell completion: auto | zsh | fish | none (install)
       --force             Overwrite existing skill files (install)
       --deep              Do a write→read→delete round-trip (doctor)
       --telemetry         Verify the OTLP export credential works (doctor)
@@ -217,6 +222,10 @@ ${c.bold('Options')}
       --no-hooks          Skip wiring the lifecycle hooks (leaves existing ones alone)
       --mcp-json          Also write a committable project .mcp.json (\${LOREKIT_TOKEN} auth)
                           for Claude Code on the web — always the repo-root file
+      --completions <s>   Install shell completion: auto (detect \$SHELL) | zsh | fish | none.
+                          Interactive runs prompt; non-interactive ones skip it unless
+                          this flag is passed. zsh adds a guarded block to ~/.zshrc; fish
+                          drops a file in ~/.config/fish/completions (auto-loaded).
       --force             Overwrite existing skill files
   -y, --yes               Non-interactive; never prompt (defaults to --project, and to the
                           already-wired hooks — all on a fresh install)
@@ -228,6 +237,7 @@ ${c.bold('Examples')}
   npx @lorekit/cli install --global --mcp-json --yes # local CLI + committable web config
   npx @lorekit/cli install --hooks read-only --yes
   npx @lorekit/cli install --no-hooks --yes
+  npx @lorekit/cli install --completions auto --yes  # detect \$SHELL and wire completion
 `,
   uninstall: `${c.bold('lorekit uninstall')} — reverse install for the chosen scope
 
@@ -856,6 +866,30 @@ Machine-facing: exposes the memory.* tools backed by the resolved store (local
 .lorekit/ offline, or remote passthrough) over JSON-RPC on stdin/stdout, so
 .mcp.json can point at the CLI instead of mcp-remote. Not run by hand.
 
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+`,
+  completion: `${c.bold('lorekit completion')} — print a shell completion script
+
+${c.bold('Usage')}
+  lorekit completion <zsh|fish>
+
+Prints the completion script for the given shell to stdout. It completes command
+names and aliases, each command's own flags, and — read live from the LOCAL
+store — scope values (\`--scope\`) and \`scope::key\` addresses (\`show\`, \`write\`,
+\`archive\`, \`delete\`, \`restore\`, \`link\`). Dynamic completion is offline: it never
+prompts for a token or hits the network, so a remote-only scope will not appear.
+
+The easiest way to install it is ${c.cyan('lorekit install --completions auto')}, which
+detects your shell and wires it up. To do it by hand:
+
+${c.bold('zsh')}
+  lorekit completion zsh > ~/.zsh/completions/_lorekit
+  # ensure that dir is on \$fpath before \`compinit\` in ~/.zshrc
+
+${c.bold('fish')}
+  lorekit completion fish > ~/.config/fish/completions/lorekit.fish
+
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
 `,
@@ -866,7 +900,7 @@ ${c.bold('Options')}
 // typo like `--gloabl` should fail loudly, not quietly fall back to --project.
 const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
-  'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'mcp-json', 'force', 'deep', 'adapter',
+  'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'mcp-json', 'completions', 'complete', 'force', 'deep', 'adapter',
   'event', 'json', 'scope', 'key', 'threshold', 'help', 'version', 'telemetry',
   'value', 'tags', 'source-agent', 'trigger', 'kind', 'host', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
   // `view` is accepted-and-IGNORED, not documented: the Explorer dropped the

package/package.json

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

package/src/commands/completion.mjs

@@ -0,0 +1,68 @@
+// `lorekit completion <zsh|fish>` — print a shell completion script.
+//
+// The generated scripts (see ../shared/completions.mjs) call back into this
+// command for DYNAMIC values: `lorekit completion --complete scope` lists the
+// scopes in the local store, `--complete key` lists `scope::key` addresses. That
+// callback fires on every TAB, which is why `completion` is a MACHINE command in
+// the registry — its stdout is a contract a shell parses (a script or a
+// newline-delimited candidate list), and it is metered, not traced, exactly like
+// `hook` / `mcp`. A span per keypress would be a firehose.
+//
+// Dynamic completion reads the LOCAL store only. It is deliberately offline: a
+// TAB must be instant and must never prompt for a token or hit the network, so a
+// scope that lives only in the remote store will not complete — a worthwhile
+// trade for a completion that never blocks the prompt.
+import process from 'node:process';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { resolveStores } from '../shared/stores.mjs';
+import { log, err, c } from '../shared/util.mjs';
+import { COMPLETION_SHELLS, renderCompletion } from '../shared/completions.mjs';
+
+export async function completion(args) {
+  // Dynamic candidate mode: emit newline-delimited candidates for the shell to
+  // consume, then exit. Any failure degrades to an empty list (exit 0) so a
+  // broken store never surfaces an error at the prompt.
+  if (args.complete !== undefined) {
+    return emitCandidates(args);
+  }
+
+  const shell = typeof args._?.[1] === 'string' ? args._[1] : null;
+  if (!shell) {
+    err(`${c.red('Missing shell.')} Usage: lorekit completion <${COMPLETION_SHELLS.join('|')}>`);
+    return 1;
+  }
+  if (!COMPLETION_SHELLS.includes(shell)) {
+    err(`${c.red(`Unsupported shell: ${shell}.`)} Supported: ${COMPLETION_SHELLS.join(', ')}`);
+    err(`Run ${c.cyan('lorekit install --completions ' + shell)} to install it, or pipe this to your shell's completion dir.`);
+    return 1;
+  }
+
+  log(renderCompletion(shell));
+  return 0;
+}
+
+// Emit the candidate list for `--complete <kind>`. `scope` → distinct scope
+// strings; `key` → `scope::key` addresses. Best-effort and offline.
+async function emitCandidates(args) {
+  const kind = typeof args.complete === 'string' ? args.complete : '';
+  try {
+    const root = resolveProjectRoot(args.dir);
+    const { local } = resolveStores(root, { env: process.env });
+    const inventory = await local.listScopes();
+
+    if (kind === 'scope') {
+      for (const { scope } of inventory) log(scope);
+      return 0;
+    }
+    if (kind === 'key') {
+      for (const { scope } of inventory) {
+        const res = await local.list({ scope });
+        for (const entry of res.entries ?? []) log(`${scope}::${entry.key}`);
+      }
+      return 0;
+    }
+  } catch {
+    // Swallow — an unreadable store yields no candidates, never a prompt error.
+  }
+  return 0;
+}

package/src/commands/hook.mjs

@@ -36,6 +36,32 @@ import { codex } from '../adapters/codex.mjs';
 
 const ADAPTERS = { claude, cursor, codex };
 
+/**
+ * Bounded health vocabulary for the hook heartbeat. The hook always exits 0, so
+ * these are the only witness that a fire did its work: `ok` (ran clean),
+ * `store_unavailable` (no usable store to read/query), `degraded` (a store
+ * lookup threw and was swallowed — the host still got its output), `crash` (an
+ * unexpected throw the outer guard caught). Kept small so `lorekit.hook.outcome`
+ * stays a low-cardinality metric label.
+ */
+const HOOK_OUTCOME = Object.freeze({
+  OK: 'ok',
+  STORE_UNAVAILABLE: 'store_unavailable',
+  DEGRADED: 'degraded',
+  CRASH: 'crash',
+});
+
+/**
+ * Map the mutable meter run() fills in to the bounded, non-PII counter
+ * dimensions. `event` is the host hook event (SessionStart / Stop / …), itself a
+ * small set; both labels are safe for a metric.
+ */
+function hookMeterAttrs(meter) {
+  const attrs = { 'lorekit.hook.outcome': meter.outcome };
+  if (meter.event) attrs['lorekit.hook.event'] = meter.event;
+  return attrs;
+}
+
 function readStdin() {
   return new Promise((resolve) => {
     let data = '';
@@ -48,15 +74,22 @@ function readStdin() {
 }
 
 export async function hook(args) {
+  // The meter run() fills in as it goes. Returned alongside the exit code so the
+  // metric-only dispatch (`meterCommand`) can count this fire with its health —
+  // the hook always exits 0, so this is the only signal a broken or degrading
+  // hook produces.
+  const meter = { event: null, outcome: HOOK_OUTCOME.OK };
   // Guarded so any unexpected error still exits 0 (never break the host agent).
   try {
-    return await run(args);
+    const exitCode = await run(args, meter);
+    return { exitCode, meter: hookMeterAttrs(meter) };
   } catch {
-    return 0;
+    meter.outcome = HOOK_OUTCOME.CRASH;
+    return { exitCode: 0, meter: hookMeterAttrs(meter) };
   }
 }
 
-async function run(args) {
+async function run(args, meter) {
   const adapter = ADAPTERS[args.adapter];
   if (!adapter) {
     // Unknown adapter: stay silent, don't disrupt the host.
@@ -81,6 +114,8 @@ async function run(args) {
 
   if (!event) return 0;
 
+  meter.event = event;
+
   const intent = adapter.intentFor(event);
   if (intent === 'noop') return 0;
 
@@ -110,6 +145,8 @@ async function run(args) {
       ? control.hooksInstructions.SessionStart : null;
     if (!store) {
       // No store: emit a minimal header + instruction when present, then return.
+      // A SessionStart that cannot read lore is the highest-value failure to see.
+      meter.outcome = HOOK_OUTCOME.STORE_UNAVAILABLE;
       if (sessionInstruction) {
         emit(formatLessons(null, { repoScope: null }, { instruction: sessionInstruction }));
       }
@@ -163,7 +200,7 @@ async function run(args) {
 
     try {
       const store = createStore(control);
-      if (!store) return 0;
+      if (!store) { meter.outcome = HOOK_OUTCOME.STORE_UNAVAILABLE; return 0; }
       const lessons = await promptLessonsFromStore(store, scope, terms, {
         // Delta only. Includes the SessionStart set, because "already shown"
         // has to mean shown by anything — a hook that only remembered its own
@@ -183,7 +220,9 @@ async function run(args) {
       }));
     } catch {
       // Best-effort, like every other branch: the user's turn proceeds either
-      // way, and a store hiccup must never cost them their prompt.
+      // way, and a store hiccup must never cost them their prompt — but record
+      // that the lookup degraded so a store that always throws is visible.
+      meter.outcome = HOOK_OUTCOME.DEGRADED;
     }
     return 0;
   }
@@ -210,6 +249,7 @@ async function run(args) {
       }
     } catch {
       // best-effort — never break the host
+      meter.outcome = HOOK_OUTCOME.DEGRADED;
     }
     return 0;
   }
@@ -224,6 +264,7 @@ async function run(args) {
     let relevant = null;
     try {
       const store = createStore(control);
+      if (!store) meter.outcome = HOOK_OUTCOME.STORE_UNAVAILABLE;
       if (store) {
         // QUERY the store across the scope hierarchy for lessons matching this
         // failure — not a post-filter of the SessionStart-injected set, which
@@ -235,6 +276,7 @@ async function run(args) {
       }
     } catch {
       relevant = null; // never let a lesson lookup break the failure nudge
+      meter.outcome = HOOK_OUTCOME.DEGRADED;
     }
     const nudge = failureNudge(parsed.toolName, scope, control);
     emit(relevant ? `${relevant}\n\n${nudge}` : nudge);

package/src/commands/install.mjs

@@ -29,6 +29,7 @@ import {
 } from '../shared/config.mjs';
 import { buildRemoteUrl, splitEndpoint } from '../shared/mcp.mjs';
 import { deriveScope } from '../shared/scope.mjs';
+import { COMPLETION_SHELLS, detectShell, installCompletion } from '../shared/completions.mjs';
 import { log, heading, status, select, err, c } from '../shared/util.mjs';
 
 // The MCP server URL is fixed — there is only one hosted LoreKit endpoint.
@@ -179,6 +180,25 @@ function requestedHookMode(args) {
   return null;
 }
 
+// Shell-completion install modes for `--completions`. `auto` detects the shell
+// from $SHELL; a shell name installs that one; `none` skips. Kept a small closed
+// set so a typo fails loudly rather than silently doing nothing.
+export const COMPLETION_MODES = ['auto', 'none', ...COMPLETION_SHELLS];
+
+// Same sentinel discipline as INVALID_HOOK_MODE: a bare or empty `--completions`
+// is a usage error, not an absent flag, so it never silently falls through to
+// the interactive/skip default.
+export const INVALID_COMPLETION_MODE = '(missing value)';
+
+// Resolve the requested completion mode from the flag, or null when it was not
+// passed (the caller then prompts interactively / skips non-interactively).
+export function requestedCompletionMode(args) {
+  const raw = args.completions;
+  if (typeof raw === 'string' && raw.trim()) return raw.trim().toLowerCase();
+  if (raw !== undefined && raw !== false) return INVALID_COMPLETION_MODE;
+  return null;
+}
+
 export async function install(args) {
   const root = resolveProjectRoot(args.dir);
   const nonInteractive = Boolean(args.yes) || !process.stdin.isTTY;
@@ -206,6 +226,21 @@ export async function install(args) {
   // write step even when the scope is already fully installed.
   const writeWebMcpJson = Boolean(args['mcp-json']);
 
+  // Validate `--completions` up front, same discipline as `--hooks`.
+  const requestedCompletion = requestedCompletionMode(args);
+  if (requestedCompletion === INVALID_COMPLETION_MODE) {
+    err(`\n  --completions needs a mode. Valid modes: ${COMPLETION_MODES.join(' | ')}.`);
+    return 1;
+  }
+  if (requestedCompletion !== null && !COMPLETION_MODES.includes(requestedCompletion)) {
+    err(`\n  Unknown --completions mode "${requestedCompletion}". Valid modes: ${COMPLETION_MODES.join(' | ')}.`);
+    return 1;
+  }
+  // An explicit request to install completion (auto / zsh / fish) must reach the
+  // completion step even on an otherwise complete install. `none` is skip-only,
+  // like `--no-hooks`, so it never justifies the bypass.
+  const completionsExplicit = requestedCompletion !== null && requestedCompletion !== 'none';
+
   heading('LoreKit install');
   log(`  project: ${c.dim(root)}`);
 
@@ -231,7 +266,7 @@ export async function install(args) {
 
   const wiredEvents = installedHookEvents(root, scope);
 
-  if (currentState.isFullyInstalled && !force && !hooksFlagExplicit && !writeWebMcpJson) {
+  if (currentState.isFullyInstalled && !force && !hooksFlagExplicit && !writeWebMcpJson && !completionsExplicit) {
     // Surface a clear, useful already-installed summary.
     log('');
     log(
@@ -474,6 +509,52 @@ export async function install(args) {
     hooks = upsertClaudeHooks(root, scope, resolveHookRunner(), hookEvents);
   }
 
+  // 5c. Shell completion — independent of the project/global scope above, since
+  //     completion lives in the user's shell config, not a repo. Resolve the
+  //     target shell, then write the script (fish auto-loads its dir; zsh gets a
+  //     guarded ~/.zshrc block). Opt-in by default: an interactive run prompts
+  //     for the detected shell, a non-interactive one skips unless
+  //     `--completions` was passed — writing to a shell rc unprompted would be
+  //     too invasive for a plain `install --yes`.
+  let completionResult = null;
+  let completionShell = null;
+  let completionSkipReason = null;
+  {
+    let mode = requestedCompletion; // 'auto' | 'zsh' | 'fish' | 'none' | null
+    if (mode === null) {
+      if (nonInteractive) {
+        mode = 'none';
+      } else {
+        const detected = detectShell(process.env);
+        if (!detected) {
+          completionSkipReason = 'shell not detected ($SHELL is not zsh or fish)';
+          mode = 'none';
+        } else {
+          log('');
+          const answer = await select(`Install ${detected} shell completion?`, [
+            { label: 'Yes', value: 'yes', hint: `write the ${detected} completion and wire it up` },
+            { label: 'No', value: 'no', hint: 'skip — add it later with `lorekit completion`' },
+          ]);
+          mode = answer === 'yes' ? detected : 'none';
+        }
+      }
+    }
+    if (mode === 'auto') {
+      const detected = detectShell(process.env);
+      if (detected) completionShell = detected;
+      else completionSkipReason = 'shell not detected ($SHELL is not zsh or fish)';
+    } else if (mode === 'zsh' || mode === 'fish') {
+      completionShell = mode;
+    }
+    if (completionShell) {
+      try {
+        completionResult = installCompletion(completionShell, { home: homeDir() });
+      } catch (e) {
+        completionSkipReason = e.message;
+      }
+    }
+  }
+
   // Show global paths relative to ~ (a repo-relative path would be a mess of
   // ../../); project paths stay repo-relative.
   const display = (p) =>
@@ -550,6 +631,21 @@ export async function install(args) {
     );
   }
 
+  // Shell completion always lives under ~, so show it relative to home
+  // regardless of the install scope.
+  const homeDisplay = (p) => p.replace(homeDir(), '~');
+  if (completionResult) {
+    const where = completionResult.autoloaded
+      ? `${homeDisplay(completionResult.file)} — auto-loaded by fish`
+      : `${homeDisplay(completionResult.file)}${completionResult.rcUpdated ? ' + ~/.zshrc block' : ''}`;
+    status('pass', `completion ${completionResult.shell}`, `${where}; open a new shell to use it`);
+  } else if (completionShell) {
+    // A shell was resolved but the write failed — surface why, don't stay silent.
+    status('warn', 'completion', completionSkipReason || 'not installed');
+  } else if (completionSkipReason) {
+    status('info', 'completion', `skipped — ${completionSkipReason}; add it with \`lorekit completion\``);
+  }
+
   const kind = tokenKind(token);
   if (scopeWriteOwnedByWeb) {
     // `--project --mcp-json`: the committable web .mcp.json is the ONLY config
@@ -615,5 +711,11 @@ export async function install(args) {
   // Bounded, non-PII: which of the three presets this run landed on. Counting
   // the `--no-hooks` FLAG (as telemetry already did) says nothing about what a
   // user picks when actually asked, which is the whole point of the prompt.
-  return { exitCode: 0, 'lorekit.cli.hooks_mode': hookMode };
+  // `completions` records the shell wired (or 'none') — a bounded enum, never a
+  // path.
+  return {
+    exitCode: 0,
+    'lorekit.cli.hooks_mode': hookMode,
+    'lorekit.cli.completions': completionResult ? completionResult.shell : 'none',
+  };
 }

package/src/commands/uninstall.mjs

@@ -13,6 +13,7 @@ import {
   removeClaudeHooks,
   homeDir,
 } from '../shared/config.mjs';
+import { COMPLETION_SHELLS, removeCompletion } from '../shared/completions.mjs';
 import { log, heading, status, c } from '../shared/util.mjs';
 
 function ask(question) {
@@ -67,10 +68,20 @@ export async function uninstall(args) {
   // "nothing to remove", other servers in the file are preserved.
   const webMcp = scope === 'global' ? attempt(() => removeWebMcpServer(root)) : null;
   const hooks = attempt(() => removeClaudeHooks(root, scope));
+  // Shell completion is a single user-level artefact (not project/global
+  // scoped), so tear it down for every supported shell regardless of the chosen
+  // scope. Each `removeCompletion` touches only lorekit's own script file and
+  // guarded ~/.zshrc block, so it never disturbs a hand-written completion.
+  const completions = COMPLETION_SHELLS.map((shell) => ({
+    shell,
+    step: attempt(() => removeCompletion(shell, { home: homeDir() })),
+  }));
 
   // Global paths shown relative to ~; project paths repo-relative.
   const display = (p) =>
     scope === 'global' ? p.replace(homeDir(), '~') : path.relative(root, p) || p;
+  // Completion artefacts always live under ~, whatever the uninstall scope.
+  const homeDisplay = (p) => p.replace(homeDir(), '~');
   const mcpLabel = scope === 'global' ? '~/.claude.json' : '.mcp.json';
 
   heading('Done');
@@ -95,15 +106,23 @@ export async function uninstall(args) {
     done: (r) => `${r.removed} removed → ${display(r.file)}`,
     noop: 'no lorekit hooks — nothing to remove',
   });
+  for (const { shell, step } of completions) {
+    report(step, `completion ${shell}`, {
+      done: (r) => `removed → ${homeDisplay(r.file)}${r.rcUpdated ? ' + ~/.zshrc block' : ''}`,
+      noop: 'not installed — nothing to remove',
+    });
+  }
 
   const skillStepList = skillSteps.map((s) => s.step);
   const webSteps = webMcp ? [webMcp] : [];
-  const failed = [...skillStepList, mcp, ...webSteps, hooks].some((s) => !s.ok);
+  const completionSteps = completions.map((s) => s.step);
+  const failed = [...skillStepList, mcp, ...webSteps, hooks, ...completionSteps].some((s) => !s.ok);
   const any =
     (skillStepList.some((s) => s.result?.removed) ||
       mcp.result?.removed ||
       webMcp?.result?.removed ||
-      hooks.result?.removed) && true;
+      hooks.result?.removed ||
+      completionSteps.some((s) => s.result?.removed)) && true;
 
   if (failed) {
     log(`\n  ${c.dim('Some items could not be removed and were left untouched — see above.')}`);

package/src/commands.mjs

@@ -54,6 +54,7 @@ import { migrate } from './commands/migrate.mjs';
 import { bootstrap } from './commands/bootstrap.mjs';
 import { mcpServer } from './commands/mcp-server.mjs';
 import { purge, purgeExpired } from './commands/purge.mjs';
+import { completion } from './commands/completion.mjs';
 
 /**
  * Every command, in the order the top-level help lists them.
@@ -90,6 +91,11 @@ export const COMMANDS = [
   { name: 'purge-expired', run: purgeExpired, traced: true, strictFlags: true, tool: 'memory.purge_expired' },
 
   // ── Machine-facing ──────────────────────────────────────────────────────────
+  // `completion` is machine-facing for the same reason hook/mcp are: its stdout
+  // is a contract a shell parses — a completion SCRIPT, or (on the `--complete`
+  // callback the scripts fire on every TAB) a newline-delimited candidate list.
+  // A span per keypress would be a firehose, so it is metered, never traced.
+  { name: 'completion', run: completion, traced: false, strictFlags: false, machine: true, native: 'prints shell completion scripts — stdout is a shell contract' },
   { 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' },
 ];

package/src/shared/completions.mjs

@@ -0,0 +1,471 @@
+// Shell completion: the ONE place the completion SURFACE is described, and the
+// helpers that write / remove the generated scripts on disk.
+//
+// The `completion` command (src/commands/completion.mjs), `install` and
+// `uninstall` all build on this module. It is deliberately dependency-light — it
+// does NOT import the command registry (commands.mjs), because `install` imports
+// this module and commands.mjs imports `install`, so pulling the registry in
+// here would close an import cycle. The registry stays the source of truth for
+// which commands EXIST; a test (test/completion.test.mjs) cross-checks that this
+// spec covers every human command and references only real flags, so the two
+// can never silently drift.
+import fs from 'node:fs';
+import path from 'node:path';
+import { homeDir, writeFileAtomic } from './config.mjs';
+
+// Shells we generate for. zsh and fish were the request; bash is intentionally
+// absent (its completion model is fiddlier and nobody asked). Adding one is a
+// new renderer plus a `completionTargets` case — nothing else changes.
+export const COMPLETION_SHELLS = ['zsh', 'fish'];
+
+// Flag metadata, shared across commands so a flag's description and value-type
+// are stated once. `arg` names the value a flag takes (absent ⇒ a boolean flag
+// that takes none); `complete` selects a DYNAMIC candidate source the generated
+// script calls back for; `values` is a STATIC candidate list; `short` is the
+// one-letter alias. Kept terse on purpose — these strings land verbatim in the
+// completion scripts a user reads.
+const FLAG = {
+  dir: { desc: 'Target project root', arg: 'dir', short: 'd' },
+  project: { desc: 'Install/act for this project only' },
+  global: { desc: 'Install/act for every project (~/.claude)' },
+  endpoint: { desc: 'Remote endpoint override', arg: 'url', short: 'e' },
+  token: { desc: 'Remote token override', arg: 'token', short: 't' },
+  mode: { desc: 'Override the resolved mode', arg: 'mode', values: ['off', 'local', 'remote'] },
+  store: { desc: 'Local project-tier store directory', arg: 'dir' },
+  from: { desc: 'Source store / range start', arg: 'path' },
+  to: { desc: 'Destination / range end', arg: 'dest' },
+  apply: { desc: 'Apply the migration (alias of --yes)' },
+  yes: { desc: 'Non-interactive; never prompt', short: 'y' },
+  hooks: { desc: 'Lifecycle hooks to wire', arg: 'mode', values: ['all', 'read-only', 'none'] },
+  'no-hooks': { desc: 'Skip wiring the lifecycle hooks' },
+  'mcp-json': { desc: 'Also write a committable project .mcp.json' },
+  completions: { desc: 'Install shell completion', arg: 'shell', values: ['auto', 'zsh', 'fish', 'none'] },
+  force: { desc: 'Overwrite / hard-delete' },
+  deep: { desc: 'Do a write→read→delete round-trip' },
+  telemetry: { desc: 'Verify the OTLP export credential works' },
+  json: { desc: 'Machine-readable output' },
+  scope: { desc: 'Restrict to / name a scope', arg: 'scope', complete: 'scope' },
+  key: { desc: 'Name the key explicitly', arg: 'key' },
+  threshold: { desc: 'Duplicate-similarity cutoff (0..1)', arg: 'n' },
+  'cluster-by-key': { desc: 'Cluster by shared key capture', arg: 'regex' },
+  value: { desc: 'Memory value', arg: 'text' },
+  tags: { desc: 'Comma-separated tags', arg: 'a,b,c' },
+  'source-agent': { desc: 'Source agent name to record', arg: 'name' },
+  trigger: { desc: 'Trigger context slug', arg: 'slug' },
+  'ttl-days': { desc: 'Days until auto-expiry (1..365)', arg: 'n' },
+  'clear-ttl': { desc: 'Remove any existing expiry' },
+  org: { desc: "Write to this org's scope (remote)", arg: 'slug' },
+  'origin-repo': { desc: 'Override the provenance repository', arg: 'owner/name' },
+  'origin-branch': { desc: 'Override the provenance branch', arg: 'branch' },
+  'origin-commit': { desc: 'Override the provenance commit', arg: 'sha' },
+  'origin-pr': { desc: 'The pull request this came out of', arg: 'n' },
+  'no-origin': { desc: 'Record no provenance at all' },
+  remote: { desc: 'Force the remote store' },
+  local: { desc: 'Force the local offline store' },
+  link: { desc: 'Print the dashboard deep-link URL instead' },
+  base: { desc: 'Dashboard base URL for deep links', arg: 'url' },
+  q: { desc: 'Pre-fill the Explorer search box', arg: 'text' },
+  owner: { desc: 'Ownership filter', arg: 'owner' },
+  range: { desc: 'Date range as JSON', arg: 'json' },
+  archived: { desc: 'Include archived memories' },
+  'retention-days': { desc: 'Only purge archived older than n days', arg: 'n' },
+  files: { desc: 'Changed files to check', arg: 'path' },
+  strict: { desc: 'Exit non-zero on any unmet obligation' },
+};
+
+// Every command's completion shape, in the top-level help order. `flags` lists
+// the flag NAMES (keys of FLAG) a command accepts; `positional` names the kind
+// of first positional argument, which drives dynamic value completion:
+//   'address' → a `scope::key` (dynamic, from the local store)
+//   'query'   → free text (no completion)
+//   'shell'   → the `completion` command's zsh|fish argument
+// `values` overrides a flag's static candidate list for this command only
+// (migrate's `--to` is an enum here but a free date elsewhere).
+const COMMANDS = [
+  { name: 'install', summary: 'Scaffold skills, wire the MCP server, install hooks',
+    flags: ['dir', 'project', 'global', 'endpoint', 'token', 'hooks', 'no-hooks', 'mcp-json', 'completions', 'force', 'yes'] },
+  { name: 'uninstall', summary: 'Reverse install for the chosen scope',
+    flags: ['dir', 'project', 'global', 'yes'] },
+  { name: 'doctor', summary: 'Verify the install, connectivity, token, scope',
+    flags: ['dir', 'mode', 'endpoint', 'token', 'store', 'deep', 'telemetry'] },
+  { name: 'list', summary: 'List memories for the current directory', aliases: ['ls'],
+    flags: ['dir', 'scope', 'json', 'endpoint', 'token', 'store', 'link', 'base'] },
+  { name: 'search', summary: 'Full-text search the applicable memories', aliases: ['grep'],
+    positional: 'query',
+    flags: ['dir', 'scope', 'json', 'endpoint', 'token', 'store', 'link', 'base'] },
+  { name: 'show', summary: 'Inspect one memory in full', positional: 'address',
+    flags: ['dir', 'json', 'endpoint', 'token', 'store', 'scope', 'key', 'link', 'base'] },
+  { name: 'stats', summary: 'Count memories per scope and store',
+    flags: ['dir', 'scope', 'json', 'endpoint', 'token', 'store'] },
+  { name: 'scopes', summary: 'Inventory every distinct scope',
+    flags: ['dir', 'scope', 'json', 'endpoint', 'token', 'store'] },
+  { name: 'diff', summary: 'Compare the offline and remote stores',
+    flags: ['dir', 'scope', 'json', 'endpoint', 'token', 'store'] },
+  { name: 'tree', summary: 'Show scope precedence and which memory wins', aliases: ['resolve'],
+    flags: ['dir', 'scope', 'json', 'endpoint', 'token', 'store', 'link', 'base'] },
+  { name: 'lint', summary: 'Flag low-quality memories (CI gate)',
+    flags: ['dir', 'scope', 'json', 'endpoint', 'token', 'store'] },
+  { name: 'dedupe', summary: 'Find likely-duplicate memories',
+    flags: ['dir', 'scope', 'threshold', 'cluster-by-key', 'json', 'endpoint', 'token', 'store'] },
+  { name: 'obligations', summary: 'Check changed files against the surface-partner map',
+    positional: 'path',
+    flags: ['files', 'strict', 'json'] },
+  { name: 'link', summary: 'Print a shareable dashboard deep-link URL', aliases: ['url'],
+    positional: 'address',
+    flags: ['dir', 'scope', 'key', 'q', 'owner', 'tags', 'range', 'from', 'to', 'archived', 'base', 'json'] },
+  { name: 'migrate', summary: 'Relocate or push a local store',
+    values: { to: ['home', 'project', 'remote'] },
+    flags: ['dir', 'from', 'to', 'apply', 'yes'] },
+  { name: 'bootstrap', summary: 'Apply the LoreKit schema to your own database',
+    flags: ['yes', 'endpoint', 'token'] },
+  { name: 'write', summary: 'Create or update a memory', positional: 'address',
+    flags: ['dir', 'scope', 'key', 'value', 'tags', 'source-agent', 'trigger', 'ttl-days', 'clear-ttl',
+      'org', 'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin', 'remote', 'local',
+      'json', 'endpoint', 'token', 'store'] },
+  { name: 'archive', summary: 'Hide a memory without losing it', positional: 'address',
+    flags: ['scope', 'key', 'remote', 'local', 'json'] },
+  { name: 'delete', summary: 'Archive a memory, or destroy it with --force', aliases: ['rm'],
+    positional: 'address',
+    flags: ['force', 'scope', 'key', 'remote', 'local', 'json'] },
+  { name: 'restore', summary: 'Bring an archived memory back', positional: 'address',
+    flags: ['scope', 'key', 'remote', 'local', 'json'] },
+  { name: 'purge', summary: 'Delete archived memories past a retention window',
+    flags: ['retention-days', 'yes', 'json', 'endpoint', 'token'] },
+  { name: 'purge-expired', summary: 'Delete every TTL-expired memory',
+    flags: ['yes', 'json', 'endpoint', 'token'] },
+  { name: 'completion', summary: 'Print a shell completion script', positional: 'shell' },
+];
+
+// The completion spec, resolved to concrete flag metadata. Exported so the
+// renderers and the parity test read the SAME structure.
+export function completionSpec() {
+  return COMMANDS.map((cmd) => ({
+    name: cmd.name,
+    summary: cmd.summary,
+    aliases: cmd.aliases ?? [],
+    positional: cmd.positional ?? null,
+    flags: (cmd.flags ?? []).map((flagName) => {
+      const meta = FLAG[flagName];
+      if (!meta) throw new Error(`completionSpec: command ${cmd.name} references unknown flag ${flagName}`);
+      const values = cmd.values?.[flagName] ?? meta.values ?? null;
+      return { name: flagName, ...meta, values };
+    }),
+  }));
+}
+
+// Every command word a completion offers — canonical names AND their aliases —
+// so `lorekit l<TAB>` surfaces both `list` and `ls`. Aliases inherit the
+// canonical command's summary.
+function commandWords(spec) {
+  const words = [];
+  for (const cmd of spec) {
+    words.push({ word: cmd.name, summary: cmd.summary });
+    for (const alias of cmd.aliases) words.push({ word: alias, summary: cmd.summary });
+  }
+  return words;
+}
+
+// Every alias-or-name that dispatches to one command, for the per-command
+// `case` arm (zsh) / `__fish_seen_subcommand_from` set (fish).
+const cmdWordSet = (cmd) => [cmd.name, ...cmd.aliases];
+
+// --- zsh -------------------------------------------------------------------
+
+// zsh optspec for one flag: `'(-x --name)'{-x,--name}'[desc]:arg:action'` when a
+// short alias exists, else `'--name[desc]:arg:action'`. A boolean flag omits the
+// `:arg:action` tail.
+function zshFlag(flag) {
+  const desc = zshDesc(flag.desc);
+  const tail = flag.arg ? `:${flag.arg}:${zshAction(flag)}` : '';
+  if (flag.short) {
+    return `'(-${flag.short} --${flag.name})'{-${flag.short},--${flag.name}}'[${desc}]${tail}'`;
+  }
+  return `'--${flag.name}[${desc}]${tail}'`;
+}
+
+// The zsh completion ACTION for a flag's value: a dynamic helper, a static
+// `(a b c)` list, file/dir completion, or nothing.
+function zshAction(flag) {
+  if (flag.complete === 'scope') return '_lorekit_scopes';
+  if (flag.values) return `(${flag.values.join(' ')})`;
+  if (flag.arg === 'dir') return '_files -/';
+  if (flag.arg === 'path' || flag.arg === 'file') return '_files';
+  return ' ';
+}
+
+// The zsh positional-argument spec for a command, or '' when it takes none.
+function zshPositional(kind) {
+  if (kind === 'address') return `'*::address:_lorekit_addresses'`;
+  if (kind === 'query') return `'*::query: '`;
+  if (kind === 'path') return `'*::file:_files'`;
+  if (kind === 'shell') return `'1:shell:(${COMPLETION_SHELLS.join(' ')})'`;
+  return '';
+}
+
+// zsh escaping: the description sits inside a single-quoted `[...]`, so a literal
+// single quote is doubled and a `[`/`]`/`:` is backslash-escaped (they are
+// optspec metacharacters). Our descriptions avoid these, but escaping keeps a
+// future edit from producing a script that fails to source.
+function zshDesc(s) {
+  return String(s).replace(/'/g, "''").replace(/[\][:]/g, '\\$&');
+}
+
+function renderZsh(spec) {
+  const commands = commandWords(spec)
+    .map((c) => `    '${c.word}:${zshDesc(c.summary)}'`)
+    .join('\n');
+
+  const arms = spec
+    .map((cmd) => {
+      const specs = [zshPositional(cmd.positional), ...cmd.flags.map(zshFlag)].filter(Boolean);
+      const body = specs.length ? `_arguments \\\n        ${specs.join(' \\\n        ')}` : ':';
+      return `    ${cmdWordSet(cmd).join('|')})\n      ${body}\n      ;;`;
+    })
+    .join('\n');
+
+  return `#compdef lorekit
+# LoreKit CLI completion for zsh — generated by \`lorekit completion zsh\`.
+# Regenerate after upgrading the CLI. See \`lorekit completion --help\`.
+
+_lorekit() {
+  local -a _lk_commands
+  _lk_commands=(
+${commands}
+  )
+
+  local curcontext="$curcontext" state line
+  typeset -A opt_args
+
+  _arguments -C '1:command:->cmds' '*::arg:->args' && return 0
+
+  case $state in
+    cmds)
+      _describe -t commands 'lorekit command' _lk_commands
+      ;;
+    args)
+      case $line[1] in
+${arms}
+      esac
+      ;;
+  esac
+}
+
+# Dynamic candidates come from the CLI itself, so they always reflect the local
+# store. Failures are swallowed — a missing token or store just yields no
+# candidates, never an error at the prompt.
+_lorekit_scopes() {
+  local -a _lk_scopes
+  _lk_scopes=(\${(f)"$(lorekit completion --complete scope 2>/dev/null)"})
+  compadd -a _lk_scopes
+}
+
+_lorekit_addresses() {
+  local -a _lk_addr
+  _lk_addr=(\${(f)"$(lorekit completion --complete key 2>/dev/null)"})
+  compadd -a _lk_addr
+}
+
+compdef _lorekit lorekit
+`;
+}
+
+// --- fish ------------------------------------------------------------------
+
+// fish description escaping: the value sits in a single-quoted `-d '...'`, so a
+// single quote and a backslash are backslash-escaped.
+function fishDesc(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+// One `complete` line for a flag under a command guard.
+function fishFlag(guard, flag) {
+  const parts = ['complete', '-c', 'lorekit', '-n', `'${guard}'`, '-l', flag.name];
+  if (flag.short) parts.push('-s', flag.short);
+  if (flag.arg) parts.push('-r'); // requires a value
+  if (flag.complete === 'scope') parts.push('-f', '-a', "'(lorekit completion --complete scope)'");
+  else if (flag.values) parts.push('-a', `'${flag.values.join(' ')}'`);
+  parts.push('-d', `'${fishDesc(flag.desc)}'`);
+  return parts.join(' ');
+}
+
+function fishPositional(guard, kind) {
+  if (kind === 'address') {
+    return `complete -c lorekit -n '${guard}' -f -a '(lorekit completion --complete key)'`;
+  }
+  if (kind === 'path') {
+    // Re-enable the file completion the global `complete -c lorekit -f` turned off.
+    return `complete -c lorekit -n '${guard}' -F`;
+  }
+  if (kind === 'shell') {
+    return `complete -c lorekit -n '${guard}' -f -a '${COMPLETION_SHELLS.join(' ')}'`;
+  }
+  return null;
+}
+
+function renderFish(spec) {
+  const lines = [
+    '# LoreKit CLI completion for fish — generated by `lorekit completion fish`.',
+    '# Install to ~/.config/fish/completions/lorekit.fish (fish auto-loads it).',
+    '',
+    '# Disable file completion by default; commands opt back in where it helps.',
+    'complete -c lorekit -f',
+    '',
+    '# Subcommands (offered only before one is chosen).',
+  ];
+
+  for (const cmd of commandWords(spec)) {
+    lines.push(
+      `complete -c lorekit -n __fish_use_subcommand -a ${cmd.word} -d '${fishDesc(cmd.summary)}'`,
+    );
+  }
+
+  for (const cmd of spec) {
+    const guard = `__fish_seen_subcommand_from ${cmdWordSet(cmd).join(' ')}`;
+    lines.push('', `# ${cmd.name}`);
+    const positional = fishPositional(guard, cmd.positional);
+    if (positional) lines.push(positional);
+    for (const flag of cmd.flags) lines.push(fishFlag(guard, flag));
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+// Render the completion script for a shell. Throws on an unknown shell so a
+// caller (or a typo) fails loudly rather than writing an empty file.
+export function renderCompletion(shell, spec = completionSpec()) {
+  if (shell === 'zsh') return renderZsh(spec);
+  if (shell === 'fish') return renderFish(spec);
+  throw new Error(`Unsupported shell: ${shell}. Supported: ${COMPLETION_SHELLS.join(', ')}`);
+}
+
+// --- shell detection + on-disk install/teardown ----------------------------
+
+// The shell a bare `--completions auto` targets, from $SHELL. Returns a
+// supported shell name or null (unknown / unsupported), so the caller can say so
+// rather than guessing.
+export function detectShell(env = process.env) {
+  const shellPath = env.SHELL || '';
+  const base = path.basename(shellPath);
+  return COMPLETION_SHELLS.includes(base) ? base : null;
+}
+
+// The zsh block appended to ~/.zshrc, wrapped in idempotent guard markers so
+// re-running install never duplicates it and uninstall can remove exactly it.
+// zsh — unlike fish — has no universal auto-load directory, so the file lives in
+// a LoreKit-owned dir that this block adds to $fpath before compinit.
+const ZSH_MARK_START = '# >>> lorekit completions >>>';
+const ZSH_MARK_END = '# <<< lorekit completions <<<';
+
+function zshBlock(dir) {
+  return [
+    ZSH_MARK_START,
+    '# Added by `lorekit install`. Managed block — edits here are overwritten.',
+    `fpath=("${dir}" $fpath)`,
+    'autoload -Uz compinit && compinit',
+    ZSH_MARK_END,
+  ].join('\n');
+}
+
+// Where each shell's completion artefacts live. `file` is the script; `rcFile`
+// (+ the guard block) is only used for shells with no auto-load directory.
+//   zsh  → ~/.lorekit/completions/_lorekit, sourced via an ~/.zshrc fpath block
+//   fish → ~/.config/fish/completions/lorekit.fish (fish auto-loads the dir)
+export function completionTargets(shell, home = homeDir()) {
+  if (shell === 'zsh') {
+    const dir = path.join(home, '.lorekit', 'completions');
+    return {
+      shell,
+      dir,
+      file: path.join(dir, '_lorekit'),
+      rcFile: path.join(home, '.zshrc'),
+      autoloaded: false,
+    };
+  }
+  if (shell === 'fish') {
+    const dir = path.join(home, '.config', 'fish', 'completions');
+    return { shell, dir, file: path.join(dir, 'lorekit.fish'), rcFile: null, autoloaded: true };
+  }
+  throw new Error(`Unsupported shell: ${shell}. Supported: ${COMPLETION_SHELLS.join(', ')}`);
+}
+
+// Splice the guarded zsh block into rc text: replace an existing block in place
+// (so a stale fpath dir is corrected), else append it. Pure, so the idempotency
+// is unit-testable without touching a real ~/.zshrc.
+export function upsertGuardedBlock(rcText, block) {
+  const text = rcText || '';
+  const start = text.indexOf(ZSH_MARK_START);
+  if (start === -1) {
+    const sep = text.length === 0 || text.endsWith('\n') ? '' : '\n';
+    return { text: `${text}${sep}${block}\n`, changed: text.indexOf(block) === -1 };
+  }
+  const end = text.indexOf(ZSH_MARK_END, start);
+  if (end === -1) {
+    // A start marker with no end — treat the rest of the file as the block.
+    return { text: text.slice(0, start) + block + '\n', changed: true };
+  }
+  const before = text.slice(0, start);
+  const after = text.slice(end + ZSH_MARK_END.length).replace(/^\n/, '');
+  const next = `${before}${block}\n${after}`;
+  return { text: next, changed: next !== text };
+}
+
+// Remove the guarded zsh block from rc text (uninstall). Pure inverse of
+// `upsertGuardedBlock`; a no-op when no block is present.
+export function removeGuardedBlock(rcText) {
+  const text = rcText || '';
+  const start = text.indexOf(ZSH_MARK_START);
+  if (start === -1) return { text, changed: false };
+  const end = text.indexOf(ZSH_MARK_END, start);
+  const cut = end === -1 ? text.length : end + ZSH_MARK_END.length;
+  const before = text.slice(0, start).replace(/\n$/, '');
+  const after = text.slice(cut).replace(/^\n/, '');
+  const next = [before, after].filter(Boolean).join('\n') + (before || after ? '\n' : '');
+  return { text: next, changed: true };
+}
+
+// Write the completion script to disk for `shell`, wiring the ~/.zshrc block
+// when the shell has no auto-load directory. Returns what happened so `install`
+// can report it. `home` is injectable for tests.
+export function installCompletion(shell, { home = homeDir() } = {}) {
+  const targets = completionTargets(shell, home);
+  const script = renderCompletion(shell);
+  fs.mkdirSync(targets.dir, { recursive: true });
+  writeFileAtomic(targets.file, script);
+
+  let rcUpdated = false;
+  if (targets.rcFile) {
+    const existing = fs.existsSync(targets.rcFile) ? fs.readFileSync(targets.rcFile, 'utf8') : '';
+    const { text, changed } = upsertGuardedBlock(existing, zshBlock(targets.dir));
+    if (changed) {
+      writeFileAtomic(targets.rcFile, text);
+      rcUpdated = true;
+    }
+  }
+
+  return { shell, file: targets.file, rcFile: targets.rcFile, autoloaded: targets.autoloaded, rcUpdated };
+}
+
+// Remove the completion script and any ~/.zshrc block for `shell`. Best-effort
+// and idempotent — a missing file / block is reported as `removed: false`, never
+// an error. `uninstall` calls this for every supported shell.
+export function removeCompletion(shell, { home = homeDir() } = {}) {
+  const targets = completionTargets(shell, home);
+  let removed = false;
+  if (fs.existsSync(targets.file)) {
+    fs.rmSync(targets.file, { force: true });
+    removed = true;
+  }
+  let rcUpdated = false;
+  if (targets.rcFile && fs.existsSync(targets.rcFile)) {
+    const existing = fs.readFileSync(targets.rcFile, 'utf8');
+    const { text, changed } = removeGuardedBlock(existing);
+    if (changed) {
+      writeFileAtomic(targets.rcFile, text);
+      rcUpdated = true;
+    }
+  }
+  // `removed` reports whether ANYTHING was torn down (the script file or the rc
+  // block), so a caller's "nothing to remove" line is honest even in the rare
+  // case where only the block survived a manually-deleted file.
+  return { shell, file: targets.file, removed: removed || rcUpdated, fileRemoved: removed, rcUpdated };
+}

package/src/telemetry/telemetry.mjs

@@ -655,25 +655,28 @@ function normalizeExitCode(result) {
  * Run a MACHINE-facing command (`hook`, `mcp`) and count the invocation —
  * counter only, no span. Returns the command's exit code unchanged.
  *
- * The export is STARTED BEFORE the command runs and awaited after, so it
- * overlaps the command's own work instead of being serialized behind it. That
- * ordering is what makes this affordable on `hook`, which fires several times
- * per agent turn: by the time there is anything to await, the POST has usually
- * already completed, and {@link METERED_TIMEOUT_MS} caps the worst case.
+ * The two commands are counted at DIFFERENT times, for a reason specific to
+ * each:
  *
- * It also makes the count robust for `mcp`, which is a LONG-LIVED stdio server —
- * `run()` does not return until the server exits, and a killed server would
- * never have reported at all if the export waited for it. Since the counter
- * reports the invocation rather than its outcome (a machine-facing command's
- * verdict belongs to its stdout contract, which the host reads), there is
- * nothing to learn by waiting.
+ *   • `mcp` is a LONG-LIVED stdio server — `run()` does not return until the
+ *     server exits, and a killed server would never report at all if the export
+ *     waited for it. So its count fires BEFORE run and is awaited after, which
+ *     also overlaps the export with the server's own startup. It carries no
+ *     outcome: a server's verdict belongs to its stdout contract.
+ *   • `hook` is short-lived and fires several times per agent turn. It is
+ *     counted AFTER run so the counter can carry the health dimensions run
+ *     reports (`lorekit.hook.event` + `lorekit.hook.outcome`) — the difference
+ *     between a healthy hook and one silently degrading (an unusable store, a
+ *     swallowed lookup error) that a bare invocation ping cannot show. The extra
+ *     latency is run's own duration (a hook is tens of ms); the
+ *     {@link METERED_TIMEOUT_MS} export cap dominates either way.
  *
  * Nothing here can affect the command: the exit code is passed through
  * untouched, and every telemetry failure is swallowed.
  *
  * @param {string} command  `hook` | `mcp`
  * @param {string} version  CLI version
- * @param {() => Promise<number>} run  the command handler
+ * @param {() => Promise<number | { exitCode?: number, meter?: object }>} run  the command handler
  */
 export async function meterCommand(command, version, run) {
   let config;
@@ -688,15 +691,26 @@ export async function meterCommand(command, version, run) {
   // cost nothing at all: no identity read, no timer, no promise.
   if (!config.enabled) return normalizeExitCode(await run());
 
-  // `.catch` attached IMMEDIATELY, before any await: an unawaited rejecting
-  // promise is an unhandled rejection, which on a machine-facing command would
-  // print to stderr and pollute a host's log.
-  const pending = countInvocation(config, command, version).catch(() => {});
-  try {
-    return normalizeExitCode(await run());
-  } finally {
-    await pending;
+  // Long-lived server: count before run (see docblock). `.catch` attached
+  // IMMEDIATELY, before any await: an unawaited rejecting promise is an
+  // unhandled rejection, which on a machine-facing command would print to
+  // stderr and pollute a host's log.
+  if (command === 'mcp') {
+    const pending = countInvocation(config, command, version).catch(() => {});
+    try {
+      return normalizeExitCode(await run());
+    } finally {
+      await pending;
+    }
   }
+
+  // Short-lived hook: count after run so the counter carries what run reported.
+  // A `meter` object on the result is the health payload; anything else (a bare
+  // exit code) counts with no extra dimensions.
+  const result = await run();
+  const meter = (result && typeof result === 'object' && result.meter) ? result.meter : {};
+  await countInvocation(config, command, version, meter).catch(() => {});
+  return normalizeExitCode(result);
 }
 
 /**