@ultimat3/cli 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -34,27 +34,27 @@
     "dev": "bun run src/bin.ts dev"
   },
   "dependencies": {
-    "@ultimat3/action": "1.0.0",
-    "@ultimat3/admin": "1.0.0",
-    "@ultimat3/ai": "1.0.0",
-    "@ultimat3/cache": "1.0.0",
-    "@ultimat3/core": "1.0.0",
-    "@ultimat3/db": "1.0.0",
-    "@ultimat3/entity": "1.0.0",
-    "@ultimat3/http": "1.0.0",
-    "@ultimat3/i18n": "1.0.0",
-    "@ultimat3/jobs": "1.0.0",
-    "@ultimat3/mail": "1.0.0",
-    "@ultimat3/manifest": "1.0.0",
-    "@ultimat3/mcp": "1.0.0",
-    "@ultimat3/policy": "1.0.0",
-    "@ultimat3/pwa": "1.0.0",
-    "@ultimat3/query": "1.0.0",
-    "@ultimat3/realtime": "1.0.0",
-    "@ultimat3/render": "1.0.0",
-    "@ultimat3/seo": "1.0.0",
-    "@ultimat3/storage": "1.0.0",
-    "@ultimat3/testing": "1.0.0",
-    "@ultimat3/time": "1.0.0"
+    "@ultimat3/action": "1.1.0",
+    "@ultimat3/admin": "1.1.0",
+    "@ultimat3/ai": "1.1.0",
+    "@ultimat3/cache": "1.1.0",
+    "@ultimat3/core": "1.1.0",
+    "@ultimat3/db": "1.1.0",
+    "@ultimat3/entity": "1.1.0",
+    "@ultimat3/http": "1.1.0",
+    "@ultimat3/i18n": "1.1.0",
+    "@ultimat3/jobs": "1.1.0",
+    "@ultimat3/mail": "1.1.0",
+    "@ultimat3/manifest": "1.1.0",
+    "@ultimat3/mcp": "1.1.0",
+    "@ultimat3/policy": "1.1.0",
+    "@ultimat3/pwa": "1.1.0",
+    "@ultimat3/query": "1.1.0",
+    "@ultimat3/realtime": "1.1.0",
+    "@ultimat3/render": "1.1.0",
+    "@ultimat3/seo": "1.1.0",
+    "@ultimat3/storage": "1.1.0",
+    "@ultimat3/testing": "1.1.0",
+    "@ultimat3/time": "1.1.0"
   }
 }

package/src/app-load.ts

@@ -22,6 +22,15 @@ const APP_GLOBS = [
   'packages/*/src/**/*.ts',
 ] as const;
 
+/**
+ * The two files that are *entry points*, not app modules: `apps/web/server.ts` starts the process
+ * and `apps/web/prerender.ts` runs the build. Importing either registers nothing — and importing
+ * `server.ts` deadlocks, because that module's own top-level `await runRole()` is what called this
+ * scan, so the dynamic import waits on a module that is waiting on the import. Anchored to the
+ * surface root: `apps/web/app/server.ts` is app code and stays in the scan.
+ */
+const ENTRY_POINT = /^apps\/[^/]+\/(?:server|prerender)\.tsx?$/;
+
 export interface LoadedApp {
   readonly root: string;
   /** App-root-relative POSIX paths of every module that imported, sorted. */
@@ -64,6 +73,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
     for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
       if (absolute.includes('node_modules') || absolute.includes('.test.')) continue;
       const file = relative(root, absolute).split(sep).join('/');
+      if (ENTRY_POINT.test(file)) continue;
       let module: Record<string, unknown>;
       try {
         module = (await import(absolute)) as Record<string, unknown>;

package/src/cmd-build.ts

@@ -1,11 +1,12 @@
 // `x build --target docker|binary|static` — three targets, no platform primitives. Deploy anywhere
 // means "anywhere that runs a container or a binary"; nothing here knows the name of a cloud.
 
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { requireAppRoot } from './app-root';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
-import { UnknownCommandError } from './errors';
+import { BuildEntryMissingError, UnknownCommandError } from './errors';
 import { execOutput } from './exec';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
@@ -26,9 +27,28 @@ export function readTarget(raw: string | undefined): BuildTarget {
   });
 }
 
