@jhizzard/termdeck 0.5.1 → 0.6.1

package/README.md

@@ -81,7 +81,7 @@ What's excluded at this tier: **Flashback is silent**, the "Ask about this termi
 
 ### Tier 2 — Add Mnestra to light up Flashback
 
-Mnestra is a separate npm package — `@jhizzard/mnestra@0.2.0` — that ships a Postgres-backed persistent memory store with an MCP server, a webhook server, six search tools, and six SQL migrations. It can be consumed by TermDeck (for Flashback), by Claude Code (as an MCP memory layer), or by any tool that speaks the MCP protocol.
+Mnestra is a separate npm package — `@jhizzard/mnestra@0.2.1` — that ships a Postgres-backed persistent memory store with an MCP server, a webhook server, six search tools, and six SQL migrations. It can be consumed by TermDeck (for Flashback), by Claude Code (as an MCP memory layer), or by any tool that speaks the MCP protocol.
 
 To enable Flashback in TermDeck:
 
@@ -147,7 +147,7 @@ Restart Claude Code. Six MCP tools appear: `memory_remember`, `memory_recall`, `
 
 ### Tier 3 — Add Rumen for async learning
 
-Rumen is a separate npm package — `@jhizzard/rumen@0.4.5` — that ships as a Supabase Edge Function designed to run on a 15-minute `pg_cron` schedule. It's the async reflection layer over Mnestra: it reads recent session memories, cross-references them with your entire historical corpus via hybrid search, synthesizes insights via Claude Haiku, and writes the results back into `rumen_insights` (a new table alongside Mnestra's `memory_items`). TermDeck's Flashback and Claude Code's `memory_recall` both automatically benefit because insights flow back into the same database.
+Rumen is a separate npm package — `@jhizzard/rumen@0.4.3` — that ships as a Supabase Edge Function designed to run on a 15-minute `pg_cron` schedule. It's the async reflection layer over Mnestra: it reads recent session memories, cross-references them with your entire historical corpus via hybrid search, synthesizes insights via Claude Haiku, and writes the results back into `rumen_insights` (a new table alongside Mnestra's `memory_items`). TermDeck's Flashback and Claude Code's `memory_recall` both automatically benefit because insights flow back into the same database.
 
 **Rumen is live.** First full-kickstart run against a production Mnestra store on 2026-04-15 19:47 UTC: **111 sessions processed, 111 insights generated** in one pass. Insights surfaced patterns like "the error detection regex in Flashback misses `No such file or directory` — same class of blind spot as X" and "Practice sessions exist as a separate model but frontend components were built and never wired into the schedule view." The cognitive loop is closed.
 
@@ -171,7 +171,7 @@ Honest limits, stated upfront so the skeptic has nothing to chase:
 - **Not a replacement for reading docs.** It's the shortest path to a memory you already wrote. If the memory isn't there, the feature does nothing.
 - **Not fully local by default.** Tier 2+ reaches out to Supabase for storage and OpenAI for embeddings. Tier 1 is fully local. A fully-local Tier 2 (local Postgres + local embeddings) is on the roadmap.
 - **Not free forever.** Tier 2+ pays OpenAI fractions of a cent per memory for embeddings. Self-hosted embeddings via Ollama are on the roadmap.
-- **Not proven at scale.** v0.4.5, validated against 3,527 memories in one developer's production store. First full Rumen kickstart on 2026-04-15 processed 111 sessions into 111 insights in one pass. No multi-user data yet. Bug reports and issues welcome.
+- **Not proven at scale.** v0.6.1, validated against 4,590 memories in one developer's production store. The Rumen 2026-04-19 re-kickstart processed 166 sessions into 166 insights in ~5.5 minutes. No multi-user data yet. Bug reports and issues welcome.
 
 ---
 
@@ -226,6 +226,18 @@ For users who want more than `npx` — cloning from source, building a macOS `.a
 
 ---
 
