frogoe 0.2.2 → 0.3.1

package/README.md

@@ -0,0 +1,84 @@
+# frogoe
+
+**Write a closure. Ship a game.** A tiny game framework built for agents — one
+`defineGame` closure with four nouns, and a CLI that scaffolds, serves, gates,
+and bundles feed-ready games as single self-contained HTML files.
+
+## Install
+
+```bash
+npx frogoe init my-game
+cd my-game
+```
+
+Or install globally:
+
+```bash
+npm install -g frogoe
+```
+
+## The 60-second loop
+
+```bash
+frogoe init my-game      # runnable folder: living stub game, BRIEF, pinned contract
+cd my-game
+frogoe run               # live reload + phone QR (try --tunnel: works on any network)
+frogoe add score-card    # themeable HUD block, injected + idempotent
+frogoe lint              # fast static contract lint (stable finding codes, --json)
+frogoe check             # full gate: lint + headless Chrome — full lifecycle, fps,
+                         # audio recovery, 4x phone-class throttle, screenshots
+frogoe report            # last playtest: fps dips, errors, wall-clock
+frogoe bundle            # ONE self-contained HTML — externals dissolved, zero
+                         # runtime requests (only after check passes)
+frogoe skills check      # skill freshness (hash = per-bundle SHA16)
+```
+
+## Built for agents
+
+The real docs are [agent skills](https://github.com/frogoe/engine/tree/main/skills) —
+the contract, creative direction, CLI loop, and HUD registry, written for the
+AI that writes the game:
+
+```bash
+npx skills add frogoe/engine
+```
+
+Playtests under `frogoe run` are telemetered: fps dips, page errors and
+lock-screens print live in your terminal and persist to
+`.frogoe/sessions/*.jsonl`. `frogoe report` replays the last session — dips
+below 30fps with their wall-clock moments.
+
+## The contract
+
+A game is one closure. The platform gives four nouns — everything visible is
+yours:
+
+```js
+import { defineGame } from "frogoe";
+
+defineGame(({ stage, input, loop, finish }) => {
+  let y = stage.height / 2;
+  let vy = 0;
+
+  input.on("down", () => {
+    vy = -300;
+  });
+
+  loop.update = (dt) => {
+    vy += 900 * dt;
+    y += vy * dt;
+  };
+  loop.render = (ctx) => {
+    ctx.fillStyle = "#fff";
+    ctx.fillRect(stage.play.center - 12, y, 24, 24);
+  };
+});
+```
+
+The platform draws nothing — zero taste by construction. Games run from a
+single pinned runtime (`frogoe.json` → `.frogoe/contract.js`), so every game
+is an immutable artifact of exactly the contract it was built on.
+
+## License
+
+Apache-2.0

package/dist/cli.js

@@ -183,19 +183,18 @@ var init_init = __esm({
 // src/add.ts
 import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
 import path2 from "path";
-var STYLE_PATTERN, MARKUP_PATTERN, parseBlock, blockMarker, injectIntoHtml, addBlock;
+var parseBlock, blockMarker, injectIntoHtml, addBlock;
 var init_add = __esm({
   "src/add.ts"() {
     "use strict";
     init_init();
-    STYLE_PATTERN = /<style>([\s\S]*?)<\/style>/u;
-    MARKUP_PATTERN = /<\/style>\s*([\s\S]*)$/u;
     parseBlock = (source) => {
-      const styleMatch = STYLE_PATTERN.exec(source);
-      const markupMatch = MARKUP_PATTERN.exec(source);
+      const styleOpen = source.indexOf("<style>");
+      const styleClose = source.indexOf("</style>");
+      const css = styleOpen === -1 || styleClose === -1 || styleClose < styleOpen ? null : source.slice(styleOpen + "<style>".length, styleClose);
       return {
-        css: styleMatch?.[1]?.trim() ?? null,
-        markup: (markupMatch?.[1] ?? "").trim()
+        css: css?.trim() ?? null,
+        markup: (styleClose === -1 ? "" : source.slice(styleClose + "</style>".length)).trim()
       };
     };
     blockMarker = (name) => `<!-- frogoe:block:${name} -->`;
@@ -371,8 +370,8 @@ var init_fetch_policy = __esm({
       url;
       status;
     };
-    sleep = (ms) => new Promise((resolve) => {
-      setTimeout(resolve, ms);
+    sleep = (ms) => new Promise((resolve2) => {
+      setTimeout(resolve2, ms);
     });
     fetchWithPolicy = async (url, options) => {
       const policy = { ...DEFAULT_FETCH_POLICY, ...options?.policy };
@@ -723,11 +722,32 @@ var init_bundle2 = __esm({
 });
 
 // ../lint/src/brief.ts
-var stripComment, parseBrief;
+var KEY_PATTERN, WS, stripComment, parseLine, parseBrief;
 var init_brief = __esm({
   "../lint/src/brief.ts"() {
     "use strict";
-    stripComment = (value) => value.replace(/\s+#.*$/u, "").trim().replace(/^["']|["']$/gu, "");
+    KEY_PATTERN = /^[a-z-]+$/u;
+    WS = /\s/u;
+    stripComment = (value) => {
+      let cut = -1;
+      for (let i = 1; i < value.length; i += 1) {
+        if (value[i] === "#" && WS.test(value[i - 1] ?? "")) {
+          cut = i;
+          break;
+        }
+      }
+      return (cut === -1 ? value : value.slice(0, cut)).trim().replace(/^["']|["']$/gu, "");
+    };
+    parseLine = (line) => {
+      let indent = 0;
+      while (indent < line.length && line[indent] === " ") indent += 1;
+      const body = line.slice(indent);
+      const colon = body.indexOf(":");
+      if (colon === -1) return null;
+      const key = body.slice(0, colon);
+      if (!KEY_PATTERN.test(key)) return null;
+      return { indent, key, rest: body.slice(colon + 1) };
+    };
     parseBrief = (source) => {
       const match = /^---\r?\n([\s\S]*?)\r?\n---/u.exec(source);
       if (!match) {
@@ -739,20 +759,20 @@ var init_brief = __esm({
         if (rawLine.trim() === "") {
           continue;
         }
-        const nested = /^\s{2,}([a-z-]+):\s*(.*)$/u.exec(rawLine);
-        const top = /^([a-z-]+):\s*(.*)$/u.exec(rawLine);
-        if (nested && section === "palette") {
-          const key = nested[1];
-          brief[key] = stripComment(nested[2] ?? "");
+        const parsed = parseLine(rawLine);
+        if (!parsed) {
           continue;
         }
-        if (top) {
-          section = top[1] ?? "";
+        if (parsed.indent >= 2 && section === "palette") {
+          brief[parsed.key] = stripComment(parsed.rest);
+          continue;
+        }
+        if (parsed.indent === 0) {
+          section = parsed.key;
           if (section === "palette") {
             continue;
           }
-          const key = section;
-          brief[key] = stripComment(top[2] ?? "");
+          brief[parsed.key] = stripComment(parsed.rest);
         }
       }
       return brief;
@@ -1333,8 +1353,8 @@ var init_driver = __esm({
         async hold(x, y, ms) {
           await page.mouse.move(x, y);
           await page.mouse.down();
-          await new Promise((resolve) => {
-            setTimeout(resolve, ms);
+          await new Promise((resolve2) => {
+            setTimeout(resolve2, ms);
           });
           await page.mouse.up();
         },
@@ -1342,8 +1362,8 @@ var init_driver = __esm({
           await page.mouse.move(x1, y1);
           await page.mouse.down();
           await page.mouse.move(x2, y2, { steps: 6 });
-          await new Promise((resolve) => {
-            setTimeout(resolve, 80);
+          await new Promise((resolve2) => {
+            setTimeout(resolve2, 80);
           });
           await page.mouse.up();
         },
@@ -1369,8 +1389,8 @@ var init_driver = __esm({
             if (Date.now() - started > grace) {
               return false;
             }
-            await new Promise((resolve) => {
-              setTimeout(resolve, 100);
+            await new Promise((resolve2) => {
+              setTimeout(resolve2, 100);
             });
           }
           const navigated = page.waitForNavigation({ timeout: timeoutMs, waitUntil: "domcontentloaded" }).then(() => true).catch(() => false);
@@ -1721,8 +1741,8 @@ var init_phases = __esm({
     STABILITY_CYCLES = 2;
     START_BURST_TAPS = 3;
     DESKTOP_FPS_MS = 2e3;
-    sleep2 = (ms) => new Promise((resolve) => {
-      setTimeout(resolve, ms);
+    sleep2 = (ms) => new Promise((resolve2) => {
+      setTimeout(resolve2, ms);
     });
     jitterX = (step) => step * 37 % 121 - 60;
     jitterY = (step) => step * 53 % 181 - 90;
@@ -2375,9 +2395,9 @@ var init_run = __esm({
         return c.body(body, 200, { "content-type": type });
       });
       const server = createAdaptorServer({ fetch: app.fetch });
-      await new Promise((resolve, reject) => {
+      await new Promise((resolve2, reject) => {
         server.once("error", reject);
-        server.listen(requestedPort, "0.0.0.0", () => resolve());
+        server.listen(requestedPort, "0.0.0.0", () => resolve2());
       });
       const address = server.address();
       const port = typeof address === "object" && address ? address.port : 0;
@@ -2568,23 +2588,27 @@ var init_check3 = __esm({
       args: {
         dir: { type: "positional", required: false, description: "game folder (default: cwd)" },
         json: { type: "boolean", description: "machine-readable findings" },
-        live: { type: "boolean", description: "also run the headless-browser sandbox pass" }
+        live: {
+          type: "boolean",
+          description: "deprecated no-op \u2014 the live sandbox always runs now"
+        }
       },
       async run({ args }) {
+        if (args.live) {
+          console.error("  note: --live is deprecated \u2014 the live sandbox always runs now");
+        }
         const dir = args.dir ? String(args.dir) : process.cwd();
         const result = checkProject(dir);
-        if (args.live) {
-          const { collectLive: collectLive2 } = await Promise.resolve().then(() => (init_live(), live_exports));
-          console.log("  live pass: boot \u2192 play \u2192 end \u2192 retry (headless chrome)\u2026");
-          const live = await collectLive2({ dir });
-          result.findings = [...result.findings, ...live.findings].sort(
-            (a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0)
-          );
-          result.errors = result.findings.filter((f) => f.severity === "error").length;
-          result.warnings = result.findings.filter((f) => f.severity === "warning").length;
-          if (live.screenshots.length > 0) {
-            console.log(`  snapshots: ${live.screenshots.join(", ")}`);
-          }
+        const { collectLive: collectLive2 } = await Promise.resolve().then(() => (init_live(), live_exports));
+        console.log("  live pass: boot \u2192 play \u2192 end \u2192 retry (headless chrome)\u2026");
+        const live = await collectLive2({ dir });
+        result.findings = [...result.findings, ...live.findings].sort(
+          (a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0)
+        );
+        result.errors = result.findings.filter((f) => f.severity === "error").length;
+        result.warnings = result.findings.filter((f) => f.severity === "warning").length;
+        if (live.screenshots.length > 0) {
+          console.log(`  snapshots: ${live.screenshots.join(", ")}`);
         }
         if (args.json) {
           console.log(JSON.stringify(result, null, 2));
@@ -2597,7 +2621,9 @@ var init_check3 = __esm({
           process.exitCode = 1;
         }
       },
-      meta: { description: "contract lint with stable finding codes" }
+      meta: {
+        description: "full gate: contract lint + live browser sandbox (FPS, playability, HUD outline, audio recovery, screenshots)"
+      }
     });
   }
 });
@@ -2633,20 +2659,55 @@ var init_init2 = __esm({
   }
 });
 
+// src/commands/lint.ts
+var lint_exports = {};
+__export(lint_exports, {
+  command: () => command5
+});
+import { defineCommand as defineCommand5 } from "citty";
+var command5;
+var init_lint = __esm({
+  "src/commands/lint.ts"() {
+    "use strict";
+    init_check2();
+    command5 = defineCommand5({
+      args: {
+        dir: { type: "positional", required: false, description: "game folder (default: cwd)" },
+        json: { type: "boolean", description: "machine-readable findings" }
+      },
+      async run({ args }) {
+        const dir = args.dir ? String(args.dir) : process.cwd();
+        const result = checkProject(dir);
+        if (args.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(formatFindings(result));
+          console.log(`
+  ${result.errors} error(s), ${result.warnings} warning(s)`);
+        }
+        if (result.errors > 0) {
+          process.exitCode = 1;
+        }
+      },
+      meta: { description: "static contract lint only \u2014 fast iteration (check is the full gate)" }
+    });
+  }
+});
+
 // src/commands/report.ts
 var report_exports = {};
 __export(report_exports, {
-  command: () => command5
+  command: () => command6
 });
 import { readFileSync as readFileSync6 } from "fs";
-import { defineCommand as defineCommand5 } from "citty";
-var command5;
+import { defineCommand as defineCommand6 } from "citty";
+var command6;
 var init_report = __esm({
   "src/commands/report.ts"() {
     "use strict";
     init_records();
     init_session();
-    command5 = defineCommand5({
+    command6 = defineCommand6({
       args: {
         dir: { type: "positional", required: false, description: "game folder (default: cwd)" }
       },
@@ -2758,12 +2819,21 @@ import { existsSync as existsSync6, mkdirSync as mkdirSync6, chmodSync, writeFil
 import os3 from "os";
 import path9 from "path";
 import { gunzipSync } from "zlib";
-var URL_PATTERN, parseTunnelUrl, octalAt, extractSingleFile, ENV_PIN, assetName, binaryFileName, cacheBase, resolveLatestTag, mb, downloadWithProgress, binaryEchoes, resolveBinary, startTunnel;
+var URL_PATTERN, parseTunnelUrl, TAG_PATTERN, assertSafeTag, octalAt, extractSingleFile, ENV_PIN, assetName, binaryFileName, cacheBase, resolveLatestTag, mb, downloadWithProgress, binaryEchoes, resolveBinary, startTunnel;
 var init_tunnel = __esm({
   "src/net/tunnel.ts"() {
     "use strict";
     URL_PATTERN = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/iu;
     parseTunnelUrl = (chunk) => URL_PATTERN.exec(chunk)?.[0];
+    TAG_PATTERN = /^\d{4}\.\d+\.\d+(-[A-Za-z0-9.]+)?$/u;
+    assertSafeTag = (tag) => {
+      if (!TAG_PATTERN.test(tag)) {
+        throw new Error(
+          `cloudflared version "${tag}" is not a valid release tag (expected e.g. 2025.10.1)`
+        );
+      }
+      return tag;
+    };
     octalAt = (block, offset, length) => {
       const raw = block.subarray(offset, offset + length).toString("utf-8");
       const digits = raw.replace(/[\0 ]/gu, "");
@@ -2856,10 +2926,15 @@ var init_tunnel = __esm({
           `cloudflared publishes no build for ${platform}/${process.arch} \u2014 install it and put \`cloudflared\` on PATH`
         );
       }
-      const tag = process.env[ENV_PIN] ?? await resolveLatestTag();
+      const tag = process.env[ENV_PIN] ? assertSafeTag(process.env[ENV_PIN]) : assertSafeTag(await resolveLatestTag());
       const root = path9.join(cacheBase(platform, process.env, os3.homedir()), "frogoe", "cloudflared");
       const dir = path9.join(root, tag);
       const bin = path9.join(dir, binaryFileName(platform));
+      const rootResolved = path9.resolve(root);
+      const binResolved = path9.resolve(bin);
+      if (!binResolved.startsWith(rootResolved + path9.sep)) {
+        throw new Error("cloudflared binary path escaped the frogoe cache \u2014 refusing to execute");
+      }
       if (existsSync6(bin) && binaryEchoes(bin, tag)) return { downloaded: false, path: bin };
       onProgress?.(`downloading cloudflared ${tag} (~25 MB, once)\u2026`);
       const res = await fetch(
@@ -2884,7 +2959,7 @@ var init_tunnel = __esm({
     startTunnel = async (port, options) => {
       const timeoutMs = options?.timeoutMs ?? 2e4;
       const bin = await resolveBinary(options?.onProgress);
-      return new Promise((resolve, reject) => {
+      return new Promise((resolve2, reject) => {
         const child = spawn(
           bin.path,
           ["tunnel", "--url", `http://localhost:${port}`, "--no-autoupdate"],
@@ -2922,7 +2997,7 @@ var init_tunnel = __esm({
             reject(new Error(tail ? `${base} \u2014 ${tail}` : base));
             return;
           }
-          resolve({ exited, stop: killTree, url });
+          resolve2({ exited, stop: killTree, url });
         };
         const timer = setTimeout(() => {
           finish(
@@ -2959,10 +3034,10 @@ var init_tunnel = __esm({
 // src/commands/run.ts
 var run_exports2 = {};
 __export(run_exports2, {
-  command: () => command6
+  command: () => command7
 });
-import { defineCommand as defineCommand6 } from "citty";
-var NUDGE_MS, printQr, message, command6;
+import { defineCommand as defineCommand7 } from "citty";
+var NUDGE_MS, printQr, message, command7;
 var init_run2 = __esm({
   "src/commands/run.ts"() {
     "use strict";
@@ -2981,7 +3056,7 @@ var init_run2 = __esm({
       });
     };
     message = (error) => error instanceof Error ? error.message : String(error);
-    command6 = defineCommand6({
+    command7 = defineCommand7({
       args: {
         dir: { type: "positional", required: false, description: "game folder (default: cwd)" },
         port: { type: "string", description: "port (default: random free)" },
@@ -3081,13 +3156,486 @@ var init_run2 = __esm({
   }
 });
 
+// src/utils/skillsManifest.ts
+import { execFile } from "child_process";
+import { createHash as createHash2 } from "crypto";
+import { existsSync as existsSync7, readdirSync as readdirSync3, readFileSync as readFileSync7, statSync as statSync2 } from "fs";
+import { homedir } from "os";
+import { isAbsolute, join, relative, resolve, sep } from "path";
+import { promisify } from "util";
+function isCoreSkill(name) {
+  return name === ENTRY_SKILL || name.startsWith("frogoe-");
+}
+function listFilesSorted(dir) {
+  const out = [];
+  const walk = (d) => {
+    for (const name of readdirSync3(d)) {
+      if (name === ".DS_Store") continue;
+      const p = join(d, name);
+      if (statSync2(p).isDirectory()) walk(p);
+      else out.push(p);
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+function hashSkillBundle(skillDir) {
+  const files = listFilesSorted(skillDir);
+  const h = createHash2("sha256");
+  for (const f of files) {
+    const rel = relative(skillDir, f).split(sep).join("/");
+    h.update(rel);
+    h.update("\0");
+    const ext = rel.slice(rel.lastIndexOf("."));
+    const buf = readFileSync7(f);
+    if (TEXT_EXT.has(ext)) h.update(buf.toString("utf8").replace(/\r\n/g, "\n"), "utf8");
+    else h.update(buf);
+    h.update("\0");
+  }
+  return { hash: h.digest("hex").slice(0, 16), files: files.length };
+}
+function buildManifest(skillsRoot, meta) {
+  const names = readdirSync3(skillsRoot).filter((n) => existsSync7(join(skillsRoot, n, "SKILL.md"))).sort();
+  const skills = {};
+  for (const name of names) skills[name] = hashSkillBundle(join(skillsRoot, name));
+  return { source: meta.source, skills };
+}
+function agentLabel(hostDir) {
+  const name = hostDir.replace(/^\.+/, "");
+  return name === "claude" ? "claude-code" : name || "unknown";
+}
+function agentFromDir(dir) {
+  const parts = dir.split(sep).filter(Boolean);
+  const i = parts.lastIndexOf("skills");
+  return agentLabel(i > 0 ? parts[i - 1] : parts[parts.length - 1] ?? "");
+}
+function listSubdirs(dir) {
+  try {
+    return readdirSync3(dir, { withFileTypes: true }).filter((e) => e.isDirectory() || e.isSymbolicLink()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+function discoverSkillRoots(base, scope) {
+  const candidates = [];
+  const add = (hostBase, host) => {
+    const dir = join(hostBase, host, "skills");
+    if (existsSync7(dir) && statSync2(dir).isDirectory())
+      candidates.push({ dir, agent: agentLabel(host), scope });
+  };
+  for (const host of listSubdirs(base)) add(base, host);
+  const xdg = join(base, ".config");
+  for (const host of listSubdirs(xdg)) add(xdg, host);
+  return candidates.sort((a, b) => {
+    if (a.agent !== b.agent) {
+      if (a.agent === "claude-code") return -1;
+      if (b.agent === "claude-code") return 1;
+      return a.agent.localeCompare(b.agent);
+    }
+    return a.dir.localeCompare(b.dir);
+  });
+}
+function scopeForDir(dir, home, cwd) {
+  const norm = (p) => {
+    const r = resolve(p);
+    return r.endsWith(sep) ? r : r + sep;
+  };
+  const d = norm(dir);
+  if (d.startsWith(norm(cwd))) return "project";
+  if (d.startsWith(norm(home))) return "global";
+  return "project";
+}
+function locateInstall(skillNames, opts = {}) {
+  if (opts.dir) {
+    return existsSync7(opts.dir) ? {
+      dir: opts.dir,
+      agent: agentFromDir(opts.dir),
+      scope: scopeForDir(opts.dir, opts.home ?? homedir(), opts.cwd ?? process.cwd())
+    } : null;
+  }
+  const roots = [
+    ...discoverSkillRoots(opts.home ?? homedir(), "global"),
+    ...discoverSkillRoots(opts.cwd ?? process.cwd(), "project")
+  ];
+  for (const root of roots) {
+    if (skillNames.some((n) => existsSync7(join(root.dir, n, "SKILL.md")))) return root;
+  }
+  return null;
+}
+function hashInstalled(root, skillNames) {
+  const out = {};
+  for (const name of skillNames) {
+    const skillDir = join(root.dir, name);
+    if (existsSync7(join(skillDir, "SKILL.md"))) out[name] = hashSkillBundle(skillDir);
+  }
+  return out;
+}
+function diffSkills(installed, latest) {
+  const skills = [];
+  const summary = { current: 0, outdated: 0, missing: 0, coreMissing: 0 };
+  for (const name of Object.keys(latest.skills).sort()) {
+    const latestEntry = latest.skills[name];
+    const installedEntry = installed[name];
+    let status;
+    if (!installedEntry) status = "missing";
+    else if (installedEntry.hash === latestEntry.hash) status = "current";
+    else status = "outdated";
+    if (status === "current") summary.current++;
+    else if (status === "outdated") summary.outdated++;
+    else {
+      summary.missing++;
+      if (isCoreSkill(name)) summary.coreMissing++;
+    }
+    skills.push({
+      name,
+      status,
+      installedHash: installedEntry?.hash,
+      latestHash: latestEntry.hash
+    });
+  }
+  return {
+    updateAvailable: summary.outdated > 0 || summary.coreMissing > 0,
+    summary,
+    skills
+  };
+}
+function findRepoManifest(cwd = process.cwd()) {
+  let dir = cwd;
+  for (let i = 0; i < 16; i++) {
+    const p = join(dir, MANIFEST_FILE);
+    if (existsSync7(p)) return p;
+    const parent = join(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function asSkillsManifest(data, sourceLabel) {
+  const m = data;
+  if (!m || typeof m !== "object" || typeof m.skills !== "object" || m.skills === null) {
+    throw new Error(`Malformed skills manifest from ${sourceLabel}`);
+  }
+  return m;
+}
+async function fetchManifest(url) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, { signal: controller.signal, headers: { Connection: "close" } });
+    if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
+    return asSkillsManifest(await res.json(), url);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function remoteHeadSha(repoSlug) {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["ls-remote", `https://github.com/${repoSlug}.git`, "refs/heads/main"],
+      { timeout: FETCH_TIMEOUT_MS, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } }
+    );
+    const sha = stdout.split(/\s+/)[0]?.trim() ?? "";
+    return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+function resolveLocalManifest(source) {
+  const direct = source.endsWith(".json") ? source : join(source, MANIFEST_FILE);
+  if (existsSync7(direct)) return JSON.parse(readFileSync7(direct, "utf8"));
+  const skillsRoot = source.endsWith("skills") ? source : join(source, "skills");
+  if (existsSync7(skillsRoot)) return buildManifest(skillsRoot, { source: skillsRoot });
+  throw new Error(`No skills manifest found at: ${source}`);
+}
+async function fetchRemoteManifest(source) {
+  if (source?.startsWith("http")) return fetchManifest(source);
+  const repoSlug = source ?? DEFAULT_REPO_SLUG;
+  const sha = await remoteHeadSha(repoSlug);
+  if (sha) {
+    try {
+      return await fetchManifest(
+        `https://raw.githubusercontent.com/${repoSlug}/${sha}/${MANIFEST_FILE}`
+      );
+    } catch {
+    }
+  }
+  return fetchManifest(`https://raw.githubusercontent.com/${repoSlug}/main/${MANIFEST_FILE}`);
+}
+async function resolveLatestManifest(source, cwd = process.cwd(), opts = {}) {
+  if (source && (source.startsWith(".") || isAbsolute(source))) {
+    return resolveLocalManifest(source);
+  }
+  if (!source && !opts.canonical) {
+    const repoManifest = findRepoManifest(cwd);
+    if (repoManifest) return JSON.parse(readFileSync7(repoManifest, "utf8"));
+  }
+  return fetchRemoteManifest(source);
+}
+async function checkSkills(opts = {}) {
+  const latest = await resolveLatestManifest(opts.source, opts.cwd, { canonical: opts.canonical });
+  const skillNames = Object.keys(latest.skills);
+  const root = locateInstall(skillNames, { dir: opts.dir, cwd: opts.cwd, home: opts.home });
+  const installed = root ? hashInstalled(root, skillNames) : {};
+  const diff = diffSkills(installed, latest);
+  return {
+    location: root?.dir ?? null,
+    agent: root?.agent ?? null,
+    scope: root?.scope ?? null,
+    updateAvailable: diff.updateAvailable,
+    summary: diff.summary,
+    skills: diff.skills,
+    lockMissing: false
+  };
+}
+var execFileAsync, TEXT_EXT, DEFAULT_REPO_SLUG, MANIFEST_FILE, FETCH_TIMEOUT_MS, ENTRY_SKILL;
+var init_skillsManifest = __esm({
+  "src/utils/skillsManifest.ts"() {
+    "use strict";
+    execFileAsync = promisify(execFile);
+    TEXT_EXT = /* @__PURE__ */ new Set([
+      ".md",
+      ".txt",
+      ".mjs",
+      ".js",
+      ".ts",
+      ".jsx",
+      ".tsx",
+      ".html",
+      ".css",
+      ".json",
+      ".svg",
+      ".csv",
+      ".yml",
+      ".yaml"
+    ]);
+    DEFAULT_REPO_SLUG = "frogoe/engine";
+    MANIFEST_FILE = "skills-manifest.json";
+    FETCH_TIMEOUT_MS = 4e3;
+    ENTRY_SKILL = "frogoe";
+  }
+});
+
+// src/commands/skills.ts
+var skills_exports = {};
+__export(skills_exports, {
+  command: () => command8
+});
+import { defineCommand as defineCommand8 } from "citty";
+import { execFileSync, spawn as spawn2 } from "child_process";
+function hasNpx() {
+  try {
+    const cmd = process.platform === "win32" ? "npx.cmd" : "npx";
+    const exe = process.platform === "win32" ? "cmd.exe" : cmd;
+    const args = process.platform === "win32" ? ["/d", "/s", "/c", "npx.cmd", "--version"] : ["--version"];
+    execFileSync(exe, args, { stdio: "ignore", timeout: 5e3 });
+    return true;
+  } catch {
+    try {
+      execFileSync("npx", ["--version"], { stdio: "ignore", timeout: 5e3 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+function hasGit() {
+  try {
+    execFileSync("git", ["--version"], { stdio: "ignore", timeout: 5e3 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function buildNpxCommand(args) {
+  if (process.platform === "win32") {
+    return { command: "cmd.exe", args: ["/d", "/s", "/c", "npx.cmd", ...args] };
+  }
+  return { command: "npx", args: [...args] };
+}
+function spawnNpx(args) {
+  const npx = buildNpxCommand(args);
+  return new Promise((resolve2, reject) => {
+    const child = spawn2(npx.command, npx.args, {
+      stdio: ["inherit", 2, 2],
+      timeout: 3e5,
+      env: {
+        ...process.env,
+        GIT_CLONE_PROTECTION_ACTIVE: "0",
+        GIT_LFS_SKIP_SMUDGE: "1"
+      }
+    });
+    child.on("close", (code, signal) => {
+      if (code === 0) resolve2();
+      else if (signal === "SIGINT" || code === 130) resolve2();
+      else reject(new Error(`npx ${args.join(" ")} exited with code ${code}`));
+    });
+    child.on("error", reject);
+  });
+}
+async function installSkills(selection) {
+  const skillArgs = selection === "*" ? ["--skill", "*"] : selection.flatMap((n) => ["--skill", n]);
+  if (!hasNpx()) throw new Error("npx not found. Install Node.js and retry.");
+  if (!hasGit()) throw new Error("git not found. Install git and retry.");
+  await spawnNpx(["skills", "add", SOURCE_URL, ...skillArgs, ...GLOBAL_INSTALL_ARGS_TAIL]);
+}
+function renderCheck(result) {
+  console.log();
+  console.log("frogoe skills");
+  console.log();
+  if (!result.location) {
+    console.log("  No frogoe skills found in the usual locations.");
+    console.log("  Install: npx skills add frogoe/engine");
+    console.log("  Or: frogoe skills update");
+    console.log();
+    return;
+  }
+  console.log(`  Location  ${result.location} (${result.agent})`);
+  console.log();
+  const parts = [];
+  parts.push(`\u2713 ${result.summary.current} current`);
+  if (result.summary.outdated) parts.push(`\u2191 ${result.summary.outdated} outdated`);
+  if (result.summary.coreMissing) parts.push(`\u25E6 ${result.summary.coreMissing} core not installed`);
+  const onDemandMissing = result.summary.missing - result.summary.coreMissing;
+  if (onDemandMissing) parts.push(`\u25E6 ${onDemandMissing} available on demand`);
+  console.log(`  ${parts.join("   ")}`);
+  for (const s of result.skills.filter((x) => x.status === "outdated")) {
+    console.log(`    \u2191 ${s.name}`);
+  }
+  for (const s of result.skills.filter((x) => x.status === "missing" && isCoreSkill(x.name))) {
+    console.log(`    \u25E6 ${s.name} (core)`);
+  }
+  console.log();
+  if (result.updateAvailable) {
+    console.log("  Update: frogoe skills update  or  npx skills add frogoe/engine");
+  } else {
+    console.log("  Installed skills are up to date");
+  }
+  console.log();
+}
+var GLOBAL_INSTALL_ARGS_TAIL, SOURCE_URL, checkCommand, updateCommand, command8;
+var init_skills = __esm({
+  "src/commands/skills.ts"() {
+    "use strict";
+    init_skillsManifest();
+    GLOBAL_INSTALL_ARGS_TAIL = [
+      "--global",
+      "--agent",
+      "claude-code",
+      "universal",
+      "--copy",
+      "--full-depth",
+      "--yes"
+    ];
+    SOURCE_URL = "https://github.com/frogoe/engine";
+    checkCommand = defineCommand8({
+      meta: { name: "check", description: "Check whether installed skills are the latest version" },
+      args: {
+        json: { type: "boolean", description: "Output as JSON", default: false },
+        dir: { type: "string", description: "Skills directory to check" },
+        source: { type: "string", description: "Where 'latest' comes from" }
+      },
+      async run({ args }) {
+        try {
+          const result = await checkSkills({
+            dir: args.dir,
+            source: args.source,
+            canonical: true
+          });
+          if (args.json) {
+            console.log(JSON.stringify(result, null, 2));
+          } else {
+            renderCheck(result);
+          }
+          if (result.updateAvailable) process.exitCode = 1;
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          if (msg.includes("Malformed") || msg.includes("HTTP") || msg.includes("fetch")) {
+            console.error(`Skills check failed (offline or GitHub unreachable): ${msg}`);
+            console.error("Try: npx skills add frogoe/engine  \u2014 or retry when online.");
+          } else {
+            console.error(`Skills check failed: ${msg}`);
+          }
+          process.exitCode = 1;
+        }
+      }
+    });
+    updateCommand = defineCommand8({
+      meta: {
+        name: "update",
+        description: "Update frogoe skills to the latest (core + installed). Pass names to also install them."
+      },
+      args: {
+        json: { type: "boolean", description: "Output as JSON", default: false }
+      },
+      async run({ args }) {
+        const requested = (args._ ?? []).map(String).filter(Boolean);
+        const invalid = requested.filter((n) => !/^[a-z0-9][a-z0-9._-]*$/i.test(n));
+        if (invalid.length) {
+          console.error(`Invalid skill name(s): ${invalid.join(", ")}`);
+          process.exitCode = 1;
+          return;
+        }
+        try {
+          const check = await checkSkills({ canonical: true });
+          const toInstall = /* @__PURE__ */ new Set();
+          for (const s of check.skills) {
+            if (s.status === "outdated" || s.status === "missing" && isCoreSkill(s.name))
+              toInstall.add(s.name);
+          }
+          for (const n of requested) toInstall.add(n);
+          if (toInstall.size === 0) {
+            const msg = "Installed skills are already up to date.";
+            if (args.json) console.log(JSON.stringify({ ...check, message: msg }, null, 2));
+            else console.log(msg);
+            return;
+          }
+          const list = [...toInstall];
+          console.log(`Updating ${list.length} skill(s): ${list.join(", ")}`);
+          await installSkills(list);
+          const verify = await checkSkills({ canonical: true });
+          if (args.json) console.log(JSON.stringify(verify, null, 2));
+          else renderCheck(verify);
+          if (verify.updateAvailable) process.exitCode = 1;
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          console.error(`Update failed: ${msg}`);
+          if (msg.includes("npx") || msg.includes("git")) {
+            console.error("Install Node.js and git, then retry: npx skills add frogoe/engine");
+          }
+          process.exitCode = 1;
+        }
+      }
+    });
+    command8 = defineCommand8({
+      meta: {
+        name: "skills",
+        description: "Install, check, and update frogoe skills for AI coding tools"
+      },
+      subCommands: { check: checkCommand, update: updateCommand },
+      args: {},
+      async run() {
+        try {
+          console.log("Installing all frogoe skills...");
+          await installSkills("*");
+          const result = await checkSkills({ canonical: true });
+          renderCheck(result);
+        } catch (err) {
+          console.error(`Install failed: ${err instanceof Error ? err.message : String(err)}`);
+          process.exitCode = 1;
+        }
+      }
+    });
+  }
+});
+
 // src/cli.ts
-import { defineCommand as defineCommand7, runMain } from "citty";
+import { defineCommand as defineCommand9, runMain } from "citty";
 
 // package.json
 var package_default = {
   name: "frogoe",
-  version: "0.2.2",
+  version: "0.3.1",
   description: "froge CLI \u2014 the agent's hands: init, add, run, check, bundle",
   homepage: "https://github.com/frogoe/engine#readme",
   bugs: "https://github.com/frogoe/engine/issues",
@@ -3153,23 +3701,27 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
 var HELP = `frogoe ${VERSION} \u2014 write a closure, ship a game
 
 Commands:
-  init [name]   scaffold a runnable game folder
-  add <block>   copy a registry HUD block into blocks/
-  run [dir]     serve with live reload + phone QR (--tunnel: any network)
-  check [dir]   contract lint (stable finding codes; --json)
-  report [dir]  last playtest session: fps dips, errors, when
-  bundle [dir]  dissolve externals \u2192 one self-contained HTML
+  init [name]              scaffold a runnable game folder
+  add <block>              copy a registry HUD block into blocks/
+  run [dir]                serve with live reload + phone QR (--tunnel: any network)
+  lint [dir]               static contract lint \u2014 fast iteration (stable codes; --json)
+  check [dir]              full gate: lint + live Chrome sandbox (FPS, HUD outline)
+  report [dir]             last playtest session: fps dips, errors, when
+  bundle [dir]             dissolve externals \u2192 one self-contained HTML
+  skills [check|update]    skill freshness \u2014 check or update via npx skills add
 
 Docs: skills/frogoe-core \u2014 the whole contract in five references.`;
-var main = defineCommand7({
+var main = defineCommand9({
   meta: { description: HELP },
   subCommands: {
     add: () => Promise.resolve().then(() => (init_add2(), add_exports)).then((m) => m.command),
     bundle: () => Promise.resolve().then(() => (init_bundle2(), bundle_exports)).then((m) => m.command),
     check: () => Promise.resolve().then(() => (init_check3(), check_exports)).then((m) => m.command),
     init: () => Promise.resolve().then(() => (init_init2(), init_exports)).then((m) => m.command),
+    lint: () => Promise.resolve().then(() => (init_lint(), lint_exports)).then((m) => m.command),
     report: () => Promise.resolve().then(() => (init_report(), report_exports)).then((m) => m.command),
-    run: () => Promise.resolve().then(() => (init_run2(), run_exports2)).then((m) => m.command)
+    run: () => Promise.resolve().then(() => (init_run2(), run_exports2)).then((m) => m.command),
+    skills: () => Promise.resolve().then(() => (init_skills(), skills_exports)).then((m) => m.command)
   }
 });
 await runMain(main);

package/dist/templates/_shared/AGENTS.md

@@ -4,14 +4,14 @@
 
 **Always read the relevant skill before writing or modifying game code.** Skills encode the frogoe contract and creative direction that generic docs don't cover. Skipping them produces broken games.
 
-**Doing anything with frogoe?** Read the `frogoe` skill — it confirms the BRIEF (verb, mood, palette) up front and routes every request. The domain skills it routes to:
+**Doing anything with frogoe?** Read the `/frogoe` skill — it confirms the BRIEF (verb, mood, palette) up front and routes every request. The domain skills it routes to:
 
-- `frogoe-core` — the technical contract: folder form, `defineGame` closure, four nouns, HUD bindings, external libraries. Read before writing any game code.
-- `frogoe-creative` — house style: three dials (VARIANCE/MOTION/DENSITY), lazy defaults, typography, palettes, game feel. Read when choosing how a game looks.
-- `frogoe-cli` — CLI dev loop: init, add, run, check, bundle. Finding codes table for self-healing.
-- `frogoe-registry` — HUD block catalog: find, evaluate, install, author new blocks.
+- `/frogoe-core` — the technical contract: folder form, `defineGame` closure, four nouns, HUD bindings, external libraries. Read before writing any game code.
+- `/frogoe-creative` — house style: three dials (VARIANCE/MOTION/DENSITY), lazy defaults, typography, palettes, game feel. Read when choosing how a game looks.
+- `/frogoe-cli` — CLI dev loop: init, add, run, check, bundle, report. Finding codes split into `finding-codes.md` / `live-sandbox.md` / `bundle.md` for self-healing.
+- `/frogoe-registry` — HUD block catalog: find, evaluate, install, author new blocks.
 
-Skills live at `.agents/skills/` (install via `npx skills add frogoe/engine`). Missing or stale? Re-run the install command and restart the agent session.
+Skills live at `.claude/skills/` and `.agents/skills/` (install via `npx skills add frogoe/engine`; both mirrors stay byte-identical). Missing or stale? Re-run the install and restart the agent session. Check freshness: `frogoe skills check`.
 
 ## The contract
 
@@ -54,15 +54,16 @@ The platform draws NOTHING. Everything visible is your code + HUD blocks from th
 ```bash
 frogoe run                  # serve with live reload + phone QR (safe-area only exists on real devices)
 frogoe run --tunnel         # + public URL — phone works on any network (cloudflared, auto-downloaded once)
-frogoe check                # static contract lint (stable finding codes; --json for CI)
-frogoe check --live         # + headless Chrome: FPS, playability, HUD outline, screenshots
-frogoe bundle               # one self-contained HTML (externals dissolved, zero runtime requests)
 frogoe add <block>          # copy a HUD block into blocks/ (score, hearts, fuel, game-over, etc.)
+frogoe lint                 # fast static contract lint (stable finding codes; --json for CI)
+frogoe check                # full gate: lint + headless Chrome — FPS, playability, HUD outline, screenshots
+frogoe bundle               # one self-contained HTML (externals dissolved) — only after check passes
 ```
 
 > **Agents must run `frogoe check` after ANY code change** and fix all errors before
-> presenting the result. Warnings should be reviewed before bundling. Use `--json` for
-> machine-readable findings that can be fixed programmatically.
+> presenting the result. `frogoe lint` is the fast static half for iteration; `frogoe
+check` is the full gate (static + live sandbox) and MUST exit 0 before `frogoe
+bundle`. Use `--json` for machine-readable findings that can be fixed programmatically.
 
 ## Project structure
 
@@ -79,8 +80,8 @@ frogoe add <block>          # copy a HUD block into blocks/ (score, hearts, fuel
 After creating or editing any file, **always** run:
 
 ```bash
-frogoe check             # static: BRIEF validation, folder structure, input patterns
-frogoe check --live      # browser: runtime errors, canvas painted, FPS, playability
+frogoe lint              # fast static: BRIEF validation, folder structure, input patterns
+frogoe check             # full gate: + browser — runtime errors, canvas painted, FPS, playability
 ```
 
 Fix all errors before presenting the result. Common findings:

package/dist/templates/_shared/CLAUDE.md

@@ -4,14 +4,14 @@
 
 **Always read the relevant skill before writing or modifying game code.** Skills encode the frogoe contract and creative direction that generic docs don't cover. Skipping them produces broken games.
 
-**Doing anything with frogoe?** Start at the `frogoe` skill — it confirms the BRIEF (verb, mood, palette) up front and routes every request. The domain skills it routes to:
+**Doing anything with frogoe?** Start at the `/frogoe` skill — it confirms the BRIEF (verb, mood, palette) up front and routes every request. The domain skills it routes to:
 
-- `frogoe-core` — the technical contract: folder form, `defineGame` closure, four nouns, HUD bindings, external libraries. Read before writing any game code.
-- `frogoe-creative` — house style: three dials (VARIANCE/MOTION/DENSITY), lazy defaults, typography, palettes, game feel. Read when choosing how a game looks.
-- `frogoe-cli` — CLI dev loop: init, add, run, check, bundle. Finding codes table for self-healing.
-- `frogoe-registry` — HUD block catalog: find, evaluate, install, author new blocks.
+- `/frogoe-core` — the technical contract: folder form, `defineGame` closure, four nouns, HUD bindings, external libraries. Read before writing any game code.
+- `/frogoe-creative` — house style: three dials (VARIANCE/MOTION/DENSITY), lazy defaults, typography, palettes, game feel. Read when choosing how a game looks.
+- `/frogoe-cli` — CLI dev loop: init, add, run, check, bundle, report. Finding codes split into `finding-codes.md` / `live-sandbox.md` / `bundle.md` for self-healing.
+- `/frogoe-registry` — HUD block catalog: find, evaluate, install, author new blocks.
 
-Skills live at `.agents/skills/` (install via `npx skills add frogoe/engine`). Missing or stale? Re-run the install command and restart the agent session.
+Skills live at `.claude/skills/` and `.agents/skills/` (install via `npx skills add frogoe/engine`; both mirrors stay byte-identical). Missing or stale? Re-run the install and restart the agent session. Check freshness: `frogoe skills check`.
 
 ## The contract
 
@@ -54,15 +54,16 @@ The platform draws NOTHING. Everything visible is your code + HUD blocks from th
 ```bash
 frogoe run                  # serve with live reload + phone QR (safe-area only exists on real devices)
 frogoe run --tunnel         # + public URL — phone works on any network (cloudflared, auto-downloaded once)
-frogoe check                # static contract lint (stable finding codes; --json for CI)
-frogoe check --live         # + headless Chrome: FPS, playability, HUD outline, screenshots
-frogoe bundle               # one self-contained HTML (externals dissolved, zero runtime requests)
 frogoe add <block>          # copy a HUD block into blocks/ (score, hearts, fuel, game-over, etc.)
+frogoe lint                 # fast static contract lint (stable finding codes; --json for CI)
+frogoe check                # full gate: lint + headless Chrome — FPS, playability, HUD outline, screenshots
+frogoe bundle               # one self-contained HTML (externals dissolved) — only after check passes
 ```
 
 > **Agents must run `frogoe check` after ANY code change** and fix all errors before
-> presenting the result. Warnings should be reviewed before bundling. Use `--json` for
-> machine-readable findings that can be fixed programmatically.
+> presenting the result. `frogoe lint` is the fast static half for iteration; `frogoe
+check` is the full gate (static + live sandbox) and MUST exit 0 before `frogoe
+bundle`. Use `--json` for machine-readable findings that can be fixed programmatically.
 
 ## Project structure
 
@@ -79,8 +80,8 @@ frogoe add <block>          # copy a HUD block into blocks/ (score, hearts, fuel
 After creating or editing any file, **always** run:
 
 ```bash
-frogoe check             # static: BRIEF validation, folder structure, input patterns
-frogoe check --live      # browser: runtime errors, canvas painted, FPS, playability
+frogoe lint              # fast static: BRIEF validation, folder structure, input patterns
+frogoe check             # full gate: + browser — runtime errors, canvas painted, FPS, playability
 ```
 
 Fix all errors before presenting the result. Common findings:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frogoe",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "froge CLI — the agent's hands: init, add, run, check, bundle",
   "homepage": "https://github.com/frogoe/engine#readme",
   "bugs": "https://github.com/frogoe/engine/issues",