@lorekit/cli 1.0.1 → 1.3.0

package/README.md

@@ -37,19 +37,44 @@ Linux, and Windows (npm creates the `lorekit` shim on every platform).
 
 ### `lorekit install`
 
-Scaffolds the `lorekit-memory` skill into `.claude/skills/lorekit-memory/` and
-adds (or updates) a `lorekit` server in the project's `.mcp.json`, preserving
-any other MCP servers already configured.
+Sets up the full memory loop — the same three parts as the Claude plugin,
+without needing a marketplace:
+
+1. **Skill** (`lorekit-memory`) — the model-invoked authoring judgment.
+2. **MCP server** (`lorekit`) — the connection to your lessons, merged into the
+   MCP config (preserving any other servers).
+3. **Hooks** — the *deterministic* layer: lessons injected on every
+   `SessionStart`, a nudge on tool failure (`PostToolUseFailure`), and a
+   retrospective nudge on `Stop`. These fire the shared `lorekit hook` engine
+   and are merged into `settings.json` (existing hooks preserved).
+
+It first asks **where** to install:
+
+- **project** (default) — `.claude/skills/`, `.mcp.json`, `.claude/settings.json`.
+  Scoped to this repo; commit it to share with your team.
+- **global** — `~/.claude/skills/`, `~/.claude.json`, `~/.claude/settings.json`.
+  Applies to every project you open. Your token lands in `~/.claude.json`, so
+  keep that file private.
 
 ```bash
 lorekit install \
   --endpoint https://pqokxlhvnosogizsjztg.supabase.co/functions/v1/mcp \
   --token    lk_rw_your_token
+
+lorekit install --global      # set it up for every project
 ```
 
-If run in a TTY without `--endpoint` / `--token`, it prompts for them.
-Use `--yes` for non-interactive environments (endpoint required via flag/env).
-Use `--force` to overwrite an existing skill copy.
+In a TTY it prompts for the scope (and for `--endpoint` / `--token` if missing).
+Flags: `--project` / `--global` pick the scope non-interactively; `--no-hooks`
+installs the skill + MCP only (memory stays model-invoked); `--yes` runs
+non-interactively (endpoint required via flag/env; scope defaults to project);
+`--force` overwrites an existing skill copy. Re-running is idempotent — the hook
+entries are updated in place, never duplicated.
+
+> The hook command uses a global `lorekit` when one is on your `PATH` (fast),
+> otherwise `npx -y @lorekit/cli`. Installing the CLI globally
+> (`npm i -g @lorekit/cli`) is recommended so hooks fire without an npx
+> resolution each time.
 
 ### `lorekit doctor`
 
@@ -63,7 +88,7 @@ Verifies the setup and prints a status report:
   gitignored
 - for `remote`: `.mcp.json` has a `lorekit` server, the endpoint is real (not
   the `<project-ref>` placeholder), the token and its permission tier
-  (`lk_rw_*` vs `lk_ro_*`), and that the endpoint is reachable
+  (`lk_rw_*` / `lk_ro_*` / `lk_wo_*`), and that the endpoint is reachable
 - for `off`: a note that memory is disabled
 - the git-derived read/write scopes for the current directory
 
@@ -243,6 +268,8 @@ active deny constraints.
 | Flag | Meaning |
 |------|---------|
 | `-d, --dir <path>` | Target project root (default: cwd) |
+| `--project` | Install into this repo: `.claude/skills` + `.mcp.json` (`install`; default) |
+| `--global` | Install for every project: `~/.claude/skills` + `~/.claude.json` (`install`) |
 | `-e, --endpoint <url>` | LoreKit MCP endpoint |
 | `-t, --token <token>` | LoreKit token |
 | `--mode <mode>` | Memory mode override for `doctor`: `off` / `local` / `remote` |
@@ -251,6 +278,7 @@ active deny constraints.
 | `--to <tier>` | Migration destination tier: `home` / `project` (`migrate`; default routes by scope) |
 | `--apply` | Apply the migration — alias of `--yes` (`migrate`) |
 | `-y, --yes` | Non-interactive / apply; never prompt |
