@motujs/cli 0.0.0-stage → 0.1.0

package/src/commands/skills.mjs

@@ -0,0 +1,156 @@
+// `motu skills install [dir]` — install the motu agent skills into a target repo.
+//
+// The skills are the JUDGEMENT half of motu (island-extract / island-create); the CLI is the
+// deterministic half. A repo that uses motu needs both, in whatever format its coding agent reads.
+// One source, two emitted formats — so they can never drift:
+//
+//   .github/agents/<name>.agent.md    (source of truth: frontmatter name/description + body)
+//     ├─ .github/agents/<name>.agent.md    GitHub Copilot custom agent   (verbatim copy)
+//     ├─ .github/prompts/<name>.prompt.md  Copilot slash-prompt          (verbatim copy, if present)
+//     └─ .claude/skills/<name>/SKILL.md    Claude Code skill             (generated from the agent)
+//
+// Deliberately config-free: this verb installs INTO a repo that may not be a motu project yet, so it
+// never reads motu.config.json and never touches the island layout.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { color, HOST_ROOT } from '../lib/util.mjs';
+import { applyHostRules } from '../lib/host-rules.mjs';
+import { frameworkFile } from '../lib/framework.mjs';
+
+/**
+ * Where the skills are read from: the checkout's `.github/`, or — installed from npm — the copy
+ * shipped inside @motujs/cli. They used to be read from `<cli>/../../.github` unconditionally, which
+ * from `node_modules/@motujs/cli` is `node_modules/.github`: nothing there, `discover()` returned an
+ * empty list, and `motu init` installed ZERO skills while printing a rules block that tells the
+ * agent to load them.
+ */
+const SRC_AGENTS = frameworkFile('.github/agents');
+const SRC_PROMPTS = frameworkFile('.github/prompts');
+const MOTU_ROOT = dirname(dirname(SRC_AGENTS));
+
+/** Parse a leading `---` YAML-ish frontmatter block into { data, body, raw }. */
+function frontmatter(raw) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
+  if (!m) return { data: {}, body: raw, raw };
+  const data = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (kv) data[kv[1]] = kv[2].trim();
+  }
+  return { data, body: raw.slice(m[0].length), raw };
+}
+
+/** The skills shipped by this motu checkout, newest source first. */
+function discover() {
+  if (!existsSync(SRC_AGENTS)) return [];
+  return readdirSync(SRC_AGENTS)
+    .filter((f) => f.endsWith('.agent.md'))
+    .sort()
+    .map((file) => {
+      const agentPath = resolve(SRC_AGENTS, file);
+      const raw = readFileSync(agentPath, 'utf8');
+      const { data, body } = frontmatter(raw);
+      const name = data.name ?? file.replace(/\.agent\.md$/, '');
+      const promptPath = resolve(SRC_PROMPTS, `${name}.prompt.md`);
+      return {
+        name,
+        description: data.description ?? '',
+        agent: { path: agentPath, raw },
+        prompt: existsSync(promptPath) ? { path: promptPath, raw: readFileSync(promptPath, 'utf8') } : null,
+        body,
+      };
+    });
+}
+
+/** A Claude Code SKILL.md: the same body, under the frontmatter keys Claude reads. */
+function skillMd(skill) {
+  const description = skill.description.replace(/\r?\n/g, ' ').trim();
+  return `---\nname: ${skill.name}\ndescription: ${description}\n---\n${skill.body.replace(/^\n*/, '\n')}`;
+}
+
+function put(path, contents, out) {
+  const rel = relative(out.root, path);
+  if (existsSync(path)) {
+    if (readFileSync(path, 'utf8') === contents) return out.same.push(rel);
+    if (!out.force) return out.skipped.push(rel);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, contents);
+    return out.updated.push(rel);
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, contents);
+  out.created.push(rel);
+}
+
+/**
+ * Write the shipped skills into `root` — never over a file that differs unless `force` (it is reported
+ * as skipped). Shared by `motu skills install` and `motu init`: the short motu rules POINT AT these
+ * skills, so a project that has the rules must have them too.
+ */
+export function installSkills(root, { force = false, only = 'both' } = {}) {
+  const skills = discover();
+  const out = { root, force, created: [], updated: [], same: [], skipped: [] };
+  for (const skill of skills) {
+    if (only !== 'claude') {
+      put(resolve(root, '.github/agents', `${skill.name}.agent.md`), skill.agent.raw, out);
+      if (skill.prompt) put(resolve(root, '.github/prompts', `${skill.name}.prompt.md`), skill.prompt.raw, out);
+    }
+    if (only !== 'copilot') {
+      put(resolve(root, '.claude/skills', skill.name, 'SKILL.md'), skillMd(skill), out);
+    }
+  }
+  return { skills, out };
+}
+
+export async function skillsInstallCommand(argv) {
+  const root = resolve(process.cwd(), argv._[0] ?? '.');
+  const only = argv.only ?? 'both'; // both | claude | copilot
+  if (!['both', 'claude', 'copilot'].includes(only)) {
+    console.error(color.red(`✗ --only must be one of: both, claude, copilot (got "${only}")`));
+    process.exit(2);
+  }
+  if (discover().length === 0) {
+    console.error(color.red(`✗ no skills found in ${SRC_AGENTS} — is this a complete motu checkout?`));
+    process.exit(1);
+  }
+  const { skills, out } = installSkills(root, { force: Boolean(argv.force), only });
+
+  if (argv.json) {
+    console.log(JSON.stringify({ root, source: MOTU_ROOT, skills: skills.map((s) => s.name), ...out }, null, 2));
+    return process.exit(out.skipped.length > 0 ? 1 : 0);
+  }
+
+  console.log(color.bold(`motu skills → ${root}`) + color.dim(`  (source: ${MOTU_ROOT})`));
+  for (const p of out.created) console.log('  ' + color.green('+ ') + p);
+  for (const p of out.updated) console.log('  ' + color.yellow('~ ') + p);
+  for (const p of out.same) console.log('  ' + color.dim('= ' + p));
+  for (const p of out.skipped) console.log('  ' + color.red('! ') + p + color.dim(' (differs — use --force to overwrite)'));
+  console.log('');
+  // The skills are the judgement half; the rules are the standing instructions that go with them, so
+  // installing one installs the other. `motu init` does the same for a fresh project.
+  // The rules belong to the HOST application — that is where the coding agent's instruction file
+  // lives. Writing them beside the motu project (which is often a subfolder) created a second
+  // CLAUDE.md nothing reads.
+  const rules = applyHostRules(HOST_ROOT);
+
+  console.log(color.green(`✓ ${skills.length} skill(s): ${skills.map((s) => s.name).join(', ')}`));
+  for (const p of rules) console.log('  ' + color.dim(p) + color.dim(' (motu rules block)'));
+  if (out.skipped.length) {
+    console.log(color.yellow(`  ${out.skipped.length} file(s) left untouched — rerun with --force to overwrite`));
+    process.exit(1);
+  }
+  // Name what was actually installed — a hardcoded pair goes stale the day a skill is added.
+  console.log('Use them: ' + skills.map((s) => color.bold(`/${s.name}`)).join(', ') + color.dim(' (Claude Code skill or Copilot agent/prompt)'));
+}
+
+export async function skillsListCommand(argv) {
+  const skills = discover();
+  if (argv.json) {
+    console.log(JSON.stringify(skills.map(({ name, description }) => ({ name, description })), null, 2));
+    return;
+  }
+  for (const s of skills) {
+    console.log(color.bold(s.name));
+    console.log('  ' + color.dim(s.description));
+  }
+}

