@plitzi/cli 0.38.2 → 0.38.3

package/dist/index.js

@@ -1186,6 +1186,10 @@ const StatCard = ({ label = 'Metric', value = 0, unit = '', series, className }:
    * It is what makes this an ELEMENT rather than a component that happens to be on the page: the element's id and
    * classes land on it, so the CSS authored on it in \`src/space.ts\` applies, the builder can select it, a test
    * can find it by name, and interactions fire on it. A plain tag renders the same pixels and none of that.
+   *
+   * Its \`style\` is inline, and inline outranks every class: what \`CARD\` sets — its display, its padding — the CSS
+   * authored on the element can never change. Keep it to what the element cannot render without, and leave layout and
+   * position (\`position\`, \`width\`, \`margin\`) to the space's classes.
    */
   return (
     <RootElement className={className} style={CARD}>
@@ -1420,6 +1424,8 @@ var managerPackageFields = (manager) => manager === "npm" ? { allowScripts: {
 	fsevents: false
 } } : {};
 var SDK_VERSION = `^${createRequire(import.meta.url)("@plitzi/sdk-authoring/package.json").version}`;
+/** The same version, bare: this CLI's own — what `--version` prints and what wrote a project's machinery. */
+var CLI_VERSION = SDK_VERSION.slice(1);
 /**
 * What every generated project builds and checks itself with.
 *
@@ -1478,8 +1484,8 @@ var NODE_ENGINES = { node: ">=22.18" };
 *
 * `client` runs Vite, so a save is a hot module replacement — the page updates without reloading, and editing the
 * space is a live loop. `server` runs the page server under Node's `--watch`: there is no client bundle of this
-* project's own to hot-replace (the SDK is served by the server from its own copy), so a save restarts the
-* process and the next request renders the change. Both are one command; only one of them is HMR, and calling
+* project's own to hot-replace (the SDK is served by the server from its own copy), so a save to the server's code
+* restarts the process — and a save to a local space is re-authored in place and the open page reloads. Both are one command; only one of them is HMR, and calling
 * the other one HMR would be a promise the loop does not keep.
 */
 var scripts = ({ mode, source }) => ({
@@ -1489,9 +1495,11 @@ var scripts = ({ mode, source }) => ({
 		* Watched by PATH, not wholesale.
 		*
 		* The server compiles the project's plugins into `.sdk-plugins/` and then IMPORTS what it built, so a
-		* bare `--watch` sees its own output land, restarts, compiles again, and never stops.
+		* bare `--watch` sees its own output land, restarts, compiles again, and never stops. A local space is not
+		* among them: `main.ts` re-authors it on save in a process of its own and the open pages load again
+		* (`reloadPages`), so only the server's own code and the plugins restart it.
 		*/
-		"start:dev": "node --watch-path=./src src/main.ts",
+		"start:dev": source === "local" ? "node --watch-path=./src/main.ts --watch-path=./src/plugins src/main.ts" : "node --watch-path=./src src/main.ts",
 		/**
 		* What production runs: the same entry compiled to JavaScript. Node strips types by loading a TypeScript
 		* transformer into the process — ~10 MB a server keeps for its whole life to read one file — so a deployment
@@ -1586,7 +1594,7 @@ var YARN_IGNORES$1 = "\n.yarn/*\n!.yarn/patches\n!.yarn/plugins\n!.yarn/releases
 /** Where the page server writes the plugin bundles it builds. A build output, and rebuilt whenever it is missing. */
 var SERVER_IGNORES = ".sdk-plugins\n.plitzi\n";
 var gitignore$1 = ({ mode, packageManager }) => `node_modules\ndist\n.env\nvisual/.results\nvisual/screenshots\n${mode === "server" ? SERVER_IGNORES : ""}${packageManager === "yarn" ? YARN_IGNORES$1 : ""}`;
-var startLine = ({ mode, packageManager }) => mode === "server" ? `\`${runCommand(packageManager, "start")}\` serves pages on http://127.0.0.1:8080 — or, when something else holds 8080, the next free port, which it prints and writes to \`.plitzi/dev-server.json\` (set \`PORT\` to choose one). \`${runCommand(packageManager, "start:dev")}\` restarts on save. In production, \`${runCommand(packageManager, "build")}\` once and run \`${runCommand(packageManager, "start:prod")}\` with \`NODE_ENV=production\`: the compiled server, with no TypeScript in the process.` : `\`${runCommand(packageManager, "start")}\` runs Vite on http://127.0.0.1:5173, with hot module replacement.`;
+var startLine = ({ mode, packageManager, source }) => mode === "server" ? `\`${runCommand(packageManager, "start")}\` serves pages on http://127.0.0.1:8080 — or, when something else holds 8080, the next free port, which it prints and writes to \`.plitzi/dev-server.json\` (set \`PORT\` to choose one). \`${runCommand(packageManager, "start:dev")}\` restarts on a save to the server's code${source === "local" ? "; a save to the space reloads the open page" : ""}. In production, \`${runCommand(packageManager, "build")}\` once and run \`${runCommand(packageManager, "start:prod")}\` with \`NODE_ENV=production\`: the compiled server, with no TypeScript in the process.` : `\`${runCommand(packageManager, "start")}\` runs Vite on http://127.0.0.1:5173, with hot module replacement.`;
 var spaceSection = (answers) => {
 	if (answers.source === "cloud") return `## Where the space comes from
 
@@ -1688,6 +1696,7 @@ ${code(".claude/skills/plitzi-cli/SKILL.md")} first: ${code("plitzi add plugin")
 ## The rules that go wrong most
 
 - Never write schema/style JSON by hand; author it. A refusal names the fix — fix the declaration; ${code("npx plitzi fix --write")} writes the ones with a single reading.
+- After the ${code("@plitzi/*")} packages move, ${code("npx plitzi upgrade")}: what this project's CLI files, scripts, skills and renamed names should now be — ${code("--write")} makes it, a file you changed comes as a diff.
 - ${zeroWarnings}
 - Chrome shared by pages is a layout; a look used twice is a class; a repeated block is a function or a ${code("map")}.
 - Ids are one namespace for the whole space: name what is referred to; a helper that runs more than once builds inside ${code("scope()")}.
@@ -1889,7 +1898,8 @@ writeFileSync(
   \`\${JSON.stringify({ name: SERVER_NAME, port: PORT, url: \`http://127.0.0.1:\${PORT}\` }, null, 2)}\\n\`
 );
 console.log(\`pages on http://127.0.0.1:\${PORT}/\`);`;
-var localMain = () => `import { mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+var localMain = () => `import { spawn } from 'node:child_process';
+import { mkdirSync, readdirSync, watch, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
 import {
@@ -1925,6 +1935,18 @@ for (const warning of warnings) {
 
 ${PLUGINS}
 
+/**
+ * While developing, the documents are served from the file \`npm run author\` writes, which the server reads again
+ * whenever it changes — so a save is re-authored and shown without restarting anything (see \`watchSpace\` below). A
+ * deployment keeps them in memory, as authored at boot.
+ */
+const DEVELOPING = process.env.NODE_ENV !== 'production';
+const OFFLINE_DATA = path.join(PROJECT_ROOT, 'space/offline-data.json');
+if (DEVELOPING) {
+  mkdirSync(path.dirname(OFFLINE_DATA), { recursive: true });
+  writeFileSync(OFFLINE_DATA, \`\${JSON.stringify(offlineData, null, 2)}\\n\`);
+}
+
 /**
  * This project's own server code: \`functions/\` — what \`plitzi functions pull\` writes and \`push\` sends — built
  * the way Plitzi builds a space's and run here, in this process. Nothing there, no functions; code that does not build
@@ -1944,9 +1966,11 @@ const SERVER_NAME = schema.definition.permanentUrl;
 const server = createServer({
   port: PORT,
   devMode: process.env.NODE_ENV !== 'production',
+  // A save to the space re-authors it and the open pages load again (\`watchSpace\` below).
+  devReload: DEVELOPING,
   health: { name: SERVER_NAME },
   adapters: createJsonAdapters({
-    offlineData,
+    offlineData: DEVELOPING ? OFFLINE_DATA : offlineData,
     deployment: { spaceId: 1, environment: 'main', revision: 0, pluginNames }
   }),
   plugins,
@@ -1966,6 +1990,56 @@ ${LISTEN_SNIPPET}
  * queue for whichever server runs next. A second ^C exits at once.
  */
 closeOnSignals(server);
+
+/**
+ * A save to the space, while developing: re-authored by \`src/author.ts\` in a process of its own — the only way to
+ * read every file of it again, which an import never does twice — and every open page loads again once it wrote the
+ * new documents. What it refuses is printed and the page keeps the last space that authored. A change to this file or
+ * to a plugin restarts the server instead (\`start:dev\` watches those).
+ */
+const RESTARTS = ['main.ts', 'plugins'];
+const watchSpace = (): void => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let authoring = false;
+  let again = false;
+  const author = (): void => {
+    if (authoring) {
+      again = true;
+
+      return;
+    }
+
+    authoring = true;
+    const child = spawn(process.execPath, [path.join(PROJECT_ROOT, 'src/author.ts')], {
+      cwd: PROJECT_ROOT,
+      stdio: 'inherit'
+    });
+    child.on('close', code => {
+      authoring = false;
+      if (code === 0) {
+        server.reloadPages();
+      }
+
+      if (again) {
+        again = false;
+        author();
+      }
+    });
+  };
+
+  watch(path.join(PROJECT_ROOT, 'src'), { recursive: true }, (_event, file) => {
+    if (!file || RESTARTS.some(name => file === name || file.startsWith(\`\${name}\${path.sep}\`))) {
+      return;
+    }
+
+    clearTimeout(timer);
+    timer = setTimeout(author, 100);
+  });
+};
+
+if (DEVELOPING) {
+  watchSpace();
+}
 `;
 var cloudMain = (name) => `import { mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
@@ -2116,7 +2190,7 @@ var filesUnder$1 = (root, folder = root) => readdirSync(folder, { withFileTypes:
 });
 /**
 * The skills a project carries: both for a project that renders a space, the CLI's alone for a plugin package. With
-* `root`, from the packages that project installed — what `plitzi skills update` brings it up to.
+* `root`, from the packages that project installed — what `plitzi upgrade skills` brings it up to.
 */
 var skillFiles = (names = SKILL_NAMES, root) => {
 	const resolvers = resolversFor(root);
@@ -2160,7 +2234,7 @@ import { space } from './space.ts';
 // \`--json\` answers in one object, for a tool or an agent; otherwise one line on success, the problems on failure.
 const json = process.argv.includes('--json');
 
-/** How many of the problems said have one fix \`plitzi fix\` can write in this source — and the line that says so. */
+/** How many of the warnings and suggestions said have one fix \`plitzi fix\` can write in this source — and the line that says so. */
 const fixableHint = (): string | undefined => {
   let count: number;
   try {
@@ -2172,18 +2246,21 @@ const fixableHint = (): string | undefined => {
   return count === 0 ? undefined : \`[fix] \${count} of these have one fix: npx plitzi fix shows it in your source, --write writes it\`;
 };
 
-/**
- * The skill an agent reads was copied from the SDK at one version: a newer SDK has what the older skill never taught.
- * Both versions, when they differ — \`npx @plitzi/cli skills update\` brings the skill up to the SDK.
- */
-const outdatedSkill = (): { skill: string; sdk: string } | undefined => {
-  let skill: string | undefined;
+/** A file's text, or undefined when there is none to read. */
+const readOptional = (file: string): string | undefined => {
   try {
-    skill = /^version: (.+)$/m.exec(readFileSync('.claude/skills/plitzi-authoring/SKILL.md', 'utf-8'))?.[1]?.trim();
+    return readFileSync(file, 'utf-8');
   } catch {
     return undefined;
   }
+};
 
+/**
+ * What of the project is older than the SDK installed: the skill an agent reads, copied from the SDK at one version,
+ * and the files the CLI wrote (\`.plitzi/scaffold.json\`) — a newer SDK has what neither taught nor wired. Each version
+ * that differs — \`npx plitzi upgrade\` brings both up.
+ */
+const outdated = (): { skill?: string; files?: string; sdk: string } | undefined => {
   const manifest: unknown = JSON.parse(
     readFileSync(createRequire(import.meta.url).resolve('@plitzi/sdk-authoring/package.json'), 'utf-8')
   );
@@ -2191,8 +2268,17 @@ const outdatedSkill = (): { skill: string; sdk: string } | undefined => {
     typeof manifest === 'object' && manifest !== null && 'version' in manifest && typeof manifest.version === 'string'
       ? manifest.version
       : undefined;
+  const skill = /^version: (.+)$/m.exec(readOptional('.claude/skills/plitzi-authoring/SKILL.md') ?? '')?.[1]?.trim();
+  const record: unknown = JSON.parse(readOptional('.plitzi/scaffold.json') ?? 'null');
+  const files =
+    typeof record === 'object' && record !== null && 'cli' in record && typeof record.cli === 'string'
+      ? record.cli
+      : undefined;
+  if (!sdk || ((!skill || skill === sdk) && (!files || files === sdk))) {
+    return undefined;
+  }
 
-  return skill && sdk && skill !== sdk ? { skill, sdk } : undefined;
+  return { ...(skill && skill !== sdk ? { skill } : {}), ...(files && files !== sdk ? { files } : {}), sdk };
 };
 
 try {
@@ -2200,30 +2286,35 @@ try {
   mkdirSync('space', { recursive: true });
   writeFileSync('space/offline-data.json', \`\${JSON.stringify({ schema, style }, null, 2)}\\n\`);
 
-  const outdated = outdatedSkill();
+  const behind = outdated();
   if (json) {
     console.log(
-      JSON.stringify({ ok: true, pages: schema.pages.length, warnings, suggestions, ...(outdated ? { outdated } : {}) })
+      JSON.stringify({ ok: true, pages: schema.pages.length, warnings, suggestions, ...(behind ? { outdated: behind } : {}) })
     );
   } else {
     for (const warning of warnings) {
       console.warn(\`[author] \${warning.code} · \${warning.message}\`);
     }
 
-    const hint = warnings.length > 0 ? fixableHint() : undefined;
-    if (hint) {
-      console.warn(hint);
-    }
-
     // Not problems: a shorter way to the same page, the one that saves the most elements first.
     for (const suggestion of suggestions) {
       const at = suggestion.at ? \` · \${suggestion.at}\` : '';
       console.warn(\`[suggest] \${suggestion.code} · \${suggestion.message} (saves \${suggestion.saves})\${at}\`);
     }
 
-    if (outdated) {
+    // After both: \`plitzi fix\` writes a warning's fix and a suggestion's alike, where it has one reading.
+    const hint = warnings.length + suggestions.length > 0 ? fixableHint() : undefined;
+    if (hint) {
+      console.warn(hint);
+    }
+
+    if (behind) {
+      const older = [
+        behind.skill ? \`the authoring skill is \${behind.skill}\` : '',
+        behind.files ? \`its files are from \${behind.files}\` : ''
+      ].filter(Boolean);
       console.warn(
-        \`[skills] the authoring skill is \${outdated.skill} and @plitzi/sdk-authoring is \${outdated.sdk}: npx @plitzi/cli skills update\`
+        \`[upgrade] \${older.join(' and ')}, and @plitzi/sdk-authoring is \${behind.sdk}: npx plitzi upgrade shows what changes, --write makes it\`
       );
     }
 
@@ -3473,6 +3564,10 @@ const ${name} = ({ label = ${tsString(title)}, start = 0, step = 1, className }:
    * It is what makes this an ELEMENT rather than a component that happens to be on the page: the element's id and
    * classes land on it, so the CSS authored on it applies, the builder can select it, a test can find it by name, and
    * the events and actions above are this element's.
+   *
+   * Its \`style\` is inline, and inline outranks every class: what \`CARD\` sets — its display, its padding — the CSS
+   * authored on the element can never change. Keep it to what the element cannot render without, and leave layout and
+   * position (\`position\`, \`width\`, \`margin\`) to the space's classes.
    */
   return (
     <RootElement
@@ -3815,6 +3910,35 @@ var scaffold = (answers) => ({
 	...visualFiles$1(answers),
 	...skillFiles()
 });
+/**
+* The files of a project that are this CLI's machinery rather than the project's own: what `plitzi upgrade` keeps up
+* with the CLI. Named, not inferred, so a file the scaffold starts a project with — its space, pages, plugins, data,
+* README, `.env` — can never be taken for one: those are the project's from the moment they are written.
+*
+* `package.json` is not among them: it is merged, never replaced (`upgrade packages`). Nor are the skills, which come
+* from the packages installed (`upgrade skills`).
+*/
+var MACHINERY = /* @__PURE__ */ new Set([
+	"src/author.ts",
+	"src/main.ts",
+	"src/preflight.css",
+	"index.html",
+	"vite.config.ts",
+	"tsconfig.json",
+	"tsconfig.build.json",
+	".gitignore",
+	"AGENTS.md",
+	"CLAUDE.md",
+	".prettierrc",
+	".prettierignore",
+	"eslint.config.mjs",
+	"playwright.config.ts",
+	"visual/home.spec.ts",
+	"src/plugins/README.md",
+	".yarnrc.yml",
+	"pnpm-workspace.yaml"
+]);
+var machineryFiles = (answers) => Object.fromEntries(Object.entries(scaffold(answers)).filter(([file]) => MACHINERY.has(file)));
 //#endregion
 //#region src/commands/existingProject.ts
 var LOCKFILES = [
@@ -3874,7 +3998,7 @@ var nearestWorkspace = async (from) => {
 var lockfileManager = async (dirs) => {
 	for (const dir of dirs) for (const [file, manager] of LOCKFILES) if (await exists(path.join(dir, file))) return manager;
 };
-var readText = async (file) => {
+var readText$1 = async (file) => {
 	try {
 		return await fs.readFile(file, "utf-8");
 	} catch {
@@ -3886,7 +4010,7 @@ var readText = async (file) => {
 * of its lists byte for byte, which is what says nobody has changed them since the CLI did.
 */
 var packageComponents = async (root) => {
-	const [elements, declarations] = await Promise.all([readText(path.join(root, "src/elements.ts")), readText(path.join(root, "src/declarations.ts"))]);
+	const [elements, declarations] = await Promise.all([readText$1(path.join(root, "src/elements.ts")), readText$1(path.join(root, "src/declarations.ts"))]);
 	if (elements === void 0 || declarations === void 0) return;
 	const components = [...elements.matchAll(/^import (\w+) from '\.\/(\w+)';$/gm)].filter(([, name, folder]) => name === folder).map(([, name]) => name);
 	return components.length > 0 && elementsRegistry(components) === elements && declarationsRegistry(components) === declarations ? components : void 0;
@@ -3896,7 +4020,7 @@ var packageComponents = async (root) => {
 * gives the file byte for byte, as with a plugin package's lists.
 */
 var projectDeclared = async (root) => {
-	const listed = await readText(path.join(root, "src/plugins/declarations.ts"));
+	const listed = await readText$1(path.join(root, "src/plugins/declarations.ts"));
 	if (listed === void 0) return;
 	const components = [...listed.matchAll(/^import \w+ from '\.\/(\w+)\/declaration\.ts';$/gm)].map(([, folder]) => folder);
 	return projectDeclarations(components) === listed ? components : void 0;
@@ -3918,7 +4042,7 @@ var plitziProject = async (root, packageJson) => {
 		...packageJson.dependencies,
 		...packageJson.devDependencies
 	};
-	const main = await readText(path.join(root, "src/main.ts"));
+	const main = await readText$1(path.join(root, "src/main.ts"));
 	if (!("@plitzi/plitzi-sdk" in dependencies) || main === void 0 || !/src\/plugins|\.\/plugins\//.test(main)) return;
 	const server = "@plitzi/sdk-server" in dependencies;
 	return {
@@ -4266,30 +4390,55 @@ var checkAt = async (browser, origin, pathname, width, scheme, handles, asked) =
 	page.on("response", (response) => {
 		if (response.status() >= 400 && response.url().startsWith(origin)) failedRequests.push(`${String(response.status())} ${response.url().slice(origin.length)}`);
 	});
-	if (!await page.goto(`${origin}${pathname}`, { waitUntil: "networkidle" }).catch(() => null)) return {
-		path: pathname,
-		width,
-		ok: false,
-		checked: 0,
-		problems: [`nothing answers at ${origin}${pathname}`],
-		consoleErrors,
-		failedRequests,
-		devTools: false
-	};
+	if (!await page.goto(`${origin}${pathname}`, { waitUntil: "networkidle" }).catch(() => null)) {
+		const issue = {
+			code: "no-answer",
+			message: `nothing answers at ${origin}${pathname}`,
+			width
+		};
+		return {
+			path: pathname,
+			width,
+			ok: false,
+			checked: 0,
+			problems: [issue.message],
+			issues: [issue],
+			hiddenAtWidth: [],
+			consoleErrors,
+			failedRequests,
+			devTools: false
+		};
+	}
 	const pageId = handles ? pageFor(handles, pathname) : void 0;
 	const report = handles && pageId ? await inspectPage(page, handles, { page: pageId }) : await inspectDocument(page);
 	const devTools = await readDevTools(page, asked);
-	const problems = [
-		...handles && !pageId ? [`no page of the space answers at ${pathname}`] : [],
-		...report.problems,
-		...devTools.flows.filter((flow) => flow.status === "failed").map(failedFlowText)
+	const noPage = handles && !pageId ? [{
+		code: "no-page",
+		message: `no page of the space answers at ${pathname}`,
+		width
+	}] : [];
+	const failedFlows = devTools.flows.filter((flow) => flow.status === "failed").map((flow) => ({
+		code: "flow-failed",
+		message: failedFlowText(flow),
+		...flow.on === void 0 ? {} : { elementId: flow.on },
+		width
+	}));
+	const issues = [
+		...noPage,
+		...report.issues.map((issue) => ({
+			...issue,
+			width
+		})),
+		...failedFlows
 	];
 	return {
 		path: pathname,
 		width,
-		ok: problems.length === 0 && consoleErrors.length === 0 && failedRequests.length === 0,
+		ok: issues.length === 0 && consoleErrors.length === 0 && failedRequests.length === 0,
 		checked: report.checked,
-		problems,
+		problems: issues.map((issue) => issue.message),
+		issues,
+		hiddenAtWidth: report.hiddenAtWidth,
 		consoleErrors,
 		failedRequests,
 		devTools: devTools.available,
@@ -4318,10 +4467,15 @@ var shapeOf = (value) => {
 	const text = value === void 0 ? "undefined" : JSON.stringify(value);
 	return text.length > 60 ? `${text.slice(0, 57)}…` : text;
 };
-var reportText = (report, asked) => {
+var reportText$1 = (report, asked) => {
 	const head = `${report.path} at ${String(report.width)} px`;
 	const held = heldText(report, asked);
-	if (report.ok) return [chalk.green(`✓ ${head} — ${report.checked > 0 ? `${String(report.checked)} elements on screen, ` : ""}nothing wrong`), ...held].join("\n");
+	const atWidth = report.hiddenAtWidth.length > 0 ? chalk.dim(`  · hidden at this width by a breakpoint, on purpose: ${report.hiddenAtWidth.join(", ")}`) : void 0;
+	if (report.ok) return [
+		chalk.green(`✓ ${head} — ${report.checked > 0 ? `${String(report.checked)} elements on screen, ` : ""}nothing wrong`),
+		...atWidth ? [atWidth] : [],
+		...held
+	].join("\n");
 	return [
 		chalk.red(`✗ ${head}`),
 		...report.problems.map((problem) => `  - ${problem}`),
@@ -4358,7 +4512,7 @@ var check = async (route, options) => {
 		};
 		const reports = [];
 		for (const width of widths) reports.push(await checkAt(browser, where.origin, route ?? "/", width, scheme, handles, asked));
-		console.log(options.json ? JSON.stringify(reports) : reports.map((report) => reportText(report, asked)).join("\n"));
+		console.log(options.json ? JSON.stringify(reports) : reports.map((report) => reportText$1(report, asked)).join("\n"));
 		if (reports.some((report) => !report.ok)) process.exitCode = 1;
 	} finally {
 		await browser.close();
@@ -5192,6 +5346,43 @@ var recordOrigin = async (root, { api, exported, source, pinned, project }) => {
 	});
 };
 //#endregion
+//#region src/commands/scaffoldRecord.ts
+/**
+* What the CLI last wrote of a project's machinery (`machineryFiles`): a digest of each file as it was written, never
+* the file — as `.plitzi/space.json` keeps of what a pull wrote. Enough for `plitzi upgrade` to tell a file nobody
+* touched since, which it may replace, from one somebody made their own, which it only shows.
+*
+* Kept where the CLI keeps its other state. A project without one — made before it existed, or a clone that did not
+* carry it — is not refused anything: every file that differs is then shown as the project's, for its author to take.
+*/
+var SCAFFOLD_RECORD_FILE = path.join(".plitzi", "scaffold.json");
+var digestOf = (contents) => createHash("sha256").update(contents).digest("hex");
+var readScaffoldRecord = async (root) => {
+	let parsed;
+	try {
+		parsed = JSON.parse(await fs.readFile(path.join(root, SCAFFOLD_RECORD_FILE), "utf-8"));
+	} catch {
+		return;
+	}
+	if (!e$1(parsed) || parsed.format !== 1 || typeof parsed.cli !== "string" || !e$1(parsed.files)) return;
+	const files = Object.fromEntries(Object.entries(parsed.files).filter((entry) => typeof entry[1] === "string"));
+	return {
+		format: 1,
+		cli: parsed.cli,
+		files
+	};
+};
+/** What the CLI wrote, file → its digest (`digestOf`), as `cli` wrote it. */
+var writeScaffoldRecord = async (root, cli, digests) => {
+	const record = {
+		format: 1,
+		cli,
+		files: Object.fromEntries(Object.entries(digests).sort(([a], [b]) => a.localeCompare(b)))
+	};
+	await fs.mkdir(path.join(root, ".plitzi"), { recursive: true });
+	await fs.writeFile(path.join(root, SCAFFOLD_RECORD_FILE), `${JSON.stringify(record, null, 2)}\n`);
+};
+//#endregion
 //#region src/commands/create.ts
 var MODES = ["server", "client"];
 var SOURCES = ["local", "cloud"];
@@ -5349,6 +5540,7 @@ var create = async (directory, options) => {
 		".env": envFromSpace(exported, answers, randomBytes(32).toString("hex"))
 	} : files);
 	const missing = fromSpace ? await writeFromSpace(target, fromSpace) : [];
+	await writeScaffoldRecord(target, CLI_VERSION, Object.fromEntries(Object.keys(machineryFiles(answers)).filter((file) => file in files).map((file) => [file, digestOf(files[file])])));
 	const wantsInstall = options.install !== false;
 	const installed = wantsInstall && await install(packageManager, target);
 	/**
@@ -5815,6 +6007,7 @@ var verdict = (before, written, after) => {
 };
 //#endregion
 //#region src/fix/sourceEdits.ts
+var one = (change) => ({ changes: [change] });
 var SINGLE = "'";
 var quoted = (text) => `${SINGLE}${text.replace(/\\/g, "\\\\").replaceAll(SINGLE, `\\${SINGLE}`)}${SINGLE}`;
 var literalText = (value) => typeof value === "string" ? quoted(value) : String(value);
@@ -5910,27 +6103,27 @@ var editKey = (ts, sourceFile, object, nested, edit) => {
 	const property = holder ? findProperty(ts, holder, edit.key) : void 0;
 	if (edit.op === "set") {
 		if (edit.value === void 0) return { unplaced: "there is no value to write" };
-		if (!holder || !property) return { change: insertInto(sourceFile, inner ?? object, edit.key, literalText(edit.value)) };
+		if (!holder || !property) return one(insertInto(sourceFile, inner ?? object, edit.key, literalText(edit.value)));
 		if (!ts.isPropertyAssignment(property) || !isLiteral(ts, property.initializer)) return { unplaced: `\`${edit.key}\` is not written as a value there` };
-		return { change: {
+		return one({
 			start: property.initializer.getStart(sourceFile),
 			end: property.initializer.getEnd(),
 			text: literalText(edit.value)
-		} };
+		});
 	}
 	if (!holder || !property) return { unplaced: `\`${edit.key}\` is not written in that call` };
-	if (edit.op === "remove") return { change: removeFromList(sourceFile, holder.properties, holder.properties.indexOf(property)) };
+	if (edit.op === "remove") return one(removeFromList(sourceFile, holder.properties, holder.properties.indexOf(property)));
 	if (edit.op === "rename" && edit.to !== void 0) {
-		if (ts.isShorthandPropertyAssignment(property)) return { change: {
+		if (ts.isShorthandPropertyAssignment(property)) return one({
 			start: property.getStart(sourceFile),
 			end: property.getEnd(),
 			text: `${keyText(edit.to)}: ${property.name.text}`
-		} };
-		if (ts.isPropertyAssignment(property)) return { change: {
+		});
+		if (ts.isPropertyAssignment(property)) return one({
 			start: property.name.getStart(sourceFile),
 			end: property.name.getEnd(),
 			text: keyText(edit.to)
-		} };
+		});
 	}
 	return { unplaced: `\`${edit.key}\` is not a property that edit applies to` };
 };
@@ -5946,18 +6139,18 @@ var editBinding = (ts, sourceFile, props, edit) => {
 			ts.forEachChild(node, visit);
 		};
 		visit(list);
-		return found ? { change: {
+		return found ? one({
 			start: found.getStart(sourceFile),
 			end: found.getEnd(),
 			text: quoted(edit.to)
-		} } : { unplaced: `"${edit.key}" is not written as a transformer there` };
+		}) : { unplaced: `"${edit.key}" is not written as a transformer there` };
 	}
 	if (edit.op !== "remove") return { unplaced: "that change to a binding has no one way to be written" };
-	const dropBind = () => ({ change: removeFromList(sourceFile, props.properties, props.properties.indexOf(bind)) });
+	const dropBind = () => one(removeFromList(sourceFile, props.properties, props.properties.indexOf(bind)));
 	if (ts.isObjectLiteralExpression(list)) {
 		const property = findProperty(ts, list, edit.key);
 		if (!property) return { unplaced: `the binding onto "${edit.key}" is not written there` };
-		return list.properties.length === 1 ? dropBind() : { change: removeFromList(sourceFile, list.properties, list.properties.indexOf(property)) };
+		return list.properties.length === 1 ? dropBind() : one(removeFromList(sourceFile, list.properties, list.properties.indexOf(property)));
 	}
 	if (ts.isArrayLiteralExpression(list)) {
 		const index = list.elements.findIndex((entry) => {
@@ -5966,10 +6159,95 @@ var editBinding = (ts, sourceFile, props, edit) => {
 			return to !== void 0 && ts.isPropertyAssignment(to) && ts.isStringLiteral(to.initializer) && to.initializer.text === edit.key;
 		});
 		if (index === -1) return { unplaced: `the binding onto "${edit.key}" is not written there` };
-		return list.elements.length === 1 ? dropBind() : { change: removeFromList(sourceFile, list.elements, index) };
+		return list.elements.length === 1 ? dropBind() : one(removeFromList(sourceFile, list.elements, index));
 	}
 	return { unplaced: "`bind` is not written as a literal there" };
 };
+/** The factories a child of the moved kind is written with: what a move may leave imported and unused. */
+var WORD_FACTORIES = ["text", "fontAwesome"];
+/**
+* `children: [text(words), fontAwesome({ icon })]` written as the element's own `content: words, icon` — the words
+* kept as written, a literal or an expression (`entry.label`). Only children written exactly so are moved: a `text`
+* handed options (a class, an id) or an icon with more than its class is something the element's own attributes would
+* not say, and is left for the author.
+*/
+var moveChildrenToContent = (ts, sourceFile, props, edit) => {
+	const children = findProperty(ts, props, "children");
+	if (!children || !ts.isPropertyAssignment(children) || !ts.isArrayLiteralExpression(children.initializer)) return { unplaced: "`children` is not written as a list there" };
+	let words;
+	let icon;
+	for (const child of children.initializer.elements) {
+		const call = ts.isCallExpression(child) && ts.isIdentifier(child.expression) && child.arguments.length === 1 ? {
+			factory: child.expression.text,
+			argument: child.arguments[0]
+		} : void 0;
+		if (call?.factory === "text" && !words) {
+			words = call.argument;
+			continue;
+		}
+		const iconProperty = call?.factory === "fontAwesome" && ts.isObjectLiteralExpression(call.argument) && call.argument.properties.length === 1 ? findProperty(ts, call.argument, "icon") : void 0;
+		if (iconProperty && ts.isPropertyAssignment(iconProperty) && !icon) {
+			icon = iconProperty.initializer;
+			continue;
+		}
+		return { unplaced: "a child carries more than its words or its icon there" };
+	}
+	if (Boolean(icon) !== (edit.icon !== void 0) || words === void 0 && edit.value !== "") return { unplaced: "the children written there are not the ones it holds" };
+	if (words && ts.isStringLiteral(words) && words.text !== edit.value) return { unplaced: "the words written there are not the ones it shows" };
+	if (icon && findProperty(ts, props, "icon")) return { unplaced: "it is written with an `icon` of its own already" };
+	const content = findProperty(ts, props, "content");
+	if (content && words && !(ts.isPropertyAssignment(content) && ts.isStringLiteral(content.initializer) && content.initializer.text === "")) return { unplaced: "it is written with words of its own beside its children" };
+	const written = [
+		words && `content: ${words.getText(sourceFile)}`,
+		icon && `icon: ${icon.getText(sourceFile)}`,
+		edit.iconPlacement && `iconPlacement: ${quoted(edit.iconPlacement)}`
+	].filter((part) => Boolean(part));
+	return {
+		changes: [...content && words ? [removeFromList(sourceFile, props.properties, props.properties.indexOf(content))] : [], {
+			start: children.getStart(sourceFile),
+			end: children.getEnd(),
+			text: written.join(", ")
+		}],
+		orphans: WORD_FACTORIES
+	};
+};
+/**
+* The named imports among `names` that nothing in the file uses any longer — what a move left behind, taken out with
+* the import that held only them.
+*/
+var pruneImports = (ts, fileName, text, names) => {
+	const sourceFile = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+	const used = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (ts.isIdentifier(node) && !ts.isImportSpecifier(node.parent)) used.add(node.text);
+		ts.forEachChild(node, visit);
+	};
+	visit(sourceFile);
+	const changes = [];
+	for (const statement of sourceFile.statements) {
+		const clause = ts.isImportDeclaration(statement) ? statement.importClause : void 0;
+		const bindings = clause?.namedBindings;
+		if (!clause || !bindings || !ts.isNamedImports(bindings)) continue;
+		const elements = bindings.elements;
+		const unused = elements.filter((element) => names.includes(element.name.text) && !used.has(element.name.text));
+		if (unused.length === 0) continue;
+		if (unused.length === elements.length && !clause.name) {
+			changes.push({
+				start: statement.getFullStart(),
+				end: statement.getEnd(),
+				text: ""
+			});
+			continue;
+		}
+		const kept = elements.filter((element) => !unused.includes(element));
+		changes.push({
+			start: bindings.getStart(sourceFile),
+			end: bindings.getEnd(),
+			text: `{ ${kept.map((element) => element.getText(sourceFile)).join(", ")} }`
+		});
+	}
+	return applyChanges(text, changes) ?? text;
+};
 /**
 * What an edit planned on a spec changes in the source that wrote it: the call at its position, the props it was
 * handed, and in them only what is written as a literal. Anything else — a value computed, props spread from a
@@ -5981,6 +6259,7 @@ var sourceEdit = (ts, sourceFile, position, edit) => {
 	const props = propsOf(ts, call);
 	if (!props) return { unplaced: "the call that wrote it was handed no props to edit" };
 	if (edit.on === "binding") return editBinding(ts, sourceFile, props, edit);
+	if (edit.on === "children") return moveChildrenToContent(ts, sourceFile, props, edit);
 	if (edit.on === "step") {
 		const step = edit.step ? stepIn(ts, props, edit.step.flow, edit.step.index) : void 0;
 		return step ? editKey(ts, sourceFile, step, "params", edit) : { unplaced: "the step is not written in that call" };
@@ -6047,7 +6326,8 @@ var editSources = async (root, fixes) => {
 		else placed.push({
 			fix,
 			file,
-			change: outcome.change
+			changes: outcome.changes,
+			orphans: outcome.orphans ?? []
 		});
 	}
 	const format = await projectFormatter(root);
@@ -6055,7 +6335,7 @@ var editSources = async (root, fixes) => {
 	const written = [];
 	for (const [file, { text }] of sources) {
 		const mine = placed.filter((entry) => entry.file === file);
-		const changed = applyChanges(text, mine.map((entry) => entry.change));
+		const changed = applyChanges(text, mine.flatMap((entry) => entry.changes));
 		if (changed === void 0) {
 			left.push(...mine.map((entry) => ({
 				fix: entry.fix,
@@ -6064,10 +6344,12 @@ var editSources = async (root, fixes) => {
 			continue;
 		}
 		if (mine.length > 0) {
+			const orphans = [...new Set(mine.flatMap((entry) => entry.orphans))];
+			const pruned = ts && orphans.length > 0 ? pruneImports(ts, file, changed, orphans) : changed;
 			files.push({
 				file,
 				before: text,
-				after: await formatLikeBefore(format, path.relative(root, file), text, changed)
+				after: await formatLikeBefore(format, path.relative(root, file), text, pruned)
 			});
 			written.push(...mine.map((entry) => entry.fix));
 		}
@@ -7380,10 +7662,23 @@ var pictureOf = async (browser, url, view) => {
 	if (view.waitFor) {
 		if (!await page.waitForSelector(selectorOf(view.waitFor), { timeout: 1e4 }).catch(() => null)) return { problem: `${view.waitFor} did not appear on ${url} within 10 s.` };
 	}
+	for (const target of [view.scrollTo, view.clip]) if (target && !await page.waitForSelector(selectorOf(target), { timeout: 1e4 }).catch(() => null)) return { problem: `${target} is not on ${url}.` };
+	if (view.scrollTo) await page.locator(selectorOf(view.scrollTo)).first().scrollIntoViewIfNeeded();
 	return {
 		page,
-		png: await page.screenshot({ fullPage: true })
+		png: await capture(page, framing(view))
+	};
+};
+var framing = (view) => {
+	if (view.clip) return {
+		kind: "element",
+		selector: selectorOf(view.clip)
 	};
+	return view.viewport || view.scrollTo ? { kind: "viewport" } : { kind: "page" };
+};
+var capture = (page, how) => {
+	if (how.kind === "element") return page.locator(how.selector).first().screenshot();
+	return page.screenshot({ fullPage: how.kind === "page" });
 };
 var regionsText = (regions) => regions.map((region) => `${region.name} ${String(region.changed)}%`).join(", ");
 /** Compared frame to frame: the most each region changed between two that follow each other. */
@@ -7408,6 +7703,11 @@ var shot = async (route, options) => {
 		fail(browser.problem);
 		return;
 	}
+	if (options.compare && (options.clip || options.scrollTo || options.viewport)) {
+		await browser.close();
+		fail("`--compare` sets the whole page beside the other site, section by section: leave out --clip, --scroll-to and --viewport.");
+		return;
+	}
 	try {
 		const pathname = route ?? "/";
 		const view = {
@@ -7415,8 +7715,12 @@ var shot = async (route, options) => {
 			height: options.height ?? 800,
 			scheme: options.scheme ?? "light",
 			reducedMotion: options.reducedMotion === true,
-			...options.waitFor ? { waitFor: options.waitFor } : {}
+			...options.waitFor ? { waitFor: options.waitFor } : {},
+			...options.clip ? { clip: options.clip } : {},
+			...options.scrollTo ? { scrollTo: options.scrollTo } : {},
+			...options.viewport ? { viewport: true } : {}
 		};
+		const how = framing(view);
 		const name = pathname === "/" ? "home" : pathname.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "");
 		const out = path.resolve(project.root, options.out ?? `visual/.shots/${name}-${String(view.width)}-${view.scheme}.png`);
 		const base = out.replace(/\.png$/, "");
@@ -7427,7 +7731,7 @@ var shot = async (route, options) => {
 		}
 		await mkdir(path.dirname(out), { recursive: true });
 		await writeFile(out, taken.png);
-		const regions = await taken.page.evaluate(pageRegions, void 0);
+		const regions = how.kind === "page" ? await taken.page.evaluate(pageRegions, void 0) : [];
 		const report = {
 			path: pathname,
 			width: view.width,
@@ -7459,11 +7763,15 @@ var shot = async (route, options) => {
 			const pictures = [taken.png];
 			for (let frame = 1; frame < frames; frame += 1) {
 				await taken.page.waitForTimeout(every);
-				pictures.push(await taken.page.screenshot({ fullPage: true }));
+				pictures.push(await capture(taken.page, how));
 			}
 			const diffs = [];
 			for (let frame = 1; frame < pictures.length; frame += 1) diffs.push(await comparePictures(taken.page, dataUrl(pictures[frame - 1]), dataUrl(pictures[frame]), regions));
-			const moved = framesMoved(diffs);
+			const whole = how.kind === "element" ? options.clip ?? "element" : "viewport";
+			const moved = how.kind === "page" ? framesMoved(diffs) : [{
+				name: whole,
+				changed: Math.max(0, ...diffs.map((diff) => diff.changed))
+			}];
 			report.frames = {
 				count: frames,
 				every,
@@ -7486,52 +7794,347 @@ var shot = async (route, options) => {
 	}
 };
 //#endregion
-//#region src/commands/skills.ts
+//#region src/commands/upgrade.ts
 /**
-* `plitzi skills update`: the Plitzi skills in `.claude/skills/` brought up to the packages the project has installed.
+* `plitzi upgrade`: a project brought up to the CLI it now has — what `create` would write today, for what is the
+* CLI's to write. Every part on its own, or all of them:
+*
+* - `files`: the machinery (`machineryFiles`) — `author.ts`, `main.ts`, the Playwright and lint configs, AGENTS.md. One
+*   nobody changed since the CLI wrote it is replaced; one the project made its own is shown as a diff and left, unless
+*   `--take` names it.
+* - `packages`: `package.json` merged — the scripts and dependencies it lacks added, `@plitzi/*` raised to this
+*   version. A script or a dependency the project has is never changed; then the install.
+* - `skills`: `.claude/skills/plitzi-*` from the packages installed, each replaced whole.
+* - `renames`: a name a version renamed, still written in the source (`canTemplate`), at its file and line — and with
+*   `--write`, renamed.
+*
+* Shown by default; `--write` makes it. What the space is — its pages, plugins, data — is the project's, never named.
 *
-* A skill is copied into a project when `create` writes it and then stays as it was, while `@plitzi/sdk-authoring` moves
-* on — and an agent reading the older one is taught a surface the SDK no longer has, or misses what it gained. Only the
-* `plitzi-*` skills are touched, each replaced whole (a reference it no longer has goes with it); any other skill in the
-* folder is the project's.
+*   plitzi upgrade                    # everything, as it would be
+*   plitzi upgrade skills --write     # only the skills
+*   plitzi upgrade --write --take src/author.ts
 */
-var readSkill = async (file) => {
+var UPGRADE_PARTS = [
+	"files",
+	"packages",
+	"skills",
+	"renames"
+];
+var RENAMES = [{
+	name: "canTemplate",
+	to: "canSnippet",
+	since: "0.38.0",
+	what: "a plugin’s builder config key"
+}, ...[
+	"authorTemplate",
+	"validateTemplate",
+	"TemplateSpec",
+	"AuthoredTemplate"
+].map((name) => ({
+	name,
+	to: name.replace("Template", "Snippet"),
+	since: "0.38.0",
+	what: "what the builder saves from a subtree is a snippet",
+	from: "@plitzi/sdk-authoring"
+}))];
+/** The project's own source: TypeScript and JavaScript under `src/` and `visual/`, never what was installed or built. */
+var sourceFiles = async (root) => {
+	const found = [];
+	const walk = async (dir) => {
+		let entries;
+		try {
+			entries = await fs.readdir(path.join(root, dir), { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const relative = path.join(dir, entry.name);
+			if (entry.isDirectory()) await walk(relative);
+			else if (/\.(ts|tsx|mts|js|jsx|mjs)$/.test(entry.name)) found.push(relative);
+		}
+	};
+	await walk("src");
+	await walk("visual");
+	return found;
+};
+var wordOf = (name) => new RegExp(`\\b${name}\\b`, "g");
+var importsFrom = (text, name, from) => new RegExp(`import\\s+(type\\s+)?\\{[^}]*\\b${name}\\b[^}]*\\}\\s*from\\s*['"]${from}['"]`).test(text);
+var renamesIn = (file, text) => RENAMES.filter((rename) => !rename.from || importsFrom(text, rename.name, rename.from)).flatMap((rename) => text.split("\n").flatMap((line, index) => wordOf(rename.name).test(line) ? [{
+	file,
+	line: index + 1,
+	name: rename.name,
+	to: rename.to,
+	since: rename.since,
+	what: rename.what
+}] : []));
+/** The lowest version a range allows, as numbers: `^0.38.2` → [0, 38, 2]. */
+var floorOf = (range) => {
+	const match = /(\d+)\.(\d+)\.(\d+)/.exec(range);
+	return match ? match.slice(1).map(Number) : void 0;
+};
+var isBelow = (range, than) => {
+	const [a, b] = [floorOf(range), floorOf(than)];
+	if (!a || !b) return false;
+	const at = a.findIndex((part, index) => part !== b[index]);
+	return at !== -1 && a[at] < b[at];
+};
+var stringsOf = (value) => e$1(value) ? Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string")) : {};
+var planPackages = (text, answers) => {
+	const parsed = JSON.parse(text);
+	const ours = JSON.parse(packageJson$1(answers));
+	const project = e$1(parsed) ? { ...parsed } : {};
+	const scaffold = e$1(ours) ? ours : {};
+	const plan = {
+		added: [],
+		raised: [],
+		scripts: [],
+		ownScripts: []
+	};
+	const scripts = stringsOf(project.scripts);
+	for (const [name, command] of Object.entries(stringsOf(scaffold.scripts))) if (!(name in scripts)) {
+		plan.scripts.push({
+			name,
+			command
+		});
+		scripts[name] = command;
+	} else if (scripts[name] !== command) plan.ownScripts.push({
+		name,
+		yours: scripts[name],
+		ours: command
+	});
+	const sections = {
+		dependencies: stringsOf(project.dependencies),
+		devDependencies: stringsOf(project.devDependencies)
+	};
+	for (const section of ["dependencies", "devDependencies"]) for (const [name, range] of Object.entries(stringsOf(scaffold[section]))) {
+		const where = name in sections.dependencies ? "dependencies" : name in sections.devDependencies ? "devDependencies" : void 0;
+		if (!where) {
+			plan.added.push({
+				section,
+				name,
+				range
+			});
+			sections[section][name] = range;
+		} else if (name.startsWith("@plitzi/") && isBelow(sections[where][name], range)) {
+			plan.raised.push({
+				section: where,
+				name,
+				from: sections[where][name],
+				to: range
+			});
+			sections[where][name] = range;
+		}
+	}
+	if (plan.added.length + plan.raised.length + plan.scripts.length === 0) return plan;
+	const sorted = (entries) => Object.fromEntries(Object.entries(entries).sort(([a], [b]) => a.localeCompare(b)));
+	const indent = /^\{\n([ \t]+)"/.exec(text)?.[1] ?? "  ";
+	const merged = {
+		...project,
+		scripts,
+		dependencies: sorted(sections.dependencies),
+		devDependencies: sorted(sections.devDependencies)
+	};
+	return {
+		...plan,
+		after: `${JSON.stringify(merged, null, indent)}\n`
+	};
+};
+var readText = async (file) => {
 	try {
 		return await fs.readFile(file, "utf-8");
 	} catch {
 		return;
 	}
 };
-var skillsUpdate = async () => {
-	const project = await projectHere("whose skills to update");
-	if (!project) return;
-	const folder = path.join(project.root, ".claude/skills");
-	const present = [];
+var planFiles = async (root, files, recorded, take) => Promise.all(Object.entries(files).map(async ([file, ours]) => {
+	const yours = await readText(path.join(root, file));
+	if (yours === void 0) return {
+		file,
+		status: "added",
+		ours
+	};
+	if (yours === ours) return {
+		file,
+		status: "current",
+		ours,
+		yours
+	};
+	if (recorded[file] === digestOf(yours)) return {
+		file,
+		status: "updated",
+		ours,
+		yours
+	};
+	return {
+		file,
+		status: take.includes("all") || take.includes(file) ? "taken" : "yours",
+		ours,
+		yours
+	};
+}));
+var WRITES = /* @__PURE__ */ new Set([
+	"added",
+	"updated",
+	"taken"
+]);
+var planSkills = async (root) => {
+	const files = skillFiles(SKILL_NAMES, root);
+	const plans = [];
 	for (const name of SKILL_NAMES) {
-		const skill = await readSkill(path.join(folder, name, "SKILL.md"));
-		if (skill !== void 0) present.push({
+		const skill = `.claude/skills/${name}/SKILL.md`;
+		if (!(skill in files)) continue;
+		const now = files[skill];
+		const was = await readText(path.join(root, skill));
+		if (was !== now) plans.push({
 			name,
-			was: skillVersion(skill)
+			...was === void 0 ? {} : { was: skillVersion(was) ?? "unversioned" },
+			now: skillVersion(now) ?? "unversioned"
 		});
 	}
-	if (present.length === 0) {
-		fail(`No Plitzi skill in ${path.relative(process.cwd(), folder) || ".claude/skills"}: \`plitzi create\` writes them into a project it makes.`);
-		return;
-	}
-	const files = skillFiles(present.map(({ name }) => name), project.root);
-	for (const { name, was } of present) {
-		const own = Object.fromEntries(Object.entries(files).filter(([file]) => file.startsWith(`.claude/skills/${name}/`)));
-		if (Object.keys(own).length === 0) {
-			console.log(chalk.yellow(`${name}: its package is not installed here, so it was left as it was.`));
-			continue;
-		}
-		await fs.rm(path.join(folder, name), {
+	return {
+		plans,
+		files
+	};
+};
+var writeSkills = async (root, plans, files) => {
+	for (const { name } of plans) {
+		await fs.rm(path.join(root, ".claude/skills", name), {
 			recursive: true,
 			force: true
 		});
-		await writeFiles(project.root, own);
-		const now = skillVersion(own[`.claude/skills/${name}/SKILL.md`] ?? "");
-		console.log(chalk.green(`${name}: ${was ?? "unversioned"} → ${now ?? "unversioned"}`));
+		await writeFiles(root, Object.fromEntries(Object.entries(files).filter(([file]) => file.startsWith(`.claude/skills/${name}/`))));
+	}
+};
+/** What a project was made with, as far as its machinery cares: none of it reads the key or the environment. */
+var answersFor = async (root, plitzi, manager) => {
+	const name = (await readPackageJson(root))?.name ?? path.basename(root);
+	const managerVersion = detectManagerVersion(manager, root);
+	return {
+		name,
+		mode: plitzi.mode,
+		source: plitzi.source,
+		key: "",
+		environment: "main",
+		packageManager: manager,
+		...managerVersion === void 0 ? {} : { managerVersion }
+	};
+};
+var statusLine = {
+	current: (file) => chalk.dim(`  = ${file}`),
+	added: (file) => chalk.green(`  + ${file}`),
+	updated: (file) => chalk.green(`  ~ ${file}`),
+	taken: (file) => chalk.yellow(`  ~ ${file} (yours, taken)`),
+	yours: (file) => chalk.yellow(`  ! ${file} — yours: the CLI's version below; --take ${file} to replace it`)
+};
+var reportText = (report) => {
+	const lines = [chalk.bold(`plitzi upgrade → ${report.version}${report.write ? "" : " (shown; --write makes it)"}`)];
+	if (report.files) {
+		const changed = report.files.filter((file) => file.status !== "current");
+		lines.push(changed.length === 0 ? chalk.green("files: up to date") : "files:");
+		for (const file of changed) {
+			lines.push(statusLine[file.status](file.file));
+			if (file.diff) lines.push(chalk.dim(file.diff));
+		}
+	}
+	if (report.packages) {
+		const { added, raised, scripts, ownScripts, install: installed } = report.packages;
+		const none = added.length + raised.length + scripts.length === 0;
+		lines.push(none ? chalk.green("packages: up to date") : "packages:");
+		lines.push(...raised.map((entry) => chalk.green(`  ~ ${entry.name} ${entry.from} → ${entry.to}`)), ...added.map((entry) => chalk.green(`  + ${entry.name} ${entry.range} (${entry.section})`)), ...scripts.map((entry) => chalk.green(`  + script ${entry.name}: ${entry.command}`)), ...ownScripts.map((entry) => chalk.dim(`  = script ${entry.name} is yours ("${entry.yours}"; the CLI writes "${entry.ours}")`)));
+		if (installed === "needed") lines.push(chalk.yellow("  then install, for the new versions to be the ones that run"));
+		else if (installed === "failed") lines.push(chalk.red("  the install failed: the reason is in the output above"));
+	}
+	if (report.skills) {
+		lines.push(report.skills.length === 0 ? chalk.green("skills: up to date") : "skills:");
+		lines.push(...report.skills.map((skill) => chalk.green(`  ~ ${skill.name}: ${skill.was ?? "none"} → ${skill.now ?? "?"}`)));
+	}
+	if (report.renames) {
+		lines.push(report.renames.length === 0 ? chalk.green("renames: none written") : "renames:");
+		lines.push(...report.renames.map((found) => chalk.yellow(`  ${report.write ? "~" : "!"} ${found.file}:${String(found.line)} ${found.name} → ${found.to} (${found.since}: ${found.what})`)));
+	}
+	return lines.join("\n");
+};
+var upgrade = async (parts, options) => {
+	const unknown = parts.filter((part) => !UPGRADE_PARTS.includes(part));
+	if (unknown.length > 0) {
+		fail(`Not a part of a project to upgrade: ${unknown.join(", ")}. The parts are ${UPGRADE_PARTS.join(", ")}.`);
+		return;
+	}
+	const project = await projectHere("to upgrade");
+	if (!project) return;
+	const wanted = new Set(parts.length === 0 ? UPGRADE_PARTS : parts);
+	const { root } = project;
+	const manager = project.packageManager ?? "npm";
+	const write = Boolean(options.write);
+	const report = {
+		version: CLI_VERSION,
+		write
+	};
+	const plitzi = project.plitzi?.kind === "project" ? project.plitzi : void 0;
+	if (!plitzi && (wanted.has("files") || wanted.has("packages"))) {
+		fail("Its files and package.json are those of a project `plitzi create` wrote, and this is not one: `plitzi upgrade skills renames` brings up the rest.");
+		return;
+	}
+	const answers = plitzi ? await answersFor(root, plitzi, manager) : void 0;
+	if (answers && wanted.has("files")) {
+		const ours = machineryFiles(answers);
+		const recorded = (await readScaffoldRecord(root))?.files ?? {};
+		const plans = await planFiles(root, ours, recorded, options.take ?? []);
+		if (write) {
+			const written = plans.filter((plan) => WRITES.has(plan.status));
+			await writeFiles(root, Object.fromEntries(written.map((plan) => [plan.file, plan.ours])));
+			await writeScaffoldRecord(root, CLI_VERSION, Object.fromEntries(plans.flatMap((plan) => {
+				if (WRITES.has(plan.status) || plan.status === "current") return [[plan.file, digestOf(plan.ours)]];
+				return plan.file in recorded ? [[plan.file, recorded[plan.file]]] : [];
+			})));
+		}
+		report.files = plans.map((plan) => ({
+			file: plan.file,
+			status: plan.status,
+			...plan.status === "yours" && plan.yours !== void 0 ? { diff: unifiedDiff(plan.file, plan.yours, plan.ours) } : {}
+		}));
+	}
+	if (answers && wanted.has("packages")) {
+		const text = await readText(path.join(root, "package.json"));
+		const plan = text === void 0 ? void 0 : planPackages(text, answers);
+		if (plan) {
+			const { after, ...rest } = plan;
+			let installed;
+			if (after !== void 0) {
+				installed = "needed";
+				if (write) {
+					await fs.writeFile(path.join(root, "package.json"), after);
+					if (options.install !== false && !options.json) installed = await install(manager, root) ? "done" : "failed";
+				}
+			}
+			report.packages = {
+				...rest,
+				...installed === void 0 ? {} : { install: installed }
+			};
+		}
+	}
+	if (wanted.has("skills")) {
+		const { plans, files } = await planSkills(root);
+		if (write) await writeSkills(root, plans, files);
+		report.skills = plans;
+	}
+	if (wanted.has("renames")) {
+		const found = [];
+		for (const file of await sourceFiles(root)) {
+			const text = await readText(path.join(root, file));
+			const inFile = text === void 0 ? [] : renamesIn(file, text);
+			if (write && text !== void 0 && inFile.length > 0) {
+				const renamed = [...new Set(inFile.map((entry) => entry.name))].reduce((result, name) => result.replace(wordOf(name), RENAMES.find((rename) => rename.name === name)?.to ?? name), text);
+				await fs.writeFile(path.join(root, file), renamed);
+			}
+			found.push(...inFile);
+		}
+		report.renames = found;
+	}
+	console.log(options.json ? JSON.stringify(report) : reportText(report));
+	if (report.packages?.install === "failed") {
+		process.exitCode = 1;
+		console.error(chalk.dim(`\`${installCommand(manager)}\` failed.`));
 	}
 };
 //#endregion
@@ -7747,7 +8350,7 @@ var positiveInteger = (value) => {
 * documented, which was the problem — a person had to read four things and write three files correctly before they
 * could tell whether any of it worked. The same holds for an element of one's own, which is the second thing it does.
 */
-program.name("plitzi").description("Plitzi command line");
+program.name("plitzi").description("Plitzi command line").version(CLI_VERSION);
 /** A flag given more than once, as the list of every value. */
 var collect = (value, previous) => [...previous, value];
 /** The flags that shape a PROJECT: given with `--plugin`, they are a mistake worth saying rather than ignoring. */
@@ -7783,9 +8386,10 @@ program.command("import").argument("<url>", "The page to start from: https://exa
 	768,
 	390
 ])).option("-f, --force", "Write over what --out already holds").option("--json", "One object, for a tool or an agent").option(...API_OPTION).action((url, options) => importPage(url, options));
-program.command("shot").argument("[path]", "The page: /about. The home page when left out").description("A picture of one page of the running project — and, asked, how it differs from another or what moves").addOption(new Option("--width <px>", "The viewport width").argParser(width).default(1280)).addOption(new Option("--height <px>", "The viewport height (the picture is the whole page)").argParser(positiveInteger).default(800)).addOption(schemeOption()).option("-o, --out <file>", "Where the picture goes. visual/.shots/<page>-<width>-<scheme>.png by default").option("--compare <url>", "Another site: the same page there, side by side, and how much differs by section").addOption(new Option("--frames <n>", "Pictures taken one after another: which sections move (a marquee, an autoplay)").argParser(positiveInteger)).addOption(new Option("--every <ms>", "How far apart --frames are taken").argParser(positiveInteger).default(500)).option("--wait-for <element>", "An element to wait for first: its name (data-plitzi-el) or a CSS selector").option("--reduced-motion", "As a visitor who asked for less motion").option("--json", "One object, for a tool or an agent").action((path, options) => shot(path, options));
+program.command("shot").argument("[path]", "The page: /about. The home page when left out").description("A picture of one page of the running project — and, asked, how it differs from another or what moves").addOption(new Option("--width <px>", "The viewport width").argParser(width).default(1280)).addOption(new Option("--height <px>", "The viewport height (the picture is the whole page unless --viewport, --scroll-to or --clip)").argParser(positiveInteger).default(800)).addOption(schemeOption()).option("-o, --out <file>", "Where the picture goes. visual/.shots/<page>-<width>-<scheme>.png by default").option("--compare <url>", "Another site: the same page there, side by side, and how much differs by section").addOption(new Option("--frames <n>", "Pictures taken one after another: which sections move (a marquee, an autoplay)").argParser(positiveInteger)).addOption(new Option("--every <ms>", "How far apart --frames are taken").argParser(positiveInteger).default(500)).option("--wait-for <element>", "An element to wait for first: its name (data-plitzi-el) or a CSS selector").option("--clip <element>", "Only this element — its name or a CSS selector — scrolled to wherever it is").option("--scroll-to <element>", "The page scrolled until this element is in view; the picture is the screen there").option("--viewport", "Only what fits the viewport, not the whole page").option("--reduced-motion", "As a visitor who asked for less motion").option("--json", "One object, for a tool or an agent").action((path, options) => shot(path, options));
 program.command("explain").argument("[name]", "An element, a step, a trigger, a problem’s code or a transformer: container, navigate, class-and-css").description("What a name means when authoring a space — what it takes, fires, reads and how it is written").option("--list <kind>", "Every name of a kind: elements, steps, triggers, codes, transformers").option("--json", "One object, for a tool or an agent").action((name, options) => explainCommand(name, options));
-program.command("skills").description("The Plitzi skills an agent reads in .claude/skills/").command("update").description("Bring them up to the Plitzi packages this project has installed, each replaced whole").action(() => skillsUpdate());
+program.command("upgrade").alias("update").argument("[parts...]", `Only these: ${UPGRADE_PARTS.join(", ")} — every one when none is named`).description("Bring the project up to this CLI: its machinery files, package.json, the skills and renamed names — shown; with --write made").option("--write", "Make the changes: files nobody changed replaced, package.json merged and installed, names renamed").option("--take <files...>", "Replace these files of your own too (`all` for every one), after reading their diff").option("--no-install", "Write package.json and leave the install to you").option("--json", "One object, for a tool or an agent").action((parts, options) => upgrade(parts, options));
+program.command("skills").description("The Plitzi skills an agent reads in .claude/skills/").command("update").description("Bring them up to the Plitzi packages this project has installed, each replaced whole (`upgrade skills --write`)").action(() => upgrade(["skills"], { write: true }));
 program.command("data").description("The JSON a project serves (public/data), without reading it whole").command("describe").argument("<file>", "A JSON file: public/data/products.json").description("Its shape — every field, its type, whether every row has it — and one row of its longest list").option("--json", "One object: { shape, example }").action((file, options) => dataDescribe(file, options));
 program.command("upload").description("Put something of this project on the space you work in").command("plugin").argument("[zip]", "The zip plitzi pack plugin built. Left out: the one packed in this project.").description("Upload a packed plugin to a CDN of the space you work in, and install it there").option("--cdn <identifier>", "Which of the space’s CDNs the bucket is in.").option("--bucket <identifier>", "Which public bucket the plugin goes in. Asked for when there are several.").option(...API_OPTION).action((zip, options) => uploadPluginCommand(zip, options));
 var functions = program.command("functions").description("The space’s own server code: functions/ in this project is a working copy of it");