+## Staying current
+
+TermDeck, Mnestra, and Rumen all evolve fast — Flashback recall quality, Mnestra search semantics, and Rumen synth quality each shift between minor releases. Running last month's stack means missing fixed bugs and degraded recall. Three layered ways to keep current:
+
+1. **One command for the whole stack:** `npx @jhizzard/termdeck-stack` — re-runs the meta-installer, which detects what's already installed and updates anything that's behind. Idempotent: safe to run any time, won't touch `~/.termdeck/{config.yaml,secrets.env,termdeck.db}`.
+2. **On demand:** `termdeck doctor` — prints a 4-row table (TermDeck, Mnestra, Rumen, termdeck-stack) of installed vs. latest versions with a status column. Exit 0 = all current, 1 = at least one update available, 2 = registry/network failure.
+3. **Passive:** TermDeck prints a single yellow `[hint]` line on startup when an update is available. Rate-limited to once per 24 hours via `~/.termdeck/update-check.json`. Never blocks startup. Suppress with `TERMDECK_NO_UPDATE_CHECK=1` (the kill switch only mutes the startup hint — `termdeck doctor` still works on demand).
+
+See **[docs/SEMVER-POLICY.md](docs/SEMVER-POLICY.md)** for what each kind of bump means across the four packages and how risky a given upgrade path is.
+
+---
+
 ## Related packages
 
 - **[@jhizzard/mnestra](https://www.npmjs.com/package/@jhizzard/mnestra)** — persistent dev memory MCP server. pgvector + hybrid search + 3-layer progressive disclosure. Works standalone with any MCP client.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/cli/src/doctor.js

@@ -0,0 +1,255 @@
+// `termdeck doctor` — Sprint 28 T2.
+//
+// Compares installed versions of the four TermDeck-stack packages against
+// the npm registry's `dist-tags.latest` and prints a status table. Zero new
+// deps — uses only node:https, node:child_process, and process.stdout.
+//
+// Module contract (per docs/sprint-28-update-signal/STATUS.md):
+//   module.exports = function doctor(argv): Promise<exitCode>
+//     0 = all current
+//     1 = at least one update available
+//     2 = network/registry failure or unrecoverable error
+//
+// `_detectInstalled` and `_fetchLatest` are exposed as properties on the
+// exported function so tests can monkey-patch the network/process surface
+// without spinning up a real registry. The doctor body calls them via
+// `module.exports.<name>` so monkey-patching takes effect at call time.
+
+const https = require('https');
+const { spawn } = require('child_process');
+
+const STACK_PACKAGES = [
+  '@jhizzard/termdeck',
+  '@jhizzard/mnestra',
+  '@jhizzard/rumen',
+  '@jhizzard/termdeck-stack',
+];
+
+const REGISTRY_TIMEOUT_MS = 5000;
+const NPM_LS_TIMEOUT_MS = 8000;
+
+const STATUS = {
+  UP_TO_DATE: 'up to date',
+  UPDATE: 'update available',
+  NOT_INSTALLED: 'not installed',
+  NETWORK_ERROR: 'network error',
+};
+
+function makeColors(enabled) {
+  if (!enabled) {
+    return { green: (s) => s, yellow: (s) => s, dim: (s) => s, bold: (s) => s };
+  }
+  return {
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  };
+}
+
+// Detect installed version via `npm ls -g <pkg> --depth=0 --json`. Returns
+// the version string on success, or null on "not installed" / parse failure
+// / npm-missing-from-PATH / timeout. Stderr noise (npm WARN lines) is
+// silently dropped — those are not fatal.
+async function _detectInstalled(pkg) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('npm', ['ls', '-g', pkg, '--depth=0', '--json'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch {
+      return resolve(null);
+    }
+
+    let stdout = '';
+    let timedOut = false;
+    const t = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGKILL'); } catch (_e) { /* already gone */ }
+    }, NPM_LS_TIMEOUT_MS);
+
+    child.stdout.on('data', (b) => { stdout += b.toString('utf8'); });
+    child.stderr.on('data', () => { /* discard npm WARNs */ });
+    child.on('error', () => { clearTimeout(t); resolve(null); });
+    child.on('close', () => {
+      clearTimeout(t);
+      if (timedOut) return resolve(null);
+      try {
+        const parsed = JSON.parse(stdout);
+        const dep = parsed && parsed.dependencies && parsed.dependencies[pkg];
+        if (dep && typeof dep.version === 'string') return resolve(dep.version);
+        return resolve(null);
+      } catch {
+        return resolve(null);
+      }
+    });
+  });
+}
+
+// Fetch the `latest` dist-tag for a package from the public npm registry.
+// Returns the version string on success, or null on any failure (offline,
+// non-200, malformed JSON, timeout). The caller treats null as a network
+// error and bumps the exit code to 2.
+async function _fetchLatest(pkg) {
+  return new Promise((resolve) => {
+    // Encode `@scope/name` as `%40scope%2Fname` per the registry's URL spec.
+    const encoded = encodeURIComponent(pkg);
+    const url = `https://registry.npmjs.org/-/package/${encoded}/dist-tags`;
+    let settled = false;
+    const done = (v) => {
+      if (settled) return;
+      settled = true;
+      resolve(v);
+    };
+
+    let req;
+    try {
+      req = https.get(url, { timeout: REGISTRY_TIMEOUT_MS }, (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          return done(null);
+        }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => { body += chunk; });
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(body);
+            if (parsed && typeof parsed.latest === 'string') return done(parsed.latest);
+            return done(null);
+          } catch {
+            return done(null);
+          }
+        });
+        res.on('error', () => done(null));
+      });
+    } catch {
+      return done(null);
+    }
+    req.on('timeout', () => {
+      try { req.destroy(); } catch (_e) { /* already gone */ }
+      done(null);
+    });
+    req.on('error', () => done(null));
+  });
+}
+
+// Lightweight semver compare — only looks at the first three numeric segments,
+// which is all dist-tags.latest ever needs. Returns -1, 0, or 1.
+function _compareSemver(a, b) {
+  const pa = String(a).split('.').map((s) => parseInt(s, 10) || 0);
+  const pb = String(b).split('.').map((s) => parseInt(s, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+function classifyRow(installed, latest) {
+  if (latest === null) return STATUS.NETWORK_ERROR;
+  if (installed === null) return STATUS.NOT_INSTALLED;
+  return _compareSemver(installed, latest) < 0 ? STATUS.UPDATE : STATUS.UP_TO_DATE;
+}
+
+function pad(s, n) {
+  const str = String(s);
+  return str.length >= n ? str : str + ' '.repeat(n - str.length);
+}
+
+function renderTable(rows, c) {
+  const out = [];
+  out.push(c.bold('TermDeck stack — version check'));
+  out.push('');
+  out.push(`  ${pad('Package', 32)}${pad('Installed', 12)}${pad('Latest', 12)}Status`);
+  out.push('  ' + '─'.repeat(63));
+  for (const r of rows) {
+    const installedDisplay = r.installed === null ? '(none)' : r.installed;
+    const latestDisplay = r.latest === null ? '?' : r.latest;
+    let statusDisplay = r.status;
+    if (r.status === STATUS.UP_TO_DATE) statusDisplay = c.green(r.status);
+    else if (r.status === STATUS.UPDATE) statusDisplay = c.yellow(r.status);
+    else if (r.status === STATUS.NOT_INSTALLED) statusDisplay = c.dim(r.status);
+    else if (r.status === STATUS.NETWORK_ERROR) statusDisplay = c.dim(r.status);
+    out.push(`  ${pad(r.package, 32)}${pad(installedDisplay, 12)}${pad(latestDisplay, 12)}${statusDisplay}`);
+  }
+  return out.join('\n');
+}
+
+function renderFooter(rows, exitCode) {
+  if (exitCode === 2) {
+    const errors = rows.filter((r) => r.status === STATUS.NETWORK_ERROR).length;
+    return `\n  Could not reach npm registry for ${errors} package${errors === 1 ? '' : 's'}. Try again later.`;
+  }
+  if (exitCode === 1) {
+    const updates = rows.filter((r) => r.status === STATUS.UPDATE).length;
+    return (
+      `\n  ${updates} update${updates === 1 ? '' : 's'} available. ` +
+      `Run: npx @jhizzard/termdeck-stack\n` +
+      `  Or upgrade individually: npm install -g @jhizzard/termdeck@latest`
+    );
+  }
+  return `\n  All packages up to date.`;
+}
+
+function parseArgv(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  return {
+    json: args.includes('--json'),
+    noColor: args.includes('--no-color'),
+  };
+}
+
+async function doctor(argv) {
+  const opts = parseArgv(argv);
+
+  // Resolve every package's installed + latest in parallel — independent
+  // network/process calls, no reason to serialize.
+  const rows = await Promise.all(
+    STACK_PACKAGES.map(async (pkg) => {
+      const [installed, latest] = await Promise.all([
+        module.exports._detectInstalled(pkg),
+        module.exports._fetchLatest(pkg),
+      ]);
+      return {
+        package: pkg,
+        installed,
+        latest,
+        status: classifyRow(installed, latest),
+      };
+    })
+  );
+
+  // Exit-code priority: any network failure → 2; any update available → 1;
+  // else 0. Computed after all rows resolve so a single transient failure
+  // doesn't mask real updates in stdout.
+  let exitCode = 0;
+  for (const r of rows) {
+    if (r.status === STATUS.NETWORK_ERROR) {
+      exitCode = 2;
+      break;
+    }
+    if (r.status === STATUS.UPDATE && exitCode < 1) exitCode = 1;
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ exitCode, rows }, null, 2) + '\n');
+    return exitCode;
+  }
+
+  const colorEnabled = !opts.noColor && process.stdout.isTTY === true;
+  const c = makeColors(colorEnabled);
+  process.stdout.write(renderTable(rows, c) + '\n');
+  process.stdout.write(renderFooter(rows, exitCode) + '\n');
+  return exitCode;
+}
+
+module.exports = doctor;
+module.exports._detectInstalled = _detectInstalled;
+module.exports._fetchLatest = _fetchLatest;
+module.exports._compareSemver = _compareSemver;
+module.exports.STACK_PACKAGES = STACK_PACKAGES;
+module.exports.STATUS = STATUS;

