@ultimat3/cli 20.0.0 → 20.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "20.0.0",
+  "version": "20.1.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "20.0.0",
-    "@ultimat3/admin": "20.0.0",
-    "@ultimat3/ai": "20.0.0",
-    "@ultimat3/auth": "20.0.0",
-    "@ultimat3/cache": "20.0.0",
-    "@ultimat3/core": "20.0.0",
-    "@ultimat3/db": "20.0.0",
-    "@ultimat3/entity": "20.0.0",
-    "@ultimat3/flags": "20.0.0",
-    "@ultimat3/http": "20.0.0",
-    "@ultimat3/i18n": "20.0.0",
-    "@ultimat3/jobs": "20.0.0",
-    "@ultimat3/mail": "20.0.0",
-    "@ultimat3/manifest": "20.0.0",
-    "@ultimat3/mcp": "20.0.0",
-    "@ultimat3/money": "20.0.0",
-    "@ultimat3/notify": "20.0.0",
-    "@ultimat3/policy": "20.0.0",
-    "@ultimat3/pwa": "20.0.0",
-    "@ultimat3/query": "20.0.0",
-    "@ultimat3/realtime": "20.0.0",
-    "@ultimat3/render": "20.0.0",
-    "@ultimat3/schema": "20.0.0",
-    "@ultimat3/scraping": "20.0.0",
-    "@ultimat3/seo": "20.0.0",
-    "@ultimat3/storage": "20.0.0",
-    "@ultimat3/testing": "20.0.0",
-    "@ultimat3/time": "20.0.0",
+    "@ultimat3/action": "20.1.0",
+    "@ultimat3/admin": "20.1.0",
+    "@ultimat3/ai": "20.1.0",
+    "@ultimat3/auth": "20.1.0",
+    "@ultimat3/cache": "20.1.0",
+    "@ultimat3/core": "20.1.0",
+    "@ultimat3/db": "20.1.0",
+    "@ultimat3/entity": "20.1.0",
+    "@ultimat3/flags": "20.1.0",
+    "@ultimat3/http": "20.1.0",
+    "@ultimat3/i18n": "20.1.0",
+    "@ultimat3/jobs": "20.1.0",
+    "@ultimat3/mail": "20.1.0",
+    "@ultimat3/manifest": "20.1.0",
+    "@ultimat3/mcp": "20.1.0",
+    "@ultimat3/money": "20.1.0",
+    "@ultimat3/notify": "20.1.0",
+    "@ultimat3/policy": "20.1.0",
+    "@ultimat3/pwa": "20.1.0",
+    "@ultimat3/query": "20.1.0",
+    "@ultimat3/realtime": "20.1.0",
+    "@ultimat3/render": "20.1.0",
+    "@ultimat3/schema": "20.1.0",
+    "@ultimat3/scraping": "20.1.0",
+    "@ultimat3/seo": "20.1.0",
+    "@ultimat3/storage": "20.1.0",
+    "@ultimat3/testing": "20.1.0",
+    "@ultimat3/time": "20.1.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/budgets.ts

@@ -13,6 +13,7 @@ import type { Manifest, RouteFact } from '@ultimat3/manifest';
 import { formatBytes, parseByteBudget } from '@ultimat3/render';
 import type { Finding } from './output';
 import type { UnmeasuredRoute } from './static-report';
+import { SW_REGISTER_PATH } from './sw-artifacts';
 
 export const BUILD_STATS_FILE = join('.x', 'build-stats.json');
 
@@ -24,7 +25,14 @@ export interface RouteStats {
    * prerenders many pages contributes ONE row, holding its heaviest.
    */
   readonly path: string;
+  /** The APP's JavaScript, and only the app's — see `FRAMEWORK_SCRIPTS`. */
   readonly jsBytes: number;
+  /**
+   * The framework's own injected runtime, in bytes: reported, never budgeted. Optional because a
+   * stats file written before 2026-09-11 has no such key, and absent is not zero — a row from an
+   * older build simply did not count it, and `checkBudgets` reads `jsBytes` either way.
+   */
+  readonly frameworkJsBytes?: number;
   /**
    * **Written by nothing, `As of 2026-08`.** `apps/web/prerender.ts` is the only producer of this
    * file and it emits static HTML — there is no browser in the build to observe a paint. So the
@@ -212,11 +220,39 @@ export interface MeasuredEntry {
 }
 
 export interface MeasuredJs {
+  /** The app's own executable bytes — what `budget.js` is a promise about. */
   readonly jsBytes: number;
-  /** Every `src=`/`data-x-entry=` module, so a finding can name the heaviest by file. */
+  /** The framework's injected runtime, counted separately so it is reported and never charged. */
+  readonly frameworkBytes: number;
+  /** Every APP `src=`/`data-x-entry=` module, so a finding can name the heaviest by file. */
   readonly entries: readonly MeasuredEntry[];
 }
 
