@ultimat3/cli 23.0.0 → 25.0.0

package/src/app-config-load.ts

@@ -0,0 +1,51 @@
+// The one reader of an app's `app.config.ts`: imported here and nowhere else in the tree
+// (`bun run boundaries`, `X_CONFIG_IMPORT_OUTSIDE_LOADER`), its `config` export handed back through
+// core's own `defineConfig` — so every boot fact the CLI reads is the validated, default-merged
+// `AppConfig`, never a structural walk with a fallback of its own.
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative.
+import { join } from 'node:path';
+import type { AppConfig, AppConfigInput } from '@ultimat3/core';
+import { ConfigInvalidError, defineConfig, describeValue } from '@ultimat3/core';
+import { APP_CONFIG_FILE } from './app-root';
+
+/** The export every app declares. Named, never default — the CLI and the runtime both import it. */
+export const APP_CONFIG_EXPORT = 'config';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * One named export of `root`'s `app.config.ts`, or `undefined` when the root has no such file or
+ * the module does not export `name`. A module that will not import throws as it did — the callers
+ * that report rather than crash (`x doctor`'s env check) turn that into a finding.
+ */
+export async function appConfigExport(root: string, name: string): Promise<unknown> {
+  const path = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const module = (await import(path)) as Record<string, unknown>;
+  return Object.hasOwn(module, name) ? module[name] : undefined;
+}
+
+/**
+ * `root`'s `AppConfig`, or `undefined` when the root has no `app.config.ts` — not an app, and each
+ * caller's "nothing declared" answer is its own. A file that IS there is held to `defineConfig`'s
+ * one validator: a hand-built `config` object reaches the boot validated and defaulted exactly as
+ * one built by `defineConfig` does, which re-merges to itself. One resolved through a 24.x core is
+ * refused (its defaults wrote keys 25.0.0 removed): install every `@ultimat3/*` at one version. A file with no `config` object is refused rather than read as "every default".
+ */
+export async function loadAppConfig(root: string): Promise<AppConfig | undefined> {
+  const path = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(path).exists())) return undefined;
+  const exported = await appConfigExport(root, APP_CONFIG_EXPORT);
+  if (!isRecord(exported)) {
+    throw new ConfigInvalidError({
+      cause: `${path} exports no ${APP_CONFIG_EXPORT} object (${describeValue(exported)})`,
+      fix: "export const config = defineConfig({ name: 'my-app' });",
+      meta: { key: APP_CONFIG_EXPORT },
+    });
+  }
+  // A cast over a record whose structure `defineConfig` screens first (`shapeIssues`, per layer):
+  // the validator IS the parse, and a second hand-written schema here would be a second answer.
+  return defineConfig(exported as unknown as AppConfigInput);
+}

package/src/app-env.ts

@@ -2,18 +2,13 @@
 // `app.config.ts`, the `.env.example` projected from it, and the drift between the two. One
 // declaration, both files (axiom 2) — nothing here holds a second list of variable names.
 
-// why: Bun ships no synchronous exists; `existsSync` answers whether this root is an app.
-import { existsSync } from 'node:fs';
 // why: Bun exposes no path API — the two files this module reads are joined to the app root.
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
-import {
-  checkEnvExample,
-  ENV_EXAMPLE_PATH,
-  ERROR_DOCS_URL,
-  renderEnvExample,
-} from '@ultimat3/core';
+import { ENV_EXAMPLE_PATH, ERROR_DOCS_URL, parseEnvKeys } from '@ultimat3/core';
+import { appConfigExport } from './app-config-load';
 import { APP_CONFIG_FILE } from './app-root';
