@ultimat3/cli 29.4.0 → 30.1.0

package/src/templates/resource-page.ts

@@ -1,6 +1,7 @@
-// `x g resource <name>`'s page: the plural route a slice is reached at. It READS — `load` calls the
-// slice's own query as the request's actor — renders the rows through the slice's list component
-// inside `AsyncRegion` (ready, empty, failed), and mounts the slice's form island. `x g route`
+// `x g resource <name>`'s page: the plural route a slice is reached at. It READS — a `<Hole>` calls
+// the slice's own query a page at a time as the request's actor, after the shell left — renders the
+// rows in a link-mode `DataTable` (loading, failed, empty, ready; paged by URL, no script), and
+// mounts the slice's form island. `x g route`
 // writes a page with a heading and nothing to read; a resource has rows and a form, and a page
 // that showed neither was a slice nobody could reach without wiring it by hand.
 
@@ -8,7 +9,8 @@ import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { titleKey } from './naming';
 import { formIslandSpecifier } from './resource-form-island';
-import { LINE_WIDTH } from './wrap';
+import { pageDbTest } from './resource-page-db';
+import { LINE_WIDTH, wrapImport } from './wrap';
 
 /**
  * The page's JS budget — MEASURED, never a ceiling picked to pass. `x build --target static` on a
@@ -20,9 +22,18 @@ import { LINE_WIDTH } from './wrap';
  * byte-identical since 1.4.1 (issue #354), so no headroom is held for run-to-run movement. An app
  * that adds per-document scripts (`navigation: { client: [...] }` charges its router, ~18 kB, to
  * every `app/` page) is over it on its first build, and `nextSteps` sends the author there.
+ *
+ * Raised to 68kb (69,632) on 2026-11-06, measured on Bun 1.4.4 the same way: 66,285 B — the island
+ * 65,430 + the runtime 855, over 64kb by 749 B. why: `@ultimat3/ui` grew a wave of components
+ * (pickers, lists, viewers, drag, charts) and the island carries ui's whole catalog-key list
+ * (`i18n-keys.ts`) beside the Form/Input/Button it renders. The same 3.3 kB of headroom.
+ *
+ * Lowered to 66kb (67,584) the same day, measured the same way: 64,167 B — the island 63,312 +
+ * the runtime 855. why: `UI_KEYS` became a namespace over `ui-keys.ts`, so the island keeps the
+ * three keys its components read, not all of them (−2,118 B). The same ~3.4 kB of headroom.
  */
-export const RESOURCE_PAGE_BUDGET = '64kb';
-export const RESOURCE_PAGE_MEASURED = '59,679 B';
+export const RESOURCE_PAGE_BUDGET = '66kb';
+export const RESOURCE_PAGE_MEASURED = '64,167 B';
 
 /** How the page reaches a string — the same rule `route.ts` states, for the same issue (#249). */
 const catalogImport = (module: string | undefined): string =>
@@ -36,11 +47,12 @@ const i18nImports = (module: string | undefined): readonly string[] =>
     ? ["import { currentLocale, t } from '@ultimat3/i18n';"]
     : [catalogImport(module), "import { currentLocale } from '@ultimat3/i18n';"];
 