+/**
+ * Scripts the FRAMEWORK injects into a document, which a route's `budget.js` does not answer for.
+ * `budget.js` is a promise about the APP's JavaScript: an author can delete an import, move one
+ * behind `hydrate: 'interaction'` or drop an island, and can do NOTHING about a file the build
+ * writes into every document it renders. Charging it made `js: '0kb'` — the budget `x new`
+ * scaffolds on `site/` — unreachable for any installable app, and the `fix:` it printed named an
+ * import chain of one entry the author never wrote.
+ *
+ * It was also not a stable number. `/x-sw-register.js` is written AFTER the documents that name
+ * it are weighed (`prerender.ts` emits the worker last, because its precache manifest is built
+ * from their content hashes), so a clean `.x/` measured a file that did not exist and recorded 0,
+ * and the next build measured the one before it and recorded 250. Same commit, green then red,
+ * decided by whether anything had cleaned the output directory.
+ *
+ * ENUMERATED, and it is one entry: `serviceWorkerHead` is the only `<script src>` the framework
+ * puts in a prerendered document — measured on a fresh scaffold plus `x g island` and
+ * `x g route`, where `<script src="/x-sw-register.js" defer>` is the only script tag across every
+ * emitted page. Two framework scripts are deliberately NOT here. `render/src/hydrate.ts`'s inline
+ * module runtime is charged, because it exists only when the page ships an island — it is the
+ * cost of the app's own interactivity, and a page with a `0kb` budget has none. `island-props.ts`'
+ * `<script type="application/json">` is already excluded as data, by `carriesJson`. A third one
+ * joins this set by a decision, here, with the same argument.
+ */
+export const FRAMEWORK_SCRIPTS: ReadonlySet<string> = new Set([SW_REGISTER_PATH]);
+
 /**
  * What a rendered document actually makes the browser execute: the bytes of every inline script
  * the parser will run, the size of every file a `src` points at, and the size of every island
@@ -226,6 +262,7 @@ export interface MeasuredJs {
  */
 export async function measureDocumentJs(html: string, out: string): Promise<MeasuredJs> {
   let jsBytes = 0;
+  let frameworkBytes = 0;
   const entries: MeasuredEntry[] = [];
   // Deduped ONCE, across both readers below, and the unit is the FETCH: a browser downloads a URL
   // once however many times the document names it, so `budget.js` — a byte budget — counts it
@@ -247,6 +284,14 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     fetched.add(url);
     const file = Bun.file(join(out, url.slice(1)));
     const bytes = (await file.exists()) ? file.size : 0;
+    // Counted and set aside, not skipped: the bytes are real and a reader is owed the number.
+    // Kept out of `entries` as well as out of `jsBytes`, because `entries` is what a finding reads
+    // to name the heaviest import — and on a fresh scaffold every route's `heaviestChain` was
+    // `/x-sw-register.js`, a file the author cannot edit, delete or move.
+    if (FRAMEWORK_SCRIPTS.has(url)) {
+      frameworkBytes += bytes;
+      return;
+    }
     entries.push({ url, bytes });
     jsBytes += bytes;
   };
@@ -266,7 +311,7 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
     if (url === undefined) continue;
     await weigh(url);
   }
-  return { jsBytes, entries };
+  return { jsBytes, frameworkBytes, entries };
 }
 
 /**

package/src/cmd-doctor.ts

@@ -3,14 +3,20 @@
 // work back to the reader.
 
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join, resolve, sep } from 'node:path';
 import {
   ENV_EXAMPLE_PATH,
   ERROR_DOCS_URL,
   tryResolveEnvironment,
   usesDevCursorSecret,
 } from '@ultimat3/core';
-import { checkDb, createPostgresClient } from '@ultimat3/db';
+import {
+  checkDb,
+  createPostgresClient,
+  PGLITE_FIX,
+  PGLITE_MISSING,
+  PGLITE_PACKAGE,
+} from '@ultimat3/db';
 import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/storage';
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
@@ -61,6 +67,16 @@ export interface DoctorProbe {
    * correctly answered `X_DB_UNAVAILABLE` (#F5).
    */
   database(): Promise<Finding | null>;
