@lorekit/cli 1.55.3 → 1.57.0

package/README.md

@@ -443,6 +443,57 @@ coincidental overlaps. Any pair scoring at or above `--threshold` links (transit
 into one cluster; only clusters of 2+ members are reported, each with a similarity
 range. Cross-**store** divergence is `diff`'s job; `dedupe` looks within a store.
 
+### `lorekit obligations`
+
+Check a changed-file set against the **Surface-Partner Map** — a declarative
+registry of known, path-keyed file partnerships (a mirrored module, a doc that
+copies a claim, a generated artifact) mined from existing CI guards — and flag
+any partner the map says the changed-set owes but doesn't contain:
+
+```bash
+lorekit obligations supabase/functions/_shared/audit/audit.ts        # positionals
+lorekit obligations --files packages/schemas/src/shared/tool-catalog.ts --json
+git diff --name-only origin/main... | lorekit obligations --strict   # from a real diff
+```
+
+This is a machine version of a recurring review finding: a fix to one surface
+leaves its partner stale because the lessons documenting the partnership are
+retrieved lexically (full-text search + recency) and rarely surface at edit
+time for the exact file just touched. Each matched entry prints its obliged
+partner files/actions, marks each as met (✓) or unmet (!), and cites the
+memory `lessonKey` the partnership encodes.
+
+An `obliges` element is a required partner path/glob, a `run:<action>`
+advisory that is always reported but never gates `--strict` (some
+partnerships are "regenerate this," not "edit this file"), or an "any of"
+group satisfied by whichever of several candidates is present. `{name}` (or
+`**/{name}`) in a `match`/`obliges` glob binds a mirrored module's relative
+path (directories + stem, extension stripped), for the (rare) case where a
+partner's path genuinely IS a predictable function of the source's, so one
+entry covers every module instead of needing one per file.
+
+The `edge-mirror`/`edge-mirror-core` entries (mcp-core ↔ the self-contained
+Deno edge mirrors) do NOT use that glob mechanism: an edge mirror doesn't
+reliably preserve mcp-core's directory structure (it may flatten or rename
+it), so a symmetric-path reconstruction false-positives on exactly those
+pairs. Instead, both entries are generated — one row per pair — from
+`src/shared/mirror-pairs.mjs`, the single-source inventory
+`packages/mcp-core/src/edge/edge-parity.spec.ts` also reads for its
+byte-comparison drift guard, so the spec and this command can never disagree
+about which files mirror which.
+
+**Cwd-independent by design**: it matches the path STRINGS it is given
+against the map and never reads the filesystem or resolves scope from the
+current directory — the changed-set can come from a real `git diff`, a PR
+file list, or by hand, from anywhere.
+
+Exits 0 by default; `--strict` exits non-zero when any PATH obligation is
+unmet. `--json` → `{ files, matched, unmet, ok }`. CLI-only (`native` — no MCP
+tool, no REST route, no `tool-catalog.ts` entry): a path-matching lint utility
+is not an operation surface. Slice 1 of a larger design — wiring a
+`PreToolUse` hook to call this at edit time, and server-side retrieval
+changes, are named follow-ups, not built here.
+
 ### `lorekit link` (alias `url`)
 
 Print a shareable **dashboard deep-link URL** to stdout — nothing else, so it
@@ -996,12 +1047,14 @@ 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` / `purge` / `purge-expired`) |
+| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `obligations` / `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`) |
+| `--files <path>...` | Changed files to check (`obligations`); also accepted as positionals or newline-separated stdin |
+| `--strict` | Exit non-zero on any unmet obligation (`obligations`) |
 | `--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) |

package/bin/lorekit.mjs

@@ -74,6 +74,14 @@ ${c.bold('Commands')}
   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>.
