# Ultimate wiki

**The full-stack framework where the primary developer is an AI agent.** Rails' philosophy on Bun + Postgres + SolidJS: everything is one of [eight primitives](/the-eight-primitives), and one `action` declaration projects into an HTTP route, an OpenAPI operation, a typed client, a job handle, an MCP tool and a test, all behind one `policy`. `x verify` is the contract: green means shippable.

```bash
bunx create-ultimate myapp && cd myapp && bun run setup && bun run dev
```

No Docker and no service: embedded Postgres, in-process NATS, local storage, a seeded database and a dev dashboard at `/_x`. `bun run setup` is not optional: `x new` installs nothing, so `x dev` straight after `cd` stops on `X_BUILD_FAILED` naming `bun install` → [Getting started](/getting-started) · [Bare VM](/bare-vm).

**Look first: [the live demo](https://social-media.ultimate.demo.developerz.ai)**, a social network deployed from `main` on every green push. Fabricated data, every row decided by a policy. Source: [`dummy/social-media-clone/`](https://github.com/developerz-ai/ultimate/tree/main/dummy/social-media-clone).

## Why pick it, and when not to

| Pick it when | Do not pick it when |
|---|---|
| an agent writes most of your code: one way per task, `--json` everywhere, every error a code, a cause and a `fix:` command | you need Node.js or Deno: Bun only |
| you want authz written once: one `policy` guards HTTP, live queries, jobs, MCP and admin | your database is not Postgres, or your UI is not SolidJS |
| you want jobs, realtime, auth, mail, storage, i18n, SEO, admin and MCP decided and gated | you deploy to Vercel functions, Lambda or Workers: containers only |
| the app may grow: the same code from one PaaS process to Kubernetes | you want a plugin API (an app wraps a primitive instead), or multi-node realtime proven today ([Known gaps](/known-gaps)) |

## Is it for a project this size

**Yes at both ends, and that is the design.** A homework assignment or a weekend idea gets a running app in four commands with nothing to install and nothing to choose; a very large product gets the scale ladder, the tier boundaries and the same 21-step gate the beginner's app already ran — the list is `VERIFY_STEP_NAMES` in [`packages/cli/src/verify-step.ts`](https://github.com/developerz-ai/ultimate/blob/main/packages/cli/src/verify-step.ts), whole or not at all. One framework, no lite mode — [axiom 1](#the-rules-everything-else-follows) forbids the second path a lite mode would be.

The measured version of that claim, with the command behind every number: [`docs/idea/21-the-range.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/21-the-range.md).

**Proof, each with a command:** what npm serves is `npm view @ultimat3/core version`; that every package is published and attested, `bun run scripts/registry-audit.ts --json` in the repository; the rolling-restart proof is `ci.yml`'s `deploy-proof` job; realtime recovery on one node is measured in [`scripts/bench/results/`](https://github.com/developerz-ai/ultimate/tree/main/scripts/bench/results) → [Realtime](/realtime). How each release was published, attestations included: [`PUBLISHING.md`](https://github.com/developerz-ai/ultimate/blob/main/PUBLISHING.md#publication-history). This wiki is the only public documentation surface.

Those facts are repeated on several pages because the wiki is plain markdown with no build step. Change them at the source first, then here: [`docs/idea/14-roadmap.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/14-roadmap.md) owns milestone status, [`CHANGELOG.md`](https://github.com/developerz-ai/ultimate/blob/main/CHANGELOG.md) owns the version, `scripts/bench/results/` owns the benchmark, and `VERIFY_STEP_NAMES` in [`packages/cli/src/verify-step.ts`](https://github.com/developerz-ai/ultimate/blob/main/packages/cli/src/verify-step.ts) owns the `x verify` step list.

| If you are | Read, in order |
|---|---|
| Evaluating it | [Getting started](/getting-started) → [Bare VM](/bare-vm) → [The eight primitives](/the-eight-primitives) → [FAQ](/faq) |
| Moving a production app off another stack | [Migrating an existing app](/migrating-an-existing-app) → [Known gaps](/known-gaps) → [Entities and migrations](/entities-and-migrations) |
| Building an app | [Installation](/installation) → [Project layout](/project-layout) → [Actions](/actions) → [Testing](/testing) |
| An agent driving the framework | `x docs "<question>"` first, offline from the install → [CLI reference](/cli-reference) → [Error codes](/error-codes) → [MCP and AI](/mcp-and-ai) → [Agents](/agents) |
| Operating it | [Configuration](/configuration) → [Deployment](/deployment) → [Observability](/observability) → [Troubleshooting](/troubleshooting) |
| Deciding whether to trust it | [Known gaps](/known-gaps) → [FAQ](/faq) → [Stability](/stability) → [Upgrading](/upgrading) |
| Contributing | [Contributing](/contributing) → [Project layout](/project-layout) → [Testing](/testing) |

## Start

| Page | What it covers |
|---|---|
| [Getting started](/getting-started) | zero to a running app, one action, one green `x verify` |
| [Installation](/installation) | prerequisites, `x new`, typed env, editor and MCP client setup |
| [Bare VM](/bare-vm) | the four commands a fresh Ubuntu box with bun and git runs, and why no Docker and no service is needed |
| [Project layout](/project-layout) | the generated monorepo, the four surfaces, feature slices, the hard boundaries |
| [Migrating an existing app](/migrating-an-existing-app) | strangler fig off Rails/Node/Django, adopting a live schema, identity during cutover, and what does not work yet |
| [Compared](/compared) | each stack this gets compared to: when to pick it instead, what you give up here, and the measured figures with the commands that reproduce them |
| [Shapes](/shapes) | `x new --shape api`, `blog` and `dashboard`: what each writes and what it leaves out |

## Tutorials

Follow in order. Each page states what it was executed against in its own first line — tutorial 1 its own measurement. `As of 2026-11-03`, 2–4 were re-run by hand, whole, in the app tutorial 1 leaves, and 5 with Docker up to the point a real host is needed. `scripts/tutorial-run.ts` (workflow `tutorial-run.yml`, on `main`) runs 1–4 in order and never 5; it has not yet run green. A workaround for a gap fixed since has been removed rather than left to mislead.

| Page | You end with |
|---|---|
| [1 · First app](/tutorial-01-first-app) | a scaffolded app running on `x dev`, green gate, no Docker |
| [2 · First feature](/tutorial-02-first-feature) | one `action` projected into five surfaces, with tests |
| [3 · Auth and admin](/tutorial-03-auth-and-admin) | roles, policies, a real login flow, and the admin's detail pages, actions and batches |
| [4 · Jobs and realtime](/tutorial-04-jobs-and-realtime) | a durable job, a cron task, a live query |
| [5 · Deploy free](/tutorial-05-deploy-free) | the image running on a free PaaS tier, migrations on release |
| [6 · Growing up](/tutorial-06-growing-up) | the rung you should be on, and the signal to climb |

## The primitives

| Page | What it covers |
|---|---|
| [The eight primitives](/the-eight-primitives) | `entity`, `policy`, `action`, `mutator`, `query`, `job`, `route`, `task` — the whole vocabulary |
| [Building your own base](/building-your-own-base) | wrap a primitive in your own factory: `tenantEntity`, `auditedMutator`, the two caveats, and why nothing downstream notices |
| [Actions](/actions) | every field, the six generated artifacts, the mutator twin, contract tests |
| [Entities and migrations](/entities-and-migrations) | tables, invariants, tenancy, the typed-handle repo, `.sealed()` columns, `x db gen`, the schema dump, drift, branch databases |
| [Policies and authz](/policies-and-authz) | `can()`, where a policy is evaluated, denials, tenancy scoping |
| [Queries and live queries](/queries-and-live-queries) | reads, `live: true`, per-row policy, bounded SQL |
| [Jobs and workflows](/jobs-and-workflows) | transactional outbox, durable steps, idempotency, keyed concurrency, `onSettled`, operating a queue, `webhook()`, drivers |
| [Scheduled tasks](/scheduled-tasks) | cron with an explicit tz, leader election, next-run introspection |
| [Routes and render modes](/routes-and-render-modes) | five render modes, hydration timing, budgets, enforced SEO |

## Capabilities

| Page | What it covers |
|---|---|
| [Realtime](/realtime) | channels → live queries → local-first, the pipeline, the reconnect problem |
| [Caching and invalidation](/caching-and-invalidation) | four tiers, one tag graph, one-hop fanout |
| [Batching and preloading](/batching-and-preloading) | JIT preload, `.preload()`, `insertAll`/`upsertAll`/`updateWhere`, `inBatches`, the tenancy guarantee |
| [N+1 detection](/n-plus-one-detection) | the two codes, `expectedQueryLoop`, four surfaces, why prod pays nothing |
| [PWA and offline](/pwa-and-offline) | generated `sw.js`, precache budgets, version skew |
| [Client data](/client-data) | the one browser transport (`browserClient`, `useQuery`), the record store, and the gate that refuses a raw `fetch(` |
| [Client navigation](/client-navigation) | soft navigation over server-rendered pages: one config line per surface, swap, prefetch, history, focus |
| [MCP and AI](/mcp-and-ai) | the dev MCP server, every action as a tool, the `llm()` gateway, evals |
| [Agents](/agents) | `agent()` as an action factory, tools as real actions, `hive()`, `agentJob()`, and the at-least-once trap |
| [Admin dashboard](/admin-dashboard) | `defineAdmin()` serving list, detail and form per entity with no host code; filters, scopes, sections, related rows, actions with `when` and `batch`, the audit log, the jobs dashboard; zero JavaScript; its MCP surface |
| [Scraping](/scraping) | `scrape()` as a job factory, the driver-blind page vocabulary, robots and host gates, per-run egress, a rented CDP browser, usage, sealed sessions, mid-run prompts |
| [Auth](/auth) | sessions, OAuth, MFA, API keys and service tokens — the output is an `Actor` |
| [Mail](/mail) | one template renders HTML and text, every string a key, sending is a job |
| [Notify](/notify) | `notifier()` as a job factory: fan-out, preference gate, digest window, ledger, inbox |
| [Storage and uploads](/storage-and-uploads) | named disks, safe keys, the three-call signed upload, upload scanning, orphans |
| [Feature flags](/feature-flags) | permanent switches and temporary ones that cannot be forgotten |
| [SEO](/seo) | enforced meta, typed JSON-LD, sitemaps, fail-closed robots, feeds, responsive images |

## Cross-cutting

| Page | What it covers |
|---|---|
| [I18n](/i18n) | flat catalogs, loud misses, locale routing, `hreflang` |
| [Theming](/theming) | 24 semantic colour roles as RGB channels, every token scale, breakpoint and layout mixins, `defineTheme()`, what contrast is gated |
| [Interface rules](/interface-rules) | how a screen must behave, and which of the app's `guards/` refuses each rule |
| [UI components](/ui-components) | the four page composites, and the generated UI component catalog |
| [Timezones and dates](/timezones-and-dates) | store UTC, format with an explicit IANA zone, frozen clocks in tests |
| [Money](/money) | `Money = { minor, currency }`, never a float |
| [Outbound HTTP](/outbound-http) | `outbound()`: one vendor call with a whole-call deadline, the caller's signal, safe-only retry, idle and byte bounds, `dial: 'public'` pinning, and `breaker()` |
| [Resource management](/resource-management) | `Disposable` db resources, `using`/`await using`, idempotent release, compile-time pins |
| [Migrations and backfills](/migrations-and-backfills) | one migration engine and ledger, concurrent index builds and drops outside a transaction, the destructive-migration rail, `backfill()` as a `job` factory |
| [Testing](/testing) | six test types, cloned databases, sealed network, the coverage floor, silent runs, `x verify` |

## Reference

| Page | What it covers |
|---|---|
| [CLI reference](/cli-reference) | every `x` command and flag, with `--json` examples |
| [Error codes](/error-codes) | every `X_*` code: meaning, cause, exact fix |
| [Configuration](/configuration) | every `app.config.ts` field and every env var |
| [Adapters](/adapters) | every swappable backend — one `runtime.ts` field each: the interface, the reference to copy, the conformance suite, the default |
| [Deployment](/deployment) | one image, six roles, `ROLE`/`PORT`, drain, compose, Helm, targets, the prebuilt island store, `docs/ops/` |
| [Deploy recipes](/deploy-recipes) | per host — Compose, the chart, Fly.io, Render, Railway, Heroku, bare VM — the build source, port, health path, release command and services, each marked executed or not |
| [Observability](/observability) | counters, gauges, histograms, process and pool gauges, `MetricExporter`, the Prometheus body, `/metrics` on its own port, and what the chart still cannot reach |
| [Known gaps](/known-gaps) | every defect and unfinished seam in the published release, named |
| [Upgrading](/upgrading) | one section per major with every manual edit, the newest first, each as a checklist, version skew — and how `x upgrade` walks them, one major per run |
| [Stability](/stability) | what semver covers and what it does not, one major per 90 days from v30, the support window, deprecation, the security exception |
| [Troubleshooting](/troubleshooting) | symptom → cause → fix |
| [FAQ](/faq) | why Bun only, why no GraphQL, is it production ready |
| [Contributing](/contributing) | a pointer: `CONTRIBUTING.md` is the one contributor guide |

## The rules everything else follows

| Axiom | Consequence |
|---|---|
| One way to do each thing | no adapter zoo, no `mode:` escape hatches. Removing an alternative is a feature |
| Define once, project everywhere | one `action` → HTTP route + OpenAPI + typed client + job handle + MCP tool + tests |
| Enforced, not documented | a convention that isn't a build error doesn't exist |
| Errors are instructions | stable `X_*` code + cause + exact fix command + `--json` |
| One command means shippable | `x verify` green = deployable |
| The static path never pays for the app path | `site/` cannot import `app/`; 0kb JS is structural |
| Deploy anywhere = containers only | zero platform primitives |
| Ultimate ships mechanism; your app ships convention | mechanisms and structural conventions ship; business conventions never do. Tenancy ships, an org model does not — primitives are functions returning values, so an app wraps one → [Building your own base](/building-your-own-base) |
| Useful, then efficient | working function first, bytes second. A budget is a measurement, not a ceiling to game: raise it by the measured amount, with the reason, rather than cut a feature. The static path still pays nothing for the app path |

## Source docs in the repo

| Where | What it is |
|---|---|
| [`docs/idea/`](https://github.com/developerz-ai/ultimate/tree/main/docs/idea) | **why** — the design spec |
| [`docs/architecture/`](https://github.com/developerz-ai/ultimate/tree/main/docs/architecture) | **how** — the internals |
| [`docs/ops/`](https://github.com/developerz-ai/ultimate/tree/main/docs/ops) | running an app for real: the PaaS → Compose → Kubernetes ladder, secrets, observability, datastore sizing, disaster recovery, runbooks. **Recommendations only** — the framework depends on none of it |
| [`docs/idea/16-app-targets.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/16-app-targets.md) | three targets, one backend, two view layers — **design only, not shipped behaviour** |
| [`docs/idea/17-scale-ladder.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/17-scale-ladder.md) | why the app code is identical at rung 0 and rung 4 — **shipped, not design only**: 24 of its 26 seam rows are marked shipped, rungs 0–2 are real, and the places the invariant breaks today are named |
| [`packages/ui/CATALOG.md`](https://github.com/developerz-ai/ultimate/blob/main/packages/ui/CATALOG.md) | the full component catalog with every prop, generated from source and drift-tested |
| [`framework.manifest.json`](https://github.com/developerz-ai/ultimate/blob/main/framework.manifest.json) | every package, tier, and `X_*` code with its owner — generated |
| [llms.txt](https://github.com/developerz-ai/ultimate/blob/main/llms.txt) | the machine-readable repo map for agents |