jeo-code 0.5.10 → 0.5.13

package/src/commands/launch.ts

@@ -1,7 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import { emitKeypressEvents } from "node:readline";
 import { PassThrough } from "node:stream";
-import { runAgentLoop, executorSystemPrompt, DEFAULT_TOOLS, TOOL_PROTOCOL, WORKING_DISCIPLINE, type AgentLoopEvents } from "../agent/engine";
+import { runAgentLoop, executorSystemPrompt, DEFAULT_TOOLS, TOOL_PROTOCOL, WORKING_DISCIPLINE, OUTPUT_DISCIPLINE, type AgentLoopEvents } from "../agent/engine";
 import { createOpikTracer, wrapEvents } from "../agent/opik-tracer";
 import { initialDynamicStepLimit } from "../agent/step-budget";
 import { memoryPromptSection, spawnDetachedDistill } from "../agent/memory";
@@ -27,6 +27,7 @@ import { renderWelcome, playWelcomeSweep } from "../tui/components/welcome";
 import { checkForUpdate, readUpdateCache, writeUpdateCache } from "../util/update-check";
 import { jeoEnv } from "../util/env";
 import { renderUpdateBox } from "../tui/components/update-box";
+import { consumeLaunchWhatsNew } from "../util/whats-new";
 import { supportsUnicode } from "../tui/components/capability";
 import pkg from "../../package.json";
 import chalk from "chalk";
@@ -498,6 +499,16 @@ interface AbortHarnessOptions {
 export const PASTE_START = "\u001b[200~";
 export const PASTE_END = "\u001b[201~";
 
+/** True when a stdin chunk is ONLY backspace bytes (DEL 0x7f or BS 0x08) — i.e. a
+ *  standalone Backspace keystroke with nothing else. A backspace on an EMPTY input
+ *  line is a no-op edit, but some Bun readline builds turn it into a spurious `close`
+ *  event, which the REPL would treat as a hard exit ("Backspace quits jeo"). The
+ *  input filter swallows these when the line buffer is already empty so the byte never
+ *  reaches readline and the close can't fire. */
+export function isStandaloneBackspace(chunk: string): boolean {
+  return chunk.length > 0 && /^[\x7f\b]+$/.test(chunk);
+}
+
 export interface PromptInputQueue {
   pendingLines: string[];
   partial: string;
@@ -963,6 +974,7 @@ export function buildToolProtocol(allowedTools: Set<string>): string {
   lines.push("Reply with STRICT JSON only — no code fences. You MAY include an optional leading");
   lines.push('"reasoning" string (one short sentence on your plan, shown live to the user) before "tool":');
   lines.push('{ "reasoning": "<one short sentence>", "tool": "<name>", "arguments": { ... } }');
+  lines.push("Tool calibration: scale calls to difficulty — one for a known fact, a few for a normal task, more only when evidence is genuinely missing. Locate before you open: search/find first, then read the hit, instead of guessing paths.");
   return lines.join("\n");
 }
 
@@ -1180,14 +1192,28 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
 
   const workflowSkills = workflowSkillsForPrompt(resolvedSkills);
   const resolvedSkillNames = resolvedSkills.map(s => s.name);
-  const skillSlashDetails: SlashCommandInfo[] = resolvedSkills.flatMap(skill =>
-    skillSlashAliases(skill).map(alias => ({
+  // Bundled workflows are first-class `/name` commands (deep-interview/ralplan/team/
+  // ultragoal), surfaced in the `/` menu even when their SKILL.md self-references no
+  // slash token — `parseSkillInvocation` dispatches `/name` by skill name. Aliases the
+  // SKILL.md does declare are listed too (deduped, case-insensitive).
+  const WORKFLOW_SLASH_NAMES = ["deep-interview", "ralplan", "team", "ultragoal"];
+  const skillSlashDetails: SlashCommandInfo[] = resolvedSkills.flatMap(skill => {
+    const aliases = skillSlashAliases(skill);
+    const nameSlash = WORKFLOW_SLASH_NAMES.includes(skill.name) ? [`/${skill.name}`] : [];
+    const seen = new Set<string>();
+    const commands = [...nameSlash, ...aliases].filter(a => {
+      const k = a.toLowerCase();
+      if (seen.has(k)) return false;
+      seen.add(k);
+      return true;
+    });
+    return commands.map(alias => ({
       command: alias,
       usage: `${alias} [intent]`,
       description: `Run ${skill.name} skill${skill.summary ? ` — ${skill.summary}` : ""}`,
       group: "skills" as const,
-    })),
-  );
+    }));
+  });
 
   const protocol = buildToolProtocol(allowedTools);
   const preamble = flags.systemPrompt ?? "You are the jeo, an interactive coding agent.\nAccomplish the user's request by calling tools and verifying your work.";
@@ -1197,7 +1223,8 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   const baseSystemPrompt =
     preamble + "\n\n" + protocol + "\n\n" +
     WORKING_DISCIPLINE + "\n\n" +
-    "Always verify (run tests / execute the program) before calling done." +
+    OUTPUT_DISCIPLINE + "\n\n" +
+    "Before calling done, self-check: did I run the test or command that exercises this change, are directly-affected callsites/tests/docs updated, and does my claim match real output? If any answer is no, keep working — do not call done." +
     "\nWhen you have finished the user's request, or need to reply to or ask the user something, call done with {\"reason\": <your natural-language reply to the user>}. The reason text is shown to the user as your message." +
     (allowedTools.has("task") ? "\n\nDelegation: " + taskToolProtocolLine(cfg) +
     " Call task with {\"role\": <one of the advertised roles>, \"task\": <assignment>, \"context\": <optional>} to hand a focused slice to a subagent." : "") +
@@ -1770,6 +1797,17 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   };
   showUpdateBanner(await readUpdateCache(pkg.version));
   showUpdateBanner(await Promise.race([updatePromise, new Promise<null>(r => setTimeout(() => r(null), 1200))]));
+  // First launch after a version bump: surface the bundled release notes ONCE
+  // (offline, from the new package's CHANGELOG.md) and record the seen version
+  // so it never repeats. Screen-safe: prints BEFORE the prompt is armed.
+  try {
+    const whatsNew = await consumeLaunchWhatsNew({
+      cols: Math.min(100, Math.max(40, (process.stdout.columns ?? 80) - 2)),
+      unicode: supportsUnicode(),
+      color: welcomeTheme.color,
+    });
+    if (whatsNew && whatsNew.length) console.log(whatsNew.join("\n"));
+  } catch { /* release notes are a courtesy; never block launch */ }
   if (!LaunchTui.usable(flags.noTui)) console.log("(plain output)");
 
   const useTui = LaunchTui.usable(flags.noTui);
@@ -1954,6 +1992,9 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     for (const off of promptListenerCleanups.splice(0)) { try { off(); } catch { /* best effort */ } }
   };
   let keyFilter: PassThrough | undefined;