package/src/commands/snapshot.mjs

@@ -0,0 +1,456 @@
+// `motu island snapshot <name|--all> [--update]` — record or check an island's visual baselines.
+//
+// Without `--update` it CHECKS: capture every declared scenario × viewport and compare to what is
+// committed. With `--update` it records, which is a deliberate, separate act — a baseline should change
+// because someone decided the UI should, never as a side effect of running the checks.
+//
+// The failure artifacts matter as much as the verdict: on a difference it writes `.actual.png` and
+// `.diff.png` beside the baseline, so the answer to "what changed?" is an image, not a percentage.
+import { existsSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { color, paths, names, lagoonViewports } from '../lib/util.mjs';
+import { listIslands } from '../lib/islands.mjs';
+import { readRegions } from '../lib/eject.mjs';
+import { readScenarios } from './verify.mjs';
+import { changedScope } from '../lib/changed.mjs';
+import { captureLagoon, captureRegionLagoon } from '../playwright-lagoon.mjs';
+import { resolveBaselineHost, putShot, fetchShot, acceptShots, listShots, writeRemoteArtifacts } from '../lib/baselines.mjs';
+import {
+  compareBuffers,
+  compareSnapshot,
+  orphanBaselines,
+  snapshotDir,
+  snapshotName,
+  writeBaseline,
+  writeFailureArtifacts,
+} from '../lib/snapshots.mjs';
+
+/** The island's declared scenarios, or a single default state. */
+async function scenariosFor(kebab) {
+  const file = paths.fixturesFile(kebab);
+  if (!existsSync(file)) return [];
+  let viaNode = [];
+  try {
+    const mod = await import(`file://${file}?t=${Date.now()}`);
+    viaNode = Array.isArray(mod.scenarios) ? mod.scenarios : [];
+  } catch {
+    /* handled by the cross-check below */
+  }
+  // TWO LOADERS FOR ONE FILE, and they disagree in silence — the exact failure `islandVerify` already
+  // had to fix. A plain node import cannot resolve a `.js` specifier pointing at a `.ts` sibling,
+  // which is the convention every evidence file here uses the moment it shares a fixture module. This
+  // returned [] and the island was pictured ONCE, in its default state, while `data-flow` (which
+  // loads through tsx) saw every scenario. Four new islands were baselined at half their coverage
+  // before the shot count gave it away. Cross-check, and take the fuller answer.
+  const viaTsx = readScenarios(file);
+  return viaTsx.length > viaNode.length ? viaTsx : viaNode;
+}
+
+async function snapshotIsland(argv, kebab, host) {
+  const { tag } = names(kebab);
+  const viewports = lagoonViewports();
+  const scenarios = await scenariosFor(kebab);
+  const dir = snapshotDir(paths.islandsDir, kebab);
+  const port = 5300 + Math.floor(Math.random() * 400);
+
+  let shots;
+  try {
+    shots = await captureLagoon({ tag, port, scenarios, viewports });
+  } catch (err) {
+    return { kebab, error: err.message, results: [] };
+  }
+
+  const results = [];
+  for (const shot of shots) {
+    const file = snapshotName(shot.scenario, shot.viewport);
+    const baseline = resolve(dir, file);
+
+    // THE HOST DECIDES. It knows what was accepted; this run only knows what it rendered. `new` is not
+    // a failure — it is the first sight of a shot, waiting for someone to accept it.
+    if (host) {
+      let sent;
+      try {
+        sent = await putShot(host, kebab, file, shot.png);
+      } catch (err) {
+        return { kebab, error: err.message, results: [] };
+      }
+      if (sent.status !== 'changed') {
+        results.push({ file, status: sent.status === 'match' ? 'match' : 'new', hash: sent.hash });
+        continue;
+      }
+      // Differed: fetch the accepted bytes and show it, rather than report a percentage.
+      const acceptedPng = await fetchShot(host, sent.accepted);
+      const cmp = acceptedPng ? await compareBuffers(acceptedPng, shot.png) : { status: 'changed', diffPixels: 0, ratio: 1 };
+      const artifact = writeRemoteArtifacts(kebab, file, shot.png, cmp.diff);
+      results.push({ file, ...cmp, status: cmp.status === 'new' ? 'changed' : cmp.status, artifact });
+      continue;
+    }
+
+    if (argv.update) {
+      writeBaseline(dir, file, shot.png);
+      results.push({ file, status: existsSync(baseline) ? 'updated' : 'recorded' });
+      continue;
+    }
+    const cmp = await compareSnapshot(baseline, shot.png);
+    if (cmp.status === 'changed' || cmp.status === 'resized') {
+      writeFailureArtifacts(dir, file, shot.png, cmp.diff);
+    } else if (cmp.status === 'new') {
+      writeBaseline(dir, file, shot.png);
+    }
+    results.push({ file, ...cmp });
+  }
+  // Orphans are a question about FILES: with the host owning baselines there is nothing to be orphaned.
+  const orphans = host ? [] : orphanBaselines(dir, shots.map((s) => snapshotName(s.scenario, s.viewport)));
+  return { kebab, dir, results, orphans };
+}
+
+
+/**
+ * Narrow a sweep to what this branch touched — the same flag, and the same discipline, as `motu check`.
+ *
+ * A full island sweep is 89s and a full region sweep 18s on a 20-island project, which is the cost of
+ * a punctual gate, not of a loop. Scoped to one island and its region it is seconds, which is the
+ * difference between a check an agent runs on the way past and one it learns to skip.
+ *
+ * NARROWING IS NEVER SILENT: `changedScope` widens back to everything the moment a file cannot be
+ * attributed, and says why. And nothing examined is NOT a pass — a sweep that pictured no island
+ * proves nothing about the project, so it exits 2 rather than printing green, the same rule this
+ * repository keeps having to reinstate in whichever flag exists to examine less.
+ */
+function scopeTargets(argv, all, pick) {
+  if (argv.changed === undefined) return { targets: all, scope: null };
+  const scope = changedScope(typeof argv.changed === 'string' ? argv.changed : undefined);
+  if (!scope.scoped) {
+    console.log(color.dim(`  --changed: running everything — ${scope.reason}`));
+    return { targets: all, scope };
+  }
+  return { targets: all.filter((id) => pick(scope).includes(id)), scope };
+}
+
+/** The shared verdict for a scoped run that found nothing to do. */
+function nothingToPicture(kind) {
+  console.log('');
+  console.log(
+    color.yellow(color.bold('NOTHING TO PICTURE')) +
+      color.dim(`  no ${kind} changed — this run proves nothing about the project`),
+  );
+  process.exit(2);
+}
+
+export async function snapshotCommand(argv) {
+  const name = argv._[0];
+  const wantsHost = argv.remote !== undefined || argv.accept !== undefined;
+  const host = wantsHost ? resolveBaselineHost(argv) : null;
+  if (wantsHost && !host) {
+    console.error(color.red('✗ no lagoon host — pass --remote <url>, set MOTU_HOST_URL, or write ~/.config/motu/host.json'));
+    process.exit(1);
+  }
+
+  // ACCEPT IS ITS OWN ACT. Not a flag on a checking run: "the UI should look like this now" is a
+  // decision, and running it as a side effect of a check is exactly what `--update` got wrong.
+  if (argv.accept !== undefined) {
+    const island = typeof argv.accept === 'string' ? names(argv.accept).kebab : name ? names(name).kebab : null;
+    let out;
+    try {
+      out = await acceptShots(host, island);
+    } catch (err) {
+      console.error(color.red(`✗ ${err.message}`));
+      process.exit(1);
+    }
+    if (argv.json) {
+      console.log(JSON.stringify({ ok: true, ...out }, null, 2));
+      process.exit(0);
+    }
+    console.log('');
+    console.log(
+      out.count
+        ? `${color.green('✓')} accepted ${out.count} shot(s)\n${out.accepted.map((a) => color.dim(`  ${a}`)).join('\n')}`
+        : color.dim('nothing to accept — every shot already matches what was accepted'),
+    );
+    process.exit(0);
+  }
+
+  if (!name && !argv.all) {
+    console.error('usage: motu island snapshot <name|--all> [--update|--remote] [--accept] [--json]');
+    process.exit(2);
+  }
+  if (host && argv.update) {
+    console.error(color.red('✗ --update writes files; --remote stores on the host. Use --remote then --accept.'));
+    process.exit(2);
+  }
+  const allIslands = listIslands(paths.islandsDir).map((i) => i.kebab);
+  const { targets, scope } = argv.all
+    ? scopeTargets(argv, allIslands, (sc) => sc.islands)
+    : { targets: [names(name).kebab], scope: null };
+  if (scope?.scoped) {
+    console.log(color.dim(`  --changed: ${targets.length}/${allIslands.length} island(s) — from ${scope.files} changed file(s)`));
+    if (!targets.length) nothingToPicture('island');
+  }
+
+  const all = [];
+  for (const kebab of targets) all.push(await snapshotIsland(argv, kebab, host));
+
+  const failed = all.filter((r) => r.error || r.results.some((x) => x.status === 'changed' || x.status === 'resized'));
+
+  if (argv.json) {
+    console.log(JSON.stringify({ pass: failed.length === 0, islands: all }, null, 2));
+    process.exit(failed.length === 0 ? 0 : 1);
+  }
+
+  console.log(
+    color.bold(
+      `\nmotu island snapshot — ${argv.update ? 'recording' : 'checking'} ${targets.length} island(s)` +
+        (host ? color.dim(`  against ${host.base} · ${host.id.repo}`) : '') +
+        '\n',
+    ),
+  );
+  for (const island of all) {
+    if (island.error) {
+      console.log(`  ${color.red('✗')} ${color.dim(island.kebab.padEnd(20))} ${color.red(island.error)}`);
+      continue;
+    }
+    const changed = island.results.filter((r) => r.status === 'changed' || r.status === 'resized');
+    const fresh = island.results.filter((r) => r.status === 'new' || r.status === 'recorded');
+    const mark = changed.length ? color.red('✗') : fresh.length ? color.yellow('+') : color.green('✓');
+    const tally = changed.length
+      ? color.red(`${changed.length} changed`)
+      : color.dim(`${island.results.length} shot(s)${fresh.length ? `, ${fresh.length} new` : ''}`);
+    console.log(`  ${mark} ${color.dim(island.kebab.padEnd(20))} ${tally}`);
+    for (const r of changed) {
+      const detail =
+        r.status === 'resized'
+          ? `size ${r.from?.join('×')} → ${r.to?.join('×')}`
+          : `${r.diffPixels} px (${(r.ratio * 100).toFixed(2)}%)`;
+      console.log(`      ${color.red('✗')} ${color.dim(r.file.padEnd(28))} ${detail}`);
+      // `--remote` writes its artifacts under `.motu/`, not beside the evidence — print where they
+      // ACTUALLY are, or the one instruction this output gives points at a file that does not exist.
+      const artifact = r.artifact ?? resolve(island.dir, r.file.replace(/\.png$/, '.diff.png'));
+      console.log(`        ${color.dim(relative(process.cwd(), artifact))}`);
+    }
+    for (const f of island.orphans ?? []) {
+      console.log(`      ${color.yellow('!')} ${color.dim(f.padEnd(28))} baseline with no scenario behind it`);
+    }
+  }
+  console.log('');
+  // NEW SHOTS ARE NOT A PASS — they are a screen nobody has looked at.
+  //
+  // Every "LOOK at it" in the rules is conditioned on a DIFFERENCE, and a first baseline has none by
+  // construction: the run goes green and says nothing. That is the one moment looking matters most,
+  // and it is the moment nothing asked for it. Twice in two days a brand-new region shipped a defect
+  // no check could see — a fixture inventing a vocabulary the app does not use, and an island
+  // stylesheet that was bundled and never applied — and both times a human had to prompt the look.
+  //
+  // `accepted` is already the record that somebody looked. So the pending count is the number of
+  // states nobody has, and this says so rather than printing "every baseline matches" over 83 of them.
+  const fresh = all.reduce((n, i) => n + i.results.filter((r) => r.status === 'new').length, 0);
+  console.log(
+    failed.length === 0
+      ? (fresh
+          ? color.yellow(color.bold('LOOK')) +
+            color.dim(
+              `  ${fresh} shot(s) nobody has looked at${host ? ` — open the lagoon, then accept: motu island snapshot --accept <name>` : ''}`,
+            )
+          : color.green(color.bold('PASS')) + color.dim(argv.update ? '  baselines written' : '  every baseline matches'))
+      : color.red(color.bold('FAIL')) +
+        color.dim(
+          `  ${failed.length} island(s) changed — look at the .diff.png, then ` +
+            (host ? '`motu island snapshot --accept <island>` if intended' : '`--update` if intended'),
+        ),
+  );
+  process.exit(failed.length === 0 ? 0 : 1);
+}
+
+
+/**
+ * The states a region can be pictured in — its flows' seeds.
+ *
+ * A region declares no `scenarios`; it declares FLOWS, and each one opens by seeding the state it
+ * needs. That seed list is the honest answer to "which shapes does this page take", and it is the
+ * answer to the case a single picture misses: an actions page with an empty week is a different PAGE,
+ * not a different value. A shape no flow seeds is an evidence gap — the same finding `render-coverage`
+ * makes — and closing it with a flow is worth doing for its own sake.
+ */
+async function regionStates(id) {
+  const file = paths.archipelagoEvidence(id);
+  if (!existsSync(file)) return [];
+  try {
+    const mod = await import(`file://${file}?t=${Date.now()}`);
+    const flows = Array.isArray(mod.scenarios) ? mod.scenarios : [];
+    const seen = new Set();
+    const out = [];
+    for (const f of flows) {
+      const name = f.name ?? 'flow';
+      // Two flows that start from the same state are one picture, not two.
+      const key = JSON.stringify(f.seed ?? {});
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ name, seed: f.seed ?? {} });
+    }
+    return out;
+  } catch {
+    // Evidence is TypeScript in most projects; node cannot load it. One picture of the default state
+    // is still worth having — it just cannot be named after the flow that would have seeded it.
+    return [];
+  }
+}
+
+async function snapshotRegion(argv, id, host) {
+  const viewports = lagoonViewports();
+  const states = await regionStates(id);
+  const port = 5300 + Math.floor(Math.random() * 400);
+  const dir = snapshotDir(paths.archipelagosDir, id);
+
+  let shots;
+  try {
+    shots = await captureRegionLagoon({ id, port, states, viewports });
+  } catch (err) {
+    return { kebab: id, error: err.message, results: [] };
+  }
+
+  const results = [];
+  for (const shot of shots) {
+    const file = snapshotName(shot.scenario, shot.viewport);
+    if (host) {
+      let sent;
+      try {
+        sent = await putShot(host, `region-${id}`, file, shot.png);
+      } catch (err) {
+        return { kebab: id, error: err.message, results: [] };
+      }
+      if (sent.status !== 'changed') {
+        results.push({ file, status: sent.status === 'match' ? 'match' : 'new' });
+        continue;
+      }
+      const acceptedPng = await fetchShot(host, sent.accepted);
+      const cmp = acceptedPng ? await compareBuffers(acceptedPng, shot.png) : { status: 'changed', diffPixels: 0, ratio: 1 };
+      const artifact = writeRemoteArtifacts(`region-${id}`, file, shot.png, cmp.diff);
+      results.push({ file, ...cmp, status: cmp.status === 'new' ? 'changed' : cmp.status, artifact });
+      continue;
+    }
+    const baseline = resolve(dir, file);
+    if (argv.update) {
+      writeBaseline(dir, file, shot.png);
+      results.push({ file, status: existsSync(baseline) ? 'updated' : 'recorded' });
+      continue;
+    }
+    const cmp = await compareSnapshot(baseline, shot.png);
+    if (cmp.status === 'changed' || cmp.status === 'resized') writeFailureArtifacts(dir, file, shot.png, cmp.diff);
+    else if (cmp.status === 'new') writeBaseline(dir, file, shot.png);
+    results.push({ file, ...cmp });
+  }
+  return { kebab: id, dir, results, orphans: [], members: readRegions(paths.archipelagosDir).find((r) => r.id === id)?.islands ?? [] };
+}
+
+
+/**
+ * `motu archipelago snapshot <id|--all>` — picture the composed page.
+ *
+ * ATTRIBUTION IS THE POINT, and it is what makes a page-level diff usable rather than noise. Any island
+ * edit changes the region picture, so on its own this signal churns and people stop accepting it. But
+ * the islands are separately baselined here, so a region diff can be explained: when a member island
+ * changed too, the region changed BECAUSE of it. A region diff with NO member changed is an
+ * ARRANGEMENT regression — the class no island shot can see, and the one that shipped once already.
+ */
+export async function archipelagoSnapshotCommand(argv) {
+  const name = argv._[0];
+  const wantsHost = argv.remote !== undefined || argv.accept !== undefined;
+  const host = wantsHost ? resolveBaselineHost(argv) : null;
+  if (wantsHost && !host) {
+    console.error(color.red('✗ no lagoon host — pass --remote <url>, set MOTU_HOST_URL, or write ~/.config/motu/host.json'));
+    process.exit(1);
+  }
+  if (argv.accept !== undefined) {
+    const island = typeof argv.accept === 'string' ? `region-${argv.accept}` : name ? `region-${name}` : null;
+    const out = await acceptShots(host, island).catch((err) => {
+      console.error(color.red(`✗ ${err.message}`));
+      process.exit(1);
+    });
+    console.log(out.count ? `${color.green('✓')} accepted ${out.count} shot(s)` : color.dim('nothing to accept'));
+    process.exit(0);
+  }
+  if (!name && !argv.all) {
+    console.error('usage: motu archipelago snapshot <id|--all> [--update|--remote] [--accept] [--json]');
+    process.exit(2);
+  }
+  const allRegions = readRegions(paths.archipelagosDir).map((r) => r.id);
+  // A changed ISLAND is a changed region here: the region's picture is its members composed, so an
+  // island edit moves it even when no file under archipelagos/ was touched. `changedScope` already
+  // maps islands to the regions that declare them.
+  const { targets, scope } = argv.all ? scopeTargets(argv, allRegions, (sc) => sc.regions) : { targets: [name], scope: null };
+  if (scope?.scoped) {
+    console.log(color.dim(`  --changed: ${targets.length}/${allRegions.length} region(s) — from ${scope.files} changed file(s)`));
+    if (!targets.length) nothingToPicture('region');
+  }
+
+  const all = [];
+  for (const id of targets) all.push(await snapshotRegion(argv, id, host));
+
+  // Which member islands ALSO differ, so a region diff can be explained instead of just reported.
+  let changedIslands = new Set();
+  let comparedIslands = new Set();
+  if (host) {
+    try {
+      const body = await listShots(host);
+      changedIslands = new Set(body.shots.filter((x) => x.status === 'changed').map((x) => x.island));
+      // An island with NO accepted baseline can never report `changed`, so "no member changed" would
+      // be true of an island nobody has ever compared. Claiming ARRANGEMENT on that is the check
+      // reporting a conclusion it did not examine.
+      comparedIslands = new Set(body.shots.filter((x) => x.accepted).map((x) => x.island));
+    } catch {
+      /* attribution is a nicety; its absence must not fail the run */
+    }
+  }
+
+  const failed = all.filter((r) => r.error || r.results.some((x) => x.status === 'changed' || x.status === 'resized'));
+  if (argv.json) {
+    console.log(JSON.stringify({ pass: failed.length === 0, regions: all }, null, 2));
+    process.exit(failed.length === 0 ? 0 : 1);
+  }
+
+  console.log(color.bold(`\nmotu archipelago snapshot — ${targets.length} region(s)${host ? color.dim(`  against ${host.base}`) : ''}\n`));
+  for (const region of all) {
+    if (region.error) {
+      console.log(`  ${color.red('✗')} ${color.dim(region.kebab.padEnd(20))} ${color.red(region.error)}`);
+      continue;
+    }
+    const changed = region.results.filter((r) => r.status === 'changed' || r.status === 'resized');
+    const fresh = region.results.filter((r) => r.status === 'new' || r.status === 'recorded');
+    const mark = changed.length ? color.red('✗') : fresh.length ? color.yellow('+') : color.green('✓');
+    console.log(
+      `  ${mark} ${color.dim(region.kebab.padEnd(20))} ` +
+        (changed.length ? color.red(`${changed.length} changed`) : color.dim(`${region.results.length} shot(s)${fresh.length ? `, ${fresh.length} new` : ''}`)),
+    );
+    for (const r of changed) {
+      const detail = r.status === 'resized' ? `size ${r.from?.join('×')} → ${r.to?.join('×')}` : `${r.diffPixels} px (${(r.ratio * 100).toFixed(2)}%)`;
+      console.log(`      ${color.red('✗')} ${color.dim(r.file.padEnd(28))} ${detail}`);
+      if (r.artifact) console.log(`        ${color.dim(relative(process.cwd(), r.artifact))}`);
+    }
+    if (changed.length) {
+      const members = (region.members ?? []).map((m) => m.element?.replace(/^x-/, '') ?? '').filter(Boolean);
+      const guilty = members.filter((k) => changedIslands.has(k));
+      const uncompared = members.filter((k) => !comparedIslands.has(k));
+      console.log(
+        guilty.length
+          ? color.dim(`        members that also changed: ${guilty.join(', ')} — the region changed because they did`)
+          : uncompared.length
+            ? color.dim(
+                `        cannot attribute: ${uncompared.length}/${members.length} member(s) have no accepted baseline ` +
+                  `(${uncompared.slice(0, 4).join(', ')}${uncompared.length > 4 ? '…' : ''}) — accept them and re-run to tell ` +
+                  `an arrangement change from an island one`,
+              )
+            : color.yellow('        no member island changed — this is the ARRANGEMENT, which nothing else checks'),
+      );
+    }
+  }
+  console.log('');
+  const freshRegions = all.reduce((n, r) => n + r.results.filter((x) => x.status === 'new').length, 0);
+  console.log(
+    failed.length === 0
+      ? (freshRegions
+          ? color.yellow(color.bold('LOOK')) +
+            color.dim(`  ${freshRegions} shot(s) nobody has looked at — open the region view before accepting`)
+          : color.green(color.bold('PASS')))
+      : color.red(color.bold('FAIL')) + color.dim(`  ${failed.length} region(s) changed`),
+  );
+  process.exit(failed.length === 0 ? 0 : 1);
+}