+  /**
+   * Is the EMBEDDED database usable, and is it the one this environment would open? A FACT and not
+   * a finding, the split `offlineFallback` makes below: reaching a module resolver is IO, and what
+   * an unresolvable optional peer MEANS is a pure rule with a pure test.
+   *
+   * `database()` answers `null` the moment `DATABASE_URL` is unset — which is exactly a bare VM,
+   * the configuration `x dev` invents a database FOR — so until this existed `x doctor` was silent
+   * about the only database a fresh box has. `bin/setup` found out instead, at `x db migrate`.
+   */
+  embeddedDatabase(): Promise<EmbeddedDatabase>;
   drift(): Promise<readonly Finding[]>;
   /**
    * The other half of the migrations directory: a newest migration with no `.snapshot.json`, which
@@ -76,11 +92,40 @@ export interface DoctorProbe {
   offlineFallback(): Promise<OfflineFallbackFact>;
 }
 
+/** What `x doctor` reads about the embedded database, without opening it. */
+export interface EmbeddedDatabase {
+  /**
+   * True while `DATABASE_URL` is unset or blank — the condition that makes PGlite the app's
+   * database (`resolveServices`), and the same reading `probeDatabase` returns `null` on.
+   */
+  readonly selected: boolean;
+  /** Does `@electric-sql/pglite` resolve from the app root? */
+  readonly resolved: boolean;
+}
+
 const finding = (code: string, cause: string, fix: string, at?: string): Finding =>
   at === undefined
     ? { code, cause, fix, docs: ERROR_DOCS_URL }
     : { code, cause, fix, docs: ERROR_DOCS_URL, at };
 
+/**
+ * The rule, pure. Red only where the embedded database is the one that would be opened: an app
+ * pointed at a real Postgres never loads PGlite, and a finding about an absent optional peer there
+ * is noise the reader learns to skim.
+ *
+ * `@ultimat3/db`'s own refusal, not a CLI twin of it — same `X_DB_UNAVAILABLE`, same sentence,
+ * same runnable fix. The package already says this the moment a query arrives; `x doctor` is what
+ * says it before `bin/setup` gets that far.
+ */
+export const embeddedDatabaseFinding = (fact: EmbeddedDatabase): Finding | undefined =>
+  fact.selected && !fact.resolved
+    ? finding(
+        'X_DB_UNAVAILABLE',
+        `${PGLITE_MISSING} — and DATABASE_URL is unset or blank, so the embedded one is the database this app would open`,
+        PGLITE_FIX,
+      )
+    : undefined;
+
 /** The file `x doctor` reports missing, and the one the reader creates. */
 export const ENV_DEVELOPMENT = '.env.development';
 
@@ -229,6 +274,10 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   if (offline !== undefined) findings.push(offline);
   const database = await probe.database();
   if (database !== null) findings.push(database);
+  // The other half of the same question, and the half a bare VM lands on: `database()` is silent
+  // where there is no `DATABASE_URL`, and that silence IS the bare-VM configuration.
+  const embedded = embeddedDatabaseFinding(await probe.embeddedDatabase());
+  if (embedded !== undefined) findings.push(embedded);
   findings.push(...(await probe.drift()));
   // Last, and it is why `X_CLI_UNEXPECTED`'s `fix: x doctor --json` is not a dead end on the path an
   // author reaches it from: `x db gen` throwing `X_MIGRATION_SNAPSHOT_MISSING` used to be a
@@ -249,6 +298,45 @@ export const doctorPort = (args: ParsedArgs): number =>
     DEFAULT_DOCTOR_PORT,
   );
 
