@ultimat3/cli 9.0.0 → 11.0.0

package/src/error-codes.ts

@@ -1,5 +1,5 @@
 // The X_* codes owned by @ultimat3/cli, and nothing else: the two lists, their titles, the one
-// registration call and `docsFor`. Every code names the exact command that resolves it, because
+// registration call. Every code names the exact command that resolves it, because
 // the CLI is the surface an agent reads first — a failure here has to be actionable without a doc
 // lookup or a second round-trip. The classes that throw these codes live in `./errors`.
 import { registerErrorCodes } from '@ultimat3/core';
@@ -21,6 +21,9 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_JOB_UNKNOWN',
   'X_FIX_TARGET_UNKNOWN',
   'X_ERROR_FIX_INVALID',
+  // The second half of the same contract: X_ERROR_FIX_INVALID means the fix is not an instruction,
+  // this one means it is one and cites a file that is not there. Two conditions, two repairs.
+  'X_ERROR_FIX_PATH_MISSING',
   'X_ERROR_CODE_UNDOCUMENTED',
   'X_ERROR_CODE_UNREGISTERED',
   // Reported as `Finding`s rather than thrown, and unregistered until now because of it — so
@@ -46,6 +49,11 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_STORAGE_SECRET_DEV',
   'X_MANIFEST_STALE',
   'X_BUDGET_UNMEASURED',
+  // The other half of #271, and the half no runtime can raise: a route reads a live hook and boots
+  // no module in a browser, so its rows have nowhere to arrive and the page renders its loading
+  // branch forever, at 200. Only this package can see it — `@ultimat3/realtime` cannot see a route
+  // and `@ultimat3/render` may not import realtime.
+  'X_LIVE_ROUTE_NO_ISLAND',
   'X_BUILD_FAILED',
   'X_BUILD_ENTRY_MISSING',
   'X_DEPLOY_FAILED',
@@ -160,6 +168,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_JOB_UNKNOWN: 'the queue holds no job with this id',
   X_FIX_TARGET_UNKNOWN: 'the named file is not one of the app source files',
   X_ERROR_FIX_INVALID: "an error's fix line is not a runnable instruction",
+  X_ERROR_FIX_PATH_MISSING: "an error's fix line cites a file this repository does not have",
   X_ERROR_CODE_UNDOCUMENTED: 'a shipped error code has no row in the error reference',
   X_ERROR_CODE_UNREGISTERED: 'the error reference documents a code no package registers',
   X_STORAGE_UNWRITABLE: 'the storage disk this process needs cannot be written to',
@@ -175,6 +184,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_RELEASE_VERSION_SKEW: 'a workspace is not at the lockstep version',
   X_MANIFEST_STALE: 'openapi.json is stale',
   X_BUDGET_UNMEASURED: 'a route declares a budget the build never measured',
+  X_LIVE_ROUTE_NO_ISLAND: 'a route reads live rows and boots nothing that could receive them',
   X_BUILD_FAILED: 'x build failed',
   X_BUILD_ENTRY_MISSING: "the build target's entry file is not in the app",
   X_DEPLOY_FAILED: 'a deploy step failed',
