baldart 3.10.0 → 3.13.0

package/framework/docs/UPGRADE-3.12-UI-COHERENCE.md

@@ -0,0 +1,268 @@
+# Upgrade to v3.12.0 — UI Excellence & Registry Coherence
+
+> **Audience**: Claude (or a human operator) working inside a **consumer
+> repo** (any project that installed BALDART via `npx baldart add` and just
+> ran `npx baldart update` to v3.12.0). This document is the alignment
+> walkthrough — it does not replace the CHANGELOG (which describes *what*
+> changed in the framework); it tells you *what to do* in this specific
+> project to align an existing graphic organization with the new discipline.
+>
+> Run this once per project after updating to v3.12.0. It is idempotent —
+> re-running on an already-aligned project produces an empty backlog.
+
+## What changed in one paragraph
+
+The `ui-expert` agent received a major upgrade (UI states taxonomy,
+Performance Gates, modern CSS, AI-era patterns, 60+ categorized red flags),
+and the registry-first discipline gained a **post-intervention coherence
+gate**: every UI task that introduces, modifies, or surfaces a primitive or
+token must reconcile the registry (`INDEX.md` + `components/<Name>.md` +
+`tokens-reference.md`) **in the same change**. Drift can no longer wait for
+Monday's `ds-drift` routine — it must be resolved at introduction. Three
+layers now enforce coherence: per-task (in `ui-expert` / `ui-design` /
+`frontend-design`) → per-merge (`code-reviewer`) → weekly safety net
+(`ds-drift`). The full text-of-record lives in
+`.framework/framework/agents/design-system-protocol.md` § "Post-Intervention
+Coherence Check".
+
+## Step 0 — Should you even run this walkthrough?
+
+Run only if all three are true. Otherwise, exit cleanly.
+
+```
+[ ] baldart.config.yml has features.has_design_system: true
+[ ] paths.design_system points to an existing directory
+[ ] That directory contains at least an INDEX.md
+```
+
+If `has_design_system: false` → there is nothing to align. The new gates
+short-circuit. Optionally consider bootstrapping a registry via
+`/design-system-init` (skill ships with v3.11.0+).
+
+If `has_design_system: true` but `paths.design_system` does not exist or is
+empty → run `/design-system-init` first; come back to this walkthrough
+after.
+
+## Step 1 — Surface the current state (no edits yet)
+
+Before touching anything, build a snapshot. Do the four scans below and
+emit one finding per item. **Do not fix anything yet** — fixing without a
+baseline produces churn and hides the size of the gap.
+
+### 1.1 — Silent primitives (`DS_INDEX_DRIFT` baseline)
+
+Goal: find components that exist in the source tree but are NOT documented
+in `INDEX.md`.
+
+```bash
+# List candidate primitives in the project (adjust glob to match the project)
+find $(yq '.paths.components_primitives' baldart.config.yml) \
+  -maxdepth 2 -type f \( -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" \)
+```
+
+For each filename `<Name>.tsx`, grep `INDEX.md` for `<Name>` (case-sensitive).
+Anything not found is a silent primitive. Record name + path + estimated
+broadness (broadly-useful vs. surface-specific). Output:
+
+```
+SILENT_PRIMITIVES:
+  - Badge        | components/ui/Badge.tsx       | broadly-useful
+  - PriceTag     | components/marketing/Price.tsx | surface-specific
+  ...
+```
+
+### 1.2 — Stale specs (`DS_COMPONENT_STALE` baseline)
+
+For each `${paths.design_system}/components/<Name>.md`:
+
+1. Locate the source file for `<Name>`.
+2. Compare the spec's documented props/variants against the source's actual
+   exported types/props. Use `codebase-architect` if the project has LSP
+   enabled — it does this cheaply via go-to-definition.
+3. Spec older than the source's last edit in git AND with mismatch on
+   props/variants → `DS_COMPONENT_STALE`.
+
+```
+STALE_SPECS:
+  - Button.md   | source mtime 2026-04-12, spec mtime 2026-01-05
+                | spec missing variants: "danger-outline", "icon-only"
+                | spec missing prop: leftIcon
+  ...
+```
+
+### 1.3 — Hardcoded tokens (`DS_TOKENS_DRIFT` baseline)
+
+Scan the codebase for values that bypass `tokens-reference.md`:
+
+```bash
+# Hardcoded hex/rgb in styled code (adjust path to actual sources)
+grep -RInE '#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)' \
+  $(yq '.paths.components_root' baldart.config.yml) \
+  --include='*.tsx' --include='*.css' --include='*.scss'
+
+# Hardcoded box-shadow tuples
+grep -RInE 'box-shadow:\s*[^v;]+;' \
+  $(yq '.paths.components_root' baldart.config.yml)
+
+# Spacing values outside the scale (heuristic: any odd or > 64 px literal)
+grep -RInE '(padding|margin|gap|inset)[^:]*:\s*[0-9]+px' \
+  $(yq '.paths.components_root' baldart.config.yml)
+```
+
+For each hit, classify:
+- **Tokenizable** — exact value matches an existing token → trivial replace
+- **Missing token** — value would belong to the system but no token exists →
+  propose adding to `tokens-reference.md`
+- **Justified one-off** — surface-specific value with a documented reason →
+  leave + add a code comment citing the exception
+
+```
+HARDCODED_TOKENS:
+  - tokenizable:      37 hits across 12 files
+  - missing-token:    8 hits (suggest 3 new tokens)
+  - justified-one-off: 2 hits
+```
+
+### 1.4 — Overlay drift (only if `.baldart/overlays/ui-expert.md` exists)
+
+The v3.12.0 base `ui-expert.md` now defines authoritatively things the
+overlay may have previously codified. Likely conflict points:
+
+| Overlay section likely to conflict | Why |
+|---|---|
+| Custom "Red Flags" list | Base now has 60+ categorized red flags — overlay items may be duplicates or contradictions |
+| Custom workflow steps | Base now has step 10 (Review) and step 12 (Design) as BLOCKING completion gates — overlay must not skip them |
+| Custom token rules | Base now references the Reference Tables in `design-system-protocol.md` — overlay numeric scales should defer to the protocol |
+| Custom motion guidance | Base now delegates to `motion-design` skill — overlay should point there, not redefine durations/easings |
+
+Read `.baldart/overlays/ui-expert.md` and report each section that:
+- Uses `## [OVERRIDE]` marker on a section the base now owns
+  authoritatively (red flags, workflow steps, expertise enumeration).
+- Uses `## [APPEND]` to add red flags that are now in the base set
+  (duplicates).
+- Hardcodes scales / thresholds / durations the new protocol tables now
+  declare canonically.
+
+Output:
+
+```
+OVERLAY_DRIFT:
+  - [OVERRIDE] Your Expertise — conflicts with expanded base (consider [APPEND] instead)
+  - [APPEND]   Red Flags — 4 of 6 items now in base list (deduplicate)
+  - hardcoded  motion duration 250ms — defer to motion-design timing tables
+```
+
+### 1.5 — Emit the baseline report
+
+Save the four sections above as:
+
+```
+${paths.references_dir:-docs/references}/ds-coherence-baseline-YYYYMMDD.md
+```
+
+Present a short summary to the user (totals per finding type + estimated
+size of the reconciliation work). **Stop here for user confirmation** before
+proceeding to Step 2.
+
+## Step 2 — Prioritize reconciliation
+
+Not all findings are equal. Rank them so the user gets quick wins first.
+
+| Priority | Criteria | Action |
+|---|---|---|
+| **P0** | Silent primitive used in ≥ 3 places AND broadly-useful | Add INDEX entry + scaffold full `components/<Name>.md` spec |
+| **P0** | Hardcoded token (tokenizable) in the design-system entry-point file or in a primitive | Replace with the existing token reference inline |
+| **P1** | Silent primitive used in 1–2 places, broadly-useful | Add INDEX entry + stub spec (`status: needs-review`) |
+| **P1** | Stale spec on a primitive used by ≥ 3 features | Update spec to match source |
+| **P1** | Missing-token (hardcoded value that should be a token) used > 5 times | Propose new token + update `tokens-reference.md` + replace inline |
+| **P2** | Surface-specific silent primitive | Add INDEX entry with `scope: local` + 2-line note |
+| **P2** | Stale spec on a rarely-used primitive | Update spec OR open follow-up card |
+| **P3** | Justified one-off hardcoded value | Add inline code comment citing the exception |
+| **P3** | Overlay-base conflict that does not break the new gates | Refactor overlay to use `[APPEND]` instead of `[OVERRIDE]` |
+
+Convert the prioritized findings into the project's backlog format. If
+`features.has_backlog: true`:
+
+- One card per P0 item.
+- One card per **group** of P1 items (e.g. "Reconcile 8 stale specs in
+  `components/forms/`").
+- One catch-all card for P2/P3 batched cleanup.
+
+If no backlog feature → emit a markdown checklist under
+`${paths.references_dir}/ds-coherence-followups-YYYYMMDD.md` and present it
+to the user.
+
+## Step 3 — Quick wins (apply now, with user approval)
+
+Apply only the items that are **truly trivial and reversible**:
+
+- Inline replacement of `tokenizable` hardcoded values (the token already
+  exists; the change is a pure substitution).
+- Adding INDEX entries for surface-specific silent primitives (no spec
+  needed beyond the scope: local note).
+- Removing overlay `[APPEND]` items that exactly duplicate the new base
+  red flags.
+
+Group them in **one commit per category** (`chore(ds): replace hardcoded
+tokens with existing references`, `docs(ds): index surface-specific
+primitives`, etc.) so the diff is reviewable.
+
+Anything more substantial (new specs, new tokens, overlay refactors, stale
+spec updates) → backlog cards, not inline edits. Resist the urge to "just
+clean it up while you're there" — that turns the alignment into a
+multi-day refactor.
+
+## Step 4 — Verify the new gates fire correctly
+
+After the quick wins land, pick **one** small UI task that touches a
+primitive (e.g. add a variant to an existing Button) and run it end-to-end:
+
+1. Invoke `ui-expert` or the relevant skill.
+2. Make the code change.
+3. Observe that the agent's final output explicitly reports the
+   Post-Intervention Coherence Check result — either "no findings" or one
+   of the `DS_*_DRIFT` codes.
+
+If the agent silently skips this step → the upgrade didn't propagate to
+this project. Check:
+
+- `npx baldart status` confirms v3.12.0 installed.
+- `.framework/framework/agents/design-system-protocol.md` contains the
+  "Post-Intervention Coherence Check" section.
+- `.framework/framework/.claude/agents/ui-expert.md` has step 10 (Review)
+  and step 12 (Design).
+
+If any of those is stale → `npx baldart update` again, then re-test.
+
+## Step 5 — Establish the rhythm
+
+Going forward, the operator (you, or future Claude instances on this
+project):
+
+- Treats the coherence check at end-of-task as **non-negotiable**, same
+  category as "tests pass". A UI task without the coherence-check report
+  is incomplete.
+- Treats `DS_*_DRIFT` findings surfaced by `code-reviewer` as merge
+  blockers — they indicate the upstream check was skipped.
+- Reads the weekly `ds-drift` routine report when it lands and treats any
+  finding there as a **process bug** (somewhere the upstream gates were
+  bypassed), not just a content fix.
+
+## Reference points (resolved by `npx baldart update`)
+
+After update, these files exist locally and are authoritative:
+
+| Concern | File |
+|---|---|
+| What "coherence check" means + decision matrix | `.framework/framework/agents/design-system-protocol.md` § "Post-Intervention Coherence Check" |
+| Numeric reference tables (type / contrast / spacing / density) | `.framework/framework/agents/design-system-protocol.md` § "Reference Tables (embed)" |
+| Token cascade primitive → semantic → component | `.framework/framework/agents/design-system-protocol.md` § "Token Cascade" |
+| Upgraded `ui-expert` (states taxonomy, red flags, gates) | `.framework/framework/.claude/agents/ui-expert.md` |
+| Code-reviewer rule 8 (merge gate) | `.framework/framework/.claude/agents/code-reviewer.md` § "Design System Compliance" rule 8 |
+| `ui-design` Step H (design-time gate) | `.framework/framework/.claude/skills/ui-design/SKILL.md` |
+| Performance Gates (CWV 2026, LCP/INP/CLS) | `.framework/framework/.claude/skills/frontend-design/SKILL.md` § "Performance Gates" |
+| Motion + reduced-motion + View Transitions | `.framework/framework/.claude/skills/motion-design/reference/accessibility-and-modern-apis.md` |
+| Weekly safety net | `.framework/framework/routines/ds-drift.routine.yml` |
+
+The framework files are symlinked, so reading them via the paths above
+gets the live, current version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "3.10.0",
+  "version": "3.13.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"

package/src/commands/configure.js

@@ -522,6 +522,27 @@ async function interactivePrompts(merged, detected) {
     merged.features[key] = await promptForKey(question, proposedDefault, 'confirm');
   }
 
+  // ---- Design-system bootstrap hint (since v3.11.0) ---------------------
+  // If the user said YES to has_design_system but autodetect found no path
+  // (i.e. they WANT a registry but it doesn't exist yet), surface the
+  // bootstrap skill so they don't end up with a flag that points at nothing.
+  // If they said NO, plant a soft pointer for the future.
+  if (merged.features.has_design_system === true && !detected.paths.design_system) {
+    UI.info(
+      'No design-system path was detected on disk. After configure, run\n' +
+      '  /design-system-init  (or invoke the skill)\n' +
+      'to scaffold INDEX.md + tokens-reference.md + per-component specs at\n' +
+      'docs/design-system/. The registry-first protocol (ui-expert, ui-design,\n' +
+      'frontend-design, /design-review) needs these files to enforce coherence.'
+    );
+  } else if (merged.features.has_design_system === false) {
+    UI.info(
+      'has_design_system=false — UI work will rely only on ui_guidelines.md.\n' +
+      'When you want visual coherence + component reuse enforced project-wide,\n' +
+      'run /design-system-init to scaffold a registry from your existing code.'
+    );
+  }
+
   // Path prompts — only ask for paths whose feature is enabled and value missing
   UI.section('Paths (autodetected — confirm or override)');
   const pathPrompts = [

package/src/commands/doctor.js

@@ -31,6 +31,8 @@ const UI = require('../utils/ui');
 const State = require('../utils/state');
 const Hooks = require('../utils/hooks');
 const LspInstaller = require('../utils/lsp-installer');
+const UpdateNotifier = require('../utils/update-notifier');
+const cliPackageJson = require('../../package.json');
 
 const FRAMEWORK_DIR = '.framework';
 const REPO_DEFAULT = 'antbald/BALDART';
@@ -146,6 +148,8 @@ async function detectState(cwd, opts = {}) {
   const git = new GitUtils(cwd);
   const state = {
     cwd,
+    cliVersion: cliPackageJson.version,
+    cliUpdate: UpdateNotifier.hint({ currentVersion: cliPackageJson.version }),
     isGitRepo: await git.isGitRepo(),
     frameworkPresent: await git.frameworkExists(),
     legacyLayout: false,
@@ -188,6 +192,19 @@ async function detectState(cwd, opts = {}) {
       ? `v${ledger.last_pushed_version} (${(ledger.last_push_date || '').slice(0, 10) || '—'})`
       : null;
 
+    // Ledger drift detection (v3.13.0+): the framework on disk says one thing,
+    // the ledger says another. Caused by interrupted updates, manual commits
+    // that excluded state.json, or filesystem write failures the old silent
+    // catch in update.js used to hide. Self-healable via `reconcile-state-ledger`.
+    state.stateLedgerDrift = null;
+    if (state.frameworkVersion && ledger.installed_version &&
+        state.frameworkVersion !== ledger.installed_version) {
+      state.stateLedgerDrift = {
+        payload: state.frameworkVersion,
+        ledger: ledger.installed_version
+      };
+    }
+
     state.remote = await describeRemote(git, ledger.framework_repo || REPO_DEFAULT, !!opts.offline);
     state.commitsAhead = await commitsAheadOfRemote(git);
     state.workingTreeDirty = await localFrameworkChanges(git);
@@ -313,6 +330,28 @@ function planActions(state) {
     // Drift is non-blocking — keep checking for other actions after.
   }
 
+  if (state.stateLedgerDrift) {
+    actions.push({
+      key: 'reconcile-state-ledger',
+      label: `Reconcile state ledger (${state.stateLedgerDrift.ledger} → ${state.stateLedgerDrift.payload})`,
+      why: `.framework/VERSION is v${state.stateLedgerDrift.payload} but .baldart/state.json records installed_version=${state.stateLedgerDrift.ledger}. Typical causes: an update flow that exited mid-way (configure declined, stash conflict), a manual commit that excluded .baldart/state.json, or a write failure that the old silent catch in update.js used to hide (fixed in v3.13.0).`,
+      autoOk: true, // pure local file write, idempotent, fully reversible
+      run: () => {
+        const res = State.reconcileInstalledVersion({
+          to: state.stateLedgerDrift.payload,
+          reason: 'doctor reconcile — payload/ledger drift'
+        });
+        if (res.changed) {
+          UI.success(`Ledger updated: installed_version ${res.from} → ${res.to}`);
+          UI.info('History entry "ledger-reconcile" recorded for audit. Commit .baldart/state.json when ready.');
+        } else {
+          UI.info('No change needed — ledger already matches payload.');
+        }
+      },
+    });
+    // Drift is non-blocking — keep checking for other actions after.
+  }
+
   if (state.editGateRegistered === false) {
     actions.push({
       key: 'register-edit-gate',
@@ -394,6 +433,17 @@ function renderDiagnostic(state) {
   console.log(`Repository:    ${state.cwd}`);
   console.log();
 
+  // CLI version line — always shown (independent of git repo state). When a
+  // newer baldart npm package was detected on a previous run, surface it here
+  // so the doctor table is the single pane of glass for "what's stale".
+  console.log(statusLine(
+    'CLI',
+    state.cliUpdate
+      ? `v${state.cliVersion} → v${state.cliUpdate.latest} available (npm i -g baldart@latest)`
+      : `v${state.cliVersion}`,
+    state.cliUpdate ? 'warn' : 'ok'
+  ));
+
   console.log(statusLine('Git repo', state.isGitRepo ? 'yes' : 'no', state.isGitRepo ? 'ok' : 'err'));
 
   if (!state.isGitRepo) return;
@@ -429,9 +479,11 @@ function renderDiagnostic(state) {
   console.log(statusLine(
     'State ledger',
     state.statePresent
-      ? `installed v${state.stateInstalled} (${fmtDate(state.stateInstallDate)})`
+      ? (state.stateLedgerDrift
+          ? `drift: ledger=v${state.stateLedgerDrift.ledger}, payload=v${state.stateLedgerDrift.payload}`
+          : `installed v${state.stateInstalled} (${fmtDate(state.stateInstallDate)})`)
       : 'not seeded',
-    state.statePresent ? 'ok' : 'warn'
+    state.stateLedgerDrift ? 'warn' : (state.statePresent ? 'ok' : 'warn')
   ));
 
   if (state.stateLastUpdate) {

package/src/commands/update.js

@@ -246,7 +246,21 @@ async function update(options = {}) {
 
       newVersion = await git.getFrameworkVersion();
       UI.success(`New version: ${newVersion}`);
-      try { State.recordUpdate({ from: currentVersion, to: newVersion }); } catch (_) { /* non-fatal */ }
+      // Update the ledger and VERIFY the write landed. Prior to v3.13.0 this
+      // call used a silent catch — write failures (permissions, EBUSY) were
+      // hidden, and the user only noticed the drift weeks later via doctor.
+      // Now: visible warning + always-actionable next step.
+      try {
+        const after = State.recordUpdate({ from: currentVersion, to: newVersion });
+        if (after.installed_version !== newVersion) {
+          UI.warning(`Ledger write returned installed_version=${after.installed_version}, expected ${newVersion}.`);
+          UI.info('Run `baldart doctor` to reconcile the ledger.');
+        }
+      } catch (err) {
+        UI.warning(`Could not write .baldart/state.json: ${err.message}`);
+        UI.info(`Framework on disk is at v${newVersion} but the ledger still records v${currentVersion}.`);
+        UI.info('Run `baldart doctor` to reconcile, or check filesystem permissions on .baldart/state.json.');
+      }
 
       // Re-apply the pre-update stash (if any). Conflicts mean we leave the
       // stash intact and tell the user how to resolve — never silently drop.

package/src/commands/version.js

@@ -1,6 +1,7 @@
 const GitUtils = require('../utils/git');
 const UI = require('../utils/ui');
 const State = require('../utils/state');
+const UpdateNotifier = require('../utils/update-notifier');
 
 const REPO_DEFAULT = 'antbald/BALDART';
 const FRAMEWORK_DIR = '.framework';
@@ -48,6 +49,7 @@ async function version(opts = {}) {
     const frameworkVersion = await git.getFrameworkVersion();
     const state = State.load();
     const cliVersion = require('../../package.json').version;
+    const cliUpdate = UpdateNotifier.hint({ currentVersion: cliVersion });
 
     // Optionally fetch upstream to compute drift (default: yes).
     const offline = opts.offline === true;
@@ -75,7 +77,9 @@ async function version(opts = {}) {
       `Last update: ${fmtDate(state.last_update_date)}`,
       `Last push:   v${state.last_pushed_version || '—'}    ${state.last_push_date ? `(${fmtDate(state.last_push_date)})` : ''}`.trim(),
       '',
-      `CLI:         v${cliVersion}`,
+      cliUpdate
+        ? `CLI:         v${cliVersion} → v${cliUpdate.latest} available (npm i -g baldart@latest)`
+        : `CLI:         v${cliVersion}`,
       `Repository:  https://github.com/${state.framework_repo || REPO_DEFAULT}`,
     ].filter((l) => l !== ''));
     UI.newline();

package/src/utils/state.js

@@ -106,6 +106,32 @@ function recordUpdate({ from, to }, cwd = process.cwd()) {
   return state;
 }
 
+/**
+ * Reconcile the ledger's installed_version with the actual framework version
+ * on disk (read from .framework/VERSION). Used by `baldart doctor` when it
+ * detects a mismatch between the payload and the ledger — typically caused by
+ * an interrupted update flow, a manual commit that excluded state.json, or a
+ * filesystem write failure that the silent catch in update.js used to hide.
+ *
+ * Idempotent: calling with the already-current version is a no-op (no history
+ * entry produced). History entry uses event "ledger-reconcile" so the source
+ * of the bump is auditable separately from real updates.
+ */
+function reconcileInstalledVersion({ to, reason }, cwd = process.cwd()) {
+  const state = load(cwd);
+  const from = state.installed_version;
+  if (from === to) return { state, changed: false };
+  state.installed_version = to;
+  state.history = appendHistory(state, {
+    event: 'ledger-reconcile',
+    from,
+    to,
+    note: reason || 'reconcile ledger with .framework/VERSION'
+  });
+  save(state, cwd);
+  return { state, changed: true, from, to };
+}
+
 function recordPush({ from, to, description }, cwd = process.cwd()) {
   const state = load(cwd);
   state.last_pushed_version = to;
@@ -137,6 +163,7 @@ module.exports = {
   recordInstall,
   recordUpdate,
   recordPush,
+  reconcileInstalledVersion,
   readFrameworkVersion,
   STATE_FILE,
   STATE_VERSION,

package/src/utils/update-notifier.js

@@ -0,0 +1,181 @@
+/**
+ * CLI self-update notifier (v3.13.0+).
+ *
+ * The framework payload inside `.framework/` is updated by `baldart update`.
+ * The CLI itself (this package) is updated by `npm i -g baldart@latest`.
+ * Until now those two layers drifted silently — users on an old CLI never
+ * learned new flags, new doctor checks, new adapters had shipped.
+ *
+ * This module surfaces CLI drift WITHOUT auto-installing anything. It is
+ * deliberately non-invasive:
+ *
+ *   - Best-effort HTTP check against the npm registry with a short timeout.
+ *   - Result cached at `~/.baldart/cli-update-check.json` (TTL 24h).
+ *   - Banner printed from the cache on the NEXT invocation (zero latency on
+ *     every run). First-ever run shows nothing — that's intentional.
+ *   - Suppressed in CI, non-TTY, --offline, NODE_ENV=test, or via
+ *     BALDART_NO_UPDATE_CHECK=1.
+ *   - Never blocks the process: the background refresh is fire-and-forget,
+ *     its timer/socket are unref'd so they cannot hold the event loop open.
+ *
+ * Design rationale (see CHANGELOG v3.13.0): we explicitly DO NOT run
+ * `npm i -g baldart@latest` automatically. Auto-updates inside a per-project
+ * CLI invocation would (a) impact every other project on the user's machine,
+ * (b) potentially require sudo, (c) break determinism in CI runs. The banner
+ * gives the user the choice; the cache means they don't pay for it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const REGISTRY_URL = 'https://registry.npmjs.org/baldart/latest';
+const CACHE_DIR = path.join(os.homedir(), '.baldart');
+const CACHE_FILE = path.join(CACHE_DIR, 'cli-update-check.json');
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const DEFAULT_TIMEOUT_MS = 1500;
+
+function isSuppressed({ offline } = {}) {
+  if (offline) return true;
+  if (process.env.BALDART_NO_UPDATE_CHECK === '1') return true;
+  if (process.env.CI === 'true' || process.env.CI === '1') return true;
+  if (process.env.NODE_ENV === 'test') return true;
+  // `process.stdout.isTTY` is `true` when attached to a terminal and
+  // `undefined` (NOT `false`) when not — so we must test for "not strictly
+  // true" rather than "=== false", otherwise piped/redirected runs silently
+  // bypass suppression.
+  if (!(process.stdout && process.stdout.isTTY === true)) return true;
+  return false;
+}
+
+function readCache() {
+  try {
+    if (!fs.existsSync(CACHE_FILE)) return null;
+    const data = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    if (!data || typeof data !== 'object') return null;
+    return data;
+  } catch (_) {
+    return null;
+  }
+}
+
+function writeCache(data) {
+  try {
+    if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, { recursive: true });
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(data, null, 2) + '\n');
+  } catch (_) {
+    // Best-effort: a read-only HOME or denied write is not worth surfacing.
+  }
+}
+
+function cmpSemver(a, b) {
+  // Returns 1 if a>b, -1 if a<b, 0 if equal. Strips prerelease and build
+  // metadata; only X.Y.Z is compared. That is enough for a "is there a newer
+  // stable on npm?" prompt — anything fancier belongs in `semver`, and we are
+  // deliberately staying dep-free here.
+  if (!a || !b) return 0;
+  const norm = (v) => String(v).split(/[-+]/)[0].split('.').map((n) => Number(n) || 0);
+  const pa = norm(a);
+  const pb = norm(b);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0, y = pb[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+async function fetchLatest(timeoutMs) {
+  if (typeof fetch !== 'function') return null; // Node < 18 fallback — node engine constraint covers this, but defensive.
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  if (typeof timer.unref === 'function') timer.unref();
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      signal: ctrl.signal,
+      headers: { Accept: 'application/json' },
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body && body.version ? String(body.version) : null;
+  } catch (_) {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function refresh({ currentVersion, timeoutMs = DEFAULT_TIMEOUT_MS, force = false } = {}) {
+  const cached = readCache();
+  const now = Date.now();
+  if (!force && cached && cached.checked_at) {
+    const age = now - new Date(cached.checked_at).getTime();
+    if (Number.isFinite(age) && age < DEFAULT_TTL_MS) return cached;
+  }
+  const latest = await fetchLatest(timeoutMs);
+  if (!latest) return cached; // Keep stale cache rather than zeroing it.
+  const data = {
+    checked_at: new Date().toISOString(),
+    latest,
+    current_at_check: currentVersion,
+  };
+  writeCache(data);
+  return data;
+}
+
+function hint({ currentVersion } = {}) {
+  if (!currentVersion) return null;
+  const cached = readCache();
+  if (!cached || !cached.latest) return null;
+  if (cmpSemver(cached.latest, currentVersion) <= 0) return null;
+  return {
+    latest: cached.latest,
+    current: currentVersion,
+    checked_at: cached.checked_at,
+  };
+}
+
+function printBanner(info) {
+  if (!info) return;
+  const chalk = require('chalk');
+  const line1 = chalk.yellow('↑') + ' ' + chalk.bold(`baldart ${info.latest}`) +
+    chalk.gray(` available (you have ${info.current})`);
+  const line2 = chalk.gray('  Update with: ') + chalk.cyan('npm i -g baldart@latest');
+  const line3 = chalk.gray('  Suppress with: BALDART_NO_UPDATE_CHECK=1');
+  console.log('');
+  console.log(line1);
+  console.log(line2);
+  console.log(line3);
+  console.log('');
+}
+
+function backgroundCheck({ currentVersion, offline = false } = {}) {
+  // Fire-and-forget. Returns immediately; never throws; cannot block exit.
+  if (isSuppressed({ offline })) return;
+  refresh({ currentVersion }).catch(() => {});
+}
+
+/**
+ * Cheap entry point for bin/baldart.js: print the banner if a cached update
+ * is known, then kick off a refresh for next time. No-op when suppressed.
+ */
+function announceAndRefresh({ currentVersion, offline = false } = {}) {
+  if (isSuppressed({ offline })) return null;
+  const info = hint({ currentVersion });
+  if (info) printBanner(info);
+  backgroundCheck({ currentVersion, offline });
+  return info;
+}
+
+module.exports = {
+  isSuppressed,
+  refresh,
+  hint,
+  printBanner,
+  backgroundCheck,
+  announceAndRefresh,
+  // Exported for tests / introspection:
+  _cmpSemver: cmpSemver,
+  _CACHE_FILE: CACHE_FILE,
+  _DEFAULT_TTL_MS: DEFAULT_TTL_MS,
+};