@cparkerwebm/webmonterey 1.0.0

package/src/cli/slug.ts

@@ -0,0 +1,109 @@
+/*
+ * Turning a domain into the names everything else uses.
+ *
+ * TWO NAMES, DELIBERATELY DIFFERENT.
+ *
+ *   GitHub repo        <domain_underscored>   webmonterey/autire_com
+ *   Cloudflare stuff   webm-<slug>            webm-autire, webm-autire-db, webm-autire-media
+ *
+ * The repo keeps the full domain so it is unambiguous which site it serves. Cloudflare drops the
+ * TLD token because `webm-autire-com` contains `autire-com`, which Chrome's lookalike check reads
+ * as a registrable domain - and every preview link then warns the client the site looks fake.
+ * `webm-autire` has nothing in it that looks like a domain. See ARCHITECTURE.md section 5.
+ */
+
+/** Public suffixes that take two labels, so `example.co.uk` slugs to `example`. */
+const TWO_PART_SUFFIXES = new Set([
+  'co.uk',
+  'org.uk',
+  'ac.uk',
+  'gov.uk',
+  'me.uk',
+  'net.uk',
+  'sch.uk',
+  'com.au',
+  'net.au',
+  'org.au',
+  'edu.au',
+  'gov.au',
+  'co.nz',
+  'net.nz',
+  'org.nz',
+  'com.br',
+  'com.mx',
+  'co.za',
+  'co.jp',
+  'co.in',
+  'com.sg',
+]);
+
+export class DomainError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DomainError';
+  }
+}
+
+/** Strip scheme, www, path and trailing dots. `https://www.Example.com/` -> `example.com` */
+export function normalizeDomain(input: string): string {
+  const cleaned = input
+    .trim()
+    .toLowerCase()
+    .replace(/^[a-z]+:\/\//, '')
+    .replace(/\/.*$/, '')
+    .replace(/^www\./, '')
+    .replace(/\.+$/, '');
+
+  if (!cleaned || !cleaned.includes('.')) {
+    throw new DomainError(`"${input}" is not a domain. Expected something like example.com.`);
+  }
+  if (!/^[a-z0-9.-]+$/.test(cleaned)) {
+    throw new DomainError(`"${input}" contains characters a hostname cannot.`);
+  }
+  return cleaned;
+}
+
+/**
+ * The GitHub repo name. Dots become UNDERSCORES: `autire.com` -> `autire_com`.
+ *
+ * Underscores, not dashes, and not the slug. Three names, three jobs:
+ *
+ *   repo       autire_com     the full domain, unambiguous about which site this is
+ *   slug       autire         no TLD, because a Cloudflare Worker named webm-autire-com
+ *                             embeds autire-com and Chrome reads that as a domain
+ *   worker     webm-autire    the slug, prefixed
+ *
+ * A rebuild creates a NEW repo under the underscore name beside the old dashed one, which is what
+ * lets the old site keep serving until the cutover.
+ */
+export function repoName(domain: string): string {
+  return normalizeDomain(domain).replace(/\./g, '_');
+}
+
+/**
+ * The client slug - the domain with its public suffix removed.
+ *
+ * `autire.com` -> `autire`, `example.co.uk` -> `example`. Subdomains are kept, because
+ * `shop.example.com` and `example.com` are different clients if they are ever both ours.
+ */
+export function slugFor(domain: string): string {
+  const clean = normalizeDomain(domain);
+  const parts = clean.split('.');
+  const lastTwo = parts.slice(-2).join('.');
+  const drop = TWO_PART_SUFFIXES.has(lastTwo) ? 2 : 1;
+  const kept = parts.slice(0, Math.max(1, parts.length - drop));
+  return kept.join('-');
+}
+
+/** Every Cloudflare resource name for a site, from one domain. */
+export function resourceNames(domain: string) {
+  const slug = slugFor(domain);
+  return {
+    slug,
+    repo: repoName(domain),
+    worker: `webm-${slug}`,
+    d1: `webm-${slug}-db`,
+    r2Media: `webm-${slug}-media`,
+    r2App: `webm-${slug}-app`,
+  };
+}

package/src/cli/sync.test.ts

@@ -0,0 +1,137 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readdirSync,
+  existsSync,
+  readFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { sync } from './sync.ts';
+
+const site = () => mkdtempSync(join(tmpdir(), 'webm-sync-'));
+
+test('materializes a skills-directory plugin at .claude/skills/webm/', () => {
+  const root = site();
+  sync(root);
+  const target = join(root, '.claude/skills/webm');
+  assert.ok(existsSync(join(target, '.claude-plugin/plugin.json')));
+  const manifest = JSON.parse(readFileSync(join(target, '.claude-plugin/plugin.json'), 'utf8'));
+  // The folder name IS the namespace - this is what makes skills /webm:go-live.
+  assert.equal(manifest.name, 'webm');
+});
+
+test('writes a version marker the doctor reads', () => {
+  const root = site();
+  const result = sync(root);
+  const marker = JSON.parse(
+    readFileSync(join(root, '.claude/skills/webm/.webm-sync.json'), 'utf8'),
+  );
+  assert.equal(marker.version, result.version);
+  assert.ok(marker.skills.includes('launch'));
+});
+
+test('the package ships exactly the skills the release claims', () => {
+  const root = site();
+  const result = sync(root);
+  assert.deepEqual([...result.added].sort(), [
+    'launch',
+    'new-component',
+    'start',
+    'traps',
+    'upgrade',
+  ]);
+});
+
+test('agents/ and hooks/ ride along when the package ships any, and never as empty dirs', () => {
+  // Empty in the package today. The mechanism is what is asserted: a .gitkeep is not an agent.
+  const root = site();
+  const result = sync(root);
+  assert.deepEqual(result.agents, []);
+  assert.deepEqual(result.hooks, []);
+  assert.ok(!existsSync(join(root, '.claude/skills/webm/agents')), 'no empty agents/ in a site');
+});
+
+test('dotfiles are not copied - .DS_Store would otherwise reach every client repo', () => {
+  const root = site();
+  sync(root);
+  const copied = readdirSync(join(root, '.claude/skills/webm/skills'));
+  assert.deepEqual(
+    copied.filter((f) => f.startsWith('.')),
+    [],
+  );
+});
+
+test('a full replace removes a skill that no longer ships', () => {
+  const root = site();
+  sync(root);
+  // Simulate a skill that existed in an older version.
+  mkdirSync(join(root, '.claude/skills/webm/skills/retired'), { recursive: true });
+  writeFileSync(
+    join(root, '.claude/skills/webm/skills/retired/SKILL.md'),
+    '---\nname: retired\n---\n',
+  );
+
+  const second = sync(root);
+  assert.ok(second.removed.includes('retired'), 'a deleted skill must disappear, not linger');
+  assert.ok(!existsSync(join(root, '.claude/skills/webm/skills/retired')));
+});
+
+test('a client skill placed BESIDE the plugin survives a sync', () => {
+  const root = site();
+  mkdirSync(join(root, '.claude/skills/add-event'), { recursive: true });
+  writeFileSync(join(root, '.claude/skills/add-event/SKILL.md'), '---\nname: add-event\n---\n');
+
+  sync(root);
+  // Siblings are untouched. Inside .claude/skills/webm/ they would be destroyed - which is why
+  // the gitignore comment says client skills go beside it.
+  assert.ok(existsSync(join(root, '.claude/skills/add-event/SKILL.md')));
+});
+
+test('scripts/ is REPLACED, because a fix to the Node guard must reach every site', () => {
+  const dir = site();
+  mkdirSync(join(dir, 'scripts'), { recursive: true });
+  writeFileSync(join(dir, 'scripts', 'check-node.mjs'), '// stale, from v1\n');
+  const result = sync(dir);
+
+  assert.ok(result.scripts.includes('check-node.mjs'), 'check-node.mjs is package-owned');
+  assert.ok(result.scripts.includes('test-hooks.mjs'), 'test-hooks.mjs is package-owned');
+  const written = readFileSync(join(dir, 'scripts', 'check-node.mjs'), 'utf8');
+  assert.ok(!written.includes('stale, from v1'), 'the stale copy was overwritten');
+  assert.match(written, /npm_config_user_agent/, 'the real guard landed');
+});
+
+test('a migration is copied when absent and NEVER rewritten once it exists', () => {
+  /*
+   * The one that would be a data bug rather than a cosmetic one. D1 records an applied
+   * migration by filename; rewriting the file does not re-run it, so an "upgrade" that edits
+   * 0001 changes local and leaves production on the old schema, with nothing to show for it.
+   */
+  const dir = site();
+  const first = sync(dir);
+  assert.ok(first.migrations.includes('0001_create_submissions.sql'), 'seeded on a fresh site');
+  assert.match(
+    readFileSync(join(dir, 'migrations', '0001_create_submissions.sql'), 'utf8'),
+    /CREATE TABLE/,
+  );
+
+  const applied = '-- already applied to production, hands off\n';
+  writeFileSync(join(dir, 'migrations', '0001_create_submissions.sql'), applied);
+  const second = sync(dir);
+
+  assert.deepEqual(second.migrations, [], 'nothing re-copied on the second sync');
+  assert.equal(
+    readFileSync(join(dir, 'migrations', '0001_create_submissions.sql'), 'utf8'),
+    applied,
+    'the applied migration is untouched',
+  );
+});
+
+test('the migrations README rides along, so the --remote trap is documented in the repo', () => {
+  const dir = site();
+  sync(dir);
+  assert.match(readFileSync(join(dir, 'migrations', 'README.md'), 'utf8'), /--remote/);
+});

package/src/cli/sync.ts

@@ -0,0 +1,266 @@
+/*
+ * `webm sync` - materialize the fleet skills into .claude/skills/webm/.
+ *
+ * CLAUDE CODE DOES NOT READ SKILLS OUT OF node_modules. Discovery is directory-based - personal,
+ * project, nested, plugin - and an npm package is none of those. A skills/ folder inside the
+ * installed package is inert: Claude never looks, the skill never appears, and nothing errors.
+ *
+ * The destination is a SKILLS-DIRECTORY PLUGIN. Any folder under .claude/skills/ containing
+ * .claude-plugin/plugin.json loads as `<folder>@skills-dir` on the next session, with no
+ * marketplace and no install step, discovered in place rather than copied to a cache. Naming the
+ * folder `webm` is what makes these `/webm:launch` - namespaced, so they can never collide with
+ * a client's own skills, which sit BESIDE this directory at .claude/skills/<name>/. The same
+ * folder carries the package's agents/ and hooks/ when it ships any; a client's own agents go in
+ * .claude/agents/, untouched by this.
+ *
+ * FULL REPLACE, NEVER A MERGE. A skill deleted in a later version has to disappear here too,
+ * which is why this directory is gitignored and exclusively package-owned. A client skill placed
+ * inside it would be destroyed on the next install.
+ *
+ * THREE KINDS OF PACKAGE-OWNED FILE ON DISK, and the difference matters:
+ *
+ *   REPLACE   skills/, agents/, hooks/, scripts/, the CI workflow
+ *                                  Regenerated every install. Pure infrastructure that a client
+ *                                  never edits, so overwriting is free and a fix propagates.
+ *   ADD-ONLY  migrations/          Copied only when absent. A migration that has been applied to
+ *                                  a real D1 database must NEVER change - SQLite has already run
+ *                                  it and wrangler tracks it by name. Later versions add 0002,
+ *                                  they do not rewrite 0001.
+ *   SEED      public/, content     Written once by `webm new` and then the client's outright.
+ *                                  Not handled here at all - see cli/scaffold.ts.
+ *
+ * Anything that is a starting point a client will edit belongs in SEED. Putting it in REPLACE
+ * throws their work away on the next `npm update`, silently.
+ *
+ * Wired from the CLIENT's package.json, so it is visible in the repo rather than a dependency
+ * writing outside its own tree behind your back:
+ *
+ *     "scripts": { "postinstall": "webm sync" }
+ */
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+  readdirSync,
+} from 'node:fs';
+import { basename, join } from 'node:path';
+import { PACKAGE_ROOT, packageVersion } from './package-root.ts';
+
+/**
+ * The namespace. Rule 5's prefix: the CLI is `webm`, the tokens are --webm-*, the classes are
+ * .webm-*, the Workers are webm-<slug>. `/webm:launch` rather than `/webmonterey:launch`.
+ */
+const NAMESPACE = 'webm';
+
+interface SyncResult {
+  added: string[];
+  removed: string[];
+  unchanged: string[];
+  version: string;
+  /** Agent definitions and hook files copied into the plugin, when the package ships any. */
+  agents: string[];
+  hooks: string[];
+  /** Files refreshed under REPLACE, relative to the site root. */
+  scripts: string[];
+  workflows: string[];
+  /** Migrations copied because the site did not have them. Never includes an existing file. */
+  migrations: string[];
+}
+
+/**
+ * REPLACE. Overwrite unconditionally from the package.
+ *
+ * `scripts/` holds two files that cannot live in node_modules:
+ *
+ *   check-node.mjs   runs as `preinstall`, which is BEFORE node_modules exists. A bin from an
+ *                    uninstalled package is not on PATH yet, so this one has to be on disk.
+ *   test-hooks.mjs   loaded with `node --import`, which resolves against the site, and is the
+ *                    thing that lets a client's own component tests import `./thing` without an
+ *                    extension the way the rest of the toolchain does.
+ *
+ * Both are dependency-free and neither has a client-specific line in it, so a full replace is
+ * the whole propagation story: fix a bug here and every site gets it on `npm update`.
+ */
+function syncDir(source: string, target: string): string[] {
+  if (!existsSync(source)) return [];
+  mkdirSync(target, { recursive: true });
+  const written: string[] = [];
+  for (const entry of readdirSync(source, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    if (!entry.isFile()) continue;
+    cpSync(join(source, entry.name), join(target, entry.name));
+    written.push(entry.name);
+  }
+  return written.sort();
+}
+
+/**
+ * ADD-ONLY. Copy what is missing and never touch what is there.
+ *
+ * A D1 migration is applied once and recorded by filename in the database's own
+ * d1_migrations table. Rewriting an applied file does not re-run it - the change simply never
+ * reaches production, and local and remote drift apart with nothing to show for it. So a later
+ * package version ships 0002 alongside, and this leaves 0001 exactly as the client has it.
+ */
+function addMissing(source: string, target: string): string[] {
+  if (!existsSync(source)) return [];
+  mkdirSync(target, { recursive: true });
+  const added: string[] = [];
+  for (const entry of readdirSync(source, { withFileTypes: true })) {
+    if (entry.name.startsWith('.') || !entry.isFile()) continue;
+    const dest = join(target, entry.name);
+    if (existsSync(dest)) continue;
+    cpSync(join(source, entry.name), dest);
+    added.push(entry.name);
+  }
+  return added.sort();
+}
+
+function listSkills(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, 'SKILL.md')))
+    .map((e) => e.name)
+    .sort();
+}
+
+export function sync(siteRoot: string): SyncResult {
+  const version = packageVersion();
+  const source = join(PACKAGE_ROOT, 'skills');
+  const target = join(siteRoot, '.claude', 'skills', NAMESPACE);
+
+  const before = listSkills(join(target, 'skills'));
+  const after = listSkills(source);
+
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(join(target, '.claude-plugin'), { recursive: true });
+
+  /*
+   * Filter dotfiles. On macOS `.DS_Store` is created in any directory Finder has opened, so
+   * without this it copies into every client repo AND ships in the npm tarball. Gitignored and
+   * harmless, but it is junk in someone else's repo with our name on it. The same filter is
+   * what lets agents/ and hooks/ hold a .gitkeep in the package and arrive empty in a site.
+   */
+  const noDotfiles = (src: string) => !basename(src).startsWith('.');
+  if (existsSync(source)) {
+    cpSync(source, join(target, 'skills'), { recursive: true, filter: noDotfiles });
+  }
+
+  /*
+   * THE PLUGIN'S OTHER COMPONENTS. A skills-directory plugin can carry agents/ (subagent
+   * definitions, invoked as webm:<name>) and hooks/hooks.json (event handlers that make a trap
+   * mechanical rather than advisory). Both ride along under the same REPLACE rule as skills/, and
+   * both need /reload-plugins in a running session - SKILL.md edits are picked up live, these are
+   * not. Empty in the package today; the mechanism is here so shipping one is a file, not a
+   * release of the sync command.
+   */
+  const plugin = (dir: string): string[] => {
+    const from = join(PACKAGE_ROOT, dir);
+    if (!existsSync(from)) return [];
+    const names = readdirSync(from).filter(noDotfiles).sort();
+    if (names.length) cpSync(from, join(target, dir), { recursive: true, filter: noDotfiles });
+    return names;
+  };
+  const agents = plugin('agents');
+  const hooks = plugin('hooks');
+
+  writeFileSync(
+    join(target, '.claude-plugin', 'plugin.json'),
+    JSON.stringify(
+      {
+        name: NAMESPACE,
+        description: 'WebMonterey fleet skills. Materialized by `webm sync` - do not edit here.',
+        version: version,
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+
+  /*
+   * A marker the doctor reads to tell whether the sync ran against the installed version.
+   * `npm install --ignore-scripts` skips postinstall silently, and the failure mode is a session
+   * with no fleet skills and no error to explain why.
+   */
+  writeFileSync(
+    join(target, '.webm-sync.json'),
+    JSON.stringify({ version: version, namespace: NAMESPACE, skills: after }, null, 2) + '\n',
+  );
+
+  const template = join(PACKAGE_ROOT, 'template');
+
+  return {
+    added: after.filter((s) => !before.includes(s)),
+    removed: before.filter((s) => !after.includes(s)),
+    unchanged: after.filter((s) => before.includes(s)),
+    version: version,
+    agents,
+    hooks,
+    scripts: syncDir(join(template, 'scripts'), join(siteRoot, 'scripts')),
+    /*
+     * CI, REPLACE-managed like scripts/. A site never edits its own workflow - if a leg is wrong
+     * it is wrong on every site, and it gets fixed here. Five sites once had no CI whatsoever,
+     * which is how code depending on an unpublished package reached main without a word.
+     */
+    workflows: syncDir(join(template, 'workflows'), join(siteRoot, '.github/workflows')),
+    migrations: addMissing(join(template, 'migrations'), join(siteRoot, 'migrations')),
+  };
+}
+
+/**
+ * Make sure the materialized directory is ignored.
+ *
+ * It is regenerated on every install, so committing it guarantees a conflict on every upgrade
+ * and a stale copy on every checkout.
+ */
+function ensureGitignored(siteRoot: string): boolean {
+  const path = join(siteRoot, '.gitignore');
+  const entry = `.claude/skills/${NAMESPACE}/`;
+  const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  if (current.includes(entry)) return false;
+  const addition =
+    `\n# Materialized by \`webm sync\` on every install. Package-owned; never commit.\n` +
+    `# Client skills go BESIDE it, at .claude/skills/<name>/.\n${entry}\n`;
+  writeFileSync(path, current.replace(/\n*$/, '\n') + addition);
+  return true;
+}
+
+export function run(argv: string[]): number {
+  const siteRoot = argv[0] ?? process.cwd();
+  const result = sync(siteRoot);
+
+  const total = result.added.length + result.unchanged.length;
+  console.log(`webm sync: ${total} skills at .claude/skills/${NAMESPACE}/ (v${result.version})`);
+  for (const s of result.added) console.log(`  + /${NAMESPACE}:${s}`);
+  for (const s of result.removed) console.log(`  - /${NAMESPACE}:${s}`);
+
+  if (result.agents.length) console.log(`  agents: ${result.agents.join(', ')}`);
+  if (result.hooks.length) console.log(`  hooks: ${result.hooks.join(', ')}`);
+  if (result.scripts.length) {
+    console.log(`  scripts/ refreshed: ${result.scripts.join(', ')}`);
+  }
+  for (const m of result.migrations) {
+    console.log(`  + migrations/${m}  (apply it: npx wrangler d1 migrations apply <DB> --remote)`);
+  }
+
+  if (ensureGitignored(siteRoot)) {
+    console.log(`  gitignored .claude/skills/${NAMESPACE}/`);
+  }
+
+  /*
+   * A new or removed SKILL.md is picked up live, within the session - Claude Code watches skill
+   * directories. Only the plugin's other components (agents/, hooks/, .mcp.json) need a reload,
+   * and the first-ever sync needs a restart because a watcher cannot watch a directory that did
+   * not exist when the session started.
+   */
+  if (result.added.length || result.removed.length) {
+    console.log(
+      `\nSkill changes are picked up live. If this was the first sync in this repo, restart ` +
+        `Claude Code so it can watch the new directory.`,
+    );
+  }
+  return 0;
+}

package/src/cli/upgrade.ts

@@ -0,0 +1,93 @@
+/*
+ * `webm upgrade` - move a site to a newer framework version.
+ *
+ * THE STEPS LIVE HERE, NOT IN THE SKILL. An invoked skill's rendered text enters the conversation
+ * once and is not re-read on later turns, so /webm:upgrade runs npm install, overwrites its own
+ * SKILL.md with the new version's, and keeps executing the OLD instructions to completion. The
+ * binary on disk is the new version the moment the install finishes; the markdown is frozen for
+ * the session. Anything version-specific therefore has to be here.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { codemodsBetween } from './codemods.ts';
+import { sync } from './sync.ts';
+import { packageName } from './package-root.ts';
+
+const PACKAGE = packageName();
+
+function git(siteRoot: string, args: string[]): string {
+  return execFileSync('git', args, { cwd: siteRoot, encoding: 'utf8' }).trim();
+}
+
+function installedVersion(siteRoot: string): string | null {
+  const path = join(siteRoot, 'node_modules', PACKAGE, 'package.json');
+  if (!existsSync(path)) return null;
+  return (JSON.parse(readFileSync(path, 'utf8')) as { version: string }).version;
+}
+
+export function run(argv: string[]): number {
+  const siteRoot = process.cwd();
+  const target = argv.find((a) => !a.startsWith('-')) ?? 'latest';
+  const dryRun = argv.includes('--dry-run');
+
+  if (!existsSync(join(siteRoot, 'webmonterey.json'))) {
+    console.error(`webm upgrade: no webmonterey.json here. Not a WebMonterey site.`);
+    return 1;
+  }
+
+  /*
+   * A dirty tree turns a failed upgrade into a mess with no clean revert. Refuse rather than
+   * stash - an automatic stash is a surprise nobody wants to discover later.
+   */
+  if (git(siteRoot, ['status', '--porcelain'])) {
+    console.error('webm upgrade: working tree is not clean. Commit or stash first.');
+    return 1;
+  }
+
+  const from = installedVersion(siteRoot);
+  console.log(`Installed: ${from ?? 'nothing'} -> ${target}`);
+  if (dryRun) {
+    console.log('--dry-run: stopping before any change.');
+    return 0;
+  }
+
+  const branch = `upgrade/${PACKAGE.split('/')[1]}-${target}`;
+  if (git(siteRoot, ['rev-parse', '--abbrev-ref', 'HEAD']) === 'main') {
+    git(siteRoot, ['checkout', '-b', branch]);
+    console.log(`Branched to ${branch}. Never upgrade on main.`);
+  }
+
+  execFileSync('npm', ['install', `${PACKAGE}@${target}`], { cwd: siteRoot, stdio: 'inherit' });
+  const to = installedVersion(siteRoot);
+  if (!to) {
+    console.error('webm upgrade: install did not produce a version. Check the npm output above.');
+    return 1;
+  }
+
+  const mods = codemodsBetween(from ?? '0.0.0', to);
+  if (mods.length) {
+    console.log(`\nRunning ${mods.length} codemod${mods.length === 1 ? '' : 's'}:`);
+    for (const mod of mods) {
+      const changes = mod.run(siteRoot);
+      console.log(`  ${mod.version} ${mod.title}`);
+      for (const c of changes) console.log(`      ${c}`);
+      if (!changes.length) console.log(`      nothing to change`);
+    }
+  }
+
+  const synced = sync(siteRoot);
+  console.log(`\nSkills re-materialized (v${synced.version})`);
+  for (const s of synced.added) console.log(`  + /webm:${s}`);
+  for (const s of synced.removed) console.log(`  - /webm:${s}`);
+
+  console.log(`\nNow, in order:`);
+  console.log(`  npx webm doctor`);
+  console.log(`  npm run check && npm run build`);
+  console.log(`  git push -u origin HEAD   # review the preview URL before merging`);
+  if (synced.added.length || synced.removed.length) {
+    console.log(`\nSkill changes are live already. Run /reload-plugins if anything outside`);
+    console.log(`skills/ changed - agents, hooks and .mcp.json are not picked up live.`);
+  }
+  return 0;
+}