@lorekit/cli 1.0.0 → 1.2.0

package/README.md

@@ -9,30 +9,72 @@ CI included. This CLI wires an agent up to it in two commands.
 
 ## Install
 
+Install it globally — recommended. You get one pinned version, the `lorekit`
+command stays on your `PATH`, and the plugin hooks (which call `lorekit hook`
+on every lifecycle event) fire instantly instead of paying an `npx` resolution
+cost each time:
+
+```bash
+npm install -g @lorekit/cli
+lorekit install
+lorekit doctor
+```
+
+Upgrade later with `npm install -g @lorekit/cli@latest`.
+
+Prefer not to install anything? Run it on demand with `npx` — same commands,
+always the latest version, fetched and cached per use:
+
 ```bash
 npx @lorekit/cli install
 npx @lorekit/cli doctor
 ```
 
-Requires Node 18+ (for the built-in `fetch`). No dependencies.
+Requires Node 18+ (for the built-in `fetch`). No dependencies. Works on macOS,
+Linux, and Windows (npm creates the `lorekit` shim on every platform).
 
 ## Commands
 
 ### `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://<project-ref>.supabase.co/functions/v1/mcp \
+  --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`
 
@@ -46,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
 
@@ -226,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` |
@@ -234,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` |

package/bin/lorekit.mjs

@@ -1,14 +1,20 @@
 #!/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';
 
-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 +22,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 +45,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 +56,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
@@ -58,6 +75,8 @@ ${c.bold('Environment')}
 
 ${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 +86,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
@@ -98,6 +117,8 @@ async function main() {
   switch (command) {
     case 'install':
       return install(args);
+    case 'uninstall':
+      return uninstall(args);
     case 'doctor':
       return doctor(args);
     case 'migrate':

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.0.0",
+  "version": "1.2.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.

package/src/install.mjs

@@ -10,19 +10,23 @@ import {
   skillInstallDir,
   copyDir,
   upsertMcpServer,
+  upsertClaudeHooks,
+  resolveHookRunner,
+  CLAUDE_HOOK_EVENTS,
   resolveConnection,
   tokenKind,
+  homeDir,
 } from './config.mjs';
 import { buildRemoteUrl } from './mcp.mjs';
 import { deriveScope } from './scope.mjs';
-import { log, err, heading, status, c } from './util.mjs';
+import { log, err, heading, status, select, c } from './util.mjs';
 
 function ask(question) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
 }
 
-const DEFAULT_ENDPOINT_HINT = 'https://<project-ref>.supabase.co/functions/v1/mcp';
+const DEFAULT_ENDPOINT_HINT = 'https://pqokxlhvnosogizsjztg.supabase.co/functions/v1/mcp';
 
 export async function install(args) {
   const root = resolveProjectRoot(args.dir);
@@ -31,7 +35,26 @@ export async function install(args) {
   heading('LoreKit install');
   log(`  project: ${c.dim(root)}`);
 
-  // 1. Connection details.
+  // 1. Scope: this project, or user-global (every project). --global / --project
+  //    force it; otherwise prompt when interactive, else default to project.
+  let scope = args.global ? 'global' : args.project ? 'project' : null;
+  if (!scope) {
+    if (nonInteractive) {
+      scope = 'project';
+    } else {
+      scope = await select('Install LoreKit for…', [
+        { label: 'This project', value: 'project', hint: 'this repo only (.claude, .mcp.json)' },
+        { label: 'All projects (global)', value: 'global', hint: 'every project (~/.claude)' },
+      ]);
+    }
+  }
+  log(
+    `  install: ${c.dim(
+      scope === 'global' ? 'global — ~/.claude, applies to every project' : 'project — this repo only',
+    )}`,
+  );
+
+  // 2. Connection details.
   let { endpoint, token } = resolveConnection(args);
 
   if (!endpoint) {
@@ -50,46 +73,81 @@ export async function install(args) {
     token = token || null;
   }
 
-  // 2. Install the skill files.
-  const dest = skillInstallDir(root);
+  // 3. Install the skill files.
+  const dest = skillInstallDir(root, scope);
   const skillExisted = fs.existsSync(path.join(dest, 'SKILL.md'));
   const written = copyDir(SKILL_SOURCE, dest, { force: Boolean(args.force) });
 
-  // 3. Wire .mcp.json.
+  // 4. Wire the MCP config for the chosen scope.
   const remoteUrl = buildRemoteUrl(endpoint, token);
-  const { file, existed } = upsertMcpServer(root, remoteUrl);
+  const { file, existed } = upsertMcpServer(root, remoteUrl, scope);
+
+  // 4b. 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'];
+  let hooks = null;
+  if (wireHooks) {
+    hooks = upsertClaudeHooks(root, scope, resolveHookRunner());
+  }
+
+  // Show global paths relative to ~ (a repo-relative path would be a mess of
+  // ../../); project paths stay repo-relative.
+  const display = (p) =>
+    scope === 'global' ? p.replace(homeDir(), '~') : path.relative(root, p) || p;
+  const mcpLabel = scope === 'global' ? '~/.claude.json' : '.mcp.json';
 
-  // 4. Report.
+  // 5. Report.
   heading('Done');
   const skillState = !skillExisted
     ? 'installed'
     : written > 0
       ? `updated (${written} file(s) written)`
       : 'unchanged — pass --force to overwrite';
-  status(skillExisted && written === 0 ? 'info' : 'pass', `skill ${SKILL_NAME}`, `${skillState} → ${path.relative(root, dest) || dest}`);
-  status('pass', '.mcp.json', `${existed ? 'updated' : 'created'} lorekit server → ${path.relative(root, file) || file}`);
+  status(skillExisted && written === 0 ? 'info' : 'pass', `skill ${SKILL_NAME}`, `${skillState} → ${display(dest)}`);
+  status('pass', mcpLabel, `${existed ? 'updated' : 'created'} lorekit server → ${display(file)}`);
+
+  if (!wireHooks) {
+    status('info', 'hooks', 'skipped (--no-hooks) — the skill still works, but lessons are model-invoked only');
+  } else {
+    const n = hooks.added + hooks.updated;
+    const hookState =
+      n === 0
+        ? 'unchanged — already wired'
+        : `${hooks.added ? `${hooks.added} added` : ''}${hooks.added && hooks.updated ? ', ' : ''}${hooks.updated ? `${hooks.updated} updated` : ''}`;
+    status(n === 0 ? 'info' : 'pass', 'hooks', `${hookState} → ${display(hooks.file)} (${CLAUDE_HOOK_EVENTS.join(', ')})`);
+  }
 
   const kind = tokenKind(token);
   if (kind === 'none') {
     status('warn', 'token', 'none configured — reads/writes will fail until a token is set');
   } else if (kind === 'read-only') {
     status('warn', 'token', 'read-only (lk_ro_*) — the skill can read lessons but not write them');
+  } else if (kind === 'write-only') {
+    status('warn', 'token', 'write-only (lk_wo_*) — the skill can write lessons but not read them');
   } else if (kind === 'unknown') {
-    status('warn', 'token', 'unrecognized prefix — expected lk_rw_* or lk_ro_*');
+    status('warn', 'token', 'unrecognized prefix — expected lk_rw_*, lk_ro_*, or lk_wo_*');
   } else {
     status('pass', 'token', 'read+write (lk_rw_*)');
   }
 
-  const scope = deriveScope(root);
-  if (scope.hasRemote) {
-    status('info', 'scope', `${scope.repoScope}${scope.branchScope ? `  ·  ${scope.branchScope}` : ''}`);
+  const gitScope = deriveScope(root);
+  if (gitScope.hasRemote) {
+    status('info', 'scope', `${gitScope.repoScope}${gitScope.branchScope ? `  ·  ${gitScope.branchScope}` : ''}`);
   } else {
     status('warn', 'scope', 'no git remote — lessons will fall back to global');
   }
 
   log(`\n  Next: ${c.cyan('npx @lorekit/cli doctor')} to verify the connection.`);
   if (token) {
-    log(`  ${c.dim('Note: your token now lives in .mcp.json — keep it out of version control.')}`);
+    log(
+      `  ${c.dim(
+        scope === 'global'
+          ? 'Note: your token now lives in ~/.claude.json (used by every project) — keep that file private.'
+          : 'Note: your token now lives in .mcp.json — keep it out of version control.',
+      )}`,
+    );
   }
   return 0;
 }

package/src/mcp-server.mjs

@@ -30,7 +30,24 @@ export const TOOL_DEFS = [
   {
     name: 'memory.write',
     description: 'Store or update a lesson',
-    inputSchema: { type: 'object', required: ['scope', 'key', 'value'] },
+    inputSchema: {
+      type: 'object',
+      required: ['scope', 'key', 'value'],
+      properties: {
+        scope: { type: 'string' },
+        key: { type: 'string' },
+        value: { type: 'string' },
+        tags: { type: 'array', items: { type: 'string' } },
+        source_agent: { type: 'string' },
+        trigger: { type: 'string' },
+        created_at: {
+          type: 'string',
+          format: 'date-time',
+          description:
+            'Optional ISO 8601 creation date for migrating a pre-existing memory. Rejected if invalid or in the future. Applies only when the memory is first created.',
+        },
+      },
+    },
   },
   {
     name: 'memory.read',

package/src/store/created-at.mjs

@@ -0,0 +1,28 @@
+// Zero-dependency mirror of the created_at validation used by the hosted MCP
+// server (packages/mcp-core/src/created-at.ts). Keeps the local `lorekit mcp`
+// stdio server's memory.write contract identical to the remote one: an optional
+// ISO 8601 creation-date override, rejected when invalid or future-dated.
+
+export const CLOCK_SKEW_MS = 60_000;
+
+// Validate and normalise an optional created_at override.
+// Returns the ISO 8601 string, or null when no override was supplied.
+// Throws Error on an invalid or future-dated value.
+export function normalizeCreatedAt(input, now = new Date()) {
+  if (input === undefined || input === null) return null;
+  if (typeof input !== 'string') {
+    throw new Error('created_at must be an ISO 8601 date-time string');
+  }
+  const trimmed = input.trim();
+  if (trimmed === '') {
+    throw new Error('created_at must be an ISO 8601 date-time string');
+  }
+  const ms = Date.parse(trimmed);
+  if (Number.isNaN(ms)) {
+    throw new Error(`created_at is not a valid date-time: ${input}`);
+  }
+  if (ms > now.getTime() + CLOCK_SKEW_MS) {
+    throw new Error('created_at cannot be in the future');
+  }
+  return new Date(ms).toISOString();
+}

package/src/store/local.mjs

@@ -8,6 +8,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { serializeEntry, parseEntry, slugify, scopeToDir } from './format.mjs';
+import { normalizeCreatedAt } from './created-at.mjs';
 
 export function createLocalStore(baseDir) {
   return new LocalStore(baseDir);
@@ -82,19 +83,34 @@ class LocalStore {
 
   // write(...) → { ok, entry } — upsert by scope+key. Preserves `created` and
   // refreshes `updated`; writing an archived key revives it.
-  async write({ scope, key, value, tags, source_agent, trigger } = {}) {
+  //
+  // `created_at` is an optional ISO 8601 override for migrating a pre-existing
+  // memory (mirrors the hosted memory.write param). It applies only when the
+  // entry is first created — on both `created` and `updated`, so a migrated
+  // memory is dated by its original time everywhere — and is ignored for an
+  // existing key (a creation date never moves). Returns { ok:false, error } on
+  // an invalid or future-dated value rather than throwing, matching the store
+  // contract's error surfacing.
+  async write({ scope, key, value, tags, source_agent, trigger, created_at } = {}) {
+    let override;
+    try {
+      override = normalizeCreatedAt(created_at);
+    } catch (e) {
+      return { ok: false, error: e.message };
+    }
     const dir = this._dir(scope);
     fs.mkdirSync(dir, { recursive: true });
     const now = new Date().toISOString();
     const existing = this._findByKey(scope, key);
+    const created = existing ? existing.entry.created || now : override || now;
     const entry = {
       scope,
       key,
       tags: Array.isArray(tags) ? tags : [],
       source_agent: source_agent || null,
       trigger: trigger || null,
-      created: existing ? existing.entry.created || now : now,
-      updated: now,
+      created,
+      updated: existing ? now : override || now,
       archived_at: null,
       value: value == null ? '' : String(value),
     };

package/src/uninstall.mjs

@@ -0,0 +1,114 @@
+// `lorekit uninstall` — reverse `install`: remove the skill, the MCP server
+// entry, and the lifecycle hooks for the chosen scope. Surgical — every other
+// server, hook, and setting is left untouched.
+import path from 'node:path';
+import readline from 'node:readline';
+import process from 'node:process';
+import {
+  SKILL_NAME,
+  resolveProjectRoot,
+  removeSkill,
+  removeMcpServer,
+  removeClaudeHooks,
+  homeDir,
+} from './config.mjs';
+import { log, heading, status, c } from './util.mjs';
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
+}
+
+export async function uninstall(args) {
+  const root = resolveProjectRoot(args.dir);
+  const nonInteractive = Boolean(args.yes) || !process.stdin.isTTY;
+
+  heading('LoreKit uninstall');
+  log(`  project: ${c.dim(root)}`);
+
+  // Mirror install's scope selection: --project / --global force it, else
+  // prompt when interactive, else default to project.
+  let scope = args.global ? 'global' : args.project ? 'project' : null;
+  if (!scope) {
+    if (nonInteractive) {
+      scope = 'project';
+    } else {
+      const ans = (
+        await ask('  Remove from this project or the global install? [project/global] (project): ')
+      ).toLowerCase();
+      scope = ans.startsWith('g') ? 'global' : 'project';
+    }
+  }
+  log(
+    `  scope: ${c.dim(
+      scope === 'global' ? 'global — ~/.claude, applies to every project' : 'project — this repo only',
+    )}`,
+  );
+
+  // Each removal is independent and best-effort: a corrupt or unwritable config
+  // for one target must not crash the run or block the others. `removeMcpServer`
+  // / `removeClaudeHooks` throw on an unparseable file (the same fail-safe as
+  // install — never clobber what we can't understand), so we catch and report it
+  // cleanly, leaving that file byte-for-byte untouched. Atomic writes
+  // (writeFileAtomic) guarantee a config can't be half-written even on a crash.
+  const skill = attempt(() => removeSkill(root, scope));
+  const mcp = attempt(() => removeMcpServer(root, scope));
+  const hooks = attempt(() => removeClaudeHooks(root, scope));
+
+  // Global paths shown relative to ~; project paths repo-relative.
+  const display = (p) =>
+    scope === 'global' ? p.replace(homeDir(), '~') : path.relative(root, p) || p;
+  const mcpLabel = scope === 'global' ? '~/.claude.json' : '.mcp.json';
+
+  heading('Done');
+  report(skill, `skill ${SKILL_NAME}`, {
+    done: (r) => `removed → ${display(r.dest)}`,
+    noop: 'not installed — nothing to remove',
+  });
+  report(mcp, mcpLabel, {
+    done: (r) => `lorekit server removed → ${display(r.file)}`,
+    noop: 'no lorekit server entry — nothing to remove',
+  });
+  report(hooks, 'hooks', {
+    done: (r) => `${r.removed} removed → ${display(r.file)}`,
+    noop: 'no lorekit hooks — nothing to remove',
+  });
+
+  const failed = [skill, mcp, hooks].some((s) => !s.ok);
+  const any = (skill.result?.removed || mcp.result?.removed || hooks.result?.removed) && true;
+
+  if (failed) {
+    log(`\n  ${c.dim('Some items could not be removed and were left untouched — see above.')}`);
+    return 1;
+  }
+  if (!any) {
+    const other = scope === 'global' ? '--project' : '--global';
+    log(`\n  ${c.dim(`Nothing found for the ${scope} scope — try ${other}?`)}`);
+  } else {
+    log(`\n  ${c.dim('Removed. Your other MCP servers, hooks, and settings were left untouched.')}`);
+    log(`  ${c.dim('Note: your token may remain in shell history or env — rotate it if it leaked.')}`);
+  }
+  return 0;
+}
+
+// Run a removal step, converting a throw into a reportable outcome so one bad
+// config can't crash the whole uninstall or leave a stack trace on screen.
+function attempt(fn) {
+  try {
+    return { ok: true, result: fn() };
+  } catch (e) {
+    return { ok: false, error: e };
+  }
+}
+
+// Render one status line for a step: a clean error (file left untouched), a
+// "removed" line, or a "nothing to remove" line.
+function report(step, label, { done, noop }) {
+  if (!step.ok) {
+    status('fail', label, `left untouched — ${step.error.message}`);
+    return;
+  }
+  const r = step.result;
+  const removed = r.removed;
+  status(removed ? 'pass' : 'info', label, removed ? done(r) : noop);
+}

package/src/util.mjs

@@ -40,6 +40,83 @@ export function status(kind, label, detail) {
   log(`  ${mark} ${label}${tail}`);
 }
 
+// Map a raw keypress to a select-list action. Pure so it can be unit-tested
+// without a pseudo-TTY. Supports arrow keys (both the `ESC [` and application
+// `ESC O` cursor modes) and vim-style j/k.
+export function selectAction(key) {
+  if (key === '') return 'cancel'; // Ctrl-C
+  if (key === '\r' || key === '\n') return 'submit';
+  if (key === 'k' || (key.startsWith('') && key.endsWith('A'))) return 'up';
+  if (key === 'j' || (key.startsWith('') && key.endsWith('B'))) return 'down';
+  return null;
+}
+
+// Interactive single-choice list. `options` is [{ label, value, hint? }].
+// Arrow keys / j / k move, Enter selects, Ctrl-C aborts. Falls back to the
+// default option when stdin isn't a TTY (CI / piped input), matching the
+// non-interactive install path. Zero-dependency; renders with raw ANSI.
+export function select(question, options, { defaultIndex = 0 } = {}) {
+  const { stdin, stdout } = process;
+  let index = Math.max(0, Math.min(defaultIndex, options.length - 1));
+
+  if (!stdin.isTTY) return Promise.resolve(options[index].value);
+
+  return new Promise((resolve) => {
+    const render = (first) => {
+      if (!first) stdout.write(`[${options.length}A`); // cursor up N lines
+      for (let i = 0; i < options.length; i++) {
+        const active = i === index;
+        const pointer = active ? c.cyan('❯') : ' ';
+        const label = active ? c.cyan(options[i].label) : options[i].label;
+        const hint = options[i].hint ? ` ${c.dim('— ' + options[i].hint)}` : '';
+        stdout.write(`  ${pointer} ${label}${hint}\n`); // clear line, write
+      }
+    };
+
+    log(`  ${question}`);
+    stdout.write('[?25l'); // hide cursor
+    render(true);
+
+    const prevRaw = Boolean(stdin.isRaw);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    const cleanup = () => {
+      stdin.setRawMode(prevRaw);
+      stdin.pause();
+      stdin.removeListener('data', onData);
+      stdout.write('[?25h'); // show cursor
+    };
+
+    const onData = (key) => {
+      switch (selectAction(key)) {
+        case 'cancel':
+          cleanup();
+          stdout.write('\n');
+          process.exit(130);
+          break;
+        case 'up':
+          index = (index - 1 + options.length) % options.length;
+          render(false);
+          break;
+        case 'down':
+          index = (index + 1) % options.length;
+          render(false);
+          break;
+        case 'submit':
+          cleanup();
+          resolve(options[index].value);
+          break;
+        default:
+          break;
+      }
+    };
+
+    stdin.on('data', onData);
+  });
+}
+
 // Minimal flag parser: --key value, --key=value, -k value, and bare --flags.
 // `aliases` maps short → long; `booleans` lists flags that take no value.
 export function parseArgs(argv, { aliases = {}, booleans = [] } = {}) {