@myvillage/cli 2.16.1 → 2.18.0

package/README.md

@@ -19,6 +19,10 @@ myvillage login
 # Create a new game project
 myvillage create-game
 
+# Or bring a web game you already have into MyVillage
+# (shows what will change and asks first; --dry-run only shows)
+myvillage init-game ./my-game
+
 # Deploy to the platform
 myvillage deploy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myvillage/cli",
-  "version": "2.16.1",
+  "version": "2.18.0",
   "description": "MyVillageOS CLI for community developers",
   "type": "module",
   "bin": {

package/src/assets/game-toolkit/myvillage-game.js

@@ -1,4 +1,4 @@
-// MyVillage Game Bridge — the "mvgame" protocol (v2).
+// MyVillage Game Bridge — the "mvgame" protocol (v3).
 //
 // ONE contract for every MyVillage game, on every surface:
 //   - muni mobile app  (React Native WebView)
@@ -12,6 +12,13 @@
 // One the host ALWAYS provides, but you can trigger too:
 //   MyVillageGame.exit()                 // leave the game
 //
+// Play time is automatic. This file measures how long the player is actually
+// playing (screen visible, touched/clicked/pressed something recently) and
+// reports it to the host, which is how the platform tells a real play from
+// someone opening the game and closing it. Don't add timers or fake input for
+// it. Optionally, report the running score as the game goes:
+//   MyVillageGame.progress({ score })
+//
 // Real-time multiplayer (optional) — see "Multiplayer" below:
 //   const mp = await MyVillageGame.multiplayer({ arena, game: 'my-game' });
 //   await mp.quickMatch();              // or mp.host() / mp.join(code)
@@ -25,7 +32,7 @@
 
 const PROTOCOL = 'mvgame';
 const HOST_PROTOCOL = 'mvgame-host';
-const VERSION = 2;
+const VERSION = 3;
 
 const hasWindow = typeof window !== 'undefined';
 const inReactNative = hasWindow && !!window.ReactNativeWebView;
@@ -59,6 +66,73 @@ function post(message) {
   }
 }
 
+// ── Play time ───────────────────────────────────────────────────────────────
+// The platform counts a session as a play once the player has been actively
+// playing for a while (the threshold is the platform's, not ours). Only the game
+// page can tell a player who's playing from a game left open on a table, so the
+// measuring happens here: time counts while the page is visible and the player
+// has touched, clicked or pressed something in the last IDLE_AFTER_MS.
+//
+// The host forwards { type: 'progress', activeMs } to the platform. A message
+// with version >= 3 also tells the host this game measures its own time, so it
+// doesn't fall back to timing how long the game is on screen.
+
+const IDLE_AFTER_MS = 20000;
+const REPORT_EVERY_MS = 10000; // of active time
+const TICK_MS = 1000;
+
+let activeMs = 0;
+let lastInputAt = -Infinity;
+let lastTickAt = now();
+let reportedMs = -1;
+let lastReportAt = -Infinity;
+let pendingUpdate = null; // from progress(), sent with the next report
+let finished = false;
+
+function pageVisible() {
+  return typeof document === 'undefined' || document.visibilityState !== 'hidden';
+}
+
+function playTick() {
+  const t = now();
+  // A throttled background tab can skip ticks; never credit more than a tick or
+  // two for one interval.
+  const dt = Math.min(t - lastTickAt, TICK_MS * 2);
+  lastTickAt = t;
+  if (pageVisible() && t - lastInputAt < IDLE_AFTER_MS) activeMs += dt;
+  if (!finished && activeMs - reportedMs >= REPORT_EVERY_MS) reportProgress();
+}
+
+function reportProgress() {
+  if (finished) return;
+  reportedMs = activeMs;
+  lastReportAt = now();
+  const update = pendingUpdate;
+  pendingUpdate = null;
+  post({ type: 'progress', ...update, activeMs: Math.round(activeMs) });
+}
+
+if (hasWindow) {
+  const onInput = () => {
+    lastInputAt = now();
+  };
+  for (const type of ['pointerdown', 'pointermove', 'touchstart', 'touchmove', 'keydown', 'wheel']) {
+    window.addEventListener(type, onInput, { capture: true, passive: true });
+  }
+  setInterval(playTick, TICK_MS);
+  // Leaving (app backgrounded, tab hidden, page closing): report what we have.
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', () => {
+      if (!pageVisible() && activeMs > reportedMs) reportProgress();
+    });
+  }
+  window.addEventListener('pagehide', () => {
+    if (activeMs > reportedMs) reportProgress();
+  });
+  // Announce right away so the host knows this game reports its own play time.
+  setTimeout(() => reportProgress(), 0);
+}
+
 // ── Host context ────────────────────────────────────────────────────────────
 // Hosts that support multiplayer hand the game a context:
 //   { apiBase, game, playToken, platform, player: { displayName } }
@@ -451,7 +525,29 @@ export const MyVillageGame = {
    * `durationMs` is added automatically.
    */
   complete(result = {}) {
-    post({ type: 'complete', durationMs: Math.round(now() - startedAt), ...result });
+    if (finished) return;
+    playTick();
+    finished = true;
+    post({
+      type: 'complete',
+      durationMs: Math.round(now() - startedAt),
+      activeMs: Math.round(activeMs),
+      ...result,
+    });
+  },
+
+  /**
+   * Optional: report how the game is going, e.g. the running score. Play time is
+   * reported automatically — you never need to call this for a play to count.
+   *   { score?: number, custom?: object }
+   */
+  progress(update = {}) {
+    pendingUpdate = { ...pendingUpdate, ...update };
+    // Safe to call every frame: sent at most every couple of seconds.
+    if (now() - lastReportAt >= 2000) {
+      playTick();
+      reportProgress();
+    }
   },
 
   /** Request to leave the game. The host also always offers an Exit control. */

package/src/assets/templates/arena/AGENTS.md

@@ -67,6 +67,7 @@ A match starts by itself once `minPlayers` are connected. Until then players can
 - Keep `MyVillageGame.ready()` in `src/main.js`.
 - **Never send positions, hits or scores yourself.** Only `net.controls`. Anything else is ignored by the server, and it's the server's results that award MVT.
 - **Don't call `MyVillageGame.complete()` when a match ends.** The platform records multiplayer results from the match server. Hosts treat `complete()` as "close the game", which would stop players from playing again.
+- Plays count automatically: `src/myvillage-game.js` reports active play time to the host, and the platform counts a play after 30 seconds of it. Don't add anything for it.
 - Players are identified only by display name and an in-match id. Don't ask for, show or store anything more about them.
 - **Players only play with their own village.** The platform enforces it: codes only admit village-mates of the host, and quick match stays inside the player's villages. Don't build anything that suggests playing with strangers.
 - Don't add an Exit button; the host provides one (top-left). The in-game **Leave** button just returns to the lobby.

package/src/commands/create-game.js

@@ -61,8 +61,8 @@ export async function createGameCommand(options = {}) {
           name: 'orientation',
           message: 'Where will this game play?',
           choices: [
-            { name: 'Portrait — muni mobile app + web (plays everywhere)', value: 'portrait' },
-            { name: 'Landscape — web only (mvp-video-games)', value: 'landscape' },
+            { name: 'Portrait — muni mobile app + web', value: 'portrait' },
+            { name: 'Landscape — muni mobile app (turned sideways) + web; Unity: web only', value: 'landscape' },
           ],
         },
       ])

