Home

Ultimate wiki

A full-stack, Bun-only, opinionated framework: Rails' philosophy applied to Bun + Postgres + SolidJS, where the primary user is an AI agent and the secondary user is a tired senior engineer working through their own AI agent and AI reviewer.

v1.0.0 As of 2026-08. 27 @ultimat3/* packages plus the unscoped create-ultimate — 28 in all — publish at 1.0.0 in lockstep to npm; the API is stable and semver applies from here (Upgrading). Milestones 0–10 are ✅; milestone 11 is 🚧, open on its two-platform deploy proof. No benchmark numbers exist yet — the 50k-socket forced-restart number is unmeasured, so every capacity figure in this wiki is a target, not a result. The marketing site is ultimate.developerz.ai; this wiki is the deeper reference.

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 owns milestone status, CHANGELOG.md owns the version, and VERIFY_STEP_NAMES in packages/cli/src/verify-step.ts owns the x verify step list.

bunx create-ultimate myapp && cd myapp && x dev

If you are	Read, in order
Evaluating it	Getting started → The eight primitives → FAQ
Building an app	Installation → Project layout → Actions → Testing
An agent driving the framework	CLI reference → Error codes → MCP and AI
Operating it	Configuration → Deployment → Troubleshooting
Contributing	Contributing → Project layout → Testing

Start

Page	What it covers
Getting started	zero to a running app, one action, one green x verify
Installation	prerequisites, x new, typed env, editor and MCP client setup
Project layout	the generated monorepo, the four surfaces, feature slices, the hard boundaries

The primitives

Page	What it covers
The eight primitives	entity, policy, action, mutator, query, job, route, task — the whole vocabulary
Actions	every field, the six generated artifacts, the mutator twin, contract tests
Entities and migrations	tables, invariants, tenancy, x db gen, drift, branch databases
Policies and authz	can(), where a policy is evaluated, denials, tenancy scoping
Queries and live queries	reads, live: true, per-row policy, bounded SQL
Jobs and workflows	transactional outbox, durable steps, idempotency, drivers
Scheduled tasks	cron with an explicit tz, leader election, next-run introspection
Routes and render modes	five render modes, hydration timing, budgets, enforced SEO

Capabilities

Page	What it covers
Realtime	channels → live queries → local-first, the pipeline, the reconnect problem
Caching and invalidation	four tiers, one tag graph, one-hop fanout
PWA and offline	generated sw.js, precache budgets, version skew
MCP and AI	the dev MCP server, every action as a tool, the llm() gateway, evals
Admin dashboard	the generated admin app and its MCP surface

Cross-cutting

Page	What it covers
I18n	flat catalogs, loud misses, locale routing, hreflang
Theming	semantic tokens as RGB channels, light + dark, no raw hex anywhere
Timezones and dates	store UTC, format with an explicit IANA zone, frozen clocks in tests
Money	Money = { minor, currency }, never a float
Testing	six test types, cloned databases, sealed network, x verify

Reference

Page	What it covers
CLI reference	every x command and flag, with --json examples
Error codes	every X_* code: meaning, cause, exact fix
Configuration	every app.config.ts field and every env var
Deployment	one image, six roles, drain, compose, Helm, targets
Upgrading	x upgrade, breaking-change detection, version skew
Troubleshooting	symptom → cause → fix
FAQ	why Bun only, why no GraphQL, is it production ready
Contributing	package layout, import tiers, conventions, PR expectations

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

Source docs live in the repo: the idea (why) and the architecture (how). The machine-readable map for agents is llms.txt.