@auraindustry/aurajs 0.1.1 → 0.1.3

package/src/external-package-surface.mjs

@@ -36,7 +36,7 @@ function shouldCopyPath(sourcePath, {
   }
 
   const topLevel = relativePath.split('/')[0];
-  if (topLevel === '.aura' || topLevel === '.git' || topLevel === 'node_modules') {
+  if (topLevel === '.aura' || topLevel === '.git' || topLevel === '.logs' || topLevel === 'node_modules') {
     return false;
   }
 

package/src/package-integrity.mjs

@@ -72,7 +72,7 @@ function readJsonFile(path) {
   }
 }
 
-function listHashedPackageFiles(root, current = root, acc = []) {
+function listHashedPackageFiles(root, current = root, acc = [], includedPaths = null) {
   for (const entry of readdirSync(current, { withFileTypes: true })) {
     const fullPath = join(current, entry.name);
     const relativePath = normalizeRelativePath(relative(root, fullPath));
@@ -92,7 +92,7 @@ function listHashedPackageFiles(root, current = root, acc = []) {
     }
 
     if (entry.isDirectory()) {
-      listHashedPackageFiles(root, fullPath, acc);
+      listHashedPackageFiles(root, fullPath, acc, includedPaths);
       continue;
     }
 
@@ -100,6 +100,10 @@ function listHashedPackageFiles(root, current = root, acc = []) {
       continue;
     }
 
+    if (includedPaths && !includedPaths.has(relativePath)) {
+      continue;
+    }
+
     const buffer = readFileSync(fullPath);
     acc.push({
       path: relativePath,
@@ -198,8 +202,16 @@ function normalizeBuildMetadata(buildMetadata = {}) {
   };
 }
 
-function buildManifestBody({ packageRoot, projectPackage, buildMetadata = null, signer }) {
+function buildManifestBody({ packageRoot, projectPackage, buildMetadata = null, signer, includedRelativePaths = null }) {
   const resolvedPackage = projectPackage || readJsonFile(resolve(packageRoot, 'package.json'));
+  const normalizedIncludedPaths = Array.isArray(includedRelativePaths)
+    ? new Set(
+      includedRelativePaths
+        .map((entry) => normalizeRelativePath(entry))
+        .filter(Boolean)
+        .filter((entry) => entry !== PACKAGE_INTEGRITY_MANIFEST_PATH && entry !== PACKAGE_INTEGRITY_SIGNATURE_PATH),
+    )
+    : null;
   return {
     schema: PACKAGE_INTEGRITY_SCHEMA,
     package: {
@@ -219,7 +231,7 @@ function buildManifestBody({ packageRoot, projectPackage, buildMetadata = null,
       publicKeyPem: signer.publicKeyPem,
       fingerprint: signer.fingerprint,
     },
-    files: listHashedPackageFiles(packageRoot),
+    files: listHashedPackageFiles(packageRoot, packageRoot, [], normalizedIncludedPaths),
   };
 }
 
@@ -512,6 +524,7 @@ export function writeSignedPackageIntegrityArtifacts({
   signerProjectRoot = packageRoot,
   buildMetadata = null,
   projectPackage = null,
+  includedRelativePaths = null,
 } = {}) {
   const resolvedPackageRoot = resolve(packageRoot || process.cwd());
   const signer = ensureSignerKeyPair(resolve(signerProjectRoot || resolvedPackageRoot));
@@ -520,6 +533,7 @@ export function writeSignedPackageIntegrityArtifacts({
     projectPackage,
     buildMetadata,
     signer,
+    includedRelativePaths,
   });
   const signature = sign(
     null,

package/src/publish-command.mjs

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
 
 import { preparePublishPackageSurface } from './external-package-surface.mjs';
 import {
@@ -9,6 +10,7 @@ import {
 } from './package-integrity.mjs';
 import { resolvePublishEnvExampleSurface } from './publish-env-example.mjs';
 import { validatePublishProject } from './publish-validation.mjs';
+import { formatBytes } from './external-asset-policy.mjs';
 
 export function isNpmPublishLifecycleInvocation(env = process.env) {
   return env.npm_lifecycle_event === 'publish' && env.npm_command === 'publish';
@@ -18,6 +20,116 @@ export function hasOption(commandArgs, optionName) {
   return commandArgs.some((arg) => arg === optionName || arg.startsWith(`${optionName}=`));
 }
 
+function stripOption(commandArgs, optionName) {
+  const nextArgs = [];
+  for (let index = 0; index < commandArgs.length; index += 1) {
+    const current = commandArgs[index];
+    if (current === optionName) {
+      index += 1;
+      continue;
+    }
+    if (current.startsWith(`${optionName}=`)) {
+      continue;
+    }
+    nextArgs.push(current);
+  }
+  return nextArgs;
+}
+
+export function extractPublishToken(commandArgs, env = process.env) {
+  let explicitToken = null;
+
+  for (let index = 0; index < commandArgs.length; index += 1) {
+    const current = commandArgs[index];
+    if (current === '--token') {
+      explicitToken = commandArgs[index + 1] || '';
+      break;
+    }
+    if (current.startsWith('--token=')) {
+      explicitToken = current.slice('--token='.length);
+      break;
+    }
+  }
+
+  const envToken = typeof env.NODE_AUTH_TOKEN === 'string' && env.NODE_AUTH_TOKEN.trim().length > 0
+    ? env.NODE_AUTH_TOKEN.trim()
+    : null;
+  const normalizedToken = typeof explicitToken === 'string' && explicitToken.trim().length > 0
+    ? explicitToken.trim()
+    : envToken;
+
+  return {
+    publishArgs: stripOption(commandArgs, '--token'),
+    publishEnv: normalizedToken
+      ? {
+        ...env,
+        NODE_AUTH_TOKEN: normalizedToken,
+      }
+      : env,
+    publishToken: normalizedToken,
+  };
+}
+
+function normalizeRegistryUrl(registryValue) {
+  const normalizedValue = String(registryValue || '').trim();
+  if (!normalizedValue) {
+    return 'https://registry.npmjs.org/';
+  }
+
+  try {
+    const registryUrl = new URL(normalizedValue);
+    if (!registryUrl.pathname.endsWith('/')) {
+      registryUrl.pathname = `${registryUrl.pathname}/`;
+    }
+    return registryUrl.toString();
+  } catch {
+    return 'https://registry.npmjs.org/';
+  }
+}
+
+function buildRegistryAuthLine(token, registryUrl) {
+  const parsedUrl = new URL(registryUrl);
+  const registryPath = parsedUrl.pathname === '/' ? '' : parsedUrl.pathname.replace(/\/$/, '');
+  return `//${parsedUrl.host}${registryPath}/:_authToken=${token}`;
+}
+
+function createPublishTokenEnv(token, env = process.env) {
+  if (!token) {
+    return {
+      env,
+      cleanup() {},
+    };
+  }
+
+  const registryUrl = normalizeRegistryUrl(env.npm_config_registry || env.NPM_CONFIG_REGISTRY);
+  const userConfigDir = mkdtempSync(join(tmpdir(), 'aurajs-npm-auth-'));
+  const userConfigPath = join(userConfigDir, '.npmrc');
+  writeFileSync(
+    userConfigPath,
+    [
+      `registry=${registryUrl}`,
+      'always-auth=true',
+      buildRegistryAuthLine(token, registryUrl),
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+
+  return {
+    env: {
+      ...env,
+      NODE_AUTH_TOKEN: token,
+      NPM_CONFIG_USERCONFIG: userConfigPath,
+      npm_config_userconfig: userConfigPath,
+      NPM_CONFIG_REGISTRY: registryUrl,
+      npm_config_registry: registryUrl,
+    },
+    cleanup() {
+      rmSync(userConfigDir, { recursive: true, force: true });
+    },
+  };
+}
+
 export function readProjectPackage(projectRoot = process.cwd()) {
   const packagePath = resolve(projectRoot, 'package.json');
   if (!existsSync(packagePath)) {
@@ -46,8 +158,9 @@ export function readProjectPackage(projectRoot = process.cwd()) {
 }
 
 export function buildPublishArgs(commandArgs, { packageName } = {}) {
-  const publishArgs = ['publish', ...commandArgs];
-  if (String(packageName || '').startsWith('@') && !hasOption(commandArgs, '--access')) {
+  const sanitizedArgs = stripOption(commandArgs, '--token');
+  const publishArgs = ['publish', ...sanitizedArgs];
+  if (String(packageName || '').startsWith('@') && !hasOption(sanitizedArgs, '--access')) {
     publishArgs.push('--access', 'public');
   }
   return publishArgs;
@@ -68,13 +181,10 @@ function spawnPublish(commandArgs, { projectRoot, env, stdout, stderr }) {
   return new Promise((resolveRun, rejectRun) => {
     const child = spawn(resolveNpmCommand(), commandArgs, {
       cwd: projectRoot,
-      stdio: ['ignore', 'pipe', 'pipe'],
+      stdio: 'inherit',
       env,
     });
 
-    pipeChildStream(child.stdout, stdout);
-    pipeChildStream(child.stderr, stderr);
-
     child.on('error', (error) => {
       rejectRun(error);
     });
@@ -134,9 +244,13 @@ export async function runPublishCommand(
       const assetBytes = Number.isFinite(error?.details?.assetBytes) ? error.details.assetBytes : null;
       const thresholdBytes = Number.isFinite(error?.details?.thresholdBytes) ? error.details.thresholdBytes : null;
       if (assetBytes !== null && thresholdBytes !== null) {
-        stdout?.write(`  Asset payload: ${assetBytes} bytes (threshold ${thresholdBytes})\n`);
+        stdout?.write(`  Asset payload: ${formatBytes(assetBytes)} (${assetBytes} bytes)\n`);
+        stdout?.write(`  Threshold: ${formatBytes(thresholdBytes)} (${thresholdBytes} bytes)\n`);
       }
-      stdout?.write('  Next step: upload the heavy assets to a public HTTPS host like Cloudflare R2 or S3, generate the external asset config, then retry publish.\n');
+      stdout?.write('  This package is too large for npm-first publish.\n');
+      stdout?.write('  Self-host for now: upload the heavy assets to your own public HTTPS host, then generate the external asset config.\n');
+      stdout?.write('  Command: auramaxx external-assets generate --public-base-url https://cdn.example.com/my-game\n');
+      stdout?.write('  Docs: https://www.aurajs.gg/docs/publishing-and-large-assets\n');
     }
     if (error?.reportPath) {
       stdout?.write(`  Validation report: ${error.reportPath}\n\n`);
@@ -146,8 +260,10 @@ export async function runPublishCommand(
 
   const packageName = validation.packageName;
   const { projectPackage } = readProjectPackage(projectRoot);
-  const publishArgs = buildPublishArgs(commandArgs, { packageName });
-  const dryRun = hasOption(commandArgs, '--dry-run');
+  const { publishArgs: sanitizedCommandArgs, publishEnv, publishToken } = extractPublishToken(commandArgs, env);
+  const publishArgs = buildPublishArgs(sanitizedCommandArgs, { packageName });
+  const publishTokenEnv = createPublishTokenEnv(publishToken, publishEnv);
+  const dryRun = hasOption(sanitizedCommandArgs, '--dry-run');
   const envExampleSurface = resolvePublishEnvExampleSurface({ projectRoot });
   const packageSurface = preparePublishPackageSurface({
     projectRoot,
@@ -162,6 +278,9 @@ export async function runPublishCommand(
     packageRoot: packageSurface.publishRoot,
     signerProjectRoot: projectRoot,
     buildMetadata: validation?.report?.validation?.build || null,
+    includedRelativePaths: Array.isArray(validation?.report?.validation?.pack?.files)
+      ? validation.report.validation.pack.files.map((entry) => entry?.path).filter(Boolean)
+      : null,
   });
   stdout?.write(`\n  aura publish: ${dryRun ? 'dry-run' : 'npm-first publish'}\n`);
   stdout?.write(`  Package: ${packageName}\n`);
@@ -176,11 +295,12 @@ export async function runPublishCommand(
   try {
     await spawnPublish(publishArgs, {
       projectRoot: packageSurface.publishRoot,
-      env,
+      env: publishTokenEnv.env,
       stdout,
       stderr,
     });
   } finally {
+    publishTokenEnv.cleanup();
     packageSurface.cleanup();
   }
 

package/src/publish-validation.mjs

@@ -401,12 +401,16 @@ export async function validatePublishProject(
       );
     }
 
+    const expectedAurajsVersion = typeof projectPackage?.dependencies?.['@auraindustry/aurajs'] === 'string'
+      ? projectPackage.dependencies['@auraindustry/aurajs'].trim()
+      : null;
+
     const binIntegrity = assertProjectBinIntegrity({
       projectRoot,
       projectPackage,
       packageName,
       aurajsPackageRoot: DEFAULT_AURAJS_PACKAGE_ROOT,
-      expectedAurajsVersion: AURAJS_PACKAGE_VERSION,
+      expectedAurajsVersion,
       enforceExactAurajsDependency: true,
     });
     report.validation.binIntegrity = {
@@ -566,20 +570,11 @@ export async function validatePublishProject(
       );
     }
 
-    const packageIntegrity = writeSignedPackageIntegrityArtifacts({
+    let packageIntegrity = writeSignedPackageIntegrityArtifacts({
       packageRoot: packageSurface.publishRoot,
       signerProjectRoot: projectRoot,
       buildMetadata,
     });
-    report.validation.packageIntegrity = {
-      reasonCode: 'publish_package_integrity_ok',
-      manifestPath: packageIntegrity.manifestPath,
-      signaturePath: packageIntegrity.signaturePath,
-      schema: packageIntegrity.schema,
-      fileCount: packageIntegrity.fileCount,
-      signerFingerprint: packageIntegrity.signerFingerprint,
-      publishedMetadata: packageIntegrity.publishedMetadata,
-    };
 
     assetThresholdRecord.packageSurfaceMode = packageSurface.mode;
     assetThresholdRecord.assetPackaging = packageSurface.mode === SELF_HOSTED_PACKAGE_SURFACE_MODE
@@ -664,6 +659,22 @@ export async function validatePublishProject(
       files: packFiles,
     };
 
+    packageIntegrity = writeSignedPackageIntegrityArtifacts({
+      packageRoot: packageSurface.publishRoot,
+      signerProjectRoot: projectRoot,
+      buildMetadata,
+      includedRelativePaths: packFiles.map((entry) => entry.path),
+    });
+    report.validation.packageIntegrity = {
+      reasonCode: 'publish_package_integrity_ok',
+      manifestPath: packageIntegrity.manifestPath,
+      signaturePath: packageIntegrity.signaturePath,
+      schema: packageIntegrity.schema,
+      fileCount: packageIntegrity.fileCount,
+      signerFingerprint: packageIntegrity.signerFingerprint,
+      publishedMetadata: packageIntegrity.publishedMetadata,
+    };
+
     report.summary = {
       pass: true,
       reasonCode: 'publish_validation_ok',

package/src/scaffold/project-docs.mjs

@@ -22,7 +22,7 @@ export function renderProjectReadme({ name, projectTitle, template, templateMeta
 
   return `# ${projectTitle}
 
-Scaffolded with \`aura create ${name} --template ${template}\`.
+Scaffolded with \`auramaxx create ${name} --template ${template}\`.
 
 ## Quick Start
 
@@ -35,14 +35,14 @@ Optional commands:
 
 \`\`\`bash
 ${optionalCommands}
-npx aura explain
-npx aura check
+auramaxx explain
+auramaxx check
 \`\`\`
 
 ${template === 'blank' ? '' : 'Press `F1` while the starter is running to toggle the development-only playtest HUD. Use the top scene strip to jump between scenes and the toolbar to record, capture screenshots, restart, pause, or minimize the HUD.\n\n'}
 
 If you are publishing outside the \`@aurajs\` scope, update \`package.json -> name\`
-before the first \`npm run publish\`.
+before the first \`auramaxx publish\`.
 
 ${largeAssetSection}
 ${workflowSection}
@@ -112,7 +112,7 @@ If any are unavailable at runtime, fail fast and capture the reason code before
 1. \`npm run build\` to emit native/web artifacts.
 1. \`npm run play\` to sanity-check the packaged local wrapper path.
 ${templateMetadata?.optionalModules?.multiplayer === true ? '1. `npm run join -- AURA2P` to join a room-code multiplayer session through the generated wrapper.\n' : ''}1. \`npm run session -- start\` to open a persistent local developer session.
-1. \`npm run publish\` once metadata and binaries are ready.
+1. \`auramaxx publish\` once metadata and binaries are ready.
 1. If you are not publishing under \`@aurajs\`, update \`package.json -> name\` first.
 
 ${largeAssetSection}
@@ -137,7 +137,7 @@ function renderRetroProjectReadme({ name, projectTitle, template, templateMetada
   const workflowSection = renderTemplateWorkflowSection(templateMetadata);
   return `# ${projectTitle}
 
-Scaffolded with \`aura create ${name} --template ${template}\`.
+Scaffolded with \`auramaxx create ${name} --template ${template}\`.
 
 ## Quick Start
 
@@ -156,8 +156,8 @@ npm run retro:explain
 \`\`\`
 
 Aura Retro projects build through the main AuraScript CLI, but they do not use
-the default desktop play/dev wrapper flow. Treat \`aura retro check\` and
-\`aura build --target <retro-target>\` as the primary development loop.
+the default desktop play/dev wrapper flow. Treat \`npm run retro:check\` and
+\`auramaxx build --target <retro-target>\` as the primary development loop.
 
 ${workflowSection}
 ## Template Summary
@@ -225,6 +225,15 @@ export function renderStateOwnershipSection() {
 - \`screenShell\` payloads are only the data passed into HUD, overlay, and modal screens.
 - \`config/\` is for defaults and tuning.
 - \`content/\` is for authored definitions and registries.
+
+Example shared session state:
+
+\`\`\`js
+const runFlags = context.ensureSessionState('runFlags', { DID_START: false });
+if (!runFlags.DID_START) {
+  runFlags.DID_START = true;
+}
+\`\`\`
 `;
 }
 
@@ -240,16 +249,16 @@ export function renderContinuityOwnershipSection() {
 - \`scenes/*.scene.js\` should keep \`sceneState\` JSON-safe when it must survive restore.
 - \`context.getCurrentScenePayload()\` is the read seam for payloads restored through \`sceneFlow\`.
 - saved slots live under \`.aura/state/slots/\` and checkpoints live under \`.aura/state/checkpoints/\`.
-- native dev restore hooks use \`aura dev --restore-slot <name>\` or \`aura dev --restore-checkpoint <name>\`.
+- native dev restore hooks use \`auramaxx dev --restore-slot <name>\` or \`auramaxx dev --restore-checkpoint <name>\`.
 `;
 }
 
 export function renderLargeAssetSection() {
   return `## Publish and Large Assets
 
-- \`npm run publish\` delegates to the engine-owned \`aura publish\` lane.
+- \`auramaxx publish\` is the public publish command inside an AuraJS project.
 - AuraJS measures built asset payload size before publish. The default npm-first threshold is 50 MiB; operators can override it with \`AURA_PUBLISH_ASSET_THRESHOLD_BYTES\`.
-- If the payload is too large, use your own HTTPS host for the heavy assets and run \`aura external-assets generate --public-base-url <url>\`.
+- If the payload is too large, use your own HTTPS host for the heavy assets and run \`auramaxx external-assets generate --public-base-url <url>\`.
 - That command writes \`aura.external-assets.json\` in the project root and stages manifests plus upload records under \`.aura/external-assets/\`.
 - Packaged \`npx <game> play\` and \`join\` hydrate self-hosted assets into a local cache before launch.
 - Cloudflare R2 and S3 are examples only. AuraPM and \`publishv2\` remain preview-only.
@@ -261,16 +270,16 @@ export function renderGenerateFilesSection(template) {
     return `## Generate Files
 
 \`\`\`bash
-npx aura make scene MainMenu
-npx aura make ui-screen PauseMenu
-npx aura make config EnemyTable
-npx aura make content SpawnTable
-npx aura explain
-npx aura check
+auramaxx make scene MainMenu
+auramaxx make ui-screen PauseMenu
+auramaxx make config EnemyTable
+auramaxx make content SpawnTable
+auramaxx explain
+auramaxx check
 \`\`\`
 
 Blank now ships the same authored roots as the other starters. Use the seeded
-files as the reference structure, then grow the project with \`npx aura make\`.
+files as the reference structure, then grow the project with \`auramaxx make\`.
 `;
   }
 
@@ -278,12 +287,12 @@ files as the reference structure, then grow the project with \`npx aura make\`.
     return `## Generate Files
 
 \`\`\`bash
-npx aura make card StrikePlus
-npx aura make enemy JawWorm
-npx aura make relic BurningBlood
-npx aura make encounter Act1Hallway
-npx aura explain
-npx aura check
+auramaxx make card StrikePlus
+auramaxx make enemy JawWorm
+auramaxx make relic BurningBlood
+auramaxx make encounter Act1Hallway
+auramaxx explain
+auramaxx check
 \`\`\`
 `;
   }
@@ -291,12 +300,12 @@ npx aura check
   return `## Generate Files
 
 \`\`\`bash
-npx aura make scene MainMenu
-npx aura make ui-screen PauseMenu
-npx aura make config EnemyTable
-npx aura make content SpawnTable
-npx aura explain
-npx aura check
+auramaxx make scene MainMenu
+auramaxx make ui-screen PauseMenu
+auramaxx make config EnemyTable
+auramaxx make content SpawnTable
+auramaxx explain
+auramaxx check
 \`\`\`
 `;
 }
@@ -309,8 +318,8 @@ export function renderProjectMapSection(template) {
 - \`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.
-- \`npx aura explain\` - inspect how the current project is wired.
-- \`npx aura check\` - validate authored wiring before runtime.
+- \`auramaxx explain\` - inspect how the current project is wired.
+- \`auramaxx check\` - validate authored wiring before runtime.
 - \`src/runtime/\` - runtime/bootstrap helpers plus the project and scene registries.
 - \`src/runtime/project-registry.js\` - authored source of truth for scenes, screens, prefabs, \`configFiles\`, and \`contentFiles\`.
 - \`src/runtime/scene-flow.js\` - active-scene continuity, stack state, and route payload handoff.
@@ -324,13 +333,13 @@ export function renderProjectMapSection(template) {
 - \`config/\` - defaults and tunables.
 - \`content/\` - authored game definitions, progression payloads, and starter-owned registries.
 - \`content/registries/\` - starter-owned registries and future generator-owned indexes.
-- \`src/runtime/app-state.js\` - shared mutable \`appState\` split into \`session\`, \`ui\`, and \`runtime\` buckets plus helper-backed access from scenes.`;
+- \`src/runtime/app-state.js\` - shared mutable \`appState\` split into \`session\`, \`ui\`, and \`runtime\` buckets plus helper-backed access from scenes. Starter example: \`context.ensureSessionState('runFlags', { DID_START: false })\`.`;
   }
 
   return `- \`src/main.js\` - stable bootstrap seam into the authored project layout.
 - \`src/runtime/\` - runtime/bootstrap helpers plus the project and scene registries.
 - \`src/runtime/project-registry.js\` - authored source of truth for scenes, screens, prefabs, \`configFiles\`, and \`contentFiles\`.
-- \`src/runtime/app-state.js\` - shared mutable \`appState\` split into \`session\`, \`ui\`, and \`runtime\` buckets plus helper-backed access from scenes.
+- \`src/runtime/app-state.js\` - shared mutable \`appState\` split into \`session\`, \`ui\`, and \`runtime\` buckets plus helper-backed access from scenes. Starter example: \`context.ensureSessionState('runFlags', { DID_START: false })\`.
 - \`src/runtime/scene-flow.js\` - active-scene continuity, scene-stack restore ownership, and route payload handoff.
 - \`src/runtime/screen-shell.js\` - HUD, overlay, and modal payload continuity ownership.
 - \`src/runtime/ui-theme.js\` - shared theme presets plus \`appState.ui.preferences\` apply/reset helpers.
@@ -355,16 +364,16 @@ export function renderFirstThirtyMinutesSteps(template) {
     return `1. Run \`npm install\` then \`npm run dev\` and confirm the starter loop is playable.
 1. Read \`src/main.js\`, \`src/runtime/app.js\`, \`src/runtime/app-state.js\`, \`scenes/\`, \`config/\`, \`content/\`, and \`docs/design/\` once before adding new structure.
 1. Decide whether your next change belongs in \`appState.session\`, \`appState.ui\`, \`appState.runtime\`, \`sceneState\`, \`config/\`, or \`content/\`, and whether it must survive save or restart continuity.
-1. Run \`npx aura explain\` once so the bootstrap stays obvious before the project grows.
-1. Use \`npx aura make\` when you want more authored files without inventing paths.`;
+1. Run \`auramaxx explain\` once so the bootstrap stays obvious before the project grows.
+1. Use \`auramaxx make\` when you want more authored files without inventing paths.`;
   }
 
   if (template === 'deckbuilder-2d') {
     return `1. Run \`npm install\` then \`npm run dev\` and finish one starter battle end to end.
 1. Read \`content/registries/\`, \`content/cards/\`, \`content/enemies/\`, and \`content/encounters/\` before changing scene flow.
 1. Open \`src/runtime/ui-theme.js\`, \`src/runtime/ui-settings.js\`, and \`src/runtime/ui-forms.js\` before adding pause/settings or form glue of your own.
-1. Generate one extra card or encounter with \`npx aura make\` instead of hand-creating files.
-1. Run \`npx aura explain\` or \`npx aura check\` once so the starter-owned registries stay obvious as the project grows.
+1. Generate one extra card or encounter with \`auramaxx make\` instead of hand-creating files.
+1. Run \`auramaxx explain\` or \`auramaxx check\` once so the starter-owned registries stay obvious as the project grows.
 1. Only then move into battle polish, rewards, or meta-progression.`;
   }
 
@@ -373,9 +382,9 @@ export function renderFirstThirtyMinutesSteps(template) {
 1. Open \`src/runtime/ui-theme.js\`, \`src/runtime/ui-settings.js\`, and \`src/runtime/ui-forms.js\` before inventing starter-local theme, settings, or form plumbing.
 1. Review \`assets/starter/\`, \`config/gameplay/\`, \`content/gameplay/\`, and \`docs/design/\` and rewrite the seed content so it matches your game's nouns, tuning, and milestone goals.
 1. Keep shared state in \`appState.session\` / \`appState.ui\`, keep route payloads in \`sceneFlow\`, and keep scene-only state inside \`sceneState\`.
-1. Run \`npx aura explain\` or \`npx aura check\` when you want a fast map of the authored project wiring.
+1. Run \`auramaxx explain\` or \`auramaxx check\` when you want a fast map of the authored project wiring.
 1. Press \`F1\` in the running starter to open the playtest HUD, jump between authored scenes, and use the compact capture/restart toolbar.
-1. Use \`npx aura make scene MainMenu\` or \`npx aura make ui-screen PauseMenu\` instead of hand-making new authored file paths.`;
+1. Use \`auramaxx make scene MainMenu\` or \`auramaxx make ui-screen PauseMenu\` instead of hand-making new authored file paths.`;
 }
 
 export function renderContentMapDoc({ template }) {
@@ -403,6 +412,15 @@ Template: \`${template}\`
 - \`src/runtime/project-inspector.js\` exposes the live F1 playtest HUD.
 - authored scenes read shared state with \`ensureSessionState\`, \`ensureUiState\`, and \`getCurrentScenePayload()\`.
 
+## Shared State Example
+
+\`\`\`js
+const runFlags = context.ensureSessionState('runFlags', { DID_START: false });
+if (!runFlags.DID_START) {
+  runFlags.DID_START = true;
+}
+\`\`\`
+
 ## Current Starter Inventory
 
 - \`scenes/boot.scene.js\`

package/templates/create/2d/src/runtime/app.js

@@ -1,6 +1,7 @@
 import { createSceneRegistry } from './scene-registry.js';
 import { createProjectInspector } from './project-inspector.js';
 import { assertRuntimeCapabilities } from './capabilities.js';
+import { initSplash, updateSplash, drawSplash, isSplashActive } from './splash.js';
 
 export function createApp() {
   const sceneRegistry = createSceneRegistry({
@@ -26,13 +27,16 @@ export function createApp() {
     },
     setup() {
       assertRuntimeCapabilities();
+      initSplash();
       activeScene()?.setup?.();
     },
     update(dt) {
+      if (isSplashActive()) { updateSplash(dt); return; }
       projectInspector.syncInput(globalThis.aura?.input || null);
       activeScene()?.update?.(dt);
     },
     draw() {
+      if (isSplashActive()) { drawSplash(); return; }
       activeScene()?.draw?.();
       projectInspector.draw({ activeSceneId });
     },

package/templates/create/2d-survivor/src/runtime/app.js

@@ -1,6 +1,7 @@
 import { createSceneRegistry } from './scene-registry.js';
 import { createProjectInspector } from './project-inspector.js';
 import { assertRuntimeCapabilities } from './capabilities.js';
+import { initSplash, updateSplash, drawSplash, isSplashActive } from './splash.js';
 
 export function createApp() {
   const sceneRegistry = createSceneRegistry({
@@ -26,13 +27,16 @@ export function createApp() {
     },
     setup() {
       assertRuntimeCapabilities();
+      initSplash();
       activeScene()?.setup?.();
     },
     update(dt) {
+      if (isSplashActive()) { updateSplash(dt); return; }
       projectInspector.syncInput(globalThis.aura?.input || null);
       activeScene()?.update?.(dt);
     },
     draw() {
+      if (isSplashActive()) { drawSplash(); return; }
       activeScene()?.draw?.();
       projectInspector.draw({ activeSceneId });
     },

package/templates/create/3d/src/runtime/app.js

@@ -1,6 +1,7 @@
 import { createSceneRegistry } from './scene-registry.js';
 import { createProjectInspector } from './project-inspector.js';
 import { assertRuntimeCapabilities } from './capabilities.js';
+import { initSplash, updateSplash, drawSplash, isSplashActive } from './splash.js';
 
 export function createApp() {
   const sceneRegistry = createSceneRegistry({
@@ -26,13 +27,16 @@ export function createApp() {
     },
     setup() {
       assertRuntimeCapabilities();
+      initSplash();
       activeScene()?.setup?.();
     },
     update(dt) {
+      if (isSplashActive()) { updateSplash(dt); return; }
       projectInspector.syncInput(globalThis.aura?.input || null);
       activeScene()?.update?.(dt);
     },
     draw() {
+      if (isSplashActive()) { drawSplash(); return; }
       activeScene()?.draw?.();
       projectInspector.draw({ activeSceneId });
     },