@lorekit/cli 1.34.0 → 1.36.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,11 +646,13 @@ ${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',
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
+  // Scale-aware survey flags
+  'all', 'max', 'since', 'until', 'key-prefix',
 ];
 
 // Commands that write to disk / talk to the network on a human's behalf. These
@@ -660,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'],
+    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.34.0",
+  "version": "1.36.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/skill/lorekit-groom/SKILL.md

@@ -117,8 +117,9 @@ archiving and deleting always go through `memory.delete` / `memory.archive`.
 |-----|-----|---------|
 | Count lessons per scope/store | `lorekit stats [--scope <s>]` | CLI (read) |
 | Inventory every scope + lesson count | `lorekit scopes` | CLI (read) |
-| Find low-quality lessons | `lorekit lint --json` | CLI (read) |
-| Find near-duplicate clusters | `lorekit dedupe --json [--threshold <n>]` | CLI (read) |
+| Find low-quality lessons | `lorekit lint --json [--since <date>] [--until <date>] [--max <n>]` | CLI (read) |
+| Find near-duplicate clusters | `lorekit dedupe --json [--threshold <n>] [--key-prefix <p>] [--since <date>] [--max <n>]` | CLI (read) |
+| List all lessons across large scopes | `lorekit list --all [--max <n>] [--since <date>] [--until <date>]` | CLI (read) |
 | Read one lesson in full | `lorekit show <scope::key> [--json]` | CLI (read) |
 | Compare offline vs remote | `lorekit diff` | CLI (read) |
 | Write the merged/consolidated lesson | `memory.write` (or `lorekit write`) | MCP / CLI |
@@ -126,6 +127,37 @@ archiving and deleting always go through `memory.delete` / `memory.archive`.
 | Archive a lesson (reversible) | `memory.archive` (or `memory.delete`) | **MCP only** |
 | Hard-delete a lesson (permanent) | `memory.delete { force: true }` | **MCP only** |
 
+### Survey flags for large scopes
+
+When a scope holds more lessons than a single page (> 50 for `list`, > 100 for
+`lint`/`dedupe`), use these flags to survey the full population or narrow it:
+
+| Flag | Commands | Effect |
+|------|----------|--------|
+| `--all` | `list` | Drain all pages (default for `lint`/`dedupe`) |
+| `--max <n>` | `list --all`, `lint`, `dedupe` | Hard cap on entries surveyed (default 5000) |
+| `--since <iso-date>` | `list --all`, `lint`, `dedupe` | Lower date bound (`created_since`) |
+| `--until <iso-date>` | `list --all`, `lint`, `dedupe` | Upper date bound (`created_until`) |
+| `--key-prefix <p>` | `dedupe` | Narrow deduplication to keys starting with prefix |
+
+`dedupe` applies an internal population cap of 2000 for memory safety. When the
+cap is reached, the output includes a warning with narrowing suggestions — use
+`--key-prefix` or `--since` to reduce the population.
+
+### MCP cursor paging
+
+`memory.list` and `memory.search` now support pagination. When more results
+exist than fit in one response, the response includes `hasMore: true` and a
+`nextCursor` string. Pass `nextCursor` as the `cursor` argument on the next
+call to retrieve the following page. Omit `cursor` to start from the first page.
+
+```json
+{ "scope": "global", "limit": 100, "cursor": "<nextCursor from previous response>" }
+```
+
+Use this to drain an arbitrarily large scope in an agent loop rather than
+relying on a truncated first page.
+
 > **`dedupe` is a heuristic, not a semantic judge.** It clusters on Jaccard
 > word-token overlap, so it can both miss reworded duplicates *and* group
 > coincidental ones. Treat every cluster as a candidate to read and decide on,

package/skill/lorekit-groom/rules/grooming-pass.md

@@ -23,9 +23,21 @@ lorekit scopes           # every scope in the store + its lesson count
 how you notice a `branch::…` scope you had forgotten about, or a scope with
 hundreds of lessons that dwarfs the rest. Neither command reports a
 last-activity date — the inventory is counts only — so judge staleness from the