+/**
+ * `DATABASE_URL` as BOTH halves of the database question read it: unset and blank are one case.
+ * One seam, because the two halves are complementary — a second reading of the same variable is
+ * how a configuration ends up reported by neither probe, or by both.
+ */
+const externalUrl = (raw: string | undefined): string | undefined =>
+  raw === undefined || raw.trim() === '' ? undefined : raw;
+
+/**
+ * Is the optional peer INSTALLED for this app — a `node_modules` walk up from the app root.
+ *
+ * Never an IMPORT: loading PGlite boots 26 MB of WASM and takes the single-writer lock the next
+ * command needs, and a diagnostic must not be the reason `x dev` cannot open the database it just
+ * reported on.
+ *
+ * Never `Bun.resolveSync` either, which was this check's first draft. It falls back to Bun's
+ * machine-global install cache: measured 2026-09-11 against a freshly scaffolded app with no
+ * `node_modules` anywhere above it, `Bun.resolveSync('@electric-sql/pglite', <app>)` answered
+ * `~/.bun/install/cache/@electric-sql/pglite@0.5.8@@@1/dist/index.js` — a version the app does not
+ * depend on, in a directory `bun install` never wrote for it. A box that had downloaded the package
+ * ONCE, for anything, would have read as ready on every app after it, which is the exact opposite
+ * of the question. The walk asks what `bun add` answers, and nothing else.
+ *
+ * Up from the root and not at it, because an app checked out inside a larger workspace is installed
+ * by the hoisting one: `examples/dummy` in this repository has no `node_modules` of its own.
+ */
+const installedAbove = (dir: string, specifier: string): boolean => {
+  let current = resolve(dir);
+  // Bounded by the path itself — one segment per step — rather than by `for (;;)` and the promise
+  // that `dirname('/')` is `/`. The loop still stops on that, one step earlier.
+  for (let remaining = current.split(sep).length; remaining > 0; remaining -= 1) {
+    if (existsSync(join(current, 'node_modules', specifier, 'package.json'))) return true;
+    const parent = dirname(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+  return false;
+};
+
 /**
  * A real `select 1` through the app's own driver, not a TCP connect: a running Postgres with the
  * wrong credentials or a database that does not exist accepts the socket and refuses the session,
@@ -258,7 +346,7 @@ export const doctorPort = (args: ParsedArgs): number =>
  * next `x db migrate` cannot have.
  */
 async function probeDatabase(url: string | undefined): Promise<Finding | null> {
-  if (url === undefined || url.trim() === '') return null;
+  if (externalUrl(url) === undefined) return null;
   const client = createPostgresClient({ url, applicationName: 'x-doctor' });
   try {
     const report = await checkDb(client);
@@ -296,6 +384,12 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     exists: (relativePath) => (root === undefined ? false : existsSync(join(root, relativePath))),
     portFree,
     database: () => probeDatabase(process.env['DATABASE_URL']),
+    // `root ?? cwd` because the walk needs a directory that exists; outside an app `runDoctor`
+    // returns on `X_NOT_IN_APP` before this is ever asked, so the value only has to be honest.
+    embeddedDatabase: async () => ({
+      selected: externalUrl(process.env['DATABASE_URL']) === undefined,
+      resolved: installedAbove(root ?? cwd, PGLITE_PACKAGE),
+    }),
     drift: async () => (root === undefined ? [] : checkMigrationDrift(root)),
     snapshots: async () => (root === undefined ? [] : checkMigrationSnapshots(root)),
     // `routes: undefined` outside an app is "not judged", which is what the caller already is:

package/src/index.ts

@@ -67,8 +67,14 @@ export type { DeployPlan } from './cmd-deploy';
 export { deployCommand, planDeploy } from './cmd-deploy';
 export type { DevServer, StartDevOptions } from './cmd-dev';
 export { devCommand, startDev } from './cmd-dev';
-export type { DoctorProbe } from './cmd-doctor';
-export { doctorCommand, ENV_DEVELOPMENT, probeFor, runDoctor } from './cmd-doctor';
+export type { DoctorProbe, EmbeddedDatabase } from './cmd-doctor';
+export {
+  doctorCommand,
+  ENV_DEVELOPMENT,
+  embeddedDatabaseFinding,
+  probeFor,
+  runDoctor,
+} from './cmd-doctor';
 export { ERRORS_SUBCOMMANDS, errorsCommand } from './cmd-errors';
 export { FIX_SUBCOMMANDS, fixCommand } from './cmd-fix';
 export type { GenerateOptions, Generator } from './cmd-generate';

package/src/prerender.ts

@@ -28,6 +28,7 @@ import {
   SW_REGISTER_PATH,
   serviceWorkerArtifacts,
   serviceWorkerHead,
+  serviceWorkerRegistration,
 } from './sw-artifacts';
 
 // Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
@@ -194,6 +195,17 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // header). `serviceWorkerHead` is the one predicate behind both, so a page can never name a
   // script the export does not carry.
   const swHead = pwa === undefined ? undefined : serviceWorkerHead(pwa);
+  // The registration's BYTES now too, and not beside `sw.js` at the end. Every document below
+  // names this file and `measureDocumentJs` weighs it off disk, so writing it last made the
+  // measurement read whatever happened to be there: nothing on a clean `out` (recorded as 0) and
+  // the PREVIOUS build's copy on a reused one. That is the run-order dependence the `jsBytes`
+  // split removed, and it came straight back in `frameworkJsBytes` because the field changed and
+  // the ORDER did not. `serviceWorkerRegistration()` depends on two constants and no document, so
+  // it has nothing to wait for; `sw.js` still comes last, because its precache manifest really is
+  // built from the hashes of pages that do not exist yet.
+  if (swHead !== undefined) {
+    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorkerRegistration());
+  }
   if (pwa !== undefined) {
     await Bun.write(join(options.out, WEB_MANIFEST_PATH.slice(1)), pwa.body);
     // And the icons that manifest NAMES. A static host runs no `assetRoutes()`, so every
@@ -252,6 +264,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         routes.push({
           path: entry.path,
           jsBytes: measured.jsBytes,
+          frameworkJsBytes: measured.frameworkBytes,
           ...(chain === undefined ? {} : { heaviestChain: chain }),
         });
       } catch (error) {
@@ -314,6 +327,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       heaviest = {
         path: entry.path,
         jsBytes: measured.jsBytes,
+        frameworkJsBytes: measured.frameworkBytes,
         ...(chain === undefined ? {} : { heaviestChain: chain }),
       };
     }
@@ -334,9 +348,10 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
           styles,
           documents,
         });
+  // `sw.js` only: `serviceWorker.register` IS `serviceWorkerRegistration()`, already on disk above
+  // and identical by construction. A second writer of one path is how the two could ever disagree.
   if (serviceWorker !== undefined) {
     await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
-    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorker.register);
   }
   const stats = await writeBuildStats(options.root, { routes });
   // Written LAST and by the same call that writes the stats, so an app whose `prerender.ts` does

