@looop-games/cli 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog — @looop-games/cli
+
+The `looop` command itself. This is the one piece of Looop you install from npm;
+everything else (the component library, the room primitives, your game's skills)
+lives in the engine and has [its own changelog](https://docs.looop.games), which
+you can read with `looop changelog`.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> Entries for 0.1.9 and earlier were reconstructed from the release history after
+> the fact, so they are short and may miss detail. Everything from 0.1.10 on is
+> written as the change is made.
+
+## [Unreleased]
+
+## [0.1.10] - 2026-07-12
+
+### Added
+- `looop changelog` — what changed in the engine. With no arguments it shows
+  every release newer than the version your game is pinned to; `looop changelog
+  <version>` shows one release, `--all` shows the whole history.
+- `looop update` now prints the changelog for every version it crosses, with
+  **BREAKING** entries called out separately, so you find out what has to change
+  in your game at the moment you take the update — not when something breaks.
+
+## [0.1.9] - 2026-07-12
+
+### Changed
+- `looop create` now signs you in and downloads the engine, which carries the
+  starter game and your game's skills. The login used to happen at your first
+  `looop dev`, one command later.
+- The published package is now just the command itself. Everything you receive as
+  a creator — the starter game, the skills, the shared libraries — comes from the
+  engine, so the two can no longer drift apart.
+
+## [0.1.8] - 2026-07-12
+
+### Added
+- `looop feedback` sends the files a report attaches, so whoever reads it can see
+  the code you are talking about.
+
+## [0.1.7] - 2026-07-11
+
+### Changed
+- `looop update` refreshes your game's skills and `AGENTS.md`, and reports every
+  file it touched. A file you edited yourself is kept, not overwritten.
+
+## [0.1.6] - 2026-07-11
+
+### Added
+- `looop update` — move a game onto the latest engine release and re-pin it.
+
+## [0.1.5] - 2026-07-11
+
+### Added
+- `looop feedback` — send the reports under `notes/feedback/` to the Looop team.
+
+## [0.1.4] - 2026-07-11
+
+### Fixed
+- `looop create` installs cleanly on macOS (`fsevents` is pre-approved along with
+  the other install scripts).
+
+## [0.1.3] - 2026-07-11
+
+### Fixed
+- `looop create` works on Windows.
+
+## [0.1.2] - 2026-07-10
+
+### Added
+- First public release. `looop create` scaffolds a game, `looop dev` runs it with
+  multiplayer, `looop publish` puts it on play.looop.games, `looop login`
+  authenticates the machine.

package/bin/looop.mjs

@@ -9,6 +9,7 @@ import { publish } from '../lib/publish.mjs';
 import { create } from '../lib/create.mjs';
 import { testCmd } from '../lib/test-cmd.mjs';
 import { update } from '../lib/update.mjs';
+import { changelog } from '../lib/changelog.mjs';
 import { sendFeedback } from '../lib/feedback.mjs';
 import { clearToken } from '../lib/config.mjs';
 
@@ -25,6 +26,7 @@ Usage:
   looop create <name>        Bootstrap a new game folder (multiplayer works out of the box)
   looop dev [--port <n>]     Run the full dev stack (game + multiplayer + services)
   looop test                 Run the game's tests (*.test.mjs) and smokes (*.smoke.mjs)
+  looop changelog [<v>]      What changed in the engine (default: everything newer than your pin)
   looop update               Move this game to the latest engine release (re-pins looop.engine)
   looop publish [--slug <s>]  Publish this game to play.looop.games (--slug for an A/B copy)
   looop feedback             Send the unsent reports under notes/feedback/ to the Looop team
@@ -57,6 +59,12 @@ try {
       const { ok } = await testCmd();
       process.exit(ok ? 0 : 1);
     }
+    case 'changelog':
+      await changelog({
+        version: rest.find((a) => !a.startsWith('--')),
+        all: rest.includes('--all'),
+      });
+      break;
     case 'update':
       await update();
       break;

package/lib/agent-surface.mjs

@@ -1,15 +1,20 @@
 // The agent surface — skills + the Layer-0 managed block — and how an update
 // reaches a repo that already exists (creator-harness Slice 2, decision Q2).
 //
-// The surface ships INSIDE the versioned engine artifact, not the npm CLI: the
-// CLI's template is only a create-time SEED (the engine is login-gated, so a
-// fresh folder can't download one before its first `dev`). From then on the
-// artifact is the source of truth. Without this, a creator's skills are frozen
-// at the version they created the game with — the exact freeze Q2 exists to end.
+// The surface ships INSIDE the versioned engine artifact, and ONLY there — the
+// npm CLI carries no copy of it. That is what makes the ownership record below
+// trustworthy: `create` places the surface by calling straight into this module
+// (against the artifact it just installed), so the bytes on disk and the hashes
+// we record come from the same place, and a fresh repo's first `update` is a
+// genuine no-op. The CLI used to seed the surface from its own bundled
+// `template/`, stamped with the ENGINE's version — a record that was false the
+// moment npm and the engine registry shipped out of step, and that made the
+// first `update` overwrite (or DELETE, via the orphan prune below) skills on a
+// repo minutes old.
 //
-// **This runs ONLY under `looop update`** (2026-07-11) — never on `dev`
-// or `publish`. It COULD run there safely (it can only ever converge a repo to
-// the engine version already pinned in its package.json, never a newer one),
+// **This runs under `looop update` — and under `looop create`** — never on
+// `dev` or `publish`. It COULD run there safely (it can only ever converge a
+// repo to the engine version already pinned in its package.json, never a newer one),
 // but a creator who ran `dev` and then found files they never wrote sitting in
 // `git status` would be right to feel we'd gone through their pockets. Updates
 // are something you ASK for. So this module writes nothing on its own schedule,
@@ -36,7 +41,7 @@
 // everything outside them (their title, their instructions below the end
 // marker) is theirs and is spliced back untouched.
 import { createHash } from 'node:crypto';
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 export const SURFACE_DIR = 'agent-surface';
@@ -269,26 +274,3 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
 
   return result;
 }
-
-// Used by `looop create`: the template seed IS the surface for a brand-new
-// repo, so record it as ours immediately. Without this the first `dev` would
-// treat a two-minute-old scaffold as an unknown pre-existing repo and adopt it.
-export function recordSeededSurface(projectDir, engineVersion) {
-  const placed = {};
-  const add = (rel) => {
-    const abs = join(projectDir, rel);
-    if (existsSync(abs)) placed[rel] = sha(readFileSync(abs));
-  };
-  const walk = (rel) => {
-    const abs = join(projectDir, rel);
-    if (!existsSync(abs)) return;
-    for (const entry of readdirSync(abs)) {
-      const child = join(rel, entry);
-      if (statSync(join(projectDir, child)).isDirectory()) walk(child);
-      else add(child);
-    }
-  };
-  walk(join('.claude', 'skills'));
-  add('AGENTS.md');
-  writeLocal(projectDir, engineVersion ?? null, placed);
-}

package/lib/changelog.mjs

@@ -0,0 +1,171 @@
+// `looop changelog` — what changed in the engine (project note azlqm2).
+//
+// The gap this closes: `looop update` used to say "Engine updated: 0.1.10 →
+// 0.1.12" and then list the SKILL FILES it rewrote. It said nothing about what
+// changed in the engine itself, so the agent crossed two versions of the shared
+// library blind — it could not know a call it makes is now wrong, or that the
+// thing it was about to hand-roll now exists.
+//
+// Two moments matter, and they are different:
+//   BEFORE an update — "what am I about to take?"   → the default, vs your pin
+//   AFTER  an update — "what do I have to change?"  → the BREAKING callout
+//
+// Reading is NOT login-gated. The version list is public by design (a version
+// number is not a secret — see builder/functions/api/creator/engine/index.ts);
+// only the DOWNLOAD carries a token. Requiring a login to read what an update
+// would do to you would be exactly backwards.
+import { findProject } from './project.mjs';
+import { readEnginePin } from './engine.mjs';
+import { getApiBase } from './config.mjs';
+import { DEFAULT_API_BASE } from './llm-shim.mjs';
+
+const RULE = '─'.repeat(64);
+
+// Semver by NUMBER. String order would put 0.1.9 after 0.1.10 and quietly show
+// the wrong set — the kind of bug nobody notices until a release is missing
+// from someone's update.
+export function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0) ? 1 : -1;
+  }
+  return 0;
+}
+
+export function selectReleases(releases, { pinned, version, all } = {}) {
+  const newestFirst = [...releases].sort((a, b) => compareVersions(b.version, a.version));
+
+  if (version) {
+    const one = newestFirst.find((r) => r.version === version);
+    if (!one) {
+      throw new Error(
+        `no engine release ${version}. Known: ${newestFirst.map((r) => r.version).join(', ')}`,
+      );
+    }
+    return [one];
+  }
+  if (all) return newestFirst;
+  // No pin means the game has never installed an engine (no `dev` yet). There is
+  // no "since" to work from, so show what it would get: the newest.
+  if (!pinned) return newestFirst.slice(0, 1);
+  return newestFirst.filter((r) => compareVersions(r.version, pinned) > 0);
+}
+
+// The actionable half. Everything else in a changelog is informative; a BREAKING
+// entry means code in THIS game has to change, so it gets hoisted out of the
+// prose and repeated on its own — with its migration line, which is the part the
+// reader actually needs.
+//
+// The marker is POSITIONAL: a breaking change is a bullet that STARTS with it.
+// Two false positives got here by loosening that, and both were found by reading
+// real output rather than by any test:
+//
+//   1. matching the bare word case-insensitively flagged the ordinary sentence
+//      "when your game turns out to be breaking a Looop rule";
+//   2. matching `**BREAKING**` anywhere on a line flagged a changelog entry that
+//      merely DESCRIBED the feature ("...calls out **BREAKING** entries
+//      separately...") — prose about breaking changes is not a breaking change.
+//
+// A callout that cries wolf is worse than no callout: it gets ignored, and the
+// next real one is ignored with it.
+// Bold form is case-insensitive (`**BREAKING**`, `**Breaking**` — the markup is
+// the deliberate part). The bare-word form must be ALL CAPS with punctuation, so
+// a bullet that merely opens with the ordinary word ("- breaking the sound
+// barrier: …") can't pass as a marker.
+const BREAKING_BOLD = /^\s*[-*]\s+\*\*breaking\*\*/i;
+const BREAKING_CAPS = /^\s*[-*]\s+BREAKING\b\s*[:—–-]/;
+const BREAKING_BULLET = { test: (l) => BREAKING_BOLD.test(l) || BREAKING_CAPS.test(l) };
+
+// True for a line that continues the bullet above it: indented, non-blank, and
+// not itself a new bullet or heading. That's how the migration line rides along.
+const CONTINUATION = /^\s+\S/;
+const NEW_BULLET_OR_HEADING = /^\s*(?:[-*]\s|#)/;
+
+export function breakingLines(notes) {
+  const lines = (notes ?? '').split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!BREAKING_BULLET.test(lines[i])) continue;
+    const block = [lines[i].trim()];
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (!CONTINUATION.test(l) || NEW_BULLET_OR_HEADING.test(l)) break;
+      block.push(l.trim());
+      i = j;
+    }
+    out.push(block.join(' '));
+  }
+  return out;
+}
+
+export function renderReleases(selected, { pinned, latest } = {}) {
+  const out = [];
+  if (!selected.length) {
+    out.push(`Engine ${pinned ?? '(unpinned)'} — nothing new. This game is up to date with ${latest}.`);
+    return out.join('\n');
+  }
+
+  const head =
+    selected.length === 1
+      ? `Engine ${selected[0].version}`
+      : `${selected.length} engine releases newer than ${pinned}, newest first (latest is ${latest})`;
+  out.push(head, '');
+
+  for (const r of selected) {
+    out.push(RULE);
+    out.push(`## ${r.version}`);
+    out.push('');
+    out.push(r.notes?.trim() ? r.notes.trim() : '  (no notes recorded — this release predates the changelog)');
+    out.push('');
+  }
+
+  const breaking = selected.flatMap((r) => breakingLines(r.notes).map((l) => `   ${r.version}  ${l}`));
+  if (breaking.length) {
+    out.push(RULE);
+    out.push('');
+    out.push(
+      `⚠  ${breaking.length} BREAKING change${breaking.length === 1 ? '' : 's'} in this range.`,
+      '   These are the entries that mean code in THIS game has to change — check each one',
+      '   against the game before you call the update done.',
+      '',
+      ...breaking,
+      '',
+    );
+  }
+  return out.join('\n');
+}
+
+export async function fetchReleases({ apiBase, fetchImpl = fetch }) {
+  const res = await fetchImpl(`${apiBase}/api/creator/engine`);
+  if (!res.ok) throw new Error(`could not read the engine changelog (HTTP ${res.status})`);
+  const body = await res.json();
+  // An older platform has no `releases` key. Printing "nothing new" there would
+  // be a lie in the most dangerous direction — it reads as "safe to update".
+  //
+  // Do NOT tell them to upgrade the CLI: the missing half is the PLATFORM's, and
+  // a creator cannot deploy it. Advice they can't act on is worse than none.
+  if (!Array.isArray(body.releases)) {
+    throw new Error(
+      'this Looop platform is not serving the engine changelog yet. Nothing is wrong with your ' +
+        'game — try again later, and `npx looop update` still works in the meantime.',
+    );
+  }
+  return body;
+}
+
+export async function changelog({
+  cwd = process.cwd(),
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  fetchImpl = fetch,
+  readPin,
+  version,
+  all = false,
+} = {}) {
+  const pinned = readPin ? readPin() : readEnginePin(findProject(cwd).dir);
+  const { releases, latest } = await fetchReleases({ apiBase, fetchImpl });
+  const selected = selectReleases(releases, { pinned, version, all });
+  log(renderReleases(selected, { pinned, latest }));
+  return { pinned, latest, selected };
+}