+import { appEnvExample, FRAMEWORK_SECRETS } from './framework-env';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 
@@ -45,28 +40,26 @@ export const isEnvSchema = (value: unknown): value is EnvSchema =>
   isRecord(value) && Object.values(value).every(isDecl);
 
 /**
- * Import `app.config.ts` and hand back the declaration it exports. Importing is the only honest
- * way to read it — the alternative is a regex over the app's source, which is the pattern
- * `app-load.ts` exists to refuse. `undefined` means "this root declares no environment"; a config
- * that will not import throws, and the caller turns that into the finding.
+ * The declaration `app.config.ts` exports, through the one loader (`app-config-load.ts`).
+ * `undefined` means "this root declares no environment"; a config that will not import throws, and
+ * the caller turns that into the finding.
  */
 export async function loadEnvSchema(root: string): Promise<EnvSchema | undefined> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!existsSync(configPath)) return undefined;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const declared = module[ENV_SCHEMA_EXPORT];
-  if (declared === undefined) return undefined;
+  const declared = await appConfigExport(root, ENV_SCHEMA_EXPORT);
   return isEnvSchema(declared) ? declared : undefined;
 }
 
-/** The bytes `.env.example` must hold. Deterministic, so a rewrite that changes nothing diffs to nothing. */
-export const envExampleFor = (schema: EnvSchema): string => renderEnvExample(schema);
+/**
+ * The bytes `.env.example` must hold: the app's declaration, then the framework's deploy-required
+ * keys (`framework-env.ts`). Deterministic, so a rewrite that changes nothing diffs to nothing.
+ */
+export const envExampleFor = (schema: EnvSchema): string => appEnvExample(schema);
 
 const driftFinding = (cause: string): Finding => ({
   code: 'X_ENV_EXAMPLE_DRIFT',
   cause,
-  // The generator, not the assertion: `assertEnvExample`'s own fix is a `Bun.write(…)` call for
-  // an app that has a schema object in scope, and a gate reader has a shell.
+  // The generator, never a `Bun.write(…)` call: that needs a schema object in scope, and a gate
+  // reader has a shell.
   fix: 'x env example',
   docs: ERROR_DOCS_URL,
   at: ENV_EXAMPLE_PATH,
@@ -97,12 +90,20 @@ export async function envExampleFindings(root: string): Promise<readonly Finding
   }
   const text = await file.text();
   if (text === expected) return [];
-  const report = checkEnvExample(schema, text);
+  const present = new Set(parseEnvKeys(text));
+  const missing = Object.keys(schema).filter((key) => !present.has(key));
+  // The framework's keys are owed by every deployed app, whatever its schema says (#679), and an
+  // example written before they were part of the contract is missing exactly these.
+  const owed = FRAMEWORK_SECRETS.map((secret) => secret.key).filter(
+    (key) => !Object.hasOwn(schema, key) && !present.has(key),
+  );
   return [
     driftFinding(
-      report.missing.length > 0
-        ? `${ENV_EXAMPLE_PATH} does not declare ${report.missing.join(', ')}, declared by ${ENV_SCHEMA_EXPORT} in ${APP_CONFIG_FILE}`
-        : `${ENV_EXAMPLE_PATH} is no longer the projection of ${ENV_SCHEMA_EXPORT} — a description, a default or the required flag has moved`,
+      missing.length > 0
+        ? `${ENV_EXAMPLE_PATH} does not declare ${missing.join(', ')}, declared by ${ENV_SCHEMA_EXPORT} in ${APP_CONFIG_FILE}`
+        : owed.length > 0
+          ? `${ENV_EXAMPLE_PATH} does not declare ${owed.join(', ')}, which the framework refuses to boot without outside development/test`
+          : `${ENV_EXAMPLE_PATH} is no longer the projection of ${ENV_SCHEMA_EXPORT} — a description, a default or the required flag has moved`,
     ),
   ];
 }

package/src/app-load.ts

@@ -3,12 +3,12 @@
 // `registerQueries` / `registerRoute` name the rest — so `x manifest`, `x routes` and `x verify`
 // read exactly the tables the running server reads.
 
