@ultimat3/cli 19.3.1 → 19.3.3

package/CLAUDE.md

@@ -1124,6 +1124,16 @@ The roles live in `@ultimat3/core` (`ROLES`, `isRole`), never in a second list h
 driver, a dev-only authorizer or a dev-only queue is the bug this design exists to prevent — the
 only thing dev changes is which driver is behind an interface.
 
+### `HOST` is the interface, read the way `PORT` is
+
+`serve.ts`'s `hostnameFromEnv` — `HOST`, trimmed, empty is `0.0.0.0` — and `ServeOptions.hostname`
+overrides it as `port` overrides `PORT`; `containerBinding(env, hostname)` is the one `WebBinding`
+`serveApp` hands `startRoles`, so `web`, `sync` and the metrics endpoint bind the same interface.
+Before 2026-09-07 `CONTAINER_BINDING` was the only production binding and an app whose auth mode
+admits one implicit actor without a login — which must refuse a public interface — could not run in
+a container at all. A loopback bind in a container is unreachable through `-p`; the wiki row says
+where it IS reachable. Not `HOSTNAME`: Docker sets that to the container id.
+
 ### `RuntimeOverrides` is the only way to hand the framework a driver
 
 `ServeOptions` was `{ root, env, role?, port?, metricsPort? }`, so the ONLY way an app could
@@ -1256,9 +1266,23 @@ Delete `graphHash` the day `Bun.build` is deterministic.
 
 **`x dev`, the container and the static export all mount the same table.** `serve.ts` builds the
 islands at boot for the same reason it mounts `apiRoutes()`: a seam that works in dev and not in the
-image is the same failure one release later. `x dev` rebuilds them on the watcher tick, and that is
-the one reload that actually takes effect — an island is the single module this process never
-imports, so there is no Bun module cache to invalidate.
+image is the same failure one release later. `x dev` rebuilds them on the watcher tick — an island
+is the single module this process never imports, so there is no Bun module cache to invalidate —
+and the SAME tick re-imports the route module beside them when its source changed
+(`app-load.ts`'s `reloadRoute`: `<path>?x-reload=<hash>` is the one cache key Bun honours,
+`registerRoute` replaces the entry for the same file, and `dev-render.ts` reads the entry back from
+the table on every request rather than closing over the one it was built from). Until 2026-09-07
+the island was the only reload that took effect, so a save served a new island under an old page —
+the old props, the placeholder the new island renders when they are missing. A route module and
+nothing else: an action, a query or an entity is held by every module that imported it, and no
+re-import can rebind those. `@ultimat3/render`'s loader admits the query
+(`/\.tsx(?:\?[^/]*)?$/`) and strips it before reading the file — anchored on `.tsx$`, the
+re-import fell through to Bun's own JSX loader and every reloaded page died on `__xh`.
+
+**The dev fixture is its own repository** (`.git/HEAD` in `DEV_FIXTURE_FILES`). The framework's root
+`.gitignore` lists `packages/cli/.dev-fixture/`, `devIgnore` honours every ancestor up to a `.git`,
+and so the watcher admitted the fixture root and nothing under it: every run booted the reload path
+and none exercised it. The marker is what lets `cmd-dev.test.ts` save a page and await the tick.
 
 **`app-load.ts` skips `*.island.tsx` deliberately.** It registers no primitive, and importing it
 would put the one module guaranteed to be outside the server's graph inside this process's, where a

package/README.md

