@lorekit/cli 1.28.0 → 1.29.1

package/src/doctor.mjs

@@ -8,9 +8,9 @@ import {
   SKILLS,
   resolveProjectRoot,
   skillInstallDir,
-  settingsPath,
   CLAUDE_HOOK_EVENTS,
-  LOREKIT_HOOK_RE,
+  installedHookEvents,
+  hookModeFromEvents,
   readLorekitServer,
   readMcpConfig,
   tokenKind,
@@ -66,6 +66,28 @@ export async function doctor(args) {
     }
   }
 
+  // 2.4. Which hooks are actually wired, and where. Hooks are an install-time
+  // CHOICE (`--hooks all|read-only|none`, or the prompt), so "why does nothing
+  // get remembered?" is answered HERE — without a positive report the only way
+  // to tell a deliberate `none` from a broken install is to read settings.json.
+  {
+    const perScope = ['project', 'global']
+      .map((s) => ({ scope: s, events: installedHookEvents(root, s) }))
+      .filter((entry) => entry.events.length > 0);
+    if (perScope.length === 0) {
+      record(
+        'info',
+        'hooks',
+        'none wired — the skills work, but memory is model-invoked only. ' +
+          'Run `lorekit install --hooks all` to wire them.',
+      );
+    } else {
+      for (const { scope, events } of perScope) {
+        record('pass', `hooks ${scope}`, `${hookModeFromEvents(events)} — ${events.join(', ')}`);
+      }
+    }
+  }
+
   // 2.5. Duplicate-hook detection — warn when the same lorekit hook event is
   // wired in both the project settings and the global settings. This causes
   // Claude Code to fire the hook twice per event, producing doubled terminal
