@lorekit/cli 1.25.0 → 1.26.0

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-server.mjs

@@ -28,6 +28,7 @@ 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';
 
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_INFO = { name: 'lorekit-local', version: '1.0.0' };
@@ -55,6 +56,27 @@ export const MEMORY_TOOL_DEFS = [
           description:
             'Optional ISO 8601 creation date for migrating a pre-existing memory. Rejected if invalid or in the future. Applies only when the memory is first created.',
         },
+        origin_repo: {
+          type: 'string',
+          description:
+            'Provenance: the owner/name of the repository this memory was recorded from. Derived from the working directory when omitted.',
+        },
+        origin_branch: {
+          type: 'string',
+          description:
+            'Provenance: the git branch this memory was recorded from. Derived from the working directory when omitted.',
+        },
+        origin_commit: {
+          type: 'string',
+          description:
+            'Provenance: the commit SHA checked out when this memory was recorded. Derived from the working directory when omitted.',
+        },
+        origin_pr: {
+          type: 'integer',
+          minimum: 1,
+          description:
+            'Provenance: the pull request number this memory came out of. Pass it when you know it — the server can only infer it from CI environment variables.',
+        },
       },
     },
   },
@@ -148,10 +170,15 @@ export const ORG_TOOL_DEFS = [
 // Legacy alias kept so existing code that imports TOOL_DEFS still compiles.
 export const TOOL_DEFS = [...MEMORY_TOOL_DEFS, ...ORG_TOOL_DEFS];
 
-// tool name → (store, args) → store result. The store destructures the args it
-// needs, so the raw `arguments` object is passed straight through.
+// tool name → (store, args, ctx) → store result. The store destructures the
+// args it needs, so the raw `arguments` object is passed straight through.
+// `ctx.root` is the resolved project root (`--dir`), NOT the process cwd — an
+// MCP client launched from elsewhere would otherwise stamp the wrong origin.
 const MEMORY_DISPATCH = {
-  'memory.write': (store, a) => store.write(a),
+  // An agent calling memory.write knows the lesson, not the working directory
+  // it is running in. Fill in whatever provenance the environment can supply,
+  // with anything the caller DID pass taking precedence.
+  'memory.write': (store, a, ctx) => store.write({ ...a, ...withDerivedOrigin(a, ctx) }),
   'memory.read': (store, a) => store.read(a),
   'memory.list': (store, a) => store.list(a),
   'memory.search': (store, a) => store.search(a),
@@ -159,6 +186,22 @@ const MEMORY_DISPATCH = {
   'memory.archive': (store, a) => store.archive(a),
 };
 
+// Provenance for a tool call: the caller's explicit values win, the working
+// directory and CI environment fill the rest. Best-effort — a failure to shell
+// out to git must never fail the write, so it degrades to no origin at all.
+function withDerivedOrigin(args = {}, { root } = {}) {
+  try {
+    return mergeOrigin(deriveOrigin({ cwd: root }), {
+      origin_repo: args.origin_repo ?? null,
+      origin_branch: args.origin_branch ?? null,
+      origin_commit: args.origin_commit ?? null,
+      origin_pr: args.origin_pr ?? null,
+    });
+  } catch {
+    return {};
+  }
+}
+
 // org.* dispatch — always routed to the remote store.
 const ORG_DISPATCH = {
   'org.create': (remote, a) => remote.orgCreate(a),
@@ -188,7 +231,7 @@ function toolResult(id, payload) {
 
 // Build the per-message handler over a resolved control model. `store` is null
 // when mode is `off`. Org tools are always advertised regardless of mode.
-export function createHandler(control) {
+export function createHandler(control, { root = process.cwd() } = {}) {
   const store = createStore(control);
   const memoryTools = store ? MEMORY_TOOL_DEFS : [];
 
@@ -257,7 +300,7 @@ export function createHandler(control) {
       const fn = MEMORY_DISPATCH[name];
       if (!fn) return errorReply(id, -32601, `Unknown tool: ${name}`);
 
-      const result = await fn(store, args);
+      const result = await fn(store, args, { root });
       return toolResult(id, result);
     }
 
@@ -359,7 +402,7 @@ export async function mcpServer(
 ) {
   const root = resolveProjectRoot(args.dir);
   const control = loadControl(root, { env: withOverrides(args, env) });
-  const handle = createHandler(control);
+  const handle = createHandler(control, { root });
   // A human who runs `lorekit mcp` in a terminal would otherwise see a silent
   // hang with no sign it is alive. Reassure them on stderr — but only when
   // stdin is a TTY, so a piped MCP client never sees the banner on either channel.

package/src/origin.mjs

@@ -0,0 +1,186 @@
+// Derive a memory's ORIGIN — where a lesson is being recorded FROM — from the
+// git working directory and the ambient CI environment.
+//
+// This is the counterpart to `scope.mjs`'s `deriveScope()`. A scope says where
+// a lesson APPLIES; an origin says where it was written: the repository, the
+// branch, the checked-out commit, and the pull request the work belonged to.
+// The dashboard renders it as a "recorded from" block with links straight back
+// to the PR, branch, and commit (migration 00048).
+//
+// Nothing here is required: every field independently degrades to `null` when
+// it cannot be determined (no git, detached HEAD, no PR context), and a write
+// with no origin at all behaves exactly as it did before this existed.
+//
+// Zero-dependency, and deliberately injectable (`{ cwd, env, run }`) so the
+// whole derivation is testable without a real repository or a real CI runner.
+import { execFileSync } from 'node:child_process';
+import { ownerRepoFromRemote } from './scope.mjs';
+
+function gitRunner(args, cwd) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      encoding: 'utf8',
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract a pull request number from the ambient environment.
+ *
+ * Precedence, first match wins:
+ *   1. LOREKIT_PR              — the explicit escape hatch, any CI or none.
+ *   2. GITHUB_REF              — `refs/pull/<n>/merge` on a GitHub Actions
+ *                                `pull_request` run.
+ *   3. GITHUB_PR_NUMBER        — set by several popular actions.
+ *
+ * Returns a positive integer, or `null` when no PR context is present.
+ */
+export function prNumberFromEnv(env = process.env) {
+  const explicit = toPositiveInt(env.LOREKIT_PR);
+  if (explicit !== null) return explicit;
+
+  const ref = typeof env.GITHUB_REF === 'string' ? env.GITHUB_REF : '';
+  const m = /^refs\/pull\/(\d+)\//.exec(ref);
+  if (m) {
+    const n = toPositiveInt(m[1]);
+    if (n !== null) return n;
+  }
+
+  return toPositiveInt(env.GITHUB_PR_NUMBER);
+}
+
+function toPositiveInt(raw) {
+  if (raw === undefined || raw === null || raw === '') return null;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) return null;
+  return n;
+}
+
+/**
+ * Whether a string is a usable git ref name, per git-check-ref-format.
+ *
+ * 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
+ * is the zero-dependency CLI copy, kept behaviourally identical so a branch the
+ * CLI derives is never one the server would reject.
+ */
+export function isValidRef(value) {
+  if (typeof value !== 'string' || value === '') return false;
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u001f\u007f ~^:?*[\\]/.test(value)) return false;
+  if (value.startsWith('/') || value.endsWith('/')) return false;
+  if (value.startsWith('.') || value.endsWith('.')) return false;
+  if (value.endsWith('.lock')) return false;
+  if (value.includes('..') || value.includes('//') || value.includes('@{')) return false;
+  return value.length <= 255;
+}
+
+function firstNonEmpty(...values) {
+  for (const v of values) {
+    if (typeof v === 'string' && v.trim() !== '') return v.trim();
+  }
+  return null;
+}
+
+/**
+ * Derive `{ origin_repo, origin_branch, origin_commit, origin_pr }` for the
+ * current working directory.
+ *
+ * Branch resolution prefers `GITHUB_HEAD_REF` over `git rev-parse`: on a
+ * GitHub Actions `pull_request` run the checkout is a detached merge commit,
+ * so git reports `HEAD` while `GITHUB_HEAD_REF` holds the real source branch.
+ *
+ * The branch is NOT lowercased (unlike a `branch::` scope) so the GitHub
+ * `/tree/` link the dashboard builds from it resolves for a mixed-case branch.
+ *
+ * @returns an object whose four fields are each a value or `null`.
+ */
+export function deriveOrigin({ cwd = process.cwd(), env = process.env, run = gitRunner } = {}) {
+  const remote = run(['config', '--get', 'remote.origin.url'], cwd);
+  const gitBranch = run(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+
+  // On a GitHub Actions `pull_request` run the checkout is a DETACHED MERGE
+  // COMMIT of the head branch into the base, so `HEAD` (and `GITHUB_SHA`) name
+  // a commit that exists on neither branch. Since the branch below deliberately
+  // reports `GITHUB_HEAD_REF` — the real source branch — taking the merge SHA
+  // here would have the two fields describe different refs.
+  //
+  // The head commit is the merge commit's SECOND parent. A shallow checkout
+  // (actions/checkout's default `fetch-depth: 1`) does not have it, in which
+  // case we record NO commit: an absent field is honest, a mismatched one is
+  // worse than nothing.
+  const onMergeCheckout = Boolean(firstNonEmpty(env.GITHUB_HEAD_REF));
+  const gitCommit = onMergeCheckout
+    ? run(['rev-parse', 'HEAD^2'], cwd)
+    : run(['rev-parse', 'HEAD'], cwd);
+
+  // Precedence matches every other field: the explicit `LOREKIT_*` override
+  // first, then what the environment can work out. `LOREKIT_REPO` losing to the
+  // git remote would make it the one override that does not override.
+  //
+  // Each candidate goes through `isValidRepo` individually rather than only the
+  // winner, so an odd remote FALLS THROUGH to `GITHUB_REPOSITORY` instead of
+  // shadowing it with a value the server's strict `parseOriginRepo` rejects —
+  // which would 400 the write this provenance only decorates.
+  const repo =
+    isValidRepo(env.LOREKIT_REPO) ??
+    isValidRepo(ownerRepoFromRemote(remote)) ??
+    isValidRepo(env.GITHUB_REPOSITORY);
+  const branchRaw = firstNonEmpty(env.LOREKIT_BRANCH, env.GITHUB_HEAD_REF, gitBranch);
+  // A derived branch that the server would reject is dropped here rather than
+  // sent: provenance is decoration, and it must never fail the write it is
+  // decorating.
+  const branch = branchRaw && branchRaw !== 'HEAD' && isValidRef(branchRaw) ? branchRaw : null;
+  // GITHUB_SHA is only a safe fallback OFF a merge checkout — on one it is the
+  // merge commit, the very value the branch above exists to avoid.
+  const commitRaw = onMergeCheckout
+    ? firstNonEmpty(env.LOREKIT_COMMIT, gitCommit)
+    : firstNonEmpty(env.LOREKIT_COMMIT, gitCommit, env.GITHUB_SHA);
+  const commit = commitRaw && /^[0-9a-fA-F]{7,40}$/.test(commitRaw) ? commitRaw.toLowerCase() : null;
+
+  return {
+    origin_repo: repo,
+    origin_branch: branch,
+    origin_commit: commit,
+    origin_pr: prNumberFromEnv(env),
+  };
+}
+
+/**
+ * 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
+ * rejection of a dots-only segment, which `[\\w.-]+` alone admits and which
+ * would render as a link to a different repository.
+ */
+export function isValidRepo(value) {
+  if (typeof value !== 'string') return null;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === '' || normalized.length > 140) return null;
+  if (!/^[\w.-]+\/[\w.-]+$/.test(normalized)) return null;
+  if (normalized.split('/').some((segment) => /^\.+$/.test(segment))) return null;
+  return normalized;
+}
+
+/**
+ * Merge a derived origin under caller-supplied overrides, dropping null fields.
+ *
+ * An explicitly supplied value always wins; a field neither supplied nor
+ * derivable is omitted entirely rather than sent as `null`, so the server's
+ * "keep the last KNOWN origin" upsert rule never erases a previously recorded
+ * value.
+ */
+export function mergeOrigin(derived = {}, overrides = {}) {
+  const out = {};
+  for (const field of ['origin_repo', 'origin_branch', 'origin_commit', 'origin_pr']) {
+    const value = overrides[field] ?? derived[field] ?? null;
+    if (value !== null && value !== undefined && value !== '') out[field] = value;
+  }
+  return out;
+}

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/store/format.mjs

@@ -17,6 +17,13 @@ export const FIELDS = [
   'created',
   'updated',
   'archived_at',
+  // Provenance — where the lesson was recorded FROM (see src/origin.mjs).
+  // Appended, never reordered: parseEntry is tolerant, so a file written before
+  // these existed simply decodes them as absent.
+  'origin_repo',
+  'origin_branch',
+  'origin_commit',
+  'origin_pr',
 ];
 
 // Serialize an entry ({ ...columns, value }) into file text.

package/src/store/local.mjs

@@ -91,7 +91,10 @@ class LocalStore {
   // existing key (a creation date never moves). Returns { ok:false, error } on
   // an invalid or future-dated value rather than throwing, matching the store
   // contract's error surfacing.
-  async write({ scope, key, value, tags, source_agent, trigger, created_at } = {}) {
+  async write({
+    scope, key, value, tags, source_agent, trigger, created_at,
+    origin_repo, origin_branch, origin_commit, origin_pr,
+  } = {}) {
     let override;
     try {
       override = normalizeCreatedAt(created_at);
@@ -109,6 +112,13 @@ class LocalStore {
       tags: Array.isArray(tags) ? tags : [],
       source_agent: source_agent || null,
       trigger: trigger || null,
+      // Provenance keeps the last KNOWN value per field, mirroring the hosted
+      // memory_write upsert: a write that does not know a field must not erase
+      // what a previous write recorded.
+      origin_repo: origin_repo ?? existing?.entry.origin_repo ?? null,
+      origin_branch: origin_branch ?? existing?.entry.origin_branch ?? null,
+      origin_commit: origin_commit ?? existing?.entry.origin_commit ?? null,
+      origin_pr: origin_pr ?? existing?.entry.origin_pr ?? null,
       created,
       updated: existing ? now : override || now,
       archived_at: null,
@@ -135,6 +145,10 @@ class LocalStore {
       tags: Array.isArray(entry.tags) ? entry.tags : [],
       source_agent: entry.source_agent ?? null,
       trigger: entry.trigger ?? null,
+      origin_repo: entry.origin_repo ?? null,
+      origin_branch: entry.origin_branch ?? null,
+      origin_commit: entry.origin_commit ?? null,
+      origin_pr: entry.origin_pr ?? null,
       created: entry.created ?? now,
       updated: entry.updated ?? now,
       archived_at: entry.archived_at ?? null,

package/src/store/remote.mjs

@@ -91,7 +91,10 @@ class RemoteStore {
   }
 
   async write(args = {}) {
-    const { scope, key, value, tags, source_agent, trigger, org, ttl_days, clear_ttl, created_at } = args;
+    const {
+      scope, key, value, tags, source_agent, trigger, org, ttl_days, clear_ttl, created_at,
+      origin_repo, origin_branch, origin_commit, origin_pr,
+    } = args;
     const body = { scope, key, value };
     if (tags !== undefined) body.tags = tags;
     if (source_agent !== undefined) body.source_agent = source_agent;
@@ -100,6 +103,13 @@ class RemoteStore {
     if (ttl_days !== undefined) body.ttl_days = ttl_days;
     if (clear_ttl !== undefined) body.clear_ttl = clear_ttl;
     if (created_at !== undefined) body.created_at = created_at;
+    // Provenance — only sent when known. Omitting a field leaves whatever the
+    // row already recorded intact (the RPC coalesces), which is what makes a
+    // write from a machine with no git context non-destructive.
+    if (origin_repo !== undefined) body.origin_repo = origin_repo;
+    if (origin_branch !== undefined) body.origin_branch = origin_branch;
+    if (origin_commit !== undefined) body.origin_commit = origin_commit;
+    if (origin_pr !== undefined) body.origin_pr = origin_pr;
     const res = await this._rest('/memories', { method: 'POST', body });
     return { ok: res.ok, error: res.error, networkError: res.networkError };
   }

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']);
 
@@ -364,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,