-lessons themselves once you narrow in (`lorekit list --scope <scope>` tags each
-one with its `updated` date). Read both, then pick the noisiest scope as the
-target for this pass and narrow to it with `--scope <scope>` from here on.
+lessons themselves once you narrow in. Read both, then pick the noisiest scope as
+the target for this pass and narrow to it with `--scope <scope>` from here on.
+
+**Large scopes:** when a scope has more lessons than a single page, use:
+
+```bash
+lorekit list --all --scope <scope>           # drain all pages; tags each lesson with its updated date
+lorekit list --all --scope <scope> --max 500 # cap at 500 to get a representative sample
+lorekit list --all --scope <scope> --since 2024-01-01  # only lessons created since that date
+```
+
+The remote store is paginated (default 50 entries per `list` call, 100 per
+`lint`/`dedupe` call). `--all` drains every page; `--max` applies a hard cap
+(default 5000). `lint` and `dedupe` default to full-scope survey — add `--max`
+or `--since` when the population is large enough to slow things down.
 
 ## Phase 2 — Lint (read-only)
 
@@ -56,6 +68,9 @@ makes it a clean CI gate — a passing `lint` is your Phase 6 proof.
 
 ```bash
 lorekit dedupe --json --scope <scope> --threshold 0.85
+# For large scopes, narrow the population:
+lorekit dedupe --json --scope <scope> --threshold 0.85 --key-prefix "debug-" --max 1000
+lorekit dedupe --json --scope <scope> --threshold 0.85 --since 2024-01-01
 ```
 
 Each cluster is a set of lessons whose values overlap heavily by word tokens.