+  // Holder for the active readline so the input filter can see the current line
+  // buffer (used by the empty-line backspace guard below). Set after rl is created.
+  let activeRl: { line?: string } | undefined;
   if (multilineInput) {
     const kf = new PassThrough();
     (kf as unknown as { isTTY: boolean }).isTTY = true;
@@ -1975,6 +2016,11 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     let kfInPaste = false;
     const kfDataHandler = (chunk: Buffer) => {
       const data = chunk.toString("utf8");
+      // Empty-line Backspace guard: a standalone Backspace with nothing to delete is a
+      // no-op, but some Bun readline builds emit a spurious `close` for it — which the
+      // REPL treats as a hard exit. Drop it before it reaches readline. (Inside a paste,
+      // or with text in the buffer, backspace is forwarded normally so editing works.)
+      if (!kfInPaste && isStandaloneBackspace(data) && !(activeRl?.line ?? "")) return;
       let out = "";
       let i = 0;
       while (i < data.length) {
@@ -2015,6 +2061,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     output: gatedStdout(process.stdout, () => previewArmed || promptActive || pickerActive || interactiveTurnActive),
     completer: (line: string) => readlineCompleter(line, completionContext()),
   });
+  activeRl = rl; // wire the input filter's empty-line backspace guard to the live buffer
   const promptStdin = process.stdin as typeof process.stdin & { isRaw?: boolean; setRawMode?(raw: boolean): void };
   const promptWasRaw = !!promptStdin.isRaw;
   let promptRawChanged = false;

package/src/commands/whats-new.ts

@@ -0,0 +1,62 @@
+import pkg from "../../package.json";
+import {
+  loadBundledChangelog,
+  parseChangelogSections,
+  releaseSections,
+  renderWhatsNew,
+} from "../util/whats-new";
+import { supportsUnicode } from "../tui/components/capability";
+
+/** `jeo whats-new` — show the release notes bundled with the running version. */
+export async function runWhatsNewCommand(args: string[] = []): Promise<void> {
+  const isHelp = args.includes("--help") || args.includes("-h");
+  const hasAll = args.includes("--all");
+  const hasJson = args.includes("--json");
+
+  const KNOWN = new Set(["--all", "--json", "-h", "--help"]);
+  for (const arg of args) {
+    if (!KNOWN.has(arg)) {
+      console.log(`Unknown flag: ${arg}`);
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  if (isHelp) {
+    printUsage();
+    return;
+  }
+
+  const md = await loadBundledChangelog();
+  const all = md ? releaseSections(parseChangelogSections(md)) : [];
+  const sections = hasAll ? all : all.slice(0, 1);
+
+  if (hasJson) {
+    console.log(JSON.stringify({ version: pkg.version, entries: sections }, null, 2));
+    return;
+  }
+
+  if (sections.length === 0) {
+    console.log(`No release notes found for jeo-code ${pkg.version}.`);
+    return;
+  }
+
+  const cols = process.stdout.columns ?? 80;
+  console.log(renderWhatsNew(sections, {
+    cols: Math.min(100, Math.max(40, cols - 2)),
+    unicode: supportsUnicode(),
+    color: process.stdout.isTTY === true,
+  }).join("\n"));
+}
+
+function printUsage(): void {
+  console.log("Usage: jeo whats-new [options]");
+  console.log("");
+  console.log("Show the release notes bundled with the installed jeo-code version.");
+  console.log("");
+  console.log("Options:");
+  console.log("  --all        Show notes for every released version, not just the latest");
+  console.log("  --json       Output the notes as JSON");
+  console.log("  -h, --help   Show this help message");
+}

package/src/skills/catalog.ts

@@ -546,6 +546,14 @@ export function parseSkillInvocation(input: string, skills: SkillDoc[]): SkillIn
     }
   }
   let skill = getSkillBySlash(skills, command);
+  // `/team`, `/deep-interview`, `/ultragoal`, … — a bare slash + skill NAME (or unique
+  // prefix) is the SAME entrypoint as `$name` and `/skill:name`. Only when getSkillBySlash
+  // found no alias and the token is a plain `/word` (no nested `/path` and no `.` so
+  // `/speckit.plan` aliases and `./file` paths keep their own resolution). This is what
+  // makes the bundled workflows actually run from the `/` menu, not just `/ralplan`.
+  if (!skill && command.length > 1 && command.startsWith("/") && !command.includes(".") && command.indexOf("/", 1) === -1) {
+    skill = getSkillFrom(skills, command.slice(1)) ?? uniquePrefixSkill(skills, command.slice(1));
+  }
   if (!skill) {
     if (command.startsWith("/") || command.startsWith(".") || command.includes("/")) {
       const resolved = tryResolveSkillFromFilePath(command);

package/src/tui/app.ts

@@ -32,7 +32,7 @@ import { renderMarkdownTables } from "./components/markdown-table";
 import { stripMarkdown, renderMarkdownAnsi } from "./components/markdown-text";
 import { visibleWidth, wrapTextWithAnsi, truncateToWidth, sanitizeForFrame } from "./components/width";
 import { categoryBadge } from "./components/category-index";
-import { formatStepTimeline, stepsFromTools, formatStepHeader, formatStepTimelineCompact, type StepState } from "./components/step-timeline";
+import { formatStepTimeline, stepsFromTools, formatStepHeader, formatStepTimelineCompact, formatDuration as formatToolMs, type StepState } from "./components/step-timeline";
 import { formatHintBar } from "./components/hints";
 import { formatDuration, formatUsage } from "./components/duration";
 import { renderHud, derivePhase, type JeoPhase } from "./components/hud";
@@ -112,6 +112,12 @@ export const FRAME_WRAP_TAIL_CHARS = 16 * 1024;
 export function tailForWrap(text: string, maxChars = FRAME_WRAP_TAIL_CHARS): string {
   return text.length > maxChars ? text.slice(text.length - maxChars) : text;
 }
+
+/** Status animation palette while a tool/process runs (background verification): an
+ *  amber→yellow gradient, distinct from the cool thinking gradient, so "the agent is
+ *  running a process / verifying" reads at a glance (gjc parity: `theme.fg("warning")`
+ *  on the in-flight tool line). */
+export const STATUS_VERIFY_PALETTE = ["#ffd24a", "#ffb300"] as const;
 const DEFAULT_MAX_STEPS = 100;
 // Tools light enough that they never get a forge card (gjc parity): completion is a
 // single ✓/✗ ledger line; only failures surface a result card with the error body.
@@ -169,6 +175,8 @@ export class LaunchTui {
   private thinking = false;
   private hudPhase: JeoPhase = "thinking";
   private runningTool = false;
+  // When the current tool started (Date.now()); drives the result card's elapsed `(Nms)`.
+  private toolStartedAt = 0;
   // Latest transient provider notice (rate-limit auto-retry countdown); pinned into the
   // [STEP] status row while waiting so backoff is visible at a glance. Cleared on the
   // next step / model reply.
@@ -412,6 +420,7 @@ export class LaunchTui {
         this.streamingActivity = "";
         if (invocation && invocation.tool !== "done") {
           this.runningTool = true;
+          this.toolStartedAt = Date.now();
           this.hudPhase = "executing";
           const toolName = invocation.tool || "(no tool)";
           this.pendingIndex = this.tools.start(toolName);
@@ -464,6 +473,12 @@ export class LaunchTui {
         // tool checklist — no category/status badge clutter.
         const mark = this.unicode ? (success ? "✓" : "✗") : success ? "v" : "x";
         const paintedMark = this.theme.color ? (success ? chalk.green(mark) : chalk.red(mark)) : mark;
+        // gjc-parity timing detail: the completed card shows how long the tool ran,
+        // dim after the ✓/✗ glyph (e.g. `✓ Bash · (438ms)`).
+        const toolMs = this.toolStartedAt ? Date.now() - this.toolStartedAt : 0;
+        this.toolStartedAt = 0;
+        const durDim = this.theme.color ? chalk.dim : (s: string) => s;
+        const durSuffix = toolMs > 0 ? durDim(` ${this.unicode ? "·" : "-"} (${formatToolMs(toolMs)})`) : "";
         const result = summarizeForgeResult(tool, success, output);
         const card = this.pendingForge;
         this.pendingForge = null;
@@ -471,7 +486,7 @@ export class LaunchTui {
           // gjc-style single Bash card: command echo + `Output` divider + body + exit
           // note, under one ✓/✗-marked header — mutated in place so the live frame and
           // the non-TTY summary both show the merged card.
-          card.title = `${paintedMark} Bash`;
+          card.title = `${paintedMark} Bash${durSuffix}`;
           card.lines.push(...result.lines);
           this.flushForgeCard(card, success);
         } else if (card && t === "web_search" && success && webSearchCardLines(output, { unicode: this.unicode })) {
@@ -480,11 +495,11 @@ export class LaunchTui {
           // the structured tool output (provider chain — Anthropic native or the
           // keyless DuckDuckGo fallback).
           const ws = webSearchCardLines(output, { unicode: this.unicode })!;
-          card.title = `${paintedMark} Web Search: ${ws.titleMeta}`;
+          card.title = `${paintedMark} Web Search: ${ws.titleMeta}${durSuffix}`;
           card.lines = ws.lines;
           this.flushForgeCard(card, success);
         } else if (card) {
-          card.title = `${paintedMark} ${card.title}`;
+          card.title = `${paintedMark} ${card.title}${durSuffix}`;
           if (!success) this.rememberForge(result);
           this.flushForgeCard(card, success);
           if (!success) this.flushForgeCard(result, false);
@@ -492,7 +507,7 @@ export class LaunchTui {
           // Light tool: one ✓/✗ line, plus a dim result tree for list-shaped output
           // (find/search/ls) and an error card when the tool failed.
           const { suffix, children } = this.ledgerTree(tool, success, output);
-          this.appendLedger(`${paintedMark} ${target}${suffix}\n${children.map(c => `${c}\n`).join("")}`, "tool");
+          this.appendLedger(`${paintedMark} ${target}${suffix}${durSuffix}\n${children.map(c => `${c}\n`).join("")}`, "tool");
           if (!success) {
             this.rememberForge(result);
             this.flushForgeCard(result, false);
@@ -1164,12 +1179,16 @@ export class LaunchTui {
     // the ⟦esc⟧ cancel hint visible without trapping the message inside a border.
     if (isThinking) {
       const grad = themeGradient(this.theme, idx);
+      // While a tool/process runs (background verification), the status animation turns
+      // amber/yellow — distinct from the cool thinking gradient (gjc warning-color parity).
+      const verifying = this.runningTool;
+      const verifySpin = verifying && this.theme.color ? chalk.yellow(this.spinner.current()) : this.spinner.current();
       const costUsd = costForUsage(this.footer.model, this.turnUsage) ?? undefined;
       const stats = this.tools.stats();
       tail.push(...renderStatusBox({
         cols: Math.max(24, Math.min(120, cols)),
         phaseLabel: this.workflowStatus ? `${this.workflowStatus.skill}:${this.workflowStatus.phase}` : this.hudPhase,
-        spinner: this.spinner.current(),
+        spinner: verifySpin,
         activity: this.retryNotice ?? (this.streamingActivity || this.currentActivity()),
         escHint: true,
         elapsedMs,
@@ -1184,7 +1203,7 @@ export class LaunchTui {
         color: this.theme.color,
         colorLevel,
         phase,
-        palette: [grad.from, grad.to],
+        palette: verifying ? [...STATUS_VERIFY_PALETTE] : [grad.from, grad.to],
         isThinking: true,
         usage: this.turnUsage,
         costUsd,
@@ -1350,7 +1369,7 @@ export class LaunchTui {
         for (const line of renderStatusBox({
           cols: innerWidth,
           phaseLabel: this.workflowStatus ? `${this.workflowStatus.skill}:${this.workflowStatus.phase}` : this.hudPhase,
-          spinner: this.spinner.current(),
+          spinner: this.runningTool && this.theme.color ? chalk.yellow(this.spinner.current()) : this.spinner.current(),
           activity: this.retryNotice ?? (this.streamingActivity || statusMsg),
           escHint: true,
           elapsedMs,
@@ -1365,7 +1384,7 @@ export class LaunchTui {
           color: this.theme.color,
           colorLevel,
           phase,
-          palette,
+          palette: this.runningTool ? [...STATUS_VERIFY_PALETTE] : palette,
           isThinking: true,
           usage: this.turnUsage,
           costUsd,

package/src/util/whats-new.ts

@@ -0,0 +1,272 @@
+import pkg from "../../package.json";
+import { compareVersions } from "../commands/update";
+import * as os from "node:os";
+import * as path from "node:path";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { jeoEnv } from "./env";
+import chalk from "chalk";
+import { boxBlock, BOX_UNICODE, BOX_ASCII } from "../tui/components/layout";
+
+// ---- "What's New" release notes ---------------------------------------------
+// Mirrors gjc's post-upgrade release-notes surface. The bundled CHANGELOG.md
+// (shipped via package.json `files`) is always the RUNNING version's changelog,
+// so after a `bun install -g jeo-code` upgrade the next launch reads the NEW
+// notes offline. `jeo whats-new` shows them on demand; `jeo update --install`
+// shows them right after a successful self-update.
+
+export interface ChangelogGroup {
+  /** "Added" | "Changed" | "Fixed" | "" (ungrouped). */
+  label: string;
+  items: string[];
+}
+
+export interface ChangelogSection {
+  version: string; // "0.5.9" | "Unreleased"
+  date?: string;
+  summary: string; // the `_italic_` one-liner under the header
+  groups: ChangelogGroup[];
+}
+
+const HEADER = /^##\s+\[([^\]]+)\](?:\s*-\s*(\S+))?\s*$/;
+const SUBHEADER = /^###\s+(.+?)\s*$/;
+const BULLET = /^[-*]\s+(.+)$/;
+const ITALIC = /^_(.+)_$/;
+
+/** Parse `## [version] - date` sections with their summary line and grouped bullets. */
+export function parseChangelogSections(markdown: string): ChangelogSection[] {
+  const lines = markdown.split(/\r?\n/);
+  const sections: ChangelogSection[] = [];
+  let current: ChangelogSection | null = null;
+  let group: ChangelogGroup | null = null;
+
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+    const head = line.match(HEADER);
+    if (head) {
+      current = { version: head[1]!, date: head[2], summary: "", groups: [] };
+      group = null;
+      sections.push(current);
+      continue;
+    }
+    if (!current) continue;
+
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+
+    const sub = trimmed.match(SUBHEADER);
+    if (sub) {
+      group = { label: sub[1]!, items: [] };
+      current.groups.push(group);
+      continue;
+    }
+
+    const bullet = trimmed.match(BULLET);
+    if (bullet) {
+      if (!group) {
+        group = { label: "", items: [] };
+        current.groups.push(group);
+      }
+      group.items.push(bullet[1]!.trim());
+      continue;
+    }
+
+    const italic = trimmed.match(ITALIC);
+    if (italic && !current.summary && current.groups.length === 0) {
+      current.summary = italic[1]!.trim();
+    }
+  }
+
+  return sections;
+}
+
+/** Real releases only (drops an `Unreleased` heading), newest-first as written. */
+export function releaseSections(sections: ChangelogSection[]): ChangelogSection[] {
+  return sections.filter(s => s.version.toLowerCase() !== "unreleased");
+}
+
+/**
+ * Sections strictly newer than `fromVersion` and at most `toVersion`.
+ * `fromVersion` null → every release up to and including `toVersion`.
+ */
+export function selectNewSections(
+  sections: ChangelogSection[],
+  fromVersion: string | null,
+  toVersion: string,
+): ChangelogSection[] {
+  return releaseSections(sections).filter(s => {
+    const newerThanFrom = fromVersion ? compareVersions(s.version, fromVersion) > 0 : true;
+    const atMostTo = compareVersions(s.version, toVersion) <= 0;
+    return newerThanFrom && atMostTo;
+  });
+}
+
+export interface WhatsNewRenderOpts {
+  cols?: number;
+  unicode?: boolean;
+  color?: boolean;
+  /** Cap rendered body lines so a multi-release jump stays bounded. Default 22. */
+  maxBodyLines?: number;
+}
+
+/** Word-wrap plain text to `width` columns, hard-breaking any single over-long token. */
+function wrapWords(text: string, width: number): string[] {
+  const w = Math.max(1, width);
+  const out: string[] = [];
+  let cur = "";
+  const flush = () => { if (cur) { out.push(cur); cur = ""; } };
+  for (let word of text.split(/\s+/).filter(Boolean)) {
+    while (word.length > w) {
+      flush();
+      out.push(word.slice(0, w));
+      word = word.slice(w);
+    }
+    if (!cur) cur = word;
+    else if (cur.length + 1 + word.length <= w) cur += " " + word;
+    else { out.push(cur); cur = word; }
+  }
+  flush();
+  return out.length ? out : [""];
+}
+
+/** Render a boxed "What's New" panel for the given sections (newest-first). */
+export function renderWhatsNew(sections: ChangelogSection[], opts?: WhatsNewRenderOpts): string[] {
+  if (sections.length === 0) return [];
+
+  const cols = opts?.cols ?? 80;
+  const useColor = opts?.color !== false;
+  const useUnicode = opts?.unicode !== false;
+  const maxBody = opts?.maxBodyLines ?? 22;
+  const width = Math.max(32, Math.min(120, cols));
+  const inner = Math.max(8, width - 2);
+
+  const accent = useColor ? chalk.hex("#f2b84b") : (s: string) => s;
+  const bold = useColor ? (s: string) => chalk.bold(accent(s)) : (s: string) => s;
+  const boldPlain = useColor ? chalk.bold : (s: string) => s;
+  const dim = useColor ? chalk.dim : (s: string) => s;
+  const bulletChar = useUnicode ? "•" : "-";
+
+  const body: string[] = [];
+  let clipped = false;
+
+  // Wrap `text` to the inner width, paint each line, and push — bullets indent
+  // their continuation lines under the marker. Returns false once the cap is hit.
+  const emit = (text: string, paint: (s: string) => string, kind: "plain" | "bullet" = "plain"): boolean => {
+    const avail = kind === "bullet" ? inner - 2 : inner;
+    const wrapped = wrapWords(text, avail);
+    for (let i = 0; i < wrapped.length; i++) {
+      if (body.length >= maxBody) { clipped = true; return false; }
+      const prefix = kind === "bullet" ? (i === 0 ? `${bulletChar} ` : "  ") : "";
+      body.push(paint(prefix + wrapped[i]!));
+    }
+    return true;
+  };
+
+  const headerLabel = sections.length === 1
+    ? `What's New in jeo ${sections[0]!.version}`
+    : `What's New (${sections.length} releases)`;
+  emit(headerLabel, bold);
+
+  outer:
+  for (const s of sections) {
+    if (sections.length > 1) {
+      if (body.length >= maxBody) { clipped = true; break; }
+      body.push("DIVIDER");
+      const when = s.date ? ` — ${s.date}` : "";
+      if (!emit(`${s.version}${when}`, accent)) break;
+    }
+    if (s.summary && !emit(s.summary, dim)) break;
+    for (const g of s.groups) {
+      if (g.label && !emit(g.label, boldPlain)) break outer;
+      for (const item of g.items) {
+        if (!emit(item, (l: string) => l, "bullet")) break outer;
+      }
+    }
+  }
+  if (clipped) body.push(dim("… see CHANGELOG.md for the full notes"));
+
+  return boxBlock(body, width, {
+    glyphs: useUnicode ? BOX_UNICODE : BOX_ASCII,
+    paint: accent,
+    align: "left",
+  });
+}
+
+// ---- Bundled changelog + last-seen-version state ----------------------------
+
+/** Read the CHANGELOG.md that ships next to this package (running version's notes). */
+export async function loadBundledChangelog(): Promise<string | null> {
+  // This module lives at src/util/whats-new.ts; CHANGELOG.md sits at the package
+  // root, i.e. two levels up. Resolve against the module dir so it works from a
+  // global install path just as from the repo.
+  const candidate = path.join(import.meta.dir, "..", "..", "CHANGELOG.md");
+  try {
+    return await readFile(candidate, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+interface WhatsNewState {
+  lastSeenVersion: string;
+  updatedAt: number;
+}
+
+function stateDir(): string {
+  return jeoEnv("CONFIG_DIR") || path.join(os.homedir(), ".jeo");
+}
+
+function statePath(): string {
+  return path.join(stateDir(), "whats-new.json");
+}
+
+export async function readLastSeenVersion(): Promise<string | null> {
+  try {
+    const raw = await readFile(statePath(), "utf-8");
+    const data = JSON.parse(raw) as Partial<WhatsNewState>;
+    if (!data || typeof data.lastSeenVersion !== "string" || !data.lastSeenVersion) return null;
+    return data.lastSeenVersion;
+  } catch {
+    return null;
+  }
+}
+
+/** Persist the last version the user has seen notes for (best-effort; never throws). */
+export async function writeLastSeenVersion(version: string): Promise<void> {
+  if (typeof version !== "string" || !version) return;
+  try {
+    await mkdir(stateDir(), { recursive: true, mode: 0o700 });
+    const payload: WhatsNewState = { lastSeenVersion: version, updatedAt: Date.now() };
+    await writeFile(statePath(), JSON.stringify(payload, null, 2), { encoding: "utf-8", mode: 0o600 });
+  } catch {
+    // State is an optimization; a write failure must never break launch/update.
+  }
+}
+
+/**
+ * Launch-time hook: returns rendered notes the FIRST time jeo runs after an
+ * upgrade, then records the current version so it never repeats. A fresh install
+ * (no prior state) records silently and shows nothing — only genuine upgrades
+ * surface notes, matching gjc / npm update-notice behaviour.
+ */
+export async function consumeLaunchWhatsNew(opts?: WhatsNewRenderOpts): Promise<string[] | null> {
+  const current = pkg.version;
+  const lastSeen = await readLastSeenVersion();
+
+  if (!lastSeen) {
+    await writeLastSeenVersion(current);
+    return null;
+  }
+  if (compareVersions(current, lastSeen) <= 0) {
+    // Not an upgrade (equal, or a local downgrade). Keep state monotonic-ish.
+    if (compareVersions(current, lastSeen) < 0) await writeLastSeenVersion(current);
+    return null;
+  }
+
+  // Genuine upgrade: mark seen up front so a render/parse failure never repeats.
+  const md = await loadBundledChangelog();
+  await writeLastSeenVersion(current);
+  if (!md) return null;
+  const sections = selectNewSections(parseChangelogSections(md), lastSeen, current);
+  if (sections.length === 0) return null;
+  return renderWhatsNew(sections, opts);
+}