mosaic-headless 1.2.0

package/bin/check-release.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Refuse to publish a package that does not hold together.
+ *
+ *   node bin/check-release.mjs
+ *
+ * Runs as `preversion` and again as `prepublishOnly`, so a release cannot be cut or
+ * pushed while any of this is false. Exits non-zero with the reason.
+ *
+ * The version number exists in three places - package.json, the SKILL.md
+ * frontmatter an agent reads, and the frontmatter each platform template writes on
+ * install. Nothing keeps them together on its own, and a skill that reports a
+ * version it is not is worse than one that reports none. `npm version` runs
+ * sync-version.mjs to write all three; this asserts it worked.
+ *
+ * It also checks that every path in package.json `files` exists, that the data files
+ * the skill's own claims rest on are present and non-trivial, and that the
+ * verification CSVs still say what SKILL.md says they say. The last one is the point:
+ * the headline numbers in the documentation are counted from the data at release
+ * time rather than trusted.
+ */
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const read = (p) => fs.readFileSync(path.join(ROOT, p), "utf8");
+const problems = [];
+const fail = (m) => problems.push(m);
+
+// ---------- versions agree --------------------------------------------------
+
+const pkg = JSON.parse(read("package.json"));
+const want = pkg.version;
+
+const skill = read("SKILL.md");
+const fmVersion = /^version:\s*"?([^"\n]+)"?\s*$/m.exec(skill.split("---")[1] || "");
+if (!fmVersion) fail("SKILL.md frontmatter has no version:");
+else if (fmVersion[1].trim() !== want)
+  fail(`SKILL.md version ${fmVersion[1].trim()} != package.json ${want}`);
+
+const platDir = path.join(ROOT, "assets", "templates", "platforms");
+for (const f of fs.readdirSync(platDir).filter((x) => x.endsWith(".json"))) {
+  const cfg = JSON.parse(fs.readFileSync(path.join(platDir, f), "utf8"));
+  const v = cfg.frontmatter?.version;
+  if (v !== undefined && v !== want) fail(`${f} frontmatter version ${v} != ${want}`);
+  if (JSON.stringify(cfg).includes("gutenberg-headless"))
+    fail(`${f} still names another skill`);
+}
+
+// ---------- everything the package claims to ship actually exists -----------
+
+// `files` entries are globs, not paths - a directory shipped whole is the mistake
+// this list exists to avoid, so the check has to understand `data/*.csv`.
+for (const entry of pkg.files) {
+  const star = entry.indexOf("*");
+  if (star === -1) {
+    if (!fs.existsSync(path.join(ROOT, entry)))
+      fail(`package.json files lists ${entry}, which does not exist`);
+    continue;
+  }
+  const dir = entry.slice(0, entry.lastIndexOf("/"));
+  const pattern = entry.slice(entry.lastIndexOf("/") + 1);
+  const quote = (x) => x.replace(/[-.+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp("^" + pattern.split("*").map(quote).join(".*") + "$");
+  const abs = path.join(ROOT, dir);
+  if (!fs.existsSync(abs) || !fs.readdirSync(abs).some((f) => re.test(f)))
+    fail(`package.json files lists ${entry}, which matches nothing`);
+}
+if (!fs.existsSync(path.join(ROOT, pkg.bin["mosaic-headless"])))
+  fail(`bin points at ${pkg.bin["mosaic-headless"]}, which does not exist`);
+
+// ---------- the numbers in the docs are counted, not trusted ----------------
+
+const rows = (p) => read(p).trim().split("\n").length - 1;   // minus the header
+const counts = {
+  "data/node-verification.csv": 122,
+  "data/style-verification.csv": 98,
+  "data/node-property-verification.csv": 181,
+  "data/rwd-verification.csv": 569,
+};
+for (const [file, expected] of Object.entries(counts)) {
+  if (!fs.existsSync(path.join(ROOT, file))) { fail(`${file} missing`); continue; }
+  const n = rows(file);
+  if (n !== expected) fail(`${file} has ${n} rows, SKILL.md claims ${expected}`);
+  if (!skill.includes(String(expected)))
+    fail(`SKILL.md never mentions ${expected}, but ${file} has that many rows`);
+}
+
+// a sweep whose own blind spots were folded into a pass rate is the failure this
+// skill argues against, so the labels have to survive into the shipped data
+const style = read("data/style-verification.csv");
+if (!style.includes("SKIPPED")) fail("style-verification.csv has no SKIPPED rows - "
+  + "blind spots should be labelled, not dropped");
+
+// ---------- nothing private ships -------------------------------------------
+
+// npm's `files` allowlist OVERRIDES .gitignore: naming a directory there ships
+// everything inside it, ignored or not. Listing `sites/` once put a real client's
+// page generator and content into the tarball - gitignored, and published anyway.
+// So the tarball is inspected rather than the intent trusted.
+let packed = "";
+try {
+  // execSync with one fixed command string: on Windows `npm` is npm.cmd, which
+  // execFileSync will not resolve, and passing an args array with shell:true is
+  // deprecated. Nothing here is interpolated, so there is nothing to escape.
+  packed = execSync("npm pack --dry-run --json",
+                    { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+} catch {
+  fail("could not run `npm pack --dry-run` to inspect the tarball");
+}
+if (packed) {
+  let files = [];
+  try {
+    files = (JSON.parse(packed)[0]?.files || []).map((f) => f.path.split("\\").join("/"));
+  } catch { fail("could not parse `npm pack --json` output"); }
+
+  const forbidden = [
+    [/^sites\/_zidanna/, "a real client's page generator"],
+    [/^sites\/zidanna\./, "a real client's content"],
+    [/^data\/raw\//, "raw capture dumps"],
+    [/__pycache__/, "python build artefacts"],
+    [/^shots\//, "screenshots"],
+    [/\.env|secret|credential/i, "something that looks like a secret"],
+  ];
+  for (const [re, what] of forbidden) {
+    const hit = files.filter((f) => re.test(f));
+    if (hit.length) fail(`tarball would ship ${what}: ${hit.slice(0, 3).join(", ")}`);
+  }
+  if (files.length === 0) fail("npm pack reported no files");
+  console.log(`tarball inspected: ${files.length} files, nothing forbidden`);
+}
+
+// ---------- report ----------------------------------------------------------
+
+if (problems.length) {
+  console.error(`release check failed (${problems.length}):`);
+  for (const p of problems) console.error("  - " + p);
+  process.exit(1);
+}
+console.log(`release check passed: v${want}, ${pkg.files.length} shipped paths, `
+  + `${Object.keys(counts).length} verification tables counted`);

package/bin/install.mjs

@@ -0,0 +1,452 @@
+#!/usr/bin/env node
+/**
+ * Install the mosaic-headless skill into any of 8 supported AI platforms.
+ *
+ *   npx mosaic-headless                       # interactive (arrow keys, zh-TW)
+ *   npx mosaic-headless --list
+ *   npx mosaic-headless claude-code --global
+ *   npx mosaic-headless cursor --to /path/to/project
+ *   npx mosaic-headless --dry-run claude-code
+ *
+ * Zero dependencies - colors, prompts and progress are hand-rolled so npx
+ * starts instantly. Python is NOT needed to install, only to run the skill's
+ * query/validation tools afterwards.
+ *
+ * Install types:
+ *   full                - SKILL.md + references/ + tools/ + data/ + sites/
+ *   rule                - single .md/.mdc rule file with embedded references
+ *   instructions-append - fenced section appended to copilot-instructions.md
+ *   zip-upload          - zip bundle for manual upload (Claude.ai)
+ *
+ * Exit codes: 0 = installed, 1 = failed, 2 = invocation error
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PLATFORMS = path.join(ROOT, "assets", "templates", "platforms");
+
+// ---------- colors (hand-rolled chalk) -------------------------------------
+
+const TTY = process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+const esc = (n) => (s) => (TTY ? `\x1b[${n}m${s}\x1b[0m` : s);
+const bold = esc("1"), dim = esc("2");
+const red = esc("1;31"), yellow = esc("1;33"), green = esc("1;32");
+const cyan = esc("1;36"), blue = esc("1;34"), magenta = esc("1;35");
+const gcyan = esc("36"), ggreen = esc("32");
+
+const die = (msg, code = 1) => { console.error(red("error"), msg); process.exit(code); };
+const info = (m) => console.log(blue("info"), m);
+const warn = (m) => console.log(yellow("warn"), m);
+const expand = (p) => (p && p.startsWith("~") ? path.join(os.homedir(), p.slice(1)) : p);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---------- the MOKSA banner ------------------------------------------------
+
+const LETTERS = {
+  M: ["███╗   ███╗", "████╗ ████║", "██╔████╔██║", "██║╚██╔╝██║", "██║ ╚═╝ ██║", "╚═╝     ╚═╝"],
+  O: [" ██████╗ ", "██╔═══██╗", "██║   ██║", "██║   ██║", "╚██████╔╝", " ╚═════╝ "],
+  K: ["██╗  ██╗", "██║ ██╔╝", "█████╔╝ ", "██╔═██╗ ", "██║  ██╗", "╚═╝  ╚═╝"],
+  S: ["███████╗", "██╔════╝", "███████╗", "╚════██║", "███████║", "╚══════╝"],
+  A: [" █████╗ ", "██╔══██╗", "███████║", "██╔══██║", "██║  ██║", "╚═╝  ╚═╝"],
+};
+const PALETTE = [red, yellow, green, cyan, magenta];
+
+function banner(subtitle) {
+  console.log();
+  for (let row = 0; row < 6; row++) {
+    console.log("  " + [..."MOKSA"].map((ch, i) => PALETTE[i % PALETTE.length](LETTERS[ch][row])).join(" "));
+  }
+  console.log();
+  console.log(bold(gcyan("               mosaic-headless · Mosaic 無頭建站技能包")));
+  console.log(bold(yellow(`               ${subtitle}`)));
+  console.log();
+}
+
+// ---------- the 完成 box ----------------------------------------------------
+
+const visualWidth = (str) => {
+  let w = 0;
+  for (const ch of str.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "")) {
+    const c = ch.codePointAt(0);
+    w += (c >= 0x4e00 && c <= 0x9fff) || (c >= 0x3000 && c <= 0x303f) ||
+         (c >= 0xff00 && c <= 0xffef) || (c >= 0xac00 && c <= 0xd7af) ? 2 : 1;
+  }
+  return w;
+};
+
+function box(lines, header = "  完成  ") {
+  const width = Math.max(visualWidth(header), ...lines.map(visualWidth)) + 2;
+  console.log();
+  console.log(ggreen("╭" + "─".repeat(width) + "╮"));
+  console.log(ggreen("│") + green(header) + " ".repeat(width - visualWidth(header)) + ggreen("│"));
+  console.log(ggreen("├" + "─".repeat(width) + "┤"));
+  for (const line of lines) {
+    console.log(ggreen("│ ") + line + " ".repeat(Math.max(0, width - visualWidth(line) - 2)) + ggreen(" │"));
+  }
+  console.log(ggreen("╰" + "─".repeat(width) + "╯"));
+  console.log();
+}
+
+// ---------- animated progress ----------------------------------------------
+
+async function step(label, fn) {
+  if (!TTY) { const out = await fn(); console.log(green("✔"), label); return out; }
+  process.stdout.write(cyan("◐") + " " + label);
+  const t0 = Date.now();
+  const out = await fn();
+  await sleep(Math.max(0, 140 - (Date.now() - t0)));
+  process.stdout.write("\r" + green("✔") + " " + label + "\n");
+  return out;
+}
+
+// ---------- interactive prompts (hand-rolled, zh-TW) ------------------------
+
+function select(message, choices) {
+  return new Promise((resolve) => {
+    let idx = 0;
+    const render = (first) => {
+      if (!first) process.stdout.write(`\x1b[${choices.length + 1}A\x1b[J`);
+      console.log(bold(message) + dim("（↑↓ 選擇，Enter 確定）"));
+      choices.forEach((c, i) => {
+        console.log(i === idx ? cyan(`  ❯ ${c.title}`) : `    ${c.title}`);
+      });
+    };
+    render(true);
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const onKey = (_s, key) => {
+      if (key.name === "up") idx = (idx - 1 + choices.length) % choices.length;
+      else if (key.name === "down") idx = (idx + 1) % choices.length;
+      else if (key.name === "return") {
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener("keypress", onKey);
+        process.stdin.pause();
+        return resolve(choices[idx].value);
+      } else if (key.name === "c" && key.ctrl) { process.stdin.setRawMode(false); process.exit(130); }
+      else return;
+      render(false);
+    };
+    process.stdin.on("keypress", onKey);
+  });
+}
+
+function toggle(message, initial = false) {
+  const yes = { title: initial ? "要（預設）" : "要", value: true };
+  const no = { title: initial ? "不要" : "不要（預設）", value: false };
+  return select(message, initial ? [yes, no] : [no, yes]);
+}
+
+// ---------- platform config ------------------------------------------------
+
+function listPlatforms() {
+  return fs.readdirSync(PLATFORMS).filter((f) => f.endsWith(".json")).sort()
+    .map((f) => JSON.parse(fs.readFileSync(path.join(PLATFORMS, f), "utf8")));
+}
+
+function loadPlatform(name) {
+  const p = path.join(PLATFORMS, `${name}.json`);
+  if (!fs.existsSync(p)) die(`Unknown platform: ${name} — run --list to see options.`, 2);
+  return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+
+function detectPlatforms() {
+  const cwd = process.cwd(), home = os.homedir();
+  const hits = [];
+  const probe = (dir, name) => { if (fs.existsSync(dir)) hits.push(name); };
+  probe(path.join(cwd, ".claude"), "claude-code");
+  probe(path.join(home, ".claude"), "claude-code");
+  probe(path.join(cwd, ".cursor"), "cursor");
+  probe(path.join(home, ".cursor"), "cursor");
+  probe(path.join(cwd, ".github"), "copilot");
+  probe(path.join(home, ".codex"), "codex-cli");
+  probe(path.join(home, ".gemini"), "gemini-cli");
+  probe(path.join(home, ".windsurf"), "windsurf");
+  return [...new Set(hits)];
+}
+
+// ---------- content assembly ------------------------------------------------
+
+function buildFrontmatter(fm) {
+  if (!fm) return "";
+  const lines = ["---"];
+  for (const [k, v] of Object.entries(fm)) {
+    if (v === null || v === undefined) continue;
+    if (Array.isArray(v)) lines.push(`${k}: [${v.map((x) => JSON.stringify(x)).join(", ")}]`);
+    else if (typeof v === "boolean") lines.push(`${k}: ${v}`);
+    else if (typeof v === "string" && (v.includes("\n") || v.length > 100)) {
+      lines.push(`${k}: |`);
+      for (const sub of v.split("\n")) lines.push(`  ${sub}`);
+    } else lines.push(`${k}: ${JSON.stringify(v)}`);
+  }
+  lines.push("---");
+  return lines.join("\n") + "\n\n";
+}
+
+function readSkillBody() {
+  let raw = fs.readFileSync(path.join(ROOT, "SKILL.md"), "utf8");
+  if (raw.startsWith("---")) {
+    const end = raw.indexOf("\n---", 3);
+    if (end !== -1) raw = raw.slice(end + 4).replace(/^\n+/, "");
+  }
+  return raw;
+}
+
+function embedReferences(names) {
+  // A missing file is a hard error, not a skip - silently shipping a rule file
+  // short one document is the silent-failure class this skill exists to kill.
+  const parts = [];
+  for (const n of names) {
+    const p = path.join(ROOT, "references", n);
+    if (!fs.existsSync(p)) {
+      const avail = fs.readdirSync(path.join(ROOT, "references")).filter((q) => q.endsWith(".md")).join(", ");
+      die(`Platform config asks to embed references/${n}, which does not exist.\nAvailable: ${avail}`);
+    }
+    parts.push(`\n\n---\n\n## Reference: ${n}\n\n${fs.readFileSync(p, "utf8")}\n`);
+  }
+  return parts.join("");
+}
+
+function walkFiles(dir) {
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.name === "__pycache__") continue;
+    if (e.isDirectory()) out.push(...walkFiles(p));
+    else out.push(p);
+  }
+  return out;
+}
+
+function copySection(sec, dstRoot, force) {
+  // Upgrades MUST delete what the previous version left behind: a stale, wrong
+  // dataset sitting next to the right one is worse than no installer.
+  const srcPath = path.join(ROOT, sec);
+  if (!fs.existsSync(srcPath)) return [0, 0];
+  let copied = 0;
+  const keep = new Set();
+  for (const f of walkFiles(srcPath)) {
+    const rel = path.relative(srcPath, f);
+    const target = path.join(dstRoot, sec, rel);
+    keep.add(path.resolve(target));
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (fs.existsSync(target) && !force) continue;
+    fs.copyFileSync(f, target);
+    copied++;
+  }
+  let pruned = 0;
+  const secDir = path.join(dstRoot, sec);
+  if (fs.existsSync(secDir)) {
+    for (const f of walkFiles(secDir)) {
+      if (!keep.has(path.resolve(f))) { fs.unlinkSync(f); pruned++; }
+    }
+  }
+  return [copied, pruned];
+}
+
+// ---------- strategies -----------------------------------------------------
+
+async function installFull(cfg, root, force, dry) {
+  const fsr = cfg.folderStructure;
+  const dir = path.join(root, fsr.skillPath);
+  const file = path.join(dir, fsr.filename);
+  const content = buildFrontmatter(cfg.frontmatter) + readSkillBody();
+  const plan = { file, size: content.length, sections: [] };
+  if (dry) {
+    for (const s of ["references", "tools", "data", "sites"]) if (cfg.sections?.[s]) plan.sections.push(s);
+    return plan;
+  }
+  await step("寫入 SKILL.md", () => {
+    fs.mkdirSync(dir, { recursive: true });
+    if (fs.existsSync(file) && !force) die(`Refusing to overwrite ${file} - pass --force.`);
+    fs.writeFileSync(file, content);
+  });
+  for (const s of ["references", "tools", "data", "sites"]) {
+    if (!cfg.sections?.[s]) continue;
+    await step(`複製 ${s}/`, () => {
+      const [n, pruned] = copySection(s, dir, force);
+      plan.sections.push(`${s} (${n} files${pruned ? `, ${pruned} stale removed` : ""})`);
+    });
+  }
+  await step("驗證安裝", () => {
+    if (!fs.existsSync(file)) die("install verification failed: SKILL.md missing");
+    if (cfg.sections?.data && !fs.existsSync(path.join(dir, "data", "node-verification.csv")))
+      die("install verification failed: data/node-verification.csv missing");
+  });
+  return plan;
+}
+
+async function installRule(cfg, root, force, dry) {
+  const fsr = cfg.folderStructure;
+  const file = path.join(root, fsr.skillPath, fsr.filename);
+  let body = readSkillBody();
+  if (cfg.embedReferences) body += embedReferences(cfg.embedReferences);
+  const content = buildFrontmatter(cfg.frontmatter) + body;
+  const plan = { file, size: content.length, embedded: cfg.embedReferences || [] };
+  if (dry) return plan;
+  await step("寫入 rule 檔（內嵌參考文件）", () => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (fs.existsSync(file) && !force) die(`Refusing to overwrite ${file} - pass --force.`);
+    fs.writeFileSync(file, content);
+  });
+  return plan;
+}
+
+async function installAppend(cfg, root, force, dry) {
+  const fsr = cfg.folderStructure;
+  const target = path.join(root, fsr.projectRoot, fsr.filename);
+  const { appendMarker: begin, appendMarkerEnd: end } = cfg;
+  let body = readSkillBody();
+  if (cfg.embedReferences) body += embedReferences(cfg.embedReferences);
+  const section = `\n\n${begin}\n## Headless Mosaic Skill\n\n${body}\n${end}\n`;
+  const existing = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  let content;
+  if (existing.includes(begin) && existing.includes(end)) {
+    const before = existing.split(begin)[0].replace(/\s+$/, "");
+    const after = existing.split(end).slice(1).join(end).replace(/^\s+/, "");
+    content = (before + "\n" + after).trim() + section;
+  } else {
+    content = (existing.replace(/\s+$/, "") + section).replace(/^\n+/, "");
+  }
+  const plan = { file: target, size: content.length, appended: true };
+  if (dry) return plan;
+  await step("附加到 copilot-instructions.md", () => {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content);
+  });
+  return plan;
+}
+
+async function installZip(cfg, root, force, dry) {
+  // Node has no built-in zip. Stage the folder, then use whatever archiver the
+  // OS has; if none, the staged folder + instructions are the result.
+  const fsr = cfg.folderStructure;
+  const outZip = path.join(root, fsr.skillPath);
+  const stage = path.join(root, "mosaic-headless-stage", "mosaic-headless");
+  const plan = { file: outZip, size: 0, entries: [] };
+  if (dry) { plan.entries.push("SKILL.md + sections (staged, then zipped)"); return plan; }
+  await step("打包 zip（Claude.ai 手動上傳用）", () => {
+    fs.rmSync(path.dirname(stage), { recursive: true, force: true });
+    fs.mkdirSync(stage, { recursive: true });
+    fs.writeFileSync(path.join(stage, "SKILL.md"), buildFrontmatter(cfg.frontmatter) + readSkillBody());
+    for (const s of ["references", "data", "sites"]) {
+      if (cfg.sections?.[s]) copySection(s, stage, true);
+    }
+    if (fs.existsSync(outZip) && !force) die(`Refusing to overwrite ${outZip} - pass --force.`);
+    fs.mkdirSync(path.dirname(outZip), { recursive: true });
+    try {
+      if (process.platform === "win32") {
+        execFileSync("powershell", ["-NoProfile", "-Command",
+          `Compress-Archive -Path '${stage}' -DestinationPath '${outZip}' -Force`]);
+      } else {
+        execFileSync("zip", ["-qr", outZip, "mosaic-headless"], { cwd: path.dirname(stage) });
+      }
+      fs.rmSync(path.dirname(stage), { recursive: true, force: true });
+      plan.size = fs.statSync(outZip).size;
+    } catch {
+      plan.file = path.dirname(stage);
+      plan.note = `no zip tool found - folder staged at ${path.dirname(stage)}; zip it manually`;
+    }
+  });
+  return plan;
+}
+
+const STRATEGIES = {
+  full: installFull, rule: installRule,
+  "instructions-append": installAppend, "zip-upload": installZip,
+};
+
+// ---------- CLI ------------------------------------------------------------
+
+function cmdList() {
+  const rows = listPlatforms();
+  console.log(`${"platform".padEnd(14)} ${"install type".padEnd(22)} verified  as-of        display name`);
+  console.log("-".repeat(90));
+  for (const c of rows) {
+    console.log(`${c.platform.padEnd(14)} ${c.installType.padEnd(22)} ${(c.verified ? "yes" : "no ").padEnd(8)}  ${(c.verifiedAsOf || "?").padEnd(12)} ${c.displayName}`);
+  }
+}
+
+function cmdInfo(name) {
+  const c = loadPlatform(name);
+  const f = c.folderStructure;
+  console.log(`Platform: ${c.platform}  (${c.displayName})`);
+  console.log(`Install type: ${c.installType}`);
+  console.log(`Project path: ${[f.projectRoot, f.skillPath, f.filename].filter(Boolean).join("/")}`);
+  if (f.globalRoot) console.log(`Global path:  ${[f.globalRoot, f.skillPath, f.filename].filter(Boolean).join("/")}`);
+  console.log(`Verified: ${!!c.verified} (as of ${c.verifiedAsOf || "unknown"})`);
+  console.log(`\n${c.loaderBehaviour}`);
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const flags = new Set(argv.filter((a) => a.startsWith("--") || a === "-f"));
+  const pos = argv.filter((a) => !a.startsWith("-") && argv[argv.indexOf(a) - 1] !== "--to" && argv[argv.indexOf(a) - 1] !== "--info");
+  const getOpt = (name) => { const i = argv.indexOf(name); return i !== -1 ? argv[i + 1] : null; };
+
+  if (flags.has("--list")) return cmdList();
+  if (getOpt("--info")) return cmdInfo(getOpt("--info"));
+
+  let name = pos[0];
+  let useGlobal = flags.has("--global");
+  let force = flags.has("--force") || flags.has("-f");
+  const dry = flags.has("--dry-run");
+
+  // Interactive mode: no platform named, and a real terminal to ask in.
+  if (!name && process.stdin.isTTY && process.stdout.isTTY) {
+    banner("Skill Installer");
+    const detected = detectPlatforms();
+    if (detected.length) info(`偵測到：${detected.map((d) => cyan(d)).join("、")}`);
+    const plats = listPlatforms();
+    name = await select("你想裝在哪個 AI 助手？", plats.map((c) => ({
+      title: `${c.displayName}${detected.includes(c.platform) ? green("  ●") : ""}`,
+      value: c.platform,
+    })));
+    const cfgPeek = loadPlatform(name);
+    if (cfgPeek.folderStructure.globalRoot && cfgPeek.installType !== "zip-upload") {
+      useGlobal = await toggle("要全域安裝嗎？（所有專案都能用）", detected.includes(name));
+    }
+    force = await toggle("檔案如果已經存在要覆蓋嗎？", true);
+  } else if (!name) {
+    cmdList();
+    console.log("\nUsage: npx mosaic-headless <platform> [--global] [--to DIR] [--force] [--dry-run]");
+    return;
+  } else {
+    banner("Skill Installer");
+  }
+
+  const cfg = loadPlatform(name);
+  const fsr = cfg.folderStructure;
+  let root = getOpt("--to") ? path.resolve(expand(getOpt("--to"))) : null;
+  if (!root) {
+    if (useGlobal && fsr.globalRoot) root = expand(fsr.globalRoot);
+    else if (cfg.installType === "instructions-append") root = process.cwd();
+    else root = path.join(process.cwd(), fsr.projectRoot || "");
+  }
+
+  info(`Installing mosaic-headless → ${cyan(cfg.displayName)}${useGlobal ? dim("（全域）") : ""}${dry ? yellow("（DRY RUN）") : ""}`);
+  info(`Target: ${dim(root)}`);
+  console.log();
+  const plan = await STRATEGIES[cfg.installType](cfg, root, force, dry);
+
+  const lines = [
+    `${bold("平台")}　${cfg.displayName}`,
+    `${bold("檔案")}　${plan.file}`,
+    `${bold("大小")}　${plan.size.toLocaleString()} bytes`,
+  ];
+  if (plan.sections?.length) lines.push(`${bold("內容")}　${plan.sections.join(", ")}`);
+  if (plan.embedded?.length) lines.push(`${bold("內嵌")}　${plan.embedded.join(", ")}`);
+  if (plan.note) lines.push(yellow(`NOTE　${plan.note}`));
+  lines.push("");
+  lines.push(dim("下一步：先讀 references/failure-modes.md，再讓 AI 依 data/ 查證後動手。"));
+  box(lines, dry ? "  DRY RUN  " : "  完成  ");
+  if (dry) console.log(dim("(dry run; nothing written.)"));
+  console.log(dim(cfg.loaderBehaviour));
+}
+
+main();

package/bin/sync-version.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Write package.json's version into every other place that carries one.
+ *
+ *   node bin/sync-version.mjs
+ *
+ * Runs from the `version` npm lifecycle script, after npm has bumped package.json
+ * and before it makes the commit and the tag - so the tagged commit already has all
+ * three versions agreeing, and `npm version patch` is the only command anyone has to
+ * remember.
+ *
+ * Targets:
+ *   SKILL.md                              frontmatter `version:`
+ *   assets/templates/platforms/*.json     frontmatter.version, where present
+ *
+ * check-release.mjs asserts afterwards that this worked, so a silent miss here
+ * cannot reach npm.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
+const v = pkg.version;
+const touched = [];
+
+// SKILL.md - only inside the frontmatter block, never in the prose below it
+const skillPath = path.join(ROOT, "SKILL.md");
+let skill = fs.readFileSync(skillPath, "utf8");
+const end = skill.indexOf("\n---", 4);
+if (end === -1) {
+  console.error("SKILL.md has no frontmatter block");
+  process.exit(1);
+}
+const head = skill.slice(0, end);
+const rest = skill.slice(end);
+// "already correct" and "line missing" are different answers, and conflating them
+// made this exit 1 on a release where the version happened to match already.
+const VERSION_LINE = /^version:\s*"?[^"\n]*"?\s*$/m;
+if (!VERSION_LINE.test(head)) {
+  console.error("SKILL.md frontmatter has no version: line to update");
+  process.exit(1);
+}
+const next = head.replace(VERSION_LINE, `version: "${v}"`);
+if (next !== head) {
+  fs.writeFileSync(skillPath, next + rest);
+  touched.push("SKILL.md");
+}
+
+// platform templates
+const platDir = path.join(ROOT, "assets", "templates", "platforms");
+for (const f of fs.readdirSync(platDir).filter((x) => x.endsWith(".json"))) {
+  const p = path.join(platDir, f);
+  const cfg = JSON.parse(fs.readFileSync(p, "utf8"));
+  if (cfg.frontmatter && "version" in cfg.frontmatter && cfg.frontmatter.version !== v) {
+    cfg.frontmatter.version = v;
+    fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
+    touched.push(`assets/templates/platforms/${f}`);
+  }
+}
+
+console.log(`synced v${v} into ${touched.length} file(s): ${touched.join(", ") || "none"}`);

package/data/animatable-properties.csv

@@ -0,0 +1,23 @@
+property,kind,animates_via
+transform,Transform,(the CSS property)
+translateX,Move,--mosaic-translate-x
+translateY,Move,--mosaic-translate-y
+translateZ,Move,--mosaic-translate-z
+scale,Scale,--mosaic-scale
+scaleX,Scale,--mosaic-scale-x
+scaleY,Scale,--mosaic-scale-y
+scaleZ,Scale,--mosaic-scale-z
+rotateX,Rotate,--mosaic-rotate-x
+rotateY,Rotate,--mosaic-rotate-y
+rotateZ,Rotate,--mosaic-rotate-z
+opacity,Opacity,(the CSS property)
+color,Color,(the CSS property)
+backgroundColor,Color,(the CSS property)
+borderColor,Color,(the CSS property)
+boxShadow,BoxShadow,(the CSS property)
+textShadow,TextShadow,(the CSS property)
+width,Size,(the CSS property)
+height,Size,(the CSS property)
+filter,Filter,(the CSS property)
+backdropFilter,Filter,(the CSS property)
+transformOrigin,TransformOrigin,(the CSS property)