@auraindustry/aurajs 0.0.7 → 0.1.0

package/src/scaffold.mjs

@@ -1,340 +1,34 @@
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const CLI_SRC_DIR = dirname(fileURLToPath(import.meta.url));
-
-const LEGACY_STARTER_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/starter');
-
-const CREATE_TEMPLATE_DIRS = {
-  '2d-shooter': resolve(CLI_SRC_DIR, '../templates/create/2d'),
-  '2d-survivor': resolve(CLI_SRC_DIR, '../templates/create/2d-survivor'),
-  '3d-platformer': resolve(CLI_SRC_DIR, '../templates/create/3d'),
-  '3d-collectathon': resolve(CLI_SRC_DIR, '../templates/create/3d-collectathon'),
-  blank: resolve(CLI_SRC_DIR, '../templates/create/blank'),
-};
-const CREATE_SHARED_TEMPLATE_DIR = resolve(CLI_SRC_DIR, '../templates/create/shared');
-
-const CREATE_TEMPLATE_ALIASES = {
-  '2d': '2d-shooter',
-  shooter: '2d-shooter',
-  '2d shooter': '2d-shooter',
-  '2d-shooter': '2d-shooter',
-  '2d-survivor': '2d-survivor',
-  survivor: '2d-survivor',
-  '2d survival': '2d-survivor',
-  '2d-survival': '2d-survivor',
-  topdown: '2d-survivor',
-  'top-down': '2d-survivor',
-  '3d': '3d-platformer',
-  platformer: '3d-platformer',
-  platformers: '3d-platformer',
-  '3d platformer': '3d-platformer',
-  '3d platformers': '3d-platformer',
-  '3d-platformer': '3d-platformer',
-  '3d-collectathon': '3d-collectathon',
-  collectathon: '3d-collectathon',
-  explorer: '3d-collectathon',
-  exploration: '3d-collectathon',
-  '3d collectathon': '3d-collectathon',
-  '3d explorer': '3d-collectathon',
-  blank: 'blank',
-};
-const CREATE_TEMPLATE_ALIAS_HINTS = ['2d', '3d', 'shooter', 'platformer', 'survivor', 'collectathon', 'blank'];
-
-const ROOT_SKILLS_DIR = resolve(CLI_SRC_DIR, '../../../skills');
-const PACKAGED_SKILLS_DIR = resolve(CLI_SRC_DIR, '../templates/skills');
-
-const GITIGNORE_TEMPLATE = `# Dependencies\nnode_modules/\n\n# Build output\nbuild/\n.aura/\n\n# Runtime logs\n.logs/\n*.log\nnpm-debug.log*\n\n# Local env\n.env\n.env.*\n`;
-
-const PLAY_BIN_TEMPLATE = `#!/usr/bin/env node
-
-import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, createWriteStream } from 'node:fs';
-import { resolve, dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const projectRoot = resolve(__dirname, '..');
-const localAuraCli = resolve(projectRoot, 'node_modules', '@auraindustry', 'aurajs', 'src', 'cli.mjs');
-const runArgs = ['run', '--asset-mode', 'sibling'];
-
-const logDir = resolve(projectRoot, '.logs');
-mkdirSync(logDir, { recursive: true });
-const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-const logPath = join(logDir, \`play-\${stamp}.log\`);
-const logStream = createWriteStream(logPath, { flags: 'a' });
-
-const command = existsSync(localAuraCli)
-  ? {
-      cmd: process.execPath,
-      args: [localAuraCli, ...runArgs],
-    }
-  : {
-      cmd: 'npm',
-      args: ['exec', '--yes', '--package', '@auraindustry/aurajs', '--', 'aura', ...runArgs],
-    };
-
-logStream.write(\`[play] \${new Date().toISOString()} command=\${command.cmd} \${command.args.join(' ')}\\n\`);
-
-const child = spawn(command.cmd, command.args, {
-  cwd: projectRoot,
-  stdio: ['inherit', 'pipe', 'pipe'],
-  env: process.env,
-});
-
-function pipeToConsoleAndLog(stream, target) {
-  if (!stream) return;
-  stream.on('data', (chunk) => {
-    target.write(chunk);
-    logStream.write(chunk);
-  });
-}
-
-pipeToConsoleAndLog(child.stdout, process.stdout);
-pipeToConsoleAndLog(child.stderr, process.stderr);
-
-child.on('error', (err) => {
-  const message = \`[play:error] \${err.message}\\n\`;
-  process.stderr.write(message);
-  logStream.write(message);
-  logStream.end();
-  process.exit(1);
-});
-
-child.on('close', (code) => {
-  logStream.write(\`\\n[play:exit] code=\${code ?? 1}\\n\`);
-  logStream.end(() => {
-    process.exit(code ?? 1);
-  });
-});
-`;
-
-const CREATE_TEMPLATE_METADATA = {
-  '2d-shooter': {
-    summary: 'Arcade shooter baseline with waves, score, and lives loop.',
-    controls: [
-      'Move: Arrow keys or WASD',
-      'Fire: Space or Z',
-      'Restart: Enter (after game over)',
-    ],
-    firstEdits: [
-      'Tune encounter pacing in src/main.js -> WAVE_CONFIG.',
-      'Add custom enemy variants in src/starter-utils/enemy-archetypes-2d.js.',
-      'Swap starter palette and HUD text in src/main.js.',
-    ],
-    keywords: ['2d', 'shooter', 'arcade'],
-    requiredApis: [
-      'aura.window.getSize',
-      'aura.window.getFPS',
-      'aura.input.isKeyDown',
-      'aura.input.isKeyPressed',
-      'aura.draw2d.clear',
-      'aura.draw2d.rect',
-      'aura.draw2d.text',
-      'aura.draw2d.measureText',
-      'aura.rgb',
-      'aura.rgba',
-      'aura.Color.WHITE',
-    ],
-    starterAssetPlan: {
-      file: 'wave-plan.json',
-      title: '2D Shooter Wave Plan',
-      steps: [
-        'Replace this JSON with your own wave progression and enemy mix.',
-        'Load this file in game logic after adding your preferred file-loading flow.',
-      ],
-      payload: {
-        waves: [
-          { id: 'intro', maxSpawns: 9, spawnEvery: 0.62, archetype: 'scout' },
-          { id: 'pressure', maxSpawns: 10, spawnEvery: 0.56, archetype: 'striker' },
-          { id: 'anchor', maxSpawns: 8, spawnEvery: 0.74, archetype: 'tank' },
-        ],
-      },
-    },
-  },
-  '2d-survivor': {
-    summary: 'Top-down auto-fire survival loop tuned for quick iteration.',
-    controls: [
-      'Move: Arrow keys or WASD',
-      'Dash: Shift',
-      'Restart: Enter (after game over)',
-    ],
-    firstEdits: [
-      'Adjust spawn pressure in src/main.js -> spawnDirector + difficulty ramps.',
-      'Tune dash timings in src/main.js constants.',
-      'Extend enemy archetypes in src/starter-utils/enemy-archetypes-2d.js.',
-    ],
-    keywords: ['2d', 'survivor', 'topdown'],
-    requiredApis: [
-      'aura.window.getSize',
-      'aura.window.getFPS',
-      'aura.input.isKeyDown',
-      'aura.input.isKeyPressed',
-      'aura.draw2d.clear',
-      'aura.draw2d.rect',
-      'aura.draw2d.text',
-      'aura.draw2d.measureText',
-      'aura.rgb',
-      'aura.rgba',
-      'aura.Color.WHITE',
-    ],
-    starterAssetPlan: {
-      file: 'survivor-zones.json',
-      title: '2D Survivor Spawn Zones',
-      steps: [
-        'Use these zones to bias enemy spawns by map phase.',
-        'Add your own tags (boss, swarm, elite) and branch in update().',
-      ],
-      payload: {
-        zones: [
-          { id: 'north-lane', x: 0.5, y: 0.08, weight: 1.0 },
-          { id: 'east-lane', x: 0.92, y: 0.52, weight: 1.2 },
-          { id: 'south-lane', x: 0.5, y: 0.94, weight: 1.0 },
-          { id: 'west-lane', x: 0.08, y: 0.52, weight: 1.1 },
-        ],
-      },
-    },
-  },
-  '3d-platformer': {
-    summary: '3D checkpoint platformer loop with moving platform helper primitives.',
-    controls: [
-      'Move: Arrow keys or WASD',
-      'Jump: Space',
-      'Restart: Enter (after goal)',
-    ],
-    firstEdits: [
-      'Adjust traversal beats in src/main.js -> STATIC_PLATFORMS and CHECKPOINTS.',
-      'Tune camera offsets in aura.update.',
-      'Swap material colors in aura.setup for your theme.',
-    ],
-    keywords: ['3d', 'platformer', 'checkpoint'],
-    requiredApis: [
-      'aura.mesh.createBox',
-      'aura.material.create',
-      'aura.light.ambient',
-      'aura.light.directional',
-      'aura.camera3d.perspective',
-      'aura.camera3d.setPosition',
-      'aura.camera3d.lookAt',
-      'aura.input.isKeyDown',
-      'aura.input.isKeyPressed',
-      'aura.draw3d.clear3d',
-      'aura.draw3d.drawMesh',
-      'aura.draw2d.text',
-      'aura.draw2d.measureText',
-      'aura.rgb',
-      'aura.Color.WHITE',
-    ],
-    starterAssetPlan: {
-      file: 'checkpoint-route.json',
-      title: '3D Platformer Route Notes',
-      steps: [
-        'Use this path list to plan encounter/collectible placement between checkpoints.',
-        'Attach analytics ids if you track failed jump segments.',
-      ],
-      payload: {
-        path: [
-          { id: 'spawn', x: 0.0, y: 1.1, z: 5.5 },
-          { id: 'ridge-a', x: -3.2, y: 2.0, z: -2.4 },
-          { id: 'ridge-b', x: 1.4, y: 3.2, z: -0.8 },
-          { id: 'goal', x: 4.4, y: 4.8, z: -3.0 },
-        ],
-      },
-    },
-  },
-  '3d-collectathon': {
-    summary: '3D collection race starter with timer pressure and checkpoint fallback.',
-    controls: [
-      'Move: Arrow keys or WASD',
-      'Jump: Space',
-      'Restart: Enter (after clear/failure)',
-    ],
-    firstEdits: [
-      'Add world pieces in src/main.js -> WORLD_PLATFORMS + COLLECTIBLES.',
-      'Balance the timer and required collectible count in constants.',
-      'Customize checkpoint/goal feedback text in aura.draw.',
-    ],
-    keywords: ['3d', 'collectathon', 'exploration'],
-    requiredApis: [
-      'aura.mesh.createBox',
-      'aura.material.create',
-      'aura.light.ambient',
-      'aura.light.directional',
-      'aura.camera3d.perspective',
-      'aura.camera3d.setPosition',
-      'aura.camera3d.lookAt',
-      'aura.input.isKeyDown',
-      'aura.input.isKeyPressed',
-      'aura.draw3d.clear3d',
-      'aura.draw3d.drawMesh',
-      'aura.draw2d.text',
-      'aura.draw2d.measureText',
-      'aura.rgb',
-      'aura.Color.WHITE',
-    ],
-    starterAssetPlan: {
-      file: 'collectible-layout.json',
-      title: '3D Collectathon Layout Plan',
-      steps: [
-        'Extend this list with your final collectible and checkpoint route.',
-        'Optionally mirror ids in your quest/state system for save/load.',
-      ],
-      payload: {
-        collectibles: [
-          { id: 'orb-a', x: -2.8, y: 1.8, z: 2.2, value: 1 },
-          { id: 'orb-b', x: 2.4, y: 2.4, z: 0.4, value: 1 },
-          { id: 'orb-c', x: 4.6, y: 3.8, z: -2.8, value: 1 },
-        ],
-      },
-    },
-  },
-  blank: {
-    summary: 'Minimal blank loop with runtime API checks for quick custom starts.',
-    controls: [
-      'No controls wired yet.',
-      'Add input + systems directly in src/main.js.',
-    ],
-    firstEdits: [
-      'Define your own game-state object and update loop in src/main.js.',
-      'Set modules and identity in aura.config.json.',
-      'Replace starter asset notes under assets/starter/.',
-    ],
-    keywords: ['blank', 'starter'],
-    requiredApis: [
-      'aura.draw2d.clear',
-      'aura.rgba',
-    ],
-    starterAssetPlan: {
-      file: 'starter-notes.json',
-      title: 'Blank Starter Notes',
-      steps: [
-        'Write your core loop goals before coding to keep agent prompts precise.',
-        'Track capability assumptions here as you expand runtime usage.',
-      ],
-      payload: {
-        goals: [
-          'Define camera and movement model.',
-          'Pick combat/progression loop.',
-          'Specify first milestone acceptance criteria.',
-        ],
-      },
-    },
-  },
-};
-
-export function listCreateTemplates() {
-  return Object.keys(CREATE_TEMPLATE_DIRS);
-}
-
-export function listCreateTemplateAliasHints() {
-  return [...CREATE_TEMPLATE_ALIAS_HINTS];
-}
-
-export function normalizeCreateTemplate(template) {
-  const normalized = String(template || '').trim().toLowerCase();
-  return CREATE_TEMPLATE_ALIASES[normalized] || null;
-}
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { initRetroTemplate } from './retro/cli/templates.mjs';
+
+import {
+  CREATE_SHARED_TEMPLATE_DIR,
+  CREATE_TEMPLATE_DIRS,
+  GITIGNORE_TEMPLATE,
+  LEGACY_STARTER_TEMPLATE_DIR,
+  PLAY_BIN_TEMPLATE,
+  applyTemplateConfigOverrides,
+  buildCapabilitiesDeclaration,
+  buildPackageJson,
+  listCreateTemplateAliasHints,
+  listCreateTemplates,
+  normalizeCreateTemplate,
+  resolveSkillsSourceDir,
+  resolveTemplateMetadata,
+  sanitizeBinName,
+  shouldCopyCreateSharedTemplate,
+  toDisplayTitle,
+} from './scaffold/config.mjs';
+import { assertDestinationIsEmpty, copyTree, listFiles } from './scaffold/fs.mjs';
+import { writeStarterAssetPack, writeUnityLikeProjectLayout } from './scaffold/layout.mjs';
+import { renderProjectReadme, renderProjectRunbook } from './scaffold/project-docs.mjs';
+
+export {
+  listCreateTemplateAliasHints,
+  listCreateTemplates,
+  normalizeCreateTemplate,
+} from './scaffold/config.mjs';
 
 /**
  * Scaffold the legacy starter template (`aura init`).
@@ -358,7 +52,7 @@ export function scaffold(name, dest) {
  * @param {object} options - Scaffolding options.
  * @param {string} options.name - Project directory name (npm package defaults to @aurajs/<name>).
  * @param {string} options.dest - Absolute destination directory.
- * @param {string} [options.template='2d-shooter'] - Template key from listCreateTemplates().
+ * @param {string} [options.template='2d-adventure'] - Template key from listCreateTemplates().
  * @param {string} [options.version='0.1.0'] - Initial package version.
  * @param {string} [options.license='MIT'] - Initial package license.
  */