+| `--no-hooks` | Skip wiring the lifecycle hooks; skill + MCP only (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
 | `--adapter <name>` | Host framework for `hook`: `claude` / `cursor` / `codex` |
@@ -269,6 +297,10 @@ active deny constraints.
 | `LOREKIT_MCP_URL` / `LOREKIT_ENDPOINT` | endpoint fallback |
 | `LOREKIT_TOKEN` | token fallback |
 | `NO_COLOR` | disable colored output |
+| `LOREKIT_TELEMETRY` | set to `0` / `off` / `false` to disable usage telemetry |
+| `DO_NOT_TRACK` | `1` also disables usage telemetry (cross-vendor standard) |
+| `LOREKIT_TELEMETRY_TOKEN` | bearer token for telemetry export (overrides the baked-in default) |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS` | override the telemetry OTLP endpoint / headers |
 
 ## What the skill does
 
@@ -331,6 +363,24 @@ forever. This reduces manual validation to a single capture pass per tool.
 > the real Claude CLI accepts the wiring; for a true live check, install the
 > plugin and start one session per tool.
 
+## Usage telemetry
+
+The human-facing commands (`install`, `uninstall`, `doctor`, `migrate`) emit one
+OpenTelemetry span + one counter point per run so the maintainers can see which
+commands people use. It is zero-dependency (OTLP/JSON over `fetch`, no SDK) and
+deliberately narrow — it carries only the command name, a bounded set of boolean
+flags (`--global`, `--deep`, …), the CLI/runtime/OS identity, and the outcome.
+**No path, token, endpoint, repo, or scope is ever sent.** The `hook` and `mcp`
+commands are never instrumented.
+
+Opt out any time with `LOREKIT_TELEMETRY=0` (or `off` / `false` / `no`) or the
+cross-vendor `DO_NOT_TRACK=1`. Point it at your own collector with
+`OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS`, or set just the
+bearer via `LOREKIT_TELEMETRY_TOKEN`. Export is a no-op when no token is
+configured. The published package's default token is injected from a CI secret
+at release time and is never committed to git. See
+[docs/otel.md](../../docs/otel.md) for the attribute list and setup.
+
 ## Security note
 
 `install` writes your token into `.mcp.json`. Keep that file out of version

package/bin/lorekit.mjs

@@ -1,14 +1,21 @@
 #!/usr/bin/env node
 // LoreKit CLI — install the shared-memory skill and run health checks.
 import process from 'node:process';
+import { readFileSync } from 'node:fs';
 import { parseArgs, log, err, c } from '../src/util.mjs';
 import { install } from '../src/install.mjs';
+import { uninstall } from '../src/uninstall.mjs';
 import { doctor } from '../src/doctor.mjs';
 import { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
 import { mcpServer } from '../src/mcp-server.mjs';
+import { traceCommand } from '../src/telemetry.mjs';
 
-const VERSION = '1.0.0';
+// Read the version from package.json so it always matches the published
+// package — release-please bumps package.json, and this tracks it for free.
+const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
 
 const HELP = `${c.bold('lorekit')} — shared persistent memory for coding agents
 
@@ -16,8 +23,16 @@ ${c.bold('Usage')}
   npx @lorekit/cli <command> [options]
 
 ${c.bold('Commands')}
-  install     Scaffold the lorekit-memory skill into .claude/skills and
-              add the LoreKit server to .mcp.json.
+  install     Scaffold the lorekit-memory skill, wire the LoreKit MCP server,
+              and install the deterministic hooks (lessons on SessionStart, a
+              nudge on tool failure + at Stop). Prompts to install for this
+              project (.claude) or globally for every project (~/.claude);
+              --project / --global choose non-interactively, --no-hooks skips
+              the hooks (skill stays model-invoked only).
+  uninstall   Reverse install: remove the lorekit-memory skill, the MCP server
+              entry, and the lifecycle hooks for the chosen scope. Surgical —
+              other servers, hooks, and settings are left untouched. Prompts
+              project vs global; --project / --global choose non-interactively.
   doctor      Verify the skill install, MCP connectivity, token, and scope.
   migrate     Relocate a LoreKit-format local store into the current layout.
               Dry-run by default; pass --yes to apply. Idempotent.
@@ -31,6 +46,8 @@ ${c.bold('Commands')}
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
+      --project           Install into this project: .claude/skills + .mcp.json (default)
+      --global            Install for every project: ~/.claude/skills + ~/.claude.json
   -e, --endpoint <url>    LoreKit MCP endpoint
   -t, --token <token>     LoreKit token (lk_rw_* to allow writes, lk_ro_* read-only)
       --mode <mode>       Memory mode: off | local | remote (doctor override)
@@ -40,6 +57,7 @@ ${c.bold('Options')}
                           default routes each entry by scope)
       --apply             Apply the migration (alias of --yes) (migrate)
   -y, --yes               Non-interactive / apply; never prompt
