@lorekit/cli 1.20.1 → 1.22.0

package/README.md

@@ -224,13 +224,13 @@ stored by basename only) — so every scope is reconstructed verbatim. Lessons
 present in both tiers are counted once (project shadows home, the same merge
 `list` uses); archived lessons are excluded.
 
-**Remote enumeration is not possible, and `scopes` says so honestly.** The
-hosted MCP surface exposes no "list all scopes" tool — every read tool
-(`memory.list` / `memory.search` / `memory.read`) *requires* a scope — so a
-remote inventory can't be built. The Remote section is therefore always a short
-note (never a faked listing), degrading gracefully at exit 0, the same way
-`stats` omits a cap-usage figure. `--endpoint` / `--token` / `--store` behave as
-in `list`.
+**Remote enumeration is exact too.** `RemoteStore.listScopes()` calls
+`GET /memories/scopes`, which aggregates one `{ scope, count }` row per scope in
+Postgres (never a truncatable `select('scope')` plus a client-side dedupe), so
+the Remote section is a real inventory rendered through the same helpers as the
+Offline one. A denied, unconfigured, unreachable, or erroring remote degrades to
+a short, accurate note (network error / HTTP status — never a faked listing) at
+exit 0. `--endpoint` / `--token` / `--store` behave as in `list`.
 
 ### `lorekit diff`
 

package/bin/lorekit.mjs

@@ -348,9 +348,10 @@ is a full inventory — it surfaces scopes anywhere in the store, regardless of
 current directory.
 
 Offline counts are exact: each scope is read from the memory files' frontmatter,
