@modelstatus/cli 0.1.83 → 0.1.85

package/README.md

@@ -148,6 +148,25 @@ Apple-notarized, every release manifest is Ed25519-signed and verified — again
 a public key embedded in the installer and the self-updater, not fetched from the
 CDN — and both refuse to proceed if any check fails.
 
+### Verify a download yourself
+
+The installer already checks everything, but you can verify any binary
+independently with [minisign](https://jedisct1.github.io/minisign/) (Ed25519).
+Each binary ships a detached `.minisig` next to it on the CDN:
+
+```sh
+# e.g. Linux x64 (use latest/ or a pinned cli/v0.1.83/)
+curl -fLO https://cdn.llmstatus.ai/cli/latest/modelstatus-cli-linux-x64
+curl -fLO https://cdn.llmstatus.ai/cli/latest/modelstatus-cli-linux-x64.minisig
+minisign -Vm modelstatus-cli-linux-x64 \
+  -P RWQlKGcm5lXiIiTvGv/cdc0joBn1sm9vOFr9WqR6CI15PXzoHNHVBY6S
+# → "Signature and comment signature verified"
+```
+
+The public key is also committed at `packages/cli/release-minisign.pub`. (On
+macOS you additionally get the Developer ID signature + Apple notarization; on
+Linux/Windows the minisign signature is the independent check.)
+
 ## Links
 
 - Website: [llmstatus.ai](https://llmstatus.ai)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelstatus/cli",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "description": "Track which AI models you use, where, and never get surprised by a retirement. Free offline model-health for any repo (mm status), browser sign-in for cloud inventory + alerts.",
   "keywords": [
     "llm",

package/src/api.js

@@ -90,7 +90,7 @@ export function createClient({ apiBase, apiKey }) {
     listNotifications: (params) => req("GET", `/notifications${qs(params)}`),
     readNotification: (id) => req("POST", `/notifications/${id}/read`),
 
-    // billing
-    checkout: () => req("POST", "/billing/checkout"),
+    // billing — plan: undefined → Pro ($5/yr subscription); "lifetime" → $29 one-time
+    checkout: (plan) => req("POST", `/billing/checkout${plan ? `?plan=${encodeURIComponent(plan)}` : ""}`),
   };
 }

package/src/changelog-data.js

@@ -1,6 +1,28 @@
 /* GENERATED by scripts/gen-changelog.mjs from apps/web/lib/changelog.json — do not edit.
  * Release notes baked into the binary (in-TUI + the on-load what's-new card). */
 export const CHANGELOG = [
+  {
+    "version": "0.1.85",
+    "date": "2026-06-14",
+    "title": "Command polish + safer billing",
+    "items": [
+      "`mm upgrade --lifetime` starts the one-time Lifetime checkout from the CLI (plain `mm upgrade` is still the $5/yr Pro plan).",
+      "`mm <command> --help` now prints per-command usage and flags; an unknown command exits non-zero instead of silently printing the help.",
+      "`mm clear` requires an explicit `--yes`/`--force` — it will no longer wipe your cloud inventory on `--ci` alone. `mm logout` no longer claims it removed a key when you weren't signed in, and warns if an env-var key still authenticates you.",
+      "Billing safety: checkout won't start a duplicate charge for an account that's already on Pro or Lifetime."
+    ]
+  },
+  {
+    "version": "0.1.84",
+    "date": "2026-06-14",
+    "title": "Clearer mm status, faster scans, safer CI",
+    "items": [
+      "`mm status` now leads with a one-line verdict, orders models by what dies first, and shows a `≈ suggestion?` for ids written without their provider prefix — so a model the registry knows isn't just labelled \"unrecognized\".",
+      "Scans are ~9x faster on large trees, with a live file counter while they run; random config keys and generated tokens no longer get mistaken for model ids.",
+      "`mm ci --diff` no longer silently passes on a symlinked checkout — it was dropping every finding, hiding retiring models in changed files behind a green check.",
+      "`mm scan --dry-run` always previews (it never launches the uploader), `mm scan --json` always emits JSON, and running the dashboard without an interactive terminal prints a clear message instead of crashing."
+    ]
+  },
   {
     "version": "0.1.83",
     "date": "2026-06-14",

package/src/detect/core.js

@@ -50,11 +50,31 @@ function matchesAtBoundary(haystack, term) {
   }
 }
 
+/** Reject a generic match that carries a long, high-entropy alnum run — a config
+ * key / generated id / random token (e.g. "claude-config-8f4k2m9x7p3q",
+ * "qwen1ah0aqumtapuychbwd2maghkvcltn") rather than a real model id. A model id —
+ * even a brand-new one not yet in the registry — has short, separated, mostly
+ * pronounceable segments; a generated key has one long mixed-case/digit blob.
+ * Only applied to GENERIC matches (exact registry strings bypass looksLikeModel),
+ * so it can never drop a known model. Pure-alpha segments (davinci) and pure-digit
+ * snapshot dates (20250514) are never flagged — only MIXED long segments are. */
+function hasRandomSegment(s) {
+  for (const seg of s.split(/[-._/:]+/)) {
+    if (seg.length < 12) continue;
+    if (!/[a-z]/i.test(seg) || !/[0-9]/.test(seg)) continue; // need mixed letters+digits
+    const distinct = new Set(seg).size;
+    const vowels = (seg.match(/[aeiou]/gi) || []).length;
+    if (distinct / seg.length > 0.6 || vowels / seg.length < 0.18) return true;
+  }
+  return false;
+}
+
 /** Family globs catch brand-NEW versioned models before they're in the
  * registry, so a real hit virtually always carries a version digit. Requiring
- * one (and rejecting filename/domain tails) kills the bulk of false positives. */
+ * one (and rejecting filename/domain tails + random-key blobs) kills the bulk of
+ * false positives. */
 function looksLikeModel(s) {
-  return s.length >= 5 && /[0-9]/.test(s) && !BANNED_TAIL.test(s);
+  return s.length >= 5 && /[0-9]/.test(s) && !BANNED_TAIL.test(s) && !hasRandomSegment(s);
 }
 
 // Detection strings that are ALSO everyday code/English words. Cohere's bare
@@ -78,8 +98,20 @@ export function compilePatterns(patterns) {
     // (The old >=4 floor silently dropped the entire OpenAI o-series.)
     if (ms.match && ms.match.length >= 2 && !STOPWORDS.has(ms.match.toLowerCase())) exact.push(ms.match.toLowerCase());
   }
+  // Bucket the exact strings by their first 2 chars. detectInLine then runs the
+  // boundary matcher ONLY on buckets whose 2-char head appears in the line (a
+  // cheap indexOf prefilter). With 1500+ registry strings this is ~9x faster on a
+  // large tree and byte-identical: a string always contains its own first 2 chars,
+  // so a present string's bucket is never skipped. (~47 distinct heads today.)
+  const exactByHead = new Map();
+  for (const s of exact) {
+    const head = s.slice(0, 2);
+    let bucket = exactByHead.get(head);
+    if (!bucket) exactByHead.set(head, (bucket = []));
+    bucket.push(s);
+  }
   const generic = (patterns.generic_model_regexes || []).map((r) => new RegExp(r, "gi"));
-  return { exact, generic };
+  return { exact, exactByHead, generic };
 }
 
 /** Find model strings on a single line. Returns a Set of lowercased strings. */
@@ -89,7 +121,16 @@ export function detectInLine(line, compiled) {
   // Exact registry strings must match at a token boundary, not as a raw substring
   // — otherwise a short alias ("gpt-4") resolves inside a longer id ("gpt-4o-mini")
   // to the wrong model. Matches the server PR scanner's boundary semantics.
-  for (const s of compiled.exact) if (matchesAtBoundary(lower, s)) found.add(s);
+  // Use the 2-char-head bucket index when available (only scan buckets whose head
+  // appears in the line); fall back to the flat list for any older compiled shape.
+  if (compiled.exactByHead) {
+    for (const [head, bucket] of compiled.exactByHead) {
+      if (lower.indexOf(head) < 0) continue;
+      for (const s of bucket) if (matchesAtBoundary(lower, s)) found.add(s);
+    }
+  } else {
+    for (const s of compiled.exact) if (matchesAtBoundary(lower, s)) found.add(s);
+  }
   for (const re of compiled.generic) {
     re.lastIndex = 0;
     let m;

package/src/index.js

@@ -72,7 +72,7 @@ if (process.argv[2] === "__bench_frames") {
   const p = runGame({
     width: 80, height: 24, scanStore: scan,
     _inject: {
-      out, inp: input, proc: process, now,
+      out, inp: input, proc: process, now, noPersist: true, // bench: never write dkHighScore
       schedule: (fn, ms) => setTimeout(() => { const t = now(); if (prev != null) emit({ t: "frame", dtMs: t - prev }); prev = t; fn(); }, ms),
       cancel: (h) => clearTimeout(h),
     },
@@ -181,8 +181,14 @@ async function cmdSignup(_positional, flags) {
 }
 
 function cmdLogout() {
+  const had = !!loadConfig().apiKey;
   clearAuth();
-  console.log("✓ Signed out (API key removed). Run `mm login` to sign back in.");
+  if (had) console.log("✓ Signed out (saved API key removed). Run `mm login` to sign back in.");
+  else console.log("Not signed in — no saved API key to remove.");
+  // clearAuth only touches the config file; an env key still authenticates.
+  if (process.env.LLMSTATUS_API_KEY || process.env.MM_API_KEY) {
+    console.log("Note: an API key is still set via LLMSTATUS_API_KEY/MM_API_KEY — unset it to fully sign out.");
+  }
 }
 
 async function cmdUpgrade(_positional, flags) {
@@ -193,7 +199,9 @@ async function cmdUpgrade(_positional, flags) {
   }
   const client = createClient({ apiBase, apiKey });
   const { upgradeViaBrowser } = await import("./upgrade.js");
-  const plan = await upgradeViaBrowser({ client });
+  // --lifetime opens the one-time $29 checkout; default is the $5/yr Pro subscription.
+  const checkoutPlan = flags.lifetime ? "lifetime" : undefined;
+  const plan = await upgradeViaBrowser({ client, plan: checkoutPlan });
   if (!plan) {
     console.error("Upgrade not detected (timed out). Run `mm upgrade` again if you completed checkout.");
     process.exit(1);
@@ -244,10 +252,18 @@ async function cmdPlay(positional, flags) {
 }
 
 async function launchTui(initialView, flags) {
-  // Pass apiKey straight through (may be null). The TUI's Bootstrap wrapper
-  // renders an interactive SignIn screen when there's no key, then swaps to
-  // the main App on success — no separate browser-login polling phase that the
-  // user has to wait through without seeing anything interactive.
+  // The Ink TUI needs raw-mode stdin. Without a TTY (piped, redirected, CI logs)
+  // Ink throws an unhandled "Raw mode is not supported" deep in a passive effect
+  // — it escapes main()'s try/catch and dumps a React/runtime stack. Guard like
+  // `mm play` does and point at the non-interactive command instead.
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.error("The mm dashboard needs an interactive terminal (a TTY).");
+    console.error("For a non-interactive check, run: mm status [dir]  (add --json for scripts)");
+    process.exit(1);
+  }
+  // Pass apiKey straight through (may be null). The TUI lands on the public
+  // "Here" tab (no account needed); sign-in is lazy — the Account tab (press 7)
+  // or any auth-gated tab prompts when you get there.
   const { apiBase, apiKey } = resolveAuth(flags);
   const dir = path.resolve(flags.dir || ".");
   const { runApp } = await import("./tui/app.js");
@@ -257,13 +273,15 @@ async function launchTui(initialView, flags) {
 }
 
 async function cmdScan(positional, flags) {
-  const dir = path.resolve(positional[1] || ".");
+  const dir = path.resolve(positional[1] || flags.dir || ".");
   const { apiBase, apiKey } = resolveAuth(flags);
   if (!apiKey) {
     console.error("No API key. Run `mm login` or pass --key.");
     process.exit(1);
   }
-  const interactive = !flags.yes && !flags.json && process.stdout.isTTY;
+  // --dry-run must NOT launch the interactive TUI (which can upload) — it's a
+  // no-upload preview, so force the non-interactive path even on a TTY.
+  const interactive = !flags.yes && !flags.json && !flags["dry-run"] && process.stdout.isTTY;
   if (interactive) {
     const { runApp } = await import("./tui/app.js");
     await runApp({ apiBase, apiKey, dir, initialView: "scan" });
@@ -290,7 +308,19 @@ async function cmdScan(positional, flags) {
   const patterns = await client.detectionPatterns();
   const candidates = await collectFrom(sources, opts, patterns, explicit);
   if (candidates.length === 0) {
-    console.log("No model usage found.");
+    // Respect --json/--ci even on the empty path, so `mm scan --ci | jq` never
+    // chokes on a bare text line. Mirror the shape of the matching non-empty path.
+    if (flags.json) {
+      const srcRows = avail.map((a) => ({ id: a.id, available: a.available }));
+      console.log(JSON.stringify(
+        flags["dry-run"]
+          ? { scanned: 0, would_upload: [], sources: avail }
+          : { scanned: 0, uploaded: 0, sources: srcRows, created: 0, updated: 0, failed: 0 },
+        null, 2,
+      ));
+    } else {
+      console.log("No model usage found.");
+    }
     return;
   }
 
@@ -436,8 +466,18 @@ async function postCiRun(dir, flags, res, failOn) {
  * annotations + a step summary under GITHUB_ACTIONS; exits non-zero per --fail-on
  * so it gates merges. Offline (public registry) by default; --report syncs (Pro). */
 async function cmdCi(positional, flags) {
-  const dir = path.resolve(positional[1] || flags.dir || ".");
+  // realpathSync so `dir` matches git's `--show-toplevel` (which resolves
+  // symlinks). Without this, on a symlinked checkout (macOS /tmp, symlinked CI
+  // workspaces) the --diff path math mismatches and ALL findings are dropped →
+  // a silent GREEN check while retired models in changed files slip through.
+  let dir = path.resolve(positional[1] || flags.dir || ".");
+  try { dir = fs.realpathSync(dir); } catch { /* keep resolved path if it doesn't exist */ }
+  const VALID_FAIL_ON = new Set(["none", "deprecating", "retiring", "retired"]);
   const failOn = String(flags["fail-on"] || "retired").toLowerCase();
+  if (flags["fail-on"] !== undefined && !VALID_FAIL_ON.has(failOn)) {
+    console.error(`Invalid --fail-on "${flags["fail-on"]}". One of: ${[...VALID_FAIL_ON].join(", ")}.`);
+    process.exit(1);
+  }
   const { evaluateCi, annotationLines, summaryMarkdown, filterToChangedFiles, getChangedFiles, HEALTH_RANK } = await import("./ci.js");
   const res = await evaluateCi({
     dir,
@@ -522,9 +562,13 @@ async function cmdClear(_positional, flags) {
   }
   const all = !!flags.all;
   const scope = all ? "ALL usages, projects, alert rules + the in-app feed" : "ALL usages";
-  if (!flags.yes && !flags.force) {
+  // A destructive delete requires an EXPLICIT --yes/--force. `--ci` implies --yes
+  // for scan/fix non-interactivity, but it must NOT silently skip the safety
+  // prompt here — so check the raw argv, not the --ci-derived flags.yes.
+  const explicitConfirm = process.argv.includes("--yes") || process.argv.includes("--force");
+  if (!explicitConfirm) {
     if (!process.stdin.isTTY) {
-      console.error(`Refusing to delete ${scope} without confirmation. Re-run with --yes.`);
+      console.error(`Refusing to delete ${scope} without confirmation. Re-run with --yes (or --force).`);
       process.exit(1);
     }
     const ok = await confirm(`Delete ${scope} from your account? This cannot be undone. [y/N] `);
@@ -551,7 +595,8 @@ async function cmdFix(positional, flags) {
   const snapshot = await getRegistry({ offline: !!flags.offline, log: (m) => prog.log(m) });
 
   prog.update("scanning for model references…");
-  const candidates = await collectFrom(["filesystem"], { root: dir }, snapshot.detection);
+  const onProgress = ({ filesScanned, candidates: c }) => prog.update(`scanning… ${filesScanned} files, ${c} reference(s)`);
+  const candidates = await collectFrom(["filesystem"], { root: dir }, snapshot.detection, new Set(), onProgress);
   prog.stop();
   const resolved = resolveLocal(snapshot, [...new Set(candidates.map((c) => c.model_string))]);
   const byStr = new Map(resolved.map((r) => [r.input.toLowerCase(), r]));
@@ -697,11 +742,15 @@ async function cmdStatus(positional, flags) {
   // A cold `mm status` downloads the ~225 kB registry snapshot then walks the
   // repo with zero output — it reads as frozen. Show live stderr progress
   // (auto-off for --json / pipes so machine output stays byte-identical).
+  // A cold `mm status` downloads the registry snapshot then walks the repo with
+  // zero output — it reads as frozen. Show live stderr progress with a MOVING
+  // file counter (auto-off for --json / pipes so machine output is byte-identical).
   const prog = startProgress(!flags.json, "fetching the model registry…");
   const snapshot = await getRegistry({ offline: !!flags.offline, log: (m) => prog.log(m) });
 
   prog.update("scanning for model references…");
-  let candidates = await collectFrom(parseSources(flags), scanOpts(flags, dir), snapshot.detection, explicitSources(flags));
+  const onProgress = ({ filesScanned, candidates: c }) => prog.update(`scanning… ${filesScanned} files, ${c} reference(s)`);
+  let candidates = await collectFrom(parseSources(flags), scanOpts(flags, dir), snapshot.detection, explicitSources(flags), onProgress);
   prog.stop();
   const resolved = resolveLocal(snapshot, [...new Set(candidates.map((c) => c.model_string))]);
   const byStr = new Map(resolved.map((r) => [r.input.toLowerCase(), r]));
@@ -719,22 +768,36 @@ async function cmdStatus(positional, flags) {
       known.set(r.model_slug, e);
     } else custom.set(c.model_string, (custom.get(c.model_string) || 0) + 1);
   }
+  const fileCount = new Set(candidates.map((c) => c.source_path || c.location_label)).size;
 
   const today = new Date();
   const ICON = { ok: "🟢", deprecating: "🟡", retiring: "🟠", retired: "🔴", withdrawn: "⛔", custom: "⚪" };
-  const rank = { withdrawn: 0, retired: 0, retiring: 1, deprecating: 2, ok: 3 };
+  // Order by WHAT DIES FIRST: already-dead (retired/withdrawn) first, then aging
+  // by soonest retirement date regardless of bucket (a deprecating model that
+  // retires sooner outranks a retiring one that retires later), then ok last.
+  const tier = (h) => (h === "retired" || h === "withdrawn") ? 0 : h === "ok" ? 2 : 1;
   const rows = [...known.values()]
     .map(({ model, count }) => ({ model, count, health: computeHealth(model, 90, today) }))
-    .sort((a, b) => rank[a.health] - rank[b.health] || String(a.model.retires_date || "9999").localeCompare(String(b.model.retires_date || "9999")));
+    .sort((a, b) => tier(a.health) - tier(b.health) || String(a.model.retires_date || "9999").localeCompare(String(b.model.retires_date || "9999")));
   const attention = rows.filter((r) => r.health !== "ok");
+  const nBy = (h) => rows.filter((r) => r.health === h).length;
+  const nDead = nBy("retired") + nBy("withdrawn");
+  const nRetiring = nBy("retiring");
+  const nDeprecating = nBy("deprecating");
+
+  // Custom strings: surface the resolver's near-miss suggestion + sort by frequency.
+  const customList = [...custom.entries()]
+    .map(([name, places]) => ({ name, places, suggestion: byStr.get(name.toLowerCase())?.suggestion || null }))
+    .sort((a, b) => b.places - a.places || a.name.localeCompare(b.name));
 
   if (flags.json) {
     console.log(JSON.stringify({
       registry: { version: snapshot.version, generated_at: snapshot.generated_at, models: snapshot.models.length },
       scanned: dir,
       references: candidates.length,
+      files: fileCount,
       models: rows.map((r) => ({ slug: r.model.slug, display: r.model.display, health: r.health, retires_date: r.model.retires_date, replacement_slug: r.model.replacement_slug, places: r.count })),
-      custom: [...custom.entries()].map(([name, places]) => ({ name, places })),
+      custom: customList,
       needs_attention: attention.length,
     }, null, 2));
     return;
@@ -742,9 +805,21 @@ async function cmdStatus(positional, flags) {
 
   const ageDays = Math.round((today - new Date(snapshot.generated_at)) / 86_400_000);
   console.log(`LLM Status — registry ${snapshot.version} (${ageDays <= 0 ? "today" : ageDays + "d old"}), ${snapshot.models.length} models`);
-  console.log(`Scanned ${dir}: ${candidates.length} reference(s) → ${known.size} model(s), ${custom.size} custom\n`);
+  console.log(`Scanned ${dir}: ${candidates.length} reference(s) in ${fileCount} file(s) → ${known.size} model(s), ${custom.size} custom`);
+  // Lead with the verdict so the result reads at a glance.
+  if (attention.length) {
+    const parts = [];
+    if (nDead) parts.push(`${nDead} retired`);
+    if (nRetiring) parts.push(`${nRetiring} retiring soon`);
+    if (nDeprecating) parts.push(`${nDeprecating} deprecating`);
+    console.log(`${attention.length} of ${known.size} model(s) need attention: ${parts.join(" · ")}`);
+  } else if (rows.length) {
+    console.log(`All ${known.size} model(s) you use are current.`);
+  }
+  console.log("");
+
   if (!rows.length && !custom.size) {
-    console.log("No model usage found here. Try `mm status <dir>`, or `mm scan` to map a whole project.");
+    console.log("No model usage found here. Point `mm status` at a repo, or run `mm scan` to map a whole project.");
     return;
   }
   if (rows.length) {
@@ -755,15 +830,23 @@ async function cmdStatus(positional, flags) {
       console.log(`  ${ICON[r.health]} ${r.health.padEnd(11)} ${r.model.slug.padEnd(32)} ${tail.padEnd(20)}${repl}  (${r.count})`);
     }
   }
-  if (custom.size) {
+  if (customList.length) {
     console.log("\nCustom / unrecognized:");
-    for (const [name, places] of custom) console.log(`  ⚪ ${name}  (${places})`);
+    const CAP = 12;
+    for (const c of customList.slice(0, CAP)) {
+      const hint = c.suggestion ? `   ≈ ${c.suggestion}?` : "";
+      console.log(`  ⚪ ${c.name}  (${c.places})${hint}`);
+    }
+    if (customList.length > CAP) console.log(`  … +${customList.length - CAP} more  (mm status --json for the full list)`);
   }
+  // Functional next steps only (no marketing voice): `mm fix` when something's
+  // auto-rewritable; the alerts pointer only when not signed in.
   if (attention.length) {
-    console.log(`\n⚠ ${attention.length} model(s) need attention before they retire.`);
-    console.log("  Get alerted automatically (email/Slack/SMS): `mm login` then `mm upgrade` — scanning is free, alerting is the paid feature.");
-  } else if (rows.length) {
-    console.log("\n✓ Everything you use is current.");
+    const fixable = attention.filter((r) => r.model.replacement_slug).length;
+    const tips = [];
+    if (fixable) tips.push(`\`mm fix\` rewrites the ${fixable} with a known replacement`);
+    if (!loadConfig().apiKey) tips.push("`mm login` to get alerted before these dates (Pro)");
+    if (tips.length) console.log("\n" + tips.map((t) => "→ " + t).join("\n"));
   }
 }
 
@@ -779,14 +862,15 @@ Usage:
   mm scan [dir]            Scan for model usage; interactive TUI, or --ci/--json for pipelines
   mm fix [dir]             Rewrite dying model ids to their replacement, in place (--dry-run previews; --model <slug> limits; --yes skips the confirm)
   mm ci [dir]              CI gate: fail the build on deprecated/retiring models (GitHub annotations)
-                          (--diff <base> limits findings to files changed vs base; auto on PRs via GITHUB_BASE_REF)
+                          (--fail-on <none|deprecating|retiring|retired> sets the threshold, default retired;
+                           --json-out <file> writes findings JSON; --diff <base> limits to changed files, auto on PRs)
   mm sources               List detection sources and whether each can run here
   mm integrations          Manage live integrations (list | enable <id> | disable <id> | env <id> <tag>)
   mm clear                 Delete all tracked usages from your inventory (--all also wipes projects/rules; --yes to skip the prompt)
   mm update                Update to the latest version now and relaunch (or add --update to any command)
-  mm upgrade               Open Stripe checkout and poll until Pro is active (the paid plan, not the binary)
+  mm upgrade               Open Stripe checkout and poll until active (--lifetime for the one-time plan; this is the paid plan, not the binary)
   mm play [dir]            Play Donkey Kong while a background scan walks the dir (just for fun)
-  mm tui                   Force-launch the TUI (logs you in first if needed)
+  mm tui                   Force-launch the TUI (needs an interactive terminal)
 
 Scan sources (--sources; default = filesystem + enabled integrations; "all" for everything):
   filesystem  repo files          aws-secrets  AWS Secrets Manager + SSM
@@ -798,11 +882,87 @@ Scan sources (--sources; default = filesystem + enabled integrations; "all" for
   Secret sources shell out to your already-authenticated CLIs, run read-only,
   and only ever upload model ids — secret VALUES never leave your machine.
 
-Flags: --update · --api <url> · --key <key> · --project <id|name> · --yes · --json · --ci · --dry-run
+Flags: --update · --api <url> · --key <key> · --project <id|name> · --dir <path> · --yes · --json · --ci · --dry-run
+       --offline (use the cached registry) · --model <slug> (fix) · --fail-on <t> · --json-out <file> (ci) · --all · --force (clear)
        --sources <list> · --region <r> · --namespace <ns> · --kube-context <c> · --db <dsn> · --sql-table <t>
        --vercel-project <p> · --vercel-team <t> · --gh-repo <owner/name> · --supabase-ref <ref>
 
-Get started: \`mm login\` (opens your browser).`;
+Get started: \`mm login\` (opens your browser).
+
+Per-command help: \`mm <command> --help\` (e.g. \`mm ci --help\`).`;
+
+/** Per-command usage. `mm <cmd> --help` / `mm help <cmd>` prints these; anything
+ * not listed falls back to the global HELP. Keep flags here in sync with parseArgs. */
+const COMMAND_HELP = {
+  status: `mm status [dir]   Offline, account-less model-health check (free).
+
+  Pulls the signed registry, scans the dir locally, prints each model in use with
+  its health + replacement, then the custom/unrecognized ids. Always exits 0 (it
+  informs; use \`mm ci\` to gate a build).
+
+  --json            machine-readable {registry, scanned, references, files, models[], custom[], needs_attention}
+  --offline         use the cached registry only (no network)
+  --sources <list>  detection sources (default: filesystem + enabled integrations; "all" for everything)
+  --dir <path>      directory to scan (alternative to the positional arg)`,
+  fix: `mm fix [dir]   Rewrite dying model ids to their registry replacement, in place.
+
+  Boundary-safe, style-preserving, chain-resolved. Only filesystem refs with a known
+  replacement are touched. Asks before writing (a non-TTY needs --yes).
+
+  --dry-run         preview the rewrites, write nothing
+  --json            machine output ({planned, dryRun} for --dry-run; {applied, stale, failed} on apply)
+  --yes             skip the confirmation prompt
+  --model <slug>    only fix this one model (full provider/slug)
+  --offline         use the cached registry only`,
+  ci: `mm ci [dir]   CI gate: fail the build on deprecated/retiring models.
+
+  Exits non-zero when a finding is at/above --fail-on. Emits GitHub annotations +
+  a step summary under GITHUB_ACTIONS. Offline-capable, no account.
+
+  --fail-on <none|deprecating|retiring|retired>   threshold (default: retired)
+  --json            print the full report to stdout
+  --json-out <file> write clean findings JSON to a file (stdout stays annotations-only)
+  --diff <base>     limit findings to files changed vs base (auto on PRs via GITHUB_BASE_REF)
+  --report          (Pro) sync this run's usages + a CI-run row to your account
+  --offline         use the cached registry only`,
+  scan: `mm scan [dir]   Scan for model usage and upload to your account's inventory (needs login).
+
+  On a TTY with no flags it opens the interactive Scan tab. --ci/--json/--yes run
+  non-interactively.
+
+  --dry-run         show exactly what WOULD upload, upload nothing
+  --json / --ci     machine output (--ci implies --yes + --json)
+  --yes             upload without the interactive TUI
+  --project <id|name>  route everything to one project (created if the name is new)
+  --sources <list>  detection sources ("all" for everything)
+  --dir <path>      directory to scan`,
+  clear: `mm clear   Delete tracked usages from your cloud inventory (DESTRUCTIVE, needs login).
+
+  Requires an explicit --yes or --force (it will NOT proceed on --ci alone).
+
+  --all             also wipe projects, alert rules + the in-app feed (a full reset)
+  --yes / --force   confirm the delete (required on a non-TTY)
+  --json            print the result counts`,
+  upgrade: `mm upgrade   Open Stripe checkout and poll until your plan is active (needs login).
+
+  --lifetime        buy the one-time Lifetime plan ($29) instead of Pro ($5/yr)`,
+  integrations: `mm integrations [list | enable <id> | disable <id> | env <id> <tag>]
+
+  Manage the local on/off state of the live integrations (the gate for what
+  \`mm scan\`/\`mm status\` run by default). Ids: aws-lambda, vercel, supabase-edge,
+  github-actions. \`env <id> <prod|staging|dev|unknown>\` sets a declared env.
+
+  --json            (list only) machine-readable integration state`,
+  config: `mm config [analytics on|off]   View or change local settings.
+
+  Bare \`mm config\` lists settings (analytics, update channel, config path).
+  \`mm config analytics on|off\` toggles anonymous usage analytics (also honored:
+  MM_NO_ANALYTICS=1, DO_NOT_TRACK=1, CI=1).`,
+  login: `mm login [api_key]   Sign in. With no key, opens the browser and polls; or paste a key.
+
+  --key <key>       paste an API key directly
+  --api <url>       override the API base`,
+};
 
 /** Awaits the updater promise; prints a one-liner if an update completed. Never throws. */
 async function maybePrintUpdate(promise) {
@@ -859,8 +1019,10 @@ async function main() {
 
   // --help / -h / help: print usage + exit. MUST come before the no-arg → TUI
   // fallthrough below (a bare `mm` launches the TUI, but `mm --help` must not).
+  // `mm <cmd> --help` and `mm help <cmd>` print per-command usage when we have it.
   if (cmd === "help" || flags.help || flags.h) {
-    console.log(HELP);
+    const topic = cmd === "help" ? positional[1] : cmd;
+    console.log((topic && COMMAND_HELP[topic]) || HELP);
     return;
   }
 
@@ -934,8 +1096,13 @@ async function main() {
       flags.dir = cmd;
       await launchTui(positional[1], flags);
     }
-    else if (cmd === "help" || flags.help) console.log(HELP);
-    else console.log(HELP);
+    else {
+      // Unknown command / non-existent path: name it on stderr + exit non-zero so
+      // a typo in a script fails loudly instead of silently printing help.
+      console.error(`Unknown command or path: ${cmd}\n`);
+      console.log(HELP);
+      process.exit(1);
+    }
   } catch (e) {
     console.error(`Error: ${e?.message ?? e}`);
     await maybePrintUpdate(updatePromise);

package/src/registry/local.js

@@ -21,10 +21,22 @@ export function resolveLocal(snapshot, strings) {
       const model = bySlug.get(slug) || null;
       return { input: s, model_slug: slug, display: model?.display ?? s, model, confidence: 1, suggestion: null };
     }
-    // No exact hit — find the nearest known id (longest two-way substring overlap).
-    let near = null;
+    // No exact hit — find the nearest known id. Prefer (1) a key the input is a
+    // PREFIX of (input = base id, key = a versioned form, e.g. "gpt-3" →
+    // "gpt-3.5-turbo"), taking the SHORTEST such (closest minor version); else
+    // (2) the longest known id the input CONTAINS (input is a longer variant);
+    // else (3) the longest known id that contains the input. Tiering avoids
+    // latching onto a long dated/ARN variant (the old longest-overlap rule
+    // suggested e.g. an Amazon Bedrock ARN slug for a bare "claude-sonnet-4").
+    let near = null, bestScore = -1, bestTie = -Infinity;
     for (const k of keys) {
-      if (k.length >= 4 && (k.includes(n) || n.includes(k)) && (!near || k.length > near.length)) near = k;
+      if (k.length < 4) continue;
+      let score, tie;
+      if (k.startsWith(n)) { score = 3; tie = -k.length; }      // versioned form of the base — shortest wins
+      else if (n.includes(k)) { score = 2; tie = k.length; }    // input is a longer variant of a known id
+      else if (k.includes(n)) { score = 1; tie = -k.length; }   // input embedded in a longer id — weakest
+      else continue;
+      if (score > bestScore || (score === bestScore && tie > bestTie)) { near = k; bestScore = score; bestTie = tie; }
     }
     const suggestion = near ? exact.get(near) || null : null;
     return { input: s, model_slug: null, display: s, model: null, confidence: suggestion ? 0.6 : 0, suggestion };

package/src/sources/index.js

@@ -94,7 +94,7 @@ export async function availability(sourceIds, opts = {}, explicit = new Set()) {
  * the cheap path: uses available() (PATH check), never authState() (spawn).
  * `explicit` is the set of ids the caller named verbatim — naming a live
  * integration there overrides the enabled-gate. */
-export async function collectFrom(sourceIds, opts, patterns, explicit = new Set()) {
+export async function collectFrom(sourceIds, opts, patterns, explicit = new Set(), onProgress = null) {
   const compiled = compilePatterns(patterns);
   const ids = sourceIds && sourceIds.length ? sourceIds : ["filesystem"];
   const seen = new Set();
@@ -108,7 +108,9 @@ export async function collectFrom(sourceIds, opts, patterns, explicit = new Set(
     // Fold the per-source declared envTag into opts.env so the integration's env
     // overrides guessEnvFrom — but an explicit --env flag (opts.env) still wins,
     // and Vercel's authoritative deploy target still wins inside its own collect.
-    const srcOpts = src.integration ? { ...opts, env: opts.env || getEnvTag(id) } : opts;
+    // onProgress (optional) lets a caller render a live file counter — only the
+    // filesystem source emits progress; the rest ignore the extra opt.
+    const srcOpts = src.integration ? { ...opts, env: opts.env || getEnvTag(id), onProgress } : { ...opts, onProgress };
     for (const c of await src.collect(srcOpts, compiled)) {
       const key = `${c.model_string}|${c.location_label}`;
       if (seen.has(key)) continue;

package/src/tui/game/loop.js

@@ -139,7 +139,9 @@ export function runGame({ width, height, level = 1, scanStore = null, onExit, in
       if (highSaved) return;
       highSaved = true;
       const score = (game && Math.max(game.best || 0, game.score || 0)) || 0;
-      if (score > best) {
+      // _inject.noPersist (the __bench_frames seam) keeps a measurement run from
+      // writing dkHighScore to the user's config.
+      if (score > best && !_inject.noPersist) {
         try { setConfigValue("dkHighScore", score); best = score; } catch { /* best effort */ }
       }
     }

package/src/upgrade.js

@@ -4,8 +4,8 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 /** Open Stripe checkout and poll /me until the plan flips off "free". Mirrors
  * the browser-login poll UX. Returns the new plan, or null on timeout. */
-export async function upgradeViaBrowser({ client, log = console.error, onTick }) {
-  const { url } = await client.checkout();
+export async function upgradeViaBrowser({ client, plan, log = console.error, onTick }) {
+  const { url } = await client.checkout(plan);
   if (!url) throw new Error("Could not start checkout.");
   log(`\n  Opening checkout in your browser…`);
   log(`  If it doesn't open, visit:\n    ${url}\n`);