package/src/sw-artifacts.ts

@@ -129,8 +129,15 @@ const staticAssets = (islands: IslandBundle, styles: StyleBundle): readonly Prec
  * silently controls a subdirectory. The `catch` because a registration that throws in a browser
  * with service workers disabled — an incognito profile, an enterprise policy — must not take an
  * otherwise working page down with it.
+ *
+ * EXPORTED because a static export has to put these bytes on disk BEFORE it renders, not after.
+ * The file is named by every document and weighed by `measureDocumentJs`, and it used to be
+ * written last, beside `sw.js` — so the measurement read a file that did not exist yet on a clean
+ * output directory, and the PREVIOUS build's copy on a reused one. `sw.js` still comes last, for
+ * the reason its own comment gives (its precache manifest is built from the rendered documents'
+ * content hashes); this half depends on nothing but two constants, so it can and must come first.
  */
-const registerSource = (): string =>
+export const serviceWorkerRegistration = (): string =>
   `if ('serviceWorker' in navigator) {
   addEventListener('load', function () {
     navigator.serviceWorker
@@ -199,7 +206,7 @@ export function serviceWorkerArtifacts(
   );
   return {
     source: output.source,
-    register: registerSource(),
+    register: serviceWorkerRegistration(),
     head,
     precache: output.precache,
     // `output.warnings` IS `output.precache.warnings` — the generator returns the manifest's list

package/src/templates/github/ci.yml.ts

@@ -0,0 +1,74 @@
+// The CI half of what `x new` writes: one workflow that runs the app's OWN two commands.
+//
+// Nothing under `templates/` emitted `.github` until this file, so every scaffolded app started
+// life with a gate that ran on exactly one machine — the author's. The two commands are `bin/setup`
+// and `bin/check` and NOT a restatement of their steps: a workflow that spelled out `bun install`,
+// `x db migrate`, `x build` and `x verify` is a second definition of the gate, free to drift from
+// the scripts a human runs, and axiom 1 has one way to do each thing. `bin/check` is also not a
+// synonym for `x verify` — it BUILDS first, and the build is what makes the gate's `budgets` step
+// measurable rather than X_BUDGET_UNMEASURED.
+
+import { REQUIRED_BUN } from '../../app-root';
+import type { GeneratedFile, NameSet } from '../naming';
+
+/** Where the workflow lands. GitHub reads this path and no other. */
+export const CI_WORKFLOW_PATH = '.github/workflows/ci.yml';
+
+/**
+ * Pinned by commit SHA with the version in the trailing comment, because this step runs before any
+ * code of yours does and `@v2` is a tag its owner can move. `actions/*` follows its major tag
+ * instead: GitHub owns the runner and the tag together. Same rule the framework's own
+ * `.github/actions/setup/action.yml` states, and the same SHA.
+ */
+const SETUP_BUN = 'oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0';
+
+const ci = (app: NameSet): string => `name: ci
+
+# The gate for ${app.kebab}: the same two commands \`README.md\` tells a human to run, in the same
+# order, on a machine that has never seen this repository. A check that exists only in CI is one
+# nobody can reproduce locally, and a CI file that restates the gate's steps is a second gate.
+#
+# \`bin/check\` is \`x build --target static\` and THEN \`x verify\`. The build is not a convenience:
+# the gate's \`budgets\` step compares declared limits against measured bytes in
+# \`.x/build-stats.json\`, so a run with no build reports X_BUDGET_UNMEASURED. Run \`x verify\` here
+# instead and this workflow is red for a reason that has nothing to do with the commit.
+#
+# No \`services:\` block, deliberately — \`bin/setup\` brings up embedded Postgres in-process, so
+# there is nothing to provision and nothing to wait on. Add one the day this app needs a real
+# server, beside the \`DATABASE_URL\` that selects it.
+
+# EVERY push, not just the default branch's. \`x new\` runs a plain \`git init\` and takes whatever
+# \`init.defaultBranch\` this machine already agreed on, so a \`branches: [main]\` filter silently
+# runs nothing on a repository whose branch is called something else — and \`CLAUDE.md\` promises a
+# run on every push, which a filter would make untrue for the app that read it.
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    # A bound on a HANG, not on cost: a step that never returns holds a runner until GitHub's
+    # six-hour default expires, and the failure is invisible for all six of them.
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ${SETUP_BUN}
+        with:
+          # \`package.json\`'s \`engines.bun\` floor, exactly — the OLDEST runtime this app declares
+          # it supports, so a call that needs a newer Bun fails here rather than in the install of
+          # whoever took the app at its word. Never \`latest\`: a Bun minor landing unannounced is a
+          # runtime change nobody chose.
+          bun-version: '${REQUIRED_BUN}'
+      # Two steps rather than one \`&&\`, so the log names which half failed and times each.
+      - run: bin/setup
+      - run: bin/check
+`;
+
+/** The CI a new app is born with, in the order a reader meets it. */
+export function githubFiles(app: NameSet): readonly GeneratedFile[] {
+  return [{ path: CI_WORKFLOW_PATH, contents: ci(app) }];
+}

