@lorekit/cli 1.55.0 → 1.55.2

package/README.md

@@ -555,7 +555,7 @@ the `.lorekit/` files directly, `remote` passes calls through to the hosted
 endpoint, and `off` advertises no tools.
 
 Tools advertised are **derived from the canonical tool catalog**
-(`packages/schemas/src/tool-catalog.ts`) rather than declared here, so this
+(`packages/schemas/src/shared/tool-catalog.ts`) rather than declared here, so this
 server and the hosted one describe each operation identically. In `local` and
 `remote` mode that is `memory.write`, `memory.read`, `memory.list`,
 `memory.search`, `memory.delete`, `memory.archive`, `memory.restore` and

package/bin/lorekit.mjs

@@ -2,7 +2,7 @@
 // LoreKit CLI — install the shared-memory skill and run health checks.
 import process from 'node:process';
 import { readFileSync } from 'node:fs';
-import { parseArgs, log, err, c } from '../src/util.mjs';
+import { parseArgs, log, err, c } from '../src/shared/util.mjs';
 // Commands, their handlers, aliases and dispatch properties all come from one
 // registry — see ../src/commands.mjs for why membership lives there and the
 // help prose stays here.
@@ -10,8 +10,8 @@ import { COMMANDS_BY_NAME, STRICT_FLAG_COMMANDS, COMMAND_ALIASES } from '../src/
 // Catalog-derived, so the default this help PROMISES is the one the server
 // applies — see src/surfaces.generated.mjs.
 import { PURGE_RETENTION_DAYS_DEFAULT } from '../src/surfaces.generated.mjs';
-import { traceCommand, meterCommand } from '../src/telemetry.mjs';
-import { loadDotEnv } from '../src/dotenv.mjs';
+import { traceCommand, meterCommand } from '../src/telemetry/telemetry.mjs';
+import { loadDotEnv } from '../src/shared/dotenv.mjs';
 
 // Read the version from package.json so it always matches the published
 // package — release-please bumps package.json, and this tracks it for free.

package/package.json

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

package/src/{bootstrap.mjs → commands/bootstrap.mjs}

@@ -12,13 +12,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
-import { log, err, heading, status, c } from './util.mjs';
+import { log, err, heading, status, c } from '../shared/util.mjs';
 
 // The bootstrap.sql file is at <repo-root>/supabase/byod/bootstrap.sql.
-// This file lives at packages/cli/src/bootstrap.mjs, so the relative path
-// from here to the repo root is ../../../  (src → cli → packages → root).
+// This file lives at packages/cli/src/commands/bootstrap.mjs, so the relative
+// path from here to the repo root is ../../../../  (commands → src → cli →
+// packages → root).
 const BOOTSTRAP_SQL_PATH = fileURLToPath(
-  new URL('../../../supabase/byod/bootstrap.sql', import.meta.url),
+  new URL('../../../../supabase/byod/bootstrap.sql', import.meta.url),
 );
 
 export async function bootstrap(_args) {

package/src/{dedupe.mjs → commands/dedupe.mjs}

@@ -11,12 +11,12 @@
 // Same Offline / Remote split and graceful degradation as `list`. Read-only.
 // Human-facing, so the bin wraps it in `traceCommand`.
 import process from 'node:process';
-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, gatherStream, clusterDuplicates, clusterDuplicatesBlocked, clusterByKeyPattern, compileKeyPattern, DEFAULT_MAX } from './lessons-view.mjs';
-import { log, heading, status, err, c } from './util.mjs';
+import { resolveProjectRoot, readLorekitJson } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { scopeList, gather, gatherStream, clusterDuplicates, clusterDuplicatesBlocked, clusterByKeyPattern, compileKeyPattern, DEFAULT_MAX } from '../shared/lessons-view.mjs';
+import { log, heading, status, err, c } from '../shared/util.mjs';
 
 const DEFAULT_THRESHOLD = 0.8;
 // Maximum entries to accumulate before the survey becomes memory-prohibitive.

package/src/{diff.mjs → commands/diff.mjs}

@@ -11,12 +11,12 @@
 // and exits 0 (never a crash). Read-only. Human-facing, so the bin wraps it in
 // `traceCommand`.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { deriveScope } from './scope.mjs';