-// Bun ships no `Bun.*` path API: `relative`/`sep` turn an absolute scan hit into the app-root-
-// relative POSIX path every finding and every manifest fact is keyed by.
-import { join, relative, resolve, sep } from 'node:path';
+// Bun ships no `Bun.*` path API: `join`/`resolve` reach the files a scan imports.
+import { join, resolve } from 'node:path';
 import { isAction, isMutator, listActions, registerActions } from '@ultimat3/action';
 import { describeEntities, registeredEntities } from '@ultimat3/entity';
-import { localeConfig } from '@ultimat3/i18n';
+import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
+import { appLocaleSet, UNDECLARED_LOCALES } from '@ultimat3/i18n/app-catalogs';
 import { isJobHandle, isTaskHandle, registeredJobs, registeredTasks } from '@ultimat3/jobs';
 import type { ErrorCodeFact } from '@ultimat3/manifest';
 import { isQuery, listQueries, registerQueries } from '@ultimat3/query';
@@ -40,6 +40,7 @@ import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { hasPathSegment } from './path-segments';
+import { posixRelative, toPosix } from './posix-path';
 import { siteAssetTable } from './site-assets';
 import { isTest } from './source-files';
 
@@ -83,13 +84,13 @@ export interface LoadedApp {
   /** Every `X_*` code the app's source declares, by code — the one fact no registry holds. */
   readonly errorCodes: readonly ErrorCodeFact[];
   /**
-   * The locale the app falls back to. `packages/i18n/src/index.ts` is inside the import loop, and
-   * `defineCatalogs()` configures `@ultimat3/i18n` on its way through — so this is the framework's
-   * own answer, read back from `localeConfig()`, and never a regex over the app's source, which
-   * only ever matched the one `defineCatalogs({ default: '…' })` spelling it anticipated. An app
-   * whose i18n module would not import leaves the framework default (`en`) and a finding saying so.
+   * The app's locales, default first — `@ultimat3/i18n`'s `appLocaleSet`, the ONE reader of
+   * `defineCatalogs()`, asked once here so every step after the load reads one answer. Never
+   * `localeConfig()` read blind (it answers an earlier import's declaration for an app that made
+   * none) and never a regex over the source. An app with no catalogs, or whose catalog module would
+   * not import (the scan's finding already says so), is `UNDECLARED_LOCALES`.
    */
-  readonly defaultLocale: string;
+  readonly locales: AppLocaleSet;
   /** Modules that would not import, and primitives that would not register. */
   readonly findings: readonly Finding[];
 }
@@ -121,6 +122,17 @@ export function resetAppLoad(): void {
   resetReloadGraph();
 }
 
+/**
+ * One glob's hits in code-unit order of their POSIX spelling — never the host's. Sorted raw, `\`
+ * (0x5C) sorts after a digit or a capital where `/` (0x2F) sorts before one, so Windows imported
+ * `app/a1/page.tsx` before `app/a/page.tsx` and Linux after: one app, two cascades.
+ */
+export function sortModulePaths(paths: readonly string[]): string[] {
+  const keyed = paths.map((path) => ({ path, key: toPosix(path) }));
+  keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  return keyed.map((one) => one.path);
+}
+
 /**
  * Every module path the app globs match, SORTED — with the API index first. `Bun.Glob` answers in
  * directory order, which is the filesystem's — ext4 hashes names with a per-filesystem seed — so
@@ -144,7 +156,7 @@ export async function appModulePaths(root: string): Promise<readonly string[]> {
       if (!seen.has(absolute)) matched.push(absolute);
       seen.add(absolute);
     }
-    found.push(...matched.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)));
+    found.push(...sortModulePaths(matched));
   }
   // Resolved, like the glob's own answers: `loadApp('.')` is a legal call.
   const index = resolve(root, API_INDEX);
@@ -196,7 +208,7 @@ export async function scanAppModules(root: string, options: ScanOptions): Promis
     // file it holds, so this loop imported none of them and the app registered nothing.
     // The ROOT-RELATIVE path is tested, never the absolute one: an app checked out under
     // `~/work/my.test.app` matched `.test.` on every file and loaded none of them.
-    const file = relative(root, absolute).split(sep).join('/');
+    const file = posixRelative(root, absolute);
     if (hasPathSegment(absolute, 'node_modules') || isTest(file)) continue;
     if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
       continue;
@@ -249,16 +261,28 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   ) {
     findings.push(emptyAppFinding(root));
   }
-  // Read after the loop, never before it: `configureLocales` runs on the app's own import.
   return {
     root,
     files: scan.files,
     errorCodes: await appErrorCodes(root),
-    defaultLocale: localeConfig().fallback,
+    locales: await loadedLocales(root),
     findings,
   };
 }
 
+/**
+ * After the scan, never before it: the scan imported the catalog module, so the set it exports is
+ * what `loadAppCatalogs` recognises. A module that would not import is the scan's finding, not a
+ * second one here.
+ */
+async function loadedLocales(root: string): Promise<AppLocaleSet> {
+  try {
+    return await appLocaleSet(root);
+  } catch {
+    return UNDECLARED_LOCALES;
+  }
+}
+
 /** No primitive in any registry this scan fills — a process that registered some itself is not empty. */
 const registersNothing = (): boolean =>
   listActions().length === 0 &&