@@ -123,7 +123,7 @@ is held to the same error contract shipped source is (`X_GUARD_INVALID`, `X_GUAR
 | `app-openapi.ts` | `openapi.json`, projected by `@ultimat3/action` |
 | `app-boundaries.ts` | app import boundaries, over `@ultimat3/render`'s surface check |
 | `app-agents-md.ts` | `AGENTS.md` exists and stays short, over `@ultimat3/manifest`'s check |
-| `serve.ts` | **what a container starts** — `runRole(options)`, the same boot `x dev` runs minus the watcher, `/_x` and `dev: true`. `x new`'s `apps/web/server.ts` is three lines that call it |
+| `serve.ts` | **what a container starts** — `runRole(options)`, the same boot `x dev` runs minus the watcher, `/_x` and `dev: true`. `x new`'s `apps/web/server.ts` is three lines that call it. `ROLE`, `PORT` and `HOST` are read from `env`; `role`, `port` and `hostname` on `ServeOptions` override each |
 | `prerender.ts` | `x build --target static`: which `site/` routes qualify, and where the bytes land |
 | `metrics-endpoint.ts` | the `METRICS_PATH` scrape listener every role opens, on `METRICS_PORT` |
 | `otlp-export.ts` | the exporters `OTEL_EXPORTER_OTLP_ENDPOINT` switches on, and their drain hooks |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "19.3.1",
+  "version": "19.3.3",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "19.3.1",
-    "@ultimat3/admin": "19.3.1",
-    "@ultimat3/ai": "19.3.1",
-    "@ultimat3/auth": "19.3.1",
-    "@ultimat3/cache": "19.3.1",
-    "@ultimat3/core": "19.3.1",
-    "@ultimat3/db": "19.3.1",
-    "@ultimat3/entity": "19.3.1",
-    "@ultimat3/flags": "19.3.1",
-    "@ultimat3/http": "19.3.1",
-    "@ultimat3/i18n": "19.3.1",
-    "@ultimat3/jobs": "19.3.1",
-    "@ultimat3/mail": "19.3.1",
-    "@ultimat3/manifest": "19.3.1",
-    "@ultimat3/mcp": "19.3.1",
-    "@ultimat3/money": "19.3.1",
-    "@ultimat3/notify": "19.3.1",
-    "@ultimat3/policy": "19.3.1",
-    "@ultimat3/pwa": "19.3.1",
-    "@ultimat3/query": "19.3.1",
-    "@ultimat3/realtime": "19.3.1",
-    "@ultimat3/render": "19.3.1",
-    "@ultimat3/schema": "19.3.1",
-    "@ultimat3/scraping": "19.3.1",
-    "@ultimat3/seo": "19.3.1",
-    "@ultimat3/storage": "19.3.1",
-    "@ultimat3/testing": "19.3.1",
-    "@ultimat3/time": "19.3.1",
+    "@ultimat3/action": "19.3.3",
+    "@ultimat3/admin": "19.3.3",
+    "@ultimat3/ai": "19.3.3",
+    "@ultimat3/auth": "19.3.3",
+    "@ultimat3/cache": "19.3.3",
+    "@ultimat3/core": "19.3.3",
+    "@ultimat3/db": "19.3.3",
+    "@ultimat3/entity": "19.3.3",
+    "@ultimat3/flags": "19.3.3",
+    "@ultimat3/http": "19.3.3",
+    "@ultimat3/i18n": "19.3.3",
+    "@ultimat3/jobs": "19.3.3",
+    "@ultimat3/mail": "19.3.3",
+    "@ultimat3/manifest": "19.3.3",
+    "@ultimat3/mcp": "19.3.3",
+    "@ultimat3/money": "19.3.3",
+    "@ultimat3/notify": "19.3.3",
+    "@ultimat3/policy": "19.3.3",
+    "@ultimat3/pwa": "19.3.3",
+    "@ultimat3/query": "19.3.3",
+    "@ultimat3/realtime": "19.3.3",
+    "@ultimat3/render": "19.3.3",
+    "@ultimat3/schema": "19.3.3",
+    "@ultimat3/scraping": "19.3.3",
+    "@ultimat3/seo": "19.3.3",
+    "@ultimat3/storage": "19.3.3",
+    "@ultimat3/testing": "19.3.3",
+    "@ultimat3/time": "19.3.3",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-agents-md.ts

@@ -15,11 +15,22 @@ export interface AgentsMdOutcome {
   readonly warnings: readonly string[];
 }
 
-/** `assertAgentsMd` throws `X_AGENTS_MD_*`; a gate step reports, so the error becomes a finding. */
-export async function checkAgentsMd(root: string): Promise<AgentsMdOutcome> {
+/**
+ * `assertAgentsMd` throws `X_AGENTS_MD_*`; a gate step reports, so the error becomes a finding.
+ *
+ * `maxBytes` is this repository's own budget, out of `x.verify.json`, and `undefined` means the
+ * 12kB default. `@ultimat3/manifest` has taken the option since it was written and this function
+ * never passed one, so the default was the only budget any app could have: a repository whose
+ * conventions genuinely need more room had to delete a rule to make space, which is the opposite
+ * of what a context-file budget is for.
+ */
+export async function checkAgentsMd(root: string, maxBytes?: number): Promise<AgentsMdOutcome> {
   const path = join(root, AGENTS_MD_FILENAME);
   try {
-    const { warnings } = await assertAgentsMd({ path });
+    const { warnings } = await assertAgentsMd({
+      path,
+      ...(maxBytes === undefined ? {} : { maxBytes }),
+    });
     return { findings: [], warnings };
   } catch (error) {
     return { findings: [{ ...findingFrom(error), at: AGENTS_MD_FILENAME }], warnings: [] };

package/src/app-load.ts

@@ -10,6 +10,7 @@ import { registerActions } from '@ultimat3/action';
 import { localeConfig } from '@ultimat3/i18n';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
 import { registerQueries } from '@ultimat3/query';
+import type { RouteConfig } from '@ultimat3/render';
 import { isRouteConfig, pageComponentOf, registerRoute } from '@ultimat3/render';
 // For the SIDE EFFECT, and it is this module's to hold: importing `@ultimat3/render/server`
 // installs the `.tsx`/`.scss` Bun plugin, a plugin only transforms modules loaded AFTER it, and
@@ -74,20 +75,32 @@ export interface LoadedApp {
   readonly findings: readonly Finding[];
 }
 
-// A module is imported and registered exactly once per PROCESS: `import()` caches, and a registry
-// rejects a second registration of a name. So a rescan refreshes only the facts DERIVED from the
-// registries — the manifest and its build id — and never the primitives themselves: an edited route
-// config, action or query needs a restart. Clearing the registries would not change that. Bun
-// exposes no way to invalidate a cached module, so the re-import hands back the same stale exports,
-// and a cache-busting query string leaks a fresh module instance on every save.
+// A module is imported and registered once per PROCESS: `import()` caches, and a registry rejects
+// a second registration of a name. So a rescan refreshes the facts DERIVED from the registries —
+// the manifest and its build id — and, for exactly one kind of module, the primitive itself. A
+// ROUTE module whose source changed is imported again under `?x-reload=<hash>`, the one cache key
+// Bun honours, and `registerRoute` replaces the entry for the same file; its own imports resolve
+// to the modules already cached, which is what makes it safe. An action, a query or an entity
+// stays registered once: its exports are held by every module that imported it, a second instance
+// would be a duplicate name in its registry, and no re-import can rebind the importers — those
+// edits need a restart. Until 2026-09-07 the route module took the same rule, so a save re-bundled
+// the island (`buildIslands` reads the disk) and kept the FIRST page component — a new island
+// rendering under an old page's props, which is the mixed generation `x dev` served.
 const registered = new Set<string>();
 // A registration failure is sticky: the file is never retried, so the finding is replayed.
 const failures = new Map<string, Finding>();
+// Route modules only: the hash of the source each one registered from, which is what a rescan
+// compares the disk against. A save that leaves the bytes alone re-imports nothing.
+const routeSources = new Map<string, bigint>();
+
+/** The query a re-imported route module carries. `module-loader.ts`'s filter admits it. */
+const RELOAD_QUERY = 'x-reload';
 
 /** Test seam, and what `x dev` would call if it ever restarted the registries in-process. */
 export function resetAppLoad(): void {
   registered.clear();
   failures.clear();
+  routeSources.clear();
 }
 
 export async function loadApp(root: string): Promise<LoadedApp> {
@@ -104,6 +117,13 @@ export async function loadApp(root: string): Promise<LoadedApp> {
       if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
         continue;
       }
+      // The source is read BEFORE the import, and only on the file's first pass — a rescan of a
+      // registered module reads nothing here. A route entry is bound to the bytes the module was
+      // evaluated from, and a read AFTER the import cannot know which bytes those were: a save
+      // landing between the two bound V1's component to V2's hash, so the next scan saw nothing to
+      // do and served V1 until the save after. Read first, the worst case is one re-import the
+      // next tick, of a file that did change.
+      const snapshot = registered.has(absolute) ? undefined : await Bun.file(absolute).text();
       let module: Record<string, unknown>;
       try {
         module = (await import(absolute)) as Record<string, unknown>;
@@ -112,7 +132,7 @@ export async function loadApp(root: string): Promise<LoadedApp> {
         continue;
       }
       files.push(file);
-      const finding = await register(absolute, file, module);
+      const finding = await register(absolute, file, module, snapshot);
       if (finding !== undefined) findings.push(finding);
     }
   }
@@ -128,35 +148,29 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   };
 }
 
-/** Registers a module once; every later call replays whatever the first one reported. */
+/**
+ * Registers a module once; every later call replays whatever the first one reported — except for
+ * a route module, which a later call re-registers from disk when its source has changed.
+ * `snapshot` is the source read before the module's first import, and absent on every later call.
+ */
 async function register(
   absolute: string,
   file: string,
   module: Record<string, unknown>,
+  snapshot: string | undefined,
 ): Promise<Finding | undefined> {
   const previous = failures.get(absolute);
   if (previous !== undefined) return previous;
-  if (registered.has(absolute)) return undefined;
+  if (snapshot === undefined) return reloadRoute(absolute, file);
   registered.add(absolute);
   try {
     const config = module['config'];
-    if (isRouteConfig(config)) {
-      // The build counts boundaries from the compiled JSX; before a build there is only the
-      // source, and `render: 'stream'` is rejected without one — so count them in the text.
-      const source = await Bun.file(absolute).text();
-      // The page component comes from the same module as its config, resolved by render's own
-      // rule — the CLI does not decide which export is a page any more than it decides what a
-      // route is. A module with no component registers without one, and renders a bare shell.
-      const component = pageComponentOf(module);
-      registerRoute({
-        file,
-        config,
-        suspenseBoundaries: countSuspense(source),
-        ...(component === undefined ? {} : { component }),
-      });
-    }
+    const route = isRouteConfig(config) ? config : undefined;
+    if (route !== undefined) registerRouteModule(file, module, route, snapshot);
     registerActions(module);
     registerQueries(module);
+    // Only a route module is ever re-imported, so only a route module's hash is worth keeping.
+    if (route !== undefined) routeSources.set(absolute, Bun.hash.wyhash(snapshot));
     return undefined;
   } catch (error) {
     const finding: Finding = { ...findingFrom(error), at: file };
@@ -165,6 +179,59 @@ async function register(
   }
 }
 
+/**
+ * The route half of a registration, and the whole of a re-registration. `source` is the text the
+ * module was imported from — read by the caller BEFORE the import, never here after it — and the
+ * hash the entry is bound to is that text's. Until 2026-09-07 this read the file again, and a save
+ * between the import and that read registered the old component under the new hash: the next
+ * scan compared equal, and the page on disk was not served until the save after it.
+ */
+function registerRouteModule(
+  file: string,
+  module: Record<string, unknown>,
+  config: RouteConfig,
+  source: string,
+): void {
+  // The page component comes from the same module as its config, resolved by render's own
+  // rule — the CLI does not decide which export is a page any more than it decides what a
+  // route is. A module with no component registers without one, and renders a bare shell.
+  const component = pageComponentOf(module);
+  registerRoute({
+    file,
+    config,
+    // The build counts boundaries from the compiled JSX; before a build there is only the
+    // source, and `render: 'stream'` is rejected without one — so count them in the text.
+    suspenseBoundaries: countSuspense(source),
+    ...(component === undefined ? {} : { component }),
+  });
+}
+
+/**
+ * A registered route module, on a rescan: imported again if the file no longer hashes to what it
+ * registered from, and left alone otherwise. A save that will not import is a finding at the file
+ * and NOT a sticky one — the next save is tried again — and the entry it would have replaced stays
+ * registered, so the last page that did import is the one served meanwhile.
+ */
+async function reloadRoute(absolute: string, file: string): Promise<Finding | undefined> {
+  const registeredFrom = routeSources.get(absolute);
+  if (registeredFrom === undefined) return undefined;
+  const source = await Bun.file(absolute).text();
+  const hash = Bun.hash.wyhash(source);
+  if (hash === registeredFrom) return undefined;
+  try {
+    const module = (await import(`${absolute}?${RELOAD_QUERY}=${hash}`)) as Record<string, unknown>;
+    const config = module['config'];
+    // A file that stopped being a route is not un-registered — the table has no verb for it, and a
+    // deleted file needs a restart either way. Its hash is recorded so the same save is not
+    // re-imported on every later tick.
+    if (isRouteConfig(config)) registerRouteModule(file, module, config, source);
+    routeSources.set(absolute, hash);
+    return undefined;
+  } catch (error) {
+    return { ...findingFrom(error), at: file };
+  }
+}
+
 const countSuspense = (source: string): number => source.match(/<Suspense[\s/>]/g)?.length ?? 0;
 
 /** `packages/db/src/errors.ts` → `packages/db`; `apps/web/app/posts/errors.ts` → `apps/web`. */

package/src/cmd-dev-fixture.ts

@@ -7,6 +7,8 @@
 //   app.config.ts               the root marker a real `x dev` cannot start without; `ai.mcp` by default
 //   apps/web/mcp.ts             the app's own MCP endpoint, mounted by the web role
 //   apps/web/runtime.ts         the app's middleware, reaching a development process
+//   .git/HEAD                   the fixture is its own repository — see the entry below
+//   apps/web/app/hello/*        an SSR page with a component, edited on disk while `x dev` runs
 //   apps/web/app/notes/*        a memory-backed entity and a live query, fed by the in-process bridge
 //   apps/web/app/posts/*        an action, a policy and a query, mounted as HTTP routes
 //   apps/web/site/pricing/*     a static page with its own stylesheet, under the CSP `x dev` sends
@@ -24,6 +26,12 @@ import { resetAppLoad } from './app-load';
 export const DEV_FIXTURE_FILES: Readonly<Record<string, string>> = {
   'package.json': JSON.stringify({ name: 'dev-fixture', version: '1.4.0' }),
 
+  // Its own repository, so the ignore walk stops HERE. The framework's root `.gitignore` lists
+  // `packages/cli/.dev-fixture/`, and `devIgnore` honours every ancestor up to a `.git` — without
+  // this marker the watcher admitted the fixture root and nothing under it, so no save in this
+  // tree ever reached `rebuild`, and the reload path was booted by every run and exercised by none.
+  '.git/HEAD': 'ref: refs/heads/main\n',
+
   // The root marker a real `x dev` cannot start without, and where `ai.mcp` is declared — by
   // default `{ expose: true, path: '/mcp' }`, which is what the MCP mount reads.
   'app.config.ts': `import { defineConfig } from '@ultimat3/core';
@@ -98,6 +106,23 @@ export const echoPost = action({
     return { word: input.word };
   },
 });
