@lorekit/cli 1.24.1 → 1.25.1

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
 
@@ -307,11 +320,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 +424,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 +479,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 +570,7 @@ 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',
 ];
 
 // Commands that write to disk / talk to the network on a human's behalf. These
@@ -524,12 +578,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 +595,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', 'json', 'remote', 'local', 'link', 'archived'],
     known: KNOWN_FLAGS,
   });
 
@@ -616,6 +670,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.24.1",
+  "version": "1.25.1",
   "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

package/src/link.mjs

@@ -0,0 +1,139 @@
+// `lorekit link` (alias `url`) — print a shareable dashboard deep-link URL to
+// stdout for the current directory's context, a scope, or a specific lesson.
+//
+// Read-only and network-free: it derives scopes from git and builds a URL — it
+// never talks to a store. The URL alone is written to stdout (pipeable, e.g.
+// `lorekit link | pbcopy`); any advisory note goes to stderr, and only when
+// stderr is a TTY, so a pipe stays clean. Human-facing, so the bin wraps it in
+// `traceCommand`.
+//
+//   lorekit link                    → /lore filtered to the cwd's most-specific scope
+//   lorekit link <scope>            → /lore?scope="<scope>"
+//   lorekit link <scope> <key>      → a link that opens that lesson's detail sheet
+//   lorekit link <scope::key>       → same, via the copy-paste shorthand
+//
+// 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 { scopeIssue } from './lessons-view.mjs';
+import {
+  resolveAppBase,
+  buildLoreUrl,
+  mostSpecificScope,
+  parseOwnerArg,
+  parseViewArg,
+  parseRangeArg,
+  resolveScopeArg,
+  surfaceFor,
+} from './deeplink-pure.mjs';
+import { log, err } from './util.mjs';
+
+export async function link(args) {
+  const root = resolveProjectRoot(args.dir);
+  const env = { ...process.env };
+  const scopeInfo = deriveScope(root);
+  const base = resolveAppBase({ base: args.base, env });
+
+  // Positionals: link [scope] [key] OR link <scope::key>. args._[0] is the
+  // command token ('link' / 'url'), so the first argument is args._[1].
+  const first = typeof args._[1] === 'string' ? args._[1] : '';
+  const second = typeof args._[2] === 'string' ? args._[2] : '';
+  let scope = null;
+  let key = null;
+  if (first && second) {
+    // Two positionals — the first IS the scope (even one containing `::`, like
+    // `repo::owner/name`); the second is the key. The `scope::key` shorthand is
+    // only consulted for a single positional, below.
+    scope = first;
+    key = second;
+  } else if (first) {
+    // One positional: disambiguate a bare scope from the `<scope>::<key>`
+    // shorthand by scope validity, not by a naive first-`::` split — otherwise
+    // `link repo::owner/name` (a valid scope) is misread as scope="repo" + a
+    // bogus key. `scopeIssue(s) === null` is the canonical "is a valid scope".
+    const resolved = resolveScopeArg(first, (s) => scopeIssue(s) === null);
+    scope = resolved.scope;
+    key = resolved.key;
+  }
+  // `--scope` sets the scope when no positional scope was given (consistency
+  // with the other read commands); an explicit positional always wins.
+  if (!scope && typeof args.scope === 'string' && args.scope) scope = args.scope;
+
+  // Filter flags (all optional; each JSON-encoded + default-omitted downstream).
+  const q = typeof args.q === 'string' ? args.q : '';
+  const owner = parseOwnerArg(args.owner);
+  const view = parseViewArg(args.view);
+  const range = parseRangeArg(args);
+  const archived = Boolean(args.archived);
+
+  const gaveAnyInput =
+    Boolean(first) ||
+    (typeof args.scope === 'string' && Boolean(args.scope)) ||
+    Boolean(q) ||
+    owner !== 'all' ||
+    view !== 'scope' ||
+    range !== null ||
+    archived;
+
+  // Bare `lorekit link` (no scope, no lesson, no filters) → the cwd's
+  // most-specific scope, so it links to "what I'm looking at". Falls back to a
+  // bare /lore when only `global` applies.
+  if (!scope && !key && !gaveAnyInput) {
+    scope = mostSpecificScope(scopeInfo);
+  }
+
+  // Assemble only the non-default params (clean URL + a truthful `--json`).
+  const params = {};
+  if (scope) params.scope = scope;
+  if (key) params.lesson = { scope, key };
+  if (q) params.q = q;
+  if (owner !== 'all') params.owner = owner;
+  if (view !== 'scope') params.view = view;
+  if (range !== null) params.range = range;
+  if (archived) params.archived = true;
+
+  // UX guard: a lesson/scope link pointing at a scope the caller isn't in
+  // (a different repo/project) may render empty for them. Note it on stderr —
+  // never stdout (keeps the URL pipeable) — and only when stderr is a TTY and
+  // we're not emitting JSON, so scripts and pipes stay quiet.
+  maybeWarnScope(scope, scopeInfo, args.json);
+
+  return emitLink({ params, base, json: args.json });
+}
+
+// Emit a deep link: the URL alone on stdout (pipeable), or the structured
+// `{ url, surface, base, params }` under `--json`. Returns the bounded, non-PII
+// telemetry extras (the surface enum + booleans — never a scope string, key,
+// query, or base URL). Shared by the `link` command AND the read commands'
+// `--link` short-circuit so the two emit an identical shape. `params` is the
+// already-assembled non-default param set.
+export function emitLink({ params = {}, base, json }) {
+  const url = buildLoreUrl(params, { base });
+  const surface = surfaceFor(params);
+  if (json) {
+    log(JSON.stringify({ url, surface, base, params }, null, 2));
+  } else {
+    log(url);
+  }
+  return {
+    exitCode: 0,
+    'lorekit.cli.link.surface': surface,
+    'lorekit.cli.link.has_scope': Boolean(params.scope),
+    'lorekit.cli.link.has_lesson': Boolean(params.lesson),
+  };
+}
+
+// Warn (stderr, TTY-only) when `scope` is a concrete scope the caller isn't in.
+// `global` is always visible; a scope present in the cwd's `readOrder` is too.
+function maybeWarnScope(scope, scopeInfo, json) {
+  if (json || !scope || scope === 'global') return;
+  if (!process.stderr.isTTY) return;
+  if ((scopeInfo.readOrder || []).includes(scope)) return;
+  err(
+    `note: ${scope} is not one of your current scopes ` +
+      `(${(scopeInfo.readOrder || []).join(', ')}); ` +
+      `the link may show nothing if you can't access that scope.`,
+  );
+}

