Why Ultimate exists, what it locks down, and what it refuses to build. Read 00-thesis.md first; everything else expands one axiom.
| Doc | Hook |
|---|---|
00-thesis.md |
Rails' philosophy, but the primary developer is an AI agent — plus the inspire-explicitly table and the 8 axioms. |
01-stack.md |
One locked choice per layer; Bun natives delete ~40 dependencies before you write a line. |
02-primitives.md |
Eight primitives. action projects to six artifacts. Two authz systems is how every Meteor-like framework died. |
03-realtime.md |
Channels → live queries → local-first: a ladder, not three products. Tier 2 → 3 is persist: true on a query — never a config key: realtime.tier was read by nothing and was deleted in 10.0.0. |
04-jobs.md |
Transactional outbox by default, durable steps, idempotency key required by the type. |
05-caching.md |
Four tiers, one invalidation graph. invalidates: [tag.post] reaches memo, LRU, Redis, ISR, and the CDN in one hop. |
06-surfaces.md |
site/ cannot import app/ — a build error, because that import is how marketing pages ship charting libraries. |
07-rendering-seo.md |
Five render modes; stream is the app default. SEO is enforced, not documented. |
08-pwa-offline.md |
sw.js is emitted, never hand-edited. Version skew is what actually breaks PWAs. |
09-ai-first.md |
The differentiator: MCP dev server, generated facts, and apps whose own dashboards expose MCP. |
10-testing.md |
One cloned Postgres database per worker, sealed network, frozen clock. Parallel is opt-in, and says so. |
11-topology.md |
One image, six roles, graceful drain that redistributes sockets instead of stampeding. |
12-build-deploy.md |
x build --target docker|binary|static. Deploy target = "runs containers". Nothing else. |
13-dx.md |
First 60 seconds: no Docker, no env scavenger hunt, sub-second HMR that keeps state. |
14-roadmap.md |
12 milestones, each ending in a working demo app + green x verify. Ship 0–5 before realtime. |
15-risks.md |
Six risks, honestly sized. The sync engine is ~70% of the effort. |
16-app-targets.md |
Web, mobile, desktop from one definition. A screen is a route, not a ninth primitive. Design only. |
17-scale-ladder.md |
PaaS to distributed in five rungs, where climbing is config and drivers — never a rewrite. Rungs 0–2 are real and 24 of the 26 seam rows are shipped; the doc names every place the invariant breaks today. |
18-build-vs-wrap.md |
Own the integration layer, wrap the protocol layer. Verdicts: jobs BUILD, SMTP BUILD, NATS WRAP — adopted, nats@2.29.3 at the transport seam. |
19-mechanism-not-convention.md |
Axiom 8. Mechanisms and structural conventions ship; business conventions never do. Tenancy ships, an org model does not — the app wraps. |
20-large-app-readiness.md |
The capability axis: what a very large app already gets, and whether a company can plug its own infrastructure in. The primitives are enterprise-grade; the dominant defect is a mechanism built, exported, and never called by the boot — the outbox, the scheduler watermark, the shared cache tier, WebSocket auth. |
21-the-range.md |
Who it is for, and the range: a homework assignment to a very large product, one framework, no lite mode. The small end measured As of 2026-09 (0 questions, 151 files, 4 commands, and the scaffold's own bin/setup && bin/check green on the first pass — no waiver, no fix-follow, asserted on an ubuntu-latest runner by ci.yml's scaffold-smoke job); the large end anchored to the ladder, the tiers and the gate; and why enforced conventions pay MORE with a cheap model. |
| You are | Read |
|---|---|
| Deciding whether it fits a project this size | 21 — the range, homework to very large, with the small end measured and the large end anchored |
| Evaluating the idea | 00 → 21 → 01 → 02 → 15 |
| Implementing a package | 02 → the doc for your primitive → 10 |
| Judging shippability | 14 → 10 → 12 |
| Here for the AI story | 09 → 02 → 13 |
| Operating it | 11 → 12 → 08 |
| Deploying and scaling | 17 → 12 → 11, then docs/ops/ for the runbooks. Start at rung 0: a free PaaS plan, no card |
| Building for mobile or desktop | 16 → 02 → 06. Design only — no package, no build target, no gate step exists yet |
| Adopting it for a very large product | 21 → 20 → 19 → 17. 20 is the capability axis — what is built but uncalled, and which seams take your own drivers; 19 is the rule it scores against; 17 is the deployment one |
Bun-only, opinionated, full-stack. Postgres with no ORM, SolidJS pinned at 1.9.14 (the stable line — 01-stack.md), SCSS modules + tokens, Standard Schema behind a dependency-free builtin provider, Better Auth. Eight primitives — entity policy action mutator query job route task — and nothing else ships. One action declaration projects to an HTTP route, an OpenAPI operation, a typed client function, a job handle, an MCP tool, and a test scaffold, all sharing one authz system. Realtime is a three-rung ladder with the same mutator shape at every rung. Jobs are durable steps enqueued through a transactional outbox. Caching is four tiers behind one tag graph. site/ cannot import app/ — build error. SEO, budgets, migration drift, and import boundaries are build failures, not guidelines. x verify green means shippable. Deploy target = anything that runs containers.
| # | Axiom |
|---|---|
| 1 | One way to do each thing. |
| 2 | Define once, project everywhere. |
| 3 | Enforced, not documented. |
| 4 | Errors are instructions. |
| 5 | One command means shippable. |
| 6 | Static path never pays for the app path. |
| 7 | Deploy anywhere = containers only. |
| 8 | Ultimate ships mechanism; your app ships convention. |
Consequences of each in 00-thesis.md; axiom 8 in full in 19-mechanism-not-convention.md.
As of 2026-08-23: repository, tag and registry all agree. The release ran. Resolve every row below rather than believing it — a version in a doc is a snapshot, a command is not, and bun run scripts/registry-audit.ts --json checks the whole table in one call. No row here names a version; every one names the command that answers it.
| Fact | State | Read it yourself |
|---|---|---|
| Versioned | 30 @ultimat3/* packages plus the unscoped create-ultimate — 31 in all — in lockstep, one commit. Every major so far has been a correctness sweep with no codemod, so each BREAKING — entry names its own manual edit |
bun run scripts/list-workspaces.ts --json for what the tree is stamped at; bun run scripts/release.ts --check <version> to assert it. Per-major counts: wiki/Upgrading.md, each read from its own CHANGELOG.md section by bun run changelog-check |
| Tagged | the tag is on origin annotated, and its GitHub Release is published — that Release is what triggers the workflow. git push --follow-tags pushes annotated tags only, so a git tag with no -a never leaves the machine |
git ls-remote --tags origin 'refs/tags/v<version>*' — expect the ref and its peeled ^{} line; then gh release view v<version> --json tagName,isDraft,publishedAt (isDraft: false, publishedAt non-null). git tag --list reads the local repository and cannot tell you either |
| Published | latest is what bunx create-ultimate myapp installs |
npm view @ultimat3/core version |
| Publication holes | none. All 31 workspaces are on the registry at the stamped version. This row and the two npm rows are what the audit covers; the tag and Release rows it does not ask about at all. @ultimat3/scraping was the last never-published package and was bootstrapped by hand at 2.0.0, exactly as @ultimat3/flags had been — the one-time step in PUBLISHING.md that every package needs before a trusted publisher can attach |
bun run scripts/registry-audit.ts --json — it resolves the derived list against npm and names each gap with a runnable fix: |
| Provenance | every tarball from 3.0.0 on carries an attestation and _npmUser: GitHub Actions; 2.0.0 carries neither, having gone out by hand |
npm view @ultimat3/core dist.attestations, npm view @ultimat3/core@2.0.0 dist.attestations |
| OIDC trusted publisher | attached to all 30 on 2026-08-19, with Environment: npm-publish — that attachment is what lets the workflow publish at all, and its absence is why 2.0.0 has no provenance. Not the first ever: 1.1.0 and 1.2.0 published under earlier publisher configurations (a different oidcConfigId per package) |
NPM_CONFIG_OTP=<code> bun run scripts/trust-publishers.ts --check --json — every package, and without a fresh code they all read as missing. Per version: npm view @ultimat3/core@1.2.0 _npmUser.trustedPublisher |
| Release approval | the workflow stops at waiting on the npm-publish environment until a named reviewer approves the pending deployment — the last point an irreversible publish can be stopped |
gh run view <id> --json status |
Docs 00–15 and 18–21 describe what exists. 16 is the only design-only doc and says so in every claim; 17 is not — it states rung by rung which rungs are real (0–2) and names where the "no app code change" invariant breaks today, which is why the index row above and wiki/Home.md both call it shipped.
Milestone order and the "done when" bar for each live in 14-roadmap.md; the honest accounting of what could kill the project is in 15-risks.md — read it before the roadmap, not after.
| Convention | Meaning |
|---|---|
| Code blocks | canonical API shapes; they match the framework's contract byte-for-byte |
X_* |
a stable error code with a cause, a fix command, and a docs page |
As of 2026-07 |
a claim about the outside world that has a shelf life |
| "build error" | literal — x verify and the dev server both fail |