@ultimat3/cli 5.0.1 → 6.0.0

package/src/templates/resource.ts

@@ -58,12 +58,29 @@ unitTest('${feature.pascal}NotFoundError carries a code, a cause and a fix', ()
 });
 `;
 
+/**
+ * The generated component reaches strings through the APP's catalog module — the one that calls
+ * `defineCatalogs()` — so a component that renders a string depends on the module that registers
+ * them. `t` from `@ultimat3/i18n` renders while depending on nothing, which is how a shipped app
+ * served every string as a loud miss with a green gate (issue #249). An app with no catalog module
+ * keeps the framework import: emitting one that cannot resolve is worse than the wrong idiom.
+ */
+const catalogImport = (module: string | undefined): string =>
+  module === undefined
+    ? "import { t } from '@ultimat3/i18n';"
+    : `import { useT } from '${module}';`;
+
+/** `useT()` is per render, so each component binds it in its own body. */
+const translatorBinding = (module: string | undefined): string =>
+  module === undefined ? '' : '\n  const t = useT();\n';
+
 const uiSource = (
   feature: NameSet,
+  module: string | undefined,
 ): string => `// Presentation only. No fetching, no business logic: the list arrives as a prop from the route,
 // which got it from the live query.
 
-import { t } from '@ultimat3/i18n';
+${catalogImport(module)}
 import { For } from 'solid-js';
 import type { ${feature.pascal} } from './entity';
 import styles from './ui.module.scss';
@@ -72,7 +89,7 @@ export interface ${feature.pascal}ListProps {
   readonly rows: readonly ${feature.pascal}[];
 }
 
