@lorekit/cli 1.25.0 → 1.26.0

package/README.md

@@ -308,6 +308,47 @@ coincidental overlaps. Any pair scoring at or above `--threshold` links (transit
 into one cluster; only clusters of 2+ members are reported, each with a similarity
 range. Cross-**store** divergence is `diff`'s job; `dedupe` looks within a store.
 
+### `lorekit link` (alias `url`)
+
+Print a shareable **dashboard deep-link URL** to stdout — nothing else, so it
+pipes straight into your clipboard or a PR/Slack message:
+
+```bash
+lorekit link                              # link to the current repo/branch context
+lorekit link | pbcopy                     # copy it straight to the clipboard
+lorekit link global                       # the Explorer filtered to global scope
+lorekit link repo::owner/repo prefer-guards   # open one lesson's detail sheet
+lorekit link global::prefer-guards --json     # { url, surface, base, params }
+lorekit url --q "flaky test" --owner personal # search + ownership filter
+```
+
+With no arguments it links to the cwd's **most-specific scope** ("share what I'm
+looking at"). A single argument that is a valid scope — including a `repo::…` or
+`branch::…::…` scope — links to the Explorer filtered to that scope; a scope
+**and** key (two positionals, or the `scope::key` shorthand) links straight to
+that lesson's detail sheet. It sets **both** the `lesson` param (which opens the
+sheet) and `scope` — not because scope is needed to find the lesson (the sidebar
+reads one unfiltered recent set), but so the Explorer list *behind* the sheet is
+filtered to the lesson's own scope. Filter flags mirror the Explorer: `--q`
+(search), `--owner <all|personal|orgId>`, `--range`/`--from`/`--to`, `--archived`,
+`--view <scope|time>`.
+
+Every param is `encodeURIComponent(JSON.stringify(value))` — the exact inverse of
+how the dashboard's `useUrlState` reads it back (`JSON.parse`, falling back to the
+default on failure). A raw `?scope=global` would silently mean "all scopes", so
+the link **must** be JSON-encoded to open the intended view. `--base <url>` (or
+`LOREKIT_APP_URL`) overrides the dashboard host for self-hosted setups; the
+default is `https://lorekit.io`. Read-only and network-free — it derives scopes
+from git and builds a URL, never touching a store.
+
+The **read commands take a `--link` flag** that short-circuits to print the
+equivalent deep link, reusing the same builder: `show <scope::key> --link` → the
+lesson link, `search foo --link` → `/lore?q="foo"` (+ scope), and `list --link` /
+`tree --link` → the Explorer filtered to the **most-specific applicable scope**
+(or `--scope` when given) — the dashboard filters one scope at a time, so the
+multi-scope `list`/`tree` view maps to its primary scope. (The same JSON-encoded
+links now back the hooks' write-confirmation and retrospective nudges.)
+
 ### `lorekit hook`
 
 The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
@@ -541,8 +582,10 @@ active deny constraints.
 | `--no-hooks` | Skip wiring the lifecycle hooks; skills + MCP only (`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`) |
-| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe`; default: all applicable). For `scopes` it is a **substring filter** over the inventory |
+| `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `link`) |
+| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe` / `link`; default: all applicable). For `scopes` it is a **substring filter** over the inventory |
+| `--link` | Print the equivalent dashboard deep-link URL instead of running (`show` / `search` / `list` / `tree`) |
+| `--base <url>` | Dashboard base URL for deep links (`link` / `--link`; else `LOREKIT_APP_URL`, default `https://lorekit.io`) |
 | `--threshold <0..1>` | Duplicate-similarity cutoff (`dedupe`; default `0.8`) |
 | `--adapter <name>` | Host framework for `hook`: `claude` / `cursor` / `codex` |
 | `--event <name>` | Host hook event for `hook` (else read from the stdin payload) |

package/bin/lorekit.mjs

@@ -16,6 +16,7 @@ import { diff } from '../src/diff.mjs';
 import { tree } from '../src/tree.mjs';
 import { lint } from '../src/lint.mjs';
 import { dedupe } from '../src/dedupe.mjs';