@@ -247,7 +269,10 @@ async function checkRemote(control, root, args, record) {
       record('fail', 'connectivity', res.networkError);
     } else if (res.ok) {
       const tools = res.result && Array.isArray(res.result.tools) ? res.result.tools.length : null;
-      record('pass', 'connectivity', tools !== null ? `reachable, ${tools} tools` : 'reachable');
+      // Say what the probe actually proved. `/health` is public, so "reachable"
+      // is a statement about the network path only — the token is judged by the
+      // `authentication` check below.
+      record('pass', 'connectivity', tools !== null ? `reachable, ${tools} tools` : 'reachable (public health probe — token not checked)');
     } else if (res.error && AUTH_CODES.has(res.error.code)) {
       record('fail', 'connectivity', `auth rejected (${res.error.code}) — check your token`);
     } else if (res.error) {
@@ -256,10 +281,64 @@ async function checkRemote(control, root, args, record) {
       record('warn', 'connectivity', `unexpected response (HTTP ${res.httpStatus})`);
     }
 
+    await checkRemoteAuth(store, record);
+
     if (args.deep) await deepCheckRemote(store, root, record);
   } else {
     record('warn', 'connectivity', 'skipped — need a valid endpoint and token');
+    record('warn', 'authentication', 'skipped — need a valid endpoint and token');
+  }
+}
+
+/**
+ * Does the configured token STILL work?
+ *
+ * The `token` check above only reads the PREFIX (`lk_rw_`/`lk_ro_`/`lk_wo_`)
+ * and `connectivity` probes the PUBLIC `/health` function, so both stay green
+ * for a token that has been revoked in the dashboard — which is precisely the
+ * state a user runs doctor in. This check makes one authenticated,
+ * side-effect-free request and reports what the server said about the
+ * credential itself.
+ *
+ * A revoked token is a FAIL (doctor exits non-zero): every remote read and
+ * write is broken, which is not a warning-level condition. A token that is
+ * accepted but lacks read permission is a PASS — that is the healthy state of a
+ * write-only token, and the `token` check already describes the tradeoff.
+ */
+async function checkRemoteAuth(store, record) {
+  const res = await store.verifyAuth();
+
+  if (res.networkError) {
+    record('warn', 'authentication', `could not verify — ${res.networkError}`);
+    return;
+  }
+  if (res.unusable) {
+    record('warn', 'authentication', 'skipped — need a valid endpoint and token');
+    return;
   }
+  if (res.authenticated === false) {
+    record(
+      'fail',
+      'authentication',
+      'token REJECTED by the server (HTTP 401) — it has been revoked, deleted, or was never valid. ' +
+        'Create a new one at https://lorekit.io/settings, then run `lorekit install --force` to replace it.',
+    );
+    return;
+  }
+  if (res.rateLimited) {
+    record('warn', 'authentication', 'could not verify — the request was rate limited (HTTP 429) before it reached the route; retry shortly');
+    return;
+  }
+  if (res.authenticated === true) {
+    record(
+      'pass',
+      'authentication',
+      res.permitted ? 'token accepted — read access confirmed' : 'token accepted — no read permission (write-only token)',
+    );
+    return;
+  }
+  const detail = res.error ? res.error.message || res.error.code : `HTTP ${res.httpStatus}`;
+  record('warn', 'authentication', `inconclusive — server said: ${detail}`);
 }
 
 async function deepCheckRemote(store, root, record) {
@@ -349,43 +428,14 @@ async function deepCheckLocal(store, scope, record) {
 // Returns the list of CLAUDE_HOOK_EVENTS whose lorekit hook command appears in
 // BOTH the project settings file (.claude/settings.json) and the global one
 // (~/.claude/settings.json). An empty array means no duplicates — healthy.
+//
+// Both sides read through `installedHookEvents`, the SAME detection `install`
+// uses to preselect its hook prompt, so the two surfaces can never disagree
+// about what is wired.
 function detectDuplicateHooks(root) {
-  const dupes = [];
-  const projectFile = settingsPath(root, 'project');
-  const globalFile = settingsPath(root, 'global');
-
-  let projectHooks = {};
-  let globalHooks = {};
-  try {
-    const cfg = JSON.parse(fs.readFileSync(projectFile, 'utf8'));
-    if (cfg && typeof cfg.hooks === 'object') projectHooks = cfg.hooks;
-  } catch { /* absent or unparseable — treat as empty */ }
-  try {
-    const cfg = JSON.parse(fs.readFileSync(globalFile, 'utf8'));
-    if (cfg && typeof cfg.hooks === 'object') globalHooks = cfg.hooks;
-  } catch { /* absent or unparseable — treat as empty */ }
-
-  for (const event of CLAUDE_HOOK_EVENTS) {
-    const hasInProject = hooksForEvent(projectHooks, event).some((cmd) => LOREKIT_HOOK_RE.test(cmd));
-    const hasInGlobal = hooksForEvent(globalHooks, event).some((cmd) => LOREKIT_HOOK_RE.test(cmd));
-    if (hasInProject && hasInGlobal) dupes.push(event);
-  }
-  return dupes;
-}
-
-// Extract the flat list of hook command strings for one event from a hooks
-// object. Handles the nested-group shape Claude Code uses:
-// { [event]: [ { hooks: [ { type, command } ] } ] }
-function hooksForEvent(hooksObj, event) {
-  const groups = Array.isArray(hooksObj[event]) ? hooksObj[event] : [];
-  const commands = [];
-  for (const group of groups) {
-    const inner = group && Array.isArray(group.hooks) ? group.hooks : [];
-    for (const h of inner) {
-      if (h && typeof h.command === 'string') commands.push(h.command);
-    }
-  }
-  return commands;
+  const inProject = new Set(installedHookEvents(root, 'project'));
+  const inGlobal = new Set(installedHookEvents(root, 'global'));
+  return CLAUDE_HOOK_EVENTS.filter((event) => inProject.has(event) && inGlobal.has(event));
 }
 
 async function checkBYODStorage(record) {

package/src/install.mjs

@@ -11,7 +11,10 @@ import {
   upsertMcpServer,
   upsertClaudeHooks,
   resolveHookRunner,
-  CLAUDE_HOOK_EVENTS,
+  HOOK_MODES,
+  hookEventsForMode,
+  hookModeFromEvents,
+  installedHookEvents,
   resolveConnection,
   tokenKind,
   homeDir,
@@ -20,7 +23,7 @@ import {
 } from './config.mjs';
 import { buildRemoteUrl, splitEndpoint } from './mcp.mjs';
 import { deriveScope } from './scope.mjs';
-import { log, heading, status, select, c } from './util.mjs';
+import { log, heading, status, select, err, c } from './util.mjs';
 
 // The MCP server URL is fixed — there is only one hosted LoreKit endpoint.
 const LOREKIT_MCP_ENDPOINT = 'https://pqokxlhvnosogizsjztg.supabase.co/functions/v1/mcp';
@@ -30,6 +33,46 @@ function ask(question) {
   return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
 }
 
+// Show enough of a token to recognise it, never enough to use it: the
+// permission prefix plus the last four characters.
+export function maskToken(token) {
+  if (!token) return 'none';
+  const s = String(token);
+  const m = /^(lk_(?:rw|ro|wo)_)/.exec(s);
+  const prefix = m ? m[1] : '';
+  const tail = s.slice(-4);
+  return s.length <= prefix.length + 4 ? `${prefix}…` : `${prefix}…${tail}`;
+}
+
+/**
+ * How `install` should arrive at the token it writes — the pure decision, so
+ * the rule is testable without a pseudo-TTY.
+ *
+ *   'flag'   → an explicit --token / LOREKIT_TOKEN wins outright.
+ *   'choose' → a token is already configured AND this is an interactive
+ *              `--force`: ask whether to keep / replace / remove it.
+ *   'reuse'  → a token is already configured: reuse it silently.
+ *   'prompt' → nothing configured and someone is there to ask.
+ *   'none'   → nothing configured and nobody to ask.
+ *
+ * WHY 'choose' exists: `--force` is what a user runs precisely BECAUSE the
+ * current setup is wrong, and the most common way for it to be wrong is a
+ * revoked token — which doctor's `authentication` check now names, telling them
+ * to come here. Reusing the stored token silently made `--force` incapable of
+ * fixing the one thing it was reached for, and no other command could either.
+ * It stays interactive-only: a non-interactive run has nobody to answer, so it
+ * keeps the old reuse behaviour and `--token` remains the way to replace a
+ * token in a script.
+ */
+export function tokenPlan({ flagToken, existingToken, force, nonInteractive } = {}) {
+  if (flagToken) return { action: 'flag', token: flagToken };
+  if (existingToken) {
+    if (force && !nonInteractive) return { action: 'choose', token: existingToken };
+    return { action: 'reuse', token: existingToken };
+  }
+  return nonInteractive ? { action: 'none', token: null } : { action: 'prompt', token: null };
+}
+
 // Detect whether lorekit is already installed for a given scope. Returns an
 // object describing what is present so the caller can give precise feedback.
 function detectInstalled(root, scope) {
@@ -60,11 +103,97 @@ function detectInstalled(root, scope) {
   };
 }
 
+// The interactive hook choice, as data so it can be asserted on without a pty.
+//
+// Deliberately THREE options, not a yes/no: `SessionStart` is a pure read that
+// injects existing lessons, while the other two only nudge. A single yes/no
+// bundles them, so a user who declines because they don't want to be nudged
+// also loses lesson injection — the thing LoreKit is for. Each hint says what
+// the hooks DO (inject context, nudge); none of them writes memory, and copy
+// that implied otherwise would ask for consent to something that never happens.
+export const HOOK_PROMPT_OPTIONS = [
+  {
+    label: 'Yes, all of them',
+    value: 'all',
+    hint: 'inject lessons at session start; nudge on a tool failure and at end of turn',
+  },
+  {
+    label: 'Read-only',
+    value: 'read-only',
+    hint: 'inject lessons at session start; never nudge',
+  },
+  {
+    label: 'No hooks',
+    value: 'none',
+    hint: 'skills + MCP only; memory stays model-invoked',
+  },
+];
+
+// Pure: which hook mode should the interactive prompt preselect?
+//
+// The default is the DETECTED state, not a constant — `install` is explicitly
+// re-runnable (token refresh, `--force`, completing a partial install), so a
+// constant "all" would silently resurrect hooks a user previously declined.
+// A genuinely fresh install has nothing to detect, so it preselects `all`: that
+// is the "opt in by default" the prompt is there to promote. A hand-wired subset
+// that matches no preset (`custom`) preselects `all` too — there is no preset to
+// re-offer, and the user still sees and chooses from the three options.
+//
+// That last clause is load-bearing and INTERACTIVE-ONLY: it is safe precisely
+// because the user is then shown the list and picks. A `--yes` / non-TTY run has
+// no such moment, so it must NOT take this value for a `custom` set — see
+// `install`, which leaves a hand-wired wiring untouched instead.
+export function defaultHookMode({ freshInstall, wiredEvents }) {
+  if (freshInstall) return 'all';
+  const detected = hookModeFromEvents(wiredEvents);
+  return detected === 'custom' ? 'all' : detected;
+}
+
+// Resolve the requested hook mode from the flags, or null when nothing was
+// specified (the caller then prompts / falls back). `--hooks <mode>` is the
+// explicit selector; `--no-hooks` is the pre-existing boolean and keeps its
+// documented SKIP semantics — it never removes hooks that are already wired,
+// which is why it maps to `none` here but is tracked separately below.
+//
+// A VALUELESS `--hooks` is a usage error, not an absent flag. `hooks` is not in
+// `parseArgs`' `booleans` list, so `--hooks --yes` and a trailing `--hooks`
+// both yield `true` and `--hooks=` yields `''`. Returning null for those would
+// resolve to the DETECTED mode — the exact silent fallback the validation below
+// exists to prevent — so they are surfaced as the sentinel `INVALID_HOOK_MODE`
+// and rejected alongside `--hooks bogus`. Mirrors `write.mjs`'s bare
+// `--ttl-days`, which feeds NaN to its validator for the same reason: an
+// explicitly supplied flag is a caller assertion, so a malformed one must fail.
+export const INVALID_HOOK_MODE = '(missing value)';
+
+function requestedHookMode(args) {
+  const raw = args.hooks;
+  if (typeof raw === 'string' && raw.trim()) return raw.trim().toLowerCase();
+  if (raw !== undefined && raw !== false) return INVALID_HOOK_MODE;
+  if (args['no-hooks']) return 'none';
+  return null;
+}
+
 export async function install(args) {
   const root = resolveProjectRoot(args.dir);
   const nonInteractive = Boolean(args.yes) || !process.stdin.isTTY;
   const force = Boolean(args.force);
 
+  // Validate `--hooks` before touching anything on disk: a mistyped mode must
+  // fail loudly, never silently fall back to a different wiring than asked for.
+  const requestedMode = requestedHookMode(args);
+  if (requestedMode === INVALID_HOOK_MODE) {
+    err(`\n  --hooks needs a mode. Valid modes: ${HOOK_MODES.join(' | ')}.`);
+    return 1;
+  }
+  if (requestedMode !== null && !HOOK_MODES.includes(requestedMode)) {
+    err(`\n  Unknown --hooks mode "${requestedMode}". Valid modes: ${HOOK_MODES.join(' | ')}.`);
+    return 1;
+  }
+  // An explicit `--hooks` IS the intent to change the wiring, so it must reach
+  // the hook step even on an otherwise complete install (which normally short-
+  // circuits). `--no-hooks` is skip-only and never justifies that bypass.
+  const hooksFlagExplicit = typeof args.hooks === 'string' && args.hooks.trim() !== '';
+
   heading('LoreKit install');
   log(`  project: ${c.dim(root)}`);
 
@@ -88,7 +217,9 @@ export async function install(args) {
   const globalState = detectInstalled(root, 'global');
   const currentState = scope === 'global' ? globalState : projectState;
 
-  if (currentState.isFullyInstalled && !force) {
+  const wiredEvents = installedHookEvents(root, scope);
+
+  if (currentState.isFullyInstalled && !force && !hooksFlagExplicit) {
     // Surface a clear, useful already-installed summary.
     log('');
     log(
@@ -124,10 +255,20 @@ export async function install(args) {
       log(`  ${c.yellow('Token: none configured — reads/writes will fail until a token is set')}`);
     }
 
+    // Hooks are a user choice now, so an already-installed run must SAY which
+    // one is in effect — otherwise "why does nothing get remembered?" has no
+    // answer here and the user has to go read settings.json.
+    log(
+      wiredEvents.length > 0
+        ? `  ${c.dim(`Hooks: ${wiredEvents.join(', ')}`)}`
+        : `  ${c.dim('Hooks: none wired — the skills work, but only when the model invokes them')}`,
+    );
+
     log('');
     log(`  Run ${c.cyan('npx @lorekit/cli doctor')} to verify the connection.`);
+    log(`  Change the hooks with ${c.cyan(`--hooks ${HOOK_MODES.join('|')}`)}.`);
     log(`  Pass ${c.cyan('--force')} to reinstall and overwrite existing files.`);
-    return 0;
+    return { exitCode: 0, 'lorekit.cli.hooks_mode': hookModeFromEvents(wiredEvents) };
   }
 
   // Partial install — note what's already there vs what will be added.
@@ -155,16 +296,44 @@ export async function install(args) {
   const endpoint = fromArgs.endpoint || LOREKIT_MCP_ENDPOINT;
 
   // Token resolution order: --token flag → env → existing config → prompt.
-  let token = fromArgs.token;
-  if (!token && currentState.existingToken) {
-    // Reuse the token that's already in the config — don't make the user repeat
-    // it just because they're running install again.
-    token = currentState.existingToken;
+  const plan = tokenPlan({
+    flagToken: fromArgs.token,
+    existingToken: currentState.existingToken,
+    force,
+    nonInteractive,
+  });
+
+  let token = null;
+  if (plan.action === 'flag') {
+    token = plan.token;
+  } else if (plan.action === 'reuse') {
+    token = plan.token;
     log(`  ${c.dim('Token: reusing existing token from config.')}`);
-  }
-  if (!token && !nonInteractive) {
-    token = await ask('  LoreKit token (lk_rw_… to allow writes, blank to skip): ');
-    token = token || null;
+  } else if (plan.action === 'choose') {
+    const choice = await select(
+      `A token is already configured (${maskToken(currentState.existingToken)}). What should this reinstall do?`,
+      [
+        { label: 'Keep the existing token', value: 'keep', hint: 'reuse what is in the config' },
+        { label: 'Replace it with a new token', value: 'replace', hint: 'paste a fresh lk_… token (e.g. after revoking one)' },
+        { label: 'Remove the token', value: 'remove', hint: 'leave the server unauthenticated' },
+      ],
+    );
+    if (choice === 'replace') {
+      const entered = await ask('  New LoreKit token (lk_rw_… to allow writes, blank to keep the existing one): ');
+      token = entered || currentState.existingToken;
+      log(`  ${c.dim(entered ? 'Token: replaced with the token you entered.' : 'Token: nothing entered — keeping the existing token.')}`);
+    } else if (choice === 'remove') {
+      // Deliberately NOT followed by the fresh-install prompt below: someone who
+      // just chose "remove" must not be immediately asked for a token again.
+      token = null;
+      log(`  ${c.yellow('Token: removed — reads/writes will fail until a token is set.')}`);
+    } else {
+      token = currentState.existingToken;
+      log(`  ${c.dim('Token: reusing existing token from config.')}`);
+    }
+  } else if (plan.action === 'prompt') {
+    const entered = await ask('  LoreKit token (lk_rw_… to allow writes, blank to skip): ');
+    token = entered || null;
   }
 
   // 4. Install the skill files — every skill the CLI ships.
@@ -179,14 +348,67 @@ export async function install(args) {
   const remoteUrl = buildRemoteUrl(endpoint, token);
   const { file, existed } = upsertMcpServer(root, remoteUrl, scope);
 
-  // 5b. Wire the deterministic hooks (unless --no-hooks). This is the layer the
-  //     Claude plugin adds on top of the skill: lessons injected on every
-  //     SessionStart, a nudge on tool failure, a retrospective nudge on Stop —
-  //     firing the shared `lorekit hook` engine, which reads the same config.
-  const wireHooks = !args['no-hooks'];
+  // 5b. Hooks — the deterministic layer the Claude plugin adds on top of the
+  //     skill, firing the shared `lorekit hook` engine (which reads the same
+  //     config). NONE of them write memory: SessionStart injects existing
+  //     lessons, PostToolUseFailure surfaces relevant ones plus a write nudge,
+  //     Stop fires the friction-gated retrospective nudge. All three only emit
+  //     context — the write is still the model calling `memory.write`. The
+  //     prompt copy below says exactly that, because a user who declines
+  //     "automatic memory writing" would be declining something that never
+  //     happens and losing lesson injection, which is the product.
+  let hookMode = requestedMode;
+  // A hand-wired set matching no preset (`custom`) is the one state the three
+  // options cannot express. Interactively that is fine — `defaultHookMode`
+  // preselects `all` and the user still chooses. A `--yes` / non-TTY run never
+  // gets that moment, so taking the preselection there would WIRE `all` and
+  // silently re-add the events the user hand-removed — exactly what
+  // `hookModeFromEvents` tells callers not to do, and the opposite of the
+  // documented "otherwise whatever is already wired". So keep exactly that set
+  // — no event added or removed, though the command string is still refreshed
+  // below; `--hooks <mode>` remains the way to change it on purpose.
+  let preserveCustomHooks = false;
+  if (hookMode === null) {
+    const preselect = defaultHookMode({
+      freshInstall: !currentState.hasSkills && !currentState.hasMcp && wiredEvents.length === 0,
+      wiredEvents,
+    });
+    if (nonInteractive) {
+      preserveCustomHooks = hookModeFromEvents(wiredEvents) === 'custom';
+      hookMode = preserveCustomHooks ? 'custom' : preselect;
+    } else {
+      log('');
+      hookMode = await select('Install the LoreKit lifecycle hooks?', HOOK_PROMPT_OPTIONS, {
+        defaultIndex: Math.max(0, HOOK_PROMPT_OPTIONS.findIndex((o) => o.value === preselect)),
+      });
+    }
+  }
+
+  // `hookEventsForMode` maps any unknown mode to the full set, so `custom` must
+  // never reach it — the preserved wiring IS the event list here.
+  const hookEvents = preserveCustomHooks ? [...wiredEvents] : hookEventsForMode(hookMode);
+  // `--no-hooks` is skip-only by contract: it has always meant "don't wire
+  // them", never "take away the ones already there". An interactive `No hooks`
+  // (or an explicit `--hooks none`) is an unambiguous request to remove.
+  const skipHooksOnly = hookMode === 'none' && Boolean(args['no-hooks']) && !hooksFlagExplicit;
+  // Nothing to wire and nothing to remove ⇒ don't create a settings.json at all.
+  // `wiredEvents` reads as empty for an unparseable settings.json, so a `none`
+  // run against one is a silent no-op — correct, not a gap: Claude Code cannot
+  // parse that file either, so no lorekit hook is firing from it. Any mode that
+  // WIRES still goes through `upsertClaudeHooks`, whose throwing read surfaces
+  // the parse error rather than clobbering the file.
+  //
+  // Preserving a `custom` set does NOT mean skipping the write. Passing
+  // `hookEvents` (== `wiredEvents` here) keeps exactly that set — nothing is
+  // added, and the prune loop finds no lorekit entry on the events outside it,
+  // so `removed` is always 0 — while still REFRESHING a stale command string.
+  // Skipping the call instead left a `--force` re-install unable to repair a
+  // hook command pointing at an old runner, which is the one thing a re-install
+  // is for.
+  const touchHooks = !skipHooksOnly && (hookEvents.length > 0 || wiredEvents.length > 0);
   let hooks = null;
-  if (wireHooks) {
-    hooks = upsertClaudeHooks(root, scope, resolveHookRunner());
+  if (touchHooks) {
+    hooks = upsertClaudeHooks(root, scope, resolveHookRunner(), hookEvents);
   }
 
   // Show global paths relative to ~ (a repo-relative path would be a mess of
@@ -207,16 +429,34 @@ export async function install(args) {
   }
   status('pass', mcpLabel, `${existed ? 'updated' : 'created'} lorekit server → ${display(file)}`);
 
-  if (!wireHooks) {
-    status('info', 'hooks', 'skipped (--no-hooks) — the skill still works, but memories are model-invoked only');
+  if (!touchHooks) {
+    status(
+      'info',
+      'hooks',
+      skipHooksOnly
+        ? 'skipped (--no-hooks) — the skills still work, but memory stays model-invoked'
+        : 'none — the skills still work, but memory stays model-invoked',
+    );
   } else {
-    const n = hooks.added + hooks.updated;
+    const n = hooks.added + hooks.updated + hooks.removed;
     const hookParts = [
       hooks.added ? `${hooks.added} added` : '',
       hooks.updated ? `${hooks.updated} updated` : '',
+      hooks.removed ? `${hooks.removed} removed` : '',
     ].filter(Boolean);
     const hookState = n === 0 ? 'already wired' : hookParts.join(', ');
-    status(n === 0 ? 'info' : 'pass', 'hooks', `${hookState} → ${display(hooks.file)} (${CLAUDE_HOOK_EVENTS.join(', ')})`);
+    const wired = hookEvents.length > 0 ? ` (${hookEvents.join(', ')})` : '';
+    // The preserved-`custom` run DOES write, so it lands here rather than in the
+    // "left as-is" branch — but it is still the one state the three modes cannot
+    // express, so it keeps its own explanation of how to leave it.
+    const kept = preserveCustomHooks
+      ? `; a hand-wired set matching no preset, pass --hooks ${HOOK_MODES.join('|')} to change it`
+      : '';
+    status(
+      n === 0 ? 'info' : 'pass',
+      `hooks ${hookMode}`,
+      `${hookState} → ${display(hooks.file)}${wired}${kept}`,
+    );
   }
 
   const kind = tokenKind(token);
@@ -249,5 +489,8 @@ export async function install(args) {
       )}`,
     );
   }
-  return 0;
+  // 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 };
 }

package/src/store/remote.mjs

@@ -197,8 +197,62 @@ class RemoteStore {
     return { ok: true, scopes: scopes.map((s) => ({ scope: s.scope, count: Number(s.count) || 0 })) };
   }
 
+  // Authentication probe for doctor — does the configured token STILL work?
+  //
+  // `ping()` deliberately hits the PUBLIC `/health` function, so it stays green
+  // for a revoked, deleted or mistyped token: it proves the network path, and
+  // nothing about the credential. This probe is the missing half. It makes one
+  // authenticated, side-effect-free request (`GET /memories?limit=1`) and
+  // classifies the answer:
+  //
+  //   200 → the token was accepted AND may read.
+  //   401 → the token was REJECTED (revoked, deleted, or never valid). This is
+  //         `resolveRestAuth` finding no `api_tokens` row for the hash
+  //         (supabase/functions/_shared/api/auth.ts).
+  //   403 → the token was ACCEPTED, but lacks read permission — the normal,
+  //         healthy answer for a write-only `lk_wo_*` token, so it must never
+  //         be reported as an auth failure.
+  //   429 → rate limited, and it says NOTHING about the credential. The only
+  //         `tooManyRequests()` call sites on the whole REST surface are
+  //         `memories/handlers/create.ts` and `purge.ts` — both write paths.
+  //         `GET /memories` (`handleList`) has no rate-limit check at all, so a
+  //         429 here is emitted by the platform edge AHEAD of the function,
+  //         before `resolveRestAuth` ever runs. `rateLimited` is still reported
+  //         so the caller can say "retry shortly" instead of "inconclusive".
+  //
+  // Returns { ok, authenticated, permitted, rateLimited, httpStatus, error,
+  // networkError, unusable }. `authenticated` is null when the answer does not
+  // settle the question — the caller must not turn "don't know" into "broken".
+  async verifyAuth() {
+    if (!this.usable()) return { ok: false, unusable: true, authenticated: null };
+    if (!this.restBase) {
+      return { ok: false, authenticated: null, error: { message: `Endpoint is not a valid URL: ${this.endpoint}` } };
+    }
+    // limit=1 keeps the probe cheap; the rows themselves are never read.
+    const res = await this._rest('/memories?limit=1');
+    if (res.networkError) return { ok: false, authenticated: null, networkError: res.networkError };
+    if (res.ok) return { ok: true, authenticated: true, permitted: true, httpStatus: res.httpStatus };
+
+    const httpStatus = res.httpStatus ?? null;
+    if (httpStatus === 401) {
+      return { ok: false, authenticated: false, permitted: false, httpStatus, error: res.error };
+    }
+    if (httpStatus === 403) {
+      return { ok: true, authenticated: true, permitted: false, httpStatus, error: res.error };
+    }
+    if (httpStatus === 429) {
+      return { ok: true, authenticated: null, permitted: null, rateLimited: true, httpStatus, error: res.error };
+    }
+    return { ok: false, authenticated: null, httpStatus, error: res.error };
+  }
+
   // Connectivity probe for doctor — a transport check, not a memory op.
   //
+  // NOTE: this is deliberately UNAUTHENTICATED (the `/health` function is
+  // public), so a green result says the endpoint is reachable and says NOTHING
+  // about the token. `verifyAuth()` above is what answers that; doctor runs
+  // both and reports them as separate checks.
+  //
   // There is no MCP fallback: a `restBase` we could not derive means the
   // configured endpoint is not a URL, and a JSON-RPC POST to that same
   // unparseable string could only fail in a less legible way. Report the