@@ -217,4 +227,11 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(CLI_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-export const docsFor = (code: CliErrorCode): string => `https://ultimate.dev/errors/${code}`;
+// This file exports NO `docsFor(code)`, and adding one back is the defect. A CLI error passes no
+// `docs:` at all — `UltimateError` fills it from `describeErrorCode(code).docs`, which is
+// `@ultimat3/core`'s `ERROR_DOCS_URL`: one page for every code, never one per code, because `wiki/`
+// is the framework's only public documentation surface and a code lives there in a TABLE ROW, which
+// has no anchor. A `Finding` is a plain object with no constructor to fill it, so it carries
+// `ERROR_DOCS_URL` imported from core — the same constant, not a second copy of it. The
+// `https://ultimate.dev/errors/<code>` links `docsFor` built until 9.x answered 404, host included,
+// on every error the CLI has ever thrown.

package/src/error-contract.ts

@@ -6,9 +6,10 @@
 
 // `join` is `node:`-only by necessity: Bun exposes no path-join primitive.
 import { join } from 'node:path';
-import { docsFor } from './error-codes';
+import { ERROR_DOCS_URL } from '@ultimat3/core';
 import { citedCommandProblem, loadCommandCatalog } from './fix-command';
 import { createHelperResolver } from './fix-imports';
+import { citedPathProblem, FILE_TOKEN_PATTERN } from './fix-path';
 import { scanFixSites } from './fix-scan';
 import type { Finding } from './output';
 import { eachSourceFile, isGenerated, isTest } from './source-files';
@@ -38,7 +39,9 @@ export const COMMAND_TOKENS: readonly RegExp[] = [
   /(?:^|[\s;|&("'`])x\s+[a-z][a-z-]*/,
   /\b(?:bun|bunx|npm|npx|node|git|docker|kubectl|helm|psql|curl|openssl|biome|tsc)\b/,
   /\b[A-Za-z_$][\w$]*\(/,
-  /[\w.@-]*\/[\w.@-]+\.(?:ts|tsx|js|json|md|toml|yaml|yml|css|scss|sql)\b/,
+  // Built from `fix-path.ts`'s extension list, because the token that makes a fix count as an
+  // instruction is exactly the token `citedPathProblem` then has to resolve.
+  new RegExp(FILE_TOKEN_PATTERN),
   /\b(?:app\.config\.ts|package\.json|tsconfig\.json|bunfig\.toml|\.env(?:\.[\w.-]+)?)\b/,
 ];
 
@@ -63,7 +66,20 @@ const fixFinding = (site: FixSite, problem: string): Finding => ({
   code: 'X_ERROR_FIX_INVALID',
   cause: problem,
   fix: `rewrite the fix at ${site.at}:${site.line} as a command to run, a call to paste, or an edit naming a file`,
-  docs: docsFor('X_ERROR_FIX_INVALID'),
+  docs: ERROR_DOCS_URL,
+  at: `${site.at}:${site.line}`,
+});
+
+/**
+ * Its own code, not `X_ERROR_FIX_INVALID`: that one means the fix is not an instruction, and this
+ * one means it IS one and points at nothing. The repairs are different — rewrite the sentence
+ * versus correct the path — and one code for both would hand two readers the same wrong edit.
+ */
+const pathFinding = (site: FixSite, problem: string): Finding => ({
+  code: 'X_ERROR_FIX_PATH_MISSING',
+  cause: `the fix at ${site.at}:${site.line} ${problem}`,
+  fix: `correct the path in the fix at ${site.at}:${site.line} to one this repo holds, or create the file it names`,
+  docs: ERROR_DOCS_URL,
   at: `${site.at}:${site.line}`,
 });
 
@@ -110,7 +126,14 @@ export async function checkErrorFixReport(root: string): Promise<ErrorFixReport>
       // resolve, and reading `<value>` as one would be a finding nobody can act on.
       const fix = staticFix(site.fix);
       const problem = fixProblem(site.fix) ?? citedCommandProblem(fix, catalog);
-      if (problem !== undefined) findings.push(fixFinding(site, problem));
+      if (problem !== undefined) {
+        findings.push(fixFinding(site, problem));
+        continue;
+      }
+      // Third rule, and the one nothing resolved: a fix that names a file this repo does not have.
+      // Reported only where the first two hold — a line already being rewritten needs one finding.
+      const missing = await citedPathProblem(fix, root);
+      if (missing !== undefined) findings.push(pathFinding(site, missing));
     }
   }
   return { findings, checked, unreadable };
@@ -132,7 +155,7 @@ const undocumentedFinding = (code: string, at: string, line: number, page: strin
   code: 'X_ERROR_CODE_UNDOCUMENTED',
   cause: `${code} is declared at ${at}:${line} and ${page} has no entry for it`,
   fix: `add a row for ${code} to ${page}, with its cause and the command that fixes it`,
-  docs: docsFor('X_ERROR_CODE_UNDOCUMENTED'),
+  docs: ERROR_DOCS_URL,
   at: page,
 });
 
@@ -163,7 +186,7 @@ const unregisteredFinding = (code: string, page: string): Finding => ({
   code: 'X_ERROR_CODE_UNREGISTERED',
   cause: `${page} documents ${code} as a live code and nothing registers it, so "x errors explain ${code}" refuses a code this page promises`,
   fix: `register ${code} through registerErrorCodes() in its package's src/errors.ts, or move its row under "${RESERVED_HEADING}" in ${page}`,
-  docs: docsFor('X_ERROR_CODE_UNREGISTERED'),
+  docs: ERROR_DOCS_URL,
   at: page,
 });
 
@@ -249,7 +272,7 @@ export async function checkErrorCodeDocs(root: string, page: string): Promise<re
         code: 'X_ERROR_CODE_UNDOCUMENTED',
         cause: `the error reference ${page} does not exist, so no code can be documented`,
         fix: `create ${page} with a row per X_* code, or stop naming it as the error reference`,
-        docs: docsFor('X_ERROR_CODE_UNDOCUMENTED'),
+        docs: ERROR_DOCS_URL,
         at: page,
       },
     ];

