@augurworks/augur 0.15.1

package/scripts/canvas-screen.mjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+// canvas-screen — scaffold a prototype that is OWNED BY a canvas.
+//
+// The model (see augur/CANVAS.md "Canvas-owned prototypes"): a canvas is a container.
+// "Build a prototype on the canvas" = create a real prototype in a SUBFOLDER of the canvas
+// (`<opp>/prototypes/<canvas>/<slug>/index.html`, ships at `/<opp>/<canvas>/<slug>/`) AND
+// place a tile for it on that canvas's board. The screen is OWNED by the canvas: removing it
+// from the canvas deletes the folder too — gone in general, not merely unlinked. (A tile that
+// points at some pre-existing top-level prototype, added via the in-app picker, is a mere
+// REFERENCE — this tool never touches those.)
+//
+// Because a canvas can't write git from the browser, that create/remove coupling is enforced
+// HERE, in the terminal, by whoever authors the prototype (you + an agent). Use:
+//   node scripts/canvas-screen.mjs add <canvasUrl> <slug> [--title "Nice Title"]
+//   node scripts/canvas-screen.mjs rm  <canvasUrl> <slug>
+//   node scripts/canvas-screen.mjs ls  <canvasUrl>
+//   node scripts/canvas-screen.mjs gc  <canvasUrl>
+// e.g. node scripts/canvas-screen.mjs add /ux-ui-audit/canvas/ voting-screen --title "Voting"
+//
+// `gc` is the browser half of the remove coupling: deleting a tile IN THE CANVAS UI can't
+// delete the folder (no git in the browser), so the folder lingers as an orphan. gc notices
+// orphans and deletes their folders after a ONE-HOUR grace window (to cover a
+// ⌘Z that brings the tile back) anchored at the first gc run that saw the orphan. Run it
+// whenever you start working a canvas; state lives in <workspace>/.canvas-gc.json (local only).
+//
+// `add`/`rm` touch two things: the FILES (in the space repo, which you then commit + push) and
+// the canvas BOARD — written THROUGH the multiplayer room as per-node ops (takes effect
+// live, and can't be clobbered by the room's own KV persistence). After `add`, write the
+// real prototype into the created index.html, then commit + push the space repo.
+
+import { readdirSync, existsSync, readFileSync, mkdirSync, writeFileSync, rmSync, cpSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");   // augur/
+const PARENT = path.join(ROOT, "..");                                           // the multi-space workspace
+const SITE = process.env.CANVAS_SITE_ORIGIN || process.env.REVIEW_SITE_URL || "";
+if (!SITE) {
+  console.error("canvas-screen: set CANVAS_SITE_ORIGIN (or REVIEW_SITE_URL) to the deployed site origin, e.g. https://<project>.pages.dev");
+  process.exit(1);
+}
+
+// ---- space resolution: map a canvas URL to its space repo + on-disk prototype dir ----------
+function spaces() {
+  // sibling dirs carrying a space.json (same rule build.js/offline use)
+  return readdirSync(PARENT, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.name.startsWith(".") && existsSync(path.join(PARENT, e.name, "space.json")))
+    .map((e) => {
+      let meta = {};
+      try { meta = JSON.parse(readFileSync(path.join(PARENT, e.name, "space.json"), "utf8")); } catch {}
+      return { dir: path.join(PARENT, e.name), id: meta.id || e.name, isDefault: !!meta.default };
+    });
+}
+
+// canvasUrl: "/ux-ui-audit/canvas/" (default space) or "/<spaceid>/<opp>/<canvas>/" (non-default)
+function resolve(canvasUrl) {
+  const segs = String(canvasUrl).replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+  if (segs.length < 2) throw new Error(`canvas URL needs at least <opp>/<canvas>: got "${canvasUrl}"`);
+  const sp = spaces();
+  const named = sp.find((s) => !s.isDefault && s.id === segs[0]);
+  const space = named || sp.find((s) => s.isDefault) || sp[0];
+  if (!space) throw new Error("no space repo found (need a sibling dir with space.json)");
+  const rest = named ? segs.slice(1) : segs;             // drop the space-id prefix if present
+  if (rest.length < 2) throw new Error(`expected <opp>/<canvas> after the space, got "${rest.join("/")}"`);
+  const [opp, canvas] = rest;
+  const canvasDir = path.join(space.dir, opp, "prototypes", canvas);
+  if (!existsSync(path.join(canvasDir, "index.html")))
+    throw new Error(`no canvas at ${path.relative(PARENT, canvasDir)} (its index.html must exist first)`);
+  const boardPath = "/" + rest.join("/") + "/";          // KV board key path is the CANVAS url (space-prefixed on live via the URL you pass)
+  return { space, opp, canvas, canvasDir, canvasUrl: (named ? "/" + segs.join("/") : "/" + rest.join("/")) + "/", boardPath: (named ? "/" + segs.join("/") : "/" + rest.join("/")) + "/" };
+}
+
+// ---- board mutations — THROUGH THE ROOM, never a raw KV overwrite --------------------------
+// Since 2026-07-27 the BoardRoom DO persists the doc itself while anyone is on the board, so
+// a direct POST /__board would be silently clobbered by the room's next write. The correct
+// write path for every out-of-band tool is the same one the engine uses: join the room, send
+// per-node ops, let the room fold them into the live doc and persist. When the room is empty
+// this still works — the one-shot client seeds it from KV, ops apply, and the room flushes to
+// KV when the client (last one out) disconnects.
+import { ClawdCanvas } from "./clawd-canvas.mjs";
+async function getBoard(canvasUrl) {
+  const r = await fetch(`${SITE}/__board?path=${encodeURIComponent(canvasUrl)}`);
+  const j = await r.json().catch(() => ({}));
+  return j.doc || { v: 1, name: "Untitled canvas", view: { x: 0, y: 0, scale: 1 }, nodes: [] };
+}
+// apply(doc) mutates a COPY of the live doc into the desired state; we then diff copy vs live
+// and send the difference as upsert/del ops. Returns the room's resulting doc.
+async function mutateBoard(boardPath, apply, confirm, label) {
+  const c = new ClawdCanvas({ boardPath, name: "canvas-screen" });
+  try {
+    await c.connect();
+    const before = JSON.parse(JSON.stringify(c.doc));
+    const desired = JSON.parse(JSON.stringify(c.doc));
+    desired.nodes = desired.nodes || [];
+    apply(desired);
+    const beforeIds = new Set((before.nodes || []).map((n) => n.id));
+    const desiredIds = new Set(desired.nodes.map((n) => n.id));
+    for (const n of desired.nodes) {
+      const old = (before.nodes || []).find((o) => o.id === n.id);
+      if (!old || JSON.stringify(old) !== JSON.stringify(n)) c.upsert(n);
+    }
+    for (const id of beforeIds) if (!desiredIds.has(id)) c.del(id);
+    await new Promise((r) => setTimeout(r, 600)); // let the ops land in the room
+    const ok = confirm(c.doc);
+    if (!ok) console.warn(`⚠ board ${label}: ops sent but end state not confirmed in the room doc.`);
+    return ok;
+  } finally {
+    try { c.close(); } catch {}
+  }
+}
+const uid = () => "n" + Math.random().toString(36).slice(2, 9);
+
+// place a new tile clear of existing nodes: to the right of the rightmost, aligned to the top
+function placeRightOf(nodes, w, h) {
+  const boxes = nodes.filter((n) => n.type !== "arrow" && typeof n.x === "number");
+  if (!boxes.length) return { x: -w / 2, y: -h / 2 };
+  const right = Math.max(...boxes.map((n) => n.x + (n.w || 240)));
+  const top = Math.min(...boxes.map((n) => n.y));
+  return { x: right + 60, y: top };
+}
+
+// The meta description is the screen's agent-facing meaning — one line stating the CLAIM
+// the prototype makes (not what it looks like). The artifact owns it: update it in the
+// same commit that changes the prototype. `ls` flags screens where it's missing/empty.
+const escAttr = (s) => String(s || "").replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+const STARTER = (title, desc) => `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="description" content="${escAttr(desc)}" />
+<title>${title}</title>
+<style>
+  body { margin: 0; font: 16px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; color: #1a1a1a; }
+  .wrap { min-height: 100vh; display: grid; place-items: center; padding: 40px; box-sizing: border-box; text-align: center; background: #f4f5f7; }
+  h1 { margin: 0 0 8px; font-size: 22px; }
+  p { margin: 0; color: #6b7280; }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <div>
+      <h1>${title}</h1>
+      <p>Scaffolded canvas screen — replace this with the real prototype.</p>
+    </div>
+  </div>
+</body>
+</html>
+`;
+
+// ---- commands ------------------------------------------------------------------------------
+async function cmdAdd(canvasUrl, slug, title, desc) {
+  const { space, canvasDir, boardPath } = resolve(canvasUrl);
+  if (!/^[a-z0-9-]+$/.test(slug)) throw new Error("slug must be lowercase [a-z0-9-]");
+  const screenDir = path.join(canvasDir, slug);
+  const url = boardPath + slug + "/";
+  const name = title || slug;
+  if (!existsSync(screenDir)) {
+    mkdirSync(screenDir, { recursive: true });
+    writeFileSync(path.join(screenDir, "index.html"), STARTER(name, desc));
+    console.log(`✓ created ${path.relative(PARENT, path.join(screenDir, "index.html"))}`);
+    if (!desc) console.log(`  ⚠ no --desc — fill the <meta name="description"> when you write the real prototype (ls flags opaque screens)`);
+  } else {
+    console.log(`• folder exists, keeping its index.html`);
+  }
+  const hasTile = (d) => (d.nodes || []).some((n) => n.type === "tile" && n.url === url);
+  await mutateBoard(boardPath, (d) => {
+    if (hasTile(d)) return;
+    const w = 560, h = 360, { x, y } = placeRightOf(d.nodes, w, h);
+    d.nodes.push({ id: uid(), type: "tile", x, y, w, h, url, name });
+  }, hasTile, "add-tile");
+  console.log(`✓ tile "${name}" → ${url} is on the canvas board`);
+  console.log(`\nNext: write the real prototype into that index.html, then commit + push the ${path.basename(space.dir)} repo.`);
+  console.log(`Lives at ${SITE}${url} once deployed.`);
+}
+
+async function cmdRm(canvasUrl, slug) {
+  const { canvasDir, boardPath } = resolve(canvasUrl);
+  const screenDir = path.join(canvasDir, slug);
+  const url = boardPath + slug + "/";
+  // 1) remove the tile from the board (retry through KV consistency until it's confirmed gone)
+  const gone = (d) => !(d.nodes || []).some((n) => n.type === "tile" && n.url === url);
+  await mutateBoard(boardPath, (d) => { d.nodes = (d.nodes || []).filter((n) => !(n.type === "tile" && n.url === url)); }, gone, "remove-tile");
+  console.log(`✓ tile ${url} removed from the board`);
+  // 2) delete the folder — owned-by-the-canvas means removing it deletes it in general
+  if (existsSync(screenDir)) { rmSync(screenDir, { recursive: true, force: true }); console.log(`✓ deleted ${path.relative(PARENT, screenDir)}`); }
+  else console.log(`• folder ${path.relative(PARENT, screenDir)} did not exist`);
+  console.log(`\nNext: commit + push the space repo so the deletion ships.`);
+}
+
+
+// Fork a canvas-owned screen: copy its folder to a new slug and point the DUPLICATE tile at
+// it. This is the terminal half of "duplicate the tile ⇒ duplicate the folder": Cmd+D on the
+// canvas clones only the tile (the browser can't write git), so both tiles briefly share one
+// folder; before editing "the copy", run dup — it repoints the duplicate (by --tile name, or
+// the one named "… copy", or the last sharer) at the fresh fork. If no duplicate tile exists
+// yet it places a new one beside the source.
+async function cmdDup(canvasUrl, srcSlug, newSlug, title, tileName) {
+  const { space, canvasDir, boardPath } = resolve(canvasUrl);
+  if (!/^[a-z0-9-]+$/.test(newSlug || "")) throw new Error("new slug must be lowercase [a-z0-9-]");
+  const srcDir = path.join(canvasDir, srcSlug), newDir = path.join(canvasDir, newSlug);
+  if (!existsSync(path.join(srcDir, "index.html"))) throw new Error(`no owned screen at ${srcSlug}`);
+  if (existsSync(newDir)) throw new Error(`${newSlug} already exists`);
+  cpSync(srcDir, newDir, { recursive: true });
+  console.log(`✓ forked ${path.relative(PARENT, srcDir)} → ${path.relative(PARENT, newDir)}`);
+  const srcUrl = boardPath + srcSlug + "/", newUrl = boardPath + newSlug + "/";
+  const name = title || newSlug;
+  const done = (d) => (d.nodes || []).some((n) => n.type === "tile" && n.url === newUrl);
+  await mutateBoard(boardPath, (d) => {
+    if (done(d)) return;
+    const sharers = d.nodes.filter((n) => n.type === "tile" && n.url === srcUrl);
+    let dupe = tileName ? sharers.find((n) => n.name === tileName) : null;
+    if (!dupe && sharers.length > 1) dupe = sharers.find((n) => / copy$/.test(n.name || "")) || sharers[sharers.length - 1];
+    if (dupe) { dupe.url = newUrl; dupe.name = name; delete dupe.liveUrl; delete dupe.thumb; }
+    else {
+      const src = sharers[0] || { x: 0, y: 0, w: 560, h: 360 };
+      d.nodes.push({ id: uid(), type: "tile", x: (src.x || 0) + 48, y: (src.y || 0) + 48, w: src.w || 560, h: src.h || 360, url: newUrl, name });
+    }
+  }, done, "fork-tile");
+  console.log(`✓ tile "${name}" → ${newUrl} on the board`);
+  console.log(`\nNext: edit the fork (${path.relative(PARENT, newDir)}), then commit + push the ${path.basename(space.dir)} repo.`);
+  console.log(`The fork inherits the source's <meta name="description"> — update it when the fork diverges.`);
+}
+
+// Pull a screen's <meta name="description"> — its agent-facing meaning. Null = opaque.
+function screenDesc(dir) {
+  try {
+    const html = readFileSync(path.join(dir, "index.html"), "utf8");
+    // exclude only the active delimiter — [^"'] would truncate at an inner apostrophe
+    const m = html.match(/<meta\s+name=["']description["']\s+content="([^"]*)"/i)
+      || html.match(/<meta\s+name=["']description["']\s+content='([^']*)'/i)
+      || html.match(/<meta\s+content="([^"]*)"\s+name=["']description["']/i)
+      || html.match(/<meta\s+content='([^']*)'\s+name=["']description["']/i);
+    return m && m[1].trim() ? m[1].trim() : null;
+  } catch { return null; }
+}
+
+async function cmdLs(canvasUrl) {
+  const { canvasDir, boardPath } = resolve(canvasUrl);
+  const folders = readdirSync(canvasDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(path.join(canvasDir, e.name, "index.html")))
+    .map((e) => e.name);
+  const doc = await getBoard(boardPath);
+  const tileUrls = new Set((doc.nodes || []).filter((n) => n.type === "tile").map((n) => n.url));
+  console.log(`Canvas ${boardPath} — owned screens (nested folders) vs board tiles:\n`);
+  for (const f of folders) {
+    const url = boardPath + f + "/";
+    const desc = screenDesc(path.join(canvasDir, f));
+    console.log(`  ${tileUrls.has(url) ? "●" : "○ (folder, no tile — orphaned)"}  ${f}  → ${url}`);
+    console.log(`      ${desc ? `"${desc}"` : "⚠ no meta description — opaque to agents"}`);
+  }
+  if (folders.some((f) => !tileUrls.has(boardPath + f + "/")))
+    console.log(`\n  → orphaned folders are meant to disappear: run \`canvas-screen gc ${boardPath}\` (1h grace for undo)`);
+  // tiles pointing under this canvas but with no folder = a dangling tile
+  for (const n of (doc.nodes || []).filter((n) => n.type === "tile" && n.url && n.url.startsWith(boardPath) && n.url !== boardPath)) {
+    const slug = n.url.slice(boardPath.length).replace(/\/$/, "");
+    if (!folders.includes(slug)) console.log(`  ⚠ tile with no folder: ${n.url} (dangling)`);
+  }
+  if (!folders.length) console.log("  (no owned screens yet)");
+  // the board's other opaque nodes: images without a desc field
+  const blind = (doc.nodes || []).filter((n) => n.type === "image" && !(n.desc && String(n.desc).trim()));
+  if (blind.length) {
+    console.log(`\n  ⚠ ${blind.length} image node(s) without desc (opaque to agents):`);
+    for (const n of blind) console.log(`      ${n.name || n.id}`);
+  }
+}
+
+// Orphan garbage collection: a screen folder whose tile was deleted in the canvas UI is
+// meant to DISAPPEAR (ownership coupling), but not instantly — a 1h grace covers undo.
+// Grace is anchored at the first gc observation (the board doc carries no deletion times),
+// so deletion happens at the first gc run at least an hour after an orphan was noticed.
+const GC_GRACE_MS = 60 * 60 * 1000;
+const GC_STATE = path.join(PARENT, ".canvas-gc.json");
+async function cmdGc(canvasUrl) {
+  const { space, canvasDir, boardPath } = resolve(canvasUrl);
+  const folders = readdirSync(canvasDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(path.join(canvasDir, e.name, "index.html")))
+    .map((e) => e.name);
+  const doc = await getBoard(boardPath);
+  const tileUrls = new Set((doc.nodes || []).filter((n) => n.type === "tile").map((n) => n.url));
+  let state = {};
+  try { state = JSON.parse(readFileSync(GC_STATE, "utf8")); } catch {}
+  const now = Date.now();
+  const deleted = [];
+  for (const f of folders) {
+    const url = boardPath + f + "/";
+    if (tileUrls.has(url)) {
+      if (state[url]) { delete state[url]; console.log(`● ${f}: tile is back on the board, grace cleared`); }
+      continue;
+    }
+    if (!state[url]) {
+      state[url] = now;
+      console.log(`○ ${f}: orphaned (no tile) — noticed now, deleting after a 1h grace (rerun gc later)`);
+    } else if (now - state[url] >= GC_GRACE_MS) {
+      rmSync(path.join(canvasDir, f), { recursive: true, force: true });
+      delete state[url];
+      deleted.push(f);
+      console.log(`✗ ${f}: grace expired, folder deleted`);
+    } else {
+      console.log(`○ ${f}: orphaned, ${Math.ceil((GC_GRACE_MS - (now - state[url])) / 60000)}m of grace left`);
+    }
+  }
+  // stamps whose folder is gone (deleted here or by hand) are spent
+  for (const url of Object.keys(state)) {
+    if (!url.startsWith(boardPath)) continue;
+    const slug = url.slice(boardPath.length).replace(/\/$/, "");
+    if (!folders.includes(slug) || deleted.includes(slug)) delete state[url];
+  }
+  mkdirSync(path.dirname(GC_STATE), { recursive: true });
+  writeFileSync(GC_STATE, JSON.stringify(state, null, 1));
+  if (!folders.length) console.log("(no owned screens)");
+  if (deleted.length) console.log(`\nNext: commit + push the ${path.basename(space.dir)} repo so the deletion ships.`);
+}
+
+// ---- cli -----------------------------------------------------------------------------------
+const [cmd, canvasUrl, slug] = process.argv.slice(2);
+const titleIdx = process.argv.indexOf("--title");
+const title = titleIdx > -1 ? process.argv[titleIdx + 1] : "";
+try {
+  const tileIdx = process.argv.indexOf("--tile");
+  const tileName = tileIdx > -1 ? process.argv[tileIdx + 1] : "";
+  const descIdx = process.argv.indexOf("--desc");
+  const desc = descIdx > -1 ? process.argv[descIdx + 1] : "";
+  if (cmd === "add" && canvasUrl && slug) await cmdAdd(canvasUrl, slug, title, desc);
+  else if (cmd === "dup" && canvasUrl && slug && process.argv[5] && !process.argv[5].startsWith("--")) await cmdDup(canvasUrl, slug, process.argv[5], title, tileName);
+  else if (cmd === "rm" && canvasUrl && slug) await cmdRm(canvasUrl, slug);
+  else if (cmd === "ls" && canvasUrl) await cmdLs(canvasUrl);
+  else if (cmd === "gc" && canvasUrl) await cmdGc(canvasUrl);
+  else {
+    console.log("usage:\n  canvas-screen add <canvasUrl> <slug> [--title \"T\"] [--desc \"one-line claim the screen makes\"]\n  canvas-screen dup <canvasUrl> <srcSlug> <newSlug> [--title \"T\"] [--tile \"Dup tile name\"]\n  canvas-screen rm  <canvasUrl> <slug>\n  canvas-screen ls  <canvasUrl>  (also flags opaque screens/images — no description)\n  canvas-screen gc  <canvasUrl>  (delete folders orphaned by in-canvas tile deletion, 1h grace)");
+    process.exit(1);
+  }
+} catch (e) { console.error("✗ " + e.message); process.exit(1); }

package/scripts/check-local.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+/**
+ * check-local — run every gate `.github/workflows/check.yml` runs, here, before pushing.
+ *
+ * WHY. `check` gates the deploy: `deploy-trigger.yml` only dispatches when it is green,
+ * so a red check does not break a live instance — it silently STOPS the engine reaching
+ * one. A push whose check fails looks exactly like a push that shipped, from this side,
+ * and the instance that auto-bumps within a minute simply never bumps.
+ *
+ * That already happened once. A commit landed on main naming a person in a comment, the
+ * repo-wide word scan caught it in CI, the deploy trigger skipped, and the engine sat one
+ * commit behind on every instance until someone looked at the run list. Every check runs
+ * locally in seconds; there was no reason not to have run them.
+ *
+ * THE WORD SCAN IS THE ONE THAT NEEDED THIS. The other five gates are node scripts anyone
+ * would think to run. The word scan is a shell grep that only exists inside the workflow
+ * YAML, so it was the one gate with no local form at all — and it is the one that fires
+ * on ordinary prose written into a comment without thinking, which is the easiest mistake
+ * in this repo to make.
+ *
+ * IF YOU EDIT check.yml, EDIT THIS. They are two copies of one list. The last check below
+ * compares them and fails when the workflow grows a step this file does not run, so the
+ * drift is caught rather than discovered.
+ *
+ * Run: npm run check     (exit 1 on the first failure, like the workflow)
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync, execSync } from "node:child_process";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const WORKFLOW = path.join(ROOT, ".github", "workflows", "check.yml");
+
+// The repo-wide instance/product/personal word scan, kept BYTE-IDENTICAL to the pattern in
+// check.yml. It is read out of the workflow rather than duplicated here, so the two can
+// never disagree — and so this file does not itself become a list of the words (which is
+// why check.yml excludes itself from the scan, and why this script must be excluded too).
+function wordScanPattern() {
+  const yml = fs.readFileSync(WORKFLOW, "utf8");
+  const m = yml.match(/^\s*'([^']*go\[[^']*)'\s*\\?\s*$/m);
+  if (!m) throw new Error("could not find the word-scan pattern in check.yml — has the step changed shape?");
+  return m[1];
+}
+
+const steps = [
+  ["Doc drift (doc-lint)", () => run("node", ["scripts/doc-lint.mjs"])],
+  ["No new module-scope tenant state", () => run("node", ["scripts/no-tenant-globals.mjs"])],
+  ["One tenant resolver, one call site", () => run("node", ["scripts/one-tenant-resolver.mjs"])],
+  ["No foreign vocabulary", () => run("node", ["scripts/no-foreign-vocabulary.mjs"])],
+  ["No other company's product named", () => run("node", ["scripts/no-product-names.mjs"])],
+  ["Empty states are a ghost and one line", () => run("node", ["scripts/ui-copy-lint.mjs"])],
+  ["The state inventory still names everything", () => run("node", ["scripts/state-inventory.mjs"])],
+  ["No instance, product, or personal words", wordScan],
+];
+
+function run(cmd, args) {
+  const out = execFileSync(cmd, args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  return out.trim().split("\n").pop();
+}
+
+function wordScan() {
+  // WHAT TO SCAN: everything the repository WILL contain if you commit — tracked files plus
+  // untracked-but-not-ignored ones. Neither half alone is right, and both halves were
+  // learned the same way.
+  //
+  // Not the whole working tree: a local tree also holds everything .gitignore covers —
+  // agent scratch, notes, old reports — which are full of these words on purpose and are
+  // going nowhere near a deploy. Grepping `.` reported hundreds of findings CI cannot see,
+  // which trains whoever runs this to scroll past its output.
+  //
+  // And not the tracked set alone: a brand-new file is invisible to `git ls-files` until
+  // it is added, so that reports OK on exactly the file you are about to commit, and then
+  // CI — which sees it — goes red. That happened: a new test used a person's name as a
+  // fixture, this check passed because the file was not staged yet, and the push landed
+  // with a red gate and a skipped deploy.
+  //
+  // A brand-new file is invisible to `git ls-files` until it is added, so scanning only the
+  // tracked set reports OK on exactly the file you are about to commit — and then CI, which
+  // sees it, goes red. That happened: a new test used a person's name as a fixture, this
+  // check passed because the file was not staged yet, and the push landed with a red gate
+  // and a skipped deploy. Untracked-and-not-ignored is precisely "what the repository will
+  // contain if you commit", which is what CI is going to scan.
+  //
+  // Ignored files stay out, which is what keeps agent scratch from swamping the output.
+  const ls = (args) => execSync(`git ${args}`, { cwd: ROOT, encoding: "buffer" })
+    .toString("utf8").split("\0").filter(Boolean);
+  const tracked = [...ls("ls-files -z"), ...ls("ls-files -o --exclude-standard -z")]
+    // check.yml necessarily writes the words down; so does this file's own excludes.
+    .filter((f) => f !== ".github/workflows/check.yml" && f !== "scripts/check-local.mjs")
+    .filter((f, i, a) => a.indexOf(f) === i);
+
+  // grep exit codes: 0 = found (FAIL), 1 = clean (pass), >=2 = the scan itself broke.
+  // Treating >=2 as a pass is how a renamed path turns a guard into a no-op.
+  let rc = 1, out = "";
+  try {
+    out = execFileSync("grep", ["-InEi", "--binary-files=without-match", wordScanPattern(), ...tracked],
+      { cwd: ROOT, encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+    rc = 0;
+  } catch (e) {
+    rc = e.status;
+    out = (e.stdout || "") + (e.stderr || "");
+  }
+  if (rc === 0) throw new Error(`instance/product/personal word found:\n${out.trim()}`);
+  if (rc >= 2) throw new Error(`the word scan failed to RUN (grep rc=${rc}) — that is a failure, never a pass:\n${out}`);
+  return `clean — ${tracked.length} files (tracked + untracked), no instance/product words`;
+}
+
+let failed = 0;
+for (const [name, fn] of steps) {
+  try {
+    const last = fn();
+    console.log(`  ok    ${name}${last ? `  —  ${last.slice(0, 90)}` : ""}`);
+  } catch (e) {
+    failed++;
+    console.log(`  FAIL  ${name}`);
+    const msg = (e.stdout || "") + (e.stderr || "") || e.message;
+    console.log(msg.split("\n").map((l) => `        ${l}`).join("\n"));
+    break; // the workflow stops at the first failing step; so does this
+  }
+}
+
+// Drift: a step added to the workflow that this file does not run would make a green local
+// check mean less than it says.
+if (!failed) {
+  const names = [...fs.readFileSync(WORKFLOW, "utf8").matchAll(/^\s*-\s*name:\s*(.+)$/gm)].map((m) => m[1].trim());
+  const missing = names.filter((n) => !steps.some(([s]) => n.toLowerCase().startsWith(s.toLowerCase().slice(0, 18))));
+  if (missing.length) {
+    console.log(`\n  FAIL  check.yml has step(s) this script does not run: ${missing.join(", ")}`);
+    console.log("        Add them here. A local check that is a subset of CI is a local check that lies.");
+    process.exit(1);
+  }
+}
+
+console.log(failed ? "\ncheck-local: FAILED — this push would not deploy" : "\ncheck-local: OK — every gate check.yml runs is green here");
+process.exit(failed ? 1 : 0);

package/scripts/clawd-art.mjs

@@ -0,0 +1,75 @@
+// clawd-art — the Clawd mascot as tintable pixel-SVG, with expression STATES.
+// One shared 14x12 pixel grid; each expression overrides eyes/mouth/arms/accessories.
+// Body pixels ('B') take the peer's color ({C}); features are fixed hues. A white outline
+// (feMorphology) keeps Clawd legible on any canvas background. clawdSvg(expr, color) -> string.
+//
+// States (so the cursor can "act"): idle · coding · thinking · happy · sleeping · love ·
+// sunglasses · handsUp. Add more from the official sheet by adding a pixel map below.
+
+const U = 4;                     // px per grid cell
+const COLS = 14, ROWS = 12;
+const K = '#1a1a1a', WHITE = '#fff', RED = '#e03131', BLUE = '#4dabf7', YELLOW = '#ffd43b', GREY = '#adb5bd';
+
+// base body silhouette (B). Head block + small side-arm nubs (rows 6-7 cols 0 & 13) + 4 feet.
+const BODY = [
+  '..BBBBBBBBBB..',
+  '.BBBBBBBBBBBB.',
+  '.BBBBBBBBBBBB.',
+  '.BBBBBBBBBBBB.',
+  '.BBBBBBBBBBBB.',
+  '.BBBBBBBBBBBB.',
+  'BBBBBBBBBBBBBB',
+  'BBBBBBBBBBBBBB',
+  '.BBBBBBBBBBBB.',
+  '.BBBBBBBBBBBB.',
+  '.BB.BB..BB.BB.',
+  '.BB.BB..BB.BB.',
+];
+
+// feature layers per expression: [row, col, color] cells painted ON TOP of the body
+function eyes(open = true, color = K) {
+  // two 2x2 eyes at rows 3-4, cols 4-5 and 8-9
+  const c = [];
+  const rows = open ? [3, 4] : [4];
+  for (const r of rows) for (const col of [4, 5, 8, 9]) c.push([r, col, color]);
+  return c;
+}
+const EXPR = {
+  idle: () => eyes(true),
+  // squint (single-row eyes) = focused on the work
+  coding: () => [...eyes(false), [3, 4, K], [3, 9, K]],
+  // normal eyes + a trailing "..." up to the right
+  thinking: () => [...eyes(true), [1, 12, K], [0, 13, K], [2, 11, K]],
+  // upward (top-row) eyes = happy squint + tiny rosy cheeks
+  happy: () => [[3, 4, K], [3, 5, K], [3, 8, K], [3, 9, K], [5, 3, '#ff8787'], [5, 10, '#ff8787']],
+  // closed dash eyes + "z z" drifting up-right
+  sleeping: () => [...eyes(false), [1, 12, GREY], [0, 13, GREY]],
+  // red hearts for eyes + a floating heart
+  love: () => [[3, 4, RED], [3, 5, RED], [4, 4, RED], [3, 8, RED], [3, 9, RED], [4, 8, RED], [0, 11, RED], [0, 12, RED]],
+  // solid black bar across the eyes
+  sunglasses: () => { const c = []; for (const col of [3, 4, 5, 6, 7, 8, 9, 10]) c.push([3, col, K]); for (const col of [4, 5, 8, 9]) c.push([4, col, K]); return c; },
+  // idle face but arms raised (extra body pixels up at the top corners)
+  handsUp: () => [...eyes(true), [0, 0, 'B'], [1, 0, 'B'], [0, 1, 'B'], [0, 13, 'B'], [1, 13, 'B'], [0, 12, 'B']],
+};
+
+export const CLAWD_STATES = Object.keys(EXPR);
+
+export function clawdSvg(expr = 'idle', color = '#d97757') {
+  const cells = new Map(); // "r,c" -> color
+  BODY.forEach((row, r) => [...row].forEach((ch, c) => { if (ch === 'B') cells.set(r + ',' + c, 'B'); }));
+  (EXPR[expr] || EXPR.idle)().forEach(([r, c, col]) => cells.set(r + ',' + c, col));
+  let rects = '';
+  for (const [k, col] of cells) {
+    const [r, c] = k.split(',').map(Number);
+    const fill = col === 'B' ? '{C}' : col;
+    rects += `<rect x="${c * U}" y="${r * U}" width="${U}" height="${U}" fill="${fill}"/>`;
+  }
+  const W = COLS * U, H = ROWS * U;
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${W}" height="${H}" viewBox="0 0 ${W} ${H}">` +
+    `<defs><filter id="clawd-o" x="-20%" y="-20%" width="140%" height="140%">` +
+    `<feMorphology in="SourceAlpha" operator="dilate" radius="1.3" result="d"/>` +
+    `<feFlood flood-color="${WHITE}"/><feComposite in2="d" operator="in" result="o"/>` +
+    `<feMerge><feMergeNode in="o"/><feMergeNode in="SourceGraphic"/></feMerge></filter></defs>` +
+    `<g filter="url(#clawd-o)">${rects}</g></svg>`;
+  return svg.replace(/\{C\}/g, color);
+}