@myvillage/cli 1.64.1 → 1.64.3

package/package.json

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

package/src/utils/templates.js

@@ -56,13 +56,17 @@ const BRAND = {
 export function createGameProject(targetDir, options) {
   const { name, description, type, ageGroup, orientation = 'landscape' } = options;
 
-  // A quiz is a 2D UI experience, not a 3D world — it gets a dedicated DOM/CSS
-  // scaffold (no Three.js, no renderer, no game loop) instead of the shared
-  // 3D shell the exploration/narrative/custom types use.
+  // Quiz and narrative are 2D UI experiences, not 3D worlds — they get dedicated
+  // DOM/CSS scaffolds (no Three.js, no renderer, no game loop) instead of the
+  // shared 3D shell the exploration/custom types use.
   if (type === 'quiz') {
     createQuizProject(targetDir, options);
     return;
   }
+  if (type === 'narrative') {
+    createNarrativeProject(targetDir, options);
+    return;
+  }
 
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
 
@@ -90,6 +94,7 @@ export function createGameProject(targetDir, options) {
   writeFileSync(join(targetDir, 'vite.config.js'), generateViteConfig());
   writeFileSync(join(targetDir, '.gitignore'), generateGitignore());
   writeFileSync(join(targetDir, 'README.md'), generateReadme(name, description, type, ageGroup));
+  writeFileSync(join(targetDir, 'AGENTS.md'), generate3DGameAgents(name, type, orientation));
   writeFileSync(join(targetDir, 'index.html'), generateIndexHtml(name, orientation));
   writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
   copyTemplateArt(targetDir, type, orientation);
@@ -102,17 +107,13 @@ export function createGameProject(targetDir, options) {
   writeFileSync(join(targetDir, 'src/utils/AudioManager.js'), generateAudioManager());
   writeFileSync(join(targetDir, 'src/components/UI.js'), generateUI(type));
 
-  // Write game-type-specific files
+  // Write the game-type-specific game logic. Quiz and narrative are handled
+  // earlier by their own 2D scaffolds, so only exploration and custom (default)
+  // reach this 3D path.
   switch (type) {
-    case 'quiz':
-      writeFileSync(join(targetDir, 'src/components/GameLogic.js'), generateQuizGameLogic());
-      break;
     case 'exploration':
       writeFileSync(join(targetDir, 'src/components/GameLogic.js'), generateExplorationGameLogic());
       break;
-    case 'narrative':
-      writeFileSync(join(targetDir, 'src/components/GameLogic.js'), generateNarrativeGameLogic());
-      break;
     default:
       writeFileSync(join(targetDir, 'src/components/GameLogic.js'), generateBaseGameLogic());
       break;
@@ -135,11 +136,12 @@ function createQuizProject(targetDir, options) {
     mkdirSync(join(targetDir, dir), { recursive: true });
   }
 
-  writeFileSync(join(targetDir, 'package.json'), generateQuizPackageJson(name, description, slug, ageGroup, orientation));
+  writeFileSync(join(targetDir, 'package.json'), generate2DGamePackageJson(name, description, slug, ageGroup, orientation, 'quiz'));
   writeFileSync(join(targetDir, 'vite.config.js'), generateViteConfig());
   writeFileSync(join(targetDir, '.gitignore'), generateGitignore());
-  writeFileSync(join(targetDir, 'index.html'), generateQuizIndexHtml(name, orientation));
+  writeFileSync(join(targetDir, 'index.html'), generate2DGameIndexHtml(name, orientation));
   writeFileSync(join(targetDir, 'README.md'), generateQuizReadme(name, description, ageGroup));
+  writeFileSync(join(targetDir, 'AGENTS.md'), generate2DGameAgents(name, 'quiz', orientation));
 
   writeFileSync(join(targetDir, 'src/main.js'), generateQuizApp());
   writeFileSync(join(targetDir, 'src/questions.js'), generateQuizQuestions(name));
@@ -150,7 +152,9 @@ function createQuizProject(targetDir, options) {
   copyTemplateArt(targetDir, 'quiz', orientation);
 }
 
-function generateQuizPackageJson(name, description, slug, ageGroup, orientation) {
+// Shared by the 2D game types (quiz, narrative) — a plain Vite project with no
+// Three.js. `gameType` goes into the myvillage block the deploy command reads.
+function generate2DGamePackageJson(name, description, slug, ageGroup, orientation, gameType) {
   return JSON.stringify({
     name: slug,
     version: '1.0.0',
@@ -162,14 +166,14 @@ function generateQuizPackageJson(name, description, slug, ageGroup, orientation)
       build: 'vite build',
       preview: 'vite preview',
     },
-    // No Three.js — a quiz is pure DOM/CSS.
+    // No Three.js — these are pure DOM/CSS games.
     devDependencies: {
       vite: '^5.0.0',
     },
     myvillage: {
       name: name,
       gameId: null,
-      gameType: 'quiz',
+      gameType,
       targetAge: ageGroup,
       orientation,
       aspectRatio: orientation === 'portrait' ? '9:16' : '16:9',
@@ -183,7 +187,8 @@ function generateQuizPackageJson(name, description, slug, ageGroup, orientation)
   }, null, 2) + '\n';
 }
 
-function generateQuizIndexHtml(name, orientation) {
+// Shared by the 2D game types — links styles.css + main.js into a #app root.
+function generate2DGameIndexHtml(name, orientation) {
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -593,6 +598,595 @@ myvillage deploy
 `;
 }
 
+// ── Narrative Game Project (2D) ────────────────────────────────────
+// A story game is text + choices, so this scaffold is plain DOM/CSS — no
+// Three.js. Devs edit src/story.js (the branching scenes) and src/styles.css
+// (the look). src/main.js runs the story and reports the result through the
+// shared MyVillage game contract.
+function createNarrativeProject(targetDir, options) {
+  const { name, description, ageGroup, orientation = 'portrait' } = options;
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+
+  const dirs = ['', 'src', 'assets', 'public'];
+  for (const dir of dirs) {
+    mkdirSync(join(targetDir, dir), { recursive: true });
+  }
+
+  writeFileSync(join(targetDir, 'package.json'), generate2DGamePackageJson(name, description, slug, ageGroup, orientation, 'narrative'));
+  writeFileSync(join(targetDir, 'vite.config.js'), generateViteConfig());
+  writeFileSync(join(targetDir, '.gitignore'), generateGitignore());
+  writeFileSync(join(targetDir, 'index.html'), generate2DGameIndexHtml(name, orientation));
+  writeFileSync(join(targetDir, 'README.md'), generateNarrativeReadme(name, description, ageGroup));
+  writeFileSync(join(targetDir, 'AGENTS.md'), generate2DGameAgents(name, 'narrative', orientation));
+
+  writeFileSync(join(targetDir, 'src/main.js'), generateNarrativeApp());
+  writeFileSync(join(targetDir, 'src/story.js'), generateNarrativeStory(name));
+  writeFileSync(join(targetDir, 'src/styles.css'), generateNarrativeStyles());
+  writeFileSync(join(targetDir, 'src/myvillage-game.js'), generateMyVillageGameSdk());
+
+  writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
+  copyTemplateArt(targetDir, 'narrative', orientation);
+}
+
+function generateNarrativeApp() {
+  return `// Narrative Game — an interactive, choice-driven story.
+//
+// Edit your story in src/story.js (scenes, speakers, choices) and the look in
+// src/styles.css. This file runs the story: it shows the start screen, each
+// scene with its choices, branches on what the player picks, and an ending —
+// then reports the result to the MyVillage host.
+
+import { MyVillageGame } from './myvillage-game.js';
+import { storyConfig, scenes } from './story.js';
+
+class NarrativeGame {
+  constructor(root) {
+    this.root = root;
+    this.index = 0;
+    this.choicesMade = 0;
+
+    this.renderStart();
+
+    // Tell the MyVillage host the game is loaded and interactive.
+    MyVillageGame.ready();
+  }
+
+  renderStart() {
+    this.root.innerHTML = \`
+      <main class="screen">
+        <div class="card start-card">
+          <h1 class="title">\${storyConfig.title}</h1>
+          <p class="intro">\${storyConfig.intro}</p>
+          <button class="btn primary" id="begin-btn">Begin</button>
+        </div>
+      </main>
+    \`;
+    this.root.querySelector('#begin-btn').addEventListener('click', () => this.begin());
+  }
+
+  begin() {
+    this.index = storyConfig.startScene || 0;
+    this.choicesMade = 0;
+    this.renderScene();
+  }
+
+  renderScene() {
+    const scene = scenes[this.index];
+    if (!scene) {
+      this.renderEnding();
+      return;
+    }
+
+    const hasChoices = Array.isArray(scene.choices) && scene.choices.length > 0;
+    const buttons = hasChoices
+      ? scene.choices.map((c, i) => \`<button class="btn choice" data-index="\${i}">\${c.text}</button>\`).join('')
+      : \`<button class="btn primary" id="end-btn">The End</button>\`;
+
+    this.root.innerHTML = \`
+      <main class="screen">
+        <div class="card scene-card">
+          \${scene.speaker ? \`<p class="speaker">\${scene.speaker}</p>\` : ''}
+          <p class="scene-text">\${scene.text}</p>
+          <div class="choices">\${buttons}</div>
+        </div>
+      </main>
+    \`;
+
+    if (hasChoices) {
+      this.root.querySelectorAll('.choice').forEach((btn) => {
+        btn.addEventListener('click', () => this.choose(Number(btn.dataset.index)));
+      });
+    } else {
+      this.root.querySelector('#end-btn').addEventListener('click', () => this.renderEnding());
+    }
+  }
+
+  choose(choiceIndex) {
+    const scene = scenes[this.index];
+    const choice = scene.choices[choiceIndex];
+    this.choicesMade++;
+    // Jump to the linked scene. An undefined / out-of-range next ends the story.
+    this.index = choice && choice.next !== undefined ? choice.next : -1;
+    this.renderScene();
+  }
+
+  renderEnding() {
+    this.root.innerHTML = \`
+      <main class="screen">
+        <div class="card results-card">
+          <h2 class="title">The End</h2>
+          <p class="intro">You made \${this.choicesMade} choice\${this.choicesMade === 1 ? '' : 's'} along the way.</p>
+          <button class="btn primary" id="again-btn">Play Again</button>
+        </div>
+      </main>
+    \`;
+    this.root.querySelector('#again-btn').addEventListener('click', () => this.begin());
+
+    // REQUIRED: tell the MyVillage host the story is finished. The host records
+    // the session, awards this game's MVT reward, and returns the player to the
+    // catalog. During \`npm run dev\` there's no host, so this just logs.
+    MyVillageGame.complete({ won: true, score: this.choicesMade, custom: { choices: this.choicesMade } });
+  }
+}
+
+new NarrativeGame(document.getElementById('app'));
+`;
+}
+
+function generateNarrativeStory(name) {
+  return `// Story content — edit this file to write your own branching narrative.
+//
+// Each scene has an optional \`speaker\`, the \`text\` to show, and \`choices\`.
+// Each choice has \`text\` and \`next\`: the index of the scene to jump to.
+// Set \`choices: null\` (or omit it) to mark a scene as the end of the story.
+
+export const storyConfig = {
+  // Shown on the start screen.
+  title: ${JSON.stringify(name)},
+  intro: 'An interactive story — your choices shape what happens next.',
+  // Index of the scene the story opens on.
+  startScene: 0,
+};
+
+export const scenes = [
+  {
+    speaker: 'Narrator',
+    text: 'You find yourself at the entrance to a mysterious village. The golden gates shine in the sunlight.',
+    choices: [
+      { text: 'Enter the village', next: 1 },
+      { text: 'Look around first', next: 2 },
+    ],
+  },
+  {
+    speaker: 'Village Elder',
+    text: 'Welcome, young traveler! We have been expecting you. Our village needs your help.',
+    choices: [
+      { text: 'How can I help?', next: 3 },
+      { text: 'What happened here?', next: 3 },
+    ],
+  },
+  {
+    speaker: 'Narrator',
+    text: 'You notice a weathered signpost and colorful flowers lining a cobblestone path. The village looks peaceful, but there is an air of anticipation.',
+    choices: [
+      { text: 'Follow the path inside', next: 1 },
+    ],
+  },
+  {
+    speaker: 'Village Elder',
+    text: 'A great challenge lies ahead. Only someone with courage and wisdom can solve it. Will you accept the quest?',
+    choices: [
+      { text: 'I accept!', next: 4 },
+      { text: 'Tell me more first', next: 4 },
+    ],
+  },
+  {
+    speaker: 'Narrator',
+    text: 'And so your adventure begins. This is where your story continues — edit src/story.js to write your own!',
+    choices: null, // null (or omitted) = the end of the story
+  },
+];
+`;
+}
+
+function generateNarrativeStyles() {
+  return `/* Narrative styling — tweak freely. Colors use the MyVillage palette. */
+
+:root {
+  --gold: #FFD700;
+  --primary: #B07C00;
+  --cream: #E4DCCB;
+  --dark: #302017;
+  --deep-green: #043922;
+  --green: #228B22;
+  --teal: #799C9F;
+}
+
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+html, body {
+  height: 100%;
+  font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+}
+
+body {
+  background: linear-gradient(160deg, var(--deep-green), var(--dark));
+  color: var(--cream);
+  display: flex;
+  -webkit-font-smoothing: antialiased;
+}
+
+#app { flex: 1; display: flex; }
+
+.screen {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  padding: 24px;
+  width: 100%;
+}
+
+.card {
+  width: 100%;
+  max-width: 540px;
+  background: rgba(48, 32, 23, 0.92);
+  border: 2px solid var(--primary);
+  border-radius: 20px;
+  padding: 28px 24px;
+  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.35);
+}
+
+.start-card, .results-card { text-align: center; }
+.scene-card { text-align: left; }
+
+.title { color: var(--gold); font-size: 30px; margin-bottom: 12px; }
+.intro { font-size: 16px; line-height: 1.5; margin-bottom: 24px; }
+
+.speaker {
+  color: var(--gold);
+  font-weight: 700;
+  font-size: 13px;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  margin-bottom: 10px;
+}
+
+.scene-text {
+  font-size: 18px;
+  line-height: 1.6;
+  margin-bottom: 24px;
+  color: var(--cream);
+}
+
+.choices { display: flex; flex-direction: column; gap: 12px; }
+
+.btn {
+  font-family: inherit;
+  font-size: 16px;
+  font-weight: 600;
+  border-radius: 12px;
+  border: none;
+  cursor: pointer;
+  min-height: 52px;
+  padding: 14px 18px;
+  transition: transform 0.05s ease, background 0.2s ease, border-color 0.2s ease;
+}
+
+.btn:active { transform: scale(0.98); }
+
+.btn.primary { background: var(--primary); color: #fff; width: 100%; font-size: 18px; }
+.btn.primary:hover { background: #c98f0a; }
+
+.choice {
+  background: var(--deep-green);
+  color: var(--cream);
+  border: 2px solid var(--green);
+  text-align: left;
+  width: 100%;
+}
+
+.choice:hover { border-color: var(--gold); }
+`;
+}
+
+function generateNarrativeReadme(name, description, ageGroup) {
+  return `# ${name}
+
+${description}
+
+- **Game Type**: Narrative
+- **Target Age Group**: ${ageGroup}
+- **Built with**: MyVillageOS CLI
+
+An interactive, choice-driven story — no 3D engine. Edit two files to make it yours:
+
+- **src/story.js** — your scenes, speakers, and branching choices
+- **src/styles.css** — colors, fonts, and layout
+
+## Getting Started
+
+\`\`\`bash
+npm install
+npm run dev      # play it locally with live reload
+npm run build    # build for production (outputs to dist/)
+\`\`\`
+
+## Writing your story
+
+Open \`src/story.js\`. Each scene has an optional \`speaker\`, the \`text\` to show,
+and \`choices\`. Each choice has \`text\` and \`next\` — the index of the scene to
+jump to. Branch the story by pointing choices at different scenes:
+
+\`\`\`js
+{
+  speaker: 'Village Elder',
+  text: 'Will you accept the quest?',
+  choices: [
+    { text: 'I accept!', next: 4 },
+    { text: 'Not yet', next: 2 },
+  ],
+}
+\`\`\`
+
+Set \`choices: null\` (or omit it) to make a scene the end of the story.
+
+## The game contract
+
+When the story ends it calls \`MyVillageGame.complete({ won, score })\`, so the
+MyVillage host records the session and awards the player this game's MVT reward.
+\`MyVillageGame.ready()\` is called on load. During \`npm run dev\` there's no host
+attached, so these just log to the console — that's expected.
+
+## Deploying
+
+Starter cover art ships in \`assets/\` — swap in your own thumbnail.png + banner.png, then:
+
+\`\`\`bash
+myvillage deploy
+\`\`\`
+
+## Learn More
+
+- [Vite Documentation](https://vitejs.dev/)
+- [MyVillageOS Developer Guide](https://portal.myvillageproject.ai)
+`;
+}
+
+// ── AGENTS.md generators ───────────────────────────────────────────
+// Each scaffold ships an AGENTS.md — a guide written for AI coding agents
+// (Claude Code, Cursor, Codex, etc. read it automatically). It points the agent
+// at the right files, documents the available APIs + the MyVillage game
+// contract, and flags what must not break. Built as string arrays (not template
+// literals) so the heavy inline-code backticks need no escaping.
+
+function generate2DGameAgents(name, gameType, orientation) {
+  const isQuiz = gameType === 'quiz';
+  const kind = isQuiz ? 'quiz' : 'narrative';
+  const engine = isQuiz ? 'QuizGame' : 'NarrativeGame';
+  const contentFile = isQuiz ? 'src/questions.js' : 'src/story.js';
+  const endFn = isQuiz ? 'renderResults()' : 'renderEnding()';
+  const banner = orientation === 'portrait'
+    ? '9:16 (e.g. 1080x1920) for this portrait game'
+    : '16:9 (e.g. 1920x1080) for this landscape game';
+  const contentLine = isQuiz
+    ? '**Content — edit `src/questions.js` first.** It exports `quizConfig` (title, intro, `passThreshold`, `showFeedback`) and a `questions` array. Each question is `{ question, choices, correct }`, where `correct` is the 0-based index of the right choice.'
+    : '**Content — edit `src/story.js` first.** It exports `storyConfig` (title, intro, `startScene`) and a `scenes` array. Each scene is `{ speaker, text, choices }`; each choice is `{ text, next }`, where `next` is the index of the next scene. Set `choices: null` to end the story. Branch by pointing choices at different scenes.';
+  const flowLine = isQuiz
+    ? '**Flow & rules — `src/main.js`.** The `QuizGame` class renders each screen (start -> question -> results) and wires the buttons. Edit here for scoring, timing, or new screens.'
+    : '**Flow — `src/main.js`.** The `NarrativeGame` class renders each screen (start -> scene -> ending), follows each choice\'s `next`, and wires the buttons.';
+
+  return [
+    '# AGENTS.md — working on this MyVillage game with an AI agent',
+    '',
+    '**' + name + '** is a MyVillage ' + kind + ' game — a 2D web game (plain DOM + CSS, no 3D engine, no Three.js) built with Vite. It 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.',
+    '',
+    '## Where common changes go',
+    '',
+    '- ' + contentLine,
+    '- **Look & feel — `src/styles.css`.** Colors are CSS variables in `:root` (the MyVillage palette). Cards, buttons, layout, fonts.',
+    '- ' + flowLine,
+    '',
+    '## File map',
+    '',
+    '| File | Purpose |',
+    '|------|---------|',
+    '| `index.html` | Entry point; mounts `#app`, loads `main.js` + `styles.css`. |',
+    '| `src/main.js` | The `' + engine + '` engine — lifecycle + rendering. |',
+    '| `' + contentFile + '` | **The content** — edit this first for content changes. |',
+    '| `src/styles.css` | Styling (CSS variables in `:root`). |',
+    '| `src/myvillage-game.js` | Host bridge — **do not edit.** |',
+    '| `assets/` | Cover art shipped on deploy. |',
+    '| `package.json` | The `myvillage` block holds metadata `myvillage deploy` reads. |',
+    '',
+    '## The MyVillage game contract — DO NOT BREAK',
+    '',
+    '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.',
+    '',
+    'Do **not** add an Exit button — the host always provides its own.',
+    '',
+    'During `npm run dev` there is no host attached, so `ready()`/`complete()` just log to the console. That is expected — do not try to "fix" it.',
+    '',
+    '## 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 the game from a sub-path, so absolute `/...` URLs will break.',
+    '',
+    '## Cover art (`assets/`)',
+    '',
+    'Starter art ships here — replace with your own, keeping the same filenames and sizes:',
+    '',
+    '- `thumbnail.png` — square 1:1 (e.g. 512x512). The game card; required.',
+    '- `banner.png` — ' + banner + '. Featured hero; optional.',
+    '',
+    '## Conventions',
+    '',
+    '- Orientation is **' + orientation + '** (set in `package.json` -> `myvillage.orientation`). Portrait runs on muni mobile **and** web; landscape is web-only.',
+    '- Vanilla JS, no framework — keep it dependency-light.',
+    '',
+  ].join('\n');
+}
+
+function generate3DGameAgents(name, type, orientation) {
+  const isExploration = type === 'exploration';
+  const banner = orientation === 'portrait'
+    ? '9:16 (e.g. 1080x1920) for this portrait game'
+    : '16:9 (e.g. 1920x1080) for this landscape game';
+  const logicLine = isExploration
+    ? 'Holds the gameplay — player movement (via `input.getMovementVector()`), collectible spawning + collision, the follow-camera, score, and win condition. It calls `input.enableJoystick()` in `start()` so mobile gets on-screen movement.'
+    : 'A blank starter — `update(delta)` is empty with hints. Build your mechanics here; the 3D scene, input, audio, UI, and game loop are already wired.';
+  const mobileLine = isExploration
+    ? 'This game already calls `this.game.input.enableJoystick()` in `GameLogic.start()`, so touch devices get an on-screen movement thumbstick (no-op on desktop). Read movement with `this.game.input.getMovementVector()`.'
+    : 'If your game uses movement, call `this.game.input.enableJoystick()` in `GameLogic.start()` to show an on-screen thumbstick on touch devices (no-op on desktop), then read it with `this.game.input.getMovementVector()`.';
+  const uiExtra = isExploration
+    ? ' This game also adds `showMinimap(pos, items)` and `showInventory(items)`.'
+    : '';
+
+  return [
+    '# AGENTS.md — working on this MyVillage game with an AI agent',
+    '',
+    '**' + name + '** is a MyVillage ' + (isExploration ? 'exploration' : 'custom') + ' game — a 3D web game built with **Three.js** and Vite. It 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.',
+    '',
+    '## Where common changes go',
+    '',
+    '- **Gameplay — `src/components/GameLogic.js`.** ' + logicLine,
+    '- **3D scene — `src/scenes/MainScene.js`.** Camera, lighting, ground, objects. The starter has a sky, a green ground plane, and a sample rotating cube (`this.sampleObject`). Add your meshes here.',
+    '- **On-screen UI — `src/components/UI.js`.** HTML overlay (start menu, HUD, pause menu, game-over) rendered over the 3D canvas.',
+    '- **Page/overlay styles are inline in `index.html`.**',
+    '',
+    '## File map',
+    '',
+    '| File | Purpose |',
+    '|------|---------|',
+    '| `src/main.js` | The `Game` class — Three.js renderer, state machine (`loading`/`menu`/`playing`/`paused`/`gameover`), the `animate()` loop, host wiring. |',
+    '| `src/scenes/MainScene.js` | The 3D scene (camera, lights, ground, objects). |',
+    '| `src/components/GameLogic.js` | **Your gameplay** — `start()`, `update(delta)`, `reset()`. |',
+    '| `src/components/UI.js` | HTML overlay (menus, HUD). |',
+    '| `src/utils/InputManager.js` | Keyboard / mouse / touch + mobile joystick. |',
+    '| `src/utils/AudioManager.js` | Sound effects + music (Web Audio). |',
+    '| `src/myvillage-game.js` | Host bridge — **do not edit.** |',
+    '| `assets/` | Cover art shipped on deploy. |',
+    '| `public/assets/` | Drop 3D models / textures / audio here. |',
+    '',
+    '## Engine API (reach it as `this.game` inside GameLogic)',
+    '',
+    '- `this.game.scene` — `.scene` (THREE.Scene), `.camera` (THREE.PerspectiveCamera), `.sampleObject`, `.update(delta)`.',
+    '- `this.game.input` — `getMovementVector()` (returns `{ x, z }` from WASD/arrows or the joystick), `isKeyDown(code)`, `isKeyJustPressed(code)`, `enableJoystick()`, `clearFrame()`, `mouse`, `touches`.',
+    '- `this.game.audio` — `playSFX(name)`, `playMusic(name)`, `stopMusic()`, `setMusicVolume(v)`, `setSFXVolume(v)`.',
+    '- `this.game.ui` — `showMenu()`, `showHUD()`, `showPauseMenu()`, `showGameOver(result)`, `clearOverlay()`, `createElement(tag, styles)`.' + uiExtra,
+    '- `this.game` — `startGame()`, `pauseGame()`, `resumeGame()`, `endGame(result)`, `state`.',
+    '',
+    '## Mobile controls',
+    '',
+    mobileLine,
+    '',
+    '## 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.',
+    '',
+    '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).',
+    '',
+    '## 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/`)',
+    '',
+    'Starter art ships here — replace with your own, same filenames and sizes:',
+    '',
+    '- `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`). Portrait runs on muni mobile **and** web; landscape is web-only.',
+    '- The follow-camera and game loop already exist — extend them, do not rebuild.',
+    '',
+  ].join('\n');
+}
+
+function generateUnityAgents(name, className, orientation) {
+  const isLandscape = orientation === 'landscape';
+  const reach = isLandscape
+    ? 'web (WebGL) only'
+    : 'the muni mobile app and the web';
+  const banner = isLandscape
+    ? '16:9 (e.g. 1920x1080) for this landscape game'
+    : '9:16 (e.g. 1080x1920) for this portrait game';
+
+  return [
+    '# AGENTS.md — working on this MyVillage Unity game with an AI agent',
+    '',
+    '**' + name + '** is a MyVillage Unity game built on the **MyVillage GameKit SDK** (a UPM package pinned in `Packages/manifest.json`). The mission is C#; it builds to AssetBundles the M-UNI host loads.',
+    '',
+    'When editing: change the mission logic, keep the **game contract** intact (`CompleteMission` / `FailMission`), and do not break the GameKit `MissionBase` lifecycle.',
+    '',
+    '## Where common changes go',
+    '',
+    '- **Mission logic — `Assets/Scripts/' + className + '.cs`.** Your `MissionBase` subclass. Override `OnBegin()` with your gameplay and call `CompleteMission(finalScore: n)` (or `FailMission(reason)`) when the player finishes. `OnEnd()` is for cleanup.',
+    '- **Scene & objects — the Unity scene** (create via the editor menu `MyVillage -> Create Starter Mission Scene`). Add GameObjects, art, and audio in the Unity editor.',
+    '- **Orientation — `Assets/Editor/MyVillageOrientation.cs`** pins it on first load.',
+    '',
+    '## File map',
+    '',
+    '| Path | Purpose |',
+    '|------|---------|',
+    '| `Assets/Scripts/' + className + '.cs` | **Your mission** — the `MissionBase` subclass. Edit here. |',
+    '| `Assets/Editor/MyVillageOrientation.cs` | Pins player orientation on first load. |',
+    '| `Packages/manifest.json` | Depends on the GameKit SDK (pinned version). Do not hand-edit the SDK. |',
+    '| `myvillage.json` | Game metadata the CLI/deploy reads (slug, gameType, orientation, assets). |',
+    '| `assets/` | Cover art shipped on deploy (thumbnail/banner). |',
+    '| `builds/{ios,android,webgl}/` | Drop-zone for built AssetBundles the CLI deploys. |',
+    '',
+    '## The game contract (GameKit `MissionBase`) — DO NOT BREAK',
+    '',
+    '- 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.**',
+    '- `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.',
+    '',
+    'The same script runs unchanged in the real M-UNI host (a `MissionHostAdapter` replaces `MockMissionHost`). Do not add platform-specific host code.',
+    '',
+    '## Build & deploy',
+    '',
+    '1. In Unity: **`MyVillage -> Build All Platforms`** (ships in GameKit). Builds iOS, Android, and WebGL into `builds/`.',
+    '2. From the terminal: `myvillage deploy` (scans `builds/`, uploads, submits).',
+    '',
+    'This game\'s orientation is **' + orientation + '** — it runs on ' + reach + '.',
+    '',
+    '## Cover art (`assets/`)',
+    '',
+    'Starter art ships here — replace with your own, same filenames and sizes:',
+    '',
+    '- `thumbnail.png` — square 1:1 (e.g. 512x512). The game card; required.',
+    '- `banner.png` — ' + banner + '. Featured hero; optional.',
+    '',
+    '## Gotchas',
+    '',
+    '- Do not edit the GameKit SDK package — it is a pinned dependency. Use its `MissionBase` API.',
+    '- Visual Scripting reflection nodes (`InvokeMember`/`GetMember`/`SetMember`) are rejected by the deploy preflight. Write C# instead.',
+    '',
+  ].join('\n');
+}
+
 // ── Unity Game Project ─────────────────────────────────────────────
 
 export async function createUnityGameProject(targetDir, options) {
@@ -675,6 +1269,7 @@ export async function createUnityGameProject(targetDir, options) {
   copyTemplateArt(targetDir, type, orientation);
   writeFileSync(join(targetDir, '.gitignore'), generateUnityGitignore());
   writeFileSync(join(targetDir, 'README.md'), generateUnityReadme(name, slug, className, orientation, unityVersion));
+  writeFileSync(join(targetDir, 'AGENTS.md'), generateUnityAgents(name, className, orientation));
 
   return { unityVersion, sdkVersion: GAMEKIT_SDK_VERSION, gameType: primaryGameType };
 }
@@ -1833,52 +2428,6 @@ function generateUI(type) {
   let typeSpecificUI = '';
 
   switch (type) {
-    case 'quiz':
-      typeSpecificUI = `
-  showQuestion(question, choices, onAnswer) {
-    this.clearOverlay();
-
-    const panel = this.createElement('div', {
-      position: 'absolute', bottom: '20px', left: '50%', transform: 'translateX(-50%)',
-      width: '90%', maxWidth: '600px', background: 'rgba(48,32,23,0.95)',
-      borderRadius: '16px', padding: '24px', color: '#E4DCCB',
-    });
-
-    const qText = this.createElement('p', {
-      fontSize: '18px', fontWeight: 'bold', marginBottom: '16px',
-      color: '#FFD700', textAlign: 'center',
-    });
-    qText.textContent = question;
-    panel.appendChild(qText);
-
-    choices.forEach((choice, index) => {
-      const btn = this.createElement('button', {
-        display: 'block', width: '100%', padding: '12px',
-        margin: '8px 0', background: '#043922', color: '#E4DCCB',
-        border: '2px solid #228B22', borderRadius: '8px',
-        fontSize: '16px', cursor: 'pointer', textAlign: 'left',
-      });
-      btn.textContent = choice;
-      btn.addEventListener('click', () => onAnswer(index));
-      panel.appendChild(btn);
-    });
-
-    this.overlay.appendChild(panel);
-  }
-
-  showScore(score, total) {
-    this.clearOverlay();
-
-    const panel = this.createElement('div', {
-      position: 'absolute', top: '10px', right: '10px',
-      background: 'rgba(48,32,23,0.85)', borderRadius: '12px',
-      padding: '10px 18px', color: '#FFD700', fontSize: '18px', fontWeight: 'bold',
-    });
-    panel.textContent = \`Score: \${score} / \${total}\`;
-    this.overlay.appendChild(panel);
-  }`;
-      break;
-
     case 'exploration':
       typeSpecificUI = `
   showMinimap(playerPos, items) {
@@ -1941,57 +2490,6 @@ function generateUI(type) {
   }`;
       break;
 
-    case 'narrative':
-      typeSpecificUI = `
-  showDialogue(speaker, text, choices, onChoice) {
-    this.clearOverlay();
-
-    const panel = this.createElement('div', {
-      position: 'absolute', bottom: '0', left: '0', width: '100%',
-      background: 'rgba(48,32,23,0.95)', padding: '20px 24px',
-      borderTop: '3px solid #B07C00', color: '#E4DCCB',
-    });
-
-    if (speaker) {
-      const nameTag = this.createElement('span', {
-        color: '#FFD700', fontWeight: 'bold', fontSize: '16px',
-        marginBottom: '8px', display: 'block',
-      });
-      nameTag.textContent = speaker;
-      panel.appendChild(nameTag);
-    }
-
-    const textEl = this.createElement('p', {
-      fontSize: '15px', lineHeight: '1.5', marginBottom: choices ? '16px' : '0',
-    });
-    textEl.textContent = text;
-    panel.appendChild(textEl);
-
-    if (choices && choices.length > 0) {
-      choices.forEach((choice, index) => {
-        const btn = this.createElement('button', {
-          display: 'block', width: '100%', padding: '10px',
-          margin: '6px 0', background: 'transparent', color: '#FFD700',
-          border: '1px solid #B07C00', borderRadius: '8px',
-          fontSize: '14px', cursor: 'pointer', textAlign: 'left',
-        });
-        btn.textContent = \`> \${choice}\`;
-        btn.addEventListener('click', () => onChoice(index));
-        panel.appendChild(btn);
-      });
-    } else {
-      const hint = this.createElement('p', {
-        fontSize: '12px', color: '#799C9F', marginTop: '8px', textAlign: 'center',
-      });
-      hint.textContent = 'Click to continue...';
-      panel.appendChild(hint);
-      panel.addEventListener('click', () => onChoice(-1));
-    }
-
-    this.overlay.appendChild(panel);
-  }`;
-      break;
-
     default:
       typeSpecificUI = '';
   }
@@ -2162,89 +2660,6 @@ export class GameLogic {
 `;
 }
 
-function generateQuizGameLogic() {
-  return `// Quiz Game Logic
-// Manages questions, answers, scoring, and progress tracking.
-
-export class GameLogic {
-  constructor(game) {
-    this.game = game;
-    this.score = 0;
-    this.currentQuestion = 0;
-
-    // Define your quiz questions here
-    this.questions = [
-      {
-        question: 'What is 2 + 2?',
-        choices: ['3', '4', '5', '6'],
-        correct: 1,
-      },
-      {
-        question: 'What is the capital of France?',
-        choices: ['London', 'Berlin', 'Paris', 'Madrid'],
-        correct: 2,
-      },
-      {
-        question: 'Which planet is closest to the Sun?',
-        choices: ['Venus', 'Mercury', 'Earth', 'Mars'],
-        correct: 1,
-      },
-    ];
-  }
-
-  start() {
-    this.score = 0;
-    this.currentQuestion = 0;
-    this.showCurrentQuestion();
-  }
-
-  reset() {
-    this.score = 0;
-    this.currentQuestion = 0;
-  }
-
-  showCurrentQuestion() {
-    if (this.currentQuestion >= this.questions.length) {
-      // Quiz complete
-      this.game.endGame({
-        won: this.score > this.questions.length / 2,
-        score: this.score,
-      });
-      return;
-    }
-
-    const q = this.questions[this.currentQuestion];
-    this.game.ui.showQuestion(q.question, q.choices, (answerIndex) => {
-      this.handleAnswer(answerIndex);
-    });
-    this.game.ui.showScore(this.score, this.questions.length);
-  }
-
-  handleAnswer(answerIndex) {
-    const q = this.questions[this.currentQuestion];
-
-    if (answerIndex === q.correct) {
-      this.score++;
-      // Play celebration animation - rotate the sample object faster
-      if (this.game.scene.sampleObject) {
-        this.game.scene.sampleObject.scale.set(1.5, 1.5, 1.5);
-        setTimeout(() => {
-          this.game.scene.sampleObject.scale.set(1, 1, 1);
-        }, 500);
-      }
-    }
-
-    this.currentQuestion++;
-    this.showCurrentQuestion();
-  }
-
-  update(delta) {
-    // Quiz games are event-driven, so update is minimal
-  }
-}
-`;
-}
-
 function generateExplorationGameLogic() {
   return `// Exploration Game Logic
 // Manages character movement, collision detection, and collectible items.
@@ -2375,107 +2790,3 @@ export class GameLogic {
 }
 `;
 }
-
-function generateNarrativeGameLogic() {
-  return `// Narrative Game Logic
-// Manages dialogue, choices, scene transitions, and story branching.
-
-export class GameLogic {
-  constructor(game) {
-    this.game = game;
-    this.currentSceneIndex = 0;
-    this.score = 0;
-
-    // Define your story scenes here.
-    // Each scene has speaker, text, and optional choices.
-    // Choices have 'text' and 'next' (index of the next scene to go to).
-    this.storyScenes = [
-      {
-        speaker: 'Narrator',
-        text: 'You find yourself at the entrance to a mysterious village. The golden gates shine in the sunlight.',
-        choices: [
-          { text: 'Enter the village', next: 1 },
-          { text: 'Look around first', next: 2 },
-        ],
-      },
-      {
-        speaker: 'Village Elder',
-        text: 'Welcome, young traveler! We have been expecting you. Our village needs your help.',
-        choices: [
-          { text: 'How can I help?', next: 3 },
-          { text: 'What happened here?', next: 3 },
-        ],
-      },
-      {
-        speaker: 'Narrator',
-        text: 'You notice a weathered signpost and colorful flowers lining a cobblestone path. The village looks peaceful but there is an air of anticipation.',
-        choices: [
-          { text: 'Follow the path inside', next: 1 },
-        ],
-      },
-      {
-        speaker: 'Village Elder',
-        text: 'A great challenge lies ahead. Only someone with courage and wisdom can solve it. Will you accept the quest?',
-        choices: [
-          { text: 'I accept!', next: 4 },
-          { text: 'Tell me more about the quest', next: 4 },
-        ],
-      },
-      {
-        speaker: 'Narrator',
-        text: 'And so your adventure begins... This is where your story continues! Edit the storyScenes array in GameLogic.js to create your own narrative.',
-        choices: null, // null choices = end of story
-      },
-    ];
-  }
-
-  start() {
-    this.currentSceneIndex = 0;
-    this.score = 0;
-    this.showCurrentScene();
-  }
-
-  reset() {
-    this.currentSceneIndex = 0;
-    this.score = 0;
-  }
-
-  showCurrentScene() {
-    const scene = this.storyScenes[this.currentSceneIndex];
-    if (!scene) {
-      this.game.endGame({ won: true, score: this.score });
-      return;
-    }
-
-    const choiceTexts = scene.choices ? scene.choices.map((c) => c.text) : null;
-
-    this.game.ui.showDialogue(scene.speaker, scene.text, choiceTexts, (choiceIndex) => {
-      this.handleChoice(choiceIndex);
-    });
-  }
-
-  handleChoice(choiceIndex) {
-    const scene = this.storyScenes[this.currentSceneIndex];
-
-    if (!scene.choices || choiceIndex === -1) {
-      // End of story
-      this.game.endGame({ won: true, score: this.score });
-      return;
-    }
-
-    const choice = scene.choices[choiceIndex];
-    if (choice && choice.next !== undefined) {
-      this.currentSceneIndex = choice.next;
-      this.score++;
-      this.showCurrentScene();
-    } else {
-      this.game.endGame({ won: true, score: this.score });
-    }
-  }
-
-  update(delta) {
-    // Narrative games are event-driven via UI choices
-  }
-}
-`;
-}