@ultimat3/cli 29.3.2 → 30.0.0

package/wiki/FAQ.md

@@ -0,0 +1,175 @@
+# FAQ
+
+Honest answers. Where something is not built yet, it says so.
+
+## Status
+
+### Is it production ready?
+
+**Yes, for a single-region app on one Postgres, `As of 2026-11`, on the evidence below.** What you can check: [the live demo](https://social-media.ultimate.demo.developerz.ai), built from `dummy/social-media-clone/` and deployed on every push to `main` (`deploy-social-demo.yml`). Two apps in the repository build on it and gate on every push, the demo and the reference app `examples/dummy/` (`scripts/lib/gated-apps.ts`); no production use and no outside adopter is claimed. The API is under semver, and the window and the next major's date are on [Stability](Stability).
+
+| Proven | By |
+|---|---|
+| a rolling restart on Kubernetes drops no request | `ci.yml`'s `deploy-proof` job, `docker/deploy-proof/run.sh`: 0 of 9,028 requests failed, `As of 2026-09-24` |
+| a fresh scaffold is green on its first gate run | `ci.yml`'s `scaffold-smoke` job, every push |
+| every package is on npm at one version, published by the workflow over OIDC, attested | `bun run scripts/registry-audit.ts --json`, and `registry-audit.yml` daily |
+| one `sync` node reconnects all 50,000 clients after a forced restart | [`scripts/bench/results/`](https://github.com/developerz-ai/ultimate/tree/main/scripts/bench/results) |
+
+What you can install is `npm view @ultimat3/core version`; only the [footer](_Footer) stamps it. How each release was published, the hand-published 2.0.0 included: [`PUBLISHING.md`](https://github.com/developerz-ai/ultimate/blob/main/PUBLISHING.md#publication-history).
+
+What it does **not** claim:
+
+| Not claimed | Detail |
+|---|---|
+| A multi-node realtime result | the 50k forced-restart benchmark **is** measured and committed, but on **one** `sync` node over `InProcessTransport` — it never crossed NATS. Fanout across nodes, throughput, and per-node socket capacity are all still targets, not results ([Realtime](Realtime)) |
+| A rolling restart on **Compose** | Compose is the single-node rung: one published port has one binder, so a restart there is a restart. The invisible-restart proof is Kubernetes only ([Deployment](Deployment)) |
+| Not shipped, `As of 2026-09-23` | the plugin API, multi-region replication, and the Redis **job** driver — all behind the interfaces that ship today (there is no NATS job driver since 25.0.0). The Redis driver throws `X_NOT_IMPLEMENTED` with a runnable `fix:` line rather than pretending to work |
+
+### What is actually finished?
+
+All 30 packages, implemented and tested — not skeletons. The eight primitives, HTTP, rendering, caching, realtime tiers 1–3 (tier 3 opt-in, since 21.0.0), auth, mail, storage, jobs, the AI-first surface (MCP, `llm()`, evals), and admin + generators + `x new`. Milestones 0–11 are ✅ and enforced by `x verify`'s `roadmap` step; milestone 11's deploy proof closed `As of 2026-09-24`, when `ci.yml`'s `deploy-proof` job upgraded an app in kind with 0 of 9,028 requests failed (Compose is the single-node rung and makes no invisible-restart claim). Each milestone ends in a **working demo app plus green `x verify`**, and the same demo app grows through all twelve. [`docs/idea/14-roadmap.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/14-roadmap.md) is the source of truth for those markers.
+
+### What is left?
+
+**No milestone is open**: milestone 11's two-platform deploy proof closed `As of 2026-09-24` (`deploy-proof`, above). The other item that was open at 1.0.0, the **50k-socket forced-restart benchmark**, is measured and committed at 1.1.0: 50,000 sockets, forced `sync` restart, first patch on the reconnected socket at p50 54.0s / p90 105.5s, on one node ([Realtime](Realtime)). Everything in milestones 0–11 is shipped and gated. Scope cuts come off the back, never the middle (M4's budgets). The open defects the current release shipped with are listed on [Known gaps](Known-Gaps).
+
+## The stack
+
+### Why Bun only?
+
+Portability costs a lowest-common-denominator API. Bun-only makes `Bun.sql`, `Bun.redis`, `Bun.s3`, `Bun.serve` WebSockets, `Bun.build`, and `bun test` **language features** instead of dependencies — roughly a thousand transitive packages that never enter the lockfile. Target: under 40 direct dependencies for the whole framework.
+
+### Why no Node or Deno support?
+
+Multi-runtime means every native gets an adapter, every adapter gets a second behavior, and the second behavior is where bugs live. It would also make the WebSocket cost model — the thing `sync`'s economics depend on — a per-runtime variable. Stated cost: no native-addon packages, and long-running Bun processes are less battle-proven than Node's.
+
+### Why no GraphQL?
+
+A second schema language, a second authz surface, and a resolver-shaped N+1 factory. Typed `action` + `query` cover the need, and `openapi.json` is generated from them. One authz system is the whole point ([Policies and authz](Policies-And-Authz)).
+
+### Why no Tailwind?
+
+Tailwind plus modules plus CSS-in-JS in one repo is three token systems and three ways to theme. SCSS modules + design tokens is build-time only, zero runtime, and dark theme is a token flip. See [Theming](Theming).
+
+### Why no React, and no RSC?
+
+Wrong runtime for RSC, and the mental model taxes exactly the audience being optimized for. Solid's fine-grained reactivity makes streaming shells cost ~0 hydration, and `stream` + `<Hole>` gets the same payoff with no new component dialect.
+
+### Why SolidJS and your own router?
+
+The router must own render mode, offline strategy, and metadata — those are framework concerns, so it cannot be a third-party dependency that disagrees with the build. `As of 2026-08` the pin is **`solid-js@1.9.14`, the stable line**: Solid 2 is still pre-release (`2.0.0-beta.N`, DOM renderer split out into `@solidjs/web`), and every app inherits whatever reactive core this repo pins, so a beta core is a risk handed downstream. The ecosystem around Solid is thin either way, which is why the UI kit is ours too.
+
+### Which schema library?
+
+None. `@ultimat3/schema` ships its own dependency-free validators (`vendor: 'ultimate'`), exposed as `t`. One schema drives runtime parse, TS type, OpenAPI, and the MCP tool's JSON Schema.
+
+Everything sits behind the Standard Schema v1 interface, so the default is swappable at the framework level — not per app. No ArkType, Zod or Valibot adapter ships; swapping to one means writing the ~40-line `configureSchemaProvider()` adapter yourself ([`packages/schema/README.md`](https://github.com/developerz-ai/ultimate/blob/main/packages/schema/README.md)). A dependency the framework does not need is a dependency every app pays for.
+
+## Design decisions people push back on
+
+### Why is `idempotencyKey` required on every job?
+
+At-least-once is the only honest guarantee any queue provides, so every handler must be replay-safe. "Remember to add a key" is exactly the instruction that gets dropped under pressure — by a human at 2am and by an agent always. Making it a required field converts a duplicate-charge incident into a red squiggle. Keys derive from `input` only: no timestamps, no random, no `ctx`.
+
+### Why is every action an MCP tool?
+
+Because the alternative is two authorization systems. An MCP call and an HTTP call reach the same `policy` with the same actor resolution — no MCP permission table, no "trusted tool" mode, no broad-rights service account. Actions still opt in per-action with `mcp: { expose: true }`; what is not optional is that exposure reuses the existing authz.
+
+### Why does `x verify` block on budgets and SEO?
+
+A convention that isn't a build error doesn't exist. A missing `description`, a blown JS budget, or a drifted migration is discovered in production otherwise — usually by someone who did not write the change. `x verify --json` names the route, the metric, the actual value, and the import chain that caused it.
+
+### Is `x verify` really the only gate?
+
+Yes. CI runs exactly `x verify` — no bespoke pipeline steps, because a check that lives only in CI is a check you cannot run locally. All 21 steps, in this order: typecheck, lint, boundaries, filesize, package-shape, errors, unit, contract, live, job, exercise, e2e, eval, drift, contract-diff, budgets, seo, i18n, policy, manifest, roadmap. No `--skip`; `--only <step>[,<step>…]` is an iteration loop that prints `NOT A GATE RUN`. See [Testing](Testing).
+
+### Why are there only eight primitives?
+
+`entity`, `policy`, `action`, `mutator`, `query`, `job`, `route`, `task`. If a feature doesn't fit one of them, it doesn't ship. A push notification is a `job`; a share target is a `route` with a policy; an admin screen is a `query` plus actions. No PWA-specific or realtime-specific concept escapes into your mental model.
+
+## Running it
+
+### Do I need Docker to develop?
+
+No. `x dev` uses embedded PGlite, in-process events, and a local directory in place of S3. `bunx create-ultimate myapp && cd myapp && bun run setup && bun run dev` — no Docker install, no `.env` scavenger hunt. `bun run setup` is six steps — `bun install`, an `.env.development.local` touch, `x db gen "initial"`, `x db migrate`, `x db seed`, `x manifest` — and is not optional: `x new` installs nothing ([Getting started](Getting-Started), [Bare VM](Bare-VM)). The compose files exist for parity debugging and CI jobs that want real services ([Deployment](Deployment)).
+
+### Do I need Redis or NATS?
+
+No. Postgres covers the job queue (`SELECT ... FOR UPDATE SKIP LOCKED`) and pubsub, and a local volume covers files. Redis is a cache tier you opt into; NATS is fanout you need once `sync` runs on more than one node. Both are drivers behind one interface — job code and query code never change.
+
+### Can I deploy serverless or to the edge?
+
+No, by design. Containers only. Edge runtimes, function-per-route, and vendor KV/queue/cron primitives would each need a second implementation of a framework primitive, and the second implementation is where behavior diverges. Requirement: something that runs containers, plus Postgres.
+
+### How much infrastructure does a small app need?
+
+One container running `ROLE=web` and one Postgres — there is **no** `ROLE=all`, and `x dev` is what co-locates roles locally. Split roles when a signal tells you to: RPS for `web`, connection count for `sync`, queue demand (jobs held plus jobs due) for `worker`. `scheduler` and `replicator` are fixed at one replica — a second is a warm standby, not throughput.
+
+### Can I use it without the realtime tiers?
+
+Yes. `realtime: { enabled: false }` in `app.config.ts` is the opt-out (its default: [Configuration → `realtime`](Configuration#realtime)), and there is no tier key to set — a tier is what your app **declares** (a `channel()` topic, a `live: true` query), never a config value. An app that declares none needs no `sync` role, no `replicator`, and no NATS. That is a complete product without any realtime at all: entities, actions, a typed client, five render modes, a 0kb static path, and durable jobs.
+
+## Risk
+
+### What happens if the sync engine doesn't work out?
+
+It is roughly **70% of total effort** and the single largest risk. Tiers 1–2 shipped in milestone 6 and are under semver; tier 3 local-first shipped in 21.0.0, opt-in per entity (`entity(name, { persist: true })`). The reconnect benchmark that gated topology — 50k sockets, a forced `sync` restart, recovery time and DB load — **is measured at 1.1.0**: all 50,000 reconnected, 49,981 received a channel patch inside the window, p50 54.0s / p90 105.5s, 156,851 connect attempts shed before any query path ([Realtime](Realtime)). That is **reachability** — first patch on the reconnected socket — not consistency; the delivery half is a separate 10,000-client run, **1,666,882 patches received, 0 observed sequence gaps** — a lower bound, since a hole is only visible between two frames one connection received ([Realtime](Realtime)) — and `As of 2026-08` the only run that counts lost patches at all. Both were run on **one** node, so multi-node fanout is still unproven. If the incremental matcher turns out to be the bottleneck, wrapping an existing protocol (Zero's) is an accepted fallback.
+
+### Why ship realtime last if it's the differentiator?
+
+A half-built sync engine is worth nothing: it cannot be shipped partially, demoed honestly, or tested against a real app, and it consumes the attention everything else needs. Starting there is how this project would die with 40 packages and no users.
+
+### What if Bun has a problem under sustained load?
+
+Stated risk, not a hidden one. `As of 2026-08` long-running Bun processes are less proven than Node's, so memory profiling under sustained socket load is explicit roadmap work. See [`docs/idea/15-risks.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/15-risks.md).
+
+## Scope
+
+### Where do plugins fit?
+
+Nowhere — there is no plugin API and there has never been one, `As of 2026-08`. Semver covers the documented surface, not internals, and a plugin API freezes internals permanently. Fork the blessed path if you need something else; extension points earn their existence from real forks, not from speculation.
+
+### Can I publish a package for other Ultimate apps?
+
+Yes: a factory over the eight primitives, published as `ultimate-<name>` with the keyword `ultimate-package` and `@ultimat3/*` as `peerDependencies` at `^<major>`. There is no marketplace or registry; `npm search keywords:ultimate-package` is the directory. How, and what a consumer's gate sees: [Building your own base](Building-Your-Own-Base#publish-it).
+
+### Does Ultimate collect anything?
+
+Nothing in `x` is written to: no telemetry, analytics, crash report or update check. What the gate proves is narrower, and exactly this: every host a non-test file in `packages/cli/src` spells is either a reserved name (`.invalid`, `.test`, `example.com`, `localhost`) or a row with its reason in `CLI_OUTBOUND_ALLOWLIST` (`scripts/cli-outbound.ts`), and a new one fails the gate's `boundaries` step with `X_CLI_OUTBOUND_UNDECLARED`. It reads literals only, in the CLI's own source: a host assembled at run time, and the other packages, are not covered. The network `x` does touch is the network you asked for: `x upgrade` reads your configured npm registry through `bun pm view`, `x pr` and `x ci` go through your own `gh`, `x deploy verify` polls your own origin. If telemetry is ever added it is opt-in, off by default, and a major.
+
+### Will you add an adapter for my host or my ORM?
+
+No. Multi-ORM means two migration stories and two sets of generated SQL for an agent to learn. Vendor deploy adapters violate the containers-only axiom. Removing an alternative is treated as a feature.
+
+### Is it overkill for a small project?
+
+No, and it is measured rather than argued. `x new` asks **0** questions (all five flags carry a
+default), writes **134** files you never edit, installs **104** packages, and reaches a running app
+in **4** commands with **0** env values supplied and nothing to install first — no Docker, no
+Postgres, no Redis, no NATS. There is no lite mode to pick, because there is no second path to pick
+between ([axiom 1](Home#the-rules-everything-else-follows)). The whole range, both ends, 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).
+
+### Is it enough for a very large project?
+
+The capability answer is [`docs/idea/20-large-app-readiness.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/20-large-app-readiness.md) — graded against what a very large product needs, including what it must still build itself — and the deployment answer is [`docs/idea/17-scale-ladder.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/17-scale-ladder.md), rung by rung, naming where the "no app code change" invariant breaks today. What is **not** claimed: nobody has shipped a very large app on it yet, and this wiki will say so until somebody has.
+
+### Who is it for?
+
+Primary user: **an AI agent** — one correct way per task, machine-readable errors, generated facts to read. Secondary: **a tired senior engineer, working through their own AI agent and AI reviewer** — no glue code, no config archaeology, no 3am pager. Both want the same thing: fewer decisions with consequences.
+
+### How is this different from Rails, Next.js, Meteor, or Phoenix?
+
+Rails, Next.js, Meteor, Phoenix and Inngest / Zero each get a section on [Compared](Compared): when to pick that stack instead, first, then when to pick this one, and what you give up here.
+
+Nothing here is novel in isolation. See [Home](Home) for the full "steal explicitly" table.
+
+## Getting unstuck
+
+### Where do I report a bug?
+
+Run `x verify --json` and `x doctor --json`, attach both, and open an issue. The JSON is the report. Security issues go through [`SECURITY.md`](https://github.com/developerz-ai/ultimate/blob/main/SECURITY.md), never a public issue.
+
+### An error code is unclear — where do I look?
+
+`x errors explain <CODE> --json`, then [Error codes](Error-Codes). Every `X_*` code carries a cause, an exact fix command, and a docs URL, rendered identically in the terminal, the browser overlay, and `--json`. Symptom-first: [Troubleshooting](Troubleshooting).

package/wiki/Feature-Flags.md

@@ -0,0 +1,65 @@
+# Feature flags
+
+**Permanent switches, and temporary ones that cannot be forgotten.** Package `@ultimat3/flags`
+(tier 1) — the full reference is
+[`packages/flags/README.md`](https://github.com/developerz-ai/ultimate/blob/main/packages/flags/README.md).
+
+N flags are 2^N states nothing tested. This package takes that trade only on terms that bound the
+exponent: every flag declares one of two kinds, and a `temporary` flag cannot be declared without an
+expiry.
+
+| Kind | Meaning | Lifecycle |
+|---|---|---|
+| `permanent` | a real product or ops switch — a plan capability, a kill switch | none |
+| `temporary` | scaffolding around an in-progress change | `expiresAt` and `owner` are required **by the type**; past the expiry every evaluation reports `X_FLAG_EXPIRED` to the app's error monitor |
+
+`defineFlag()` is a `define*` helper, not a ninth primitive: a flag has no handler, no input schema
+and no surface of its own ([The eight primitives](The-Eight-Primitives)).
+
+```ts
+import { defineFlag, isEnabled } from '@ultimat3/flags';
+
+export const newTaxEngine = defineFlag({
+  kind: 'temporary',
+  key: 'checkout.new-tax-engine',
+  description: 'routes checkout through the rewritten tax engine',
+  owner: 'payments',
+  expiresAt: '2026-12-01',
+  targeting: { default: false, rollout: 10, roles: ['staff'] },
+});
+
+if (isEnabled('checkout.new-tax-engine', actor)) {
+  // …
+}
+```
+
+`isEnabled` is **synchronous**, for the reason `can()` is: it runs inside policy predicates and
+render passes. An undeclared key throws `X_FLAG_UNKNOWN` rather than answering `false` — a typo read
+as "off" is a branch that never runs in production.
+
+## Targeting
+
+Allow lists first, then the rollout, then `default`:
+
+| Field | Meaning |
+|---|---|
+| `actors`, `roles`, `orgs` | always on for these ids, roles or tenants |
+| `subjects` | allow lists for the app's own record kinds — `{ bank: ['bank_integration:bbva'] }`, read from the call site's third argument |
+| `rollout` | whole percentage 0–100, stable per subject: `fnv1a(key + ':' + id) % 100`, never `Math.random()` |
+| `bucketBy` | what the rollout divides — `'actor'` (default), `'org'`, or any subject kind, so a tenant is on one side **whole** |
+
+Targeting by a subject kind the call does not carry throws `X_FLAG_SUBJECT_REQUIRED` — never a
+fallback to the actor or to `default`.
+
+## Overrides and reporting
+
+`applyFlagSnapshot({ key: targeting })` lands targeting from outside — a poller, a job, a channel —
+so evaluation never loads anything. Keys this build does not declare come back in `unknown` rather
+than throwing: a control plane is often ahead of a deploy. An overdue flag is reported through
+core's one error-reporting seam (`configureErrorReporting`), at most once an hour per flag.
+
+`flagsReport()` projects every flag with its kind, owner and expiry. Nothing reads it yet: no CLI
+command prints it and no manifest section carries it.
+
+Codes: `X_FLAG_DUPLICATE`, `X_FLAG_EXPIRED`, `X_FLAG_EXPIRY_INVALID`, `X_FLAG_SUBJECT_REQUIRED`,
+`X_FLAG_TARGETING_INVALID`, `X_FLAG_UNKNOWN` — [Error codes](Error-Codes).

package/wiki/Getting-Started.md

@@ -0,0 +1,221 @@
+# Getting started
+
+```
+bunx create-ultimate myapp && cd myapp && bun run setup && bun run dev
+```
+
+Building a blog or an API rather than a dashboard? Add `--shape blog` or `--shape api` to the
+first command: [Shapes](Shapes) says what each writes and leaves out.
+
+**Four commands, and `bun run setup` is one of them.** It is the scaffold's own script, six steps —
+`bun install`, an `.env.development.local` touch, `x db gen "initial"` when
+`packages/db/migrations` holds no `.sql`, `x db migrate`, `x db seed`, `x manifest` — idempotent, so
+re-running it after a pull is safe. The last step is not optional either: `x.manifest.json` is a
+projection of the loaded app, nothing else ever runs the command, and `x verify`'s `manifest` step
+refuses its absence with `X_MANIFEST_MISSING`. `bunx create-ultimate myapp && cd myapp && x dev` is what this page said until 2026-08-23 and
+it does not work: `x new` writes files and installs nothing, so the app has no `node_modules`, no `x`
+of its own, and `x dev` stops on `X_BUILD_FAILED` — *"Could not resolve `@ultimat3/ui`. Maybe you
+need to `bun install`?"*
+
+**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).
+
+No Docker daemon, no `.env` scavenger hunt, no service to provision — `.env.development` ships
+committed non-secret defaults and an empty `DATABASE_URL` means embedded PGlite.
+
+No service to install either — bun and git are the whole prerequisite list → [Bare VM](Bare-VM).
+
+`bun run setup`, then `x dev`, measured on a fresh scaffold `As of 2026-08-23` (6.7s for setup on a warm
+Bun cache) — recorded **before** the `.env.development.local` touch and `x manifest` joined the
+script, so neither is in the transcript or the number, and the closing line now reads
+`next: bun run dev`:
+
+```
+$ bun run setup
+  packages/db/migrations/20260823155026_initial.sql
+✓ migration 20260823155026_initial generated
+✓ migrations applied
+✓ 1 seed(s): 2 inserted, 0 updated, 0 already stored
+setup complete — next: x dev
+
+$ x dev
+  roles web, sync, worker, scheduler
+  panels routes, timeline, live, jobs, db, mail, cache, policy, manifest, services, boundaries
+  manifest /path/to/myapp/x.manifest.json
+  introspect http://localhost:3000/_x
+✓ dev ready on http://localhost:3000 — /_x mounted (11 panels), db=embedded events=embedded storage=embedded mail=embedded cdn=none
+```
+
+`replicator` is the fifth role and is **opt-in** — it takes a replication slot, which is not
+something every `x dev` should do by starting: `x dev --role web,sync,worker,scheduler,replicator`.
+
+## What you get before writing a line
+
+Measured on a fresh scaffold, `As of 2026-08-23`.
+
+| Thing | Where | Detail |
+|---|---|---|
+| Embedded Postgres | `.x/pgdata` | PGlite in-process, no local install; `bun run setup` migrates and seeds it |
+| In-process events | same process | `events=embedded`; the same seam NATS fills in prod |
+| S3 | `./.x/storage` | real S3 API surface via `Bun.s3` |
+| Mail | `/_x` inbox | captured, never sent |
+| Redis (the shared cache tier) | not started | the scaffold's `cache.tiers` is `['request-memo', 'lru']`; adding `'redis'` is what builds the shared rung |
+| `/_x` dev panel | `http://localhost:3000/_x` | 11 panels: routes, timeline, live, jobs, db, mail, cache, policy, manifest, services, boundaries |
+| MCP server | `x mcp serve` | 19 dev tools over `stdio` or `http` (14 framework tools plus five `ui.*`). **Not started by `x dev`** — `/mcp` on the dev server is 404 |
+| Landing page | `apps/web/site/page.tsx` | `render: 'static'`, `hydrate: 'never'`, `budget: { js: '0kb' }`, real meta + JSON-LD |
+| Dashboard | `apps/web/app/dashboard/page.tsx` | `render: 'stream'`, `hydrate: 'visible'`, `budget: { js: '60kb' }` (one island, the theme toggle), behind `policy: { permission: 'dashboard:read' }`. A `<Hole>` is the next read it does not wait for ([Routes and render modes](Routes-And-Render-Modes#what-a-hole-does)) |
+| Admin app | `apps/admin/` | one `ssr` page; your actions reach an agent through `mcp: { expose: true }` and `x mcp serve`, not through this app |
+| Green gate | `bun run verify` — `x verify` | 21 steps, in this order: typecheck, lint, boundaries, filesize, package-shape, errors, unit, contract, live, job, exercise, e2e, eval, drift, contract-diff, budgets, seo, i18n, policy, manifest, roadmap. `budgets` weighs `.x/build-stats.json` and runs `x build --target static` itself when that file is missing or older than the source, so `x verify` alone is the gate on an app nobody has built (`As of 30.0`). The first-run verdict on a fresh scaffold is measured by CI, never asserted here |
+
+`x dev` runs **every role in one process** with isolation simulated, not skipped: separate ALS contexts, a real Postgres queue, real logical replication, a real SIGTERM drain on `x dev restart`. Nothing in the framework branches on `if (dev)` — only the drivers differ.
+
+## 1. Write your first action
+
+```
+x g action publish-post
+```
+
+```ts
+export const publishPost = action({
+  input:  t.object({ postId: t.uuid, notify: t.boolean.default(true) }),
+  output: PostView,
+  policy: can('post:publish', ({ input, actor }) => ownsPost(actor, input.postId)),
+  cache:  { invalidates: [tag.post, tag.feed] },
+  mcp:    { expose: true, description: 'Publish a draft post' },
+  async handle({ input, ctx }) {
+    const post = await ctx.posts.publish(input.postId);
+    if (input.notify) await notifySubscribers.enqueue({ postId: post.id, orgId: post.orgId });
+    return post;
+  },
+});
+```
+
+That one declaration emits six artifacts — HTTP route, OpenAPI operation, typed client function, job handle, MCP tool, test scaffold. See [Actions](Actions).
+
+Register it, with every other primitive, in one call. Importing `api/index.ts` IS the boot.
+
+```ts
+// apps/web/api/index.ts
+import { defineApi } from '@ultimat3/action';
+import * as postActions from '../app/posts/actions';
+import * as postJobs from '../app/posts/jobs';
+import * as postQueries from '../app/posts/live';
+import * as postMutators from '../app/posts/mutator';
+import * as scheduledTasks from './tasks';
+
+export const api = defineApi({
+  actions: [postActions],
+  mutators: [postMutators],
+  queries: [postQueries],
+  jobs: [postJobs],
+  tasks: [scheduledTasks],
+});
+
+export type Api = typeof api;
+```
+
+## 2. Call it from `app/`
+
+`app/` may import `api/` **types only**. The typed client is derived from those types; there is no codegen step to remember and no `fetch`.
+
+```ts
+// apps/web/shared/client.ts
+import { rpc } from '@ultimat3/action';
+import type { Api } from '../api';
+
+export const api = rpc<Api['actions']>({ baseUrl: '/' });
+```
+
+```tsx
+// apps/web/app/posts/ui/publish-button.tsx
+import { api } from '../../../shared/client';
+import { t as translate } from '@ultimat3/i18n';
+import type { PostView } from '@myapp/domain';
+
+export function PublishButton(props: { post: PostView }) {
+  const publish = async (): Promise<void> => {
+    await api.publishPost({ postId: props.post.id, notify: true });
+  };
+  return (
+    <button type="button" onClick={publish}>
+      {translate('post.publish')}
+    </button>
+  );
+}
+```
+
+Rename `postId` in the action and this file fails typecheck. One rename, N errors, all real work.
+
+## 3. Drive it from an agent over MCP
+
+**`x dev` does not serve MCP** — measured `As of 2026-08-23`, `GET /mcp` on the dev server answers
+404 and nothing listens on 9229. The MCP server is its own command, and it prints the bearer token
+your client must send:
+
+```
+x mcp serve --transport stdio                  # a client that spawns the server
+x mcp serve --transport http --port 9229       # POST /mcp, bearer token printed at boot
+```
+
+`stdio` and `http` are the two transports (`x help mcp`); there is no `ws` transport, and a client
+configured for one gets no connection. Register the printed URL and token with whatever MCP client
+you use.
+
+The agent now sees `publishPost` as a tool with JSON Schema from `input`, the description from `mcp.description`, and **the action's own `policy` as its authorization** — unwrapped, identical to the HTTP path. A denial is the same code in all three encodings:
+
+```json
+{ "code": "X_FORBIDDEN", "cause": "actor user_2 lacks post:publish on post_9",
+  "fix": "grant post:publish to the actor's role, or call as the post owner",
+  "docs": "https://github.com/developerz-ai/ultimate/wiki/Error-Codes" }
+```
+
+Introspection an agent should use instead of grepping:
+
+| Want | Command | MCP tool |
+|---|---|---|
+| every action + schemas | `x actions list --json` | `actions.describe` (no arguments — every action and query) |
+| one action in detail | `x actions show publishPost --json` | `actions.describe`, then pick the entry |
+| is this protected | `x policy explain publishPost --json` | none — `policies.list` returns the catalog, not the per-declaration matrix |
+| the whole app as data | `x manifest --json` | `manifest.read` |
+| what an `X_*` code means | `x errors explain X_FORBIDDEN` | `errors.explain` |
+| how the framework does X — **ask this first**, before stating a limit | `x docs "send email"` (offline: the installed packages and this wiki) | none |
+
+## 4. `x verify`
+
+One command. Green means shippable.
+
+```text
+$ x verify
+  ✓ typecheck  ✓ lint  ✓ boundaries  ✓ filesize  ✓ package-shape  ✓ errors
+  ✓ unit  ✓ contract  ✓ live  ✓ job  ✓ e2e  ✓ eval
+  ✗ drift
+      X_DB_DRIFT: schema differs from migrations
+        cause: table "posts" has column "publish_at" not present in any migration
+        fix:   x db gen "add publish_at"
+```
+
+`x verify --json` emits the same content machine-readably. CI runs exactly `x verify` — a check that lives only in CI is a check you cannot run.
+
+## Where next
+
+| Page | Read it for |
+|---|---|
+| [Installation](Installation) | prerequisites, `x new` flags, typed env, MCP client setup |
+| [Project layout](Project-Layout) | the generated tree, surfaces, the `site/` → `app/` boundary |
+| [The eight primitives](The-Eight-Primitives) | the whole conceptual surface, in eight lines |
+| [Actions](Actions) | every field, all six projections, introspection |
+| [Entities and migrations](Entities-And-Migrations) | schema, drift, branch DBs |
+| [Policies and authz](Policies-And-Authz) | one authz system, tenancy, denials |
+| [Queries and live queries](Queries-And-Live-Queries) | reads, `live: true` |
+| [Jobs and workflows](Jobs-And-Workflows) | durable steps, idempotency |
+| [Routes and render modes](Routes-And-Render-Modes) | `static` / `isr` / `ssr` / `stream` |
+| [Testing](Testing) | six test types, DB-clone parallelism |
+| [CLI reference](CLI-Reference) | every command, every `--json` |
+| [Error codes](Error-Codes) | code → cause → fix |
+| [Troubleshooting](Troubleshooting) | first-run failures |
+
+## Status
+
+`As of 2026-08-23`. Stable API — semver from here ([Upgrading](Upgrading); `x upgrade` moves one major per run). The repository holds 30 `@ultimat3/*` packages plus the unscoped `create-ultimate` and versions all 30 in lockstep. Every major so far has been a correctness sweep with no codemod, so each `BREAKING —` entry names its own manual edit; [Upgrading](Upgrading) walks all of them, oldest first, and each section states its own count. Only the [footer](_Footer) stamps a version number, and this page states none. **What `bunx create-ultimate myapp` installs is npm's `latest`**, one version for all 31 workspaces, each published by the release workflow over OIDC with a provenance attestation. Resolve it, do not trust this line — `npm view @ultimat3/core version`, and `npm view @ultimat3/core dist.attestations` for the attestation. **No publication holes**: `@ultimat3/scraping` was the last never-published package, bootstrapped by hand at 2.0.0, so `bun add @ultimat3/scraping` resolves. Milestones 0–10 are ✅; milestone 11 is 🚧, open on its two-platform deploy proof. Realtime tiers 1–2 ship, and tier 3 (local-first) shipped in 21.0.0, opt-in per entity (`entity(name, { persist: true })`). The 50k-socket forced-restart benchmark **is measured and committed** — first patch on the reconnected socket at p50 54.0s / p90 105.5s, on one node; delivery is a second run, 10,000 clients, 1,666,882 patches, 0 observed sequence gaps ([Realtime](Realtime)). Status markers come from [`docs/idea/14-roadmap.md`](https://github.com/developerz-ai/ultimate/blob/main/docs/idea/14-roadmap.md). See [FAQ](FAQ).

package/wiki/Home.md

@@ -0,0 +1,160 @@
+# 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, quarantine, 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 |
+| [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 in-flight major as a checklist under `[Unreleased]`, 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 |