@ultimat3/cli 9.0.0 → 11.0.0

package/src/metrics-endpoint.ts

@@ -11,7 +11,6 @@ import {
   stringField,
   UltimateError,
 } from '@ultimat3/core';
-import { docsFor } from './error-codes';
 import { neighbouringPort } from './flag-number';
 
 /**
@@ -44,7 +43,6 @@ export class MetricsPortInUseError extends UltimateError {
       code: 'X_PORT_IN_USE',
       cause: `the metrics port ${input.port} is already bound, so no role could open its scrape listener`,
       fix: `METRICS_PORT=${neighbouringPort(input.port)} x dev --json`,
-      docs: docsFor('X_PORT_IN_USE'),
     });
   }
 }

package/src/output.ts

@@ -2,7 +2,7 @@
 // and the JSON renderer are projections of it, so `--json` can never drift from the terminal
 // output (axiom 4). The human renderer owns the canonical 3-line error format.
 
-import { renderThrowable, singleLine, stringField } from '@ultimat3/core';
+import { ERROR_DOCS_URL, renderThrowable, singleLine, stringField } from '@ultimat3/core';
 import { msg } from './messages';
 
 export interface Finding {
@@ -107,7 +107,7 @@ export function findingFrom(value: unknown): Finding {
     code: 'X_CLI_UNEXPECTED',
     cause: renderThrowable(value),
     fix: 'x doctor --json',
-    docs: 'https://ultimate.dev/errors/X_CLI_UNEXPECTED',
+    docs: ERROR_DOCS_URL,
   };
 }
 

package/src/prerender.ts

@@ -4,7 +4,7 @@
 // only which routes qualify and where the bytes land.
 
 import { join } from 'node:path';
-import { renderThrowable } from '@ultimat3/core';
+import { createContext, renderThrowable, runWithContext } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
 import { routeEntries } from '@ultimat3/render';
 import { renderStatic } from '@ultimat3/render/server';
@@ -13,11 +13,17 @@ import { appManifest } from './app-manifest';
 import type { RouteStats } from './budgets';
 import { measureDocumentJs, writeBuildStats } from './budgets';
 import { routeDocument } from './dev-render';
+import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
+import { FAVICON_PATH, faviconBytes } from './favicon';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
-import type { SkippedRoute } from './static-report';
+import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 
+// Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
+// carries it, and this file already imports that module.
+export type { UnmeasuredRoute };
+
 /**
  * `static` only. `isr` revalidates and `ssr`/`stream` need a process, so writing any of them to
  * disk would publish a page whose staleness nothing can correct — and the route already declared
@@ -46,12 +52,6 @@ export interface PrerenderedPage {
   readonly bytes: number;
 }
 
-/** A route that declared a budget and could not be rendered here, and what stopped it. */
-export interface UnmeasuredRoute {
-  readonly path: string;
-  readonly reason: string;
-}
-
 export interface PrerenderReport {
   readonly out: string;
   readonly buildId: string;
@@ -97,6 +97,9 @@ function heaviestSource(
 
 export const DEFAULT_ORIGIN = 'https://localhost';
 
+/** The one status a static export can answer for itself: a path that matches no file. */
+const NOT_FOUND_STATUS = 404;
+
 /**
  * Prerendering and measuring are two questions, and conflating them made `X_BUDGET_UNMEASURED`
  * unclosable by any invocation: only `static` was ever rendered, so a `budget:` on an ssr, isr,
@@ -129,6 +132,37 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // behind it, so the artifact carries every byte the browser will ask for.
   const islands = await buildIslands(options.root);
   await writeIslands(islands, options.out);
+  // Same rule, one asset further: a browser asks for `/favicon.ico` on the first page it loads,
+  // and a static export has no route to answer it — so the bytes the served surfaces would have
+  // returned go into the artifact instead of leaving a 404 in every visitor's console.
+  await Bun.write(
+    join(options.out, FAVICON_PATH.slice(1)),
+    (await faviconBytes(options.root)).bytes,
+  );
+  // And the one error page a static host serves ITSELF: `404.html` at the export root is what S3,
+  // Cloudflare Pages, Netlify and nginx all reach for when a path matches no file. The app's own
+  // file if it wrote one, the framework's page otherwise — the same two rungs the served process
+  // answers a 404 with, so the artifact and the server cannot disagree about one document.
+  await Bun.write(
+    join(options.out, STATIC_ERROR_PAGE),
+    await errorPageDocument(options.root, NOT_FOUND_STATUS),
+  );
+
+  // Every render below goes through `routeDocument`, which is the function a REQUEST reaches — and
+  // a request arrives inside `runWithContext`, installed by the HTTP pipeline (`dev-render.ts`).
+  // Called bare, any route whose component, `load` or `meta` reads `useContext()` threw
+  // `X_NO_CONTEXT`: measured against `examples/dummy`, `/posts/new` and `/settings` were filed
+  // unmeasured for that reason alone, and a `render: 'static'` route reading it failed the whole
+  // build. One context for the build, `role: 'web'` because that is the role serving these
+  // documents, and this build's own id so a component reading `ctx.buildId` stamps the artifact
+  // with the id the report and the stats carry.
+  const ctx = createContext({ role: 'web', buildId });
+  const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
+    runWithContext(ctx, () =>
+      routeDocument(entry, data, {
+        resolveIsland: (file: string) => islands.resolverFor(file),
+      }),
+    );
 
   for (const entry of routeEntries()) {
     const facts = { surface: entry.surface, render: entry.config.render, route: entry.path };
@@ -141,11 +175,10 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       // routes it never used to touch would be a worse regression than the gap it closes. A route
       // that will not render here is reported, gets no stats entry, and stays `X_BUDGET_UNMEASURED`.
       try {
-        const html = await routeDocument(
-          entry,
-          { url: new URL(entry.path, origin).href, params: {} },
-          { resolveIsland: (file: string) => islands.resolverFor(file) },
-        );
+        const html = await document(entry, {
+          url: new URL(entry.path, origin).href,
+          params: {},
+        });
         const measured = await measureDocumentJs(html, options.out);
         const chain = heaviestSource(islands, measured.entries);
         routes.push({
@@ -162,12 +195,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     }
     const artifacts = await renderStatic(
       entry,
-      ({ path, params }) =>
-        routeDocument(
-          entry,
-          { url: new URL(path, origin).href, params },
-          { resolveIsland: (file: string) => islands.resolverFor(file) },
-        ),
+      ({ path, params }) => document(entry, { url: new URL(path, origin).href, params }),
       { buildId },
     );
     // `enumeratePrerender` answers `[]` for a dynamic route with no `prerender()`, so a
@@ -178,6 +206,13 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       skipped.push(skippedRoute(facts, 'no-prerender-paths'));
       continue;
     }
+    // One stats row per ROUTE, holding its heaviest page. `checkBudgets` looks a route up by
+    // `route.url`, which is the manifest's DECLARED pattern (`/blog/:slug`), and this pushed the
+    // FILLED path (`/blog/hello`) — so no dynamic static route has ever been weighed: every one
+    // was `X_BUDGET_UNMEASURED` and `X_BUDGET_EXCEEDED` could not fire for the whole class. The
+    // heaviest page and not the first, because a budget is a ceiling: the page that breaks it is
+    // the one the route has to answer for. `pages` below still names every filled path.
+    let heaviest: RouteStats | undefined;
     for (const artifact of artifacts) {
       const file = join(options.out, artifact.outputPath);
       const bytes = await Bun.write(file, artifact.html);
@@ -192,12 +227,14 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       // declared budget against bytes that exist on disk rather than against a graph's estimate.
       const measured = await measureDocumentJs(artifact.html, options.out);
       const chain = heaviestSource(islands, measured.entries);
-      routes.push({
-        path: artifact.path,
+      if (heaviest !== undefined && heaviest.jsBytes >= measured.jsBytes) continue;
+      heaviest = {
+        path: entry.path,
         jsBytes: measured.jsBytes,
         ...(chain === undefined ? {} : { heaviestChain: chain }),
-      });
+      };
     }
+    if (heaviest !== undefined) routes.push(heaviest);
   }
   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
@@ -209,6 +246,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     buildId,
     emitted: pages.map((page) => ({ route: page.route, path: page.path, file: page.file })),
     skipped,
+    // The list `X_BUDGET_UNMEASURED`'s `fix:` cites by name. It rode home on the in-process
+    // `PrerenderReport` and nowhere else, and `cmd-build.ts` discards a successful subprocess's
+    // stdout — so the one command the finding tells an author to run printed no `unmeasured` key
+    // and no reason. Written into the report is what makes the instruction true.
+    unmeasured,
   });
   return {
     out: options.out,

package/src/script-csp.ts

@@ -0,0 +1,17 @@
+// Every inline `<script>` body a served process can put in a document, as the `script-src` sources
+// that admit it. The mirror of `style-csp.ts`, and needed for the same reason: `script-src` was
+// `'self' 'wasm-unsafe-eval'` while every document carrying an island shipped the hydration runtime
+// INLINE, so under the enforced policy a container serves (`dev: false`) no island ever booted —
+// invisible in `x dev`, where the policy is report-only.
+
+import { cspHashSource } from '@ultimat3/http';
+import { HYDRATE_RUNTIME_BODIES } from '@ultimat3/render';
+
+/**
+ * Hashes, never a nonce: a `render: 'static'` page is a file on disk, so no per-response value can
+ * reach it. Read from `@ultimat3/render`'s own enumeration rather than restated here — the body
+ * the document carries and the body the policy hashes have to be one string.
+ */
+export function inlineScriptSources(): readonly string[] {
+  return [...new Set(HYDRATE_RUNTIME_BODIES.map(cspHashSource))].sort();
+}

package/src/serve.ts

@@ -328,6 +328,9 @@ async function bootRoles(boot: {
     // Same declaration `x dev` reads. Without it a container answers a browser that opened a
     // guarded page with the problem document, rendered as raw JSON in the viewport.
     signInPath: await loadSignInPath(options.root),
+    // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
+    // process and `x dev` cannot answer a browser differently.
+    root: options.root,
     http: CONTAINER_BINDING,
     ...(options.runtime === undefined ? {} : { overrides: options.runtime }),
   });
@@ -367,6 +370,14 @@ export async function runRole(options: ServeOptions): Promise<StartedApp> {
   }
   const app = await serveApp({ ...options, role });
   logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
-  await holdUntilShutdown('serve', () => app.stop())();
+  // `exit` because this is the one entry point with nothing above it: `bin.ts` ends in
+  // `process.exit(code)` and `apps/web/server.ts` — which is what awaits this — does not. One
+  // non-unref'd interval anywhere in the app then holds an event loop that has nothing left to do,
+  // until `terminationGracePeriodSeconds` runs out and the kubelet SIGKILLs a drained process.
+  await holdUntilShutdown('serve', () => app.stop(), {
+    exit: (code) => {
+      process.exit(code);
+    },
+  })();
   return app;
 }

package/src/static-report.ts

@@ -48,6 +48,19 @@ export type SkippedRoute = RouteFacts & {
   readonly why: string;
 };
 
+/**
+ * A route that declared a budget and could not be rendered here, and what stopped it.
+ *
+ * Declared HERE and not in `prerender.ts`, though `prerenderSite` is what fills it: this file is
+ * the report's shape and `prerender.ts` imports it, so the other direction is a cycle. `prerender`
+ * re-exports the name for its own callers.
+ */
+export type UnmeasuredRoute = {
+  /** The DECLARED path, as `X_BUDGET_UNMEASURED`'s `at:` spells it, so the two rows join. */
+  readonly path: string;
+  readonly reason: string;
+};
+
 /** One HTML file in the artifact, and the declared route that produced it. */
 export type EmittedPage = {
   readonly route: string;
@@ -62,6 +75,15 @@ export type StaticReport = {
   readonly buildId: string;
   readonly emitted: readonly EmittedPage[];
   readonly skipped: readonly SkippedRoute[];
+  /**
+   * Every budgeted route this build could not weigh, with the reason. `X_BUDGET_UNMEASURED`'s own
+   * `fix:` cites this list by name — `x build --target static --json # its "unmeasured" list says
+   * why` — and until it was written here the list existed only on the in-process `PrerenderReport`
+   * and reached no `x` command's output at all: `cmd-build.ts` discards a successful subprocess's
+   * stdout. A `fix:` naming a key nothing prints is axiom 4 inverted at the step meant to unblock
+   * the reader.
+   */
+  readonly unmeasured: readonly UnmeasuredRoute[];
 };
 
 /**
@@ -139,6 +161,9 @@ const isSkipped = (value: unknown): value is SkippedRoute =>
   typeof value['why'] === 'string' &&
   inDomain(SKIP_REASONS, value['reason']);
 
+const isUnmeasured = (value: unknown): value is UnmeasuredRoute =>
+  isRecord(value) && typeof value['path'] === 'string' && typeof value['reason'] === 'string';
+
 const isEmitted = (value: unknown): value is EmittedPage =>
   isRecord(value) &&
   typeof value['route'] === 'string' &&
@@ -152,13 +177,20 @@ const isEmitted = (value: unknown): value is EmittedPage =>
  */
 export function parseStaticReport(value: unknown): StaticReport | undefined {
   if (!isRecord(value)) return undefined;
-  const { target, out, buildId, emitted, skipped } = value;
+  const { target, out, buildId, emitted, skipped, unmeasured } = value;
   if (target !== 'static' || typeof out !== 'string' || typeof buildId !== 'string') {
     return undefined;
   }
   if (!Array.isArray(emitted) || !emitted.every(isEmitted)) return undefined;
   if (!Array.isArray(skipped) || !skipped.every(isSkipped)) return undefined;
-  return { target, out, buildId, emitted, skipped };
+  // OPTIONAL on the way in, total on the way out. `.x/` survives a checkout of an older commit,
+  // and a report written before this field existed has to read as "nothing unmeasured" — refusing
+  // it would answer `X_BUDGET_UNMEASURED` for every route on a build that had weighed them all.
+  // Present and malformed is still no report, exactly as a malformed skip row is.
+  if (unmeasured !== undefined && (!Array.isArray(unmeasured) || !unmeasured.every(isUnmeasured))) {
+    return undefined;
+  }
+  return { target, out, buildId, emitted, skipped, unmeasured: unmeasured ?? [] };
 }
 
 export async function writeStaticReport(root: string, report: StaticReport): Promise<string> {
@@ -198,7 +230,9 @@ export async function removeStaticReport(root: string): Promise<void> {
 export function staticReportData(report: StaticReport | undefined): Record<string, JsonValue> {
   // Never `{ ...report }`: `out` is an absolute build path and `buildId` is this run's, neither of
   // which the inventory is about — `data` already carries `artifact` and the build's own id.
-  return report === undefined ? {} : { emitted: report.emitted, skipped: report.skipped };
+  return report === undefined
+    ? {}
+    : { emitted: report.emitted, skipped: report.skipped, unmeasured: report.unmeasured };
 }
 
 /**
@@ -209,6 +243,10 @@ export function renderStaticReport(report: StaticReport): readonly string[] {
   const rows: readonly (readonly string[])[] = [
     ...report.emitted.map((page) => ['emitted', page.route, page.file]),
     ...report.skipped.map((route) => ['skipped', route.route, route.why]),
+    // The same three columns, so the terminal and `--json` carry the same three lists. A route
+    // whose budget could not be weighed is invisible in `emitted` and, when it also rendered, in
+    // `skipped` too — and it is the row `X_BUDGET_UNMEASURED` sends its reader here to read.
+    ...report.unmeasured.map((route) => ['unmeasured', route.path, route.reason]),
   ];
   const widths = [0, 1].map((index) =>
     Math.max(...rows.map((row) => (row[index] ?? '').length), 0),

package/src/templates/admin-page.ts

@@ -5,6 +5,7 @@
 // declaration here would hand back the unguarded second way in that seam exists to close.
 
 import { catalogJson } from './catalog-json';
+import { sortedImports } from './imports';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile } from './naming';
 import { camel, kebab, pascal } from './naming';
@@ -47,15 +48,18 @@ const catalogImport = (module: string | undefined): string =>
 /**
  * The two imports, in the order biome's organize-imports wants — which DEPENDS on the app's scope
  * and cannot be hardcoded either way. An app catalog (`@myapp/i18n`) sorts BEFORE
- * `@ultimat3/admin`; the fallback `@ultimat3/i18n` sorts AFTER it. Emitting one fixed order makes
- * every generated admin page a lint error in exactly one of the two cases, and each case is
- * covered by a different job — the fallback by `templates`' own linter test, the app-scoped one
- * only by `scaffold-smoke`, which runs the generators against a real scaffold.
+ * `@ultimat3/admin`; the fallback `@ultimat3/i18n` sorts AFTER it, and `@zebra/i18n` after that.
+ * Emitting one fixed order makes every generated admin page a lint error in one of those cases.
+ *
+ * `sortedImports` is this sort, moved to `templates/imports.ts` so the four scaffold sites that
+ * had the same mix and none of the fix share it — `x new zebra` was four `organizeImports` errors
+ * on its first `x verify`.
  */
 const pageImports = (module: string | undefined): string =>
-  [`import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';`, catalogImport(module)]
-    .sort((a, b) => (a.slice(a.indexOf("'")) < b.slice(b.indexOf("'")) ? -1 : 1))
-    .join('\n');
+  sortedImports([
+    `import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';`,
+    catalogImport(module),
+  ]);
 
 /** `useT()` is per render, so the component binds it in its own body. */
 const translatorBinding = (module: string | undefined): string =>

package/src/templates/imports.ts

@@ -0,0 +1,26 @@
+// The order Biome's `organizeImports` wants for a generated file — COMPUTED, because it depends on
+// the app's own scope and no fixed order can be right for every app.
+//
+// `import { useT } from '@myapp/i18n'` sorts BEFORE `@ultimat3/render`; `@zebra/i18n` sorts after
+// it. Every template wrote one fixed order, so `x new zebra` scaffolded four files Biome refuses
+// (`assist/source/organizeImports`, measured: `apps/web/site/page.tsx`,
+// `apps/web/app/dashboard/page.tsx`, `apps/admin/app/admin/page.tsx`, `packages/mcp/src/index.ts`)
+// and the app's very first `x verify` was red on its `lint` step. `x new alpha` was clean, which is
+// why nothing caught it: both CI fixtures — `demoapp` and `bareapp` — sort before `ultimat3`.
+//
+// `templates/admin-page.ts` already did this by hand for its two lines; this is that sort, in one
+// place, for every generator that mixes an app specifier with a framework one.
+
+/** The quoted specifier a line imports from — the only thing Biome orders these lines by. */
+const specifierOf = (line: string): string => line.slice(line.indexOf("'"));
+
+/**
+ * One import block, sorted the way Biome would sort it.
+ *
+ * BARE specifiers only (`@myapp/i18n`, `@ultimat3/render`, `solid-js`). A relative specifier
+ * (`./page.module.scss`) belongs to a LATER group and sorts before every `@` by plain string
+ * compare, so passing one here would emit the block Biome then moves — the exact defect this
+ * exists to end. Templates write those lines after the block, where they already are.
+ */
+export const sortedImports = (lines: readonly string[]): string =>
+  [...lines].sort((a, b) => (specifierOf(a) < specifierOf(b) ? -1 : 1)).join('\n');

package/src/templates/route.ts

@@ -5,6 +5,7 @@
 // fallback is a blank screen on a train.
 
 import { catalogJson } from './catalog-json';
+import { sortedImports } from './imports';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile } from './naming';
 import { kebab, pascal, titleKey } from './naming';
@@ -112,8 +113,7 @@ const pageSource = (surface: Surface, path: string, module: string | undefined):
   return `// Route: /${path} on the ${surface} surface. Config first: render mode, offline
 // strategy and budget are declarations, not runtime choices.
 
-${catalogImport(module)}
-import { defineRoute } from '@ultimat3/render';
+${sortedImports([catalogImport(module), `import { defineRoute } from '@ultimat3/render';`])}
 import styles from './page.module.scss';
 
 export const config = defineRoute({

package/src/templates/scaffold-app.ts

@@ -2,8 +2,10 @@
 // already speaks MCP, and the mobile/desktop placeholders that exist so adding them later is not
 // a restructure. Every file here is real, typed and covered — no placeholder that fails to boot.
 
+import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { apiFiles } from './scaffold-api';
+import { authFiles } from './scaffold-auth';
 import { entryFiles } from './scaffold-entries';
 import { icon } from './scaffold-icon';
 import { rolesFiles } from './scaffold-roles';
@@ -47,8 +49,10 @@ const sitePage = (
 // \`t\` in @ultimat3/i18n. That import is what puts the module holding \`defineCatalogs()\` in
 // this page's graph, so rendering a string is what registers the catalogs. A page that reached
 // past it shipped every string as \`\u27e6key\u27e7\` with \`x verify\` green (issue #249).
-import { useT } from '@${app.kebab}/i18n';
-import { defineRoute } from '@ultimat3/render';
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  `import { defineRoute } from '@ultimat3/render';`,
+])}
 import styles from './page.module.scss';
 
 export const config = defineRoute({
@@ -126,8 +130,10 @@ const dashboardPage = (
 // as their data resolves.
 
 // \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
-import { useT } from '@${app.kebab}/i18n';
-import { defineRoute } from '@ultimat3/render';
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  `import { defineRoute } from '@ultimat3/render';`,
+])}
 import styles from './page.module.scss';
 
 export const config = defineRoute({
@@ -323,8 +329,10 @@ const adminPage = (
 // user's agents can drive the user's product with the user's permissions.
 
 // \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
-import { useT } from '@${app.kebab}/i18n';
-import { defineRoute } from '@ultimat3/render';
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  `import { defineRoute } from '@ultimat3/render';`,
+])}
 
 export const config = defineRoute({
   render: 'ssr',
@@ -377,6 +385,10 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     { path: 'apps/web/app/dashboard/page.tsx', contents: dashboardPage(app) },
     { path: 'apps/web/app/dashboard/page.module.scss', contents: dashboardStyle() },
     { path: 'apps/web/app/dashboard/page.test.ts', contents: dashboardTest() },
+    // The third piece of the authz story the scaffold already tells twice: the routes declare a
+    // policy and `shared/roles.ts` declares the grants, and until this file existed nothing
+    // answered "who is this?" — so every one of those routes refused every request.
+    ...authFiles(app),
     { path: 'apps/web/app/offline.tsx', contents: offlineFallback(app) },
     { path: 'apps/web/app/offline.module.scss', contents: offlineStyle() },
     // The third surface, and the one call that registers what the app declares — `scaffold-api.ts`.

package/src/templates/scaffold-auth.ts

@@ -0,0 +1,151 @@
+// The scaffold's answer to "who is this?", which it did not have.
+//
+// `hooks.authenticate` is the ONLY place an actor can come from, and nothing in a generated app
+// called `configureAuthenticator()` — so a fresh `x new` booted with
+// `X_CONFIG_INVALID: 7 route(s) declare auth: 'required' and no authenticator is configured` on
+// every start, and its own `/dashboard` answered 401 on the first click. The scaffold declares the
+// routes and the roles; this is the missing third piece, and it is deliberately the smallest one
+// that can be honest: a viewer named by a cookie, installed in `development` and nowhere else.
+//
+// The alternative — dropping `policy:` from the scaffolded routes — was refused: a dashboard that
+// declares no policy is registered `auth: 'public'`, which also skips `render-ssr`'s gated branch,
+// so the document ships with no `vary: cookie` and a shared cache may hand one visitor's page to
+// the next. The scaffold would teach the wrong shape to every app that starts from it.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const devActor = (
+  app: NameSet,
+): string => `// Who a browser is until this app issues sessions of its own.
+//
+// \`hooks.authenticate\` is the one place an actor can come from. Without it every request is
+// anonymous, so each route declaring a \`policy:\` answers 401 and the boot warns
+// \`X_CONFIG_INVALID\` — which is what a scaffolded app did on its very first \`x dev\`.
+//
+// DEVELOPMENT ONLY, and the guard is the point: a viewer that followed this to staging would sign
+// every visitor in as an admin. \`bun test\` sets \`NODE_ENV=test\`, so it does not install there
+// either — a fixture mints its own actor, and a second one arriving from a cookie would decide
+// which actor a test is about.
+//
+// REPLACE IT with the real thing: resolve a session cookie to a row, and return that actor.
+// Everything downstream — pages, policies, live subscribers, MCP tools — reads what this returns.
+import { type Actor, logger, tryResolveEnvironment } from '@ultimat3/core';
+import { configureAuthenticator, readCookie } from '@ultimat3/http';
+
+/** Set it to a role from \`apps/web/shared/roles.ts\` to browse as that role. */
+export const DEV_ROLE_COOKIE = '${app.kebab}_dev_role';
+
+/** The roles \`shared/roles.ts\` declares. A cookie naming anything else falls back. */
+export const DEV_ROLES = ['member', 'admin'] as const;
+
+export type DevRole = (typeof DEV_ROLES)[number];
+
+/** The one that can open every scaffolded route, including \`/admin\`. */
+export const DEFAULT_DEV_ROLE: DevRole = 'admin';
+
+const isDevRole = (value: string | null): value is DevRole =>
+  value !== null && (DEV_ROLES as readonly string[]).includes(value);
+
+/**
+ * An unknown cookie value falls back rather than refusing: the cookie is a viewing convenience,
+ * and a typo that resolved nobody would reproduce the 401 this module exists to remove.
+ */
+export const devRoleFrom = (cookieHeader: string | null): DevRole => {
+  const named = readCookie(cookieHeader, DEV_ROLE_COOKIE);
+  return isDevRole(named) ? named : DEFAULT_DEV_ROLE;
+};
+
+/**
+ * \`roles\`, never a permission list: \`can()\` expands the role map at decision time, so a grant
+ * moved between roles reaches this actor without an edit here.
+ */
+export const devActorFor = (role: DevRole): Actor => ({
+  kind: 'user',
+  id: 'dev-actor',
+  orgId: 'dev-org',
+  roles: [role],
+  // Both required, and both deliberately empty: \`scopes\` is the framework's own escape hatch
+  // (\`tenancy:cross\`) and \`permissions\` is a DIRECT grant that bypasses the role map — a
+  // development viewer holds exactly what its role holds, and nothing a rule cannot explain.
+  scopes: [],
+  permissions: [],
+});
+
+/**
+ * Installs it, and says so — loudly, because a silent stand-in for authentication is the one thing
+ * worse than none. Returns whether it installed, so the test can assert both halves.
+ */
+export function installDevAuthenticator(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  if (tryResolveEnvironment({ env }) !== 'development') return false;
+  configureAuthenticator((request) => devActorFor(devRoleFrom(request.header('cookie'))));
+  logger.warn('every request is answered as a development viewer', {
+    role: DEFAULT_DEV_ROLE,
+    cause:
+      'apps/web/app/auth/dev-actor.ts installs a viewer in development only, because this app issues no session yet',
+    fix: \`browse as someone else: document.cookie = '\${DEV_ROLE_COOKIE}=member'\`,
+  });
+  return true;
+}
+
+// Module scope, which IS the wiring: the boot scan imports every module under \`apps/*\` before a
+// listener binds, and \`x dev\` and the container both read the configured value back at start.
+installDevAuthenticator();
+`;
+
+const devActorTest =
+  (): string => `// The two halves that make a development-only stand-in safe: it resolves the cookie, and it does
+// not install itself anywhere but development.
+import { configuredAuthenticator, resetAuthenticator } from '@ultimat3/http';
+import { actorHas } from '@ultimat3/policy';
+import { expect, unitTest } from '@ultimat3/testing';
+import { roles } from '../../shared/roles';
+import {
+  DEFAULT_DEV_ROLE,
+  DEV_ROLE_COOKIE,
+  devActorFor,
+  devRoleFrom,
+  installDevAuthenticator,
+} from './dev-actor';
+
+unitTest('the cookie names the role, and anything else falls back', () => {
+  expect(devRoleFrom(\`\${DEV_ROLE_COOKIE}=member\`)).toBe('member');
+  expect(devRoleFrom(\`\${DEV_ROLE_COOKIE}=nobody\`)).toBe(DEFAULT_DEV_ROLE);
+  expect(devRoleFrom(null)).toBe(DEFAULT_DEV_ROLE);
+});
+
+unitTest('the actor it mints holds what the role map grants it, and nothing else', () => {
+  // \`actorHas\` and not \`holds\`: this is the function \`can()\` itself calls, so the assertion is
+  // the pipeline's own decision rather than a second implementation of it. The map is passed
+  // explicitly — a test that depended on which module imported first would pass alone and fail
+  // inside a suite.
+  expect(actorHas(devActorFor('admin'), 'admin:read', roles)).toBe(true);
+  expect(actorHas(devActorFor('member'), 'dashboard:read', roles)).toBe(true);
+  // The whole reason this is development-only: a member is not an admin, and neither is a deploy.
+  expect(actorHas(devActorFor('member'), 'admin:read', roles)).toBe(false);
+});
+
+unitTest('it installs in development and in no other environment', () => {
+  // This process is \`test\`, so the module-scope call at the bottom of dev-actor.ts installed
+  // nothing — which is what keeps a fixture's own actor the only one a test can be about.
+  expect(configuredAuthenticator()).toBeUndefined();
+
+  expect(installDevAuthenticator({ ULTIMATE_ENV: 'production' })).toBe(false);
+  expect(installDevAuthenticator({ ULTIMATE_ENV: 'staging' })).toBe(false);
+  expect(configuredAuthenticator()).toBeUndefined();
+
+  expect(installDevAuthenticator({ ULTIMATE_ENV: 'development' })).toBe(true);
+  expect(configuredAuthenticator()).toBeDefined();
+  // Process-global, so the case that installed one takes it back out.
+  resetAuthenticator();
+});
+`;
+
+/** The app's development viewer, beside the roles it names. */
+export function authFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'apps/web/app/auth/dev-actor.ts', contents: devActor(app) },
+    { path: 'apps/web/app/auth/dev-actor.test.ts', contents: devActorTest() },
+  ];
+}

package/src/templates/scaffold-container.ts

@@ -197,6 +197,18 @@ services:
     deploy: { replicas: 1 } # scales on concurrent websockets, no sticky sessions — pinned by the port
     # The sync role binds PORT + 1. PORT is unset here, so it is 3000 and this listens on 3001.
     ports: ['3001:3001']
+    # ...which is why the image's own HEALTHCHECK cannot be inherited here. It fetches $PORT —
+    # 3000 — and this role never binds it, so the container reports \`unhealthy\` from
+    # \`start_period\` onward and never recovers, and anything gated on \`sync: service_healthy\`
+    # would never start. Literal 3001 rather than an expression, for the same reason \`ports:\`
+    # above is literal: PORT is unset in this file, and two ways of saying one number drift.
+    # \`docker/helm\` states the same rule as \`PORT = .port - 1\`.
+    healthcheck:
+      test: ['CMD', 'bun', '--eval', "fetch('http://127.0.0.1:3001/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+      interval: 10s
+      timeout: 3s
+      start_period: 30s
+      retries: 3
 
   worker:
     <<: *image

package/src/templates/scaffold-docs.ts

@@ -58,7 +58,7 @@ file in it is deletable.
 
 const readme = (app: NameSet): string => `# ${app.pascal}
 
-Built with [Ultimate](https://ultimate.dev). Bun-only, Postgres, SolidJS.
+Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Postgres, SolidJS.
 
 ## 🚀 Start