@cellajs/cli 0.4.2 → 0.6.0

package/dist/index.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env tsx
 
 // src/cella-cli.ts
-import { existsSync as existsSync13, statSync as statSync3 } from "fs";
+import { existsSync as existsSync14, statSync as statSync3 } from "fs";
 import { join as join19, resolve as resolve7 } from "path";
-import process9 from "process";
+import process11 from "process";
 
 // src/cli.ts
-import process5 from "process";
+import process6 from "process";
 import { select } from "@inquirer/prompts";
 import { Command } from "commander";
 
@@ -57,7 +57,7 @@ import { z as z2 } from "zod";
 
 // src/config/types.ts
 import { z } from "zod";
-var PACKAGE_JSON_SYNC_KEYS = [
+var PACKAGE_JSON_KEYS = [
   "dependencies",
   "devDependencies",
   "peerDependencies",
@@ -75,7 +75,9 @@ var cellaConfigSchema = z.object({
     upstreamBranch: z.string().min(1).optional(),
     upstreamTrack: z.enum(["release", "branch"]).optional(),
     releaseBase: z.string().min(1).optional(),
-    packageJsonSync: z.array(z.enum(PACKAGE_JSON_SYNC_KEYS)).optional(),
+    packageJsonKeys: z.array(z.enum(PACKAGE_JSON_KEYS)).optional(),
+    mergePackageJson: z.boolean().optional(),
+    packageJsonSync: z.array(z.enum(PACKAGE_JSON_KEYS)).optional(),
     syncWithPackages: z.boolean().optional(),
     fileLinkMode: z.enum(["commit", "file"]).optional()
   }).strict(),
@@ -156,13 +158,18 @@ function resolveAppModuleFolders(repoPath) {
 // src/utils/config.ts
 var DEFAULT_UPSTREAM_REMOTE = "cella-upstream";
 var DEFAULT_BRANCH = "main";
-var DEFAULT_SYNC_PREFIX = "cella/sync";
-var DEFAULT_PACKAGE_JSON_SYNC = ["dependencies", "devDependencies"];
+var UPGRADE_BRANCH_PREFIX = "cella/upgrade";
+var TEMPORARY_BRANCH_PREFIXES = [UPGRADE_BRANCH_PREFIX, "cella/sync"];
+var DEFAULT_PACKAGE_JSON_KEYS = ["dependencies", "devDependencies"];
+var RENAMED_SETTINGS = { packageJsonSync: "packageJsonKeys", syncWithPackages: "mergePackageJson" };
+function renamedSettingWarnings(config) {
+  return Object.entries(RENAMED_SETTINGS).filter(([old]) => old in config.settings).map(([old, current]) => `settings.${old} is renamed to ${current}: rename it in ${CONFIG_FILE}`);
+}
 function isUpstreamRepo(repoPath) {
   return JSON.parse(readFileSync(join2(repoPath, "package.json"), "utf8")).name === "cella";
 }
 function isTemporarySyncBranch(branch) {
-  return branch.startsWith(`${DEFAULT_SYNC_PREFIX}/`);
+  return TEMPORARY_BRANCH_PREFIXES.some((prefix) => branch.startsWith(`${prefix}/`));
 }
 function resolveReleaseBase(settings) {
   return settings.releaseBase ?? DEFAULT_BRANCH;
@@ -171,7 +178,7 @@ function buildTemporarySyncBranch() {
   const now = /* @__PURE__ */ new Date();
   const pad2 = (n) => String(n).padStart(2, "0");
   const stamp = `${now.getFullYear()}${pad2(now.getMonth() + 1)}${pad2(now.getDate())}-${pad2(now.getHours())}${pad2(now.getMinutes())}`;
-  return `${DEFAULT_SYNC_PREFIX}/${stamp}`;
+  return `${UPGRADE_BRANCH_PREFIX}/${stamp}`;
 }
 function resolveUpstream(settings) {
   const track = settings.upstreamTrack ?? "release";
@@ -201,6 +208,8 @@ async function loadConfig(forkPath) {
 ${z2.prettifyError(result.error)}`);
   }
   const config = result.data;
+  config.settings.packageJsonKeys ??= config.settings.packageJsonSync;
+  config.settings.mergePackageJson ??= config.settings.syncWithPackages;
   const appModuleFolders = resolveAppModuleFolders(realForkPath);
   if (appModuleFolders.length > 0) {
     const existing = config.overrides?.ignored ?? [];
@@ -213,16 +222,16 @@ ${z2.prettifyError(result.error)}`);
 }
 
 // src/utils/display.ts
-import { resolve as resolve2 } from "path";
-import process4 from "process";
+import { resolve as resolve3 } from "path";
+import process5 from "process";
 
 // package.json
 var package_default = {
   name: "@cellajs/cli",
-  version: "0.4.2",
+  version: "0.6.0",
   private: false,
   license: "MIT",
-  description: "CLI for managing your monorepo and syncing with upstream Cella.",
+  description: "CLI for managing your monorepo and upgrading it with upstream Cella.",
   repository: {
     type: "git",
     url: "https://github.com/cellajs/cella-cli"
@@ -334,377 +343,19 @@ var package_default = {
         200
       ],
       "footer-max-line-length": [
-        0,
-        "always",
-        200
-      ]
-    }
-  }
-};
-
-// src/utils/display.ts
-var VERSION = package_default.version;
-var DIVIDER = "\u2500".repeat(60);
-var MENU_DIVIDER = "\u2500".repeat(40);
-var COMMIT_LIST_MAX = 50;
-var warningMark = colors_default.yellow("\u26A0");
-var checkMark = colors_default.green("\u2713");
-var activeSpinner = null;
-var jsonMode = false;
-function setJsonMode(enabled) {
-  jsonMode = enabled;
-  if (!enabled) return;
-  const toStderr = (...args) => {
-    process4.stderr.write(`${args.map((a) => typeof a === "string" ? a : String(a)).join(" ")}
-`);
-  };
-  console.info = toStderr;
-  console.warn = toStderr;
-}
-function writeStdout(text) {
-  process4.stdout.write(text.endsWith("\n") ? text : `${text}
-`);
-}
-function printHeader() {
-  const left = "\u29C8 cella cli";
-  const right = "cellajs.com";
-  const padding = Math.max(1, 60 - `${left} v${VERSION}`.length - right.length);
-  console.info();
-  console.info(`${colors_default.cyan(left)}${colors_default.dim(` \xB7 v${VERSION}`)}${colors_default.cyan(`${" ".repeat(padding)}${right}`)}`);
-  console.info(DIVIDER);
-  console.info();
-}
-function createSpinner(text) {
-  const enabled = !jsonMode && !getEnv("VITEST") && getEnv("NODE_ENV") !== "test" && !!process4.stdout.isTTY;
-  const frames = ["-", "\\", "|", "/"];
-  let frame = 0;
-  let timer;
-  const spinner = {
-    text,
-    stop() {
-      clearInterval(timer);
-      if (enabled) process4.stdout.write("\r\x1B[2K");
-    }
-  };
-  const render = () => process4.stdout.write(`\r${colors_default.cyan(frames[frame++ % frames.length])} ${spinner.text}`);
-  if (enabled) {
-    render();
-    timer = setInterval(render, 80);
-  }
-  activeSpinner = spinner;
-  return spinner;
-}
-function spinnerSuccess(message, detail) {
-  stopSpinner();
-  if (!message) return;
-  console.info(`${checkMark} ${message}`);
-  if (detail) {
-    console.info(`  ${colors_default.dim(detail)}`);
-    console.info();
-  }
-}
-function spinnerFail(message) {
-  stopSpinner();
-  console.info(`${colors_default.red("\u2717")} ${message}`);
-}
-function spinnerText(text) {
-  if (activeSpinner) {
-    activeSpinner.text = text;
-  }
-}
-function stopSpinner() {
-  if (activeSpinner) {
-    activeSpinner.stop();
-    activeSpinner = null;
-  }
-}
-function hyperlink(label, url) {
-  if (!url) return label;
-  const safeUrl = url.replace(/[\x00-\x1f\x7f]/g, "");
-  return `\x1B]8;;${safeUrl}\x07${label}\x1B]8;;\x07`;
-}
-function formatFetchedUpstreamDetail(commitCount, commits, upstreamGitHubUrl, maxShownCommits = COMMIT_LIST_MAX) {
-  const lines = [`${plural(commitCount, "new commit")} since last merge`];
-  const shown = commits.slice(0, maxShownCommits);
-  for (const commit of shown) {
-    const shortHash = commit.hash.slice(0, 7);
-    const commitUrl = upstreamGitHubUrl ? `${upstreamGitHubUrl}/commit/${commit.hash}` : void 0;
-    const hashLabel = hyperlink(shortHash, commitUrl);
-    lines.push(`  ${hashLabel} "${commit.message}" (${commit.date})`);
-  }
-  if (commitCount > shown.length) {
-    lines.push(`  ... and ${commitCount - shown.length} more`);
-  }
-  return lines.join("\n");
-}
-function printSectionHeader(title) {
-  console.info();
-  console.info(title);
-  console.info(DIVIDER);
-  console.info();
-}
-function formatFileDateInfo(filePath, commit, date, options) {
-  if (!date) return "";
-  const { upstreamGitHubUrl: url, upstreamBranch, fileLinkMode = "commit" } = options;
-  let link = commit?.slice(0, 9) ?? "";
-  if (url && fileLinkMode === "file" && upstreamBranch) {
-    link = hyperlink(filePath.split("/").pop() || filePath, `${url}/blob/${upstreamBranch}/${filePath}`);
-  } else if (url) {
-    link = commit ? hyperlink(link, `${url}/commit/${commit}`) : "";
-  }
-  return colors_default.dim(` \u2260 ${date} ${link}`);
-}
-function formatMergeInProgressDetail(conflictCount, autoMergedFiles, linkOptions, maxFiles = 100) {
-  const lines = [`${conflictCount} conflicts to resolve in IDE`];
-  if (autoMergedFiles.length === 0) {
-    return lines.join("\n");
-  }
-  lines.push("");
-  lines.push(`  auto-merged files (${autoMergedFiles.length}):`);
-  const { forkPath } = linkOptions;
-  const shown = autoMergedFiles.slice(0, maxFiles);
-  for (const filePath of shown) {
-    lines.push(`  - ${forkPath ? hyperlink(filePath, `vscode://file${resolve2(forkPath, filePath)}`) : filePath}`);
-  }
-  if (autoMergedFiles.length > shown.length) {
-    lines.push(`  ... + ${autoMergedFiles.length - shown.length} more`);
-  }
-  return lines.join("\n");
-}
-var statusConfig = {
-  behind: { icon: colors_default.cyan("\u2193"), label: "behind", color: colors_default.cyan, description: "upstream changed, will sync" },
-  diverged: { icon: colors_default.magenta("\u21C5"), label: "diverged", color: colors_default.magenta, description: "both changed, will merge" },
-  drifted: { icon: colors_default.yellow("!"), label: "drifted", color: colors_default.yellow, description: "fork changed (at risk)" },
-  ahead: { icon: colors_default.blue("\u2191"), label: "ahead", color: colors_default.blue, description: "fork changed (protected)" },
-  local: { icon: colors_default.green("+"), label: "local", color: colors_default.green, description: "local file in cella folders" },
-  pinned: { icon: colors_default.green("\u2A00"), label: "pinned", color: colors_default.green, description: "both changed, fork wins" },
-  ignored: { icon: colors_default.gray("\u2A02"), label: "ignored", color: colors_default.gray },
-  identical: { icon: colors_default.gray("\u2713"), label: "identical", color: colors_default.gray, description: "no changes" },
-  deleted: { icon: colors_default.red("\u2717"), label: "deleted", color: colors_default.red },
-  renamed: { icon: colors_default.blue("\u2192"), label: "renamed", color: colors_default.blue }
-};
-var summaryStatusConfig = {
-  ...statusConfig,
-  managed: {
-    icon: colors_default.cyan("\u25C7"),
-    label: "managed",
-    color: colors_default.cyan,
-    description: "package.jsons & cella/cella.config.ts handled separately"
-  },
-  ignored: { ...statusConfig.ignored, description: "protected by ignored config" }
-};
-function printSummary(summary, title = "summary") {
-  printSectionHeader(colors_default.cyan(title));
-  const maxCount = Math.max(...Object.values(summary));
-  const countWidth = String(maxCount).length + 1;
-  const groups = [
-    ["managed", "ignored"],
-    ["identical"],
-    ["ahead", "local", "drifted"],
-    ["diverged", "pinned"],
-    ["behind"]
-  ];
-  for (const group of groups) {
-    if (group !== groups[0]) console.info();
-    for (const status of group) {
-      const { icon, label, color, description } = summaryStatusConfig[status];
-      const countStr = color(String(summary[status]).padStart(countWidth));
-      console.info(`  ${icon} ${countStr}  ${label.padEnd(15)}${description ? colors_default.dim(description) : ""}`);
-    }
-  }
-}
-function printFileSection(files, title, linkOptions, options) {
-  if (files.length === 0) return;
-  printSectionHeader(`${title} ${colors_default.dim(`\xB7 ${files.length} files`)}`);
-  const useUpstream = options.dateSource === "upstream";
-  const maxLines = 100;
-  const shown = files.length > maxLines ? files.slice(0, maxLines) : files;
-  for (const file of shown) {
-    const icon = typeof options.icon === "string" ? options.icon : options.icon(file);
-    const commit = useUpstream ? file.upstreamCommit : file.changedCommit;
-    const date = useUpstream ? file.upstreamChangedAt : file.changedAt;
-    const dateInfo = formatFileDateInfo(file.path, commit, date, linkOptions);
-    console.info(`  ${icon} ${file.path}${dateInfo}${options.suffix?.(file) ?? ""}`);
-  }
-  if (files.length > maxLines) {
-    console.info(colors_default.dim(`  ... + ${files.length - maxLines} more`));
-  }
-  if (options.hint) {
-    console.info();
-    for (const line of Array.isArray(options.hint) ? options.hint : [options.hint]) {
-      console.info(colors_default.dim(`  ${line}`));
-    }
-  }
-}
-function filesWithStatus(files, status) {
-  return files.filter((f) => f.status === status && !isManagedFile(f.path));
-}
-function printFileGroup(files, status, linkOptions, options) {
-  const config = statusConfig[status];
-  const title = options?.title ?? `${config.icon} ${config.label}`;
-  printFileSection(filesWithStatus(files, status), title, linkOptions, { ...options, icon: config.icon });
-}
-function findProtectedBehind(files) {
-  return files.filter((file) => file.upstreamChanged && !isManagedFile(file.path));
-}
-var PROTECTED_BEHIND_HINT = "pinned/ignored files where upstream also changed since the last sync; the fork side wins on conflict, so review what upstream changed and adopt what you need.";
-function protectionIcon(file) {
-  return file.isIgnored ? statusConfig.ignored.icon : statusConfig.pinned.icon;
-}
-function formatUpstreamChangedLines(file) {
-  if (file.upstreamChangedLines === void 0) return "";
-  return colors_default.yellow(` \xB7 ${plural(file.upstreamChangedLines, "line")} changed upstream`);
-}
-function formatUpstreamLinesAbsent(file) {
-  const n = file.upstreamLinesAbsent ?? 0;
-  return n > 0 ? colors_default.yellow(` \xB7 ${plural(n, "upstream line")} absent`) : "";
-}
-function printAnalysisFileGroups(files, linkOptions) {
-  const protectedBehind = findProtectedBehind(files);
-  printFileGroup(files, "behind", linkOptions, {
-    title: colors_default.cyan("\u2193 behind on upstream")
-  });
-  printFileGroup(files, "ahead", linkOptions, {
-    title: `${colors_default.blue("\u2191 protected in fork")}`,
-    suffix: formatUpstreamLinesAbsent,
-    hint: [
-      "these files have fork changes but are protected (pinned); upstream did not change them since the last sync.",
-      "pinned files keep the fork copy whole; a count here is upstream content the fork never received, deliberately or not: `analyze --unpinned` shows what a merge would bring in."
-    ]
-  });
-  printFileSection(protectedBehind, `${warningMark} ${colors_default.yellow("protected but behind upstream")}`, linkOptions, {
-    icon: protectionIcon,
-    suffix: formatUpstreamChangedLines,
-    dateSource: "upstream",
-    hint: PROTECTED_BEHIND_HINT
-  });
-  printFileGroup(files, "drifted", linkOptions, {
-    title: `${warningMark} ${colors_default.yellow("drifted from upstream")}`,
-    hint: "these files have fork changes but are not pinned or ignored."
-  });
-  printFileGroup(files, "diverged", linkOptions, {
-    title: `${colors_default.magenta("\u21C5 diverged")}`,
-    hint: "both fork and upstream changed.",
-    dateSource: "upstream"
-  });
-}
-function printSyncComplete(result, options = {}) {
-  const updated = result.files.filter((file) => file.status === "behind" || file.status === "diverged").length;
-  const diverged = result.files.filter((file) => file.status === "diverged").length;
-  const merged = result.autoMergedFiles?.length ?? Math.max(0, diverged - result.conflicts.length);
-  const conflicts = result.conflicts.length;
-  console.info();
-  if (options.stagedBranch) {
-    console.info(`${checkMark} sync merge staged on '${options.stagedBranch}'`);
-    console.info(
-      colors_default.dim(`  ${updated} files updated, ${merged} auto-merged, ${conflicts} conflicts. committing next...`)
-    );
-  } else {
-    console.info(`${checkMark} sync complete`);
-    console.info(colors_default.dim(`  ${updated} files updated, ${merged} auto-merged, ${conflicts} conflicts`));
-  }
-  printProtectedConflicts(result);
-  console.info();
-}
-function printProtectedConflicts(result) {
-  const paths = result.protectedConflicts ?? [];
-  if (paths.length === 0) return;
-  const byPath = new Map(result.files.map((file) => [file.path, file]));
-  console.info();
-  console.info(
-    `${warningMark} ${colors_default.yellow(
-      `${plural(paths.length, "protected file kept", "protected files kept")} the fork version, dropping upstream changes:`
-    )}`
-  );
-  for (const path of paths) {
-    const file = byPath.get(path);
-    const icon = file ? protectionIcon(file) : statusConfig.pinned.icon;
-    console.info(`  ${icon} ${path}${file ? formatUpstreamChangedLines(file) : ""}`);
-  }
-  console.info(colors_default.dim(`  ${PROTECTED_BEHIND_HINT}`));
-}
-function plural(count3, singular, pluralForm = `${singular}s`) {
-  return `${count3} ${count3 === 1 ? singular : pluralForm}`;
-}
-function printIgnoredUpstreamChanges(result) {
-  const groups = result.ignoredUpstreamChanges ?? [];
-  if (groups.length === 0) return;
-  const total = groups.reduce((count3, group) => count3 + group.paths.length, 0);
-  console.info();
-  console.info(
-    `${warningMark} ${colors_default.yellow(`ignored paths changed upstream \xB7 ${plural(total, "file")} under ${plural(groups.length, "entry", "entries")}`)}`
-  );
-  for (const group of groups) {
-    const counts = [plural(group.paths.length, "file")];
-    if (group.added > 0) counts.push(`${group.added} new`);
-    if (group.deleted > 0) counts.push(`${group.deleted} deleted`);
-    console.info(`  ${statusConfig.ignored.icon} ${group.entry} ${colors_default.dim(`\xB7 ${counts.join(", ")}`)}`);
-  }
-  console.info(colors_default.dim("  the fork left these untouched and ignored paths never sync: review and adopt what you need."));
-}
-function printUpstreamOverrideChanges(result) {
-  const report = result.upstreamOverrides;
-  if (!report) return;
-  console.info();
-  if (report.kind === "unreadable") {
-    const side = report.side === "base" ? "the last sync point" : "the incoming ref";
-    console.info(
-      colors_default.dim(`upstream sync config not compared: upstream ${CONFIG_FILE} is missing or unreadable at ${side}`)
-    );
-    return;
-  }
-  const lines = [];
-  for (const list of ["pinned", "ignored", "packageJsonSync"]) {
-    for (const entry of report[list].added) lines.push(`  ${colors_default.green("+")} ${list}: ${entry}`);
-    for (const entry of report[list].removed) {
-      lines.push(`  ${colors_default.red("\u2212")} ${list}: ${entry}${colors_default.dim(" \xB7 dropped upstream, still in your config")}`);
-    }
-  }
-  console.info(
-    `${warningMark} ${colors_default.yellow(`upstream changed its sync config \xB7 ${plural(lines.length, "entry", "entries")} to review`)}`
-  );
-  for (const line of lines) console.info(line);
-  console.info(colors_default.dim(`  ${CONFIG_FILE} never syncs: add or drop these by hand where they fit your app.`));
-}
-function findMaskingPins(files) {
-  return files.filter(
-    (file) => file.isPinned && !isManagedFile(file.path) && file.status === "behind" && file.existsInFork && file.existsInUpstream
-  );
-}
-function printMaskingPinWarning(files) {
-  const masking = findMaskingPins(files);
-  if (masking.length === 0) return;
-  console.info();
-  console.info(
-    `${warningMark} ${colors_default.yellow(
-      `${plural(masking.length, "pinned file matches", "pinned files match")} the previous upstream but changed upstream:`
-    )}`
-  );
-  console.info(colors_default.yellow("  the pin keeps the old fork copy and silently drops those upstream changes:"));
-  for (const file of masking) {
-    console.info(colors_default.dim(`  \u2A00 ${file.path}`));
-  }
-  console.info(
-    colors_default.yellow("  if the fork never customized these, unpin them in cella/cella.config.ts to take upstream.")
-  );
-  console.info();
-}
-function printEngineReports(result, title) {
-  printSummary(result.summary, title);
-  printIgnoredUpstreamChanges(result);
-  printUpstreamOverrideChanges(result);
-  printMaskingPinWarning(result.files);
-}
-
-// src/utils/overrides.ts
-import { existsSync as existsSync5 } from "fs";
-import { join as join6 } from "path";
+        0,
+        "always",
+        200
+      ]
+    }
+  }
+};
 
 // src/utils/git.ts
 import { execFile } from "child_process";
 import { existsSync as existsSync3 } from "fs";
 import { mkdir as mkdir2, readdir, rmdir, unlink } from "fs/promises";
