@myvillage/cli 1.60.1 → 1.62.0

package/package.json

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

package/src/commands/agent-local.js

@@ -10,6 +10,7 @@ import { isAuthenticated, getAccessToken } from '../utils/auth.js';
 import { getConfig, setConfig } from '../utils/config.js';
 import {
   createAgent as apiCreateAgent,
+  deleteAgent as apiDeleteAgent,
   agentJoinCommunity as apiAgentJoinCommunity,
   listCommunities,
   getAgentActivity,
@@ -803,11 +804,16 @@ export async function agentDeleteLocalCommand(name) {
     return;
   }
 
+  const agentConfig = readAgentConfig(name);
+  const remoteAgentId = agentConfig?.man?.agent_id || null;
+
   try {
     const { confirm } = await inquirer.prompt([{
       type: 'confirm',
       name: 'confirm',
-      message: `Delete local agent "${name}"? This removes all local files and cannot be undone.`,
+      message: remoteAgentId
+        ? `Delete agent "${name}"? This removes all local files AND deletes the agent on the server. This cannot be undone.`
+        : `Delete local agent "${name}"? This removes all local files and cannot be undone.`,
       default: false,
     }]);
 
@@ -833,6 +839,27 @@ export async function agentDeleteLocalCommand(name) {
       }
     }
 
+    // Delete the remote AgentProfile first so a server failure stops us
+    // before we wipe local files. If the remote is already gone (404),
+    // proceed with local cleanup.
+    if (remoteAgentId) {
+      const remoteSpinner = villageSpinner('Deleting agent on server...').start();
+      try {
+        await apiDeleteAgent(remoteAgentId);
+        remoteSpinner.succeed('Agent deleted on server.');
+      } catch (err) {
+        const status = err.response?.status;
+        const message = err.response?.data?.error || err.response?.data?.message || err.message;
+        if (status === 404) {
+          remoteSpinner.warn('Agent already removed on server.');
+        } else {
+          remoteSpinner.fail(`Failed to delete agent on server: ${message}`);
+          console.log(brand.teal('  Local files were not removed. Re-run once the server issue is resolved.\n'));
+          return;
+        }
+      }
+    }
+
     // Delete directory
     const { rmSync } = await import('fs');
     const agentDir = getAgentDir(name);

package/src/commands/create-game.js

@@ -15,6 +15,21 @@ export async function createGameCommand(options = {}) {
     return;
   }
 
+  // Orientation first — it decides where the game can play.
+  //   Portrait  → muni mobile app + web (mvp-video-games)
+  //   Landscape → web only (mvp-video-games)
+  const { orientation } = await inquirer.prompt([
+    {
+      type: 'list',
+      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' },
+      ],
+    },
+  ]);
+
   // Engine choice
   const { engine } = await inquirer.prompt([
     {
@@ -22,14 +37,19 @@ export async function createGameCommand(options = {}) {
       name: 'engine',
       message: 'Which engine are you using?',
       choices: [
-        { name: 'Three.js — Web-based 3D game (runs in browser)', value: 'threejs' },
-        { name: 'Unity — Mobile or WebGL game (built in Unity Editor)', value: 'unity' },
+        { name: 'JS / Three.js — web build (runs in a browser / WebView)', value: 'threejs' },
+        {
+          name: orientation === 'landscape'
+            ? 'Unity — WebGL build (runs in browser)'
+            : 'Unity — native build for muni (can also build WebGL for web)',
+          value: 'unity',
+        },
       ],
     },
   ]);
 
   if (engine === 'unity') {
-    return createUnityGame(options);
+    return createUnityGame({ ...options, orientation });
   }
 
   // ── Three.js path (existing flow) ──
@@ -91,6 +111,7 @@ export async function createGameCommand(options = {}) {
       description: answers.description,
       type: answers.type,
       ageGroup: answers.ageGroup,
+      orientation,
     });
 
     spinner.text = 'Installing dependencies...';
