@ultimat3/cli 29.4.0 → 30.1.0

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

@@ -6,6 +6,7 @@
 import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
 import { examplePageTest, exampleViewTest } from './scaffold-dashboard-example-tests';
+import { exampleView } from './scaffold-dashboard-example-view';
 import { DASHBOARD_DIR, routeConfig, themeActions, themeIsland } from './scaffold-dashboard-shared';
 
 // Plain strings for the framework lines, never template literals: the workspace-dependency scanner
@@ -24,7 +25,7 @@ ${sortedImports([
   "import { isUltimateError } from '@ultimat3/core';",
   "import { currentLocale } from '@ultimat3/i18n';",
   "import { formatMoney } from '@ultimat3/money';",
-  "import { defineRoute, island } from '@ultimat3/render';",
+  "import { defineRoute, island, type RouteContext } from '@ultimat3/render';",
   [
     'import {',
     '  AreaChart,',
@@ -38,6 +39,8 @@ ${sortedImports([
     '  Section,',
     '  StatTile,',
     '  ThemeToggle,',
+    '  TimeRangePicker,',
+    '  timeRangeUrl,',
     "} from '@ultimat3/ui';",
   ].join('\n'),
 ])}
@@ -45,7 +48,10 @@ import { Shell } from '../../shared/shell';
 import { postList } from '../post/live/post-list';
 import {
   bucketByDay,
-  CHART_DAYS,
+  CHART_RANGES,
+  CHART_ZONE,
+  chartDays,
+  DEFAULT_CHART_RANGE,
   formatCount,
   type PostRow,
   postStats,
@@ -66,6 +72,8 @@ export interface DashboardData {
   readonly rows: readonly PostRow[];
   /** The instant the windows were cut at, so server and test agree on "the last 7 days". */
   readonly now: string;
+  /** The request's URL: the chart's window lives in it (\`?range=\`, or a custom \`from\`/\`to\`). */
+  readonly url: string;
 }
 
 /**
@@ -76,12 +84,13 @@ export interface DashboardData {
  */
 export async function dashboardData(
   read: () => Promise<readonly Parameters<typeof toPostRow>[0][]>,
+  url: string,
 ): Promise<DashboardData> {
   const now = new Date().toISOString();
   try {
-    return { rows: (await read()).map(toPostRow), now };
+    return { rows: (await read()).map(toPostRow), now, url };
   } catch (error) {
-    if (isUltimateError(error) && error.code === 'X_DB_UNAVAILABLE') return { rows: [], now };
+    if (isUltimateError(error) && error.code === 'X_DB_UNAVAILABLE') return { rows: [], now, url };
     throw error;
   }
 }
@@ -93,7 +102,8 @@ export async function dashboardData(
  * read to the request's actor, so the viewer \`auth/dev-actor.ts\` resolves sees the rows
  * \`packages/db/src/seed.ts\` wrote, and a real session sees its own org's the day one exists.
  */
-const load = (): Promise<DashboardData> => dashboardData(() => postList({ limit: ROW_LIMIT }));
+const load = ({ url }: RouteContext): Promise<DashboardData> =>
+  dashboardData(() => postList({ limit: ROW_LIMIT }), url);
 
 ${themeIsland}
 
@@ -108,7 +118,27 @@ export function Page(props: PageProps) {
   const locale = currentLocale();
   const now = new Date(props.data.now);
   const stats = postStats(props.data.rows, now);
-  const points = bucketByDay(props.data.rows, now, CHART_DAYS);
+  // The chart's window, from the URL: a preset link or the custom form, kept across reload and
+  // share. A window the URL cannot hold (backwards, malformed) is the default, and the picker says so.
+  const labels = new Map<string, string>([
+    ['week', t('app.dashboard.rangeWeek')],
+    ['fortnight', t('app.dashboard.rangeFortnight')],
+    ['month', t('app.dashboard.rangeMonth')],
+  ]);
+  const range = timeRangeUrl(props.data.url, {
+    presets: CHART_RANGES.map((preset) => ({
+      id: preset.id,
+      label: labels.get(preset.id) ?? preset.id,
+      seconds: preset.days * 86_400,
+    })),
+    default: DEFAULT_CHART_RANGE,
+    timeZone: CHART_ZONE,
+    now,
+  });
+  // A capped read cannot see the days before its oldest row: those are unknown, never zero.
+  const points = bucketByDay(props.data.rows, range.to, chartDays(range.from, range.to), {
+    capped: props.data.rows.length >= ROW_LIMIT,
+  });
   const mix = priceMix(props.data.rows);
   const latest = props.data.rows.slice(0, TABLE_ROWS);
   // Per currency: a bar is a share of the dearest post IN ITS CURRENCY, never of another's minor units.
@@ -137,6 +167,8 @@ export function Page(props: PageProps) {
             label={t('app.dashboard.statWeek')}
             value={formatCount(stats.lastWeek, locale)}
             delta={stats.delta}
+            goodWhen="up"
+            trend={points}
             hint={t('app.dashboard.hintVsPriorWeek')}
           />
           <StatTile
@@ -157,6 +189,11 @@ export function Page(props: PageProps) {
             title={t('app.dashboard.chartTitle')}
             description={t('app.dashboard.chartRange')}
           >
+            <TimeRangePicker
+              range={range}
+              timeZone={CHART_ZONE}
+              label={t('app.dashboard.rangeLabel')}
+            />
             <AreaChart
               label={t('app.dashboard.chartLabel')}
               keys={points.map((point) => point.key)}
@@ -225,131 +262,6 @@ export function Page(props: PageProps) {
 }
 `;
 
-const exampleView =
-  (): string => `// The dashboard's numbers, apart from its markup: pure functions over the rows the page loaded,
-// so the server render and a test cannot disagree about a figure. No I/O, no \`t()\`, no JSX.
-
-import type { Money } from '@ultimat3/money';
-import { type ChartPoint, deltaOf, type StatDelta } from '@ultimat3/ui';
-
-/** Days of history the chart shows, oldest first. */
-export const CHART_DAYS = 14;
-
-const DAY_MS = 86_400_000;
-
-/** One post as the page reads it. \`createdAt\` is ISO text: a \`Date\` cannot cross a JSON seam. */
-export interface PostRow {
-  readonly id: string;
-  readonly title: string;
-  /** Integer minor units plus an ISO code, never a float — the entity's \`money()\` column. */
-  readonly price: Money;
-  readonly createdAt: string;
-}
-
-/**
- * Duck-typed rather than the entity's own row: the page only ever reads these four columns. The
- * query reads through the typed handle, so \`createdAt\` arrives as the \`Date\` the entity declares.
- */
-export function toPostRow(row: {
-  readonly id: string;
-  readonly title: string;
-  readonly price: Money;
-  readonly createdAt: Date | string;
-}): PostRow {
-  const at = row.createdAt;
-  return {
-    id: row.id,
-    title: row.title,
-    price: row.price,
-    createdAt: at instanceof Date ? at.toISOString() : at,
-  };
-}
-
-/** Free (a zero price) against paid, over every row loaded — the two halves of the ring. */
-export interface PriceMix {
-  readonly free: number;
-  readonly paid: number;
-}
-
-export function priceMix(rows: readonly PostRow[]): PriceMix {
-  const paid = rows.filter((row) => row.price.minor > 0).length;
-  return { free: rows.length - paid, paid };
-}
-
-/**
- * The dearest price per currency, in minor units — what each row's in-cell bar is a share of.
- * Per currency because 1,900 cents and 1,900 yen are not the same height.
- */
-export function priceCeilings(rows: readonly PostRow[]): ReadonlyMap<string, number> {
-  const ceilings = new Map<string, number>();
-  for (const row of rows) {
-    const { currency, minor } = row.price;
-    ceilings.set(currency, Math.max(ceilings.get(currency) ?? 0, minor));
-  }
-  return ceilings;
-}
-
-export interface PostStats {
-  readonly total: number;
-  /** Created in the seven days ending at \`now\`. */
-  readonly lastWeek: number;
-  /** \`lastWeek\` against the seven days before it; absent when that baseline is zero. */
-  readonly delta: StatDelta | undefined;
-  /** Created in the UTC day \`now\` falls in — a partial day, so it carries no delta. */
-  readonly today: number;
-}
-
-const createdAtOf = (row: PostRow): number => Date.parse(row.createdAt);
-
-const within = (rows: readonly PostRow[], from: number, to: number): number =>
-  rows.filter((row) => {
-    const at = createdAtOf(row);
-    return Number.isFinite(at) && at > from && at <= to;
-  }).length;
-
-export function postStats(rows: readonly PostRow[], now: Date): PostStats {
-  const end = now.getTime();
-  const weekAgo = end - 7 * DAY_MS;
-  const dayStart = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
-  const lastWeek = within(rows, weekAgo, end);
-  return {
-    total: rows.length,
-    lastWeek,
-    delta: deltaOf(lastWeek, within(rows, weekAgo - 7 * DAY_MS, weekAgo)),
-    today: within(rows, dayStart - 1, end),
-  };
-}
-
-/** \`MM-DD\` of a UTC day. ISO, never \`toLocaleDateString\`: the chart's axis is data, not prose. */
-const dayKey = (at: number): string => new Date(at).toISOString().slice(5, 10);
-
-/**
- * One bucket per UTC day, the last one being the day \`now\` falls in, oldest first — the shape
- * \`BarChart\` draws. Every day is present even when nothing was created on it: a chart with the
- * quiet days removed reads as busier than the app is.
- */
-export function bucketByDay(
-  rows: readonly PostRow[],
-  now: Date,
-  days: number,
-): readonly ChartPoint[] {
-  const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
-  const start = today - (days - 1) * DAY_MS;
-  const counts: number[] = Array.from({ length: days }, () => 0);
-  for (const row of rows) {
-    const at = createdAtOf(row);
-    if (!Number.isFinite(at)) continue;
-    const index = Math.floor((at - start) / DAY_MS);
-    if (index >= 0 && index < days) counts[index] = (counts[index] ?? 0) + 1;
-  }
-  return counts.map((value, index) => ({ key: dayKey(start + index * DAY_MS), value }));
-}
-
-/** A figure for a tile, in the page's locale. \`Intl.NumberFormat\` needs no time zone. */
-export const formatCount = (value: number, locale: string): string =>
-  new Intl.NumberFormat(locale).format(value);
-`;
-
 /** The example dashboard's page, view module and the tests beside both. */
 export const exampleDashboardFiles = (app: NameSet): readonly GeneratedFile[] => [
   { path: `${DASHBOARD_DIR}/page.tsx`, contents: examplePage(app) },

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

@@ -5,12 +5,8 @@
 export const DASHBOARD_DIR = 'apps/web/app/dashboard';
 
 export const routeConfig = (load: string): string => `export const config = defineRoute({
-  // 'ssr', not 'stream', and this is not a downgrade: 'stream' needs a boundary to stream into,
-  // and the framework has no hole marker yet. Solid's <Suspense> is not it — it throws outside a
-  // Solid renderer, and the server JSX factory is inert on purpose. A scaffolded 'stream' route
-  // therefore failed x routes with X_ROUTE_MODE_INVALID on the first run, printing a fix nobody
-  // could follow. Ship the mode that works. Async data needs no boundary: await it in the page.
-  render: 'ssr',
+  // The app/ default: the shell flushes first, and a read moved into a <Hole> arrives after it.
+  render: 'stream',
   // 'visible' for the one island on this page, the theme toggle in the header.
   hydrate: 'visible',
   offline: 'runtime',
@@ -22,7 +18,7 @@ export const routeConfig = (load: string): string => `export const config = defi
   // toggle, provider, the ui runtime they share and the error registry are the rest. It was
   // 60.9kb before the framework stopped shipping solid-js twice and the i18n catalog with it
   // (issue #490), which is what put this at 64kb; 60kb is the figure the scaffold budgets held
-  // before that, kept rather than tightened so a Bun patch cannot red a first \`bun run check\`.
+  // before that, kept rather than tightened so a Bun patch cannot red a first \`bun run verify\`.
   budget: { js: '60kb' },${load}
   meta: ({ t }) => ({
     title: t('app.dashboard.title'),

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

@@ -75,7 +75,7 @@ export const dbClientSource = (
 
 ${sortedImports([
   "import { storeMode } from '@ultimat3/core';",
-  "import { type Driver, database, memoryDriver, postgresDriver } from '@ultimat3/entity';",
+  "import { type Driver, database, postgresDriver, testDriver } from '@ultimat3/entity';",
   ...entries.map(handleImportLine),
 ])}
 
@@ -84,13 +84,13 @@ ${sortedImports([
  * reads through (\`driver.reset?.()\`).
  *
  * \`postgresDriver()\` takes no connection: it resolves \`@ultimat3/db\`'s process client, which is
- * the embedded PGlite under \`x dev\` and the \`DATABASE_URL\` pool in a container. \`bun test\`
- * installs no client, so a test gets the in-memory driver — the same contract, no database.
- * \`storeMode\` is core's one answer to that question, shared with every other seam that has a
- * memory and a database store.
+ * the embedded PGlite under \`x dev\` and the \`DATABASE_URL\` pool in a container. Under
+ * \`bun test\` it is \`testDriver()\`: memory until a test installs its migrated database with
+ * \`setDbClient\`, that database while it is installed — decided per call, so this module-load
+ * constant follows the client. \`storeMode\` is core's one answer to which store a seam takes.
  */
 export const selectDriver = (env: Readonly<Record<string, string | undefined>>): Driver =>
-  storeMode(env) === 'memory' ? memoryDriver() : postgresDriver();
+  storeMode(env) === 'memory' ? testDriver() : postgresDriver();
 
 export const driver = selectDriver(Bun.env);
 
@@ -111,6 +111,7 @@ const clientTest = (
 ): string => `// Which store the handle reads: memory under \`bun test\`, the process's Postgres client
 // everywhere else. A handle that silently took the memory driver in a container would serve an
 // empty database with a green gate.
+import { recordingClient, setDbClient } from '@ultimat3/db';
 import { expect, unitTest } from '@ultimat3/testing';
 import { db, driver, selectDriver } from './client';
 
@@ -126,6 +127,19 @@ unitTest('the handle is built over the driver this module exports', () => {
   expect(driver.reset).toBeDefined();
   expect(typeof db).toBe('object');
 });
+
+// The test driver decides per call: a migrated database installed with \`setDbClient\` is what
+// \`db\` reaches, and clearing it hands the handle back to memory.
+unitTest('under test the handle follows an installed client', async () => {
+  const client = recordingClient();
+  setDbClient(client);
+  try {
+    await driver.transactor().run(async () => undefined);
+  } finally {
+    setDbClient(undefined);
+  }
+  expect(client.texts).toContain('BEGIN');
+});
 `;
 
 /**

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

@@ -101,19 +101,6 @@ export {};
  *
  * `x db seed` owns the connection, the tier and the per-seed transaction. One runner, one answer.
  */
-/**
- * The seed's two package imports in the order Biome sorts them: the app's own scope can sort on
- * either side of \`@ultimat3\`, and a fixed order is a lint failure for half of all app names.
- */
-const seedImports = (app: NameSet): string =>
-  [
-    [`@${app.kebab}/web/shared/demo-org`, 'DEMO_ORG_LABEL'],
-    ['@ultimat3/entity', 'defineSeed'],
-  ]
-    .sort(([a = ''], [b = '']) => (a < b ? -1 : a > b ? 1 : 0))
-    .map(([from, name]) => `import { ${name} } from '${from}';`)
-    .join('\n');
-
 const dbSeed = (app: NameSet, example: boolean): string =>
   example
     ? `// Deterministic fixtures: the same rows every time, so a test, a demo and a branch database
@@ -124,9 +111,13 @@ const dbSeed = (app: NameSet, example: boolean): string =>
 // 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.
-${seedImports(app)}
+import { defineSeed } from '@ultimat3/entity';
 import { post } from './schema';
 
+// \`apps/web/shared/demo-org.ts\`'s label, spelled here because a package imports no app
+// (X_BOUNDARY_PACKAGE_TO_APP). \`seed.test.ts\` reads that module and holds the two equal.
+const DEMO_ORG_LABEL = 'org:demo';
+
 /** 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, [

package/src/templates/scaffold-docs.ts

@@ -2,34 +2,52 @@
 // the bin/ scripts and the optional dev compose. Separated from the config half so neither file has
 // to be scrolled to find the other — one file, one job applies to templates too. The image, its
 // ignore file, the production topology and the deploy page are `scaffold-container.ts`; the
-// `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`; the one workflow is
+// `.claude/` harness that reads CLAUDE.md is `scaffold-claude.ts`; the one workflow is
 // `github/ci.yml.ts`.
 
 import { LINE_CEILING } from '../workspace-checks';
 import { githubFiles } from './github/ci.yml';
 import type { GeneratedFile, NameSet } from './naming';
+import { S3_GATEWAY_IMAGE } from './pinned-images';
 import { binFiles } from './scaffold-bin';
 import { claudeFiles } from './scaffold-claude';
 import { containerFiles } from './scaffold-container';
+import { mcpJsonFile } from './scaffold-mcp-json';
 import { testServicesFiles } from './scaffold-test-services';
 
-const agents = (app: NameSet): string => `# AGENTS.md
+/**
+ * The one convention file, under two names: `CLAUDE.md` holds it and `AGENTS.md` is a relative
+ * symlink to it (the owner's ruling, 2026-11-03), so there is no second copy to drift. Every word
+ * stays vendor-neutral, because every agent reads it — `scaffold-agents-md.test.ts` refuses one.
+ */
+const conventions = (app: NameSet): string => `# ${app.pascal}
 
-Human-authored, short, stable. Facts live in \`x.manifest.json\`; this file holds only what an
-agent cannot infer from the code.
+Human-authored, short, stable — one file under two names, \`AGENTS.md\` being a symlink to it.
+Facts live in \`x.manifest.json\`; this file holds only what an agent cannot infer from the code.
 
 Every row below names what refuses it. A rule with nothing in the last column is a rule that does
-not exist — five of these had an empty column and were each measured green on \`x verify\`.
+not exist — five of these had an empty column and were each measured green on \`bunx x verify\`.
+
+There is no global \`x\`: every command here is \`bunx x …\`, the CLI this app installs.
+
+Before stating or working around a framework limit, ask the installed framework:
+\`bunx x docs "<question>"\`, and \`bunx x errors explain <CODE>\` for an error code.
+
+Before an edit, ask what it reaches: \`bunx x impact <file> --json\` names the routes, actions,
+queries, jobs, MCP tools, published operations and tests it touches, each with provenance.
 
 | Rule | Detail | Refused by |
 |---|---|---|
-| One gate | \`bun run check\` — \`x build\` and then \`x verify\`. Green means shippable; never merge red. | the gate itself, and \`.github/workflows/ci.yml\` on every push and pull request; \`.github/workflows/image.yml\` publishes only a commit it passed |
+| One gate | \`bun run verify\` — \`bunx x verify\`, which builds what its \`budgets\` step weighs. Green means shippable; never merge red. CI runs the same two commands as your terminal: \`bun run setup && bun run verify\` | the gate itself, and \`.github/workflows/ci.yml\` on every push and pull request; \`.github/workflows/image.yml\` publishes only a commit it passed |
 | Coverage | the unit suite covers 95% of the lines and functions of this app's own source — every file under \`apps/\` and \`packages/\`, one no test loads counted at 0%. A floor, not the goal: a test added to raise it is proven by mutation — break the source, watch it go red, restore | \`X_COVERAGE_BELOW_FLOOR\` on the \`unit\` step; \`coverage\` in \`x.verify.json\` states the floor, and it only rises |
-| One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` | review |
+| One way | generators, not hand-rolled files: \`bunx x g resource\`, \`bunx x g action\`, \`bunx x g route\` | review |
 | Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf | \`X_BOUNDARY_SITE_TO_APP\` |
 | Data | routes call actions and queries; only \`repo.ts\` touches the database | \`X_BOUNDARY_ROUTE_TO_DB\` |
 | Repos | a \`repo.ts\` reads through the typed handle, never a \`sql\` literal the handle can express | \`guards/repo-raw-sql.ts\` |
-| Errors | never \`throw new Error\` — subclass \`UltimateError\` with a code, a cause and a fix | \`guards/bare-error.ts\` |
+| Vendors | a server \`fetch(\` carries a \`signal\` in its own options — better, it is \`outbound()\` from \`@ultimat3/core/outbound\`: a deadline, the caller's signal, safe-only retry | \`guards/raw-fetch.ts\` |
+| Polling | an island re-reads on a timer with \`visibleInterval(run, ms)\` from \`@ultimat3/core/page\` — no call while the tab is hidden, none after a lost session — never a bare \`setInterval(\`; a \`// why:\` on the line admits a tick that is not a read | \`guards/raw-interval.ts\` |
+| Confirmation | a destructive act asks through \`ConfirmDialog\` from \`@ultimat3/ui\` — Cancel focused, a native post, stays open on a refusal — never \`confirm(\`; a \`// why:\` on the line admits a call that is not that question | \`guards/native-confirm.ts\` |
+| Errors | never \`throw new Error\` — declare each code once, \`defineError({ code, title, status, cause, fix })\` from \`@ultimat3/core\`, and throw its class; never a handwritten \`UltimateError\` subclass | \`guards/bare-error.ts\`, \`guards/error-declared.ts\` |
 | Money | \`{ minor, currency }\`, never a float — \`money()\` on the column | the type: \`price: 19.99\` is TS2322, \`number\` is not \`MoneyInput\` |
 | Time | store UTC, format with an explicit IANA time zone | \`guards/unzoned-date.ts\` |
 | Strings | every user-facing string goes through \`t()\` | \`guards/untranslated-string.ts\` |
@@ -45,11 +63,11 @@ not exist — five of these had an empty column and were each measured green on
 | Focus | \`outline: none\` replaces the ring in the same rule or the one beside it, or it does not remove it | \`guards/focus-visible.ts\` |
 | Images | every image carries width + height or an aspect-ratio, and the priority one is never \`loading="lazy"\` | \`guards/image-dimensions.ts\` |
 | Motion | animate \`transform\` and \`opacity\` — never a layout property, never \`transition: all\` | \`guards/animated-layout-property.ts\` |
-| Islands | every \`*.island.tsx\` has a sibling \`*.island.states.ts\`, so \`x shot --island\` can photograph its failures | \`guards/island-without-states.ts\` |
+| Islands | every \`*.island.tsx\` has a sibling \`*.island.states.ts\`, so \`bunx x shot --island\` can photograph its failures | \`guards/island-without-states.ts\` |
 | Size | one file, one job — ${LINE_CEILING} lines of reviewable logic, and split past it | \`X_FILE_TOO_LONG\` |
 
-\`guards/\` is yours: each file is one rule, discovered by \`x verify\` and run inside its
-\`boundaries\` step. Delete one to drop the rule, and \`x g guard <name>\` writes the next.
+\`guards/\` is yours: each file is one rule, discovered by \`bunx x verify\` and run inside its
+\`boundaries\` step. Delete one to drop the rule, and \`bunx x g guard <name>\` writes the next.
 
 The last five rows are about what this app is like to USE, and each is decidable from the file
 alone — which is why they are those five and not the many that are not. A role is a promise:
@@ -58,21 +76,21 @@ already does. Only \`transform\` and \`opacity\` animate without a layout pass.
 moves everything under it when its bytes land.
 
 Size is a hard line and not a style note: past ${LINE_CEILING} lines a file has stopped being the
-unit of review, and \`x verify\` refuses it. The one exemption is a file that is nothing but re-exports —
+unit of review, and \`bunx x verify\` refuses it. The one exemption is a file that is nothing but re-exports —
 it has one job by construction, and its length tracks the API's size rather than its complexity;
 one statement of logic in such a file re-arms the ceiling on the same save.
 
 Coverage counts execution, not validation: 100% is reachable with zero assertions, and a covered
 branch whose test cannot fail is worse than an uncovered one, because it reads as done. An
 \`exclude\` entry under \`coverage\` is for code a unit test cannot execute — an island's
-browser-only mount, a container entry point — carries its \`why\`, and is printed by \`x doctor\`.
+browser-only mount, a container entry point — carries its \`why\`, and is printed by \`bunx x doctor\`.
 
 Every test the scaffold and the generators write is the idiom to copy. All of them run on the
 \`unit\` step — in process, on the in-memory driver, with no database, browser or server.
 
 A suite that needs a real server reads it from \`docker/test-services.env\`: Postgres 18, Redis, NATS
 and S3 from \`docker/docker-compose.test.yml\`, in RAM, with durability and logging off — CI starts
-it before \`bun run check\`, a laptop with \`docker compose -f docker/docker-compose.test.yml up -d
+it before \`bun run verify\`, a laptop with \`docker compose -f docker/docker-compose.test.yml up -d
 --wait\` then \`set -a; . docker/test-services.env; set +a\`. A resource a test opens is held with
 \`await using\` — \`await using db = await acquireWorkerDatabase()\` drops its database however
 the test ends:
@@ -83,7 +101,7 @@ the test ends:
 | a component | \`renderView(Component, props)\` | \`apps/web/shared/shell.test.ts\` |
 | an island | \`mountIsland\`, once per state its \`*.island.states.ts\` declares | \`apps/web/shared/theme-toggle.island.test.ts\` |
 | an action or a query | \`target.as(actor, input)\` — the refusal first, then what it answers | \`apps/web/api/health.test.ts\` |
-| a job, a task, a backfill | \`test('…', async ({ runJobs }) => …)\` — a worker in this process; assert on \`trace.steps\` and each run's \`outcome\` | what \`x g job\` writes |
+| a job, a task, a backfill | \`test('…', async ({ runJobs }) => …)\` — a worker in this process; assert on \`trace.steps\` and each run's \`outcome\` | what \`bunx x g job\` writes |
 | a repo, a seed | as an actor, \`runWithContext(ctxOf({ actor }), …)\`, with \`driver.reset?.()\` after each | \`packages/db/src/seed.test.ts\` |
 
 Money is the one row with no guard, deliberately: a float has no static signature a text rule can
@@ -91,45 +109,37 @@ see, and the type already fires — measured, \`price: 19.99\` in a seed is
 \`TS2322: Type 'number' is not assignable to type 'MoneyInput'\`. A guard that pretended to check
 it would be worse than the type that really does.
 
-\`bun run check\` is the gate and \`x verify\` is only its second half: the first is
-\`x build --target static\`, and the build is what writes the \`.x/build-stats.json\` the
-\`budgets\` step measures. Run \`x verify\` on a tree nobody has built and \`budgets\` is red with
-X_BUDGET_UNMEASURED — the gate reporting on a file that does not exist, not on your code.
+\`bun run verify\` is \`bunx x verify\`, the whole gate: its \`budgets\` step runs
+\`bunx x build --target static\` itself when \`.x/build-stats.json\` is missing or older than the
+source, so nothing has to be built first.
 
-The platform's \`.dz/\` is ADDITIVE, in both directions. developerz.ai keeps its own files under
-\`.dz/maintainer/\` and \`.dz/pipeline/\`; nothing \`x new\` writes lands under \`.dz/\` and nothing
-here is generated from it. So the scaffold never clobbers a maintainer policy, the platform never
-clobbers \`AGENTS.md\`, \`bin/\`, \`.claude/\` or \`.github/\`, and deleting either side leaves the
-other exactly as it was.
+Commands: \`bun run setup\`, \`bun run dev\`, \`bun run verify\`, \`bunx x g <primitive>\`,
+\`bunx x g guard <name>\`, \`bunx x db branch create <name>\`, \`bunx x doctor\`. \`setup\` is
+\`bin/setup.ts\`, a file Bun runs, so all three are the same command in PowerShell, cmd and bash.
 
-Commands: \`bun run setup\`, \`bun run dev\`, \`bun run check\`, \`x g <primitive>\`,
-\`x g guard <name>\`, \`x db branch create <name>\`, \`x doctor\`. \`setup\` and \`check\` are
-\`bin/*.ts\` files Bun runs, so all three are the same command in PowerShell, cmd and bash.
+- \`bunx x g --help\` lists every generator kind, and is the only place that list is stated.
+- Destructive database work goes in a branch, \`bunx x db branch create <name>\`, never the shared
+  dev database.
+- \`bunx x db gen\` also writes \`packages/db/schema/\`, the whole schema as SQL, one file per
+  table: read it, never edit it. \`bunx x verify\` fails with \`X_SCHEMA_DUMP_DRIFT\` when it is not
+  what the migrations produce, and \`bunx x db gen\` rewrites it.
+- \`bunx x doctor\` explains a broken environment and prints the fix for every finding.
+- \`.claude/\` holds a harness that reads this file: \`/feature\`, \`/planx\`, \`/verify\` and four
+  boundary-scoped subagents. \`.claude/README.md\` says what each costs; every file is deletable.
 
-Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
-`;
+## Agent tools
+
+| Tool | What it answers | How to reach it |
+|---|---|---|
+| \`x.manifest.json\` | every route, action, query, job and policy, generated — read it before searching the tree | \`bunx x manifest\` rewrites it |
+| \`bunx x impact <file|primitive> --json\` · \`bunx x graph --json\` | what an edit reaches, and the app as one graph (declared, import and observed edges) | rebuilt from the loaded app on every call |
+| \`.mcp.json\` | the dev tools over MCP: routes, schema, policies, the database, tests, the gate — \`bunx x mcp tools\` lists them | a client that reads \`.mcp.json\` starts it; from any other, run \`bunx @ultimat3/cli mcp serve --transport stdio\` here |
+| \`POST /mcp\` | this app's own tools — every action declaring \`mcp: { expose: true }\` — for a remote agent | \`apps/web/mcp.ts\`; under \`bun run dev\`, \`Authorization: Bearer dev-agent.admin\`, else an API key |
+| \`.claude/commands/feature.md\` | build or fix one thing end to end, done when \`bun run verify\` is green | plain markdown: any agent can read one and follow it |
+| \`.claude/commands/planx.md\` | write a plan to \`docs/plans/\` for another agent to execute | the same |
+| \`.claude/commands/verify.md\` | run the gate and fix what it reports | the same |
 
-const claude = (app: NameSet): string => `# CLAUDE.md
-
-${app.kebab} — Ultimate app. Read AGENTS.md first; it is the same content in the same order.
-
-- Gate: \`bun run check\` (add \`--json\` for machine output — it reaches both halves). It is
-  \`x build --target static\` and then \`x verify\`; \`x verify\` alone leaves \`budgets\` with
-  nothing to measure. \`.github/workflows/ci.yml\` runs \`bun run setup && bun run check\` on
-  every push and pull request, so CI and your terminal run the same two commands.
-- \`.dz/\` belongs to the developerz.ai platform and is additive both ways: the scaffold writes
-  nothing there, and nothing there is generated from this repo. Neither side clobbers the other.
-- Scaffold, do not hand-write: \`x g <kind> <name>\` — \`x g --help\` lists every kind, and is the
-  only place that list is stated.
-- Destructive DB work goes in a branch: \`x db branch create <name>\`, never the shared dev DB.
-- \`x db gen\` also writes \`packages/db/schema/\` — the whole schema as SQL, one file per table.
-  Read it; never edit it. \`x verify\` fails with \`X_SCHEMA_DUMP_DRIFT\` when it is not what the
-  migrations produce, and \`x db gen\` rewrites it.
-- \`x doctor\` explains a broken environment and prints the fix command for every finding.
-
-\`.claude/\` holds the harness that reads this file: \`/feature\`, \`/planx\`, \`/verify\` and four
-boundary-scoped subagents. It is yours — \`.claude/README.md\` says what each one costs, and every
-file in it is deletable.
+Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
 `;
 
 const readme = (app: NameSet): string => `# ${app.pascal}
@@ -141,7 +151,7 @@ Built with [Ultimate](https://github.com/developerz-ai/ultimate). Bun-only, Post
 \`\`\`sh
 bun run setup   # prerequisites, deps, env, the first migration, migrate, seed, the manifest
 bun run dev     # all roles in one process, embedded Postgres, /_x mounted
-bun run check   # the gate: a static build, then typecheck, lint, boundaries, tests, drift, budgets
+bun run verify  # the gate: typecheck, lint, boundaries, tests, drift, budgets (it builds to weigh)
 \`\`\`
 
 Tests against real servers — Postgres 18, Redis, NATS, S3, in RAM and silent, as CI runs them:
@@ -149,7 +159,7 @@ Tests against real servers — Postgres 18, Redis, NATS, S3, in RAM and silent,
 \`\`\`sh
 docker compose -f docker/docker-compose.test.yml up -d --wait
 set -a; . docker/test-services.env; set +a
-bun run check
+bun run verify
 \`\`\`
 
 \`packages/db/migrations\` starts empty and \`x db gen\` is its only writer — \`bun run setup\` runs
@@ -168,7 +178,9 @@ with \`X_DB_DRIFT\`, and that is the fix it names.
 | \`packages/*\` | domain, db, i18n, ui, mcp |
 | \`app.config.ts\` | the one config file |
 | \`x.manifest.json\` | generated facts: routes, actions, jobs, policies |
-| \`.github/workflows/ci.yml\` | \`bun run setup\` then \`bun run check\`, on push and pull request |
+| \`.mcp.json\` | MCP client config: the dev tools, \`bunx @ultimat3/cli mcp serve --transport stdio\` |
+| \`apps/web/mcp.ts\` | the app's own \`POST /mcp\`: exposed actions, behind a bearer token |
+| \`.github/workflows/ci.yml\` | \`bun run setup\` then \`bun run verify\`, on push and pull request |
 | \`.github/workflows/image.yml\` | after a green \`ci\` on the default branch: \`docker/Dockerfile\` to \`ghcr.io\`, tagged \`sha-<7>\`, always on \`ubuntu-latest\` (bash and Docker). \`ci.yml\` runs on \`vars.CI_RUNNER\`, default \`ubuntu-latest\` |
 `;
 
@@ -206,7 +218,7 @@ services:
   # the region a request was signed for, and an app that sets no S3_REGION signs for \`auto\` — so
   # that is this gateway's region. A server for a laptop; production is any S3-compatible endpoint.
   s3:
-    image: versity/versitygw:v1.8.0@sha256:30292fc2eeacc67a36993b01f7a7a5e3361a19cced0e80c1d71cfa2a4b0a2499
+    image: ${S3_GATEWAY_IMAGE}
     environment:
       VGW_BACKEND: posix
       VGW_BACKEND_ARG: /data
@@ -225,9 +237,13 @@ volumes:
 export function docsFiles(app: NameSet): readonly GeneratedFile[] {
   return [
     { path: 'README.md', contents: readme(app) },
-    { path: 'AGENTS.md', contents: agents(app) },
-    { path: 'CLAUDE.md', contents: claude(app) },
-    // The scripts `bun run setup` and `bun run check` run — TypeScript, so one file per OS.
+    { path: 'CLAUDE.md', contents: conventions(app) },
+    // A link, after its target. \`contents\` is the copy written only where the OS refuses a
+    // symlink (Windows without the privilege): \`write-generated.ts\` decides, never this list.
+    { path: 'AGENTS.md', contents: conventions(app), link: 'CLAUDE.md' },
+    // The one MCP client config — what AGENTS.md's "Agent tools" block names first.
+    mcpJsonFile(app),
+    // The script `bun run setup` runs — TypeScript, so one file per OS.
     ...binFiles(),
     { path: 'docker/docker-compose.dev.yml', contents: composeDev(app) },
     // What the suites run against — in RAM, silent; ci.yml starts it before the gate.