@looop-games/cli 0.1.4 → 0.1.6

package/bin/looop.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// looop — the Looop game-development CLI (project note cuqfzo).
+// looop — the Looop game-development CLI.
 //
 // Runs inside a standalone game folder (its own repo). The agent is the
 // primary user: keep output plain, actionable, and machine-legible.

package/lib/agent-surface.mjs

@@ -0,0 +1,251 @@
+// 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.
+//
+// **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),
+// 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,
+// and it narrates nothing either: it returns what it did, and `looop update`
+// tells the creator, who decides whether to commit it.
+//
+// The one contract everything here serves:
+//
+//     an update reaches a pre-existing repo without touching anything
+//     user-owned.
+//
+// So ownership is tracked explicitly, in `.looop/agent-surface.json` — the
+// hash of every file WE wrote. On each run a file is one of:
+//
+//   ours, unmodified  (hash matches what we recorded)  → replace with the new
+//   ours, edited      (hash differs)                   → KEEP theirs, warn
+//   never ours        (no record, but on disk)         → KEEP theirs, warn
+//   not on disk                                        → place ours
+//   retired upstream                                   → remove, if still ours
+//
+// A skill we never placed is never even enumerated, so a creator's own skills
+// are invisible to this code by construction. `AGENTS.md` is the exception that
+// proves the rule: the managed block between the markers is ours to rewrite;
+// 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 { dirname, join } from 'node:path';
+
+export const SURFACE_DIR = 'agent-surface';
+export const LOCAL_MANIFEST = '.looop/agent-surface.json';
+
+const START = '<!-- looop:managed:start -->';
+const END = '<!-- looop:managed:end -->';
+
+const sha = (buf) => createHash('sha256').update(buf).digest('hex');
+
+// Where each artifact path lands in the game repo. `skills/**` is the whole
+// surface today; AGENTS.md is spliced rather than written whole.
+function target(rel) {
+  if (rel === 'AGENTS.md') return 'AGENTS.md';
+  if (rel.startsWith('skills/')) return join('.claude', rel);
+  return null; // unknown surface entry from a newer engine — ignore, don't guess
+}
+
+function projectName(projectDir) {
+  try {
+    return JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8')).name || '';
+  } catch {
+    return '';
+  }
+}
+
+function readLocal(projectDir) {
+  try {
+    const m = JSON.parse(readFileSync(join(projectDir, LOCAL_MANIFEST), 'utf8'));
+    return { engineVersion: m.engineVersion ?? null, placed: m.placed ?? {} };
+  } catch {
+    return null; // no manifest = a pre-Slice-2 repo; see `adopt` below
+  }
+}
+
+function writeLocal(projectDir, engineVersion, placed) {
+  const p = join(projectDir, LOCAL_MANIFEST);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify({ engineVersion, placed }, null, 2) + '\n');
+}
+
+// Splice the artifact's managed block into the repo's AGENTS.md, preserving
+// everything outside the markers. Returns null when the creator's file has no
+// markers — they rewrote Layer 0 themselves, so it is theirs now.
+function spliceManaged(current, incoming) {
+  const cs = current.indexOf(START);
+  const ce = current.indexOf(END);
+  if (cs === -1 || ce === -1 || ce < cs) return null;
+
+  const is = incoming.indexOf(START);
+  const ie = incoming.indexOf(END);
+  if (is === -1 || ie === -1) return null;
+
+  const block = incoming.slice(is, ie + END.length);
+  return current.slice(0, cs) + block + current.slice(ce + END.length);
+}
+
+/**
+ * Reconcile the game repo's agent surface against the installed engine artifact.
+ * Never throws: a malformed or absent surface must not block `looop dev`.
+ */
+export function reconcileAgentSurface(projectDir, engineDir, { log = console.log } = {}) {
+  const result = {
+    placed: [], removed: [], shadowed: [], backups: [],
+    adopted: false, skipped: false, engineVersion: null, backupDir: null,
+  };
+  const surface = join(engineDir, SURFACE_DIR);
+
+  let manifest;
+  try {
+    if (!existsSync(join(surface, 'manifest.json'))) {
+      result.skipped = true; // engine older than Slice 2 — it carries no surface
+      return result;
+    }
+    manifest = JSON.parse(readFileSync(join(surface, 'manifest.json'), 'utf8'));
+  } catch (err) {
+    log(`⚠️  Could not read the engine's agent surface (${err.message}) — skills left as they are.`);
+    result.skipped = true;
+    return result;
+  }
+
+  try {
+    const name = projectName(projectDir);
+    const render = (buf) => Buffer.from(buf.toString('utf8').replaceAll('{{name}}', name), 'utf8');
+
+    const prior = readLocal(projectDir);
+    // Adoption: a repo scaffolded before this mechanism existed has our files on
+    // disk but no record of them. We take ownership so it can ever be updated —
+    // and back up anything whose bytes diverge, so an edit we can't distinguish
+    // from ours is preserved rather than destroyed.
+    const adopt = prior === null;
+    result.adopted = adopt;
+    const placed = adopt ? {} : { ...prior.placed };
+
+    const backupRoot = join(projectDir, '.looop', `backup-${manifest.engineVersion}`);
+    const backups = [];
+    const backup = (rel) => {
+      const from = join(projectDir, rel);
+      if (!existsSync(from)) return;
+      const to = join(backupRoot, rel);
+      mkdirSync(dirname(to), { recursive: true });
+      cpSync(from, to, { recursive: true });
+      backups.push(rel);
+    };
+
+    // ── retired entries: remove what upstream dropped. This is the half that
+    //    makes a RENAME possible on a repo that already exists — without it a
+    //    replaced skill would linger next to its replacement forever. ─────────
+    for (const rel of manifest.retired ?? []) {
+      const dest = target(rel);
+      if (!dest) continue;
+      const abs = join(projectDir, dest);
+      if (!existsSync(abs)) continue;
+
+      const owned = Object.keys(placed).some((p) => p === dest || p.startsWith(`${dest}/`));
+      if (!owned && !adopt) {
+        result.shadowed.push(dest);
+        continue;
+      }
+      if (adopt) backup(dest);
+      rmSync(abs, { recursive: true, force: true });
+      for (const p of Object.keys(placed)) {
+        if (p === dest || p.startsWith(`${dest}/`)) delete placed[p];
+      }
+      result.removed.push(dest);
+    }
+
+    // ── the live surface ────────────────────────────────────────────────────
+    for (const rel of Object.keys(manifest.files ?? {})) {
+      const dest = target(rel);
+      if (!dest) continue;
+      const src = join(surface, rel);
+      if (!existsSync(src)) continue;
+
+      const abs = join(projectDir, dest);
+      const desired = render(readFileSync(src));
+      const exists = existsSync(abs);
+      const current = exists ? readFileSync(abs) : null;
+      const recorded = placed[dest];
+
+      if (dest === 'AGENTS.md') {
+        // The markers ARE the contract: inside is ours, outside is theirs.
+        const next = exists
+          ? spliceManaged(current.toString('utf8'), desired.toString('utf8'))
+          : desired.toString('utf8');
+        if (next === null) {
+          result.shadowed.push(dest);
+          continue;
+        }
+        if (exists && current.toString('utf8') === next) continue;
+        writeFileSync(abs, next);
+        placed[dest] = sha(Buffer.from(next, 'utf8'));
+        result.placed.push(dest);
+        continue;
+      }
+
+      if (exists) {
+        const now = sha(current);
+        if (now === recorded) {
+          if (now === sha(desired)) continue; // already current
+        } else if (recorded === undefined && adopt) {
+          if (now !== sha(desired)) backup(dest);
+        } else {
+          // Either they edited ours, or it was never ours. Both are theirs.
+          result.shadowed.push(dest);
+          placed[dest] = recorded ?? now;
+          continue;
+        }
+      }
+
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, desired);
+      placed[dest] = sha(desired);
+      result.placed.push(dest);
+    }
+
+    writeLocal(projectDir, manifest.engineVersion, placed);
+    result.engineVersion = manifest.engineVersion;
+    result.backups = backups;
+    result.backupDir = backups.length
+      ? `${LOCAL_MANIFEST.replace('agent-surface.json', '')}backup-${manifest.engineVersion}/`
+      : null;
+  } catch (err) {
+    // A surface bug must never be the reason a creator can't run their game.
+    log(`⚠️  Could not sync the agent skills (${err.message}) — continuing; your game is unaffected.`);
+  }
+
+  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/bundle-primitives.mjs