+`,
+
+  // A page with a body, on the surface an author edits all day. What the reload test rewrites: the
+  // module must be imported again for the new body to be served, which `import()` alone never does.
+  'apps/web/app/hello/page.tsx': `import { defineRoute } from '@ultimat3/render';
+
+export const config = defineRoute({
+  render: 'ssr',
+  hydrate: 'visible',
+  offline: 'runtime',
+  budget: { js: '60kb' },
+  meta: () => ({ title: 'Hello', description: 'A page that is edited while x dev runs' }),
+});
+
+export function Page() {
+  return <p>generation one</p>;
+}
 `,
 
   // A stylesheet the page imports, because that import is what registers it — and the document's

package/src/cmd-dev.ts

@@ -16,7 +16,6 @@ import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { describeRoutes } from '@ultimat3/render';
 import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
-import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import { mountAppMcp } from './app-mcp';
 import { requireAppRoot } from './app-root';
@@ -88,10 +87,17 @@ interface DevState {
   reloads: number;
   /** A save that will not build. Replaced on every attempt, so a fixed file clears it. */
   reloadFinding: Finding | undefined;
+  /**
+   * Modules that would not import and primitives that would not register, as of the LAST scan —
+   * the boot's, then each rebuild's. A page saved with a syntax error is a finding here until the
+   * save that fixes it, and the boot's list alone would never show it.
+   */
+  appFindings: readonly Finding[];
   /**
    * The client entries, rebuilt on the same tick as the manifest. An island is the one module this
-   * process never imports, so a fresh `Bun.build` is the whole of its reload — no module cache to
-   * invalidate, which is exactly why editing one takes effect where editing a route does not.
+   * process never imports, so a fresh `Bun.build` is the whole of its reload. The route module
+   * beside it is re-imported by that same scan (`app-load.ts`) — the two are one generation, or
+   * a save serves a new island under an old page, which is what it did until 2026-09-07.
    */
   islands: IslandBundle;
 }
@@ -135,11 +141,16 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // uninstalled, and nothing more (axiom 6).
   const statements = createStatementLedger();
   setStatementObserver(statements.observer);
-  const app = await loadApp(options.root);
+  // ONE load at boot, the same call the rebuild below makes: the manifest and the findings are
+  // two projections of one scan. Until 2026-09-07 this was `loadApp` for the findings and then
+  // `appManifest` — which loads again — for the manifest, so a save landing between the two put
+  // `/_x`'s findings and its manifest on different registration states.
+  const app = await appManifest(options.root);
   const state: DevState = {
-    manifest: (await appManifest(options.root)).manifest,
+    manifest: app.manifest,
     reloads: 0,
     reloadFinding: undefined,
+    appFindings: app.findings,
     islands: await buildIslands(options.root),
   };
   // The manifest's build id is a content hash of every fact below it, so a dev document's
@@ -279,11 +290,12 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   const rebuild = coalesceReloads(
     async (file) => {
       const started = performance.now();
-      const [{ manifest }, islands] = await Promise.all([
+      const [{ manifest, findings }, islands] = await Promise.all([
         appManifest(options.root),
         buildIslands(options.root),
       ]);
       state.manifest = manifest;
+      state.appFindings = findings;
       state.islands = islands;
       state.reloads += 1;
       state.reloadFinding = undefined;
@@ -316,8 +328,8 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     get findings(): readonly Finding[] {
       const loops = statements.repeats().map(loopFacts).map(loopFinding);
       return state.reloadFinding === undefined
-        ? [...app.findings, ...loops]
-        : [...app.findings, state.reloadFinding, ...loops];
+        ? [...state.appFindings, ...loops]
+        : [...state.appFindings, state.reloadFinding, ...loops];
     },
     running,
     runtime,

package/src/cmd-generate.ts

@@ -7,7 +7,8 @@ import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { appManifest, writeAppManifest } from './app-manifest';
 import { requireAppRoot } from './app-root';
 import type { CliCommand, CommandContext } from './command';
-import { generate } from './generate-files';
+import { generate, sliceDir } from './generate-files';
+import type { Generator } from './generate-kinds';
 import { GENERATORS, readKind, readName, readPermission, readSurface } from './generate-kinds';
 import { containedPath, writeFiles } from './generate-write';
 import { resolveCatalogModule } from './i18n-audit';
@@ -70,10 +71,13 @@ export const generateCommand: CliCommand = {
     // Read before a file is planned, like the flags above: which module a generated component
     // imports `useT()` from is a fact about THIS app, and `generate` is a pure function.
     const catalogModule = await resolveCatalogModule(root);
+    // Read for the same reason: which errors the slice declares is written on THIS app's disk.
+    const sliceErrors = await readSliceErrors(root, kind, sliceDir(surface, featureFlag ?? name));
     const files = generate({
       kind,
       name,
       ...(featureFlag === undefined ? {} : { feature: featureFlag }),
+      ...(sliceErrors === undefined ? {} : { sliceErrors }),
       ...(at === undefined ? {} : { at }),
       ...(permission === undefined ? {} : { permission }),
       surface,
@@ -138,3 +142,18 @@ export const generateCommand: CliCommand = {
     };
   },
 };
+
+/**
+ * The slice's `errors.ts`, for the two generators whose template throws from it. Only those two:
+ * a route or an island names no slice, and the "feature" the fallback derives for them is a path
+ * that exists nowhere — reading it would be answering a question nobody asked.
+ */
+async function readSliceErrors(
+  root: string,
+  kind: Generator,
+  slice: string,
+): Promise<string | undefined> {
+  if (kind !== 'action' && kind !== 'mutator') return undefined;
+  const file = containedPath(root, `${slice}/errors.ts`);
+  return existsSync(file) ? await Bun.file(file).text() : undefined;
+}

package/src/dev-render.ts

@@ -27,6 +27,8 @@ import {
   renderHead,
   routeDataFor,
   routeEntries,
+  routeFor,
+  routeStatusOf,
   seoRenderers,
 } from '@ultimat3/render';
 import type { IsrController } from '@ultimat3/render/server';
@@ -212,12 +214,15 @@ async function resultFor(
   // ONCE per request, before the mode is chosen. Every branch below reads this same object, so a
   // route's `load` runs exactly once however its mode splits head from body.
   const data = await routeDataFor(entry.config, request);
+  // The status the loader answered through `withStatus`, 200 when it said nothing. Read once,
+  // here, and handed to every mode: this file mints the `Response`, render owns the seam.
+  const status = routeStatusOf(data);
   switch (entry.config.render) {
     case 'static': {
       // Not `renderStatic`: that enumerates every prerendered path for the build. A request
       // names exactly one, and it earns the same content-hashed headers.
       const body = await documentFrom(entry, request, data, options);
-      return { status: 200, headers: staticHeaders(contentHash(body), options.buildId), body };
+      return { status, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'isr': {
       // `isrKey(url, locale)`, never `url.pathname`: the query is part of what was rendered — this
@@ -227,9 +232,12 @@ async function resultFor(
       // The locale is the second dimension and it is `ctx.locale`, the answer the `locale` stage
       // already negotiated for THIS request — never `currentLocale()`, which would read the same
       // value through an ambient store the key does not need.
-      const served = await isr.serve(isrKey(url, ctx.locale), () =>
-        documentFrom(entry, request, data, options),
-      );
+      // `{ html, status }`, never the bare string: the entry stores the status beside the HTML
+      // and serves it on every hit, so a 404 under `isr` is a 404 for its whole TTL.
+      const served = await isr.serve(isrKey(url, ctx.locale), async () => ({
+        html: await documentFrom(entry, request, data, options),
+        status,
+      }));
       return served.result;
     }
     case 'stream': {
@@ -253,13 +261,14 @@ async function resultFor(
           holes: [],
         },
         { buildId: options.buildId },
+        status,
       );
     }
     default:
       return renderSsr(
         { entry, params: request.params, url, ctx },
         () => documentFrom(entry, request, data, options),
-        { buildId: options.buildId },
+        { buildId: options.buildId, status },
       );
   }
 }
@@ -281,15 +290,32 @@ const metaOf = (entry: RouteEntry): HttpRouteMeta => ({
   ...(entry.config.policy === undefined ? {} : { policy: entry.config.policy.permission }),
 });
 
-/** One HTTP route per registered `route` primitive, in the table's own order. */
+/**
+ * One HTTP route per registered `route` primitive, in the table's own order.
+ *
+ * The URL and the method are the table's at the time this is called; the ENTRY — the component the
+ * handler renders AND the `meta` the pipeline enforces — is read back from the table on every
+ * request. `x dev` re-registers a route module when its source changes (`app-load.ts`), and a
+ * handler closing over the entry it was built from kept serving the first component after every
+ * save — the table had moved and this closure had not. `meta` was the same defect one stage
+ * earlier: a snapshot taken here, so a `policy` added in a save was not enforced until a restart
+ * while the page behind it was already the new one — the pipeline's `auth` and `authz` stages read
+ * `route.meta` per request, and this getter is what makes that read the table's. The path cannot
+ * move under a reload (the table derives it from the file, and the file is the reload's key), so
+ * the entry captured here is only the fallback for a table cleared under a running server, which
+ * only a test does — and then guard and page fall back together.
+ */
 export function appRoutes(options: DevRenderOptions): readonly Route[] {
   const isr = options.isr ?? createIsrController({ buildId: options.buildId });
-  return routeEntries().map((entry) => ({
+  return routeEntries().map((registered) => ({
     method: 'GET' as const,
-    path: entry.path,
-    meta: metaOf(entry),
+    path: registered.path,
+    get meta(): HttpRouteMeta {
+      return metaOf(routeFor(registered.path) ?? registered);
+    },
     // `ctx.params` is the router's own match — the CLI never re-parses a path it did not match.
     handler: async (request, ctx): Promise<Response> => {
+      const entry = routeFor(registered.path) ?? registered;
       const data: DevRouteData = { url: request.url.href, params: ctx.params };
       return responseOf(await resultFor(entry, data, options, isr, asCtx(ctx)));
     },

package/src/generate-files.ts

@@ -48,6 +48,13 @@ export interface GenerateOptions {
    * package, and only then does a generated file import `t` from `@ultimat3/i18n` instead.
    */
   readonly catalogModule?: string;
+  /**
+   * `action` and `mutator`: the slice's `errors.ts` as it stands on disk, absent when there is
+   * none. Supplied by `run` for `catalogModule`'s reason — whether the slice declares
+   * `<Feature>NotFoundError` is a fact about THIS app, and a template that assumed it wrote an
+   * import of a class the app never declared. Read at `sliceDir(surface, feature)/errors.ts`.
+   */
+  readonly sliceErrors?: string;
 }
 
 const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
@@ -55,6 +62,10 @@ const DEFAULT_SURFACE_DIR: Record<Surface, string> = {
   app: 'apps/web/app',
 };
 
+/** Where a feature slice lives, relative to the app root — the one derivation `run` reads from. */
+export const sliceDir = (surface: Surface, feature: string): string =>
+  `${DEFAULT_SURFACE_DIR[surface]}/${feature}`;
+
 /**
  * Pure: returns the files a generator would write. `x g` writes them, the generator test asserts
  * on them, and nothing has to run a filesystem to review what a generator produces.
@@ -76,9 +87,20 @@ export function generate(options: GenerateOptions): readonly GeneratedFile[] {
         }),
       );
     case 'action':
-      return dedupe(actionFiles(options.name, target));
+      return dedupe(
+        actionFiles(options.name, {
+          ...target,
+          ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+        }),
+      );
     case 'mutator':
-      return dedupe(actionFiles(options.name, { ...target, mutator: true }));
+      return dedupe(
+        actionFiles(options.name, {
+          ...target,
+          mutator: true,
+          ...(options.sliceErrors === undefined ? {} : { sliceErrors: options.sliceErrors }),
+        }),
+      );
     case 'backfill':
       return dedupe(backfillFiles(options.name, target));
     case 'entity':

package/src/scaffold-fixture.ts

@@ -10,6 +10,17 @@ import type { GeneratedFile } from './templates';
 /** The app the fixture scaffolds. Kebab, multi-word: single-word names hide casing bugs. */
 export const FIXTURE_APP = 'ledger-demo';
 
+/**
+ * An `errors.ts` an author wrote: it declares what the slice throws, and not the generated name.
+ * The generator's INPUT only — the sandbox's own `errors.ts` is the one the resource wrote — so it
+ * carries no `X_*` code: a literal here would be one shipped source hands a reader, and the
+ * registry rule would ask where it was registered.
+ */
+export const HANDWRITTEN_ERRORS = `import { UltimateError } from '@ultimat3/core';
+
+export class LedgerClosedError extends UltimateError {}
+`;
+
 /**
  * One realistic invocation of every generator, on top of `x new --example`. Names differ from
  * their feature on purpose: `x g query invoice --feature invoice` would collide with the entity
@@ -25,6 +36,12 @@ export const FIXTURE_GENERATORS: readonly GenerateOptions[] = [
   { kind: 'policy', name: 'credit-note', feature: 'credit-note' },
   { kind: 'action', name: 'send-invoice', feature: 'invoice' },
   { kind: 'mutator', name: 'rename-invoice', feature: 'invoice' },
+  // The other shape both templates have: a slice whose `errors.ts` is the author's and declares
+  // no `InvoiceNotFoundError`. The resource's own `errors.ts` still lands in the sandbox (it does
+  // declare one), which is the point — this compiles the file `x g action` writes when it must
+  // not import that class, beside the one it writes when it may.
+  { kind: 'action', name: 'ping-invoice', feature: 'invoice', sliceErrors: HANDWRITTEN_ERRORS },
+  { kind: 'mutator', name: 'touch-invoice', feature: 'invoice', sliceErrors: HANDWRITTEN_ERRORS },
   { kind: 'query', name: 'invoice-search', feature: 'invoice' },
   { kind: 'query', name: 'invoice-feed', feature: 'invoice', live: true },
   { kind: 'job', name: 'sweep-invoices', feature: 'invoice' },

package/src/serve.ts

@@ -1,8 +1,8 @@
 // What a container starts. `apps/web/server.ts` is three lines that call `runRole`, so the boot a
 // production process performs is framework code with tests rather than app code the author has to
 // get right — and it is the SAME code `x dev` runs, minus the watcher, minus `/_x`, minus
-// `dev: true`. The only production-shaped decisions live here: which role, which port, and the
-// fact that a container must bind every interface.
+// `dev: true`. The only production-shaped decisions live here: which role, which port, and which
+// interface — every one by default, because a container is reached through a port mapping.
 
 import type { Role } from '@ultimat3/core';
 import {
@@ -56,9 +56,35 @@ import { serviceWorkerRoutes } from './sw-routes';
 
 export const DEFAULT_PORT = 3000;
 
-/** Every interface. A container bound to loopback is unreachable through its own port mapping. */
+/**
+ * Every interface, which is what a role binds when nothing says otherwise: a container bound to
+ * loopback is unreachable through its own port mapping. `HOST` and `ServeOptions.hostname` are the
+ * two ways of saying otherwise — see `hostnameFromEnv`.
+ */
 export const CONTAINER_BINDING: WebBinding = { dev: false, hostname: '0.0.0.0' };
 
+/**
+ * The interface the `web` and `sync` roles bind, and the metrics endpoint with them (`WebBinding`
+ * is one decision). Read the way `PORT` is: empty or whitespace is the default.
+ *
+ * Exists because a container had exactly one binding, `0.0.0.0`, and an app whose auth mode is
+ * "nobody logs in, one implicit actor" must refuse a public interface — so it could not run in a
+ * container at all. `HOST=127.0.0.1` is unreachable through `docker run -p` (the proxy connects to
+ * the container's bridge address, never its loopback); it is reachable where the container shares
+ * the host's network namespace (`--network host`), or through a sidecar and `ssh -L` inside it —
+ * which is the exposure such an app wants. Not `HOSTNAME`: Docker sets that to the container id.
+ */
+export function hostnameFromEnv(env: Env): string {
+  const raw = env['HOST']?.trim();
+  return raw === undefined || raw.length === 0 ? CONTAINER_BINDING.hostname : raw;
+}
+
+/** What `serveApp` hands `startRoles`: the caller's hostname, else `HOST`, else every interface. */
+export const containerBinding = (env: Env, hostname?: string): WebBinding => ({
+  dev: false,
+  hostname: hostname ?? hostnameFromEnv(env),
+});
+
 /**
  * `ROLE` is the one knob one image exposes. Validated rather than defaulted: a typo that fell back
  * to `web` would start a process that serves nothing the operator asked for and reports healthy.
@@ -144,6 +170,11 @@ export interface ServeOptions {
   readonly port?: number;
   /** Overrides `METRICS_PORT`, on the same terms. */
   readonly metricsPort?: number;
+  /**
+   * Overrides `HOST`: the interface the HTTP roles bind. An app that must never answer on a public
+   * interface passes `'127.0.0.1'` here rather than trusting the deployment to set the variable.
+   */
+  readonly hostname?: string;
   /**
    * The drivers this deployment supplies instead of the ones the environment would select.
    *
@@ -391,7 +422,7 @@ async function bootRoles(boot: {
     // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
     // process and `x dev` cannot answer a browser differently.
     root: options.root,
-    http: CONTAINER_BINDING,
+    http: containerBinding(options.env, options.hostname),
     // The read-replica scope rides in FRONT of whatever the host supplied, or the host's own value
     // passes through untouched. `DATABASE_REPLICA_URL` was read by no booted process before this:
     // `defaultClient()` is the one composer of a replicated pair and it runs only when an app

package/src/templates/action.ts

@@ -5,12 +5,25 @@
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
-import { sliceFoundation } from './slice-foundation';
+import { sliceExports, sliceFoundation } from './slice-foundation';
 import { wrapImport } from './wrap';
 
+/**
+ * The handler's lookup-by-id, or the comment that says what a slice needs before it can have one.
+ * `x g resource` writes a slice whose `errors.ts` declares `<Feature>NotFoundError`, and so does
+ * the foundation this generator lays under an empty directory; a slice an author wrote by hand
+ * (ai-maxxing's `fleet`, with `HostNotFoundError` and `SessionNotFoundError`) declares the errors
+ * it has and not this one. Importing it anyway is a file that fails at import.
+ */
+const missingLookup = (feature: NameSet): string =>
+  `    // No lookup by id: ../errors declares no ${feature.pascal}NotFoundError, and a row that is not
+    // there needs one to be thrown for it. Declare it there — the shape \`x g resource\` writes —
+    // then read the row through ../repo and throw it when the read answers nothing.`;
+
 const actionSource = (
   name: NameSet,
   feature: NameSet,
+  lookup: boolean,
 ): string => `// ${name.camel}: one mutation, server-authoritative. Input is validated before the handler runs
 // and the policy is the same object the MCP tool and the HTTP route evaluate.
 // \`t\` comes from @ultimat3/action, not @ultimat3/schema: an action file imports one package.
@@ -18,23 +31,25 @@ const actionSource = (
 import { action, t } from '@ultimat3/action';
 // One directory up: actions live in \`actions/\`, the feature's errors, policy and repo are the
 // slice's own files and are shared by every action in it.
-
-import { ${feature.pascal}NotFoundError } from '../errors';
-${wrapImport([`can${feature.pascal}Write`, `${feature.camel}Tag`], '../policy')}
-import * as repo from '../repo';
-
+${lookup ? `\nimport { ${feature.pascal}NotFoundError } from '../errors';\n` : ''}${wrapImport([`can${feature.pascal}Write`, `${feature.camel}Tag`], '../policy')}
+${lookup ? "import * as repo from '../repo';\n" : ''}
 export const ${name.camel} = action({
   // orgId is part of the input because the policy decides on it — authz reads the declaration,
   // never the database.
   input: t.object({ id: t.uuid, orgId: t.uuid }),
-  output: t.object({ id: t.uuid, title: t.string }),
+  output: t.object({ id: t.uuid${lookup ? ', title: t.string' : ''} }),
   policy: can${feature.pascal}Write,
   cache: { invalidates: [${feature.camel}Tag] },
   mcp: { expose: true, description: '${name.raw} — edit this description' },
   async handle({ input }) {
-    const row = await repo.byId(input.id);
+${
+  lookup
+    ? `    const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
-    return { id: row.id, title: row.title };
+    return { id: row.id, title: row.title };`
+    : `${missingLookup(feature)}
+    return { id: input.id };`
+}
   },
 });
 `;
