youiyoux 0.1.9 → 0.1.10

package/dist/chunks/{chunk-F33PKGES.js → chunk-3RP664IP.js}

@@ -4,7 +4,7 @@ import {
   loadPackage,
   readTryIndex,
   send
-} from "./chunk-DCBF7QQY.js";
+} from "./chunk-T3KNPVQG.js";
 import {
   writeFileAtomic
 } from "./chunk-DWYDHVLZ.js";

package/dist/chunks/{chunk-E5OHZJBS.js → chunk-75DBKEAH.js}

@@ -53,7 +53,7 @@ import {
   vendoredPath,
   whereUsed,
   withFile
-} from "./chunk-3HON5Q5K.js";
+} from "./chunk-X2YYMHR4.js";
 import {
   escapingLinks,
   within
@@ -137,6 +137,7 @@ import {
   sha256,
   shortHash,
   toPosix,
+  unifiedDiff,
   writeFileAtomic
 } from "./chunk-DWYDHVLZ.js";
 import {
@@ -147,8 +148,8 @@ import {
 var import_yaml4 = __toESM(require_dist(), 1);
 import { execFile as execFile5 } from "node:child_process";
 import { existsSync as existsSync5 } from "node:fs";
-import { appendFile as appendFile2, readFile as readFile10, rm as rm6, rmdir as rmdir3 } from "node:fs/promises";
-import { basename as basename5, dirname as dirname13, join as join25, relative as relative11, resolve as resolve15 } from "node:path";
+import { appendFile as appendFile2, readFile as readFile10, rm as rm7, rmdir as rmdir3 } from "node:fs/promises";
+import { basename as basename5, dirname as dirname13, join as join26, relative as relative11, resolve as resolve15 } from "node:path";
 import { parseArgs, promisify as promisify5 } from "node:util";
 
 // ../cli/src/check.ts
@@ -166,7 +167,7 @@ import { join as join2, relative, resolve } from "node:path";
 
 // ../cli/src/command.ts
 var COMMAND = "youiyoux";
-var SUBCOMMANDS = ["show", "where", "bom", "check", "baseline", "rules", "plan", "migrate", "init", "adopt", "status", "system", "sync", "link", "unlink", "scan", "watch", "hooks", "agents", "mcp", "ui", "library", "discover", "index", "report", "render", "screens", "requests", "detect", "build", "parity", "schema", "inventory", "gaps", "help"];
+var SUBCOMMANDS = ["show", "where", "bom", "check", "baseline", "rules", "plan", "migrate", "upgrade", "init", "adopt", "status", "system", "sync", "link", "unlink", "scan", "watch", "hooks", "agents", "mcp", "ui", "library", "discover", "index", "report", "render", "screens", "requests", "detect", "build", "parity", "schema", "inventory", "gaps", "help"];
 
 // ../cli/src/agents.ts
 var import_yaml = __toESM(require_dist(), 1);
@@ -801,6 +802,7 @@ async function readLock(root) {
 var Writer = class {
   actions = [];
   files = {};
+  contents = /* @__PURE__ */ new Map();
   project;
   options;
   previous;
@@ -813,6 +815,7 @@ var Writer = class {
     return join6(this.project.root, file);
   }
   async write(file, content) {
+    this.contents.set(file, content);
     if (!this.options.dryRun) await writeFileAtomic(this.path(file), content);
   }
   record(action) {
@@ -985,7 +988,7 @@ async function syncProject(project2, options = {}) {
   };
   if (!options.dryRun) await writeFileAtomic(join6(project2.root, LOCK_FILE), `${JSON.stringify(lock, null, 2)}
 `);
-  return { actions: writer.actions, lock, unknownTools: unknownToolMentions(project2) };
+  return { actions: writer.actions, lock, unknownTools: unknownToolMentions(project2), contents: writer.contents };
 }
 async function sameFile(a, b) {
   const [x, y] = await Promise.all([realpath(a).catch(() => null), realpath(b).catch(() => null)]);
@@ -2106,7 +2109,7 @@ async function libraryLicence(id) {
   }
 }
 async function startRuleEditor(options) {
-  const { FileStore, RuleWorkflow, serveWorkflow } = await import("./src-EUVBYTKY.js");
+  const { FileStore, RuleWorkflow, serveWorkflow } = await import("./src-6SNQVIZS.js");
   const projectRoot = resolve6(options.project);
   const load2 = { ...options.config ? { configPath: resolve6(options.config) } : {}, ...options.design ? { designRoot: resolve6(options.design) } : {}, ...options.root ? { productRoot: resolve6(options.root) } : {} };
   const project2 = await loadProject(projectRoot, load2);
@@ -2650,14 +2653,186 @@ async function extractSystem(project2, dir, options = {}) {
   }
 }
 
+// ../cli/src/upgrade.ts
+import { lstat as lstat2, rm as rm5 } from "node:fs/promises";
+import { join as join16 } from "node:path";
+var LOCK_FILE2 = "youi.lock.json";
+var WRITES = /* @__PURE__ */ new Set(["created", "updated", "merged", "adopted", "removed"]);
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core = "", pre = ""] = v.replace(/^v/, "").split("-", 2);
+    return [core.split(".").slice(0, 3).map((n) => Number(n) || 0), pre];
+  };
+  const [[x, xp], [y, yp]] = [parse(a), parse(b)];
+  for (let i = 0; i < 3; i++) if ((x[i] ?? 0) !== (y[i] ?? 0)) return (x[i] ?? 0) - (y[i] ?? 0);
+  if (xp === yp) return 0;
+  return xp === "" ? 1 : yp === "" ? -1 : xp < yp ? -1 : 1;
+}
+function admits(range, version) {
+  const parts = range.trim().split(/\s+/);
+  const results = parts.map((part) => {
+    if (part === "*" || part === "x") return true;
+    const xr = /^v?(\d+)(?:\.(\d+|x))?(?:\.(x))?$/.exec(part);
+    if (xr && (xr[2] === "x" || xr[3] === "x" || xr[2] === void 0)) {
+      const [major, minor] = version.split(".").map(Number);
+      return major === Number(xr[1]) && (xr[2] === void 0 || xr[2] === "x" || minor === Number(xr[2]));
+    }
+    const op = /^(\^|~|>=|<=|>|<|=)?v?(\d+\.\d+\.\d+(?:-[\w.]+)?)$/.exec(part);
+    if (!op) return null;
+    const [, kind = "=", base = ""] = op;
+    const cmp = compareVersions(version, base);
+    const [bMajor, bMinor] = base.split(".").map(Number);
+    const [vMajor, vMinor] = version.split(".").map(Number);
+    if (kind === "^") return cmp >= 0 && (bMajor === 0 ? vMajor === 0 && vMinor === bMinor : vMajor === bMajor);
+    if (kind === "~") return cmp >= 0 && vMajor === bMajor && vMinor === bMinor;
+    return { "=": cmp === 0, ">=": cmp >= 0, "<=": cmp <= 0, ">": cmp > 0, "<": cmp < 0 }[kind] ?? null;
+  });
+  return results.includes(null) ? null : results.every(Boolean);
+}
+function pendingMigrations(project2, lock) {
+  const entries = Object.entries(lock.files).flatMap(([file, entry]) => entry.kind === "vendored" ? [{ file, ...entry }] : []);
+  const planned = [];
+  for (const { contract, migrations } of project2.system.components) {
+    const entry = entries.find((e) => e.file === vendoredPath(project2, contract.source.file) && e.elements.includes(contract.id)) ?? entries.filter((e) => e.elements.includes(contract.id)).sort((a, b) => a.elements.length - b.elements.length)[0];
+    if (!entry) continue;
+    let at = entry.version;
+    for (const spec of [...migrations].filter((m) => compareVersions(m.to, entry.version) > 0 && compareVersions(m.to, contract.version) <= 0).sort((a, b) => compareVersions(a.to, b.to) || a.id.localeCompare(b.id))) {
+      planned.push({ spec, at, mismatch: admits(spec.from, at) === false });
+      at = spec.to;
+    }
+  }
+  return planned.sort((a, b) => compareVersions(a.spec.to, b.spec.to) || a.spec.id.localeCompare(b.spec.id));
+}
+var Snapshot = class {
+  saved = /* @__PURE__ */ new Map();
+  root;
+  constructor(root) {
+    this.root = root;
+  }
+  async keep(files) {
+    for (const file of files) if (!this.saved.has(file)) this.saved.set(file, await readTextOrNull(join16(this.root, file)));
+  }
+  /** A file's content before a step wrote it, unless it was kept already. */
+  remember(file, content) {
+    if (!this.saved.has(file)) this.saved.set(file, content);
+  }
+  /** Put back each file that changed; those that could not be are returned, to name them. */
+  async restore() {
+    const stuck = [];
+    for (const [file, content] of this.saved) {
+      const path = join16(this.root, file);
+      try {
+        if (content !== null) {
+          if (await readTextOrNull(path) !== content) await writeFileAtomic(path, content);
+        } else if (await lstat2(path).then((s) => s.isFile(), () => false)) await rm5(path);
+      } catch {
+        stuck.push(file);
+      }
+    }
+    return stuck;
+  }
+};
+var gateFailures = (result) => result.gates.filter((g) => !g.ok).map((g) => `${g.name}: ${g.detail}`).join("; ");
+async function withRef(configFile, ref) {
+  const text = await readTextOrNull(configFile) ?? "{}";
+  const config = JSON.parse(text);
+  return `${JSON.stringify({ ...config, source: { ...config.source, ref } }, null, 2)}
+`;
+}
+async function upgradeProject(project2, options = {}) {
+  const lock = await readLock(project2.root);
+  const source = project2.config.source;
+  const system = { id: project2.system.config.id, name: project2.system.config.name };
+  const to = { version: project2.system.config.version, commit: project2.designCommit ?? null, ref: options.to ?? ("git" in source ? source.ref : null) };
+  const from = { version: lock?.systemVersion ?? null, commit: lock?.sourceCommit ?? null };
+  const result = (status, parts, next2) => ({ status, system, from, to, sync: parts.sync ?? [], migrations: parts.migrations ?? [], blocked: parts.blocked ?? [], next: next2 });
+  if (!lock) return result("blocked", { blocked: ["this product has never been synced with its System, so there is no earlier version to upgrade from"] }, "youiyoux sync");
+  if (lock.system !== system.id) return result("blocked", { blocked: [`youi.lock.json is for System ${lock.system}, and the config names ${system.id}: an upgrade moves within one System`] }, "youiyoux sync, to switch Systems");
+  const dry = await syncProject(project2, { dryRun: true });
+  const conflicts = dry.actions.filter((a) => a.action === "conflict");
+  const sync = dry.actions.filter((a) => WRITES.has(a.action) || a.action === "conflict" || a.action === "kept-local");
+  const planned = pendingMigrations(project2, lock);
+  const blocked = [
+    ...conflicts.map((a) => `${a.file}: ${a.detail ?? "conflicts with upstream"}`),
+    ...planned.filter((p) => p.mismatch).map((p) => `${p.spec.id} migrates from ${p.spec.from}, but ${p.spec.element} would be at ${p.at} here: no migration takes it from ${p.at} to ${p.spec.from}`)
+  ];
+  if (blocked.length > 0) return result("blocked", { sync, blocked }, conflicts.length > 0 ? "youiyoux sync: resolve the conflicts it reports, then youiyoux sync --adopt records them, then youiyoux upgrade" : "ask the System's owners for the missing migration, or migrate by hand, then youiyoux sync");
+  let staged = Object.fromEntries(dry.actions.filter((a) => a.role === "component" && dry.contents.has(a.file)).map((a) => [a.file, dry.contents.get(a.file)]));
+  const previews = [];
+  for (const { spec } of planned) {
+    const preview = await runMigration({ ...project2, staged }, spec);
+    previews.push(preview);
+    if (preview.status === "rejected") return result("blocked", { sync, migrations: previews, blocked: [`${spec.id} would not hold: ${gateFailures(preview)}`] }, "fix what the failing gate names, or ask the System's owners; nothing was written");
+    staged = { ...staged, ...Object.fromEntries(preview.changes.map((c) => [c.file, c.after])) };
+  }
+  const ref = options.to !== void 0 && "git" in source && options.to !== source.ref ? options.to : null;
+  const changes = sync.some((a) => WRITES.has(a.action)) || previews.some((m) => m.status !== "noop") || ref !== null || lock.systemVersion !== to.version;
+  if (!changes) return result("current", { sync, migrations: previews }, "nothing to do");
+  if (!options.write) return result("preview", { sync, migrations: previews }, `youiyoux upgrade${options.to !== void 0 ? ` --to ${options.to}` : ""} --write`);
+  const configFile = project2.configFile ?? join16(project2.root, PROJECT_FILE);
+  const snapshot = new Snapshot(project2.root);
+  const configBefore = await readTextOrNull(configFile);
+  await snapshot.keep([LOCK_FILE2, ...dry.contents.keys(), ...dry.actions.filter((a) => a.action === "removed").map((a) => a.file), ...previews.flatMap((m) => m.changes.map((c) => c.file))]);
+  const fail = async (why, done) => {
+    const stuck = await snapshot.restore();
+    if (ref !== null && configBefore !== null) await writeFileAtomic(configFile, configBefore).catch(() => stuck.push(PROJECT_FILE));
+    const back = stuck.length === 0 ? "every file the upgrade wrote was put back" : `the files it wrote were put back except ${stuck.join(", ")}: restore those from git`;
+    return result("blocked", { sync, migrations: previews, ...done, blocked: [`${why}; ${back}`] }, "run youiyoux upgrade again to see what changed");
+  };
+  try {
+    if (ref !== null) await writeFileAtomic(configFile, await withRef(configFile, ref));
+    const synced = await syncProject(project2);
+    const late = synced.actions.filter((a) => a.action === "conflict");
+    if (late.length > 0) return await fail(`the sync conflicted in ${late.map((a) => a.file).join(", ")}`, {});
+    const applied = [];
+    for (const { spec } of planned) {
+      const run7 = await runMigration(project2, spec, { write: true });
+      applied.push(run7);
+      for (const change of run7.changes) snapshot.remember(change.file, change.before);
+      if (run7.status === "rejected") return await fail(`${spec.id} did not hold on the written files: ${gateFailures(run7)}`, { migrations: applied });
+    }
+    const residuals = applied.reduce((n, m) => n + m.residuals.length, 0);
+    return result("upgraded", { sync: synced.actions.filter((a) => WRITES.has(a.action) || a.action === "kept-local"), migrations: applied }, residuals > 0 ? `fix the ${residuals === 1 ? "site" : `${residuals} sites`} listed for a person, then youiyoux check` : "youiyoux check");
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : String(error), {});
+  }
+}
+var ACTION = { created: style.ok, updated: style.live, merged: style.live, adopted: style.ok, removed: style.live, "kept-local": style.warn, conflict: style.error };
+function renderUpgrade(r, showDiff) {
+  const version = (v) => v === null ? "never synced" : `v${v}`;
+  const move = r.from.version === r.to.version ? `${version(r.to.version)}${r.from.commit && r.to.commit && r.from.commit !== r.to.commit ? style.dim(` (${r.from.commit.slice(0, 7)} \u2192 ${r.to.commit.slice(0, 7)})`) : ""}` : `${version(r.from.version)} \u2192 v${r.to.version}`;
+  const verdict = { current: style.ok("up to date"), preview: style.live("preview: nothing written"), upgraded: style.ok("upgraded"), blocked: style.error("blocked: nothing written") }[r.status];
+  const lines = [`${style.accent("upgrade")} ${r.system.name} ${move}${r.to.ref ? style.dim(` \xB7 ref ${r.to.ref}`) : ""}  ${verdict}`, ""];
+  const row = (a) => `  ${padEnd((ACTION[a.action] ?? style.dim)(a.action), 11)} ${a.file}${a.detail ? style.dim(`  ${a.detail}`) : ""}`;
+  const generated = r.sync.filter((a) => a.role !== "component" && a.action !== "conflict");
+  lines.push(style.bold("sync"), ...r.sync.length === 0 ? [style.dim("  nothing to bring")] : r.sync.filter((a) => !generated.includes(a)).map(row));
+  if (generated.length === 1) lines.push(row(generated[0]));
+  else if (generated.length > 1) lines.push(`  ${padEnd(style.live("updated"), 11)} ${plural(generated.length, "generated file")}${style.dim(`  ${generated.slice(0, 3).map((a) => a.file).join(", ")}${generated.length > 3 ? ", \u2026" : ""}`)}`);
+  lines.push("", style.bold("migrations"));
+  if (r.migrations.length === 0) lines.push(style.dim(r.status === "blocked" && r.sync.length > 0 ? "  not run" : r.status === "current" ? "  none pending" : "  none: no component this product has changed its API in this release"));
+  for (const m of r.migrations) {
+    const mark = m.status === "rejected" ? style.error("\u2716") : m.status === "noop" ? style.dim("\xB7") : style.ok("\u2713");
+    const what = m.status === "noop" ? style.dim("nothing here uses what it changes") : `${plural(m.edited, "site")} rewritten in ${plural(m.changes.length, "file")}${m.residuals.length > 0 ? ` \xB7 ${style.warn(`${plural(m.residuals.length, "site")} for a person`)}` : ""}`;
+    lines.push(`  ${mark} ${m.migration}  ${what}`);
+    for (const gate of m.gates.filter((g) => !g.ok)) lines.push(`      ${style.error(gate.name)} ${style.dim(gate.detail)}`);
+    for (const residual of m.residuals) lines.push(`      ${style.dim(`${residual.file}:${residual.line}`)}  ${residual.reason}`);
+  }
+  const files = /* @__PURE__ */ new Map();
+  for (const change of r.migrations.flatMap((m) => m.changes)) files.set(change.file, { before: files.get(change.file)?.before ?? change.before, after: change.after });
+  if (showDiff) for (const [file, { before, after }] of files) lines.push("", ...unifiedDiff(file, before, after).trimEnd().split("\n").map((l) => l.startsWith("+") && !l.startsWith("+++") ? style.ok(l) : l.startsWith("-") && !l.startsWith("---") ? style.error(l) : style.dim(l)));
+  if (r.blocked.length > 0) lines.push("", ...r.blocked.map((b) => `${style.error("\u2716")} ${b}`));
+  lines.push("", `${style.bold("Next:")} ${r.next}`);
+  return lines.join("\n");
+}
+
 // ../cli/src/status.ts
 import { realpath as realpath5 } from "node:fs/promises";
-import { dirname as dirname9, join as join16, relative as relative8, resolve as resolve10 } from "node:path";
+import { dirname as dirname9, join as join17, relative as relative8, resolve as resolve10 } from "node:path";
 var placeOf = (cwd, root) => {
   const rel = relative8(cwd, root) || ".";
   return rel.split(/[\\/]/).filter((part) => part === "..").length > 1 ? resolve10(root) : rel;
 };
-var WRITES = /* @__PURE__ */ new Set(["created", "updated", "merged", "adopted", "conflict", "removed"]);
+var WRITES2 = /* @__PURE__ */ new Set(["created", "updated", "merged", "adopted", "conflict", "removed"]);
 function sourceOf(project2) {
   if (project2.linked) return `your checkout ${project2.linked}`;
   const source = project2.config.source;
@@ -2665,9 +2840,10 @@ function sourceOf(project2) {
   if ("git" in source) return `git ${source.git} at ${source.ref}`;
   return resolve10(project2.root) === resolve10(project2.repo.root) ? "this repo" : `path ${source.path}`;
 }
-function nextStep(s) {
+function nextStep(s, migrations) {
   if (s.sync.state === "never") return "youiyoux sync: this product has never been synced with its System";
   if (s.sync.state === "conflict") return "youiyoux sync: resolve the conflicts it reports, then youiyoux sync --adopt records them";
+  if (migrations > 0) return `youiyoux upgrade: ${s.system.name} v${s.system.version} comes with ${plural(migrations, "migration")} for this product's code, which upgrade runs with the sync`;
   if (s.sync.state === "behind") return `youiyoux sync: ${plural(s.sync.changes.length, "file")} would change`;
   if (s.check.incomplete) return "youiyoux check: some files or rules could not be checked, and it says which";
   if (s.check.errors > 0) return `youiyoux check: fix ${plural(s.check.errors, "error")}`;
@@ -2678,13 +2854,13 @@ function nextStep(s) {
 async function projectStatus(project2, cwd = process.cwd()) {
   const lock = await readLock(project2.root);
   const { actions } = await syncProject(project2, { dryRun: true });
-  const changes = actions.filter((a) => WRITES.has(a.action)).map((a) => ({ file: a.file, action: a.action }));
+  const changes = actions.filter((a) => WRITES2.has(a.action)).map((a) => ({ file: a.file, action: a.action }));
   const baselineFile2 = baselinePath(project2);
   const check = await runCheck(project2, { baseline: await readTextOrNull(baselineFile2) === null ? null : baselineFile2 });
   const comparison = check.baseline?.comparison;
   const counted = comparison ? [...comparison.new, ...comparison.regressed] : check.violations;
   const usages = check.scan.report.usages;
-  const { RequestStore } = await import("./src-EUVBYTKY.js");
+  const { RequestStore } = await import("./src-6SNQVIZS.js");
   const requests = await new RequestStore(project2.root, project2.config.id).list();
   const status = {
     id: project2.config.id,
@@ -2702,7 +2878,7 @@ async function projectStatus(project2, cwd = process.cwd()) {
     components: { system: project2.system.components.length, used: new Set(usages.map((u) => u.element)).size, sites: usages.length },
     requests: { open: requests.requests.filter((r) => r.status === "open").length, addressed: requests.requests.filter((r) => r.status === "addressed").length, unreadable: requests.unreadable.length }
   };
-  return { ...status, next: nextStep(status) };
+  return { ...status, next: nextStep(status, lock ? pendingMigrations(project2, lock).length : 0) };
 }
 async function statusTargets(cwd, named2) {
   if (named2) return { roots: [resolve10(named2)], workspace: null };
@@ -2710,7 +2886,7 @@ async function statusTargets(cwd, named2) {
   if (product2) return { roots: [product2], workspace: null };
   const at = findUp(cwd, WORKSPACE_FILE);
   if (at) {
-    const file = join16(at, WORKSPACE_FILE);
+    const file = join17(at, WORKSPACE_FILE);
     const workspace = await readDefinition(file, WorkspaceConfig);
     return { roots: workspace.projects.map((p) => resolve10(at, p)), workspace: file };
   }
@@ -2732,7 +2908,7 @@ async function workspaceStatus(cwd, named2) {
       projects.push(await projectStatus(await loadProject(root), cwd));
     } catch (error) {
       const label = placeOf(cwd, root);
-      projects.push({ root: label, error: error instanceof Error ? error.message : String(error), next: await readTextOrNull(join16(root, PROJECT_FILE)) === null ? `youiyoux adopt or youiyoux init --design <dir> in ${label}` : `fix ${join16(label, PROJECT_FILE)}` });
+      projects.push({ root: label, error: error instanceof Error ? error.message : String(error), next: await readTextOrNull(join17(root, PROJECT_FILE)) === null ? `youiyoux adopt or youiyoux init --design <dir> in ${label}` : `fix ${join17(label, PROJECT_FILE)}` });
     }
   }
   return { schema: "youi.status/v1", generatedAt: (/* @__PURE__ */ new Date()).toISOString(), workspace: workspace ? relative8(cwd, workspace) || WORKSPACE_FILE : null, projects };
@@ -2829,14 +3005,14 @@ async function startWorkspaceHub(options) {
 }
 
 // ../cli/src/index-store.ts
-import { appendFile, mkdir as mkdir4, readFile as readFile6, stat as stat2, rename as rename2, mkdtemp as mkdtemp4, rm as rm5 } from "node:fs/promises";
-import { dirname as dirname10, join as join17, resolve as resolve11 } from "node:path";
+import { appendFile, mkdir as mkdir4, readFile as readFile6, stat as stat2, rename as rename2, mkdtemp as mkdtemp4, rm as rm6 } from "node:fs/promises";
+import { dirname as dirname10, join as join18, resolve as resolve11 } from "node:path";
 var SOURCES_FILE = "index-sources.json";
 var SCANS_LOG = "scans.jsonl";
 var EMPTY = { discover: null, inventories: [], projects: [] };
 async function readIndexSources(home) {
   try {
-    const raw = JSON.parse(await readFile6(join17(home, SOURCES_FILE), "utf8"));
+    const raw = JSON.parse(await readFile6(join18(home, SOURCES_FILE), "utf8"));
     return { discover: raw.discover ?? null, inventories: raw.inventories ?? [], projects: raw.projects ?? [] };
   } catch {
     return EMPTY;
@@ -2849,14 +3025,14 @@ async function noteSource(home, change) {
     inventories: change.inventory && !sources.inventories.includes(change.inventory) ? [...sources.inventories, change.inventory] : sources.inventories,
     projects: change.project ? [...sources.projects.filter((p) => p.root !== change.project.root), change.project] : sources.projects
   };
-  await writeFileAtomic(join17(home, SOURCES_FILE), `${JSON.stringify(next2, null, 2)}
+  await writeFileAtomic(join18(home, SOURCES_FILE), `${JSON.stringify(next2, null, 2)}
 `);
 }
 async function recordInventory(store, home, report, file) {
   const run7 = inventoryRun(report, resolve11(file));
   const logged = { run: run7.run, source: run7.source, scannedAt: run7.scannedAt, projects: run7.projects, families: run7.families };
   await mkdir4(home, { recursive: true });
-  await appendFile(join17(home, SCANS_LOG), `${JSON.stringify({ schema: "youi.scan-log/v1", ...logged })}
+  await appendFile(join18(home, SCANS_LOG), `${JSON.stringify({ schema: "youi.scan-log/v1", ...logged })}
 `);
   await store.recordInventory(run7);
   await noteSource(home, { inventory: run7.source });
@@ -2867,7 +3043,7 @@ async function recordProject(store, project2, usage) {
   await store.replaceGraph(`project:${project2.root}`, projectGraph({ project: project2.config.id, rules: project2.system.rules, components: project2.system.components.map((c) => ({ id: c.contract.id, name: c.contract.name })), usage }));
 }
 async function readLog(home) {
-  const text = await readFile6(join17(home, SCANS_LOG), "utf8").catch(() => "");
+  const text = await readFile6(join18(home, SCANS_LOG), "utf8").catch(() => "");
   return text.split("\n").flatMap((line) => {
     if (!line.trim()) return [];
     try {
@@ -2884,7 +3060,7 @@ async function rebuildIndex(path, options = {}) {
   const home = indexHome(path, env);
   await mkdir4(dirname10(path), { recursive: true });
   const scratch = !env.DATABASE_URL ? await mkdtemp4(`${path}.rebuild-`) : null;
-  const target = scratch ? join17(scratch, "index.db") : path;
+  const target = scratch ? join18(scratch, "index.db") : path;
   const store = scratch ? await openSqlite(target) : await sharedStore(path, env);
   try {
     if (env.DATABASE_URL) await store.reset();
@@ -2892,7 +3068,7 @@ async function rebuildIndex(path, options = {}) {
     const sources = await readIndexSources(home);
     const cache = options.discoverCache ?? sources.discover;
     let discover = { cache, chosen: 0, all: 0 };
-    if (cache && await stat2(join17(cache, "index.json")).then(() => true, () => false)) {
+    if (cache && await stat2(join18(cache, "index.json")).then(() => true, () => false)) {
       const loaded = await ingestCatalog(store, cache);
       discover = { cache, chosen: loaded.chosen, all: loaded.all };
     }
@@ -2920,7 +3096,7 @@ async function rebuildIndex(path, options = {}) {
       }
       try {
         const project2 = await loadProject(source.root, source.options);
-        const usage = ScanReport.safeParse(await readJson(source.usage ?? join17(project2.root, ".youi/usage.json")));
+        const usage = ScanReport.safeParse(await readJson(source.usage ?? join18(project2.root, ".youi/usage.json")));
         await recordProject(store, project2, usage.success ? usage.data : null);
         projects++;
       } catch (error) {
@@ -2955,7 +3131,7 @@ async function rebuildIndex(path, options = {}) {
   } finally {
     if (scratch) {
       await store.close();
-      await rm5(scratch, { recursive: true, force: true });
+      await rm6(scratch, { recursive: true, force: true });
     }
   }
 }
@@ -3139,7 +3315,7 @@ function renderAdoptionRequest(request) {
 // ../cli/src/report/run.ts
 import { randomBytes as randomBytes3 } from "node:crypto";
 import { mkdir as mkdir5, rename as rename3, stat as stat3, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join24, relative as relative10, resolve as resolve14 } from "node:path";
+import { join as join25, relative as relative10, resolve as resolve14 } from "node:path";
 
 // ../cli/src/report/card.ts
 import { deflateSync } from "node:zlib";
@@ -3375,7 +3551,7 @@ function drawCard(input) {
 
 // ../cli/src/report/model.ts
 import { readFile as readFile8 } from "node:fs/promises";
-import { join as join21 } from "node:path";
+import { join as join22 } from "node:path";
 
 // ../cli/src/report/filters.ts
 var SHOWCASE_GLOBS = ["**/{__stories__,.storybook,storybook,storybook-static,example,examples,demo,demos,playground,showcase,showcases}/**", "**/*.stories.*", "**/*.story.*"];
@@ -3502,11 +3678,11 @@ function publicLook(caption) {
 
 // ../cli/src/report/groups.ts
 import { existsSync as existsSync3 } from "node:fs";
-import { join as join19 } from "node:path";
+import { join as join20 } from "node:path";
 
 // ../cli/src/report/imports.ts
 import { realpathSync } from "node:fs";
-import { dirname as dirname11, join as join18, relative as relative9, resolve as resolve12 } from "node:path";
+import { dirname as dirname11, join as join19, relative as relative9, resolve as resolve12 } from "node:path";
 import ts from "typescript";
 var resolvers = /* @__PURE__ */ new Map();
 function resolverOf(root) {
@@ -3525,13 +3701,13 @@ function clearImportCache() {
 }
 async function verifiedImport(root, keeper, from, suggested) {
   const { options, cache } = resolverOf(root);
-  let local = relative9(dirname11(join18(root, from)), join18(root, keeper)).replaceAll("\\", "/").replace(/\.(tsx?|jsx?|mjs)$/, "");
+  let local = relative9(dirname11(join19(root, from)), join19(root, keeper)).replaceAll("\\", "/").replace(/\.(tsx?|jsx?|mjs)$/, "");
   if (!local.startsWith(".")) local = `./${local}`;
   for (const specifier of /* @__PURE__ */ new Set([suggested, local])) {
     const found = ts.resolveModuleName(specifier, resolve12(root, from), options, ts.sys, cache).resolvedModule?.resolvedFileName;
     if (found) {
       try {
-        if (realpathSync(found) === realpathSync(join18(root, keeper))) return specifier;
+        if (realpathSync(found) === realpathSync(join19(root, keeper))) return specifier;
       } catch {
       }
     }
@@ -3939,7 +4115,7 @@ function factsOf(project2, id, modules, eligible, workspaceNames, dependencies,
     if (dirs.has(file.slice(0, at))) break;
     dirs.add(file.slice(0, at));
   }
-  const roots = [...dirs].filter((dir) => existsSync3(join19(project2.root, dir, "package.json"))).sort((a, b) => b.length - a.length);
+  const roots = [...dirs].filter((dir) => existsSync3(join20(project2.root, dir, "package.json"))).sort((a, b) => b.length - a.length);
   const nested = (file) => roots.find((dir) => file.startsWith(`${dir}/`)) ?? "";
   return { project: project2, id, dependencies, packageImports, jsxCounts, eligible, twins, dirs, importer, packageOf: nested };
 }
@@ -3947,11 +4123,11 @@ function factsOf(project2, id, modules, eligible, workspaceNames, dependencies,
 // ../cli/src/report/projects.ts
 var import_yaml3 = __toESM(require_dist(), 1);
 import { readFile as readFile7 } from "node:fs/promises";
-import { basename as basename4, join as join20, resolve as resolve13 } from "node:path";
+import { basename as basename4, join as join21, resolve as resolve13 } from "node:path";
 var UI_FILES = ["**/*.{tsx,jsx,astro,vue,svelte}"];
 var strings = (value) => Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
 async function workspaceGlobs(root, pkg) {
-  const pnpm = await readFile7(join20(root, "pnpm-workspace.yaml"), "utf8").catch(() => null);
+  const pnpm = await readFile7(join21(root, "pnpm-workspace.yaml"), "utf8").catch(() => null);
   if (pnpm !== null) {
     try {
       const globs2 = strings((0, import_yaml3.parse)(pnpm)?.packages);
@@ -3966,7 +4142,7 @@ async function workspaceGlobs(root, pkg) {
 var hasUi = async (dir) => (await findFiles(dir, UI_FILES, DEFAULT_EXCLUDE)).length > 0;
 async function findProjects(dir) {
   const root = resolve13(dir);
-  const pkg = await readJson(join20(root, "package.json"));
+  const pkg = await readJson(join21(root, "package.json"));
   const name = typeof pkg?.name === "string" && pkg.name.trim() ? pkg.name.trim() : basename4(root);
   const single = { dir: ".", root, name: typeof pkg?.name === "string" ? pkg.name : null };
   const workspace = await workspaceGlobs(root, pkg);
@@ -3977,12 +4153,12 @@ async function findProjects(dir) {
   const projects = [];
   const skipped = [];
   for (const member of members) {
-    const memberRoot = join20(root, member);
+    const memberRoot = join21(root, member);
     if (!await hasUi(memberRoot)) {
       skipped.push(member);
       continue;
     }
-    const memberPkg = await readJson(join20(memberRoot, "package.json"));
+    const memberPkg = await readJson(join21(memberRoot, "package.json"));
     projects.push({ dir: member, root: memberRoot, name: typeof memberPkg?.name === "string" ? memberPkg.name : null });
   }
   if (projects.length === 0) return { root, name, layout: `one project (${workspace.source} names no package with UI files)`, projects: [single], skipped };
@@ -4009,7 +4185,7 @@ var Lines = class {
     if (!this.enabled) return { at };
     let lines = this.files.get(file);
     if (!lines) {
-      lines = (await readFile8(join21(this.root, file), "utf8").catch(() => "")).split("\n");
+      lines = (await readFile8(join22(this.root, file), "utf8").catch(() => "")).split("\n");
       this.files.set(file, lines);
     }
     const code = lines[line - 1]?.trim();
@@ -4029,7 +4205,7 @@ async function modulesOf(project2, target, failed2) {
   for (const file of target.files) {
     if (isShowcase(file)) continue;
     try {
-      const module = await parseModule(file, await readFile8(join21(project2.root, file), "utf8"));
+      const module = await parseModule(file, await readFile8(join22(project2.root, file), "utf8"));
       if (module) modules.push(module);
     } catch (error) {
       failed2.push(`${repoPath(project2.dir, file)}: ${errorText(error)}`);
@@ -4133,7 +4309,7 @@ async function analyseProject(project2, index, inventory, inventoryError, worksp
       incomplete.push(`Library choices were not compared (${errorText(error)}); run ${NPX} detect ${project2.dir} to see why`);
     }
   }
-  const pkg = await readFile8(join21(project2.root, "package.json"), "utf8").then((text) => JSON.parse(text), () => null);
+  const pkg = await readFile8(join22(project2.root, "package.json"), "utf8").then((text) => JSON.parse(text), () => null);
   const dependencies = new Set(["dependencies", "devDependencies", "peerDependencies"].flatMap((key2) => Object.keys(pkg?.[key2] ?? {})));
   const importer = changeProject ? await importOf(changeProject) : () => "";
   const facts = factsOf(project2, projectId ?? null, modules, eligible, workspaceNames, dependencies, target?.files ?? [], importer);
@@ -4577,7 +4753,7 @@ ${model.projects.map((p) => projectSection(p, many, looks)).join("\n")}
 import { spawn as spawn2 } from "node:child_process";
 import { existsSync as existsSync4, readFileSync as readFileSync2 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
-import { dirname as dirname12, join as join22 } from "node:path";
+import { dirname as dirname12, join as join23 } from "node:path";
 var LOOKS_PER_PROJECT = 4;
 var DOWNLOAD_SIZE = "~100 MB";
 var DEPENDENCIES = "Install the repo's dependencies to see rendered looks";
@@ -4585,26 +4761,26 @@ var UNDRAWABLE = /not installed|loads no stylesheet|drawn from (?:its|their) (?:
 var playwrightDir = () => dirname12(playwrightCli());
 function browsersPath(env) {
   const set = env.PLAYWRIGHT_BROWSERS_PATH;
-  if (set === "0") return join22(playwrightDir(), ".local-browsers");
+  if (set === "0") return join23(playwrightDir(), ".local-browsers");
   if (set) return set;
-  if (process.platform === "darwin") return join22(homedir2(), "Library/Caches/ms-playwright");
-  if (process.platform === "win32") return join22(env.LOCALAPPDATA ?? join22(homedir2(), "AppData/Local"), "ms-playwright");
-  return join22(env.XDG_CACHE_HOME ?? join22(homedir2(), ".cache"), "ms-playwright");
+  if (process.platform === "darwin") return join23(homedir2(), "Library/Caches/ms-playwright");
+  if (process.platform === "win32") return join23(env.LOCALAPPDATA ?? join23(homedir2(), "AppData/Local"), "ms-playwright");
+  return join23(env.XDG_CACHE_HOME ?? join23(homedir2(), ".cache"), "ms-playwright");
 }
 function chromiumStatus(env = process.env) {
   if (env.YOUI_CHROMIUM) return { available: existsSync4(env.YOUI_CHROMIUM), where: env.YOUI_CHROMIUM };
   try {
-    const browsers = JSON.parse(readFileSync2(join22(playwrightDir(), "browsers.json"), "utf8"));
+    const browsers = JSON.parse(readFileSync2(join23(playwrightDir(), "browsers.json"), "utf8"));
     const revision2 = browsers.browsers.find((b) => b.name === "chromium-headless-shell")?.revision;
-    const dir = join22(browsersPath(env), `chromium_headless_shell-${revision2}`);
-    return { available: revision2 !== void 0 && existsSync4(join22(dir, "INSTALLATION_COMPLETE")), where: dir };
+    const dir = join23(browsersPath(env), `chromium_headless_shell-${revision2}`);
+    return { available: revision2 !== void 0 && existsSync4(join23(dir, "INSTALLATION_COMPLETE")), where: dir };
   } catch {
     return { available: false, where: "playwright-core is not installed" };
   }
 }
 function downloadChromium() {
   return new Promise((resolve16) => {
-    const child = spawn2(process.execPath, [join22(playwrightDir(), "cli.js"), "install", "chromium-headless-shell"], { stdio: ["ignore", 2, 2] });
+    const child = spawn2(process.execPath, [join23(playwrightDir(), "cli.js"), "install", "chromium-headless-shell"], { stdio: ["ignore", 2, 2] });
     child.on("error", () => resolve16(false));
     child.on("close", (code) => resolve16(code === 0));
   });
@@ -4620,9 +4796,9 @@ async function addLooks(model, repoRoot, options = {}) {
     const where2 = section.dir === "." ? "this repo" : section.dir;
     try {
       const installed = (name) => {
-        let dir = join22(repoRoot, section.dir);
+        let dir = join23(repoRoot, section.dir);
         while (true) {
-          if (existsSync4(join22(dir, "node_modules", name, "package.json"))) return true;
+          if (existsSync4(join23(dir, "node_modules", name, "package.json"))) return true;
           if (dir === repoRoot || dirname12(dir) === dir) return false;
           dir = dirname12(dir);
         }
@@ -4631,13 +4807,13 @@ async function addLooks(model, repoRoot, options = {}) {
         missing.push(where2);
         continue;
       }
-      const projectRoot = join22(repoRoot, section.dir);
+      const projectRoot = join23(repoRoot, section.dir);
       const target = await loadInventoryTarget(projectRoot);
       if (findStylesheets(projectRoot, target.files, { tsconfig: target.tsconfig, override: target.specimenCss, templates: target.templates }).found.length === 0) {
         missing.push(where2);
         continue;
       }
-      const report = await renderShots(join22(repoRoot, section.dir), names, { download: false, base: "HEAD", ...options.executablePath ? { executablePath: options.executablePath } : {}, ...options.cache ? { cache: options.cache } : {}, ...options.log ? { log: options.log } : {} });
+      const report = await renderShots(join23(repoRoot, section.dir), names, { download: false, base: "HEAD", ...options.executablePath ? { executablePath: options.executablePath } : {}, ...options.cache ? { cache: options.cache } : {}, ...options.log ? { log: options.log } : {} });
       const unavailable = report.notes.some((note) => UNDRAWABLE.test(note));
       if (unavailable) {
         missing.push(where2);
@@ -4709,7 +4885,7 @@ function renderMarkdown(model, reportFile) {
 import { realpathSync as realpathSync2 } from "node:fs";
 import { readFile as readFile9 } from "node:fs/promises";
 import { homedir as homedir3, userInfo as userInfo2 } from "node:os";
-import { join as join23 } from "node:path";
+import { join as join24 } from "node:path";
 var REDACTED = "[redacted]";
 var OUTSIDE = "[path outside the repo]";
 var MIN_VALUE = 6;
@@ -4721,7 +4897,7 @@ async function dotenvValues(root) {
   const files = await findFiles(root, [".env", ".env.*", "**/.env", "**/.env.*"]).catch(() => []);
   const values = [];
   for (const file of files) {
-    const text = await readFile9(join23(root, file), "utf8").catch(() => "");
+    const text = await readFile9(join24(root, file), "utf8").catch(() => "");
     for (const line of text.split(/\r?\n/)) {
       const match = /^\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_.-]*\s*=\s*(.*)$/.exec(line);
       if (!match) continue;
@@ -4894,7 +5070,7 @@ async function runReport(options = {}, io = {}) {
   const clean = redactor.model(model);
   const outDir = resolve14(options.out ?? root);
   await mkdir5(outDir, { recursive: true });
-  const files = { report: join24(outDir, REPORT_FILE), card: join24(outDir, CARD_FILE), summary: join24(outDir, SUMMARY_FILE) };
+  const files = { report: join25(outDir, REPORT_FILE), card: join25(outDir, CARD_FILE), summary: join25(outDir, SUMMARY_FILE) };
   const t = clean.totals;
   const card = {
     repo: redactor.scrub(clean.repo),
@@ -5044,6 +5220,12 @@ ${style.bold("System")}  ${style.dim("approved elements: build only with these")
   plan <component> --patch <json|file>    classify a contract change and show its impact
   plan --token <id> [--value v]           impact of a token change
   migrate <migration.yaml> [--write] [--diff]   gated codemod for props and renamed or removed exports
+  upgrade [--to ref] [--write] [--diff]
+                           move to the System's new release in one step: the sync, and each component's
+                           migrations past the version youi.lock.json records, run as gated dry runs on
+                           the components as the sync would bring them; a preview unless --write, which
+                           writes all of it or, if a step fails, puts every file back. --to moves a git
+                           source to another tag or branch (written to the config's source.ref)
                            (imports, re-exports, uses); a dry run that prints the diff and the sites
                            left for a person (file:line, why) unless --write; --diff shows it after --write too
   rules [--preview <rule.yaml>]   whether each rule is checked; preview a draft rule on the current scan
@@ -5159,6 +5341,7 @@ var OPTIONS = {
   inventory: { type: "string" },
   package: { type: "string" },
   fork: { type: "boolean", default: false },
+  to: { type: "string" },
   cache: { type: "string" },
   role: { type: "string" },
   license: { type: "string" },
@@ -5196,7 +5379,7 @@ async function readJsonOrFile(value) {
 async function cmdScan(values) {
   const p = await project(values);
   const { report } = await scanProject(p);
-  const out = values.out ?? join25(p.root, ".youi/usage.json");
+  const out = values.out ?? join26(p.root, ".youi/usage.json");
   await writeFileAtomic(resolve15(out), `${JSON.stringify(report)}
 `);
   const recorded = await recordUsage(values, p, report, resolve15(out));
@@ -5243,7 +5426,7 @@ async function cmdInventory(values) {
   if (values.history) return cmdHistory(values, []);
   const dirs = inventoryDirs(values);
   const report = await scanInventory(values, dirs);
-  const out = resolve15(values.out ?? join25(dirs[0], ".youi/inventory.json"));
+  const out = resolve15(values.out ?? join26(dirs[0], ".youi/inventory.json"));
   await writeFileAtomic(out, `${JSON.stringify(report, null, 2)}
 `);
   const recorded = await recordScan(values, report, out);
@@ -5273,7 +5456,7 @@ async function cmdIndex(values, positionals) {
   const [action, ...rest] = positionals;
   const { path, home } = indexOf(values);
   if (action === "path") {
-    if (values.json) json3({ store: storeLocation({ path }), sources: join25(home, SOURCES_FILE), scans: join25(home, SCANS_LOG) });
+    if (values.json) json3({ store: storeLocation({ path }), sources: join26(home, SOURCES_FILE), scans: join26(home, SCANS_LOG) });
     else print(storeLocation({ path }));
     return 0;
   }
@@ -5444,15 +5627,23 @@ async function cmdLibrary(values, positionals) {
 async function cmdSync(values) {
   const p = await loadProject(values.project ?? process.cwd(), { ...loadOptions(values), refreshDesign: true });
   const result = await syncProject(p, { dryRun: values["dry-run"], adopt: values.adopt });
-  if (values.json) json3(result);
+  if (values.json) json3({ actions: result.actions, lock: result.lock, unknownTools: result.unknownTools });
   else print([renderSync(result, values["dry-run"]), ...p.linked ? [style.warn(`! linked: the design system is your checkout ${p.linked}, not the config's source (youiyoux unlink to undo)`)] : []].join("\n"));
   return result.actions.some((a) => a.action === "conflict") ? 1 : 0;
 }
+async function cmdUpgrade(values) {
+  if (values.to !== void 0 && !/^[\w][\w./-]*$/.test(values.to)) throw new UsageError(`--to ${JSON.stringify(values.to)}: expected a git tag, branch or commit`);
+  const p = await loadProject(values.project ?? process.cwd(), { ...loadOptions(values), refreshDesign: true, ...values.to !== void 0 ? { ref: values.to } : {} });
+  const result = await upgradeProject(p, { write: values.write, ...values.to !== void 0 ? { to: values.to } : {} });
+  if (values.json) json3(result);
+  else print([renderUpgrade(result, values.diff || result.status === "preview"), ...p.linked ? [style.warn(`! linked: the design system is your checkout ${p.linked}, not the config's source (youiyoux unlink to undo)`)] : []].join("\n"));
+  return result.status === "blocked" ? 1 : 0;
+}
 async function cmdInit(values) {
   if (!values.design) throw new UsageError("youiyoux init --design <dir|package>   (a design repo checkout, the directory holding youi.config.json, or the npm package that holds it)");
   const root = values.project ?? process.cwd();
   const design = await designArg(values.design, root);
-  const result = await initProject({ root, ...design, schemaDir: join25(TOOL_ROOT, "schema"), ...values.system ? { system: values.system } : {}, ...values.components ? { componentsDir: values.components } : {}, force: values.force });
+  const result = await initProject({ root, ...design, schemaDir: join26(TOOL_ROOT, "schema"), ...values.system ? { system: values.system } : {}, ...values.components ? { componentsDir: values.components } : {}, force: values.force });
   if (!values.json) {
     print(`${style.ok("created")} ${result.file}`);
     for (const note of result.notes) print(style.dim(`  \xB7 ${note}`));
@@ -5463,27 +5654,27 @@ async function cmdInit(values) {
 }
 async function cmdAdopt(values) {
   const root = resolve15(values.project ?? process.cwd());
-  if (await exists(join25(root, PROJECT_FILE))) throw new Error(`${root} already has ${PROJECT_FILE}: it follows a design system already (youiyoux sync updates it)`);
+  if (await exists(join26(root, PROJECT_FILE))) throw new Error(`${root} already has ${PROJECT_FILE}: it follows a design system already (youiyoux sync updates it)`);
   const plan = await planAdoption({ root, ...values.components ? { componentsDir: values.components } : {}, ...values.css ? { css: values.css } : {}, ...values.system ? { system: values.system } : {}, fork: values.fork });
-  const taken = (await Promise.all(plan.files.map(async (f) => await exists(join25(root, f.path)) ? f.path : null))).filter((f) => f !== null);
+  const taken = (await Promise.all(plan.files.map(async (f) => await exists(join26(root, f.path)) ? f.path : null))).filter((f) => f !== null);
   if (taken.length > 0) throw new Error(`nothing was written: ${taken.slice(0, 5).join(", ")}${taken.length > 5 ? ` and ${taken.length - 5} more` : ""} already exist${taken.length === 1 ? "s" : ""}`);
   if (values["dry-run"]) {
     if (values.json) json3(plan);
     else print([...adoptLines(plan, true), "", style.dim(`dry run: nothing written; would write ${plan.files.map((f) => f.path).join(", ")}${plan.stylesheet ? ` and change ${plan.stylesheet.path}` : ""}`)].join("\n"));
     return 0;
   }
-  const stylesheet = plan.stylesheet ? await readFile10(join25(root, plan.stylesheet.path), "utf8") : null;
+  const stylesheet = plan.stylesheet ? await readFile10(join26(root, plan.stylesheet.path), "utf8") : null;
   try {
-    for (const file of plan.files) await writeFileAtomic(join25(root, file.path), file.content);
-    if (plan.stylesheet) await writeFileAtomic(join25(root, plan.stylesheet.path), plan.stylesheet.content);
-    await initProject({ root, design: root, schemaDir: join25(TOOL_ROOT, "schema"), system: plan.system.id, componentsDir: plan.componentsDir, outputs: { ...plan.outputs, targets: [...plan.outputs.targets], dark: [...plan.outputs.dark] }, tokenSources: plan.tokenSources });
+    for (const file of plan.files) await writeFileAtomic(join26(root, file.path), file.content);
+    if (plan.stylesheet) await writeFileAtomic(join26(root, plan.stylesheet.path), plan.stylesheet.content);
+    await initProject({ root, design: root, schemaDir: join26(TOOL_ROOT, "schema"), system: plan.system.id, componentsDir: plan.componentsDir, outputs: { ...plan.outputs, targets: [...plan.outputs.targets], dark: [...plan.outputs.dark] }, tokenSources: plan.tokenSources });
     await syncProject(await loadProject(root), { dryRun: true });
   } catch (error) {
-    for (const file of [...plan.files.map((f) => f.path), PROJECT_FILE]) await rm6(join25(root, file), { force: true });
-    for (const folder of [...new Set(plan.files.map((f) => dirname13(f.path)))].sort((a, b) => b.length - a.length)) await rmdir3(join25(root, folder)).catch(() => void 0);
-    await rmdir3(join25(root, "design/components")).catch(() => void 0);
-    await rmdir3(join25(root, "design")).catch(() => void 0);
-    if (plan.stylesheet && stylesheet !== null) await writeFileAtomic(join25(root, plan.stylesheet.path), stylesheet);
+    for (const file of [...plan.files.map((f) => f.path), PROJECT_FILE]) await rm7(join26(root, file), { force: true });
+    for (const folder of [...new Set(plan.files.map((f) => dirname13(f.path)))].sort((a, b) => b.length - a.length)) await rmdir3(join26(root, folder)).catch(() => void 0);
+    await rmdir3(join26(root, "design/components")).catch(() => void 0);
+    await rmdir3(join26(root, "design")).catch(() => void 0);
+    if (plan.stylesheet && stylesheet !== null) await writeFileAtomic(join26(root, plan.stylesheet.path), stylesheet);
     throw new Error(`adopt was undone, nothing kept: ${error instanceof Error ? error.message : String(error)}`);
   }
   if (!values.json) print([...adoptLines(plan), ""].join("\n"));
@@ -5557,7 +5748,7 @@ async function cmdUnlink(values) {
 }
 async function designArg(value, root) {
   if (existsSync5(resolve15(value)) || !PACKAGE_NAME.test(value)) return { design: value };
-  return { design: await designRootOf({ package: value }, join25(resolve15(root), PROJECT_FILE), root), package: value };
+  return { design: await designRootOf({ package: value }, join26(resolve15(root), PROJECT_FILE), root), package: value };
 }
 async function cmdBuild(values) {
   const root = resolve15(values.design ?? process.cwd());
@@ -5566,10 +5757,10 @@ async function cmdBuild(values) {
   const output = OutputConfig.parse({ cssVarPrefix: values.prefix ?? "youi", targets: ["css-vars", "tailwind-v4", "ts", "react-native"] });
   const started = performance.now();
   const built = await buildTokens(root, system.config, output, { contracts: system.components.map((c) => c.contract) });
-  const out = resolve15(values.out ?? join25(root, "build", system.config.id));
-  const boundary = values.out ? out : join25(root, "build");
-  if (!within(boundary, out) || built.files.some((file) => !within(out, join25(out, file.path)))) throw new Error(`Cannot build system ${JSON.stringify(system.config.id)}: an output path leaves the output directory.`);
-  for (const file of built.files) await writeFileAtomic(join25(out, file.path), file.content);
+  const out = resolve15(values.out ?? join26(root, "build", system.config.id));
+  const boundary = values.out ? out : join26(root, "build");
+  if (!within(boundary, out) || built.files.some((file) => !within(out, join26(out, file.path)))) throw new Error(`Cannot build system ${JSON.stringify(system.config.id)}: an output path leaves the output directory.`);
+  for (const file of built.files) await writeFileAtomic(join26(out, file.path), file.content);
   if (values.json) json3({ out, files: built.files.map((f) => f.path), tokens: built.tokens.length });
   else print(`${style.ok("built")} ${plural(built.tokens.length, "token")} \u2192 ${built.files.map((f) => f.path).join(", ")} ${style.dim(`in ${out} (${ms(performance.now() - started)})`)}`);
   return 0;
@@ -5594,16 +5785,16 @@ async function cmdParity(values) {
 async function cmdSchema(values) {
   const schemas = renderJsonSchemas();
   if (values.check) {
-    const dir = join25(values.design ? resolve15(values.design) : TOOL_ROOT, "schema");
+    const dir = join26(values.design ? resolve15(values.design) : TOOL_ROOT, "schema");
     const stale = [];
-    for (const { file, content } of schemas) if (await readFile10(join25(dir, file), "utf8").catch(() => null) !== content) stale.push(file);
+    for (const { file, content } of schemas) if (await readFile10(join26(dir, file), "utf8").catch(() => null) !== content) stale.push(file);
     if (values.json) json3({ dir, stale });
     else print(stale.length === 0 ? `${style.ok("\u2713")} ${dir} matches this youi's schemas` : `${style.error("\u2716")} out of date in ${dir}: ${stale.join(", ")}; run youiyoux schema --write${values.design ? " --design <dir>" : ""}`);
     return stale.length === 0 ? 0 : 1;
   }
   if (values.write) {
     const root = values.design ? resolve15(values.design) : TOOL_ROOT;
-    for (const { file, content } of schemas) await writeFileAtomic(join25(root, "schema", file), content);
+    for (const { file, content } of schemas) await writeFileAtomic(join26(root, "schema", file), content);
     print(`${style.ok("wrote")} ${schemas.map((s) => s.file).join(", ")}`);
   } else json3(Object.fromEntries(schemas.map((s) => [s.file, JSON.parse(s.content)])));
   return 0;
@@ -5626,7 +5817,7 @@ async function cmdHooks(values, positionals) {
   if (action !== "install") throw new UsageError("youiyoux hooks install [--claude] [--git] [--ci [--diff]] [--strict]   or   youiyoux hooks run claude|pre-commit");
   const p = await loadCheckProject(values.project ?? process.cwd(), loadOptions(values), !values.project);
   if (values.ci && !configured(p)) throw new UsageError("Run youiyoux init --design <dir> before installing the pinned CI workflow; repo-mode CI can run youiyoux check --diff <base> --strict directly");
-  const target = { ...hookTarget(values), project: p.root, ...configured(p) && p.configFile && p.configFile !== join25(p.root, PROJECT_FILE) ? { config: p.configFile } : {}, ...values.root !== void 0 ? { root: p.root } : {} };
+  const target = { ...hookTarget(values), project: p.root, ...configured(p) && p.configFile && p.configFile !== join26(p.root, PROJECT_FILE) ? { config: p.configFile } : {}, ...values.root !== void 0 ? { root: p.root } : {} };
   const all = !values.claude && !values.git && !values.ci;
   const results = [];
   if (values.claude || all) results.push({ kind: "Claude Code", ...await installClaudeHook(await repoRootOf(p.root), hookCommand(TOOL_ROOT, "claude", target)) });
@@ -5645,7 +5836,7 @@ async function cmdAgents(values, positionals) {
   const repoRoot = await repoRootOf(projectRoot);
   const target = { project: projectRoot, ...values.config ? { config: resolve15(values.config) } : {}, ...values.design ? { design: resolve15(values.design) } : {}, ...values.root !== void 0 ? { root: resolve15(values.root || ".") } : {} };
   const server = mcpCommand(TOOL_ROOT, target);
-  const system = existsSync5(resolve15(values.config ?? join25(projectRoot, PROJECT_FILE))) ? await project(values) : null;
+  const system = existsSync5(resolve15(values.config ?? join26(projectRoot, PROJECT_FILE))) ? await project(values) : null;
   const claudeServer = system && system.root === repoRoot ? { command: "node", args: mcpArgs(system) } : relativeTo(repoRoot, server);
   const both = !values.claude && !values.codex;
   const results = [];
@@ -5787,7 +5978,7 @@ async function cmdRequests(values, positionals) {
   const usage = "youiyoux requests [--status open|addressed|closed|all] [--route r]   or   youiyoux requests show <id> | reply <id> --message <text> | addressed <id> --message <what you changed>";
   const [action, id, ...rest] = positionals;
   if (rest.length > 0) throw new UsageError(usage);
-  const { RequestStore, requestBrief } = await import("./src-EUVBYTKY.js");
+  const { RequestStore, requestBrief } = await import("./src-6SNQVIZS.js");
   const { project: project2, root } = await product(values);
   const store = new RequestStore(root, project2?.config.id ?? basename5(root));
   const agent = { kind: "agent", name: "youiyoux CLI" };
@@ -5820,8 +6011,8 @@ async function cmdScreens(values, positionals, io) {
   if (!["capture", "login"].includes(positionals[0] ?? "") || positionals.length > 1 || !values.base) throw new UsageError(usage);
   const { root } = await product(values);
   if (positionals[0] === "login") return screensLogin(values.base, values["storage-state"] ? resolve15(values["storage-state"]) : sessionFile(root), io);
-  const dir = resolve15(values.out ?? join25(root, ".youi/screens"));
-  if (!existsSync5(join25(dir, "screens.json"))) {
+  const dir = resolve15(values.out ?? join26(root, ".youi/screens"));
+  if (!existsSync5(join26(dir, "screens.json"))) {
     process.stderr.write(`${style.error("\u2716")} no screens.json in ${dir}: list the routes to capture there, as {"schema":"youiyoux.screens/v1","project":"<name>","source":"<what the app is>","capturedAt":"","viewport":{"width":1440,"height":900},"screens":[{"route":"/","path":"/"}]}
 `);
     return 1;
@@ -5886,7 +6077,7 @@ async function cmdReport(values, positionals, io) {
   return result.code;
 }
 async function cmdMcp(values) {
-  const { startStdioServer } = await import("./src-YKPJ3PII.js");
+  const { startStdioServer } = await import("./src-75ODGHE3.js");
   await startStdioServer({ projectRoot: values.project ?? process.cwd(), ...loadOptions(values), ...values.cache ? { discoverCache: values.cache } : {} });
   return -1;
 }
@@ -5961,6 +6152,7 @@ var COMMANDS = {
   rules: cmdRules,
   plan: cmdPlan,
   migrate: cmdMigrate,
+  upgrade: cmdUpgrade,
   init: cmdInit,
   sync: cmdSync,
   scan: cmdScan,
@@ -6012,7 +6204,7 @@ ${HELP}
   }
   return guarded(() => handler(located(command2, parsed.values), rest, io));
 }
-var IN_A_PRODUCT = /* @__PURE__ */ new Set(["system", "link", "unlink", "show", "where", "bom", "check", "baseline", "rules", "plan", "migrate", "sync", "scan", "watch", "hooks", "agents", "mcp", "ui", "library", "render", "screens", "requests"]);
+var IN_A_PRODUCT = /* @__PURE__ */ new Set(["system", "link", "unlink", "show", "where", "bom", "check", "baseline", "rules", "plan", "migrate", "upgrade", "sync", "scan", "watch", "hooks", "agents", "mcp", "ui", "library", "render", "screens", "requests"]);
 var IN_A_DESIGN_REPO = /* @__PURE__ */ new Set(["build", "parity"]);
 function located(command2, values, cwd = process.cwd()) {
   if (IN_A_PRODUCT.has(command2) && values.project === void 0 && values.config === void 0 && values.root === void 0) {

package/dist/chunks/{chunk-Y4IBE6WS.js → chunk-OCZJ3JGH.js}

@@ -9,7 +9,7 @@ import {
   scanProject,
   screenSlug,
   tokenImpact
-} from "./chunk-3HON5Q5K.js";
+} from "./chunk-X2YYMHR4.js";
 import {
   buildTokens,
   contrastText,

package/dist/chunks/{chunk-DCBF7QQY.js → chunk-T3KNPVQG.js}

@@ -3,7 +3,7 @@ import { createRequire as __youiRequire } from "node:module"; import { dirname a
 // src/hub-packages.js
 var PACKAGES = {
   core: () => import("./src-BYNWPNRT.js"),
-  scanner: () => import("./src-M3OJMCUE.js"),
+  scanner: () => import("./src-XTNHB65M.js"),
   discover: () => import("./src-DPFJ4S2N.js"),
   tokens: () => import("./src-PURAHRCR.js")
 };

package/dist/chunks/{chunk-3HON5Q5K.js → chunk-X2YYMHR4.js}

@@ -751,7 +751,13 @@ async function loadProject(root, options = {}) {
   const productRoot = options.productRoot !== void 0 ? resolve2(options.productRoot || ".") : config.root ? fromConfig(config.root) : resolve2(root);
   if (!await isDirectory2(productRoot)) throw new ProjectRootError(`product root ${productRoot} is not a directory (config ${configFile}); ${ROOT_HINT}`);
   const linked = options.designRoot ? null : await linkedDesign(productRoot);
-  const located = options.designRoot || linked ? { root: resolve2(options.designRoot || linked), commit: null } : await locateDesign(config.source, configFile, productRoot, { refresh: options.refreshDesign });
+  if (options.ref !== void 0) {
+    if (options.designRoot || linked) throw new Error(`the design system is ${options.designRoot ? "the --design folder" : `your checkout ${linked}`}, not the config's source: check out ${options.ref} there${linked ? ", or youiyoux unlink" : ""}`);
+    if ("package" in config.source) throw new Error(`${config.source.package} is an npm package: install the version you want (npm install ${config.source.package}@<version>), then run this again without --to`);
+    if ("path" in config.source) throw new Error(`the design system is the folder ${config.source.path}: check out ${options.ref} there, then run this again without --to`);
+  }
+  const source = options.ref !== void 0 && "git" in config.source ? { ...config.source, ref: options.ref } : config.source;
+  const located = options.designRoot || linked ? { root: resolve2(options.designRoot || linked), commit: null } : await locateDesign(source, configFile, productRoot, { refresh: options.refreshDesign || options.ref !== void 0 });
   const repo = await loadDesignRepo(located.root);
   return {
     root: productRoot,
@@ -2408,7 +2414,7 @@ async function parseAll(project, files, overrides, parse3) {
 }
 async function scanProject(project, options = {}) {
   const started = performance.now();
-  const overrides = options.overrides ?? {};
+  const overrides = { ...project.staged, ...options.overrides };
   const { cache } = options;
   cache?.beginScan();
   const parse3 = cache?.parse ?? parseModule;

package/dist/chunks/{src-EUVBYTKY.js → src-6SNQVIZS.js}

@@ -57,8 +57,8 @@ import {
   validateContent,
   validateLibraryContent,
   validateStyleContent
-} from "./chunk-Y4IBE6WS.js";
-import "./chunk-3HON5Q5K.js";
+} from "./chunk-OCZJ3JGH.js";
+import "./chunk-X2YYMHR4.js";
 import "./chunk-42YJX3W5.js";
 import "./chunk-FLBRX6Y3.js";
 import "./chunk-DWYDHVLZ.js";

package/dist/chunks/{src-YKPJ3PII.js → src-75ODGHE3.js}

@@ -2,7 +2,7 @@ import { createRequire as __youiRequire } from "node:module"; import { dirname a
 import {
   RequestStore,
   requestBrief
-} from "./chunk-Y4IBE6WS.js";
+} from "./chunk-OCZJ3JGH.js";
 import {
   PROJECT_FILE,
   ScanCache,
@@ -30,7 +30,7 @@ import {
   shotsText,
   tokenRows,
   whereUsed
-} from "./chunk-3HON5Q5K.js";
+} from "./chunk-X2YYMHR4.js";
 import "./chunk-42YJX3W5.js";
 import {
   SHADCN_SLOTS,

package/dist/chunks/{src-M3OJMCUE.js → src-XTNHB65M.js}

@@ -188,7 +188,7 @@ import {
   whyNoLines,
   withFile,
   withoutCredentials
-} from "./chunk-3HON5Q5K.js";
+} from "./chunk-X2YYMHR4.js";
 import {
   escapingLinks,
   relativeInside,

package/dist/hub-previews.js

@@ -16,8 +16,8 @@ import {
   selectCandidates,
   thumbsDir,
   writeThumbIndex
-} from "./chunks/chunk-F33PKGES.js";
-import "./chunks/chunk-DCBF7QQY.js";
+} from "./chunks/chunk-3RP664IP.js";
+import "./chunks/chunk-T3KNPVQG.js";
 import "./chunks/chunk-FVVL5JCY.js";
 import "./chunks/chunk-DWYDHVLZ.js";
 import "./chunks/chunk-WNTS7ZO4.js";

package/dist/hub-server.js

@@ -2,7 +2,7 @@
 import { createRequire as __youiRequire } from "node:module"; import { dirname as __youiDir } from "node:path"; import { fileURLToPath as __youiPath } from "node:url"; const require = __youiRequire(import.meta.url); const __youiDirname = __youiDir(__youiPath(import.meta.url));
 import {
   discoverThumbsMiddleware
-} from "./chunks/chunk-F33PKGES.js";
+} from "./chunks/chunk-3RP664IP.js";
 import {
   isLocalHost,
   loadPackage,
@@ -10,7 +10,7 @@ import {
   readTryIndex,
   send,
   tryMiddleware
-} from "./chunks/chunk-DCBF7QQY.js";
+} from "./chunks/chunk-T3KNPVQG.js";
 import "./chunks/chunk-FVVL5JCY.js";
 import "./chunks/chunk-DWYDHVLZ.js";
 import "./chunks/chunk-WNTS7ZO4.js";

package/dist/hub-snapshot.js

@@ -3,7 +3,7 @@ import { createRequire as __youiRequire } from "node:module"; import { dirname a
 import {
   loadPackage,
   tryProject
-} from "./chunks/chunk-DCBF7QQY.js";
+} from "./chunks/chunk-T3KNPVQG.js";
 import "./chunks/chunk-FVVL5JCY.js";
 import "./chunks/chunk-WNTS7ZO4.js";
 

package/dist/youi.js

@@ -2,8 +2,8 @@
 import { createRequire as __youiRequire } from "node:module"; import { dirname as __youiDir } from "node:path"; import { fileURLToPath as __youiPath } from "node:url"; const require = __youiRequire(import.meta.url); const __youiDirname = __youiDir(__youiPath(import.meta.url));
 import {
   main
-} from "./chunks/chunk-E5OHZJBS.js";
-import "./chunks/chunk-3HON5Q5K.js";
+} from "./chunks/chunk-75DBKEAH.js";
+import "./chunks/chunk-X2YYMHR4.js";
 import "./chunks/chunk-42YJX3W5.js";
 import "./chunks/chunk-HDJ2TOWZ.js";
 import "./chunks/chunk-6GITMASZ.js";

package/dist/youiyoux.js

@@ -3,8 +3,8 @@ import { createRequire as __youiRequire } from "node:module"; import { dirname a
 import {
   COMMAND_NAMES,
   main
-} from "./chunks/chunk-E5OHZJBS.js";
-import "./chunks/chunk-3HON5Q5K.js";
+} from "./chunks/chunk-75DBKEAH.js";
+import "./chunks/chunk-X2YYMHR4.js";
 import "./chunks/chunk-42YJX3W5.js";
 import "./chunks/chunk-HDJ2TOWZ.js";
 import "./chunks/chunk-6GITMASZ.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "youiyoux",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Your agent rebuilds components you already have. youiyoux catches it: npx youiyoux turns any repo into a shareable report of near-duplicate components, hardcoded token values and off-library imports, with the fixes.",
   "license": "MIT",
   "repository": {
@@ -46,9 +46,9 @@
     "typescript": "6.0.3"
   },
   "devDependencies": {
-    "@youiyoux/cli": "0.1.9",
-    "@youiyoux/core": "0.1.9",
-    "@youiyoux/scanner": "0.1.9"
+    "@youiyoux/cli": "0.1.10",
+    "@youiyoux/core": "0.1.10",
+    "@youiyoux/scanner": "0.1.10"
   },
   "exports": {
     "./package.json": "./package.json"