@ultimat3/cli 24.0.0 → 25.1.0

package/src/templates/scaffold-auth.ts

@@ -1,40 +1,32 @@
-// The scaffold's answer to "who is this?", which it did not have.
+// The scaffold's answer to "who is this?": a session cookie, resolved by `@ultimat3/auth` over the
+// framework's own `x_users` / `x_sessions` tables, installed in EVERY environment.
 //
-// `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.
+// `hooks.authenticate` is the ONLY place an actor can come from, and a fresh `x new` once installed
+// nothing there — `X_CONFIG_INVALID: 7 route(s) declare auth: 'required' and no authenticator is
+// configured` on every start, and a 401 on its own `/dashboard`. The first answer was a viewer
+// named by a cookie, installed in `development` alone, which left every other environment with no
+// authenticator at all and the real path for the app's author to invent. Now the real path is the
+// one installed, and the development viewer is only what a request with NO session is answered as
+// under `x dev` — so `x dev` stays zero-config and nothing has to be swapped out before a deploy.
 //
-// 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.
+// 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.
 
 import type { GeneratedFile, NameSet } from './naming';
 
 const devActor = (
   app: NameSet,
-): string => `// Who a browser is until this app issues sessions of its own.
+): string => `// Who a browser with NO session is under \`x dev\`: a viewer named by a cookie.
 //
-// \`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\`.
+// \`authenticator.ts\` is the real path — a session cookie, resolved by \`@ultimat3/auth\` — and it
+// is installed in every environment. A fresh app issues no session until it has a sign-in page, so
+// without this every route declaring a \`policy:\` answered 401 on the first \`x dev\`. This module
+// only answers; \`authenticator.ts\` decides when it is asked, and it asks in \`development\` alone —
+// a viewer that followed this to staging would sign every visitor in as an admin.
 //
-// DEVELOPMENT ONLY, and the guard is the point: a viewer that followed this to staging would sign
-// every visitor in as an admin. FAILS CLOSED (\`fallback: 'production'\`) rather than trusting
-// \`tryResolveEnvironment\`'s own default: that default is \`development\`, so a process that named
-// NEITHER \`ULTIMATE_ENV\` nor \`NODE_ENV\` would otherwise read as development too — indistinguishable
-// from the one this file exists to allow. \`x dev\` declares \`ULTIMATE_ENV=development\` for exactly
-// this reason (whenever neither key is already set), so a bare \`x dev\` still installs this viewer;
-// \`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';
+// Delete it the day sign-in exists, and the fallback line in \`authenticator.ts\` with it.
+import { type Actor, logger, readCookie } from '@ultimat3/core';
 import { DEMO_ORG_ID } from '../../shared/demo-org';
 import { roles } from '../../shared/roles';
 
@@ -82,13 +74,13 @@ export const devActorFor = (role: string): Actor => ({
 });
 
 /** The one method this reads off a request. */
