@ultimat3/cli 22.15.0 → 23.0.0

package/src/budgets.ts

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest, RouteFact } from '@ultimat3/manifest';
 import {
+  describeRoutes,
   formatBytes,
   parseByteBudget,
   SPECULATION_RULES_TYPE,
@@ -74,6 +75,25 @@ const chainOf = (stats: RouteStats): string =>
 
 const jsBudgetOf = (route: RouteFact): number | null => parseByteBudget(route.budget?.js);
 
+/** Which file declares a route, by URL — the loaded app's route table, read when the step runs. */
+export type RouteFileOf = (url: string) => string | undefined;
+
+const declaredFileOf: RouteFileOf = (url) =>
+  describeRoutes().find((route) => route.path === url && route.mount === undefined)?.file;
+
+const KB = 1024;
+
+/**
+ * The paste, not the advice: the file, the literal to set (the measured bytes rounded UP to a
+ * whole kb, so the raise is the smallest that clears) and the comment `bun run budget-raises`
+ * reads above it. The other way out stays beside it — a raise is axiom 9's to allow, not to force.
+ */
+function exceededJsFix(url: string, file: string | undefined, bytes: number): string {
+  const where = file ?? `the file declaring ${url}`;
+  const kb = Math.ceil(bytes / KB);
+  return `edit ${where} — set budget: { js: '${String(kb)}kb' } with // measured: ${String(bytes)} B (x build --target static) — why: <the function it buys> directly above it; or x routes --json for the chain and move the heavy import behind hydrate: 'interaction'`;
+}
+
 /** Which budgets the route declared, for a cause line that names what went unmeasured. */
 function declaredBudgets(js: number | null, lcp: number | undefined): string {
   const labels: string[] = [];
@@ -169,11 +189,15 @@ function ownCodeFinding(url: string, unmeasured: readonly UnmeasuredRoute[]): Fi
  * each failure's code when it had one. Optional because the report is written beside the stats
  * and can be absent for the same reason; with it, a route whose measurement failed on a code in
  * `REPORTED_BY_OWN_CODE` is reported under that code, with the build's own cause and fix.
+ *
+ * `fileOf` names the file an `X_BUDGET_EXCEEDED` fix edits: the step runs after the app loaded,
+ * so render's route table already holds it. A test hands its own.
  */
 export function checkBudgets(
   manifest: Manifest,
   stats: BuildStats | undefined,
   unmeasured: readonly UnmeasuredRoute[] = [],
+  fileOf: RouteFileOf = declaredFileOf,
 ): readonly Finding[] {
   const byPath = new Map((stats?.routes ?? []).map((route) => [route.path, route]));
   // Routes no build can weigh by construction (`UnmeasuredRoute.weighable`): printed by the step,
@@ -205,7 +229,7 @@ export function checkBudgets(
       findings.push({
         code: 'X_BUDGET_EXCEEDED',
         cause: `${route.url} ships ${formatBytes(measured.jsBytes)} of JS (minified, uncompressed) over a ${formatBytes(js)} budget via ${chainOf(measured)}`,
-        fix: `x routes --json to see the chain, then move the heavy import behind hydrate: 'interaction'`,
+        fix: exceededJsFix(route.url, fileOf(route.url), measured.jsBytes),
         docs: ERROR_DOCS_URL,
         at: route.url,
       });

package/src/cmd-build-spec.ts

@@ -5,12 +5,19 @@ import type { CommandSpec } from './parse';
 
 export const buildSpec: CommandSpec = {
   name: 'build',
-  summary: 'build a container image, a single binary, or a prerendered static site',
+  summary:
+    'build a container image, a single binary, a prerendered static site, or the store an image boots from',
   usage:
-    'x build --target docker|binary|static [--tag name] [--out path] [--no-preflight] [--json]',
+    'x build --target docker|binary|static|prebuilt [--tag name] [--out path] [--no-preflight] [--json]',
   requiresApp: true,
   flags: [
-    { name: 'target', type: 'string', summary: 'docker | binary | static', default: 'docker' },
+    {
+      name: 'target',
+      type: 'string',
+      summary:
+        'docker | binary | static | prebuilt — prebuilt is the line a Dockerfile runs inside the image build',
+      default: 'docker',
+    },
     { name: 'tag', type: 'string', summary: 'image tag (docker target)' },
     { name: 'out', type: 'string', summary: 'output path (binary and static targets)' },
     {

package/src/cmd-build.ts

@@ -1,5 +1,6 @@
-// `x build --target docker|binary|static` — three targets, no platform primitives. Deploy anywhere
-// means "anywhere that runs a container or a binary"; nothing here knows the name of a cloud.
+// `x build --target docker|binary|static|prebuilt` — no platform primitives. Deploy anywhere means
+// "anywhere that runs a container or a binary"; nothing here knows the name of a cloud. `prebuilt`
+// is the docker target's other half: the line the Dockerfile runs INSIDE the image build.
 
 import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -9,13 +10,13 @@ import { buildSpec } from './cmd-build-spec';
 import { runVerify } from './cmd-verify';
 import type { CliCommand, CommandContext } from './command';
 import { externalArgs } from './compile-externals';
-import { BuildEntryMissingError, UnknownCommandError } from './errors';
+import { BadFlagError, BuildEntryMissingError, UnknownCommandError } from './errors';
 import type { ExecResult } from './exec';
 import { execOutput } from './exec';
-import { prepareImage } from './image-prepare';
 import { msg } from './messages';
 import type { CommandResult } from './output';
 import { flagString } from './parse';
+import { PREBUILT_DIR } from './serve-prebuilt-paths';
 import type { StaticReport } from './static-report';
 import {
   readStaticReport,
@@ -24,10 +25,13 @@ import {
   staticReportData,
 } from './static-report';
 
-export const BUILD_TARGETS = ['docker', 'binary', 'static'] as const;
+export const BUILD_TARGETS = ['docker', 'binary', 'static', 'prebuilt'] as const;
 
 export type BuildTarget = (typeof BUILD_TARGETS)[number];
 
+/** The targets whose builder is a subprocess. `prebuilt` is this process, inside `docker build`. */
+export type SpawnedTarget = Exclude<BuildTarget, 'prebuilt'>;
+
 export function readTarget(raw: string | undefined): BuildTarget {
   const targets: readonly string[] = BUILD_TARGETS;
   if (raw === undefined) return 'docker';
@@ -48,6 +52,8 @@ export const BUILD_ENTRY: Readonly<Record<BuildTarget, string>> = {
   docker: 'docker/Dockerfile',
   binary: 'apps/web/server.ts',
   static: 'apps/web/prerender.ts',
+  // What boots from the store: an image with no server entry has nothing to prebuild for.
+  prebuilt: 'apps/web/server.ts',
 };
 
 /** Absolute path of the target's entry, or the error that names the file and what writes it. */
@@ -109,7 +115,7 @@ export function staticArgs(root: string, out: string): readonly string[] {
 }
 
 export function argsFor(
-  target: BuildTarget,
+  target: SpawnedTarget,
   paths: {
     readonly root: string;
     readonly tag: string;
@@ -184,6 +190,45 @@ export function buildResult(input: {
   };
 }
 
+/**
+ * `x build --target prebuilt`: the island chunks and compiled stylesheets, written by the process
+ * `docker build` runs after the source is copied in. No gate and no subprocess — the image holds
+ * no devDependencies to typecheck with, and `x verify` ran before `docker build` was called.
+ *
+ * A module that would not import fails the image build rather than warning into a build log
+ * nobody reads: its stylesheets are missing from the store, and every pod would compile them.
+ */
+async function buildPrebuilt(ctx: CommandContext, root: string): Promise<CommandResult> {
+  // The boot reads ONE place; a flag that seemed to move it would write a store no pod opens.
+  for (const flag of ['tag', 'out']) {
+    if (flagString(ctx.args, flag) === undefined) continue;
+    throw new BadFlagError({
+      flag,
+      command: 'build',
+      reason: `the prebuilt target writes ${PREBUILT_DIR}, the one place a container boots from, and takes no --${flag}`,
+      fix: 'x build --target prebuilt',
+    });
+  }
+  const started = Bun.nanoseconds();
+  const { prebuildImage } = await import('./image-prepare');
+  const built = await prebuildImage(root);
+  const ok = built.findings.length === 0;
+  return {
+    ok,
+    command: 'build',
+    summary: msg(ok ? 'cli.build.done' : 'cli.build.failed', { target: 'prebuilt' }),
+    findings: built.findings,
+    data: {
+      target: 'prebuilt',
+      artifact: built.dir,
+      durationMs: Math.round((Bun.nanoseconds() - started) / 1e6),
+      islands: built.islands,
+      stylesheets: built.stylesheets,
+    },
+    lines: [],
+  };
+}
+
 /** The static steps `x build` runs before it builds, and `--no-preflight` leaves to the gate. */
 export const PREFLIGHT_STEPS: readonly string[] = [
   'typecheck',
@@ -203,6 +248,7 @@ export const buildCommand: CliCommand = {
     // typecheck, and eight seconds of `tsc` ahead of "that file does not exist" is eight seconds
     // an agent spends on the wrong question.
     requireEntry(root, target);
+    if (target === 'prebuilt') return buildPrebuilt(ctx, root);
 
     // Run static verify steps before building — unless the caller is a gate that runs the same
     // six steps itself right after (`bin/check`: `x build --no-preflight && x verify`), where the
@@ -227,9 +273,10 @@ export const buildCommand: CliCommand = {
         ? join(root, '.x', target === 'static' ? 'static' : 'app')
         : resolve(ctx.cwd, outFlag);
     const tag = flagString(ctx.args, 'tag') ?? 'ultimate-app:dev';
-    // The docker target stamps the manifest's build id into the image, and writes the island
-    // chunks the image serves, so a container boot neither re-derives the one nor rebuilds the other.
-    const buildId = target === 'docker' ? await prepareImage(root) : undefined;
+    // The docker target stamps the manifest's build id into the image, so no role derives one at
+    // boot. The island chunks and stylesheets are the image build's own (`--target prebuilt`).
+    const buildId =
+      target === 'docker' ? await (await import('./image-prepare')).imageBuildId(root) : undefined;
     const command = argsFor(target, {
       root,
       tag,

package/src/cmd-db.ts

@@ -22,6 +22,13 @@ import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
 import { stepFinding } from './db-finding';
 import { generateAppMigration, unrenderedJson, unrenderedLines } from './db-generate';
+import { liveObjectDrift } from './db-object-drift';
+import {
+  afterWrittenMigration,
+  refreshSchemaDump,
+  type SchemaDumpRefresh,
+  schemaDumpJson,
+} from './db-schema-refresh';
 import type { SeedPassRow } from './db-seed';
 import {
   discoverSeeds,
@@ -109,34 +116,52 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
   // `x i18n add fr` failure, repeated. The count is the verdict; the gate's own `drift` step is
   // where a red belongs, and it reads the same list to decide that `x db gen` is not the fix.
   const lost = unrenderedLines(generated.unrendered);
+  // After the migration, from the migrations alone: the dump is what replaying them produces, so
+  // it is rewritten on all three outcomes — `unchanged` included, which is what makes this
+  // command the `fix:` on `X_SCHEMA_DUMP_DRIFT` when a framework table or a hand edit moved it.
+  const dump = await refreshSchemaDump(root, ctx.env);
+  const dumpFindings = dump.finding === undefined ? [] : [dump.finding];
   const migration = generated.migration;
   if (migration === undefined) {
     return {
-      ok: generated.findings.length === 0,
+      ok: generated.findings.length === 0 && dumpFindings.length === 0,
       command: 'db',
       // The sidecar path, never a bare id: `hash-recorded` writes exactly one, and it is the file
       // the `drift` step reads back.
+      // `blocked` FIRST: the app did not load, so nothing was diffed, and every sentence below
+      // it is a claim about a comparison that never ran. It read "entities and migrations agree"
+      // over an exit 1.
       summary:
-        generated.outcome === 'hash-recorded'
-          ? msg('cli.db.gen.recorded', { file: generated.files[0] ?? '' })
-          : msg('cli.db.gen.unchanged'),
-      findings: generated.findings,
+        generated.outcome === 'blocked'
+          ? msg('cli.db.gen.blocked', { count: generated.findings.length })
+          : generated.outcome === 'hash-recorded'
+            ? msg('cli.db.gen.recorded', { file: generated.files[0] ?? '' })
+            : dump.status === 'written'
+              ? msg('cli.db.gen.dumped', { count: dump.written.length + dump.removed.length })
+              : msg('cli.db.gen.unchanged'),
+      findings: [...generated.findings, ...dumpFindings],
       // `files` is what this command WROTE, so the empty array here was a false claim.
-      lines: [...generated.files.map((file) => `  ${file}`), ...lost],
+      lines: [...generated.files.map((file) => `  ${file}`), ...dumpLines(dump), ...lost],
       data: {
         outcome: generated.outcome,
         migration: null,
         files: [...generated.files],
         schemaHash: generated.schemaHash ?? null,
         unrendered: unrenderedJson(generated.unrendered),
+        schemaDump: schemaDumpJson(dump),
       },
     };
   }
   return {
-    ok: true,
+    ok: dumpFindings.length === 0,
     command: 'db',
-    summary: msg('cli.db.gen.written', { id: migration.id }),
-    lines: [...generated.files.map((file) => `  ${file}`), ...lost],
+    summary:
+      dumpFindings.length === 0
+        ? msg('cli.db.gen.written', { id: migration.id })
+        : msg('cli.db.gen.writtenDumpFailed', { id: migration.id }),
+    // Exit 1 with a migration on disk: the finding has to say so, or the next move is a duplicate.
+    findings: dumpFindings.map((finding) => afterWrittenMigration(finding, migration.id)),
+    lines: [...generated.files.map((file) => `  ${file}`), ...dumpLines(dump), ...lost],
     data: {
       outcome: generated.outcome,
       migration: migration.id,
@@ -144,10 +169,20 @@ async function runGen(ctx: CommandContext, root: string, name: string): Promise<
       files: [...generated.files],
       schemaHash: generated.schemaHash ?? null,
       unrendered: unrenderedJson(generated.unrendered),
+      schemaDump: schemaDumpJson(dump),
     },
   };
 }
 
+/**
+ * What the dump refresh did, one path per line — the same list `data.schemaDump` carries, so the
+ * human render and `--json` report one fact. A refresh that changed nothing prints nothing.
+ */
+const dumpLines = (dump: SchemaDumpRefresh): readonly string[] => [
+  ...dump.written.map((file) => `  ${file}`),
+  ...dump.removed.map((file) => `  - ${file}`),
+];
+
 /**
  * The post-migrate report, rendered. Through `driftError` rather than a second literal: the
  * three-line `X_DB_DRIFT` output is pinned by the framework contract, and this command must not be
@@ -175,16 +210,30 @@ async function runMigrate(
   try {
     const migrated = await runMigrations({ root, env: ctx.env });
     const report = migrated.report;
+    // A hand-written or pulled migration reaches the dump here, with no `x db gen` in between.
+    const dump = await refreshSchemaDump(root, ctx.env);
+    // The half a snapshot cannot hold: a trigger, function, view, type or sequence this database
+    // carries and no migration creates. Asked only when the replay produced a catalog to ask
+    // against — without one there is nothing that says what the migrations create.
+    const objects =
+      dump.catalog === undefined ? [] : await liveObjectDrift(root, ctx.env, dump.catalog);
+    const findings = [
+      ...driftFindings(migrated.drift),
+      ...objects.map((difference) => findingFrom(driftError(difference))),
+      ...(dump.finding === undefined ? [] : [dump.finding]),
+    ];
     return {
-      ok: migrated.drift.ok,
+      ok: findings.length === 0,
       command: 'db',
       summary,
-      findings: driftFindings(migrated.drift),
+      findings,
+      lines: dumpLines(dump),
       data: {
         applied: report.applied.map((entry) => entry.id),
         skipped: report.skipped.length,
         appVersion: report.appVersion,
         durationMs: report.durationMs,
+        schemaDump: schemaDumpJson(dump),
       },
     };
   } catch (error) {

package/src/cmd-doctor.ts

@@ -22,8 +22,12 @@ import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import { DEFAULT_DOCTOR_PORT, doctorSpec } from './cmd-doctor-spec';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
+import { coverageExcludesProbe, withCoverageExcludes } from './doctor-coverage';
+import { shippedGuardsProbe, withGuardListing } from './doctor-guards';
 import type { OfflineFallbackFact } from './doctor-offline';
 import { offlineFallbackFinding, offlineFallbackProbe } from './doctor-offline';
+import type { SealedKeysFact } from './doctor-sealed';
+import { sealedKeyFindings, sealedKeysProbe } from './doctor-sealed';
 import { intFlagOr, PORT_RANGE, portPairAfter } from './flag-number';
 import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
@@ -91,6 +95,12 @@ export interface DoctorProbe {
    * reaching the disk — the same split `drift()` makes one question over.
    */
   offlineFallback(): Promise<OfflineFallbackFact>;
+  /**
+   * The app's `.sealed()` columns and the master keys this environment declares. A FACT, for the
+   * reason `offlineFallback` is one: loading the app and opening the secrets file is IO, and what
+   * a retired key beside a sealed column means is `sealedKeyFindings`' pure rule.
+   */
+  sealedKeys(): Promise<SealedKeysFact>;
 }
 
 /** What `x doctor` reads about the embedded database, without opening it. */
@@ -281,6 +291,8 @@ export async function runDoctor(probe: DoctorProbe): Promise<readonly Finding[]>
   // author reaches it from: `x db gen` throwing `X_MIGRATION_SNAPSHOT_MISSING` used to be a
   // condition this diagnostic could not see at all, so the fix line ran clean over a broken app.
   findings.push(...(await probe.snapshots()));
+  // Sealed columns against the key ring: no key at all, or a rotation whose re-seal is pending.
+  findings.push(...sealedKeyFindings(await probe.sealedKeys()));
   return findings;
 }
 
@@ -394,6 +406,8 @@ export function probeFor(cwd: string, bunVersion: string, port: number): DoctorP
     // `runDoctor` returns on `X_NOT_IN_APP` before this can be asked.
     offlineFallback: async () =>
       root === undefined ? { fallback: null, routes: undefined } : offlineFallbackProbe(root),
+    sealedKeys: async () =>
+      root === undefined ? { columns: undefined, keys: undefined } : sealedKeysProbe(root),
   };
 }
 
@@ -401,16 +415,26 @@ export const doctorCommand: CliCommand = {
   spec: doctorSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
     const port = doctorPort(ctx.args);
-    const findings = await runDoctor(probeFor(ctx.cwd, ctx.bunVersion, port));
-    return {
-      ok: findings.length === 0,
-      command: 'doctor',
-      summary:
-        findings.length === 0
-          ? msg('cli.doctor.clean')
-          : msg('cli.doctor.findings', { count: findings.length }),
-      findings,
-      data: { count: findings.length, codes: findings.map((entry) => entry.code) },
-    };
+    const probe = probeFor(ctx.cwd, ctx.bunVersion, port);
+    const findings = await runDoctor(probe);
+    const listed = withGuardListing(
+      {
+        ok: findings.length === 0,
+        command: 'doctor',
+        summary:
+          findings.length === 0
+            ? msg('cli.doctor.clean')
+            : msg('cli.doctor.findings', { count: findings.length }),
+        findings,
+        data: { count: findings.length, codes: findings.map((entry) => entry.code) },
+      },
+      // A listing beside the verdict, never part of it (`doctor-guards.ts` says why).
+      probe.root === undefined ? [] : await shippedGuardsProbe(probe.root),
+    );
+    // The second listing: what the coverage floor does not see (`doctor-coverage.ts`).
+    return withCoverageExcludes(
+      listed,
+      probe.root === undefined ? [] : await coverageExcludesProbe(probe.root),
+    );
   },
 };

package/src/cmd-generate.ts

@@ -4,6 +4,7 @@
 
 import { existsSync } from 'node:fs';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { registerAdminResources } from './admin-registration';
 import { registerGeneratedPrimitives } from './api-registration';
 import { writeAppArtifacts } from './app-artifacts';
 import { appManifest } from './app-manifest';
@@ -13,18 +14,21 @@ import type { CliCommand, CommandContext } from './command';
 import { invocationOf } from './command';
 import { assertFeatureExists } from './generate-feature';
 import { generate, sliceDir } from './generate-files';
+import { ungrantedByGenerator } from './generate-grant-findings';
 import { grantGeneratedPermissions } from './generate-grants';
 import type { Generator } from './generate-kinds';
 import { readFeature, readKind, readName, readPermission, readSurface } from './generate-kinds';
 import { containedPath, writeFiles } from './generate-write';
+import { declareGeneratedImports } from './generated-imports';
+import { registerGeneratedEntities, resolveDbModule } from './handle-registration';
 import { resolveCatalogModule } from './i18n-audit';
-import { syncI18nIndex } from './i18n-index';
+import { catalogLocales, syncI18nIndex } from './i18n-index';
 import { reproducedFlags } from './invocation-flags';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import { flagBool, flagList, flagString } from './parse';
 import { quoteArg } from './shell-quote';
-import { kebab, resolveLocales } from './templates';
+import { kebab, names, resolveLocales } from './templates';
 
 // One import path for the generator, unchanged by the split: `index.ts`, `x new` and the scaffold
 // fixture reach the kinds, the pure file list and the writer through this module, and a second path
@@ -46,7 +50,7 @@ export const generateCommand: CliCommand = {
     // Both flags are resolved before a single file is planned: a bad surface or a locale that is
     // really a path fails here, with nothing written and nothing to undo.
     const surface = readSurface(flagString(ctx.args, 'surface'), kind, name);
-    const locales = resolveLocales(flagList(ctx.args, 'locales'));
+    const locales = resolveLocales(await namedOrAppLocales(root, flagList(ctx.args, 'locales')));
     const at = flagString(ctx.args, 'at');
     // Read with the two above, and refused here for their reason: the value is spliced into the
     // emitted source three times, and a value that is not a `<resource>:<verb>` is a page the app
@@ -55,6 +59,10 @@ 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);
+    // And for the same reason: which package a generated `repo.ts` imports the typed handle from.
+    const dbModule = await resolveDbModule(root);
+    // And whether the app has the frame a resource's page sits in.
+    const shell = existsSync(containedPath(root, SHELL_MODULE));
     // Read for the same reason: which errors the slice declares is written on THIS app's disk.
     const slice = sliceDir(surface, kebab(featureFlag ?? name));
     // A named slice that is not there is refused, never invented (X_FEATURE_UNKNOWN).
@@ -78,6 +86,8 @@ export const generateCommand: CliCommand = {
       admin: flagBool(ctx.args, 'admin'),
       locales,
       ...(catalogModule === undefined ? {} : { catalogModule }),
+      ...(dbModule === undefined ? {} : { dbModule }),
+      shell,
     });
     if (flagBool(ctx.args, 'dry-run')) {
       return {
@@ -97,13 +107,29 @@ export const generateCommand: CliCommand = {
       ...reproducedFlags(generateCommand.spec, ctx.args),
     ].join(' ');
     const report = await writeFiles(root, files, flagBool(ctx.args, 'force'), invocation);
-    // The two edits a generated primitive needs outside its own slice, performed rather than left
-    // as findings: a declared permission granted to a role, and a job listed in `defineApi`.
-    // Before the manifest load below, so the projection sees both.
+    // The three edits a generated primitive needs outside its own slice, performed rather than
+    // left as findings: a declared permission granted to a role, a job listed in `defineApi`, and
+    // an entity added to the typed handle its `repo.ts` reads through. Before the manifest load
+    // below, so the projection sees all three — a repo reading a table the handle lacks would not
+    // load at all.
+    const handle = await registerGeneratedEntities(root, report.written, dbModule);
+    // And a fourth, for `--admin`: the override it wrote, listed where `defineAdmin()` reads it.
+    const adminWiring = await registerAdminResources(root, report.written);
+    // And a fifth, last because the others add imports too: every sibling workspace a written file
+    // imports, declared in the manifest it landed under — or `package-shape` refuses the output.
     const edited = [
-      ...(await grantGeneratedPermissions(root, report.written)),
-      ...(await registerGeneratedPrimitives(root, report.written)),
+      ...new Set([
+        ...(await grantGeneratedPermissions(root, report.written)),
+        ...(await registerGeneratedPrimitives(root, report.written)),
+        ...handle.edited,
+        ...adminWiring.edited,
+        ...(await declareGeneratedImports(root, report.written)),
+      ]),
     ];
+    // A grant that edit could not place is said so, with the role each permission belongs to: an
+    // app whose role map is not the scaffold's got no grant and no word, and a 403 on every
+    // endpoint the run had just written.
+    const ungranted = await ungrantedByGenerator(root, report.written);
     // A locale's catalog existing on disk and the app being able to select it are two different
     // facts — see `syncI18nIndex`. Runs before the manifest load below so a route or resource
     // this same invocation just wrote never gets projected against a stale catalog registration.
@@ -133,17 +159,36 @@ export const generateCommand: CliCommand = {
         buildId = manifest.buildId;
       } else loadFailures.push(...findings);
     }
-    const findings = [...report.conflicts, ...indexSync.findings, ...loadFailures];
+    const findings = [
+      ...report.conflicts,
+      ...handle.findings,
+      ...ungranted,
+      ...adminWiring.findings,
+      ...indexSync.findings,
+      ...loadFailures,
+    ];
     // One list behind all three renderings. The manifest was printed as a `+` line while the count
     // beside it came from `report.written` alone, so `x g island` said "wrote 2 file(s)" over three
     // lines — and `--json` carried the shorter list, which is the drift `--json` exists to prevent.
     const written = [...report.written, ...edited, ...artifacts];
+    // Named only over a clean run: with a finding, the finding's own `fix:` is the next command.
+    const table = names(isEntityKind(kind) ? name : (featureFlag ?? name)).table;
+    const next = findings.length === 0 ? nextSteps(report.written, edited, table) : [];
     return {
       ok: findings.length === 0,
       command: 'g',
-      summary: msg('cli.generate.wrote', { count: written.length, kind, name }),
+      summary:
+        next.length === 0
+          ? msg('cli.generate.wrote', { count: written.length, kind, name })
+          : msg('cli.generate.wroteNext', {
+              count: written.length,
+              kind,
+              name,
+              next: next.join(' && '),
+            }),
       data: {
         files: written,
+        ...(next.length === 0 ? {} : { next }),
         ...(buildId === undefined ? {} : { manifest: { buildId } }),
       },
       lines: written.map((path) => msg('cli.file.added', { path })),
@@ -152,6 +197,59 @@ export const generateCommand: CliCommand = {
   },
 };
 
+/**
+ * `--locales` when the caller named any, and otherwise every locale the app already has a catalog
+ * for: a key written to `en` alone in an app that also ships `es` renders ⟦key⟧ for every Spanish
+ * reader. A stem that is not a locale tag is some other JSON file, and not a catalog to write to.
+ */
+async function namedOrAppLocales(
+  root: string,
+  named: readonly string[],
+): Promise<readonly string[]> {
+  if (named.length > 0) return named;
+  return (await catalogLocales(root)).filter((stem) => {
+    try {
+      return Intl.getCanonicalLocales(stem).length === 1;
+    } catch {
+      return false;
+    }
+  });
+}
+
+const isEntityKind = (kind: Generator): boolean => kind === 'entity' || kind === 'resource';
+
+/**
+ * What a run that declared a table owes before the app can read it, in the order it has to
+ * happen — each one a command that runs as printed. `bunx x`, never a bare `x`: `bun install`
+ * links the binary into `./node_modules/.bin` and nowhere on PATH.
+ *
+ * `bun install` leads when a manifest gained a workspace edge: the handle imports the entity from
+ * the web workspace, and an edge only a manifest declares is not linked until the install runs.
+ * `x db gen` then writes the migration AND `packages/db/schema/`, which the `drift` step holds.
+ */
+export function nextSteps(
+  written: readonly string[],
+  edited: readonly string[],
+  table: string,
+): readonly string[] {
+  if (!written.some((path) => path.endsWith('/entity.ts'))) return [];
+  return [
+    ...(edited.some((path) => path.endsWith('package.json')) ? ['bun install'] : []),
+    `bunx x db gen "create ${table}"`,
+    'bunx x db migrate',
+    // A page that mounts an island has a byte budget only a build can weigh — measured on `x new`'s
+    // app (`RESOURCE_PAGE_BUDGET`), and an app that charges more per document is over it on this
+    // run rather than on the next `bin/check`.
+    ...(written.some((path) => path.endsWith('/page.tsx')) ? [MEASURE_PAGE] : []),
+  ];
+}
+
+/** The two commands that weigh a page against its budget: the build writes the bytes it reads. */
+export const MEASURE_PAGE = 'bunx x build --target static && bunx x verify --only budgets';
+
+/** The frame `x new` writes: a resource's page renders inside it when the app has one. */
+export const SHELL_MODULE = 'apps/web/shared/shell.tsx';
+
 /**
  * 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
@@ -167,20 +265,23 @@ async function readSliceErrors(
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }
 
+/** The generators whose output depends on what the slice's `entity.ts` / `repo.ts` declare. */
+const READS_SLICE: ReadonlySet<Generator> = new Set(['job', 'task', 'action', 'mutator', 'query']);
+
 /**
- * `job`, `task`, `action` and `mutator`: the slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the
- * generator's kind is neither or the file does not exist yet. `readSliceErrors`'s reason —
- * whichever generator reads it decides on THIS app's disk, not on a default the template assumes.
+ * The slice's `entity.ts`/`repo.ts` as they stand on disk, absent when the generator's kind reads
+ * neither or the file does not exist yet. `readSliceErrors`'s reason — whichever generator reads
+ * it decides on THIS app's disk, not on a default the template assumes. `query` reads them for its
+ * test alone: whether it may store a row is a fact about the entity an author may have reshaped.
+ * Exported so a test can ask which kinds read the disk without running a whole generation.
  */
-async function readSliceFile(
+export async function readSliceFile(
   root: string,
   kind: Generator,
   slice: string,
   name: 'entity.ts' | 'repo.ts',
 ): Promise<string | undefined> {
-  if (kind !== 'job' && kind !== 'task' && kind !== 'action' && kind !== 'mutator') {
-    return undefined;
-  }
+  if (!READS_SLICE.has(kind)) return undefined;
   const file = containedPath(root, `${slice}/${name}`);
   return existsSync(file) ? await Bun.file(file).text() : undefined;
 }