+      --no-hooks          Skip wiring the lifecycle hooks (install)
       --force             Overwrite existing skill files (install)
       --deep              Do a write→read→delete round-trip (doctor)
       --adapter <name>    Host framework for hook: claude | cursor | codex
@@ -55,9 +73,13 @@ ${c.bold('Environment')}
   LOREKIT_MCP_URL / LOREKIT_ENDPOINT   endpoint fallback
   LOREKIT_TOKEN                        token fallback
   NO_COLOR                             disable colored output
+  LOREKIT_TELEMETRY / DO_NOT_TRACK     set to 0/off (or DO_NOT_TRACK=1) to opt
+                                       out of anonymous command-usage telemetry
 
 ${c.bold('Examples')}
   npx @lorekit/cli install --endpoint https://ref.supabase.co/functions/v1/mcp --token lk_rw_xxx
+  npx @lorekit/cli install --global    # set up memory for every project (~/.claude)
+  npx @lorekit/cli uninstall --global  # tear that global setup back down
   npx @lorekit/cli doctor --deep
   npx @lorekit/cli migrate --from .lore                 # preview a rename
   npx @lorekit/cli migrate --from .lore --to project --yes
@@ -67,7 +89,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'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks'],
   });
 
   // `hook` is machine-facing: it must never print help/errors to stdout
@@ -95,13 +117,19 @@ async function main() {
     return command ? 0 : args.help ? 0 : 1;
   }
 
+  // Human-facing commands are wrapped so we can see which commands people run
+  // (one OTel span + counter per invocation). `hook` and `mcp` are handled
+  // above and stay uninstrumented — they are machine-facing, fire on every
+  // agent event, and must keep stdout to their host protocol.
   switch (command) {
     case 'install':
-      return install(args);
+      return traceCommand('install', args, VERSION, () => install(args));
+    case 'uninstall':
+      return traceCommand('uninstall', args, VERSION, () => uninstall(args));
     case 'doctor':
-      return doctor(args);
+      return traceCommand('doctor', args, VERSION, () => doctor(args));
     case 'migrate':
-      return migrate(args);
+      return traceCommand('migrate', args, VERSION, () => migrate(args));
     default:
       err(`${c.red('Unknown command:')} ${command}\n`);
       log(HELP);

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.0.1",
+  "version": "1.3.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mthines/lorekit"
+  },
   "type": "module",
   "bin": {
     "lorekit": "bin/lorekit.mjs"
@@ -33,4 +37,4 @@
     "doctor": "node bin/lorekit.mjs doctor",
     "test": "node --test test/*.test.mjs"
   }
-}
+}

package/skill/lorekit-memory/SKILL.md