package/src/error-pages.ts

@@ -0,0 +1,79 @@
+// The app's own error page, which only a process with a disk can find: `@ultimat3/http` renders the
+// framework's and declares the seam, this file is the half that reads a file. Rails' `public/404.html`,
+// one directory further in — `apps/web/site/` is already where an app's public files live, which is
+// where `favicon.ico` is overridden too.
+
+// why: Bun exposes no path-join primitive, and the source path is app-root-relative — the same
+// necessity `favicon.ts` records for `FAVICON_SOURCE`.
+import { join } from 'node:path';
+import { renderErrorPage } from '@ultimat3/http';
+import { currentLocale } from '@ultimat3/i18n';
+
+/**
+ * One file per status, named by the status, and NO generic `error.html` beside it: a second rung
+ * would need a precedence rule, and a `{{status}}` slot would be a template language the framework
+ * does not otherwise have. An app that wants one page for three statuses writes three files.
+ */
+export const ERROR_PAGE_DIR = 'apps/web/site/errors';
+
+/** What `x verify`, a `fix:` and this reader all name — never spelled twice. */
+export const errorPageSource = (status: number): string =>
+  `${ERROR_PAGE_DIR}/${String(status)}.html`;
+
+/**
+ * What a static host serves for a path that matches no file. `404.html` at the export root is the
+ * convention S3, Cloudflare Pages, Netlify and nginx already look for, so the artifact needs no
+ * configuration to answer the way the served process does.
+ */
+export const STATIC_ERROR_PAGE = '404.html';
+
+/** A status a `Response` can carry. A number outside it never becomes a path. */
+const isStatus = (status: number): boolean =>
+  Number.isInteger(status) && status >= 100 && status <= 599;
+
+/**
+ * The app's page for one status, or `undefined`.
+ *
+ * Read per REQUEST, never cached at boot, for `favicon.ts`'s reason: `x dev` is a running process
+ * an author drops a file into, and a reader that captured "there was none" at startup would keep
+ * answering the framework's page until the server was restarted.
+ */
+export async function errorPageOverride(root: string, status: number): Promise<string | undefined> {
+  if (!isStatus(status)) return undefined;
+  const file = Bun.file(join(root, errorPageSource(status)));
+  return (await file.exists()) ? file.text() : undefined;
+}
+
+/**
+ * `ServerHooks.errorPage`, bound to one app root. Installed by `startWeb` so `x dev` and the
+ * container cannot answer a browser differently — the rule `assetRoutes` already holds for
+ * `/favicon.ico`.
+ */
+export const errorPageHook =
+  (root: string) =>
+  (status: number): Promise<string | undefined> =>
+    errorPageOverride(root, status);
+
+/**
+ * The document that goes into a static export: the app's file if it has one, the framework's page
+ * otherwise. Its own function because the export has no process to ask, exactly as `faviconBytes`
+ * is — a second rule for which page a static build carries would be an artifact that disagrees
+ * with the server it was built from.
+ *
+ * No request id and no pathname: nothing about this file is per-request, and the renderer omits
+ * both rather than inventing them.
+ */
+export async function errorPageDocument(root: string, status: number): Promise<string> {
+  const own = await errorPageOverride(root, status);
+  return (
+    own ??
+    renderErrorPage({
+      status,
+      // What the served 404 carries, so the artifact and the process name one code.
+      code: 'X_ROUTE_NOT_FOUND',
+      // The app's default, resolved after `loadApp` registered its catalogs — a build has no
+      // request to negotiate against.
+      locale: currentLocale(),
+    })
+  );
+}

package/src/errors.ts

@@ -2,7 +2,7 @@
 // that resolves it — the codes themselves, their titles and their registration are `./error-codes`,
 // so a package importing a class does not pull the table and vice versa.
 import { UltimateError } from '@ultimat3/core';
