@looop-games/cli 0.1.6 → 0.1.8

package/lib/agent-surface.mjs

@@ -78,6 +78,23 @@ function writeLocal(projectDir, engineVersion, placed) {
   writeFileSync(p, JSON.stringify({ engineVersion, placed }, null, 2) + '\n');
 }
 
+// Removing the last SKILL.md from a skill folder must remove the folder too —
+// an empty `.claude/skills/handbook/` still reads to an agent as a skill that
+// exists and is broken. Walks up, stopping at .claude/skills (never the repo).
+function pruneEmptyDirs(projectDir, dest) {
+  let dir = dirname(join(projectDir, dest));
+  const stop = join(projectDir, '.claude', 'skills');
+  while (dir.startsWith(stop) && dir !== stop) {
+    try {
+      if (readdirSync(dir).length) return;
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      return;
+    }
+    dir = dirname(dir);
+  }
+}
+
 // 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.
@@ -213,6 +230,32 @@ export function reconcileAgentSurface(projectDir, engineDir, { log = console.log
       result.placed.push(dest);
     }
 
+    // ── orphans: anything WE placed that the artifact no longer ships ────────
+    // Deleting a skill upstream is enough to delete it here — no declaration,
+    // nothing to remember. The manifest already knows what we put on disk, so a
+    // file of ours that vanished from the artifact has been retired, full stop.
+    // (`retired` above still earns its keep: on ADOPTION there is no manifest,
+    // so an orphan is indistinguishable from a skill the creator wrote.)
+    const shipped = new Set(
+      Object.keys(manifest.files ?? {})
+        .map(target)
+        .filter(Boolean),
+    );
+    for (const dest of Object.keys(placed)) {
+      if (shipped.has(dest)) continue;
+      const abs = join(projectDir, dest);
+      if (existsSync(abs)) {
+        if (sha(readFileSync(abs)) !== placed[dest]) {
+          result.shadowed.push(dest); // they changed it — it's theirs now
+          continue;
+        }
+        rmSync(abs, { force: true });
+        pruneEmptyDirs(projectDir, dest);
+        result.removed.push(dest);
+      }
+      delete placed[dest];
+    }
+
     writeLocal(projectDir, manifest.engineVersion, placed);
     result.engineVersion = manifest.engineVersion;
     result.backups = backups;

package/lib/feedback.mjs

@@ -8,18 +8,117 @@
 // looop.engine pin, and this CLI's version. A delivered file is stamped
 // `sent:` + `id:` in its frontmatter so it never ships twice; a failed send
 // leaves the file unstamped and is retried on the next run.
-import { readdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { readdirSync, readFileSync, writeFileSync, existsSync, statSync, realpathSync } from 'node:fs';
+import { basename, join, resolve, relative, isAbsolute, sep } from 'node:path';
 import { findProject } from './project.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
 
 const CLI_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
+// Attachment caps. The riven report cited game.js:56 and riven-render.js:302 —
+// source files, not screenshots — so attachments are TEXT. Kept well under the
+// intake's own ceiling so an oversized set is caught HERE, with a readable
+// message: Cloudflare replaces a Pages Function's 5xx body with its own HTML
+// page, which would reach the creator as an unreadable wall.
+export const MAX_ATTACHMENTS = 20;
+export const MAX_ATTACHMENT_BYTES = 256 * 1024; // per file
+export const MAX_ATTACHMENTS_BYTES = 1024 * 1024; // all of them together
+
+const frontmatter = (text) => /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+
 // A report is "sent" when its frontmatter carries a `sent:` stamp.
 function isSent(text) {
-  const fm = /^---\n([\s\S]*?)\n---/.exec(text);
-  return fm ? /^sent:\s*\S/m.test(fm[1]) : false;
+  return /^sent:\s*\S/m.test(frontmatter(text));
+}
+
+// `attachments:` in the report's frontmatter, in either YAML shape agents write:
+//
+//   attachments:          attachments: [game.js, src/render.js]
+//     - game.js
+//     - src/render.js
+export function parseAttachments(text) {
+  const fm = frontmatter(text);
+  const inline = /^attachments:\s*\[(.*)\]\s*$/m.exec(fm);
+  if (inline) {
+    return inline[1]
+      .split(',')
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+      .filter(Boolean);
+  }
+  const block = /^attachments:\s*$/m.exec(fm);
+  if (!block) return [];
+  const out = [];
+  for (const line of fm.slice(block.index).split('\n').slice(1)) {
+    const item = /^\s*-\s*(.+?)\s*$/.exec(line);
+    if (!item) break; // the list ends at the first non-item line
+    out.push(item[1].replace(/^['"]|['"]$/g, ''));
+  }
+  return out;
+}
+
+// The agent chooses this list, so it is arbitrary filesystem read access over a
+// network. Every path must land inside the game folder — resolved, not merely
+// inspected, because a symlink's string looks innocent. An escape is a hard
+// error, never a skipped file.
+function readAttachments(projectDir, paths, reportName) {
+  if (paths.length > MAX_ATTACHMENTS) {
+    throw new Error(
+      `${reportName} lists ${paths.length} attachments (max ${MAX_ATTACHMENTS}) — attach only the files the diagnosis rests on.`,
+    );
+  }
+
+  const root = realpathSync(projectDir);
+  const inside = (candidate) => candidate === root || candidate.startsWith(root + sep);
+  const escaped = (p, resolved) => {
+    throw new Error(
+      `${reportName} attaches "${p}", which resolves outside the game folder (${resolved}). ` +
+        `Feedback may only attach files from this game.`,
+    );
+  };
+
+  const files = [];
+  let total = 0;
+
+  for (const p of paths) {
+    // Containment is checked BEFORE existence, and on the lexical path first:
+    // "../../.ssh/id_rsa" is refused for what it asks for, not for whether it
+    // happens to be there. Then again after realpath — a symlink's string looks
+    // perfectly innocent.
+    const full = resolve(root, p);
+    if (isAbsolute(p) || !inside(full)) escaped(p, full);
+
+    let real;
+    try {
+      real = realpathSync(full);
+    } catch {
+      throw new Error(`${reportName} attaches "${p}", which does not exist in the game folder.`);
+    }
+    if (!inside(real)) escaped(p, real);
+    if (!statSync(real).isFile()) throw new Error(`${reportName} attaches "${p}", which is not a file.`);
+
+    const bytes = statSync(real).size;
+    if (bytes > MAX_ATTACHMENT_BYTES) {
+      throw new Error(
+        `${reportName} attaches "${p}" (${Math.round(bytes / 1024)} KiB) — too large, the per-file cap is ${MAX_ATTACHMENT_BYTES / 1024} KiB.`,
+      );
+    }
+    total += bytes;
+    if (total > MAX_ATTACHMENTS_BYTES) {
+      throw new Error(
+        `${reportName}'s attachments are too large together (over ${MAX_ATTACHMENTS_BYTES / 1024} KiB) — attach fewer files.`,
+      );
+    }
+
+    const content = readFileSync(real, 'utf8');
+    if (content.includes('\0')) {
+      throw new Error(`${reportName} attaches "${p}", which is not a text file. Attach source, logs, or config.`);
+    }
+    // Report the path the creator wrote (project-relative), not the real one —
+    // it is what the report's prose cites.
+    files.push({ path: relative(root, real).split(sep).join('/'), content });
+  }
+  return files;
 }
 
 function titleOf(text, path) {
@@ -61,12 +160,16 @@ export async function sendFeedback({
   const sent = [];
   for (const path of unsent) {
     const body = readFileSync(path, 'utf8');
+    // Read + guard the attachments BEFORE the request: a bad path must fail the
+    // send outright, leaving the report unstamped and retryable.
+    const files = readAttachments(project.dir, parseAttachments(body), basename(path));
     const report = {
       title: titleOf(body, path),
       body,
       slug: project.slug,
       engine: project.pkg?.looop?.engine,
       cli: CLI_VERSION,
+      ...(files.length ? { files } : {}),
     };
     const res = await fetch(`${apiBase}/api/creator/feedback`, {
       method: 'POST',
@@ -79,8 +182,9 @@ export async function sendFeedback({
     }
     const { id } = await res.json();
     writeFileSync(path, stamp(body, id));
-    log(`✅ Sent ${basename(path)} → ${id}`);
-    sent.push({ file: path, id });
+    const withFiles = files.length ? ` (+${files.length} file${files.length === 1 ? '' : 's'})` : '';
+    log(`✅ Sent ${basename(path)}${withFiles} → ${id}`);
+    sent.push({ file: path, id, files: files.map((f) => f.path) });
   }
   log(`${sent.length} report${sent.length === 1 ? '' : 's'} delivered to the Looop team.`);
   return { sent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",

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

@@ -112,6 +112,32 @@ they'd care about (feel, fairness, what can break) goes to them; one with no
 creator-visible consequence does not. Never hide a real fork to keep things
 simple — there is always a non-confusing way to ask it.
 
+**The shape decisions are ALWAYS the creator's** — never a default you carry in
+on their behalf, and never something you mention in passing as already settled:
+
+- **Camera and perspective** — top-down, side-on, isometric, first-person, 3D.
+  There is no house camera; see `/engine`'s render paths.
+- **Art direction and look** — the Looop iso kit is *available*, not mandatory.
+- **The core verb** — what the player actually does, moment to moment.
+- **How conflict works** — combat, avoidance, puzzles, none of the above.
+- **Single-player vs. co-op vs. competitive** feel (the *plumbing* is always
+  multiplayer-first; what the game is *about* is theirs).
+
+**NEVER invent a platform constraint.** Do not tell the creator "the engine
+only does X", "Looop doesn't support Y", or "that would take months" unless you
+have just checked and can point at what says so. A Looop game is a web page;
+the library is a bag of conveniences, not a fence (`/engine` — "The library is
+NOT the limit"). This failure is worse than a silent default: a creator can
+argue with "that's a lot of work", but they cannot argue with "the platform
+can't", so a fabricated limit kills their idea and looks like physics while
+doing it. If a thing is genuinely unbuilt, that is a **cost to price honestly**
+and hand them — never a "no" you issue on Looop's behalf.
+
+Watch for this specifically when scope pressure and a gap in the library point
+the same way: **"default to the smallest build" is never a licence to narrow
+the creator's vision** — that's the scope-narrowing this skill forbids two
+paragraphs down, wearing a technical disguise.
+
 **Default to the smallest build that meets the creator's ask — never inflate
 scope.** Every "we could also…" and every richer-than-asked option is scope
 YOU are injecting; the creator can't push back on over-building they didn't
@@ -192,7 +218,7 @@ Outcomes:
   back to the last save (`git reset --hard` — nothing was saved mid-milestone,
   so that's the last accepted state).
 - **The playtest caught a defect you missed** → that's a hole in the
-  verification, not just a bug. Fix it, then run `/update-handbook` so this
+  verification, not just a bug. Fix it, then run `/handbook` so this
   class of defect gets an automated check and never reaches a playtest again.
 
 ## 5. Offer publish — never publish on your own

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

@@ -11,6 +11,42 @@ system from scratch — movement, audio, UI, chat, NPCs, scoring — check wheth
 the engine already has it. Reinventing a library is the most common way a game
 gets worse.
 
+**But the library is a floor, not a ceiling — read the next section before you
+ever tell the creator something isn't possible.**
+
+## The library is NOT the limit of what the game can be
+
+A Looop game is **a web page**. Anything the browser can do, the game can do.
+The engine saves you work; it does not bound the game. The catalog is what
+Looop has *already built for you* — never mistake it for the list of things a
+Looop game is allowed to be.
+
+So there are only ever two answers to "can Looop do X?":
+
+1. **The library has it** → use it (don't reinvent it).
+2. **The library doesn't** → **then you build it, in the game folder.** That is
+   the normal, expected path — it is how the library got its entries in the
+   first place. Price it honestly and let the creator decide.
+
+**Never say "the engine doesn't support that" as if it settled the question.**
+It is the most damaging sentence you can say to a creator: it retires their
+idea without their consent, and it is almost always false. If you catch
+yourself about to say it — stop, come back here, and check. What you *may* say
+is an honest **cost**: "nothing in the kit does this, so we'd build it; here's
+roughly what that means." Price it from what actually exists, never from a
+worst case you imagined.
+
+## Render paths (the camera is the creator's decision, not yours)
+
+There is no house camera. Pick with the creator, framed by consequences:
+
+| path | what it is |
+| --- | --- |
+| **plain 2D canvas** | `getContext('2d')` — what the scaffold ships with. Top-down, side-on, whatever you draw. Lightest. |
+| **iso 2D** (`shared/ui/iso` + `iso-style-looop`) | Isometric 3/4 canvas drawing with the Looop world kit. The best-supported look. Depth is a painter-algorithm sort, so large occluders can glitch. |
+| **iso-3d** (`shared/ui/iso-3d`) | Real WebGL/three.js geometry with per-pixel depth-buffer occlusion. Same iso look, no depth-sort bugs. |
+| **anything else** | First-person, over-the-shoulder, free 3D camera, 2.5D — all buildable on three.js in the game folder. Less kit support, not less possible. |
+
 ## Discover
 
 1. **Start at the index:**
@@ -57,3 +93,8 @@ when the behaviour truly must change inside the engine module.
   game would want** → that's platform feedback: `/feedback`.
 - The need is **specific to this game** → build it game-local (or override),
   and note in `handbook/design.md` if it's a pillar.
+- The engine has **nothing at all** for something many games would want (a
+  whole render path, a genre's core system) → do **both**: build it game-local
+  so the creator is never blocked waiting on Looop, *and* `/feedback` it so
+  Looop can make it first-class. Never let a gap in the library become a "no"
+  to the creator.

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

@@ -1,6 +1,6 @@
 ---
 name: feedback
-description: File feedback to the Looop team when something in Looop ITSELF seems broken or missing — the engine, a shared component, the looop CLI, login, publishing, the platform. Use the moment you or the creator notice "this looks like a Looop bug, not our game" — offer to file it right away, don't wait to be asked.
+description: File feedback to the Looop team when something in Looop ITSELF is broken or missing — the engine, a shared component, the looop CLI, login, publishing, the platform. Use the moment you or the creator think "this looks like a Looop bug, not our game" — AND, just as importantly, whenever you discover your own game breaking a Looop rule, because Looop's own instructions may be what put it there. Offer to file it right away; don't wait to be asked.
 ---
 
 # /feedback — tell Looop when Looop is the problem
@@ -13,6 +13,34 @@ that lied, a missing capability every game would want — **offer to file it**:
 
 This game's own bugs are NOT feedback — they're `/todo`s or just fixes.
 
+## The defect you will not notice
+
+There is one class of Looop bug the reflex above is blind to, and it is the most
+valuable class there is: **a defect Looop's own guidance caused.**
+
+It looks like this. You discover your game violating a Looop rule — it's routing
+state the wrong way, using an API it shouldn't. The symptom is in *your* code, so
+the conclusion writes itself: *"our bug, not the engine's."* You fix your game and
+move on, and Looop never hears about it.
+
+That inference is locally correct and globally wrong. **Looop's instructions are
+not a fixed point — they are a suspect.** They contradict each other sometimes.
+The mandatory ones (this repo's `AGENTS.md`, injected into every session) can be
+wrong while an opt-in practices doc is right, and you will have followed the
+mandatory one without ever noticing there was a choice.
+
+So, the rule:
+
+> **When you find your game violating a Looop rule, work out what led you there
+> BEFORE you fix it.**
+
+Retrace it honestly. Did a Looop-authored source — `AGENTS.md`, a
+`shared/practices/` doc, a library README, a skill — point you this way? If yes,
+**that is a Looop defect and it gets filed**, even though your game is also wrong.
+Both are true at the same time; fix your game *and* file the report. If you'd have
+made the same mistake with no guidance at all, it's just your bug — fix it and
+move on.
+
 ## What to file
 
 Write the report to `notes/feedback/<YYYY-MM-DD-HHMM>-<short-slug>.md`
@@ -26,6 +54,9 @@ detail you leave out is a detail they'll have to guess. Include:
 created: YYYY-MM-DD
 engine: <the looop.engine pin from package.json>
 cli: <@looop-games/cli version from package.json devDependencies>
+attachments:
+  - game.js
+  - src/net.js
 ---
 # <One line: what's wrong>
 
@@ -40,6 +71,10 @@ custom port, offline, …).
 The smallest steps/snippet that shows it. Exact commands **with their full
 output pasted verbatim** — never summarize an error message.
 
+## What led us here (if a Looop source did)
+The file and line that pointed you wrong, quoted, and the doc that contradicts
+it. This is the section that gets the guidance itself fixed.
+
 ## Transcript
 The conversation that surfaced this, quoted verbatim — from the creator's
 request that first hit the problem through your diagnosis: what they asked,
@@ -54,18 +89,37 @@ Trim game-specific noise, never evidence: cut what's irrelevant to the
 defect, keep everything that shows it. (The intake caps a report at 256 KiB —
 if the transcript pushes past that, cut it down to the relevant exchange.)
 
+## Attach the files you're talking about
+
+A report that cites `game.js:56` is only as good as the reader's ability to see
+line 56. **List the files your diagnosis rests on in the `attachments:`
+frontmatter** — they ship with the report, and the team reads them beside it.
+
+This applies to **any** report, whatever its reason: a bug, a missing capability,
+a rule that led you wrong, a module you had to fork. Whatever your evidence is,
+attach it.
+
+- **You pick the files** — you wrote the diagnosis, so you know what it rests on.
+- Paths are **relative to the game folder** and must stay inside it. Anything
+  pointing outside is refused outright.
+- **Text only** (source, logs, config) — up to 20 files, 256 KiB each, 1 MiB total.
+- Attach what the report *argues from*: the file with the bug, the module you
+  worked around, the config that reproduces it. Not the whole game.
+
 ## Send it
 
 1. Run **`npx looop feedback`** — it delivers every unsent report under
    `notes/feedback/` to the Looop team (login required; it's the same account
-   as publishing) and stamps each delivered file with `sent:` + `id:` in its
-   frontmatter so it never ships twice.
-2. If the send fails (offline, not logged in), the file stays unstamped —
-   just run `npx looop feedback` again later; it retries everything unsent.
+   as publishing), attachments included, and stamps each delivered file with
+   `sent:` + `id:` in its frontmatter so it never ships twice.
+2. If the send fails (offline, not logged in, a bad attachment path), the file
+   stays unstamped — fix what it says and run `npx looop feedback` again; it
+   retries everything unsent.
 
 ## Why bother
 
 An override that patches an engine bug is a fork that stops receiving updates;
-feedback is how the fix lands upstream so the fork can be deleted. And a
-missing capability filed from a real game is exactly how the engine decides
-what to build next.
+feedback is how the fix lands upstream so the fork can be deleted. A missing
+capability filed from a real game is exactly how the engine decides what to build
+next. And a rule that led you wrong will lead **every** creator wrong, in every
+game, until somebody says so.

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

@@ -0,0 +1,142 @@
+---
+name: handbook
+description: The entry point to this game's handbook — its durable truth. Use when you need to know what this game already believes (before building, before proposing anything), and when something durable emerges that belongs in it — a design pillar, a blessed feel value, or a playtest catch that needs converting into an automated check. Also use when durable truth appears that has no chapter yet (the game's vision, its world, its cast, its economy) and one should be started.
+---
+
+# /handbook — what this game knows about itself
+
+`handbook/` is this game's **durable truth**: the things a future session must
+not violate, and must not have to re-derive. It is the game's own layer on top
+of the engine's read-only craft docs — where they touch the same topic, the
+handbook is *this game's* answer.
+
+Three places knowledge lives here; keep them straight:
+
+| | Holds | Lifespan |
+|---|---|---|
+| **`handbook/`** | what this game IS and has decided | durable — outlives every plan |
+| **`notes/`** | what we're building or might build (`plans/`, `todos/`) | transient — closed when the work is |
+| the engine's `shared/practices/` | how Looop games are built in general | read-only, ships with the engine |
+
+The test for whether something belongs here: **would a future session need to
+*not violate* this?** → handbook. *Is it something we're doing, or might do?* →
+`notes/`.
+
+## The chapters
+
+```
+handbook/
+  design.md   the pillars — what this game IS, checked against new ideas
+  feel.md     locked feel values the creator has blessed
+  qa.md       checks this game has earned (mostly from playtests that caught something)
+```
+
+**The set is open, and these three are only where it starts.** They ship with
+every game because every game accumulates them. They are not the limit, and they
+are not a template to fill in — what else a handbook holds depends entirely on
+what this game turns out to need. See *Starting a new chapter*.
+
+## Reading it — do this before you build
+
+**`ls handbook/` and read what's relevant before writing game code or proposing
+a direction.** Every chapter opens with a line saying what it's for, so the
+folder listing plus the first two lines of each file is a cheap orientation.
+Reading is free; contradicting the handbook and being caught later is not.
+
+If what you're about to propose **contradicts something the handbook already
+says**, that is not a detail to smooth over — stop and say so. Either the idea is
+wrong, or what's written is out of date and the creator needs to say so out loud.
+Never quietly build against it.
+
+An empty chapter is honest — an early game hasn't decided much yet, and a
+speculative pillar nobody has lived is worse than none.
+
+## Growing it
+
+**Every handbook write needs the creator's approval first.** The handbook is
+*their* game's truth — propose the exact entry ("I'd like to record: …") and
+write it only after they say yes. Never slip an entry in as a side effect of
+other work. (Smoke/test FILES don't need this gate — they're regression tests,
+not blessed truth; only `handbook/` writes do.)
+
+### A design principle emerged → `handbook/design.md`
+
+When a decision reveals what this game IS ("never text tutorials — the world
+teaches", "death must always be the player's fault"), write the pillar down.
+Future builds check new ideas against these.
+
+### A playtest caught a defect → an automated check
+
+The premise (from the engine's `shared/practices/qa.md`): **a human catching a
+defect means an automated check was missing.** Convert the *class* of defect,
+not the instance:
+
+1. Name the miss precisely — not "the door was broken" but "doors can lose
+   their collision when the room resets, and nothing checks collision after a
+   reset."
+2. Prefer an **executable check**: write a `<aspect>.smoke.mjs` (or
+   `*.test.mjs`) that reproduces the defect — confirm it fails RED on the
+   broken state, then goes green on the fix. `npx looop test` discovers it
+   forever after; a guard you never saw fail is a guard you can't trust.
+3. **If the check needs to SEE the game's internals** (collision boxes, depth
+   order, hit areas) and the game has no debug overlay yet, **build one as part
+   of the conversion** — a keyboard-toggled draw of the real boxes/order. It's
+   a small one-time cost, and every later screenshot-verify reuses it (master
+   list row R2).
+4. Only if it truly can't be executed (needs human perception), add it as a
+   procedural step in **`handbook/qa.md`** — `/qa` runs those by hand each time.
+
+## Starting a new chapter
+
+The four standing chapters won't fit everything. When durable truth appears
+that belongs in none of them, **start a chapter** — that is the handbook
+working as intended, not a special case.
+
+A subject earns a chapter when it is: **durable** (it outlives the current
+plan), **referred back to** (future sessions need it to stay consistent), and
+**not a fit** for an existing chapter. It can be anything this game actually
+needs: `vision.md` (what the game is *for*, once the creator has said it out
+loud), `world.md` (a setting an agent must not contradict), `characters.md`,
+`economy.md` (numbers that have to balance), `controls.md`. Don't shop from that
+list — reach for whatever this game keeps needing to remember.
+
+To start one:
+
+1. **Propose it** — the name, and the exact first entry. Same approval gate as
+   any handbook write; creating a chapter is a bigger act than adding a line,
+   not a smaller one.
+2. Create `handbook/<subject>.md` with the standard shape:
+
+   ```markdown
+   # <Subject> — <what this chapter is for, in half a line>
+
+   <One or two sentences: what belongs here, what doesn't.>
+
+   ## YYYY-MM-DD — <the entry>
+   <The truth itself. Short. Actionable cold, by someone who wasn't there.>
+   ```
+
+3. Don't pre-create chapters "in case", and don't propose one because the game
+   "ought to" have it. An empty speculative chapter is a trap — it invites
+   invented content, and a creator filling in a template is not the same as a
+   creator telling you something true. A chapter starts the day it has something
+   true to hold.
+
+## The upstream half
+
+Before writing, ask: **is this lesson specific to this game, or would every
+Looop game want it?** A generic hole (an engine component that breaks a
+universal expectation, a check every game should run) belongs in the engine's
+master list, not just this repo — offer `/feedback` so it lands upstream for
+everyone. Do both when in doubt: the handbook entry protects this game now; the
+feedback fixes it everywhere later.
+
+## Rules
+
+- **One lesson per invocation, converted fully** — an entry someone can act on
+  cold, not a vague reminder.
+- **Date entries.** When a later decision supersedes one, update it **in place**
+  rather than stacking contradictions — a handbook that argues with itself is
+  worse than no handbook, because a future session will pick the wrong side.
+- **Short.** Every line in here is read by every future session. It earns its
+  place or it goes.

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

@@ -40,7 +40,7 @@ creator's list.
    URL to open, never a command to run). If everything was automatable, say
    so plainly; "couldn't test it" must never read as "tested and fine".
 5. **Close the ratchet.** If the creator's pass catches something your run
-   missed, that's a hole in the checks — run `/update-handbook` to convert
+   missed, that's a hole in the checks — run `/handbook` to convert
    that defect class into an automated check.
 
 ## Notes

package/template/AGENTS.md

@@ -48,11 +48,18 @@ applies. This table routes only what has no skill:
    scores, world objects) rides the room's authority — `room.update(...)`,
    `room.send('input', ...)` — never local mutation only one client sees.
    Verify multiplayer behaviour with TWO browser contexts, not one.
-2. **The engine is read-only.** `/shared/...` imports come from the installed
-   engine at `node_modules/@looop-games/engine` (not an npm dependency —
-   `looop dev` downloads the version pinned in `package.json`'s `looop.engine`
-   and reinstalls it if an `npm install` prunes it). Never edit files in
-   `node_modules` — use `overrides/shared/` (see the table above).
+2. **The engine is read-only — and it is not the ceiling.** `/shared/...`
+   imports come from the installed engine at `node_modules/@looop-games/engine`
+   (not an npm dependency — `looop dev` downloads the version pinned in
+   `package.json`'s `looop.engine` and reinstalls it if an `npm install` prunes
+   it). Never edit files in `node_modules` — use `overrides/shared/` (see the
+   table above). But read-only means *don't edit it*, **not** *don't exceed
+   it*: a Looop game is a web page, so **anything the browser can do, this game
+   can do.** The library is a bag of conveniences you draw from, not a fence
+   around what the game may be — what it doesn't have, you build, here in the
+   game folder. **Never tell the creator that Looop "can't" do something**
+   (see `/engine` — it is almost always false, and it retires their idea
+   without their consent).
 3. **Never hand-roll a server.** Only `looop dev` (or `looop test`) serves
    this game: they alias `/shared/...` and inject the platform layer. A plain
    static server 404s every engine import and the game silently never boots.
@@ -75,7 +82,7 @@ applies. This table routes only what has no skill:
 
 - **`handbook/`** — durable truth about THIS game: `qa.md` (its checks),
   `feel.md` (locked feel values), `design.md` (its pillars). Consult it before
-  working; grow it with `/update-handbook`.
+  working; grow it with `/handbook`.
 - **`notes/`** — work tracking: `notes/plans/` (what's being built — `/build`
   runs from these), `notes/todos/` (captured bugs/ideas), and
   `notes/feedback/` (reports for the Looop team, written by `/feedback`).

package/template/handbook/design.md

@@ -1,7 +1,8 @@
 # Design — the pillars
 
-What this game IS: the principles new ideas get checked against. Written as
-they emerge from real decisions (via `/update-handbook`), not invented up
+The rules that follow from the vision: the principles new ideas get checked
+against. Written as
+they emerge from real decisions (via `/handbook`), not invented up
 front — an empty file is honest; a speculative pillar is a trap.
 
 _No pillars yet._

package/template/handbook/feel.md

@@ -3,6 +3,6 @@
 Feel calls the creator has blessed: the value, where it lives, and why it's
 right — so no future session "improves" them away. General feel craft lives in
 the engine's `shared/practices/feel.md`; this file is only what THIS game has
-locked. `/update-handbook` adds entries.
+locked. `/handbook` adds entries.
 
 _Nothing locked yet._

package/template/handbook/qa.md

@@ -2,7 +2,7 @@
 
 Checks THIS game has earned, on top of the engine's master list
 (`node_modules/@looop-games/engine/shared/practices/qa.md`) and the executable
-tests `npx looop test` discovers. `/qa` runs all three sources; `/update-handbook`
+tests `npx looop test` discovers. `/qa` runs all three sources; `/handbook`
 adds entries here when a playtest catches something no automated check saw —
 but prefer writing a `*.smoke.mjs` when the check can be executed.
 

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

@@ -1,69 +0,0 @@
----
-name: update-handbook
-description: Record something durable this game just taught us — convert a playtest catch into an automated check, lock in a blessed feel value, or write down a design pillar. Use right after a creator playtest catches a defect the automated checks missed, when a feel value gets approved ("that jump is perfect — keep it"), or when a design principle emerges.
----
-
-# /update-handbook — keep what the game taught us
-
-`handbook/` is this game's durable truth — the layer that AUGMENTS the
-engine's read-only practices with what THIS game has learned. This skill is
-how it grows.
-
-**Every handbook write needs the creator's approval first.** The handbook is
-*their* game's truth — propose the exact entry ("I'd like to record: …"),
-and write it only after they say yes. Never slip an entry in as a side effect
-of other work. (Smoke/test FILES don't need this gate — they're regression
-tests, not blessed truth; only `handbook/` writes do.)
-
-Three kinds of lesson, three destinations:
-
-## 1. A playtest caught a defect → an automated check
-
-The premise (from the engine's `shared/practices/qa.md`): **a human catching a
-defect means an automated check was missing.** Convert the *class* of defect,
-not the instance:
-
-1. Name the miss precisely — not "the door was broken" but "doors can lose
-   their collision when the room resets, and nothing checks collision after a
-   reset."
-2. Prefer an **executable check**: write a `<aspect>.smoke.mjs` (or
-   `*.test.mjs`) that reproduces the defect — confirm it fails RED on the
-   broken state, then goes green on the fix. `npx looop test` discovers it
-   forever after; a guard you never saw fail is a guard you can't trust.
-3. **If the check needs to SEE the game's internals** (collision boxes, depth
-   order, hit areas) and the game has no debug overlay yet, **build one as
-   part of the conversion** — a keyboard-toggled draw of the real boxes/order.
-   It's a small one-time cost, and every later screenshot-verify reuses it
-   (master list row R2).
-4. Only if it truly can't be executed (needs human perception), add it as a
-   procedural step in **`handbook/qa.md`** — `/qa` runs those by hand each
-   time.
-
-## 2. A feel value got blessed → `handbook/feel.md`
-
-When the creator locks a feel call ("that speed is exactly right"), record the
-value, where it lives, and WHY it's right — so no future session "improves" it
-away. If it's worth defending, pin it with a smoke too.
-
-## 3. A design principle emerged → `handbook/design.md`
-
-When a decision reveals what this game IS ("never text tutorials — the world
-teaches", "death must always be the player's fault"), write the pillar down.
-Future builds check new ideas against these.
-
-## The upstream half
-
-Before writing, ask: **is this lesson specific to this game, or would every
-Looop game want it?** A generic hole (an engine component that breaks a
-universal expectation, a check every game should run) belongs in the engine's
-master list, not just this repo — offer `/feedback` so it lands upstream for
-everyone. Do both when in doubt: the handbook entry protects this game now;
-the feedback fixes it everywhere later.
-
-## Rules
-
-- One lesson per invocation, converted fully — an entry someone can act on
-  cold, not a vague reminder.
-- Handbook entries are durable truth: date them, keep them short, and when a
-  later decision supersedes one, update it in place rather than stacking
-  contradictions.