@@ -64,6 +79,11 @@ Start high (`0.85`) to see the confident duplicates, then re-run lower (`0.75`,
 clusters are coincidental overlaps rather than true duplicates, so read more
 carefully.
 
+`dedupe` surveys the full scope by default. When the population exceeds 2000
+entries it stops and prints a narrowing warning — use `--key-prefix` to focus
+on a key namespace, or `--since` to limit the date range. The `--max` flag sets
+a lower cap (default 5000, internal safety cap at 2000).
+
 For every cluster you intend to act on, read the members in full first:
 
 ```bash

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/dedupe.mjs

@@ -15,18 +15,30 @@ import { resolveProjectRoot, readLorekitJson } from './config.mjs';
 import { deriveScope } from './scope.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { scopeList, gather, clusterDuplicates } from './lessons-view.mjs';
+import { scopeList, gather, gatherStream, clusterDuplicates, clusterDuplicatesBlocked, DEFAULT_MAX } from './lessons-view.mjs';
 import { log, heading, status, c } from './util.mjs';
 
 const DEFAULT_THRESHOLD = 0.8;
+// Maximum entries to accumulate before the token-blocking index becomes
+// memory-prohibitive. Beyond this the user must narrow via --key-prefix /
+// --since / --max.
+const DEDUPE_POP_CAP = 2000;
 
-// Parse `--threshold` into a number in [0, 1]; anything unparseable or out of
+// Smallest threshold the blocked clusterer accepts. `clusterDuplicatesBlocked`
+// is provably equivalent to the oracle `clusterDuplicates` only for
+// threshold > 0 (at 0 the oracle clusters even zero-overlap pairs, which the
+// token-blocking sweep never generates). Any positive value below the smallest
+// possible Jaccard behaves identically to 0+ while preserving that invariant,
+// so we floor to a tiny epsilon rather than accept a literal 0.
+const MIN_THRESHOLD = Number.EPSILON;
+
+// Parse `--threshold` into a number in (0, 1]; anything unparseable or out of
 // range falls back to the default (never a crash on bad input). Pure-ish helper.
 export function parseThreshold(raw) {
   if (raw === undefined || raw === true) return DEFAULT_THRESHOLD;
   const n = Number(raw);
   if (!Number.isFinite(n)) return DEFAULT_THRESHOLD;
-  return Math.min(1, Math.max(0, n));
+  return Math.min(1, Math.max(MIN_THRESHOLD, n));
 }
 
 // Read `dedupe.threshold` from .lorekit.json (non-throwing). Returns the
@@ -78,19 +90,93 @@ export async function dedupe(args) {
   // Deny-wins section suppression, identical to the other read commands.
   const { localDenied, remoteDenied } = resolveDenies(root, { env });
 
-  const buildSection = (flat) => ({
-    available: true,
-    clusters: clusterDuplicates(flat.entries, threshold),
-    errored: flat.errored,
-  });
+  // `dedupe` defaults to full-scope survey. --max, --since, --key-prefix narrow
+  // the population. Population cap: 2000. Past it stop accumulating, warn, and
+  // surface a narrowing hint. Use token-blocking (`clusterDuplicatesBlocked`)
+  // for the one super-linear operation.
+  const surveyMax = args.max !== undefined ? Number(args.max) : DEFAULT_MAX;
+  const surveySince = args.since || undefined;
+  const surveyUntil = args.until || undefined;
+  const surveyKeyPrefix = args['key-prefix'] || undefined;
+
+  // Stream-accumulate entries up to DEDUPE_POP_CAP and note when capped.
+  async function streamAccumulate(store) {
+    const accumulated = [];
+    const errored = [];
+    let popCapped = false;
+
+    await gatherStream(store, scopes, {
+      max: surveyMax,
+      since: surveySince,
+      until: surveyUntil,
+      keyPrefix: surveyKeyPrefix,
+      onPage: ({ scope, entries }) => {
+        if (popCapped) return;
+        for (const e of entries) {
+          if (accumulated.length >= DEDUPE_POP_CAP) {
+            popCapped = true;
+            break;
+          }
+          accumulated.push({ ...e, scope: e.scope ?? scope });
+        }
+      },
+    });
+
+    return { entries: accumulated, errored, popCapped };
+  }
+
+  const buildSection = async (store, local) => {
+    if (local) {
+      // Local store is already exhaustive; gather everything, then apply the
+      // SAME narrowing the remote path gets server-side (the local store's
+      // `list()` honours only scope/tags, so it can't narrow itself). Filtering
+      // here — before the population cap — is what makes `--key-prefix`/
+      // `--since`/`--until`/`--max` real offline instead of silent no-ops.
+      const flat = flatten(await gather(store, scopes));
+      let entries = flat.entries;
+      if (surveyKeyPrefix) {
+        entries = entries.filter(
+          (e) => typeof e.key === 'string' && e.key.startsWith(surveyKeyPrefix),
+        );
+      }
+      // `created_at` is compared as an ISO string; both bounds mirror the REST
+      // handler — inclusive `since`, exclusive `until` (the `[since, until)`
+      // window). An entry with no `created` timestamp is kept (never dropped by
+      // a bound it can't be judged against).
+      if (surveySince) entries = entries.filter((e) => !e.created || e.created >= surveySince);
+      if (surveyUntil) entries = entries.filter((e) => !e.created || e.created < surveyUntil);
+      // Silent `--max` cap first, then the memory-safety population cap that
+      // drives the "partial results" warning — mirroring the remote path where
+      // gatherStream's `max` and the DEDUPE_POP_CAP are distinct.
+      if (entries.length > surveyMax) entries = entries.slice(0, surveyMax);
+      let popCapped = false;
+      if (entries.length > DEDUPE_POP_CAP) {
+        entries = entries.slice(0, DEDUPE_POP_CAP);
+        popCapped = true;
+      }
+      return {
+        available: true,
+        clusters: clusterDuplicatesBlocked(entries, threshold),
+        errored: flat.errored,
+        popCapped,
+      };
+    }
+    const { entries, errored, popCapped } = await streamAccumulate(store);
+    return {
+      available: true,
+      clusters: clusterDuplicatesBlocked(entries, threshold),
+      errored,
+      popCapped,
+    };
+  };
 
   const offlineSection = localDenied
     ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }
-    : buildSection(flatten(await gather(local, scopes)));
+    : await buildSection(local, true);
 
   const remoteAvailable = !remoteDenied && remote.usable();
   const remoteSection = remoteAvailable
-    ? buildSection(flatten(await gather(remote, scopes)))
+    ? await buildSection(remote, false)
     : {
         available: false,
         reason: remoteDenied
@@ -109,6 +195,13 @@ export async function dedupe(args) {
     log(`  scopes:  ${scopes.join('  →  ')}`);
     log(`  ${c.dim(`heuristic: Jaccard word-token overlap >= ${threshold} (not semantic)`)}`);
 
+    if (offlineSection.available && offlineSection.popCapped) {
+      log(`  ${c.yellow('!')} population cap (${DEDUPE_POP_CAP}) reached for Offline — results are partial. Narrow with --key-prefix, --since, or --max.`);
+    }
+    if (remoteSection.available && remoteSection.popCapped) {
+      log(`  ${c.yellow('!')} population cap (${DEDUPE_POP_CAP}) reached for Remote — results are partial. Narrow with --key-prefix, --since, or --max.`);
+    }
+
     renderDedupeSection({ title: 'Offline' }, offlineSection);
     renderDedupeSection(
       { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined },

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/lessons-view.mjs

@@ -65,6 +65,7 @@ export function normalizeEntry(e = {}) {
     key: e.key ?? null,
     value: e.value == null ? '' : String(e.value),
     updated: e.updated ?? e.updated_at ?? null,
+    created: e.created ?? e.created_at ?? null,
     tags,
     kind: e.kind ?? inferred.kind ?? null,
     host: e.host ?? inferred.host ?? null,
@@ -433,6 +434,8 @@ export function clusterDuplicates(entries = [], threshold = 0.8) {
 // `store.list({scope})` contract. Returns ordered per-scope groups plus a total
 // — a per-scope read failure is captured on the group, never thrown, so one bad
 // scope can't abort the listing. `store` may be a local or remote store.
+// Single-page only (the existing default behaviour). For full-scope traversal
+// use `gatherStream` below.
 export async function gather(store, scopes, filters = {}) {
   // Parse the taxonomy filters into value sets. `filters` is passed to the store
   // too (the remote narrows server-side); we ALSO post-filter the normalized
@@ -468,6 +471,208 @@ export async function gather(store, scopes, filters = {}) {
   return { groups, total };
 }
 
+// Default maximum entries to survey in a full-scope traversal. High enough to
+// cover almost every real scope; callers can raise or lower via `--max`.
+export const DEFAULT_MAX = 5000;
+
+// Page size used by `gatherStream` for remote stores.
+const STREAM_PAGE_LIMIT = 100;
+
+// Stream every page of entries across `scopes` from `store`, invoking
+// `onPage({ scope, entries })` once per page as entries arrive. Designed for
+// linear consumers (lint, stats, dedupe) that process page-by-page without
+// accumulating all rows in memory.
+//
+// Options:
+//   max        — hard cap on total surveyed entries (default: DEFAULT_MAX). When
+//                reached the walk stops and `capped` is set in the result.
+//   since      — ISO date/timestamp lower bound, forwarded as `created_since`.
+//   until      — ISO date/timestamp upper bound, forwarded as `created_until`.
+//   keyPrefix  — key prefix filter, forwarded as `key_prefix`.
+//   onPage     — callback invoked with `{ scope, entries }` per page.
+//
+// Returns `{ surveyed, total, capped, byScope }` where:
+//   surveyed  — total entries delivered to `onPage`.
+//   total     — exact aggregate from `listScopes()` when available (remote),
+//               else equal to `surveyed`.
+//   capped    — true when `max` stopped the walk before all pages were read.
+//   byScope   — `[{ scope, count, error }]` per scope (error=null on success).
+//
+// A per-scope read failure is captured on `byScope`, never thrown — mirrors
+// `gather()`'s resilience contract. `LocalStore.list` returns everything in one
+// page (no `nextCursor`), so the loop naturally terminates after one iteration
+// offline and adds no overhead.
+export async function gatherStream(store, scopes, {
+  max = DEFAULT_MAX,
+  since,
+  until,
+  keyPrefix,
+  onPage,
+} = {}) {
+  const byScope = [];
+  let surveyed = 0;
+  let capped = false;
+
+  // Attempt to get exact aggregate counts for the remote store via listScopes().
+  // Only available on stores that implement listScopes(); degrades gracefully.
+  let scopeCountMap = null;
+  if (typeof store.listScopes === 'function') {
+    try {
+      const ls = await store.listScopes();
+      if (ls && ls.ok && Array.isArray(ls.scopes)) {
+        scopeCountMap = new Map(ls.scopes.map((s) => [s.scope, s.count]));
+      }
+    } catch { /* best-effort */ }
+  }
+
+  for (const scope of scopes) {
+    if (capped) {
+      byScope.push({ scope, count: 0, error: null });
+      continue;
+    }
+    let cursor = undefined;
+    let scopeCount = 0;
+    let scopeError = null;
+
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const remaining = max - surveyed;
+      if (remaining <= 0) {
+        capped = true;
+        break;
+      }
+      const pageLimit = Math.min(STREAM_PAGE_LIMIT, remaining);
+      let res;
+      try {
+        res = await store.list({
+          scope,
+          limit: pageLimit,
+          cursor,
+          ...(since ? { created_since: since } : {}),
+          ...(until ? { created_until: until } : {}),
+          ...(keyPrefix ? { key_prefix: keyPrefix } : {}),
+        });
+      } catch (e) {
+        res = { ok: false, networkError: (e && e.message) || 'error' };
+      }
+      if (!res || res.ok === false) {
+        scopeError = describeError(res);
+        break;
+      }
+      const entries = (res.entries || []).map(normalizeEntry);
+      if (entries.length > 0) {
+        if (onPage) onPage({ scope, entries });
+        scopeCount += entries.length;
+        surveyed += entries.length;
+      }
+      // hasMore absent (local store) or false → done with this scope.
+      if (!res.hasMore || !res.nextCursor) break;
+      cursor = res.nextCursor;
+      // Safety: stop if we hit the cap after this page.
+      if (surveyed >= max) {
+        capped = true;
+        break;
+      }
+    }
+    byScope.push({ scope, count: scopeCount, error: scopeError });
+  }
+
+  // Derive total: use the aggregate when available (remote), else surveyed.
+  let total = surveyed;
+  if (scopeCountMap) {
+    total = 0;
+    for (const scope of scopes) {
+      total += scopeCountMap.get(scope) ?? 0;
+    }
+  }
+
+  return { surveyed, total, capped, byScope };
+}
+
+// Token-blocking near-duplicate clustering — a performance-bounded alternative
+// to `clusterDuplicates`'s O(n²) all-pairs sweep. Uses an inverted index
+// (token → indices) to generate only the candidate pairs that share at least
+// one token, then applies the SAME Jaccard `>= threshold` + union-find logic as
+// `clusterDuplicates`. The resulting clusters are provably identical:
+//
+//   IF similarity(a, b) >= threshold > 0 THEN a and b share at least one token,
+//   so they WILL appear as a candidate pair in the inverted-index sweep.
+//
+// Keeping `clusterDuplicates` intact means equivalence is a testable property
+// (AC-7) rather than a rewrite claim. Pure.
+export function clusterDuplicatesBlocked(entries = [], threshold = 0.8) {
+  const items = entries.map((e, i) => ({
+    i,
+    scope: e.scope ?? null,
+    key: e.key ?? null,
+    tokens: tokenize(e.value),
+  }));
+
+  // Build inverted index: token → [item indices]
+  /** @type {Map<string, number[]>} */
+  const invertedIndex = new Map();
+  for (const item of items) {
+    for (const token of item.tokens) {
+      if (!invertedIndex.has(token)) invertedIndex.set(token, []);
+      invertedIndex.get(token).push(item.i);
+    }
+  }
+
+  // Generate candidate pairs: any two items sharing at least one token.
+  // Use a Set of encoded pair keys to avoid duplicates.
+  const candidatePairs = new Set();
+  for (const indices of invertedIndex.values()) {
+    for (let x = 0; x < indices.length; x += 1) {
+      for (let y = x + 1; y < indices.length; y += 1) {
+        const a = Math.min(indices[x], indices[y]);
+        const b = Math.max(indices[x], indices[y]);
+        candidatePairs.add(`${a}:${b}`);
+      }
+    }
+  }
+
+  // Apply the SAME union-find as clusterDuplicates over candidate pairs only.
+  const parent = items.map((_, i) => i);
+  const find = (x) => {
+    while (parent[x] !== x) {
+      parent[x] = parent[parent[x]];
+      x = parent[x];
+    }
+    return x;
+  };
+  const pairs = [];
+  for (const pairKey of candidatePairs) {
+    const [a, b] = pairKey.split(':').map(Number);
+    const sim = similarity(items[a].tokens, items[b].tokens);
+    if (sim >= threshold) {
+      pairs.push({ a, b, sim });
+      parent[find(a)] = find(b);
+    }
+  }
+
+  // Assemble clusters — identical logic to clusterDuplicates.
+  const byRoot = new Map();
+  for (const it of items) {
+    const r = find(it.i);
+    if (!byRoot.has(r)) byRoot.set(r, []);
+    byRoot.get(r).push(it);
+  }
+  const clusters = [];
+  for (const members of byRoot.values()) {
+    if (members.length < 2) continue;
+    const idx = new Set(members.map((m) => m.i));
+    const sims = pairs.filter((p) => idx.has(p.a) && idx.has(p.b)).map((p) => p.sim);
+    clusters.push({
+      members: members.map((m) => ({ scope: m.scope, key: m.key })),
+      size: members.length,
+      minSimilarity: sims.length ? Math.min(...sims) : threshold,
+      maxSimilarity: sims.length ? Math.max(...sims) : threshold,
+    });
+  }
+  clusters.sort((x, y) => y.size - x.size);
+  return clusters;
+}
+
 // Render one section (Offline or Remote). `section` is either
 //   { available:false, reason }                         → a graceful note, or
 //   { available:true, groups, total }                   → grouped lessons.

package/src/lint.mjs

@@ -15,7 +15,7 @@ import { resolveProjectRoot } from './config.mjs';
 import { deriveScope } from './scope.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { scopeList, gather, lintGroups } from './lessons-view.mjs';
+import { scopeList, gather, gatherStream, lintGroups, DEFAULT_MAX } from './lessons-view.mjs';
 import { log, heading, status, c } from './util.mjs';
 
 export async function lint(args) {
@@ -36,9 +36,47 @@ export async function lint(args) {
   // Deny-wins section suppression, identical to the other read commands.
   const { localDenied, remoteDenied } = resolveDenies(root, { env });
 
-  const offlineResult = localDenied ? { groups: [], total: 0 } : lintGroups(await gather(local, scopes));
+  // `lint` defaults to full-scope survey (--all). Use gatherStream for remote
+  // to drain all pages; gather (single-page) still serves local store which is
+  // already exhaustive. --max, --since, --until are forwarded when provided.
+  const surveyMax = args.max !== undefined ? Number(args.max) : DEFAULT_MAX;
+  const surveySince = args.since || undefined;
+  const surveyUntil = args.until || undefined;
+
+  let offlineResult;
+  if (localDenied) {
+    offlineResult = { groups: [], total: 0 };
+  } else {
+    offlineResult = lintGroups(await gather(local, scopes));
+  }
+
   const remoteAvailable = !remoteDenied && remote.usable();
-  const remoteResult = remoteAvailable ? lintGroups(await gather(remote, scopes)) : { groups: [], total: 0 };
+  let remoteResult;
+  if (!remoteAvailable) {
+    remoteResult = { groups: [], total: 0 };
+  } else {
+    // Stream all pages, accumulating entries per scope for linting.
+    const accumulated = new Map();
+    for (const scope of scopes) accumulated.set(scope, []);
+    await gatherStream(remote, scopes, {
+      max: surveyMax,
+      since: surveySince,
+      until: surveyUntil,
+      onPage: ({ scope, entries }) => {
+        const arr = accumulated.get(scope);
+        if (arr) for (const e of entries) arr.push(e);
+      },
+    });
+    // Build a gather()-shaped result so lintGroups can consume it unchanged.
+    const groups = [];
+    let total = 0;
+    for (const scope of scopes) {
+      const entries = accumulated.get(scope) || [];
+      total += entries.length;
+      groups.push({ scope, entries, error: null });
+    }
+    remoteResult = lintGroups({ groups, total });
+  }
 
   const offlineSection = localDenied
     ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }

package/src/list.mjs

@@ -13,7 +13,7 @@ import { resolveProjectRoot } from './config.mjs';
 import { deriveScope } from './scope.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { scopeList, gather, renderSection } from './lessons-view.mjs';
+import { scopeList, gather, gatherStream, renderSection, DEFAULT_MAX } from './lessons-view.mjs';
 import { resolveAppBase, mostSpecificScope } from './deeplink-pure.mjs';
 import { emitLink } from './link.mjs';
 import { log, heading, c } from './util.mjs';
@@ -69,9 +69,54 @@ export async function list(args) {
   // agent-facing control model enforces, honored here in the human read view.
   const { localDenied, remoteDenied } = resolveDenies(root, { env });
 
+  // --all: drain all pages from the remote store (for large scopes). Default
+  // is single-page per scope (what `list` has always shown). The local store is
+  // always exhaustive regardless of --all.
+  const surveyAll = Boolean(args.all);
+  const surveyMax = args.max !== undefined ? Number(args.max) : DEFAULT_MAX;
+  const surveySince = args.since || undefined;
+  const surveyUntil = args.until || undefined;
+
+  // Taxonomy `keep` predicate mirroring `gather()`'s: `gatherStream` neither
+  // forwards `kind`/`host` to the store nor post-filters, so a `--all` drain
+  // must apply the same narrowing here or `list --all --kind X` would ignore X.
+  const wanted = (v) =>
+    v == null ? null : new Set(String(v).split(',').map((s) => s.trim()).filter(Boolean));
+  const kindSet = wanted(filters.kind);
+  const hostSet = wanted(filters.host);
+  const keep = (e) =>
+    (!kindSet || (e.kind != null && kindSet.has(e.kind))) &&
+    (!hostSet || (e.host != null && hostSet.has(e.host)));
+
   const offline = localDenied ? { groups: [], total: 0 } : await gather(local, scopes, filters);
   const remoteAvailable = !remoteDenied && remote.usable();
-  const remoteResult = remoteAvailable ? await gather(remote, scopes, filters) : { groups: [], total: 0 };
+  let remoteResult;
+  if (!remoteAvailable) {
+    remoteResult = { groups: [], total: 0 };
+  } else if (surveyAll) {
+    // Full drain: accumulate all pages into a groups-shaped result.
+    const accumulated = new Map();
+    for (const scope of scopes) accumulated.set(scope, []);
+    await gatherStream(remote, scopes, {
+      max: surveyMax,
+      since: surveySince,
+      until: surveyUntil,
+      onPage: ({ scope, entries }) => {
+        const arr = accumulated.get(scope);
+        if (arr) for (const e of entries) if (keep(e)) arr.push(e);
+      },
+    });
+    const groups = [];
+    let total = 0;
+    for (const scope of scopes) {
+      const entries = accumulated.get(scope) || [];
+      total += entries.length;
+      groups.push({ scope, entries, error: null });
+    }
+    remoteResult = { groups, total };
+  } else {
+    remoteResult = await gather(remote, scopes, filters);
+  }
 
   const offlineSection = localDenied
     ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }

package/src/mcp-server.mjs

@@ -100,12 +100,31 @@ export const MEMORY_TOOL_DEFS = [
   {
     name: 'memory.list',
     description: 'List memories for a scope',
-    inputSchema: { type: 'object', required: ['scope'] },
+    inputSchema: {
+      type: 'object',
+      required: ['scope'],
+      properties: {
+        scope: { type: 'string' },
+        tags: { type: 'array', items: { type: 'string' } },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 50 },
+        cursor: { type: 'string', description: 'Opaque cursor from a previous response\'s nextCursor. Omit to start from the first page.' },
+      },
+    },
   },
   {
     name: 'memory.search',
     description: 'Keyword search across memories',
-    inputSchema: { type: 'object', required: ['q'] },
+    inputSchema: {
+      type: 'object',
+      required: ['q'],
+      properties: {
+        q: { type: 'string' },
+        scopes: { type: 'array', items: { type: 'string' } },
+        tags: { type: 'array', items: { type: 'string' } },
+        limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 },
+        cursor: { type: 'string', description: 'Opaque cursor from a previous response\'s nextCursor. Omit to start from the first page.' },
+      },
+    },
   },
   {
     name: 'memory.delete',

package/src/stats.mjs

@@ -20,7 +20,7 @@ import { resolveProjectRoot } from './config.mjs';
 import { deriveScope } from './scope.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { scopeList, gather, tallyGroups } from './lessons-view.mjs';
+import { scopeList, gather, tallyGroups, summarizeScopeInventory, filterScopeInventory } from './lessons-view.mjs';
 import { log, heading, status, c } from './util.mjs';
 
 export async function stats(args) {
@@ -44,9 +44,32 @@ export async function stats(args) {
 
   const offlineTally = localDenied ? { perScope: [], total: 0 } : tallyGroups(await gather(local, scopes));
   const remoteAvailable = !remoteDenied && remote.usable();
-  const remoteTally = remoteAvailable
-    ? tallyGroups(await gather(remote, scopes))
-    : { perScope: [], total: 0 };
+
+  // Remote counts come from the GET /memories/scopes Postgres aggregate
+  // (RemoteStore.listScopes), which is exact at any scale — never row-draining.
+  // This is the fix for `stats`=50 vs `scopes`=487: the old code used
+  // gather() which returned only the first page from the remote store.
+  let remoteTally;
+  if (!remoteAvailable) {
+    remoteTally = { perScope: [], total: 0 };
+  } else {
+    const scopesRes = await remote.listScopes();
+    if (scopesRes && scopesRes.ok && Array.isArray(scopesRes.scopes)) {
+      // Filter to only the applicable scopes; total the filtered set.
+      const filtered = filterScopeInventory(scopesRes.scopes, null).filter(
+        (s) => scopes.includes(s.scope),
+      );
+      const perScope = scopes.map((scope) => {
+        const match = filtered.find((s) => s.scope === scope);
+        return { scope, count: match ? match.count : 0, error: null };
+      });
+      const total = perScope.reduce((n, s) => n + s.count, 0);
+      remoteTally = { perScope, total };
+    } else {
+      // Fallback when listScopes() is unavailable/errors — single-page gather.
+      remoteTally = tallyGroups(await gather(remote, scopes));
+    }
+  }
 
   const offlineSection = localDenied
     ? { available: false, reason: `disabled by deny constraint (${localDenied.source})` }

package/src/store/remote.mjs

@@ -58,19 +58,29 @@ class RemoteStore {
 
   // ── Memory operations → REST ──────────────────────────────────────────────
 
-  async list({ scope, tags, kind, host, limit } = {}) {
+  async list({ scope, tags, kind, host, limit, cursor, created_since, created_until, key_prefix } = {}) {
     const p = new URLSearchParams();
     if (scope) p.set('scope', scope);
     if (tags?.length) p.set('tags', Array.isArray(tags) ? tags.join(',') : tags);
     if (kind) p.set('kind', Array.isArray(kind) ? kind.join(',') : kind);
     if (host) p.set('host', Array.isArray(host) ? host.join(',') : host);
     if (limit) p.set('limit', String(limit));
+    if (cursor) p.set('cursor', cursor);
+    if (created_since) p.set('created_since', created_since);
+    if (created_until) p.set('created_until', created_until);
+    if (key_prefix) p.set('key_prefix', key_prefix);
     const res = await this._rest(`/memories?${p}`);
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
-    return { ok: true, entries: res.data?.entries ?? [] };
+    const data = res.data ?? {};
+    return {
+      ok: true,
+      entries: data.entries ?? [],
+      hasMore: data.hasMore ?? false,
+      nextCursor: data.nextCursor ?? null,
+    };
   }
 
-  async search({ q, scopes, tags } = {}) {
+  async search({ q, scopes, tags, limit, cursor } = {}) {
     // A list of terms collapses into ONE `websearch` query joined by `OR`, so a
     // multi-term failure lookup is a single round-trip (the server FTS ORs them
     // and stems each). `failureQuery` distils terms to `[a-z0-9]+` tokens, so no
@@ -80,9 +90,17 @@ class RemoteStore {
     if (query) body.q = query;
     if (scopes?.length) body.scopes = scopes;
     if (tags?.length) body.tags = tags;
+    if (limit) body.limit = limit;
+    if (cursor) body.cursor = cursor;
     const res = await this._rest('/memories/search', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
-    return { ok: true, entries: res.data?.entries ?? [] };
+    const data = res.data ?? {};
+    return {
+      ok: true,
+      entries: data.entries ?? [],
+      hasMore: data.hasMore ?? false,
+      nextCursor: data.nextCursor ?? null,
+    };
   }
 
   async read({ scope, key } = {}) {

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.')}`);