@lorekit/cli 1.35.0 → 1.37.0

package/README.md

@@ -74,6 +74,38 @@ lorekit install \
 lorekit install --global      # set it up for every project
 ```
 
+#### Claude Code on the web (`--mcp-json`)
+
+Claude Code on the web clones the repo fresh into an ephemeral container, so the
+only MCP config it can see is a **committed, repo-root `.mcp.json`** — a global
+`~/.claude.json` lives on your machine and never travels there. `--mcp-json`
+writes exactly that file, in a **committable** form: it authenticates via a
+`${LOREKIT_TOKEN}` reference in an `mcp-remote --header` rather than embedding
+the token, so there is no secret in the file.
+
+```bash
+lorekit install --mcp-json --yes            # web-ready project .mcp.json
+lorekit install --global --mcp-json --yes   # + the machine-wide CLI, skills, hooks
+```
+
+Set **`LOREKIT_TOKEN`** as an environment secret in the web UI; the value is
+expanded before `mcp-remote` is spawned. `--mcp-json` always writes the
+**project-root** file regardless of `--project` / `--global`, and it composes
+with either — pair it with `--global` to get the local CLI, skills, and hooks in
+`~/.claude` **and** the committable web config in one command. On a `--project`
+install it takes over `.mcp.json` with the committable form instead of the
+embedded-token one.
+
+**You have to commit the file, and `.mcp.json` is usually git-ignored** (the
+default install embeds a token, so LoreKit's own `.gitignore` — and many
+projects — ignore it). Un-ignore it before committing (drop the `.mcp.json` line
+from `.gitignore`, negate it with `!.mcp.json`, or `git add -f .mcp.json` once);
+`install --mcp-json` **warns when the file it wrote is still git-ignored**, so a
+fresh web clone silently missing the config is not a mystery. Once `.mcp.json` is
+tracked, only run `install --mcp-json` in that repo — a plain `install --project`
+would embed a live token in the now-committed file. See the
+[Claude Code on the web guide](https://lorekit.io/docs/claude-code-web).
+
 In a TTY it prompts for the scope (and for `--endpoint` / `--token` if missing).
 Flags: `--project` / `--global` pick the scope non-interactively; `--yes` runs
 non-interactively (endpoint required via flag/env; scope defaults to project);
@@ -754,6 +786,7 @@ also returns their headroom against the plan's memory cap.
 | `-y, --yes` | Non-interactive / apply; never prompt |
 | `--hooks <mode>` | Lifecycle hooks to wire: `all` / `read-only` / `none` (`install`; `none` removes any already wired) |
 | `--no-hooks` | Skip wiring the lifecycle hooks; skills + MCP only. Leaves already-wired hooks alone (`install`) |
+| `--mcp-json` | Also write a committable project `.mcp.json` (auth via `${LOREKIT_TOKEN}`, no embedded token) for Claude Code on the web (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
 | `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `link`) |
