@ultimat3/cli 1.0.0

package/src/templates/scaffold-app.ts

@@ -0,0 +1,320 @@
+// The `apps/*` half of what `x new` writes: the three surfaces of apps/web, the admin app that
+// already speaks MCP, and the mobile/desktop placeholders that exist so adding them later is not
+// a restructure. Every file here is real, typed and covered — no placeholder that fails to boot.
+
+import type { GeneratedFile, NameSet } from './naming';
+import { icon } from './scaffold-icon';
+
+const webPackage = (app: NameSet): string => `{
+  "name": "@${app.kebab}/web",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./*": "./*.ts",
+    "./*.tsx": "./*.tsx"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}
+`;
+
+// The ambient \`*.module.scss\` declaration is not reachable through an import, so a program that
+// only sees this app's files would report TS2307 on every stylesheet. Naming it in \`include\`
+// is what makes \`tsc -p apps/web\` agree with \`tsc -p .\`.
+const tsconfig = (): string => `{
+  "extends": "../../tsconfig.json",
+  "include": ["**/*.ts", "**/*.tsx", "../../types/scss.d.ts"]
+}
+`;
+
+const sitePage = (
+  app: NameSet,
+): string => `// The landing page. site/ is 0kb JS: static render, hydrate never, no framework script tag.
+import { t } from '@ultimat3/i18n';
+import { defineRoute } from '@ultimat3/render';
+import styles from './page.module.scss';
+
+export const config = defineRoute({
+  render: 'static',
+  hydrate: 'never',
+  offline: 'precache',
+  budget: { js: '0kb', lcp: 1500 },
+  meta: () => ({
+    title: t('site.home.title'),
+    description: t('site.home.description'),
+  }),
+});
+
+export function HomePage() {
+  return (
+    <main class={styles.hero}>
+      <h1>{t('site.home.title')}</h1>
+      <p>{t('site.home.description')}</p>
+      <a class={styles.cta} href="/dashboard">
+        {t('site.home.cta')}
+      </a>
+    </main>
+  );
+}
+
+export const appName = '${app.kebab}';
+`;
+
+const siteStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
+
+.hero {
+  display: grid;
+  gap: tokens.$space-4;
+  padding: tokens.$space-8;
+  background: tokens.$surface-base;
+  color: tokens.$text-primary;
+}
+
+.cta {
+  justify-self: start;
+  padding: tokens.$space-2 tokens.$space-4;
+  border-radius: tokens.$radius-md;
+  background: tokens.$accent-solid;
+  color: tokens.$accent-on-solid;
+}
+`;
+
+const sitePageTest = (): string => `import { expect, unitTest } from '@ultimat3/testing';
+import { config } from './page';
+
+unitTest('the landing page ships zero JS and declares metadata', async () => {
+  expect(config.render).toBe('static');
+  expect(config.hydrate).toBe('never');
+  expect(config.budget.js).toBe('0kb');
+  const meta = await config.meta({});
+  expect(meta.title ?? '').not.toBe('');
+});
+`;
+
+const dashboardPage =
+  (): string => `// The authed dashboard. app/ streams: a static shell is flushed instantly and the holes arrive
+// as their data resolves.
+
+import { t } from '@ultimat3/i18n';
+import { defineRoute } from '@ultimat3/render';
+import styles from './page.module.scss';
+
+export const config = defineRoute({
+  render: 'stream',
+  hydrate: 'visible',
+  offline: 'runtime',
+  // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
+  policy: { permission: 'dashboard:read' },
+  budget: { js: '60kb', lcp: 2500 },
+  meta: () => ({ title: t('app.dashboard.title'), description: t('app.dashboard.description') }),
+});
+
+export function DashboardPage() {
+  return (
+    <section class={styles.panel}>
+      <h1>{t('app.dashboard.title')}</h1>
+    </section>
+  );
+}
+`;
+
+const dashboardStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
+
+.panel {
+  padding: tokens.$space-6;
+  background: tokens.$surface-raised;
+  color: tokens.$text-primary;
+}
+`;
+
+const dashboardTest = (): string => `import { expect, unitTest } from '@ultimat3/testing';
+import { config } from './page';
+
+unitTest('the dashboard streams, requires a permission and has an offline strategy', () => {
+  expect(config.render).toBe('stream');
+  expect(config.policy?.permission).toBe('dashboard:read');
+  expect(config.offline).toBe('runtime');
+});
+`;
+
+const offlineFallback =
+  (): string => `// The offline fallback. Every app/ route with offline: 'runtime' falls back here, so a train
+// tunnel shows the product's own shell instead of the browser's error page.
+
+import { t } from '@ultimat3/i18n';
+import styles from './offline.module.scss';
+
+export function OfflineFallback() {
+  return (
+    <main class={styles.offline}>
+      <h1>{t('app.offline.title')}</h1>
+      <p>{t('app.offline.description')}</p>
+    </main>
+  );
+}
+`;
+
+const offlineStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
+
+.offline {
+  display: grid;
+  gap: tokens.$space-3;
+  padding: tokens.$space-8;
+  background: tokens.$surface-base;
+  color: tokens.$text-secondary;
+}
+`;
+
+const apiAction =
+  (): string => `// api/ holds actions only: no rendering, no components. This one is the readiness probe every
+// role exposes, declared as an action so it appears in OpenAPI and MCP like everything else.
+
+import { action, t } from '@ultimat3/action';
+import { allow } from '@ultimat3/policy';
+
+export const health = action({
+  input: t.object({}),
+  output: t.object({ ok: t.boolean, role: t.string }),
+  // Public, said out loud. \`can('x:y')\` is the other branch; a missing policy is a build error,
+  // so "anyone may call this" has to be a declaration too.
+  policy: allow('public'),
+  mcp: { expose: true, description: 'Readiness of this process' },
+  async handle({ ctx }) {
+    return { ok: true, role: ctx.role };
+  },
+});
+`;
+
+const apiTest = (): string => `import { contractTest, expect } from '@ultimat3/testing';
+import { health } from './health';
+
+// Named here because every projection needs a stable name and this file does not boot the app.
+// At boot \`registerActions\` stamps the same name onto the same object.
+const target = health.named('health');
+
+contractTest('health is an action exposed over MCP', () => {
+  expect(target.kind).toBe('action');
+  expect(target.mcp?.expose).toBe(true);
+});
+
+contractTest('health projects one MCP tool and one OpenAPI operation', () => {
+  // Same policy object on both surfaces — a public action says so once, not once per surface.
+  expect(target.tool().policy).toBe(target.policy);
+  expect(target.openapi().operationId).toBe('health');
+});
+`;
+
+const sharedTokens =
+  (): string => `// Semantic tokens for this app, layered on @ultimat3/ui. Components reference these names; a raw
+// hex anywhere in the app is a lint failure, because dark theme is not a later project.
+@use '@ultimat3/ui/tokens' as base;
+
+$surface-base: base.$surface-base;
+$surface-raised: base.$surface-raised;
+$text-primary: base.$text-primary;
+$text-secondary: base.$text-secondary;
+$accent-solid: base.$accent-solid;
+$accent-on-solid: base.$accent-on-solid;
+`;
+
+const sharedActor =
+  (): string => `// The actor type both surfaces agree on. Policies read this and nothing else, so authz cannot
+// disagree between HTTP, live queries, jobs and MCP.
+export interface Actor {
+  readonly id: string;
+  readonly orgId: string;
+  readonly roles: readonly string[];
+}
+
+export const isMember = (actor: Actor | null): boolean =>
+  actor !== null && (actor.roles.includes('member') || actor.roles.includes('owner'));
+`;
+
+const sharedActorTest = (): string => `import { expect } from 'bun:test';
+import { unitTest } from '@ultimat3/testing';
+import { isMember } from './actor';
+
+unitTest('isMember rejects anonymous and viewer actors', () => {
+  expect(isMember(null)).toBe(false);
+  expect(isMember({ id: 'a', orgId: 'o', roles: ['viewer'] })).toBe(false);
+  expect(isMember({ id: 'a', orgId: 'o', roles: ['owner'] })).toBe(true);
+});
+`;
+
+const adminPackage = (app: NameSet): string => `{
+  "name": "@${app.kebab}/admin",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./*": "./*.ts",
+    "./*.tsx": "./*.tsx"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}
+`;
+
+const adminPage =
+  (): string => `// The generated admin dashboard. It ships an MCP surface over the app's own actions, so the
+// user's agents can drive the user's product with the user's permissions.
+
+import { t } from '@ultimat3/i18n';
+import { defineRoute } from '@ultimat3/render';
+
+export const config = defineRoute({
+  render: 'spa',
+  hydrate: 'idle',
+  offline: 'network-only',
+  // A spa renders no data, so the shell itself must be gated — @ultimat3/render requires it.
+  policy: { permission: 'admin:read' },
+  budget: { js: '120kb', lcp: 3000 },
+  meta: () => ({ title: t('admin.home.title'), description: t('admin.home.description') }),
+});
+
+export function AdminHome() {
+  return <h1>{t('admin.home.title')}</h1>;
+}
+`;
+
+const placeholder = (surface: string, app: NameSet): string => `# ${surface}
+
+Placeholder. The monorepo shape exists now so adding ${surface} later is a new directory, not a
+restructure.
+
+| Question | Answer |
+|---|---|
+| Stack | ${surface === 'mobile' ? 'native Swift / Kotlin against the generated typed client' : 'Tauri shell around the app/ surface'} |
+| API | the same actions as \`apps/web/api\` — one authz system, one contract |
+| Contract | \`openapi.json\` at the repo root, regenerated by \`x manifest\` |
+| Start | \`x new ${app.kebab}-${surface}\` inside this directory, or wire it by hand |
+`;
+
+export function appFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'apps/web/package.json', contents: webPackage(app) },
+    { path: 'apps/web/tsconfig.json', contents: tsconfig() },
+    { path: 'apps/web/site/icon.png', contents: icon() },
+    { path: 'apps/web/site/page.tsx', contents: sitePage(app) },
+    { path: 'apps/web/site/page.module.scss', contents: siteStyle() },
+    { path: 'apps/web/site/page.test.ts', contents: sitePageTest() },
+    { path: 'apps/web/app/dashboard/page.tsx', contents: dashboardPage() },
+    { path: 'apps/web/app/dashboard/page.module.scss', contents: dashboardStyle() },
+    { path: 'apps/web/app/dashboard/page.test.ts', contents: dashboardTest() },
+    { path: 'apps/web/app/offline.tsx', contents: offlineFallback() },
+    { path: 'apps/web/app/offline.module.scss', contents: offlineStyle() },
+    { path: 'apps/web/api/health.ts', contents: apiAction() },
+    { path: 'apps/web/api/health.test.ts', contents: apiTest() },
+    { path: 'apps/web/shared/tokens.scss', contents: sharedTokens() },
+    { path: 'apps/web/shared/actor.ts', contents: sharedActor() },
+    { path: 'apps/web/shared/actor.test.ts', contents: sharedActorTest() },
+    { path: 'apps/admin/package.json', contents: adminPackage(app) },
+    { path: 'apps/admin/tsconfig.json', contents: tsconfig() },
+    { path: 'apps/admin/app/page.tsx', contents: adminPage() },
+    { path: 'apps/mobile/README.md', contents: placeholder('mobile', app) },
+    { path: 'apps/desktop/README.md', contents: placeholder('desktop', app) },
+  ];
+}

package/src/templates/scaffold-docs.ts

@@ -0,0 +1,156 @@
+// The human-authored half of what `x new` writes: the READMEs, the agent-facing convention files,
+// the bin/ shims and the docker directory. Separated from the config half so neither file has to
+// be scrolled to find the other — one file, one job applies to templates too.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const agents = (app: NameSet): string => `# AGENTS.md
+
+Human-authored, short, stable. Facts live in \`x.manifest.json\`; this file holds only what an
+agent cannot infer from the code.
+
+| Rule | Detail |
+|---|---|
+| One gate | \`x verify\` — green means shippable. Never merge red. |
+| One way | generators, not hand-rolled files: \`x g resource\`, \`x g action\`, \`x g route\` |
+| Surfaces | \`site/\` is 0kb JS and may not import \`app/\`; \`shared/\` is a leaf |
+| Data | routes call actions and queries; only \`repo.ts\` touches the database |
+| Errors | never \`throw new Error\` — subclass \`UltimateError\` with a code, a cause and a fix |
+| Money | integer minor units + ISO code, never a float |
+| Time | store UTC, format with an explicit IANA time zone |
+| Strings | every user-facing string goes through \`t()\` |
+| Colour | semantic tokens only, never a raw hex |
+
+Commands: \`x dev\`, \`x verify\`, \`x g <primitive>\`, \`x db branch <name>\`, \`x doctor\`.
+
+Project notes for ${app.kebab}: replace this line with the conventions a newcomer could not guess.
+`;
+
+const claude = (app: NameSet): string => `# CLAUDE.md
+
+${app.kebab} — Ultimate app. Read AGENTS.md first; it is the same content in the same order.
+
+- Gate: \`x verify\` (add \`--json\` for machine output).
+- Scaffold, do not hand-write: \`x g resource|action|job|route|policy|entity|query|task\`.
+- Destructive DB work goes in a branch: \`x db branch <name>\`, never the shared dev DB.
+- \`x doctor\` explains a broken environment and prints the fix command for every finding.
+`;
+
+const readme = (app: NameSet): string => `# ${app.pascal}
+
+Built with [Ultimate](https://ultimate.dev). Bun-only, Postgres, SolidJS.
+
+## 🚀 Start
+
+\`\`\`sh
+bin/setup     # prerequisites, deps, env, migrate, seed
+x dev         # all roles in one process, embedded Postgres, /_x mounted
+x verify      # the gate: typecheck, lint, boundaries, tests, drift, budgets
+\`\`\`
+
+## 🗺 Layout
+
+| Path | Holds |
+|---|---|
+| \`apps/web/site\` | static/isr, 0kb JS, SEO-critical |
+| \`apps/web/app\` | authed, streaming, realtime |
+| \`apps/web/api\` | actions only |
+| \`apps/web/shared\` | tokens, primitives, actor type — a leaf |
+| \`apps/admin\` | generated admin dashboard, MCP on |
+| \`packages/*\` | domain, db, i18n, ui, mcp |
+| \`app.config.ts\` | the one config file |
+| \`x.manifest.json\` | generated facts: routes, actions, jobs, policies |
+`;
+
+const binSetup = (): string => `#!/usr/bin/env bash
+# Fresh clone to running. Idempotent: safe to re-run.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+command -v bun >/dev/null || { echo "X_BUN_MISSING: install bun — https://bun.sh"; exit 1; }
+bun install
+[ -f .env.development.local ] || printf '# per-box secrets, gitignored, wins over .env.development\\n' > .env.development.local
+bunx x db migrate "$@"
+bun run db:seed
+echo "setup complete — next: x dev"
+`;
+
+const binDev = (): string => `#!/usr/bin/env bash
+# Every role in one process: embedded Postgres, in-process NATS, S3 to a local dir.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+exec bunx x dev "$@"
+`;
+
+const binCheck = (): string => `#!/usr/bin/env bash
+# The gate. Same steps as CI, because a check that lives only in CI cannot be run locally.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+exec bunx x verify "$@"
+`;
+
+const composeDev = (
+  app: NameSet,
+): string => `# Optional: x dev needs none of this. Use it when you want the real Postgres/NATS/MinIO locally.
+services:
+  db:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_PASSWORD: ${app.kebab}
+      POSTGRES_DB: ${app.kebab}
+    ports: ['5432:5432']
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U postgres']
+      interval: 5s
+  nats:
+    image: nats:2-alpine
+    command: ['-js']
+    ports: ['4222:4222']
+  s3:
+    image: minio/minio
+    command: ['server', '/data']
+    environment:
+      MINIO_ROOT_USER: ${app.kebab}
+      MINIO_ROOT_PASSWORD: ${app.kebab}-dev
+    ports: ['9000:9000']
+`;
+
+const dockerfile = (
+  app: NameSet,
+): string => `# One image, all roles. ROLE selects behaviour at start; nothing else differs between processes.
+FROM oven/bun:1.3-alpine AS deps
+WORKDIR /src
+COPY package.json bun.lock ./
+COPY apps ./apps
+COPY packages ./packages
+RUN bun install --frozen-lockfile --production
+
+FROM oven/bun:1.3-alpine AS build
+WORKDIR /src
+COPY --from=deps /src/node_modules ./node_modules
+COPY . .
+RUN bunx x build --target binary --out /out/${app.kebab}
+
+FROM gcr.io/distroless/base-debian12 AS runtime
+COPY --from=build /out/${app.kebab} /app/${app.kebab}
+ENV ROLE=web PORT=3000
+EXPOSE 3000
+USER 65532:65532
+ENTRYPOINT ["/app/${app.kebab}"]
+`;
+
+/** Docs, shims and container files for a new app, in the order a reader meets them. */
+export function docsFiles(app: NameSet): readonly GeneratedFile[] {
+  return [
+    { path: 'README.md', contents: readme(app) },
+    { path: 'AGENTS.md', contents: agents(app) },
+    { path: 'CLAUDE.md', contents: claude(app) },
+    { path: 'bin/setup', contents: binSetup() },
+    { path: 'bin/dev', contents: binDev() },
+    { path: 'bin/check', contents: binCheck() },
+    { path: 'docker/Dockerfile', contents: dockerfile(app) },
+    { path: 'docker/docker-compose.dev.yml', contents: composeDev(app) },
+  ];
+}
+
+/** Files that must be executable after `x new` writes them. */
+export const EXECUTABLE_FILES: readonly string[] = ['bin/setup', 'bin/dev', 'bin/check'];

package/src/templates/scaffold-i18n.ts

@@ -0,0 +1,149 @@
+// The generated app's `packages/i18n`: one catalog file per locale, and the framework's one
+// blessed typed-catalog shape (modelled on examples/dummy/packages/i18n/src/index.ts) — split out
+// of scaffold-repo.ts to stay under the file-size ceiling.
+
+import { catalogJson } from './catalog-json';
+import type { GeneratedFile, NameSet } from './naming';
+import { camel } from './naming';
+import { packageShapeFiles } from './scaffold-package-shape';
+
+/** The only `packages/*` manifest that names a dependency: every other one only re-exports a
+ * framework package's types, but this one statically imports `@ultimat3/i18n` at runtime. */
+const i18nPackage = (app: NameSet, version: string): string => `{
+  "name": "@${app.kebab}/i18n",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Flat catalogs with loud misses",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
+  },
+  "dependencies": {
+    "@ultimat3/i18n": "^${version}"
+  }
+}
+`;
+
+/**
+ * `en` first, then every other locale alphabetically — a stable order so a diff shows only the
+ * locale a run actually added, never a reshuffle. `en` is always included: `default: 'en'` below
+ * requires it to be a registered locale, and every real catalog set already has one from `x new`
+ * scaffold time.
+ */
+const orderedLocales = (locales: readonly string[]): readonly string[] => {
+  const rest = new Set(locales);
+  rest.delete('en');
+  return ['en', ...[...rest].sort()];
+};
+
+/** A locale tag is not always a valid JS binding (`zh-hant`) — `camel()` is the one identifier
+ * derivation every generated file already uses for names, so the import agrees with the rest of
+ * the app's own naming instead of inventing a second casing rule. */
+const localeImport = (locale: string): string =>
+  `import ${camel(locale)} from '../catalogs/${locale}.json';`;
+
+/** The object-literal entry for one locale: shorthand when the binding IS the tag (`en`, `es`, …),
+ * `'tag': binding` when `camel()` had to reshape it (`zh-hant` → `zhHant`) — `defineCatalogs` reads
+ * the locale from the key, never the identifier, so the quoted form is what keeps it addressable. */
+const localeEntry = (locale: string): string => {
+  const binding = camel(locale);
+  return binding === locale ? binding : `'${locale}': ${binding}`;
+};
+
+/**
+ * The app's one catalog-registration module — regenerated, never hand-edited, to the full current
+ * locale set every time `x g ... --locales` lands a new catalog file (`syncI18nIndex` in
+ * `cmd-generate.ts`). `i18nFiles` below calls this with `['en']` for the shape `x new` has always
+ * scaffolded; a later run passes whatever `packages/i18n/catalogs/` actually holds.
+ */
+export function i18nIndex(locales: readonly string[]): string {
+  const ordered = orderedLocales(locales);
+  const imports = ordered.map(localeImport).join('\n');
+  const entries = ordered.map(localeEntry).join(', ');
+  return `// The app's catalog, registered once and typed against English. Every surface resolves strings
+// through this module, and an unknown key is a compile error via useT() — never a runtime miss
+// nobody notices until production.
+
+import {
+  defineCatalogs,
+  type TranslationKey as KeyOf,
+  type Translator,
+  useI18n,
+} from '@ultimat3/i18n';
+${imports}
+
+export const catalogs = defineCatalogs({ default: 'en', locales: { ${entries} } });
+
+/**
+ * English is the source of truth for the key space — a second locale must match it exactly, or
+ * \`x verify\` fails.
+ */
+export type AppCatalog = typeof en;
+
+/** Every key this app's catalog defines — dot-paths, plus the stem of each plural family. */
+export type TranslationKey = KeyOf<AppCatalog>;
+
+/**
+ * Use this, never \`useI18n()\` directly — the type parameter is what makes an unknown key a
+ * compile error instead of a \`⟦key⟧\` someone notices in production.
+ */
+export const useT = (): Translator<AppCatalog> => useI18n<AppCatalog>();
+`;
+}
+
+// `app.post.*` is not listed here: under `--example`, `x g resource post` merges its own keys
+// into this same file (`merge: 'json'`, resolved by `dedupe()`); under `--no-example` that
+// generator never runs, so those keys are simply absent, never a dangling reference.
+const i18nCatalog = (app: NameSet): string =>
+  catalogJson({
+    'site.home.title': app.pascal,
+    'site.home.description': 'Everything you need, one command from shippable.',
+    'site.home.cta': 'Open the dashboard',
+    'app.dashboard.title': 'Dashboard',
+    'app.dashboard.description': 'Your workspace.',
+    'app.offline.title': 'You are offline',
+    'app.offline.description': 'This page will refresh itself when the connection returns.',
+    'admin.home.title': 'Admin',
+    'admin.home.description': `Operations for ${app.pascal}.`,
+  });
+
+const i18nTest = (): string => `import { expect } from 'bun:test';
+import { unitTest } from '@ultimat3/testing';
+import { catalogs } from './index';
+
+unitTest('every locale has the same keys as the default one', () => {
+  const base = Object.keys(catalogs.catalogs[catalogs.default]).sort();
+  for (const locale of catalogs.locales) {
+    expect(Object.keys(catalogs.catalogs[locale]).sort()).toEqual(base);
+  }
+});
+
+unitTest('no catalog value is empty', () => {
+  for (const catalog of Object.values(catalogs.catalogs)) {
+    for (const value of Object.values(catalog)) expect(value.length).toBeGreaterThan(0);
+  }
+});
+`;
+
+/**
+ * Everything `packages/i18n` ships: the manifest (the one package that declares a dependency),
+ * the shared shape files with the extra `catalogs/**` include the JSON needs, the typed index,
+ * its test, and the `en` catalog. `merge: 'json'` on the catalog is what lets `x g resource
+ * post` (the example slice, under `--example`) land its own keys in this same file instead of
+ * `dedupe()` dropping one contributor's — see the comment on `i18nCatalog` above.
+ */
+export function i18nFiles(app: NameSet, version: string): readonly GeneratedFile[] {
+  return [
+    { path: 'packages/i18n/package.json', contents: i18nPackage(app, version) },
+    ...packageShapeFiles(app, 'i18n', 'Flat catalogs with loud misses', [
+      '**/*.ts',
+      'catalogs/**/*',
+    ]),
+    { path: 'packages/i18n/src/index.ts', contents: i18nIndex(['en']) },
+    { path: 'packages/i18n/src/index.test.ts', contents: i18nTest() },
+    { path: 'packages/i18n/catalogs/en.json', contents: i18nCatalog(app), merge: 'json' },
+  ];
+}

package/src/templates/scaffold-icon.ts

@@ -0,0 +1,54 @@
+// The one source icon `x new` scaffolds. @ultimat3/core's image pipeline decodes PNG and JPEG
+// only (`DECODABLE_FORMATS`, packages/core/src/image/pipeline.ts) — an SVG source, which is what
+// this used to emit, can never be decoded, so `@ultimat3/pwa`'s `BuiltinImagePipeline` could
+// never turn it into the fourteen `ICON_MATRIX` PNGs the generated web manifest declares.
+
+import type { Raster } from '@ultimat3/core';
+import { createRaster, encodeImage } from '@ultimat3/core';
+
+/** `@ultimat3/pwa`'s own contract (`requireSourceIcon`'s fix line): square, 1024 or larger. */
+const ICON_SIZE = 1024;
+
+/**
+ * Mirrors `MASKABLE_PADDING` (`packages/pwa/src/icons.ts`): a maskable icon is cropped to the
+ * middle ~80% of the edge, so the mark has to stay inside that fraction or an installed Android
+ * icon clips it. Inlined rather than imported — `@ultimat3/pwa` is not a dependency of this
+ * package, and a placeholder icon does not need the rest of it.
+ */
+const MASKABLE_PADDING = 0.1;
+
+/**
+ * Not a colour: one mid-grey LEVEL, written to all three channels, so this file recreates no
+ * palette value that could drift from one. A token cannot supply it either — `@ultimat3/ui` owns
+ * the colour roles and is tier 5 like this package, so `cli -> ui` is a boundary error and
+ * `cli -> admin -> ui` does not transit. A placeholder must claim no brand colour to begin with.
+ */
+const MARK_LEVEL = 128;
+
+/** Opaque over the transparent canvas — the mark is what `probeImage` and a human both see. */
+const MARK_ALPHA = 255;
+
+/** Fills the maskable-safe inner square, transparent canvas left untouched around it. */
+function paintMark(raster: Raster, inset: number): void {
+  const { width, height, pixels } = raster;
+  for (let y = inset; y < height - inset; y += 1) {
+    for (let x = inset; x < width - inset; x += 1) {
+      const i = (y * width + x) * 4;
+      pixels[i] = MARK_LEVEL;
+      pixels[i + 1] = MARK_LEVEL;
+      pixels[i + 2] = MARK_LEVEL;
+      pixels[i + 3] = MARK_ALPHA;
+    }
+  }
+}
+
+/**
+ * A 1024x1024 PNG: a solid square mark inside the maskable safe zone, transparent elsewhere —
+ * exactly what a placeholder needs to be, not art. Deterministic: no `Date.now()`, no randomness,
+ * so `x new` output never depends on run order or the clock.
+ */
+export function icon(): Uint8Array {
+  const raster = createRaster(ICON_SIZE, ICON_SIZE, 'scaffold-icon');
+  paintMark(raster, Math.round(ICON_SIZE * MASKABLE_PADDING));
+  return encodeImage(raster, 'png');
+}