@@ -1,5 +1,5 @@
-// cuqfzo Phase 2 / Option B — Slice 2: bundle a server-backed game's primitives
-// on the CREATOR's machine, with the engine marked external.
+// Bundle a server-backed game's primitives on the CREATOR's machine, with the
+// engine marked external.
 //
 // The publish endpoint is a Pages Function — a Worker with no filesystem and no
 // npm — so it cannot run a bundler. But real server primitives import npm

package/lib/create.mjs

@@ -1,4 +1,4 @@
-// `looop create <name>` — bootstrap a standalone Looop game (cuqfzo Slice 4).
+// `looop create <name>` — bootstrap a standalone Looop game.
 //
 // The create-next-app gesture: one command → a complete folder that is its
 // own repo, where `looop dev` immediately serves a WORKING multiplayer game
@@ -19,6 +19,7 @@ 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';
 
 export const TEMPLATE_DIR = join(import.meta.dirname, '..', 'template');
 
@@ -127,6 +128,12 @@ export async function create({
     ) + '\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' });

package/lib/dev.mjs

@@ -1,5 +1,4 @@
-// `looop dev` — the standalone three-service dev stack (decision Q3 in
-// cuqfzo), same shape the monorepo's dev.sh proved:
+// `looop dev` — the standalone three-service dev stack:
 //
 //   static :8000  game folder at /games/<slug>/, /shared/ → engine bundle,
 //                 head injection + auto-reload