@@ -42,14 +57,13 @@ export const ${name.camel} = action({
 const mutatorSource = (
   name: NameSet,
   feature: NameSet,
+  lookup: boolean,
 ): string => `// ${name.camel}: an action with an optimistic local twin. The local half runs against the client
 // store immediately; the server half is authoritative and reconciles on conflict.
 
 import { mutator, t } from '@ultimat3/action';
-import { ${feature.pascal}NotFoundError } from '../errors';
-import { can${feature.pascal}Write } from '../policy';
-import * as repo from '../repo';
-
+${lookup ? `import { ${feature.pascal}NotFoundError } from '../errors';\n` : ''}import { can${feature.pascal}Write } from '../policy';
+${lookup ? "import * as repo from '../repo';\n" : ''}
 interface Local${feature.pascal} {
   readonly id: string;
   readonly title: string;
@@ -71,9 +85,14 @@ export const ${name.camel} = mutator({
     });
   },
   async server(_ctx, input) {
-    const row = await repo.byId(input.id);
+${
+  lookup
+    ? `    const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
-    return { id: row.id, title: input.title };
+    return { id: row.id, title: input.title };`
+    : `${missingLookup(feature)}
+    return { id: input.id, title: input.title };`
+}
   },
   conflict: 'server-wins',
 });
@@ -181,6 +200,13 @@ contractTest('${name.camel} projects one tool and one operation', () => {
 
 export interface ActionOptions extends FeatureTarget {
   readonly mutator?: boolean;
+  /**
+   * The slice's `errors.ts` as it stands on disk, or absent when the slice has none yet. Absent,
+   * the foundation writes one declaring `<Feature>NotFoundError` and the action may throw it;
+   * present, the file is the author's and is never rewritten, so the action throws it only when
+   * `sliceExports` finds it there.
+   */
+  readonly sliceErrors?: string;
 }
 
 export function actionFiles(rawName: string, target: ActionOptions): readonly GeneratedFile[] {
@@ -188,6 +214,9 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
   const feature = names(target.feature);
   const dir = `${target.surfaceDir}/${target.feature}/actions`;
   const isMutator = target.mutator === true;
+  const lookup =
+    target.sliceErrors === undefined ||
+    sliceExports(target.sliceErrors, `${feature.pascal}NotFoundError`);
   return [
     // The three slice modules this action's source imports — `../errors`, `../policy`, `../repo`
     // (which comes with `../entity`, its row type). Composed rather than assumed: `x g action`
@@ -195,7 +224,9 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
     ...sliceFoundation(target, ['entity', 'policy', 'errors']),
     {
       path: `${dir}/${name.kebab}.ts`,
-      contents: isMutator ? mutatorSource(name, feature) : actionSource(name, feature),
+      contents: isMutator
+        ? mutatorSource(name, feature, lookup)
+        : actionSource(name, feature, lookup),
     },
     // TWO test files, because the gate types a test by its FILENAME and this declaration owes two
     // suites: the input parse is a `unit` assertion and the three projections are `contract` ones.

package/src/templates/island.ts

@@ -71,9 +71,11 @@ function ${Name}(props: ${Name}Props): JSX.Element {
  * container already has children, so without it the server's markup stays on screen above a
  * second, live copy of the same thing.
  */
-export function mount(el: HTMLElement, props: ${Name}Props): void {
+export function mount(el: HTMLElement, props: ${Name}Props): () => void {
   el.textContent = '';
-  render(() => <${Name} {...props} />, el);
+  // Solid's \`render\` answers its disposer; returning it is what lets \`mountIsland\` in
+  // \`@ultimat3/testing\` stop this island — its timers included — when a test is done with it.
+  return render(() => <${Name} {...props} />, el);
 }
 `;
 };

package/src/templates/scaffold-docs.ts

@@ -4,6 +4,7 @@
 // ignore file, the production topology and the deploy page are `scaffold-container.ts`; the
 // `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`.
 
+import { LINE_CEILING } from '../workspace-checks';
 import type { GeneratedFile, NameSet } from './naming';
 import { claudeFiles } from './scaffold-claude';
 import { containerFiles } from './scaffold-container';
@@ -27,10 +28,16 @@ not exist — five of these had an empty column and were each measured green on
 | 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\` |
 | Colour | semantic tokens only, never a raw hex | \`guards/raw-colour.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.
 
+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 —
+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.
+
 Money is the one row with no guard, deliberately: a float has no static signature a text rule can
 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

package/src/templates/scaffold-entries.ts

@@ -9,8 +9,10 @@ import type { GeneratedFile } from './naming';
 const server =
   (): string => `// The production entry. \`docker/Dockerfile\` starts this, and \`x build --target binary\` compiles it.
 // ROLE selects what this process is — web, sync, worker, scheduler, replicator, or migrate, which
-// applies the migrations and exits. PORT is bound on every interface, because a container bound to
-// localhost is unreachable through its own port mapping.
+// applies the migrations and exits. PORT is bound on HOST, and HOST defaults to every interface,
+// because a container bound to loopback is unreachable through its own port mapping. HOST=127.0.0.1
+// is for a process that must never answer a public interface: reachable only where the container
+// shares the host's network namespace (\`--network host\`), or through a sidecar and \`ssh -L\`.
 
 import { join } from 'node:path';
 import { runRole } from '@ultimat3/cli';

package/src/templates/slice-foundation.ts

@@ -3,6 +3,7 @@
 // `policyFiles`; the five generators that write *into* a slice imported the same files and wrote
 // none of them, so each emitted TS2307 in any slice a resource had not been run in first.
 
+import { stripComments } from '../ts-scan';
 import type { FeatureTarget } from './entity';
 import { entityFiles } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
@@ -84,3 +85,38 @@ export function sliceFoundation(
       : []),
   ]);
 }
