@mnemahq/cli 0.1.0 → 0.3.0

package/README.md

@@ -15,8 +15,15 @@ The package is `@mnemahq/cli`; the command it installs is **`mnema`**. (The unsc
 name `mnema` is blocked on npm — its typosquat filter rejects it as too close to the
 existing package `mem`.)
 
-You'll be asked for your **workspace id** and a **hook token** (both in *Settings → Developer*), and
-optionally an **API key** for search. `init` installs the capture hook, stores your secrets in the OS
+Run `mnema login` first and the workspace is filled in automatically. Otherwise you'll be asked
+for two values, which live on **two different settings pages**:
+
+| value | where |
+| --- | --- |
+| Workspace id | **Settings → Workspace** |
+| Hook token | **Settings → Access** → *Session capture* → **Generate token** |
+
+Optionally an **API key** for search. `init` installs the capture hook, stores your secrets in the OS
 keychain, and writes a `.mnema/config.json` (safe to commit — it holds no secrets).
 
 Start a Claude Code session and it appears under **Sessions** with its cost.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemahq/cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Mnema CLI — connect a repo to your Mnema workspace: install session capture, sweep past sessions, and search from the terminal.",
   "type": "module",
   "bin": {
@@ -29,9 +29,12 @@
   "devDependencies": {
     "vitest": "^3.2.7"
   },
+  "dependencies": {
+    "@mnemahq/sdk": "0.3.1"
+  },
   "scripts": {
     "build": "node -e \"process.exit(0)\"",
-    "typecheck": "node --check bin/mnema.mjs && node --check src/cli.mjs && node --check src/util.mjs && node --check src/secrets.mjs",
+    "typecheck": "node --check bin/mnema.mjs && node --check src/cli.mjs && node --check src/util.mjs && node --check src/secrets.mjs && node --check src/client.mjs && node --check src/read-commands.mjs",
     "test": "vitest run"
   }
 }

package/src/cli.mjs

@@ -11,9 +11,13 @@
  */
 
 import { existsSync } from 'node:fs';
-import { cmdLogin, cmdLogout } from './login.mjs';
+import { cmdLogin, cmdLogout, accessToken } from './login.mjs';
+import { makeClient, canAuthenticate, renderError } from './client.mjs';
 import {
-  DEFAULT_ORIGIN, c, gitInfo, canonicalRepo, readConfig, writeConfig, removeConfigDir,
+  cmdTasks, cmdNext, cmdDocs, cmdDoc, cmdProjects, cmdAsk, cmdGraph, cmdBriefing,
+} from './read-commands.mjs';
+import {
+  DEFAULT_ORIGIN, DEFAULT_APP_URL, c, gitInfo, canonicalRepo, readConfig, writeConfig, removeConfigDir,
   apiFetch, prompt, promptHidden, localSessionsForRepo,
 } from './util.mjs';
 import { getSecret, setSecret, deleteSecrets, backendName, usingFallback } from './secrets.mjs';