package/src/list.mjs

@@ -14,6 +14,8 @@ 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 { resolveAppBase, mostSpecificScope } from './deeplink-pure.mjs';
+import { emitLink } from './link.mjs';
 import { log, heading, c } from './util.mjs';
 
 // Abbreviate the user's home directory to `~` for readable paths.
@@ -40,6 +42,17 @@ export async function list(args) {
   // scope outside the applicable set is honoured — the user asked for it).
   const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeList(scopeInfo);
 
+  // `--link` short-circuits: print the Explorer deep link for the current
+  // context (the most-specific applicable scope, or `--scope`), no store reads.
+  if (args.link) {
+    const base = resolveAppBase({ base: args.base, env });
+    const scope =
+      args.scope && typeof args.scope === 'string' ? args.scope : mostSpecificScope(scopeInfo);
+    const params = {};
+    if (scope) params.scope = scope;
+    return emitLink({ params, base, json: args.json });
+  }
+
   const { local, remote, connection } = resolveStores(root, {
     env,
     endpoint: args.endpoint,

package/src/mcp.mjs

@@ -124,16 +124,36 @@ export function mcpToRestBase(mcpEndpointUrl) {
  * @param {number} [opts.timeoutMs=10000]
  * @param {string} [opts.traceparent] - W3C traceparent header value
  */
+/**
+ * Normalise a client-supplied usage correlation id (a PR ref, session id, or CI
+ * job id). Bounded + charset-restricted to match the server's `parseCorrelationId`
+ * (supabase/functions/_shared/usage-stats.ts); returns null for empty/over-long/
+ * out-of-charset input so a bad value is simply not sent. Zero-dep (the CLI does
+ * not import mcp-core), so the small regex is duplicated intentionally.
+ */
+export function normalizeCorrelationId(raw) {
+  if (typeof raw !== 'string') return null;
+  const t = raw.trim();
+  if (!t || t.length > 200) return null;
+  return /^[A-Za-z0-9_\-./:#@]+$/.test(t) ? t : null;
+}
+
 export async function restFetch(baseUrl, token, path, { method = 'GET', body, timeoutMs = 10000, traceparent } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
     const url = `${baseUrl}${path}`;
+    // Opt-in usage correlation: when LOREKIT_CORRELATION_ID is set (e.g. by a CI
+    // job or a hook to a PR/session id), tag every REST call so GET
+    // /memories/usage?correlation_id=… can report "usage for this PR". Absent env
+    // ⇒ no header ⇒ existing behaviour unchanged.
+    const correlationId = normalizeCorrelationId(process.env.LOREKIT_CORRELATION_ID);
     const headers = {
       accept: 'application/json',
       ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
       ...(token ? { authorization: `Bearer ${token}` } : {}),
       ...(traceparent ? { traceparent } : {}),
+      ...(correlationId ? { 'x-lorekit-correlation-id': correlationId } : {}),
     };
     const res = await fetch(url, {
       method,

package/src/search.mjs

@@ -19,6 +19,8 @@ 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 { emitLink } from './link.mjs';
 import { log, err, heading, c } from './util.mjs';
 
 export async function search(args) {
@@ -41,6 +43,17 @@ export async function search(args) {
   // scope outside the applicable set is honoured — the user asked for it).
   const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeList(scopeInfo);
 
+  // `--link` short-circuits: print the Explorer deep link for this search
+  // (`?q=…` plus the most-specific applicable scope), without touching a store.
+  if (args.link) {
+    const base = resolveAppBase({ base: args.base, env });
+    const scope =
+      args.scope && typeof args.scope === 'string' ? args.scope : mostSpecificScope(scopeInfo);
+    const params = { q: query };
+    if (scope) params.scope = scope;
+    return emitLink({ params, base, json: args.json });
+  }
+
   const { local, remote, connection } = resolveStores(root, {
     env,
     endpoint: args.endpoint,

package/src/show.mjs

@@ -19,6 +19,8 @@ import { resolveProjectRoot } from './config.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
 import { normalizeEntry, shortDate, describeError, recordsDiverge, parseScopeKey } from './lessons-view.mjs';
+import { resolveAppBase } from './deeplink-pure.mjs';
+import { emitLink } from './link.mjs';
 import { log, err, heading, status, c } from './util.mjs';
 
 // Read one scope::key from a store, normalizing the result into a small,
@@ -67,6 +69,13 @@ export async function show(args) {
     return 1;
   }
 
+  // `--link` short-circuits: print the deep link that opens THIS lesson's detail
+  // sheet (`?scope=…&lesson=…`) for the current args, without touching a store.
+  if (args.link) {
+    const base = resolveAppBase({ base: args.base, env });
+    return emitLink({ params: { scope, lesson: { scope, key } }, base, json: args.json });
+  }
+
   const { local, remote, connection } = resolveStores(root, {
     env,
     endpoint: args.endpoint,

package/src/telemetry.mjs

@@ -5,8 +5,8 @@
 // otel.ts): OTLP/JSON over the global fetch (Node 18+), no @opentelemetry/*
 // packages. One span + one counter data point per human-facing command
 // (install / uninstall / doctor / list / search / show / stats / scopes / diff /
-// tree / lint / dedupe / migrate), fired to Dash0 so the maintainers can see
-// which commands people actually run.
+// tree / lint / dedupe / link / migrate), fired to Dash0 so the maintainers can
+// see which commands people actually run.
 //
 // Privacy — this runs on end-users' machines, so it is deliberately narrow:
 //   • Opt-out honored: LOREKIT_TELEMETRY=0|off|false|no|disable, or the
@@ -38,7 +38,7 @@ const DEFAULT_DATASET = 'default';
 
 // Flags worth counting (e.g. how many installs are --global). Bounded on
 // purpose: only these booleans are ever attached, never free-form values.
-const FLAG_ATTRS = ['global', 'project', 'deep', 'yes', 'force', 'no-hooks', 'json'];
+const FLAG_ATTRS = ['global', 'project', 'deep', 'yes', 'force', 'no-hooks', 'json', 'link'];
 
 const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disable', 'disabled']);
 
@@ -165,16 +165,58 @@ function toOtlpAttributes(attributes) {
   return Object.entries(attributes).map(([key, value]) => ({ key, value: toOtlpValue(value) }));
 }
 
-function resourceAttributes(version) {
-  return [
+// OTel `os.type` / `host.arch` use their own bounded enum vocabularies, which
+// are NOT identical to Node's `process.platform` / `process.arch` spellings.
+// Node's `win32` / `sunos` and `x64` / `ia32` / `arm` are the ones that differ;
+// emitting them verbatim produces off-registry attribute values that a Dash0 /
+// OTel-native backend can't group with telemetry from other SDKs. Map the known
+// divergences and pass anything already-canonical (or unknown) through.
+//   os.type:   https://opentelemetry.io/docs/specs/semconv/registry/attributes/os/
+//   host.arch: https://opentelemetry.io/docs/specs/semconv/registry/attributes/host/
+const OS_TYPE_BY_PLATFORM = { win32: 'windows', sunos: 'solaris' };
+// Node's `process.arch` reports `ppc` for 32-bit PowerPC; the OTel `host.arch`
+// registry value for it is `ppc32` (its `ppc64` spelling already matches Node).
+const HOST_ARCH_BY_PROCESS_ARCH = { x64: 'amd64', ia32: 'x86', arm: 'arm32', ppc: 'ppc32' };
+
+/** Map a Node `process.platform` value to an OTel `os.type` registry value. */
+export function normalizeOsType(platform) {
+  return OS_TYPE_BY_PLATFORM[platform] ?? platform;
+}
+
+/** Map a Node `process.arch` value to an OTel `host.arch` registry value. */
+export function normalizeHostArch(arch) {
+  return HOST_ARCH_BY_PROCESS_ARCH[arch] ?? arch;
+}
+
+/**
+ * Resolve the `deployment.environment.name` resource value, or `undefined` when
+ * none is set. The CLI runs on end-users' machines, so — unlike the edge/web/
+ * mcp-node deployments — it has no ambient environment and deliberately OMITS
+ * the attribute by default. It is emitted ONLY when explicitly overridden via
+ * `DEPLOYMENT_ENVIRONMENT` (falling back to `OTEL_DEPLOYMENT_ENVIRONMENT`) — the
+ * same single, env-driven knob the edge honours, which the correlated-trace
+ * harness (`scripts/emit-correlated-trace.mts`) uses to stamp `test`.
+ * @param {object} [env]  defaults to process.env
+ */
+export function resolveDeploymentEnvironment(env = process.env) {
+  const raw = env.DEPLOYMENT_ENVIRONMENT ?? env.OTEL_DEPLOYMENT_ENVIRONMENT;
+  const value = raw !== undefined ? String(raw).trim() : '';
+  return value || undefined;
+}
+
+function resourceAttributes(version, env = process.env) {
+  const attrs = [
     { key: 'service.name', value: { stringValue: 'cli' } },
     { key: 'service.namespace', value: { stringValue: 'lorekit' } },
     { key: 'service.version', value: { stringValue: String(version) } },
     { key: 'process.runtime.name', value: { stringValue: 'nodejs' } },
     { key: 'process.runtime.version', value: { stringValue: process.versions.node } },
-    { key: 'os.type', value: { stringValue: process.platform } },
-    { key: 'host.arch', value: { stringValue: process.arch } },
+    { key: 'os.type', value: { stringValue: normalizeOsType(process.platform) } },
+    { key: 'host.arch', value: { stringValue: normalizeHostArch(process.arch) } },
   ];
+  const deploymentEnv = resolveDeploymentEnvironment(env);
+  if (deploymentEnv) attrs.push({ key: 'deployment.environment.name', value: { stringValue: deploymentEnv } });
+  return attrs;
 }
 
 // ── Payload builders (pure — unit-tested) ─────────────────────────────────────
@@ -322,7 +364,7 @@ function normalizeExitCode(result) {
  * counter point. Returns the command's exit code unchanged. Telemetry failures
  * are swallowed — the command result is never affected.
  *
- * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | scopes | diff | tree | lint | dedupe | migrate
+ * @param {string} command  bounded: install | uninstall | doctor | list | search | show | stats | scopes | diff | tree | lint | dedupe | link | migrate
  * @param {object} args     parsed CLI args (read for allow-listed flags only)
  * @param {string} version  CLI version (from package.json)
  * @param {() => Promise<number>} run  the command handler

package/src/tree.mjs

@@ -27,6 +27,8 @@ 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 { emitLink } from './link.mjs';
 import { log, heading, status, c } from './util.mjs';
 
 export async function tree(args) {
@@ -39,6 +41,17 @@ export async function tree(args) {
   // `--scope <s>` narrows to one (honored even outside the set — the user asked).
   const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeInfo.readOrder;
 
+  // `--link` short-circuits: print the Explorer deep link for the resolved
+  // context (the most-specific applicable scope, or `--scope`), no store reads.
+  if (args.link) {
+    const base = resolveAppBase({ base: args.base, env });
+    const scope =
+      args.scope && typeof args.scope === 'string' ? args.scope : mostSpecificScope(scopeInfo);
+    const params = {};
+    if (scope) params.scope = scope;
+    return emitLink({ params, base, json: args.json });
+  }
+
   const { local, remote, connection } = resolveStores(root, {
     env,
     endpoint: args.endpoint,