-interface HeaderRequest {
+export interface HeaderRequest {
   header(name: string): string | null;
 }
 
 /**
- * What \`hooks.authenticate\` is handed: the request's cookie header decides the role. Named, and
- * typed by the one method it reads, so a test calls it with a header and no server.
+ * The development viewer for a request: its cookie header decides the role. Typed by the one
+ * method it reads, so a test calls it with a header and no server.
  *
  * A cookie naming an undeclared role answers \`null\` — ANONYMOUS, the least a request can be —
  * and says so, with the value it read and the roles it could have named.
@@ -104,35 +96,111 @@ export const devAuthenticate = (request: HeaderRequest): Actor | null => {
   });
   return null;
 };
+`;
+
+const authModule =
+  (): string => `// This app's one \`@ultimat3/auth\` instance: sessions, passwords and the lockout, over the
+// framework's own \`x_users\` and \`x_sessions\` tables — \`x dev\` and \`ROLE=migrate\` apply them.
+//
+// Sign-in is one call once the app has a page for it: \`login(appAuth(), { email, password, ip })\`
+// answers \`{ token, cookie }\` — set \`cookie\` on the response and every request after it is that
+// user, through \`authenticator.ts\`. \`register(appAuth(), { email, password, orgId, roles })\`
+// creates one.
+import { type Auth, defineAuth, postgresAuthAdapter } from '@ultimat3/auth';
+
+let built: Auth | undefined;
+
+/**
+ * Built on first use, never at import: the boot scan imports this module before the database and
+ * the host's shared lockout limiter are installed, and \`defineAuth\` reads both.
+ */
+export const appAuth = (): Auth => {
+  built ??= defineAuth({ adapter: postgresAuthAdapter() });
+  return built;
+};
+`;
+
+const authenticatorModule =
+  (): string => `// Who a request is: the session its cookie names, resolved by \`@ultimat3/auth\` — the one
+// authenticator this app installs, in every environment. Everything downstream (pages, policies,
+// live subscribers, MCP tools) reads the actor this returns.
+//
+// With NO session cookie the request is anonymous — except under \`x dev\`, where it is the
+// development viewer (\`dev-actor.ts\`), so a fresh app opens its own dashboard with nothing
+// configured. That fallback FAILS CLOSED (\`fallback: 'production'\`): \`tryResolveEnvironment\`'s own
+// default is \`development\`, so a process naming NEITHER \`ULTIMATE_ENV\` nor \`NODE_ENV\` would
+// otherwise read as development too. \`x dev\` declares \`ULTIMATE_ENV=development\` for exactly this
+// reason, and \`bun test\` sets \`NODE_ENV=test\`, where a fixture mints its own actor.
+import { type Auth, authenticate } from '@ultimat3/auth';
+import { type Actor, logger, tryResolveEnvironment } from '@ultimat3/core';
+import { configureAuthenticator } from '@ultimat3/http';
+import { appAuth } from './auth';
+import {
+  DEFAULT_DEV_ROLE,
+  DEV_ROLE_COOKIE,
+  devAuthenticate,
+  type HeaderRequest,
+} from './dev-actor';
+
+/** The two methods this reads off a request. */
+export interface SessionRequest extends HeaderRequest {
+  cookie(name: string): string | null;
+}
+
+export interface SessionAuthenticatorOptions {
+  /** The app's \`Auth\`, asked for per request so it is built after the boot, not at import. */
+  readonly auth: () => Auth;
+  /** Whether a request with no session is the development viewer rather than anonymous. */
+  readonly development: boolean;
+}
 
 /**
- * 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.
+ * A session cookie is that session's user, or a refusal — never a fallback to anyone else:
+ * \`X_SESSION_EXPIRED\` for a session past its absolute or idle expiry, \`X_UNAUTHENTICATED\` for
+ * one that is unknown, revoked or forged, or whose user is disabled. No cookie is the development
+ * viewer or nobody.
  */
-export function installDevAuthenticator(
+export const sessionAuthenticator =
+  (options: SessionAuthenticatorOptions) =>
+  async (request: SessionRequest): Promise<Actor | null> => {
+    const auth = options.auth();
+    const token = request.cookie(auth.sessions.policy.cookieName);
+    if (token !== null && token.length > 0) return await authenticate(auth, token);
+    return options.development ? devAuthenticate(request) : null;
+  };
+
+/**
+ * Installs the session authenticator, and returns whether the development fallback is on — so the
+ * test can assert both halves. Loud when it is, because a stand-in for a session is the one thing
+ * an operator must never find in a log they did not expect it in.
+ */
+export function installAuthenticator(
   env: Readonly<Record<string, string | undefined>> = process.env,
+  auth: () => Auth = appAuth,
 ): boolean {
-  if (tryResolveEnvironment({ env, fallback: 'production' }) !== 'development') return false;
-  configureAuthenticator(devAuthenticate);
-  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;
+  const development = tryResolveEnvironment({ env, fallback: 'production' }) === 'development';
+  configureAuthenticator(sessionAuthenticator({ auth, development }));
+  if (development) {
+    logger.warn('a request with no session is answered as a development viewer', {
+      role: DEFAULT_DEV_ROLE,
+      cause:
+        'apps/web/app/auth/authenticator.ts falls back to dev-actor.ts in development, because this app has no sign-in page yet',
+      fix: \`browse as someone else: document.cookie = '\${DEV_ROLE_COOKIE}=member'\`,
+    });
+  }
+  return development;
 }
 
 // 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();
+installAuthenticator();
 `;
 
 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.
+  (): string => `// The development viewer is safe because of what it refuses: a role nobody declared is never the
+// default viewer, and the actor it mints holds what its role holds and nothing else. WHEN it is
+// asked is \`authenticator.ts\`'s, and \`authenticator.test.ts\` holds that half.
 import { setLogSink } from '@ultimat3/core';
-import { configuredAuthenticator, resetAuthenticator } from '@ultimat3/http';
 import { actorHas } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
 import { roles } from '../../shared/roles';
@@ -143,7 +211,6 @@ import {
   devActorFor,
   devAuthenticate,
   devRoleFrom,
-  installDevAuthenticator,
 } from './dev-actor';
 
 unitTest('the cookie names a DECLARED role; with no cookie it is the default viewer', () => {
@@ -173,27 +240,7 @@ unitTest('the actor it mints holds what the role map grants it, and nothing else
   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);
-  // FAILS CLOSED: a process naming NEITHER key is production here, never the default-development
-  // a bare \`tryResolveEnvironment({ env })\` would answer. \`x dev\` is what makes a real \`x dev\`
-  // still install this viewer — it declares \`ULTIMATE_ENV=development\` before this module loads,
-  // for exactly the process this call simulates having none of.
-  expect(installDevAuthenticator({})).toBe(false);
-  expect(configuredAuthenticator()).toBeUndefined();
-
-  expect(installDevAuthenticator({ ULTIMATE_ENV: 'development' })).toBe(true);
-  expect(configuredAuthenticator()).toBe(devAuthenticate);
-  // Process-global, so the case that installed one takes it back out.
-  resetAuthenticator();
-});
-
-unitTest('what it installs answers a request from its cookie header, and no other', () => {
+unitTest('it answers a request from its cookie header, and no other', () => {
   const cookie = \`\${DEV_ROLE_COOKIE}=member\`;
   const request = { header: (name: string) => (name === 'cookie' ? cookie : null) };
   expect(devAuthenticate(request)?.roles).toEqual(['member']);
@@ -217,9 +264,97 @@ unitTest('an undeclared role is answered as ANONYMOUS, and the log names what it
 });
 `;
 
-/** The app's development viewer, beside the roles it names. */
+const authenticatorTest =
+  (): string => `// The real path and its one fallback: a session cookie is its user in every environment, a bad
+// one is refused rather than replaced, and only development answers a request with no session.
+import { defineAuth, login, memoryAuthAdapter, register } from '@ultimat3/auth';
+import { configuredAuthenticator, resetAuthenticator } from '@ultimat3/http';
+import { expect, unitTest } from '@ultimat3/testing';
+import { DEMO_ORG_ID } from '../../shared/demo-org';
+import { installAuthenticator, sessionAuthenticator } from './authenticator';
+import { DEFAULT_DEV_ROLE, DEV_ROLE_COOKIE } from './dev-actor';
+
+/** In memory: the session half is the package's, and this test is about the wiring around it. */
+const memoryAuth = () => {
+  const auth = defineAuth({ adapter: memoryAuthAdapter() });
+  return () => auth;
+};
+
+/** A request carrying exactly these cookies, through both methods the authenticator reads. */
+const requestWith = (cookies: Readonly<Record<string, string>>) => ({
+  header: (name: string) =>
+    name === 'cookie' && Object.keys(cookies).length > 0
+      ? Object.entries(cookies)
+          .map(([key, value]) => \`\${key}=\${value}\`)
+          .join('; ')
+      : null,
+  cookie: (name: string) => cookies[name] ?? null,
+});
+
+const PASSWORD = 'a long scaffold test passphrase';
+
+unitTest('a session cookie is the user it was issued to, in every environment', async () => {
+  const auth = memoryAuth();
+  const user = await register(auth(), {
+    email: 'ada@example.com',
+    password: PASSWORD,
+    orgId: DEMO_ORG_ID,
+    roles: ['member'],
+  });
+  const { token } = await login(auth(), { email: 'ada@example.com', password: PASSWORD });
+  const request = requestWith({ [auth().sessions.policy.cookieName]: token });
+  for (const development of [true, false]) {
+    const actor = await sessionAuthenticator({ auth, development })(request);
+    expect(actor?.id).toBe(user.id);
+    expect(actor?.roles).toEqual(['member']);
+  }
+});
+
+unitTest('a cookie naming no live session is refused, never answered as the viewer', async () => {
+  const auth = memoryAuth();
+  const request = requestWith({ [auth().sessions.policy.cookieName]: 'forged.token' });
+  await expect(sessionAuthenticator({ auth, development: true })(request)).rejects.toMatchObject({
+    code: 'X_UNAUTHENTICATED',
+  });
+});
+
+unitTest('no session: the development viewer under x dev, anonymous anywhere else', async () => {
+  const auth = memoryAuth();
+  const member = requestWith({ [DEV_ROLE_COOKIE]: 'member' });
+  expect((await sessionAuthenticator({ auth, development: true })(member))?.roles).toEqual([
+    'member',
+  ]);
+  const none = requestWith({});
+  expect((await sessionAuthenticator({ auth, development: true })(none))?.roles).toEqual([
+    DEFAULT_DEV_ROLE,
+  ]);
+  expect(await sessionAuthenticator({ auth, development: false })(member)).toBeNull();
+});
+
+unitTest('it installs in every environment; only development turns the fallback on', () => {
+  const auth = memoryAuth();
+  try {
+    expect(installAuthenticator({ ULTIMATE_ENV: 'production' }, auth)).toBe(false);
+    expect(configuredAuthenticator()).toBeDefined();
+    expect(installAuthenticator({ ULTIMATE_ENV: 'staging' }, auth)).toBe(false);
+    // FAILS CLOSED: a process naming NEITHER key is production here, never the default-development
+    // a bare \`tryResolveEnvironment({ env })\` would answer. \`x dev\` declares
+    // \`ULTIMATE_ENV=development\` before this module loads, for exactly the process this simulates.
+    expect(installAuthenticator({}, auth)).toBe(false);
+    expect(installAuthenticator({ ULTIMATE_ENV: 'development' }, auth)).toBe(true);
+  } finally {
+    // Process-global, so the case that installed one takes it back out.
+    resetAuthenticator();
+  }
+});
+`;
+
+/** The app's authenticator, its \`Auth\`, and the development viewer it falls back to. */
 export function authFiles(app: NameSet): readonly GeneratedFile[] {
   return [
+    { path: 'apps/web/app/auth/auth.ts', contents: authModule() },
+    { path: 'apps/web/app/auth/authenticator.ts', contents: authenticatorModule() },
+    { path: 'apps/web/app/auth/authenticator.test.ts', contents: authenticatorTest() },
     { 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-bin.ts

@@ -0,0 +1,122 @@
+// The two scripts a scaffolded app is driven by — `bun run setup` and `bun run check` — written as
+// TypeScript that Bun runs, never as shell. A bash `bin/setup` was the first thing a PowerShell or
+// cmd user hit after `x new`, and it failed there; a `.ts` file run by the Bun the app already
+// requires is the same script on every OS. `bun run dev` needs no file: it is `x dev`.
+
+import type { GeneratedFile } from './naming';
+
+/** Where each script lands, and what the root `package.json`'s `scripts` run — named once. */
+export const BIN_SCRIPTS = {
+  setup: 'bin/setup.ts',
+  check: 'bin/check.ts',
+} as const;
+
+/** The `package.json` script line that runs a bin file: Bun itself, so no shell interprets it. */
+export const binScript = (path: string): string => `bun ${path}`;
+
+// Every step is a TOP-LEVEL call statement, one per line — `scripts/setup-commands.ts` reads the
+// documented sequence out of exactly those lines, so a helper's body (indented) or the closing
+// `console.log` (a member call) is never mistaken for a step. `bun x x` is `bunx x` spelled through
+// the running Bun's own path: no PATH lookup, so no shell or PATHEXT decides which `x` runs.
+const binSetup =
+  (): string => `// Fresh clone to running. Idempotent: safe to re-run. \`bun run setup\` — Bun runs this file, so
+// it is the same script under PowerShell, cmd or any POSIX shell.
+import { existsSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = join(import.meta.dir, '..');
+
+/** One step, from the app root, on this terminal. A red step ends setup with its own exit code. */
+const run = async (argv: readonly string[]): Promise<void> => {
+  const code = await Bun.spawn([...argv], { cwd: root, stdio: ['inherit', 'inherit', 'inherit'] })
+    .exited;
+  if (code !== 0) process.exit(code);
+};
+
+/** Bun itself, by the path it is running from. */
+const bun = (...args: string[]): Promise<void> => run([process.execPath, ...args]);
+
+/** The app's own CLI, as \`bunx x\` resolves it — the install below links it into node_modules. */
+const x = (...args: string[]): Promise<void> => run([process.execPath, 'x', 'x', ...args]);
+
+/** Writes a file only when it is absent, so a re-run never clobbers what a box put there. */
+const ensureFile = (path: string, contents: string): void => {
+  if (!existsSync(join(root, path))) writeFileSync(join(root, path), contents);
+};
+
+const PER_BOX = '# per-box secrets, gitignored, wins over .env.development\\n';
+
+// \`x db gen\` is the ONE writer of packages/db/migrations — the scaffold no longer hand-writes a
+// 0000_initial.sql, because a second writer is how the source and the ledger ended up disagreeing
+// about what "initial" meant. Guarded on the directory rather than on the generator being a no-op:
+// this script is documented idempotent, and the guard is what makes that true here.
+const hasMigration = (): boolean => {
+  const dir = join(root, 'packages', 'db', 'migrations');
+  return existsSync(dir) && readdirSync(dir).some((name) => name.endsWith('.sql'));
+};
+
+await bun('install');
+ensureFile('.env.development.local', PER_BOX);
+if (!hasMigration()) await x('db', 'gen', 'initial');
+await x('db', 'migrate', ...process.argv.slice(2));
+// \`x db seed\`, never a plain script: the CLI owns the connection, so this reaches the same
+// embedded PGlite the migration above just wrote to. A plain script goes through \`db()\`, which
+// needs a \`postgres:\` DATABASE_URL and so dies on a clone with no Postgres.
+await x('db', 'seed');
+// The file AGENTS.md tells an agent facts live in, and \`x dev\` prints the path of. It is a
+// projection of the loaded app, so \`x new\` cannot write it — node_modules does not exist yet.
+// \`x verify\`'s manifest step refuses its absence (X_MANIFEST_MISSING).
+await x('manifest');
+console.log('setup complete — next: bun run dev');
+`;
+
+const binCheck =
+  (): string => `// The gate. Same steps as CI, because a check that lives only in CI cannot be run locally.
+// \`bun run check\` — Bun runs this file, so it is the same gate under PowerShell, cmd or bash.
+import { join } from 'node:path';
+
+const root = join(import.meta.dir, '..');
+const args = process.argv.slice(2);
+
+/** The app's own CLI, as \`bunx x\` resolves it, from the app root; resolves to its exit code. */
+const x = async (...argv: string[]): Promise<number> => {
+  const child = Bun.spawn([process.execPath, 'x', 'x', ...argv], {
+    cwd: root,
+    stdio: ['inherit', 'inherit', 'inherit'],
+  });
+  // The terminal already hands Ctrl-C to the child; this process only waits for its verdict. A
+  // SIGTERM is forwarded, so a CI timeout stops the gate instead of orphaning it mid-step.
+  const wait = (): void => {};
+  const stop = (): void => {
+    child.kill('SIGTERM');
+  };
+  process.on('SIGINT', wait);
+  process.on('SIGTERM', stop);
+  const code = await child.exited;
+  process.off('SIGINT', wait);
+  process.off('SIGTERM', stop);
+  return code;
+};
+
+// The build FIRST, and not as a convenience: \`x verify\`'s budgets step compares declared limits
+// against measured bytes in .x/build-stats.json, so with no build it reports X_BUDGET_UNMEASURED
+// and the very first gate anyone runs on a brand-new app is red for a reason that has nothing to
+// do with their code.
+//
+// \`--json\` is forwarded to BOTH, or the contract breaks: the build's human renderer followed by
+// the gate's JSON is neither on stdout. Both commands emit one object; a reader takes the last line.
+// \`--no-preflight\`: the build's own preflight is x verify's first six steps (typecheck, lint,
+// boundaries, filesize, package-shape, errors), and the gate below runs them anyway.
+const json = args.some((arg) => arg === '--json' || arg === '-j') ? ['--json'] : [];
+const built = await x('build', '--target', 'static', '--no-preflight', ...json);
+if (built !== 0) process.exit(built);
+process.exit(await x('verify', ...args));
+`;
+
+/** The bin scripts, in the order a newcomer runs them. */
+export function binFiles(): readonly GeneratedFile[] {
+  return [
+    { path: BIN_SCRIPTS.setup, contents: binSetup() },
+    { path: BIN_SCRIPTS.check, contents: binCheck() },
+  ];
+}

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 \`bin/check\`.
+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 \`bun run 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 \`bin/check\` green.** A passing unit test is not done. A working \`x dev\` is not done.
+**Done means \`bun run 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,15 +77,15 @@ the filename never is. One interactive control on a 0kb page is an island: \`x g
 ## 4. Gate it
 
 \`\`\`sh
-bin/check               # the gate. green = shippable
-bin/check --json        # the same, machine-readable
+bun run check           # the gate. green = shippable
+bun run check --json    # the same, machine-readable
 \`\`\`
 
-\`bin/check\` is \`x build --target static\` and THEN \`x verify\`, and the order is the whole point:
+\`bun run 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.
+\`bun run setup\` and then \`bun run 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
@@ -118,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:       bin/check ✓ | ✗ <failing steps>
+Gate:       bun run check ✓ | ✗ <failing steps>
 Deferred:   <what you did not do, and why>      [never omit this line]
 \`\`\`
 `;
@@ -172,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 \`bin/check\` green.
+- Acceptance criteria, ending in \`bun run check\` green.
 
 ## Risks
 - Anything the executor must decide, and every claim in the ask the code disproves.
@@ -185,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 \`bin/check\` green as the last line of *Done when*.
+  every new failure, and \`bun run check\` green as the last line of *Done when*.
 
 ## Output
 
@@ -202,7 +202,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 
 # /verify
 
-Run \`bin/check\`.
+Run \`bun run 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:
@@ -213,7 +213,7 @@ 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. \`bin/check --json\` gives the same steps machine-readably; \`x doctor\`
+when the cause is not enough. \`bun run 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-container.ts

@@ -10,7 +10,7 @@ import { SECRETS_KEY_FILE } from '@ultimat3/core';
 import { PREBUILT_COMMAND } from '../serve-prebuilt-paths';
 import type { GeneratedFile, NameSet } from './naming';
 import { composeProdFile, PROD_ENV_FILE } from './scaffold-container-compose';
-import { helmFiles } from './scaffold-helm';
+import { helmFiles, RUNTIME_UID } from './scaffold-helm';
 
 const dockerfile = (
   app: NameSet,
@@ -32,6 +32,8 @@ const dockerfile = (
 # from the file itself, and without it the frozen install cannot find what the lockfile names.
 # The tag names the series for the reader; the digest is what builds — a tag is a pointer its
 # publisher can move. Dependabot's docker ecosystem moves the digest together with the tag.
+# The digest is \`oven/bun:1.4.2-alpine\`'s, the patch the framework that wrote this file was
+# tested on — the same patch as \`engines.bun\` in package.json.
 FROM oven/bun:1.4-alpine@sha256:d888c0ae6c86d7866ff10c5aafdd9077b36aee6455b33dd270fb93c0dd5cef6f AS manifests
 WORKDIR /app
 COPY . .
@@ -92,9 +94,11 @@ HEALTHCHECK --interval=10s --timeout=3s --start-period=30s --retries=3 CMD \\
 # \`.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
+# Numeric, and the same number docker/helm/values.yaml runs every pod as: ${RUNTIME_UID} is the base
+# image's \`bun\` user, and a numeric USER is one a kubelet can check against runAsNonRoot.
+RUN mkdir -p /app/.x && chown -R ${RUNTIME_UID}:${RUNTIME_UID} /app/.x
 
-USER bun
+USER ${RUNTIME_UID}:${RUNTIME_UID}
 # 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"]
@@ -190,9 +194,11 @@ x build --target static --out dist/static   # one HTML file per \`render: 'stati
 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.
+The binary bundles neither the framework nor the app: it is a launcher. \`@ultimat3/*\` stays
+external and loads from the app's own \`node_modules\`, the app's \`package.json\` and
+\`tsconfig.json\` are read at run time, and the registries are filled by scanning
+\`apps/*/{site,app,api,shared}\` at boot. So it must be **started from the app root**, with the
+source tree and an installed \`node_modules\` beside it. The image is the self-contained artifact.
 
 ## A PaaS (Heroku, Render, Fly, Railway, Cloud Run, App Runner…)
 

package/src/templates/scaffold-dashboard-bare.ts

@@ -224,10 +224,14 @@ unitTest('the tiles are the framework registries, counted', async () => {
 unitTest('the table is the route table: path, surface and render mode per route', async () => {
   const t = useT();
   const view = await renderRoute(page, { url });
-  expect(view.html.match(/<tr data-row=/g)).toHaveLength(1);
-  expect(view.html).toMatch(
-    /<tr data-row="\\/dashboard"><td>\\/dashboard<\\/td><td>app<\\/td><td>ssr<\\/td>/,
-  );
+  expect(view.html.match(/<tr[^>]*\\sdata-row=/g)).toHaveLength(1);
+  // Each cell ends in its value; on a phone a card label rides in front of it, hidden from AT.
+  const row = view.html.match(/<tr[^>]*data-row="\\/dashboard">([\\s\\S]*?)<\\/tr>/)?.[1] ?? '';
+  expect([...row.matchAll(/([^>]*)<\\/td>/g)].map((cell) => cell[1])).toEqual([
+    '/dashboard',
+    'app',
+    'ssr',
+  ]);
   expect(view.text).toContain(t('app.dashboard.routesCaption'));
   expect(view.meta.title).toBe(t('app.dashboard.title'));
   // The sidebar knows where it is.