@@ -366,7 +60,7 @@ export function scaffoldGame(options) {
   const {
     name,
     dest,
-    template = '2d-shooter',
+    template = '2d-adventure',
     version = '0.1.0',
     license = 'MIT',
   } = options;
@@ -391,9 +85,26 @@ export function scaffoldGame(options) {
     PROJECT_LICENSE: license,
   };
   const templateMetadata = resolveTemplateMetadata(normalizedTemplate);
+  if (templateMetadata?.runtimeFamily === 'retro') {
+    const retroResult = scaffoldRetroGame({
+      name,
+      dest,
+      version,
+      license,
+      binName,
+      normalizedTemplate,
+      templateMetadata,
+    });
+    return retroResult;
+  }
+  const baseTemplate = templateMetadata?.baseTemplate || null;
+  const baseTemplateDir = baseTemplate ? CREATE_TEMPLATE_DIRS[baseTemplate] : null;
 
+  if (baseTemplateDir && existsSync(baseTemplateDir)) {
+    copyTree(baseTemplateDir, dest, replacements);
+  }
   copyTree(templateDir, dest, replacements);
-  if (normalizedTemplate !== 'blank' && existsSync(CREATE_SHARED_TEMPLATE_DIR)) {
+  if (shouldCopyCreateSharedTemplate(normalizedTemplate, templateMetadata) && existsSync(CREATE_SHARED_TEMPLATE_DIR)) {
     copyTree(CREATE_SHARED_TEMPLATE_DIR, dest, replacements);
   }
 
@@ -407,12 +118,14 @@ export function scaffoldGame(options) {
     version,
     license,
     binName,
+    template: normalizedTemplate,
     templateMetadata,
   });
 
   writeFileSync(join(dest, 'package.json'), JSON.stringify(pkg, null, 2) + '\n', 'utf8');
   writeFileSync(join(dest, '.gitignore'), GITIGNORE_TEMPLATE, 'utf8');
   writeFileSync(join(dest, 'bin', 'play.js'), PLAY_BIN_TEMPLATE, { encoding: 'utf8', mode: 0o755 });
+  applyTemplateConfigOverrides({ dest, templateMetadata });
   writeFileSync(
     join(dest, 'README.md'),
     renderProjectReadme({ name, projectTitle, template: normalizedTemplate, templateMetadata }),
@@ -436,6 +149,7 @@ export function scaffoldGame(options) {
     'utf8',
   );
   writeStarterAssetPack({ dest, projectTitle, template: normalizedTemplate, templateMetadata });
+  writeUnityLikeProjectLayout({ dest, projectTitle, template: normalizedTemplate, templateMetadata });
 
   const skillsSource = resolveSkillsSourceDir();
   if (skillsSource) {
@@ -447,282 +161,65 @@ export function scaffoldGame(options) {
   return {
     dest,
     template: normalizedTemplate,
+    runtimeFamily: templateMetadata?.runtimeFamily || 'default',
     files: listFiles(dest),
   };
 }
 
-function sanitizeBinName(name) {
-  const normalized = String(name || '').trim();
-  const compact = normalized
-    .replace(/^@[^/]+\//, '')
-    .replace(/\s+/g, '-')
-    .replace(/[^a-zA-Z0-9._-]/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^[-._]+|[-._]+$/g, '')
-    .toLowerCase();
-
-  if (!compact) {
-    throw new Error(`Unable to derive executable name from project name "${name}".`);
-  }
-
-  return compact;
-}
-
-function sanitizePackageSlug(name) {
-  const normalized = String(name || '').trim();
-  const compact = normalized
-    .replace(/^@[^/]+\//, '')
-    .replace(/\s+/g, '-')
-    .replace(/[^a-zA-Z0-9._-]/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^[-._]+|[-._]+$/g, '')
-    .toLowerCase();
-
-  if (!compact) {
-    throw new Error(`Unable to derive package slug from project name "${name}".`);
-  }
-
-  return compact;
-}
-
-function toDisplayTitle(name) {
-  const cleaned = String(name || '').replace(/^@[^/]+\//, '');
-  const words = cleaned.split(/[-_\s]+/).filter(Boolean);
-  if (words.length === 0) return String(name || '').trim() || 'AuraJS Game';
-  return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
-}
-
-function resolveSkillsSourceDir() {
-  if (existsSync(ROOT_SKILLS_DIR)) return ROOT_SKILLS_DIR;
-  if (existsSync(PACKAGED_SKILLS_DIR)) return PACKAGED_SKILLS_DIR;
-  return null;
-}
-
-function resolveTemplateMetadata(template) {
-  return CREATE_TEMPLATE_METADATA[template] || CREATE_TEMPLATE_METADATA.blank;
-}
-
-function buildPackageJson({ name, version, license, binName, templateMetadata }) {
-  const packageSlug = sanitizePackageSlug(name);
-  const packageName = `@aurajs/${packageSlug}`;
-  const keywords = ['aurajs', 'game', ...(templateMetadata?.keywords || [])];
+function scaffoldRetroGame({
+  name,
+  dest,
+  version,
+  license,
+  binName,
+  normalizedTemplate,
+  templateMetadata,
+}) {
+  initRetroTemplate({
+    destination: dest,
+    template: templateMetadata.retroTemplateId,
+    force: false,
+  });
 
-  return {
-    name: packageName,
+  const projectTitle = toDisplayTitle(name);
+  const pkg = buildPackageJson({
+    name,
     version,
-    description: `${toDisplayTitle(name)} — built with AuraJS`,
-    type: 'module',
-    bin: {
-      [binName]: './bin/play.js',
-    },
-    files: ['bin/', 'src/', 'assets/', 'skills/', 'aura.config.json', 'aura.capabilities.json', 'README.md', 'RUNBOOK.md'],
-    scripts: {
-      dev: 'aura dev',
-      build: 'aura build',
-      play: 'node ./bin/play.js',
-      publish: 'npx auramaxx publish',
-    },
-    dependencies: {
-      '@auraindustry/aurajs': '*',
-    },
-    keywords,
     license,
-  };
-}
-
-function buildCapabilitiesDeclaration({ template, templateMetadata }) {
-  return {
-    schema: 'aurajs.create-capabilities.v1',
-    template,
-    summary: templateMetadata.summary,
-    requiredApis: [...templateMetadata.requiredApis],
-    optionalModules: {
-      physics: false,
-      network: true,
-      multiplayer: false,
-      steam: false,
-    },
-    notes: [
-      'Keep this file in sync with runtime API usage added in src/main.js.',
-      'Treat missing APIs as scaffold contract mismatches, not silent fallbacks.',
-    ],
-  };
-}
-
-function renderProjectReadme({ name, projectTitle, template, templateMetadata }) {
-  const controls = templateMetadata.controls.map((line) => `- ${line}`).join('\n');
-  const firstEdits = templateMetadata.firstEdits.map((line) => `1. ${line}`).join('\n');
-
-  return `# ${projectTitle}
-
-Scaffolded with \`aura create ${name} --template ${template}\`.
-
-## Quick Start
-
-\`\`\`bash
-npm install
-npm run dev
-\`\`\`
-
-Optional commands:
-
-\`\`\`bash
-npm run build
-npm run play
-npm run publish
-\`\`\`
-
-## Template Summary
-
-${templateMetadata.summary}
-
-## Controls
-
-${controls}
-
-## Project Map
-
-- \`src/main.js\` - gameplay loop and rendering.
-- \`src/starter-utils/\` - reusable helpers copied for non-blank templates.
-- \`assets/starter/\` - starter asset pack and editable design payloads.
-- \`aura.config.json\` - identity/window/build/modules.
-- \`aura.capabilities.json\` - canonical runtime API declaration for this scaffold.
-- \`RUNBOOK.md\` - first-hour implementation and triage checklist.
-
-## First Edits
-
-${firstEdits}
-`;
-}
-
-function renderProjectRunbook({ projectTitle, template, templateMetadata }) {
-  const firstEdits = templateMetadata.firstEdits.map((line) => `1. ${line}`).join('\n');
-  const requiredApis = templateMetadata.requiredApis.map((entry) => `- \`${entry}\``).join('\n');
-
-  return `# ${projectTitle} Runbook
-
-Template: \`${template}\`
-
-## First 30 Minutes
-
-1. Run \`npm install\` then \`npm run dev\` and confirm the starter loop is playable.
-1. Read \`src/main.js\` once end-to-end before editing prompts or logic.
-1. Review \`assets/starter/\` and replace placeholder payloads with game-specific values.
-
-## First-Hour Implementation Pass
-
-${firstEdits}
-
-## Capability Contract
-
-The scaffold assumes the runtime APIs below:
-
-${requiredApis}
-
-If any are unavailable at runtime, fail fast and capture the reason code before adding fallback behavior.
-
-## Build + Share
-
-1. \`npm run build\` to emit native/web artifacts.
-1. \`npm run play\` to package + execute with sibling assets.
-1. \`npm run publish\` once metadata and binaries are ready.
-`;
-}
-
-function writeStarterAssetPack({ dest, projectTitle, template, templateMetadata }) {
-  const starterDir = join(dest, 'assets', 'starter');
-  mkdirSync(starterDir, { recursive: true });
+    binName,
+    template: normalizedTemplate,
+    templateMetadata,
+  });
 
+  writeFileSync(join(dest, 'package.json'), JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+  writeFileSync(join(dest, '.gitignore'), GITIGNORE_TEMPLATE, 'utf8');
   writeFileSync(
-    join(starterDir, 'README.md'),
-    `# ${projectTitle} Starter Assets
-
-Template: \`${template}\`
-
-Use this folder as the first source of truth for seed content:
-
-- Keep machine-readable balancing data in JSON files.
-- Store design intent in markdown notes so agents can edit safely.
-- Replace placeholders as soon as your core loop is stable.
-`,
+    join(dest, 'README.md'),
+    renderProjectReadme({ name, projectTitle, template: normalizedTemplate, templateMetadata }),
     'utf8',
   );
-
   writeFileSync(
-    join(starterDir, 'dev-notes.md'),
-    `# First Pass Notes
-
-- Core loop hypothesis:
-- Success metric for this week:
-- Next three gameplay experiments:
-`,
+    join(dest, 'RUNBOOK.md'),
+    renderProjectRunbook({ projectTitle, template: normalizedTemplate, templateMetadata }),
     'utf8',
   );
-
-  const plan = templateMetadata.starterAssetPlan;
   writeFileSync(
-    join(starterDir, plan.file),
+    join(dest, 'aura.capabilities.json'),
     JSON.stringify(
-      {
-        schema: 'aurajs.starter-asset-plan.v1',
-        title: plan.title,
-        template,
-        steps: plan.steps,
-        payload: plan.payload,
-      },
+      buildCapabilitiesDeclaration({
+        template: normalizedTemplate,
+        templateMetadata,
+      }),
       null,
       2,
     ) + '\n',
     'utf8',
   );
-}
-
-function assertDestinationIsEmpty(name, dest) {
-  if (existsSync(dest)) {
-    const entries = readdirSync(dest);
-    if (entries.length > 0) {
-      throw new Error(`Directory "${name}" already exists and is not empty.`);
-    }
-  }
-}
 
-/**
- * Recursively copy a directory tree, applying placeholder replacements
- * to text files.
- */
-function copyTree(src, dest, replacements) {
-  mkdirSync(dest, { recursive: true });
-
-  for (const entry of readdirSync(src)) {
-    const srcPath = join(src, entry);
-    const destPath = join(dest, entry);
-    const stat = statSync(srcPath);
-
-    if (stat.isDirectory()) {
-      copyTree(srcPath, destPath, replacements);
-    } else {
-      let content = readFileSync(srcPath, 'utf8');
-      for (const [key, value] of Object.entries(replacements)) {
-        content = content.replaceAll(`{{${key}}}`, value);
-      }
-      writeFileSync(destPath, content, 'utf8');
-    }
-  }
-}
-
-/**
- * List all files in a directory tree (relative paths).
- */
-function listFiles(dir, prefix = '') {
-  const files = [];
-  for (const entry of readdirSync(dir)) {
-    const full = join(dir, entry);
-    const rel = prefix ? `${prefix}/${entry}` : entry;
-    if (statSync(full).isDirectory()) {
-      files.push(...listFiles(full, rel));
-    } else {
-      files.push(rel);
-    }
-  }
-  return files;
+  return {
+    dest,
+    template: normalizedTemplate,
+    runtimeFamily: 'retro',
+    files: listFiles(dest),
+  };
 }