package/lib/create.mjs

@@ -2,26 +2,45 @@
 //
 // The create-next-app gesture: one command → a complete folder that is its
 // own repo, where `looop dev` immediately serves a WORKING multiplayer game
-// (the platform is not optional — the template joins a room on line one, no
+// (the platform is not optional — the scaffold joins a room on line one, no
 // "add multiplayer later" tier). The folder name is the slug.
 //
-// The scaffold lives as REAL FILES in ../template/ (creator-harness Slice 1)
-// — edit the template there, not string literals here. `create` copies it
-// with a {{name}} substitution pass. One rename on copy, an npm-pack
-// artifact: `gitignore` → `.gitignore` (npm silently strips .gitignore
-// files from packages). package.json is generated below instead of shipped
-// in the template (nested package.json files confuse npm's packer, and it
-// carries the dynamic cliSpec anyway).
+// ── Where the creator's files come from ─────────────────────────────────────
+//
+// EVERYTHING a creator receives comes from the versioned engine artifact: the
+// starter game (`scaffold/`) and the agent surface (`agent-surface/` — skills
+// plus the Layer-0 managed block). This npm package ships CODE ONLY.
+//
+// It used to ship a `template/` folder, and that was a bug with a long fuse.
+// npm and the engine registry are two independent, immutable release lanes, so
+// the two copies of the surface drifted the moment one shipped without the
+// other — and `create` seeded from the CLI while stamping the ownership record
+// with the ENGINE's version, so that record was a lie the day it was written.
+// The creator paid for it on their first `looop update`: skills they had never
+// touched changed under them, and a skill the CLI shipped but the engine didn't
+// was silently DELETED (agent-surface.mjs prunes files it owns that the
+// artifact no longer lists). On a repo minutes old.
+//
+// One authored copy, one release lane. A skill or scaffold change now ships
+// with an engine release alone; the CLI is released only when the CLI's own
+// code changes.
+//
+// The consequence, and it is deliberate: `create` needs the engine, and the
+// engine download is login-gated — so CREATE SIGNS YOU IN. That gate existed
+// anyway, one command later, at first `dev`. This moves it to where the creator
+// is already waiting and leaves `dev` instant.
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync, symlinkSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, relative, dirname } from 'node:path';
 import { getApiBase } from './config.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
 import { runNpm } from './npm.mjs';