package/src/templates/scaffold-claude-commands.ts

@@ -6,7 +6,7 @@
 import type { GeneratedFile, NameSet } from './naming';
 
 const feature = (app: NameSet): string => `---
-description: Build or fix one thing in ${app.kebab} end to end — name the primitive, generate it, wire it inside the boundaries, gate it with \`x verify\`.
+description: Build or fix one thing in ${app.kebab} end to end — name the primitive, generate it, wire it inside the boundaries, gate it with \`bin/check\`.
 argument-hint: <what you want built or fixed, plain language>
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, Skill
 ---
@@ -16,7 +16,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, Skill
 You are a senior engineer on **${app.kebab}**, an Ultimate app. Read \`AGENTS.md\` before designing
 anything — it is the short form of every rule below, and it wins where the two disagree.
 
-**Done means \`x verify\` green.** A passing unit test is not done. A working \`x dev\` is not done.
+**Done means \`bin/check\` green.** A passing unit test is not done. A working \`x dev\` is not done.
 Report what you actually ran, never what you assume passed.
 
 ## Request
@@ -77,10 +77,16 @@ the filename never is. One interactive control on a 0kb page is an island: \`x g
 ## 4. Gate it
 
 \`\`\`sh
-x verify                # the gate. green = shippable
-x verify --json         # the same steps, machine-readable
+bin/check               # the gate. green = shippable
+bin/check --json        # the same, machine-readable
 \`\`\`
 
+\`bin/check\` is \`x build --target static\` and THEN \`x verify\`, and the order is the whole point:
+the \`budgets\` step measures \`.x/build-stats.json\`, which only a build writes, so \`x verify\` on
+its own reports X_BUDGET_UNMEASURED on a tree that is fine. \`--json\` is forwarded to both halves;
+a machine consumer takes the last line. CI runs this same script — \`.github/workflows/ci.yml\` is
+\`bin/setup\` and then \`bin/check\`, nothing else.
+
 Red is instructions, not a verdict: **every finding carries an executable \`fix:\` — run it verbatim
 before improvising**, and \`x errors explain <CODE>\` expands any code it names. Never narrow the gate
 to make it pass: there is no \`--only\` and no \`--skip\`, on purpose, and disabling a lint rule or
@@ -112,7 +118,7 @@ ISO code, never a float. Bun only.
 Primitive:  <which of the eight>    Slice: <dir>
 Generated:  <the x g invocations you ran>
 Changed:    <files>
-Gate:       x verify ✓ | ✗ <failing steps>
+Gate:       bin/check ✓ | ✗ <failing steps>
 Deferred:   <what you did not do, and why>      [never omit this line]
 \`\`\`
 `;