-import { docsFor } from './error-codes';
+import { quoteArg } from './shell-quote';
 
 /** An unknown command or subcommand. Carries a suggestion so the retry is one keystroke away. */
 export class UnknownCommandError extends UltimateError {
@@ -11,7 +11,6 @@ export class UnknownCommandError extends UltimateError {
       code: 'X_CLI_UNKNOWN_COMMAND',
       cause: `"x ${input.path}" is not a command (known: ${input.known.join(', ')})`,
       fix: input.suggestion === undefined ? 'x help' : `x ${input.suggestion}`,
-      docs: docsFor('X_CLI_UNKNOWN_COMMAND'),
     });
   }
 }
@@ -27,7 +26,6 @@ export class BadFlagError extends UltimateError {
       code: 'X_CLI_BAD_FLAG',
       cause: `--${input.flag} on "x ${input.command}": ${input.reason}`,
       fix: input.fix ?? `x ${input.command} --help`,
-      docs: docsFor('X_CLI_BAD_FLAG'),
     });
   }
 }
@@ -46,7 +44,30 @@ export class MissingPositionalError extends UltimateError {
       code: 'X_CLI_BAD_FLAG',
       cause: `"x ${input.command}" needs a <${input.positional}> positional and got none`,
       fix: input.example,
-      docs: docsFor('X_CLI_BAD_FLAG'),
+    });
+  }
+}
+
+/**
+ * `x new /srv/apps/shop` — a PATH where a NAME goes.
+ *
+ * `names()` slugifies whatever it is given, so the separators became hyphens and the whole path
+ * turned into ONE directory inside the cwd: `x new /tmp/probe/vision` wrote `tmp-probe-vision`
+ * into the current directory and `git init`-ed it there. Nothing failed, and the app the caller
+ * asked for did not exist.
+ *
+ * `--dir` is the flag that takes a path, so the two are one flag apart and the fix is the
+ * invocation the caller meant — built from what they typed, never a placeholder.
+ */
+export class AppNameIsPathError extends UltimateError {
+  constructor(input: { name: string; parent: string; base: string; invocation?: string }) {
+    // The invocation the caller typed, not the literal `x new`: the same command is the whole of
+    // `bunx create-ultimate`, which runs before `x` is installed.
+    const invocation = input.invocation ?? 'x new';
+    super({
+      code: 'X_CLI_BAD_FLAG',
+      cause: `"${invocation}" takes a NAME and got the path "${input.name}" — it would be slugified into one directory name`,
+      fix: `${invocation} ${quoteArg(input.base)} --dir ${quoteArg(input.parent)}`,
     });
   }
 }
@@ -70,7 +91,6 @@ export class MissingSubcommandError extends UltimateError {
       code: 'X_CLI_BAD_FLAG',
       cause: `"x ${input.command}" takes a subcommand and got none (one of: ${input.known.join(', ')})`,
       fix: `x help ${input.command}`,
-      docs: docsFor('X_CLI_BAD_FLAG'),
     });
   }
 }
@@ -82,7 +102,6 @@ export class VerifyFailedError extends UltimateError {
       code: 'X_VERIFY_FAILED',
       cause: `${input.failed.length} verify step(s) failed: ${input.failed.join(', ')}`,
       fix: 'x verify --json',
-      docs: docsFor('X_VERIFY_FAILED'),
     });
   }
 }
@@ -94,7 +113,6 @@ export class NotInAppError extends UltimateError {
       code: 'X_NOT_IN_APP',
       cause: `"x ${input.command}" must run inside an Ultimate app; no app.config.ts at or above ${input.from}`,
       fix: 'x new myapp && cd myapp',
-      docs: docsFor('X_NOT_IN_APP'),
     });
   }
 }
@@ -106,7 +124,6 @@ export class BunVersionError extends UltimateError {
       code: 'X_BUN_VERSION',
       cause: `Bun ${input.found} is older than the required ${input.required}`,
       fix: 'bun upgrade',
-      docs: docsFor('X_BUN_VERSION'),
     });
   }
 }
@@ -127,7 +144,6 @@ export class NoTestFilesError extends UltimateError {
       code: 'X_TEST_NO_FILES',
       cause: `no *.test.ts files${where} under ${input.root}`,
       fix: parts.length === 0 ? 'x test --json   # run it from the repo root' : 'x test',
-      docs: docsFor('X_TEST_NO_FILES'),
     });
   }
 }