+/**
+ * The one file each target builds from, app-root-relative and POSIX. One table, because `x build`
+ * has to refuse a missing entry by name before it spawns anything, and the spawned command has to
+ * name the same file — a second copy is how `binary` came to compile a path `x new` never wrote.
+ */
+export const BUILD_ENTRY: Readonly<Record<BuildTarget, string>> = {
+  docker: 'docker/Dockerfile',
+  binary: 'apps/web/server.ts',
+  static: 'apps/web/prerender.ts',
+};
+
+/** Absolute path of the target's entry, or the error that names the file and what writes it. */
+export function requireEntry(root: string, target: BuildTarget): string {
+  const entry = BUILD_ENTRY[target];
+  const absolute = join(root, entry);
+  if (!existsSync(absolute)) throw new BuildEntryMissingError({ target, entry });
+  return absolute;
+}
+
 /** One image for every role; ROLE selects behaviour at start, so there is one artifact to promote. */
 export function dockerArgs(root: string, tag: string): readonly string[] {
-  return ['docker', 'build', '-f', join(root, 'docker', 'Dockerfile'), '-t', tag, root];
+  return ['docker', 'build', '-f', join(root, BUILD_ENTRY.docker), '-t', tag, root];
 }
 
 export function binaryArgs(root: string, out: string): readonly string[] {
@@ -37,14 +57,14 @@ export function binaryArgs(root: string, out: string): readonly string[] {
     'build',
     '--compile',
     '--minify',
-    join(root, 'apps', 'web', 'server.ts'),
+    join(root, BUILD_ENTRY.binary),
     '--outfile',
     out,
   ];
 }
 
 export function staticArgs(root: string, out: string): readonly string[] {
-  return ['bun', 'run', join(root, 'apps', 'web', 'prerender.ts'), '--out', out];
+  return ['bun', 'run', join(root, BUILD_ENTRY.static), '--out', out];
 }
 
 export function argsFor(
@@ -71,6 +91,10 @@ export const buildCommand: CliCommand = {
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('build', ctx.cwd).dir;
     const target = readTarget(flagString(ctx.args, 'target'));
+    // Before the gate, not after: an entry the app does not have cannot be produced by a green
+    // typecheck, and eight seconds of `tsc` ahead of "that file does not exist" is eight seconds
+    // an agent spends on the wrong question.
+    requireEntry(root, target);
 
     // Run static verify steps before building.
     const staticSteps = ['typecheck', 'lint', 'boundaries', 'filesize', 'package-shape', 'errors'];

package/src/dev-render.ts

@@ -43,7 +43,11 @@ const headFor = async (entry: RouteEntry, data: DevRouteData): Promise<string> =
     headFromMeta(await entry.config.meta(data), seoRenderers({ path: new URL(data.url).pathname })),
   );
 
-async function documentFor(entry: RouteEntry, data: DevRouteData): Promise<string> {
+/**
+ * Head + shell for one route render. Exported because the build's prerenderer must emit the same
+ * document `x dev` serves — two document builders is how a page that works in dev ships broken.
+ */
+export async function routeDocument(entry: RouteEntry, data: DevRouteData): Promise<string> {
   return shellFor(await headFor(entry, data));
 }
 
@@ -63,11 +67,11 @@ async function resultFor(
     case 'static': {
       // Not `renderStatic`: that enumerates every prerendered path for the build. A request
       // names exactly one, and it earns the same content-hashed headers.
-      const body = await documentFor(entry, data);
+      const body = await routeDocument(entry, data);
       return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
-      const served = await isr.serve(url.pathname, () => documentFor(entry, data));
+      const served = await isr.serve(url.pathname, () => routeDocument(entry, data));
       return served.result;
     }
     case 'spa':
@@ -90,7 +94,7 @@ async function resultFor(
       );
     }
     default:
-      return renderSsr({ entry, params: data.params, url, ctx }, () => documentFor(entry, data), {
+      return renderSsr({ entry, params: data.params, url, ctx }, () => routeDocument(entry, data), {
         buildId: options.buildId,
       });
   }

package/src/dev-roles.ts

@@ -49,8 +49,24 @@ export interface StartRolesOptions {
   readonly routes: readonly Route[];
   /** The process environment, for the roles that resolve a driver from it. */
   readonly env: Env;
+  /**
+   * How the web role binds and what it admits about itself. `x dev` keeps the default —
+   * loopback, `dev: true`, so a laptop on a café network is not serving the app to the café. A
+   * container passes `{ dev: false, hostname: '0.0.0.0' }`: a process bound to `localhost` inside
+   * a container is unreachable from the port mapping, the load balancer and every PaaS health
+   * probe, which is the same failure in four costumes.
+   */
+  readonly http?: WebBinding;
 }
 
+export interface WebBinding {
+  readonly dev: boolean;
+  readonly hostname: string;
+}
+
+/** Loopback and dev-mode. What `x dev` means, and what a container must override. */
+export const DEV_BINDING: WebBinding = { dev: true, hostname: 'localhost' };
+
 export interface RunningRoles {
   readonly roles: readonly Role[];
   /** `http://…` once the web role is up; null when it was not selected. */
@@ -99,15 +115,16 @@ export function selectRoles(flag: string | undefined): readonly Role[] {
 }
 
 function startWeb(options: StartRolesOptions): ServerHandle {
+  const binding = options.http ?? DEV_BINDING;
   return createServer({
     routes: options.routes,
     role: 'web',
     hooks: devHooks(),
     config: defineHttpConfig({
       port: options.port,
-      dev: true,
+      dev: binding.dev,
       buildId: options.buildId,
-      hostname: 'localhost',
+      hostname: binding.hostname,
     }),
   }).start();
 }

package/src/dev-services.ts

@@ -33,10 +33,15 @@ const nonEmpty = (value: string | undefined): string | undefined =>
  */
 export function resolveServices(root: string, env: Env): DevServices {
   const stateDir = join(root, '.x');
-  mkdirSync(stateDir, { recursive: true });
   const databaseUrl = nonEmpty(env['DATABASE_URL']);
   const natsUrl = nonEmpty(env['NATS_URL']);
   const s3Endpoint = nonEmpty(env['S3_ENDPOINT']);
+  // Created only when something will actually live in it. A container whose bindings are all
+  // external runs non-root over a read-only app directory, and an unconditional mkdir there is an
+  // EACCES at boot for a directory that would have stayed empty.
+  if (databaseUrl === undefined || natsUrl === undefined || s3Endpoint === undefined) {
+    mkdirSync(stateDir, { recursive: true });
+  }
   return {
     stateDir,
     db:

package/src/errors.ts

@@ -36,7 +36,14 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_MANIFEST_STALE',
   'X_BUDGET_UNMEASURED',
   'X_BUILD_FAILED',
+  'X_BUILD_ENTRY_MISSING',
   'X_DEPLOY_FAILED',
+  // The two the container's own environment can get wrong. A PaaS injects `PORT` and a supervisor
+  // injects `ROLE`; both arrive as strings from outside the app, so both are validated at boot
+  // rather than defaulted — a web role that quietly bound 3000 when the platform said 8080 fails
+  // its health check with nothing in the log that names the cause.
+  'X_ROLE_UNKNOWN',
+  'X_PORT_INVALID',
   'X_GENERATE_CONFLICT',
   'X_PORT_IN_USE',
   'X_DB_GEN_FAILED',
@@ -100,7 +107,10 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_MANIFEST_STALE: 'openapi.json is stale',
   X_BUDGET_UNMEASURED: 'a route declares a budget the build never measured',
   X_BUILD_FAILED: 'x build failed',
+  X_BUILD_ENTRY_MISSING: "the build target's entry file is not in the app",
   X_DEPLOY_FAILED: 'a deploy step failed',
+  X_ROLE_UNKNOWN: 'ROLE names something that is not a role',
+  X_PORT_INVALID: 'PORT is not a TCP port number',
   X_GENERATE_CONFLICT: 'a generator would overwrite a file',
   X_PORT_IN_USE: 'the dev port is taken',
   X_DB_GEN_FAILED: 'x db gen failed',
@@ -354,6 +364,53 @@ export class FixTargetUnknownError extends UltimateError {
   }
 }
 
+/**
+ * A build target names an entry file the app does not have. `x build` refuses before it spawns the
+ * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
+ * supposed to own, and `docker build`'s says nothing about which target wanted it.
+ */
+export class BuildEntryMissingError extends UltimateError {
+  constructor(input: { target: string; entry: string }) {
+    super({
+      code: 'X_BUILD_ENTRY_MISSING',
+      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
+      fix: `x new <name> writes ${input.entry} — copy it from a fresh scaffold into this app`,
+      docs: docsFor('X_BUILD_ENTRY_MISSING'),
+    });
+  }
+}
+
+/**
+ * `ROLE` selects what a container is. One image runs every role, so a typo is a process that would
+ * otherwise start, serve nothing and report healthy — the one failure a rolling deploy cannot see.
+ */
+export class RoleUnknownError extends UltimateError {
+  constructor(input: { role: string; known: readonly string[] }) {
+    super({
+      code: 'X_ROLE_UNKNOWN',
+      cause: `ROLE="${input.role}" is not a role (known: ${input.known.join(', ')})`,
+      fix: `docker run -e ROLE=web <image>   # one of: ${input.known.join(', ')}`,
+      docs: docsFor('X_ROLE_UNKNOWN'),
+    });
+  }
+}
+
+/**
+ * Every PaaS injects `PORT` and expects the process to bind exactly it. Defaulting past a value
+ * that will not parse is how a deploy comes up on 3000, fails the platform's health probe, and
+ * reports nothing an operator can act on.
+ */
+export class PortInvalidError extends UltimateError {
+  constructor(input: { value: string }) {
+    super({
+      code: 'X_PORT_INVALID',
+      cause: `PORT="${input.value}" is not a TCP port number between 0 and 65535`,
+      fix: 'docker run -e PORT=3000 <image>',
+      docs: docsFor('X_PORT_INVALID'),
+    });
+  }
+}
+
 /** An interface-complete command path whose remote/native half is not written yet. */
 export class CliNotImplementedError extends UltimateError {
   constructor(input: { feature: string; fix: string }) {

package/src/index.ts

@@ -24,7 +24,14 @@ export { planBoundaryCuts } from './boundary-cuts';
 export type { BuildStats, RouteStats } from './budgets';
 export { BUILD_STATS_FILE, checkBudgets, readBuildStats } from './budgets';
 export type { BuildTarget } from './cmd-build';
-export { argsFor, BUILD_TARGETS, buildCommand, readTarget } from './cmd-build';
+export {
+  argsFor,
+  BUILD_ENTRY,
+  BUILD_TARGETS,
+  buildCommand,
+  readTarget,
+  requireEntry,
+} from './cmd-build';
 export { branchDatabaseName, branchSql, dbCommand, previewUrl } from './cmd-db';
 export type { DeployPlan } from './cmd-deploy';
 export { deployCommand, planDeploy } from './cmd-deploy';
@@ -64,9 +71,9 @@ export { devHooks } from './dev-hooks';
 export type { DevDbClient, RunningQueue } from './dev-queue';
 export { startQueue } from './dev-queue';
 export type { DevRenderOptions, DevRouteData } from './dev-render';
-export { appRoutes } from './dev-render';
-export type { RunningRoles, StartRolesOptions } from './dev-roles';
-export { DEV_ROLES, selectRoles, startRoles } from './dev-roles';
+export { appRoutes, routeDocument } from './dev-render';
+export type { RunningRoles, StartRolesOptions, WebBinding } from './dev-roles';
+export { DEV_BINDING, DEV_ROLES, selectRoles, startRoles } from './dev-roles';
 export type { RunningServices } from './dev-runtime';
 export { startServices } from './dev-runtime';
 export type { DevServices, ServiceBinding } from './dev-services';
@@ -98,6 +105,7 @@ export {
 export type { CliErrorCode } from './errors';
 export {
   BadFlagError,
+  BuildEntryMissingError,
   BunVersionError,
   CatalogExistsError,
   CLI_ERROR_CODES,
@@ -109,6 +117,8 @@ export {
   JobUnknownError,
   NoTestFilesError,
   NotInAppError,
+  PortInvalidError,
+  RoleUnknownError,
   UnknownCommandError,
   VerifyFailedError,
 } from './errors';
@@ -122,6 +132,7 @@ export { renderJobTable } from './jobs-table';
 export type { CliMcpServer, DevHostInput } from './mcp-host';
 export { createDevMcpServer, DEV_TOOL_SCOPES, localCaller } from './mcp-host';
 export { messageKeys, msg } from './messages';
+export { MIGRATIONS_DIR, migrationName, parseMigrationSql, readMigrations } from './migrations';
 export type { CommandResult, Finding, JsonValue, StepResult } from './output';
 export {
   exitCodeFor,
@@ -135,7 +146,19 @@ export {
 } from './output';
 export type { CommandSpec, FlagSpec, ParsedArgs } from './parse';
 export { flagBool, flagList, flagString, GLOBAL_FLAGS, nearest, parseArgs } from './parse';
+export type { PrerenderedPage, PrerenderOptions, PrerenderReport } from './prerender';
+export { DEFAULT_ORIGIN, isPrerenderable, prerenderSite } from './prerender';
 export { CLI_VERSION, COMMANDS, commandFor, SPECS } from './registry';
+export type { MigratedApp, ServedApp, ServeOptions, StartedApp } from './serve';
+export {
+  CONTAINER_BINDING,
+  DEFAULT_PORT,
+  portFromEnv,
+  roleFromEnv,
+  runMigrations,
+  runRole,
+  serveApp,
+} from './serve';
 export {
   eachSourceFile,
   isGenerated,

package/src/mcp-errors.ts

@@ -47,7 +47,13 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_MANIFEST_STALE: 'x manifest --json',
   X_BUDGET_UNMEASURED: 'x build --json && x verify --json',
   X_BUILD_FAILED: 'x build --json   # the finding names the failing step',
+  X_BUILD_ENTRY_MISSING:
+    'x new <name> --dry-run --json   # the file list names every entry a build needs',
   X_DEPLOY_FAILED: 'x deploy --json   # the finding carries the command to re-run directly',
+  // The container's own environment, so the answer is the run that sets it — never an `x` command,
+  // which is not what is running when a `ROLE=wroker` pod refuses to boot.
+  X_ROLE_UNKNOWN: 'docker run -e ROLE=web <image>',
+  X_PORT_INVALID: 'docker run -e PORT=3000 <image>',
   X_GENERATE_CONFLICT: 'x g <kind> <name> --force --json',
   X_PORT_IN_USE: 'x dev --port 3001 --json',
   // Not `x db status`: there is no such subcommand (`x db` is gen, migrate, reset, studio, branch),

package/src/migrations.ts

@@ -0,0 +1,45 @@
+// The app's SQL migrations, read off disk into `@ultimat3/db`'s own `Migration` shape. One reader,
+// because the release phase and the developer must apply the identical list through the identical
+// ledger — a deploy that migrated by some other route is a schema nobody can reconstruct.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Migration } from '@ultimat3/db';
+
+/** Where `x new` writes them and where `x db gen` adds to. App-root-relative, POSIX. */
+export const MIGRATIONS_DIR = 'packages/db/migrations';
+
+/**
+ * `-- down` alone on a line splits a migration file. Anchored to the whole line so a comment that
+ * merely mentions the word — `-- down migrations are required` — is not mistaken for the marker.
+ */
+const DOWN_MARKER = /^[ \t]*--[ \t]*down[ \t]*$/im;
+
+/** `0000_initial` → the ledger id; `initial` → the name a conflict message prints. */
+export const migrationName = (id: string): string => id.replace(/^\d+_/, '');
+
+export function parseMigrationSql(id: string, sql: string): Migration {
+  const marker = DOWN_MARKER.exec(sql);
+  const up = (marker === null ? sql : sql.slice(0, marker.index)).trim();
+  const down = marker === null ? '' : sql.slice(marker.index + marker[0].length).trim();
+  return { id, name: migrationName(id), up, down };
+}
+
+/**
+ * Sorted by id, because that is the apply order and `pendingMigrations` re-sorts on the same key.
+ * A missing directory is an empty list rather than a throw: an app can legitimately declare no
+ * entity yet, and the count is reported so "nothing was applied" is never silent.
+ */
+export async function readMigrations(root: string): Promise<readonly Migration[]> {
+  const dir = join(root, MIGRATIONS_DIR);
+  if (!existsSync(dir)) return [];
+  const files: string[] = [];
+  for await (const file of new Bun.Glob('*.sql').scan({ cwd: dir })) files.push(file);
+  files.sort();
+  const migrations: Migration[] = [];
+  for (const file of files) {
+    const text = await Bun.file(join(dir, file)).text();
+    migrations.push(parseMigrationSql(file.replace(/\.sql$/, ''), text));
+  }
+  return migrations;
+}

package/src/prerender.ts

@@ -0,0 +1,71 @@
+// `x build --target static` — the `site/` surface, rendered once and written as files a CDN or an
+// object store can serve with no process behind it. Enumeration, hashing and the output path are
+// `@ultimat3/render`'s `renderStatic`; the document is the one `x dev` serves. This file decides
+// only which routes qualify and where the bytes land.
+
+import { join } from 'node:path';
+import type { RouteEntry } from '@ultimat3/render';
+import { renderStatic, routeEntries } from '@ultimat3/render';
+import { loadApp } from './app-load';
+import { appManifest } from './app-manifest';
+import { routeDocument } from './dev-render';
+
+/**
+ * `static` only. `isr` revalidates and `ssr`/`stream`/`spa` need a process, so writing any of them
+ * to disk would publish a page whose staleness nothing can correct — and the route already
+ * declared which of the five it is.
+ */
+export const isPrerenderable = (entry: RouteEntry): boolean => entry.config.render === 'static';
+
+export interface PrerenderOptions {
+  readonly root: string;
+  readonly out: string;
+  /** Origin the rendered `<head>` builds canonical and og:url from. */
+  readonly origin?: string;
+}
+
+export interface PrerenderedPage {
+  readonly path: string;
+  /** Relative to `out`, POSIX, as `renderStatic` computed it. */
+  readonly file: string;
+  readonly hash: string;
+  readonly bytes: number;
+}
+
+export interface PrerenderReport {
+  readonly out: string;
+  readonly buildId: string;
+  readonly pages: readonly PrerenderedPage[];
+  /** Routes that exist and are not static. Reported, so "only 2 pages" is never a mystery. */
+  readonly skipped: readonly string[];
+}
+
+export const DEFAULT_ORIGIN = 'https://localhost';
+
+export async function prerenderSite(options: PrerenderOptions): Promise<PrerenderReport> {
+  // The same load `x dev` and `x manifest` perform: importing the app's modules IS what fills the
+  // route registry, so there is no route table to prerender before this runs.
+  await loadApp(options.root);
+  const buildId = (await appManifest(options.root)).manifest.buildId;
+  const origin = options.origin ?? DEFAULT_ORIGIN;
+  const pages: PrerenderedPage[] = [];
+  const skipped: string[] = [];
+
+  for (const entry of routeEntries()) {
+    if (!isPrerenderable(entry)) {
+      skipped.push(entry.path);
+      continue;
+    }
+    const artifacts = await renderStatic(
+      entry,
+      ({ path, params }) => routeDocument(entry, { url: new URL(path, origin).href, params }),
+      { buildId },
+    );
+    for (const artifact of artifacts) {
+      const file = join(options.out, artifact.outputPath);
+      const bytes = await Bun.write(file, artifact.html);
+      pages.push({ path: artifact.path, file: artifact.outputPath, hash: artifact.hash, bytes });
+    }
+  }
+  return { out: options.out, buildId, pages, skipped };
+}

package/src/serve.ts

@@ -0,0 +1,176 @@
+// What a container starts. `apps/web/server.ts` is three lines that call `runRole`, so the boot a
+// production process performs is framework code with tests rather than app code the author has to
+// get right — and it is the SAME code `x dev` runs, minus the watcher, minus `/_x`, minus
+// `dev: true`. The only production-shaped decisions live here: which role, which port, and the
+// fact that a container must bind every interface.
+
+import { listActions, toRoute } from '@ultimat3/action';
+import type { Role } from '@ultimat3/core';
+import { isRole, logger, ROLES } from '@ultimat3/core';
+import { type MigrationReport, migrate } from '@ultimat3/db';
+import type { Route } from '@ultimat3/http';
+import { loadApp } from './app-load';
+import { appManifest } from './app-manifest';
+import { assetRoutes } from './dev-assets';
+import { startQueue } from './dev-queue';
+import { appRoutes } from './dev-render';
+import type { RunningRoles, WebBinding } from './dev-roles';
+import { startRoles } from './dev-roles';
+import type { RunningServices } from './dev-runtime';
+import { startServices } from './dev-runtime';
+import type { Env } from './dev-services';
+import { resolveServices } from './dev-services';
+import { PortInvalidError, RoleUnknownError } from './errors';
+import { holdUntilShutdown } from './hold';
+import { readMigrations } from './migrations';
+
+export const DEFAULT_PORT = 3000;
+
+/** Every interface. A container bound to loopback is unreachable through its own port mapping. */
+export const CONTAINER_BINDING: WebBinding = { dev: false, hostname: '0.0.0.0' };
+
+/**
+ * `ROLE` is the one knob one image exposes. Validated rather than defaulted: a typo that fell back
+ * to `web` would start a process that serves nothing the operator asked for and reports healthy.
+ */
+export function roleFromEnv(env: Env): Role {
+  const raw = env['ROLE'] ?? 'web';
+  if (!isRole(raw)) throw new RoleUnknownError({ role: raw, known: ROLES });
+  return raw;
+}
+
+/**
+ * Every PaaS injects `PORT` and routes traffic to exactly it. `Number.parseInt` would read `80abc`
+ * as 80, so the whole string has to be a port — a partially-parsed port is a deploy that binds
+ * somewhere nobody asked for.
+ */
+export function portFromEnv(env: Env): number {
+  const raw = env['PORT'];
+  if (raw === undefined || raw.trim().length === 0) return DEFAULT_PORT;
+  const port = Number(raw.trim());
+  if (!Number.isInteger(port) || port < 0 || port > 65_535)
+    throw new PortInvalidError({ value: raw });
+  return port;
+}
+
+export interface ServeOptions {
+  readonly root: string;
+  readonly env: Env;
+  /** Overrides `ROLE`; `runRole` reads the environment when this is absent. */
+  readonly role?: Role;
+  /** Overrides `PORT`. 0 asks the kernel for an ephemeral one, which is what a test wants. */
+  readonly port?: number;
+}
+
+export interface ServedApp {
+  readonly kind: 'served';
+  readonly role: Role;
+  /** `http://…` for the web role; null for the roles that open no HTTP socket. */
+  readonly url: string | null;
+  readonly buildId: string;
+  readonly running: RunningRoles;
+  readonly runtime: RunningServices;
+  stop(): Promise<void>;
+}
+
+export interface MigratedApp {
+  readonly kind: 'migrated';
+  readonly role: 'migrate';
+  readonly report: MigrationReport;
+}
+
+export type StartedApp = ServedApp | MigratedApp;
+
+/**
+ * The release phase, as a role. `migrate` is not a server: it applies the app's own migrations
+ * through `@ultimat3/db`'s ledger — advisory lock, per-migration checksum, app-version fence — and
+ * exits, so a platform that runs one container to completion before the rest start (Heroku's
+ * release phase, a compose `service_completed_successfully`, a Kubernetes Job) has exactly one
+ * thing to run and no framework-specific flag to learn.
+ *
+ * It boots the queue, not the whole runtime: this role touches the database and nothing else, and
+ * `startQueue` is what installs `db()` for `migrate()` to find.
+ */
+export async function runMigrations(options: ServeOptions): Promise<MigratedApp> {
+  const queue = await startQueue(resolveServices(options.root, options.env));
+  try {
+    const migrations = await readMigrations(options.root);
+    const report = await migrate({
+      migrations,
+      ...(options.env['APP_VERSION'] === undefined
+        ? {}
+        : { appVersion: options.env['APP_VERSION'] }),
+    });
+    logger.info('ultimate migrate applied', {
+      applied: report.applied.length,
+      available: migrations.length,
+      appVersion: report.appVersion,
+    });
+    return { kind: 'migrated', role: 'migrate', report };
+  } finally {
+    await queue.stop();
+  }
+}
+
+/**
+ * Boot order is `x dev`'s, for the reason `x dev` gives: services, then the app's own modules
+ * (importing them IS the registration), then the role that serves what they registered. The route
+ * table is the same three contributions minus the dashboard — a `/_x` in production would expose
+ * the app's policy matrix, its outbox and its spans to the internet.
+ */
+export async function serveApp(options: ServeOptions): Promise<ServedApp> {
+  const role = options.role ?? roleFromEnv(options.env);
+  const runtime = await startServices(resolveServices(options.root, options.env), options.env);
+  // Importing the app's modules IS the registration: every route, action and job below is
+  // whatever this call put in the registries.
+  await loadApp(options.root);
+  // The build stamps `BUILD_ID` into the image; unstamped, the manifest's content hash is the same
+  // answer computed here, so `x-ultimate-build` is never absent and never a lie. Projected only
+  // when unstamped, because a stamped image already paid for it at build time and a replica's boot
+  // should not repeat it — the load above is the part every boot needs either way.
+  const stamped = options.env['BUILD_ID'];
+  const buildId =
+    stamped !== undefined && stamped.length > 0
+      ? stamped
+      : (await appManifest(options.root)).manifest.buildId;
+  const routes: readonly Route[] = [
+    ...listActions().map(toRoute),
+    ...assetRoutes({ root: options.root, storage: runtime.storage }),
+    ...appRoutes({ buildId }),
+  ];
+  const running = await startRoles({
+    roles: [role],
+    port: options.port ?? portFromEnv(options.env),
+    buildId,
+    runtime,
+    routes,
+    env: options.env,
+    http: CONTAINER_BINDING,
+  });
+  return {
+    kind: 'served',
+    role,
+    url: running.url,
+    buildId,
+    running,
+    runtime,
+    async stop() {
+      await running.stop();
+      await runtime.stop();
+    },
+  };
+}
+
+/**
+ * What `apps/web/server.ts` calls. Returns for `migrate` — the process is meant to exit — and
+ * holds for every other role until core's drain completes, so SIGTERM from a rolling restart takes
+ * the three-phase path (stop accepting, finish in-flight, close) instead of killing a query.
+ */
+export async function runRole(options: ServeOptions): Promise<StartedApp> {
+  const role = options.role ?? roleFromEnv(options.env);
+  if (role === 'migrate') return runMigrations({ ...options, role });
+  const app = await serveApp({ ...options, role });
+  logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
+  await holdUntilShutdown('serve', () => app.stop())();
+  return app;
+}

package/src/templates/index.ts

@@ -18,6 +18,7 @@ export { resourceFiles } from './resource';
 export type { RouteOptions, Surface } from './route';
 export { routeFiles } from './route';
 export { appFiles } from './scaffold-app';
+export { containerFiles } from './scaffold-container';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
 export { i18nIndex } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';

package/src/templates/scaffold-app.ts

@@ -280,6 +280,59 @@ export function AdminHome() {
 }
 `;
 
+// The two entry files a deploy needs. Both are deliberately thin: which role a container is, which
+// port it binds, how it drains and what a static build enumerates are the framework's answers, so
+// an upgrade moves them without a codemod in every app that ever shipped.
+
+const server =
+  (): string => `// The production entry. \`docker/Dockerfile\` starts this, and \`x build --target binary\` compiles it.
+// ROLE selects what this process is — web, sync, worker, scheduler, replicator, or migrate, which
+// applies the migrations and exits. PORT is bound on every interface, because a container bound to
+// localhost is unreachable through its own port mapping.
+
+import { join } from 'node:path';
+import { runRole } from '@ultimat3/cli';
+
+/**
+ * Where the app is. From this file normally — the image's WORKDIR is not the app root's business.
+ * A \`--compile\` binary is the exception: its \`import.meta.dir\` is Bun's virtual filesystem, which
+ * holds this module's bundled imports and none of the app's source, and the framework's registries
+ * are filled by scanning that source at boot. So a binary reads its root from the directory it is
+ * started in — it is a launcher for an app tree, not a self-contained copy of one.
+ */
+const root = import.meta.dir.startsWith('/$bunfs')
+  ? process.cwd()
+  : join(import.meta.dir, '..', '..');
+
+// Guarded, because the framework's module scan imports every file under apps/*/ to fill its
+// registries — an unguarded boot would start a server inside \`x verify\`.
+if (import.meta.main) {
+  await runRole({ root, env: Bun.env });
+}
+`;
+
+const prerender =
+  (): string => `// The static entry. \`x build --target static\` runs this with \`--out <dir>\` and it writes one HTML
+// file per \`render: 'static'\` route — a CDN or an object store then serves site/ with no process
+// behind it. Every other render mode needs a running app and is reported as skipped, never emitted.
+
+import { join } from 'node:path';
+import { prerenderSite } from '@ultimat3/cli';
+
+const root = join(import.meta.dir, '..', '..');
+const flag = Bun.argv.indexOf('--out');
+const out = (flag === -1 ? undefined : Bun.argv[flag + 1]) ?? join(root, '.x', 'static');
+// SITE_ORIGIN is what canonical and og:url are built from; the default is only ever a local build.
+const origin = Bun.env['SITE_ORIGIN'];
+
+if (import.meta.main) {
+  const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
+  await Bun.stdout.write(
+    \`\${JSON.stringify({ ok: true, out: report.out, pages: report.pages.length, skipped: report.skipped })}\\n\`,
+  );
+}
+`;
+
 const placeholder = (surface: string, app: NameSet): string => `# ${surface}
 
 Placeholder. The monorepo shape exists now so adding ${surface} later is a new directory, not a
@@ -297,6 +350,8 @@ export function appFiles(app: NameSet): readonly GeneratedFile[] {
   return [
     { path: 'apps/web/package.json', contents: webPackage(app) },
     { path: 'apps/web/tsconfig.json', contents: tsconfig() },
+    { path: 'apps/web/server.ts', contents: server() },
+    { path: 'apps/web/prerender.ts', contents: prerender() },
     { path: 'apps/web/site/icon.png', contents: icon() },
     { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
     { path: 'apps/web/site/page.module.scss', contents: siteStyle() },

package/src/templates/scaffold-container.ts

@@ -0,0 +1,264 @@
+// The container half of what `x new` writes: the image, what to ignore when building it, the
+// production topology, and the one page that explains how a platform runs the release phase.
+// Split from scaffold-docs.ts because these four are one subject and that file is another.
+//
+// Axiom 7 in file form. Nothing here names a cloud: `$PORT`, `0.0.0.0`, `/readyz` and a
+// run-to-completion migrate step are conventions every container platform shares — a Heroku
+// buildpack, a Render blueprint or a fly.toml would be the primitive that never ships.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const dockerfile = (
+  app: NameSet,
+): string => `# One image, every role. ROLE selects behaviour at start, so there is exactly one artifact to
+# promote — the image that passed staging is the image production runs.
+#
+#   x build --target docker --tag ${app.kebab}:$(git rev-parse --short HEAD)
+#   docker run --rm -e ROLE=migrate -e DATABASE_URL=... ${app.kebab}:...   # release phase
+#   docker run -e ROLE=web -e PORT=8080 -p 8080:8080 -e DATABASE_URL=... ${app.kebab}:...
+#
+# syntax=docker/dockerfile:1
+
+# ---------- deps: runtime dependencies only, cached on the workspace manifests ----------
+FROM oven/bun:1.3-alpine AS deps
+WORKDIR /app
+COPY package.json bun.lock ./
+# The workspace members' manifests are what \`bun install\` resolves against; their sources are not.
+COPY apps ./apps
+COPY packages ./packages
+RUN bun install --frozen-lockfile --production
+
+# ---------- runtime ----------
+# No build stage and no second gate: \`x verify\` is the gate and \`x build\` runs the static steps
+# before it ever calls \`docker build\`. Re-running typecheck and lint here would need the
+# devDependencies the \`--production\` install above deliberately leaves out — which is exactly how
+# a build stage came to run \`tsc\` and \`biome\` against a tree that had neither.
+FROM oven/bun:1.3-alpine AS runtime
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# The immutable content hash this image serves. Stamped by CI (\`--build-arg BUILD_ID=$(git rev-parse HEAD)\`);
+# without one the server computes the same hash from the manifest at boot. Never \`latest\`.
+ARG BUILD_ID=
+ENV NODE_ENV=production \\
+    ROLE=web \\
+    PORT=3000 \\
+    BUILD_ID=\${BUILD_ID}
+
+# Documentation only — the platform decides the real port and injects it as PORT. The server binds
+# whatever arrives, on 0.0.0.0, because a container bound to localhost is unreachable through its
+# own port mapping, its load balancer and every health probe alike.
+EXPOSE 3000
+
+# Every role serves /healthz and /readyz. /readyz flips to 503 on SIGTERM *before* the socket
+# closes, so a rolling restart drains in-flight work instead of dropping it.
+HEALTHCHECK --interval=10s --timeout=3s --start-period=30s --retries=3 CMD \\
+  bun --eval "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"
+
+# \`.x/\` is where any binding that is still embedded keeps its state — the local storage disk, and
+# PGlite if DATABASE_URL is unset. Owned by the runtime user, because /app is not: the alternative
+# is a non-root process failing at boot on a directory it is the only one that ever writes.
+RUN mkdir -p /app/.x && chown -R bun:bun /app/.x
+
+USER bun
+# apps/web/server.ts reads ROLE and PORT and nothing else. \`migrate\` applies the migrations and
+# exits; every other role serves until SIGTERM.
+ENTRYPOINT ["bun", "apps/web/server.ts"]
+`;
+
+/**
+ * BuildKit prefers `<dockerfile>.dockerignore` over the context root's, so this sits beside the
+ * Dockerfile. Without it `COPY . .` ships `node_modules` and `.x/` — a stale host `node_modules`
+ * would shadow the `--production` install the deps stage just made.
+ */
+const dockerignore = (): string => `node_modules
+**/node_modules
+**/.x
+**/dist
+**/*.tsbuildinfo
+.git
+.env
+.env.*.local
+coverage
+**/test-results
+**/playwright-report
+`;
+
+const composeProd = (
+  app: NameSet,
+): string => `# The production topology: one service per role, one image, differing only by ROLE and replicas.
+# What \`x deploy --method compose\` runs. migrate runs to completion before anything serves.
+#
+#   IMAGE=ghcr.io/you/${app.kebab}:1.2.3 x deploy --image ghcr.io/you/${app.kebab}:1.2.3
+name: ${app.kebab}
+
+x-image: &image
+  image: \${IMAGE:-${app.kebab}:dev}
+  env_file: [../.env.production]
+  restart: unless-stopped
+  stop_grace_period: 30s # SIGTERM → drain in-flight requests, jobs and sockets
+  depends_on:
+    db: { condition: service_healthy }
+
+services:
+  db:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_PASSWORD: \${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
+      POSTGRES_DB: ${app.kebab}
+    volumes: ['pgdata:/var/lib/postgresql/data']
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 5s
+    restart: unless-stopped
+
+  # The release phase. Applies pending migrations under an advisory lock and exits; every serving
+  # role waits for it to complete, so no replica ever serves against a schema it does not ship.
+  migrate:
+    <<: *image
+    environment: [ROLE=migrate]
+    restart: 'no'
+
+  web:
+    <<: *image
+    environment: [ROLE=web]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 2 } # stateless: scales on RPS
+    ports: ['3000:3000']
+
+  sync:
+    <<: *image
+    environment: [ROLE=sync]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 1 } # scales on concurrent websockets; no sticky sessions
+    ports: ['3001:3001']
+
+  worker:
+    <<: *image
+    environment: [ROLE=worker]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 1 } # scales on queue depth
+
+  scheduler:
+    <<: *image
+    environment: [ROLE=scheduler]
+    depends_on:
+      db: { condition: service_healthy }
+      migrate: { condition: service_completed_successfully }
+    deploy: { replicas: 1 } # fixed 1; leadership is a Postgres advisory lock
+
+volumes:
+  pgdata:
+`;
+
+const readme = (app: NameSet): string => `# docker
+
+One image, every role. \`ROLE\` selects behaviour at start, so there is one artifact to promote and
+nothing to rebuild between staging and production.
+
+| Role | Does | Listens |
+|---|---|---|
+| \`web\` | HTTP: pages, actions, assets | \`$PORT\` (default 3000) |
+| \`sync\` | websockets for live queries | \`$PORT + 1\` |
+| \`worker\` | the job queue | — |
+| \`scheduler\` | cron tasks; leadership is a Postgres advisory lock | — |
+| \`replicator\` | the logical replication slot, exactly one per database | — |
+| \`migrate\` | applies pending migrations and **exits** | — |
+
+Every serving role answers \`/healthz\` and \`/readyz\`. \`/readyz\` flips to 503 on \`SIGTERM\` before the
+socket closes, which is what makes a rolling restart drain instead of drop.
+
+## Build and run
+
+\`\`\`sh
+x build --target docker --tag ${app.kebab}:dev
+docker run --rm -e ROLE=migrate -e DATABASE_URL=postgres://... ${app.kebab}:dev
+docker run -p 3000:3000 -e DATABASE_URL=postgres://... ${app.kebab}:dev
+\`\`\`
+
+## One box, every role
+
+\`\`\`sh
+docker compose -f docker/docker-compose.prod.yml up -d      # db → migrate → the rest
+x deploy --image ${app.kebab}:dev --dry-run --json           # the same plan, printed
+\`\`\`
+
+## The other two build targets
+
+\`\`\`sh
+x build --target static --out dist/static   # one HTML file per \`render: 'static'\` route
+x build --target binary --out dist/app      # a single executable, no Bun install needed
+\`\`\`
+
+The binary bundles the framework, not the app: the registries are filled by scanning
+\`apps/*/{site,app,api,shared}\` at boot, so it is a launcher that must be **started from the app
+root**, with the source tree beside it. The image is the self-contained artifact.
+
+## A PaaS (Heroku, Render, Fly, Railway, Cloud Run, App Runner…)
+
+The framework ships **no** platform primitives — no buildpack, no \`app.json\`, no \`fly.toml\`, no
+adapter. It does not need to: every one of these platforms builds a Dockerfile and every one of
+them expects the same three things, which this image already does.
+
+| The platform does | The image does |
+|---|---|
+| injects \`PORT\` and routes traffic to it | \`apps/web/server.ts\` binds exactly \`$PORT\`, refusing a value that is not a port (\`X_PORT_INVALID\`) rather than defaulting past it |
+| requires the process to bind \`0.0.0.0\` | it binds every interface; loopback would be unreachable from outside the container |
+| polls a health path | \`/readyz\` for "may I have traffic", \`/healthz\` for "am I alive" |
+| sends \`SIGTERM\`, then \`SIGKILL\` after a grace period | drains in three phases: stop accepting, finish in-flight, close |
+
+Set \`DATABASE_URL\` and deploy the Dockerfile. That is the whole integration.
+
+### Release-phase migrations — the one way
+
+Run **the same image** with \`ROLE=migrate\` before the new release serves traffic. It applies every
+pending migration in \`packages/db/migrations\` under a Postgres advisory lock, records each in the
+\`x_migrations\` ledger with its checksum, and exits 0. Concurrent migrators serialise; a checksum
+that no longer matches an applied migration stops the release instead of corrupting it.
+
+| Platform | Where the command goes |
+|---|---|
+| Heroku | \`release: bun apps/web/server.ts\` in \`Procfile\`, with \`ROLE=migrate\` on the release dyno |
+| Render | \`preDeployCommand: ROLE=migrate bun apps/web/server.ts\` |
+| Fly.io | \`[deploy] release_command = "bun apps/web/server.ts"\` with \`ROLE=migrate\` |
+| Railway | a pre-deploy command running the same |
+| Kubernetes | an \`initContainer\` or a \`Job\` on the same image with \`ROLE=migrate\` |
+| Compose | the \`migrate\` service; every other role waits on \`service_completed_successfully\` |
+
+There is no \`x db migrate\` in that list on purpose: it is the developer's command and it needs the
+toolchain, while the release phase runs the shipped image and nothing else.
+
+## Environment
+
+| Key | Meaning | Unset means |
+|---|---|---|
+| \`ROLE\` | which process this is | \`web\` |
+| \`PORT\` | the port the web role binds | 3000 |
+| \`DATABASE_URL\` | Postgres | embedded PGlite — never in production |
+| \`BUILD_ID\` | the immutable build hash clients are served against | computed from the manifest at boot |
+| \`NATS_URL\` | multi-node realtime transport | in-process fanout, single node only |
+| \`S3_ENDPOINT\` | object storage | a local directory |
+
+## Kubernetes
+
+\`x deploy --method helm\` expects a chart at \`docker/helm\`. \`x new\` does not write one — a chart is
+a topology decision, not a scaffold default. Copy \`docker/helm\` from the framework repository, or
+stay on \`--method compose\`.
+`;
+
+/** The container files for a new app, in the order a reader meets them. */
+export function containerFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'docker/Dockerfile', contents: dockerfile(app) },
+    { path: 'docker/Dockerfile.dockerignore', contents: dockerignore() },
+    { path: 'docker/docker-compose.prod.yml', contents: composeProd(app) },
+    { path: 'docker/README.md', contents: readme(app) },
+  ];
+}

package/src/templates/scaffold-docs.ts

@@ -1,8 +1,10 @@
 // The human-authored half of what `x new` writes: the READMEs, the agent-facing convention files,
-// the bin/ shims and the docker directory. Separated from the config half so neither file has to
-// be scrolled to find the other — one file, one job applies to templates too.
+// the bin/ shims and the optional dev compose. Separated from the config half so neither file has
+// to be scrolled to find the other — one file, one job applies to templates too. The image, its
+// ignore file, the production topology and the deploy page are `scaffold-container.ts`.
 
 import type { GeneratedFile, NameSet } from './naming';
+import { containerFiles } from './scaffold-container';
 
 const agents = (app: NameSet): string => `# AGENTS.md
 
@@ -114,30 +116,6 @@ services:
     ports: ['9000:9000']
 `;
 
-const dockerfile = (
-  app: NameSet,
-): string => `# One image, all roles. ROLE selects behaviour at start; nothing else differs between processes.
-FROM oven/bun:1.3-alpine AS deps
-WORKDIR /src
-COPY package.json bun.lock ./
-COPY apps ./apps
-COPY packages ./packages
-RUN bun install --frozen-lockfile --production
-
-FROM oven/bun:1.3-alpine AS build
-WORKDIR /src
-COPY --from=deps /src/node_modules ./node_modules
-COPY . .
-RUN bunx x build --target binary --out /out/${app.kebab}
-
-FROM gcr.io/distroless/base-debian12 AS runtime
-COPY --from=build /out/${app.kebab} /app/${app.kebab}
-ENV ROLE=web PORT=3000
-EXPOSE 3000
-USER 65532:65532
-ENTRYPOINT ["/app/${app.kebab}"]
-`;
-
 /** Docs, shims and container files for a new app, in the order a reader meets them. */
 export function docsFiles(app: NameSet): readonly GeneratedFile[] {
   return [
@@ -147,8 +125,8 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     { path: 'bin/setup', contents: binSetup() },
     { path: 'bin/dev', contents: binDev() },
     { path: 'bin/check', contents: binCheck() },
-    { path: 'docker/Dockerfile', contents: dockerfile(app) },
     { path: 'docker/docker-compose.dev.yml', contents: composeDev(app) },
+    ...containerFiles(app),
   ];
 }
 

package/src/templates/scaffold-repo.ts

@@ -1,14 +1,19 @@
 // The config half of what `x new` writes: the one config file, the tooling configs and the
 // workspace packages. Committed defaults only — a fresh clone boots with `x dev` and no env
-// scavenger hunt. The docs, shims and container files live in scaffold-docs.ts.
+// scavenger hunt. The docs and shims live in scaffold-docs.ts, the container files in
+// scaffold-container.ts.
 
 import type { GeneratedFile, NameSet } from './naming';
 import { docsFiles } from './scaffold-docs';
 import { i18nFiles } from './scaffold-i18n';
 import { packageShapeFiles } from './scaffold-package-shape';
 
+// `version` is not decoration: the manifest's app version IS the contract's compatibility gate,
+// and the manifest never fabricates one — so an app scaffolded without it failed `x manifest`,
+// the `manifest` verify step and every production boot with X_APP_PACKAGE_INVALID.
 const rootPackage = (app: NameSet, version: string): string => `{
   "name": "${app.kebab}",
+  "version": "0.1.0",
   "private": true,
   "type": "module",
   "workspaces": [
@@ -64,6 +69,8 @@ const rootTsconfig = (app: NameSet): string => `{
     "lib": ["ES2023", "DOM", "DOM.Iterable"],
     "types": ["bun"],
     "paths": {
+      "@${app.kebab}/web/*": ["./apps/web/*"],
+      "@${app.kebab}/admin/*": ["./apps/admin/*"],
       "@${app.kebab}/*": ["./packages/*/src"]
     },
     "strict": true,
@@ -105,10 +112,13 @@ export const config = defineConfig({
 });
 `;
 
+// `biome.json` is strict JSON — Biome's own parser rejects a `//` comment in it, which made every
+// scaffolded app fail its first `x verify` on the config rather than on the code. The note that
+// used to be a comment lives here, where it is read by the person who would have changed the line:
+// x.manifest.json and openapi.json are emitted byte-for-byte by `x manifest`, so a formatter
+// rewriting them puts `x manifest` and `x verify` in a loop neither can win.
 const biome = (): string => `{
   "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
-  // x.manifest.json and openapi.json are emitted byte-for-byte by \`x manifest\`; a formatter
-  // rewriting them puts \`x manifest\` and \`x verify\` in a loop neither can win.
   "files": { "includes": ["**", "!x.manifest.json", "!openapi.json"] },
   "formatter": { "indentStyle": "space", "indentWidth": 2, "lineWidth": 100 },
   "linter": {