@modelstatus/cli 0.1.58 → 0.1.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelstatus/cli",
-  "version": "0.1.58",
+  "version": "0.1.60",
   "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/tui/app.js

@@ -281,7 +281,7 @@ export function App({ apiBase, apiKey, dir, initialView, onSignedIn, fresh }) {
     h(Text, {}, ""),
     toast ? h(Text, { color: toast.color }, ` ${toast.msg}`) : h(Text, {}, ""),
     h(StatusBar, { segsLeft, segsRight, width: W }),
-    h(KeyBar, { keys: keys.some((k) => k.k === "P") ? keys : [...keys, { k: "P", label: "play" }], width: W }),
+    h(KeyBar, { keys: keys.some((k) => k.k === "P") ? keys : [...keys, { k: "P", label: "play 🦍" }], width: W }),
   );
 }
 

package/src/tui/ui.js

@@ -159,8 +159,12 @@ export function relativeTime(retiresDate, today = new Date()) {
 /** env → { text, color }. */
 export function envTag(env) {
   const e = String(env || "");
-  const color = e === "prod" ? C.ACCENT : e === "staging" ? "#a78bfa" : C.FG_FAINT;
-  return { text: e, color };
+  // Fit the 5-char env column without mid-word chops ("unknown" → "unkno").
+  // Unknown renders BLANK: it's the default, not information — only a real env
+  // should draw the eye.
+  const SHORT = { unknown: "", production: "prod", staging: "stage", development: "dev" };
+  const color = e === "prod" || e === "production" ? C.ACCENT : e === "staging" ? "#a78bfa" : C.FG_FAINT;
+  return { text: SHORT[e] ?? e, color };
 }
 
 // ===========================================================================
@@ -360,9 +364,16 @@ export function KeyBar({ keys, width }) {
 // ===========================================================================
 
 /** kind ∈ loading|scanning|done|error → leading glyph + colored text, one row. */
-export function StateLine({ kind, text, spin }) {
+export function StateLine({ kind, text, spin, hint }) {
+  // `hint` = dim recovery affordance appended after an error ("g retries") so a
+  // failure line always says how to get unstuck, in one consistent style.
   if (kind === "done") return h(Text, {}, h(Text, { color: "#16a34a" }, ` ${GLYPH.check} `), h(Text, { color: C.FG_DIM }, text));
-  if (kind === "error") return h(Text, {}, h(Text, { color: "#dc2626" }, ` ${GLYPH.cross} `), h(Text, { color: "#dc2626" }, text));
+  if (kind === "error")
+    return h(Text, {},
+      h(Text, { color: "#dc2626" }, ` ${GLYPH.cross} `),
+      h(Text, { color: "#dc2626" }, text),
+      hint ? h(Text, { color: C.FG_DIM }, `  ·  ${hint}`) : null,
+    );
   // loading / scanning
   return h(Text, {}, h(Text, { color: C.ACCENT }, ` ${spin ?? SPINNER[0]} `), h(Text, { color: C.FG_DIM }, text));
 }

package/src/tui/views/account.js

@@ -28,7 +28,10 @@ export function AccountView({ client, me, refreshMe, apiBase, ui, active }) {
   React.useEffect(() => ui?.reportStatus?.({ context: `plan: ${me?.plan ?? "…"}` }), [me, ui]);
 
   async function upgrade() {
-    if (me?.plan && me.plan !== "free") return ui.showToast(`already on ${me.plan}`, "yellow");
+    // Without a loaded account a checkout would just fire at an unreachable
+    // endpoint and die with a raw fetch error — say what to do instead.
+    if (!me?.plan) return ui.showToast("account not loaded — press g to refresh first", "yellow");
+    if (me.plan !== "free") return ui.showToast(`already on ${me.plan}`, "yellow");
     setStatus("Starting checkout…");
     try {
       const { url } = await client.checkout();
@@ -52,7 +55,7 @@ export function AccountView({ client, me, refreshMe, apiBase, ui, active }) {
       };
       setTimeout(tick, 4000);
     } catch (e) {
-      setStatus(e.status === 503 ? "Billing isn't configured on this server." : e.message);
+      setStatus(e.status === 503 ? "Billing isn't configured on this server." : `checkout failed: ${e.message} — press u to retry.`);
     }
   }
 
@@ -67,11 +70,16 @@ export function AccountView({ client, me, refreshMe, apiBase, ui, active }) {
 
   const plan = me?.plan ?? "…";
   const isFree = plan === "free";
+  // An UNLOADED account is not Pro — never show the PRO badge (or the thank-you
+  // line below) until /me actually resolves; offline must read as offline.
+  const unknown = me?.plan == null;
   const endpoint = apiBase || cfg.apiBase || "https://llmstatus.ai";
 
-  const badge = isFree
-    ? h(Text, { color: C.FG_FAINT }, " free ")
-    : h(Text, { backgroundColor: BG_ON ? "#16a34a" : undefined, color: C.ACCENT_INK, bold: true }, " PRO ");
+  const badge = unknown
+    ? h(Text, { color: C.FG_FAINT }, " … ")
+    : isFree
+      ? h(Text, { color: C.FG_FAINT }, " free ")
+      : h(Text, { backgroundColor: BG_ON ? "#16a34a" : undefined, color: C.ACCENT_INK, bold: true }, " PRO ");
 
   return h(
     Box,
@@ -90,17 +98,19 @@ export function AccountView({ client, me, refreshMe, apiBase, ui, active }) {
       h(Row, { label: "retiring", value: `${me?.retiring_window_days ?? 90} day window` }),
       h(Row, { label: "endpoint", value: endpoint }),
       h(Row, { label: "key", value: keyPrefix }),
-      h(Text, { color: C.FG_FAINT }, `config: ${configFilePath}`),
+      h(Row, { label: "config", value: configFilePath, color: C.FG_FAINT }),
     ),
     h(Text, {}, ""),
-    isFree
-      ? h(
-          Box,
-          { flexDirection: "column" },
-          h(Text, { color: "#d97706" }, `Free plan · up to ${FREE_LIMITS.projects} project, ${FREE_LIMITS.usages} usages, email+in-app alerts.`),
-          h(Text, { color: C.FG_DIM }, "Press u to upgrade to Pro ($5/yr): unlimited usages + Slack/Discord/SMS/webhook alerts."),
-        )
-      : h(Text, { color: "#16a34a" }, `${GLYPH.check} Pro features unlocked. Thanks for supporting LLM Status!`),
+    unknown
+      ? h(Text, {}, h(Text, { color: "#dc2626" }, `${GLYPH.cross} couldn't load account`), h(Text, { color: C.FG_DIM }, "  ·  g retries"))
+      : isFree
+        ? h(
+            Box,
+            { flexDirection: "column" },
+            h(Text, { color: "#d97706" }, `Free plan · up to ${FREE_LIMITS.projects} project, ${FREE_LIMITS.usages} usages, email+in-app alerts.`),
+            h(Text, { color: C.FG_DIM }, "Press u to upgrade to Pro ($5/yr): unlimited usages + Slack/Discord/SMS/webhook alerts."),
+          )
+        : h(Text, { color: "#16a34a" }, `${GLYPH.check} Pro features unlocked. Thanks for supporting LLM Status!`),
     status ? h(Text, { color: C.ACCENT, marginTop: 1 }, status) : null,
   );
 }

package/src/tui/views/add.js

@@ -2,7 +2,9 @@ import React from "react";
 import { Box, Text, useInput } from "ink";
 import { h, C, GLYPH, useAsync, clampCursor } from "../ui.js";
 
-const ENV_ORDER = ["prod", "staging", "dev", "unknown"];
+// No "unknown" here: on a MANUAL add the user knows the env — the unknown
+// bucket is something the scanner infers, never a deliberate choice.
+const ENV_ORDER = ["prod", "staging", "dev"];
 
 export const meta = {
   keys: [
@@ -67,9 +69,12 @@ export function AddView({ client, ui, active }) {
     (input, key) => {
       if (!active || busy) return;
       if (input === "m") return ui.askPrompt("Model string", { initial: modelStr, onSubmit: setModel });
-      if (input === "p") return setProjectIdx((i) => (projects.length ? (i + 1) % projects.length : 0));
+      // With no projects loaded (offline / failed fetch), p retries the fetch
+      // instead of being a silent no-op.
+      if (input === "p") return projects.length ? setProjectIdx((i) => (i + 1) % projects.length) : projQ.reload();
       if (input === "e") return setEnvIdx((i) => (i + 1) % ENV_ORDER.length);
-      if (key.return || input === "s") return submit();
+      // enter is the one advertised save key — no undocumented "s" alias to trip on.
+      if (key.return) return submit();
     },
     { isActive: active },
   );
@@ -98,9 +103,13 @@ export function AddView({ client, ui, active }) {
     h(Text, {}, ""),
     field("model  ", modelStr, "(press m to type one)"),
     resolveLine,
-    field("project", project ? project.name : "", "(new: Manual)"),
+    field("project", project ? project.name : "", '(p to pick · else saves to a new "Manual" project)'),
+    projQ.error
+      ? h(Text, { color: "#dc2626" }, `  ${GLYPH.cross} couldn't load projects — ${projQ.error}`, h(Text, { color: C.FG_DIM }, "  ·  p retries"))
+      : null,
     field("env    ", ENV_ORDER[envIdx], ""),
     h(Text, {}, ""),
-    h(Text, { color: C.FG_FAINT }, "m model · p project · e env · ↵ save   (auto-matched to the registry, else tracked as custom)"),
+    // Keys live in the keybar below — this line carries only what the keybar can't.
+    h(Text, { color: C.FG_FAINT }, "models are auto-matched to the registry; unmatched names are tracked as custom"),
   );
 }

package/src/tui/views/alerts.js

@@ -27,8 +27,8 @@ const KIND_COLOR = {
 // follows the active sub-tab (published via ui.setKeys) rather than advertising
 // Rules keys while you're on Channels.
 const ALERTS_TAB_KEYS = [
-  [{ k: "←→", label: "section" }, { k: "↑↓", label: "nav" }, { k: "n", label: "new rule" }, { k: "space", label: "enable" }, { k: "c", label: "cadence" }, { k: "d", label: "delete" }, { k: "g", label: "refresh" }],
-  [{ k: "←→", label: "section" }, { k: "↑↓", label: "nav" }, { k: "n", label: "add channel" }, { k: "t", label: "test" }, { k: "g", label: "refresh" }],
+  [{ k: "↑↓", label: "nav" }, { k: "n", label: "new rule" }, { k: "space", label: "toggle" }, { k: "g", label: "refresh" }, { k: "c", label: "cadence" }, { k: "d", label: "delete" }],
+  [{ k: "↑↓", label: "nav" }, { k: "n", label: "add channel" }, { k: "t", label: "test" }, { k: "g", label: "refresh" }],
 ];
 
 export function AlertsView({ client, ui, active, width = 78, height = 14 }) {
@@ -49,8 +49,8 @@ export function AlertsView({ client, ui, active, width = 78, height = 14 }) {
   const tick = useTick(80, loading);
 
   React.useEffect(
-    () => ui?.reportStatus?.({ context: `${ruleList.length} rules · ${chanList.length} chan` }),
-    [ruleList, chanList, ui],
+    () => ui?.reportStatus?.({ context: rules.error || channels.error ? "offline" : `${ruleList.length} rules · ${chanList.length} chan` }),
+    [ruleList, chanList, rules.error, channels.error, ui],
   );
 
   async function newRule() {
@@ -85,7 +85,7 @@ export function AlertsView({ client, ui, active, width = 78, height = 14 }) {
               ui.showToast(`${k} channel added`);
               channels.reload();
             } catch (e) {
-              if (e.status === 402) ui.showToast("Channels are a Pro feature — press 6 → u to upgrade", "yellow");
+              if (e.status === 402) ui.showToast("Channels are a Pro feature — press 7 → u to upgrade", "yellow");
               else ui.showToast(e.message, "red");
             }
           },
@@ -145,7 +145,7 @@ export function AlertsView({ client, ui, active, width = 78, height = 14 }) {
     body = h(StateLine, { kind: "loading", spin: SPINNER[tick % SPINNER.length], text: tab === 0 ? "loading rules…" : "loading channels…" });
   } else if (err) {
     // Don't let a network/API error masquerade as "no rules" (a false empty).
-    body = h(StateLine, { kind: "error", text: `couldn't load ${tab === 0 ? "rules" : "channels"} — ${err}. Press g to retry.` });
+    body = h(StateLine, { kind: "error", text: `couldn't load ${tab === 0 ? "rules" : "channels"} — ${err}`, hint: "g retries" });
   } else if (tab === 0) {
     if (!ruleList.length) {
       body = h(EmptyCard, { title: "No alert rules yet", lines: ["Stay ahead of your model timeline — a heads-up 90, 30, 7, and 1 day before anything you use is deprecated or retired.", "Press n to set the sensible default (your models · in-app + email · those lead times)."], width });
@@ -179,7 +179,7 @@ export function AlertsView({ client, ui, active, width = 78, height = 14 }) {
         Box,
         { flexDirection: "column" },
         h(EmptyCard, { title: "No channels", lines: ["Press n to add one (Pro)."], width }),
-        h(Text, { color: "#d97706" }, "  Slack/Discord/SMS/webhook channels need Pro — press 6 → u to upgrade."),
+        h(Text, { color: "#d97706" }, "  Slack/Discord/SMS/webhook channels need Pro — press 7 → u to upgrade."),
       );
     } else {
       const curIdx = clampCursor(cursor, chanList.length);
@@ -200,7 +200,7 @@ export function AlertsView({ client, ui, active, width = 78, height = 14 }) {
   }
 
   const hint = tab === 0
-    ? "  Rules watch the registry — deprecations · retirements · replacements · new models — and alert your channels."
+    ? "  Rules watch the registry for lifecycle changes and alert your channels."
     : "  Channels deliver alerts: Slack/Discord/SMS/webhook are Pro; in-app + email are always on.";
   return h(
     Box,
@@ -216,7 +216,7 @@ export const meta = {
     { k: "←→", label: "tab" },
     { k: "↑↓", label: "nav" },
     { k: "n", label: "new" },
-    { k: "space", label: "enable" },
+    { k: "space", label: "toggle" },
     { k: "c", label: "cadence" },
     { k: "t", label: "test" },
     { k: "d", label: "delete" },

package/src/tui/views/integrations.js

@@ -156,13 +156,13 @@ export function IntegrationsView({ client, me, ui, active, width = 78, height =
   // Column budget: rail(1) + toggle(2) + label + gap(1) + kind(10) + status(rest) + env(8).
   const ENV_W = 8;
   const KIND_W = 10;
-  const LABEL_W = 30;
+  const LABEL_W = 35;
   const restW = Math.max(8, width - 1 - 2 - LABEL_W - 1 - KIND_W - ENV_W);
 
   // Status string per row: not-installed › off/available › on › on·authorized / auth failed.
   function statusFor(r) {
     if (!r.hasCmd) return { text: `${r.meta.requiresCmd} not installed`, color: C.FG_FAINT };
-    if (r.probe && !r.probe.connected) return { text: "auth failed", color: "#dc2626" };
+    if (r.probe && !r.probe.connected) return { text: `auth failed${r.probe.reason ? ` · ${r.probe.reason}` : ""}`, color: "#dc2626" };
     if (r.probe && r.probe.connected) {
       const who = r.probe.account ? ` · ${r.probe.account}` : "";
       return { text: `authorized${who}`, color: "#16a34a" };
@@ -190,7 +190,7 @@ export function IntegrationsView({ client, me, ui, active, width = 78, height =
         const isCur = i === curIdx;
         const st = statusFor(r);
         const spin = probing === r.id ? `${SPINNER[tick % SPINNER.length]} ` : "";
-        const et = envTagSeg(r.env);
+        const et = r.env === "unknown" ? { text: "env ?", color: C.FG_FAINT } : envTagSeg(r.env);
         const cells = [
           { text: `${r.enabled ? GLYPH.check : GLYPH.dot} `, color: r.enabled ? C.ACCENT : C.FG_FAINT },
           { text: cellE(r.meta.label, LABEL_W), color: isCur ? C.FG_STRONG : r.enabled ? C.FG : C.FG_FAINT, bold: isCur },
@@ -204,7 +204,7 @@ export function IntegrationsView({ client, me, ui, active, width = 78, height =
     );
   }
 
-  const hint = "  Toggle which live deployments scan by default · space on/off · t authorize · e env. Secrets stay on your machine.";
+  const hint = "  Toggle which live deployments mm scan checks by default. Secrets stay on your machine.";
   return h(
     Box,
     { flexDirection: "column" },
@@ -218,7 +218,7 @@ export const meta = {
     { k: "↑↓", label: "nav" },
     { k: "space", label: "toggle" },
     { k: "e", label: "env" },
-    { k: "t", label: "test" },
+    { k: "t", label: "test auth" },
     { k: "g", label: "refresh" },
   ],
 };

package/src/tui/views/inventory.js

@@ -14,18 +14,21 @@ import { sourceOf, SOURCE_META, sourceGlyph } from "../source-meta.js";
 
 const ENV_ORDER = ["prod", "staging", "dev", "unknown"];
 
+// Ordered by survival priority — KeyBar truncates the tail on narrow terminals,
+// so recovery (g) and the populate verbs (r/n) must outlive the per-row
+// secondaries, and destructive keys come last.
 export const meta = {
   keys: [
     { k: "↑↓", label: "nav" },
     { k: "/", label: "search" },
+    { k: "g", label: "refresh" },
+    { k: "r", label: "rescan" },
+    { k: "n", label: "new" },
     { k: "e", label: "env" },
-    { k: "t", label: "tag untagged" },
+    { k: "t", label: "tag" },
     { k: "c", label: "critical" },
     { k: "d", label: "delete" },
     { k: "C", label: "clear all" },
-    { k: "r", label: "rescan" },
-    { k: "n", label: "new" },
-    { k: "g", label: "refresh" },
   ],
 };
 
@@ -84,12 +87,18 @@ export function InventoryView({ client, ui, dir = ".", active, width = 78, heigh
     return abs ? readSnippet(abs, cur.source_line, matchStr) : null;
   }, [cur?.source_path, cur?.source_line, matchStr, dir]); // eslint-disable-line react-hooks/exhaustive-deps
 
-  // Push health legend + tracked context up to the shell status bar.
+  // Push health legend + tracked context up to the shell status bar. While the
+  // fetch is failed/loading the truth is UNKNOWN — suppress the zeroed counts
+  // and say so, rather than asserting "0 tracked".
   React.useEffect(() => {
+    if (q.error || q.loading) {
+      ui?.reportStatus?.({ context: q.error ? "offline" : "loading…" });
+      return;
+    }
     const counts = { ok: 0, deprecating: 0, retiring: 0, retired: 0, custom: 0 };
     for (const u of usages) if (counts[u.health] != null) counts[u.health] += 1;
     ui?.reportStatus?.({ counts, context: query ? `${filtered.length} of ${usages.length}` : `${usages.length} tracked` });
-  }, [usages, ui, query, filtered.length]);
+  }, [usages, ui, query, filtered.length, q.error, q.loading]);
 
   async function patch(u, body, label) {
     try {
@@ -161,28 +170,39 @@ export function InventoryView({ client, ui, dir = ".", active, width = 78, heigh
         return patch(cur, { environment: ENV_ORDER[(i + 1) % ENV_ORDER.length] }, "env updated");
       }
       if (input === "c") return patch(cur, { is_critical: !cur.is_critical }, "critical toggled");
-      if (input === "d")
-        return client
-          .deleteUsage(cur.id)
-          .then(() => {
-            ui.showToast("deleted");
-            setCursor((c) => clampCursor(c, filtered.length - 1));
-            q.reload();
-          })
-          .catch((e) => ui.showToast(e.message, "red"));
+      if (input === "d") {
+        // One stray keypress shouldn't silently delete a cloud-synced usage —
+        // confirm like C clear-all does (proportionally lighter: a single y).
+        const name = cur.model_display || cur.custom_model_name || "this usage";
+        return ui.askPrompt(`Delete ${name}? type y`, {
+          onSubmit: (v) => {
+            if (String(v || "").trim().toLowerCase() !== "y") return ui.showToast("delete cancelled");
+            client
+              .deleteUsage(cur.id)
+              .then(() => {
+                ui.showToast("deleted");
+                setCursor((c) => clampCursor(c, filtered.length - 1));
+                q.reload();
+              })
+              .catch((e) => ui.showToast(e.message, "red"));
+          },
+        });
+      }
     },
     { isActive: active },
   );
 
   if (q.loading) return h(StateLine, { kind: "loading", spin, text: "loading inventory…" });
-  if (q.error) return h(StateLine, { kind: "error", text: q.error });
+  if (q.error) return h(StateLine, { kind: "error", text: `couldn't load inventory — ${q.error}`, hint: "g retries" });
   if (!usages.length)
     return h(EmptyCard, {
       icon: GLYPH.spark,
       title: "Let's find your AI models",
       lines: [
-        "Press 4 Scan to auto-detect every model used in this repo.",
-        "Or press 5 Add to enter one by name — takes about 30 seconds.",
+        // Name this tab's OWN keys (r/n in the keybar below), and be honest that
+        // the cloud inventory fills from the Scan tab's upload, not the scan alone.
+        "Press r to scan this repo, then u on the Scan tab to upload what it finds.",
+        "Or press n to add one by name — takes about 30 seconds.",
       ],
       width,
     });

package/src/tui/views/local.js

@@ -19,15 +19,18 @@ import { readSnippet } from "../snippet.js";
 import { openLocation } from "../../openUrl.js";
 import { addGlobalIgnore } from "../../sources/filesystem.js";
 
+// Ordered by survival priority — KeyBar drops trailing entries on narrow
+// terminals, so the primary verb (u push) and recovery (g rescan) must come
+// before the secondaries. "p pause" lives in the in-strip hint while a scan
+// runs (the only time it works), never here.
 export const meta = {
   keys: [
-    { k: "↑↓", label: "scroll" },
+    { k: "↑↓", label: "nav" },
     { k: "↵", label: "refs" },
-    { k: "e", label: "exclude" },
-    { k: "/", label: "search" },
-    { k: "p", label: "pause" },
+    { k: "u", label: "push → Inv" },
     { k: "g", label: "rescan" },
-    { k: "u", label: "push all → inventory" },
+    { k: "/", label: "search" },
+    { k: "e", label: "exclude" },
   ],
 };
 
@@ -169,6 +172,16 @@ export function LocalView({ client, me, dir, ui, width = 78, height = 14, active
     return () => setHandlesBack?.(false);
   }, [setHandlesBack, focus, search.query]);
 
+  // The refs drill-in swaps the keymap (↵ opens in editor, esc backs out) — the
+  // keybar must say so instead of advertising the dead list keys.
+  const setKeys = ui?.setKeys;
+  React.useEffect(() => {
+    setKeys?.(focus === "refs"
+      ? [{ k: "↑↓", label: "nav" }, { k: "↵", label: "open in editor" }, { k: "e", label: "exclude path" }, { k: "esc", label: "back" }]
+      : null);
+    return () => setKeys?.(null);
+  }, [setKeys, focus]);
+
   useInput(
     (input, key) => {
       if (!active) return;
@@ -211,7 +224,7 @@ export function LocalView({ client, me, dir, ui, width = 78, height = 14, active
     { isActive: active },
   );
 
-  if (phase === "error") return h(StateLine, { kind: "error", text: scan.error });
+  if (phase === "error") return h(StateLine, { kind: "error", text: scan.error, hint: "g rescans" });
 
   // ----- strip (1 line) -----
   const counters = `${fmtNum(filesScanned)} files · ${fmtNum(dirsSeen)} dirs · ${fmtNum(candidateCount)} refs${catalogsSkipped ? ` · ${catalogsSkipped} catalog${catalogsSkipped === 1 ? "" : "s"} skipped` : ""}`;
@@ -224,14 +237,15 @@ export function LocalView({ client, me, dir, ui, width = 78, height = 14, active
   else if (phase === "scanning")
     strip = h(Box, {}, h(Text, { color: C.ACCENT }, ` ${spin}  `), h(SweepBar, { tick }), h(Text, { color: C.FG }, `  ${counters}`), h(Text, { color: C.FG_FAINT }, "  ·  p pause"));
   else
+    // Lead with the verdict (what needs attention), then the scan housekeeping —
+    // the warning is the one thing the user came for; stats are context.
     strip = h(
       Box,
       {},
-      h(Text, { color: "#16a34a" }, ` ${GLYPH.check} `),
-      h(Text, { color: C.FG_DIM }, fromCache ? `loaded last scan${scannedAt ? ` (${agoText(Date.now() - scannedAt)})` : ""} · ${fmtNum(candidateCount)} refs · g rescan` : `scanned just now · ${counters} · g rescan`),
       attention > 0
-        ? h(Text, { color: "#d97706" }, `   ${GLYPH.warn} ${attention} need attention`)
-        : h(Text, { color: "#16a34a" }, "   all current"),
+        ? h(Text, { color: "#d97706" }, ` ${GLYPH.warn} ${attention} need attention`)
+        : h(Text, { color: "#16a34a" }, ` ${GLYPH.check} all current`),
+      h(Text, { color: C.FG_DIM }, fromCache ? `   scanned ${scannedAt ? agoText(Date.now() - scannedAt) : "earlier"} · ${fmtNum(candidateCount)} refs · g rescan` : `   scanned just now · ${counters} · g rescan`),
     );
 
   // ----- list rows (full width) -----

package/src/tui/views/scan.js

@@ -36,16 +36,19 @@ import { track } from "../../telemetry.js";
 import { openUrl, openLocation } from "../../openUrl.js";
 import { boardSize, MIN_W, MIN_H } from "../game/dk-core.js";
 
+// Ordered by survival priority — KeyBar truncates the tail on narrow terminals,
+// and `u upload` is this tab's entire purpose: it must never be the key that
+// gets hidden behind the "…".
 export const meta = {
   keys: [
     { k: "↑↓", label: "nav" },
     { k: "space", label: "toggle" },
+    { k: "u", label: "upload" },
     { k: "a/x", label: "all/none" },
     { k: "↵", label: "refs" },
     { k: "/", label: "search" },
     { k: "g", label: "rescan" },
-    { k: "u", label: "upload all" },
-    { k: "P", label: "play" }, // launches anytime (also the global Shift-P)
+    { k: "P", label: "play 🦍" }, // launches anytime (also the global Shift-P)
     { k: "N", label: "new project" },
   ],
 };
@@ -162,7 +165,10 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
 
   React.useEffect(() => {
     const counts = countHealth(items);
-    const ctx = `${project ? project.name + " · " : ""}${selCount}/${items.length} sel`;
+    // "p <project>" self-documents the otherwise-invisible p key (cycles the
+    // upload target) — important because the adjacent Here tab used to teach
+    // people that p means pause.
+    const ctx = `p ${project ? project.name : "auto"} · ${selCount}/${items.length} sel`;
     ui?.reportStatus?.({ counts, context: ctx });
   }, [items, selCount, project, ui]);
 
@@ -174,6 +180,16 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
     return () => setHandlesBack?.(false);
   }, [setHandlesBack, focus, search.query]);
 
+  // The refs drill-in swaps the keymap — advertise the real keys, not the dead
+  // list ones (same pattern as the Here tab).
+  const setKeys = ui?.setKeys;
+  React.useEffect(() => {
+    setKeys?.(focus === "refs"
+      ? [{ k: "↑↓", label: "nav" }, { k: "↵", label: "open in editor" }, { k: "e", label: "exclude path" }, { k: "esc", label: "back" }]
+      : null);
+    return () => setKeys?.(null);
+  }, [setKeys, focus]);
+
   function openRef(r) {
     if (!r) return;
     const abs = path.resolve(dir, r.source_path || r.location_label || "");
@@ -285,7 +301,7 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
     { isActive: active },
   );
 
-  if (scan.phase === "error") return h(StateLine, { kind: "error", text: scan.error });
+  if (scan.phase === "error") return h(StateLine, { kind: "error", text: scan.error, hint: "g rescans" });
   if (running && !items.length)
     return h(
       Box,
@@ -319,7 +335,7 @@ export function ScanView({ client, dir, ui, active, width = 78, height = 14, fre
 
   // While the walk is still running (and the terminal fits a board), nudge the
   // "Play Donkey Kong while you wait" affordance on the showing line.
-  const playHint = running && canPlay ? " · P play" : "";
+  const playHint = running && canPlay ? " · P play 🦍" : "";
   const showingLine = h(
     Text,
     { color: C.FG_FAINT },

package/src/tui/views/whatsnew.js

@@ -13,24 +13,19 @@ import { loadConfig, setConfigValue } from "../../config.js";
 
 const TABS = ["Registry", "Alerts", "Drift"];
 
-export const meta = {
-  keys: [
-    { k: "←→", label: "section" },
-    { k: "↑↓", label: "scroll" },
-    { k: "m", label: "mark seen" },
-    { k: "r", label: "drift" },
-  ],
-};
-
 // Per-section keybars — the active actions differ by tab (Registry: mark seen ·
 // Notifications: mark read · Drift: rescan + archive). Published via ui.setKeys()
 // so the keybar never advertises a key that's dead on the current section.
 const TAB_KEYS = [
-  [{ k: "←→", label: "section" }, { k: "↑↓", label: "scroll" }, { k: "m", label: "mark all seen" }],
-  [{ k: "←→", label: "section" }, { k: "↑↓", label: "scroll" }, { k: "o", label: "mark read" }],
-  [{ k: "←→", label: "section" }, { k: "↑↓", label: "scroll" }, { k: "r", label: "rescan" }, { k: "a", label: "archive" }],
+  [{ k: "←→", label: "section" }, { k: "↑↓", label: "nav" }, { k: "m", label: "mark all seen" }, { k: "g", label: "refresh" }],
+  [{ k: "←→", label: "section" }, { k: "↑↓", label: "nav" }, { k: "o", label: "mark read" }, { k: "g", label: "refresh" }],
+  [{ k: "←→", label: "section" }, { k: "↑↓", label: "nav" }, { k: "r", label: "rescan" }, { k: "a", label: "archive" }],
 ];
 
+// The static fallback must match the default (Registry) section exactly —
+// advertising `m`/`r` together implies both work everywhere, and they don't.
+export const meta = { keys: TAB_KEYS[0] };
+
 export function WhatsNewView({ client, dir, ui, active, width = 78, height = 14 }) {
   const [tab, setTab] = React.useState(0);
   const [cursor, setCursor] = React.useState(0);
@@ -93,6 +88,13 @@ export function WhatsNewView({ client, dir, ui, active, width = 78, height = 14
       if (key.rightArrow) return (setTab((t) => (t + 1) % TABS.length), setCursor(0));
       if (key.downArrow || input === "j") return setCursor((c) => c + 1);
       if (key.upArrow || input === "k") return setCursor((c) => Math.max(0, c - 1));
+      // g refreshes whichever section is showing — the universal retry across tabs
+      // (and the escape hatch when a fetch fails).
+      if (input === "g") {
+        if (tab === 0) return reg.reload();
+        if (tab === 1) return notif.reload();
+        return runDrift();
+      }
 
       if (tab === 0) {
         if (input === "m") {
@@ -110,7 +112,8 @@ export function WhatsNewView({ client, dir, ui, active, width = 78, height = 14
       } else if (tab === 2) {
         if (input === "r") return runDrift();
         const gone = drift?.gone || [];
-        const cur = gone[clampCursor(cursor, gone.length)];
+        // Same visible-rows clamp as the render — archive only what's on screen.
+        const cur = gone[clampCursor(cursor, Math.min(gone.length, 7))];
         if (input === "a" && cur)
           client.deleteUsage(cur.id).then(() => {
             ui.showToast("archived");
@@ -123,17 +126,19 @@ export function WhatsNewView({ client, dir, ui, active, width = 78, height = 14
 
   // Push per-tab context up to the shell status bar.
   React.useEffect(() => {
+    // On a failed fetch the count is UNKNOWN, not zero — say "offline", don't
+    // assert "0 changes".
     let context;
-    if (tab === 0) context = `${reg.data?.events.length || 0} changes`;
-    else if (tab === 1) context = `${(notif.data || []).length} alerts`;
+    if (tab === 0) context = reg.error ? "offline" : `${reg.data?.events.length || 0} changes`;
+    else if (tab === 1) context = notif.error ? "offline" : `${(notif.data || []).length} alerts`;
     else context = drift && !drift.loading && !drift.error ? `+${drift.added.length} / -${drift.gone.length}` : "drift";
     ui?.reportStatus?.({ context });
-  }, [tab, reg.data, notif.data, drift, ui]);
+  }, [tab, reg.data, reg.error, notif.data, notif.error, drift, ui]);
 
   let body;
   if (tab === 0) {
     if (reg.loading) body = h(StateLine, { kind: "loading", spin, text: "loading registry changes…" });
-    else if (reg.error) body = h(StateLine, { kind: "error", text: reg.error });
+    else if (reg.error) body = h(StateLine, { kind: "error", text: `couldn't load registry changes — ${reg.error}`, hint: "g retries" });
     else {
       const events = reg.data.events;
       if (!events.length) body = h(Text, { color: C.FG_DIM }, "  No registry changes recorded yet.");
@@ -161,31 +166,37 @@ export function WhatsNewView({ client, dir, ui, active, width = 78, height = 14
   } else if (tab === 1) {
     const list = notif.data || [];
     if (notif.loading) body = h(StateLine, { kind: "loading", spin, text: "loading alerts…" });
-    else if (notif.error) body = h(StateLine, { kind: "error", text: notif.error });
-    else if (!list.length) body = h(Text, { color: C.FG_DIM }, "  No alerts yet. Configure rules in the Alerts view.");
+    else if (notif.error) body = h(StateLine, { kind: "error", text: `couldn't load alerts — ${notif.error}`, hint: "g retries" });
+    else if (!list.length) body = h(Text, { color: C.FG_DIM }, "  No alerts yet. Press 6 to set up alert rules.");
     else {
+      // Window the list around the cursor so ↑↓ can reach every row — a fixed
+      // slice(0, ROWS) lets the selection walk below the visible page and `o`
+      // act on a row the user can't see.
       const cur = clampCursor(cursor, list.length);
+      const start = Math.max(0, Math.min(cur - ROWS + 1, list.length - ROWS));
       body = h(
         Box,
         { flexDirection: "column" },
-        ...list.slice(0, ROWS).map((n, i) => {
+        ...list.slice(start, start + ROWS).map((n, i) => {
           const cells = [
             { text: `${n.unread ? GLYPH.bullet : GLYPH.custom} `, color: n.unread ? C.ACCENT : C.FG_FAINT },
             { text: cellE(n.title, 40), color: n.unread ? C.FG : C.FG_DIM },
             { text: " ", color: C.FG },
             { text: String(n.when || "").slice(0, 10).padEnd(10), color: C.FG_DIM },
           ];
-          return h(ListRow, { key: n.id, active: i === cur, cells, width });
+          return h(ListRow, { key: n.id, active: start + i === cur, cells, width });
         }),
       );
     }
   } else {
     if (!drift) body = h(Text, { color: C.FG_DIM }, `  Press r to scan ${dir} and compare against tracked usages.`);
     else if (drift.loading) body = h(StateLine, { kind: "loading", spin, text: "scanning for drift…" });
-    else if (drift.error) body = h(StateLine, { kind: "error", text: drift.error });
+    else if (drift.error) body = h(StateLine, { kind: "error", text: `drift scan failed — ${drift.error}`, hint: "r rescans" });
     else {
       const gone = drift.gone || [];
-      const curGone = clampCursor(cursor, gone.length);
+      // Clamp the archive cursor to the VISIBLE rows — `a` must never act on a
+      // row below the 7 shown.
+      const curGone = clampCursor(cursor, Math.min(gone.length, 7));
       body = h(
         Box,
         { flexDirection: "column" },
@@ -206,6 +217,7 @@ export function WhatsNewView({ client, dir, ui, active, width = 78, height = 14
           ];
           return h(ListRow, { key: "a" + i, active: false, cells, width });
         }),
+        drift.added.length > 5 ? h(Text, { color: C.FG_DIM }, `  … ${drift.added.length - 5} more new`) : null,
         ...gone.slice(0, 7).map((u, i) => {
           const cells = [
             { text: "- ", color: "#dc2626" },
@@ -215,6 +227,7 @@ export function WhatsNewView({ client, dir, ui, active, width = 78, height = 14
           ];
           return h(ListRow, { key: "g" + i, active: i === curGone, cells, width });
         }),
+        gone.length > 7 ? h(Text, { color: C.FG_DIM }, `  … ${gone.length - 7} more gone`) : null,
       );
     }
   }