-import { recordSeededSurface } from './agent-surface.mjs';
+import { ensureEngine } from './engine.mjs';
+import { reconcileAgentSurface } from './agent-surface.mjs';
 
-export const TEMPLATE_DIR = join(import.meta.dirname, '..', 'template');
+// The starter game, inside the installed engine artifact.
+export const SCAFFOLD_DIR = 'scaffold';
 
 const NAME_OK = /^[a-z0-9][a-z0-9-]{0,40}$/;
 
@@ -48,69 +67,37 @@ const ALLOW_SCRIPTS = { esbuild: true, workerd: true, fsevents: true };
 // what create-time provisioning exists to prevent.
 const PLAYWRIGHT_SPEC = '^1.61.1';
 
-// Resolve the engine pin AT CREATE TIME so the initial commit — the
-// milestone-1 revert baseline — already carries `looop.engine`. Without
-// this, first `looop dev` writes the pin AFTER the baseline: the fresh repo
-// starts dirty, and a milestone-1 reject (`git reset --hard`) deletes the
-// pin, so the next dev re-resolves "latest" and can silently change engine
-// versions under a revert. The version LIST endpoint is public (a version
-// number is not a secret); the engine BYTES stay login-gated at first dev.
-async function resolveEnginePin(apiBase, log) {
-  try {
-    const res = await fetch(`${apiBase}/api/creator/engine`);
-    if (!res.ok) throw new Error(`HTTP ${res.status}`);
-    const { latest } = await res.json();
-    if (!latest) throw new Error('no downloadable releases');
-    return latest;
-  } catch (err) {
-    log(`⚠️  Could not resolve the engine version (${err.message}) — the first \`looop dev\` will pin it instead.`);
-    return null;
+// Copy the starter game out of the artifact. One rename: `gitignore` →
+// `.gitignore` (npm pack silently strips .gitignore files from a package, so
+// the artifact stores it dot-less).
+function copyScaffold(engineDir, dir, name, version) {
+  const root = join(engineDir, SCAFFOLD_DIR);
+  if (!existsSync(root)) {
+    // RELEASE ORDER: the engine must ship the scaffold BEFORE a CLI that expects
+    // it. If this CLI ever reaches a creator ahead of that engine, `create`
+    // resolves the latest engine, finds no starter game, and every create on
+    // earth fails — so say exactly what is wrong, and never blame the creator's
+    // setup for our release ordering.
+    throw new Error(
+      `Looop engine ${version} ships no starter game — it predates engine-owned scaffolding. ` +
+        'This is a platform-side issue, not something you did: please report it (`npx looop feedback`) or retry shortly.',
+    );
   }
-}
-
-function copyTemplate(dir, name) {
-  const entries = readdirSync(TEMPLATE_DIR, { withFileTypes: true, recursive: true }).filter((e) => e.isFile());
-  for (const entry of entries) {
-    const rel = relative(TEMPLATE_DIR, join(entry.parentPath, entry.name));
+  for (const entry of readdirSync(root, { withFileTypes: true, recursive: true })) {
+    if (!entry.isFile()) continue;
+    const rel = relative(root, join(entry.parentPath, entry.name));
     const dest = join(dir, rel === 'gitignore' ? '.gitignore' : rel);
     mkdirSync(dirname(dest), { recursive: true });
-    writeFileSync(dest, readFileSync(join(TEMPLATE_DIR, rel), 'utf8').replaceAll('{{name}}', name));
+    writeFileSync(dest, readFileSync(join(root, rel), 'utf8').replaceAll('{{name}}', name));
   }
 }
 
-export async function create({
-  name,
-  cwd = process.cwd(),
-  install = true,
-  cliSpec = process.env.LOOOP_CREATE_CLI_SPEC || '^0.1.0',
-  apiBase = getApiBase(DEFAULT_API_BASE),
-  log = console.log,
-} = {}) {
-  if (!name || !NAME_OK.test(name)) {
-    throw new Error(
-      `"${name ?? ''}" won't work as a game name — use lowercase letters, digits, and dashes (it becomes the URL: play.looop.games/g/<name>).`,
-    );
-  }
-  const dir = join(cwd, name);
-  if (existsSync(dir)) throw new Error(`${dir} already exists — pick another name or remove it first.`);
-
-  mkdirSync(dir, { recursive: true });
-  copyTemplate(dir, name);
-  // Non-Claude agent CLIs (Codex, Gemini/Antigravity, Cursor, opencode)
-  // discover project skills at .agents/skills/ — alias it to the same files.
-  // Created here, not shipped in the template: npm pack can't carry symlinks.
-  try {
-    mkdirSync(join(dir, '.agents'), { recursive: true });
-    symlinkSync(join('..', '.claude', 'skills'), join(dir, '.agents', 'skills'), 'dir');
-  } catch {
-    // e.g. Windows without symlink rights — Claude Code (and any tool that
-    // reads .claude/skills/ directly) still works.
-  }
-  // The engine is deliberately NOT a dependency (Q4 revision): it installs
-  // from the platform's login-gated registry on first `looop dev`. The
-  // VERSION is pinned here at create time (public lookup, warn-fallback) so
-  // the initial commit already carries it — see resolveEnginePin above.
-  const enginePin = await resolveEnginePin(apiBase, log);
+async function scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, reconcile }) {
+  // Written FIRST, and without the engine pin: npm needs a package.json to
+  // install into, and `ensureEngine` writes the pin itself once it knows which
+  // version it actually installed. ONE writer for the pin — the old code had
+  // `create` resolve it and `ensureEngine` resolve it again, which is precisely
+  // how they came to disagree.
   writeFileSync(
     join(dir, 'package.json'),
     JSON.stringify(
@@ -121,28 +108,50 @@ export async function create({
         scripts: { dev: 'looop dev', publish: 'looop publish', test: 'looop test' },
         devDependencies: { '@looop-games/cli': cliSpec, playwright: PLAYWRIGHT_SPEC },
         allowScripts: ALLOW_SCRIPTS,
-        ...(enginePin ? { looop: { engine: enginePin } } : {}),
       },
       null,
       2,
     ) + '\n',
   );
 
-  // The template we just copied IS this repo's agent surface, so record it as
-  // ours now (Slice 2 / Q2). Without this, the first `looop dev` would meet a
-  // two-minute-old scaffold with no ownership record, treat it as a legacy
-  // pre-Slice-2 repo, and noisily "adopt" it. From here the artifact drives it.
-  recordSeededSurface(dir, enginePin);
-
   if (install) {
     log(`Installing the CLI (npm install in ${name}/)…`);
     runNpm(['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'pipe' });
+  }
+
+  // The engine — and with it the starter game and the agent skills. Signs the
+  // creator in via the device flow if this machine has no token yet, and writes
+  // the `looop.engine` pin.
+  const engine = await ensure(dir, { apiBase, log });
+
+  copyScaffold(engine.dir, dir, name, engine.version);
+
+  // The agent surface is PLATFORM-owned and reconciled on every `looop update`,
+  // so it is placed here by the very code that will later update it — reading
+  // the artifact, recording the real hash of what landed. That identity is the
+  // whole point: a fresh repo's first `update` is now a genuine no-op, because
+  // the bytes on disk and the bytes in the ownership record came from the same
+  // artifact.
+  reconcile(dir, engine.dir, { log });
+
+  // Non-Claude agent CLIs (Codex, Gemini/Antigravity, Cursor, opencode)
+  // discover project skills at .agents/skills/ — alias it to the same files.
+  // After reconcile, so the link is never dangling.
+  try {
+    mkdirSync(join(dir, '.agents'), { recursive: true });
+    symlinkSync(join('..', '.claude', 'skills'), join(dir, '.agents', 'skills'), 'dir');
+  } catch {
+    // e.g. Windows without symlink rights — Claude Code (and any tool that
+    // reads .claude/skills/ directly) still works.
+  }
+
+  if (install) {
     // Fetch the smoke-test browser NOW (cached machine-wide per version) so
     // the first `looop test` never stalls on a surprise download mid-build.
     // Resolved + run via node directly — NEVER a nested `npx`: when create
-    // itself runs under `npm exec --package=<tarball>` (the stranger
-    // gesture), the inherited npm_config_* env makes an inner npx try to
-    // re-install the tarball and cancel (caught live, 2026-07-10).
+    // itself runs under `npm exec --package=<tarball>` (the stranger gesture),
+    // the inherited npm_config_* env makes an inner npx try to re-install the
+    // tarball and cancel (caught live, 2026-07-10).
     try {
       log('Fetching the test browser (Chromium — one-time download, cached for every game)…');
       const req = createRequire(join(dir, 'package.json'));
@@ -152,12 +161,14 @@ export async function create({
       log('⚠️  Could not fetch Chromium (offline?) — `looop test` will fetch it when first needed.');
     }
   }
+
   try {
     execFileSync('git', ['init', '-q'], { cwd: dir, stdio: 'pipe' });
-    // Commit the scaffold: the initial commit is the first revert baseline
-    // (rejecting milestone 1 resets to it) and what lets `git worktree add`
-    // work — on a never-committed repo it silently creates an empty orphan
-    // lane instead.
+    // The initial commit is the first revert baseline (rejecting milestone 1
+    // resets to it) and what lets `git worktree add` work — on a never-committed
+    // repo it silently creates an empty orphan lane instead. It carries the
+    // engine pin AND the true agent surface, so a reset to baseline cannot
+    // silently change either.
     execFileSync('git', ['add', '-A'], { cwd: dir, stdio: 'pipe' });
     const msg = ['commit', '-q', '-m', 'initial scaffold (looop create)'];
     try {
@@ -175,8 +186,43 @@ export async function create({
   }
 
   log('');
-  log(`✅ ${name} is ready.`);
-  log(`   cd ${dir} && npx looop dev`);
-  log('   (first run downloads the Looop engine — it will ask you to sign in)');
-  return { dir };
+  log(`✅ ${name} is ready (Looop engine ${engine.version}).`);
+  log(`   cd ${name} && npx looop dev`);
+  return { dir, engineVersion: engine.version };
+}
+
+export async function create({
+  name,
+  cwd = process.cwd(),
+  install = true,
+  cliSpec = process.env.LOOOP_CREATE_CLI_SPEC || '^0.1.0',
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  // Seams, mirroring `looop update` — the tests drive a real artifact on disk
+  // through the real reconciler, with no network and no account.
+  ensure = ensureEngine,
+  reconcile = reconcileAgentSurface,
+} = {}) {
+  if (!name || !NAME_OK.test(name)) {
+    throw new Error(
+      `"${name ?? ''}" won't work as a game name — use lowercase letters, digits, and dashes (it becomes the URL: play.looop.games/g/<name>).`,
+    );
+  }
+  const dir = join(cwd, name);
+  if (existsSync(dir)) throw new Error(`${dir} already exists — pick another name or remove it first.`);
+
+  mkdirSync(dir, { recursive: true });
+  try {
+    return await scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, reconcile });
+  } catch (err) {
+    // ATOMIC. Everything a creator receives now arrives over the network behind
+    // a login, so a failure anywhere leaves a folder with no game, no skills and
+    // no initial commit — one that `looop dev` cannot run, and that `create`
+    // would refuse to retry into ("already exists"). A folder that looks like a
+    // game and isn't one is worse than no folder at all: it fails later,
+    // somewhere more confusing. Take it back, and say so.
+    rmSync(dir, { recursive: true, force: true });
+    log(`\n⚠️  Could not finish creating ${name} — removed the incomplete folder so you can retry cleanly.`);
+    throw err;
+  }
 }