@@ -114,8 +114,9 @@ Full resolution rules: [references/scope-resolution.md](./references/scope-resol
 | `memory.read` | Read one lesson by scope + key | read |
 | `memory.write` | Store or update a lesson (same scope+key updates in place) | read+write |
 
-Write tools need an `lk_rw_*` token; read tools accept `lk_rw_*` or `lk_ro_*`.
-A read-only token cannot write — if a write fails with an authorization error,
+Write tools need write permission (`lk_rw_*` or `lk_wo_*`); read tools need read
+permission (`lk_rw_*` or `lk_ro_*`). A read-only token cannot write and a
+write-only token cannot read — if a call fails with an authorization error,
 report it and move on; do not retry.
 
 Every lesson this skill writes carries the tag `skill::lorekit-memory` plus a

package/src/config.mjs

@@ -1,5 +1,6 @@
 // Project layout + .mcp.json read/merge helpers.
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -12,12 +13,169 @@ export function resolveProjectRoot(dir) {
   return path.resolve(dir || process.cwd());
 }
 
+// Atomic config write: serialize to a sibling temp file, then rename over the
+// target. rename(2) is atomic within a filesystem, so a crash / Ctrl-C / ENOSPC
+// mid-write can never leave a half-written (corrupt) file — the original stays
+// intact until the complete new content is swapped in. This matters most for
+// ~/.claude.json, which can be large and holds all of Claude Code's per-project
+// state and OAuth tokens. The temp file inherits the target's permissions when
+// it exists (so we don't widen a locked-down 0600 config to 0644 on replace).
+export function writeFileAtomic(file, data) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.tmp`);
+  try {
+    fs.writeFileSync(tmp, data);
+    try {
+      fs.chmodSync(tmp, fs.statSync(file).mode);
+    } catch {
+      /* target didn't exist — leave the temp file's default perms */
+    }
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      /* best-effort cleanup of the temp file */
+    }
+    throw e;
+  }
+}
+
+// The user's home directory. Honors $HOME / %USERPROFILE% (so it can be
+// redirected in tests) and falls back to the OS lookup.
+export function homeDir() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
 export function mcpJsonPath(root) {
   return path.join(root, '.mcp.json');
 }
 
-export function skillInstallDir(root) {
-  return path.join(root, '.claude', 'skills', SKILL_NAME);
+// Where the MCP server entry is written for a given scope:
+//   project → <root>/.mcp.json          (Claude Code project config)
+//   global  → ~/.claude.json            (Claude Code user config, all projects)
+export function mcpConfigPath(root, scope = 'project') {
+  return scope === 'global' ? path.join(homeDir(), '.claude.json') : mcpJsonPath(root);
+}
+
+// Where the skill is scaffolded for a given scope:
+//   project → <root>/.claude/skills/…   (this repo only)
+//   global  → ~/.claude/skills/…        (personal skills, all projects)
+export function skillInstallDir(root, scope = 'project') {
+  const base = scope === 'global' ? homeDir() : root;
+  return path.join(base, '.claude', 'skills', SKILL_NAME);
+}
+
+// Claude Code settings file that holds the hooks for a given scope:
+//   project → <root>/.claude/settings.json
+//   global  → ~/.claude/settings.json
+export function settingsPath(root, scope = 'project') {
+  const base = scope === 'global' ? homeDir() : root;
+  return path.join(base, '.claude', 'settings.json');
+}
+
+// The lifecycle events the memory loop wires: read lessons on start, nudge on a
+// tool failure, nudge a retrospective at end of turn. Mirrors the plugin's
+// hooks.json so `install` delivers the same deterministic layer.
+export const CLAUDE_HOOK_EVENTS = ['SessionStart', 'PostToolUseFailure', 'Stop'];
+
+// Matches a hook command that fires the lorekit engine, whether wired as a
+// global `lorekit hook …` or `npx -y @lorekit/cli hook …`. Shared by the
+// upsert (find-or-update) and remove (uninstall) paths so they agree on what
+// counts as "ours".
+export const LOREKIT_HOOK_RE = /(?:@lorekit\/cli|lorekit) hook\b/;
+
+// npx stages the package's own bin into an ephemeral cache dir
+// (…/_npx/<hash>/node_modules/.bin) and prepends it to PATH for the lifetime of
+// the `npx @lorekit/cli …` process. That makes `lorekit` *look* globally
+// installed during `install`, so the hooks get wired as bare `lorekit hook …`
+// — but the symlink vanishes when npx exits, and Claude Code then fails every
+// hook with `lorekit: command not found`. Excluding these transient dirs keeps
+// the bare-`lorekit` runner reserved for a genuine global install.
+const isEphemeralNpxDir = (dir) => /[\\/]_npx[\\/]/.test(dir);
+
+// Is `bin` resolvable on a *durable* PATH entry? Used to prefer a fast global
+// `lorekit` over `npx` for hook commands. Zero-dep, cross-platform.
+export function onPath(bin) {
+  const dirs = (process.env.PATH || '').split(path.delimiter);
+  const exts = process.platform === 'win32' ? ['.cmd', '.exe', '.bat', ''] : [''];
+  for (const dir of dirs) {
+    if (!dir || isEphemeralNpxDir(dir)) continue;
+    for (const ext of exts) {
+      try {
+        if (fs.existsSync(path.join(dir, bin + ext))) return true;
+      } catch {
+        /* ignore unreadable PATH entries */
+      }
+    }
+  }
+  return false;
+}
+
+// The command prefix for hook entries: a global `lorekit` when it's installed
+// (fast — no npx resolution per event), else `npx -y @lorekit/cli`.
+export function resolveHookRunner() {
+  return onPath('lorekit') ? 'lorekit' : 'npx -y @lorekit/cli';
+}
+
+// Read the lorekit MCP server entry out of an arbitrary config file.
+function readServerFromFile(file) {
+  if (!fs.existsSync(file)) return null;
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+  const server = config && config.mcpServers && config.mcpServers.lorekit;
+  if (!server) return null;
+  const args = Array.isArray(server.args) ? server.args : [];
+  const url = args.find((a) => typeof a === 'string' && /^https?:\/\//.test(a));
+  return { server, url: url || null };
+}
+
+// Wire the lorekit hook engine into Claude Code settings for the scope,
+// preserving all other settings and any non-lorekit hooks. Idempotent: an
+// existing lorekit hook entry per event is updated in place, never duplicated.
+// `runner` is the command prefix (e.g. 'lorekit' or 'npx -y @lorekit/cli').
+export function upsertClaudeHooks(root, scope, runner) {
+  const file = settingsPath(root, scope);
+  const config = readJsonIfExists(file) || {};
+  if (!config.hooks || typeof config.hooks !== 'object') config.hooks = {};
+
+  let added = 0;
+  let updated = 0;
+  let unchanged = 0;
+
+  for (const event of CLAUDE_HOOK_EVENTS) {
+    const command = `${runner} hook --adapter claude --event ${event} --dir "\${CLAUDE_PROJECT_DIR}"`;
+    if (!Array.isArray(config.hooks[event])) config.hooks[event] = [];
+    const groups = config.hooks[event];
+
+    let existing = null;
+    for (const group of groups) {
+      const inner = group && Array.isArray(group.hooks) ? group.hooks : [];
+      existing = inner.find(
+        (h) => h && typeof h.command === 'string' && LOREKIT_HOOK_RE.test(h.command),
+      );
+      if (existing) break;
+    }
+
+    if (existing) {
+      if (existing.command === command) unchanged++;
+      else {
+        existing.command = command;
+        updated++;
+      }
+    } else {
+      groups.push({ hooks: [{ type: 'command', command }] });
+      added++;
+    }
+  }
+
+  writeFileAtomic(file, JSON.stringify(config, null, 2) + '\n');
+  return { file, added, updated, unchanged };
 }
 
 // Throwing read — used by `install` so a corrupt .mcp.json aborts the write
@@ -44,9 +202,10 @@ export function readMcpConfig(root) {
   }
 }
 
-// Merge a lorekit server entry into .mcp.json, preserving any other servers.
-export function upsertMcpServer(root, remoteUrl) {
-  const file = mcpJsonPath(root);
+// Merge a lorekit server entry into the scope's MCP config, preserving any
+// other servers (and, for the global ~/.claude.json, all other user settings).
+export function upsertMcpServer(root, remoteUrl, scope = 'project') {
+  const file = mcpConfigPath(root, scope);
   const config = readJsonIfExists(file) || {};
   if (!config.mcpServers || typeof config.mcpServers !== 'object') {
     config.mcpServers = {};
@@ -56,20 +215,80 @@ export function upsertMcpServer(root, remoteUrl) {
     command: 'npx',
     args: ['-y', 'mcp-remote', remoteUrl],
   };
-  fs.writeFileSync(file, JSON.stringify(config, null, 2) + '\n');
+  writeFileAtomic(file, JSON.stringify(config, null, 2) + '\n');
   return { file, existed };
 }
 
-// Pull the configured lorekit remote URL out of .mcp.json, if present.
-// Non-throwing: returns null when the file is absent, invalid, or has no
-// lorekit server. Callers that need to distinguish those use readMcpConfig.
+// Pull the configured lorekit remote URL out of the project .mcp.json, if
+// present. Non-throwing: returns null when the file is absent, invalid, or has
+// no lorekit server. Callers that need to distinguish those use readMcpConfig.
 export function readLorekitServer(root) {
-  const { config } = readMcpConfig(root);
-  const server = config && config.mcpServers && config.mcpServers.lorekit;
-  if (!server) return null;
-  const args = Array.isArray(server.args) ? server.args : [];
-  const url = args.find((a) => typeof a === 'string' && /^https?:\/\//.test(a));
-  return { server, url: url || null };
+  return readServerFromFile(mcpJsonPath(root));
+}
+
+// --- uninstall: surgical removal of the three things `install` writes. -------
+// Each helper touches only lorekit's own entries and leaves every other
+// server / hook / setting intact, so uninstalling never damages a shared
+// ~/.claude.json or settings.json.
+
+// Delete the scaffolded skill directory. We own the whole
+// .claude/skills/lorekit-memory tree, so a recursive remove is safe.
+export function removeSkill(root, scope = 'project') {
+  const dest = skillInstallDir(root, scope);
+  const removed = fs.existsSync(dest);
+  if (removed) fs.rmSync(dest, { recursive: true, force: true });
+  return { dest, removed };
+}
+
+// Drop the `lorekit` MCP server entry, preserving any other servers (and, for
+// the global ~/.claude.json, all other user settings). Prunes an emptied
+// mcpServers object. No-op (no write) when there's nothing to remove.
+export function removeMcpServer(root, scope = 'project') {
+  const file = mcpConfigPath(root, scope);
+  const config = readJsonIfExists(file);
+  const hasEntry =
+    config &&
+    config.mcpServers &&
+    typeof config.mcpServers === 'object' &&
+    Object.prototype.hasOwnProperty.call(config.mcpServers, 'lorekit');
+  if (!hasEntry) return { file, removed: false };
+
+  delete config.mcpServers.lorekit;
+  if (Object.keys(config.mcpServers).length === 0) delete config.mcpServers;
+  writeFileAtomic(file, JSON.stringify(config, null, 2) + '\n');
+  return { file, removed: true };
+}
+
+// Strip lorekit hook entries from every event, preserving non-lorekit hooks in
+// the same groups. Prunes groups left with no hooks and events left with no
+// groups. Returns the count removed; only writes when something changed.
+export function removeClaudeHooks(root, scope = 'project') {
+  const file = settingsPath(root, scope);
+  const config = readJsonIfExists(file);
+  if (!config || !config.hooks || typeof config.hooks !== 'object') {
+    return { file, removed: 0 };
+  }
+
+  let removed = 0;
+  for (const event of Object.keys(config.hooks)) {
+    const groups = config.hooks[event];
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      if (!group || !Array.isArray(group.hooks)) continue;
+      const before = group.hooks.length;
+      group.hooks = group.hooks.filter(
+        (h) => !(h && typeof h.command === 'string' && LOREKIT_HOOK_RE.test(h.command)),
+      );
+      removed += before - group.hooks.length;
+    }
+    // Drop groups we emptied, then the event key if it has no groups left.
+    config.hooks[event] = groups.filter((g) => g && Array.isArray(g.hooks) && g.hooks.length > 0);
+    if (config.hooks[event].length === 0) delete config.hooks[event];
+  }
+  if (Object.keys(config.hooks).length === 0) delete config.hooks;
+
+  if (removed > 0) writeFileAtomic(file, JSON.stringify(config, null, 2) + '\n');
+  return { file, removed };
 }
 
 // Recursively copy the skill source into the target, skipping files that
@@ -111,21 +330,25 @@ export function tokenKind(token) {
   if (!token) return 'none';
   if (token.startsWith('lk_rw_')) return 'read-write';
   if (token.startsWith('lk_ro_')) return 'read-only';
+  if (token.startsWith('lk_wo_')) return 'write-only';
   return 'unknown';
 }
 
-// For hooks: resolve the connection from the project's .mcp.json first
-// (that is where `lorekit install` wrote the token), then fall back to env.
-// `splitEndpoint` is passed in to avoid a circular import with mcp.mjs.
+// For hooks: resolve the connection closest-scope first — the project's
+// .mcp.json (a project install), then the global ~/.claude.json (a global
+// install), then env. `splitEndpoint` is passed in to avoid a circular import
+// with mcp.mjs.
 export function resolveProjectConnection(root, splitEndpoint) {
-  const configured = readLorekitServer(root);
-  if (configured && configured.url) {
-    const { endpoint, token } = splitEndpoint(configured.url);
-    if (endpoint && !endpoint.includes('<project-ref>')) {
-      return {
-        endpoint,
-        token: token || process.env.LOREKIT_TOKEN || null,
-      };
+  const sources = [readLorekitServer(root), readServerFromFile(mcpConfigPath(root, 'global'))];
+  for (const configured of sources) {
+    if (configured && configured.url) {
+      const { endpoint, token } = splitEndpoint(configured.url);
+      if (endpoint && !endpoint.includes('<project-ref>')) {
+        return {
+          endpoint,
+          token: token || process.env.LOREKIT_TOKEN || null,
+        };
+      }
     }
   }
   return resolveConnection({});

package/src/doctor.mjs

@@ -41,10 +41,16 @@ export async function doctor(args) {
     `v${process.versions.node}${major < 18 ? ' — need v18+ for fetch' : ''}`,
   );
 
-  // 2. Skill installed.
-  const skillMd = path.join(skillInstallDir(root), 'SKILL.md');
-  if (fs.existsSync(skillMd)) {
-    record('pass', `skill ${SKILL_NAME}`, path.relative(root, skillMd) || skillMd);
+  // 2. Skill installed — check BOTH the project and the global (~/.claude)
+  // locations. `lorekit install --global` writes the skill under home, not the
+  // repo, so a project-only check reports a healthy global install as "not
+  // found" (exactly the false FAIL a --global setup would hit).
+  const skillMd = [skillInstallDir(root, 'project'), skillInstallDir(root, 'global')]
+    .map((dir) => path.join(dir, 'SKILL.md'))
+    .find((p) => fs.existsSync(p));
+  if (skillMd) {
+    const rel = path.relative(root, skillMd);
+    record('pass', `skill ${SKILL_NAME}`, rel && !rel.startsWith('..') ? rel : prettyPath(skillMd));
   } else {
     record('fail', `skill ${SKILL_NAME}`, 'not found — run `lorekit install`');
   }
@@ -163,7 +169,8 @@ async function checkRemote(control, root, args, record) {
   const kind = tokenKind(token);
   if (kind === 'none') record('fail', 'token', 'none configured');
   else if (kind === 'read-only') record('warn', 'token', 'read-only (lk_ro_*) — reads only, no writes');
-  else if (kind === 'unknown') record('warn', 'token', 'unrecognized prefix (expected lk_rw_* / lk_ro_*)');
+  else if (kind === 'write-only') record('warn', 'token', 'write-only (lk_wo_*) — writes only, no reads');
+  else if (kind === 'unknown') record('warn', 'token', 'unrecognized prefix (expected lk_rw_* / lk_ro_* / lk_wo_*)');
   else record('pass', 'token', 'read+write (lk_rw_*)');
 
   // Connectivity, through the store.