+  obligations Check a changed-file set against the Surface-Partner Map: known,
+              path-keyed file partnerships (a mirrored module, a doc that
+              copies a claim, a generated artifact) mined from existing CI
+              guards. Prints each matched partnership's obliged partner
+              files/actions and flags any partner NOT in the given set.
+              Cwd-independent — matches path strings, never reads the FS.
+              --files <path>..., positionals, or stdin (newline-separated).
+              --json, --strict (exit non-zero on any unmet obligation).
   link (url)  Print a shareable dashboard deep-link URL for the current context,
               a scope, or a specific lesson (opens its detail sheet). No args
               links to the cwd's most-specific scope. Filter flags mirror the
@@ -102,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)
@@ -111,9 +123,11 @@ ${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 / scopes / diff / tree / lint / dedupe / link)
+      --json              Machine-readable output (list / search / show / stats / scopes / diff / tree / lint / dedupe / obligations / link)
       --scope <scope>     Restrict to a single scope; a substring filter for scopes (list / search / stats / scopes / diff / tree / lint / dedupe / link)
                           On show / write it NAMES the scope, overriding the positional
+      --files <path>...   Changed files to check (obligations); also accepted as positionals or newline-separated stdin
+      --strict            Exit non-zero on any unmet obligation (obligations)
       --key <key>         Name the key explicitly (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)
@@ -131,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)
@@ -207,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)
@@ -218,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
 
@@ -566,6 +586,41 @@ ${c.bold('Examples')}
   npx @lorekit/cli dedupe
   npx @lorekit/cli dedupe --threshold 0.6 --json
   npx @lorekit/cli dedupe --cluster-by-key "(pr\\d+-\\d+)" --json
+`,
+  obligations: `${c.bold('lorekit obligations')} — check a changed-file set against the Surface-Partner Map
+
+${c.bold('Usage')}
+  npx @lorekit/cli obligations <path>... [options]
+  npx @lorekit/cli obligations --files <path>... [options]
+  git diff --name-only | npx @lorekit/cli obligations [options]
+
+Checks a changed-file set against a declarative registry of known, path-keyed
+file partnerships (a mirrored module, a doc that copies a claim, a generated
+artifact) mined from existing CI guards — a machine version of the recurring
+review finding "you fixed one surface and left its partner stale." For each
+matched partnership it prints the obliged partner files/actions and flags any
+partner NOT in the given changed-set, citing the memory lesson the
+partnership encodes.
+
+Cwd-INDEPENDENT: it matches the path STRINGS it is given against the map — it
+never reads the filesystem or resolves scope from the current directory, so
+the changed-set can come from anywhere (a git diff, a PR file list, by hand).
+
+The changed-set is positionals unioned with ${c.cyan('--files')} (its single-value
+form — extra paths after it fall through as positionals); when neither is
+given, it falls back to stdin lines (newline-separated, trimmed, non-empty),
+read only when stdin is piped.
+
+${c.bold('Options')}
+      --files <path>...   Changed files to check (also: positionals, stdin)
+      --strict            Exit non-zero when any path obligation is unmet
+                          (an advisory run: action never gates this)
+      --json              Machine-readable output ({ files, matched, unmet, ok })
+
+${c.bold('Examples')}
+  npx @lorekit/cli obligations supabase/functions/_shared/audit/audit.ts
+  npx @lorekit/cli obligations --files packages/schemas/src/shared/tool-catalog.ts --json
+  git diff --name-only origin/main... | npx @lorekit/cli obligations --strict
 `,
   link: `${c.bold('lorekit link')} — print a shareable dashboard deep-link URL ${c.dim('(alias: url)')}
 
@@ -811,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)
 `,
@@ -821,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
@@ -835,6 +914,8 @@ const KNOWN_FLAGS = [
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
   // Scale-aware survey flags
   'all', 'max', 'since', 'until', 'key-prefix', 'cluster-by-key',
+  // `obligations`
+  'files', 'strict',
 ];
 
 async function main() {
@@ -847,7 +928,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
-    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'strict'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.55.3",
+  "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',
+  };
 }