package/packages/cli/src/index.js

@@ -76,12 +76,22 @@ if (args[0] === 'stack') {
   return;
 }
 
+// `termdeck doctor` — Sprint 28: version-check the whole stack.
+if (args[0] === 'doctor') {
+  const doctor = require(path.join(__dirname, 'doctor.js'));
+  doctor(args.slice(1)).then((code) => process.exit(code || 0)).catch((err) => {
+    console.error('[cli] doctor failed:', err && err.stack || err);
+    process.exit(2);
+  });
+  return;
+}
+
 // Sprint 24: when `termdeck` is invoked with no subcommand AND a configured
 // stack is detected, route through stack.js so users don't have to remember
 // the `stack` subcommand. `--no-stack` is the explicit opt-out.
 const { shouldAutoOrchestrate } = require(path.join(__dirname, 'auto-orchestrate.js'));
 
-const KNOWN_SUBCOMMANDS = new Set(['init', 'forge', 'stack']);
+const KNOWN_SUBCOMMANDS = new Set(['init', 'forge', 'stack', 'doctor']);
 const noStackIdx = args.indexOf('--no-stack');
 const noStackRequested = noStackIdx !== -1;
 if (noStackRequested) args.splice(noStackIdx, 1); // strip before flag parsing
@@ -120,6 +130,7 @@ for (let i = 0; i < args.length; i++) {
     termdeck init --mnestra     Configure Tier 2 memory (Supabase + Mnestra)
     termdeck init --rumen       Deploy Tier 3 async learning (Rumen)
     termdeck forge              Generate Claude skills from memories (experimental)
+    termdeck doctor             Check whether the stack packages are up to date
 
   Keyboard shortcuts (in browser):
     Ctrl+Shift+N                Focus prompt bar
@@ -175,6 +186,30 @@ if (!LOOPBACK.has(host)) {
   }
 }
 