package/src/commands/deploy.js

@@ -9,6 +9,7 @@ import { villageSpinner, brand } from '../utils/brand.js';
 import { isAuthenticated } from '../utils/auth.js';
 import { deployGame, getGameUploadUrl, confirmGameUpload, submitGameForReview, getGameDetail, updateGameMetadata } from '../utils/api.js';
 import { preflightBundles } from '../utils/preflight.js';
+import { refreshGameToolkit, gameCallsComplete } from '../utils/game-toolkit.js';
 import { selectGameVillages } from '../utils/village-resolver.js';
 
 function readPackageJson(dir) {
@@ -269,6 +270,21 @@ async function deployThreeJsGame(projectDir, pkg, options = {}) {
   const villageIds = await gatherVillages(pkg.myvillage.villages || [], options);
   if (villageIds === null) return; // could not resolve villages — abort
 
+  // Ship the current platform toolkit (play-time reporting, host protocol),
+  // whatever CLI version the game was created with.
+  const toolkitUpdated = refreshGameToolkit(projectDir);
+  if (toolkitUpdated.length && !json) {
+    console.log(brand.teal(`  Updated the MyVillage game toolkit (${toolkitUpdated.join(', ')})`));
+  }
+  // Multiplayer games never call complete() — the match server records results.
+  const warnings = [];
+  if (!multiplayer && !gameCallsComplete(projectDir)) {
+    warnings.push(
+      "This game never calls MyVillageGame.complete(). Plays still count, but finishing the game won't record a completion or pay the player's reward. Call it on every way the game can end (win, lose, game over).",
+    );
+  }
+  if (!json) for (const w of warnings) console.log(chalk.yellow(`  ⚠ ${w}`));
+
   const spinner = json ? null : villageSpinner('Building game...').start();
 
   const failOut = (msg) => {
@@ -360,6 +376,8 @@ async function deployThreeJsGame(projectDir, pkg, options = {}) {
           status: finalStatus,
           title: metadata.title,
           villageIds,
+          toolkitUpdated,
+          warnings,
         }),
       );
       return;

package/src/commands/init-game.js

@@ -0,0 +1,200 @@
+import { existsSync, statSync } from 'fs';
+import { resolve, basename } from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { brand } from '../utils/brand.js';
+import {
+  inspectGameFolder,
+  convertToGame,
+  defaultCopyDir,
+  updatePlatformFiles,
+  GAME_CATEGORIES,
+  TARGET_AGES,
+} from '../utils/game-init.js';
+
+// `myvillage init-game [dir]` — bring an existing web game into MyVillage, or
+// bring a MyVillage game's platform files up to this CLI's. Shows what will
+// change and asks before writing anything (--yes skips the question, --dry-run
+// only shows). MVP Studio runs the same code in-process (src/utils/game-init.js).
+//
+// A web game is converted into a new folder next to it (<name>-myvillage) so
+// the original stays as it was; --into picks the folder, --in-place converts
+// the original instead.
+
+function out(json, payload) {
+  if (json) console.log(JSON.stringify(payload));
+}
+
+function fail(json, msg) {
+  if (json) console.log(JSON.stringify({ ok: false, error: msg }));
+  else console.log(chalk.red(`\n  ✗ ${msg}`));
+  process.exitCode = 1;
+}
+
+function printChanges(changes) {
+  for (const c of changes) {
+    const verb = c.action === 'create' ? brand.green('+ add   ') : brand.gold('~ update');
+    console.log(`    ${verb} ${c.path}  ${brand.teal(c.summary)}`);
+  }
+}
+
+function printNotes(notes) {
+  if (!notes.length) return;
+  console.log();
+  console.log(brand.gold('  Still needed (left for you):'));
+  for (const n of notes) console.log(`    • ${n}`);
+}
+
+async function confirm(message) {
+  const { ok } = await inquirer.prompt([{ type: 'confirm', name: 'ok', message, default: true }]);
+  return ok;
+}
+
+export async function initGameCommand(dirArg, options = {}) {
+  const json = !!options.json;
+  const dryRun = !!options.dryRun;
+  // JSON means a program is driving: never prompt.
+  const ask = !json && !options.yes;
+  const dir = resolve(dirArg || options.dir || process.cwd());
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return fail(json, `No such folder: ${dir}`);
+
+  let info;
+  try {
+    info = inspectGameFolder(dir);
+  } catch (err) {
+    return fail(json, err.message);
+  }
+
+  if (info.kind === 'unsupported') {
+    if (!json) return fail(json, info.reason);
+    process.exitCode = 1;
+    return out(json, { ok: false, kind: info.kind, dir, error: info.reason });
+  }
+
+  if (info.kind === 'unity') {
+    if (json) return out(json, { ok: true, kind: 'unity', dir, dryRun, changes: [], notes: [] });
+    console.log(brand.green(`\n  ✓ ${info.name} is a MyVillage Unity game. Nothing to set up here.`));
+    return;
+  }
+
+  // ── Already a MyVillage game: refresh its platform files ──
+  if (info.kind === 'myvillage') {
+    if (dryRun || !info.changes.length) {
+      if (json) return out(json, { ok: true, kind: 'myvillage', dir, name: info.name, dryRun: true, changes: info.changes, notes: [] });
+      if (!info.changes.length) {
+        console.log(brand.green(`\n  ✓ ${info.name} already has the latest MyVillage platform files.`));
+      } else {
+        console.log(`\n  ${info.name} has older MyVillage platform files:\n`);
+        printChanges(info.changes);
+        console.log(brand.teal('\n  Run without --dry-run to update them.'));
+      }
+      return;
+    }
+    if (ask) {
+      console.log(`\n  ${info.name} has older MyVillage platform files. This will:\n`);
+      printChanges(info.changes);
+      console.log();
+      if (!(await confirm('Update them?'))) return;
+    }
+    try {
+      const res = updatePlatformFiles(dir);
+      if (json) return out(json, { ok: true, kind: 'myvillage', dir, name: info.name, dryRun: false, changes: res.changes, notes: [] });
+      console.log(brand.green(`\n  ✓ Updated ${res.changes.map((c) => c.path).join(', ')}`));
+    } catch (err) {
+      fail(json, err.message);
+    }
+    return;
+  }
+
+  // ── A web project: convert it ──
+  const given = {
+    name: options.name,
+    description: options.description,
+    category: options.category,
+    orientation: options.orientation,
+    targetAge: options.targetAge,
+  };
+  let details = { ...info.defaults };
+  for (const [k, v] of Object.entries(given)) if (v !== undefined) details[k] = String(v);
+  if (options.into && options.inPlace) return fail(json, 'Use --into or --in-place, not both.');
+  let into = options.inPlace ? undefined : resolve(options.into || defaultCopyDir(dir));
+
+  if (ask && !dryRun) {
+    console.log(`\n  ${brand.gold(dir)} is a web project that isn't a MyVillage game yet.\n`);
+    const prompts = [];
+    if (given.name === undefined) prompts.push({ type: 'input', name: 'name', message: 'Game name:', default: details.name });
+    if (given.description === undefined) prompts.push({ type: 'input', name: 'description', message: 'Description:', default: details.description });
+    if (given.category === undefined)
+      prompts.push({ type: 'list', name: 'category', message: 'What kind of game is it?', choices: GAME_CATEGORIES, default: details.category });
+    if (given.orientation === undefined)
+      prompts.push({
+        type: 'list',
+        name: 'orientation',
+        message: 'Where will it play?',
+        choices: [
+          { name: 'Portrait — muni mobile app + web', value: 'portrait' },
+          { name: 'Landscape — muni mobile app (turned sideways) + web', value: 'landscape' },
+        ],
+        default: details.orientation,
+      });
+    if (given.targetAge === undefined)
+      prompts.push({ type: 'list', name: 'targetAge', message: 'Target age group:', choices: TARGET_AGES, default: details.targetAge });
+    if (!options.into && !options.inPlace)
+      prompts.push({
+        type: 'list',
+        name: 'where',
+        message: 'Where should the MyVillage version go?',
+        choices: [
+          { name: `A new folder: ${basename(into)} (your original stays as it is)`, value: 'copy' },
+          { name: 'This folder (change it in place)', value: 'in-place' },
+        ],
+        default: 'copy',
+      });
+    const { where, ...answers } = await inquirer.prompt(prompts);
+    details = { ...details, ...answers };
+    if (where === 'in-place') into = undefined;
+  }
+
+  let plan;
+  try {
+    plan = convertToGame(dir, details, { dryRun: true, into });
+  } catch (err) {
+    return fail(json, err.message);
+  }
+
+  if (dryRun) {
+    if (json) return out(json, { ok: true, kind: 'web', source: dir, name: details.name, defaults: info.defaults, dryRun: true, ...plan });
+    console.log(`\n  Bringing ${details.name} into MyVillage would${into ? ` copy it to ${brand.gold(into)} and then` : ''}:\n`);
+    printChanges(plan.changes);
+    printNotes(plan.notes);
+    console.log(brand.teal('\n  Run without --dry-run to make these changes.'));
+    return;
+  }
+
+  if (ask) {
+    console.log(into ? `\n  This will copy the game to ${brand.gold(into)}, then in the copy:\n` : `\n  This will:\n`);
+    printChanges(plan.changes);
+    printNotes(plan.notes);
+    console.log(brand.teal(into ? '\n  The original folder isn\'t changed. node_modules, build output and git history aren\'t copied.' : "\n  Your game's own code isn't changed."));
+    console.log();
+    if (!(await confirm('Make these changes?'))) return;
+  }
+
+  try {
+    const res = convertToGame(dir, details, { into });
+    if (json) return out(json, { ok: true, kind: 'web', source: dir, name: details.name, dryRun: false, ...res });
+    console.log(brand.green(`\n  ✓ ${details.name} is set up as a MyVillage game${into ? ` in ${res.dir}` : ''}.`));
+    if (into) console.log(brand.teal(`    cd ${res.dir} && npm install`));
+    printNotes(res.notes);
+    console.log();
+    console.log(brand.teal('  Next, connect the game itself (or let MVP Studio\'s AI do it: open the game → Design):'));
+    console.log(`    1. ${brand.gold("import { MyVillageGame } from './myvillage-game.js'")} where the game starts`);
+    console.log(`    2. ${brand.gold('MyVillageGame.ready()')} once it's playable`);
+    console.log(`    3. ${brand.gold('MyVillageGame.complete({ score, won })')} on every way it can end`);
+    console.log(`    4. ${brand.gold('npm run build')}, then ${brand.gold('myvillage deploy')}`);
+    console.log(brand.teal('  AGENTS.md has the full rules (phone layout, play time).'));
+    console.log();
+  } catch (err) {
+    fail(json, err.message);
+  }
+}

package/src/index.js

@@ -16,6 +16,7 @@ import {
   apiKeyShowScopesCommand,
 } from './commands/api-key.js';
 import { createGameCommand } from './commands/create-game.js';
+import { initGameCommand } from './commands/init-game.js';
 import { createCommand } from './commands/create-app.js';
 import { deployCommand } from './commands/deploy.js';
 import { publishBookCommand } from './commands/publish-book.js';
@@ -229,6 +230,22 @@ export function run() {
     .option('--json', 'Output the result as JSON (implies non-interactive)')
     .action(createGameCommand);
 
+  program
+    .command('init-game [dir]')
+    .description('Bring an existing web game into MyVillage, or update a game\'s MyVillage platform files')
+    .option('--name <name>', 'Game name (defaults to package.json)')
+    .option('--description <text>', 'Game description')
+    .option('--category <category>', 'education | action | adventure | puzzle | quiz | exploration | narrative | other')
+    .option('--orientation <orientation>', 'portrait | landscape')
+    .option('--target-age <age>', 'under-5 | 6-12 | 13-and-over')
+    .option('--dir <path>', 'Project folder (defaults to cwd)')
+    .option('--into <path>', 'Convert into this new folder (default: <folder>-myvillage next to it)')
+    .option('--in-place', 'Convert the folder itself instead of a copy')
+    .option('--dry-run', 'Show what would change and write nothing')
+    .option('-y, --yes', "Don't ask: use the defaults and make the changes")
+    .option('--json', 'Output the result as JSON (implies --yes)')
+    .action(initGameCommand);
+
   program
     .command('create')
     .description('Create a new application or game')

package/src/utils/game-init.js

@@ -0,0 +1,379 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, cpSync, readdirSync, rmSync } from 'fs';
+import { join, basename, dirname, resolve, relative, isAbsolute, sep } from 'path';
+import { installGameToolkit, refreshGameToolkit } from './game-toolkit.js';
+import { generateGameAgents, generateMinimalViteConfig, starterThumbnailPath } from './templates.js';
+
+// Bringing a web game that wasn't made with MyVillage into the platform
+// (`myvillage init-game`), and keeping a MyVillage game's platform files current.
+// MVP Studio imports this module in-process, so it must stay free of chalk,
+// inquirer and anything else that prints or prompts.
+//
+// Every entry point takes `dryRun`: the same code computes what would change
+// and makes the change, so what Studio shows before asking is exactly what
+// gets written.
+
+export const GAME_CATEGORIES = ['education', 'action', 'adventure', 'puzzle', 'quiz', 'exploration', 'narrative', 'other'];
+export const TARGET_AGES = ['under-5', '6-12', '13-and-over'];
+export const ORIENTATIONS = ['portrait', 'landscape'];
+
+const VITE_CONFIGS = ['vite.config.js', 'vite.config.mjs', 'vite.config.ts', 'vite.config.mts', 'vite.config.cjs', 'vite.config.cts'];
+const OUR_AGENTS = /^# AGENTS\.md — working on this MyVillage/;
+const AGENTS_START = '<!-- myvillage:agents:start -->';
+const AGENTS_END = '<!-- myvillage:agents:end -->';
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(path, data) {
+  writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
+}
+
+function deps(pkg) {
+  return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+}
+
+function titleFromPackageName(raw) {
+  const bare = String(raw || '').replace(/^@[^/]+\//, '');
+  return bare
+    .split(/[-_.\s]+/)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+/**
+ * What kind of folder this is, and what `init-game` would do to it.
+ *
+ *   kind 'web'          a package.json project with no `myvillage` block: `changes`
+ *                       is the conversion plan, `defaults` the prefilled details
+ *   kind 'myvillage'    already a MyVillage JS game: `changes` lists platform
+ *                       files that are older than this CLI's
+ *   kind 'unity'        a MyVillage Unity game (nothing to update here)
+ *   kind 'unsupported'  anything else; `reason` says what is supported
+ */
+export function inspectGameFolder(dir) {
+  const unity = readJson(join(dir, 'myvillage.json'));
+  if (unity && unity.engine === 'unity') {
+    return { kind: 'unity', dir, name: unity.name || basename(dir), changes: [], notes: [] };
+  }
+
+  const pkgPath = join(dir, 'package.json');
+  const pkg = readJson(pkgPath);
+  if (!pkg) {
+    const looksUnity = existsSync(join(dir, 'Assets')) && existsSync(join(dir, 'ProjectSettings'));
+    const reason = existsSync(pkgPath)
+      ? "package.json isn't valid JSON, so this folder can't be read as a web game. Fix it and try again."
+      : looksUnity
+        ? 'This looks like a Unity project that wasn\'t made with MyVillage. Unity games start from New game with Engine set to Unity; bring your scenes and scripts into that project.'
+        : 'This folder isn\'t a game Studio can bring in. Studio supports web games with a package.json (built with Vite, or any tool whose `npm run build` writes a dist/ folder), and Unity games made with MyVillage.';
+    return { kind: 'unsupported', dir, reason, changes: [], notes: [] };
+  }
+
+  if (pkg.myvillage && typeof pkg.myvillage === 'object') {
+    const { changes } = updatePlatformFiles(dir, { dryRun: true });
+    return { kind: 'myvillage', dir, name: pkg.myvillage.name || pkg.name || basename(dir), changes, notes: [] };
+  }
+
+  const defaults = conversionDefaults(dir, pkg);
+  const { changes, notes } = convertToGame(dir, defaults, { dryRun: true });
+  return { kind: 'web', dir, name: defaults.name, defaults, changes, notes, copyTo: defaultCopyDir(dir) };
+}
+
+// ── Converting into a copy ──────────────────────────────────────────────────
+// By default a game is converted into a new folder next to the original, so the
+// original stays exactly as it was. Installed packages and build output aren't
+// copied (npm install / npm run build make them again), and neither is git
+// history: the copy is a new project.
+
+const SKIP_ANYWHERE = new Set(['node_modules', '.git', '.DS_Store']);
+const SKIP_AT_TOP = new Set(['dist', 'build', '.vite', '.cache', '.parcel-cache', '.turbo', '.next', 'coverage']);
+
+/** A free sibling folder for the converted copy: `<name>-myvillage`, then -2, -3… */
+export function defaultCopyDir(dir) {
+  const base = join(dirname(resolve(dir)), `${basename(resolve(dir))}-myvillage`);
+  if (!existsSync(base)) return base;
+  for (let i = 2; ; i++) if (!existsSync(`${base}-${i}`)) return `${base}-${i}`;
+}
+
+function isInside(child, parent) {
+  const rel = relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+/** Copy a project into `to` (which must not exist yet, or be empty). */
+export function copyGameProject(from, to) {
+  const src = resolve(from);
+  const dest = resolve(to);
+  if (isInside(dest, src)) throw new Error('The new folder can\'t be inside the game\'s own folder.');
+  if (existsSync(dest) && readdirSync(dest).length) {
+    throw new Error(`${dest} already exists and isn't empty. Pick a new folder.`);
+  }
+  cpSync(src, dest, {
+    recursive: true,
+    filter: (path) => {
+      const rel = relative(src, path);
+      if (!rel) return true;
+      const parts = rel.split(sep);
+      if (parts.some((p) => SKIP_ANYWHERE.has(p))) return false;
+      return !SKIP_AT_TOP.has(parts[0]);
+    },
+  });
+}
+
+/** The game details to prefill, from what package.json already says. */
+export function conversionDefaults(dir, pkg = readJson(join(dir, 'package.json')) || {}) {
+  const keywords = Array.isArray(pkg.keywords) ? pkg.keywords.map((k) => String(k).toLowerCase()) : [];
+  return {
+    name: String(pkg.productName || '').trim() || titleFromPackageName(pkg.name) || titleFromPackageName(basename(dir)) || 'My Game',
+    description: typeof pkg.description === 'string' ? pkg.description : '',
+    category: GAME_CATEGORIES.find((c) => keywords.includes(c)) || 'education',
+    // Portrait plays everywhere (the muni app and the web).
+    orientation: 'portrait',
+    targetAge: '6-12',
+  };
+}
+
+function normalizeDetails(details) {
+  const name = String(details.name || '').trim();
+  if (!name) throw new Error('The game needs a name.');
+  const category = String(details.category || 'education').toLowerCase();
+  if (!GAME_CATEGORIES.includes(category)) throw new Error(`Category must be one of: ${GAME_CATEGORIES.join(', ')}`);
+  const orientation = String(details.orientation || 'portrait').toLowerCase();
+  if (!ORIENTATIONS.includes(orientation)) throw new Error('Orientation must be portrait or landscape.');
+  const targetAge = String(details.targetAge || '6-12').toLowerCase();
+  if (!TARGET_AGES.includes(targetAge)) throw new Error(`Target age must be one of: ${TARGET_AGES.join(', ')}`);
+  const description = typeof details.description === 'string' ? details.description.trim() : '';
+  return { name, category, orientation, targetAge, description };
+}
+
+/**
+ * Turn a package.json web project into a MyVillage game: the `myvillage`
+ * block, the toolkit, AGENTS.md, a relative Vite base + build script, and a
+ * starter thumbnail. Never touches the game's own code, and never rewrites a
+ * build it doesn't understand (a note says what's needed instead).
+ *
+ * With `into`, the project is first copied there (see copyGameProject) and the
+ * copy is converted; the original folder isn't touched. Without it, the folder
+ * itself is converted.
+ *
+ * Returns { dir, changes: [{ path, action: 'create'|'update', summary }], notes },
+ * where `dir` is the folder that was (or would be) converted.
+ */
+export function convertToGame(dir, details, { dryRun = false, into } = {}) {
+  if (!into) return { dir, ...convertInPlace(dir, details, { dryRun }) };
+  // The copy would get exactly the original's plan (it's the same files).
+  if (dryRun) return { dir: resolve(into), ...convertInPlace(dir, details, { dryRun: true }) };
+  // Check the details before copying anything.
+  normalizeDetails(details);
+  const dest = resolve(into);
+  const existed = existsSync(dest);
+  copyGameProject(dir, dest);
+  try {
+    return { dir: dest, ...convertInPlace(dest, details) };
+  } catch (err) {
+    // Don't leave a half-converted copy behind.
+    if (!existed) rmSync(dest, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+function convertInPlace(dir, details, { dryRun = false } = {}) {
+  const pkgPath = join(dir, 'package.json');
+  const pkg = readJson(pkgPath);
+  if (!pkg) throw new Error('No readable package.json in this folder.');
+  if (pkg.myvillage) throw new Error('This folder is already a MyVillage game.');
+  const game = normalizeDetails(details);
+
+  const changes = [];
+  const notes = [];
+  const change = (path, action, summary) => changes.push({ path, action, summary });
+
+  const isVite = !!deps(pkg).vite || VITE_CONFIGS.some((f) => existsSync(join(dir, f)));
+
+  // ── package.json ──
+  const pkgSummary = ['add the MyVillage details (name, kind, orientation, ages)'];
+  const scripts = { ...(pkg.scripts || {}) };
+  if (isVite) {
+    if (!scripts.build) {
+      scripts.build = 'vite build';
+      pkgSummary.push('add a `build` script (vite build)');
+    } else if (!/\bvite\b/.test(scripts.build)) {
+      notes.push(`The \`build\` script ("${scripts.build}") doesn't run Vite. Deploy runs \`npm run build\` and uploads the dist/ folder it makes, so check that it still does.`);
+    }
+    if (!scripts.dev) {
+      scripts.dev = 'vite';
+      pkgSummary.push('add a `dev` script for the preview');
+    }
+  } else if (!scripts.build) {
+    notes.push("This project doesn't use Vite and has no `build` script. Deploy runs `npm run build` and uploads the dist/ folder it makes (with an index.html and relative asset paths), so add a build that does that. Vite is the easiest way.");
+  } else {
+    notes.push(`This project doesn't use Vite, so its build was left alone. Deploy runs \`npm run build\` ("${scripts.build}") and uploads dist/: make sure it writes there, with index.html at the top and asset paths that don't start with "/".`);
+  }
+  if (!isVite && !scripts.dev) {
+    notes.push('There is no `dev` script, so Studio can\'t show a live preview until one is added.');
+  }
+
+  const banner = ['assets/banner.png', 'assets/banner.jpg'].find((p) => existsSync(join(dir, p)));
+  const myvillage = {
+    name: game.name,
+    gameId: null,
+    gameType: 'custom',
+    category: game.category,
+    engine: deps(pkg).three ? 'three' : 'web',
+    // Brought in with init-game (not scaffolded): picks the AGENTS.md guide.
+    converted: true,
+    targetAge: game.targetAge,
+    orientation: game.orientation,
+    aspectRatio: game.orientation === 'portrait' ? '9:16' : '16:9',
+    assets: { thumbnail: 'assets/thumbnail.png', ...(banner && { banner }) },
+    villages: [],
+    lastDeployed: null,
+  };
+  const nextPkg = { ...pkg };
+  if (game.description && game.description !== pkg.description) nextPkg.description = game.description;
+  if (Object.keys(scripts).length) nextPkg.scripts = scripts;
+  nextPkg.myvillage = myvillage;
+  change('package.json', 'update', pkgSummary.join('; '));
+
+  // ── Vite config ──
+  if (isVite) {
+    const configFile = VITE_CONFIGS.find((f) => existsSync(join(dir, f)));
+    if (!configFile) {
+      const file = pkg.type === 'module' ? 'vite.config.js' : 'vite.config.mjs';
+      change(file, 'create', "use relative asset paths (base: './') so the game loads from MyVillage");
+      if (!dryRun) writeFileSync(join(dir, file), generateMinimalViteConfig());
+    } else {
+      const fixed = withRelativeBase(readFileSync(join(dir, configFile), 'utf8'));
+      if (fixed.text) {
+        change(configFile, 'update', fixed.summary);
+        if (!dryRun) writeFileSync(join(dir, configFile), fixed.text);
+      } else if (fixed.note) {
+        notes.push(`${configFile}: ${fixed.note}`);
+      }
+      const outDir = /\boutDir\s*:\s*(['"`])([^'"`]+)\1/.exec(readFileSync(join(dir, configFile), 'utf8'))?.[2];
+      if (outDir && !['dist', './dist', 'dist/', './dist/'].includes(outDir)) {
+        notes.push(`${configFile} builds into "${outDir}", but deploy uploads dist/. Change build.outDir to 'dist'.`);
+      }
+    }
+  }
+
+  // ── Toolkit ──
+  const hadToolkit = new Set(['src/myvillage-game.js', 'src/myvillage-realtime.js'].filter((p) => existsSync(join(dir, p))));
+  const toolkit = installGameToolkit(dir, { dryRun });
+  for (const path of toolkit.changed) {
+    change(path, hadToolkit.has(path) ? 'update' : 'create',
+      path.endsWith('myvillage-game.js')
+        ? 'the MyVillage toolkit: ready(), complete() and automatic play time'
+        : 'multiplayer support the toolkit loads when a game asks for it');
+  }
+  for (const path of toolkit.conflicts) {
+    notes.push(`${path} already exists and isn't the MyVillage toolkit, so it was left alone. Rename it, then run this again.`);
+  }
+
+  // ── AGENTS.md ──
+  const agents = agentsMdChange(dir, myvillage, { slug: pkg.name, description: nextPkg.description, dryRun });
+  if (agents) change('AGENTS.md', agents.action, agents.summary);
+
+  // ── Cover art ──
+  if (!existsSync(join(dir, 'assets', 'thumbnail.png'))) {
+    change('assets/thumbnail.png', 'create', 'starter cover art (swap it for your own any time)');
+    if (!dryRun) {
+      mkdirSync(join(dir, 'assets'), { recursive: true });
+      copyFileSync(starterThumbnailPath(), join(dir, 'assets', 'thumbnail.png'));
+    }
+  }
+
+  // package.json last, so a failure above leaves the folder still unconverted.
+  if (!dryRun) writeJson(pkgPath, nextPkg);
+  return { changes, notes };
+}
+
+/**
+ * Bring a MyVillage JS game's platform files (the toolkit and AGENTS.md) up to
+ * this CLI's. `deploy` already refreshes the toolkit; AGENTS.md only changes here.
+ */
+export function updatePlatformFiles(dir, { dryRun = false } = {}) {
+  const pkg = readJson(join(dir, 'package.json'));
+  if (!pkg || !pkg.myvillage) throw new Error('Not a MyVillage web game (no `myvillage` block in package.json).');
+
+  const changes = [];
+  for (const path of refreshGameToolkit(dir, { dryRun })) {
+    changes.push({ path, action: 'update', summary: 'the latest MyVillage toolkit' });
+  }
+  const agents = agentsMdChange(dir, pkg.myvillage, { slug: pkg.name, description: pkg.description, dryRun });
+  if (agents) changes.push({ path: 'AGENTS.md', ...agents });
+  return { changes, notes: [] };
+}
+
+/**
+ * Write (or plan) the AGENTS.md this CLI generates for the game. A file that
+ * is ours is replaced; someone else's AGENTS.md keeps its text and gets ours as
+ * a marked section at the end. Returns null when it's already current.
+ */
+function agentsMdChange(dir, myvillage, { slug, description, dryRun }) {
+  const path = join(dir, 'AGENTS.md');
+  const latest = generateGameAgents(myvillage, { slug, description });
+  const section = `${AGENTS_START}\n${latest.trimEnd()}\n${AGENTS_END}\n`;
+
+  let next;
+  let action;
+  let summary;
+  if (!existsSync(path)) {
+    next = latest;
+    action = 'create';
+    summary = 'a guide for AI helpers: the game contract and phone layout rules';
+  } else {
+    const current = readFileSync(path, 'utf8');
+    const start = current.indexOf(AGENTS_START);
+    const end = current.indexOf(AGENTS_END);
+    if (OUR_AGENTS.test(current)) {
+      if (current === latest) return null;
+      next = latest;
+      summary = 'replace with the latest guide for AI helpers';
+    } else if (start >= 0 && end > start) {
+      const tail = current.slice(end + AGENTS_END.length).replace(/^\n/, '');
+      next = current.slice(0, start) + section + tail;
+      if (next === current) return null;
+      summary = 'refresh the MyVillage section (your own text is kept)';
+    } else {
+      next = current.trimEnd() + '\n\n' + section;
+      summary = 'add a MyVillage section at the end (your own text is kept)';
+    }
+    action = 'update';
+  }
+  if (!dryRun) writeFileSync(path, next);
+  return { action, summary };
+}
+
+/**
+ * Make a Vite config use base: './'. Returns { text, summary } with the new
+ * config, { note } when it can't be changed safely (a computed base, a config
+ * shape we don't recognise), or {} when it's already right.
+ */
+export function withRelativeBase(config) {
+  const literal = /\bbase\s*:\s*(['"`])([^'"`]*)\1/.exec(config);
+  if (literal) {
+    if (literal[2] === './' || literal[2] === '') return {};
+    return {
+      text: config.slice(0, literal.index) + "base: './'" + config.slice(literal.index + literal[0].length),
+      summary: `use relative asset paths: base '${literal[2]}' becomes './'`,
+    };
+  }
+  if (/\bbase\s*:/.test(config)) {
+    return { note: "`base` is computed, so it was left alone. Make sure the build uses base: './' (relative asset paths); MyVillage serves the game from its own folder." };
+  }
+  const open = /(defineConfig\(\s*(?:\([^)]*\)\s*=>\s*\(\s*)?\{|export\s+default\s+\{|module\.exports\s*=\s*\{)/.exec(config);
+  if (!open) {
+    return { note: "couldn't find where to add base: './'. Add it to the config so asset paths are relative; MyVillage serves the game from its own folder." };
+  }
+  const at = open.index + open[0].length;
+  return {
+    text: config.slice(0, at) + "\n  base: './'," + config.slice(at),
+    summary: "use relative asset paths (base: './') so the game loads from MyVillage",
+  };
+}

package/src/utils/game-toolkit.js

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSync } from 'fs';
+import { join, dirname, extname } from 'path';
+import { fileURLToPath } from 'url';
+
+// The platform files every JS game ships (see src/assets/game-toolkit). They're
+// copied into a game at scaffold time, so without a refresh a game keeps the
+// toolkit it was created with forever — and platform behaviour that lives in
+// the toolkit (like reporting play time) never reaches it. `deploy` refreshes
+// them, so every deploy from the CLI or MVP Studio ships the current toolkit.
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TOOLKIT_FILES = [
+  {
+    target: 'src/myvillage-game.js',
+    source: join(HERE, '..', 'assets', 'game-toolkit', 'myvillage-game.js'),
+    // Only replace a file that is still ours; a hand-rolled bridge is left alone.
+    isOurs: (text) => text.startsWith('// MyVillage Game Bridge'),
+  },
+  {
+    target: 'src/myvillage-realtime.js',
+    source: join(HERE, '..', '..', 'vendor', 'realtime', 'myvillage-realtime-client.js'),
+    isOurs: (text) => text.startsWith('// myvillage-realtime client'),
+    // The bridge imports it lazily, so it must exist next to the bridge for the
+    // build to resolve, even in games scaffolded before multiplayer existed.
+    createIfMissing: true,
+  },
+];
+
+/**
+ * Bring a game's platform files up to the toolkit bundled with this CLI.
+ * Returns the paths it changed (or, with `dryRun`, would change). Does nothing
+ * for a game without our bridge.
+ */
+export function refreshGameToolkit(projectDir, { dryRun = false } = {}) {
+  const bridge = join(projectDir, 'src/myvillage-game.js');
+  if (!existsSync(bridge) || !TOOLKIT_FILES[0].isOurs(readFileSync(bridge, 'utf8'))) return [];
+
+  const changed = [];
+  for (const file of TOOLKIT_FILES) {
+    const target = join(projectDir, file.target);
+    const latest = readFileSync(file.source, 'utf8');
+    if (existsSync(target)) {
+      const current = readFileSync(target, 'utf8');
+      if (current === latest || !file.isOurs(current)) continue;
+    } else if (!file.createIfMissing) {
+      continue;
+    }
+    if (!dryRun) writeFileSync(target, latest);
+    changed.push(file.target);
+  }
+  return changed;
+}
+
+/**
+ * Add the toolkit to a game that doesn't have it yet (`init-game`). Never
+ * replaces a file of the same name that isn't ours; those come back in
+ * `conflicts` so the caller can say so.
+ */
+export function installGameToolkit(projectDir, { dryRun = false } = {}) {
+  const changed = [];
+  const conflicts = [];
+  for (const file of TOOLKIT_FILES) {
+    const target = join(projectDir, file.target);
+    if (existsSync(target)) {
+      if (!file.isOurs(readFileSync(target, 'utf8'))) conflicts.push(file.target);
+      continue;
+    }
+    if (!dryRun) {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, readFileSync(file.source, 'utf8'));
+    }
+    changed.push(file.target);
+  }
+  // A bridge that was already there may be an older copy of ours.
+  if (!conflicts.includes(TOOLKIT_FILES[0].target)) {
+    changed.push(...refreshGameToolkit(projectDir, { dryRun }).filter((p) => !changed.includes(p)));
+  }
+  return { changed, conflicts };
+}
+
+/**
+ * Whether the game's own code (not the toolkit) ever calls complete(). A game
+ * that never does can't record a finished game or pay its reward.
+ */
+export function gameCallsComplete(projectDir) {
+  const src = join(projectDir, 'src');
+  if (!existsSync(src)) return true; // not a toolkit game; nothing to judge
+  const toolkit = new Set(TOOLKIT_FILES.map((f) => join(projectDir, f.target)));
+  const stack = [src];
+  while (stack.length) {
+    const dir = stack.pop();
+    for (const name of readdirSync(dir)) {
+      const path = join(dir, name);
+      if (statSync(path).isDirectory()) {
+        stack.push(path);
+      } else if (['.js', '.mjs', '.ts', '.jsx', '.tsx'].includes(extname(name)) && !toolkit.has(path)) {
+        if (/MyVillageGame\s*\.\s*complete\s*\(/.test(readFileSync(path, 'utf8'))) return true;
+      }
+    }
+  }
+  return false;
+}

package/src/utils/templates.js

@@ -700,20 +700,7 @@ function createNarrativeProject(targetDir, options) {
 function createArenaProject(targetDir, options) {
   const { name, description, ageGroup, orientation = 'landscape' } = options;
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
-  const src = join(ASSETS_DIR, 'templates', 'arena');
-  const vars = {
-    NAME: name,
-    SLUG: slug,
-    DESCRIPTION: description || 'A real-time multiplayer arena game.',
-    ORIENTATION: orientation,
-    GOLD: BRAND.gold,
-    DARK: BRAND.darkBrown,
-    CONTAINER_CSS: orientation === 'portrait'
-      ? `#game-container { position: relative; width: 100vw; height: 100vh; height: 100dvh; overflow: hidden; }
-    @media (min-aspect-ratio: 3/4) { #game-container { width: min(100vw, calc(100dvh * 9 / 16)); margin: 0 auto; } }`
-      : '#game-container { position: relative; width: 100%; height: 100%; overflow: hidden; }',
-  };
-  const fill = (file) => readFileSync(join(src, file), 'utf8').replace(/\{\{([A-Z_]+)\}\}/g, (m, k) => (k in vars ? vars[k] : m));
+  const fill = arenaTemplateFiller(name, slug, description, orientation);
 
   for (const dir of ['', 'src', 'assets', 'public']) {
     mkdirSync(join(targetDir, dir), { recursive: true });
@@ -731,6 +718,24 @@ function createArenaProject(targetDir, options) {
   copyTemplateArt(targetDir, 'arena', orientation);
 }
 
+// Reads one arena template file with its {{VARS}} filled in.
+function arenaTemplateFiller(name, slug, description, orientation) {
+  const src = join(ASSETS_DIR, 'templates', 'arena');
+  const vars = {
+    NAME: name,
+    SLUG: slug,
+    DESCRIPTION: description || 'A real-time multiplayer arena game.',
+    ORIENTATION: orientation,
+    GOLD: BRAND.gold,
+    DARK: BRAND.darkBrown,
+    CONTAINER_CSS: orientation === 'portrait'
+      ? `#game-container { position: relative; width: 100vw; height: 100vh; height: 100dvh; overflow: hidden; }
+    @media (min-aspect-ratio: 3/4) { #game-container { width: min(100vw, calc(100dvh * 9 / 16)); margin: 0 auto; } }`
+      : '#game-container { position: relative; width: 100%; height: 100%; overflow: hidden; }',
+  };
+  return (file) => readFileSync(join(src, file), 'utf8').replace(/\{\{([A-Z_]+)\}\}/g, (m, k) => (k in vars ? vars[k] : m));
+}
+
 function generateArenaPackageJson(name, description, slug, ageGroup, orientation) {
   const pkg = JSON.parse(generatePackageJson(name, description || 'A real-time multiplayer arena game.', slug, 'arena', ageGroup, orientation));
   pkg.myvillage.category = 'action';
@@ -1129,7 +1134,8 @@ function generate2DGameAgents(name, gameType, orientation) {
     'The game talks to its host through `src/myvillage-game.js`:',
     '',
     '- `MyVillageGame.ready()` — called on load. Leave it.',
-    '- `MyVillageGame.complete({ score, won })` — **required.** Called when the game ends (in `' + endFn + '`). It is how the host records the session and awards the player\'s reward. If you change the end flow, keep this call wired to the real end condition.',
+    '- `MyVillageGame.complete({ score, won })` — **required.** Called when the game ends (in `' + endFn + '`). It records a completion and awards the player\'s reward. If you change the end flow, keep it wired to **every** way the game can end (win, lose, out of time).',
+    '- **Plays count automatically.** `src/myvillage-game.js` reports how long the player is actively playing; the platform counts a play after 30 seconds of it. Do not add timers, fake input, or early `complete()` calls to make plays count.',
     '',
     'Do **not** add an Exit button — the host always provides its own.',
     '',
@@ -1153,7 +1159,7 @@ function generate2DGameAgents(name, gameType, orientation) {
     '',
     '## Conventions',
     '',
-    '- Orientation is **' + orientation + '** (set in `package.json` -> `myvillage.orientation`). Portrait runs on muni mobile **and** web; landscape is web-only.',
+    '- Orientation is **' + orientation + '** (set in `package.json` -> `myvillage.orientation`). Both play in the muni mobile app (it turns the phone to match) and on the web.',
     '- Vanilla JS, no framework — keep it dependency-light.',
     '',
   ].join('\n');
@@ -1224,7 +1230,8 @@ function generate3DGameAgents(name, type, orientation) {
     '## The MyVillage game contract — DO NOT BREAK',
     '',
     '- `MyVillageGame.ready()` — called after assets load in `src/main.js`. Leave it.',
-    '- `this.game.endGame({ won, score })` — call at your win/lose condition. It calls `MyVillageGame.complete(...)`, which is **required**: the host records the session and awards the player\'s reward.',
+    '- `this.game.endGame({ won, score })` — call at **every** win/lose condition. It calls `MyVillageGame.complete(...)`, which is **required**: it records a completion and awards the player\'s reward. An exploration game needs a real end (everything found, the exit reached) that calls it.',
+    '- **Plays count automatically.** `src/myvillage-game.js` reports how long the player is actively playing; the platform counts a play after 30 seconds of it. Do not add timers, fake input, or early `complete()` calls to make plays count.',
     '',
     'Do **not** add an Exit button — the host always provides its own. During `npm run dev` there is no host, so host calls just log to the console (expected).',
     '',
@@ -1246,12 +1253,108 @@ function generate3DGameAgents(name, type, orientation) {
     '',
     '## Conventions',
     '',
-    '- Orientation is **' + orientation + '** (`package.json` -> `myvillage.orientation`). Portrait runs on muni mobile **and** web; landscape is web-only.',
+    '- Orientation is **' + orientation + '** (`package.json` -> `myvillage.orientation`). Both play in the muni mobile app (it turns the phone to match) and on the web.',
     '- The follow-camera and game loop already exist — extend them, do not rebuild.',
     '',
   ].join('\n');
 }
 
+// For a web game that started outside MyVillage and was brought in with
+// `myvillage init-game`. We don't know its files, so instead of a file map it
+// says how to connect any game to the host.
+function generateConvertedGameAgents(name, orientation) {
+  const banner = orientation === 'portrait'
+    ? '9:16 (e.g. 1080x1920) for this portrait game'
+    : '16:9 (e.g. 1920x1080) for this landscape game';
+  return [
+    '# AGENTS.md — working on this MyVillage game with an AI agent',
+    '',
+    '**' + name + '** is a web game that was brought into MyVillage. It is built with `npm run build` and runs inside the MyVillage host (the muni mobile app or the web player) and standalone in a browser.',
+    '',
+    'When editing: make the requested change, keep the **MyVillage game contract** intact (see below), and keep `npm run build` working.',
+    '',
+    '## Platform files',
+    '',
+    '| File | Purpose |',
+    '|------|---------|',
+    '| `src/myvillage-game.js` | Host bridge — **do not edit.** Import it from the game\'s code: `import { MyVillageGame } from \'./myvillage-game.js\'` (path relative to the importing file). |',
+    '| `src/myvillage-realtime.js` | Multiplayer netcode (unused unless the game calls `MyVillageGame.multiplayer()`) — **do not edit.** |',
+    '| `assets/` | Cover art shipped on deploy. |',
+    '| `package.json` | The `myvillage` block holds metadata `myvillage deploy` reads. |',
+    '',
+    'Everything else is the game\'s own code. Read it before changing it, and keep its structure.',
+    '',
+    '## The MyVillage game contract — DO NOT BREAK',
+    '',
+    '- `MyVillageGame.ready()` — call once, when the game is interactive (after loading).',
+    '- `MyVillageGame.complete({ score, won })` — **required.** Call it on **every** way the game can end (win, lose, out of time, last level done). It records a completion and awards the player\'s reward. A game with no ending (endless, sandbox) needs a real one that fits it: a goal, a last level, a time limit.',
+    '- **Plays count automatically.** `src/myvillage-game.js` reports how long the player is actively playing; the platform counts a play after 30 seconds of it. Do not add timers, fake input, or early `complete()` calls to make plays count.',
+    '- Optional: `MyVillageGame.progress({ score })` reports the running score during play. It is throttled, so calling it every frame is fine.',
+    '',
+    'Do **not** add an Exit button — the host always provides its own. During `npm run dev` there is no host, so host calls just log to the console (expected).',
+    '',
+    '## Screen layout (phones)',
+    '',
+    '- The game fills the whole screen edge to edge, including behind the status bar and home indicator. The viewport meta needs `viewport-fit=cover`. Never letterbox it or add bars.',
+    '- Define the safe-area variables in `:root`: `--safe-top`, `--safe-bottom`, `--safe-left`, `--safe-right` as `max(env(safe-area-inset-*, 0px), var(--mv-safe-*, 0px))`, plus `--hud-top: calc(var(--safe-top) + 12px)` and `--exit-clear: 64px`. Keep HUD inside them: top row at `var(--hud-top)`, others offset by `var(--safe-bottom)` / `var(--safe-left)` / `var(--safe-right)`.',
+    '- Leave the **top-left corner** (`var(--exit-clear)` wide, below `var(--safe-top)`) empty: the host app draws its Exit button there. Put Pause and other top buttons on the right.',
+    '',
+    '## Run / build / deploy',
+    '',
+    '    npm install',
+    '    npm run dev      # local dev server, live reload',
+    '    npm run build    # production build -> dist/ (must pass before deploy)',
+    '    myvillage deploy # build, then upload + submit to MyVillage',
+    '',
+    'Keep asset URLs relative (Vite `base: \'./\'`). The host serves from a sub-path, so absolute `/...` URLs break.',
+    '',
+    '## Cover art (`assets/`)',
+    '',
+    '- `thumbnail.png` — square 1:1 (e.g. 512x512). The game card; required.',
+    '- `banner.png` — ' + banner + '. Featured hero; optional.',
+    '',
+    '## Conventions',
+    '',
+    '- Orientation is **' + orientation + '** (`package.json` -> `myvillage.orientation`). Both play in the muni mobile app (it turns the phone to match) and on the web.',
+    '- Don\'t add npm dependencies unless the change really needs one.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * The AGENTS.md this CLI would write for a JS game, from its package.json
+ * `myvillage` block. Lets `init-game` bring an older game's guide up to date.
+ */
+export function generateGameAgents(myvillage, { slug, description } = {}) {
+  const name = myvillage.name || slug || 'My Game';
+  const orientation = myvillage.orientation === 'portrait' ? 'portrait' : 'landscape';
+  if (myvillage.converted) return generateConvertedGameAgents(name, orientation);
+  const type = String(myvillage.gameType || 'custom');
+  if (type === 'quiz' || type === 'narrative') return generate2DGameAgents(name, type, orientation);
+  if (type === 'arena' || myvillage.multiplayer) {
+    const gameSlug = slug || name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+    return arenaTemplateFiller(name, gameSlug, description, orientation)('AGENTS.md');
+  }
+  return generate3DGameAgents(name, type, orientation);
+}
+
+/** Vite config for a converted game that had none: just the relative base. */
+export function generateMinimalViteConfig() {
+  return `import { defineConfig } from 'vite';
+
+// base: './' keeps asset URLs relative. MyVillage serves each game from its own
+// folder (/api/v1/games/game-files/<slug>/), so absolute /assets/... URLs break.
+export default defineConfig({
+  base: './',
+});
+`;
+}
+
+/** Bundled starter thumbnail (square) for a game that has no cover art yet. */
+export function starterThumbnailPath() {
+  return join(GAME_ART_DIR, 'custom-thumbnail.png');
+}
+
 function generateUnityAgents(name, className, orientation) {
   const isLandscape = orientation === 'landscape';
   const reach = isLandscape
@@ -1290,6 +1393,7 @@ function generateUnityAgents(name, className, orientation) {
     '',
     '- The host drives your mission and runs `OnBegin()`. In the editor, `MockMissionHost` stands in and logs host calls to the Console.',
     '- **`CompleteMission(finalScore: n)`** — call when the player finishes. This is the native equivalent of the web games\' `MyVillageGame.complete()`; the host records the session and awards the player\'s reward. **Required to end the game properly.**',
+    '- Plays count automatically: the host times how long the mission is on screen and the platform counts a play after 30 seconds. Call `CompleteMission` on every way the mission can end so finished games are recorded too.',
     '- `FailMission(reason)` — the lose path. `Host.LogEvent("...")` — telemetry.',
     '- **Do not build an Exit button** — the host always shows its own and calls `OnEnd()` for cleanup when the player exits.',
     '',
@@ -1737,8 +1841,8 @@ function generatePackageJson(name, description, slug, type, ageGroup, orientatio
       gameId: null,
       gameType: type,
       targetAge: ageGroup,
-      // Portrait games run in the muni mobile app AND on the web (mvp-video-games).
-      // Landscape games run on the web only. Hosts read this to frame the game.
+      // Both orientations run in the muni mobile app (it rotates to match) and on
+      // the web (mvp-video-games). Hosts read this to frame the game.
       orientation,
       aspectRatio: orientation === 'portrait' ? '9:16' : '16:9',
       // Declared up front so `myvillage deploy` ships them with the submission.
@@ -1886,7 +1990,12 @@ consistent experience:
 - **Done / finished** — call \`MyVillageGame.complete({ score })\` when the game is
   over. The host records the session and awards the player this game's MVT reward
   (set by an admin when the game is published). The scaffold already calls this
-  from \`Game.endGame()\` in \`src/main.js\` — wire that to your real end condition.
+  from \`Game.endGame()\` in \`src/main.js\` — wire that to **every** way the game
+  can end (win, lose, out of time).
+- **Plays count automatically** — \`src/myvillage-game.js\` measures how long the
+  player is actively playing and the platform counts a play after 30 seconds of
+  it. You don't need to do anything for that. To pass along a running score, call
+  \`MyVillageGame.progress({ score })\` (optional; safe to call every frame).
 - **Exit any time** — the host (the muni mobile app or the web player) always
   shows an Exit control, so a player can leave at any moment. You don't build an
   exit button. You *may* trigger \`MyVillageGame.exit()\` yourself (e.g. a "Quit"