package/src/commands/sync.mjs

@@ -0,0 +1,38 @@
+// `motu sync` — regenerate everything motu derives from the files on disk and the config.
+//
+// ONE VERB, because the derived files are one kind of thing: never edited by hand, and stale is a
+// build error. There used to be two — `island sync` (the element registry and the contracts) and
+// `archipelago sync` (the region-side module coverage's deployment config lives in) — split by noun
+// so each command owned what it named. The split was right about ownership and wrong about use:
+// nobody runs half a regeneration on purpose, and running the half that was not stale left `motu
+// check` red with a message naming the other verb. `island sync` / `archipelago sync` still answer,
+// and run this.
+import { paths, color, names, islandComponentPath, islandComponentExport } from '../lib/util.mjs';
+import { syncRegistry } from '../lib/islands.mjs';
+import { syncContracts } from '../lib/contracts.mjs';
+import { syncArchipelagos } from '../lib/archipelagos.mjs';
+
+export function syncCommand() {
+  // The ISLAND side: the element registry and the contracts read from each component.
+  //
+  // Static imports in the registry rather than a glob, because the barrel that exports it is consumed
+  // by the host application's bundler, which has no `import.meta.glob`.
+  const { path, count } = syncRegistry(paths.islandsDir, paths.isolation);
+  console.log(`${paths.rel(path)} — ${count} island(s)`);
+  const contracts = syncContracts(paths.islandsDir, { islandComponentPath, islandComponentExport, names });
+  console.log(`${paths.rel(contracts.path)} — ${contracts.count} contract(s)${contracts.changed ? '' : ' (unchanged)'}`);
+
+  // The REGION side: coverage's deployment config. It names regions (`regions: ["actions"]`), so it
+  // is generated beside the archipelagos, not baked into the island registry it once rode in.
+  const regions = syncArchipelagos(paths.archipelagosDir, paths.coverage);
+  const wanted = paths.coverage?.regions;
+  const state = regions.enabled
+    ? `coverage on for ${!wanted ? 'every region (no `regions` declared)' : wanted.includes('*') ? 'every region (*)' : wanted.join(', ')}`
+    : 'coverage off — an empty module, so nothing names @motujs/coverage';
+  console.log(`${paths.rel(regions.path)} — ${state}`);
+  if (regions.registry === 'import added') {
+    console.log(color.dim(`  added the import to ${paths.rel(paths.archipelagosDir)}/registry.ts`));
+  } else if (regions.registry === 'no registry') {
+    console.log(color.yellow(`  ! no registry.ts in ${paths.rel(paths.archipelagosDir)} — nothing imports this module, so it will not run`));
+  }
+}