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.1.0 As of 2026-08. 27 @ultimat3/* packages plus the unscoped create-ultimate — 28 in all — publish in lockstep to npm; the API is stable and semver applies from here (Upgrading). 1.1.0 is the first release published by the workflow, over OIDC trusted publishing with no NPM_TOKEN and provenance attached; 1.0.0 was the manual bootstrap. Milestones 0–10 are ✅; milestone 11 is 🚧, still open on the two-platform deploy proof — 1.1.0 gave a scaffolded app a real deployable artifact, which is progress toward it, not the proof.

The realtime restart number is now measured and committed (scripts/bench/results/50k-restart.json): 50,000 real WebSocket clients against a single sync node over InProcessTransport, SIGKILLed with no drain — all 50,000 reconnected, 49,981 received a channel patch inside the window, time-to-consistent p50 54.0s / p90 105.5s / max 145.7s, and 156,851 connect attempts shed by the AcceptBudget before any query path. It is per-node recovery: the run never crossed NATS, so it is not a multi-node result and not a throughput figure → Realtime. This wiki is the only public documentation surface; there is no separate site.

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, scripts/bench/results/ owns the benchmark, 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 → Observability → Troubleshooting
Deciding whether to trust it	Known gaps → FAQ → Upgrading
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

Tutorials

Follow in order. Every command and every output was executed against the published 1.1.0 packages, and each page names the gaps it hits and the workaround.

Page	You end with
1 · First app	a scaffolded app running on x dev, green gate, no Docker
2 · First feature	one action projected into five surfaces, with tests
3 · Auth and admin	roles, policies and a real login flow
4 · Jobs and realtime	a durable job, a cron task, a live query
5 · Deploy free	the image running on a free PaaS tier, migrations on release
6 · Growing up	the rung you should be on, and the signal to climb

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	24 semantic colour roles as RGB channels, every token scale, defineTheme(), what contrast is gated
UI components	the four page composites, and the generated 46-component catalog
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, ROLE/PORT, drain, compose, Helm, targets, docs/ops/
Observability	counters, gauges, histograms, MetricExporter, the Prometheus body, /metrics on its own port, and what the chart still cannot reach
Known gaps	every defect and unfinished seam that shipped in 1.1.0, named
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 in the repo

Where	What it is
docs/idea/	why — the design spec
docs/architecture/	how — the internals
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	three targets, one backend, two view layers — design only, not shipped behaviour
docs/idea/17-scale-ladder.md	why the app code is identical at rung 0 and rung 4 — design only, not shipped behaviour
packages/ui/CATALOG.md	all 46 components with every prop, generated from source and drift-tested
framework.manifest.json	every package, tier, and X_* code with its owner — generated
llms.txt	the machine-readable repo map for agents