-import { dirname as dirname2, join as join4, resolve as resolve3 } from "path";
+import { dirname as dirname2, join as join4, resolve as resolve2 } from "path";
 import { promisify } from "util";
 
 // src/utils/manifest.ts
@@ -840,7 +491,7 @@ async function commitSquash(cwd, message) {
   await git(["commit", "-m", message], cwd, { skipEditor: true });
 }
 async function gitPath(cwd, file) {
-  return resolve3(cwd, await git(["rev-parse", "--git-path", file], cwd));
+  return resolve2(cwd, await git(["rev-parse", "--git-path", file], cwd));
 }
 async function stageAll(cwd) {
   await git(["add", "-A"], cwd);
@@ -848,6 +499,10 @@ async function stageAll(cwd) {
 async function mergeInProgress(cwd) {
   return await revParse(cwd, "MERGE_HEAD") !== null;
 }
+function splitPrNumber(subject) {
+  const match = /\s*\(#(\d+)\)\s*$/.exec(subject);
+  return match ? { subject: subject.slice(0, match.index), pr: Number(match[1]) } : { subject };
+}
 async function getShortSha(cwd, ref) {
   return git(["rev-parse", "--short", ref], cwd);
 }
@@ -920,16 +575,16 @@ async function countCommitsBetween(cwd, fromRef, toRef) {
   return Number.parseInt(output.trim(), 10) || 0;
 }
 async function listCommitsBetween(cwd, fromRef, toRef, limit) {
-  const args = ["log", "--format=%H%x1f%s%x1f%ar", "--reverse", `${fromRef}..${toRef}`];
+  const args = ["log", "--format=%H%x1f%s%x1f%ar%x1f%ct", "--reverse", `${fromRef}..${toRef}`];
   if (limit) args.push(`-n${limit}`);
   const output = await git(args, cwd, { ignoreErrors: true });
   if (!output) return [];
   const commits = [];
   for (const line of output.split("\n")) {
     if (!line) continue;
-    const [hash, message, date] = line.split("");
+    const [hash, message, date, timestamp] = line.split("");
     if (!hash || !message || !date) continue;
-    commits.push({ hash, message, date });
+    commits.push({ hash, message, date, timestamp: Number(timestamp) || void 0 });
   }
   return commits;
 }
@@ -1100,16 +755,25 @@ async function cleanupEmptyParentDirs(cwd, relativePath) {
   } catch {
   }
 }
+var LAST_UPGRADE_REF = "refs/cella/last-upgrade";
+var LEGACY_LAST_UPGRADE_REF = "refs/cella/last-sync";
 async function storeLastSyncRef(cwd, upstreamHash) {
-  await git(["update-ref", "refs/cella/last-sync", upstreamHash], cwd);
+  await git(["update-ref", LAST_UPGRADE_REF, upstreamHash], cwd);
   const head = await revParse(cwd, "HEAD");
-  if (head) await git(["update-ref", "refs/cella/last-sync-head", head], cwd);
+  if (head) await git(["update-ref", `${LAST_UPGRADE_REF}-head`, head], cwd);
 }
 async function stagePath(cwd, path) {
   await git(["add", "--", path], cwd, { ignoreErrors: true });
 }
+async function readStoredSyncRefs(cwd) {
+  for (const name of [LAST_UPGRADE_REF, LEGACY_LAST_UPGRADE_REF]) {
+    const ref = await revParse(cwd, name);
+    if (ref) return { ref, head: await revParse(cwd, `${name}-head`) };
+  }
+  return null;
+}
 async function getStoredSyncRef(cwd) {
-  return revParse(cwd, "refs/cella/last-sync");
+  return (await readStoredSyncRefs(cwd))?.ref ?? null;
 }
 async function readManifestAtRef(cwd, ref) {
   const raw = await git(["show", `${ref}:${MANIFEST_FILE}`], cwd, { ignoreErrors: true });
@@ -1158,11 +822,11 @@ async function unshallowRepository(cwd) {
 ${error.message}` : "";
     throw new Error(
       `this is a shallow clone and its full history could not be restored automatically.
-Sync needs the complete history to find the common ancestor with upstream. Restore it with:
+An upgrade needs the complete history to find the common ancestor with upstream. Restore it with:
 
   git fetch --unshallow
 
-then re-run sync.${detail}`
+then re-run the upgrade.${detail}`
     );
   }
 }
@@ -1188,20 +852,20 @@ async function ensureSyncBase(cwd, headRef, upstreamRef) {
   }
   if (!baseSha) {
     throw new Error(
-      `no common ancestor between the fork and '${upstreamRef}', and no sync base could be determined.
+      `no common ancestor between the fork and '${upstreamRef}', and no upgrade base could be determined.
 
 This fork has unrelated history with upstream (typical for a create-cella scaffold, or after
 upstream squashed its history) and no recorded base commit exists after fetching
-upstream. Seed it manually with the upstream commit the fork was created from, then re-run sync:
+upstream. Seed it manually with the upstream commit the fork was created from, then re-run the upgrade:
 
-  git update-ref refs/cella/last-sync <upstream-sha>
+  git update-ref ${LAST_UPGRADE_REF} <upstream-sha>
 `
     );
   }
   const root = await getRootCommit(cwd, headRef);
-  if (!root) throw new Error("could not determine the fork's root commit to bootstrap sync ancestry");
+  if (!root) throw new Error("could not determine the fork's root commit to bootstrap upgrade ancestry");
   await git(["replace", "-f", "--graft", root, baseSha], cwd);
-  await git(["update-ref", "refs/cella/last-sync", baseSha], cwd);
+  await git(["update-ref", LAST_UPGRADE_REF, baseSha], cwd);
 }
 async function isAncestor(cwd, ancestor, descendant) {
   try {
@@ -1212,14 +876,13 @@ async function isAncestor(cwd, ancestor, descendant) {
   }
 }
 async function getLegacySyncRef(cwd, headRef) {
-  const storedRef = await getStoredSyncRef(cwd);
-  if (!storedRef) return null;
-  const storedHead = await revParse(cwd, "refs/cella/last-sync-head");
-  if (storedHead) {
+  const stored = await readStoredSyncRefs(cwd);
+  if (!stored) return null;
+  if (stored.head) {
     const currentHead = await revParse(cwd, headRef);
-    if (currentHead && currentHead === storedHead) return null;
+    if (currentHead && currentHead === stored.head) return null;
   }
-  return storedRef;
+  return stored.ref;
 }
 async function getEffectiveMergeBase(cwd, headRef, upstreamRef) {
   const gitBase = await getMergeBase(cwd, headRef, upstreamRef);
@@ -1231,36 +894,432 @@ async function getEffectiveMergeBase(cwd, headRef, upstreamRef) {
   if (recordedIsNewer && recorded !== gitBase) {
     return { base: recorded, isStale: true, storedRef: recorded };
   }
-  return { base: gitBase, isStale: false, storedRef: recorded };
+  return { base: gitBase, isStale: false, storedRef: recorded };
+}
+async function withTemporarySyncBaseGraft(cwd, headRef, baseSha, fn) {
+  const headSha = await revParse(cwd, headRef);
+  if (!headSha || !await commitObjectExists(cwd, baseSha)) return fn();
+  if (await isAncestor(cwd, baseSha, headSha)) return fn();
+  const existingReplacement = await git(["replace", "-l", headSha], cwd, { ignoreErrors: true });
+  if (existingReplacement) return fn();
+  const parentsRaw = await git(["log", "-1", "--format=%P", headSha], cwd, { ignoreErrors: true });
+  const parents = parentsRaw ? parentsRaw.split(/\s+/) : [];
+  await git(["replace", "-f", "--graft", headSha, ...parents, baseSha], cwd);
+  try {
+    return await fn();
+  } finally {
+    await git(["replace", "-d", headSha], cwd, { ignoreErrors: true });
+  }
+}
+
+// src/utils/layout.ts
+import process4 from "process";
+import { stripVTControlCharacters } from "util";
+function terminalColumns() {
+  const columns = process4.stdout.isTTY ? process4.stdout.columns : void 0;
+  return Math.max(60, columns || 80);
+}
+function visibleWidth(text) {
+  return stripVTControlCharacters(text).length;
+}
+function padVisible(text, width, align = "start") {
+  const padding = " ".repeat(Math.max(0, width - visibleWidth(text)));
+  return align === "start" ? `${text}${padding}` : `${padding}${text}`;
+}
+function fitText(text, width) {
+  if (text.length <= width) return text;
+  return `${text.slice(0, Math.max(0, width - 1)).trimEnd()}\u2026`;
+}
+var AGE_STEPS = [
+  [90 * 60, 60, "m"],
+  [36 * 3600, 3600, "h"],
+  [14 * 86400, 86400, "d"],
+  [70 * 86400, 7 * 86400, "w"],
+  [365 * 86400, 30 * 86400, "mo"]
+];
+function shortAge(epochSeconds, nowMs = Date.now()) {
+  const seconds = Math.max(0, Math.round(nowMs / 1e3 - epochSeconds));
+  if (seconds < 60) return "now";
+  for (const [below, unit, suffix] of AGE_STEPS) {
+    if (seconds < below) return `${Math.max(1, Math.round(seconds / unit))}${suffix}`;
+  }
+  return `${Math.floor(seconds / (365 * 86400))}y`;
+}
+function compactCount(count3) {
+  if (count3 < 1e4) return String(count3);
+  if (count3 < 1e6) return `${(count3 / 1e3).toFixed(1)}k`;
+  return `${(count3 / 1e6).toFixed(1)}M`;
+}
+
+// src/utils/display.ts
+var VERSION = package_default.version;
+var DIVIDER = "\u2500".repeat(60);
+var MENU_DIVIDER = "\u2500".repeat(40);
+var COMMIT_LIST_MAX = 50;
+var COMMIT_STEP_MAX = 10;
+var STEP_LABEL_WIDTH = 9;
+var STEP_INDENT = 2 + STEP_LABEL_WIDTH + 2;
+var warningMark = colors_default.yellow("\u26A0");
+var checkMark = colors_default.green("\u2713");
+var activeSpinner = null;
+var jsonMode = false;
+function setJsonMode(enabled) {
+  jsonMode = enabled;
+  if (!enabled) return;
+  const toStderr = (...args) => {
+    process5.stderr.write(`${args.map((a) => typeof a === "string" ? a : String(a)).join(" ")}
+`);
+  };
+  console.info = toStderr;
+  console.warn = toStderr;
+}
+function writeStdout(text) {
+  process5.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+}
+function printHeader() {
+  const left = "\u29C8 cella cli";
+  const version = ` \xB7 v${VERSION}`;
+  const right = "cellajs.com";
+  const padding = Math.max(1, DIVIDER.length - `${left}${version}${right}`.length);
+  console.info();
+  console.info(`${colors_default.cyan(left)}${colors_default.dim(version)}${colors_default.cyan(`${" ".repeat(padding)}${right}`)}`);
+  console.info(DIVIDER);
+  console.info();
+}
+function createSpinner(text) {
+  const enabled = !jsonMode && !getEnv("VITEST") && getEnv("NODE_ENV") !== "test" && !!process5.stdout.isTTY;
+  const frames = ["-", "\\", "|", "/"];
+  let frame = 0;
+  let timer;
+  const spinner = {
+    text,
+    stop() {
+      clearInterval(timer);
+      if (enabled) process5.stdout.write("\r\x1B[2K");
+    }
+  };
+  const render = () => process5.stdout.write(`\r${colors_default.cyan(frames[frame++ % frames.length])} ${spinner.text}`);
+  if (enabled) {
+    render();
+    timer = setInterval(render, 80);
+  }
+  activeSpinner = spinner;
+  return spinner;
+}
+function printStep(label, detail, mark = checkMark) {
+  stopSpinner();
+  const [first = "", ...rest] = (detail ?? "").split("\n");
+  console.info(`${mark} ${colors_default.bold(label.padEnd(STEP_LABEL_WIDTH))}  ${first}`.trimEnd());
+  for (const line of rest) console.info(line ? `${" ".repeat(STEP_INDENT)}${line}` : "");
+}
+function spinnerSuccess(message, detail) {
+  stopSpinner();
+  if (!message) return;
+  console.info(`${checkMark} ${message}`);
+  if (detail) {
+    console.info(`  ${colors_default.dim(detail)}`);
+    console.info();
+  }
+}
+function spinnerFail(message) {
+  stopSpinner();
+  console.info(`${colors_default.red("\u2717")} ${message}`);
+}
+function spinnerText(text) {
+  if (activeSpinner) {
+    activeSpinner.text = text;
+  }
+}
+function stopSpinner() {
+  if (activeSpinner) {
+    activeSpinner.stop();
+    activeSpinner = null;
+  }
+}
+function hyperlink(label, url) {
+  if (!url) return label;
+  const safeUrl = url.replace(/[\x00-\x1f\x7f]/g, "");
+  return `\x1B]8;;${safeUrl}\x07${label}\x1B]8;;\x07`;
+}
+function styleSubject(subject) {
+  if (/^chore(\([^)]*\))?: release\b/.test(subject)) return colors_default.dim(subject);
+  const breaking = /^([a-z]+(\([^)]*\))?!:)/.exec(subject);
+  return breaking ? `${colors_default.yellow(breaking[1])}${subject.slice(breaking[1].length)}` : subject;
+}
+function formatCheckoutStep(checkout) {
+  const { forkPath, branch, headSha, changeCount, upstream } = checkout;
+  const parts = [
+    changeCount === 0 ? "clean" : `${plural(changeCount, "uncommitted change")}, not included in the analysis`
+  ];
+  if (upstream.upstream && (upstream.ahead > 0 || upstream.behind > 0)) {
+    parts.push(`${upstream.ahead} ahead, ${upstream.behind} behind ${upstream.upstream}`);
+  }
+  const line = `${branch} @ ${headSha}${colors_default.dim(` \xB7 ${parts.join(" \xB7 ")}`)}`;
+  return resolve3(forkPath) === resolve3(process5.cwd()) ? line : `${line}
+${colors_default.dim(forkPath)}`;
+}
+function formatUpstreamStep(upstream) {
+  const { label, sha, baseSha, pinned, commitCount, commits, githubUrl } = upstream;
+  const since = commitCount === 0 ? "no new commits since the last upgrade" : `${plural(commitCount, "new commit")} since the last upgrade at ${baseSha}`;
+  return [
+    `${label} @ ${sha}${colors_default.dim(`${pinned ? " \xB7 --ref" : ""} \xB7 ${since}`)}`,
+    ...formatUpstreamCommits(commitCount, commits, githubUrl)
+  ].join("\n");
+}
+function formatUpstreamCommits(commitCount, commits, upstreamGitHubUrl, options = {}) {
+  const { columns = terminalColumns(), max = COMMIT_STEP_MAX, nowMs } = options;
+  const shown = commits.slice(-max).reverse();
+  const rows = shown.map((commit) => ({ commit, ...splitPrNumber(commit.message) }));
+  const prWidth = Math.max(0, ...rows.map((row) => row.pr ? `#${row.pr}`.length : 0));
+  const ages = rows.map((row) => row.commit.timestamp ? shortAge(row.commit.timestamp, nowMs) : "");
+  const ageWidth = Math.max(0, ...ages.map((age) => age.length));
+  const subjectWidth = Math.max(
+    20,
+    columns - STEP_INDENT - 7 - 2 - (prWidth ? prWidth + 2 : 0) - (ageWidth ? ageWidth + 2 : 0)
+  );
+  const lines = rows.map((row, index) => {
+    const hash = hyperlink(
+      row.commit.hash.slice(0, 7),
+      upstreamGitHubUrl && `${upstreamGitHubUrl}/commit/${row.commit.hash}`
+    );
+    const subject = fitText(row.subject, subjectWidth);
+    let line = `${colors_default.dim(hash)}  ${padVisible(styleSubject(subject), subjectWidth)}`;
+    if (prWidth) {
+      const pr = row.pr ? hyperlink(`#${row.pr}`, upstreamGitHubUrl && `${upstreamGitHubUrl}/pull/${row.pr}`) : "";
+      line += `  ${colors_default.dim(padVisible(pr, prWidth))}`;
+    }
+    if (ageWidth) line += `  ${colors_default.dim(ages[index].padStart(ageWidth))}`;
+    return line.trimEnd();
+  });
+  if (commitCount > shown.length) lines.push(colors_default.dim(`+ ${commitCount - shown.length} earlier`));
+  return lines;
+}
+function printNextSteps(steps) {
+  if (steps.length === 0) return;
+  printSectionHeader(colors_default.cyan("next steps"));
+  for (const [index, step] of steps.entries()) {
+    const label = step.label.padEnd(STEP_INDENT - 5);
+    console.info(`  ${colors_default.dim(String(index + 1))} ${colors_default.bold(label)} ${step.line}`.trimEnd());
+    for (const detail of step.details ?? []) console.info(`${" ".repeat(STEP_INDENT)}${detail}`);
+  }
+}
+function printSectionHeader(title) {
+  console.info();
+  console.info(title);
+  console.info(DIVIDER);
+  console.info();
+}
+function formatMergeInProgressDetail(conflictCount, autoMergedFiles, linkOptions, maxFiles = 100) {
+  const lines = [`${plural(conflictCount, "conflict")} to resolve in your editor`];
+  if (autoMergedFiles.length === 0) {
+    return lines.join("\n");
+  }
+  lines.push("");
+  lines.push(`  auto-merged files (${autoMergedFiles.length}):`);
+  const { forkPath } = linkOptions;
+  const shown = autoMergedFiles.slice(0, maxFiles);
+  for (const filePath of shown) {
+    lines.push(`  - ${forkPath ? hyperlink(filePath, `vscode://file${resolve3(forkPath, filePath)}`) : filePath}`);
+  }
+  if (autoMergedFiles.length > shown.length) {
+    lines.push(`  ... + ${autoMergedFiles.length - shown.length} more`);
+  }
+  return lines.join("\n");
+}
+var statusConfig = {
+  behind: { icon: colors_default.cyan("\u2193"), label: "behind", color: colors_default.cyan, description: "upstream changed, will update" },
+  diverged: { icon: colors_default.magenta("\u21C5"), label: "diverged", color: colors_default.magenta, description: "both changed, will merge" },
+  drifted: { icon: colors_default.yellow("!"), label: "drifted", color: colors_default.yellow, description: "fork changed (at risk)" },
+  ahead: { icon: colors_default.blue("\u2191"), label: "ahead", color: colors_default.blue, description: "fork changed (protected)" },
+  local: { icon: colors_default.green("+"), label: "local", color: colors_default.green, description: "local file in cella folders" },
+  pinned: { icon: colors_default.green("\u2A00"), label: "pinned", color: colors_default.green, description: "both changed, fork wins" },
+  ignored: { icon: colors_default.gray("\u2A02"), label: "ignored", color: colors_default.gray },
+  identical: { icon: colors_default.gray("\u2713"), label: "identical", color: colors_default.gray, description: "no changes" },
+  deleted: { icon: colors_default.red("\u2717"), label: "deleted", color: colors_default.red },
+  renamed: { icon: colors_default.blue("\u2192"), label: "renamed", color: colors_default.blue }
+};
+var summaryStatusConfig = {
+  ...statusConfig,
+  managed: {
+    icon: colors_default.cyan("\u25C7"),
+    label: "managed",
+    color: colors_default.cyan,
+    description: "package.jsons & cella/cella.config.ts handled separately"
+  },
+  ignored: { ...statusConfig.ignored, description: "protected by ignored config" }
+};
+function printSummary(summary, title = "summary") {
+  printSectionHeader(colors_default.cyan(title));
+  const maxCount = Math.max(...Object.values(summary));
+  const countWidth = String(maxCount).length + 1;
+  const groups = [
+    ["managed", "ignored"],
+    ["identical"],
+    ["ahead", "local", "drifted"],
+    ["diverged", "pinned"],
+    ["behind"]
+  ];
+  for (const group of groups) {
+    if (group !== groups[0]) console.info();
+    for (const status of group) {
+      const { icon, label, color, description } = summaryStatusConfig[status];
+      const countStr = color(String(summary[status]).padStart(countWidth));
+      console.info(`  ${icon} ${countStr}  ${label.padEnd(15)}${description ? colors_default.dim(description) : ""}`);
+    }
+  }
+}
+function filesWithStatus(files, status) {
+  return files.filter((f) => f.status === status && !isManagedFile(f.path));
+}
+function findProtectedBehind(files) {
+  return files.filter((file) => file.upstreamChanged && !isManagedFile(file.path) && !isGeneratedFile(file.path));
+}
+function findProtectedBehindUpstream(result) {
+  const ignoredOnly = new Set((result.ignoredUpstreamChanges ?? []).flatMap((group) => group.paths));
+  return [...findProtectedBehind(result.files), ...result.files.filter((file) => ignoredOnly.has(file.path))];
+}
+var PROTECTED_BEHIND_HINT = "pinned/ignored files where upstream also changed since the last upgrade; the fork side wins on conflict, so review what upstream changed and adopt what you need.";
+function protectionIcon(file) {
+  return file.isIgnored ? statusConfig.ignored.icon : statusConfig.pinned.icon;
+}
+function formatUpstreamChangedLines(file) {
+  if (file.upstreamChangedLines === void 0) return "";
+  return colors_default.yellow(` \xB7 ${plural(file.upstreamChangedLines, "line")} changed upstream`);
+}
+function printSyncComplete(result, options = {}) {
+  const updated = result.files.filter((file) => file.status === "behind" || file.status === "diverged").length;
+  const diverged = result.files.filter((file) => file.status === "diverged").length;
+  const merged = result.autoMergedFiles?.length ?? Math.max(0, diverged - result.conflicts.length);
+  const conflicts = result.conflicts.length;
+  const counts = `${plural(updated, "file")} updated, ${merged} auto-merged, ${plural(conflicts, "conflict")}`;
+  console.info();
+  if (options.stagedBranch) {
+    console.info(`${checkMark} upgrade merge staged on '${options.stagedBranch}'`);
+    console.info(colors_default.dim(`  ${counts}. committing next...`));
+  } else if (conflicts > 0) {
+    console.info(`${warningMark} upgrade merge staged with conflicts`);
+    console.info(colors_default.dim(`  ${counts}`));
+  } else {
+    console.info(`${checkMark} upgrade merge complete`);
+    console.info(colors_default.dim(`  ${counts}`));
+  }
+  printProtectedConflicts(result);
+  console.info();
+}
+function printProtectedConflicts(result) {
+  const paths = result.protectedConflicts ?? [];
+  if (paths.length === 0) return;
+  const byPath2 = new Map(result.files.map((file) => [file.path, file]));
+  console.info();
+  console.info(
+    `${warningMark} ${colors_default.yellow(
+      `${plural(paths.length, "protected file kept", "protected files kept")} the fork version, dropping upstream changes:`
+    )}`
+  );
+  for (const path of paths) {
+    const file = byPath2.get(path);
+    const icon = file ? protectionIcon(file) : statusConfig.pinned.icon;
+    console.info(`  ${icon} ${path}${file ? formatUpstreamChangedLines(file) : ""}`);
+  }
+  console.info(colors_default.dim(`  ${PROTECTED_BEHIND_HINT}`));
+}
+function plural(count3, singular, pluralForm = `${singular}s`) {
+  return `${count3} ${count3 === 1 ? singular : pluralForm}`;
+}
+function printIgnoredUpstreamChanges(result) {
+  const groups = result.ignoredUpstreamChanges ?? [];
+  if (groups.length === 0) return;
+  const total = groups.reduce((count3, group) => count3 + group.paths.length, 0);
+  console.info();
+  console.info(
+    `${warningMark} ${colors_default.yellow(`ignored paths changed upstream \xB7 ${plural(total, "file")} under ${plural(groups.length, "entry", "entries")}`)}`
+  );
+  for (const group of groups) {
+    const counts = [plural(group.paths.length, "file")];
+    if (group.added > 0) counts.push(`${group.added} new`);
+    if (group.deleted > 0) counts.push(`${group.deleted} deleted`);
+    console.info(`  ${statusConfig.ignored.icon} ${group.entry} ${colors_default.dim(`\xB7 ${counts.join(", ")}`)}`);
+  }
+  console.info(
+    colors_default.dim("  the fork left these untouched and ignored paths never merge: review and adopt what you need.")
+  );
+}
+function printUpstreamOverrideChanges(result) {
+  const report = result.upstreamOverrides;
+  if (!report) return;
+  console.info();
+  if (report.kind === "unreadable") {
+    const side = report.side === "base" ? "the last upgrade" : "the incoming ref";
+    console.info(
+      colors_default.dim(`upstream CLI config not compared: upstream ${CONFIG_FILE} is missing or unreadable at ${side}`)
+    );
+    return;
+  }
+  const lines = [];
+  for (const list of ["pinned", "ignored", "packageJsonKeys"]) {
+    for (const entry of report[list].added) lines.push(`  ${colors_default.green("+")} ${list}: ${entry}`);
+    for (const entry of report[list].removed) {
+      lines.push(`  ${colors_default.red("\u2212")} ${list}: ${entry}${colors_default.dim(" \xB7 dropped upstream, still in your config")}`);
+    }
+  }
+  console.info(
+    `${warningMark} ${colors_default.yellow(`upstream changed its CLI config \xB7 ${plural(lines.length, "entry", "entries")} to review`)}`
+  );
+  for (const line of lines) console.info(line);
+  console.info(colors_default.dim(`  ${CONFIG_FILE} never merges: add or drop these by hand where they fit your app.`));
 }
-async function withTemporarySyncBaseGraft(cwd, headRef, baseSha, fn) {
-  const headSha = await revParse(cwd, headRef);
-  if (!headSha || !await commitObjectExists(cwd, baseSha)) return fn();
-  if (await isAncestor(cwd, baseSha, headSha)) return fn();
-  const existingReplacement = await git(["replace", "-l", headSha], cwd, { ignoreErrors: true });
-  if (existingReplacement) return fn();
-  const parentsRaw = await git(["log", "-1", "--format=%P", headSha], cwd, { ignoreErrors: true });
-  const parents = parentsRaw ? parentsRaw.split(/\s+/) : [];
-  await git(["replace", "-f", "--graft", headSha, ...parents, baseSha], cwd);
-  try {
-    return await fn();
-  } finally {
-    await git(["replace", "-d", headSha], cwd, { ignoreErrors: true });
+function findMaskingPins(files) {
+  return files.filter(
+    (file) => file.isPinned && !isManagedFile(file.path) && file.status === "behind" && file.existsInFork && file.existsInUpstream
+  );
+}
+function printMaskingPinWarning(files) {
+  const masking = findMaskingPins(files);
+  if (masking.length === 0) return;
+  console.info();
+  console.info(
+    `${warningMark} ${colors_default.yellow(
+      `${plural(masking.length, "pinned file matches", "pinned files match")} the previous upstream but changed upstream:`
+    )}`
+  );
+  console.info(colors_default.yellow("  the pin keeps the old fork copy and silently drops those upstream changes:"));
+  for (const file of masking) {
+    console.info(colors_default.dim(`  \u2A00 ${file.path}`));
   }
+  console.info(
+    colors_default.yellow("  if the fork never customized these, unpin them in cella/cella.config.ts to take upstream.")
+  );
+  console.info();
+}
+function printEngineReports(result, title) {
+  printSummary(result.summary, title);
+  printIgnoredUpstreamChanges(result);
+  printUpstreamOverrideChanges(result);
+  printMaskingPinWarning(result.files);
 }
 
-// src/utils/migration-notes.ts
+// src/utils/overrides.ts
+import { existsSync as existsSync5 } from "fs";
+import { join as join6 } from "path";
+
+// src/utils/alignments.ts
 import { existsSync as existsSync4 } from "fs";
 import { mkdir as mkdir3, readFile as readFile2, rm, writeFile as writeFile2 } from "fs/promises";
 import { dirname as dirname3, join as join5 } from "path";
-var NOTES_DIR = "cella/migrations";
-var PENDING_FILE = "cella/cella.migrations.json";
-var NOTE_ID = /^\d{8}T\d{4}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var ALIGNMENTS_DIR = "cella/alignments";
+var UPSTREAM_ONLY_DIRS = [ALIGNMENTS_DIR, "cella/migrations"];
+var PENDING_FILE = "cella/cella.alignments.json";
+var ALIGNMENT_ID = /^\d{8}T\d{4}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var CAUGHT_BY = ["compiler", "tests", "nothing"];
 function isCodemodFile(name) {
   return name.endsWith(".ts") && !name.endsWith(".test.ts");
 }
+function splitList(value) {
+  return (value ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+}
 function isUpstreamOnly(filePath) {
-  return filePath === NOTES_DIR || filePath.startsWith(`${NOTES_DIR}/`);
+  return UPSTREAM_ONLY_DIRS.some((dir) => filePath === dir || filePath.startsWith(`${dir}/`));
 }
 function bodyLines(lines) {
   let inComment = false;
@@ -1270,7 +1329,7 @@ function bodyLines(lines) {
     return false;
   });
 }
-function parseNote(id, source, fileNames) {
+function parseAlignment(id, source, fileNames) {
   const lines = source.replace(/\r\n/g, "\n").split("\n");
   const close = lines[0] === "---" ? lines.indexOf("---", 1) : -1;
   const meta = /* @__PURE__ */ new Map();
@@ -1282,31 +1341,75 @@ function parseNote(id, source, fileNames) {
   const blocks = body.split(/\n\s*\n/).map((block) => block.trim()).filter(Boolean);
   const title = /^# (.+)$/.exec(blocks[0] ?? "")?.[1].trim();
   const summary = title && blocks[1] && !/^(#|>|[-*|]|```)/.test(blocks[1]) ? blocks[1].replace(/\s*\n\s*/g, " ") : "";
+  const caughtBy = CAUGHT_BY.find((value) => value === meta.get("caughtBy")) ?? null;
   return {
     id,
     title: title || id,
     summary,
-    syncBreaking: meta.get("syncBreaking") === "true",
+    // `syncBreaking` is the field's name in alignments up to cella 0.27
+    breaking: (meta.get("breaking") ?? meta.get("syncBreaking")) === "true",
     clientCacheBump: meta.get("clientCacheBump") === "true",
-    roots: (meta.get("roots") ?? "").split(",").map((root) => root.trim()).filter(Boolean),
+    caughtBy,
+    generate: meta.get("generate") === "true",
+    grep: splitList(meta.get("grep")),
+    roots: splitList(meta.get("roots")),
     codemod: fileNames.find(isCodemodFile) ?? null
   };
 }
-async function listNoteIds(cwd, ref) {
-  const out = await git(["ls-tree", "--name-only", `${ref}:${NOTES_DIR}`], cwd, { ignoreErrors: true });
-  return out.split("\n").filter((name) => NOTE_ID.test(name)).sort();
+async function listAlignmentIds(cwd, ref) {
+  const out = await git(["ls-tree", "--name-only", `${ref}:${ALIGNMENTS_DIR}`], cwd, { ignoreErrors: true });
+  return out.split("\n").filter((name) => ALIGNMENT_ID.test(name)).sort();
 }
-async function readNote(cwd, ref, id) {
-  const source = await git(["show", `${ref}:${NOTES_DIR}/${id}/README.md`], cwd, { ignoreErrors: true });
+async function readAlignment(cwd, ref, id) {
+  const source = await git(["show", `${ref}:${ALIGNMENTS_DIR}/${id}/README.md`], cwd, { ignoreErrors: true });
   if (!source) return null;
-  const files = await git(["ls-tree", "--name-only", `${ref}:${NOTES_DIR}/${id}`], cwd, { ignoreErrors: true });
-  return parseNote(id, source, files.split("\n").filter(Boolean));
+  const files = await git(["ls-tree", "--name-only", `${ref}:${ALIGNMENTS_DIR}/${id}`], cwd, { ignoreErrors: true });
+  return parseAlignment(id, source, files.split("\n").filter(Boolean));
 }
-async function arrivedNoteIds(cwd, from, to) {
-  const [before, after] = await Promise.all([listNoteIds(cwd, from), listNoteIds(cwd, to)]);
+async function arrivedAlignmentIds(cwd, from, to) {
+  const [before, after] = await Promise.all([listAlignmentIds(cwd, from), listAlignmentIds(cwd, to)]);
   const known = new Set(before);
   return after.filter((id) => !known.has(id));
 }
+async function readAlignmentSource(cwd, ref, id) {
+  const out = await git(
+    ["log", "-1", "--diff-filter=A", "--format=%H%x09%s", ref, "--", `${ALIGNMENTS_DIR}/${id}/README.md`],
+    cwd,
+    { ignoreErrors: true }
+  );
+  if (!out) return null;
+  const [commit, subject = ""] = out.split("	");
+  const { pr = null } = splitPrNumber(subject);
+  const nulSeparated = (text) => text.split("\0").filter(Boolean);
+  const [changed, added] = await Promise.all([
+    git(["diff-tree", "--root", "--no-commit-id", "--name-only", "--no-renames", "-r", "-z", commit], cwd),
+    git(
+      [
+        "diff-tree",
+        "--root",
+        "--no-commit-id",
+        "--name-only",
+        "--diff-filter=A",
+        "-r",
+        "-z",
+        commit,
+        "--",
+        ALIGNMENTS_DIR
+      ],
+      cwd
+    )
+  ]);
+  const readmeId = new RegExp(`^${ALIGNMENTS_DIR}/([^/]+)/README\\.md$`);
+  const sharedCommit = nulSeparated(added).map((path) => readmeId.exec(path)?.[1]).filter((other) => !!other && other !== id && ALIGNMENT_ID.test(other)).sort();
+  return { commit, pr, sharedCommit, changedFiles: nulSeparated(changed) };
+}
+async function grepAlignmentTerms(cwd, terms, inFiles) {
+  if (terms.length === 0) return [];
+  const out = await git(["grep", "-n", "-I", "-w", "-F", "-z", ...terms.flatMap((term) => ["-e", term]), "--"], cwd, {
+    ignoreErrors: true
+  });
+  return out.split("\n").map((match) => match.split("\0")).filter(([file, line]) => file && line && inFiles(file)).map(([file, line]) => ({ file, line: Number(line) }));
+}
 async function readPending(cwd) {
   const path = join5(cwd, PENDING_FILE);
   if (!existsSync4(path)) return [];
@@ -1324,14 +1427,13 @@ async function writePending(cwd, ids) {
   await writeFile2(path, `${JSON.stringify({ pending }, null, 2)}
 `, "utf8");
 }
-function noteUrl(upstreamGitHubUrl, commit, id) {
-  return upstreamGitHubUrl ? `${upstreamGitHubUrl}/blob/${commit}/${NOTES_DIR}/${id}/README.md` : void 0;
+function alignmentUrl(upstreamGitHubUrl, commit, id) {
+  return upstreamGitHubUrl ? `${upstreamGitHubUrl}/blob/${commit}/${ALIGNMENTS_DIR}/${id}/README.md` : void 0;
 }
-function formatNotesLine(total, open, arrived, options = {}) {
+function formatAlignmentsLine(total, open) {
   const parts = [open === 0 ? `all ${total} handled` : `${Math.max(0, total - open)} of ${total} handled`];
-  if (arrived) parts.push(`${arrived} ${options.dryRun ? "arrive" : "arrived"} with this sync`);
-  if (open > 0) parts.push(`${open} open: pnpm cella migrate`);
-  return `migration notes: ${parts.join(" \xB7 ")}`;
+  if (open > 0) parts.push(`${open} open: pnpm cella align`);
+  return `alignments: ${parts.join(" \xB7 ")}`;
 }
 
 // src/utils/overrides.ts
@@ -1450,11 +1552,12 @@ var forkOption = ["--fork <name>", "pre-select a fork by name (skips the fork se
 var serviceDefinitions = [
   {
     name: "analyze",
-    description: "dry run to see what would change on sync",
+    description: "dry run to see what would change on upgrade",
     options: [
       ["--list", "non-interactive output for tooling (one file per line)"],
       jsonOption,
       ["--scope <scope>", "analyze scope for --list/--json: all|risk|protected"],
+      ["--all", "list every file instead of collapsing large groups"],
       trackOption,
       refOption,
       unpinnedOption
@@ -1462,30 +1565,31 @@ var serviceDefinitions = [
     includeInMenu: (context) => !context.isUpstreamRepo
   },
   {
-    name: "sync",
-    description: "merge upstream changes onto a fresh branch, sync package.json and open a squash-merge PR",
+    name: "upgrade",
+    description: "merge upstream changes onto a fresh branch, merge package.json and open a squash-merge PR",
+    aliases: ["sync"],
     options: [
       trackOption,
       refOption,
-      ["--keep-config", "merge with your sync config as it stands when upstream changed its own"],
+      ["--keep-config", "merge with your CLI config as it stands when upstream changed its own"],
       unpinnedOption
     ],
     includeInMenu: (context) => !context.isUpstreamRepo
   },
   {
-    name: "migrate",
-    description: "list the upstream migration notes this app has not handled yet",
+    name: "align",
+    description: "list the upstream alignments this app has not handled yet",
     options: [
-      ["--all", "list every upstream note, handled or not"],
+      ["--all", "list every upstream alignment, handled or not"],
       jsonOption,
-      ["--show <id>", "print one note's README"],
-      ["--extract <id>", "write one note's folder under node_modules/.cache to run its codemod"],
-      ["--run <id>", "run one note's codemod; files identical to upstream stay as they are"],
-      ["--mark <ids...>", "record notes as handled"]
+      ["--show <id>", "print one alignment's README and what git tells about it"],
+      ["--extract <id>", "write one alignment's folder under node_modules/.cache to run its codemod"],
+      ["--run <id>", "run one alignment's codemod; files identical to upstream stay as they are"],
+      ["--mark <ids...>", "record alignments as handled"]
     ],
     operands: [
       "[codemodArgs...]",
-      "with --run, after `--`: arguments for the codemod (default: inventory and the note's roots)"
+      "with --run, after `--`: arguments for the codemod (default: inventory and the alignment's roots)"
     ],
     includeInMenu: (context) => !context.isUpstreamRepo
   },
@@ -1496,10 +1600,10 @@ var serviceDefinitions = [
   },
   {
     name: "forks",
-    description: "run normal sync inside local fork repositories",
+    description: "run the upgrade inside local fork repositories",
     options: [
       forkOption,
-      ["--keep-config", "merge with the fork's sync config as it stands when upstream changed its own"]
+      ["--keep-config", "merge with the fork's CLI config as it stands when upstream changed its own"]
     ],
     includeInMenu: (context) => context.hasForks
   },
@@ -1538,17 +1642,21 @@ function buildServiceChoices(context) {
   ];
 }
 function addServiceCommand(program, definition, setSelection) {
-  const command = program.command(definition.name).description(definition.description);
-  for (const option of definition.options ?? []) command.option(...option);
-  if (definition.operands) command.argument(...definition.operands);
-  command.action((...args) => {
-    const operands = definition.operands ? args[0] : [];
-    const opts = definition.operands ? args[1] : args[0];
-    setSelection({
-      service: definition.name,
-      options: readOptions(opts, operands)
+  for (const name of [definition.name, ...definition.aliases ?? []]) {
+    const renamedFrom = name === definition.name ? void 0 : name;
+    const command = program.command(name, { hidden: !!renamedFrom }).description(definition.description);
+    for (const option of definition.options ?? []) command.option(...option);
+    if (definition.operands) command.argument(...definition.operands);
+    command.action((...args) => {
+      const operands = definition.operands ? args[0] : [];
+      const opts = definition.operands ? args[1] : args[0];
+      setSelection({
+        service: definition.name,
+        renamedFrom,
+        options: readOptions(opts, operands)
+      });
     });
-  });
+  }
 }
 function buildProgram(setSelection) {
   const program = new Command("cella").version(VERSION, "-v, --version", "output the current version").usage("[service] [options]").helpOption("-h, --help", "display help for a command").showHelpAfterError().addHelpText(
@@ -1558,10 +1666,10 @@ function buildProgram(setSelection) {
       "Examples:",
       "  $ cella analyze",
       "  $ cella analyze --json --scope risk",
-      "  $ cella sync --track branch",
-      "  $ cella sync --ref 4f7d87c",
-      "  $ cella migrate --run 20261001T2116-tailwind-class-conventions -- rewrite frontend/src",
-      "  $ cella migrate --mark 20261002T0614-config-switch",
+      "  $ cella upgrade --track branch",
+      "  $ cella upgrade --ref 4f7d87c",
+      "  $ cella align --run 20261001T2116-tailwind-class-conventions -- rewrite frontend/src",
+      "  $ cella align --mark 20261002T0614-config-switch",
       "  $ cella audit --list",
       "  $ cella stats --since origin/main --md",
       "  $ cella contributions --fork raak --json"
@@ -1592,7 +1700,7 @@ async function promptForService(userConfig, forkPath) {
   if (selected === "exit") {
     console.info(colors_default.dim("exiting..."));
     console.info();
-    process5.exit(0);
+    process6.exit(0);
   }
   console.info();
   return selected;
@@ -1601,12 +1709,18 @@ function buildRuntimeConfig(userConfig, forkPath, selection, upstreamRef) {
   return { ...userConfig, forkPath, upstreamRef, service: selection.service ?? "analyze", ...selection.options };
 }
 async function parseCli(userConfig, forkPath) {
-  const selection = parseCommandLine(process5.argv);
+  const selection = parseCommandLine(process6.argv);
   const machineList = selection.options.list && selection.service !== "audit";
   if (selection.options.json || selection.options.md || machineList) setJsonMode(true);
   printHeader();
   const { branchRef } = resolveUpstream(userConfig.settings);
-  const warnings = await validateOverrides(userConfig, forkPath, branchRef);
+  const warnings = [
+    ...renamedSettingWarnings(userConfig),
+    ...await validateOverrides(userConfig, forkPath, branchRef)
+  ];
+  if (selection.renamedFrom) {
+    warnings.unshift(`\`cella ${selection.renamedFrom}\` is renamed to \`cella ${selection.service}\``);
+  }
   for (const warning of warnings) console.info(`${warningMark} ${warning}`);
   if (warnings.length > 0) console.info();
   if (!selection.service) {
@@ -1615,6 +1729,12 @@ async function parseCli(userConfig, forkPath) {
   return buildRuntimeConfig(userConfig, forkPath, selection, branchRef);
 }
 
+// src/services/align.ts
+import { execFileSync, spawnSync } from "child_process";
+import { mkdir as mkdir4, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname4, join as join8 } from "path";
+import process7 from "process";
+
 // src/services/merge-engine.ts
 import { existsSync as existsSync6 } from "fs";
 import { rm as rm2 } from "fs/promises";
@@ -1689,7 +1809,7 @@ function cliVersionMismatch(running, range) {
   const current = parseComparableVersion(running);
   if (!required || !current || compareVersions(current, required) >= 0) return null;
   return [
-    `upstream needs ${CLI_PACKAGE} ${range}, this is ${running}: an older CLI misses fixes to the sync itself.`,
+    `upstream needs ${CLI_PACKAGE} ${range}, this is ${running}: an older CLI misses fixes to the upgrade itself.`,
     `  update it, commit, then rerun: pnpm add -D -w '${CLI_PACKAGE}@${range}'`
   ].join("\n");
 }
@@ -1743,12 +1863,13 @@ function readStringEntries(node) {
   }
   return entries;
 }
-function readPackageJsonSync(config, sourceFile) {
+function readPackageJsonKeys(config, sourceFile) {
   const settings = readProperty(config, "settings", sourceFile);
-  if (settings === void 0) return [...DEFAULT_PACKAGE_JSON_SYNC];
+  if (settings === void 0) return [...DEFAULT_PACKAGE_JSON_KEYS];
   if (!settings || !Node.isObjectLiteralExpression(settings)) return null;
-  const keys = readProperty(settings, "packageJsonSync", sourceFile);
-  if (keys === void 0) return [...DEFAULT_PACKAGE_JSON_SYNC];
+  const current = readProperty(settings, "packageJsonKeys", sourceFile);
+  const keys = current === void 0 ? readProperty(settings, "packageJsonSync", sourceFile) : current;
+  if (keys === void 0) return [...DEFAULT_PACKAGE_JSON_KEYS];
   return keys ? readStringEntries(keys) : null;
 }
 function parseOverrideLists(source) {
@@ -1760,7 +1881,7 @@ function parseOverrideLists(source) {
     const lists = {
       pinned: [],
       ignored: [],
-      packageJsonSync: readPackageJsonSync(config, sourceFile)
+      packageJsonKeys: readPackageJsonKeys(config, sourceFile)
     };
     const overrides = readProperty(config, "overrides", sourceFile);
     if (overrides === void 0) return lists;
@@ -1788,14 +1909,14 @@ function diffOverrideLists(base, incoming, fork) {
     };
   };
   const diffKeys = () => {
-    const [baseKeys, incomingKeys, forkKeys] = [base.packageJsonSync, incoming.packageJsonSync, fork.packageJsonSync];
+    const [baseKeys, incomingKeys, forkKeys] = [base.packageJsonKeys, incoming.packageJsonKeys, fork.packageJsonKeys];
     if (!baseKeys || !incomingKeys || !forkKeys) return { added: [], removed: [] };
     return {
       added: [...new Set(incomingKeys)].filter((key) => !baseKeys.includes(key) && !forkKeys.includes(key)),
       removed: [...new Set(baseKeys)].filter((key) => !incomingKeys.includes(key) && forkKeys.includes(key))
     };
   };
-  return { pinned: diff("pinned"), ignored: diff("ignored"), packageJsonSync: diffKeys() };
+  return { pinned: diff("pinned"), ignored: diff("ignored"), packageJsonKeys: diffKeys() };
 }
 async function compareUpstreamOverrides(repoPath, mergeBaseRef, incomingRef, forkConfig) {
   const [baseSource, incomingSource] = await Promise.all(
@@ -1809,7 +1930,7 @@ async function compareUpstreamOverrides(repoPath, mergeBaseRef, incomingRef, for
   const fork = {
     pinned: forkConfig.overrides?.pinned ?? [],
     ignored: forkConfig.overrides?.ignored ?? [],
-    packageJsonSync: forkConfig.settings.packageJsonSync ?? DEFAULT_PACKAGE_JSON_SYNC
+    packageJsonKeys: forkConfig.settings.packageJsonKeys ?? DEFAULT_PACKAGE_JSON_KEYS
   };
   const changes = diffOverrideLists(base, incoming, fork);
   const count3 = Object.values(changes).reduce((n, list) => n + list.added.length + list.removed.length, 0);
@@ -1936,7 +2057,9 @@ async function analyzeRefs(repoPath, localRef, incomingRef, mergeBaseRef, predic
     const upstreamOnly = fileIsIgnored && isReportableIgnored(filePath) && upstreamHash !== baseHash && forkHash === baseHash;
     push(status, { upstreamChanged: upstreamChanged || void 0, upstreamOnly: upstreamOnly || void 0 });
   }
-  const flagged = analyzedFiles.filter((file) => file.upstreamChanged && !renamedProtected.has(file.path));
+  const flagged = analyzedFiles.filter(
+    (file) => file.upstreamChanged && !renamedProtected.has(file.path) || file.upstreamOnly
+  );
   if (flagged.length > 0) {
     const stat = await getDiffStat(
       repoPath,
@@ -1983,7 +2106,7 @@ async function enrichChangeInfo(repoPath, files, mergeBaseRef, localRef, incomin
       setChanged(file, forkInfo.get(file.path));
     } else if (file.status === "behind") {
       setChanged(file, upstreamInfo.get(file.path));
-    } else if (file.status === "diverged" || file.status === "pinned" || file.upstreamChanged) {
+    } else if (file.status === "diverged" || file.status === "pinned" || file.upstreamChanged || file.upstreamOnly) {
       setChanged(file, forkInfo.get(file.path));
       const info = upstreamInfo.get(file.path);
       if (info) {
@@ -2003,7 +2126,7 @@ var UpstreamConfigChangedError = class extends Error {
   constructor(report) {
     super(
       [
-        "upstream changed its sync config and yours does not follow it: stopped before the merge, nothing changed.",
+        "upstream changed its CLI config and yours does not follow it: stopped before the merge, nothing changed.",
         `  add or drop the entries that fit your app in ${CONFIG_FILE}, commit, then rerun.`,
         "  to merge with your config as it stands, rerun with --keep-config."
       ].join("\n")
@@ -2015,6 +2138,10 @@ function getGitHubBaseUrl(remoteUrl) {
   const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
   return match ? `https://github.com/${match[1]}/${match[2]}` : null;
 }
+async function readOriginGitHubUrl(forkPath) {
+  const origin = await git(["remote", "get-url", "origin"], forkPath, { ignoreErrors: true });
+  return getGitHubBaseUrl(origin.trim()) ?? void 0;
+}
 function isProtectedFile(file) {
   return file.isIgnored || file.isPinned;
 }
@@ -2150,11 +2277,6 @@ function calculateSummary(files) {
   }
   return summary;
 }
-function formatLocalCheckoutDetail(forkPath, branch, headSha, changeCount, upstream) {
-  const tracking = upstream.upstream ? `, tracking ${upstream.upstream} (${upstream.ahead} ahead, ${upstream.behind} behind)` : ", no tracking branch";
-  const workingTree = changeCount === 0 ? "  working tree clean" : `  ${changeCount} uncommitted change${changeCount === 1 ? "" : "s"} in working tree, not included in analysis`;
-  return [`${forkPath}`, `  ${branch} @ ${headSha}${tracking}`, workingTree].join("\n");
-}
 async function resolvePinnedRef(forkPath, config, remoteName, branchRef, ref) {
   const resolved = await resolveUpstreamCommit(forkPath, remoteName, ref);
   if (!resolved) {
@@ -2164,7 +2286,7 @@ async function resolvePinnedRef(forkPath, config, remoteName, branchRef, ref) {
   }
   if (!await isPublishedUpstream(forkPath, remoteName, branchRef, resolved.sha)) {
     throw new Error(
-      `--ref '${ref}' (${resolved.sha.slice(0, 7)}) is not on ${branchRef} or in an upstream release. Sync only to commits upstream has published there.`
+      `--ref '${ref}' (${resolved.sha.slice(0, 7)}) is not on ${branchRef} or in an upstream release. Upgrade only to commits upstream has published there.`
     );
   }
   return resolved.release ? { ref: resolved.release.ref, releaseTag: resolved.release.tag } : { ref: resolved.sha };
@@ -2178,7 +2300,7 @@ async function prepareUpstream(config, onProgress, onStep) {
     getWorkingTreeChangeCount(forkPath),
     getUpstreamStatus(forkPath)
   ]);
-  onStep?.("local checkout", formatLocalCheckoutDetail(forkPath, branch, headSha, changeCount, upstreamStatus));
+  onStep?.("checkout", formatCheckoutStep({ forkPath, branch, headSha, changeCount, upstream: upstreamStatus }));
   onProgress?.("setting up upstream remote...");
   const { track: configTrack, branchRef } = resolveUpstream(config.settings);
   const remoteName = DEFAULT_UPSTREAM_REMOTE;
@@ -2206,7 +2328,6 @@ async function prepareUpstream(config, onProgress, onStep) {
   }
   const upstreamLabel = releaseTag ?? (config.ref ? `--ref ${config.ref}` : upstreamRef);
   config.upstreamRef = upstreamRef;
-  onStep?.("remote configured", `${upstreamLabel} \u2192 ${config.settings.upstreamUrl}`);
   const cliRange = await readUpstreamCliRange(forkPath, upstreamRef);
   const cliMismatch = cliRange ? cliVersionMismatch(VERSION, cliRange) : null;
   if (cliMismatch) throw new Error(cliMismatch);
@@ -2217,20 +2338,35 @@ async function prepareUpstream(config, onProgress, onStep) {
   const mergeRef = config.unpinned ? await getMergeBase(forkPath, "HEAD", upstreamRef) : mergeBase;
   const upstreamCommit = await getCommitInfo(forkPath, upstreamRef);
   if (upstreamCommit.hash !== mergeBase && await isAncestor(forkPath, upstreamCommit.hash, mergeBase)) {
-    const [upstreamShort, syncShort] = await Promise.all([
+    const [upstreamShort2, syncShort] = await Promise.all([
       getShortSha(forkPath, upstreamCommit.hash),
       getShortSha(forkPath, mergeBase)
     ]);
-    const hint = config.ref ? "Pick a newer --ref." : releaseTag ? `Nothing to sync until a release past ${syncShort}; to follow the tip instead, run with --track branch.` : `Nothing to sync until '${branchRef}' moves past ${syncShort}.`;
+    const hint2 = config.ref ? "Pick a newer --ref." : releaseTag ? `Nothing to upgrade until a release past ${syncShort}; to follow the tip instead, run with --track branch.` : `Nothing to upgrade until '${branchRef}' moves past ${syncShort}.`;
     throw new BehindSyncPointError(
-      `upstream ${upstreamLabel} (${upstreamShort}) is behind the last sync point ${syncShort}: the fork already has it, and syncing it would revert the upstream changes after it.
-${hint}`
+      `upstream ${upstreamLabel} (${upstreamShort2}) is behind the last upgrade at ${syncShort}: the fork already has it, and merging it would revert the upstream changes after it.
+${hint2}`
     );
   }
   const commitCount = await countCommitsBetween(forkPath, mergeBase, upstreamRef);
-  const upstreamCommits = commitCount > 0 ? await listCommitsBetween(forkPath, mergeBase, upstreamRef, COMMIT_LIST_MAX) : [];
-  onStep?.("fetched upstream", formatFetchedUpstreamDetail(commitCount, upstreamCommits, upstreamGitHubUrl));
-  return { upstreamRef, releaseTag, mergeBase, mergeRef, upstreamGitHubUrl, upstreamCommit };
+  const upstreamCommits = commitCount > 0 ? await listCommitsBetween(forkPath, mergeBase, upstreamRef, COMMIT_STEP_MAX) : [];
+  const [upstreamShort, baseShort] = await Promise.all([
+    getShortSha(forkPath, upstreamCommit.hash),
+    getShortSha(forkPath, mergeBase)
+  ]);
+  onStep?.(
+    "upstream",
+    formatUpstreamStep({
+      label: releaseTag ?? branchRef.replace(`${remoteName}/`, ""),
+      sha: upstreamShort,
+      baseSha: baseShort,
+      pinned: !!config.ref,
+      commitCount,
+      commits: upstreamCommits,
+      githubUrl: upstreamGitHubUrl
+    })
+  );
+  return { upstreamRef, releaseTag, mergeBase, mergeRef, upstreamGitHubUrl, upstreamCommit, commitCount };
 }
 async function assertSyncConfigFollowed(config, ctx) {
   if (config.keepConfig) return;
@@ -2245,7 +2381,8 @@ function resultMeta(config, ctx) {
     upstreamRef: ctx.upstreamRef,
     upstreamTag: ctx.releaseTag,
     upstreamGitHubUrl: ctx.upstreamGitHubUrl,
-    upstreamCommit: ctx.upstreamCommit
+    upstreamCommit: ctx.upstreamCommit,
+    upstreamCommitCount: ctx.commitCount
   };
 }
 async function upstreamOnlyReports(config, ctx, files) {
@@ -2266,33 +2403,40 @@ async function upstreamOnlyReports(config, ctx, files) {
     return {};
   }
 }
-async function readNotesInRange(config, ctx) {
+function pendingAfterSync(alignments) {
+  return [.../* @__PURE__ */ new Set([...alignments.pending, ...alignments.arrived])];
+}
+async function readAlignmentsInRange(config, ctx) {
   const { forkPath } = config;
   try {
     const [total, arrived, pending] = await Promise.all([
-      listNoteIds(forkPath, ctx.upstreamRef),
-      arrivedNoteIds(forkPath, ctx.mergeBase, ctx.upstreamRef),
+      listAlignmentIds(forkPath, ctx.upstreamRef),
+      arrivedAlignmentIds(forkPath, ctx.mergeBase, ctx.upstreamRef),
       readPending(forkPath)
     ]);
-    return { total: total.length, arrived, pending: [.../* @__PURE__ */ new Set([...pending, ...arrived])] };
+    return { total: total.length, arrived, pending };
   } catch {
     return void 0;
   }
 }
-function notesResult(notes) {
-  return notes ? { migrationNotes: { total: notes.total, arrived: notes.arrived, open: notes.pending.length } } : {};
+function alignmentsResult(alignments, options) {
+  if (!alignments) return {};
+  const open = options.dryRun ? alignments.pending : pendingAfterSync(alignments);
+  return { alignments: { total: alignments.total, arrived: alignments.arrived, open } };
 }
 async function removeUpstreamOnlyCopy(forkPath, onStep) {
-  if (!existsSync6(join7(forkPath, NOTES_DIR))) return;
-  await git(["rm", "-r", "-q", "--ignore-unmatch", "--", NOTES_DIR], forkPath);
-  await rm2(join7(forkPath, NOTES_DIR), { recursive: true, force: true });
-  onStep?.("migration notes", `removed ${NOTES_DIR}/: notes stay upstream, list them with pnpm cella migrate`);
+  for (const dir of UPSTREAM_ONLY_DIRS) {
+    if (!existsSync6(join7(forkPath, dir))) continue;
+    await git(["rm", "-r", "-q", "--ignore-unmatch", "--", dir], forkPath);
+    await rm2(join7(forkPath, dir), { recursive: true, force: true });
+    onStep?.("alignments", `removed ${dir}/: alignments stay upstream, list them with pnpm cella align`);
+  }
 }
 async function runSyncMerge(config, ctx, onProgress, onStep) {
   const { forkPath } = config;
   const { upstreamRef, releaseTag, mergeRef, upstreamGitHubUrl, upstreamCommit } = ctx;
   await assertSyncConfigFollowed(config, ctx);
-  const notes = await readNotesInRange(config, ctx);
+  const alignments = await readAlignmentsInRange(config, ctx);
   const { remainingConflicts, analyzedFiles, autoMergedFiles, protectedConflicts } = await applyDirectMerge(
     forkPath,
     upstreamRef,
@@ -2310,32 +2454,29 @@ async function runSyncMerge(config, ctx, onProgress, onStep) {
       commit: upstreamCommit.hash,
       release: releaseTag ?? null,
       url: upstreamGitHubUrl ? releaseTag ? `${upstreamGitHubUrl}/releases/tag/${releaseTag}` : `${upstreamGitHubUrl}/commit/${upstreamCommit.hash}` : void 0,
-      syncedAt: (/* @__PURE__ */ new Date()).toISOString()
+      upgradedAt: (/* @__PURE__ */ new Date()).toISOString()
     }
   };
   const recordSyncPoint = async () => {
     await storeLastSyncRef(forkPath, upstreamCommit.hash);
     await writeSyncManifest(forkPath, syncManifest);
     await stagePath(forkPath, MANIFEST_FILE);
-    if (notes) {
-      await writePending(forkPath, notes.pending);
+    if (alignments) {
+      await writePending(forkPath, pendingAfterSync(alignments));
       await stagePath(forkPath, PENDING_FILE);
     }
     await removeUpstreamOnlyCopy(forkPath, onStep);
   };
   if (remainingConflicts.length > 0) {
     await recordSyncPoint();
-    onStep?.(
-      "merge in progress",
-      formatMergeInProgressDetail(remainingConflicts.length, autoMergedFiles, { forkPath }, 100)
-    );
+    onStep?.("merged", formatMergeInProgressDetail(remainingConflicts.length, autoMergedFiles, { forkPath }, 100));
   } else if (totalResolved > 0) {
     const label = synced > 0 ? `${synced} files from upstream` : "upstream changes";
     await recordSyncPoint();
-    onStep?.("synced", `${label} (staged, commit to finish)`);
+    onStep?.("upgraded", `${label} (staged, commit to finish)`);
   } else {
     await mergeAbort(forkPath);
-    onStep?.("up to date", "no upstream changes to sync");
+    onStep?.("up to date", "no upstream changes to merge");
   }
   return {
     success: remainingConflicts.length === 0,
@@ -2346,12 +2487,12 @@ async function runSyncMerge(config, ctx, onProgress, onStep) {
     protectedConflicts,
     ...resultMeta(config, ctx),
     ...await upstreamOnlyReports(config, ctx, analyzedFiles),
-    ...notesResult(notes)
+    ...alignmentsResult(alignments, { dryRun: false })
   };
 }
 async function runAnalyzePreview(config, ctx, onProgress, onStep) {
   const { forkPath } = config;
-  const notes = await readNotesInRange(config, ctx);
+  const alignments = await readAlignmentsInRange(config, ctx);
   onProgress?.("analyzing files...");
   const analyzedFiles = await analyzeRefs(
     forkPath,
@@ -2364,7 +2505,7 @@ async function runAnalyzePreview(config, ctx, onProgress, onStep) {
   await enrichChangeInfo(forkPath, analyzedFiles, ctx.mergeBase, "HEAD", ctx.upstreamRef);
   const protectedConflicts = analyzedFiles.filter((f) => f.upstreamChanged).map((f) => f.path);
   const reports = await upstreamOnlyReports(config, ctx, analyzedFiles);
-  onStep?.("analysis complete", `${analyzedFiles.length} files analyzed, dry run, no changes applied`);
+  onStep?.("analyzed", `${plural(analyzedFiles.length, "file")}${colors_default.dim(" \xB7 dry run, nothing changed")}`);
   return {
     success: true,
     files: analyzedFiles,
@@ -2374,25 +2515,23 @@ async function runAnalyzePreview(config, ctx, onProgress, onStep) {
     protectedConflicts,
     ...resultMeta(config, ctx),
     ...reports,
-    ...notesResult(notes)
+    ...alignmentsResult(alignments, { dryRun: true })
   };
 }
 async function runEngineWithSpinner(config, apply) {
   const onProgress = (message) => spinnerText(message);
   const onStep = (label, detail) => {
-    spinnerSuccess(label, detail);
+    printStep(label, detail);
     createSpinner("...");
   };
   const ctx = await prepareUpstream(config, onProgress, onStep);
   return apply ? runSyncMerge(config, ctx, onProgress, onStep) : runAnalyzePreview(config, ctx, onProgress, onStep);
 }
 
-// src/services/migrate.ts
-import { execFileSync, spawnSync } from "child_process";
-import { mkdir as mkdir4, writeFile as writeFile3 } from "fs/promises";
-import { dirname as dirname4, join as join8 } from "path";
-var EXTRACT_DIR = "node_modules/.cache/cella/migrations";
+// src/services/align.ts
+var EXTRACT_DIR = "node_modules/.cache/cella/alignments";
 var RESTORED_LIST_MAX = 20;
+var SHOW_LIST_MAX = 30;
 async function ensureUpstreamCommit(config, sha) {
   const { forkPath } = config;
   const present = async () => !!await revParse(forkPath, `${sha}^{commit}`);
@@ -2402,60 +2541,158 @@ async function ensureUpstreamCommit(config, sha) {
   if (!await present())
     throw new Error(`upstream commit ${sha.slice(0, 7)} is not reachable from '${DEFAULT_UPSTREAM_REMOTE}'`);
 }
-async function resolveNotesRef(config) {
+async function resolveAlignmentsRef(config) {
   const { forkPath } = config;
   const ref = await getStoredSyncRef(forkPath) ?? await readManifestBaseAtRef(forkPath, "HEAD");
   if (!ref) return null;
   await ensureUpstreamCommit(config, ref);
   return ref;
 }
-async function readNotesStatus(config) {
+async function readOpenAlignments(config) {
   try {
-    const ref = await resolveNotesRef(config);
+    const ref = await resolveAlignmentsRef(config);
     if (!ref) return null;
-    const [ids, pending] = await Promise.all([listNoteIds(config.forkPath, ref), readPending(config.forkPath)]);
-    return ids.length > 0 || pending.length > 0 ? { total: ids.length, open: pending.length } : null;
+    return { ref, open: await readPending(config.forkPath) };
   } catch {
     return null;
   }
 }
-async function printMigrationNotesLine(config, result) {
-  const notes = result?.migrationNotes;
-  if (notes) {
-    if (notes.total === 0) return;
-    console.info();
-    console.info(
-      colors_default.dim(formatNotesLine(notes.total, notes.open, notes.arrived.length, { dryRun: config.service === "analyze" }))
-    );
-    return;
-  }
-  const status = await readNotesStatus(config);
-  if (!status) return;
-  console.info();
-  console.info(colors_default.dim(formatNotesLine(status.total, status.open)));
+var STEP_ROWS_MAX = 5;
+function alignmentTags(alignment) {
+  return [
+    alignment.codemod ? "codemod" : "manual",
+    alignment.breaking ? "breaking" : "not breaking",
+    alignment.caughtBy ? `caught by ${alignment.caughtBy}` : null
+  ].filter(Boolean).join(" \xB7 ");
+}
+async function alignmentsStep(config, view) {
+  const arriving = view.arriving ?? [];
+  const open = view.open.filter((id) => !arriving.includes(id));
+  const arrived = (view.arrived ?? []).filter((id) => open.includes(id));
+  if (arriving.length === 0 && open.length === 0) return void 0;
+  const line = arriving.length > 0 ? `${plural(arriving.length, "alignment")} ${arriving.length === 1 ? "arrives" : "arrive"} with this upgrade${open.length > 0 ? colors_default.dim(` \xB7 ${open.length} open`) : ""}` : `${plural(open.length, "alignment")} open${arrived.length > 0 ? colors_default.dim(` \xB7 ${arrived.length} arrived with this upgrade`) : ""}`;
+  const githubUrl = getGitHubBaseUrl(config.settings.upstreamUrl) ?? void 0;
+  const ids = [...arriving, ...open];
+  const details = [];
+  for (const id of ids.slice(0, STEP_ROWS_MAX)) {
+    const alignment = await readAlignment(config.forkPath, view.ref, id).catch(() => null);
+    const title = hyperlink(alignment?.title ?? id, alignmentUrl(githubUrl, view.ref, id));
+    details.push(`${colors_default.cyan("\u25CB")} ${title}${alignment ? colors_default.dim(` \xB7 ${alignmentTags(alignment)}`) : ""}`);
+    if (!process7.stdout.isTTY) details.push(colors_default.dim(`  id ${id}`));
+  }
+  if (ids.length > STEP_ROWS_MAX) details.push(colors_default.dim(`+ ${ids.length - STEP_ROWS_MAX} more`));
+  details.push(`${arriving.length > 0 ? colors_default.dim("after the upgrade: ") : ""}pnpm cella align`);
+  return { label: "align", line, details };
+}
+async function readForkView(config, ref) {
+  const { pinned = [], ignored = [] } = config.overrides ?? {};
+  const counts = (path) => !isManagedFile(path) && !isGeneratedFile(path) && !isUpstreamOnly(path);
+  const out = await git(["diff", "--name-only", "--no-renames", "-z", ref, "--"], config.forkPath);
+  return {
+    githubUrl: getGitHubBaseUrl(config.settings.upstreamUrl) ?? void 0,
+    owns: (path) => counts(path) && isUnderAnyFolder(path, [...pinned, ...ignored]),
+    changed: new Set(out.split("\0").filter((path) => path && counts(path)))
+  };
+}
+async function describeAlignment(config, view, ref, alignment, open) {
+  const { forkPath } = config;
+  const [source, grepHits] = await Promise.all([
+    readAlignmentSource(forkPath, ref, alignment.id),
+    grepAlignmentTerms(forkPath, alignment.grep, (path) => view.changed.has(path))
+  ]);
+  const pr = source?.pr ?? null;
+  return {
+    ...alignment,
+    kind: alignment.codemod ? "codemod" : "manual",
+    open,
+    url: alignmentUrl(view.githubUrl, ref, alignment.id) ?? null,
+    commit: source?.commit ?? null,
+    pr,
+    prUrl: pr !== null && view.githubUrl ? `${view.githubUrl}/pull/${pr}` : null,
+    sharedCommit: source?.sharedCommit ?? [],
+    yourFiles: (source?.changedFiles ?? []).filter((path) => view.owns(path) || view.changed.has(path)),
+    grepHits
+  };
+}
+function grepSummary(alignment) {
+  if (alignment.grep.length === 0) return null;
+  const hits = alignment.grepHits.length;
+  if (hits === 0) return "grep: no app hits";
+  const files = new Set(alignment.grepHits.map((hit) => hit.file)).size;
+  return `grep: ${hits} hit${hits === 1 ? "" : "s"} in ${files} app file${files === 1 ? "" : "s"}`;
 }
-function printNote(index, note, url) {
+function printAlignment(index, alignment) {
   const tags = [
-    note.codemod ? "codemod" : "manual",
-    note.syncBreaking ? "sync-breaking" : null,
-    note.clientCacheBump ? "cache-bump" : null
+    alignment.codemod ? "codemod" : "manual",
+    alignment.breaking ? "breaking" : null,
+    alignment.clientCacheBump ? "cache-bump" : null,
+    alignment.caughtBy ? `caught by: ${alignment.caughtBy}` : null,
+    alignment.generate ? "generate" : null
   ].filter(Boolean).join(", ");
-  console.info(`${index}. ${note.title}  ${colors_default.dim(`[${tags}]`)}`);
-  console.info(colors_default.dim(`   id:      ${note.id}`));
-  if (note.summary) console.info(`   ${note.summary}`);
-  console.info(colors_default.dim(`   read:    pnpm cella migrate --show ${note.id}`));
-  if (url) console.info(colors_default.dim(`            ${url}`));
-  if (note.codemod) console.info(colors_default.dim(`   codemod: pnpm cella migrate --run ${note.id}`));
+  const grep = grepSummary(alignment);
+  console.info(`${index}. ${alignment.title}  ${colors_default.dim(`[${tags}]`)}`);
+  console.info(colors_default.dim(`   id:      ${alignment.id}`));
+  if (alignment.summary) console.info(`   ${alignment.summary}`);
+  if (alignment.pr !== null) {
+    console.info(colors_default.dim(`   added in #${alignment.pr}${alignment.prUrl ? `  ${alignment.prUrl}` : ""}`));
+  }
+  if (grep) console.info(colors_default.dim(`   ${grep}`));
+  console.info(colors_default.dim(`   read:    pnpm cella align --show ${alignment.id}`));
+  if (alignment.url) console.info(colors_default.dim(`            ${alignment.url}`));
+  if (alignment.codemod) console.info(colors_default.dim(`   codemod: pnpm cella align --run ${alignment.id}`));
+  console.info();
+}
+function printShowBlock(title, items) {
+  if (items.length === 0) return;
+  console.info(colors_default.dim(`${title} (${items.length}):`));
+  for (const item of items.slice(0, SHOW_LIST_MAX)) console.info(colors_default.dim(`  ${item}`));
+  if (items.length > SHOW_LIST_MAX) console.info(colors_default.dim(`  ... + ${items.length - SHOW_LIST_MAX} more`));
+}
+async function showAlignment(config, ref, pending, id) {
+  const { forkPath } = config;
+  const upstreamBranch = `${DEFAULT_UPSTREAM_REMOTE}/${config.settings.upstreamBranch}`;
+  let readRef = ref;
+  let alignment = await readAlignment(forkPath, ref, id);
+  if (!alignment && await revParse(forkPath, upstreamBranch)) {
+    alignment = await readAlignment(forkPath, upstreamBranch, id);
+    readRef = upstreamBranch;
+  }
+  if (!alignment) throw new Error(`no alignment '${id}' at upstream ${ref.slice(0, 7)} or ${upstreamBranch}`);
+  const source = await git(["show", `${readRef}:${ALIGNMENTS_DIR}/${id}/README.md`], forkPath);
+  const described = await describeAlignment(
+    config,
+    await readForkView(config, ref),
+    readRef,
+    alignment,
+    pending.includes(id)
+  );
+  if (readRef !== ref) console.info(colors_default.dim(`not at the last upgrade ${ref.slice(0, 7)}: read at ${upstreamBranch}`));
+  if (described.url) console.info(colors_default.dim(described.url));
+  console.info(source);
   console.info();
+  if (described.commit) {
+    const pr = described.pr !== null ? `#${described.pr} ` : "";
+    console.info(
+      colors_default.dim(`added in ${pr}(${described.commit.slice(0, 9)})${described.prUrl ? `  ${described.prUrl}` : ""}`)
+    );
+  }
+  printShowBlock("added in the same commit", described.sharedCommit);
+  printShowBlock("files of that commit the app pins, ignores or changed", described.yourFiles);
+  const grep = grepSummary(described);
+  if (grep) console.info(colors_default.dim(`${grep} (${described.grep.join(", ")})`));
+  printShowBlock(
+    "grep hits",
+    described.grepHits.map((hit) => `${hit.file}:${hit.line}`)
+  );
 }
-async function writeNoteFolder(config, ref, id) {
+async function writeAlignmentFolder(config, ref, id) {
   const { forkPath } = config;
-  const note = await readNote(forkPath, ref, id);
-  if (!note) throw new Error(`no migration note '${id}' at upstream ${ref.slice(0, 7)}`);
-  const files = (await git(["ls-tree", "-r", "--name-only", `${ref}:${NOTES_DIR}/${id}`], forkPath)).split("\n").filter(Boolean);
+  const alignment = await readAlignment(forkPath, ref, id);
+  if (!alignment) throw new Error(`no alignment '${id}' at upstream ${ref.slice(0, 7)}`);
+  const files = (await git(["ls-tree", "-r", "--name-only", `${ref}:${ALIGNMENTS_DIR}/${id}`], forkPath)).split("\n").filter(Boolean);
   const target = join8(EXTRACT_DIR, id);
   for (const file of files) {
-    const content = execFileSync("git", ["show", `${ref}:${NOTES_DIR}/${id}/${file}`], {
+    const content = execFileSync("git", ["show", `${ref}:${ALIGNMENTS_DIR}/${id}/${file}`], {
       cwd: forkPath,
       maxBuffer: MAX_BUFFER
     });
@@ -2463,27 +2700,27 @@ async function writeNoteFolder(config, ref, id) {
     await mkdir4(dirname4(path), { recursive: true });
     await writeFile3(path, content);
   }
-  return { note, target, files };
+  return { alignment, target, files };
 }
-async function extractNote(config, ref, id) {
-  const { note, target, files } = await writeNoteFolder(config, ref, id);
+async function extractAlignment(config, ref, id) {
+  const { alignment, target, files } = await writeAlignmentFolder(config, ref, id);
   console.info(`${checkMark} extracted ${files.length} file(s) to ${target}/`);
-  console.info(colors_default.dim(`  the README's ${NOTES_DIR}/${id}/ paths are this folder.`));
-  if (note.codemod) {
-    console.info(colors_default.dim(`  pnpm exec tsx ${target}/${note.codemod} inventory ${note.roots.join(" ")}`));
-    console.info(colors_default.dim(`  or, keeping files identical to upstream as they are: pnpm cella migrate --run ${id}`));
+  console.info(colors_default.dim(`  the README's ${ALIGNMENTS_DIR}/${id}/ paths are this folder.`));
+  if (alignment.codemod) {
+    console.info(colors_default.dim(`  pnpm exec tsx ${target}/${alignment.codemod} inventory ${alignment.roots.join(" ")}`));
+    console.info(colors_default.dim(`  or, keeping files identical to upstream as they are: pnpm cella align --run ${id}`));
   }
 }
-async function runNote(config, ref, id) {
+async function runAlignment(config, ref, id) {
   const { forkPath } = config;
-  const { note, target } = await writeNoteFolder(config, ref, id);
-  if (!note.codemod) {
+  const { alignment, target } = await writeAlignmentFolder(config, ref, id);
+  if (!alignment.codemod) {
     throw new Error(
-      `migration note '${id}' ships no codemod script: its steps are manual, read them with \`pnpm cella migrate --show ${id}\`.`
+      `alignment '${id}' ships no codemod script: its steps are manual, read them with \`pnpm cella align --show ${id}\`.`
     );
   }
-  const script = join8(target, note.codemod);
-  const args = config.runArgs?.length ? config.runArgs : ["inventory", ...note.roots];
+  const script = join8(target, alignment.codemod);
+  const args = config.runArgs?.length ? config.runArgs : ["inventory", ...alignment.roots];
   const upstreamCommit = await readManifestBase(forkPath) ?? ref;
   await ensureUpstreamCommit(config, upstreamCommit);
   const identical = await listIdenticalToRef(forkPath, upstreamCommit);
@@ -2508,92 +2745,335 @@ async function runNote(config, ref, id) {
   }
   if (child.status !== 0) throw new Error(`the codemod exited with code ${child.status ?? "unknown"}`);
   if (!config.runArgs?.length) {
-    const apply = ["rewrite", ...note.roots].join(" ");
-    console.info(colors_default.dim(`report only. to apply: pnpm cella migrate --run ${id} -- ${apply}`));
+    const apply = ["rewrite", ...alignment.roots].join(" ");
+    console.info(colors_default.dim(`report only. to apply: pnpm cella align --run ${id} -- ${apply}`));
   }
 }
-async function markNotes(config, ref, pending, ids) {
+async function markAlignments(config, ref, pending, ids) {
   const open = new Set(pending);
   const unknown = ids.filter((id) => !open.has(id));
   for (const id of ids) open.delete(id);
   await writePending(config.forkPath, [...open]);
   const marked = ids.length - unknown.length;
-  if (marked > 0) console.info(`${checkMark} recorded ${marked} note(s) as handled`);
+  if (marked > 0) console.info(`${checkMark} recorded ${marked} alignment(s) as handled`);
   if (unknown.length > 0) console.info(colors_default.dim(`not pending, left as is: ${unknown.join(", ")}`));
-  console.info(colors_default.dim(formatNotesLine((await listNoteIds(config.forkPath, ref)).length, open.size)));
+  console.info(colors_default.dim(formatAlignmentsLine((await listAlignmentIds(config.forkPath, ref)).length, open.size)));
 }
-async function runMigrate(config) {
+async function runAlign(config) {
   const { forkPath } = config;
-  const ref = await resolveNotesRef(config);
+  const ref = await resolveAlignmentsRef(config);
   if (!ref) {
-    console.info(colors_default.dim("no sync point recorded yet: migration notes start with the first `pnpm cella sync`."));
+    console.info(colors_default.dim("no upgrade recorded yet: alignments start with the first `pnpm cella upgrade`."));
     return;
   }
   const pending = await readPending(forkPath);
-  const githubUrl = getGitHubBaseUrl(config.settings.upstreamUrl) ?? void 0;
-  const urlOf = (id) => noteUrl(githubUrl, ref, id);
-  if (config.mark?.length) return markNotes(config, ref, pending, config.mark);
-  if (config.run) return runNote(config, ref, config.run);
-  if (config.extract) return extractNote(config, ref, config.extract);
-  if (config.show) {
-    const source = await git(["show", `${ref}:${NOTES_DIR}/${config.show}/README.md`], forkPath, {
-      ignoreErrors: true
-    });
-    if (!source) throw new Error(`no migration note '${config.show}' at upstream ${ref.slice(0, 7)}`);
-    const url = urlOf(config.show);
-    if (url) console.info(colors_default.dim(url));
-    console.info(source);
-    return;
-  }
-  const ids = config.all ? await listNoteIds(forkPath, ref) : pending;
-  const notes = (await Promise.all(ids.map((id) => readNote(forkPath, ref, id)))).map(
-    (note, i) => note ?? {
+  if (config.mark?.length) return markAlignments(config, ref, pending, config.mark);
+  if (config.run) return runAlignment(config, ref, config.run);
+  if (config.extract) return extractAlignment(config, ref, config.extract);
+  if (config.show) return showAlignment(config, ref, pending, config.show);
+  const ids = config.all ? await listAlignmentIds(forkPath, ref) : pending;
+  const read = await Promise.all(ids.map((id) => readAlignment(forkPath, ref, id)));
+  const alignments = read.map(
+    (alignment, i) => alignment ?? {
       id: ids[i],
       title: `${ids[i]} (no longer upstream)`,
       summary: "",
-      syncBreaking: false,
+      breaking: false,
       clientCacheBump: false,
+      caughtBy: null,
+      generate: false,
+      grep: [],
       roots: [],
       codemod: null
     }
   );
-  const total = (await listNoteIds(forkPath, ref)).length;
+  const total = (await listAlignmentIds(forkPath, ref)).length;
+  const open = new Set(pending);
+  const view = await readForkView(config, ref);
+  const described = await Promise.all(
+    alignments.map((alignment) => describeAlignment(config, view, ref, alignment, open.has(alignment.id)))
+  );
   if (config.json) {
-    const open = new Set(pending);
-    const out = {
-      upstreamCommit: ref,
-      total,
-      open: pending.length,
-      notes: notes.map((note) => ({
-        ...note,
-        kind: note.codemod ? "codemod" : "manual",
-        open: open.has(note.id),
-        url: urlOf(note.id) ?? null
-      }))
-    };
-    writeStdout(JSON.stringify(out, null, 2));
+    writeStdout(JSON.stringify({ upstreamCommit: ref, total, open: pending.length, alignments: described }, null, 2));
     return;
   }
-  console.info(colors_default.dim(formatNotesLine(total, pending.length)));
-  if (notes.length === 0) return;
+  console.info(colors_default.dim(formatAlignmentsLine(total, pending.length)));
+  if (described.length === 0) return;
   console.info();
-  for (const [i, note] of notes.entries()) printNote(i + 1, note, urlOf(note.id));
+  for (const [i, alignment] of described.entries()) printAlignment(i + 1, alignment);
+  const schema = described.filter((alignment) => alignment.open && alignment.generate);
+  if (schema.length > 1) {
+    console.info(
+      colors_default.dim(
+        `${schema.length} open alignments change the schema: work their code steps first, then run pnpm generate once.`
+      )
+    );
+  }
   if (pending.length > 0) {
-    console.info(colors_default.dim("work each note's README, check with `pnpm check`, then record it:"));
-    console.info(colors_default.dim(`  pnpm cella migrate --mark ${pending.join(" ")}`));
+    console.info(colors_default.dim("work each alignment's README, check with `pnpm check`, then record it:"));
+    console.info(colors_default.dim(`  pnpm cella align --mark ${pending.join(" ")}`));
   }
 }
 
-// src/services/review-page.ts
+// src/services/analyze-report.ts
 import { basename as basename2 } from "path";
-import process7 from "process";
+var BEHIND_FLAT_MAX = 15;
+var AHEAD_FLAT_MAX = 8;
+var ABSENT_SHOWN_MIN = 10;
+var ENTRY_COLLAPSE_MIN = 5;
+var SECTION_ROWS_MAX = 100;
+var UPSTREAM_CHANGE = { fields: "changed", repo: "upstream" };
+var UPSTREAM_SIDE = { fields: "upstream", repo: "upstream" };
+var FORK_SIDE = { fields: "changed", repo: "fork" };
+function cell(value, width, color, align) {
+  if (!value) return " ".repeat(width);
+  return padVisible(color ? color(value) : value, width, align === "end" ? "end" : "start");
+}
+function formatRows(rows, caption) {
+  const iconWidth = rows.some((row) => row.icon) ? 2 : 0;
+  const labelWidth = Math.max(...rows.map((row) => row.label.length + (row.note ? row.note.length + 1 : 0)));
+  const countWidth = Math.max(0, ...rows.map((row) => row.count?.length ?? 0));
+  const tagWidth = Math.max(0, ...rows.map((row) => row.tag?.length ?? 0));
+  const ageWidth = Math.max(0, ...rows.map((row) => row.age?.length ?? 0));
+  const lines = [];
+  if (caption && countWidth > 0) lines.push(colors_default.dim(caption.padStart(2 + iconWidth + labelWidth + 2 + countWidth)));
+  for (const row of rows) {
+    const icon = iconWidth ? cell(row.icon, iconWidth) : "";
+    const label = `${hyperlink(row.label, row.link)}${row.note ? ` ${colors_default.dim(row.note)}` : ""}`;
+    const cells = [`  ${icon}${padVisible(label, labelWidth)}`];
+    if (countWidth) cells.push(cell(row.count, countWidth, row.countColor, "end"));
+    if (tagWidth) cells.push(cell(row.tag, tagWidth, row.tagColor));
+    if (ageWidth) cells.push(cell(row.age, ageWidth, colors_default.dim, "end"));
+    lines.push(cells.join("  ").trimEnd());
+  }
+  return lines;
+}
+function formatCappedRows(rows, caption) {
+  if (rows.length <= SECTION_ROWS_MAX) return formatRows(rows, caption);
+  return [
+    ...formatRows(rows.slice(0, SECTION_ROWS_MAX), caption),
+    colors_default.dim(`  + ${rows.length - SECTION_ROWS_MAX} more`)
+  ];
+}
+function hint(text, command = "") {
+  return `  ${colors_default.dim(text)}${command}`;
+}
+function printSection(title, count3, body, hints = []) {
+  printSectionHeader(`${title} ${colors_default.dim(`\xB7 ${plural(count3, "file")}`)}`);
+  for (const line of body) console.info(line);
+  if (hints.length === 0) return;
+  console.info();
+  for (const line of hints) console.info(line);
+}
+function byPath(a, b) {
+  return a.path.localeCompare(b.path);
+}
+function fileLink(file, side, links) {
+  const { fileLinkMode = "commit", upstreamGitHubUrl, upstreamSha, forkGitHubUrl } = links;
+  if (fileLinkMode === "file") {
+    if (!upstreamGitHubUrl || !upstreamSha || !file.existsInUpstream) return void 0;
+    return `${upstreamGitHubUrl}/blob/${upstreamSha}/${file.path}`;
+  }
+  const commit = side.fields === "upstream" ? file.upstreamCommit : file.changedCommit;
+  const repo = side.repo === "upstream" ? upstreamGitHubUrl : forkGitHubUrl;
+  return commit && repo ? `${repo}/commit/${commit}` : void 0;
+}
+function changeTimestamp(file, side) {
+  return side.fields === "upstream" ? file.upstreamChangedTs : file.changedTs;
+}
+function changeKind(file) {
+  if (!file.existsInFork) return "new";
+  if (!file.existsInUpstream) return "deleted";
+  return "changed";
+}
+var KIND_TAG = { new: { tag: "new", color: colors_default.green }, deleted: { tag: "deleted", color: colors_default.red } };
+function fileRow(file, side, options, extra = {}) {
+  const timestamp = changeTimestamp(file, side);
+  const kind = changeKind(file);
+  return {
+    label: file.path,
+    link: fileLink(file, side, options.links),
+    age: timestamp ? shortAge(timestamp, options.nowMs) : void 0,
+    ...kind === "changed" ? {} : { tag: KIND_TAG[kind].tag, tagColor: KIND_TAG[kind].color },
+    ...extra
+  };
+}
+function commonFolder(paths) {
+  const folders = paths.map((path) => path.split("/").slice(0, -1));
+  const [first] = folders;
+  let depth = 0;
+  while (depth < first.length && folders.every((parts) => parts[depth] === first[depth])) depth++;
+  return first.slice(0, depth).join("/");
+}
+function formatFolderRows(files, columns) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    const top = file.path.includes("/") ? file.path.split("/")[0] : file.path;
+    groups.set(top, [...groups.get(top) ?? [], file]);
+  }
+  const rows = [...groups.values()].map((group) => ({
+    label: group.length === 1 ? group[0].path : `${commonFolder(group.map((file) => file.path))}/`,
+    files: group
+  })).sort((a, b) => b.files.length - a.files.length || a.label.localeCompare(b.label));
+  const labelWidth = Math.max(...rows.map((row) => row.label.length));
+  const countWidth = Math.max(...rows.map((row) => String(row.files.length).length));
+  const order = { new: 0, deleted: 1, changed: 2 };
+  return rows.map((row) => {
+    let line = `  ${row.label.padEnd(labelWidth)}  ${colors_default.cyan(String(row.files.length).padStart(countWidth))}`;
+    if (row.files.length === 1) return line.trimEnd();
+    const seen = /* @__PURE__ */ new Map();
+    for (const file of row.files) seen.set(basename2(file.path), (seen.get(basename2(file.path)) ?? 0) + 1);
+    const names = row.files.map((file) => ({
+      kind: changeKind(file),
+      name: (seen.get(basename2(file.path)) ?? 0) > 1 ? file.path.slice(row.label.length) : basename2(file.path)
+    })).sort((a, b) => order[a.kind] - order[b.kind] || a.name.localeCompare(b.name));
+    let width = visibleWidth(line);
+    for (const { kind, name } of names) {
+      const text = kind === "new" ? `+${name}` : kind === "deleted" ? `\u2212${name}` : name;
+      if (width + 2 + text.length > columns - 2) {
+        line += colors_default.dim(" \u2026");
+        break;
+      }
+      line += `  ${kind === "new" ? colors_default.green(text) : kind === "deleted" ? colors_default.red(text) : colors_default.dim(text)}`;
+      width += 2 + text.length;
+    }
+    return line;
+  });
+}
+function printBehind(files, options, columns) {
+  const behind = filesWithStatus(files, "behind").sort(byPath);
+  if (behind.length === 0) return;
+  const title = colors_default.cyan("\u2193 behind on upstream");
+  if (options.all || behind.length <= BEHIND_FLAT_MAX) {
+    printSection(title, behind.length, formatCappedRows(behind.map((file) => fileRow(file, UPSTREAM_CHANGE, options))));
+    return;
+  }
+  printSection(title, behind.length, formatFolderRows(behind, columns), [
+    hint("every path: ", "pnpm cella analyze --all")
+  ]);
+}
+function printFlat(files, title, side, options) {
+  if (files.length === 0) return;
+  const rows = [...files].sort(byPath).map((file) => fileRow(file, side, options));
+  printSection(title, files.length, formatCappedRows(rows));
+}
+function absentLines(file) {
+  return file.upstreamLinesAbsent ?? 0;
+}
+function describeAbsent(files) {
+  const counts = files.map(absentLines);
+  const missing = counts.filter((count3) => count3 > 0);
+  const parts = [];
+  if (missing.length > 0) {
+    const [low, high] = [Math.min(...missing), Math.max(...missing)];
+    parts.push(`${missing.length} with ${low === high ? plural(low, "line") : `${low}\u2013${high} lines`} absent`);
+  }
+  if (missing.length < counts.length) parts.push(`${counts.length - missing.length} with none`);
+  return parts.join(", ");
+}
+function printAhead(files, options) {
+  const ahead = filesWithStatus(files, "ahead").sort((a, b) => absentLines(b) - absentLines(a) || byPath(a, b));
+  if (ahead.length === 0) return;
+  let shown = ahead;
+  if (!options.all && ahead.length > AHEAD_FLAT_MAX) {
+    const many = ahead.filter((file) => absentLines(file) >= ABSENT_SHOWN_MIN);
+    shown = many.length > 0 ? many : ahead.slice(0, 5);
+  }
+  const rest = ahead.slice(shown.length);
+  const rows = shown.map(
+    (file) => fileRow(file, FORK_SIDE, options, {
+      count: absentLines(file) > 0 ? String(absentLines(file)) : void 0,
+      countColor: colors_default.yellow
+    })
+  );
+  const body = formatCappedRows(rows, "upstream lines absent");
+  if (rest.length > 0) body.push(colors_default.dim(`  + ${rest.length} more: ${describeAbsent(rest)}`));
+  const hints = ahead.some((file) => absentLines(file) > 0) ? [hint("what a merge would bring in: ", "pnpm cella analyze --unpinned")] : [];
+  printSection(colors_default.blue("\u2191 protected in fork"), ahead.length, body, hints);
+}
+function entryFinder(overrides) {
+  const entries = [...overrides?.ignored ?? [], ...overrides?.pinned ?? []].map(normalizeEntry).filter(Boolean).sort((a, b) => b.length - a.length);
+  return (path) => entries.find((entry) => isUnderAnyFolder(path, [entry]));
+}
+var KIND_ORDER = { new: 0, changed: 1, deleted: 2 };
+function protectedRow(items, options) {
+  const [{ file, kind, entry }] = items;
+  const lines = items.map((item) => item.file.upstreamChangedLines);
+  const total = lines.every((count3) => count3 !== void 0) ? lines.reduce((sum, count3) => sum + (count3 ?? 0), 0) : void 0;
+  const sign = kind === "new" ? "+" : kind === "deleted" ? "\u2212" : "";
+  const newest = Math.max(0, ...items.map((item) => changeTimestamp(item.file, UPSTREAM_SIDE) ?? 0));
+  const row = {
+    label: file.path,
+    link: fileLink(file, UPSTREAM_SIDE, options.links),
+    icon: protectionIcon(file),
+    count: total === void 0 ? void 0 : `${sign}${compactCount(total)}`,
+    countColor: kind === "new" ? colors_default.green : kind === "deleted" ? colors_default.red : colors_default.yellow,
+    ...kind === "changed" ? {} : { tag: KIND_TAG[kind].tag, tagColor: KIND_TAG[kind].color },
+    age: newest ? shortAge(newest, options.nowMs) : void 0
+  };
+  if (items.length === 1 || !entry) return row;
+  const names = new Set(items.map((item) => basename2(item.file.path)));
+  const { upstreamGitHubUrl, upstreamSha } = options.links;
+  return {
+    ...row,
+    label: `${entry}/`,
+    note: names.size === 1 ? `\xB7 ${items.length} \xD7 ${[...names][0]}` : `\xB7 ${items.length} files`,
+    link: upstreamGitHubUrl && upstreamSha ? `${upstreamGitHubUrl}/tree/${upstreamSha}/${entry}` : void 0
+  };
+}
+function printProtectedBehind(result, options) {
+  const findEntry = entryFinder(options.overrides);
+  const items = findProtectedBehindUpstream(result).map((file) => ({
+    file,
+    kind: file.upstreamOnly ? changeKind(file) : "changed",
+    entry: findEntry(file.path)
+  }));
+  if (items.length === 0) return;
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = options.all || !item.entry ? item.file.path : `${item.kind}\0${item.entry}`;
+    groups.set(key, [...groups.get(key) ?? [], item]);
+  }
+  const single = (group) => group.length < ENTRY_COLLAPSE_MIN;
+  const lines = (group) => group.reduce((sum, item) => sum + (item.file.upstreamChangedLines ?? 0), 0);
+  const ordered = [...groups.values()].flatMap((group) => single(group) ? group.map((item) => [item]) : [group]).sort(
+    (a, b) => Number(a.length > 1) - Number(b.length > 1) || KIND_ORDER[a[0].kind] - KIND_ORDER[b[0].kind] || lines(b) - lines(a) || byPath(a[0].file, b[0].file)
+  );
+  printSection(
+    `${warningMark} ${colors_default.yellow("protected but behind upstream")}`,
+    items.length,
+    formatCappedRows(
+      ordered.map((group) => protectedRow(group, options)),
+      "lines changed upstream"
+    ),
+    [hint("the fork side wins: adopt what you need from the review page")]
+  );
+}
+function printAnalysisFileGroups(result, options) {
+  const columns = options.columns ?? terminalColumns();
+  printBehind(result.files, options, columns);
+  printFlat(filesWithStatus(result.files, "diverged"), colors_default.magenta("\u21C5 diverged"), UPSTREAM_SIDE, options);
+  printAhead(result.files, options);
+  printFlat(
+    filesWithStatus(result.files, "drifted"),
+    `${warningMark} ${colors_default.yellow("drifted from upstream")}`,
+    FORK_SIDE,
+    options
+  );
+  printProtectedBehind(result, options);
+}
+
+// src/services/review-page.ts
+import { existsSync as existsSync7, rmSync } from "fs";
+import { basename as basename3 } from "path";
+import process9 from "process";
 import { pathToFileURL } from "url";
 
 // src/utils/diff.ts
 import { execFileSync as execFileSync2 } from "child_process";
 import { mkdirSync, writeFileSync } from "fs";
-import { join as join9 } from "path";
-import process6 from "process";
+import { dirname as dirname5, join as join9 } from "path";
+import process8 from "process";
 function gitDiffFile(cwd, range, filePath) {
   try {
     return execFileSync2("git", ["diff", "--no-color", range, "--", filePath], { cwd, maxBuffer: MAX_BUFFER });
@@ -2628,9 +3108,9 @@ ${prerenderedHTML}
     for (const file of section.files) files.push(await renderFile(file));
     const count3 = section.files.length + (section.omitted?.length ?? 0);
     const title = section.title ? `<h2>${escapeHtml(section.title)} <span class="count">\xB7 ${count3} ${count3 === 1 ? "file" : "files"}</span></h2>` : "";
-    const hint = section.hint ? `<p class="hint">${escapeHtml(section.hint)}</p>` : "";
+    const hint2 = section.hint ? `<p class="hint">${escapeHtml(section.hint)}</p>` : "";
     const omitted = section.omitted?.length ? `<p class="hint">Not shown here (binary, too large, or past the page limit):</p><ul class="omitted">${section.omitted.map((path) => `<li><code>${escapeHtml(path)}</code></li>`).join("")}</ul>` : "";
-    blocks.push(`<section id="section-${index2 + 1}">${title}${hint}${files.join("\n")}${omitted}</section>`);
+    blocks.push(`<section id="section-${index2 + 1}">${title}${hint2}${files.join("\n")}${omitted}</section>`);
   }
   const titled = sections.filter((section) => section.title);
   const index = titled.length > 1 ? `<nav><ol>${sections.map(
@@ -2694,16 +3174,18 @@ ${blocks.join("\n")}
 }
 async function writeDiffPage(sections, meta, repoPath, name) {
   const html = await renderDiffPage(sections, meta);
-  const gitDir = execFileSync2("git", ["rev-parse", "--absolute-git-dir"], { cwd: repoPath, encoding: "utf8" }).trim();
-  const dir = join9(gitDir, "cella-diff");
-  mkdirSync(dir, { recursive: true });
-  const outPath = join9(dir, `${name.replace(/[^\w.-]+/g, "-")}.html`);
+  const outPath = diffPagePath(repoPath, name);
+  mkdirSync(dirname5(outPath), { recursive: true });
   writeFileSync(outPath, html);
   return outPath;
 }
+function diffPagePath(repoPath, name) {
+  const gitDir = execFileSync2("git", ["rev-parse", "--absolute-git-dir"], { cwd: repoPath, encoding: "utf8" }).trim();
+  return join9(gitDir, "cella-diff", `${name.replace(/[^\w.-]+/g, "-")}.html`);
+}
 function openInBrowser(target) {
   try {
-    execFileSync2(process6.platform === "darwin" ? "open" : "xdg-open", [target], { stdio: "ignore" });
+    execFileSync2(process8.platform === "darwin" ? "open" : "xdg-open", [target], { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -2711,49 +3193,50 @@ function openInBrowser(target) {
 }
 
 // src/services/review-page.ts
-var MAX_PAGE_FILES = 50;
+var PAGE_LIMITS = { files: 50, lines: 15e3, patchLines: 2e3 };
 var MAX_PATCH_BYTES = 512 * 1024;
 function reviewSections(result, command) {
   const [base, upstream] = result.upstreamDiffRange?.split("..") ?? [];
   if (!base || !upstream) return [];
   const sinceSync = `${base}..${upstream}`;
-  const dropped = command === "sync" ? {
-    title: "protected files kept the fork version",
-    hint: "What upstream changed in these files since the last sync. The fork kept its own version, so none of it arrived: adopt what you need.",
-    range: sinceSync,
-    paths: result.protectedConflicts ?? []
-  } : {
-    title: "protected but behind upstream",
-    hint: "What upstream changed in these files since the last sync. They are pinned or ignored, so the sync keeps the fork version and none of it arrives: adopt what you need.",
-    range: sinceSync,
-    paths: findProtectedBehind(result.files).map((file) => file.path)
-  };
-  const sections = [
-    dropped,
+  const sections = command === "upgrade" ? [
+    {
+      title: "protected files kept the fork version",
+      hint: "What upstream changed in these files since the last upgrade. The fork kept its own version, so none of it arrived: adopt what you need.",
+      range: sinceSync,
+      paths: result.protectedConflicts ?? []
+    },
     {
       title: "ignored paths changed upstream",
-      hint: "What upstream changed under ignored paths since the last sync. The fork left these files untouched, and ignored paths never sync.",
+      hint: "What upstream changed under ignored paths since the last upgrade. The fork left these files untouched, and ignored paths never merge.",
       range: sinceSync,
       paths: (result.ignoredUpstreamChanges ?? []).flatMap((group) => group.paths)
-    },
+    }
+  ] : [
     {
-      title: "pinned files that match the previous upstream",
-      hint: "What upstream changed in these files since the last sync. The fork copy still equals the previous upstream, so the pin only drops these changes: unpin to take them.",
+      title: "protected but behind upstream",
+      hint: "What upstream changed in these files since the last upgrade. They are pinned or ignored, so the upgrade keeps the fork version and none of it arrives: adopt what you need.",
       range: sinceSync,
-      paths: findMaskingPins(result.files).map((file) => file.path)
+      paths: findProtectedBehindUpstream(result).map((file) => file.path)
     }
   ];
+  sections.push({
+    title: "pinned files that match the previous upstream",
+    hint: "What upstream changed in these files since the last upgrade. The fork copy still equals the previous upstream, so the pin only drops these changes: unpin to take them.",
+    range: sinceSync,
+    paths: findMaskingPins(result.files).map((file) => file.path)
+  });
   if (command === "analyze") {
     sections.push(
       {
         title: "protected in fork, upstream lines absent",
-        hint: "The fork's version against upstream's, both as they are now: added lines are upstream content the fork does not have, dropped by an earlier sync or removed on purpose.",
+        hint: "The fork's version against upstream's, both as they are now: added lines are upstream content the fork does not have, dropped by an earlier upgrade or removed on purpose.",
         range: `HEAD..${upstream}`,
         paths: filesWithStatus(result.files, "ahead").filter((file) => (file.upstreamLinesAbsent ?? 0) > 0).map((file) => file.path)
       },
       {
         title: "drifted from upstream",
-        hint: "What the fork changed in these files since the last sync. They are not pinned or ignored, so upstream changes still merge into them.",
+        hint: "What the fork changed in these files since the last upgrade. They are not pinned or ignored, so upstream changes still merge into them.",
         range: `${base}..HEAD`,
         paths: filesWithStatus(result.files, "drifted").map((file) => file.path)
       }
@@ -2761,55 +3244,100 @@ function reviewSections(result, command) {
   }
   return sections.filter((section) => section.paths.length > 0);
 }
-async function writeReviewPage(forkPath, sections, meta) {
+function countLines(patch) {
+  let count3 = 0;
+  for (let at = patch.indexOf(10); at !== -1; at = patch.indexOf(10, at + 1)) count3++;
+  return count3;
+}
+async function writeReviewPage(forkPath, sections, meta, limits = PAGE_LIMITS) {
   const [base, upstream] = meta.range.split("..");
+  const pageSections = sections.map((section) => ({
+    title: section.title,
+    hint: section.hint,
+    files: [],
+    omitted: []
+  }));
+  const queues = sections.map((section) => [...section.paths]);
   let diffs = 0;
-  const pageSections = [];
-  for (const section of sections) {
-    const pageSection = { title: section.title, hint: section.hint, files: [], omitted: [] };
-    for (const path of section.paths) {
-      if (diffs >= MAX_PAGE_FILES) {
-        pageSection.omitted?.push(path);
+  let lines = 0;
+  while (queues.some((queue) => queue.length > 0)) {
+    for (const [index, queue] of queues.entries()) {
+      const path = queue.shift();
+      if (path === void 0) continue;
+      const pageSection = pageSections[index];
+      if (diffs >= limits.files || lines >= limits.lines) {
+        pageSection.omitted.push(path);
         continue;
       }
-      const patch = gitDiffFile(forkPath, section.range, path);
+      const patch = gitDiffFile(forkPath, sections[index].range, path);
       if (patch.length === 0) continue;
-      if (patch.length > MAX_PATCH_BYTES || !patch.includes("\n@@ ")) {
-        pageSection.omitted?.push(path);
+      const patchLines = patch.length > MAX_PATCH_BYTES ? Number.POSITIVE_INFINITY : countLines(patch);
+      if (patchLines > limits.patchLines || lines + patchLines > limits.lines || !patch.includes("\n@@ ")) {
+        pageSection.omitted.push(path);
         continue;
       }
       pageSection.files.push({ path, patch: patch.toString() });
       diffs++;
+      lines += patchLines;
     }
-    if (pageSection.files.length > 0 || pageSection.omitted?.length) pageSections.push(pageSection);
   }
   if (diffs === 0) return void 0;
+  const shown = pageSections.filter((section) => section.files.length > 0 || section.omitted.length > 0);
   const page = await writeDiffPage(
-    pageSections,
-    { title: `${meta.command} review`, note: `${basename2(forkPath)} \xB7 last sync ${base} \u2192 upstream ${upstream}` },
+    shown,
+    { title: `${meta.command} review`, note: `${basename3(forkPath)} \xB7 last upgrade ${base} \u2192 upstream ${upstream}` },
     forkPath,
     `${meta.command}-review`
   );
-  return { path: page, diffs };
+  const listed = shown.reduce((count3, section) => count3 + section.omitted.length, 0);
+  return { path: page, diffs, listed, sections: shown.length };
 }
 async function reportReviewPage(forkPath, result, command) {
   const sections = reviewSections(result, command);
-  if (sections.length === 0 || !result.upstreamDiffRange) return;
-  createSpinner("writing review page...");
   let page;
+  if (sections.length > 0 && result.upstreamDiffRange) {
+    createSpinner("writing review page...");
+    try {
+      page = await writeReviewPage(forkPath, sections, { command, range: result.upstreamDiffRange });
+    } catch {
+      page = void 0;
+    }
+    spinnerSuccess();
+  }
+  if (!page) {
+    if (command === "upgrade") removeSyncReviewPage(forkPath);
+    return void 0;
+  }
+  const opened = command === "upgrade" && process9.stdout.isTTY === true && openInBrowser(page.path);
+  return { ...page, command, opened };
+}
+function removeSyncReviewPage(forkPath) {
   try {
-    page = await writeReviewPage(forkPath, sections, { command, range: result.upstreamDiffRange });
+    rmSync(diffPagePath(forkPath, "upgrade-review"), { force: true });
   } catch {
-    page = void 0;
   }
-  spinnerSuccess();
-  if (!page) return;
-  const opened = command === "sync" && process7.stdout.isTTY === true && openInBrowser(page.path);
-  console.info();
-  console.info(
-    `${colors_default.cyan("\u29C8")} review page with ${plural(page.diffs, "diff")}${opened ? ", opened in the browser" : ""}:`
-  );
-  console.info(colors_default.dim(`  ${hyperlink(page.path, pathToFileURL(page.path).href)}`));
+}
+function existingSyncReviewPage(forkPath) {
+  try {
+    const path = diffPagePath(forkPath, "upgrade-review");
+    return existsSync7(path) ? path : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function reviewStep(page) {
+  const path = typeof page === "string" ? page : page.path;
+  const url = pathToFileURL(path).href;
+  let detail = colors_default.dim("upstream changes the upgrade did not bring in, from the merge run");
+  if (typeof page !== "string") {
+    const what = page.command === "upgrade" ? `${plural(page.diffs, "diff")} of upstream changes that did not arrive` : `${plural(page.diffs, "diff")} in ${plural(page.sections, "section")}`;
+    const notes = [
+      page.listed > 0 ? `${page.listed} listed without a diff` : "",
+      page.opened ? "opened in the browser" : ""
+    ].filter(Boolean).map((note) => ` \xB7 ${note}`).join("");
+    detail = `${what}${notes ? colors_default.dim(notes) : ""}`;
+  }
+  return { label: "review", line: hyperlink(colors_default.cyan(url), url), details: [detail] };
 }
 
 // src/services/analyze.ts
@@ -2844,8 +3372,8 @@ async function runAnalyze(config) {
       upstreamChangedLines: f.upstreamChangedLines ?? null,
       upstreamLinesAbsent: f.upstreamLinesAbsent ?? null,
       upstreamOnly: f.upstreamOnly ?? false,
-      // Only on the sync config: upstream override entries and packageJsonSync keys the fork config does not follow
-      upstreamOverrides: overrides && f.path === CONFIG_FILE ? { pinned: overrides.pinned, ignored: overrides.ignored, packageJsonSync: overrides.packageJsonSync } : null
+      // Only on the CLI config: upstream override entries and packageJsonKeys the fork config does not follow
+      upstreamOverrides: overrides && f.path === CONFIG_FILE ? { pinned: overrides.pinned, ignored: overrides.ignored, packageJsonKeys: overrides.packageJsonKeys } : null
     }));
     writeStdout(JSON.stringify(out, null, 2));
     return result;
@@ -2856,23 +3384,56 @@ async function runAnalyze(config) {
     }
     return result;
   }
-  const linkOptions = {
-    upstreamGitHubUrl: result.upstreamGitHubUrl,
-    upstreamBranch: result.upstreamBranch,
-    fileLinkMode: config.settings.fileLinkMode,
-    forkPath: config.forkPath
-  };
-  printAnalysisFileGroups(result.files, linkOptions);
-  printEngineReports(result, "analysis summary");
-  await reportReviewPage(config.forkPath, result, "analyze");
-  await printMigrationNotesLine(config, result);
-  console.info();
+  printAnalysisFileGroups(result, {
+    links: {
+      upstreamGitHubUrl: result.upstreamGitHubUrl,
+      upstreamSha: result.upstreamCommit?.hash,
+      forkGitHubUrl: await readOriginGitHubUrl(config.forkPath),
+      fileLinkMode: config.settings.fileLinkMode,
+      forkPath: config.forkPath
+    },
+    all: config.all,
+    overrides: config.overrides
+  });
+  printUpstreamOverrideChanges(result);
+  printMaskingPinWarning(result.files);
+  printSummary(result.summary, "analysis summary");
+  const steps = [];
+  const review = await reportReviewPage(config.forkPath, result, "analyze");
+  if (review) steps.push(reviewStep(review));
+  const sync = syncStep(result);
+  if (sync) steps.push(sync);
+  const align = result.alignments && result.upstreamCommit ? await alignmentsStep(config, {
+    ref: result.upstreamCommit.hash,
+    open: result.alignments.open,
+    arriving: result.alignments.arrived
+  }) : void 0;
+  if (align) steps.push(align);
+  printNextSteps(steps);
   return result;
 }
+function syncStep(result) {
+  if (!result.upstreamCommitCount) return void 0;
+  const { behind, diverged, renamed } = result.summary;
+  const changes = [
+    behind > 0 ? `${behind} update` : "",
+    diverged > 0 ? `${diverged} merge` : "",
+    renamed > 0 ? `${renamed} rename` : ""
+  ].filter(Boolean);
+  return {
+    label: "upgrade",
+    line: "pnpm cella upgrade",
+    details: [
+      colors_default.dim(
+        `commits on a fresh branch, a rerun opens the PR \xB7 ${changes.length > 0 ? changes.join(", ") : "no file changes"}`
+      )
+    ]
+  };
+}
 
 // src/services/audit.ts
 import { readFileSync as readFileSync4 } from "fs";
-import { basename as basename4, join as join13, relative as relative3 } from "path";
+import { basename as basename5, join as join13, relative as relative3 } from "path";
 import { checkbox, Separator } from "@inquirer/prompts";
 
 // src/utils/audit-utils.ts
@@ -2980,14 +3541,14 @@ function formatDependents(dependents) {
 
 // src/utils/local-tools.ts
 import { execFile as execFile3 } from "child_process";
-import { existsSync as existsSync7, realpathSync as realpathSync2 } from "fs";
+import { existsSync as existsSync8, realpathSync as realpathSync2 } from "fs";
 import { tmpdir } from "os";
-import { delimiter, dirname as dirname6, join as join11, sep as sep2 } from "path";
+import { delimiter, dirname as dirname7, join as join11, sep as sep2 } from "path";
 import { promisify as promisify3 } from "util";
 
 // src/utils/runtimes.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { basename as basename3, dirname as dirname5, join as join10 } from "path";
+import { basename as basename4, dirname as dirname6, join as join10 } from "path";
 var DAY = 24 * 60 * 60 * 1e3;
 var FROZEN_AFTER = 180 * DAY;
 var RECENT_PUSH = 30 * DAY;
@@ -2995,7 +3556,7 @@ var EXACT_VERSION = /^\d+\.\d+\.\d+$/;
 var FROM_LINE = /^\s*FROM\s+(?:--platform=\S+\s+)?(\S+)(?:\s+AS\s+(\S+))?\s*$/i;
 var NODE_ARG_TAG = /^(?:docker\.io\/)?(?:library\/)?node:\$\{?\w+\}?([\w.-]*)$/;
 var MINOR_TAG = /^(\d+(?:\.\d+){1,2})(-[\w.-]+)?$/;
-var isDockerfile = (path) => /(^|\.)Dockerfile$|^Dockerfile\./i.test(basename3(path));
+var isDockerfile = (path) => /(^|\.)Dockerfile$|^Dockerfile\./i.test(basename4(path));
 function parseDockerfile(file, content) {
   const images = [];
   const nodeImageSuffixes = [];
@@ -3233,7 +3794,7 @@ async function missingNodeImages(version, suffixes) {
   return missing.flat();
 }
 function pinLocation(file) {
-  const dir = dirname5(file);
+  const dir = dirname6(file);
   return dir === "." ? file : dir;
 }
 
@@ -3357,7 +3918,7 @@ var execFileAsync3 = promisify3(execFile3);
 function findOnPath(name, skip = []) {
   for (const dir of (getEnv("PATH") ?? "").split(delimiter)) {
     if (!dir || skip.includes(dir) || dir.endsWith(`node_modules${sep2}.bin`)) continue;
-    if (existsSync7(join11(dir, name))) return join11(dir, name);
+    if (existsSync8(join11(dir, name))) return join11(dir, name);
   }
   return null;
 }
@@ -3385,7 +3946,7 @@ async function readNode(now) {
 }
 async function readPnpm(cwd) {
   const running = getEnv("npm_execpath");
-  const file = findOnPath("pnpm", running ? [dirname6(running)] : []);
+  const file = findOnPath("pnpm", running ? [dirname7(running)] : []);
   const version = file && await versionOf(file, tmpdir());
   if (!file || !version) return null;
   const [published, advisories] = await Promise.all([fetchPublishTimes("pnpm", cwd), fetchPnpmAdvisories(version)]);
@@ -3556,14 +4117,14 @@ function writeAuditSettings(content, next) {
 
 // src/services/audit-security.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { cpSync, existsSync as existsSync8, mkdirSync as mkdirSync2, mkdtempSync, readFileSync as readFileSync3, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { cpSync, existsSync as existsSync9, mkdirSync as mkdirSync2, mkdtempSync, readFileSync as readFileSync3, rmSync as rmSync2, writeFileSync as writeFileSync2 } from "fs";
 import { tmpdir as tmpdir2 } from "os";
-import { dirname as dirname7, join as join12, relative as relative2 } from "path";
+import { dirname as dirname8, join as join12, relative as relative2 } from "path";
 import { confirm, select as select2 } from "@inquirer/prompts";
 var WORKSPACE_FILE = "pnpm-workspace.yaml";
 var LOCK_FILE = "pnpm-lock.yaml";
 var RESOLUTION_FILES = ["package.json", LOCK_FILE, ".npmrc", ".pnpmfile.cjs"];
-var readOr = (path, fallback = "") => existsSync8(path) ? readFileSync3(path, "utf8") : fallback;
+var readOr = (path, fallback = "") => existsSync9(path) ? readFileSync3(path, "utf8") : fallback;
 var count2 = (n, noun, plural2 = `${noun}s`) => `${n} ${n === 1 ? noun : plural2}`;
 var isBreaking = (item) => item.remedy.kind !== "none" && item.remedy.breaking;
 var needsDecision = (item) => item.standing === "new" && (item.remedy.kind !== "override" || item.remedy.breaking || item.direct);
@@ -3577,8 +4138,8 @@ async function createStaging(forkPath, workspaceYaml) {
     ...projects.map((project) => join12(relative2(forkPath, project.path), "package.json"))
   ];
   for (const file of new Set(files)) {
-    if (file.startsWith("..") || !existsSync8(join12(forkPath, file))) continue;
-    mkdirSync2(dirname7(join12(staging, file)), { recursive: true });
+    if (file.startsWith("..") || !existsSync9(join12(forkPath, file))) continue;
+    mkdirSync2(dirname8(join12(staging, file)), { recursive: true });
     cpSync(join12(forkPath, file), join12(staging, file));
   }
   return staging;
@@ -3821,7 +4382,7 @@ async function runSecurityPass(forkPath, options) {
     return true;
   } finally {
     spinner.stop();
-    rmSync(staging, { recursive: true, force: true });
+    rmSync2(staging, { recursive: true, force: true });
   }
 }
 function printOpen(modules) {
@@ -4023,7 +4584,7 @@ function printOutdatedResults(rows, forkPath) {
   const dependentMap = /* @__PURE__ */ new Map();
   for (const pkg of rows) {
     for (const { name, location } of pkg.dependentPackages) {
-      const dependentName = name || basename4(location);
+      const dependentName = name || basename5(location);
       const existing = dependentMap.get(dependentName);
       if (existing) {
         existing.count++;
@@ -4219,8 +4780,8 @@ import {
 import { select as select3 } from "@inquirer/prompts";
 
 // src/services/contrib-core.ts
-import { rmSync as rmSync2 } from "fs";
-import { dirname as dirname8, join as join14, resolve as resolve4 } from "path";
+import { rmSync as rmSync3 } from "fs";
+import { dirname as dirname9, join as join14, resolve as resolve4 } from "path";
 async function listFilesAtRef(repoPath, ref) {
   const raw = await git(["ls-tree", "-r", "--name-only", ref], repoPath);
   return new Set(raw.split("\n").filter(Boolean));
@@ -4236,10 +4797,10 @@ async function detectContributableFiles(repoPath, baseRef, forkRef, config, fork
   const baseFiles = await listFilesAtRef(repoPath, baseRef);
   const baseDirs = /* @__PURE__ */ new Set(["."]);
   for (const f of baseFiles) {
-    let dir = dirname8(f);
+    let dir = dirname9(f);
     while (dir !== ".") {
       baseDirs.add(dir);
-      dir = dirname8(dir);
+      dir = dirname9(dir);
     }
   }
   const files = [];
@@ -4252,7 +4813,7 @@ async function detectContributableFiles(repoPath, baseRef, forkRef, config, fork
     if (inCella && !inFork) {
       kind = "deleted";
     } else if (!inCella && inFork) {
-      if (!baseDirs.has(dirname8(file.path))) continue;
+      if (!baseDirs.has(dirname9(file.path))) continue;
       kind = "created";
     } else {
       kind = "modified";
@@ -4306,25 +4867,25 @@ ${commitBody}`;
     await git(["update-ref", `refs/heads/${branch}`, commitHash], repoPath);
     return { branch, appliedFiles };
   } finally {
-    rmSync2(tmpIndex, { force: true });
+    rmSync3(tmpIndex, { force: true });
   }
 }
 
 // src/services/fork-utils.ts
-import { existsSync as existsSync9 } from "fs";
-import { dirname as dirname9, resolve as resolve5 } from "path";
+import { existsSync as existsSync10 } from "fs";
+import { dirname as dirname10, resolve as resolve5 } from "path";
 async function resolveForkBasePath(repoPath) {
   const commonDir = await git(["rev-parse", "--git-common-dir"], repoPath, { ignoreErrors: true });
-  return commonDir ? dirname9(resolve5(repoPath, commonDir)) : repoPath;
+  return commonDir ? dirname10(resolve5(repoPath, commonDir)) : repoPath;
 }
 function validateForkPath(fork, basePath, requireConfig = false) {
   const resolvedPath = resolve5(basePath, fork.localPath);
   if (!resolvedPath.startsWith(resolve5(basePath, ".."))) {
     return { fork, resolvedPath, valid: false, error: "path resolves outside parent directory" };
   }
-  if (!existsSync9(resolvedPath)) return { fork, resolvedPath, valid: false, error: "path does not exist" };
-  if (!existsSync9(`${resolvedPath}/.git`)) return { fork, resolvedPath, valid: false, error: "not a git repository" };
-  if (requireConfig && !existsSync9(`${resolvedPath}/${CONFIG_FILE}`)) {
+  if (!existsSync10(resolvedPath)) return { fork, resolvedPath, valid: false, error: "path does not exist" };
+  if (!existsSync10(`${resolvedPath}/.git`)) return { fork, resolvedPath, valid: false, error: "not a git repository" };
+  if (requireConfig && !existsSync10(`${resolvedPath}/${CONFIG_FILE}`)) {
     return { fork, resolvedPath, valid: false, error: `missing ${CONFIG_FILE}` };
   }
   return { fork, resolvedPath, valid: true };
@@ -4630,10 +5191,10 @@ async function runContributions(config) {
 
 // src/services/forks.ts
 import { resolve as resolve6 } from "path";
-import process8 from "process";
+import process10 from "process";
 import { Separator as Separator2, select as select5 } from "@inquirer/prompts";
 
-// src/services/sync.ts
+// src/services/upgrade.ts
 import { spawnSync as spawnSync4 } from "child_process";
 import { select as select4 } from "@inquirer/prompts";
 
@@ -4647,7 +5208,7 @@ function runGh(cwd, args) {
   const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
   return { ok: result.status === 0, output };
 }
-function listOpenSyncPrs(cwd, prefix) {
+function listOpenSyncPrs(cwd, prefixes) {
   const { ok, output } = runGh(cwd, [
     "pr",
     "list",
@@ -4665,7 +5226,29 @@ function listOpenSyncPrs(cwd, prefix) {
   } catch {
     return [];
   }
-  return parsed.filter((pr) => pr.headRefName.startsWith(`${prefix}/`)).sort((a, b) => b.number - a.number);
+  return parsed.filter((pr) => prefixes.some((prefix) => pr.headRefName.startsWith(`${prefix}/`))).sort((a, b) => b.number - a.number);
+}
+function createPr(cwd, repoSlug, pr) {
+  const repo = repoSlug ?? "{owner}/{repo}";
+  const fields = ["title", "head", "base", "body"];
+  const created = runGh(cwd, [
+    "api",
+    `repos/${repo}/pulls`,
+    "-X",
+    "POST",
+    ...fields.flatMap((field) => ["-f", `${field}=${pr[field]}`]),
+    "--jq",
+    ".html_url"
+  ]);
+  if (created.ok) return { ...created, url: created.output || void 0 };
+  const owner = repoSlug ? repoSlug.split("/")[0] : "{owner}";
+  const existing = runGh(cwd, [
+    "api",
+    `repos/${repo}/pulls?state=open&head=${owner}:${pr.head}`,
+    "--jq",
+    ".[0].html_url // empty"
+  ]);
+  return { ...created, url: existing.ok && existing.output ? existing.output : void 0 };
 }
 function mergePrSquash(cwd, ref, options = {}) {
   return runGh(cwd, ["pr", "merge", String(ref), "--squash", ...options.deleteBranch ? ["--delete-branch"] : []]);
@@ -4675,11 +5258,11 @@ function closePr(cwd, ref) {
 }
 
 // src/services/packages.ts
-import { existsSync as existsSync11, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync6, writeFileSync as writeFileSync3 } from "fs";
 import { join as join16 } from "path";
 
 // src/services/package-usage.ts
-import { existsSync as existsSync10, readFileSync as readFileSync5, statSync } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync5, statSync } from "fs";
 import { join as join15 } from "path";
 var MAX_FILE_BYTES = 1024 * 1024;
 function escapeRegExp(value) {
@@ -4720,7 +5303,7 @@ function binNames(forkPath, location, name) {
   const bareName = name.split("/").pop();
   for (const dir of [join15(forkPath, location), forkPath]) {
     const manifest = join15(dir, "node_modules", name, "package.json");
-    if (!existsSync10(manifest)) continue;
+    if (!existsSync11(manifest)) continue;
     try {
       const { bin } = JSON.parse(readFileSync5(manifest, "utf8"));
       if (typeof bin === "string") return [bareName];
@@ -4901,7 +5484,7 @@ function setTopLevelKey(pkg, key, value) {
   Object.assign(pkg, Object.fromEntries(entries));
 }
 function readPackageJson(filePath) {
-  if (!existsSync11(filePath)) return null;
+  if (!existsSync12(filePath)) return null;
   try {
     return JSON.parse(readFileSync6(filePath, "utf8"));
   } catch (error) {
@@ -4941,7 +5524,7 @@ async function syncPackageJson(config, baseRef, usage, relativePath, keysToSync)
   const basePkg = baseRef ? (await readPackageJsonAtRef(forkPath, baseRef, relativePath))?.data : void 0;
   if (!upstream) return { updated: false, changes, kept };
   if (!forkPkg) {
-    const workspaceArrived = relativePath !== "" && existsSync11(join16(forkPath, relativePath));
+    const workspaceArrived = relativePath !== "" && existsSync12(join16(forkPath, relativePath));
     if (basePkg || !workspaceArrived || isIgnored(pkgRelPath, config)) return { updated: false, changes, kept };
     writeFileSync3(pkgPath, upstream.raw.endsWith("\n") ? upstream.raw : `${upstream.raw}
 `, "utf8");
@@ -5013,8 +5596,8 @@ async function syncPackageJson(config, baseRef, usage, relativePath, keysToSync)
   return { updated, changes, kept };
 }
 async function runPackages(config, options = {}) {
-  createSpinner("syncing package.json files...");
-  const keysToSync = config.settings.packageJsonSync || DEFAULT_PACKAGE_JSON_SYNC;
+  createSpinner("merging package.json files...");
+  const keysToSync = config.settings.packageJsonKeys || DEFAULT_PACKAGE_JSON_KEYS;
   const conflictedSet = new Set(options.conflictedFiles ?? []);
   const baseRef = await resolveMergeBase(config.forkPath, config.upstreamRef);
   const usage = baseRef ? await loadForkUsage(config.forkPath, config.upstreamRef, baseRef) : null;
@@ -5027,12 +5610,15 @@ async function runPackages(config, options = {}) {
       skipped.push(pkgRelPath);
       continue;
     }
-    spinnerText(`syncing ${location || "root"}/package.json...`);
+    spinnerText(`merging ${location || "root"}/package.json...`);
     const { updated, changes, kept: kept2 } = await syncPackageJson(config, baseRef, usage, location, keysToSync);
     if (updated || kept2.length > 0) reports.push({ path: pkgRelPath, changes, kept: kept2 });
   }
   const changedCount = reports.filter(({ changes }) => changes.length > 0).length;
-  spinnerSuccess("package sync complete", `${plural(changedCount, "package.json was", "package.jsons were")} changed`);
+  spinnerSuccess(
+    "package.json merge complete",
+    `${plural(changedCount, "package.json was", "package.jsons were")} changed`
+  );
   for (const { path, changes } of reports) {
     if (changes.length === 0) continue;
     console.info(`  ${path}`);
@@ -5042,7 +5628,7 @@ async function runPackages(config, options = {}) {
   const them = kept.length === 1 ? "it" : "them";
   printWarnList(`kept ${plural(kept.length, "entry", "entries")} upstream dropped, the fork still uses ${them}:`, kept);
   printWarnList(
-    `skipped ${skipped.length} conflicted package.json file(s): resolve the conflicts, commit the merge, then rerun \`pnpm cella sync\`:`,
+    `skipped ${skipped.length} conflicted package.json file(s): resolve the conflicts, commit the merge, then rerun \`pnpm cella upgrade\`:`,
     skipped
   );
 }
@@ -5053,7 +5639,7 @@ function printWarnList(header, entries) {
   for (const entry of entries) console.info(`    ${colors_default.dim("\u2192")} ${entry}`);
 }
 
-// src/services/sync.ts
+// src/services/upgrade.ts
 async function resolveCycleStart(forkPath, base, currentBranch) {
   if (!await branchExists(forkPath, base)) {
     await fetchRemote(forkPath, "origin").catch(() => {
@@ -5069,7 +5655,7 @@ async function resolveCycleStart(forkPath, base, currentBranch) {
   if (ahead > 0 && behind > 0) {
     throw new Error(
       `'${base}' has diverged from '${upstream}' (${ahead} ahead, ${behind} behind).
-Reconcile '${base}' with '${upstream}' first (e.g. rebase or reset it), then re-run sync.`
+Reconcile '${base}' with '${upstream}' first (e.g. rebase or reset it), then re-run the upgrade.`
     );
   }
   if (behind > 0) {
@@ -5098,7 +5684,7 @@ async function setupTemporarySyncBranch(config) {
   console.info(colors_default.dim(`updating '${base}'...`));
   const startPoint = await resolveCycleStart(forkPath, base, startBranch);
   const temporaryBranch = buildTemporarySyncBranch();
-  console.info(colors_default.dim(`creating temporary sync branch '${temporaryBranch}' from '${startPoint}'...`));
+  console.info(colors_default.dim(`creating temporary upgrade branch '${temporaryBranch}' from '${startPoint}'...`));
   console.info();
   await createBranchFrom(forkPath, temporaryBranch, startPoint);
   return { temporaryBranch, base, startBranch, startCommit };
@@ -5122,7 +5708,7 @@ async function returnToBase(forkPath, base) {
   return `back on '${base}'`;
 }
 async function runSync(config, options) {
-  createSpinner("starting sync...");
+  createSpinner("starting upgrade...");
   let result;
   try {
     result = await runEngineWithSpinner(config, true);
@@ -5137,7 +5723,7 @@ async function runSync(config, options) {
   if (result.success) {
     spinnerSuccess();
   } else {
-    spinnerFail("sync completed with conflicts");
+    spinnerFail("upgrade merge completed with conflicts");
   }
   printEngineReports(result, "merge summary");
   if (config.unpinned) {
@@ -5147,49 +5733,89 @@ async function runSync(config, options) {
   const staged = result.files.some((file) => SYNC_APPLIED_STATUSES.includes(file.status));
   const stagedBranch = options?.stagedBranch && result.conflicts.length === 0 && staged ? options.stagedBranch : void 0;
   printSyncComplete(result, { stagedBranch });
-  await reportReviewPage(config.forkPath, result, "sync");
-  await printMigrationNotesLine(config, result);
-  return result;
+  const reviewPage = await reportReviewPage(config.forkPath, result, "upgrade");
+  return { ...result, reviewPage };
+}
+var CONFLICTS_LISTED = 10;
+async function syncAlignmentsStep(config, run) {
+  if (run?.alignments && run.upstreamCommit) {
+    const { open, arrived } = run.alignments;
+    return alignmentsStep(config, { ref: run.upstreamCommit.hash, open, arrived });
+  }
+  const view = await readOpenAlignments(config);
+  return view ? alignmentsStep(config, view) : void 0;
+}
+function syncReviewStep(config, run) {
+  const page = run ? run.reviewPage : existingSyncReviewPage(config.forkPath);
+  return page ? reviewStep(page) : void 0;
+}
+async function conflictSteps(config, conflicts, run) {
+  const listed = conflicts.slice(0, CONFLICTS_LISTED).map((file) => colors_default.dim(file));
+  if (conflicts.length > CONFLICTS_LISTED) listed.push(colors_default.dim(`+ ${conflicts.length - CONFLICTS_LISTED} more`));
+  const steps = [
+    {
+      label: "resolve",
+      line: `${plural(conflicts.length, "conflict")} in your editor, then stage them`,
+      details: listed
+    },
+    {
+      label: "finish",
+      line: "pnpm cella upgrade",
+      details: [
+        colors_default.dim("commits the upgrade and stops for drift triage"),
+        colors_default.dim("let the rerun commit: a manual `git commit` records a merge commit that bloats the PR")
+      ]
+    },
+    syncReviewStep(config, run),
+    await syncAlignmentsStep(config, run)
+  ];
+  return steps.filter((step) => !!step);
 }
-var SYNC_PR_TITLE = "chore: sync upstream cella";
+var UPGRADE_PR_TITLE = "chore: upgrade cella";
 async function buildSyncCommitMessage(forkPath, upstreamRef) {
   const shortSha = await getShortSha(forkPath, upstreamRef).catch(() => "");
-  if (!shortSha) return SYNC_PR_TITLE;
+  if (!shortSha) return UPGRADE_PR_TITLE;
   const manifest = await readSyncManifest(forkPath);
   const version = manifest?.upstream.release ?? await readPackageVersionAtRef(forkPath, upstreamRef).catch(() => null);
-  return version ? `${SYNC_PR_TITLE} v${version.replace(/^v/, "")} (${shortSha})` : `${SYNC_PR_TITLE} ${shortSha}`;
+  return version ? `${UPGRADE_PR_TITLE} to v${version.replace(/^v/, "")} (${shortSha})` : `${UPGRADE_PR_TITLE} to ${shortSha}`;
 }
 function qualifyPrRefs(subject, repoSlug) {
   if (!repoSlug) return subject;
   return subject.replace(/(^|[^\w/])#(\d+)\b/g, `$1${repoSlug}#$2`);
 }
 function buildSyncPrBody(input) {
-  const { repoSlug, version, fromSha, toSha, commits, totalCount, notes } = input;
+  const { repoSlug, version, fromSha, toSha, commits, totalCount, alignments } = input;
   const githubUrl = repoSlug ? `https://github.com/${repoSlug}` : void 0;
   const short = (sha) => sha.slice(0, 7);
   const commitRef = (sha) => githubUrl ? `[\`${short(sha)}\`](${githubUrl}/commit/${sha})` : `\`${short(sha)}\``;
   const upstreamName = githubUrl ? `[${repoSlug}](${githubUrl})` : "cella";
   const versionSuffix = version ? ` (v${version.replace(/^v/, "")})` : "";
-  const lines = [`Syncs upstream ${upstreamName} to ${commitRef(toSha)}${versionSuffix}.`];
+  const lines = [`Upgrades ${upstreamName} to ${commitRef(toSha)}${versionSuffix}.`];
   if (totalCount > 0 && fromSha) {
     const compare = githubUrl ? ` ([compare](${githubUrl}/compare/${short(fromSha)}...${short(toSha)}))` : "";
-    lines.push("", `**${totalCount} upstream commit${totalCount === 1 ? "" : "s"} since last sync**${compare}:`, "");
+    lines.push(
+      "",
+      `**${totalCount} upstream commit${totalCount === 1 ? "" : "s"} since the last upgrade**${compare}:`,
+      ""
+    );
     if (totalCount > commits.length) lines.push(`- \u2026${totalCount - commits.length} earlier commit(s) not shown`);
     for (const commit of commits) {
       lines.push(`- ${commitRef(commit.hash)} ${qualifyPrRefs(commit.message, repoSlug)}`);
     }
   }
-  if (notes && notes.total > 0) {
-    const { total, open } = notes;
-    if (open.length === 0) lines.push("", `**Migration notes**: all ${total} handled.`);
+  if (alignments && alignments.total > 0) {
+    const { total, open } = alignments;
+    if (open.length === 0) lines.push("", `**Alignments**: all ${total} handled.`);
     else {
       lines.push(
         "",
-        `**Migration notes**: ${Math.max(0, total - open.length)} of ${total} handled, open (\`pnpm cella migrate\`):`,
+        `**Alignments**: ${Math.max(0, total - open.length)} of ${total} handled, open (\`pnpm cella align\`):`,
         ""
       );
-      for (const note of open)
-        lines.push(`- ${note.url ? `[${note.title}](${note.url})` : note.title} (\`${note.id}\`)`);
+      for (const alignment of open)
+        lines.push(
+          `- ${alignment.url ? `[${alignment.title}](${alignment.url})` : alignment.title} (\`${alignment.id}\`)`
+        );
     }
   }
   return `${lines.join("\n")}
@@ -5203,22 +5829,30 @@ async function buildSyncPrBodyForBranch(forkPath, base) {
   const version = manifest.upstream.release ?? await readPackageVersionAtRef(forkPath, toSha).catch(() => null);
   const totalCount = fromSha ? await countCommitsBetween(forkPath, fromSha, toSha).catch(() => 0) : 0;
   const commits = fromSha && totalCount > 0 ? await listCommitsBetween(forkPath, fromSha, toSha, COMMIT_LIST_MAX) : [];
-  const notes = await readPrBodyNotes(forkPath, toSha, manifest.upstream.repo).catch(() => void 0);
-  return buildSyncPrBody({ repoSlug: manifest.upstream.repo, version, fromSha, toSha, commits, totalCount, notes });
+  const alignments = await readPrBodyAlignments(forkPath, toSha, manifest.upstream.repo).catch(() => void 0);
+  return buildSyncPrBody({
+    repoSlug: manifest.upstream.repo,
+    version,
+    fromSha,
+    toSha,
+    commits,
+    totalCount,
+    alignments
+  });
 }
-async function readPrBodyNotes(forkPath, toSha, repoSlug) {
+async function readPrBodyAlignments(forkPath, toSha, repoSlug) {
   const githubUrl = repoSlug ? `https://github.com/${repoSlug}` : void 0;
-  const [ids, pending] = await Promise.all([listNoteIds(forkPath, toSha), readPending(forkPath)]);
+  const [ids, pending] = await Promise.all([listAlignmentIds(forkPath, toSha), readPending(forkPath)]);
   const open = await Promise.all(
     pending.map(async (id) => ({
       id,
-      title: (await readNote(forkPath, toSha, id))?.title ?? id,
-      url: noteUrl(githubUrl, toSha, id)
+      title: (await readAlignment(forkPath, toSha, id))?.title ?? id,
+      url: alignmentUrl(githubUrl, toSha, id)
     }))
   );
   return { total: ids.length, open };
 }
-function printPrCreateStep(branch, base, title = SYNC_PR_TITLE) {
+function printPrCreateStep(branch, base, title = UPGRADE_PR_TITLE) {
   console.info(colors_default.dim(`  gh pr create --base ${base} --head ${branch} --title "${title}" --fill`));
 }
 async function flattenSyncBranch(forkPath, branch, base) {
@@ -5242,7 +5876,7 @@ async function shipSyncBranch(config, branch) {
   let prUrl;
   let prOpened = false;
   const upstreamCommit = (await readSyncManifest(forkPath))?.upstream.commit;
-  const prTitle = upstreamCommit ? await buildSyncCommitMessage(forkPath, upstreamCommit) : SYNC_PR_TITLE;
+  const prTitle = upstreamCommit ? await buildSyncCommitMessage(forkPath, upstreamCommit) : UPGRADE_PR_TITLE;
   console.info(colors_default.dim(`pushing '${branch}' to origin...`));
   try {
     await pushBranch(forkPath, "origin", branch, { forceWithLease: flattened });
@@ -5254,16 +5888,11 @@ async function shipSyncBranch(config, branch) {
   }
   if (ghAvailable()) {
     console.info(colors_default.dim("opening a pull request..."));
-    const prBody = await buildSyncPrBodyForBranch(forkPath, cutBase);
-    const bodyArgs = prBody ? ["--body", prBody] : ["--fill"];
-    const pr = spawnSync4("gh", ["pr", "create", "--base", base, "--head", branch, "--title", prTitle, ...bodyArgs], {
-      cwd: forkPath,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-    prUrl = `${pr.stdout ?? ""}
-${pr.stderr ?? ""}`.match(/https?:\/\/\S+/)?.[0];
-    prOpened = pr.status === 0;
+    const prBody = await buildSyncPrBodyForBranch(forkPath, cutBase) ?? "";
+    const repoSlug = (await readOriginGitHubUrl(forkPath))?.replace("https://github.com/", "") ?? null;
+    const pr = createPr(forkPath, repoSlug, { base, head: branch, title: prTitle, body: prBody });
+    prUrl = pr.url;
+    prOpened = pr.ok;
     if (!prOpened) {
       console.info(colors_default.yellow("could not open the PR automatically (it may already exist). open it with:"));
       if (prUrl) console.info(colors_default.dim(`  ${prUrl}`));
@@ -5276,13 +5905,21 @@ ${pr.stderr ?? ""}`.match(/https?:\/\/\S+/)?.[0];
   const position = await returnToBase(forkPath, base);
   console.info();
   if (prUrl) {
-    console.info(`${checkMark} sync pull request ${prOpened ? "opened" : "ready"}`);
+    console.info(`${checkMark} upgrade pull request ${prOpened ? "opened" : "ready"}`);
     console.info(colors_default.dim(`  ${prUrl} \xB7 branch pushed, ${position}`));
   } else {
-    console.info(`${checkMark} sync branch pushed`);
+    console.info(`${checkMark} upgrade branch pushed`);
     console.info(colors_default.dim(`  '${branch}' is on origin, ${position}`));
   }
-  await printMigrationNotesLine(config);
+  const steps = [
+    prUrl ? {
+      label: "merge",
+      line: hyperlink(colors_default.cyan(prUrl), prUrl),
+      details: [colors_default.dim(`squash-merge it into '${base}'; the next upgrade offers to while it is open`)]
+    } : void 0,
+    await syncAlignmentsStep(config)
+  ];
+  printNextSteps(steps.filter((step) => !!step));
 }
 function finalizeWorkspace(forkPath) {
   for (const args of [["install"], ["check"]]) {
@@ -5318,43 +5955,56 @@ async function runSyncCycle(config) {
     }
     throw error;
   }
-  if (config.settings.syncWithPackages !== false) {
+  if (config.settings.mergePackageJson !== false) {
     await runPackages(config, { conflictedFiles: result.conflicts });
   }
-  if (result.conflicts.length > 0) return { status: "conflicts", branch };
+  if (result.conflicts.length > 0) return { status: "conflicts", branch, result };
   if (!await mergeInProgress(forkPath)) {
     await discardTemporarySyncBranch(forkPath, branch);
-    return { status: "noop" };
+    return { status: "noop", result };
   }
-  return { status: "staged", branch };
+  return { status: "staged", branch, result };
 }
-async function commitSyncMerge(config, branch) {
+async function commitSyncMerge(config, branch, run) {
   const { forkPath } = config;
   const conflicts = await getConflictedFiles(forkPath);
   console.info();
   if (conflicts.length > 0) {
-    console.info(colors_default.yellow(`${conflicts.length} file(s) still conflict on '${branch}':`));
-    for (const file of conflicts) console.info(colors_default.dim(`  ${file}`));
-    console.info(colors_default.dim("resolve and stage them, then re-run `pnpm cella sync` to finish (it commits for you)."));
+    printStep("conflicts", `${plural(conflicts.length, "file")} still conflict on '${branch}'`, warningMark);
+    printNextSteps(await conflictSteps(config, conflicts, run));
     return;
   }
   await stageAll(forkPath);
   if (!finalizeWorkspace(forkPath)) {
     console.info();
-    console.info(
-      colors_default.yellow("`pnpm install`/`pnpm check` failed. fix the issues, then re-run `pnpm cella sync` to finish.")
-    );
+    printStep("checks", "`pnpm install` or `pnpm check` failed", warningMark);
+    printNextSteps([
+      { label: "fix", line: "what failed above", details: [colors_default.dim(`the merge stays staged on '${branch}'`)] },
+      {
+        label: "finish",
+        line: "pnpm cella upgrade",
+        details: [colors_default.dim("commits the upgrade and stops for drift triage")]
+      }
+    ]);
     return;
   }
   const message = await buildSyncCommitMessage(forkPath, "MERGE_HEAD");
   await stageAll(forkPath);
   await commitSquash(forkPath, message);
   console.info();
-  console.info(colors_default.green(`committed the sync on '${branch}' as '${message}'.`));
-  console.info(colors_default.dim(`staying on '${branch}' without pushing.`));
-  console.info(colors_default.dim("  run drift triage (`pnpm cella analyze`), commit any follow-ups, then:"));
-  console.info(colors_default.dim("  pnpm cella sync   (pushes the branch and opens the PR)"));
-  await printMigrationNotesLine(config);
+  printStep("committed", `${message}
+${colors_default.dim(`on '${branch}', not pushed`)}`);
+  const steps = [
+    syncReviewStep(config, run),
+    {
+      label: "triage",
+      line: "pnpm cella analyze",
+      details: [colors_default.dim("drift triage: commit any follow-ups on this branch")]
+    },
+    await syncAlignmentsStep(config, run),
+    { label: "ship", line: "pnpm cella upgrade", details: [colors_default.dim("pushes the branch and opens the squash-merge PR")] }
+  ];
+  printNextSteps(steps.filter((step) => !!step));
 }
 async function mergeOpenSyncPrs(config, open) {
   const { forkPath, settings } = config;
@@ -5365,7 +6015,7 @@ async function mergeOpenSyncPrs(config, open) {
   const merged = mergePrSquash(forkPath, newest.number, { deleteBranch: true });
   if (!merged.ok) {
     console.info();
-    console.info(colors_default.yellow(`could not merge #${newest.number}: resolve it first, then re-run \`pnpm cella sync\`:`));
+    console.info(colors_default.yellow(`could not merge #${newest.number}: resolve it first, then re-run \`pnpm cella upgrade\`:`));
     if (merged.output) console.info(colors_default.dim(merged.output.replace(/^/gm, "  ")));
     console.info(colors_default.dim(`  ${newest.url}`));
     return "cancel";
@@ -5382,25 +6032,27 @@ async function mergeOpenSyncPrs(config, open) {
 async function guardAgainstOpenSyncPr(config) {
   const { forkPath } = config;
   if (!ghAvailable() || !process.stdout.isTTY) return "continue";
-  const open = listOpenSyncPrs(forkPath, DEFAULT_SYNC_PREFIX);
+  const open = listOpenSyncPrs(forkPath, TEMPORARY_BRANCH_PREFIXES);
   if (open.length === 0) return "continue";
   const many = open.length > 1;
   console.info();
   console.info(
-    `${warningMark} ${colors_default.yellow(`${many ? `${open.length} earlier sync PRs are` : "an earlier sync PR is"} still open and unmerged:`)}`
+    `${warningMark} ${colors_default.yellow(`${many ? `${open.length} earlier upgrade PRs are` : "an earlier upgrade PR is"} still open and unmerged:`)}`
   );
   for (const pr of open) {
     console.info(colors_default.dim(`  #${pr.number}  ${pr.title}`));
     console.info(colors_default.dim(`         ${pr.url}`));
   }
-  console.info(colors_default.dim(`  starting a new sync now produces a PR that re-includes ${many ? "these" : "those"} changes.`));
+  console.info(
+    colors_default.dim(`  starting a new upgrade now produces a PR that re-includes ${many ? "these" : "those"} changes.`)
+  );
   console.info();
   const choice = await select4({
     message: "how do you want to proceed?",
     choices: [
       {
         value: "merge",
-        name: `merge ${many ? "them" : `#${open[0].number}`} first, then sync   ${colors_default.dim("(recommended)")}`
+        name: `merge ${many ? "them" : `#${open[0].number}`} first, then upgrade   ${colors_default.dim("(recommended)")}`
       },
       { value: "continue", name: `continue anyway   ${colors_default.dim("(new PR will re-include the unmerged changes)")}` },
       { value: "cancel", name: colors_default.red("cancel") }
@@ -5411,7 +6063,7 @@ async function guardAgainstOpenSyncPr(config) {
   if (choice === "continue") return "continue";
   return mergeOpenSyncPrs(config, open);
 }
-async function runSyncCommand(config) {
+async function runUpgradeCommand(config) {
   const { forkPath } = config;
   const currentBranch = await getCurrentBranch(forkPath);
   const onSyncBranch = isTemporarySyncBranch(currentBranch);
@@ -5424,7 +6076,7 @@ async function runSyncCommand(config) {
       console.info();
       console.info(
         colors_default.yellow(
-          `sync branch '${currentBranch}' has uncommitted changes.
+          `upgrade branch '${currentBranch}' has uncommitted changes.
 commit them first (\`git commit --amend --no-edit\` or a new commit).`
         )
       );
@@ -5434,29 +6086,30 @@ commit them first (\`git commit --amend --no-edit\` or a new commit).`
     return;
   }
   if (!await isClean(forkPath)) {
-    throw new Error("working directory has uncommitted changes. please commit or stash before syncing.");
+    throw new Error("working directory has uncommitted changes. please commit or stash before upgrading.");
   }
   if (await guardAgainstOpenSyncPr(config) === "cancel") return;
   const outcome = await runSyncCycle(config);
-  console.info();
   if (outcome.status === "noop") {
+    console.info();
     if (outcome.behind) {
-      console.info(colors_default.green("nothing to sync: the last sync already went past this upstream point."));
+      console.info(colors_default.green("nothing to upgrade: the last upgrade already went past this upstream point."));
       for (const line of outcome.behind.split("\n")) console.info(colors_default.dim(`  ${line}`));
     } else {
-      console.info(colors_default.green("already up to date with upstream, nothing to sync."));
+      console.info(colors_default.green("already up to date with upstream, nothing to upgrade."));
     }
+    const align = await syncAlignmentsStep(config, outcome.result);
+    if (align) printNextSteps([align]);
     return;
   }
   const { temporaryBranch } = outcome.branch;
   if (outcome.status === "conflicts") {
-    console.info(`${warningMark} ${colors_default.yellow(`conflicts on '${temporaryBranch}'. Resolve and stage them, then:`)}`);
-    console.info(colors_default.dim("  pnpm cella sync"));
-    console.info(colors_default.dim("  rerun commits the sync and stops for drift triage; a further rerun ships (push + PR)."));
-    console.info(colors_default.dim("  let the rerun commit: a manual `git commit` records a merge commit that bloats the PR."));
+    const conflicts = await getConflictedFiles(forkPath);
+    printStep("conflicts", `${plural(conflicts.length, "file")} on '${temporaryBranch}'`, warningMark);
+    printNextSteps(await conflictSteps(config, conflicts, outcome.result));
     return;
   }
-  await commitSyncMerge(config, temporaryBranch);
+  await commitSyncMerge(config, temporaryBranch, outcome.result);
 }
 
 // src/services/forks.ts
@@ -5481,7 +6134,7 @@ function formatForkChoice(name, status) {
     syncPart = colors_default.dim(`${status.lastSync.date}`);
     if (msg) syncPart += colors_default.dim(` '${msg}'`);
   } else {
-    syncPart = colors_default.dim("never synced");
+    syncPart = colors_default.dim("never upgraded");
   }
   const dirtyPart = status.dirty > 0 ? colors_default.yellow(`${status.dirty} uncommitted`) : "";
   const parts = [name, colors_default.dim(`[${status.branch}]`), syncPart];
@@ -5513,15 +6166,15 @@ async function buildForkChoices(forks, basePath) {
 }
 async function syncFork(config, fork, forkPath) {
   console.info();
-  console.info(colors_default.cyan(`syncing to ${fork.name}...`));
+  console.info(colors_default.cyan(`upgrading ${fork.name}...`));
   console.info(colors_default.dim(`path: ${forkPath}`));
   console.info();
   const forkConfig = await loadConfig(forkPath);
-  await runSyncCommand({
+  await runUpgradeCommand({
     ...forkConfig,
     forkPath,
     upstreamRef: resolveUpstream(forkConfig.settings).branchRef,
-    service: "sync",
+    service: "upgrade",
     list: false,
     json: false,
     verbose: false,
@@ -5548,12 +6201,12 @@ async function runForks(config) {
     const choices = await buildForkChoices(forks, forkBasePath);
     const forkChoices = [...choices, new Separator2(MENU_DIVIDER), { value: "_exit", name: colors_default.dim("exit") }];
     const selectedPath = await select5({
-      message: "select fork to sync:",
+      message: "select fork to upgrade:",
       choices: forkChoices,
       loop: false
     });
     if (selectedPath === "_exit") {
-      process8.exit(0);
+      process10.exit(0);
     }
     const resolvedForkPath = resolve6(forkBasePath, selectedPath);
     const selectedFork = forks.find((f) => f.localPath === selectedPath);
@@ -5571,7 +6224,7 @@ import { readFile as readFile3 } from "fs/promises";
 import { join as join18 } from "path";
 
 // src/utils/coverage-utils.ts
-import { existsSync as existsSync12, readFileSync as readFileSync7, statSync as statSync2 } from "fs";
+import { existsSync as existsSync13, readFileSync as readFileSync7, statSync as statSync2 } from "fs";
 import { join as join17, relative as relative4, sep as sep3 } from "path";
 var STALE_THRESHOLD_MS = 7 * 24 * 60 * 60 * 1e3;
 function colorPct(pct) {
@@ -5594,7 +6247,7 @@ function printCoverageSummary(forkPath) {
   let summary;
   let mtimeMs = 0;
   let problem = "no coverage data found";
-  if (existsSync12(file)) {
+  if (existsSync13(file)) {
     try {
       mtimeMs = statSync2(file).mtimeMs;
       summary = JSON.parse(readFileSync7(file, "utf8"));
@@ -5994,26 +6647,26 @@ function getForkPath() {
   const envPath = getEnv("CELLA_FORK_PATH");
   if (envPath) {
     const resolved = resolve7(envPath);
-    if (!existsSync13(resolved) || !statSync3(resolved).isDirectory()) {
+    if (!existsSync14(resolved) || !statSync3(resolved).isDirectory()) {
       throw new Error(`CELLA_FORK_PATH is not a valid directory: ${resolved}`);
     }
     return resolved;
   }
-  let cwd = process9.cwd();
+  let cwd = process11.cwd();
   if (cwd.endsWith("/cli/cella") || cwd.endsWith("\\cli\\cella")) {
     cwd = resolve7(cwd, "../..");
   }
   return cwd;
 }
 function preflight(forkPath) {
-  if (!existsSync13(join19(forkPath, ".git"))) {
+  if (!existsSync14(join19(forkPath, ".git"))) {
     throw new Error(`not a git repository: ${forkPath}`);
   }
 }
 var services = {
   analyze: runAnalyze,
-  sync: runSyncCommand,
-  migrate: runMigrate,
+  upgrade: runUpgradeCommand,
+  align: runAlign,
   audit: runAudit,
   forks: runForks,
   contributions: runContributions,
@@ -6024,7 +6677,7 @@ var services = {
   }
 };
 function isHelpOrVersionRequest() {
-  return process9.argv.slice(2).some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v") || process9.argv[2] === "help";
+  return process11.argv.slice(2).some((arg) => arg === "--help" || arg === "-h" || arg === "--version" || arg === "-v") || process11.argv[2] === "help";
 }
 async function main() {
   try {
@@ -6043,7 +6696,7 @@ async function main() {
   } catch (error) {
     console.error();
     console.error(`${colors_default.red("\u2717")} ${errorMessage(error)}`);
-    process9.exit(1);
+    process11.exit(1);
   }
 }
 main();