+import { link } from '../src/link.mjs';
 import { hook } from '../src/hook.mjs';
 import { migrate } from '../src/migrate.mjs';
 import { bootstrap } from '../src/bootstrap.mjs';
@@ -81,6 +82,12 @@ ${c.bold('Commands')}
   dedupe      Find likely-duplicate memories via a zero-dep word-overlap HEURISTIC
               (Jaccard >= threshold, not semantic), grouped into clusters per
               store. --json, --scope <s>, --threshold <0..1>.
+  link (url)  Print a shareable dashboard deep-link URL for the current context,
+              a scope, or a specific lesson (opens its detail sheet). No args
+              links to the cwd's most-specific scope. Filter flags mirror the
+              Explorer (--q / --owner / --range / --archived / --view); --base or
+              LOREKIT_APP_URL override the dashboard host. --json. Pipe it:
+              lorekit link | pbcopy.
   bootstrap   Apply the BYOD schema to a user-supplied Supabase database.
               Only needed when using LOREKIT_STORAGE_URL / LOREKIT_STORAGE_ANON_KEY.
               See docs/byod.md for setup instructions.
@@ -102,8 +109,10 @@ ${c.bold('Options')}
   -t, --token <token>     LoreKit token (lk_rw_* to allow writes, lk_ro_* read-only)
       --mode <mode>       Memory mode: off | local | remote (doctor override)
       --store <path>      Local project-tier store directory (default: .lorekit)