@@ -882,3 +915,12 @@ at release time and is never committed to git. See
 
 `install` writes your token into `.mcp.json`. Keep that file out of version
 control (LoreKit's root `.gitignore` already ignores `.mcp.json`).
+
+The **one exception is `install --mcp-json`**: that file authenticates via a
+`${LOREKIT_TOKEN}` reference instead of an embedded token, so it holds no secret
+and **is** meant to be committed (that is how Claude Code on the web reads it
+after a fresh clone). You'll need to un-ignore `.mcp.json` first, since it is
+normally git-ignored for the embedded-token reason above. The token itself comes
+from the `LOREKIT_TOKEN` environment variable at runtime — set it as an
+environment secret, never commit it — and once the file is tracked, keep using
+`--mcp-json` so a later plain install never writes a token into it.

package/bin/lorekit.mjs

@@ -43,7 +43,8 @@ ${c.bold('Commands')}
               (~/.claude); --project / --global choose non-interactively.
               Also prompts whether to wire the hooks (all / read-only /
               none); --hooks <mode> chooses non-interactively and --no-hooks
-              skips them (skills stay model-invoked only).
+              skips them (skills stay model-invoked only). --mcp-json also
+              writes a committable project .mcp.json for Claude Code on the web.
   uninstall   Reverse install: remove the lorekit-memory + lorekit-setup skills,
               the MCP server entry, and the lifecycle hooks for the chosen scope. Surgical —
               other servers, hooks, and settings are left untouched. Prompts
@@ -126,6 +127,8 @@ ${c.bold('Options')}
   -y, --yes               Non-interactive / apply; never prompt
       --hooks <mode>      Lifecycle hooks to wire: all | read-only | none (install)
       --no-hooks          Skip wiring the lifecycle hooks (install)
+      --mcp-json          Also write a committable project .mcp.json for Claude Code on
+                          the web — auth via \${LOREKIT_TOKEN}, no embedded secret (install)
       --force             Overwrite existing skill files (install)
       --deep              Do a write→read→delete round-trip (doctor)
       --telemetry         Verify the OTLP export credential works (doctor)
@@ -183,6 +186,14 @@ An interactive run preselects whatever is already wired, so re-running install
 never resurrects hooks you declined. Answering "No hooks" (or --hooks none)
 REMOVES hooks that are already there; --no-hooks only skips wiring new ones.
 
+${c.bold('Claude Code on the web')}
+Add --mcp-json to write a committable project .mcp.json (repo root) that Claude
+Code on the web can see after a fresh clone. It authenticates via a
+\${LOREKIT_TOKEN} reference in an mcp-remote --header — NOT an embedded token —
+so the file is safe to commit; set LOREKIT_TOKEN as an environment secret in the
+web UI. Pair it with --global to get the local CLI, skills, and hooks in
+~/.claude AND the committable web config in one command.
+
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
       --project           Install into this project: .claude/skills + .mcp.json (default)
@@ -191,6 +202,8 @@ ${c.bold('Options')}
   -t, --token <token>     LoreKit token: lk_rw_* read+write, lk_ro_* read-only, lk_wo_* write-only
       --hooks <mode>      Wire the lifecycle hooks: all | read-only | none
       --no-hooks          Skip wiring the lifecycle hooks (leaves existing ones alone)
+      --mcp-json          Also write a committable project .mcp.json (\${LOREKIT_TOKEN} auth)
+                          for Claude Code on the web — always the repo-root file
       --force             Overwrite existing skill files
   -y, --yes               Non-interactive; never prompt (defaults to --project, and to the
                           already-wired hooks — all on a fresh install)
@@ -198,6 +211,8 @@ ${c.bold('Options')}
 ${c.bold('Examples')}
   npx @lorekit/cli install --endpoint https://ref.supabase.co/functions/v1/mcp --token lk_rw_xxx
   npx @lorekit/cli install --global
+  npx @lorekit/cli install --mcp-json --yes          # web-ready project .mcp.json
+  npx @lorekit/cli install --global --mcp-json --yes # local CLI + committable web config
   npx @lorekit/cli install --hooks read-only --yes
   npx @lorekit/cli install --no-hooks --yes
 `,
@@ -631,7 +646,7 @@ ${c.bold('Options')}
 // typo like `--gloabl` should fail loudly, not quietly fall back to --project.
 const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
-  'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'force', 'deep', 'adapter',
+  'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'mcp-json', 'force', 'deep', 'adapter',
   'event', 'json', 'scope', 'key', 'threshold', 'help', 'version', 'telemetry',
   'value', 'tags', 'source-agent', 'trigger', 'kind', 'host', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
   'link', 'base', 'q', 'owner', 'range', 'view', 'archived',
@@ -662,7 +677,7 @@ async function main() {
   const argv = process.argv.slice(2);
   const args = parseArgs(argv, {
     aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
-    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

package/src/config.mjs

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 // packages/cli/ — the installable package root (this file lives in src/).
@@ -366,6 +367,88 @@ export function upsertMcpServer(root, remoteUrl, scope = 'project') {
   return { file, existed };
 }
 
+// The environment variable the committable (web) .mcp.json references for its
+// token, instead of embedding a live secret. Kept as a constant so the writer,
+// the install summary, and the docs can never name a different variable.
+export const WEB_TOKEN_ENV_VAR = 'LOREKIT_TOKEN';
+
+// Strip any credential from an endpoint URL before it goes into the committable
+// web .mcp.json. The whole point of that file is to carry NO secret, so an
+// `--endpoint` / LOREKIT_MCP_URL value that already embeds `?token=lk_…` (a
+// perfectly ordinary thing to paste) must not be written verbatim — that would
+// commit a live token in the file install tells you to commit. Mirrors
+// `splitEndpoint`'s token removal (mcp.mjs) inline rather than importing it, so
+// config.mjs keeps its no-mcp.mjs-import invariant (see resolveProjectConnection),
+// and also clears userinfo for defense in depth. A non-URL string is left as-is;
+// endpoint validity is the caller's concern, not this function's.
+function stripEndpointCredentials(endpoint) {
+  try {
+    const u = new URL(endpoint);
+    u.searchParams.delete('token');
+    u.username = '';
+    u.password = '';
+    return u.toString();
+  } catch {
+    return endpoint;
+  }
+}
+
+// Merge a lorekit server entry into the PROJECT-root .mcp.json in the
+// committable form Claude Code on the web needs: instead of embedding the token
+// in the URL (a live secret, which is why the embedded form is git-ignored), it
+// authenticates via an mcp-remote `--header` that references `${LOREKIT_TOKEN}`.
+//
+// WHY this exists as a distinct writer. Claude Code on the web clones the repo
+// fresh into an ephemeral container, so the only MCP config it can see is a
+// COMMITTED, repo-root `.mcp.json` — a global `~/.claude.json` never travels to
+// the clone. And it must be committable, which the embedded-token form is not.
+// So the web path needs exactly this: the project file (never the global one)
+// with the token supplied at runtime from an environment secret. Callers set
+// `LOREKIT_TOKEN` as an environment secret in the web UI; the value is expanded
+// by Claude Code before mcp-remote is spawned. Preserves any other servers.
+//
+// The endpoint is credential-stripped first: it is the one field that could
+// carry a `?token=` in from `--endpoint` / LOREKIT_MCP_URL, and writing that
+// into a file meant to be committed would leak a live token.
+export function upsertWebMcpServer(root, endpoint, envVar = WEB_TOKEN_ENV_VAR) {
+  const file = mcpJsonPath(root); // always the project file — the web clone only sees this one
+  const config = readJsonIfExists(file) || {};
+  if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+    config.mcpServers = {};
+  }
+  const existed = Boolean(config.mcpServers.lorekit);
+  config.mcpServers.lorekit = {
+    command: 'npx',
+    args: ['-y', 'mcp-remote', stripEndpointCredentials(endpoint), '--header', `Authorization:Bearer \${${envVar}}`],
+  };
+  writeFileAtomic(file, JSON.stringify(config, null, 2) + '\n');
+  return { file, existed };
+}
+
+// Is the project .mcp.json git-ignored in this repo? Tri-state so callers can
+// distinguish "definitely ignored" from "can't tell" and stay quiet when unsure:
+//   true  → ignored (git check-ignore matched)  — the caller warns
+//   false → tracked / not ignored               — nothing to say
+//   null  → unknown (no git, not a repo, error)  — say nothing
+//
+// This exists because the committable web .mcp.json (upsertWebMcpServer) only
+// works if it is actually committed, and .mcp.json is COMMONLY git-ignored (the
+// default embedded-token form is a secret, so LoreKit's own root .gitignore and
+// many projects ignore it). Silently writing a file the repo will never commit
+// is the trap this lets `install --mcp-json` warn about. `git check-ignore -q`
+// exits 0 when ignored, 1 when not, 128 on error — anything but 0/1 is unknown.
+export function isMcpJsonGitIgnored(root) {
+  try {
+    const r = spawnSync('git', ['-C', root, 'check-ignore', '-q', '.mcp.json'], { stdio: 'ignore' });
+    if (r.error) return null; // git not found / spawn failed
+    if (r.status === 0) return true;
+    if (r.status === 1) return false;
+    return null; // 128 (not a repo) or anything unexpected
+  } catch {
+    return null;
+  }
+}
+
 // 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.
@@ -406,6 +489,37 @@ export function removeMcpServer(root, scope = 'project') {
   return { file, removed: true };
 }
 
+// Is a lorekit server entry the committable WEB form — auth via a `--header`
+// that references an `${ENV_VAR}` token, as written by `upsertWebMcpServer` —
+// rather than an embedded-token or plain URL entry? Used to gate the global
+// uninstall's project-file cleanup so it only removes what `--mcp-json` wrote.
+export function isWebMcpServerEntry(server) {
+  const args = server && Array.isArray(server.args) ? server.args : [];
+  const i = args.indexOf('--header');
+  if (i === -1 || typeof args[i + 1] !== 'string') return false;
+  return /^Authorization:Bearer \$\{[^}]+\}$/.test(args[i + 1].trim());
+}
+
+// Remove the lorekit entry from the PROJECT .mcp.json ONLY when it is the
+// committable web form. `uninstall --global` calls this to clean up the file
+// `install --global --mcp-json` wrote — WITHOUT touching an unrelated
+// embedded-token `install --project` entry a user set up separately (which a
+// blind removeMcpServer(root, 'project') would delete). No-op otherwise.
+export function removeWebMcpServer(root) {
+  const file = mcpJsonPath(root);
+  const config = readJsonIfExists(file);
+  const server =
+    config && config.mcpServers && typeof config.mcpServers === 'object'
+      ? config.mcpServers.lorekit
+      : null;
+  if (!server || !isWebMcpServerEntry(server)) 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.
@@ -475,18 +589,29 @@ export function tokenKind(token) {
 // install), then the `mcp.endpoint` field in .lorekit.json (committable URL
 // without token — safe for VCS), then env. `splitEndpoint` is passed in to
 // avoid a circular import with mcp.mjs.
+//
+// A source that STORES a token wins outright (project beats global — closest
+// scope), but a TOKENLESS source must NOT shadow a later source that has one.
+// That shadowing is exactly what `install --global --mcp-json` created: it
+// writes a committable, token-free project .mcp.json (auth via ${LOREKIT_TOKEN})
+// AND the real token into ~/.claude.json. Returning early on the project entry
+// left the local CLI, doctor, and hooks resolving `token: null` unless
+// LOREKIT_TOKEN was exported — so a tokenless source is only remembered as an
+// endpoint fallback, and the loop keeps looking for a stored token.
 export function resolveProjectConnection(root, splitEndpoint) {
   const sources = [readLorekitServer(root), readServerFromFile(mcpConfigPath(root, 'global'))];
+  let endpointOnly = null; // closest usable endpoint that carried no token (e.g. the web .mcp.json)
   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,
-        };
-      }
-    }
+    if (!configured || !configured.url) continue;
+    const { endpoint, token } = splitEndpoint(configured.url);
+    if (!endpoint || endpoint.includes('<project-ref>')) continue;
+    if (token) return { endpoint, token }; // a stored token wins; project (closest) beats global
+    if (!endpointOnly) endpointOnly = endpoint; // remember the closest tokenless source, keep looking
+  }
+  if (endpointOnly) {
+    // No source stored a token — the committable web .mcp.json is exactly this
+    // case. Fall back to the env token so the local CLI still authenticates.
+    return { endpoint: endpointOnly, token: process.env.LOREKIT_TOKEN || null };
   }
 
   // Fallback: `mcp.endpoint` in .lorekit.json — a committable URL without token.

package/src/install.mjs

@@ -9,6 +9,9 @@ import {
   skillInstallDir,
   copyDir,
   upsertMcpServer,
+  upsertWebMcpServer,
+  isMcpJsonGitIgnored,
+  WEB_TOKEN_ENV_VAR,
   upsertClaudeHooks,
   resolveHookRunner,
   HOOK_MODES,
@@ -194,6 +197,12 @@ export async function install(args) {
   // circuits). `--no-hooks` is skip-only and never justifies that bypass.
   const hooksFlagExplicit = typeof args.hooks === 'string' && args.hooks.trim() !== '';
 
+  // `--mcp-json` writes a committable, env-var-referencing project .mcp.json for
+  // Claude Code on the web (see upsertWebMcpServer). It is an explicit intent to
+  // (re)write that file, so — like an explicit `--hooks` — it must reach the
+  // write step even when the scope is already fully installed.
+  const writeWebMcpJson = Boolean(args['mcp-json']);
+
   heading('LoreKit install');
   log(`  project: ${c.dim(root)}`);
 
@@ -219,7 +228,7 @@ export async function install(args) {
 
   const wiredEvents = installedHookEvents(root, scope);
 
-  if (currentState.isFullyInstalled && !force && !hooksFlagExplicit) {
+  if (currentState.isFullyInstalled && !force && !hooksFlagExplicit && !writeWebMcpJson) {
     // Surface a clear, useful already-installed summary.
     log('');
     log(
@@ -345,8 +354,28 @@ export async function install(args) {
   });
 
   // 5. Wire the MCP config for the chosen scope.
+  //    When `--mcp-json` is going to (re)write the PROJECT .mcp.json in its
+  //    committable form and the scope target IS that same file (project scope),
+  //    skip this write — otherwise we would write an embedded-token file only to
+  //    overwrite it with the committable one a moment later. A global scope
+  //    targets ~/.claude.json, a different file, so it always writes.
   const remoteUrl = buildRemoteUrl(endpoint, token);
-  const { file, existed } = upsertMcpServer(root, remoteUrl, scope);
+  const scopeWriteOwnedByWeb = writeWebMcpJson && scope === 'project';
+  let file = null;
+  let existed = false;
+  if (!scopeWriteOwnedByWeb) {
+    ({ file, existed } = upsertMcpServer(root, remoteUrl, scope));
+  }
+
+  // 5a. `--mcp-json`: write the committable, env-var-referencing project
+  //     .mcp.json for Claude Code on the web (see upsertWebMcpServer). Always
+  //     the repo-root file, regardless of scope — that is the only MCP config a
+  //     fresh web clone can see. The token is NOT embedded here: the file
+  //     references `${LOREKIT_TOKEN}`, set as an environment secret in the web UI.
+  let webMcp = null;
+  if (writeWebMcpJson) {
+    webMcp = upsertWebMcpServer(root, endpoint, WEB_TOKEN_ENV_VAR);
+  }
 
   // 5b. Hooks — the deterministic layer the Claude plugin adds on top of the
   //     skill, firing the shared `lorekit hook` engine (which reads the same
@@ -427,7 +456,30 @@ export async function install(args) {
         : 'already up to date';
     status(s.existed && s.written === 0 ? 'info' : 'pass', `skill ${s.name}`, `${skillState} → ${display(s.dest)}`);
   }
-  status('pass', mcpLabel, `${existed ? 'updated' : 'created'} lorekit server → ${display(file)}`);
+  if (file) {
+    status('pass', mcpLabel, `${existed ? 'updated' : 'created'} lorekit server → ${display(file)}`);
+  }
+  if (webMcp) {
+    // The committable web form: reported separately so it is clear this file is
+    // meant to be committed (unlike the embedded-token form) and that the token
+    // comes from an environment secret rather than the file.
+    const webPath = path.relative(root, webMcp.file) || webMcp.file;
+    status(
+      'pass',
+      '.mcp.json (web)',
+      `${webMcp.existed ? 'updated' : 'created'} committable lorekit server (auth via \${${WEB_TOKEN_ENV_VAR}}) → ${webPath}`,
+    );
+    // The web file only works if it is actually committed, and .mcp.json is
+    // commonly git-ignored (the embedded-token form is a secret). Warn when it
+    // is, so a fresh web clone silently missing the config is not a mystery.
+    if (isMcpJsonGitIgnored(root) === true) {
+      status(
+        'warn',
+        '.mcp.json (git)',
+        'git-ignored — un-ignore it (add `!.mcp.json` to .gitignore, or `git add -f .mcp.json`) or a fresh web clone will not see it',
+      );
+    }
+  }
 
   if (!touchHooks) {
     status(
@@ -465,8 +517,29 @@ export async function install(args) {
   }
 
   const kind = tokenKind(token);
-  if (kind === 'none') {
-    status('warn', 'token', 'none configured — reads/writes will fail until a token is set');
+  if (scopeWriteOwnedByWeb) {
+    // `--project --mcp-json`: the committable web .mcp.json is the ONLY config
+    // written, and it references ${LOREKIT_TOKEN} rather than storing a token —
+    // so NOTHING persists a credential here. Reporting the token's tier would
+    // imply it was configured; instead say it is not stored (and that a passed
+    // --token was therefore not persisted), pointing at the environment secret.
+    status(
+      'warn',
+      'token',
+      `not stored — the committable .mcp.json resolves \${${WEB_TOKEN_ENV_VAR}} at runtime; set it as an environment secret${
+        token ? ' (any --token you passed is not persisted)' : ''
+      }`,
+    );
+  } else if (kind === 'none') {
+    // A global --mcp-json with no token still writes the web file; explain the
+    // runtime resolution rather than implying reads/writes will fail.
+    status(
+      'warn',
+      'token',
+      webMcp
+        ? `none stored — the committable .mcp.json resolves \${${WEB_TOKEN_ENV_VAR}} at runtime; set it as an environment secret`
+        : '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 memories but not write them');
   } else if (kind === 'write-only') {
@@ -485,15 +558,26 @@ export async function install(args) {
   }
 
   log(`\n  Next: ${c.cyan('npx @lorekit/cli doctor')} to verify the connection.`);
-  if (token) {
+  // Where the token lives, and how to treat that file, depends on which MCP
+  // configs were written. The web `.mcp.json` never holds the token, so a
+  // project scope that was owned by `--mcp-json` gets the web guidance, not the
+  // "keep it out of version control" note that applies to the embedded form.
+  if (webMcp) {
     log(
       `  ${c.dim(
-        scope === 'global'
-          ? 'Note: your token is stored in ~/.claude.json (used by every project) — keep that file private.'
-          : 'Note: your token is stored in .mcp.json — keep it out of version control.',
+        `For Claude Code on the web: commit .mcp.json (it is often git-ignored — un-ignore it first), then set ${WEB_TOKEN_ENV_VAR} as an environment secret. The file references the token, so it never holds the secret itself.`,
       )}`,
     );
   }
+  if (token && scope === 'global') {
+    log(
+      `  ${c.dim('Note: your token is stored in ~/.claude.json (used by every project) — keep that file private.')}`,
+    );
+  } else if (token && scope === 'project' && !scopeWriteOwnedByWeb) {
+    log(
+      `  ${c.dim('Note: your token is stored in .mcp.json — keep it out of version control.')}`,
+    );
+  }
   // 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.

package/src/mcp-server.mjs

@@ -146,6 +146,17 @@ export const MEMORY_TOOL_DEFS = [
     description: 'Soft-archive a memory. Hidden from reads but restorable.',
     inputSchema: { type: 'object', required: ['scope', 'key'] },
   },
+  {
+    name: 'memory.scopes',
+    // The description tells the model WHEN to reach for this, not just what it
+    // returns: every other read tool needs a scope named up front, so this is
+    // the one that answers "what is there?" before you can ask "what is in it?".
+    description:
+      'List every scope in the store with how many active memories it holds — '
+      + 'the inventory to consult when you do not already know which scope to read. '
+      + 'Takes no arguments and is store-wide, NOT limited to the current directory.',
+    inputSchema: { type: 'object', properties: {} },
+  },
 ];
 
 // Org tools — always advertised regardless of memory mode. They always route
@@ -215,8 +226,117 @@ const MEMORY_DISPATCH = {
   'memory.search': (store, a) => store.search(a),
   'memory.delete': (store, a) => store.delete(a),
   'memory.archive': (store, a) => store.archive(a),
+  'memory.scopes': (store) => listScopes(store),
 };
 
+// `memory.scopes` — the store-wide inventory, normalised.
+//
+// This exists because an agent that cannot enumerate scopes cannot know what it
+// does not know. `memory.list` and `memory.search` both need a scope (or a
+// scope list) up front, so without this the only reachable lore is the lore
+// whose scope the agent could already name — and the SessionStart injection is
+// deliberately a bounded slice, not an index of the whole store. `GET
+// /memories/scopes` and the `lorekit scopes` command have answered this since
+// migration 00039; the MCP surface was the one caller that could not ask.
+//
+// THE TWO STORES ANSWER IN DIFFERENT SHAPES, and normalising here is the whole
+// job of this function. `LocalStore`/`TwoTierStore.listScopes()` return a BARE
+// ARRAY (`[{ scope, count }]`), while `RemoteStore.listScopes()` returns the
+// standard `{ ok, scopes }` envelope — or `{ ok: false, error, networkError,
+// unusable }`. A tool that passed either through verbatim would hand the model
+// two different contracts for one tool name depending on a config value it
+// cannot see.
+//
+// DEGRADATION IS EXIT-CLEAN, mirroring the `scopes` command, which reports an
+// unreachable remote as a short note at exit 0 rather than failing the run. An
+// inventory that cannot be built is `{ scopes: [], note }` with `ok: true`, so
+// `toolResult` does NOT mark it `isError`: "I could not enumerate" is a fact
+// about the store, not a failed tool call, and a model that receives a
+// tool-level error is liable to retry it rather than carry on with the lore it
+// can already reach. The note says which, in bounded, non-PII terms.
+export async function listScopes(store) {
+  let res;
+  try {
+    res = await store.listScopes();
+  } catch (e) {
+    // A store that cannot enumerate must not take the session down with it.
+    return { ok: true, scopes: [], note: `scope enumeration failed: ${errText(e)}` };
+  }
+
+  // Local/two-tier: the bare array form.
+  if (Array.isArray(res)) return { ok: true, scopes: sortScopes(res.map(shapeScope)) };
+
+  // Remote: the envelope form.
+  if (res && res.ok) {
+    return { ok: true, scopes: sortScopes((Array.isArray(res.scopes) ? res.scopes : []).map(shapeScope)) };
+  }
+
+  return { ok: true, scopes: [], note: scopeFailureNote(res) };
+}
+
+// Sorted by scope ascending, which is the contract `docs/mcp-tools.md`, the
+// tool catalog and `llms.txt` all state for `memory.scopes`. The HOSTED surface
+// gets that ordering from `lorekit_memory_scopes` (`order by m.scope asc`,
+// migration 00039/00049), but `LocalStore`/`TwoTierStore.listScopes()` both
+// return their `Map` insertion order — a walk order, not an ordering — so the
+// stdio server owns it here rather than the two surfaces answering differently.
+// Sorting BOTH shapes (not just the local one) makes the guarantee a property
+// of this function instead of an assumption about the store it was handed.
+// Codepoint comparison, deliberately not `localeCompare`: the ordering must not
+// depend on the HOST's locale.
+//
+// That is ascending-by-scope, not byte-identical parity with the hosted path,
+// and the difference is worth being precise about. `order by m.scope asc` sorts
+// under the DATABASE's collation (`en_US.UTF-8` on a default Supabase project),
+// which does not order like codepoint around punctuation — and a scope string
+// is mostly punctuation (`::`, `/`, `-`), so `repo::a-b` and `repo::ab` can come
+// out in the opposite relative order on the two surfaces. Case cannot differ
+// (every scope segment is lowercased, see docs/scope-format.md). Closing the
+// remaining gap means `collate "C"` on the RPC's `order by`, which changes the
+// order `GET /memories/scopes` has always returned — a public contract change
+// that belongs in its own migration, not here. Until then: both surfaces are
+// sorted ascending, neither is unordered, and nothing should depend on the two
+// agreeing on the exact position of a punctuated neighbour.
+function sortScopes(rows) {
+  return rows.sort((a, b) => (a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : 0));
+}
+
+// One inventory row. `last_activity` is passed through when the store supplied
+// it (the hosted `GET /memories/scopes` has returned it since migration 00049)
+// and OMITTED — never null — when it did not, so a client can tell "this store
+// does not report freshness" from "this scope has no activity".
+function shapeScope(s) {
+  const scope = String(s?.scope ?? '');
+  const count = Number(s?.count);
+  const row = { scope, count: Number.isFinite(count) ? count : 0 };
+  const last = s?.last_activity ?? s?.lastActivity;
+  return last ? { ...row, last_activity: last } : row;
+}
+
+// A short, bounded reason an enumeration produced nothing. Deliberately built
+// here rather than reusing `lessons-view.mjs`'s `describeError`: that module
+// carries the whole render/`util` stack, and this server has kept clear of it.
+// The vocabulary matches what that helper reports, so the two read alike.
+function scopeFailureNote(res) {
+  if (!res) return 'the store returned no result';
+  if (res.unusable) return 'no usable store is configured';
+  if (res.networkError) return `network error: ${String(res.networkError).slice(0, 200)}`;
+  // `httpStatus` is the ONLY field that carries a real status: `restFetch`'s
+  // error object is `{ message, code }`, and `code` is the response body's own
+  // application code on a JSON error, so rendering it as "HTTP <code>" would
+  // print a non-status. Read the top-level field first — that is the one
+  // `RemoteStore.listScopes()` passes through — and keep the nested read as a
+  // tolerance for any store that nests it instead.
+  const status = res.httpStatus ?? res.error?.httpStatus;
+  if (status) return `request failed with HTTP ${status}`;
+  if (res.error?.message) return String(res.error.message).slice(0, 200);
+  return 'the store could not enumerate its scopes';
+}
+
+function errText(e) {
+  return String(e?.message ?? e).slice(0, 200);
+}
+
 // Provenance for a tool call: the caller's explicit values win, the working
 // directory and CI environment fill the rest. Best-effort — a failure to shell
 // out to git must never fail the write, so it degrades to no origin at all.

package/src/store/remote.mjs

@@ -217,11 +217,43 @@ class RemoteStore {
   // is not relied upon (the server sorts by scope asc; the view re-sorts by
   // scope type). Failures use this store's standard `{ ok:false, error,
   // networkError }` envelope so the caller can degrade gracefully.
+  //
+  // `httpStatus` is carried through VERBATIM from `restFetch`, which is the ONLY
+  // place the real status lives: its error object holds `{ message, code }`,
+  // where `code` is the response body's own application code on a JSON error
+  // (a string like `permission_denied`) and only incidentally the status on a
+  // non-JSON one. A consumer that wants to say "HTTP 403" must therefore read
+  // `httpStatus`, never `error.code` — `mcp-server.mjs`'s `scopeFailureNote`
+  // does exactly that, and it had nothing to read until this field was passed
+  // through. Additive: `scopes.mjs`, `stats.mjs` and `lessons-view.mjs` all
+  // branch on `ok` / `unusable` / `networkError` and ignore the extra key.
   async listScopes() {
     const res = await this._rest('/memories/scopes');
-    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError, unusable: res.unusable };
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: res.error,
+        httpStatus: res.httpStatus,
+        networkError: res.networkError,
+        unusable: res.unusable,
+      };
+    }
     const scopes = Array.isArray(res.data?.scopes) ? res.data.scopes : [];