+
+/** The exported names an `export { a, b as c }` list declares — `c`, never `b`. */
+const listedExports = (code: string): readonly string[] =>
+  [...code.matchAll(/\bexport\s*\{([^}]*)\}/g)].flatMap((match) =>
+    (match[1] ?? '')
+      .split(',')
+      .map(
+        (entry) =>
+          entry
+            .trim()
+            .split(/\s+as\s+/)
+            .at(-1)
+            ?.trim() ?? '',
+      )
+      .filter((entry) => entry !== ''),
+  );
+
+/**
+ * Whether `source` — a slice module as it stands on the app's disk — exports the VALUE `name`.
+ * Read at generation time because assuming it was measured: `x g action` into ai-maxxing's
+ * `fleet` slice wrote `import { FleetNotFoundError } from '../errors'` into a slice whose
+ * `errors.ts` declared `HostNotFoundError` and `SessionNotFoundError` and no `FleetNotFoundError`.
+ * The file failed at import — and because `x db gen` and `x manifest` load every module, one
+ * generated-and-not-yet-edited action made both refuse to run.
+ *
+ * Comments are masked first: `// TODO: add FleetNotFoundError` is not an export. A `type` or an
+ * `interface` of that name is not one either — the generated code constructs it.
+ */
+export function sliceExports(source: string, name: string): boolean {
+  const code = stripComments(source);
+  const declared = new RegExp(
+    `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|function|enum)\\s+${name}\\b`,
+  );
+  return declared.test(code) || listedExports(code).includes(name);
+}