+// Sprint 25 T4: non-blocking nudge when RAG is configured but the Supabase MCP
+// (T1's `@supabase/mcp-server-supabase` detection) isn't installed. Lazy-loads
+// T1's module so Tier 1 users with no RAG never pay the require cost. Silent
+// when RAG is off, when the MCP is detected, when ~/.claude/mcp.json already
+// declares a `supabase` server, or when anything below throws.
+async function checkSupabaseMcpHint(cfg) {
+  if (!cfg || !cfg.rag || cfg.rag.enabled !== true) return null;
+  try {
+    const claudeMcpPath = path.join(os.homedir(), '.claude', 'mcp.json');
+    if (fs.existsSync(claudeMcpPath)) {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(claudeMcpPath, 'utf8'));
+        if (parsed && parsed.mcpServers && parsed.mcpServers.supabase) return null;
+      } catch (_e) { /* malformed JSON — fall through and let detectMcp decide */ }
+    }
+    const { detectMcp } = require(path.join(__dirname, '..', '..', 'server', 'src', 'setup', 'supabase-mcp.js'));
+    const result = await detectMcp();
+    if (result && result.available) return null;
+    return 'Supabase MCP not installed — wizard auto-fill unavailable. Install with: npx @jhizzard/termdeck-stack --tier 4';
+  } catch (_e) {
+    return null;
+  }
+}
+
 server.listen(port, host, async () => {
   // Box inner width is 38 (count of ═ between ╔ and ╗). Center the title
   // dynamically so the right border stays aligned regardless of version length.
@@ -205,6 +240,23 @@ server.listen(port, host, async () => {
     console.error(`  \x1b[31m[health] Preflight failed: ${err.message}\x1b[0m\n`);
   });
 
+  // Sprint 28 T3: fire-and-forget update-check banner. Lazy-required so users
+  // who never start the server don't pay the require cost. Errors are swallowed
+  // inside the module; never blocks startup. Double-protected (try/catch around
+  // the require + swallowed .catch on the promise) so a missing or broken T3
+  // module can never break startup.
+  try {
+    const { checkAndPrintHint } = require(path.join(__dirname, 'update-check.js'));
+    checkAndPrintHint(config).catch(() => { /* swallowed inside the module too */ });
+  } catch (_e) { /* never block startup on a hint module load failure */ }
+
+  // Sprint 25 T4: Supabase MCP install nudge — runs alongside (not inside)
+  // runPreflight. Silent unless RAG is on AND the MCP is missing AND the
+  // user hasn't already declared it in ~/.claude/mcp.json.
+  checkSupabaseMcpHint(config).then((msg) => {
+    if (msg) console.log(`  \x1b[33m[hint]\x1b[0m ${msg}`);
+  }).catch(() => { /* silent */ });
+
   // Skip auto-open in Codespaces/CI (port forwarding handles it)
   const isCodespaces = !!process.env.CODESPACES || !!process.env.GITHUB_CODESPACE_TOKEN;
   const isCI = !!process.env.CI;

package/packages/cli/src/update-check.js

@@ -0,0 +1,156 @@
+// Sprint 28 T3 — passive startup update-check banner.
+//
+// Side-effect-only module. checkAndPrintHint() rate-limits a single GET against
+// the npm registry's dist-tags endpoint to once every 24h via a JSON cache at
+// ~/.termdeck/update-check.json, and prints one yellow [hint] line when a
+// newer version of @jhizzard/termdeck is published. All failures are swallowed
+// — startup must never block on this.
+//
+// Suppression order (any one short-circuits before any side effect):
+//   1. process.env.TERMDECK_NO_UPDATE_CHECK === '1'
+//   2. process.stdout.isTTY is falsy (CI, piped output)
+//   3. cache exists and lastCheckedAt is within 24h of now
+//
+// Module contract per docs/sprint-28-update-signal/STATUS.md.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const CACHE_VERSION = 1;
+const TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+const PACKAGE_NAME = '@jhizzard/termdeck';
+const REGISTRY_URL =
+  'https://registry.npmjs.org/-/package/@jhizzard%2Ftermdeck/dist-tags';
+
+function defaultCachePath() {
+  return path.join(os.homedir(), '.termdeck', 'update-check.json');
+}
+
+// The CLI ships inside the @jhizzard/termdeck package; the workspace root
+// package.json is three levels up from packages/cli/src/. If anything goes
+// wrong reading it (renamed file, broken JSON), return null and let the caller
+// suppress.
+function defaultPackageVersion() {
+  try {
+    const pkg = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+    return pkg && pkg.version ? String(pkg.version) : null;
+  } catch {
+    return null;
+  }
+}
+
+function isValidSemver(v) {
+  return typeof v === 'string' && /^\d+\.\d+\.\d+/.test(v);
+}
+
+// Three-way semver compare on [major, minor, patch]. Pre-release suffixes are
+// ignored — "0.5.1-beta" and "0.5.1" compare equal. Good enough for the hint.
+function compareSemver(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+function readCache(cachePath) {
+  try {
+    const raw = fs.readFileSync(cachePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (parsed.version !== CACHE_VERSION) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cachePath, data) {
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(cachePath, JSON.stringify(data, null, 2), 'utf8');
+  } catch {
+    // Read-only home, ENOSPC, race with another process — all benign here.
+  }
+}
+
+async function fetchLatest(registryUrl) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(registryUrl, { signal: controller.signal });
+    if (!res || !res.ok) return null;
+    const json = await res.json();
+    const latest = json && json.latest;
+    return isValidSemver(latest) ? latest : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function checkAndPrintHint(_config, opts) {
+  try {
+    if (process.env.TERMDECK_NO_UPDATE_CHECK === '1') return;
+    if (!process.stdout || !process.stdout.isTTY) return;
+
+    const o = opts || {};
+    const now = o.now instanceof Date ? o.now : new Date();
+    const registryUrl = typeof o.registryUrl === 'string' ? o.registryUrl : REGISTRY_URL;
+    const cachePath = typeof o.cachePath === 'string' ? o.cachePath : defaultCachePath();
+    const installed = typeof o.packageVersion === 'string'
+      ? o.packageVersion
+      : defaultPackageVersion();
+
+    if (!isValidSemver(installed)) return;
+
+    const cache = readCache(cachePath);
+    if (cache && cache.lastCheckedAt) {
+      const lastMs = Date.parse(cache.lastCheckedAt);
+      if (Number.isFinite(lastMs) && now.getTime() - lastMs < TTL_MS) {
+        return;
+      }
+    }
+
+    const latest = await fetchLatest(registryUrl);
+    if (!isValidSemver(latest)) return;
+
+    writeCache(cachePath, {
+      version: CACHE_VERSION,
+      lastCheckedAt: now.toISOString(),
+      lastSeenLatest: latest,
+      installedAtCheck: installed,
+    });
+
+    if (compareSemver(installed, latest) >= 0) return;
+
+    console.log(
+      '\x1b[33m[hint]\x1b[0m TermDeck v' +
+        latest +
+        ' available — upgrade with: npm install -g ' +
+        PACKAGE_NAME +
+        '@latest'
+    );
+    console.log(
+      '       Or run `termdeck doctor` for the whole stack. ' +
+        'Suppress with TERMDECK_NO_UPDATE_CHECK=1.'
+    );
+  } catch {
+    // Never throw from a fire-and-forget hook.
+  }
+}
+
+module.exports = {
+  checkAndPrintHint,
+  // Exported for unit testing only — not part of the public contract.
+  _internal: { compareSemver, isValidSemver, readCache, writeCache, CACHE_VERSION, TTL_MS },
+};