-    return { ok: true, scopes: scopes.map((s) => ({ scope: s.scope, count: Number(s.count) || 0 })) };
+    // `last_activity` (migration 00049) is `max(created_at)` over exactly the
+    // counted rows — per-scope freshness without listing rows to reduce them,
+    // which is the row-cap trap this endpoint exists to avoid. It is passed
+    // through when present and OMITTED when absent (an older backend, or the
+    // offline store, which has no equivalent), so a consumer can tell "this
+    // store does not report freshness" from "this scope has none". Callers that
+    // read only `{ scope, count }` — `scopes.mjs`, `stats.mjs` — are unaffected.
+    return {
+      ok: true,
+      scopes: scopes.map((s) => ({
+        scope: s.scope,
+        count: Number(s.count) || 0,
+        ...(s.last_activity ? { last_activity: s.last_activity } : {}),
+      })),
+    };
   }
 
   // Authentication probe for doctor — does the configured token STILL work?

package/src/uninstall.mjs

@@ -9,6 +9,7 @@ import {
   resolveProjectRoot,
   removeSkill,
   removeMcpServer,
+  removeWebMcpServer,
   removeClaudeHooks,
   homeDir,
 } from './config.mjs';
@@ -56,6 +57,15 @@ export async function uninstall(args) {
     step: attempt(() => removeSkill(root, scope, skill.name)),
   }));
   const mcp = attempt(() => removeMcpServer(root, scope));