package/src/verify-checks.ts

@@ -50,14 +50,21 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'typecheck',
     summary: 'tsc -b across every project the root references',
+    // `typecheckBin` (`x.verify.json`, beside `agentsMdMaxBytes`) swaps the binary and nothing
+    // else: same `-b --pretty false` invocation, same output format to parse, same `X_TYPECHECK_
+    // FAILED` finding either way. Absent means `tsc` — the only checker every app already has,
+    // since `typescript` is a framework dependency and a drop-in replacement is the app's own
+    // devDependency to add, never a default this step could assume.
     async run(ctx) {
-      const result = await ctx.runner(['bunx', 'tsc', '-b', '--pretty', 'false'], {
+      const floor = await readVerifyFloor(ctx.root);
+      const bin = floor?.typecheckBin ?? 'tsc';
+      const result = await ctx.runner(['bunx', bin, '-b', '--pretty', 'false'], {
         cwd: ctx.root,
       });
       return fromExec(result, {
         code: 'X_TYPECHECK_FAILED',
         cause: 'the project does not typecheck',
-        fix: 'bunx tsc -b --pretty false',
+        fix: `bunx ${bin} -b --pretty false`,
       });
     },
   },
@@ -304,12 +311,15 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // vanish, so a typo in the floor covers nothing — which is the false green the floor exists to
     // close, and it is only visible if something reads the file for its own sake.
     async run(ctx) {
-      const agents = await checkAgentsMd(ctx.root);
+      // The floor is read FIRST: it is where a repository declares its own `AGENTS.md` budget,
+      // and reading it after the check would enforce the default on a repo that raised it.
+      const floor = await readVerifyFloor(ctx.root);
+      const agents = await checkAgentsMd(ctx.root, floor?.agentsMdMaxBytes);
       const findings = [
         ...manifestMissingFindings(ctx.root),
         ...(await driftFindings(ctx.root)),
         ...(await envExampleFindings(ctx.root)),
-        ...floorProblemFindings(await readVerifyFloor(ctx.root)),
+        ...floorProblemFindings(floor),
         ...agents.findings,
         ...(await hostFindings(ctx, 'manifest')),
       ];

package/src/verify-floor.ts

@@ -8,6 +8,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import { AGENTS_MD_MAX_BYTES } from '@ultimat3/manifest';
 import type { Finding } from './output';
 import { VERIFY_STEP_NAMES } from './verify-step';
 
@@ -17,10 +18,81 @@ export const VERIFY_FLOOR_FILE = 'x.verify.json';
 export interface VerifyFloor {
   /** Declared step names this run may not report as skipped. */
   readonly steps: readonly string[];
+  /**
+   * This repository's `AGENTS.md` budget, in bytes, when it declares one. `@ultimat3/manifest`
+   * has always taken a `maxBytes` and the gate never passed one, so the 12kB default was the only
+   * budget an app could have — and an app whose conventions genuinely need more had no move left
+   * but to delete a rule to make room, which is the opposite of what the budget is for.
+   *
+   * It is here rather than in `x.config.ts` because this is the file that configures the GATE,
+   * and it is read by the very step that enforces the budget. Raising it is a commit a reviewer
+   * sees, which is the whole safeguard: the number is small, visible, and argued for in one place.
+   */
+  readonly agentsMdMaxBytes?: number;
+  /**
+   * The binary the `typecheck` step invokes in place of `tsc` — `bunx <typecheckBin> -b --pretty
+   * false`, unchanged otherwise. Absent means `tsc`, which is the only binary every app already
+   * has: `typescript` is a framework dependency, not one this file can assume an app added.
+   *
+   * Here for the same reason `agentsMdMaxBytes` is: this is the file that configures the GATE,
+   * and it is read by the very step the key names. A drop-in `tsc -b` compatible checker (Microsoft's
+   * `tsgo`, `@typescript/native-preview`) is a devDependency + a one-line commit here, never a
+   * hardcoded default — an app that has not installed the binary this names gets `command not
+   * found` from its own shell, not a framework opinion about which compiler is correct.
+   */
+  readonly typecheckBin?: string;
   /** Why part of the file is not a floor. The `manifest` step reports these; nothing swallows them. */
   readonly problems: readonly string[];
 }
 
+/** The floor's budget key. Named once: the problem quotes it and the fix repairs it. */
+export const BUDGET_FIELD = 'agentsMdMaxBytes';
+
+/** The floor's typecheck-binary key. Named once: the problem quotes it and the fix repairs it. */
+export const TYPECHECK_BIN_FIELD = 'typecheckBin';
+
+/**
+ * `agentsMdMaxBytes`, or a reason it is not one. A budget that is not a positive whole number is
+ * the caller's bug and must not silently fall back to the default: a floor file that says
+ * `"agentsMdMaxBytes": "16kb"` and is quietly ignored is a repository that believes it raised a
+ * budget it did not, and finds out when the gate goes red on a commit that changed nothing.
+ */
+function readBudget(payload: Record<string, unknown> | undefined): {
+  budget?: number;
+  problems: readonly string[];
+} {
+  const raw = payload?.[BUDGET_FIELD];
+  if (raw === undefined) return { problems: [] };
+  if (typeof raw !== 'number' || !Number.isSafeInteger(raw) || raw <= 0)
+    return {
+      problems: [
+        `"${BUDGET_FIELD}" is ${JSON.stringify(raw)}, which is not a positive whole number of bytes`,
+      ],
+    };
+  return { budget: raw, problems: [] };
+}
+
+/**
+ * `typecheckBin`, or a reason it is not one. A non-string value must not silently fall back to
+ * `tsc`: a floor that names `"typecheckBin": 7` and gets `tsc` anyway is a repository that
+ * believes the `typecheck` step is running a checker it is not, which is the same false green
+ * `readBudget` above already refuses for the byte count. An empty string is refused for the same
+ * reason `-b`'s own project argument may not be empty — `bunx '' -b …` is not a step that failed
+ * to typecheck, it is a step that never ran a compiler at all.
+ */
+function readTypecheckBin(payload: Record<string, unknown> | undefined): {
+  bin?: string;
+  problems: readonly string[];
+} {
+  const raw = payload?.[TYPECHECK_BIN_FIELD];
+  if (raw === undefined) return { problems: [] };
+  if (typeof raw !== 'string' || raw.trim().length === 0)
+    return {
+      problems: [`"${TYPECHECK_BIN_FIELD}" is ${JSON.stringify(raw)}, which is not a binary name`],
+    };
+  return { bin: raw, problems: [] };
+}
+
 const asRecord = (value: unknown): Record<string, unknown> | undefined =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -48,19 +120,35 @@ export function parseVerifyFloor(
     // was meant to make the path safe (`metrics-endpoint.ts` states the same rule over `stringField`).
     return { steps: [], problems: [`it does not parse as JSON (${renderThrowable(error)})`] };
   }
-  const steps = asRecord(payload)?.['steps'];
+  const record = asRecord(payload);
+  const budget = readBudget(record);
+  const typecheckBin = readTypecheckBin(record);
+  const steps = record?.['steps'];
   if (!Array.isArray(steps)) {
-    return { steps: [], problems: ['it has no "steps" array of step names'] };
+    return {
+      steps: [],
+      ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
+      ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
+      problems: [
+        'it has no "steps" array of step names',
+        ...budget.problems,
+        ...typecheckBin.problems,
+      ],
+    };
   }
   const named = steps.filter((step): step is string => typeof step === 'string');
   const unknown = named.filter((step) => !declared.includes(step));
   return {
     steps: named.filter((step) => declared.includes(step)),
+    ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
+    ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
     problems: [
       ...(named.length === steps.length ? [] : ['"steps" holds an entry that is not a string']),
+      ...typecheckBin.problems,
       ...(unknown.length === 0
         ? []
         : [`"steps" names ${unknown.join(', ')}, which x verify does not run`]),
+      ...budget.problems,
     ],
   };
 }
@@ -129,7 +217,22 @@ export const floorProblemFindings = (floor: VerifyFloor | undefined): readonly F
   (floor?.problems ?? []).map((problem) => ({
     code: 'X_CONFIG_INVALID',
     cause: `${VERIFY_FLOOR_FILE} is not a suite floor: ${problem}`,
-    fix: `x verify --json   # then write ${VERIFY_FLOOR_FILE} as {"steps":["unit","contract"]}, naming only steps it ran`,
+    fix: fixFor(problem),
     docs: ERROR_DOCS_URL,
     at: VERIFY_FLOOR_FILE,
   }));
+
+/**
+ * The edit that repairs THIS problem, not the file in general. The steps-shaped fix is useless
+ * against a bad budget — it prints a `{"steps":[…]}` example with no `agentsMdMaxBytes` in it, so
+ * an author who followed it verbatim would still have the value that failed. A finding whose fix
+ * does not fix it is the failure `packages/cli/CLAUDE.md` names, and the budget is the first
+ * problem this file can report that is not about `steps` at all.
+ */
+const fixFor = (problem: string): string => {
+  if (problem.includes(`"${BUDGET_FIELD}"`))
+    return `x verify --json   # then set "${BUDGET_FIELD}" in ${VERIFY_FLOOR_FILE} to a positive whole number of bytes, or drop the key for the ${AGENTS_MD_MAX_BYTES}B default`;
+  if (problem.includes(`"${TYPECHECK_BIN_FIELD}"`))
+    return `x verify --json   # then set "${TYPECHECK_BIN_FIELD}" in ${VERIFY_FLOOR_FILE} to a non-empty binary name, or drop the key to run tsc`;
+  return `x verify --json   # then write ${VERIFY_FLOOR_FILE} as {"steps":["unit","contract"]}, naming only steps it ran`;
+};