-not reverse-mapped from the directory layout. The Remote section is always a
-short note: the hosted MCP surface has no "list all scopes" tool (every read tool
-requires a scope), so a remote inventory isn't possible — never an error (exit 0).
+not reverse-mapped from the directory layout. Remote counts are exact too — they
+come from \`GET /memories/scopes\`, which aggregates one row per scope server-side.
+A denied, unconfigured, or unreachable remote degrades to a short, accurate note
+rather than an error (exit 0).
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)

package/package.json

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

package/src/mcp.mjs

@@ -27,7 +27,11 @@ export function buildRemoteUrl(endpoint, token) {
 let idCounter = 0;
 
 // Returns { ok, httpStatus, result, error, networkError }.
-export async function mcpCall(endpoint, token, method, params = {}, { timeoutMs = 10000 } = {}) {
+//
+// `opts.traceparent` is an optional W3C traceparent header value (see
+// src/telemetry.mjs `getActiveTraceparent`); when present it is forwarded so
+// the server-side span joins the CLI's trace — same idiom as restFetch.
+export async function mcpCall(endpoint, token, method, params = {}, { timeoutMs = 10000, traceparent } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -40,6 +44,7 @@ export async function mcpCall(endpoint, token, method, params = {}, { timeoutMs
         'content-type': 'application/json',
         accept: 'application/json, text/event-stream',
         ...(token ? { authorization: `Bearer ${token}` } : {}),
+        ...(traceparent ? { traceparent } : {}),
       },
       body: JSON.stringify({ jsonrpc: '2.0', id: ++idCounter, method, params }),
       signal: controller.signal,
@@ -87,3 +92,69 @@ function parseBody(text) {
     return null;
   }
 }
+
+/**
+ * Derive the REST API base URL from an MCP endpoint URL.
+ * e.g. 'https://ref.supabase.co/functions/v1/mcp?token=...'
+ *   → 'https://ref.supabase.co/functions/v1'
+ */
+export function mcpToRestBase(mcpEndpointUrl) {
+  if (!mcpEndpointUrl) return null;
+  try {
+    const u = new URL(mcpEndpointUrl);
+    u.searchParams.delete('token');
+    // Strip /mcp suffix (with or without trailing slash)
+    const restPath = u.pathname.replace(/\/mcp\/?$/, '');
+    return `${u.origin}${restPath || '/'}`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Minimal REST fetch for LoreKit REST API endpoints.
+ * Returns { ok, httpStatus, data, error, networkError } — same shape as mcpCall.
+ *
+ * @param {string} baseUrl - REST base URL (from mcpToRestBase)
+ * @param {string} token   - Bearer token
+ * @param {string} path    - e.g. '/memories' or '/memories/search'
+ * @param {object} [opts]
+ * @param {string} [opts.method='GET']
+ * @param {object} [opts.body] - JSON body for POST/PATCH/DELETE
+ * @param {number} [opts.timeoutMs=10000]
+ * @param {string} [opts.traceparent] - W3C traceparent header value
+ */
+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}`;
+    const headers = {
+      accept: 'application/json',
+      ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+      ...(traceparent ? { traceparent } : {}),
+    };
+    const res = await fetch(url, {
+      method,
+      headers,
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { /* non-JSON body */ }
+    if (!res.ok) {
+      return {
+        ok: false,
+        httpStatus: res.status,
+        error: data?.error ? { message: data.error, code: data.code } : { code: res.status, message: text.slice(0, 200) || res.statusText },
+      };
+    }
+    return { ok: true, httpStatus: res.status, data };
+  } catch (e) {
+    return { ok: false, networkError: String(e?.message ?? e) };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/scopes.mjs

@@ -13,10 +13,12 @@
 // mapping the on-disk directory layout, which is lossy for `project::{name}`
 // (stored by basename only) — so every scope is reconstructed exactly.
 //
-// Remote enumeration is NOT possible: the hosted MCP surface exposes no "list
-// all scopes" tool — every read tool (memory.list / search / read) REQUIRES a
-// scope — so the Remote section is always an honest note (never faked), the same
-// way `stats` omits a cap-usage figure. It still degrades gracefully at exit 0.
+// Remote enumeration is EXACT too: `RemoteStore.listScopes()` calls
+// `GET /memories/scopes`, which aggregates one row per scope in Postgres (never
+// a truncatable `select('scope')` + client-side dedupe), so both sections are
+// real inventories rendered through the same pure helpers. A denied,
+// unconfigured, unreachable, or erroring remote still degrades to a short,
+// accurate note at exit 0 — never a throw.
 //
 // Graceful, read-only, human-facing (the bin wraps it in `traceCommand`).
 // `LOREKIT_DENY` suppresses a section; `--scope <s>` filters the inventory to
@@ -26,15 +28,9 @@ import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { summarizeScopeInventory, filterScopeInventory } from './lessons-view.mjs';
+import { summarizeScopeInventory, filterScopeInventory, describeError } from './lessons-view.mjs';
 import { log, heading, status, c } from './util.mjs';
 
-// The honest note the Remote section shows when it isn't denied/unconfigured:
-// the hosted MCP surface simply can't enumerate scopes. Exported so tests can
-// assert the exact wording rather than a fragile substring.
-export const REMOTE_SCOPES_UNSUPPORTED =
-  'remote scope enumeration is not supported by the hosted MCP surface (memory.list requires a scope)';
-
 export async function scopes(args) {
   const root = resolveProjectRoot(args.dir);
   const env = { ...process.env };
@@ -63,16 +59,21 @@ export async function scopes(args) {
     offlineSection = { available: true, ...summarizeScopeInventory(inventory) };
   }
 
-  // Remote: never enumerable. A deny note, an unconfigured note, or the honest
-  // "not supported" note — all graceful (exit 0). Order matches the other
-  // commands' precedence: deny first, then connectivity, then the capability.
+  // Remote: the hosted enumeration, via `GET /memories/scopes`. Precedence is
+  // unchanged from the other read commands — deny first, then connectivity, then
+  // the call itself. A failed call degrades to the same bounded, non-PII
+  // `describeError` note a failed `list()` gets (network error / HTTP status),
+  // never a throw and never a faked inventory.
   let remoteSection;
   if (remoteDenied) {
     remoteSection = { available: false, reason: `disabled by deny constraint (${remoteDenied.source})` };
   } else if (!remote.usable()) {
     remoteSection = { available: false, reason: remoteUnavailableReason(connection) };
   } else {
-    remoteSection = { available: false, reason: REMOTE_SCOPES_UNSUPPORTED };
+    const res = await remote.listScopes();
+    remoteSection = res.ok
+      ? { available: true, ...summarizeScopeInventory(filterScopeInventory(res.scopes, filter)) }
+      : { available: false, reason: describeError(res) };
   }
 
   if (args.json) {
@@ -89,15 +90,17 @@ export async function scopes(args) {
     log('');
   }
 
-  // Bounded, non-PII telemetry extras (counts + a boolean) — never a scope
-  // string, path, or token. `remote_available` is always false: the surface
-  // can't enumerate, and saying so is the honest signal.
+  // Bounded, non-PII telemetry extras (counts + booleans) — never a scope
+  // string, path, or token. `remote_available` now reflects whether the hosted
+  // enumeration actually answered; the remote counts mirror the offline pair.
   return {
     exitCode: 0,
     'lorekit.cli.scopes.offline_scope_count': offlineSection.available ? offlineSection.scopes.length : 0,
     'lorekit.cli.scopes.offline_total': offlineSection.available ? offlineSection.total : 0,
     'lorekit.cli.scopes.filtered': Boolean(filter),
-    'lorekit.cli.scopes.remote_available': false,
+    'lorekit.cli.scopes.remote_scope_count': remoteSection.available ? remoteSection.scopes.length : 0,
+    'lorekit.cli.scopes.remote_total': remoteSection.available ? remoteSection.total : 0,
+    'lorekit.cli.scopes.remote_available': remoteSection.available,
   };
 }
 

package/src/store/remote.mjs

@@ -1,25 +1,17 @@
-// Remote store: wraps the LoreKit MCP `memory.*` tools behind the common store
-// contract. Behaviour is identical to the previous direct `mcpCall` usage —
-// this only relocates it behind the interface. Zero-dependency.
-import { mcpCall } from '../mcp.mjs';
-
-// LoreKit returns tool output as { content: [{ type:'text', text:'<json>' }] }.
-function unwrap(result) {
-  if (!result) return null;
-  if (Array.isArray(result.content)) {
-    const text = result.content.map((c) => (c && c.text) || '').join('');
-    try {
-      return JSON.parse(text);
-    } catch {
-      return null;
-    }
-  }
-  return result;
-}
-
-// Drop undefined/null args so the JSON-RPC payload matches the old direct calls
-// (e.g. `memory.list` with only { scope, limit }).
-function clean(obj) {
+// Remote store: wraps the LoreKit REST API `memory.*` endpoints behind the
+// common store contract. EVERY memory operation goes over REST — list, search,
+// read, write, delete (soft-archive AND `?force=true` hard-delete) and the
+// store-wide `listScopes()` enumeration — for lower overhead and W3C
+// traceparent propagation. MCP remains ONLY for the four `org.*` calls and the
+// `ping` fallback: org RPCs require a Supabase JWT session (they resolve the
+// actor via auth.uid() inside SECURITY DEFINER functions), which is
+// incompatible with the lk_* api_key tokens that CLI users have.
+// Zero-dependency.
+import { mcpCall, restFetch, mcpToRestBase } from '../mcp.mjs';
+import { getActiveTraceparent } from '../telemetry.mjs';
+
+// Drop undefined/null args so JSON payloads stay tidy.
+function stripUndefined(obj) {
   const out = {};
   for (const [k, v] of Object.entries(obj || {})) if (v !== undefined && v !== null) out[k] = v;
   return out;
@@ -31,8 +23,9 @@ export function createRemoteStore({ endpoint, token } = {}) {
 
 class RemoteStore {
   constructor(endpoint, token) {
-    this.endpoint = endpoint;
+    this.endpoint = endpoint; // MCP URL (kept for org ops)
     this.token = token;
+    this.restBase = mcpToRestBase(endpoint); // REST base URL for memory ops
     this.mode = 'remote';
   }
 
@@ -40,89 +33,166 @@ class RemoteStore {
     return Boolean(this.endpoint && this.token && !String(this.endpoint).includes('<project-ref>'));
   }
 
-  async _call(name, args) {
+  _tp() { return getActiveTraceparent(); }
+
+  async _rest(path, opts = {}) {
+    if (!this.usable()) return { ok: false, unusable: true };
+    return restFetch(this.restBase, this.token, path, { ...opts, traceparent: this._tp() });
+  }
+
+  async _mcp(name, args) {
     if (!this.usable()) return { ok: false, unusable: true };
-    return mcpCall(this.endpoint, this.token, 'tools/call', { name, arguments: args });
+    return mcpCall(this.endpoint, this.token, 'tools/call', { name, arguments: args }, { traceparent: this._tp() });
   }
 
-  _entries(res) {
+  _mcpEntries(res) {
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
-    const payload = unwrap(res.result);
-    const entries = payload && Array.isArray(payload.entries) ? payload.entries : [];
-    return { ok: true, entries };
+    // MCP wraps results in { content: [{ type: 'text', text: '<json>' }] }
+    let payload = null;
+    if (Array.isArray(res.result?.content)) {
+      const text = res.result.content.map((c) => c?.text ?? '').join('');
+      try { payload = JSON.parse(text); } catch { /* ignore */ }
+    } else { payload = res.result; }
+    return { ok: true, entries: Array.isArray(payload?.entries) ? payload.entries : [] };
   }
 
+  // ── Memory operations → REST ──────────────────────────────────────────────
+
   async list({ scope, tags, limit } = {}) {
-    return this._entries(await this._call('memory.list', clean({ scope, tags, limit })));
+    const p = new URLSearchParams();
+    if (scope) p.set('scope', scope);
+    if (tags?.length) p.set('tags', Array.isArray(tags) ? tags.join(',') : tags);
+    if (limit) p.set('limit', String(limit));
+    const res = await this._rest(`/memories?${p}`);
+    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
+    return { ok: true, entries: res.data?.entries ?? [] };
   }
 
   async search({ q, scopes, tags } = {}) {
-    return this._entries(await this._call('memory.search', clean({ q, scopes, tags })));
+    const body = {};
+    if (q) body.q = q;
+    if (scopes?.length) body.scopes = scopes;
+    if (tags?.length) body.tags = tags;
+    const res = await this._rest('/memories/search', { method: 'POST', body });
+    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
+    return { ok: true, entries: res.data?.entries ?? [] };
   }
 
   async read({ scope, key } = {}) {
-    const res = await this._call('memory.read', { scope, key });
+    const p = new URLSearchParams();
+    if (scope) p.set('scope', scope);
+    if (key) p.set('key', key);
+    // scope+key is unique, so one row is all there can be — don't pull the default page of 50.
+    p.set('limit', '1');
+    const res = await this._rest(`/memories?${p}`);
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
-    const payload = unwrap(res.result);
-    return { ok: true, entry: payload && payload.entry ? payload.entry : payload };
+    const entries = res.data?.entries ?? [];
+    return { ok: true, entry: entries[0] ?? null };
   }
 
   async write(args = {}) {
-    const res = await this._call('memory.write', clean(args));
-    return { ok: res.ok, error: res.error, networkError: res.networkError, result: res.result };
+    const { scope, key, value, tags, source_agent, trigger, org, ttl_days, clear_ttl, created_at } = args;
+    const body = { scope, key, value };
+    if (tags !== undefined) body.tags = tags;
+    if (source_agent !== undefined) body.source_agent = source_agent;
+    if (trigger !== undefined) body.trigger = trigger;
+    if (org !== undefined) body.org = org;
+    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;
+    const res = await this._rest('/memories', { method: 'POST', body });
+    return { ok: res.ok, error: res.error, networkError: res.networkError };
   }
 
-  async delete({ scope, key, force } = {}) {
-    const res = await this._call('memory.delete', { scope, key, force: Boolean(force) });
+  // Natural-key DELETE. Without `force` the server soft-archives (stamps
+  // `archived_at`); `?force=true` hard-deletes the row outright — both forms of
+  // the same REST route (supabase/functions/memories/handlers/remove.ts).
+  async delete({ scope, key, force = false } = {}) {
+    const p = new URLSearchParams({ scope, key });
+    if (force) p.set('force', 'true');
+    const res = await this._rest(`/memories?${p}`, { method: 'DELETE' });
     return { ok: res.ok, error: res.error, networkError: res.networkError };
   }
 
   async archive({ scope, key } = {}) {
-    const res = await this._call('memory.archive', { scope, key });
-    return { ok: res.ok, error: res.error, networkError: res.networkError };
+    // Soft-archive = DELETE without force
+    return this.delete({ scope, key, force: false });
   }
 
-  // ── Org management ─────────────────────────────────────────────────────────
-  // These proxy to the hosted MCP endpoint's org.* tools. Auth is resolved
-  // server-side from the Bearer token; no user-id is passed by the caller.
+  // ── Org operations ─────────────────────────────────────────────────────────
+  // Org RPCs (lorekit_org_*) use auth.uid() server-side via SECURITY DEFINER
+  // functions, which only works with a Supabase JWT session. CLI uses lk_*
+  // api_key tokens which provide no JWT context, so the REST /orgs endpoint
+  // returns 403 for api_key callers. Org ops stay on the MCP endpoint which
+  // handles this correctly (the Deno edge function has its own auth path).
+  // TODO: if org RPCs ever gain api_key support, switch these to REST too.
 
   async orgCreate({ slug, name } = {}) {
-    const res = await this._call('org.create', clean({ slug, name }));
+    const res = await this._mcp('org.create', { slug, name });
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
-    const payload = unwrap(res.result);
+    let payload = null;
+    if (Array.isArray(res.result?.content)) {
+      try { payload = JSON.parse(res.result.content.map((c) => c?.text ?? '').join('')); } catch {}
+    } else { payload = res.result; }
     return { ok: true, org: payload };
   }
 
   async orgList() {
-    const res = await this._call('org.list', {});
-    return this._entries(res);
+    const res = await this._mcp('org.list', {});
+    return this._mcpEntries(res);
   }
 
   async orgRename({ slug, name } = {}) {
-    const res = await this._call('org.rename', clean({ slug, name }));
+    const res = await this._mcp('org.rename', { slug, name });
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
-    const payload = unwrap(res.result);
-    return { ok: true, ...payload };
+    let payload = null;
+    try { payload = Array.isArray(res.result?.content) ? JSON.parse(res.result.content.map((c) => c?.text ?? '').join('')) : res.result; } catch {}
+    return { ok: true, ...(payload ?? {}) };
   }
 
   async orgDelete({ slug } = {}) {
-    const res = await this._call('org.delete', clean({ slug }));
+    const res = await this._mcp('org.delete', { slug });
     if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
-    const payload = unwrap(res.result);
-    return { ok: true, ...payload };
-  }
-
-  // Store-wide scope enumeration is NOT possible against the hosted MCP surface:
-  // every read tool (memory.list / memory.search / memory.read) REQUIRES a
-  // scope, and there is no "list all scopes" tool. Signal that honestly so the
-  // `scopes` command shows a clear note rather than faking an inventory.
+    let payload = null;
+    try { payload = Array.isArray(res.result?.content) ? JSON.parse(res.result.content.map((c) => c?.text ?? '').join('')) : res.result; } catch {}
+    return { ok: true, ...(payload ?? {}) };
+  }
+
+  // Store-wide scope enumeration — every distinct scope the caller can see with
+  // its count of active (non-archived, non-expired) memories. `GET
+  // /memories/scopes` aggregates in Postgres, so the answer is exact at any size
+  // (see supabase/functions/memories/handlers/scopes.ts).
+  //
+  // The `scopes` array is the SAME `[{ scope, count }]` inventory shape
+  // `LocalStore.listScopes()` returns, so `scopes.mjs` feeds both through the
+  // same pure `filterScopeInventory`/`summarizeScopeInventory` helpers. Ordering
+  // is not relied upon (the server sorts by scope asc; the view re-sorts by
+  // scope type). Failures use this store's standard `{ ok:false, error,
+  // networkError }` envelope so the caller can degrade gracefully.
   async listScopes() {
-    return { ok: false, unsupported: true };
+    const res = await this._rest('/memories/scopes');
+    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError, unusable: res.unusable };
+    const scopes = Array.isArray(res.data?.scopes) ? res.data.scopes : [];
+    return { ok: true, scopes: scopes.map((s) => ({ scope: s.scope, count: Number(s.count) || 0 })) };
   }
 
   // Connectivity probe for doctor — a transport check, not a memory op.
   async ping() {
     if (!this.usable()) return { ok: false, unusable: true };
-    return mcpCall(this.endpoint, this.token, 'tools/list', {});
+    // Use the /health function as a connectivity probe (public, no auth)
+    const healthUrl = this.restBase
+      ? `${this.restBase.replace(/\/functions\/v1$/, '')}/functions/v1/health`
+      : null;
+    if (healthUrl) {
+      const tp = this._tp();
+      try {
+        const res = await fetch(healthUrl, {
+          signal: AbortSignal.timeout(5000),
+          ...(tp ? { headers: { traceparent: tp } } : {}),
+        });
+        return { ok: res.ok, httpStatus: res.status };
+      } catch (e) { return { ok: false, networkError: String(e?.message ?? e) }; }
+    }
+    return mcpCall(this.endpoint, this.token, 'tools/list', {}, { traceparent: this._tp() });
   }
 }

package/src/telemetry.mjs

@@ -40,6 +40,33 @@ const FLAG_ATTRS = ['global', 'project', 'deep', 'yes', 'force', 'no-hooks', 'js
 
 const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disable', 'disabled']);
 
+// ── Active trace context (for traceparent propagation to REST calls) ──────────
+// Set at the start of EVERY traced command run — including runs where export is
+// disabled. Context propagation is deliberately decoupled from export: a user
+// who opted out (or who simply has no OTLP endpoint configured) must still get
+// correlated server-side traces, they just don't contribute a CLI span.
+let _activeTraceId = null;
+let _activeSpanId = null;
+// Whether the current command's span will actually be exported. Drives the
+// W3C `sampled` bit only — never whether the header is sent.
+let _activeSampled = false;
+
+/**
+ * Get the W3C traceparent for the currently-running CLI command, or null when
+ * no command is running. Called by RemoteStore to inject the header into
+ * outgoing REST/MCP calls so the server span joins the CLI's trace.
+ *
+ * Flags are `01` when the CLI span is exported and `00` when it is not — the
+ * trace id is still carried either way, so the server can correlate. This
+ * mirrors `formatTraceparent` in `packages/mcp-core/src/trace-context.ts`
+ * (the CLI is zero-dep `.mjs` and cannot import the TS module); keep the two
+ * byte-consistent.
+ */
+export function getActiveTraceparent() {
+  if (!_activeTraceId || !_activeSpanId) return null;
+  return `00-${_activeTraceId}-${_activeSpanId}-${_activeSampled ? '01' : '00'}`;
+}
+
 // ── Config resolution ─────────────────────────────────────────────────────────
 
 /**
@@ -155,7 +182,7 @@ export function commandAttributes({ command, args = {}, outcome, exitCode, extra
   return attrs;
 }
 
-export function buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage }) {
+export function buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId }) {
   return {
     resourceSpans: [
       {
@@ -165,8 +192,8 @@ export function buildTracePayload({ version, name, attributes, startMs, endMs, s
             scope: { name: 'lorekit-cli', version: String(version) },
             spans: [
               {
-                traceId: randHex(16),
-                spanId: randHex(8),
+                traceId: traceId ?? randHex(16),
+                spanId: spanId ?? randHex(8),
                 name,
                 kind: 1, // INTERNAL
                 startTimeUnixNano: String(startMs * 1_000_000),
@@ -243,9 +270,9 @@ async function post(url, headers, payload, timeoutMs) {
  * can never delay or fail the CLI. Awaited before process exit (Node would
  * otherwise drop the in-flight request), but capped at timeoutMs.
  */
-export async function exportInvocation(config, { version, name, attributes, startMs, endMs, status, statusMessage }, { timeoutMs = 1500 } = {}) {
+export async function exportInvocation(config, { version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId }, { timeoutMs = 1500 } = {}) {
   if (!config || !config.enabled) return;
-  const trace = buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage });
+  const trace = buildTracePayload({ version, name, attributes, startMs, endMs, status, statusMessage, traceId, spanId });
   const metric = buildMetricsPayload({ version, attributes, startMs, endMs });
   await Promise.all([
     post(`${config.endpoint}/v1/traces`, config.headers, trace, timeoutMs),
@@ -297,13 +324,32 @@ export async function traceCommand(command, args, version, run) {
     config = { enabled: false };
   }
 
+  // Generate trace context BEFORE the export gate below, so outgoing REST/MCP
+  // calls can forward it as `traceparent` even when telemetry is disabled.
+  // Propagation is decoupled from export: a user with no OTLP endpoint (the
+  // common case — TELEMETRY_TOKEN is empty in git) still gets a single
+  // correlated server-side trace. The `sampled` bit is what reflects export.
+  // The same IDs are reused in exportInvocation() to link the CLI span to
+  // REST spans.
+  _activeTraceId = randHex(16);
+  _activeSpanId = randHex(8);
+  _activeSampled = Boolean(config.enabled);
+
   // Fast path: no export configured → run with zero telemetry overhead. Still
   // normalize the result to a numeric exit code: commands may resolve to an
   // { exitCode, ...extra } object (e.g. `doctor`), and only the instrumented
   // path below unwraps it. Returning `run()` raw would leak that object all the
   // way to `process.exit(obj)` in the bin entry → ERR_INVALID_ARG_TYPE crash
   // (exit 1) for every user without an OTLP endpoint configured.
-  if (!config.enabled) return normalizeExitCode(await run());
+  if (!config.enabled) {
+    try {
+      return normalizeExitCode(await run());
+    } finally {
+      _activeTraceId = null;
+      _activeSpanId = null;
+      _activeSampled = false;
+    }
+  }
 
   const startMs = Date.now();
   let exitCode = 0;
@@ -360,9 +406,15 @@ export async function traceCommand(command, args, version, run) {
         endMs: Date.now(),
         status,
         statusMessage,
+        traceId: _activeTraceId,
+        spanId: _activeSpanId,
       });
     } catch {
       // never let telemetry break the CLI
+    } finally {
+      _activeTraceId = null;
+      _activeSpanId = null;
+      _activeSampled = false;
     }
   }
 }