-export function ${feature.pascal}List(props: ${feature.pascal}ListProps) {
+export function ${feature.pascal}List(props: ${feature.pascal}ListProps) {${translatorBinding(module)}
   return (
     <ul class={styles.list}>
       <For each={props.rows} fallback={<li>{t('app.${feature.kebab}.empty')}</li>}>
@@ -103,10 +120,11 @@ const uiStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 const cardSource = (
   feature: NameSet,
+  module: string | undefined,
 ): string => `// One ${feature.camel} rendered on its own — the list's \`item\` shown outside a list, so a
 // detail route and a search result render the identical markup.
 
-import { t } from '@ultimat3/i18n';
+${catalogImport(module)}
 import type { ${feature.pascal} } from '../entity';
 import styles from '../ui.module.scss';
 
@@ -114,7 +132,7 @@ export interface ${feature.pascal}CardProps {
   readonly row: ${feature.pascal};
 }
 
-export function ${feature.pascal}Card(props: ${feature.pascal}CardProps) {
+export function ${feature.pascal}Card(props: ${feature.pascal}CardProps) {${translatorBinding(module)}
   return (
     <article class={styles.item}>
       <h3>{props.row.title}</h3>
@@ -126,10 +144,11 @@ export function ${feature.pascal}Card(props: ${feature.pascal}CardProps) {
 
 const formSource = (
   feature: NameSet,
+  module: string | undefined,
 ): string => `// Presentation only: the mutator this submits to owns validation server-side, so this form
 // never re-implements the invariant — a blank title fails at the boundary, not in the DOM.
 
-import { t } from '@ultimat3/i18n';
+${catalogImport(module)}
 import { createSignal } from 'solid-js';
 import styles from '../ui.module.scss';
 
@@ -138,7 +157,7 @@ export interface ${feature.pascal}FormProps {
 }
 
 export function ${feature.pascal}Form(props: ${feature.pascal}FormProps) {
-  const [title, setTitle] = createSignal('');
+  const [title, setTitle] = createSignal('');${translatorBinding(module)}
   return (
     <form
       class={styles.item}
@@ -174,6 +193,11 @@ export interface ResourceOptions extends FeatureTarget {
   readonly admin?: boolean;
   /** Every locale the feature's catalog ships for. Defaults to `['en']`. */
   readonly locales?: readonly string[];
+  /**
+   * The app's own catalog module — `@<app>/i18n`, read off `packages/i18n/package.json` by
+   * `resolveCatalogModule`. Absent only for an app that ships no such package.
+   */
+  readonly catalogModule?: string;
 }
 
 export function resourceFiles(rawName: string, target: ResourceOptions): readonly GeneratedFile[] {
@@ -190,10 +214,16 @@ export function resourceFiles(rawName: string, target: ResourceOptions): readonl
     ...jobFiles(`reindex-${feature.kebab}`, slice),
     { path: `${dir}/service.ts`, contents: serviceSource(feature) },
     { path: `${dir}/service.test.ts`, contents: serviceTest(feature) },
-    { path: `${dir}/ui.tsx`, contents: uiSource(feature) },
+    { path: `${dir}/ui.tsx`, contents: uiSource(feature, target.catalogModule) },
     { path: `${dir}/ui.module.scss`, contents: uiStyle() },
-    { path: `${dir}/ui/${feature.kebab}-card.tsx`, contents: cardSource(feature) },
-    { path: `${dir}/ui/${feature.kebab}-form.tsx`, contents: formSource(feature) },
+    {
+      path: `${dir}/ui/${feature.kebab}-card.tsx`,
+      contents: cardSource(feature, target.catalogModule),
+    },
+    {
+      path: `${dir}/ui/${feature.kebab}-form.tsx`,
+      contents: formSource(feature, target.catalogModule),
+    },
     ...locales.map((locale) => ({
       path: catalogPath(locale),
       contents: catalogSource(feature),

package/src/templates/route.ts

@@ -69,7 +69,27 @@ export const routeParams = (path: string): readonly string[] =>
 const routeDir = (surface: Surface, path: string): string =>
   `apps/web/${surface}/${segmentsOf(path).join('/')}`;
 
-const pageSource = (surface: Surface, path: string): string => {
+/**
+ * How the generated page reaches a string, and it is the whole reason this generator takes an app
+ * module at all. `useT()` comes from the app's own catalog module — the one that calls
+ * `defineCatalogs()` — so a page that renders a string DEPENDS on the module that registers them.
+ * Reaching straight for `t` in `@ultimat3/i18n` renders strings while depending on nothing, which
+ * is how a shipped app served `⟦app.play.title⟧` on every page with a green gate (issue #249), and
+ * this generator is where that idiom came from.
+ *
+ * An app with no catalog module keeps the framework import: emitting one that cannot resolve would
+ * trade a wrong idiom for a file that does not compile.
+ */
+const catalogImport = (module: string | undefined): string =>
+  module === undefined
+    ? "import { t } from '@ultimat3/i18n';"
+    : `import { useT } from '${module}';`;
+
+/** `useT()` is per render, so the body binds it; `meta` takes the router's own `t`. */
+const translatorBinding = (module: string | undefined): string =>
+  module === undefined ? '' : '\n  const t = useT();\n';
+
+const pageSource = (surface: Surface, path: string, module: string | undefined): string => {
   const name = pascal(
     path
       .split('/')
@@ -79,7 +99,7 @@ const pageSource = (surface: Surface, path: string): string => {
   return `// Route: /${path} on the ${surface} surface. Config first: render mode, offline
 // strategy and budget are declarations, not runtime choices.
 
-import { t } from '@ultimat3/i18n';
+${catalogImport(module)}
 import { defineRoute } from '@ultimat3/render';
 import styles from './page.module.scss';
 
@@ -88,13 +108,13 @@ export const config = defineRoute({
   hydrate: '${HYDRATE[surface]}',
   offline: '${OFFLINE[surface]}',
   budget: ${budgetLiteral(surface)},
-  meta: () => ({
+  meta: ({ t }) => ({
     title: t('${titleKey(path)}'),
     description: t('${titleKey(path).replace('.title', '.description')}'),
   }),
 });
 
-export function ${name}Page() {
+export function ${name}Page() {${translatorBinding(module)}
   return (
     <main class={styles.page}>
       <h1>{t('${titleKey(path)}')}</h1>
@@ -202,6 +222,12 @@ export interface RouteOptions {
   readonly surface: Surface;
   /** Every locale the catalog entry ships for. Defaults to `['en']` — an app narrows or grows it. */
   readonly locales?: readonly string[];
+  /**
+   * The app's own catalog module — `@<app>/i18n`, read off `packages/i18n/package.json` by
+   * `resolveCatalogModule`. Absent for an app that ships no such package, and only then does the
+   * generated page fall back to importing `t` from `@ultimat3/i18n`.
+   */
+  readonly catalogModule?: string;
 }
 
 export function routeFiles(rawPath: string, options: RouteOptions): readonly GeneratedFile[] {
@@ -209,7 +235,7 @@ export function routeFiles(rawPath: string, options: RouteOptions): readonly Gen
   const dir = routeDir(options.surface, path);
   const locales = resolveLocales(options.locales);
   return [
-    { path: `${dir}/page.tsx`, contents: pageSource(options.surface, path) },
+    { path: `${dir}/page.tsx`, contents: pageSource(options.surface, path, options.catalogModule) },
     { path: `${dir}/page.module.scss`, contents: styleSource() },
     { path: `${dir}/page.test.ts`, contents: routeTest(options.surface, path) },
     { path: `${dir}/page.e2e.test.ts`, contents: routeE2eTest(path) },

package/src/templates/scaffold-app.ts

@@ -7,6 +7,10 @@ import { apiFiles } from './scaffold-api';
 import { icon } from './scaffold-icon';
 import { rolesFiles } from './scaffold-roles';
 
+// The one dependency this manifest names, and it is not decoration: every page below reads its
+// strings through `@<app>/i18n`'s `useT()`, so the surface that renders a string DEPENDS on the
+// module that registers the catalogs. An undeclared workspace dependency resolves through the root
+// symlink and then breaks the day the app is built anywhere else.
 const webPackage = (app: NameSet): string => `{
   "name": "@${app.kebab}/web",
   "version": "0.0.0",
@@ -18,6 +22,9 @@ const webPackage = (app: NameSet): string => `{
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@${app.kebab}/i18n": "0.0.0"
   }
 }
 `;
@@ -34,7 +41,12 @@ const tsconfig = (): string => `{
 const sitePage = (
   app: NameSet,
 ): string => `// The landing page. site/ is 0kb JS: static render, hydrate never, no framework script tag.
-import { t } from '@ultimat3/i18n';
+//
+// Strings come from \`useT()\` — this app's own catalog module — and never from
+// \`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';
 import styles from './page.module.scss';
 
@@ -43,13 +55,17 @@ export const config = defineRoute({
   hydrate: 'never',
   offline: 'precache',
   budget: { js: '0kb' },
-  meta: () => ({
+  // \`t\` is handed to \`meta\` by the router — one translator per render, resolved against the
+  // request's locale before the head is built.
+  meta: ({ t }) => ({
     title: t('site.home.title'),
     description: t('site.home.description'),
   }),
 });
 
 export function HomePage() {
+  const t = useT();
+
   return (
     <main class={styles.hero}>
       <h1>{t('site.home.title')}</h1>
@@ -103,11 +119,13 @@ unitTest('the landing page ships zero JS and declares metadata', async () => {
 });
 `;
 
-const dashboardPage =
-  (): string => `// The authed dashboard. app/ streams: a static shell is flushed instantly and the holes arrive
+const dashboardPage = (
+  app: NameSet,
+): string => `// The authed dashboard. app/ streams: a static shell is flushed instantly and the holes arrive
 // as their data resolves.
 
-import { t } from '@ultimat3/i18n';
+// \`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';
 import styles from './page.module.scss';
 
@@ -123,10 +141,15 @@ export const config = defineRoute({
   // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
   policy: { permission: 'dashboard:read' },
   budget: { js: '60kb' },
-  meta: () => ({ title: t('app.dashboard.title'), description: t('app.dashboard.description') }),
+  meta: ({ t }) => ({
+    title: t('app.dashboard.title'),
+    description: t('app.dashboard.description'),
+  }),
 });
 
 export function DashboardPage() {
+  const t = useT();
+
   return (
     <section class={styles.panel}>
       <h1>{t('app.dashboard.title')}</h1>
@@ -157,14 +180,18 @@ unitTest('the dashboard renders on the server, is gated, and has an offline stra
 });
 `;
 
-const offlineFallback =
-  (): string => `// The offline fallback. Every app/ route with offline: 'runtime' falls back here, so a train
+const offlineFallback = (
+  app: NameSet,
+): string => `// The offline fallback. Every app/ route with offline: 'runtime' falls back here, so a train
 // tunnel shows the product's own shell instead of the browser's error page.
 
-import { t } from '@ultimat3/i18n';
+// \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
+import { useT } from '@${app.kebab}/i18n';
 import styles from './offline.module.scss';
 
 export function OfflineFallback() {
+  const t = useT();
+
   return (
     <main class={styles.offline}>
       <h1>{t('app.offline.title')}</h1>
@@ -267,6 +294,8 @@ unitTest('holds answers from the role map, and an anonymous actor holds nothing'
 });
 `;
 
+// Same one dependency as `apps/web`, and for the same reason: `app/admin/page.tsx` reads its
+// strings through `@<app>/i18n`'s `useT()`.
 const adminPackage = (app: NameSet): string => `{
   "name": "@${app.kebab}/admin",
   "version": "0.0.0",
@@ -278,28 +307,36 @@ const adminPackage = (app: NameSet): string => `{
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@${app.kebab}/i18n": "0.0.0"
   }
 }
 `;
 
-const adminPage =
-  (): string => `// The generated admin dashboard. It ships an MCP surface over the app's own actions, so the
+const adminPage = (
+  app: NameSet,
+): string => `// The generated admin dashboard. It ships an MCP surface over the app's own actions, so the
 // user's agents can drive the user's product with the user's permissions.
 
-import { t } from '@ultimat3/i18n';
+// \`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';
 
 export const config = defineRoute({
-  render: 'spa',
+  render: 'ssr',
   hydrate: 'idle',
   offline: 'network-only',
-  // A spa renders no data, so the shell itself must be gated — @ultimat3/render requires it.
+  // Behind auth, and \`ssr\` is the one mode that can be: it renders per request, so the guard runs
+  // on the server before the page does. \`static\` and \`isr\` refuse a policy outright.
   policy: { permission: 'admin:read' },
   budget: { js: '120kb' },
-  meta: () => ({ title: t('admin.home.title'), description: t('admin.home.description') }),
+  meta: ({ t }) => ({ title: t('admin.home.title'), description: t('admin.home.description') }),
 });
 
 export function AdminHome() {
+  const t = useT();
+
   return <h1>{t('admin.home.title')}</h1>;
 }
 `;
@@ -402,10 +439,10 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
     { path: 'apps/web/site/page.module.scss', contents: siteStyle() },
     { path: 'apps/web/site/page.test.ts', contents: sitePageTest() },
-    { path: 'apps/web/app/dashboard/page.tsx', contents: dashboardPage() },
+    { 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() },
-    { path: 'apps/web/app/offline.tsx', contents: offlineFallback() },
+    { 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`.
     ...apiFiles(example),
@@ -425,7 +462,7 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     // `apps/web/site/page.tsx` — `x dev` loads both surfaces into one route table and the
     // scaffolded app failed its own `x routes` with X_ROUTE_DUPLICATE. `/admin` also matches
     // @ultimat3/admin's own `basePath` default, so the two agree instead of merely not clashing.
-    { path: 'apps/admin/app/admin/page.tsx', contents: adminPage() },
+    { path: 'apps/admin/app/admin/page.tsx', contents: adminPage(app) },
     { path: 'apps/mobile/README.md', contents: placeholder('mobile', app) },
     { path: 'apps/desktop/README.md', contents: placeholder('desktop', app) },
   ];

package/src/templates/scaffold-container.ts

@@ -21,7 +21,7 @@ const dockerfile = (
 # syntax=docker/dockerfile:1
 
 # ---------- deps: runtime dependencies only, cached on the workspace manifests ----------
-FROM oven/bun:1.3-alpine AS deps
+FROM oven/bun:1.4-alpine AS deps
 WORKDIR /app
 COPY package.json bun.lock ./
 # The workspace members' manifests are what \`bun install\` resolves against; their sources are not.
@@ -34,7 +34,7 @@ RUN bun install --frozen-lockfile --production
 # before it ever calls \`docker build\`. Re-running typecheck and lint here would need the
 # devDependencies the \`--production\` install above deliberately leaves out — which is exactly how
 # a build stage came to run \`tsc\` and \`biome\` against a tree that had neither.
-FROM oven/bun:1.3-alpine AS runtime
+FROM oven/bun:1.4-alpine AS runtime
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
 COPY . .

package/src/templates/scaffold-db-package.ts

@@ -28,20 +28,6 @@ export * as schema from './schema';
 const SCHEMA_HEADER = `// Every entity the app declares, re-exported here. This list is what the migration generator
 // reads, so an entity that is not exported here does not exist as far as the database is concerned.`;
 
-/**
- * `bun run db:seed`'s entry point. Identical either way — only the rows differ. Interpolated, not
- * nested, so it carries exactly the escaping a single template literal needs.
- */
-const SEED_MAIN = `
-
-if (import.meta.main) {
-  const count = await seed();
-  // Bun's stdout, not process.stdout: one runtime, one API. Awaited because the write resolves
-  // asynchronously, and this JSON line is the whole output of \`bun run db:seed\`.
-  await Bun.stdout.write(\`\${JSON.stringify({ ok: true, seeded: count })}\\n\`);
-}
-`;
-
 const dbSchema = (app: NameSet, example: boolean): string =>
   example
     ? `${SCHEMA_HEADER}
@@ -52,34 +38,66 @@ export { post } from '@${app.kebab}/web/app/post/entity';
 export {};
 `;
 
+/**
+ * The seed, as a `defineSeed()` — which is what `x db seed` discovers and what the framework has
+ * meant by "a seed" since 2.0.0.
+ *
+ * It used to be a plain `export async function seed()` with an `import.meta.main` block, run by a
+ * `bun run db:seed` npm script, and that shipped two defects at once. `x db seed` discovers
+ * every `seed*.ts` under a package's `src` and looks for an exported `Seed`, so the scaffold's
+ * own seed was invisible to its own command — `x db seed` on a fresh app answered "no seed
+ * matched".
+ * And `bun run db:seed` reaches the database through `@ultimat3/db`'s `db()`, which reads
+ * `DATABASE_URL` and speaks `postgres:` only, so on a clone with no Postgres it cannot see the
+ * embedded PGlite that `x db migrate` had just migrated in process. `bin/setup` therefore printed
+ * `✓ migrations applied` and then died on `X_DB_UNAVAILABLE`, whose `fix:` says "run `x dev` to use
+ * the embedded PGlite" — naming the mechanism that had just worked one line above.
+ *
+ * `x db seed` owns the connection, the tier and the per-seed transaction. One runner, one answer.
+ */
 const dbSeed = (app: NameSet, example: boolean): string =>
   example
-    ? `// Deterministic seed: same rows every time, so a test and a demo see the same database.
-import { db, sql } from '@ultimat3/db';
-
-const ORG = '00000000-0000-0000-0000-000000000002';
+    ? `// Deterministic fixtures: the same rows every time, so a test, a demo and a branch database
+// all see the same content.
+//
+// \`x db seed\` is the runner — it discovers every exported \`defineSeed()\` in a package's
+// \`src/seed*.ts\`, opens the database exactly as \`x db migrate\` does (embedded PGlite
+// included), and wraps each seed in its own transaction. Never a plain \`bun run\` script: that
+// reaches the database through \`db()\`, which needs a \`postgres:\` \`DATABASE_URL\` and so cannot
+// see the embedded database at all.
+import { defineSeed } from '@ultimat3/entity';
+import { post } from './schema';
 
-export async function seed(): Promise<number> {
-  const rows = [
-    { id: '00000000-0000-0000-0000-000000000101', title: 'Hello ${app.pascal}', minor: 0 },
-    { id: '00000000-0000-0000-0000-000000000102', title: 'Second post', minor: 1900 },
-  ];
-  for (const row of rows) {
-    // Idempotent by primary key, so re-seeding a branch database is a no-op rather than a crash.
-    await db().execute(sql\`
-      insert into posts (id, org_id, title, price_minor, price_currency)
-      values (\${row.id}, \${ORG}, \${row.title}, \${row.minor}, 'USD')
-      on conflict (id) do nothing\`);
-  }
-  return rows.length;
-}${SEED_MAIN}`
-    : `// Deterministic seed: same rows every time, so a test and a demo see the same database.
-// No entity is declared yet, so there is nothing to insert — the shape stays, so the first
-// \`x g entity\` has one obvious place to seed from.
+/** Stable across runs: \`id('post:hello')\` is a UUID v5 of the label, not a random one. */
+export const ${app.camel}Seed = defineSeed('${app.kebab}', async ({ insert, id }) => {
+  await insert(post, [
+    {
+      id: id('post:hello'),
+      orgId: id('org:demo'),
+      title: 'Hello ${app.pascal}',
+      price: { minor: 0, currency: 'USD' },
+    },
+    {
+      id: id('post:second'),
+      orgId: id('org:demo'),
+      title: 'Second post',
+      price: { minor: 1900, currency: 'USD' },
+    },
+  ]);
+});
+`
+    : `// Deterministic fixtures, run by \`x db seed\`. No entity is declared yet, so there is nothing
+// to insert — the shape stays so the first \`x g entity\` has one obvious place to seed from.
+//
+// \`x db seed\` discovers every exported \`defineSeed()\` in a package's \`src/seed*.ts\` and opens
+// the database the way \`x db migrate\` does, embedded PGlite included. Never a plain \`bun run\`
+// script: that needs a \`postgres:\` \`DATABASE_URL\` and cannot see the embedded database.
+import { defineSeed } from '@ultimat3/entity';
 
-export async function seed(): Promise<number> {
-  return 0;
-}${SEED_MAIN}`;
+export const ${app.camel}Seed = defineSeed('${app.kebab}', async () => {
+  // \`await insert(<entity>, [...])\` once an entity exists.
+});
+`;
 
 /** Every file the `packages/db` workspace ships, in the order `x new` writes them. */
 export const dbPackageFiles = (app: NameSet, example: boolean): readonly GeneratedFile[] => [

package/src/templates/scaffold-docs.ts

@@ -88,7 +88,11 @@ bun install
 # this script is documented idempotent, and the guard is what makes that true here.
 ls packages/db/migrations/*.sql >/dev/null 2>&1 || bunx x db gen "initial"
 bunx x db migrate "$@"
-bun run db:seed
+# \`x db seed\`, never \`bun run\`: 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 — one line after reporting a
+# successful migration.
+bunx x db seed
 echo "setup complete — next: x dev"
 `;
 
@@ -103,6 +107,19 @@ const binCheck = (): string => `#!/usr/bin/env bash
 # The gate. Same steps as CI, because a check that lives only in CI cannot be run locally.
 set -euo pipefail
 cd "$(dirname "$0")/.."
+# 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. Cheap on a warm tree, and it makes "green" reachable from a fresh clone.
+#
+# \`--json\` is forwarded to BOTH, or the contract breaks: \`bin/check --json\` would otherwise print
+# the build's human renderer to stdout and then the gate's JSON, and a machine consumer reading one
+# document off stdout gets neither. Both commands emit one object; a reader takes the last line.
+build_flags=""
+for arg in "$@"; do
+  case "$arg" in --json|-j) build_flags="--json" ;; esac
+done
+bunx x build --target static $build_flags
 exec bunx x verify "$@"
 `;
 

package/src/templates/scaffold-i18n.ts

@@ -87,8 +87,15 @@ export type AppCatalog = typeof en;
 export type TranslationKey = KeyOf<AppCatalog>;
 
 /**
- * Use this, never \`useI18n()\` directly — the type parameter is what makes an unknown key a
- * compile error instead of a \`⟦key⟧\` someone notices in production.
+ * The app's ONE way to read a string. Never \`useI18n()\` directly and never \`t\` from
+ * \`@ultimat3/i18n\`, for two independent reasons:
+ *
+ * 1. the type parameter makes an unknown key a compile error instead of a \`⟦key⟧\` someone
+ *    notices in production;
+ * 2. importing THIS module is what registers the catalogs — \`defineCatalogs()\` above runs on
+ *    import and nowhere else. A page that reached past it rendered every string as \`⟦key⟧\`
+ *    with \`x verify\` green, because nothing in the app depended on the module that registers
+ *    (issue #249). \`x i18n check\` now refuses that app; this import is why it never happens.
  */
 export const useT = (): Translator<AppCatalog> => useI18n<AppCatalog>();
 `;

package/src/templates/scaffold-repo.ts

@@ -45,12 +45,12 @@ const rootPackage = (app: NameSet, version: string): string => `{
     "lint": "biome check .",
     "test": "bun test",
     "db:migrate": "x db migrate",
-    "db:seed": "bun run packages/db/src/seed.ts"
+    "db:seed": "x db seed"
   },
   "devDependencies": {
     "@biomejs/biome": "${BIOME_VERSION}",
     "@electric-sql/pglite": "^0.5.4",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "@ultimat3/testing": "^${version}",
     "typescript": "^6.0.3"
   },