@@ -37,12 +36,11 @@ export function partykitBin() {
   }
 }
 
-// Per-game server parity (cuqfzo Phase 4): a game shipping its own
+// Per-game server parity: a game shipping its own
 // `partykit.json` runs its OWN server in dev — partykit gets the game folder
 // as cwd, resolving the game's `main` entry (which imports the room server
 // from the installed engine). Without one, the bundle's shared room server
-// runs, exactly as before. Mirrors the monorepo dev.sh detection so a
-// vendor-flipped game behaves identically standalone. A config whose `main`
+// runs, exactly as before. A config whose `main`
 // doesn't exist is ignored LOUDLY — a dead file must not take dev's
 // multiplayer down with it.
 export function partykitCwdFor(project, engine, warn = console.warn) {

package/lib/feedback.mjs

@@ -1,5 +1,5 @@
 // `looop feedback` — send the reports under notes/feedback/ to the Looop team
-// (cuqfzo; the transport behind the template's /feedback skill).
+// (the transport behind the template's /feedback skill).
 //
 // Target: /api/creator/feedback — the token-authenticated intake beside
 // creator/publish. Each unsent notes/feedback/*.md ships VERBATIM as the

package/lib/inject.mjs

@@ -1,5 +1,4 @@
-// HTML/JS dev-serving transforms — a Node port of the proven logic in
-// looop-core tools/game/dev_server.py, kept behaviour-identical:
+// HTML/JS dev-serving transforms:
 //
 //   * Head injection mirrors the production /g/<slug> serve path
 //     (builder/functions/g/[[path]].ts): window.GAME_SLUG + window.LOOOP_IDENTITY

package/lib/llm-shim.mjs

@@ -1,4 +1,4 @@
-// Local platform-services shim (:8788) — decision Q3b in cuqfzo.
+// Local platform-services shim (:8788).
 //
 // Thin auth/CORS plumbing between a game running on localhost and the
 // platform's services API (LLM today; whatever comes next). It forwards

package/lib/login.mjs

@@ -1,5 +1,4 @@
-// `looop login` — device-flow authentication (cuqfzo Slice 1, decisions
-// Q2/Q6, the `gh auth login` shape):
+// `looop login` — device-flow authentication (the `gh auth login` shape):
 //
 //   1. ask the platform for a pairing (device_code for us, user_code for the
 //      human),

package/lib/ports.mjs

@@ -1,4 +1,4 @@
-// Port conventions + takeover, mirroring looop-core tools/game/dev.sh.
+// Port conventions + takeover.
 //
 // Canonical ports: static :8000, partykit :1999, services shim :8788. The
 // engine's browser clients derive the other two from location.port

package/lib/publish.mjs

@@ -1,9 +1,9 @@
-// `looop publish` — ship the game to play.looop.games (cuqfzo Slice 2, Q1).
+// `looop publish` — ship the game to play.looop.games.
 //
 // Server-resolved: we send ONLY the game's own files plus the engine version
 // the installed bundle declares; the platform resolves /shared/... from its
-// release registry. Compare catalog_publish.py, which staged the whole shared
-// library client-side — that trust hole is what this replaces.
+// release registry. The client never stages the shared library itself — that
+// trust hole is what this design replaces.
 //
 // Target: /api/creator/publish — the token-authenticated creator lane, the
 // one publish route reachable on the public play host (the legacy
@@ -21,9 +21,8 @@ import { bundlePrimitives, PRIMITIVES_ENTRY } from './bundle-primitives.mjs';
 export const PLAY_BASE = 'https://play.looop.games';
 
 // Never shipped: tooling, VCS, agent workspace, notes + handbook + agent
-// instructions (repo knowledge travels with the repo, not the catalog — same
-// rule as the monorepo publisher; a published game must not expose it on a
-// public URL), tests/smokes.
+// instructions (repo knowledge travels with the repo, not the catalog — a
+// published game must not expose it on a public URL), tests/smokes.
 const SKIP_DIRS = new Set(['node_modules', 'notes', 'handbook', '.git', '.looop', '.claude', '__pycache__']);
 const SKIP_FILES = [
   /^package(-lock)?\.json$/,
@@ -69,7 +68,7 @@ export async function publish({
     throw new Error('this game has no index.html at its root — publish needs an entry page.');
   }
 
-  // Server-backed game (cuqfzo Phase 2 / Option B, Slice 2): its primitives can
+  // Server-backed game: its primitives can
   // import npm packages + WASM the platform's bundler-less endpoint can't
   // resolve, so we bundle them HERE (engine marked external) and send the
   // single self-contained module in place of the raw barrel. The endpoint

package/lib/static-server.mjs

@@ -1,6 +1,5 @@
-// The standalone dev static server — Node port of looop-core
-// tools/game/dev_server.py, serving a single game + the installed engine
-// bundle behind the same URL shape production uses:
+// The standalone dev static server — serves a single game + the installed
+// engine bundle behind the same URL shape production uses:
 //
 //   /games/<slug>/…   → the game folder
 //   /shared/…         → the engine bundle's shared/ tree

package/lib/test-cmd.mjs

@@ -1,5 +1,4 @@
-// `looop test` — run the game's own verification gate (cuqfzo creator-harness
-// Slice 1; the successor to the monorepo's `gamedev <name> test`).
+// `looop test` — run the game's own verification gate.
 //
 // Discovers the game's test files — `*.test.mjs` (unit, run under
 // `node --test`) and `*.smoke.mjs` (integration, run against a REAL dev
@@ -115,8 +114,8 @@ export async function testCmd({ cwd = process.cwd(), log = console.log, devFn =
           env: {
             ...env,
             LOOOP_TEST_GAME_URL: handle.url,
-            // The monorepo's smoke convention — exported too, so a game (and
-            // its smokes) moving out of looop-games ports without edits.
+            // A legacy alias for the same URL, exported so smokes written
+            // against the older convention keep running unedited.
             GAMEDEV_TEST_GAME_URL: handle.url,
             URL: handle.url,
           },

package/lib/update.mjs

@@ -1,15 +1,53 @@
-// `looop update` — move this game to the latest engine release (the CLI verb
-// the demoted /update skill became, cuqfzo Q6). Asks the platform registry
-// for the latest downloadable release, rewrites the `looop.engine` pin, and
-// lets ensureEngine do what it already does on every dev/publish: download
-// (cached), install, re-pin. Slice 2 extends this with the skills/agent-
-// surface reconciliation once those ride the engine artifact.
-import { findProject } from './project.mjs';
+// `looop update` — move this game to the latest Looop: the engine bundle AND
+// the agent surface (skills + the Layer-0 managed block) that rides it.
+//
+// This is the ONLY command that writes to `.claude/skills/` or `AGENTS.md`
+// (creator-harness Slice 2 / Q2, scoped to update-only, 2026-07-11).
+// `dev` and `publish` never touch them: an update is something a creator asks
+// for, not something that happens to them while they were doing something else.
+//
+// Because it writes into files the creator has in git, it OWES them a full
+// account of what it changed — every path, and whose it was. The `/update-looop`
+// skill wraps this to walk them through the diff and offer the commit.
+import { findProject, resolveEngine } from './project.mjs';
 import { ensureEngine, readEnginePin, writeEnginePin } from './engine.mjs';
+import { reconcileAgentSurface } from './agent-surface.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { login } from './login.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
 
+// The report is the point. A creator reading this must be able to answer, with
+// no further digging: what changed, was any of it mine, and what do I do now.
+function report(log, engineVersion, surface) {
+  const { placed = [], removed = [], shadowed = [], backups = [], backupDir } = surface;
+  if (!placed.length && !removed.length && !shadowed.length) {
+    log('   Your skills and instructions were already current.');
+    return;
+  }
+
+  log('');
+  log(`Looop also updated this game's skills and instructions to match engine ${engineVersion}:`);
+  for (const f of placed) log(`   updated     ${f}`);
+  for (const f of removed) log(`   removed     ${f}   (retired by Looop)`);
+  for (const f of shadowed) log(`   KEPT YOURS  ${f}   (you changed it — we left it alone)`);
+
+  if (backups.length) {
+    // On adoption we cannot tell an untouched old platform file from one the
+    // creator edited — there is no ownership record to compare against, which
+    // is precisely why we're adopting. Most of these are just the previous
+    // version's files. Claiming "you edited these" would be a lie that alarms;
+    // saying nothing would risk a silent overwrite. State only what is true.
+    log('');
+    log(`   This game predates Looop's skill updates, so those files had no`);
+    log(`   ownership record. Their previous contents are saved in ${backupDir}`);
+    log(`   — if you had edited any of them, your version is in there.`);
+  }
+
+  log('');
+  log("   These are Looop's files inside your repo, so they show up in git as");
+  log("   changes you didn't make. Review them and save them with your next commit.");
+}
+
 export async function update({
   cwd = process.cwd(),
   apiBase = getApiBase(DEFAULT_API_BASE),
@@ -17,6 +55,7 @@ export async function update({
   fetchImpl = fetch,
   loginFn = login,
   ensure = ensureEngine,
+  reconcile = reconcileAgentSurface,
 } = {}) {
   const project = findProject(cwd);
   const from = readEnginePin(project.dir);
@@ -36,16 +75,36 @@ export async function update({
   const { latest } = await res.json();
   if (!latest) throw new Error('the platform has no downloadable engine releases yet.');
 
+  let engineDir = null;
+  let updated = false;
+
   if (from === latest) {
     log(`✅ Engine ${latest} — already up to date.`);
-    return { from, to: latest, updated: false };
+    // Reconcile anyway. A repo can sit on the latest engine and STILL have an
+    // out-of-date surface: one scaffolded before this mechanism existed has
+    // never had its skills adopted, and would otherwise wait forever for a
+    // release it already has.
+    try {
+      engineDir = resolveEngine(project.dir).dir;
+    } catch {
+      engineDir = null; // engine not installed yet — the next `dev` fetches it
+    }
+  } else {
+    // Rewrite the pin first; ensureEngine honors it (download → install → pin).
+    writeEnginePin(project.dir, latest);
+    const engine = await ensure(project.dir, { apiBase, log, fetchImpl });
+    engineDir = engine.dir ?? null;
+    updated = true;
+    log('');
+    log(`✅ Engine updated: ${from ?? '(none)'} → ${engine.version}`);
   }
 
-  // Rewrite the pin first; ensureEngine honors it (download → install → pin).
-  writeEnginePin(project.dir, latest);
-  const engine = await ensure(project.dir, { apiBase, log, fetchImpl });
-  log('');
-  log(`✅ Engine updated: ${from ?? '(none)'} → ${engine.version}`);
-  log('   Republish (`npx looop publish`) when you want the live game on it.');
-  return { from, to: engine.version, updated: true };
+  const surface = engineDir ? reconcile(project.dir, engineDir, { log }) : { skipped: true };
+  if (!surface.skipped) report(log, surface.engineVersion ?? latest, surface);
+
+  if (updated) {
+    log('');
+    log('   Republish (`npx looop publish`) when you want the live game on it.');
+  }
+  return { from, to: latest, updated, surface };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",
@@ -10,7 +10,8 @@
   "files": [
     "bin",
     "lib",
-    "template"
+    "template",
+    "!lib/**/*.test.mjs"
   ],
   "engines": {
     "node": ">=20.11"

package/template/.claude/skills/engine/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: engine
-description: Discover what the Looop engine already provides before building something from scratch — components (rooms, physics, audio, joysticks, leaderboards, LLM NPCs…), craft docs, and how to customize engine behaviour. Use when the creator asks "can it do X?", when you're about to write a system a game engine would normally provide, or when tuning game feel.
+description: Discover what the Looop engine already provides before building something from scratch — its component library, craft docs, and how to customize engine behaviour. Read the index rather than assuming what exists. Use when the creator asks "can it do X?", when you're about to write a system a game engine would normally provide, or when tuning game feel.
 ---
 
 # /engine — what Looop already gives you

package/template/.claude/skills/update-looop/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: update-looop
+description: Update Looop itself — the engine, and the skills and instructions this repo runs on. Use when the creator asks for the latest Looop ("is there an update?", "update looop", "get the newest version"), when a Looop feature they've heard about is missing, or when something looks like a Looop bug that may already be fixed. Not for updating their GAME — that's just building.
+---
+
+# /update-looop — get the latest Looop, and explain what changed
+
+`npx looop update` moves this game to the newest Looop release. It is the **only**
+command that writes to Looop's files inside this repo — `dev` and `publish` never
+do. That is deliberate: an update is something the creator *asks* for.
+
+But it does write into **their** repo. After it runs, `git status` shows changes
+they did not make. **Your job is to make sure that is never a surprise.**
+
+## Before
+
+Tell them what an update touches, in one or two sentences:
+
+- **The engine** — the game code they import from (`/shared/...`). Their game
+  keeps running on the old engine until they publish again, so an update is safe
+  to take at any time.
+- **The skills and instructions** — the files in `.claude/skills/` and the Looop
+  section of `AGENTS.md`. These are Looop's, living in their repo.
+- **Never their game.** Not `index.html`, not `game.js`, not `handbook/`, not
+  `notes/`. And never a skill they wrote, or an edit they made to one of ours —
+  where they've changed something, their version wins and the update says so.
+
+If they have uncommitted work, say so first — the update's changes will land
+alongside it, and a mixed diff is harder to read. Offer to save theirs first.
+
+## Run it
+
+```bash
+npx looop update
+```
+
+It prints exactly what it did: every file updated, every file removed, and every
+file it **kept because the creator had changed it**. Read that output — it is the
+source of truth for the next step, not your assumptions about what a release
+contains.
+
+## After — the part that matters
+
+**Report the change in their terms, not ours.** Don't paste the file list back at
+them; tell them what is now different about what you and they can do:
+
+> *"Looop updated to engine 0.1.8. The `/update-handbook` skill was replaced by a
+> broader `/handbook` — same job, plus it now keeps your game's vision and design
+> pillars. Your own `/my-thing` skill was left alone."*
+
+Then **offer the commit** — never run it unasked:
+
+> *"That changed 3 of Looop's files in your repo. Want me to save them?
+> (`git add -A && git commit -m "update Looop to engine 0.1.8"`)"*
+
+Two things to volunteer without being asked:
+
+- **If they'd edited a Looop file**, the update kept *their* version and did not
+  apply ours. Say which file, and that they may want to re-apply their change on
+  top of the new one — otherwise they'll silently miss the update to that file
+  forever.
+- **If the update mentions a backup folder** (`.looop/backup-<version>/`), that
+  is the pre-update copy of files whose history we couldn't be sure of. Tell them
+  it exists. They can delete it once they're happy.
+
+## Rules
+
+- **Never run `looop update` as a side effect of something else.** It is its own
+  act, with its own consent. If a bug looks like it might already be fixed
+  upstream, *propose* the update — don't just do it mid-build.
+- **Never commit on their behalf** without asking, even when the only changes are
+  Looop's own files. It is their repo and their history.
+- The live game at `play.looop.games` does **not** change until they run
+  `npx looop publish`. Say so — creators reasonably assume an update is live.

package/template/AGENTS.md

@@ -19,7 +19,7 @@ applies. This table routes only what has no skill:
 | The creator wants… | Do this |
 |---|---|
 | To "save my work" | `git add -A && git commit` (and push, if the repo has a remote). Saving is local; it is **not** publishing. |
-| To update Looop / the engine | `npx looop update` — moves the game to the latest engine release and re-pins `looop.engine` in `package.json`. The live game changes only on the next publish. |
+| To update Looop / the engine | `/update-looop`. It is the ONLY thing that writes Looop's files into this repo (`.claude/skills/`, the managed block of this file) — `dev` and `publish` never do, so an update is never a surprise in their git. The live game changes only on the next publish. |
 | Better game feel (tuning speeds, jumps, timings) | The engine's **tweaks** library (`node_modules/@looop-games/engine/shared/ui/tweaks/`) + `shared/practices/feel.md`. |
 | To change how an engine file behaves | Copy it to `overrides/shared/<same path>` and edit the copy — dev and publish serve your override instead of the official module. Imports stay `/shared/...`; never rewrite them. An override is a fork: that file stops receiving engine updates until you re-port it. |