@@ -166,7 +172,7 @@ slice it lives in. If it fits none, the design is wrong — say so here instead
 - What to add, next to the source as \`<file>.test.ts\`. Command to run it.
 
 ## Done when
-- Acceptance criteria, ending in \`x verify\` green.
+- Acceptance criteria, ending in \`bin/check\` green.
 
 ## Risks
 - Anything the executor must decide, and every claim in the ask the code disproves.
@@ -179,7 +185,7 @@ slice it lives in. If it fits none, the design is wrong — say so here instead
 - No checkboxes. The plan is a map, not a tracker.
 - The plan must obey the app's own rules — one way to do each thing, generators over hand-written
   files, imports that never cross a surface boundary, a stable error code with a runnable \`fix:\` for
-  every new failure, and \`x verify\` green as the last line of *Done when*.
+  every new failure, and \`bin/check\` green as the last line of *Done when*.
 
 ## Output
 
@@ -196,13 +202,18 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 
 # /verify
 
-Run \`x verify\`.
+Run \`bin/check\`.
+
+It is \`x build --target static\` and then \`x verify\`, and it is THE gate — the one CI runs
+(\`.github/workflows/ci.yml\`) and the one \`README.md\` names. \`x verify\` alone is half of it:
+the \`budgets\` step measures \`.x/build-stats.json\`, which only the build writes, so a bare
+\`x verify\` reports X_BUDGET_UNMEASURED on a tree with nothing wrong with it.
 
 Green: say so and stop.
 
 Red: fix every finding, then re-run until green. Each finding carries a stable code, a cause and an
 executable \`fix:\` — **run the \`fix:\` verbatim before improvising**, and use \`x errors explain <CODE>\`
-when the cause is not enough. \`x verify --json\` gives the same steps machine-readably; \`x doctor\`
+when the cause is not enough. \`bin/check --json\` gives the same steps machine-readably; \`x doctor\`
 covers the case where the environment, not the code, is what is broken.
 
 Do not narrow the gate to make it pass. There is no \`--only\` and no \`--skip\`; disabling a lint rule,

package/src/templates/scaffold-docs.ts

@@ -2,9 +2,11 @@
 // 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`; the
-// `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`.
+// `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`; the one workflow is
+// `github/ci.yml.ts`.
 
 import { LINE_CEILING } from '../workspace-checks';
+import { githubFiles } from './github/ci.yml';
 import type { GeneratedFile, NameSet } from './naming';
 import { claudeFiles } from './scaffold-claude';
 import { containerFiles } from './scaffold-container';
@@ -19,7 +21,7 @@ not exist — five of these had an empty column and were each measured green on
 
 | Rule | Detail | Refused by |
 |---|---|---|
-| One gate | \`x verify\` — green means shippable. Never merge red. | the gate itself |
+| One gate | \`bin/check\` — \`x build\` and then \`x verify\`. Green means shippable; never merge red. | the gate itself, and \`.github/workflows/ci.yml\` on every push and pull request |
 | One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` | review |
 | Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf | \`X_BOUNDARY_SITE_TO_APP\` |
 | Data | routes call actions and queries; only \`repo.ts\` touches the database | \`X_BOUNDARY_ROUTE_TO_DB\` |
@@ -54,7 +56,19 @@ see, and the type already fires — measured, \`price: 19.99\` in a seed is
 \`TS2322: Type 'number' is not assignable to type 'MoneyInput'\`. A guard that pretended to check
 it would be worse than the type that really does.
 
-Commands: \`x dev\`, \`x verify\`, \`x g <primitive>\`, \`x g guard <name>\`, \`x db branch create <name>\`, \`x doctor\`.
+\`bin/check\` is the gate and \`x verify\` is only its second half: the first is
+\`x build --target static\`, and the build is what writes the \`.x/build-stats.json\` the
+\`budgets\` step measures. Run \`x verify\` on a tree nobody has built and \`budgets\` is red with
+X_BUDGET_UNMEASURED — the gate reporting on a file that does not exist, not on your code.
+
+The platform's \`.dz/\` is ADDITIVE, in both directions. developerz.ai keeps its own files under
+\`.dz/maintainer/\` and \`.dz/pipeline/\`; nothing \`x new\` writes lands under \`.dz/\` and nothing
+here is generated from it. So the scaffold never clobbers a maintainer policy, the platform never
+clobbers \`AGENTS.md\`, \`bin/\`, \`.claude/\` or \`.github/\`, and deleting either side leaves the
+other exactly as it was.
+
+Commands: \`bin/setup\`, \`bin/dev\`, \`bin/check\`, \`x g <primitive>\`, \`x g guard <name>\`,
+\`x db branch create <name>\`, \`x doctor\`.
 
 Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
 `;