-import { resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { scopeList, gather, diffGroups, preview, shortDate } from './lessons-view.mjs';
-import { log, heading, status, c } from './util.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { scopeList, gather, diffGroups, preview, shortDate } from '../shared/lessons-view.mjs';
+import { log, heading, status, c } from '../shared/util.mjs';
 
 export async function diff(args) {
   const root = resolveProjectRoot(args.dir);

package/src/{doctor.mjs → commands/doctor.mjs}

@@ -16,18 +16,18 @@ import {
   readMcpConfig,
   tokenKind,
   readLorekitJson,
-} from './config.mjs';
-import { splitEndpoint } from './mcp.mjs';
+} from '../shared/config.mjs';
+import { splitEndpoint } from '../shared/mcp.mjs';
 import {
   resolveTelemetryConfig,
   resolveTelemetryTokenSource,
   probeTelemetryExport,
-} from './telemetry.mjs';
-import { describeIdentity } from './telemetry-identity.mjs';
-import { deriveScope } from './scope.mjs';
-import { loadControl, HOOK_INSTRUCTION_EVENTS } from './control.mjs';
-import { createStore } from './store/index.mjs';
-import { log, heading, status, c } from './util.mjs';
+} from '../telemetry/telemetry.mjs';
+import { describeIdentity } from '../telemetry/telemetry-identity.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { loadControl, HOOK_INSTRUCTION_EVENTS } from '../shared/control.mjs';
+import { createStore } from '../store/index.mjs';
+import { log, heading, status, c } from '../shared/util.mjs';
 
 const AUTH_CODES = new Set([401, 403, -32001]);
 
@@ -590,7 +590,7 @@ async function checkTelemetryExport(args, root, record) {
 /** The running CLI version, for stamping the telemetry probe span. */
 function cliVersion() {
   try {
-    return JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    return JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
   } catch {
     return '0.0.0';
   }

package/src/{hook.mjs → commands/hook.mjs}

@@ -3,10 +3,10 @@
 // logic, and prints the framework-shaped injection on stdout. Always exits 0 —
 // a memory hook must never block or break the host agent.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { deriveScope } from './scope.mjs';
-import { loadControl } from './control.mjs';
-import { createStore } from './store/index.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { loadControl } from '../shared/control.mjs';
+import { createStore } from '../store/index.mjs';
 import {
   fetchLessons,
   formatLessons,
@@ -20,19 +20,19 @@ import {
   relevantLessonsFromStore,
   formatRelevantLessons,
   writeConfirmation,
-} from './core/lessons.mjs';
-import { isFailure } from './core/failure.mjs';
-import { readSessionFriction, shouldRetrospect, FRICTION_FAILURE } from './core/friction.mjs';
+} from '../core/lessons.mjs';
+import { isFailure } from '../core/failure.mjs';
+import { readSessionFriction, shouldRetrospect, FRICTION_FAILURE } from '../core/friction.mjs';
 import {
   firstTimeThisSession,
   sessionMarkerExists,
   shownLessons,
   recordShownLessons,
-} from './core/state.mjs';
-import { recordFixture } from './core/record.mjs';
-import { claude } from './adapters/claude.mjs';
-import { cursor } from './adapters/cursor.mjs';
-import { codex } from './adapters/codex.mjs';
+} from '../core/state.mjs';
+import { recordFixture } from '../core/record.mjs';
+import { claude } from '../adapters/claude.mjs';
+import { cursor } from '../adapters/cursor.mjs';
+import { codex } from '../adapters/codex.mjs';
 
 const ADAPTERS = { claude, cursor, codex };
 

package/src/{install.mjs → commands/install.mjs}

@@ -26,10 +26,10 @@ import {
   readJsonIfExists,
   readLorekitServer,
   isWebMcpServerEntry,
-} from './config.mjs';
-import { buildRemoteUrl, splitEndpoint } from './mcp.mjs';
-import { deriveScope } from './scope.mjs';
-import { log, heading, status, select, err, c } from './util.mjs';
+} from '../shared/config.mjs';
+import { buildRemoteUrl, splitEndpoint } from '../shared/mcp.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { log, heading, status, select, err, c } from '../shared/util.mjs';
 
 // The MCP server URL is fixed — there is only one hosted LoreKit endpoint.
 const LOREKIT_MCP_ENDPOINT = 'https://pqokxlhvnosogizsjztg.supabase.co/functions/v1/mcp';

package/src/{link.mjs → commands/link.mjs}

