@ultimat3/cli 29.4.0 → 30.0.0

package/wiki/I18n.md

@@ -0,0 +1,239 @@
+# I18n
+
+Flat key catalog, one JSON file per locale. Loud misses. `Intl.*` for anything that is not a string.
+
+Zero hardcoded user-facing strings — every string an end user can read goes through `t()`. A literal in JSX or in an error message is a lint failure and fails `x verify`.
+
+## Catalogs
+
+One file per locale, flat dot-keys after load, nested for authoring.
+
+```
+packages/i18n/src/catalogs/en.json  # framework strings — ships inside @ultimat3/i18n
+packages/i18n/catalogs/en.json      # the app's own catalogs, same shape
+packages/i18n/catalogs/es.json
+```
+
+```json
+{
+  "nav": { "home": "Home", "billing": "Billing" },
+  "post": {
+    "published": "Published {title}",
+    "count_one": "{count} post",
+    "count_other": "{count} posts"
+  }
+}
+```
+
+| Rule | Detail |
+|---|---|
+| Authoring | nested objects; `flattenCatalog` produces `nav.home`, `post.published` |
+| Key segments | `/^[A-Za-z0-9_-]+$/` — anything else is `X_CATALOG_INVALID` |
+| Leaves | strings only. An array or a number leaf is `X_CATALOG_INVALID` |
+| Collisions | a nested branch and a dotted key that flatten to the same path throw |
+| Merge order | framework catalog first, app catalog last — apps override framework keys. **Under `en` only**: the framework catalog is English, so `defineCatalogs` seats it under core's `DEFAULT_LOCALE` (`en`) and nowhere else. An app shipping only `es` renders `⟦errors.notFound.title⟧` for a framework key it has not translated, which is the golden rule working — it used to be served English with `isMiss` reading `false`, a fallback locale chain wearing registration as a disguise |
+| `en` | the reference locale. Its key set is what every other locale is diffed against |
+
+## `t()`
+
+```ts
+import { t } from '@ultimat3/i18n';
+
+export function billingHeading(count: number): string {
+  return t('post.count', { count });
+}
+```
+
+| Aspect | Behavior |
+|---|---|
+| Signature | `t(key: string, vars?: TranslateVars): string` — `TranslateVars` is `Record<string, string \| number \| boolean>` plus optional `count` |
+| Locale | ambient, read from the ALS request context. `t()` never takes a locale argument |
+| Miss | returns `⟦key⟧`. Never throws, never falls back to another locale, never returns the key bare |
+| Typed keys | keys are generated into a union from the `en` catalog; an unknown key is a type error |
+| Introspection | `t.has(key)`, `t.raw(key)`, `t.keys()`; `isMiss(rendered)` for assertions in tests |
+| No concatenation | `t('a') + ' ' + name` is banned — put the slot in the string: `t('a', { name })` |
+
+Word order differs per language, so a concatenated sentence is untranslatable by construction. One key = one complete sentence or label.
+
+## Interpolation
+
+| Form | Renders |
+|---|---|
+| `{name}` | `String(vars.name)` |
+| `{{` / `}}` | a literal `{` / `}` |
+| `{name}` with no `vars.name` | `⟦name⟧` — loud, same reason a missing key is loud |
+
+`t()` interpolates on **every** call, with `vars` or without: `t('greeting')` on `Hello {name}` is `Hello ⟦name⟧`, exactly as `t('greeting', {})` is, and `{{` is unescaped either way. The template itself — to hand a client island its plural forms, say — is `t.raw(key)`, never `t(key)`.
+
+## Pluralization
+
+CLDR categories via `Intl.PluralRules`, never an English `n === 1` branch.
+
+| Locale | Categories it needs |
+|---|---|
+| `en`, `de`, `es` | `one`, `other` |
+| `pl`, `ru`, `uk` | `one`, `few`, `many`, `other` |
+| `ar` | `zero`, `one`, `two`, `few`, `many`, `other` |
+| `ja`, `zh`, `ko` | `other` only |
+
+Pass `count`; the translator picks the key. Candidates, most specific first: `key_<category>` → `key_plural` → `key_other` → `key`. For `count === 1`: `key_one` → `key`. `_plural` is the two-form authoring shortcut; the `_<category>` suffixes are what a 3+ form locale needs.
+
+## Ordinals and `select`
+
+`As of 2026-11-06`. **The suffix mechanism, two more families; no ICU syntax.** One selection
+(`selectMessageKey`) serves `t()` and a mail's render alike.
+
+| Call | Reads, in order |
+|---|---|
+| `t('place', { ordinal: 2 })` | `place_ordinal_<category>` by CLDR's **ordinal** rules (`en`: 1 one, 2 two, 3 few, 4 and 11 other), then `place_ordinal_other` |
+| `t('invite', { select: 'female' })` | `invite_select_female`, then `invite_select_other` |
+| `t('invite', { select: 'female', count: 2 })` | each of those stems with `count`'s plural chain: `invite_select_female_other`, … |
+
+A family the catalog lacks falls through to the key's own plural, as before. A `select` value is a
+key segment (`[A-Za-z0-9-]`, ≤ 32) or it selects nothing. The typed key admits the stem (`invite`),
+as it does a plural stem. `x i18n check` counts every member used through its stem, a locale owes
+the stem and not each value (a language without gender defines `invite_select_other` alone), and a
+family with no `_other` is `X_I18N_FAMILY_INCOMPLETE`, red in the `i18n` step.
+
+## Loud misses
+
+| Surface | Behavior on a missing key |
+|---|---|
+| dev render | `⟦post.published⟧` in the DOM — visible in the page and in review screenshots |
+| `x verify` | check 8 (SEO + i18n) fails with `X_CATALOG_MISSING_KEYS` |
+| CI | same failure, `--json` shaped |
+| Tests | `isMiss(t('k'))` is the assertion — never assert on `''` |
+
+Silently falling back to English is what makes a half-translated app ship. The framework does not do it.
+
+## Strings in an island
+
+`t()`'s catalog does not cross into an island, and a translator is not a prop. An island's own copy
+arrives already translated, as text. When it needs keys — `t(key, { count })` after the page
+rendered, or the design system's `ui.*` strings — the page sends a slice and the island builds a
+translator over it (`As of 2026-10`):
+
+| Side | Call |
+|---|---|
+| page (server) | `catalogSubset(t, ['app.post.likes'])` from `@ultimat3/i18n`; `uiCatalog(t)` from `@ultimat3/ui` for every `ui.*` key |
+| island | `subsetTranslator(props.strings)` from `@ultimat3/i18n/subset`; `<UiProvider t={subsetTranslator(props.ui)}>` |
+
+The slice carries every plural variant of each key, and a key it lacks renders `⟦key⟧` in the
+island exactly as on the server.
+
+**A form's validation messages key on the issue's `rule`**, never on its English `message` — the
+framework's diagnostic text changes without a semver signal, the rule names do not
+(`SCHEMA_RULES`, `@ultimat3/schema`). Ship one key per rule in the slice and pass `params`:
+``messageFor: (issue) => t(`form.${issue.rule}`, issue.params)`` — `form.string.min` → `At least
+{min} characters`. A third-party schema names no rule; fall back to a generic key for those.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `x i18n add <locale>` | create `catalogs/<locale>.json` seeded with every default-locale key, each value copied inside `⟦…⟧` |
+| `x i18n sync <locale>` | add keys the locale is missing; a key it already has is never overwritten, translated or not; never deletes |
+| `x i18n check --json` | extract keys from source, diff against every catalog and against `en`, report missing / unused / dynamic / slot mismatch / untranslated |
+
+Every command supports `--json`. `add` and `sync` copy the source value inside the marker, so the text sits where the translation goes and `x i18n check` counts the key as missing until a person replaces it. Source means every shape below; a key only a mail or a push names is a key.
+
+| Shape in source | Key |
+|---|---|
+| `t('k')`, `$t('k')`, `translate('k')` | first argument |
+| `blocks.heading`, `paragraph`, `button`, `callout`, `detail` | first argument |
+| `titleKey:`, `bodyKey:` | a literal value |
+| `subject:` | a literal value, in a file that names `defineMail` |
+
+Any other value of these is listed `dynamic`.
+
+`check` reports five separate things, and three of them fail the command:
+
+| Reported | Meaning | Exit |
+|---|---|---|
+| `missing` | a key source names, or a key `en` defines (compared by plural stem, so `pl`'s `_few` and `ja`'s lone `_other` answer it), that the locale does not define | non-zero, one `X_CATALOG_MISSING_KEYS` finding per locale |
+| `unused` | a key the locale defines that no shape above names | 0 — informational |
+| `dynamic` | `t(`plans.${plan}.name`)`, a key the static extractor cannot resolve | 0 — informational, with file, line and column |
+| `slot mismatch` | two locales define one key with different interpolation slots — the slot sets are compared by name, so the same slots in another order are not a mismatch | non-zero, one `X_CATALOG_SLOT_MISMATCH` finding per direction |
+| `untranslated` | a locale still carries the reference locale's value — byte-identical to it and longer than 24 characters | non-zero, one `X_CATALOG_UNTRANSLATED` finding per key |
+
+The last two are the parity rules, and both compare a locale with the reference locale `en` (`As of 2026-10`). A key `en` defines and another locale lacks is a missing key, not a parity finding, and that holds for a key only reached dynamically (`t(`plans.${plan}.name`)`). A key only another locale defines is `unused` there. A `⟦key⟧` placeholder is a missing key too — never a copy. Every finding names the locale, the catalog key and the file `packages/i18n/catalogs/<locale>.json`; `x verify`'s `i18n` step and `x i18n check` report them from one implementation, so the command and the gate answer about an app with one voice.
+
+Before any of the five, `check` resolves `@ultimat3/i18n` from the app root, from every workspace and from the CLI itself. Two real directories is `X_PACKAGE_DUPLICATED`, and every registration gap is then reported as the install's fault with the install's fix (pin one version, `bun install`) — not as a misplaced `defineCatalogs()`: each copy keeps its own registry, so the app registers into one and the check reads the other.
+
+A dynamic call contributes its static head (`plans.`) as a runtime-key prefix, so a key only ever reached that way is never listed `unused` — otherwise the list reads as "safe to delete" over live keys. An expression with no static head (a ternary over literals, a bare variable) contributes nothing: a guessed prefix would suppress real gaps.
+
+## Locale routing
+
+`As of 22.3.0`. The routed locales are `routedLocales()`: the ones `defineCatalogs()` declared, default first. An app that declared none routes its fallback alone — no prefix, no per-locale files.
+
+| Path (default `es-co`, also `en`) | Locale | Answer |
+|---|---|---|
+| `/precios` | `es-co` | the `/precios` route |
+| `/en/precios` | `en` | the `/precios` route — the prefix is stripped before the route table is matched. An `isr` page keeps the prefix in its store key and is revalidated by that route's `ttl` and `tags` ([Routes](Routes-And-Render-Modes)) |
+| `/es-co/precios` | — | `301` to `/precios` (`308` for a non-GET); the default is never prefixed |
+| `/fr/precios` | — | `404`: `fr` is not routed, so `/fr/precios` is an ordinary path |
+| `/en/nothing` | `en` | `404`, its error page in English |
+
+| Rule | Detail |
+|---|---|
+| Prefix | authoritative on every surface: it beats `?locale=`, the cookie, the user and `Accept-Language`. Stripped in `@ultimat3/http`'s `context` stage, never by middleware — middleware wraps matched routes only |
+| `site/` | the URL alone (`RouteMeta.localeSource: 'path'`). Unprefixed is **always** `defaultLocale` — no `Accept-Language` negotiation, because a CDN serves `/` as one file — and `Vary` drops `accept-language` |
+| `app/` / `api/` | unprefixed keeps `query → cookie → user → header`, configurable via `configureLocales({ order })`. The `user` rung is the actor's saved `locale`, which your `authenticate` hook sets (`userActor({ id, locale, tz })`); `@ultimat3/http` re-resolves once `auth` has run. An explicit choice outranks the browser: `?locale=` is how an email preview link pins a locale, the cookie is what the language switcher writes, and `Accept-Language` is only the fallback when nobody has chosen. An `order` without `'header'` never reads it, and the response drops `accept-language` from `Vary` (`As of 22.10`) — a CDN no longer stores one copy per browser language of a page that cannot differ by it |
+| Static export | `x build --target static` renders each `site/` page once per routed locale, in that locale's context: `index.html` (`lang="es-co"`), `en/index.html` (`lang="en"`), `en/precios/index.html`. Every static host serves `/en/precios` from that layout with no rewrite |
+| Cookie | `x_locale`, written only by an explicit language switcher |
+| Unsupported tag | skipped, not thrown — a stale cookie must never 500 a page. `assertSupportedLocale` throws `X_LOCALE_UNSUPPORTED` where an unknown tag is a caller bug |
+| Direction | `currentDirection()` returns `'rtl'` for `ar`, `he`, `fa`, `ur`, … and is written to `<html dir>` |
+
+| API | From | Answers |
+|---|---|---|
+| `routedLocales()` | `@ultimat3/i18n` | the locales a URL may name, default first |
+| `localizedPath(path, locale)` | `@ultimat3/i18n` | `/precios` + `en` → `/en/precios`; the default → `/precios`; `/` + `en` → `/en/`; an existing prefix is re-spelled, never doubled |
+| `splitLocalePrefix(pathname)` / `unlocalizedPath(pathname)` | `@ultimat3/i18n` | the prefix split off, or the bare path |
+| `localizePath(path, locale, locales, defaultLocale)` | `@ultimat3/core` | the same arithmetic over an explicit list — for browser code, which must not import the i18n barrel |
+| `<LocaleSwitcher locales={routedLocales()} path={pathname} />` | `@ultimat3/ui` | links to this page in each locale; `hrefFor` overrides, `defaultLocale` defaults to `locales[0]` |
+
+`meta` receives `locale`, `localizedPath(locale)` and `alternates` (`{ locale, path }` per routed locale). The head then carries, with no route code:
+
+| Tag | Value |
+|---|---|
+| `<link rel="canonical">`, `og:url` | absolute, against `APP_URL` / `SITE_ORIGIN` / `site.origin` ([Configuration](Configuration)) |
+| `<link rel="alternate" hreflang>` | one per routed locale in BCP 47 region form (`es-co` → `es-CO`), plus `x-default` → the default locale's page. A route's own `alternates` replace the set whole |
+| `og:locale` / `og:locale:alternate` | `es_CO` form — language and region only, so `zh-hant-tw` is `zh_TW`; the document's locale, then every other one |
+
+`sitemap.xml` lists every page once per locale, each with the same `xhtml:link` cluster. A single-locale app emits none of the cluster.
+
+## Numbers, dates, money
+
+Never hand-rolled, never string-formatted in a component.
+
+| Value | Route |
+|---|---|
+| Number / percent | `Intl.NumberFormat` with the request locale |
+| Date / time | `Intl.DateTimeFormat` with the request locale **and an explicit IANA `timeZone`** → [Timezones and dates](Timezones-And-Dates) |
+| Currency | `Money = { minor, currency }` formatted at the edge → [Money](Money) |
+
+A colour is a token, a string is a key, a date needs a zone, an amount is minor units. Same four rules everywhere.
+
+## Errors
+
+| Code | Cause | Fix |
+|---|---|---|
+| `X_LOCALE_UNSUPPORTED` | tag is not in the supported set | `x i18n add <locale>` |
+| `X_CATALOG_MISSING_KEYS` | a locale file is missing keys source names or `en` defines (names up to 12 of them) | `x i18n sync <locale>` |
+| `X_CATALOG_INVALID` | non-string leaf, bad key segment, or duplicate flat key | `x i18n check --json` |
+| `X_CATALOG_SLOT_MISMATCH` | two locales define one key with different interpolation slots | `x i18n check --json` — the finding names the locale, the key and the slots that differ |
+| `X_CATALOG_UNTRANSLATED` | a locale still carries the reference locale's value | `x i18n check --json` — the finding names the locale and the key still carrying the reference value |
+| `X_PACKAGE_DUPLICATED` | two installed copies of `@ultimat3/i18n`, each with its own registry | pin one version in the `package.json` the finding names, then `bun install` |
+
+Full list: [Error codes](Error-Codes).
+
+## Rules
+
+- Zero hardcoded user-facing strings. Everything through `t()`.
+- One key per complete sentence. Never concatenate translated fragments.
+- `en` is the reference key set; other locales are diffed against it, never the reverse.
+- A miss is `⟦key⟧` and a red build, never English.
+- `x i18n sync` adds; deletion of a key is a deliberate edit in a PR.
+- Supported locales live in `app.config.ts`; `SUPPORTED_LOCALES` is the framework's own set, which apps narrow or extend.
+
+Source: [`packages/i18n/src`](https://github.com/developerz-ai/ultimate/blob/main/packages/i18n/src)

package/wiki/Installation.md

@@ -0,0 +1,206 @@
+# Installation
+
+## Prerequisites
+
+| Requirement | Version | Needed for | Notes |
+|---|---|---|---|
+| Bun | **>= 1.4.4** (`engines.bun`; target 2.0) | everything | the only runtime. No Node, Deno, or workerd support — ever |
+| Postgres | 16+ | prod, parity checks | **optional in dev** — `x dev` embeds one in `.x/pg` |
+| Docker | any | parity checks, prod images | never required for `x dev`; `x build --target docker` needs it |
+| Redis | 7+ | cache tier 3 in prod | dev uses an in-process map behind the same interface |
+| NATS | 2.10+ | fanout in prod | dev runs it in-process |
+| Native toolchain | — | **nothing** | no native addons in the dependency graph; no `node-gyp`, no `sharp`, no `libvips` |
+
+Bun below the floor fails before anything else runs:
+
+```
+X_BUN_VERSION: bun version is below the framework floor
+  cause: Bun 1.4.3 is older than the required 1.4.4
+  fix:   bun upgrade
+```
+
+`x doctor --json` checks the runtime, the embedded Postgres, ports, and the resolved env. Outside an app, `x` is on no `PATH` and `bunx x` fetches an **unrelated** npm package named `x`: spell it `bunx @ultimat3/cli doctor --json` there, and start an app with `bunx create-ultimate myapp`.
+
+| Platform | Status | Proved by |
+|---|---|---|
+| Linux x64 | supported | every CI job; `scaffold-smoke` gates a fresh scaffold twice per shape |
+| macOS | supported | the `macos` CI job: a fresh scaffold's `bun run setup` and its gate on `macos-latest` |
+| Windows, native (PowerShell, cmd) | supported | the `windows` CI job: lint, typecheck, a path-heavy unit subset and a scaffold's gate, in pwsh |
+
+| Without Docker | Works |
+|---|---|
+| `bun run dev`, `bun run setup`, `bun run verify` (the gate) | yes — the database is embedded and no service is dialled ([Bare VM](Bare-VM)) |
+| a deploy | takes an image (`x build --target docker` needs Docker, or a host that builds the Dockerfile — [Deploy recipes](Deploy-Recipes)), or `x build --target binary` with no container runtime |
+
+## Create an app
+
+```
+bunx create-ultimate myapp && cd myapp && bun run setup && bun run dev
+```
+
+`create-ultimate` is a thin front for `x new`. Inside an existing workspace, use `x new` directly.
+
+**PowerShell and cmd run the same commands.** `bun run setup` runs the app's `bin/setup.ts` —
+TypeScript that Bun executes, no bash and no WSL — and `bun run dev` and `bun run verify` are
+`x dev` and `x verify`. Windows PowerShell 5.1 has no `&&`: type the commands one per line there
+(PowerShell 7 and cmd take the line as written).
+
+**`bun run setup` is not optional.** `x new` writes files and installs nothing, so `cd myapp && x dev`
+stops on `X_BUILD_FAILED` naming `bun install` (measured `As of 2026-08-23`; this page said
+otherwise until then). `bun run setup` is six steps, idempotent and safe to re-run:
+
+| # | Step | Why it is in the script |
+|---|---|---|
+| 1 | `bun install` | `x new` writes files and installs nothing |
+| 2 | touch `.env.development.local` | per-box secrets, gitignored, wins over the committed `.env.development` |
+| 3 | `x db gen "initial"` | skipped when `packages/db/migrations` already holds a `.sql` — `x db gen` is that directory's only writer |
+| 4 | `x db migrate` | applies them, then diffs the live schema against the ledger |
+| 5 | `x db seed` | run through the CLI, never `bun run`: the CLI owns the connection, so it reaches the same embedded database the migration just wrote to |
+| 6 | `x manifest` | `x.manifest.json` is a projection of the loaded app, so `x new` cannot write it. Nothing else ever ran the command, and `x verify`'s `manifest` step now refuses its absence with `X_MANIFEST_MISSING` |
+
+Every flag, from the registry — `bun run x -- help new`, or `x help new` in an app. There are six,
+each with a default, so **`x new` asks nothing**: an agent cannot answer a prompt and is never given
+one.
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--dir <path>` | cwd | parent directory the app is written into |
+| `--example` / `--no-example` | `--example` | include the example feature slice; `--no-example` gives the same shape with an empty `app/` |
+| `--shape <shape>` | none | start from `api`, `blog` or `dashboard` instead of the dashboard and example slice — what each writes and leaves out: [Shapes](Shapes) |
+| `--git` / `--no-git` | `--git` | `git init` and commit the scaffold |
+| `--dry-run` | off | print the file list, write nothing |
+| `--force` | off | write into a directory that already exists |
+| `--json` | off | machine-readable result: the directory, every path written, the git outcome |
+
+There is **no** `--admin`, `--locale`, `--tz`, `--currency`, `--no-install` or `--yes` — this table
+listed all six until 2026-08-23 and the parser refuses each with `X_CLI_BAD_FLAG`. `apps/admin/` is
+always written; locale, timezone and currency are `app.config.ts` fields you edit after scaffolding
+([Configuration](Configuration)).
+
+What `x new` writes, and who owns it afterwards:
+
+| Artifact | Author | Rule |
+|---|---|---|
+| `.env.development` | generated, **complete and valid**, committed | non-secret defaults; per-box secrets go in `.env.development.local`, which wins. Dev secrets carry a loud `dev-only-` prefix. The scaffold writes no `.env` — Bun still loads `.env`, `.env.<mode>` and `.env.local` when they exist ([`packages/core/src/env-example.ts:31`](https://github.com/developerz-ai/ultimate/blob/main/packages/core/src/env-example.ts)), and `.env` is the one you never commit |
+| `.env.example` | generated from `envSchema`, plus the framework's deploy-required secrets | never hand-edited — it is a projection of the declaration, and drift fails `x verify`. Regenerate with `x env example` |
+| `app.config.ts` | yours | the one config file; validated at boot ([Configuration](Configuration)) |
+| `x.manifest.json` | generated every build | routes, entities, actions, jobs, policies, tags, MCP tools, budgets. Never hand-edited; drift fails `x verify` |
+| `openapi.json` | generated | HTTP surface from `action` / `query` declarations |
+| `CLAUDE.md`, and `AGENTS.md` a symlink to it | **human-authored stub**, one file | short, terse; a copy only where Windows refuses the link. Ultimate never generates prose docs at runtime |
+| `.github/workflows/ci.yml` | generated | `bun run setup` then `bun run verify`, on push and pull request — yours to edit, and the same two commands the app's `README.md` opens with |
+| `docker/` | generated | dev compose + per-role prod compose + Dockerfile ([Deployment](Deployment)) |
+| `packages/db/migrations/` | **not written at all** | `x db gen` is its only writer, `As of 2026-08`. First commands in a new app: `x db gen "initial"`, then `x db migrate` — `bun run setup` runs both. Until the first one has, `x verify`'s `drift` step is red and names it, for any app declaring an entity; `--no-example` declares none, and zero against zero is agreement |
+
+## Typed env, validated at boot
+
+Declared at module scope in `app.config.ts`, next to `defineConfig`. There is no `env.ts` — `app.config.ts` is the one file the CLI and the runtime both load, so it is the one place the env gate can run before anything binds.
+
+```ts
+// app.config.ts
+import { defineConfig, defineEnv } from '@ultimat3/core';
+
+export const env = defineEnv({
+  DATABASE_URL: { type: 'url' },
+  NATS_URL:     { type: 'url', required: false },
+  S3_BUCKET:    { type: 'string' },
+  VAPID:        { type: 'string', required: false },
+  STRIPE_KEY:   { type: 'string', pattern: /^sk_/, secret: true },
+});
+
+export const config = defineConfig({ name: 'myapp' /* … */ });
+```
+
+Boot parses this before any listener binds. Failure costs ~40ms and exit 1 — not a 3am `undefined` in a payment handler.
+
+```
+X_ENV_MISSING: required environment variables are missing or invalid
+  cause: STRIPE_KEY missing; NATS_URL is not a URL ("nats:4222")
+  fix:   add STRIPE_KEY, NATS_URL to .env (copy .env.example), then run: x env check
+```
+
+The `fix:` is per-key and built from your own declarations ([`packages/core/src/env.ts:237`](https://github.com/developerz-ai/ultimate/blob/main/packages/core/src/env.ts)); `defineEnv({ KEY: { fix } })` overrides it for one key.
+
+| Property | Behavior |
+|---|---|
+| Access | `env.STRIPE_KEY` is typed. A `process.env` read outside the schema is a lint error |
+| Per-role | a role requires only the keys it uses — `ROLE=worker` does not fail on a missing `VAPID` |
+| Repair | `x env example` regenerates `.env.example` from the schema; copy the keys it names into `.env.development.local` in dev, or into your platform's secret store in production. There is **no** `x env --fix` — `x env` declares `check` and `example` and no flags, so `x env check --fix` dies at the parser with `X_CLI_BAD_FLAG` |
+| CI | `x verify`'s `manifest` step holds `.env.example` to the schema's projection (`X_ENV_EXAMPLE_DRIFT`); `x env check` is not a gate step — run it against the deploy's own environment (`ULTIMATE_ENV=production x env check`), where it also reports the framework's deploy-required secrets |
+| Provenance | `/_x` → **Env** shows every resolved key and which source it came from |
+
+## What Bun natives replace
+
+Each row is a dependency subtree that never enters the lockfile. Target: **under 40 direct dependencies for the whole framework**.
+
+| Bun primitive | Replaces | Deps killed (approx) |
+|---|---|---|
+| `Bun.sql` | `pg`, `pg-pool`, `pg-connection-string`, `postgres`, pool wrappers | ~8 |
+| `Bun.redis` | `ioredis` / `redis` + command/parser packages | ~5 |
+| `Bun.s3` | `@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner` + AWS SDK core | ~25 |
+| `Bun.serve` WebSockets | `ws`, `socket.io`, `engine.io`, `uWebSockets.js` | ~10 |
+| `bun test` | `vitest` / `jest`, `@types/jest`, coverage + mock + snapshot plugins | ~30 |
+| `Bun.build` | `esbuild` / `rollup` / `vite` + framework plugin + postcss chain | ~40 |
+| `Bun.Transpiler` / macros | `ts-node`, `tsx`, `swc`, babel presets | ~15 |
+| `Bun.password` | `bcrypt` / `argon2` native addons | ~4 |
+| `Bun.file` / `Bun.write` | `fs-extra`, `graceful-fs`, `globby` | ~6 |
+| `bun --hot` | `nodemon`, `concurrently`, HMR middleware | ~5 |
+
+One more subtree dies with no Bun native behind it — a pure-TypeScript framework pipeline, written because native addons are blocked:
+
+| Framework primitive | Replaces | Deps killed (approx) |
+|---|---|---|
+| `@ultimat3/core` image | `sharp` + libvips + `imagemin` plugins | ~12 |
+
+Stated cost: no native-addon packages, and Bun's long-running-process maturity is less proven than Node's.
+
+## Editor and agent setup
+
+Two MCP servers, and an app ships both. The **dev tools** are `x mcp serve` — `x dev` does not
+start them, and nothing listens on 9229 until this command runs. A new app's `.mcp.json` already
+names the stdio form, as `bunx @ultimat3/cli mcp serve --transport stdio`, so a client that reads
+that file starts it with no setup; [MCP and AI](MCP-And-AI#client-config) says what to give one that does not.
+The **app's own tools** are `POST /mcp` on the app (`apps/web/mcp.ts`), mounted by `x dev` and the
+web role, refusing any request without a bearer token. The HTTP form below prints its token:
+
+```
+bunx x mcp serve --transport stdio              # a client that spawns the server
+bunx x mcp serve --transport http --port 9229   # POST /mcp; the bearer token is printed at boot
+```
+
+`stdio` and `http` are the two transports (`x help mcp`) — there is no `ws` transport, and this page
+told readers to configure one until 2026-08-23. Register the URL and the printed token with whatever
+MCP client you use; a request without the token is answered 401 with no catalog.
+
+The catalog is `bunx x mcp tools --json`: every tool's exact name and description, read off the
+server itself rather than counted here. The core of it:
+
+| Tool | Replaces the agent's usual guess |
+|---|---|
+| `routes.list` | grepping a router directory |
+| `schema.describe` | reading migration files in order |
+| `policies.list` | "is this endpoint protected?" |
+| `actions.describe` | reading `api/` by hand — actions and queries in one call |
+| `jobs.inspect` | reading `jobs.ts` for retry policy and step names |
+| `queue.depth` | guessing whether the worker is keeping up |
+| `manifest.read` | ten separate reads |
+| `errors.explain` | a web search for an error string |
+| `db.query` | inventing a query and hoping (read-only; 100-row default, 1000-row maximum) |
+| `db.migrate` | mutating the dev DB — writes land in a **branch DB only** |
+| `tests.run` | parsing terminal output |
+| `verify.run` | guessing whether the work is shippable |
+| `logs.tail` | scrollback archaeology |
+
+Read tools are unrestricted in dev; write tools are scoped to branch environments. The dev server is never exposed under `ROLE=web`. `db.query` refuses a batch, a write keyword anywhere at statement level (a data-modifying CTE included), a locking clause, `EXPLAIN ANALYZE`, and the banned function families matched by prefix (`pg_read_*`, `pg_ls_*`, `lo_*`, `pg_advisory_*`, `pg_sleep*`, `set_config`, …) — `X_MCP_QUERY_REJECTED`, before the host sees the string. Use `x mcp` for a standalone server (CI, remote agents). Editor config: Biome is the only formatter/linter — one binary, one config, no ESLint or Prettier.
+
+## Upgrading and removal
+
+| Task | Command |
+|---|---|
+| Framework version bump | `x upgrade --json`, one major per run ([CLI reference](CLI-Reference#x-upgrade)). An app below 30.0.0 has no such command yet: `bunx @ultimat3/cli@latest upgrade --json` |
+| Check what a bump would change | `x upgrade --dry-run --json`: the pins, the Bun floor edits and the section to read. Writes nothing, runs no gate |
+| Remove dev state (embedded PG, storage, caches) | `rm -rf .x` |
+| Remove the CLI | it ships with the app; deleting the repo is the uninstall |
+
+Framework ranges: an app declares every `@ultimat3/*` package at `^<version>`, as `x new` writes it, and `bun.lock` pins the exact build. Keep them on one version: the packages move in lockstep, and `x upgrade` moves them together. A third-party wrapper declares them as `peerDependencies` at `^<major>` ([Publish it](Building-Your-Own-Base#publish-it)).
+
+Version pinning: `As of 2026-11`, the Bun floor is the one stated at the top of this page and 2.0 the target; SolidJS 2 is in beta and is pinned exactly, and its upgrade is framework work, not app work. There is no ArkType or Drizzle pin to carry — `@ultimat3/schema` ships its own dependency-free validators and `@ultimat3/entity` its own `postgresDriver()`. Details and codemod inventory in [Upgrading](Upgrading). Boot failures and port conflicts in [Troubleshooting](Troubleshooting).