@@ -146,7 +162,6 @@ export class ScaffoldPathEscapeError extends UltimateError {
       fix:
         input.fix ??
         `make the path relative to the app root with no ".." segment, then re-run: bun test packages/cli/src/scaffold-typecheck.contract.test.ts`,
-      docs: docsFor('X_SCAFFOLD_PATH_ESCAPE'),
     });
   }
 }
@@ -163,7 +178,6 @@ export class GenerateJsonInvalidError extends UltimateError {
       code: 'X_GENERATE_JSON_INVALID',
       cause: `${input.path} is declared merge: 'json' but the generator's own contents for it do not parse as a JSON object`,
       fix: `fix the template that emits ${input.path}, then re-run: bun test packages/cli/src/cmd-generate.test.ts`,
-      docs: docsFor('X_GENERATE_JSON_INVALID'),
     });
   }
 }
@@ -182,7 +196,6 @@ export class CatalogExistsError extends UltimateError {
       code: 'X_GENERATE_CONFLICT',
       cause: `${input.path} already exists`,
       fix: `x i18n sync ${input.locale}`,
-      docs: docsFor('X_GENERATE_CONFLICT'),
     });
   }
 }
@@ -198,7 +211,6 @@ export class AppPackageInvalidError extends UltimateError {
       code: 'X_APP_PACKAGE_INVALID',
       cause: `${input.path} ${input.problem}, so the manifest has no app name or version to gate on`,
       fix: 'bun pm pkg set name=my-app version=0.1.0',
-      docs: docsFor('X_APP_PACKAGE_INVALID'),
     });
   }
 }
@@ -216,7 +228,6 @@ export class ErrorCodeUnknownError extends UltimateError {
         input.suggestion === undefined
           ? 'x errors list --json'
           : `x errors explain ${input.suggestion}`,
-      docs: docsFor('X_ERROR_CODE_UNKNOWN'),
     });
   }
 }
@@ -243,7 +254,6 @@ export class DeclarationUnknownError extends UltimateError {
         input.suggestion === undefined
           ? `x ${input.kind} list --json`
           : `x ${input.kind} ${input.verb ?? 'describe'} ${input.suggestion}`,
-      docs: docsFor('X_DECLARATION_UNKNOWN'),
     });
   }
 }
@@ -255,7 +265,6 @@ export class JobUnknownError extends UltimateError {
       code: 'X_JOB_UNKNOWN',
       cause: `the "${input.driver}" queue holds no job with id "${input.id}"`,
       fix: 'x jobs ls --json',
-      docs: docsFor('X_JOB_UNKNOWN'),
     });
   }
 }
@@ -274,7 +283,6 @@ export class FixTargetUnknownError extends UltimateError {
         input.suggestion === undefined
           ? 'x routes --json   # every registered route file, app-root-relative'
           : `x fix boundary ${input.suggestion}`,
-      docs: docsFor('X_FIX_TARGET_UNKNOWN'),
     });
   }
 }
@@ -290,7 +298,6 @@ export class BuildEntryMissingError extends UltimateError {
       code: 'X_BUILD_ENTRY_MISSING',
       cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
       fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
-      docs: docsFor('X_BUILD_ENTRY_MISSING'),
     });
   }
 }
@@ -306,7 +313,6 @@ export class IslandBuildFailedError extends UltimateError {
       code: 'X_BUILD_FAILED',
       cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
       fix: `bun build --target browser ${input.file}`,
-      docs: docsFor('X_BUILD_FAILED'),
     });
   }
 }
@@ -321,7 +327,6 @@ export class RoleUnknownError extends UltimateError {
       code: 'X_ROLE_UNKNOWN',
       cause: `ROLE="${input.role}" is not a role (known: ${input.known.join(', ')})`,
       fix: `docker run -e ROLE=web my-app:latest   # one of: ${input.known.join(', ')}`,
-      docs: docsFor('X_ROLE_UNKNOWN'),
     });
   }
 }
@@ -344,7 +349,6 @@ export class RuntimeDriverSplitError extends UltimateError {
       // queues, and "they match" is exactly the reading that makes this bug invisible.
       cause: `an app module installed a ${input.driver} driver (ambient: "${input.ambient}") that is not the object this boot captured ("${input.captured}"), so enqueues and claims would use different queues`,
       fix: `pass the driver to the boot instead of installing it from an app module: runRole({ root, env, runtime: { ${input.driver}: yourDriver } })`,
-      docs: docsFor('X_RUNTIME_DRIVER_SPLIT'),
     });
   }
 }