@@ -15,8 +15,8 @@
 // Every param is JSON-encoded per the `useUrlState` contract (see
 // `deeplink-pure.mjs`) — a raw `?scope=global` would silently mean "all scopes".
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { deriveScope } from './scope.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
 import {
   resolveAppBase,
   buildLoreUrl,
@@ -26,8 +26,8 @@ import {
   parseTagsArg,
   resolveScopeKeyArgs,
   surfaceFor,
-} from './deeplink-pure.mjs';
-import { log, err } from './util.mjs';
+} from '../shared/deeplink-pure.mjs';
+import { log, err } from '../shared/util.mjs';
 
 export async function link(args) {
   const root = resolveProjectRoot(args.dir);

package/src/{lint.mjs → commands/lint.mjs}

@@ -11,12 +11,12 @@
 // `list`; a `LOREKIT_DENY` ceiling or an unconfigured remote is a note, not an
 // error. Read-only. Human-facing, so the bin wraps it in `traceCommand`.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { deriveScope } from './scope.mjs';
-import { resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { scopeList, gather, gatherStream, lintGroups, DEFAULT_MAX } from './lessons-view.mjs';
-import { log, heading, status, c } from './util.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { scopeList, gather, gatherStream, lintGroups, DEFAULT_MAX } from '../shared/lessons-view.mjs';
+import { log, heading, status, c } from '../shared/util.mjs';
 
 export async function lint(args) {
   const root = resolveProjectRoot(args.dir);

package/src/{list.mjs → commands/list.mjs}

@@ -9,14 +9,14 @@
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { deriveScope } from './scope.mjs';
-import { resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { scopeList, gather, gatherStream, renderSection, DEFAULT_MAX } from './lessons-view.mjs';
-import { resolveAppBase, mostSpecificScope } from './deeplink-pure.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { scopeList, gather, gatherStream, renderSection, DEFAULT_MAX } from '../shared/lessons-view.mjs';
+import { resolveAppBase, mostSpecificScope } from '../shared/deeplink-pure.mjs';
 import { emitLink } from './link.mjs';
-import { log, heading, c } from './util.mjs';
+import { log, heading, c } from '../shared/util.mjs';
 
 // Abbreviate the user's home directory to `~` for readable paths.
 function prettyPath(p) {

package/src/{mcp-server.mjs → commands/mcp-server.mjs}

@@ -24,17 +24,17 @@
 //
 // The transport is hand-rolled (no MCP SDK) to keep the CLI dependency-free.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { loadControl } from './control.mjs';
-import { createStore } from './store/index.mjs';
-import { createRemoteStore } from './store/remote.mjs';
-import { deriveOrigin, mergeOrigin } from './origin.mjs';
-import { readScopeInventory } from './store/scope-inventory.mjs';
-import { inferKindHostFromTags } from './lessons-view.mjs';
-// Generated from packages/schemas/src/tool-catalog.ts — the same declaration the
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { loadControl } from '../shared/control.mjs';
+import { createStore } from '../store/index.mjs';
+import { createRemoteStore } from '../store/remote.mjs';
+import { deriveOrigin, mergeOrigin } from '../shared/origin.mjs';
+import { readScopeInventory } from '../store/scope-inventory.mjs';
+import { inferKindHostFromTags } from '../shared/lessons-view.mjs';
+// Generated from packages/schemas/src/shared/tool-catalog.ts — the same declaration the
 // hosted MCP server renders `tools/list` from. Committed and zero-dep because
 // this is a published package that cannot import the workspace schemas.
-import { MCP_TOOL_DEFS, MCP_TOOL_NAMES } from './surfaces.generated.mjs';
+import { MCP_TOOL_DEFS, MCP_TOOL_NAMES } from '../surfaces.generated.mjs';
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_INFO = { name: 'lorekit-local', version: '1.0.0' };
@@ -365,7 +365,7 @@ export function advertise(dispatch) {
       if (!def) {
         throw new Error(
           `mcp-server dispatches "${name}", which the tool catalog does not declare. `
-          + 'Add it to packages/schemas/src/tool-catalog.ts (and regenerate: node scripts/gen-surfaces.mjs).',
+          + 'Add it to packages/schemas/src/shared/tool-catalog.ts (and regenerate: node scripts/gen-surfaces.mjs).',
         );
       }
       return def;

package/src/{migrate.mjs → commands/migrate.mjs}

@@ -22,16 +22,16 @@
 // org-owned writes; a v1 migration always lands as the caller's personal lore.
 import fs from 'node:fs';
 import path from 'node:path';
-import { resolveProjectRoot, tokenKind } from './config.mjs';
-import { localStoreDirs, loadControl } from './control.mjs';
-import { createLocalStore, createTwoTierStore, createRemoteStore } from './store/index.mjs';
-import { parseEntry } from './store/format.mjs';
-import { isLive, TTL_MAX_DAYS } from './store/ttl.mjs';
-import { remoteWriteLosses } from './store/remote.mjs';
+import { resolveProjectRoot, tokenKind } from '../shared/config.mjs';
+import { localStoreDirs, loadControl } from '../shared/control.mjs';
+import { createLocalStore, createTwoTierStore, createRemoteStore } from '../store/index.mjs';
+import { parseEntry } from '../store/format.mjs';
+import { isLive, TTL_MAX_DAYS } from '../store/ttl.mjs';
+import { remoteWriteLosses } from '../store/remote.mjs';
 import {
   createPacer, withRetry, isMemoryCap, sleep, DEFAULT_CONSECUTIVE_FAILURE_LIMIT,
-} from './store/rate-limit.mjs';
-import { log, heading, status, err, c } from './util.mjs';
+} from '../store/rate-limit.mjs';
+import { log, heading, status, err, c } from '../shared/util.mjs';
 
 // Recursively collect every parseable LoreKit entry under a base dir. The
 // canonical scope comes from each file's frontmatter, so the source layout does

package/src/{purge.mjs → commands/purge.mjs}

@@ -24,11 +24,11 @@
 //    business sweeping the whole account. The CLI makes exactly one request and
 //    reports the server's answer; it never retries, never splits the sweep and
 //    never re-scopes to work around it.
-import { resolveProjectRoot } from './config.mjs';
-import { loadControl, resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { log, err, c, select } from './util.mjs';
-import { PURGE_RETENTION_DAYS_DEFAULT } from './surfaces.generated.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { loadControl, resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { log, err, c, select } from '../shared/util.mjs';
+import { PURGE_RETENTION_DAYS_DEFAULT } from '../surfaces.generated.mjs';
 
 /** The window `retention_days` accepts, mirroring `PurgeMemoriesBodySchema`. */
 export const RETENTION_DAYS_MIN = 1;

package/src/{remove.mjs → commands/remove.mjs}

@@ -12,11 +12,11 @@
 // memory.delete / memory.restore operations, which are scope-authorized for an
 // API token by its allowlist (migrations 00071 / 00072): a key scoped to a
 // scope may manage every writer's row in it, an unscoped key only its own.
-import { resolveProjectRoot } from './config.mjs';
-import { loadControl, resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { log, err, c } from './util.mjs';
-import { resolveScopeKeyArgs, scopeIssue } from './lessons-view.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { loadControl, resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { log, err, c } from '../shared/util.mjs';
+import { resolveScopeKeyArgs, scopeIssue } from '../shared/lessons-view.mjs';
 
 // The three surfaces return different success shapes: the remote store answers
 // `{ ok, error, networkError }`, the local store `{ deleted, archived, entry }`.

package/src/{scopes.mjs → commands/scopes.mjs}

@@ -25,11 +25,11 @@
 // scopes whose string contains that substring; `--json` emits `{ offline,
 // remote }`.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { summarizeScopeInventory, filterScopeInventory, describeError } from './lessons-view.mjs';
-import { log, heading, status, c } from './util.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { summarizeScopeInventory, filterScopeInventory, describeError } from '../shared/lessons-view.mjs';
+import { log, heading, status, c } from '../shared/util.mjs';
 
 export async function scopes(args) {
   const root = resolveProjectRoot(args.dir);

package/src/{search.mjs → commands/search.mjs}

@@ -14,14 +14,14 @@
 // never an error; a per-scope read failure is a warning, not a crash. Read-only,
 // archived hidden. Human-facing, so the bin wraps it in `traceCommand`.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { deriveScope } from './scope.mjs';
-import { resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { scopeList, gather, filterGroups, renderSection } from './lessons-view.mjs';
-import { resolveAppBase, mostSpecificScope } from './deeplink-pure.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { scopeList, gather, filterGroups, renderSection } from '../shared/lessons-view.mjs';
+import { resolveAppBase, mostSpecificScope } from '../shared/deeplink-pure.mjs';
 import { emitLink } from './link.mjs';
-import { log, err, heading, c } from './util.mjs';
+import { log, err, heading, c } from '../shared/util.mjs';
 
 export async function search(args) {
   const root = resolveProjectRoot(args.dir);

package/src/{show.mjs → commands/show.mjs}

@@ -18,9 +18,9 @@
 // an unconfigured remote is a short note, never an error. Read-only. Human-facing,
 // so the bin wraps it in `traceCommand`.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
 import {
   normalizeEntry,
   shortDate,
@@ -28,10 +28,10 @@ import {
   recordsDiverge,
   resolveScopeKeyArgs,
   scopeIssue,
-} from './lessons-view.mjs';
-import { resolveAppBase } from './deeplink-pure.mjs';
+} from '../shared/lessons-view.mjs';
+import { resolveAppBase } from '../shared/deeplink-pure.mjs';
 import { emitLink } from './link.mjs';
-import { log, err, heading, status, c } from './util.mjs';
+import { log, err, heading, status, c } from '../shared/util.mjs';
 
 // Read one scope::key from a store, normalizing the result into a small,
 // uniform shape: { available:true, found, record } on success, or

package/src/{stats.mjs → commands/stats.mjs}

@@ -16,12 +16,12 @@
 // `memory.list` returns for each scope (server-side default page size), the
 // same window `list` already shows.
 import process from 'node:process';
-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, summarizeScopeInventory, filterScopeInventory } from './lessons-view.mjs';
-import { log, heading, status, c } from './util.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { scopeList, gather, tallyGroups, summarizeScopeInventory, filterScopeInventory } from '../shared/lessons-view.mjs';
+import { log, heading, status, c } from '../shared/util.mjs';
 
 export async function stats(args) {
   const root = resolveProjectRoot(args.dir);

package/src/{tree.mjs → commands/tree.mjs}

@@ -28,15 +28,15 @@
 // in the same Offline / Remote split as `list`. Graceful, read-only, wrapped in
 // `traceCommand` by the bin.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { deriveScope } from './scope.mjs';
-import { resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { resolvePrecedence } from './lessons-pure.mjs';
-import { gather, preview, shortDate } from './lessons-view.mjs';
-import { resolveAppBase, mostSpecificScope } from './deeplink-pure.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { deriveScope } from '../shared/scope.mjs';
+import { resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { resolvePrecedence } from '../shared/lessons-pure.mjs';
+import { gather, preview, shortDate } from '../shared/lessons-view.mjs';
+import { resolveAppBase, mostSpecificScope } from '../shared/deeplink-pure.mjs';
 import { emitLink } from './link.mjs';
-import { log, heading, status, c } from './util.mjs';
+import { log, heading, status, c } from '../shared/util.mjs';
 
 export async function tree(args) {
   const root = resolveProjectRoot(args.dir);

package/src/{uninstall.mjs → commands/uninstall.mjs}

@@ -12,8 +12,8 @@ import {
   removeWebMcpServer,
   removeClaudeHooks,
   homeDir,
-} from './config.mjs';
-import { log, heading, status, c } from './util.mjs';
+} from '../shared/config.mjs';
+import { log, heading, status, c } from '../shared/util.mjs';
 
 function ask(question) {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

package/src/{write.mjs → commands/write.mjs}

@@ -60,13 +60,13 @@
 // resolved scope, key, store written, and a boolean `inserted` (true = created,
 // false = updated) when the remote reports it.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
-import { loadControl, resolveDenies } from './control.mjs';
-import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { log, err, heading, status, c } from './util.mjs';
-import { resolveScopeKeyArgs, scopeIssue } from './lessons-view.mjs';
-import { deriveOrigin, mergeOrigin } from './origin.mjs';
-import { parseTtlDays, resolveDefaultTtlDays } from './store/ttl.mjs';
+import { resolveProjectRoot } from '../shared/config.mjs';
+import { loadControl, resolveDenies } from '../shared/control.mjs';
+import { resolveStores, remoteUnavailableReason } from '../shared/stores.mjs';
+import { log, err, heading, status, c } from '../shared/util.mjs';
+import { resolveScopeKeyArgs, scopeIssue } from '../shared/lessons-view.mjs';
+import { deriveOrigin, mergeOrigin } from '../shared/origin.mjs';
+import { parseTtlDays, resolveDefaultTtlDays } from '../store/ttl.mjs';
 
 // Read all of stdin to a string. Resolves to '' when stdin IS a TTY (no pipe).
 function readStdin() {
@@ -108,7 +108,7 @@ export async function write(args) {
   // string, so this is also the only thing standing between a local write and
   // a scope the hosted API would reject with a 400. It is a PARTIAL gate, not
   // an equivalent one: `scopeIssue` checks the segment SHAPE (`[^/]+/[^/]+`)
-  // where `packages/mcp-core/src/scope.ts` additionally restricts the CHARSET
+  // where `packages/mcp-core/src/scope/scope.ts` additionally restricts the CHARSET
   // (`[\w.-]+/[\w.-]+`), so `repo::a b/c,d` and `branch::o/r::a",x` pass here
   // and still 400 remotely. Tightening the CLI to match would also change what
   // `lint`'s malformed-scope rule flags in existing offline stores, so it is a

package/src/commands.mjs

@@ -33,32 +33,32 @@
 // leaving them entirely silent meant the usage that dominates was the usage
 // nobody could see — a span each is still the wrong trade, a counter is not.
 
-import { install } from './install.mjs';
-import { uninstall } from './uninstall.mjs';
-import { doctor } from './doctor.mjs';
-import { list } from './list.mjs';
-import { search } from './search.mjs';
-import { show } from './show.mjs';
-import { write } from './write.mjs';
-import { archive, del, restore } from './remove.mjs';
-import { stats } from './stats.mjs';
-import { scopes } from './scopes.mjs';
-import { diff } from './diff.mjs';
-import { tree } from './tree.mjs';
-import { lint } from './lint.mjs';
-import { dedupe } from './dedupe.mjs';
-import { link } from './link.mjs';
-import { hook } from './hook.mjs';
-import { migrate } from './migrate.mjs';
-import { bootstrap } from './bootstrap.mjs';
-import { mcpServer } from './mcp-server.mjs';
-import { purge, purgeExpired } from './purge.mjs';
+import { install } from './commands/install.mjs';
+import { uninstall } from './commands/uninstall.mjs';
+import { doctor } from './commands/doctor.mjs';
+import { list } from './commands/list.mjs';
+import { search } from './commands/search.mjs';
+import { show } from './commands/show.mjs';
+import { write } from './commands/write.mjs';
+import { archive, del, restore } from './commands/remove.mjs';
+import { stats } from './commands/stats.mjs';
+import { scopes } from './commands/scopes.mjs';
+import { diff } from './commands/diff.mjs';
+import { tree } from './commands/tree.mjs';
+import { lint } from './commands/lint.mjs';
+import { dedupe } from './commands/dedupe.mjs';
+import { link } from './commands/link.mjs';
+import { hook } from './commands/hook.mjs';
+import { migrate } from './commands/migrate.mjs';
+import { bootstrap } from './commands/bootstrap.mjs';
+import { mcpServer } from './commands/mcp-server.mjs';
+import { purge, purgeExpired } from './commands/purge.mjs';
 
 /**
  * Every command, in the order the top-level help lists them.
  *
  * `tool` binds a command to a catalog operation (`surfaces.cli` in
- * `packages/schemas/src/tool-catalog.ts`) — the two are cross-checked, so a
+ * `packages/schemas/src/shared/tool-catalog.ts`) — the two are cross-checked, so a
  * catalog op claiming a CLI command that does not exist here fails a test.
  * `native` marks a command with no catalog operation and says why, which is
  * most of them: installing, diagnosing and grooming are CLI concerns that no

package/src/core/lessons.mjs

@@ -2,7 +2,7 @@
 // Framework-agnostic — adapters shape these strings into each tool's contract.
 // Storage is reached through the resolved store (local | remote), never a
 // backend directly, so the same read path serves every mode.
-import { deriveScope } from '../scope.mjs';
+import { deriveScope } from '../shared/scope.mjs';
 // The cross-scope precedence merge comes from the dependency-free
 // `lessons-pure.mjs` — the SAME `resolvePrecedence` `tree` uses, so the hook
 // can't drift from it, and the hot path never pulls in the `lessons-view.mjs`
@@ -14,7 +14,7 @@ import { deriveScope } from '../scope.mjs';
 // of what "most useful" means.
 import {
   resolvePrecedence, rankLessons, diversifyRankedLessons, capPerBucket, loopBucketOf,
-} from '../lessons-pure.mjs';
+} from '../shared/lessons-pure.mjs';
 // The store's own scope inventory, normalised — the SAME helper `memory.scopes`
 // uses, so the map and the MCP tool cannot disagree about what a scope holds or
 // about what a failed enumeration looks like.
@@ -23,7 +23,7 @@ import { readScopeInventory } from '../store/scope-inventory.mjs';
 // `--link` flag use, so the hook's confirmation/nudge links are JSON-encoded
 // correctly (a raw `?scope=global` silently means "all scopes") and can't drift
 // from the command-line links.
-import { loreScopeUrl, buildLessonUrl } from '../deeplink-pure.mjs';
+import { loreScopeUrl, buildLessonUrl } from '../shared/deeplink-pure.mjs';
 // The SAME resolver `lorekit write` applies, so the TTL the nudge advises an
 // agent to send is byte-for-byte the one the CLI would have applied itself. A
 // hook cannot set a TTL — it only reads and emits text; the write happens later,
@@ -41,7 +41,7 @@ import {
   DEFAULT_SESSION_START_MAX_LESSONS,
   MAX_SESSION_START_MAX_LESSONS,
   SESSION_START_MODES,
-} from '../control.mjs';
+} from '../shared/control.mjs';
 import { FRICTION_FAILURE, FRICTION_STUCK_LOOP } from './friction.mjs';
 
 // THE INJECTED SET IS BOUNDED BY A CHARACTER BUDGET, NOT BY A COUNT.

package/src/{config.mjs → shared/config.mjs}

@@ -5,8 +5,8 @@ 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/).
-export const PKG_ROOT = fileURLToPath(new URL('../', import.meta.url));
+// packages/cli/ — the installable package root (this file lives in src/shared/).
+export const PKG_ROOT = fileURLToPath(new URL('../../', import.meta.url));
 export const SKILL_NAME = 'lorekit-memory';
 export const SKILL_SOURCE = path.join(PKG_ROOT, 'skill', SKILL_NAME);
 

package/src/{deeplink-pure.mjs → shared/deeplink-pure.mjs}

@@ -131,6 +131,13 @@ export function loreScopeUrl(scope, opts = {}) {
 // own scope, coherent with the detail view. A lesson older than that window or
 // archived can still open blank — a dashboard-side limitation the link can't fix.
 // `scope` is the lesson's own scope. Pure.
+//
+// NOTE FOR ANYONE HAND-BUILDING A URL INSTEAD OF CALLING THIS: the `lesson`
+// param takes a JSON-encoded `{scope, key}`, NOT a memory id. If you hold the
+// `id` a write returned, the param is `?memoryId=<uuid>` (raw, not JSON-encoded).
+// `/lore` now also accepts a UUID in `?lesson=` so the wrong combination
+// resolves rather than silently doing nothing — but that is a safety net, and
+// this function is the thing to call when you have a scope and key.
 export function buildLessonUrl(scope, key, opts = {}) {
   const params = { lesson: { scope, key } };
   if (scope) params.scope = scope;

package/src/{lessons-pure.mjs → shared/lessons-pure.mjs}

@@ -271,7 +271,7 @@ export const DEFAULT_RANK_WEIGHTS = Object.freeze({ recency: 1, salience: 1, rel
  *
  * This is the ONE deliberate asymmetry vs `normalizeRelevance` (which returns
  * 0 for absent / unreadable input). Mirrored byte-identically in
- * `packages/mcp-core/src/lesson-rank.ts` and its edge twin.
+ * `packages/mcp-core/src/ranking/lesson-rank.ts` and its edge twin.
  */
 export const COLD_START_OUTCOME_PRIOR = 0.5;
 
@@ -491,7 +491,7 @@ function seenCountFrom(entry) {
  * MMR λ (lambda) — weight given to relevance vs diversity in the MMR objective.
  * At 0.7 the selector favours relevance, with 0.3 of the budget for diversity.
  * Anchored to Carbonell & Goldstein (1998), the original MMR paper.
- * Mirrored byte-identically in the edge twin and `packages/mcp-core/src/lesson-rank.ts`.
+ * Mirrored byte-identically in the edge twin and `packages/mcp-core/src/ranking/lesson-rank.ts`.
  */
 export const MMR_LAMBDA = 0.7;
 

package/src/{mcp.mjs → shared/mcp.mjs}

@@ -77,6 +77,24 @@ export async function mcpCall(endpoint, token, method, params = {}, { timeoutMs
         error: { code: res.status, message: text.slice(0, 200) || res.statusText },
       };
     }
+    // A tool-originated failure arrives as a SUCCESSFUL JSON-RPC result carrying
+    // `isError: true` — that is the MCP spec's shape, so the model can see the
+    // error and self-correct, and the edge handler now uses it for everything
+    // the caller can fix (a memory-cap hit, a malformed scope, a bad TTL).
+    //
+    // Without this branch the check above passes (there is no `json.error`) and
+    // the call is reported as `ok: true`, so a cap rejection reads as a
+    // successful write. Exactly the trap the load-test driver hit from the other
+    // side: on this transport the status code does not carry the outcome.
+    if (json && json.result && json.result.isError) {
+      const text0 = json.result.content && json.result.content[0];
+      return {
+        ok: false,
+        httpStatus: res.status,
+        toolError: true,
+        error: { code: 'tool_error', message: (text0 && text0.text) || 'The tool reported an error.' },
+      };
+    }
     return { ok: true, httpStatus: res.status, result: json ? json.result : undefined };
   } catch (e) {
     return { ok: false, networkError: String(e && e.message ? e.message : e) };

package/src/{origin.mjs → shared/origin.mjs}

@@ -65,7 +65,7 @@ function toPositiveInt(raw) {
  *
  * A deny list, deliberately: a branch is whatever a contributor named it, and
  * `feat/add+x` / `fix/issue#123` / `feat/café` are all legal. The canonical
- * rule lives in `packages/mcp-core/src/origin.ts` (`parseOriginBranch`); this
+ * rule lives in `packages/mcp-core/src/provenance/origin.ts` (`parseOriginBranch`); this
  * is the zero-dependency CLI copy, kept behaviourally identical so a branch the
  * CLI derives is never one the server would reject.
  */
@@ -155,7 +155,7 @@ export function deriveOrigin({ cwd = process.cwd(), env = process.env, run = git
  * Normalise a candidate `owner/name`, or null when it is not one.
  *
  * The single repo rule for every derivation path, matching the server's
- * `parseOriginRepo` (`packages/mcp-core/src/origin.ts`) — including its
+ * `parseOriginRepo` (`packages/mcp-core/src/provenance/origin.ts`) — including its
  * rejection of a dots-only segment, which `[\\w.-]+` alone admits and which
  * would render as a link to a different repository.
  */

package/src/{stores.mjs → shared/stores.mjs}

@@ -12,7 +12,7 @@ import process from 'node:process';
 import { localStoreDirs } from './control.mjs';
 import { resolveProjectConnection } from './config.mjs';
 import { splitEndpoint } from './mcp.mjs';
-import { createTwoTierStore, createRemoteStore } from './store/index.mjs';
+import { createTwoTierStore, createRemoteStore } from '../store/index.mjs';
 
 // Build both stores for `root`. Explicit `endpoint` / `token` (e.g. from
 // `--endpoint` / `--token` flags) take precedence over the resolved connection;

package/src/store/created-at.mjs

@@ -1,5 +1,5 @@
 // Zero-dependency mirror of the created_at validation used by the hosted MCP
-// server (packages/mcp-core/src/created-at.ts). Keeps the local `lorekit mcp`
+// server (packages/mcp-core/src/limits/created-at.ts). Keeps the local `lorekit mcp`
 // stdio server's memory.write contract identical to the remote one: an optional
 // ISO 8601 creation-date override, rejected when invalid or future-dated.
 

package/src/store/remote.mjs

@@ -14,13 +14,13 @@
 // and the `orgs` edge function now passes it plus its own tenant filters — so
 // every `/orgs*` route serves api_key tokens and the holdout is gone.
 //
-// `packages/cli/src/mcp.mjs` still exists and is still used: it backs the
+// `packages/cli/src/shared/mcp.mjs` still exists and is still used: it backs the
 // `lorekit mcp` stdio server command and provides `mcpToRestBase`. It is just
 // no longer a transport for this store.
 // Zero-dependency.
-import { restFetch, mcpToRestBase } from '../mcp.mjs';
-import { rememberAccountId } from '../telemetry-identity.mjs';
-import { getActiveTraceparent } from '../telemetry.mjs';
+import { restFetch, mcpToRestBase } from '../shared/mcp.mjs';
+import { rememberAccountId } from '../telemetry/telemetry-identity.mjs';
+import { getActiveTraceparent } from '../telemetry/telemetry.mjs';
 import { withReadFields } from './entry-fields.mjs';
 import { normalizeCreatedAt } from './created-at.mjs';
 
@@ -598,7 +598,7 @@ class RemoteStore {
   // ── Org operations → REST ─────────────────────────────────────────────────
   // `supabase/functions/orgs/` serves `lk_*` tokens on every route as of
   // 00041_org_actor_override.sql (see the file header). Each method's RETURN
-  // SHAPE is unchanged from the MCP era — `packages/cli/src/mcp-server.mjs`
+  // SHAPE is unchanged from the MCP era — `packages/cli/src/commands/mcp-server.mjs`
   // serialises these objects straight into a `tools/call` result, so the shape
   // is a published contract, not an internal detail.
   //
@@ -613,7 +613,7 @@ class RemoteStore {
   // `{ id, slug, name }`. A bare JSON id string is the LEGACY shape an older
   // deployed backend can still return — that is what the string branch below is
   // for, not the normal case. Either way this method reassembles the
-  // `{ id, slug, name }` triple, because `packages/cli/src/mcp-server.mjs`
+  // `{ id, slug, name }` triple, because `packages/cli/src/commands/mcp-server.mjs`
   // serialises it straight into a `tools/call` result and that shape is a
   // published contract.
   async orgCreate({ slug, name } = {}) {

package/src/store/ttl.mjs

@@ -1,5 +1,5 @@
 // Zero-dependency mirror of the TTL (time-to-live) contract used by the hosted
-// MCP server (packages/mcp-core/src/ttl.ts) and the `memory_write` RPC
+// MCP server (packages/mcp-core/src/limits/ttl.ts) and the `memory_write` RPC
 // (migrations 00030/00031). Keeps the local file store's expiry semantics
 // identical to the remote one, so a memory written offline expires the same way
 // it would have online — and a local↔remote migration is lossless.

package/src/surfaces.generated.mjs

@@ -1,5 +1,5 @@
 // GENERATED — do not edit.
-// Source: packages/schemas/src/tool-catalog.ts
+// Source: packages/schemas/src/shared/tool-catalog.ts
 // Regenerate: node scripts/gen-surfaces.mjs
 //
 // Edit the catalog's `surfaces` bindings, not this file. `--check` fails CI

package/src/{telemetry-identity.mjs → telemetry/telemetry-identity.mjs}

@@ -50,8 +50,8 @@
 import process from 'node:process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { homeRoot } from './control.mjs';
-import { writeFileAtomic } from './config.mjs';
+import { homeRoot } from '../shared/control.mjs';
+import { writeFileAtomic } from '../shared/config.mjs';
 
 /** Filename under the home tier. Sits beside `config.json` and the local store. */
 const IDENTITY_FILE = 'telemetry-id.json';

package/src/{telemetry.mjs → telemetry/telemetry.mjs}

@@ -34,7 +34,7 @@
 
 import process from 'node:process';
 import { TELEMETRY_TOKEN } from './telemetry-token.mjs';
-import { readLorekitJson } from './config.mjs';
+import { readLorekitJson } from '../shared/config.mjs';
 import {
   ensureIdentity,
   identityAttributes,
@@ -77,7 +77,7 @@ let _activeSampled = false;
  *
  * Flags are `01` when the CLI span is exported and `00` when it is not — the
  * trace id is still carried either way, so the server can correlate. This
- * mirrors `formatTraceparent` in `packages/mcp-core/src/trace-context.ts`
+ * mirrors `formatTraceparent` in `packages/mcp-core/src/telemetry/trace-context.ts`
  * (the CLI is zero-dep `.mjs` and cannot import the TS module); keep the two
  * byte-consistent.
  */