-/** `const load = … => rowsState(() => <read>(input()));`, as Biome prints it at any name length. */
-const loadLine = (read: string): string => {
-  const head = 'const load = (): Promise<PageData> =>';
-  const body = `rowsState(() => ${read}(input()));`;
-  return `${head} ${body}`.length <= LINE_WIDTH ? `${head} ${body}` : `${head}\n  ${body}`;
+/** The read in `rows()`, as Biome prints it at any name length. */
+const stateLine = (read: string): string => {
+  const line = `  const state = await rowsState(() => ${read}.page(inputOf(list), windowOf(list)));`;
+  return line.length <= LINE_WIDTH
+    ? line
+    : `  const state = await rowsState(() =>\n    ${read}.page(inputOf(list), windowOf(list)),\n  );`;
 };
 
 export interface ResourcePageOptions {
@@ -59,6 +71,7 @@ const pageSource = (options: ResourcePageOptions): string => {
   const { feature } = options;
   const path = feature.pluralKebab;
   const list = `${feature.camel}List`;
+  const translator = options.catalogModule === undefined ? '' : '\n  const t = useT();\n';
   const open = options.shell
     ? '<Shell>\n      <div class={styles.page}>'
     : '<main class={styles.page}>';
@@ -69,24 +82,25 @@ const pageSource = (options: ResourcePageOptions): string => {
       .split('\n')
       .map((line) => (line === '' ? line : `${indent}${line}`))
       .join('\n');
-  return `// /${path}: the org's ${feature.pluralKebab}, newest first, and the form that adds one. \`load\`
-// reads through the slice's own query, so the policy, the tenancy and the order are the query's;
-// the form is the slice's island, the one module of this page a browser downloads.
+  return `// /${path}: the org's ${feature.pluralKebab}, newest first, and the form that adds one.
+// The rows are read inside a \`<Hole>\`, through the slice's own query, so the shell and the form
+// are on screen before the read answers; the policy, the tenancy and the order are the query's.
+// The pager is links (\`listUrl\`), so paging needs no script; the form is the slice's island, the
+// one module of this page a browser downloads.
 
 ${sortedImports([
   ...i18nImports(options.catalogModule),
   "import { derivePath } from '@ultimat3/action';",
-  "import type { AsyncState } from '@ultimat3/core';",
+  "import type { AsyncState, Page as RowPage } from '@ultimat3/core';",
   "import type { KnownPermission } from '@ultimat3/policy';",
-  "import { defineRoute, island } from '@ultimat3/render';",
-  "import { AsyncRegion, EmptyState, PageHeader, Section, Skeleton } from '@ultimat3/ui';",
+  "import { defineRoute, Hole, island } from '@ultimat3/render';",
+  "import {\n  DataTable,\n  type ListUrl,\n  listUrl,\n  Money,\n  PageHeader,\n  Section,\n  Skeleton,\n} from '@ultimat3/ui';",
 ])}
 ${options.shell ? "import { Shell } from '../../shared/shell';\n" : ''}import type { ${feature.pascal} } from '../${feature.kebab}/entity';
-import { ${list} } from '../${feature.kebab}/live/${feature.kebab}-list';
-import { ${feature.pascal}List } from '../${feature.kebab}/ui';
+${wrapImport([list, `${list}Sorts`], `../${feature.kebab}/live/${feature.kebab}-list`)}
 import styles from './page.module.scss';
 
-/** One page of rows: the read's own bound. Past it, page with a cursor (\`${list}.page\`). */
+/** The most rows one page shows; \`?limit=\` may ask for fewer, never more. */
 const PAGE_ROWS = 50;
 
 /** The currency a price is typed in; the form sends integer minor units of it. */
@@ -94,14 +108,14 @@ const CURRENCY = 'USD';
 
 type Row = ${feature.pascal};
 
-/** What \`load\` answers: the read's outcome as DATA, so the page renders each of its states. */
-export type PageData = AsyncState<readonly Row[]>;
+/** The read's outcome as DATA, so the table renders each of its states. */
+export type PageData = AsyncState<RowPage<Row>>;
 
 /**
- * The read, as a state. A refusal or a failed read is the region's error branch — code, cause and
- * fix on screen, the form still there — never a 500 for the whole document.
+ * The read, as a state. A refusal, a failed read or a stale cursor is the table's error branch —
+ * code, cause and fix on screen, the form still there — never a 500 for the whole document.
  */
-export async function rowsState(read: () => Promise<readonly Row[]>): Promise<PageData> {
+export async function rowsState(read: () => Promise<RowPage<Row>>): Promise<PageData> {
   try {
     return { status: 'ready', data: await read() };
   } catch (error) {
@@ -109,10 +123,62 @@ export async function rowsState(read: () => Promise<readonly Row[]>): Promise<Pa
   }
 }
 
-/** No org: the query reads the ACTOR's, so a read can only ever be for the caller's own org. */
-const input = () => ({ limit: PAGE_ROWS });
+/** The list's state in the URL: a sort among the query's own columns, a cursor, a page size. */
+type ListState = ListUrl<(typeof ${list}Sorts)[number]>;
 
-${loadLine(list)}
+const listOf = (url: string | undefined): ListState =>
+  listUrl(url ?? '/${path}', {
+    sorts: ${list}Sorts,
+    limit: { default: PAGE_ROWS, max: PAGE_ROWS },
+  });
+
+/**
+ * No org: the query reads the ACTOR's, so a read can only ever be for the caller's own org. No
+ * sort in the URL is the query's own order, newest first; a cursor is minted for one sort alone,
+ * and \`listUrl\` drops it whenever the sort changes.
+ */
+const inputOf = (list: ListState) =>
+  list.sort === undefined
+    ? { limit: PAGE_ROWS }
+    : { limit: PAGE_ROWS, sort: list.sort.key, dir: list.sort.direction };
+
+/** The page the URL names: its size, and the cursor it reads after when it is not the first. */
+const windowOf = (list: ListState) =>
+  list.cursor === undefined ? { first: list.limit } : { first: list.limit, after: list.cursor };
+
+/** The rows, once they are read. Called by the \`<Hole>\`: it starts after the first flush. */
+async function rows(list: ListState) {${translator}
+${stateLine(list)}
+  const page = state.status === 'ready' ? state.data : undefined;
+  return (
+    <DataTable
+      caption={t('${titleKey(path)}')}
+      rows={page?.rows ?? []}
+      rowKey={(row: Row) => row.id}
+      error={state.status === 'failed' ? state.error : undefined}
+      emptyTitle={t('app.${feature.kebab}.empty')}
+      columns={[
+        {
+          key: 'title',
+          header: t('app.${feature.kebab}.titleLabel'),
+          sortable: true,
+          cell: (row) => row.title,
+        },
+        {
+          key: 'price',
+          header: t('app.${feature.kebab}.priceLabel'),
+          numeric: true,
+          cell: (row) => <Money value={row.price} />,
+        },
+      ]}
+      sort={list.sort}
+      sortHrefFor={list.sortHrefFor}
+      nextCursor={page?.nextCursor}
+      hrefFor={list.hrefFor}
+      firstHref={list.firstHref}
+    />
+  );
+}
 
 // Declared ABOVE \`defineRoute\`: the route drains the islands declared before it. Named by
 // SPECIFIER, never imported — a string has no import edge, so the page's bundle graph stays the
@@ -123,28 +189,24 @@ const ${feature.pascal}Form = island({
 });
 
 export const config = defineRoute({
-  render: 'ssr',
+  render: 'stream',
   hydrate: 'visible',
   offline: 'runtime',
   // An org's rows are not public: a route with no policy registers \`auth: 'public'\` and its
   // response carries no \`vary: cookie\`. Which ORG is the query's decision, on every read.
   policy: { permission: '${feature.kebab}:read' satisfies KnownPermission },
-  // measured: ${RESOURCE_PAGE_MEASURED} (\`x build --target static\`, Bun 1.4.0) — the form island and the
+  // measured: ${RESOURCE_PAGE_MEASURED} (\`x build --target static\`, Bun 1.4.4) — the form island and the
   // \`visible\` runtime. why: the form is Solid, @ultimat3/ui's Form/Input/Button and the transport.
   // A raise states its own measured bytes and why here, in the same diff (\`X_BUDGET_EXCEEDED\`).
   budget: { js: '${RESOURCE_PAGE_BUDGET}' },
-  load,
   meta: ({ t }) => ({
     title: t('${titleKey(path)}'),
     description: t('${titleKey(path).replace('.title', '.description')}'),
   }),
 });
 
-export interface PageProps {
-  readonly data: PageData;
-}
-
-export function Page(props: PageProps) {${options.catalogModule === undefined ? '' : '\n  const t = useT();\n'}
+export function Page(props: { readonly url?: string | undefined }) {${options.catalogModule === undefined ? '' : '\n  const t = useT();\n'}
+  const list = listOf(props.url);
   return (
     ${open}
 ${inner(`<PageHeader title={t('${titleKey(path)}')} />
@@ -164,12 +226,7 @@ ${inner(`<PageHeader title={t('${titleKey(path)}')} />
     <Skeleton lines={3} />
   </${feature.pascal}Form>
 </Section>
-<AsyncRegion
-  state={props.data}
-  reserve={{ lines: 3 }}
-  empty={() => <EmptyState title={t('app.${feature.kebab}.empty')} />}
-  ready={(rows) => <${feature.pascal}List rows={rows} />}
-/>`)}
+<Hole fallback={<Skeleton lines={3} />}>{() => rows(list)}</Hole>`)}
 ${close}
   );
 }
@@ -182,9 +239,9 @@ const OTHER_ORG = '00000000-0000-4000-8000-000000000009';
 const pageTest = (options: ResourcePageOptions): string => {
   const { feature } = options;
   const t = options.catalogModule === undefined ? '' : '\n  const t = useT();';
-  return `// /${feature.pluralKebab}, rendered as a request renders it: \`load\` reads the actor's org through the
-// slice's query — the in-memory driver under test — and the page shows the rows, the empty state
-// or the refusal, with the form island beside them in every one.
+  return `// /${feature.pluralKebab}, rendered as a request renders it, with the \`<Hole>\` awaited in line: the
+// read names the actor's org through the slice's query — the in-memory driver under test — and the
+// page shows the rows, the empty state or the refusal, with the form island beside them in each.
 ${sortedImports([
   catalogImport(options.catalogModule),
   `import { driver } from '${options.dbModule}';`,
@@ -224,7 +281,7 @@ unitTest('the page lists the org’s rows, newest first, beside the form', async
   clock.advance(1000);
   await store('newer');
   const view = await renderRoute(page, { url, actor: member });
-  expect(view.data.status).toBe('ready');
+  expect(view.text).toContain('newer');
   expect(view.text.indexOf('newer')).toBeLessThan(view.text.indexOf('older'));
   // The form is the one island, and it wakes when it is visible.
   expect(view.islands.map((island) => island.strategy)).toEqual(['visible']);
@@ -233,30 +290,78 @@ unitTest('the page lists the org’s rows, newest first, beside the form', async
 
 unitTest('an org with no rows reads the empty state, not an empty list', async () => {${t}
   const view = await renderRoute(page, { url, actor: member });
-  expect(view.data).toEqual({ status: 'ready', data: [] });
   expect(view.text).toContain(t('app.${feature.kebab}.empty'));
   expect(view.meta.title).toBe(t('${titleKey(feature.pluralKebab)}'));
 });
 
-unitTest('a member of another org reads none of this org’s rows', async () => {
+unitTest('a member of another org reads none of this org’s rows', async () => {${t}
   await store('ours');
   // The same page, the same URL: which org it reads is the actor's, never a parameter.
   const outsider = testActor('outsider', { orgId: otherOrg, permissions: [read] }).actor;
   const view = await renderRoute(page, { url, actor: outsider });
-  expect(view.data).toEqual({ status: 'ready', data: [] });
+  expect(view.text).not.toContain('ours');
+  expect(view.text).toContain(t('app.${feature.kebab}.empty'));
 });
 
 unitTest('a caller the read refuses sees the refusal, and the page around it', async () => {
   // In the org, without the grant: the query's policy refuses before any row is read.
   const stranger = testActor('stranger', { orgId }).actor;
   const view = await renderRoute(page, { url, actor: stranger });
-  expect(view.data.status).toBe('failed');
   expect(view.html).toContain('X_FORBIDDEN');
   expect(view.islands).toHaveLength(1);
 });
 
+/** The anchor a pager side renders, read off the HTML: \`rel\` names the side. */
+const linkTo = (html: string, rel: string): string | undefined => {
+  const anchor = new RegExp(\`<a\\\\b[^>]*\\\\brel="\${rel}"[^>]*>\`).exec(html)?.[0];
+  return /href="([^"]*)"/.exec(anchor ?? '')?.[1]?.replaceAll('&amp;', '&');
+};
+
+unitTest('the list pages by link: a cursor in the URL, no script', async () => {
+  await store('older');
+  clock.advance(1000);
+  await store('newer');
+  const first = await renderRoute(page, { url: \`\${url}?limit=1\`, actor: member });
+  expect(first.text).toContain('newer');
+  expect(first.text).not.toContain('older');
+  // The first page has nowhere back to, and a keyset page has no Previous.
+  expect(first.html).not.toContain('href="/${feature.pluralKebab}?limit=1"');
+  expect(linkTo(first.html, 'prev')).toBeUndefined();
+  const next = linkTo(first.html, 'next');
+  expect(next).toContain('after=');
+
+  const second = await renderRoute(page, { url: new URL(next ?? '', url).href, actor: member });
+  expect(second.text).toContain('older');
+  expect(second.text).not.toContain('newer');
+  // The last page links back to the first and on to nothing, never to \`after=null\`.
+  expect(second.html).toContain('href="/${feature.pluralKebab}?limit=1"');
+  expect(linkTo(second.html, 'next')).toBeUndefined();
+  expect(second.html).not.toContain('after=null');
+});
+
+unitTest('the list sorts by link, and a sorted list pages in that order', async () => {
+  // Written so that newest-first and by-title disagree: a sort applied after the bound would show
+  // the two newest re-sorted, never the first two titles.
+  for (const title of ['beta', 'gamma', 'alpha']) {
+    await store(title);
+    clock.advance(1000);
+  }
+  const sorted = \`\${url}?sort=title&dir=asc&limit=2\`;
+  const first = await renderRoute(page, { url: sorted, actor: member });
+  expect(first.text.indexOf('alpha')).toBeLessThan(first.text.indexOf('beta'));
+  expect(first.text).not.toContain('gamma');
+  // The header links on to the next state of its cycle, the cursor dropped with the old order.
+  const descending = 'href="/${feature.pluralKebab}?sort=title&amp;dir=desc&amp;limit=2"';
+  expect(first.html).toContain(descending);
+  const next = linkTo(first.html, 'next');
+  expect(next).toContain('sort=title');
+  const second = await renderRoute(page, { url: new URL(next ?? '', url).href, actor: member });
+  expect(second.text).toContain('gamma');
+  expect(second.text).not.toContain('alpha');
+});
+
 unitTest('it is gated, rendered per request, and budgeted', () => {
-  expect(page.config.render).toBe('ssr');
+  expect(page.config.render).toBe('stream');
   expect(page.config.policy?.permission).toBe(read);
   expect(page.config.offline).toBe('runtime');
   expect(page.config.budget.js).toBe('${RESOURCE_PAGE_BUDGET}');
@@ -264,8 +369,12 @@ unitTest('it is gated, rendered per request, and budgeted', () => {
 `;
 };
 
-/** The resource's `page.tsx` and its unit test. The stylesheet, e2e test and catalog are `x g route`'s. */
+/**
+ * The resource's `page.tsx`, its unit test, and the same read over the migrated database. The
+ * stylesheet, e2e test and catalog are `x g route`'s.
+ */
 export const resourcePageFiles = (options: ResourcePageOptions): readonly GeneratedFile[] => [
   { path: `${options.pageDir}/page.tsx`, contents: pageSource(options) },
   { path: `${options.pageDir}/page.test.ts`, contents: pageTest(options) },
+  { path: `${options.pageDir}/page-db.test.ts`, contents: pageDbTest(options) },
 ];

package/src/templates/route.ts

@@ -13,13 +13,11 @@ import { kebab, pascal, titleKey } from './naming';
 export type Surface = 'site' | 'app';
 
 /**
- * `ssr` on `app/`, not `stream`, for the reason `scaffold-app.ts`'s dashboard already states:
- * `stream` sets `needsSuspense`, the framework ships no hole marker, and `defineRoute` therefore
- * throws `X_ROUTE_MODE_INVALID` at import. That is not a failing page — it is a page that registers
- * NO route at all, so every `x g route --surface app` and every `x g resource` scaffolded a URL
- * that was absent from `x routes`, from the manifest and from `budgets`. Ship the mode that works.
+ * `stream` on `app/`: the surface's default (`surfaces.ts`), and a stream is always
+ * `private, no-store` where an ungated `ssr` page may be public. A page with no `<Hole>` pays
+ * nothing for it (`renderStreamHtml`), and the first read an author moves into one streams.
  */
-const RENDER: Record<Surface, string> = { site: 'isr', app: 'ssr' };
+const RENDER: Record<Surface, string> = { site: 'isr', app: 'stream' };
 /**
  * `app` is `'visible'` on a page the generator writes with no island, and that is not an oversight.
  * A declared strategy costs nothing when there is nothing to hydrate — `hydrateRuntime` is emitted

package/src/templates/scaffold-app.ts

@@ -10,6 +10,7 @@ import { dashboardFiles } from './scaffold-dashboard';
 import { demoOrgFiles } from './scaffold-demo-org';
 import { entryFiles } from './scaffold-entries';
 import { errorPageFiles } from './scaffold-errors';
+import { exerciseFiles } from './scaffold-exercise';
 import { httpFiles } from './scaffold-http';
 import { icon } from './scaffold-icon';
 import { rolesFiles } from './scaffold-roles';
@@ -407,6 +408,8 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     { path: 'apps/web/tsconfig.json', contents: tsconfig() },
     // The process a container starts and the artifact a CDN is handed — `scaffold-entries.ts`.
     ...entryFiles(),
+    // What `x exercise` cannot guess, empty until a finding says what to paste — `scaffold-exercise.ts`.
+    ...exerciseFiles(),
     { path: 'apps/web/site/icon.png', contents: icon() },
     // The landing page: hero, two calls to action, three feature cards — `scaffold-site.ts`.
     ...siteFiles(app),

package/src/templates/scaffold-auth.ts

@@ -98,7 +98,8 @@ export const devAuthenticate = (request: HeaderRequest): Actor | null => {
 };
 `;
 
-const authModule =
+/** `apps/web/app/auth/auth.ts`: also `x g sign-in`'s, written only where an older app lacks it. */
+export 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.
 //

package/src/templates/scaffold-bin.ts

@@ -1,14 +1,13 @@
-// 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`.
+// The script a scaffolded app is set up by — `bun run setup` — 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. `bun run dev` and `bun run verify` need no file: they are `x dev` and
+// `x verify`, and `x verify` builds what its budgets step weighs (no `bin/check`, plan 101 21).
 
 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. */
@@ -70,53 +69,7 @@ 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() },
-  ];
+  return [{ path: BIN_SCRIPTS.setup, contents: binSetup() }];
 }

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

@@ -7,7 +7,7 @@ import type { GeneratedFile, NameSet } from './naming';
 
 const shape = (app: NameSet): string => `---
 name: shape
-description: Use BEFORE writing any code, at the idea stage — turns a product request into the one decision that governs everything after it: which of the eight primitives each piece is, which slice and surface it lives in, and the exact \`x g\` invocations. Read-only; it decides, it never builds. Also use when a request seems to need something the framework does not have.
+description: Use BEFORE writing any code, at the idea stage — turns a product request into the one decision that governs everything after it: which of the eight primitives each piece is, which slice and surface it lives in, and the exact \`bunx x g\` invocations. Read-only; it decides, it never builds. Also use when a request seems to need something the framework does not have.
 tools: Read, Glob, Grep, Bash
 ---
 
@@ -45,8 +45,8 @@ stop; that answer is worth more than a plan built on a shape the app cannot hold
 | \`packages/db/\` | schema, migrations, seed |
 | \`packages/ui/\` | components with no feature knowledge |
 
-Read the tree before you place anything. \`x routes\`, \`x actions\`, \`x queries\`, \`x entities\`,
-\`x jobs\`, \`x tasks\` and \`x policy list\` are the registries — check whether the thing already
+Read the tree before you place anything. \`bunx x routes\`, \`bunx x actions\`, \`bunx x queries\`, \`bunx x entities\`,
+\`bunx x jobs\`, \`bunx x tasks\` and \`bunx x policy list\` are the registries — check whether the thing already
 exists before proposing it, and add \`--json\` to any of them.
 
 ## Report
@@ -54,7 +54,7 @@ exists before proposing it, and add \`--json\` to any of them.
 \`\`\`
 Build:      yes | no — <one line>
 Pieces:     <primitive> <name> → <dir>          (one line each)
-Generate:   x g <kind> <name> --feature <slice> (one line each, in dependency order)
+Generate:   bunx x g <kind> <name> --feature <slice> (one line each, in dependency order)
 Existing:   <what already covers part of this>
 Refused:    <anything that fits no primitive, and why>
 \`\`\`
@@ -72,17 +72,17 @@ feature slice. Nothing else. A change outside that set is a collision — report
 | Rule | Detail |
 |---|---|
 | The entity is the schema | columns, invariants, indexes and tenancy are declared there, never in SQL |
-| Migrations are generated | edit \`entity.ts\`, then \`x db gen "what changed"\`. Never hand-write a file into \`packages/db/migrations/\` |
+| Migrations are generated | edit \`entity.ts\`, then \`bunx x db gen "what changed"\`. Never hand-write a file into \`packages/db/migrations/\` |
 | Destructive is declared | a migration that drops, truncates or retypes carries \`-- destructive: true\`, or the gate refuses it |
 | \`repo.ts\` is the only door | every read and write goes through it; a raw statement anywhere else is authz bypassed |
-| Branch before you break things | \`x db branch create <name>\`, never the shared dev database |
+| Branch before you break things | \`bunx x db branch create <name>\`, never the shared dev database |
 | Money | \`{ minor, currency }\` — integer minor units and an ISO code, both, always. Never a float |
 | Time | store UTC; a formatted date always names an explicit IANA time zone |
 
-Inspect before you change: \`x entities list\`, \`x entities show <name>\`, both with \`--json\`.
+Inspect before you change: \`bunx x entities list\`, \`bunx x entities show <name>\`, both with \`--json\`.
 
 Checks: \`bun test <path>/entity.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
-once when you are otherwise done. Never \`x verify\` — that belongs to whoever coordinates you.
+once when you are otherwise done. Never \`bunx x verify\` — that belongs to whoever coordinates you.
 `;
 
 const server = (app: NameSet): string => `---
@@ -97,19 +97,19 @@ renders. A change outside that set is a collision — report it, do not make it.
 
 | Rule | Detail |
 |---|---|
-| Generate, then edit | \`x g <kind> <name> --feature <slice>\` for every one of them — a hand-written primitive is missing from every registry that projects it |
+| Generate, then edit | \`bunx x g <kind> <name> --feature <slice>\` for every one of them — a hand-written primitive is missing from every registry that projects it |
 | One authz object | the policy decides; a route or a UI that re-checks is a second answer that will drift |
 | Data through the repo | an action calls \`repo.ts\`, never the database |
-| Errors are instructions | never \`throw new Error\` — subclass \`UltimateError\` with a stable \`X_SCREAMING_SNAKE\` code, a cause and a \`fix:\` a caller can actually run |
+| Errors are instructions | never \`throw new Error\` — declare each code once with \`defineError({ code, title, status, cause, fix })\` from \`@ultimat3/core\`: a stable \`X_SCREAMING_SNAKE\` code, a cause and a \`fix:\` a caller can actually run. \`guards/error-declared.ts\` refuses a handwritten \`UltimateError\` subclass |
 | Jobs run at least once | a handler must be idempotent — an upsert or a statement whose second run changes nothing, never \`count + 1\` |
 | Tasks name a time zone | a cron schedule with an ambient zone is a different time twice a year |
 | No \`any\` | \`unknown\` plus a schema parse |
 
-Inspect before you change: \`x actions show <name>\`, \`x queries show <name>\`, \`x jobs list\`,
-\`x tasks list\`, \`x policy explain <subject>\` — every one takes \`--json\`.
+Inspect before you change: \`bunx x actions show <name>\`, \`bunx x queries show <name>\`, \`bunx x jobs list\`,
+\`bunx x tasks list\`, \`bunx x policy explain <subject>\` — every one takes \`--json\`.
 
 Checks: \`bun test <path>/<file>.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
-once when you are otherwise done. Never \`x verify\` — that belongs to whoever coordinates you.
+once when you are otherwise done. Never \`bunx x verify\` — that belongs to whoever coordinates you.
 `;
 
 const web = (app: NameSet): string => `---
@@ -124,7 +124,7 @@ calls. A change outside that set is a collision — report it, do not make it.
 
 | Rule | Detail |
 |---|---|
-| \`site/\` is 0kb JS | and may not import from \`app/\`. One interactive control on a static page is an island: \`x g island <name> --at <dir>\` |
+| \`site/\` is 0kb JS | and may not import from \`app/\`. One interactive control on a static page is an island: \`bunx x g island <name> --at <dir>\` |
 | \`shared/\` is a leaf | tokens, primitives, the actor type. It imports nothing of yours |
 | The directory is the URL | \`page.tsx\` under \`site/\`/\`app/\`; \`api/\` holds no route file, only \`defineApi()\`'s actions and queries. The filename is never the path |
 | Every string through \`t()\` | a literal in a component is a string no locale can ever translate |
@@ -135,16 +135,16 @@ calls. A change outside that set is a collision — report it, do not make it.
 | The focus ring is replaced | \`outline: none\` on its own leaves a keyboard user with nothing. \`@include tokens.focus-ring\`, or a \`:focus-visible\` box-shadow beside it |
 | Every image has a box | width + height, or an aspect-ratio. An unsized image moves everything under it when its bytes land, and the priority one is never \`loading="lazy"\` |
 | Animate transform and opacity | nothing else composites: a \`top\`, a \`width\` or a \`box-shadow\` costs a layout pass every frame, and \`transition: all\` animates properties nobody chose. \`tokens.duration()\` / \`tokens.easing()\` are the values |
-| An island declares its states | a sibling \`<name>.island.states.ts\`, so \`x shot --island <name> --json\` can photograph the failures nobody can click to |
+| An island declares its states | a sibling \`<name>.island.states.ts\`, so \`bunx x shot --island <name> --json\` can photograph the failures nobody can click to |
 
-Every one of the last five is a build error, not a preference — \`guards/\` holds them and \`x verify\`'s
+Every one of the last five is a build error, not a preference — \`guards/\` holds them and \`bunx x verify\`'s
 \`boundaries\` step runs them. Read the guard rather than guessing at the rule.
 
-Inspect before you change: \`x routes --json\`, \`x i18n check\` for catalog gaps, and
-\`x shot <route> --json\` when you need to see what you built.
+Inspect before you change: \`bunx x routes --json\`, \`bunx x i18n check\` for catalog gaps, and
+\`bunx x shot <route> --json\` when you need to see what you built.
 
 Checks: \`bun test <path>/page.test.ts\`, \`bunx biome check --write <paths>\`, and \`bun run typecheck\`
-once when you are otherwise done. Never \`x verify\` — that belongs to whoever coordinates you.
+once when you are otherwise done. Never \`bunx x verify\` — that belongs to whoever coordinates you.
 `;
 
 /** One agent per boundary, plus the read-only one that runs before there is a boundary to hold. */