+  // `install --global --mcp-json` writes the committable project .mcp.json in
+  // ADDITION to ~/.claude.json, so a GLOBAL uninstall must also clear that
+  // entry or it orphans a lorekit server pointing at a now-removed setup. A
+  // project uninstall already targets .mcp.json via `mcp` above, so this is
+  // global-only. `removeWebMcpServer` removes ONLY the committable web form, so
+  // it never deletes an unrelated embedded-token `install --project` entry a
+  // user set up separately. Surgical and idempotent: no web file ⇒ a quiet
+  // "nothing to remove", other servers in the file are preserved.
+  const webMcp = scope === 'global' ? attempt(() => removeWebMcpServer(root)) : null;
   const hooks = attempt(() => removeClaudeHooks(root, scope));
 
   // Global paths shown relative to ~; project paths repo-relative.
@@ -74,15 +84,26 @@ export async function uninstall(args) {
     done: (r) => `lorekit server removed → ${display(r.file)}`,
     noop: 'no lorekit server entry — nothing to remove',
   });
+  if (webMcp) {
+    // Always the repo-relative project path, even under a global uninstall.
+    report(webMcp, '.mcp.json (web)', {
+      done: (r) => `lorekit server removed → ${path.relative(root, r.file) || r.file}`,
+      noop: 'no committable project .mcp.json — nothing to remove',
+    });
+  }
   report(hooks, 'hooks', {
     done: (r) => `${r.removed} removed → ${display(r.file)}`,
     noop: 'no lorekit hooks — nothing to remove',
   });
 
   const skillStepList = skillSteps.map((s) => s.step);
-  const failed = [...skillStepList, mcp, hooks].some((s) => !s.ok);
+  const webSteps = webMcp ? [webMcp] : [];
+  const failed = [...skillStepList, mcp, ...webSteps, hooks].some((s) => !s.ok);
   const any =
-    (skillStepList.some((s) => s.result?.removed) || mcp.result?.removed || hooks.result?.removed) && true;
+    (skillStepList.some((s) => s.result?.removed) ||
+      mcp.result?.removed ||
+      webMcp?.result?.removed ||
+      hooks.result?.removed) && true;
 
   if (failed) {
     log(`\n  ${c.dim('Some items could not be removed and were left untouched — see above.')}`);