@@ -57,6 +61,32 @@ function fmtAge(mtimeMs) {
 
 // ── init ───────────────────────────────────────────────────────────────────────
 
+/**
+ * The workspace this login already belongs to.
+ *
+ * ⭐ THE CLI WAS ASKING FOR SOMETHING IT COULD LOOK UP. `init` prompted "Workspace
+ * id:" with no hint, and the id lives on a different settings page from the hook
+ * token — so the first thing a new user did was go hunting for a UUID the tool
+ * could have read from their own session. If they have run `mnema login`, /api/me
+ * answers it.
+ *
+ * Returns null on any failure. This is a convenience, never a requirement: not
+ * logged in, offline, or an unexpected body all fall through to the prompt.
+ */
+async function workspaceFromSession(origin) {
+  try {
+    if (!(await accessToken())) return null;
+    // Via the SDK: /api/public/v1/me returns camelCase, and the SDK is the only
+    // thing that should know that.
+    const me = await makeClient({ origin }).me();
+    if (!me?.workspaceId) return null;
+    console.log(c.green(`\u2713 Workspace: ${me.workspaceName || me.workspaceId} (from your login)`));
+    return me.workspaceId;
+  } catch {
+    return null;
+  }
+}
+
 async function cmdInit(flags) {
   const git = gitInfo();
   const root = git.root || process.cwd();
@@ -66,11 +96,24 @@ async function cmdInit(flags) {
   const existing = readConfig(root);
 
   let workspaceId = flags.workspace || process.env.MNEMA_WORKSPACE_ID || existing?.workspaceId;
-  if (!workspaceId) workspaceId = await prompt('Workspace id: ');
+  if (!workspaceId) workspaceId = await workspaceFromSession(origin);
+  if (!workspaceId) {
+    console.log(`  Workspace id — ${c.dim('Settings \u2192 Workspace')}  ${c.dim(`${DEFAULT_APP_URL}/app/settings/workspace`)}`);
+    console.log(`  ${c.dim('(or run `mnema login` first and this is filled in for you)')}`);
+    workspaceId = await prompt('Workspace id: ');
+  }
   if (!workspaceId) { console.error(c.red('A workspace id is required.')); process.exit(1); }
 
   let hookToken = process.env.MNEMA_HOOK_TOKEN || getSecret(workspaceId, 'hook-token');
-  if (!hookToken) hookToken = await promptHidden('Hook token (Settings → Developer): ');
+  if (!hookToken) {
+    // ⚠️ NOT "Settings → Developer". That page does not exist and never did in
+    // this shape — the hook token moved to the Access page when tokens were
+    // consolidated there, and the id lives on Workspace. The old prompt sent
+    // every new user looking for a page that was not in the app.
+    console.log(`  Hook token — ${c.dim('Settings \u2192 Access \u2192 "Session capture" \u2192 Generate token')}`);
+    console.log(`  ${c.dim(`${DEFAULT_APP_URL}/app/settings/access`)}`);
+    hookToken = await promptHidden('Hook token: ');
+  }
   if (!hookToken) { console.error(c.red('A hook token is required.')); process.exit(1); }
 
   let apiKey = process.env.MNEMA_API_KEY || getSecret(workspaceId, 'api-key') || '';
@@ -164,15 +207,24 @@ async function cmdSessions(flags) {
     console.log(`  ${s.sessionId.slice(0, 8)}…  ${fmtAge(s.mtimeMs).padStart(8)}  ${c.dim((s.sizeBytes / 1024).toFixed(0) + ' KB')}`);
   }
 
-  const apiKey = workspaceId ? getSecret(workspaceId, 'api-key') : null;
-  if (!apiKey) { console.log(c.dim('\n  (add an API key via `mnema init` to see server-side cost + status)')); return; }
+  if (!(await canAuthenticate(workspaceId))) {
+    console.log(c.dim('\n  (run `mnema login` — or add an API key — to see server-side cost + status)'));
+    return;
+  }
 
   const repo = canonicalRepo(git.remote);
-  const q = new URLSearchParams({ limit: String(limit) });
-  if (repo) q.set('repo', repo);
-  const r = await apiFetch(origin, `/api/public/v1/sessions?${q}`, { token: apiKey });
-  if (!r.ok) { console.log(c.yellow(`\n  server sessions unavailable (HTTP ${r.status})`)); return; }
-  const rows = r.json?.data?.sessions ?? [];
+  let rows = [];
+  try {
+    rows = await makeClient({ origin, workspaceId })
+      .sessions.list({ limit, ...(repo ? { repo } : {}) })
+      .all();
+  } catch (e) {
+    // Non-fatal by design: the LOCAL list above is the useful half and has
+    // already printed. Degrading here is deliberate, and it says which wall it
+    // hit rather than a bare HTTP number.
+    console.log(c.yellow(`\n  server sessions unavailable — ${e?.message ?? e}`));
+    return;
+  }
   console.log(c.bold(`\nServer sessions (${rows.length})`));
   for (const s of rows) {
     const cost = typeof s.totalCostUsd === 'number' ? `$${s.totalCostUsd.toFixed(4)}` : '$0';
@@ -201,12 +253,15 @@ async function cmdSearch(flags, rest) {
   const { origin, workspaceId } = resolveContext(flags);
   const query = rest.join(' ').trim();
   if (!query) { console.error(c.red('Usage: mnema search "<query>"')); process.exit(1); }
-  const apiKey = workspaceId ? getSecret(workspaceId, 'api-key') : (process.env.MNEMA_API_KEY || null);
-  if (!apiKey) { console.error(c.red('Search needs an API key. Run `mnema init` and provide one.')); process.exit(1); }
+  if (!(await canAuthenticate(workspaceId))) {
+    console.error(c.red('Search needs a credential — run `mnema login`, or `mnema init` with an API key.'));
+    process.exit(1);
+  }
 
-  const r = await apiFetch(origin, `/api/public/v1/docs/search?q=${encodeURIComponent(query)}`, { token: apiKey });
-  if (!r.ok) { console.error(c.red(`Search failed (HTTP ${r.status}): ${r.json?.error?.message || r.text || ''}`)); process.exit(1); }
-  const results = r.json?.data?.results ?? [];
+  let results = [];
+  try {
+    results = await makeClient({ origin, workspaceId }).docs.search(query);
+  } catch (e) { renderError(e, { context: 'search' }); }
   if (!results.length) { console.log(c.dim('No results.')); return; }
   console.log(c.bold(`${results.length} result(s) for "${query}"`));
   for (const d of results) {
@@ -221,12 +276,17 @@ async function cmdPull(flags) {
   const { git, root, origin, workspaceId } = resolveContext(flags);
   const repo = flags.repo || canonicalRepo(git.remote);
   if (!repo) { console.error(c.red('No git remote to identify this repo. Set one, or pass --repo <url>.')); process.exit(1); }
-  const apiKey = (workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY;
-  if (!apiKey) { console.error(c.red('`mnema pull` needs an API key. Run `mnema init` and provide one.')); process.exit(1); }
+  if (!(await canAuthenticate(workspaceId))) {
+    console.error(c.red('`mnema pull` needs a credential — run `mnema login`, or `mnema init` with an API key.'));
+    process.exit(1);
+  }
 
-  const r = await apiFetch(origin, `/api/public/v1/repo-context?repo=${encodeURIComponent(repo)}`, { token: apiKey });
-  if (!r.ok) { console.error(c.red(`Pull failed (HTTP ${r.status}): ${r.json?.error?.message || r.text || ''}`)); process.exit(1); }
-  const docs = r.json?.data?.context ?? [];
+  let docs = [];
+  try {
+    // `.context`, not the whole result — `.repo` is the URL the server matched.
+    // Reading the wrong one of these two is the bug this rewire found in the SDK.
+    docs = (await makeClient({ origin, workspaceId }).repos.context(repo)).context ?? [];
+  } catch (e) { renderError(e, { context: 'pull' }); }
 
   scaffold(root);
   const s = applyContext(root, docs);
@@ -268,7 +328,8 @@ async function cmdDoctor(flags) {
 
   const apiKey = workspaceId ? getSecret(workspaceId, 'api-key') : null;
   if (apiKey) {
-    let keyOk = false; try { keyOk = (await apiFetch(origin, '/api/public/v1/docs?limit=1', { token: apiKey })).ok; } catch { /* */ }
+    let keyOk = false;
+    try { await makeClient({ origin, workspaceId }).docs.list({ limit: 1 }).pages().next(); keyOk = true; } catch { /* */ }
     ok('API key valid', keyOk);
   } else {
     ok('API key stored', false, 'optional — needed for search/sessions');
@@ -319,10 +380,23 @@ Commands:
   doctor       Diagnose install, hooks, auth, connectivity
   uninstall    Remove hooks and stored secrets
 
+Read your workspace:
+  tasks        List tasks            [--status --project --limit]
+  next         The next task to pick up, with a ready-made branch name
+  docs         List documents        [--limit]
+  doc <id>     Print one document as markdown
+  projects     List projects
+  briefing     What deserves attention — pulse, deltas, findings
+
+Ask the knowledge graph (paid feature):
+  ask "q"      A cited answer, with the confidence it deserves
+  graph <a> [b]  Neighbourhood of a, or the shortest path from a to b
+
 Options:
   --workspace <id>   Workspace id (else prompted / MNEMA_WORKSPACE_ID)
   --origin <url>     API origin (default ${DEFAULT_ORIGIN})
-  --limit <n>        Row limit for sessions
+  --limit <n>        Row limit
+  --json             Machine-readable output (every read command)
   --yes              Non-interactive; skip optional prompts
   --purge            uninstall: also delete .mnema/config.json
   --version, --help
@@ -344,6 +418,17 @@ export async function run(argv) {
     case 'search':    return cmdSearch(flags, rest);
     case 'doctor':    return cmdDoctor(flags);
     case 'uninstall': return cmdUninstall(flags);
+
+    // Reads. Each resolves context once and hands the SDK client to a wrapper;
+    // none of them knows a URL or an envelope key (§A2, t-623).
+    case 'tasks':     return cmdTasks(flags, resolveContext(flags));
+    case 'next':      return cmdNext(flags, resolveContext(flags));
+    case 'docs':      return cmdDocs(flags, resolveContext(flags));
+    case 'doc':       return cmdDoc(flags, resolveContext(flags), rest);
+    case 'projects':  return cmdProjects(flags, resolveContext(flags));
+    case 'ask':       return cmdAsk(flags, resolveContext(flags), rest);
+    case 'graph':     return cmdGraph(flags, resolveContext(flags), rest);
+    case 'briefing':  return cmdBriefing(flags, resolveContext(flags));
     case undefined:
     case 'help':      return help();
     default:

package/src/client.mjs

@@ -0,0 +1,128 @@
+/**
+ * The one place the CLI talks to Mnema — through @mnemahq/sdk (§A2).
+ *
+ * ⭐ WHY THE RULE EXISTS, DEMONSTRATED THE HOUR IT WAS FOLLOWED. Rewiring the
+ * first command onto the SDK immediately turned up that `repos.context()` had
+ * been unwrapping the wrong envelope key since it shipped — it returned the repo
+ * URL string instead of the documents. The CLI's own raw fetch read the right key
+ * and had been right all along. An SDK its own CLI routes around has no first
+ * user, so its mistakes are found by everyone else instead.
+ *
+ * ⚠️ NOT EVERY REQUEST BELONGS HERE. `/install/mnema-hook.mjs` is a static asset,
+ * not an API call, and stays on plain fetch in hook-install.mjs. Routing it
+ * through a typed API client would imply an envelope and a credential that the
+ * endpoint neither sends nor wants.
+ */
+
+import { Mnema } from '@mnemahq/sdk';
+import { getSecret } from './secrets.mjs';
+import { accessToken } from './login.mjs';
+import { c, DEFAULT_APP_URL } from './util.mjs';
+
+/**
+ * A client carrying whichever credential this machine actually has.
+ *
+ * Order is deliberate: an API key is explicit, scoped, and what CI uses, so it
+ * wins. The OAuth token from `mnema login` is the human fallback. `getToken` is
+ * passed as a FUNCTION rather than a resolved string so the SDK re-reads it per
+ * request — that is what makes a refresh mid-command work instead of failing on
+ * a token that expired thirty seconds ago.
+ */
+export function makeClient({ origin, workspaceId }) {
+  const apiKey = (workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY || null;
+  return new Mnema(
+    apiKey
+      ? { apiKey, baseUrl: origin }
+      : { getToken: accessToken, baseUrl: origin },
+  );
+}
+
+/** True when an explicit API key is configured. Cheap; no network. */
+export function hasApiKey(workspaceId) {
+  return Boolean((workspaceId && getSecret(workspaceId, 'api-key')) || process.env.MNEMA_API_KEY);
+}
+
+/**
+ * True when this machine can authenticate AT ALL — by key or by login.
+ *
+ * ⭐ THE COMMANDS USED TO DEMAND A KEY, and that was a leftover from before the
+ * public API accepted both. `/api/public/v1` has taken an OAuth access token
+ * since the login flow shipped, so "Search needs an API key" was refusing work
+ * the server would happily have done for someone who had already run
+ * `mnema login`. Asking a person to go generate a credential they do not need is
+ * the kind of friction that makes a tool feel broken.
+ */
+export async function canAuthenticate(workspaceId) {
+  if (hasApiKey(workspaceId)) return true;
+  try { return Boolean(await accessToken()); } catch { return false; }
+}
+
+/**
+ * Turn a thrown SDK error into something a person can act on, and exit.
+ *
+ * ⭐ THIS IS THE POINT OF THE REWIRE, not a nicety. Every failure used to print
+ * `HTTP 402` and a raw body — which tells you a wall exists and nothing about
+ * which one. The hierarchy already knows: whether you need to log in, upgrade,
+ * top up, wait, or accept that this server does not have the feature at all.
+ * Four of those five have different fixes and the fifth cannot be fixed by
+ * paying.
+ *
+ * Errors are matched by NAME rather than instanceof: the CLI may load a
+ * different copy of @mnemahq/core than the SDK did (npm dedupes, pnpm does not
+ * always), and a cross-realm instanceof silently falls through to the generic
+ * branch — turning a good message back into a bad one for the exact reason this
+ * function exists.
+ */
+export function renderError(e, { context = '' } = {}) {
+  const name = e?.constructor?.name ?? '';
+  const where = context ? `${context}: ` : '';
+
+  switch (name) {
+    case 'AuthError':
+      console.error(c.red(`${where}not authenticated.`));
+      console.error(`  ${e.fix ?? 'Run `mnema login`.'}`);
+      break;
+
+    case 'PlanRequiredError':
+      console.error(c.yellow(`${where}your ${e.plan ?? 'current'} plan does not include ${e.feature ?? 'this'}.`));
+      console.error(`  Needs the ${e.required ?? 'a paid'} plan.`);
+      console.error(`  ${c.dim(e.upgradeUrl ?? `${DEFAULT_APP_URL}/app/settings/billing`)}`);
+      break;
+
+    case 'FeatureUnavailableError':
+      // No upgrade link here on purpose. There is nothing to buy: this server's
+      // build does not contain the feature, and pointing at billing would sell
+      // someone a plan that cannot change their binary.
+      console.error(c.yellow(`${where}${e.feature ?? 'that feature'} is not available on this server.`));
+      console.error(`  ${c.dim(`This is a ${e.edition ?? 'core'} build — the enterprise modules are not installed.`)}`);
+      break;
+
+    case 'InsufficientCreditError': {
+      const need = typeof e.topUpNeededCents === 'number' ? `$${(e.topUpNeededCents / 100).toFixed(2)}` : 'more credit';
+      console.error(c.yellow(`${where}not enough credit for ${e.action ?? 'this action'}.`));
+      console.error(`  Top up ${need}. ${c.dim(`${DEFAULT_APP_URL}/app/settings/wallet`)}`);
+      break;
+    }
+
+    case 'RateLimitError': {
+      const secs = typeof e.retryAfterMs === 'number' ? Math.ceil(e.retryAfterMs / 1000) : null;
+      console.error(c.yellow(`${where}rate limited${secs ? ` — retry in ${secs}s` : ''}.`));
+      break;
+    }
+
+    case 'ValidationError':
+      console.error(c.red(`${where}${e.message}`));
+      if (e.fields) for (const [f, msgs] of Object.entries(e.fields)) console.error(`  ${f}: ${[].concat(msgs).join(', ')}`);
+      break;
+
+    case 'NetworkError':
+      console.error(c.red(`${where}could not reach the server.`));
+      console.error(`  ${c.dim(e.message)}`);
+      break;
+
+    default:
+      console.error(c.red(`${where}${e?.message ?? String(e)}`));
+      if (e?.status) console.error(`  ${c.dim(`HTTP ${e.status}`)}`);
+  }
+  process.exit(1);
+}

package/src/keychain.mjs

@@ -181,8 +181,19 @@ export function deleteSecret(account) {
 }
 
 /** Where the CLI keeps non-secret login state (origin, workspace, expiry). */
+/**
+ * Where the CLI keeps non-secret login state.
+ *
+ * ⚠️ MNEMA_STATE_DIR EXISTS BECAUSE THE TEST SUITE ATE A REAL LOGIN. keychain's
+ * own test calls writeState({ origin: 'https://api.example', … }) to check the
+ * file round-trips — and with the path hard-wired to homedir() that wrote over
+ * the developer's actual ~/.mnema/auth.json. Running `pnpm test` silently
+ * repointed a working CLI at a fake host; the next command failed with
+ * `getaddrinfo api.example`, which reads like a network fault and is nothing of
+ * the kind. Tests must not be able to reach a real home directory.
+ */
 export function statePath() {
-  const dir = join(homedir(), '.mnema');
+  const dir = process.env.MNEMA_STATE_DIR || join(homedir(), '.mnema');
   mkdirSync(dir, { recursive: true });
   return join(dir, 'auth.json');
 }

package/src/read-commands.mjs

@@ -0,0 +1,196 @@
+/**
+ * The read commands — tasks, docs, projects, ask, graph, briefing (t-624).
+ *
+ * ⭐ EVERY ONE OF THESE IS A WRAPPER, NOT A CLIENT. They exist because t-623 put
+ * the CLI on @mnemahq/sdk; each is four lines of SDK call plus formatting, and
+ * none of them knows a URL, an envelope key or a header. That is the payoff §A2
+ * was arguing for: the surface grew without the transport growing with it.
+ *
+ * ⚠️ THE FORMATTING IS THE PART WITH JUDGEMENT IN IT, and two of these can lie by
+ * omission if it is done carelessly:
+ *
+ *   ask       the interpreter HEDGES below its confidence threshold. Printing the
+ *             sentence without the number turns a hedge into a claim, which is
+ *             worse than printing nothing.
+ *   briefing  a short list has three quite different causes and only one is good
+ *             news. On a core build six of seven finding families cannot produce
+ *             anything at all, and `coverage.notice` is the only thing that says so.
+ *
+ * --json everywhere: a CLI you cannot pipe is half a CLI, and the SDK already
+ * returns the shape worth emitting, so it costs one line each.
+ */
+
+import { makeClient, canAuthenticate, renderError } from './client.mjs';
+import { c } from './util.mjs';
+
+/** Machine output is the whole object; humans get the formatted view. */
+function emit(flags, value, render) {
+  if (flags.json) { console.log(JSON.stringify(value, null, 2)); return; }
+  render();
+}
+
+async function guard(workspaceId) {
+  if (await canAuthenticate(workspaceId)) return;
+  console.error(c.red('Not authenticated — run `mnema login`, or `mnema init` with an API key.'));
+  process.exit(1);
+}
+
+const trunc = (s, n) => (s && s.length > n ? `${s.slice(0, n - 1)}…` : (s ?? ''));
+
+// ── tasks ─────────────────────────────────────────────────────────────────────
+export async function cmdTasks(flags, ctx) {
+  await guard(ctx.workspaceId);
+  const limit = Number(flags.limit) || 20;
+  try {
+    const rows = await makeClient(ctx).tasks.list({
+      limit,
+      ...(flags.status ? { status: flags.status } : {}),
+      ...(flags.project ? { project: flags.project } : {}),
+    }).all();
+    emit(flags, rows, () => {
+      if (!rows.length) return console.log(c.dim('No tasks match.'));
+      console.log(c.bold(`${rows.length} task(s)`));
+      for (const t of rows) {
+        const id = (t.publicId || t.id.slice(0, 8)).padEnd(8);
+        console.log(`  ${c.cyan(id)} ${String(t.status).padEnd(12)} ${c.dim(String(t.priority).padEnd(8))} ${trunc(t.title, 70)}`);
+      }
+    });
+  } catch (e) { renderError(e, { context: 'tasks' }); }
+}
+
+export async function cmdNext(flags, ctx) {
+  await guard(ctx.workspaceId);
+  try {
+    const t = await makeClient(ctx).tasks.next();
+    emit(flags, t, () => {
+      if (!t) return console.log(c.dim('Nothing queued — the board is clear.'));
+      console.log(`${c.bold(t.publicId || t.id)}  ${t.title}`);
+      if (t.description) console.log(c.dim(trunc(t.description.replace(/\s+/g, ' '), 300)));
+      // The branch name is the load-bearing part of this project's dev loop, so
+      // the CLI hands it over ready to paste rather than making it be derived.
+      if (t.publicId) {
+        const slug = t.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40).replace(/-+$/g, '');
+        console.log(`\n  ${c.dim('branch:')} git checkout -b ${t.publicId}${slug ? `-${slug}` : ''}`);
+      }
+    });
+  } catch (e) { renderError(e, { context: 'next' }); }
+}
+
+// ── docs ──────────────────────────────────────────────────────────────────────
+export async function cmdDocs(flags, ctx) {
+  await guard(ctx.workspaceId);
+  const limit = Number(flags.limit) || 20;
+  try {
+    const rows = await makeClient(ctx).docs.list({ limit }).all();
+    emit(flags, rows, () => {
+      if (!rows.length) return console.log(c.dim('No docs.'));
+      console.log(c.bold(`${rows.length} doc(s)`));
+      for (const d of rows) {
+        console.log(`  ${c.dim(d.id.slice(0, 8))}  ${trunc(d.title, 60).padEnd(60)} ${c.dim(String(d.updatedAt).slice(0, 10))}`);
+      }
+    });
+  } catch (e) { renderError(e, { context: 'docs' }); }
+}
+
+export async function cmdDoc(flags, ctx, rest) {
+  await guard(ctx.workspaceId);
+  const id = rest[0];
+  if (!id) { console.error(c.red('Usage: mnema doc <id>')); process.exit(1); }
+  try {
+    const d = await makeClient(ctx).docs.get(id);
+    // Markdown goes to stdout unadorned so `mnema doc <id> > file.md` works and
+    // the heading is not silently baked into the file.
+    emit(flags, d, () => {
+      console.error(c.bold(d.title));
+      console.error(c.dim(`${d.path} · updated ${String(d.updatedAt).slice(0, 10)}`));
+      if (d.markdown) console.log(d.markdown);
+    });
+  } catch (e) { renderError(e, { context: 'doc' }); }
+}
+
+// ── projects ──────────────────────────────────────────────────────────────────
+export async function cmdProjects(flags, ctx) {
+  await guard(ctx.workspaceId);
+  try {
+    const rows = await makeClient(ctx).projects.list().all();
+    emit(flags, rows, () => {
+      if (!rows.length) return console.log(c.dim('No projects.'));
+      console.log(c.bold(`${rows.length} project(s)`));
+      for (const p of rows) console.log(`  ${c.dim(p.id.slice(0, 8))}  ${trunc(p.name, 50)}`);
+    });
+  } catch (e) { renderError(e, { context: 'projects' }); }
+}
+
+// ── graph: ask + traverse ─────────────────────────────────────────────────────
+export async function cmdAsk(flags, ctx, rest) {
+  await guard(ctx.workspaceId);
+  const q = rest.join(' ').trim();
+  if (!q) { console.error(c.red('Usage: mnema ask "<question>"')); process.exit(1); }
+  try {
+    const a = await makeClient(ctx).graph.ask(q, { ...(flags.budget ? { budgetMs: Number(flags.budget) } : {}) });
+    emit(flags, a, () => {
+      console.log(a.answer);
+      // ⚠️ NEVER WITHOUT THE CONFIDENCE. The interpreter deliberately hedges
+      // rather than asserts when the graph is thin; a terminal that prints only
+      // the sentence promotes a hedge to a fact.
+      const pct = Math.round((a.confidence ?? 0) * 100);
+      const why = a.confidenceReason ? ` (${a.confidenceReason})` : '';
+      const line = `confidence ${pct}%${why} · tier ${a.tier}${a.usedFallback ? ' · fallback' : ''}`;
+      console.log(pct >= 60 ? c.dim(`\n${line}`) : c.yellow(`\n${line} — treat as a lead, not a fact`));
+      if (a.sources?.length) {
+        console.log(c.dim(`\nsources (${a.sources.length}):`));
+        for (const s of a.sources.slice(0, 5)) console.log(c.dim(`  ${trunc(s.title, 70)}`));
+      }
+    });
+  } catch (e) { renderError(e, { context: 'ask' }); }
+}
+
+export async function cmdGraph(flags, ctx, rest) {
+  await guard(ctx.workspaceId);
+  const [from, to] = rest;
+  if (!from) { console.error(c.red('Usage: mnema graph <from> [to]')); process.exit(1); }
+  try {
+    const g = await makeClient(ctx).graph.traverse(from, to);
+    emit(flags, g, () => {
+      if (to) {
+        // connected:false is an ANSWER, not a failure — say so plainly rather
+        // than printing an empty list and letting it read as an error.
+        if (!g.connected) return console.log(c.yellow(`No route between "${from}" and "${to}".`));
+        console.log(c.bold(`${g.hopCount} hop(s) from "${from}" to "${to}"`));
+        for (const id of g.path) {
+          const n = g.nodes.find((x) => x.id === id);
+          console.log(`  ${n ? trunc(n.label, 60) : id}${n?.type ? c.dim(`  [${n.type}]`) : ''}`);
+        }
+        return;
+      }
+      console.log(c.bold(`${g.nodes.length} node(s), ${g.edges.length} edge(s) around "${from}"`));
+      for (const n of g.nodes.slice(0, 25)) console.log(`  ${trunc(n.label, 60).padEnd(60)} ${c.dim(n.type ?? '')}`);
+    });
+  } catch (e) { renderError(e, { context: 'graph' }); }
+}
+
+// ── briefing ──────────────────────────────────────────────────────────────────
+export async function cmdBriefing(flags, ctx) {
+  await guard(ctx.workspaceId);
+  try {
+    const b = await makeClient(ctx).findings.briefing();
+    emit(flags, b, () => {
+      const p = b.pulse;
+      console.log(c.bold('Pulse'));
+      console.log(`  ${p.activeProjects} active project(s) · ${p.problemsInActiveProjects} problem(s) · $${p.cost7dUsd} last 7d`);
+
+      // ⚠️ THE CAVEATS COME BEFORE THE LIST, on purpose. A short list has three
+      // causes and only one is good news; printing the findings first invites the
+      // reader to conclude "all clear" before reaching the reason it is short.
+      if (b.neverComputed) console.log(c.yellow('\n  The findings engine has never run for this workspace.'));
+      if (b.coverage?.degraded) console.log(c.yellow(`\n  ${b.coverage.notice}`));
+
+      console.log(c.bold(`\nFindings (${b.findings.length})`));
+      if (!b.findings.length) console.log(c.dim('  nothing surfaced'));
+      for (const f of b.findings) {
+        const count = f.grouped ? c.dim(` ×${f.count}`) : '';
+        console.log(`  ${c.dim(String(f.kind).padEnd(14))} ${trunc(f.headline, 90)}${count}`);
+      }
+    });
+  } catch (e) { renderError(e, { context: 'briefing' }); }
+}

package/src/util.mjs

@@ -18,6 +18,16 @@ import { createInterface } from 'node:readline';
 // capture hook uses.
 export const DEFAULT_ORIGIN = process.env.MNEMA_API_ORIGIN || 'https://api.theboringpeople.in';
 
+/**
+ * ⭐ THE APP, NOT THE API — a SEPARATE host, and the reason this constant exists.
+ * Everything the CLI asks a human to fetch lives in the web app at
+ * mnema.theboringpeople.in, while every request it makes goes to
+ * api.theboringpeople.in. Deriving one from the other is not possible, and
+ * printing the API origin in a "go here and copy this" message sends people to a
+ * host with no UI on it.
+ */
+export const DEFAULT_APP_URL = process.env.MNEMA_APP_URL || 'https://mnema.theboringpeople.in';
+
 export const c = {
   dim: (s) => `\x1b[2m${s}\x1b[0m`,
   green: (s) => `\x1b[32m${s}\x1b[0m`,