@@ -63,7 +77,12 @@ const claude = (app: NameSet): string => `# CLAUDE.md
 
 ${app.kebab} — Ultimate app. Read AGENTS.md first; it is the same content in the same order.
 
-- Gate: \`x verify\` (add \`--json\` for machine output).
+- Gate: \`bin/check\` (add \`--json\` for machine output — it reaches both halves). It is
+  \`x build --target static\` and then \`x verify\`; \`x verify\` alone leaves \`budgets\` with
+  nothing to measure. \`.github/workflows/ci.yml\` runs \`bin/setup && bin/check\` on every push
+  and pull request, so CI and your terminal run the same two commands.
+- \`.dz/\` belongs to the developerz.ai platform and is additive both ways: the scaffold writes
+  nothing there, and nothing there is generated from this repo. Neither side clobbers the other.
 - Scaffold, do not hand-write: \`x g <kind> <name>\` — \`x g --help\` lists every kind, and is the
   only place that list is stated.
 - Destructive DB work goes in a branch: \`x db branch create <name>\`, never the shared dev DB.
@@ -83,7 +102,7 @@ Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Post
 \`\`\`sh
 bin/setup     # prerequisites, deps, env, the first migration, migrate, seed, the manifest
 bin/dev       # all roles in one process, embedded Postgres, /_x mounted
-bin/check     # the gate: typecheck, lint, boundaries, tests, drift, budgets
+bin/check     # the gate: a static build, then typecheck, lint, boundaries, tests, drift, budgets
 \`\`\`
 
 \`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bin/setup\` runs
@@ -102,6 +121,7 @@ with \`X_DB_DRIFT\`, and that is the fix it names.
 | \`packages/*\` | domain, db, i18n, ui, mcp |
 | \`app.config.ts\` | the one config file |
 | \`x.manifest.json\` | generated facts: routes, actions, jobs, policies |
+| \`.github/workflows/ci.yml\` | \`bin/setup\` then \`bin/check\`, on push and pull request |
 `;
 
 const binSetup = (): string => `#!/usr/bin/env bash
@@ -204,6 +224,10 @@ export function docsFiles(app: NameSet): readonly GeneratedFile[] {
     // The harness half of the same job AGENTS.md does. It lands in the app's own repo rather than
     // in a global config, so it is visible in the scaffold's diff and deletable in one line.
     ...claudeFiles(app),
+    // The same two commands `README.md` opens with, run by a machine that has never seen this
+    // repository. Registered here and not in `scaffold-repo.ts` because it is documentation of the
+    // gate in executable form, which is the job this file has.
+    ...githubFiles(app),
     ...containerFiles(app),
   ];
 }

package/src/templates/scaffold-repo.ts

@@ -5,6 +5,7 @@
 // container files scaffold-container.ts.
 
 import { ENV_EXAMPLE_PATH } from '@ultimat3/core';
+import { REQUIRED_BUN } from '../app-root';
 import { VERIFY_FLOOR_FILE } from '../verify-floor';
 import type { VerifyStepName } from '../verify-step';
 import type { GeneratedFile, NameSet } from './naming';
@@ -37,6 +38,14 @@ const BIOME_VERSION = '2.5.8';
  */
 const TYPESCRIPT_VERSION = '^7.0.2';
 
+// `engines.bun` is `REQUIRED_BUN`, the floor the SHIPPED `x` enforces
+// (`packages/cli/src/app-root.ts`), and not a second literal. It was one: `>=1.3.0`, a whole minor
+// BELOW the CLI the app then runs, so on a box with Bun 1.3.x `bun install` succeeded and the very
+// next line of `bin/setup` died `X_BUN_VERSION: Bun 1.3.14 is older than the required 1.4.0` — a
+// floor admitting a runtime the app's own first command refuses. Interpolated, the two cannot
+// disagree; `scripts/bun-pin.test.ts` reads the emitted string as one more pin site, and
+// `github/ci.yml.ts` pins the workflow's Bun to the same constant.
+//
 // `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.
@@ -89,7 +98,7 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "solid-js": "1.9.14"
   },
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=${REQUIRED_BUN}"
   }
 }
 `;