@@ -362,7 +366,6 @@ export class PortInvalidError extends UltimateError {
       code: 'X_PORT_INVALID',
       cause: `${name}="${input.value}" is not a TCP port number between 0 and 65535`,
       fix: `docker run -e ${name}=${name === 'PORT' ? 3000 : 9090} my-app:latest`,
-      docs: docsFor('X_PORT_INVALID'),
     });
   }
 }
@@ -382,7 +385,6 @@ export class EnvSchemaMissingError extends UltimateError {
       code: 'X_CONFIG_INVALID',
       cause: `x env ${input.subcommand} needs the env declaration, and app.config.ts exports no "envSchema"`,
       fix: "add to app.config.ts: export const envSchema = { DATABASE_URL: { type: 'url', description: 'Postgres connection URL' } } satisfies EnvSchema; export const env = defineEnv(envSchema);",
-      docs: docsFor('X_CONFIG_INVALID'),
     });
   }
 }
@@ -394,7 +396,6 @@ export class CliNotImplementedError extends UltimateError {
       code: 'X_NOT_IMPLEMENTED',
       cause: `${input.feature} is not implemented in this build`,
       fix: input.fix,
-      docs: docsFor('X_NOT_IMPLEMENTED'),
     });
   }
 }
@@ -410,7 +411,7 @@ export class CliNotImplementedError extends UltimateError {
  */
 export class StorageUnwritableError extends UltimateError {
   constructor(cause: string, fix: string) {
-    super({ code: 'X_STORAGE_UNWRITABLE', cause, fix, docs: docsFor('X_STORAGE_UNWRITABLE') });
+    super({ code: 'X_STORAGE_UNWRITABLE', cause, fix });
   }
 }
 
@@ -435,7 +436,6 @@ export class LocalDiskUnsafeError extends UltimateError {
         `disk at ${input.root} — and with no STORAGE_SIGNING_SECRET it would sign upload grants ` +
         'with the development key published in @ultimat3/storage',
       fix: 'export S3_ENDPOINT=https://s3.example.com S3_BUCKET=my-app-uploads   # or keep the disk on a mounted volume: export STORAGE_SIGNING_SECRET="$(openssl rand -hex 32)"',
-      docs: docsFor('X_ENV_MISSING'),
     });
   }
 }
@@ -450,7 +450,6 @@ export class SecretsEditorMissingError extends UltimateError {
       code: 'X_SECRETS_EDITOR_MISSING',
       cause: `x secrets edit opens the decrypted secrets in an editor and none of ${input.vars.join(', ')} is set`,
       fix: 'EDITOR=nano x secrets edit',
-      docs: docsFor('X_SECRETS_EDITOR_MISSING'),
     });
   }
 }
@@ -466,7 +465,6 @@ export class SecretsEditFailedError extends UltimateError {
       code: 'X_SECRETS_EDIT_FAILED',
       cause: `"${input.editor}" exited ${input.code}, so the decrypted buffer was discarded and the committed secrets file was not rewritten`,
       fix: 'x secrets edit',
-      docs: docsFor('X_SECRETS_EDIT_FAILED'),
     });
   }
 }
@@ -483,7 +481,6 @@ export class SecretsExistsError extends UltimateError {
       code: 'X_GENERATE_CONFLICT',
       cause: `${input.path} already exists, and x secrets init would replace it`,
       fix: input.fix,
-      docs: docsFor('X_GENERATE_CONFLICT'),
     });
   }
 }

package/src/favicon.ts

