@homie-rocks/studio 0.19.0 → 0.19.2

package/README.md

@@ -108,14 +108,20 @@ are watched only by those they let in (NETPLAY.md section 16, site/SITE.md).
 
 ## Upgrading a studio
 
-A studio pins one version, so nothing changes until it asks. To take a newer one:
+A studio pins one version, so nothing changes until it asks. To take a newer one (`latest`, or a version):
 
 ```sh
-npx -y @homie-rocks/studio@0.18.2 upgrade          # the plan; changes nothing
-npx -y @homie-rocks/studio@0.18.2 upgrade --apply  # after the person agrees
+npx -y @homie-rocks/studio@latest upgrade          # what's new, and the plan; changes nothing
+npx -y @homie-rocks/studio@0.19.2 upgrade --apply  # after the person agrees (the version the plan named)
 npm install && npm run build
 ```
 
+The plan starts with **what's new** since the version the studio pins: one line per version and every upgrade note
+(anything the person has to do), read from the new version's own `CHANGELOG.md`, which ships in the package (the
+repository's [CHANGELOG.md](https://github.com/homie-rocks/homie/blob/main/CHANGELOG.md) is the same file). `--json`
+carries it as `whatsNew`. In Claude Desktop, `studio_run ["upgrade"]` runs the extension's own newer toolkit for
+this, and the studio card says what's new when a studio is behind.
+
 `upgrade` compares the studio with what this version's `new` would write for it: an AGENTS.md section, a README,
 a `.gitignore` line, a D1 migration or a package.json script it lacks is added, and one it never changed since an
 older template wrote it (`lib/template-history.json` knows every earlier version's text by a fingerprint) takes
@@ -440,6 +446,12 @@ playable, heap, the host's upload) must not get worse. Results are files under `
 command prints paths and medians. The Homie plugin's `perf` skill runs the whole loop: baseline, one change at a time,
 keep or revert, and a report in the studio's `perf/` folder.
 
+`perf sizes` reads each big script for whether it is minified from its code, not from how well it gzips: whitespace,
+comments and names outside its strings (a minifier leaves about 1 to 2% whitespace; indented source has 15 to 30%).
+Minified JavaScript gzips about as well as source text, and a bundle with three.js in it carries the shaders as GLSL
+source in strings, which no minifier touches; the line for such a file says `minified, 19% GLSL shader source in
+strings`, and the JSON's `code` has every measure.
+
 ## Checks on a computer without a GPU
 
 `check`, `port check` and `look` run Chrome headless. On a Mac they use its GPU. On Linux (a Claude Code cloud
@@ -492,6 +504,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `lib/cloudflare.mjs` | `deploy` (and `deploy --plan`): Wrangler, D1, migrations; refuses resources it did not create. In Workers Builds, migrations and deploy only. `storage add`: the optional R2 bucket; `media move`: big media into it, checked by SHA-256 (every deploy runs it). |
 | `lib/check.mjs` | `check`: two fresh Chrome processes (computer + phone) must share a room and finish a round with both in it, with each one's frame rate; on a busy computer it waits out a round a browser was dropped from, and says why when none counts. `lib/chrome.mjs`: which Chrome, and how (the GPU on a Mac, SwiftShader on Linux). |
 | `lib/upgrade.mjs`, `lib/template-history.json` | `upgrade`: an existing studio takes what a newer template adds, never over its own edits. |
+| `lib/changelog.mjs`, `CHANGELOG.md` | The release history this package carries (a copy of the repository's): `upgrade`'s what's new, the studio card's, and the release notes. |
 | `lib/progress.mjs`, `lib/setup.mjs` | The progress feed (`progress …`), a build the chat opened (`progress attach`), a change as a pull request (`progress change`, `progress pr`), and `setup attach`. |
 | `lib/net.mjs`, `lib/repo.mjs` | The toolkit's own web requests: through the environment's proxy, and an honest reason when one fails. The studio's repository (`owner/name`), from its remote, never the engine's. |
 | `template/` (repository root), `scripts/template.mjs` | The public "Deploy to Cloudflare" template, generated from `new --template`. |

package/bin/homie-studio.mjs

@@ -31,7 +31,8 @@
  *                                          emulated (a --cpu times slower CPU, 4G) on this computer's GPU. The plugin's perf
  *                                          skill runs the whole measure, change, compare, keep-or-revert loop)
  *   homie-studio perf sizes <id>          (what a player downloads: every built file, raw and gzipped, the biggest first; with
- *                                          build --maps, which modules make up the bundle)
+ *                                          build --maps, which modules make up the bundle; each big script read for whether it
+ *                                          is minified, from its code, and how much of it is GLSL shader source in strings)
  *   homie-studio perf compare <before dir> <after dir> [--goal phone.host.frame.p95] [--min 3] [--guards a,b] [--also c,d]
  *                                         (better, worse or the same within the noise: medians, a 95% interval, a rank test,
  *                                          and the guards that must not get worse; runs taken side by side with the same
@@ -60,7 +61,9 @@
  *   homie-studio upgrade [--apply] [--diff]
  *                                         (what this version's template adds to an existing studio: AGENTS.md
  *                                          sections, READMEs, .gitignore lines, the pin; changes nothing until
- *                                          --apply, and never a file or section the studio changed)
+ *                                          --apply, and never a file or section the studio changed. It starts
+ *                                          with what's new since the studio's version, from this package's
+ *                                          CHANGELOG.md)
  *   homie-studio stats [--range 1d|7d|30d|90d] [--game <id> | --song <slug> | --video <slug>] [--url <site>]
  *   homie-studio stats key [--hours 1]    (a read key for the Homie MCP tool studio_stats)
  *   homie-studio stats link               (a one-time link to the private stats page, for the owner's browser)
@@ -169,6 +172,7 @@ import { DEFAULT_GOAL, perfCompare, perfRun, perfSizes } from '../lib/perf.mjs';
 import { R2_COST, lineOf, mediaPlan, r2OverOf, recordUpload, resolveMedia, sizeOf, typeOf } from '../lib/media.mjs';
 import { ensureMigrations, migrationWord, newStudio } from '../lib/scaffold.mjs';
 import { lineDiff, upgradeApply, upgradePlan } from '../lib/upgrade.mjs';
+import { whatsNewLines } from '../lib/changelog.mjs';
 import { listGames, newGame, readStudio, remixGame, requireStudio, siteUrl, starters, workerDir } from '../lib/studio.mjs';
 import { STUDIO_VERSION } from '../lib/version.mjs';
 import { statsKey, statsLink, statsRevoke, statsShare, statsShow } from '../lib/stats.mjs';
@@ -438,7 +442,9 @@ function print(result) {
       lines.push(result.applied
         ? `${result.studio} is on the @homie-rocks/studio ${result.to} template now (${list.length} change${list.length === 1 ? '' : 's'}).`
         : list.length ? `${result.studio}: what the @homie-rocks/studio ${result.to} template adds (from ${result.from ?? 'an older version'}). Nothing is changed until --apply.` : `${result.studio} has everything the @homie-rocks/studio ${result.to} template writes.`);
-      if (list.length) lines.push('');
+      // What the versions since the studio's own brought, from this package's CHANGELOG.md (also after --apply).
+      if (result.whatsNew) lines.push('', ...whatsNewLines(result.whatsNew, { source: `@homie-rocks/studio ${result.to}'s CHANGELOG.md` }));
+      if (list.length) lines.push('', result.applied ? 'Done:' : 'The changes:');
       for (const c of list) {
         lines.push(`  ${mark[c.kind] ?? '·'} ${c.file.padEnd(18)} ${c.what}${c.kind === 'add-section' && (c.after || c.before) ? ` (${c.after ? `after "${c.after}"` : `before "${c.before}"`})` : ''}`);
         if (result.applied) continue;
@@ -477,7 +483,7 @@ function print(result) {
     case 'perf sizes': {
       const kb = (b) => `${(b / 1024).toFixed(1)} KB`;
       lines.push(`${result.game}: ${result.total.files} files, ${kb(result.total.bytes)} (${kb(result.total.gzip)} gzipped); JavaScript ${kb(result.js.bytes)} (${kb(result.js.gzip)} gzipped)`,
-        'Biggest:', ...result.biggest.slice(0, 8).map((f) => `  ${kb(f.bytes).padStart(10)}  ${f.path}${f.gzip !== f.bytes ? `  (${kb(f.gzip)} gzipped)` : ''}`),
+        'Biggest:', ...result.biggest.slice(0, 8).map((f) => `  ${kb(f.bytes).padStart(10)}  ${f.path}${f.gzip !== f.bytes ? `  (${kb(f.gzip)} gzipped)` : ''}${f.code ? `  ${f.code.minified ? `minified${f.code.shaderPct >= 5 ? `, ${f.code.shaderPct}% GLSL shader source in strings` : ''}` : 'NOT minified'}` : ''}`),
         ...(result.modules ? ['Bundle modules:', ...result.modules.top.slice(0, 8).map((m) => `  ${kb(m.bytes).padStart(10)}  ${m.module}`)] : []),
         ...(result.apart ? [`Not loaded by the game: ${result.apart.files} file(s), ${kb(result.apart.bytes)} (${result.apart.note})`] : []));
       break;

package/lib/changelog.mjs

@@ -0,0 +1,204 @@
+/**
+ * CHANGELOG.md: what changed in each @homie-rocks/studio version, and the Homie plugin's version beside it.
+ *
+ * The repository keeps it at its root; the package carries an identical copy (packages/studio/CHANGELOG.md, in
+ * `files`, kept the same by `node scripts/changelog.mjs --sync`), so an installed toolkit knows its own history with
+ * no network. Read by:
+ *   - `homie-studio upgrade`: "What's new since <the pinned version>", from the NEW version's own copy (the one
+ *     `npx -y @homie-rocks/studio@<new> upgrade` runs);
+ *   - the studio card (lib/mcp-tools.mjs), when a studio pins an older toolkit than the one answering;
+ *   - scripts/changelog.mjs: CI's check, and the GitHub release notes the publish workflow writes.
+ *
+ * The shape (Keep a Changelog, https://keepachangelog.com/en/1.1.0/), newest first:
+ *
+ *   ## [0.19.2] - 2026-10-02                              one section per studio version
+ *
+ *   **Plugin 0.20.2** · [#29](…) · [release-…](…)          the meta line: the plugin's version (", then 0.20.3" when
+ *                                                          the plugin had a release of its own after it), the pull
+ *                                                          requests and the tag
+ *   One sentence: what this version is.                    the summary "What's new" prints
+ *
+ *   ### Added | ### Changed | ### Fixed | ### Upgrade notes   bullets ("- " and lines indented under them)
+ *
+ *   [0.19.2]: https://…                                    link definitions, at the end of the file
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export const CHANGELOG_FILE = fileURLToPath(new URL('../CHANGELOG.md', import.meta.url));
+export const GROUPS = Object.freeze(['Added', 'Changed', 'Fixed', 'Upgrade notes']);
+export const REPO_URL = 'https://github.com/homie-rocks/homie';
+
+const VERSION = /^\d+\.\d+\.\d+$/;
+const HEADING = /^## \[?(\d+\.\d+\.\d+)\]?(?:\s+-\s+(\d{4}-\d{2}-\d{2}))?\s*$/;
+const LINK_DEF = /^\[[^\]]+\]:\s+\S+/;
+
+/** -1, 0 or 1, as a sorts before, with or after b (x.y.z only; anything else sorts first). */
+export function compareVersions(a, b) {
+  const x = VERSION.test(String(a)) ? String(a).split('.').map(Number) : [-1, -1, -1];
+  const y = VERSION.test(String(b)) ? String(b).split('.').map(Number) : [-1, -1, -1];
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return 0;
+}
+
+/** Markdown as one line of plain words: links keep their text, code and bold lose their marks. */
+export function plain(markdown) {
+  return String(markdown ?? '')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** The paragraphs and bullets of a run of lines: paragraphs split on blank lines, a bullet takes the lines indented under it. */
+function blocks(lines) {
+  const out = [];
+  let cur = null;
+  for (const line of lines) {
+    if (!line.trim()) { cur = null; continue; }
+    if (/^- /.test(line)) { cur = { kind: 'bullet', text: line.slice(2).trim() }; out.push(cur); continue; }
+    if (cur && (cur.kind === 'paragraph' || /^\s+\S/.test(line))) { cur.text += ` ${line.trim()}`; continue; }
+    cur = { kind: 'paragraph', text: line.trim() }; out.push(cur);
+  }
+  return out;
+}
+
+/**
+ * The file as its sections. Each: { version, date, plugin, plugins, meta, summary, notes, groups, body, line }.
+ * `body` is the section's own Markdown (no heading, no link definitions), what a release's notes are made of.
+ * `problems` lists what does not follow the shape (CI fails on them); a heading that is not a version (an
+ * "Unreleased" one, say) ends the section before it and is otherwise left alone.
+ */
+export function parseChangelog(text) {
+  const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const versions = [];
+  const problems = [];
+  let cur = null;
+  const close = () => {
+    if (!cur) return;
+    while (cur.lines.length && !cur.lines[cur.lines.length - 1].trim()) cur.lines.pop();
+    const { lines: own, ...section } = cur;
+    section.body = own.join('\n').replace(/^\n+/, '');
+    // Before the first ### heading: the meta line, the summary and any notes; then the groups.
+    const groups = {};
+    let head = [];
+    let group = null;
+    for (const line of own) {
+      const g = /^### (.+?)\s*$/.exec(line);
+      if (g) { group = g[1]; groups[group] = []; continue; }
+      if (group === null) head.push(line); else groups[group].push(line);
+    }
+    const paras = blocks(head).map((b) => b.text);
+    const metaAt = paras.findIndex((p) => /^\*\*Plugin /.test(p));
+    section.meta = metaAt >= 0 ? paras[metaAt] : null;
+    const rest = paras.filter((_, i) => i !== metaAt);
+    section.summary = rest[0] ?? null;
+    section.notes = rest.slice(1);
+    section.plugins = section.meta ? [...(/^\*\*Plugin ([^*]+)\*\*/.exec(section.meta)?.[1] ?? '').matchAll(/\d+\.\d+\.\d+/g)].map((m) => m[0]) : [];
+    section.plugin = section.plugins.at(-1) ?? null;
+    section.groups = Object.fromEntries(Object.entries(groups).map(([k, v]) => [k, blocks(v).filter((b) => b.kind === 'bullet').map((b) => b.text)]));
+    const where = `CHANGELOG.md line ${section.line} (## [${section.version}])`;
+    if (!section.date) problems.push(`${where}: the heading has no date; write it as "## [${section.version}] - YYYY-MM-DD"`);
+    if (!section.meta) problems.push(`${where}: no "**Plugin x.y.z** · …" line under the heading`);
+    else if (!section.plugin) problems.push(`${where}: the Plugin line names no version`);
+    if (!section.summary) problems.push(`${where}: no one-sentence summary under the Plugin line`);
+    for (const k of Object.keys(section.groups)) if (!GROUPS.includes(k)) problems.push(`${where}: "### ${k}" is not one of ${GROUPS.map((g) => `"### ${g}"`).join(', ')}`);
+    if (!Object.values(section.groups).some((b) => b.length)) problems.push(`${where}: no "- " entries under ${GROUPS.map((g) => `"### ${g}"`).join(', ')}`);
+    versions.push(section);
+    cur = null;
+  };
+  lines.forEach((line, i) => {
+    if (/^## /.test(line)) {
+      close();
+      const m = HEADING.exec(line);
+      if (m) cur = { version: m[1], date: m[2] ?? null, heading: line, line: i + 1, lines: [] };
+      return;
+    }
+    if (cur && LINK_DEF.test(line)) { close(); return; }
+    if (cur) cur.lines.push(line);
+  });
+  close();
+  for (let i = 1; i < versions.length; i++) {
+    if (compareVersions(versions[i - 1].version, versions[i].version) <= 0) problems.push(`CHANGELOG.md line ${versions[i].line}: ${versions[i].version} comes after ${versions[i - 1].version}; newest first, each version once`);
+  }
+  return { versions, problems };
+}
+
+/** The package's own CHANGELOG.md, parsed; null when it is missing (a checkout from before 0.19.2) or unreadable. */
+export function readChangelog(file = CHANGELOG_FILE) {
+  try { return { file, ...parseChangelog(readFileSync(file, 'utf8')) }; } catch { return null; }
+}
+
+/** One version's section, or null. */
+export function sectionOf(changelog, version) {
+  return changelog?.versions?.find((s) => s.version === version) ?? null;
+}
+
+/**
+ * What changed after `from` up to and including `to`, newest first: each version's summary and its upgrade notes
+ * (what the person may have to do). null when there is nothing to say (no pin known, no changelog, or not older).
+ */
+export function whatsNew(from, to, { changelog = readChangelog() } = {}) {
+  if (!VERSION.test(String(from ?? '')) || !VERSION.test(String(to ?? '')) || compareVersions(from, to) >= 0 || !changelog) return null;
+  const versions = changelog.versions
+    .filter((s) => compareVersions(s.version, from) > 0 && compareVersions(s.version, to) <= 0)
+    .map((s) => ({ version: s.version, date: s.date, plugin: s.plugin, summary: plain(s.summary), upgrade: (s.groups['Upgrade notes'] ?? []).map(plain) }));
+  return versions.length ? { from, to, versions } : null;
+}
+
+/**
+ * whatsNew as a few lines for a terminal or a card's text: one line per version (the newest `maxVersions`), then the
+ * upgrade notes of every version in the range (the first `maxNotes`), each cut to `width`.
+ */
+export function whatsNewLines(news, { width = 110, maxVersions = 8, maxNotes = 8, source = null } = {}) {
+  if (!news?.versions?.length) return [];
+  const cut = (s, n) => (s.length > n ? `${s.slice(0, n - 1).replace(/\s+\S*$/, '')}…` : s);
+  const shown = news.versions.slice(0, maxVersions);
+  const pad = Math.max(...news.versions.map((v) => v.version.length));
+  const lines = [`What's new since ${news.from}${source ? ` (${source})` : ''}:`];
+  for (const v of shown) lines.push(`  ${v.version.padEnd(pad)}  ${cut(v.summary ?? '', width - pad - 4)}`);
+  const more = news.versions.length - shown.length;
+  if (more) lines.push(`  … and ${more} earlier version${more === 1 ? '' : 's'} (CHANGELOG.md has every one)`);
+  const notes = news.versions.flatMap((v) => v.upgrade.map((u) => [v.version, u]));
+  if (notes.length) {
+    lines.push('Upgrade notes (anything to do yourself):');
+    for (const [v, u] of notes.slice(0, maxNotes)) lines.push(`  ${v.padEnd(pad)}  ${cut(u, width - pad - 4)}`);
+    if (notes.length > maxNotes) lines.push(`  … and ${notes.length - maxNotes} more (--json has every one)`);
+  }
+  return lines;
+}
+
+/**
+ * Markdown with each paragraph and each "- " entry on one line. CHANGELOG.md wraps them at 120 columns, which a
+ * file ignores; GitHub's release notes render every line end as a break, so a wrapped entry would break mid-sentence.
+ */
+export function unwrap(markdown) {
+  const out = [];
+  for (const line of String(markdown ?? '').split('\n')) {
+    const prev = out.length ? out[out.length - 1] : '';
+    const starts = !line.trim() || /^(#{1,6} |- |\* |\d+\. |---\s*$|\|)/.test(line.trim()) && !/^\s+/.test(line);
+    const continues = prev.trim() && !/^(#{1,6} |---\s*$|\|)/.test(prev.trim());
+    if (!starts && continues) out[out.length - 1] = `${prev.replace(/\s+$/, '')} ${line.trim()}`;
+    else out.push(line);
+  }
+  return out.join('\n');
+}
+
+/**
+ * A GitHub release's notes: the version's section as it is in CHANGELOG.md (each paragraph and entry on one line),
+ * then the Desktop extension's line (its .mcpb is attached to the release) and where every version is.
+ */
+export function releaseNotes(changelog, version, { tag = null, repo = REPO_URL } = {}) {
+  const s = sectionOf(changelog, version);
+  if (!s) return null;
+  return [
+    unwrap(s.body),
+    '',
+    '---',
+    '',
+    `Homie for Claude Desktop ${version}: [desktop/README.md](${repo}/blob/${tag ?? 'main'}/desktop/README.md) says how to install it (\`homie-studio-${version}.mcpb\` below).`,
+    `Every version: [CHANGELOG.md](${repo}/blob/main/CHANGELOG.md).`,
+    '',
+  ].join('\n');
+}

package/lib/jobs.mjs

@@ -159,10 +159,11 @@ export function jobView(job, { lines = 12 } = {}) {
 }
 
 /** Run the studio's pinned CLI as a job: `homie-studio <args> --json`. */
-export function cliJob(root, label, args, opts = {}) {
+export function cliJob(root, label, args, { cli = null, ...opts } = {}) {
   const node = findNode();
   if (!node) throw new Error('no Node.js 22 or newer on this computer: install it from https://nodejs.org/en/download (the LTS), then ask again');
-  return startJob({ root, label, cmd: node.bin, args: [cliOf(root), ...args, '--json'], json: true, ...opts });
+  // `cli`: another homie-studio than the studio's pinned one (this package's, for an upgrade to it).
+  return startJob({ root, label, cmd: node.bin, args: [cli ?? cliOf(root), ...args, '--json'], json: true, ...opts });
 }
 
 /** `npm install` in a studio (its pinned toolkit and Wrangler). */

package/lib/mcp-tools.mjs

@@ -28,8 +28,10 @@ import { cliJob, findNode, getJob, installJob, installed, jobView, runningJobs,
 import { Feed, currentId, publicFeed, readFeed, startProgress } from './progress.mjs';
 import { newStudio, slugify } from './scaffold.mjs';
 import { repoFromUrl, studioRepo } from './repo.mjs';
-import { GAME_ID, findStudio, listGames, readLocal, readStudio, siteUrl, workerDir } from './studio.mjs';
+import { GAME_ID, PACKAGE_ROOT, findStudio, listGames, readLocal, readStudio, siteUrl, workerDir } from './studio.mjs';
 import { STUDIO_VERSION } from './version.mjs';
+import { compareVersions, whatsNew, whatsNewLines } from './changelog.mjs';
+import { pinnedVersion } from './upgrade.mjs';
 import { AgentSeat } from './agent-seat.mjs';
 
 export const UI = Object.freeze({
@@ -120,8 +122,8 @@ const ok = (text, structured, extra = {}) => ({ content: [{ type: 'text', text }
 const fail = (text, structured) => ({ content: [{ type: 'text', text }], ...(structured ? { structuredContent: structured } : {}), isError: true });
 
 /** Run the pinned CLI and wait a while; { ended, job, result }. */
-async function cli(ctx, root, label, args, { wait = ctx.waitMs, onEnd = null } = {}) {
-  const job = cliJob(root, label, args, { onEnd });
+async function cli(ctx, root, label, args, { wait = ctx.waitMs, onEnd = null, cli: bin = null } = {}) {
+  const job = cliJob(root, label, args, { onEnd, ...(bin ? { cli: bin } : {}) });
   const ended = await waitJob(job, wait);
   return { ended, job, result: job.result };
 }
@@ -245,6 +247,18 @@ function published(root, kind) {
   } catch { return []; }
 }
 
+/**
+ * When the studio pins an older @homie-rocks/studio than this one: the pin, this version, and what's new between them
+ * (this package's own CHANGELOG.md). null when it is on this version, a newer one, or a link to a checkout.
+ */
+export function behindOf(root) {
+  let pkg = null;
+  try { pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')); } catch { return null; }
+  const pinned = pinnedVersion(pkg?.devDependencies?.['@homie-rocks/studio'] ?? pkg?.dependencies?.['@homie-rocks/studio']);
+  if (!pinned || compareVersions(pinned, STUDIO_VERSION) >= 0) return null;
+  return { pinned, here: STUDIO_VERSION, whatsNew: whatsNew(pinned, STUDIO_VERSION) };
+}
+
 async function studioCard(ctx, root) {
   const studio = readStudio(root);
   const dev = devOf(root);
@@ -282,6 +296,8 @@ async function studioCard(ctx, root) {
     games, songs: published(root, 'music'), videos: published(root, 'videos'), posts,
     dev: dev ? { url: dev.url } : null, site: live, rooms, demo, installed: installed(root),
   };
+  const behind = behindOf(root);
+  if (behind) data.behind = { ...behind, whatsNew: behind.whatsNew ? { ...behind.whatsNew, versions: behind.whatsNew.versions.slice(0, 6).map(({ version, summary, upgrade }) => ({ version, summary, upgrade: upgrade.slice(0, 2) })) } : null };
   const text = [
     `${studio.name} (${root})`,
     games.length ? `Games: ${games.map((g) => `${g.name} (${g.id}${live ? (g.live ? ', live' : ', not deployed yet') : ''})`).join(', ')}` : 'No game yet: its home page says "First game coming soon".',
@@ -289,6 +305,10 @@ async function studioCard(ctx, root) {
     live ? `Live: ${live}/` : 'Not online yet (studio_deploy).',
     ...(rooms.length ? [`Live rooms: ${rooms.map((r) => `${r.game} ${r.room} (${r.players})`).join(', ')}`] : []),
     ...(demo ? [`See a working game meanwhile: ${demo.name}, ${demo.play}`] : []),
+    ...(behind ? [
+      `Toolkit: this studio pins @homie-rocks/studio ${behind.pinned}; this Homie is ${behind.here}. Tell the person what is new (below) and offer the upgrade: studio_run { "args": ["upgrade"] } shows the plan and changes nothing; with their yes, ["upgrade","--apply"], then studio_install.`,
+      ...whatsNewLines(behind.whatsNew, { maxVersions: 6, maxNotes: 6 }),
+    ] : []),
   ].join('\n');
   return ok(text, data);
 }
@@ -948,7 +968,7 @@ export function toolDefs(ctx, avail = {}) {
     },
     {
       name: 'studio_run', title: 'Run a studio command',
-      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job.',
+      description: 'Any other homie-studio command in the studio, by its words (the guides name them): e.g. ["progress","stage","plan","done","--note","…"], ["progress","spend","0.40","--what","a cover"], ["look"], ["stats"], ["codex","link","<id>"], ["port","check","<id>","--url","…"], ["upgrade"], ["storage","add"]. Runs the studio\'s own pinned toolkit; long commands hand back a job. ["upgrade"] runs with THIS Homie\'s toolkit when the studio pins an older one (that is how a studio moves up to it): it says what is new since the studio\'s version and what would change, and changes nothing; ["upgrade","--apply"] only after the person agrees, then studio_install.',
       inputSchema: { type: 'object', properties: { args: { type: 'array', items: { type: 'string' }, description: 'The command\'s words after `homie-studio`' }, ...STUDIO_ARG }, required: ['args'] },
       annotations: { title: 'Run a studio command', readOnlyHint: false, destructiveHint: false, openWorldHint: true },
       run: async (a) => {
@@ -959,7 +979,9 @@ export function toolDefs(ctx, avail = {}) {
         if (refused) return fail(`not here: ${refused}`);
         if (!['help', 'version', 'setup', 'doctor', 'demo', 'starters', 'progress', 'codex', 'games', 'status'].includes(args[0])) { const need = needsInstall(ctx, root); if (need) return need; }
         if (args[0] === 'game' && args[1] === 'new') ctx.note(root).demo = true;
-        const r = await cli(ctx, root, `homie-studio ${args.slice(0, 3).join(' ')}`, args);
+        // The upgrade is the newer toolkit's to make: the studio's own pinned copy knows nothing newer than itself.
+        const own = args[0] === 'upgrade' && behindOf(root) ? { cli: join(PACKAGE_ROOT, 'bin', 'homie-studio.mjs') } : {};
+        const r = await cli(ctx, root, `homie-studio ${args.slice(0, 3).join(' ')}`, args, own);
         if (!r.ended) return stillRunning(r.job, `homie-studio ${args.slice(0, 2).join(' ')}`);
         const text = r.result ? JSON.stringify(r.result, null, 1).slice(0, 12_000) : jobView(r.job, { lines: 40 }).tail.join('\n');
         return r.job.code === 0 ? ok(text, { kind: 'run', args, result: r.result }) : fail(`homie-studio ${args.join(' ')}: ${whyOf(r.job)}`, { kind: 'run', args, result: r.result });