package/src/app-manifest.ts

@@ -21,7 +21,7 @@ import {
 import { knownPermissions } from '@ultimat3/policy';
 import { describeQueries } from '@ultimat3/query';
 import type { RouteDescriptor } from '@ultimat3/render';
-import { describeRoutes } from '@ultimat3/render';
+import { describePages } from '@ultimat3/render';
 import { loadApp } from './app-load';
 import { AppPackageInvalidError } from './errors';
 import type { Finding } from './output';
@@ -105,7 +105,7 @@ type UrlRoute = RouteDescriptor & { readonly surface: 'site' | 'app' | 'api' };
 const hasUrl = (route: RouteDescriptor): route is UrlRoute => route.surface !== 'shared';
 
 const routeFacts = (): readonly RouteFact[] =>
-  describeRoutes()
+  describePages()
     .filter(hasUrl)
     .map((route) => ({
       url: route.path,
@@ -117,14 +117,8 @@ const routeFacts = (): readonly RouteFact[] =>
       ...budgetOf(route),
     }));
 
-function budgetOf(route: RouteDescriptor): { budget?: { js?: string; lcp?: number } } {
-  if (route.budgetJs === null && route.budgetLcp === null) return {};
-  return {
-    budget: {
-      ...(route.budgetJs === null ? {} : { js: route.budgetJs }),
-      ...(route.budgetLcp === null ? {} : { lcp: route.budgetLcp }),
-    },
-  };
+function budgetOf(route: RouteDescriptor): { budget?: { js: string } } {
+  return route.budgetJs === null ? {} : { budget: { js: route.budgetJs } };
 }
 
 /**

package/src/app-mcp.ts

@@ -1,27 +1,26 @@
 // The app's own MCP endpoint, mounted by the web role. `defineAppMcp` built `mcp.route` — a
 // `POST` handler with token auth and per-class rate limits — and `app.config.ts` declared
-// `ai: { mcp: { expose: true, path: '/mcp' } }` by DEFAULT, and nothing between the two served it:
+// `ai: { mcp: { expose: true } }` by DEFAULT, and nothing between the two served it:
 // neither `x dev` nor `runRole` mounted the route, so `POST /mcp` answered `X_ROUTE_NOT_FOUND` in
 // every app ever scaffolded (measured 2026-09-05). The contract is one file: `apps/<app>/mcp.ts`
 // exports `mcp` — one `AppMcp`, or an array of them, one per population (customers, staff,
-// affiliates) — this module finds it, and both boots mount what it carries: endpoint #0 at
-// `ai.mcp.path`, every other at its own `defineAppMcp({ path })`.
+// affiliates) — this module finds it, and both boots mount what it carries: EVERY endpoint at its
+// own `defineAppMcp({ path })`, the one path its RFC 9728 metadata and its 401 also name.
 
 // why: a directory's existence — `Bun.file().exists()` answers for files, and `apps/` is a directory.
 import { existsSync } from 'node:fs';
-// why: Bun exposes no path-join primitive; the config file and each candidate are joined to root.
+// why: Bun exposes no path-join primitive; each candidate is joined to root.
 import { join } from 'node:path';
 import { logger } from '@ultimat3/core';
 import type { Route } from '@ultimat3/http';
-import { json, selfOrigin } from '@ultimat3/http';
+import { jsonResponse, selfOrigin } from '@ultimat3/http';
 import {
   type AppMcp,
   McpAppUnmountedError,
   McpPathDuplicateError,
   PROTECTED_RESOURCE_WELL_KNOWN,
 } from '@ultimat3/mcp';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 
 /** The one file an app writes, per app directory. */
 export const APP_MCP_GLOB = 'apps/*/mcp.ts';
@@ -37,7 +36,7 @@ export const APP_MCP_ROUTE_NAME = 'mcp';
 export interface AppMcpMount {
   /** `[]` when `expose` is false, when nothing exports `mcp`, or when no endpoint has a route. */
   readonly routes: readonly Route[];
-  /** Endpoint #0's `POST <path>` when mounted, else `null` — the default, at `ai.mcp.path`. */
+  /** Endpoint #0's `POST <path>` when mounted, else `null` — the default endpoint. */
   readonly path: string | null;
   /** Every mounted endpoint's `POST <path>`, in export order — the boot line prints one each. */
   readonly paths: readonly string[];
@@ -49,34 +48,19 @@ export interface AppMcpMount {
   readonly warning: McpAppUnmountedError | undefined;
 }
 
-interface ExposeDeclaration {
-  readonly expose: boolean;
-  readonly path: string;
-}
-
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null;
 
 /**
- * `config.ai.mcp`, off the app's own resolved config — the exported `config` is what
- * `defineConfig` returned, so both keys are present and defaulted. Read the same way
- * `loadSignInPath` reads `auth.signInPath`: the config file is imported, never re-parsed.
- * An app with no config file has nothing exposed and nothing to warn about.
+ * `defineAppMcp`'s own default — `mcp/src/transport-http.ts`, `input.path ?? '/mcp'` — named here
+ * ONLY in a warning about an endpoint that has no route and so no resolved path. It never decides
+ * where anything mounts: a mounted endpoint's path is `route.path`.
  */
-async function exposeDeclaration(root: string): Promise<ExposeDeclaration | undefined> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return undefined;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config) || !isRecord(config['ai']) || !isRecord(config['ai']['mcp'])) {
-    return undefined;
-  }
-  const mcp = config['ai']['mcp'];
-  const path = mcp['path'];
-  return {
-    expose: mcp['expose'] === true,
-    path: typeof path === 'string' && path.startsWith('/') ? path : '/mcp',
-  };
+const UNROUTED_MCP_PATH = '/mcp';
+
+/** `config.ai.mcp.expose` off the one loader (`app-config-load.ts`); false with no config file. */
+async function exposed(root: string): Promise<boolean> {
+  return (await loadAppConfig(root))?.ai.mcp.expose ?? false;
 }
 
 const isAppMcp = (value: unknown): value is AppMcp =>
@@ -112,21 +96,20 @@ const NOTHING: AppMcpMount = { routes: [], path: null, paths: [], warning: undef
  * does not have and answer 401 before the token was ever read.
  */
 export async function appMcpMount(root: string): Promise<AppMcpMount> {
-  const declared = await exposeDeclaration(root);
-  if (declared === undefined || !declared.expose) return NOTHING;
+  if (!(await exposed(root))) return NOTHING;
   const files = await candidates(root);
   const fallbackFile = 'apps/web/mcp.ts';
   for (const file of files) {
     const module = (await import(join(root, file))) as Record<string, unknown>;
     const endpoints = endpointsOf(module[APP_MCP_EXPORT]);
     if (endpoints === undefined) continue;
-    return mountEndpoints(endpoints, declared.path, file);
+    return mountEndpoints(endpoints, file);
   }
   return {
     ...NOTHING,
     warning: new McpAppUnmountedError({
       reason: 'missing',
-      path: declared.path,
+      path: UNROUTED_MCP_PATH,
       file: files[0] ?? fallbackFile,
     }),
   };
@@ -137,11 +120,7 @@ export async function appMcpMount(root: string): Promise<AppMcpMount> {
  * route: it is skipped and the FIRST such is the warning, so one unfinished population never takes
  * the others down with it. Two endpoints on one route is thrown — see `McpPathDuplicateError`.
  */
-function mountEndpoints(
-  endpoints: readonly AppMcp[],
-  defaultPath: string,
-  file: string,
-): AppMcpMount {
+function mountEndpoints(endpoints: readonly AppMcp[], file: string): AppMcpMount {
   const routes: Route[] = [];
   const paths: string[] = [];
   const claimed = new Map<string, number>();
@@ -151,13 +130,15 @@ function mountEndpoints(
     if (route === undefined) {
       warning ??= new McpAppUnmountedError({
         reason: 'no-route',
-        path: defaultPath,
+        path: UNROUTED_MCP_PATH,
         file,
         ...(index === 0 ? {} : { endpoint: index }),
       });
       return;
     }
-    const path = index === 0 ? defaultPath : route.path;
+    // The descriptor's own path — the one its metadata, its `resourceUrl` and its 401 were built
+    // over. A mount path from anywhere else is a resource advertised where nothing answers.
+    const path = route.path;
     for (const mounted of endpointRoutes(route, path, index)) {
       const key = `${mounted.method} ${mounted.path}`;
       const first = claimed.get(key);
@@ -174,8 +155,7 @@ function mountEndpoints(
     }
     paths.push(path);
   });
-  const path = endpoints[0]?.route === undefined ? null : defaultPath;
-  return { routes, path, paths, warning };
+  return { routes, path: endpoints[0]?.route?.path ?? null, paths, warning };
 }
 
 type Descriptor = NonNullable<AppMcp['route']>;
@@ -197,7 +177,7 @@ function endpointRoutes(route: Descriptor, path: string, index: number): readonl
               method: 'GET',
               path: metadataPath,
               handler: (_request, ctx) => {
-                const response = json(resource.document(selfOrigin(ctx.url, ctx.https)));
+                const response = jsonResponse(resource.document(selfOrigin(ctx.url, ctx.https)));
                 // A browser-hosted MCP client reads this cross-origin; it holds nothing secret.
                 response.headers.set('access-control-allow-origin', '*');
                 response.headers.set('cache-control', 'public, max-age=3600');
@@ -213,8 +193,13 @@ function endpointRoutes(route: Descriptor, path: string, index: number): readonl
       // The PUBLIC origin, as the pipeline resolved it (`ctx.https` honours a trusted proxy's
       // `x-forwarded-proto`): behind a TLS-terminating ingress the raw request URL is `http://`
       // on an internal host, and a `resource_metadata` naming that is a URL no client can reach.
+      // The client ADDRESS likewise: failed tokens are metered per address, and the descriptor
+      // has no other way to learn it.
       handler: (request, ctx) =>
-        route.handle(request.raw, { origin: selfOrigin(ctx.url, ctx.https) }),
+        route.handle(request.raw, {
+          origin: selfOrigin(ctx.url, ctx.https),
+          address: ctx.ip ?? undefined,
+        }),
       meta: { name, auth: 'public', enforcedBy: 'handler' },
     },
     ...metadata,

package/src/app-name.ts

@@ -0,0 +1,52 @@
+// `x new <name>`'s last refusal before a byte lands: the slug must be a name core's `defineConfig`
+// accepts, because it is written verbatim as `app.config.ts`'s `name:` and spelled into every
+// identifier the scaffold derives (`<app>Seed`). The rule is asked of core, never restated here.
+
+import { defineConfig, isUltimateError, renderThrowable, UltimateError } from '@ultimat3/core';
+
+/**
+ * Why core's own config validator refuses `name`, in core's words, or `undefined` when it accepts
+ * it — asked by building the one config that name would scaffold, every other field defaulted. A
+ * copy of core's pattern here would be a second answer to "what is an app name", and the day one
+ * of them moved `x new` would again write an app whose `app.config.ts` throws at its own import.
+ */
+export function appNameIssue(name: string): string | undefined {
+  try {
+    defineConfig({ name });
+    return undefined;
+  } catch (error) {
+    return isUltimateError(error) ? error.cause : renderThrowable(error);
+  }
+}
+
+/** The bound the suggestion trims an over-long slug to — re-proved by `appNameIssue`, not trusted. */
+const MAX_LENGTH = 64;
+
+/**
+ * A slug core accepts, as close to `slug` as one edit gets: a leading digit gains an `app-` prefix
+ * (an identifier cannot start with one either), a one-letter name an `-app` suffix, and an
+ * over-long one is cut at the bound. `undefined` when none of those land on a valid name.
+ */
+export function suggestAppName(slug: string): string | undefined {
+  let candidate = /^[0-9]/.test(slug) ? `app-${slug}` : slug;
+  if (candidate.length < 2) candidate = `${candidate}-app`;
+  candidate = candidate.slice(0, MAX_LENGTH).replace(/-+$/, '');
+  return appNameIssue(candidate) === undefined ? candidate : undefined;
+}
+
+/** `x new 9lives`, `x new a`: a slug core's `defineConfig` would refuse at the app's first boot. */
+export class AppNameInvalidError extends UltimateError {
+  constructor(input: {
+    name: string;
+    slug: string;
+    issue: string;
+    invocation: string;
+    flags: readonly string[];
+  }) {
+    super({
+      code: 'X_CLI_BAD_FLAG',
+      cause: `"${input.name}" scaffolds the app name "${input.slug}", which app.config.ts's defineConfig refuses: ${input.issue}`,
+      fix: [input.invocation, suggestAppName(input.slug) ?? '<name>', ...input.flags].join(' '),
+    });
+  }
+}

package/src/app-permissions-borrowed.ts

@@ -0,0 +1,123 @@
+// The `policy` step's provenance question: every permission the app's OWN actions, queries and
+// routes require is one the app ITSELF declares. `defineAdmin()` declares `<entity>:read|write|
+// delete` for every mounted entity, so an app rule naming one passed in the web process and threw
+// X_PERMISSION_UNKNOWN in any process that never mounted the admin — with nothing saying so.
+
+import { listActions } from '@ultimat3/action';
+import { type Policy, permissionDeclarationSites, policyPermissions } from '@ultimat3/policy';
+import { listQueries } from '@ultimat3/query';
+import { routeEntries } from '@ultimat3/render';
+import { frameFile, rootRelative, siteFile } from './app-permissions-site';
+import type { Finding } from './output';
+
+/** One permission one app declaration requires. */
+export interface AppRule {
+  readonly permission: string;
+  /** `action createPost`, `query postList`, or the route file. */
+  readonly by: string;
+}
+
+/** An app rule whose permission no app module declares, and the file that did declare it. */
+export interface BorrowedPermission extends AppRule {
+  /**
+   * Root-relative paths of EVERY declaring module (`node_modules/…` or `../…`), distinct and
+   * sorted: naming only the first told the reader one package declared it when two did.
+   */
+  readonly from: readonly string[];
+}
+
+/**
+ * EVERY permission in each tree, composites included — unlike the grant question, which judges
+ * only a bare `can()`: an `or()` branch is still a `can()` that asserted its name, so it needs the
+ * app's own declaration as much as a bare one does. A screen the admin MOUNTS is not here: those
+ * are the package's rules, and declaring their names is the package's job.
+ */
+export function appRules(): readonly AppRule[] {
+  const named = (by: string, policy: Policy<unknown, unknown>): readonly AppRule[] =>
+    policyPermissions(policy).map((permission) => ({ permission, by }));
+  return [
+    ...listActions().flatMap((target) => named(`action ${target.name}`, target.policy)),
+    ...listQueries().flatMap((target) => named(`query ${target.name}`, target.policy)),
+    ...routeEntries().flatMap((entry) => {
+      const permission = entry.config.policy?.permission;
+      return permission === undefined ? [] : [{ permission, by: entry.file }];
+    }),
+  ];
+}
+
+/** An app module's root-relative path, or `undefined` for a dependency's or an unreadable frame. */
+const appFile = (root: string, site: string): string | undefined => {
+  const file = siteFile(root, site);
+  return file === undefined || file.split('/').includes('node_modules') ? undefined : file;
+};
+
+/**
+ * Provenance by the declaring module's PATH, which is where the call ran — never by the name's
+ * shape: `posts:read` is the same string whether `defineAdmin()` or the app declared it. A name
+ * with any unreadable site is one whose origin nobody can state, so it is not judged — and that
+ * covers an UNKNOWN name too, which has no site at all: it is X_PERMISSION_UNKNOWN's, asked first,
+ * and a second finding would be a second instruction for one fault.
+ */
+export function borrowedPermissions(
+  root: string,
+  rules: readonly AppRule[] = appRules(),
+  declaredAt: Readonly<Record<string, readonly string[]>> = permissionDeclarationSites(),
+): readonly BorrowedPermission[] {
+  const found = new Map<string, BorrowedPermission>();
+  for (const rule of rules) {
+    const sites = Object.hasOwn(declaredAt, rule.permission) ? declaredAt[rule.permission] : [];
+    const files = (sites ?? []).map(frameFile);
+    if (files.length === 0 || files.some((file) => file === undefined)) continue;
+    if ((sites ?? []).some((site) => appFile(root, site) !== undefined)) continue;
+    const from = [
+      ...new Set(files.flatMap((file) => (file === undefined ? [] : [rootRelative(root, file)]))),
+    ].sort();
+    found.set(`${rule.permission}\u0000${rule.by}`, { ...rule, from });
+  }
+  return [...found.values()].sort((a, b) =>
+    a.permission === b.permission
+      ? a.by.localeCompare(b.by)
+      : a.permission.localeCompare(b.permission),
+  );
+}
+
+/**
+ * The app file its permissions are declared in — where the missing name is added. Read off the
+ * recorded sites, never a scaffold path; none under the root is `undefined`, never a guess.
+ */
+export function permissionsFile(root: string): string | undefined {
+  for (const sites of Object.values(permissionDeclarationSites())) {
+    for (const site of sites) {
+      const file = appFile(root, site);
+      if (file !== undefined) return file;
+    }
+  }
+  return undefined;
+}
+
+/** A TS string literal for the name — quoted the house way unless the name itself needs escaping. */
+const literal = (name: string): string =>
+  /^[\w:.*-]+$/.test(name) ? `'${name}'` : JSON.stringify(name);
+
+export function borrowedFinding(
+  entry: BorrowedPermission,
+  declaredIn: string | undefined,
+): Finding {
+  const [only, ...more] = entry.from;
+  const declarers =
+    more.length === 0 ? `only ${only} declares it` : `only ${entry.from.join(', ')} declare it`;
+  const where =
+    declaredIn === undefined
+      ? 'paste this call into an app module'
+      : `paste this call into ${declaredIn} (definePermissions() merges, so a second call is fine)`;
+  const finding: Finding = {
+    code: 'X_PERMISSION_BORROWED',
+    cause:
+      `${entry.by} requires ${literal(entry.permission)}, and ${declarers} — no app module does, ` +
+      "so the rule holds only in a process that ran that package's declaration (defineAdmin()) " +
+      `first; ${where}, then x verify --only policy`,
+    // A call to paste, never prose: `add …` read as a command answered `add: command not found`.
+    fix: `definePermissions([${literal(entry.permission)}])`,
+  };
+  return declaredIn === undefined ? finding : { ...finding, at: declaredIn };
+}