@@ -112,7 +133,8 @@ export async function createGameCommand(options = {}) {
     console.log(`    ${brand.gold('npm run build')}    ${brand.teal('- Build for production')}`);
     console.log(`    ${brand.gold('myvillage deploy')} ${brand.teal('- Deploy to MyVillageOS')}`);
     console.log();
-    console.log(brand.teal(`  Game type: ${answers.type} | Age group: ${answers.ageGroup}`));
+    console.log(brand.teal(`  Game type: ${answers.type} | Orientation: ${orientation} | Age group: ${answers.ageGroup}`));
+    console.log(brand.teal(`  Cover art: drop thumbnail.png / banner.png in ${slug}/assets/ before deploy.`));
     console.log();
   } catch (err) {
     spinner.fail('Failed to create game project.');
@@ -123,6 +145,9 @@ export async function createGameCommand(options = {}) {
 // ── Unity path ──
 
 async function createUnityGame(options = {}) {
+  // orientation is decided in the top-level wizard; default portrait for Unity.
+  const orientation = options.orientation || 'portrait';
+
   const answers = await inquirer.prompt([
     {
       type: 'input',
@@ -152,15 +177,6 @@ async function createUnityGame(options = {}) {
         { name: 'Other', value: 'other' },
       ],
     },
-    {
-      type: 'list',
-      name: 'platform',
-      message: 'Target platform:',
-      choices: [
-        { name: 'Mobile (iOS / Android) — AssetBundle loaded by Izi Graham', value: 'mobile' },
-        { name: 'WebGL — Runs in browser on M-UNI', value: 'webgl' },
-      ],
-    },
     {
       type: 'list',
       name: 'ageGroup',
@@ -190,7 +206,7 @@ async function createUnityGame(options = {}) {
       description: answers.description,
       type: answers.category,
       ageGroup: answers.ageGroup,
-      platform: answers.platform,
+      orientation,
       unityVersion: options.unityVersion,
     });
 
@@ -200,6 +216,7 @@ async function createUnityGame(options = {}) {
     console.log(brand.green(`  \u2713 Unity game "${answers.name}" created!`));
     console.log(brand.teal(`     Unity: ${scaffold.unityVersion}`));
     console.log(brand.teal(`     GameKit SDK: ${scaffold.sdkVersion}`));
+    console.log(brand.teal(`     Orientation: ${orientation} (${orientation === 'landscape' ? 'web only' : 'muni mobile + web'})`));
     console.log();
     console.log(brand.teal('  Next steps:'));
     console.log();
@@ -209,14 +226,16 @@ async function createUnityGame(options = {}) {
     console.log(`    4. ${brand.teal('Edit')} ${brand.gold(`Assets/Scripts/${answers.name.replace(/[^a-zA-Z0-9]/g, '')}.cs`)} ${brand.teal('and iterate (hit Play again)')}`);
     console.log();
     console.log(brand.teal('  Ready to ship:'));
-    if (answers.platform === 'mobile') {
-      console.log(`    5. ${brand.teal('Build AssetBundle:')} ${brand.gold('MyVillage \u2192 Build Mission Bundle')}`);
-      console.log(`    6. ${brand.gold('cd ' + slug + ' && myvillage deploy --platform ios')} ${brand.teal('(or android)')}`);
-    } else {
+    if (orientation === 'landscape') {
       console.log(`    5. ${brand.teal('Build WebGL via')} ${brand.gold('File \u2192 Build Settings \u2192 WebGL \u2192 Build')} ${brand.teal('to')} ${brand.gold('builds/webgl/')}`);
       console.log(`    6. ${brand.gold('cd ' + slug + ' && myvillage deploy --platform webgl')}`);
+    } else {
+      console.log(`    5. ${brand.teal('Build AssetBundle:')} ${brand.gold('MyVillage \u2192 Build Mission Bundle')} ${brand.teal('(into builds/ios or builds/android)')}`);
+      console.log(`    6. ${brand.gold('cd ' + slug + ' && myvillage deploy')} ${brand.teal('\u2014 ships every platform found in builds/')}`);
+      console.log(`       ${brand.teal('Optional: also build WebGL into builds/webgl/ to offer it on the web too.')}`);
     }
     console.log();
+    console.log(brand.teal(`  Cover art: drop thumbnail.png / banner.png in ${slug}/assets/ before deploy.`));
     console.log(brand.teal(`  See ${slug}/README.md for the full developer guide.`));
     console.log();
   } catch (err) {

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 } from '../utils/api.js';
 import { preflightBundles } from '../utils/preflight.js';
+import { selectGameVillages } from '../utils/village-resolver.js';
 
 function readPackageJson(dir) {
   const pkgPath = join(dir, 'package.json');
@@ -48,6 +49,34 @@ function saveGameIdToMyVillageJson(dir, gameId, slug) {
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 }
 
+// Persist the village selection so re-deploys pre-check the same villages.
+function saveVillages(dir, isUnity, villageIds) {
+  if (!Array.isArray(villageIds)) return;
+  if (isUnity) {
+    const configPath = join(dir, 'myvillage.json');
+    if (!existsSync(configPath)) return;
+    const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+    config.villages = villageIds;
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  } else {
+    const pkgPath = join(dir, 'package.json');
+    if (!existsSync(pkgPath)) return;
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    pkg.myvillage = { ...pkg.myvillage, villages: villageIds };
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+  }
+}
+
+// Gather the submission's village visibility once per deploy. Returns an array
+// of village ids (possibly empty), or null if the developer aborted/failed —
+// the caller should stop the deploy in that case.
+async function gatherVillages(existingIds = []) {
+  console.log();
+  console.log(brand.teal('  Village visibility — who can see & play this game:'));
+  const villageIds = await selectGameVillages(existingIds);
+  return villageIds;
+}
+
 // Recursively collect file paths from a directory
 function collectFilePaths(dir) {
   const paths = [];
@@ -122,6 +151,11 @@ async function autoSubmitForReview(gameId, deployResult) {
 // ── Three.js deploy (existing flow) ──
 
 async function deployThreeJsGame(projectDir, pkg) {
+  // Village visibility is part of the submission — gather it up front (before
+  // the build) so it travels in the deploy metadata.
+  const villageIds = await gatherVillages(pkg.myvillage.villages || []);
+  if (villageIds === null) return; // could not resolve villages — abort
+
   const spinner = villageSpinner('Building game...').start();
 
   try {
@@ -155,7 +189,9 @@ async function deployThreeJsGame(projectDir, pkg) {
       category: (pkg.myvillage.gameType || 'OTHER').toUpperCase(),
       gameType: 'THREE_JS',
       targetAge: pkg.myvillage.targetAge || 'all',
+      orientation: pkg.myvillage.orientation || 'landscape',
       entryFile: 'index.html',
+      villageIds,
     };
     formData.append('metadata', JSON.stringify(metadata));
 
@@ -191,9 +227,11 @@ async function deployThreeJsGame(projectDir, pkg) {
     if (result.slug) console.log(brand.teal(`  Slug:    ${result.slug}`));
     if (result.gameId) console.log(brand.teal(`  Game ID: ${result.gameId}`));
 
-    // Prompt for thumbnail/banner images
+    saveVillages(projectDir, false, villageIds);
+
+    // Cover art is part of the submission: ship declared assets, require a thumbnail.
     if (finalGameId) {
-      await promptForImages(finalGameId);
+      await submitCoverArt(finalGameId, projectDir, pkg.myvillage);
     }
 
     console.log();
@@ -260,6 +298,11 @@ async function deployUnityGame(projectDir, mvConfig, options) {
   }
 
   console.log(brand.teal(`  Deploying ${platformsToDeploy.length} platform(s): ${platformsToDeploy.join(', ')}`));
+
+  // Village visibility is part of the submission — gather once for the whole
+  // multi-platform deploy and thread it into every platform's metadata.
+  const villageIds = await gatherVillages(mvConfig.villages || []);
+  if (villageIds === null) return; // could not resolve villages — abort
   console.log();
 
   // Track final outcome across all platforms.
@@ -269,7 +312,7 @@ async function deployUnityGame(projectDir, mvConfig, options) {
   let finalTitle = null;
 
   for (const platform of platformsToDeploy) {
-    const outcome = await deployUnityPlatform(projectDir, mvConfig, platform, { gameIdOverride: finalGameId });
+    const outcome = await deployUnityPlatform(projectDir, mvConfig, platform, { gameIdOverride: finalGameId, villageIds });
     if (!outcome.ok) return; // bail on first platform failure; nothing else makes sense to ship
     finalGameId = outcome.gameId || finalGameId;
     finalSlug = outcome.slug || finalSlug;
@@ -289,8 +332,11 @@ async function deployUnityGame(projectDir, mvConfig, options) {
   if (finalSlug) console.log(brand.teal(`  Slug:      ${finalSlug}`));
   if (finalGameId) console.log(brand.teal(`  Game ID:   ${finalGameId}`));
 
+  saveVillages(projectDir, true, villageIds);
+
+  // Cover art is part of the submission: ship declared assets, require a thumbnail.
   if (finalGameId) {
-    await promptForImages(finalGameId);
+    await submitCoverArt(finalGameId, projectDir, mvConfig);
   }
 
   console.log();
@@ -302,7 +348,7 @@ async function deployUnityGame(projectDir, mvConfig, options) {
  * Deploy one specific platform. Returns { ok, gameId, slug, status, title } or
  * { ok: false } and writes a user-readable error to the console.
  */
-async function deployUnityPlatform(projectDir, mvConfig, platform, { gameIdOverride }) {
+async function deployUnityPlatform(projectDir, mvConfig, platform, { gameIdOverride, villageIds }) {
   const buildDir = join(projectDir, 'builds', platform);
   const filePaths = collectFilePaths(buildDir);
 
@@ -352,10 +398,12 @@ async function deployUnityPlatform(projectDir, mvConfig, platform, { gameIdOverr
       category: (mvConfig.category || 'OTHER').toUpperCase(),
       gameType,
       targetAge: mvConfig.targetAge || 'all',
+      orientation: mvConfig.orientation || (platform === 'webgl' ? 'landscape' : 'portrait'),
       buildPlatform: platform,
     };
     if (mvConfig.sdkVersion) metadata.sdkVersion = mvConfig.sdkVersion;
     if (platform === 'webgl') metadata.entryFile = 'index.html';
+    if (Array.isArray(villageIds)) metadata.villageIds = villageIds;
 
     formData.append('metadata', JSON.stringify(metadata));
 
@@ -465,49 +513,108 @@ async function uploadImageAsset(gameId, filePath, assetType) {
   }
 }
 
-async function promptForImages(gameId) {
+// Read PNG pixel dimensions from the IHDR chunk. Returns {width,height} or null
+// for non-PNG / unreadable files (we only sanity-check PNGs, the scaffold default).
+function readPngSize(filePath) {
+  try {
+    const buf = readFileSync(filePath);
+    // PNG signature + IHDR: width is big-endian uint32 at offset 16, height at 20.
+    if (buf.length < 24 || buf[0] !== 0x89 || buf[1] !== 0x50) return null;
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+  } catch {
+    return null;
+  }
+}
+
+// Warn (don't block) if a declared image's shape doesn't match the orientation.
+function warnOnAspectMismatch(filePath, assetType, orientation) {
+  const size = readPngSize(filePath);
+  if (!size || !size.height) return;
+  const ratio = size.width / size.height;
+  if (assetType === 'BANNER') {
+    if (orientation === 'portrait' && ratio > 1) {
+      console.log(chalk.yellow(`  ! banner looks landscape (${size.width}×${size.height}); portrait games want a tall 9:16 hero.`));
+    } else if (orientation === 'landscape' && ratio < 1) {
+      console.log(chalk.yellow(`  ! banner looks portrait (${size.width}×${size.height}); landscape games want a wide 16:9 hero.`));
+    }
+  } else if (assetType === 'THUMBNAIL' && Math.abs(ratio - 1) > 0.2) {
+    console.log(chalk.yellow(`  ! thumbnail isn't square (${size.width}×${size.height}); cards look best at 1:1.`));
+  }
+}
+
+// Cover art shipped with the submission. Uploads whatever's declared in
+// myvillage.assets first; only prompts for what's missing. A thumbnail is
+// required — without one the game card renders blank in muni and on the web.
+async function submitCoverArt(gameId, projectDir, config) {
+  const orientation = config?.orientation || 'landscape';
+  const declared = config?.assets || {};
   console.log();
-  const { addThumbnail } = await inquirer.prompt([{
-    type: 'confirm',
-    name: 'addThumbnail',
-    message: 'Upload a thumbnail image? (shown on game cards)',
-    default: false,
-  }]);
 
-  if (addThumbnail) {
-    const { thumbnailPath } = await inquirer.prompt([{
-      type: 'input',
-      name: 'thumbnailPath',
-      message: 'Path to thumbnail image:',
-      validate: (input) => {
-        if (!input.trim()) return 'Path is required.';
-        if (!existsSync(resolve(input.trim()))) return 'File not found.';
-        return true;
-      },
-    }]);
-    await uploadImageAsset(gameId, thumbnailPath.trim(), 'THUMBNAIL');
+  // 1. Thumbnail — declared, else prompt (required).
+  let thumbUploaded = false;
+  if (declared.thumbnail) {
+    const p = resolve(projectDir, declared.thumbnail);
+    if (existsSync(p)) {
+      warnOnAspectMismatch(p, 'THUMBNAIL', orientation);
+      thumbUploaded = await uploadImageAsset(gameId, p, 'THUMBNAIL');
+    } else {
+      console.log(chalk.yellow(`  ! Declared thumbnail not found: ${declared.thumbnail}`));
+    }
+  }
+  if (!thumbUploaded) {
+    thumbUploaded = await promptForImage(gameId, 'THUMBNAIL', orientation, { required: true });
   }
 
-  const { addBanner } = await inquirer.prompt([{
+  // 2. Banner — declared, else optional prompt.
+  let bannerHandled = false;
+  if (declared.banner) {
+    const p = resolve(projectDir, declared.banner);
+    if (existsSync(p)) {
+      warnOnAspectMismatch(p, 'BANNER', orientation);
+      await uploadImageAsset(gameId, p, 'BANNER');
+      bannerHandled = true;
+    } else {
+      console.log(chalk.yellow(`  ! Declared banner not found: ${declared.banner}`));
+    }
+  }
+  if (!bannerHandled) {
+    await promptForImage(gameId, 'BANNER', orientation, { required: false });
+  }
+}
+
+// Prompt for a single image. `required` thumbnails warn loudly if skipped.
+async function promptForImage(gameId, assetType, orientation, { required }) {
+  const label = assetType.toLowerCase();
+  const hint = assetType === 'THUMBNAIL'
+    ? 'square, shown on game cards'
+    : (orientation === 'portrait' ? '9:16 hero for muni' : '16:9 featured hero');
+  const { add } = await inquirer.prompt([{
     type: 'confirm',
-    name: 'addBanner',
-    message: 'Upload a banner image? (shown on featured displays)',
-    default: false,
+    name: 'add',
+    message: `Upload a ${label} image? (${hint})`,
+    default: required,
   }]);
 
-  if (addBanner) {
-    const { bannerPath } = await inquirer.prompt([{
-      type: 'input',
-      name: 'bannerPath',
-      message: 'Path to banner image:',
-      validate: (input) => {
-        if (!input.trim()) return 'Path is required.';
-        if (!existsSync(resolve(input.trim()))) return 'File not found.';
-        return true;
-      },
-    }]);
-    await uploadImageAsset(gameId, bannerPath.trim(), 'BANNER');
+  if (!add) {
+    if (required) {
+      console.log(chalk.yellow(`  ! No thumbnail — your game card will render blank until you add one with "myvillage game upload-thumbnail <file>".`));
+    }
+    return false;
   }
+
+  const { imgPath } = await inquirer.prompt([{
+    type: 'input',
+    name: 'imgPath',
+    message: `Path to ${label} image:`,
+    validate: (input) => {
+      if (!input.trim()) return 'Path is required.';
+      if (!existsSync(resolve(input.trim()))) return 'File not found.';
+      return true;
+    },
+  }]);
+  const p = resolve(imgPath.trim());
+  warnOnAspectMismatch(p, assetType, orientation);
+  return uploadImageAsset(gameId, p, assetType);
 }
 
 function formatStatus(status) {

package/src/utils/templates.js

@@ -48,7 +48,7 @@ const BRAND = {
 };
 
 export function createGameProject(targetDir, options) {
-  const { name, description, type, ageGroup } = options;
+  const { name, description, type, ageGroup, orientation = 'landscape' } = options;
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
 
   // Create directory structure
@@ -59,6 +59,7 @@ export function createGameProject(targetDir, options) {
     'public/assets/models',
     'public/assets/textures',
     'public/assets/audio',
+    'assets',
     'src',
     'src/scenes',
     'src/components',
@@ -70,13 +71,15 @@ export function createGameProject(targetDir, options) {
   }
 
   // Write common files
-  writeFileSync(join(targetDir, 'package.json'), generatePackageJson(name, description, slug, type, ageGroup));
+  writeFileSync(join(targetDir, 'package.json'), generatePackageJson(name, description, slug, type, ageGroup, orientation));
   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, 'index.html'), generateIndexHtml(name));
+  writeFileSync(join(targetDir, 'index.html'), generateIndexHtml(name, orientation));
+  writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
 
   // Write base source files
+  writeFileSync(join(targetDir, 'src/myvillage-game.js'), generateMyVillageGameSdk());
   writeFileSync(join(targetDir, 'src/main.js'), generateMainJs(type));
   writeFileSync(join(targetDir, 'src/scenes/MainScene.js'), generateMainScene(type));
   writeFileSync(join(targetDir, 'src/utils/InputManager.js'), generateInputManager());
@@ -103,10 +106,14 @@ export function createGameProject(targetDir, options) {
 // ── Unity Game Project ─────────────────────────────────────────────
 
 export async function createUnityGameProject(targetDir, options) {
-  const { name, description, type, ageGroup, platform, unityVersion: explicitUnityVersion } = options;
+  const { name, description, type, ageGroup, orientation = 'portrait', unityVersion: explicitUnityVersion } = options;
   const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
   const className = name.replace(/[^a-zA-Z0-9]/g, '');
   const unityVersion = explicitUnityVersion || await resolveUnityVersion();
+  // Portrait Unity ships a native AssetBundle for the muni mobile app (and can
+  // also build WebGL for the web). Landscape Unity is WebGL-only (web).
+  const isLandscape = orientation === 'landscape';
+  const primaryGameType = isLandscape ? 'UNITY_WEBGL' : 'UNITY_NATIVE';
 
   // Scaffold an openable Unity project that pulls com.myvillage.gamekit via UPM.
   // Layout matches what Unity Hub expects:
@@ -119,8 +126,10 @@ export async function createUnityGameProject(targetDir, options) {
     '',
     'Assets',
     'Assets/Scripts',
+    'Assets/Editor',
     'Packages',
     'ProjectSettings',
+    'assets',
     'builds',
     'builds/ios',
     'builds/android',
@@ -137,9 +146,19 @@ export async function createUnityGameProject(targetDir, options) {
     slug,
     description,
     engine: 'unity',
-    gameType: platform === 'webgl' ? 'UNITY_WEBGL' : 'UNITY_NATIVE',
+    gameType: primaryGameType,
     category: type.toUpperCase(),
     targetAge: ageGroup,
+    // Portrait → muni mobile + web; landscape → web only. Hosts frame on this.
+    orientation,
+    aspectRatio: isLandscape ? '16:9' : '9:16',
+    // Cover art shipped with the submission. Drop files at these paths.
+    assets: {
+      thumbnail: 'assets/thumbnail.png',
+      banner: 'assets/banner.png',
+    },
+    // Villages allowed to see & play the game. Populated by `myvillage deploy`.
+    villages: [],
     sdkVersion: GAMEKIT_SDK_VERSION,
     unityVersion,
     gameId: null,
@@ -154,10 +173,56 @@ export async function createUnityGameProject(targetDir, options) {
   writeFileSync(join(targetDir, `Assets/Scripts/${className}.cs`), generateMissionScript(className, name, unityVersion));
   writeFileSync(join(targetDir, `Assets/Scripts/${className}.cs.meta`), generateUnityScriptMeta());
 
+  // Editor script that pins PlayerSettings orientation so the project starts
+  // correct (portrait for muni) instead of Unity's landscape default — no more
+  // hand-converting like the legacy izi-graham project had to.
+  writeFileSync(join(targetDir, 'Assets/Editor/MyVillageOrientation.cs'), generateOrientationEditorScript(orientation));
+  writeFileSync(join(targetDir, 'Assets/Editor/MyVillageOrientation.cs.meta'), generateUnityScriptMeta());
+
+  writeFileSync(join(targetDir, 'assets/README.md'), generateAssetsReadme(orientation));
   writeFileSync(join(targetDir, '.gitignore'), generateUnityGitignore());
-  writeFileSync(join(targetDir, 'README.md'), generateUnityReadme(name, slug, className, platform, unityVersion));
+  writeFileSync(join(targetDir, 'README.md'), generateUnityReadme(name, slug, className, orientation, unityVersion));
 
-  return { unityVersion, sdkVersion: GAMEKIT_SDK_VERSION };
+  return { unityVersion, sdkVersion: GAMEKIT_SDK_VERSION, gameType: primaryGameType };
+}
+
+// Editor script: applies orientation to PlayerSettings on first load so a
+// freshly scaffolded project opens in the right orientation. Runs once per
+// session (guarded by SessionState) and is safe to delete once set.
+function generateOrientationEditorScript(orientation) {
+  const isPortrait = orientation !== 'landscape';
+  const defaultOrientation = isPortrait ? 'UIOrientation.Portrait' : 'UIOrientation.LandscapeLeft';
+  return `using UnityEditor;
+using UnityEngine;
+
+// Auto-applies this game's orientation (${orientation}) to PlayerSettings.
+// Generated by the MyVillage CLI. Edit MyVillage > Apply Orientation to re-run.
+[InitializeOnLoad]
+public static class MyVillageOrientation
+{
+    const string AppliedKey = "MyVillage.OrientationApplied";
+
+    static MyVillageOrientation()
+    {
+        if (!SessionState.GetBool(AppliedKey, false))
+        {
+            Apply();
+            SessionState.SetBool(AppliedKey, true);
+        }
+    }
+
+    [MenuItem("MyVillage/Apply Orientation (${orientation})")]
+    public static void Apply()
+    {
+        PlayerSettings.defaultInterfaceOrientation = ${defaultOrientation};
+        PlayerSettings.allowedAutorotateToPortrait = ${isPortrait ? 'true' : 'false'};
+        PlayerSettings.allowedAutorotateToPortraitUpsideDown = false;
+        PlayerSettings.allowedAutorotateToLandscapeLeft = ${isPortrait ? 'false' : 'true'};
+        PlayerSettings.allowedAutorotateToLandscapeRight = ${isPortrait ? 'false' : 'true'};
+        Debug.Log("[MyVillage] Applied ${orientation} orientation to PlayerSettings.");
+    }
+}
+`;
 }
 
 // ── Unity (GameKit SDK) ─────────────────────────────────────────────
@@ -204,6 +269,14 @@ using UnityEngine;
 ///
 /// EDIT THIS SCRIPT: replace OnBegin with your game logic and call
 /// CompleteMission(score) when the player finishes.
+///
+/// THE GAME CONTRACT (consistent across every MyVillage game):
+///   • DONE  — call CompleteMission(score) (or FailMission(reason)) so the host
+///             knows the game is over. This is the native equivalent of the web
+///             games' MyVillageGame.complete().
+///   • EXIT  — the M-UNI host always shows an Exit control, so players can leave
+///             at any time. You don't build an exit button; the host owns it and
+///             calls OnEnd() for cleanup when the player exits.
 /// </summary>
 public sealed class ${className} : MissionBase
 {
@@ -272,11 +345,15 @@ function generateUnityGitignore() {
   ].join('\n') + '\n';
 }
 
-function generateUnityReadme(name, slug, className, platform, unityVersion) {
-  const gameType = platform === 'webgl' ? 'UNITY_WEBGL' : 'UNITY_NATIVE';
-  const buildHint = platform === 'webgl'
+function generateUnityReadme(name, slug, className, orientation, unityVersion) {
+  const isLandscape = orientation === 'landscape';
+  const gameType = isLandscape ? 'UNITY_WEBGL' : 'UNITY_NATIVE';
+  const reach = isLandscape
+    ? 'web only (mvp-video-games)'
+    : 'the muni mobile app **and** web (mvp-video-games)';
+  const buildHint = isLandscape
     ? `4. Build to \`builds/webgl/\` via **File -> Build Settings -> WebGL**, then \`myvillage deploy --platform webgl\``
-    : `4. Build AssetBundles to \`builds/ios/\` or \`builds/android/\` via **MyVillage -> Build Mission Bundle**, then \`myvillage deploy --platform ios\` (or \`android\`)`;
+    : `4. Build AssetBundles to \`builds/ios/\` or \`builds/android/\` via **MyVillage -> Build Mission Bundle**, then \`myvillage deploy --platform ios\` (or \`android\`). To also offer this portrait game on the web, build WebGL into \`builds/webgl/\` and it ships under the same game.`;
 
   return `# ${name}
 
@@ -284,6 +361,7 @@ A MyVillage game scaffolded with the MyVillage CLI and the MyVillage GameKit SDK
 
 - **Slug:** \`${slug}\`
 - **Game type:** \`${gameType}\`
+- **Orientation:** \`${orientation}\` — plays on ${reach}
 - **SDK:** \`com.myvillage.gamekit\` (pinned in \`Packages/manifest.json\`)
 
 ## What's in this project
@@ -337,7 +415,7 @@ For configurable missions (quiz questions, level layouts, etc.), create a \`Miss
 
 // ── Three.js Templates ─────────────────────────────────────────────
 
-function generatePackageJson(name, description, slug, type, ageGroup) {
+function generatePackageJson(name, description, slug, type, ageGroup, orientation = 'landscape') {
   return JSON.stringify({
     name: slug,
     version: '1.0.0',
@@ -360,11 +438,43 @@ function generatePackageJson(name, description, slug, type, ageGroup) {
       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.
+      orientation,
+      aspectRatio: orientation === 'portrait' ? '9:16' : '16:9',
+      // Declared up front so `myvillage deploy` ships them with the submission.
+      // Drop files at these paths (relative to the project root).
+      assets: {
+        thumbnail: 'assets/thumbnail.png',
+        banner: 'assets/banner.png',
+      },
+      // Villages allowed to see & play the game. Populated by `myvillage deploy`.
+      villages: [],
       lastDeployed: null,
     },
   }, null, 2) + '\n';
 }
 
+// Drop-zone guidance for cover art that ships with the submission.
+function generateAssetsReadme(orientation) {
+  const thumb = orientation === 'portrait'
+    ? 'Square (1:1, e.g. 512×512) — shown on game cards in muni and on the web.'
+    : 'Square (1:1, e.g. 512×512) — shown on game cards.';
+  const banner = orientation === 'portrait'
+    ? 'Portrait hero (9:16, e.g. 1080×1920) — the full-bleed muni catalog hero.'
+    : 'Landscape hero (16:9, e.g. 1920×1080) — featured banner on the web.';
+  return `# Submission art
+
+These files ship with \`myvillage deploy\` (declared in the \`myvillage.assets\` block of package.json).
+
+- **thumbnail.png** — ${thumb}
+- **banner.png** — ${banner}
+
+Replace the placeholders before deploying. The CLI checks aspect ratio against
+this game's orientation (\`${orientation}\`) and warns on a mismatch.
+`;
+}
+
 function generateViteConfig() {
   // base: './' makes the built HTML use relative asset URLs (e.g. ./assets/main.js
   // instead of /assets/main.js). The MyVillage host serves games at
@@ -427,6 +537,7 @@ npm run preview
 \`\`\`
 src/
   main.js           - Game entry point, sets up Three.js renderer
+  myvillage-game.js - MyVillage game bridge (completion + exit contract)
   scenes/
     MainScene.js    - Main Three.js scene with lighting and camera
   components/
@@ -435,20 +546,47 @@ src/
   utils/
     InputManager.js - Keyboard, mouse, and touch input handling
     AudioManager.js - Sound effects and background music
-public/
-  index.html        - HTML entry point
-  assets/           - Static assets (models, textures, audio)
+index.html          - HTML entry point
+assets/             - Cover art that ships with your submission (thumbnail/banner)
 \`\`\`
 
+## The game contract (works the same in every MyVillage game)
+
+Every MyVillage game — web or Unity — follows one contract so players have a
+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.
+- **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"
+  menu item).
+- **Ready** — \`MyVillageGame.ready()\` is called once your game is interactive
+  (already wired after asset loading).
+
+\`\`\`js
+import { MyVillageGame } from './myvillage-game.js';
+
+// when the player wins / the round ends:
+MyVillageGame.complete({ score: 1200, won: true });
+\`\`\`
+
+During \`npm run dev\` there's no host attached, so these calls just log to the
+console — that's expected. They take effect once the game runs inside muni or the
+web player.
+
 ## Deploying to MyVillageOS
 
-When your game is ready, deploy it to the MyVillageOS platform:
+Drop your cover art in \`assets/\` (thumbnail.png + banner.png), then:
 
 \`\`\`bash
 myvillage deploy
 \`\`\`
 
-You'll earn MVT tokens for successful deployments!
+Deploy walks you through village visibility (who can see & play it) and ships your
+cover art with the submission. An admin sets the game's MVT reward at review time.
 
 ## Learn More
 
@@ -458,18 +596,31 @@ You'll earn MVT tokens for successful deployments!
 `;
 }
 
-function generateIndexHtml(name) {
+function generateIndexHtml(name, orientation = 'landscape') {
+  const isPortrait = orientation === 'portrait';
+  // Portrait games are framed by a 9:16 stage so they look right both in the
+  // muni mobile shell (portrait WebView) and on the web. Landscape fills the
+  // viewport as before.
+  const containerStyle = isPortrait
+    ? `#game-container {
+      position: relative;
+      width: min(100vw, calc(100vh * 9 / 16));
+      height: min(100vh, calc(100vw * 16 / 9));
+      margin: 0 auto;
+    }`
+    : `#game-container { width: 100%; height: 100%; position: relative; }`;
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
+  <!-- orientation: ${orientation} -->
   <title>${name}</title>
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
     html, body { width: 100%; height: 100%; overflow: hidden; }
-    body { background: ${BRAND.darkBrown}; }
-    #game-container { width: 100%; height: 100%; position: relative; }
+    body { background: ${BRAND.darkBrown}; display: flex; align-items: center; justify-content: center; }
+    ${containerStyle}
     canvas { display: block; }
 
     /* Loading screen */
@@ -532,6 +683,7 @@ import { InputManager } from './utils/InputManager.js';
 import { AudioManager } from './utils/AudioManager.js';
 import { GameLogic } from './components/GameLogic.js';
 import { UI } from './components/UI.js';
+import { MyVillageGame } from './myvillage-game.js';
 
 class Game {
   constructor() {
@@ -567,6 +719,8 @@ class Game {
       this.state = 'menu';
       this.hideLoadingScreen();
       this.ui.showMenu();
+      // Tell the MyVillage host the game is loaded and interactive.
+      MyVillageGame.ready();
     });
 
     // Start game loop
@@ -620,6 +774,12 @@ class Game {
   endGame(result) {
     this.state = 'gameover';
     this.ui.showGameOver(result);
+    // REQUIRED: tell the MyVillage host the game is finished. The host records
+    // the session, awards MVT, and returns the player to the catalog.
+    MyVillageGame.complete({
+      score: result?.score,
+      won: result?.won,
+    });
   }
 
   animate() {
@@ -644,6 +804,92 @@ window.game = game;
 `;
 }
 
+// The universal MyVillage game contract (the "mvgame" protocol). Every
+// scaffolded game ships this verbatim so completion + exit behave identically
+// across the muni mobile app, the web (mvp-video-games), and standalone dev.
+function generateMyVillageGameSdk() {
+  return `// MyVillage Game Bridge — the "mvgame" protocol (v1).
+//
+// ONE contract for every MyVillage game, on every surface:
+//   - muni mobile app  (React Native WebView)
+//   - the web          (mvp-video-games, in an iframe)
+//   - standalone dev   (logs to the console)
+//
+// Two calls every game makes:
+//   MyVillageGame.ready()                // once, when your game is interactive
+//   MyVillageGame.complete({ score })    // when the game is finished / won / over
+//
+// One the host ALWAYS provides, but you can trigger too:
+//   MyVillageGame.exit()                 // leave the game
+//
+// The host always renders an Exit control, so a player can leave ANY game at
+// any time even if the game never calls exit() itself. Mirrors the native Unity
+// contract (CompleteMission / abort) so there is a single mental model.
+
+const PROTOCOL = 'mvgame';
+const VERSION = 1;
+
+function now() {
+  return typeof performance !== 'undefined' ? performance.now() : Date.now();
+}
+
+function post(message) {
+  const payload = { source: PROTOCOL, version: VERSION, ...message };
+  const json = JSON.stringify(payload);
+  try {
+    // React Native WebView (muni mobile app)
+    if (typeof window !== 'undefined' && window.ReactNativeWebView) {
+      window.ReactNativeWebView.postMessage(json);
+    }
+    // Iframe parent (mvp-video-games web host) — only if actually embedded
+    if (typeof window !== 'undefined' && window.parent && window.parent !== window) {
+      window.parent.postMessage(payload, '*');
+    }
+    // Standalone dev: nothing is listening, so surface it for debugging.
+    if (typeof window !== 'undefined' && !window.ReactNativeWebView && window.parent === window) {
+      console.info('[mvgame] (no host attached) ' + json);
+    }
+  } catch (e) {
+    console.warn('[mvgame] postMessage failed', e);
+  }
+}
+
+let readySent = false;
+let startedAt = now();
+
+export const MyVillageGame = {
+  /** Call once when the game has loaded and is interactive. */
+  ready() {
+    if (readySent) return;
+    readySent = true;
+    startedAt = now();
+    post({ type: 'ready' });
+  },
+
+  /**
+   * Call when the game is finished. \`result\` is optional:
+   *   { score?: number, rewards?: number, won?: boolean, custom?: object }
+   * \`durationMs\` is added automatically.
+   */
+  complete(result = {}) {
+    post({ type: 'complete', durationMs: Math.round(now() - startedAt), ...result });
+  },
+
+  /** Request to leave the game. The host also always offers an Exit control. */
+  exit() {
+    post({ type: 'exit' });
+  },
+};
+
+// Expose globally too, for non-module games and quick debugging.
+if (typeof window !== 'undefined') {
+  window.MyVillageGame = MyVillageGame;
+}
+
+export default MyVillageGame;
+`;
+}
+
 function generateMainScene(type) {
   return `// Main Three.js Scene
 // Sets up camera, lighting, and the 3D environment.

package/src/utils/village-resolver.js

@@ -9,6 +9,71 @@ import {
   joinCommunity,
 } from './api.js';
 
+/**
+ * Resolve the authenticated developer's villager UUID from stored credentials,
+ * falling back to a lookup by villager_id. Returns the UUID or null.
+ */
+async function resolveVillagerUuid(creds) {
+  let villagerUuid = creds.villager_uuid;
+  if (!villagerUuid && creds.villager_id) {
+    const result = await getVillagerByVillagerId(creds.villager_id);
+    villagerUuid = result?.data?.id || result?.id;
+  }
+  return villagerUuid || null;
+}
+
+/**
+ * Villages the authenticated developer has access to. Returns [] on any failure
+ * so callers can degrade gracefully.
+ */
+export async function getMyVillages() {
+  const creds = loadCredentials();
+  if (!creds) return [];
+  const villagerUuid = await resolveVillagerUuid(creds);
+  if (!villagerUuid) return [];
+  const villagesResult = await getVillagerVillages(villagerUuid);
+  return villagesResult?.data || [];
+}
+
+/**
+ * Prompt the developer to pick which of their villages can see & play a game.
+ * Multi-select. `existingIds` pre-checks the previous selection on re-deploy.
+ *
+ * Returns an array of village ids, or null if villages could not be loaded
+ * (caller decides whether to proceed). An empty array means "no villages" — the
+ * developer isn't in any, so the game ships without village scoping.
+ */
+export async function selectGameVillages(existingIds = []) {
+  const spinner = villageSpinner('Loading your villages...').start();
+  let villages;
+  try {
+    villages = await getMyVillages();
+  } catch (err) {
+    spinner.fail(`Could not load your villages: ${err.message}`);
+    return null;
+  }
+  spinner.stop();
+
+  if (!villages.length) {
+    console.log(chalk.yellow('  You are not a member of any villages — the game will be submitted without village scoping.'));
+    return [];
+  }
+
+  const { selected } = await inquirer.prompt([{
+    type: 'checkbox',
+    name: 'selected',
+    message: 'Which villages can see & play this game? (space to toggle, enter to confirm)',
+    choices: villages.map((v) => ({
+      name: `${v.name}${v.city ? ` (${v.city}${v.state ? ', ' + v.state : ''})` : ''}`,
+      value: v.id,
+      checked: existingIds.includes(v.id),
+    })),
+    validate: (ans) => (ans.length > 0 ? true : 'Select at least one village (space to toggle).'),
+  }]);
+
+  return selected;
+}
+
 /**
  * Resolves a villager's village context: which village they're acting on behalf of
  * and the corresponding MAN community.