-      --json              Machine-readable output (list / search / show / stats / scopes / diff / tree / lint / dedupe)
-      --scope <scope>     Restrict to a single scope; a substring filter for scopes (list / search / stats / scopes / diff / tree / lint / dedupe)
+      --json              Machine-readable output (list / search / show / stats / scopes / diff / tree / lint / dedupe / link)
+      --scope <scope>     Restrict to a single scope; a substring filter for scopes (list / search / stats / scopes / diff / tree / lint / dedupe / link)
+      --link              Print the equivalent dashboard deep-link URL instead of running (show / search / list / tree)
+      --base <url>        Dashboard base URL for deep links (link / --link; else LOREKIT_APP_URL, default https://lorekit.io)
       --threshold <0..1>  Duplicate-similarity cutoff (dedupe; default 0.8)
       --from <path>       Source store to migrate from (migrate)
       --to <tier>         Migration destination tier: home | project (migrate;
@@ -228,11 +237,13 @@ ${c.bold('Options')}
   -e, --endpoint <url>    Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
   -t, --token <token>     Remote token override (else .mcp.json / LOREKIT_TOKEN)
       --store <path>      Local project-tier store directory (default: .lorekit)
+      --link              Print the Explorer deep-link for the most-specific scope (or --scope) instead of running (with --base / --json)
 
 ${c.bold('Examples')}
   npx @lorekit/cli list
   npx @lorekit/cli list --json
   npx @lorekit/cli list --scope global
+  npx @lorekit/cli list --scope global --link
 `,
   search: `${c.bold('lorekit search')} — full-text search the applicable memories ${c.dim('(alias: grep)')}
 
@@ -252,11 +263,13 @@ ${c.bold('Options')}
   -e, --endpoint <url>    Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
   -t, --token <token>     Remote token override (else .mcp.json / LOREKIT_TOKEN)
       --store <path>      Local project-tier store directory (default: .lorekit)
+      --link              Print this view's dashboard deep-link URL instead of running (with --base / --json)
 
 ${c.bold('Examples')}
   npx @lorekit/cli search sandbox
   npx @lorekit/cli grep "flaky test" --json
   npx @lorekit/cli search migration --scope global
+  npx @lorekit/cli search "flaky test" --scope global --link
 `,
   write: `${c.bold('lorekit write')} — create or update a memory from the CLI
 
@@ -277,6 +290,11 @@ ${c.bold('Options')}
       --trigger <slug>     Trigger context slug (default: none)
       --ttl-days <n>       Days until auto-expiry 1–365 (remote only)
       --org <slug>         Write to this org's scope (remote only)
+      --origin-repo <o/n>  Override the derived provenance repository
+      --origin-branch <b>  Override the derived provenance branch
+      --origin-commit <s>  Override the derived provenance commit SHA
+      --origin-pr <n>      The pull request this lesson came out of
+      --no-origin          Record no provenance at all
       --remote             Force write to the remote store
       --local              Force write to the local offline store
       --json               Machine-readable output
@@ -307,11 +325,13 @@ ${c.bold('Options')}
   -e, --endpoint <url>    Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
   -t, --token <token>     Remote token override (else .mcp.json / LOREKIT_TOKEN)
       --store <path>      Local project-tier store directory (default: .lorekit)
+      --link              Print this memory's dashboard deep-link URL instead of reading (with --base / --json)
 
 ${c.bold('Examples')}
   npx @lorekit/cli show global prefer-guard-clauses
   npx @lorekit/cli show global::prefer-guard-clauses
   npx @lorekit/cli show project::widget build-flags --json
+  npx @lorekit/cli show global prefer-guard-clauses --link
 `,
   stats: `${c.bold('lorekit stats')} — count the applicable memories per scope and per store
 
@@ -409,10 +429,12 @@ ${c.bold('Options')}
   -e, --endpoint <url>    Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
   -t, --token <token>     Remote token override (else .mcp.json / LOREKIT_TOKEN)
       --store <path>      Local project-tier store directory (default: .lorekit)
+      --link              Print the Explorer deep-link for the most-specific scope (or --scope) instead of running (with --base / --json)
 
 ${c.bold('Examples')}
   npx @lorekit/cli tree
   npx @lorekit/cli resolve --json
+  npx @lorekit/cli tree --scope global --link
 `,
   lint: `${c.bold('lorekit lint')} — flag low-quality memories across the applicable scopes
 
@@ -462,6 +484,42 @@ ${c.bold('Options')}
 ${c.bold('Examples')}
   npx @lorekit/cli dedupe
   npx @lorekit/cli dedupe --threshold 0.6 --json
+`,
+  link: `${c.bold('lorekit link')} — print a shareable dashboard deep-link URL ${c.dim('(alias: url)')}
+
+${c.bold('Usage')}
+  npx @lorekit/cli link [scope] [key] [options]
+  npx @lorekit/cli link <scope::key> [options]
+
+Prints a ${c.cyan('lorekit.io/lore')} deep link to stdout — nothing else — so it pipes
+cleanly into your clipboard or a message. With no arguments it links to the
+current directory's most-specific scope ("share what I'm looking at"). Given a
+scope it links to the Explorer filtered to that scope; given a scope AND key (or
+the ${c.cyan('scope::key')} shorthand) it links straight to that lesson's detail sheet.
+
+Every param is JSON-encoded exactly as the dashboard reads it, so the link opens
+the intended view — a raw ${c.dim('?scope=global')} would silently mean "all scopes".
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+      --scope <scope>     Scope to link to (when no positional scope is given)
+      --q <text>          Pre-fill the Explorer search box
+      --owner <o>         Ownership filter: all | personal | <orgId>
+      --range <json>      Date range as {"from":"YYYY-MM-DD","to":"YYYY-MM-DD"}
+      --from <date>       Range start (shorthand for --range)
+      --to <date>         Range end (shorthand for --range)
+      --archived          Include archived memories
+      --view <mode>       Explorer view: scope | time
+      --base <url>        Dashboard base URL (else LOREKIT_APP_URL, default https://lorekit.io)
+      --json              Machine-readable { url, surface, base, params }
+
+${c.bold('Examples')}
+  npx @lorekit/cli link                              # link to the current repo/branch context
+  npx @lorekit/cli link | pbcopy                     # copy it straight to the clipboard
+  npx @lorekit/cli link global                       # the Explorer filtered to global scope
+  npx @lorekit/cli link repo::owner/repo prefer-guards   # open one lesson's detail sheet
+  npx @lorekit/cli link global::prefer-guards --json     # { url, surface, base, params }
+  npx @lorekit/cli url --q "flaky test" --owner personal # search + ownership filter
 `,
   migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
 
@@ -517,6 +575,8 @@ const KNOWN_FLAGS = [
   'from', 'to', 'apply', 'yes', 'no-hooks', 'force', 'deep', 'adapter',
   'event', 'json', 'scope', 'threshold', 'help', 'version',
   'value', 'tags', 'source-agent', 'trigger', 'ttl-days', 'org', 'remote', 'local',
+  'link', 'base', 'q', 'owner', 'range', 'view', 'archived',
+  'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
 ];
 
 // Commands that write to disk / talk to the network on a human's behalf. These
@@ -524,12 +584,12 @@ const KNOWN_FLAGS = [
 // never fail on a stray flag, and only ever receive flags we control).
 const HUMAN_COMMANDS = new Set([
   'install', 'uninstall', 'doctor', 'list', 'search', 'show', 'stats', 'scopes',
-  'diff', 'tree', 'lint', 'dedupe', 'migrate', 'write',
+  'diff', 'tree', 'lint', 'dedupe', 'link', 'migrate', 'write',
 ]);
 
 // Command aliases — canonicalized before help / dispatch so `lorekit ls --help`
 // and telemetry both resolve to the real command name.
-const COMMAND_ALIASES = { ls: 'list', grep: 'search', resolve: 'tree' };
+const COMMAND_ALIASES = { ls: 'list', grep: 'search', resolve: 'tree', url: 'link' };
 
 async function main() {
   // Load a `.env` from the current directory (if any) before anything reads the
@@ -541,7 +601,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', 'json', 'remote', 'local'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'no-origin', 'json', 'remote', 'local', 'link', 'archived'],
     known: KNOWN_FLAGS,
   });
 
@@ -616,6 +676,8 @@ async function main() {
       return traceCommand('lint', args, VERSION, () => lint(args));
     case 'dedupe':
       return traceCommand('dedupe', args, VERSION, () => dedupe(args));
+    case 'link':
+      return traceCommand('link', args, VERSION, () => link(args));
     case 'migrate':
       return traceCommand('migrate', args, VERSION, () => migrate(args));
     case 'bootstrap':

package/package.json

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

package/src/core/lessons.mjs

@@ -8,6 +8,11 @@ import { deriveScope } from '../scope.mjs';
 // use, so the hook can't drift from them, and the hot path never pulls in the
 // `lessons-view.mjs` render/`util` stack.
 import { resolvePrecedence, matchesQuery } from '../lessons-pure.mjs';
+// The deep-link builder is the SAME pure module the `link` command and the
+// `--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';
 
 const MAX_LESSONS = 15;
 // Cap on lessons injected on a failure — a small, focused "you've seen this
@@ -176,10 +181,11 @@ function tagsHint(writeScope, { tagsDefault = [], scopeDefaults = null } = {}) {
 
 // The LoreKit web app URL for the Lore Explorer, pre-filtered to the given scope.
 // Exported so tests can assert the URL shape without re-deriving the encoding.
+// Delegates to the shared `loreScopeUrl` so the scope param is JSON-encoded the
+// way the dashboard reads it — the previous raw `?scope=${scope}` fell through
+// `useUrlState`'s `JSON.parse` and silently filtered to ALL scopes.
 export function loreUrl(writeScope) {
-  const base = 'https://lorekit.io/lore';
-  if (!writeScope || writeScope === 'global') return base;
-  return `${base}?scope=${encodeURIComponent(writeScope)}`;
+  return loreScopeUrl(writeScope);
 }
 
 // The retrospective nudge emitted at end-of-turn (one-shot per session).
@@ -200,16 +206,20 @@ export function retrospectiveNudge(scope, control) {
 }
 
 // Terse confirmation emitted via PostToolUse when a memory.write succeeded.
-// `key` is the lesson key from the tool response (may be null when the response
-// shape doesn't surface it). Includes a deep link to the scope's Lore Explorer
-// page so the user can verify immediately.
-export function writeConfirmation(scope, key) {
-  const writeScope = scope.repoScope || 'global';
+// `key` is the lesson key from the tool input (may be null when it isn't
+// surfaced). `writtenScope` is the ACTUAL scope the write targeted (from the tool
+// input) — the link must point there, not at `repoScope`: a `global` (or project)
+// write deep-linked to `repoScope` would open a lesson ref that doesn't exist.
+// Falls back to the cwd's repo scope, then `global`, when the write scope is
+// unknown. When the key is known the link opens that exact lesson's detail sheet
+// (`?scope=…&lesson=…`); otherwise it filters the Explorer to the write scope —
+// both JSON-encoded via the shared builder so they actually open the intended view.
+export function writeConfirmation(scope, key, writtenScope) {
+  const target =
+    typeof writtenScope === 'string' && writtenScope ? writtenScope : scope.repoScope || 'global';
   const keyPart = key ? ` · ${key}` : '';
-  const url = key
-    ? `${loreUrl(writeScope)}&q=${encodeURIComponent(key)}`
-    : loreUrl(writeScope);
-  return `LoreKit: memory saved to ${writeScope}${keyPart}\nView: ${url}`;
+  const url = key ? buildLessonUrl(target, key) : loreScopeUrl(target);
+  return `LoreKit: memory saved to ${target}${keyPart}\nView: ${url}`;
 }
 
 // The nudge emitted when a tool failure is detected.

package/src/deeplink-pure.mjs

@@ -0,0 +1,194 @@
+// Dependency-free deep-link builder for LoreKit dashboard URLs.
+//
+// Zero imports on purpose (the `lessons-pure.mjs` precedent): both the hook hot
+// path (`core/lessons.mjs`) and the `link` command / `--link` flag share this
+// without pulling in `util`/render/store code.
+//
+// THE governing constraint — every `/lore` Explorer param is read by the web
+// app's `useUrlState` (`packages/web/src/lib/hooks/useUrlState.ts`) via
+// `JSON.parse(searchParams.get(key))`, falling back to the param's DEFAULT on a
+// parse failure and OMITTING any param whose value equals its default. So a URL
+// value must be `encodeURIComponent(JSON.stringify(value))` — a JSON string,
+// double-quoted for a string scope — NOT a raw token. A raw `?scope=global`
+// fails `JSON.parse` and silently means "all scopes". This is the exact inverse
+// of the app's read, and mirrors the production builder in
+// `packages/web/src/components/dashboard/ScopeHealthCard.tsx`:
+//   `/lore?scope=${encodeURIComponent(JSON.stringify(health.scope))}`.
+
+// The default dashboard base for the hosted deployment. Overridable per call
+// (self-hosted setups) via `resolveAppBase` (`--base` flag / `LOREKIT_APP_URL`).
+export const DEFAULT_APP_BASE = 'https://lorekit.io';
+
+// The `/lore` Explorer param defaults, mirroring the `useUrlState` calls in
+// `LoreExplorer.tsx` (+ the `lesson` param in `MemorySidebarProvider.tsx`)
+// EXACTLY. A param whose value JSON-equals its default is omitted from the URL
+// — the app would treat a present-but-default param as noise, and clean URLs
+// match what the app itself produces.
+export const LORE_PARAM_DEFAULTS = {
+  scope: null, // string | null — null means "all scopes"
+  q: '', // string search query
+  range: null, // { from, to } | null (DateRange, "YYYY-MM-DD")
+  owner: 'all', // 'all' | 'personal' | { orgId }
+  view: 'scope', // 'scope' | 'time'
+  archived: false, // boolean
+  lesson: null, // { scope, key } | null — opens the detail sheet
+};
+
+// A stable, readable param order (also makes URLs deterministic for tests).
+// `scope` precedes `lesson` so a lesson link reads `?scope=…&lesson=…`.
+const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'view', 'archived', 'lesson'];
+
+// Strip trailing slashes from a base URL, falling back to the default when the
+// input is empty/absent. Pure.
+function normalizeBase(base) {
+  const b = String(base == null ? '' : base)
+    .trim()
+    .replace(/\/+$/, '');
+  return b || DEFAULT_APP_BASE;
+}
+
+// Resolve the dashboard base URL: an explicit `--base` flag wins, then the
+// `LOREKIT_APP_URL` env var, then the baked-in default. Pure — `env` is passed
+// in (never read from `process` here) so it stays trivially unit-testable.
+export function resolveAppBase({ base, env = {} } = {}) {
+  const flag = typeof base === 'string' && base.trim() ? base.trim() : '';
+  const fromEnv =
+    env && typeof env.LOREKIT_APP_URL === 'string' && env.LOREKIT_APP_URL.trim()
+      ? env.LOREKIT_APP_URL.trim()
+      : '';
+  return normalizeBase(flag || fromEnv || DEFAULT_APP_BASE);
+}
+
+// Encode ONE param value the way `useUrlState` reads it back:
+// `encodeURIComponent(JSON.stringify(value))`. The exact inverse of the app's
+// `JSON.parse(searchParams.get(key))`. Pure.
+export function encodeParam(value) {
+  return encodeURIComponent(JSON.stringify(value));
+}
+
+// Build the `/lore` query string from a params object, JSON-encoding each value
+// and OMITTING any param that is `undefined` or JSON-equal to its default (so
+// the URL carries only the filters that actually change the view). Pure and
+// total — an unknown key in `params` is ignored (only PARAM_ORDER is emitted).
+export function buildLoreQuery(params = {}) {
+  const parts = [];
+  for (const key of PARAM_ORDER) {
+    const value = params[key];
+    if (value === undefined) continue;
+    if (JSON.stringify(value) === JSON.stringify(LORE_PARAM_DEFAULTS[key])) continue;
+    parts.push(`${key}=${encodeParam(value)}`);
+  }
+  return parts.join('&');
+}
+
+// Build a full `/lore` deep link from a params object. `base` defaults to the
+// hosted dashboard; pass a resolved base for self-hosted setups. Pure.
+export function buildLoreUrl(params = {}, { base = DEFAULT_APP_BASE } = {}) {
+  const cleanBase = normalizeBase(base);
+  const query = buildLoreQuery(params);
+  return `${cleanBase}/lore${query ? `?${query}` : ''}`;
+}
+
+// A shareable link to the Explorer filtered to a scope. `null`/`''` → the bare
+// `/lore` (all scopes, the default); any concrete scope — INCLUDING `global` —
+// → `?scope="<scope>"`. (`global` is a real scope the app can filter to, not a
+// synonym for "no filter" — only the actual default `null` is omitted.) Pure.
+export function loreScopeUrl(scope, opts = {}) {
+  const params = scope ? { scope } : {};
+  return buildLoreUrl(params, opts);
+}
+
+// A shareable link that opens a specific lesson's detail sheet. Sets the
+// `lesson` param (which opens the sheet) plus `scope` — NOT because scope is
+// needed to RESOLVE the lesson (the sidebar's `useLoreData` reads one unfiltered
+// recent set, `.limit(500)`, non-archived, so `scope` does not widen that
+// lookup), but so the Explorer list BEHIND the sheet is filtered to the lesson's
+// 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.
+export function buildLessonUrl(scope, key, opts = {}) {
+  const params = { lesson: { scope, key } };
+  if (scope) params.scope = scope;
+  return buildLoreUrl(params, opts);
+}
+
+// Resolve a SINGLE positional `link` argument into a { scope, key } pair,
+// disambiguating a bare scope from the `<scope>::<key>` shorthand. `isScope` is
+// an injected validity predicate (the caller passes a `scopeIssue`-based check),
+// keeping this module zero-import.
+//
+// The rule: split at the LAST `::` and take it as `<scope>::<key>` ONLY when the
+// left side is itself a COMPLETE valid scope — otherwise the whole arg is the
+// scope. Splitting on the last `::` (not the first) keeps a multi-segment scope
+// whole (`repo::owner/name::key` → scope `repo::owner/name`, key `key`); gating
+// on a valid left side means a bare `repo::owner/name` is NOT mis-split, because
+// its left part `repo` is not a valid scope. This is the fix for the prior
+// first-`::` split, which turned `link repo::acme/widget` into scope="repo" plus
+// a bogus `acme/widget` key — breaking the shorthand for EVERY non-`global`
+// scope. A malformed arg falls through to the scope, never a fabricated key. Pure.
+export function resolveScopeArg(arg, isScope = () => false) {
+  const s = typeof arg === 'string' ? arg.trim() : '';
+  if (!s) return { scope: null, key: null };
+  const idx = s.lastIndexOf('::');
+  if (idx !== -1) {
+    const left = s.slice(0, idx).trim();
+    const right = s.slice(idx + 2).trim();
+    if (right && isScope(left)) return { scope: left, key: right };
+  }
+  return { scope: s, key: null };
+}
+
+// ── Flag → param coercion (pure, shared by the `link` command) ────────────────
+
+// Coerce the `--owner` flag to an `OwnerFilter`: 'all' (default) / 'personal' /
+// any other non-empty string → `{ orgId }`. Pure.
+export function parseOwnerArg(owner) {
+  if (typeof owner !== 'string' || !owner || owner === 'all') return 'all';
+  if (owner === 'personal') return 'personal';
+  return { orgId: owner };
+}
+
+// Coerce the `--view` flag to a `ViewMode`: only 'time' is non-default; anything
+// else (incl. absent/invalid) → 'scope'. Pure.
+export function parseViewArg(view) {
+  return view === 'time' ? 'time' : 'scope';
+}
+
+// Coerce the date-range flags to a `{ from, to }` DateRange or null. `--range`
+// (a JSON object string) wins; else `--from`/`--to` shorthand builds one (both
+// keys always present so the shape matches the app's DateRange). A malformed
+// `--range` yields null rather than throwing. Pure.
+export function parseRangeArg({ range, from, to } = {}) {
+  if (typeof range === 'string' && range.trim()) {
+    try {
+      const v = JSON.parse(range);
+      if (v && typeof v === 'object') return v;
+    } catch {
+      /* malformed --range → no range */
+    }
+    return null;
+  }
+  const hasFrom = typeof from === 'string' && from;
+  const hasTo = typeof to === 'string' && to;
+  if (hasFrom || hasTo) {
+    return { from: hasFrom ? from : '', to: hasTo ? to : '' };
+  }
+  return null;
+}
+
+// The Explorer's most-specific applicable scope for the cwd — `readOrder`'s
+// first non-global entry, or null when only `global` applies (→ a bare `/lore`).
+// The single-scope representation a deep link can carry for a multi-scope view.
+// Pure — takes an already-derived `deriveScope()` result.
+export function mostSpecificScope({ readOrder = [] } = {}) {
+  return readOrder.find((s) => s && s !== 'global') ?? null;
+}
+
+// Classify a params object into a bounded surface label (non-PII — safe as a
+// telemetry attribute): 'lesson' | 'search' | 'scope' | 'explorer'. Pure.
+export function surfaceFor(params = {}) {
+  if (params.lesson) return 'lesson';
+  if (params.q) return 'search';
+  if (params.scope) return 'scope';
+  return 'explorer';
+}

package/src/doctor.mjs

@@ -282,14 +282,43 @@ async function deepCheckRemote(store, root, record) {
     record('fail', 'round-trip', `write failed: ${w.error ? w.error.message || w.error.code : w.networkError}`);
     return;
   }
-  const r = await store.read({ scope: writeScope, key });
-  const readBack = r.ok && JSON.stringify(r.entry || '').includes('round-trip');
-  record(
-    readBack ? 'pass' : 'warn',
-    'round-trip',
-    readBack ? `wrote + read back in ${writeScope}` : 'wrote, but read-back was inconclusive',
-  );
-  await store.delete({ scope: writeScope, key, force: true });
+  // Everything after a SUCCESSFUL write runs under `finally`, because this
+  // probe writes to the user's REAL project (CI runs it against production on
+  // every deploy). A throw or an early return between the write and the delete
+  // leaves a synthetic row in that tenant with nothing to remove it — the read
+  // is a diagnostic, never a reason to abandon the row it created.
+  try {
+    const r = await store.read({ scope: writeScope, key });
+    const readBack = r.ok && JSON.stringify(r.entry || '').includes('round-trip');
+    record(
+      readBack ? 'pass' : 'warn',
+      'round-trip',
+      readBack ? `wrote + read back in ${writeScope}` : 'wrote, but read-back was inconclusive',
+    );
+  } finally {
+    await removeProbeRow(store, writeScope, key, record);
+  }
+}
+
+/**
+ * Delete the probe row, reporting rather than swallowing a failure.
+ *
+ * A silent `.catch` here means a synthetic row left in the user's REAL project
+ * with no signal anywhere — the same class of invisible leak this cleanup work
+ * exists to end. It is a `warn`, not a `fail`: the round-trip the user asked
+ * about did happen, so this must not flip doctor's verdict; it must just be
+ * impossible to miss. Both the thrown case and the `{ ok: false }` case are
+ * covered, because a REST delete reports its failure in the return value.
+ */
+async function removeProbeRow(store, writeScope, key, record) {
+  try {
+    const d = await store.delete({ scope: writeScope, key, force: true });
+    if (d && d.ok === false) {
+      record('warn', 'round-trip cleanup', `could not remove ${writeScope}::${key} — delete it manually`);
+    }
+  } catch (err) {
+    record('warn', 'round-trip cleanup', `could not remove ${writeScope}::${key}: ${err && err.message ? err.message : err}`);
+  }
 }
 
 async function deepCheckLocal(store, scope, record) {
@@ -302,14 +331,19 @@ async function deepCheckLocal(store, scope, record) {
     tags: ['skill::lorekit-memory', 'source::doctor'],
     trigger: 'manual',
   });
-  const r = await store.read({ scope: writeScope, key });
-  const readBack = w.ok && r.ok && r.entry && String(r.entry.value).includes('round-trip');
-  record(
-    readBack ? 'pass' : 'warn',
-    'round-trip',
-    readBack ? `wrote + read back in ${writeScope}` : 'write/read-back was inconclusive',
-  );
-  await store.delete({ scope: writeScope, key, force: true });
+  // Same `finally` contract as the remote probe: the local store is a real
+  // store too, and a half-finished probe should not leave a row in it.
+  try {
+    const r = await store.read({ scope: writeScope, key });
+    const readBack = w.ok && r.ok && r.entry && String(r.entry.value).includes('round-trip');
+    record(
+      readBack ? 'pass' : 'warn',
+      'round-trip',
+      readBack ? `wrote + read back in ${writeScope}` : 'write/read-back was inconclusive',
+    );
+  } finally {
+    await removeProbeRow(store, writeScope, key, record);
+  }
 }
 
 // Returns the list of CLAUDE_HOOK_EVENTS whose lorekit hook command appears in

package/src/hook.mjs

@@ -122,7 +122,13 @@ async function run(args) {
         const key = (parsed.toolInput && typeof parsed.toolInput.key === 'string')
           ? parsed.toolInput.key
           : null;
-        emit(writeConfirmation(scope, key));
+        // The scope the write actually targeted (tool input) — the confirmation
+        // link must point there, not at the cwd's repo scope, or a global/project
+        // write would deep-link to a lesson ref that doesn't exist.
+        const writtenScope = (parsed.toolInput && typeof parsed.toolInput.scope === 'string' && parsed.toolInput.scope)
+          ? parsed.toolInput.scope
+          : null;
+        emit(writeConfirmation(scope, key, writtenScope));
       }
     } catch {
       // best-effort — never break the host