@@ -0,0 +1,113 @@
+// `/favicon.ico`, which every browser requests unprompted and no Ultimate app answered: the
+// scaffold wrote no file and neither served surface mounted a route, so a permanent 404 sat in the
+// console of every app the framework produces. The app's own file wins; the framework answers when
+// there is none, so an app inherits a clean console rather than a file it has to remember to add.
+
+// why: Bun exposes no path-join primitive, and `FAVICON_SOURCE` is app-root-relative, so resolving
+// it against the root is string work no `Bun.file` overload does — the same necessity
+// `dev-assets.ts` records for `ICON_SOURCE`.
+import { join } from 'node:path';
+import { createRaster, encodeImage } from '@ultimat3/core';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders } from '@ultimat3/http';
+
+/** What a browser asks for with no `<link rel="icon">` to tell it otherwise. */
+export const FAVICON_PATH = '/favicon.ico';
+
+/**
+ * The one file an app overrides it with — beside `ICON_SOURCE`, in the same directory, because
+ * `apps/web/site/` is already where an app's public files live. One path, never a search order: a
+ * mechanism that accepted `favicon.png` too would be two ways to do one thing, and an app whose
+ * icon is not there would have to be told which of them won.
+ */
+export const FAVICON_SOURCE = 'apps/web/site/favicon.ico';
+
+/** 32px, which is what a browser tab and a bookmark bar both ask for. */
+const DEFAULT_SIZE = 32;
+
+/**
+ * Not a colour: one mid-grey LEVEL written to all three channels, exactly as
+ * `templates/scaffold-icon.ts` argues — `@ultimat3/ui` owns the colour roles and `cli -> ui` is a
+ * boundary error, so a placeholder here must claim no brand colour to begin with.
+ */
+const MARK_LEVEL = 128;
+const OPAQUE = 255;
+
+const FAVICON_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
+
+/**
+ * The framework's answer when the app declares none: a solid 32x32 PNG, encoded through
+ * `@ultimat3/core`'s own pipeline rather than shipped as an opaque blob — the same encoder
+ * `x new`'s icon goes through, so there is no second image format in the tree and no base64
+ * constant nobody can verify. Served as `image/png` under an `.ico` URL, which every browser reads
+ * by content type; a real ICO container would be a fourth format for one placeholder.
+ *
+ * Deliberately NOT derived from `ICON_SOURCE`: resizing the app's install icon needs
+ * `@ultimat3/pwa`'s pipeline and would make the answer depend on a file that may be missing, which
+ * is a third rung under a mechanism that has exactly two.
+ */
+export function defaultFavicon(): Uint8Array {
+  const raster = createRaster(DEFAULT_SIZE, DEFAULT_SIZE, 'favicon');
+  const { pixels } = raster;
+  for (let i = 0; i < pixels.length; i += 4) {
+    pixels[i] = MARK_LEVEL;
+    pixels[i + 1] = MARK_LEVEL;
+    pixels[i + 2] = MARK_LEVEL;
+    pixels[i + 3] = OPAQUE;
+  }
+  return encodeImage(raster, 'png');
+}
+
+/** Encoded once per process: the bytes are a pure function of two constants. */
+let builtin: Uint8Array | undefined;
+
+const builtinBytes = (): Uint8Array => {
+  builtin ??= defaultFavicon();
+  return builtin;
+};
+
+const iconResponse = (bytes: Uint8Array, contentType: string): Response =>
+  applyCacheHeaders(
+    // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
+    // `SharedArrayBuffer`, which `Response` does not accept — `dev-assets.ts`'s rule, verbatim.
+    new Response(new Uint8Array(bytes), { headers: { 'content-type': contentType } }),
+    FAVICON_CACHE,
+  );
+
+/** What a surface answers with, and what it says the bytes are. */
+export interface FaviconBytes {
+  readonly bytes: Uint8Array;
+  readonly contentType: string;
+}
+
+/**
+ * Read per REQUEST, never once at boot: `x dev` is a running process an author drops a favicon
+ * into, and a route that captured "there was no file" at startup would keep answering the
+ * placeholder until the server was restarted — the class of dev/prod difference this package's
+ * own header forbids.
+ *
+ * Its own function because the static export has no process to ask: `prerenderSite` writes these
+ * same bytes into the artifact, and a second rule for which favicon a static build carries would
+ * be a build whose tab icon differs from the server's.
+ */
+export async function faviconBytes(root: string): Promise<FaviconBytes> {
+  const own = Bun.file(join(root, FAVICON_SOURCE));
+  if (await own.exists()) return { bytes: await own.bytes(), contentType: 'image/x-icon' };
+  return { bytes: builtinBytes(), contentType: 'image/png' };
+}
+
+export async function faviconResponse(root: string): Promise<Response> {
+  const favicon = await faviconBytes(root);
+  return iconResponse(favicon.bytes, favicon.contentType);
+}
+
+/**
+ * Mounted through `assetRoutes`, so `x dev`, the container and every test that boots either get it
+ * from one place. Public by definition — a browser requests it before anyone has signed in.
+ */
+export const faviconRoute = (root: string): Route => ({
+  method: 'GET',
+  path: FAVICON_PATH,
+  meta: { name: 'assets.favicon', auth: 'public', cache: FAVICON_CACHE, tags: ['assets'] },
+  handler: async (_request: UltimateRequest): Promise<Response> => faviconResponse(root),
+});