@ultimat3/cli 29.4.0 → 30.1.0

package/wiki/Tutorial-01-First-App.md

@@ -0,0 +1,289 @@
+# Tutorial 1 — your first app
+
+One command scaffolds a monorepo that already runs. No Docker daemon, no database to provision, no `.env` to fill in.
+
+`As of 2026-08-23`, with every gate row re-measured `As of 2026-09-12`. **This page documents `main`, not a published release.** Every file count, gate result and command output below was re-measured on this tree: `x new` → `bun install` → the command, in a directory outside the checkout. Rows that still describe a published version say so in their own line.
+
+Series: **1** · [2 — first feature](Tutorial-02-First-Feature) · [3 — auth and admin](Tutorial-03-Auth-And-Admin) · [4 — jobs and realtime](Tutorial-04-Jobs-And-Realtime) · [5 — deploy free](Tutorial-05-Deploy-Free) · [6 — growing up](Tutorial-06-Growing-Up)
+
+## Prerequisites
+
+| Need | Version | Check |
+|---|---|---|
+| Bun | ≥ 1.4.4 | `bun --version` |
+| Docker | only for [tutorial 5](Tutorial-05-Deploy-Free) | `docker --version` |
+| Postgres | never, locally | — |
+
+## Scaffold
+
+```bash
+cd $(mktemp -d)
+bunx create-ultimate myapp
+```
+
+**Unpinned on purpose.** Pinning the tutorial to a version pins readers to a scaffold that stops matching this page on the next tag; `README.md` and `llms.txt` drop the pin for the same reason. To reproduce a specific release, add `@<version>` and read that release's tag of this page.
+
+```text
+  213 files in /tmp/tmp.XXXXXXXX/myapp
+✓ created myapp — next: cd myapp && bun run setup && bun run dev
+```
+
+`As of 2026-11-03`; `--no-example` writes 181.
+
+Counts are a derived fact — `x new --dry-run --json` lists every file, and one added template moves the number.
+
+```bash
+cd myapp && bun run setup
+```
+
+```text
+setup complete — next: bun run dev
+```
+
+`bun run setup` is `bun install`, an `.env.development.local` touch, `x db gen "initial"`, `x db migrate`, `x db seed`, then `x manifest` — so the database is migrated and `x.manifest.json` exists before the gate asks for either. `x new` installs nothing, so this is not optional.
+
+`x` is a workspace dependency, not a global install. `bunx x <command>` resolves `node_modules/.bin/x`; the `package.json` scripts (`bun run verify`, `bun run dev`) resolve the same binary. A globally installed `x` (`bun link`, `bun add -g`) run inside the app **hands over** to that same file, `As of 2026-09-05`, and says so on stderr: a global copy carries its own `@ultimat3/entity` with an empty registry, and it wrote a zero-entity manifest under a green exit code before it did. `ULTIMATE_KEEP_GLOBAL_CLI=1` is the opt-out — [`@ultimat3/cli`'s README](https://github.com/developerz-ai/ultimate/blob/main/packages/cli/README.md) has the measurement.
+
+### Two shapes, one generator
+
+Counts are derived, never quoted here — `x new --dry-run --json | jq '.data.files | length'`, per
+shape. Measured on fresh scaffolds of this tree, `As of 2026-11-05`:
+
+| Invocation | `bun run setup && bun run verify` on run one |
+|---|---|
+| `bunx create-ultimate myapp` | **green, 20 of 21 steps pass** — `budgets` among them; `roadmap` skipped (a framework-repo step) |
+| `bunx create-ultimate myapp --no-example` | **green, 17 of 21 steps pass** — `live`, `job`, `e2e` skipped (no such test yet) and `roadmap` |
+
+`--no-example` omits the `post` feature slice and its route. Pick it when an agent is about to write the real feature anyway — [tutorial 2](Tutorial-02-First-Feature) starts there. Pick the default when you want a worked example to read.
+
+## The gate, first thing
+
+```bash
+bun run verify
+```
+
+The app's own gate is `x verify`, alone. Its `budgets` step weighs `.x/build-stats.json`, and on a
+fresh scaffold no such file exists yet, so the step runs `x build --target static` itself first
+(into `.x/verify-static`, never over `.x/static`).
+
+The default scaffold, after `bun run setup`, with no `.x/build-stats.json` beforehand,
+`As of 2026-11-03` (`exercise` measured 2026-11-05): the whole gate, in the order it runs:
+
+```text
+  ✓ typecheck          3064ms
+  ✓ lint               232ms
+  ✓ boundaries         844ms
+  ✓ filesize           906ms
+  ✓ package-shape      402ms
+  ✓ errors             951ms
+  ✓ unit               2790ms  3 workers (budget 4.0 GB)
+  ✓ contract           1233ms  3 workers (budget 4.0 GB)
+  ✓ live               840ms  serial
+  ✓ job                345ms  1 of 3 workers (budget 4.0 GB)
+  ✓ exercise           1952ms
+  ✓ e2e                12124ms  serial
+  ✓ eval               91ms
+  ✓ drift              1486ms
+  ✓ contract-diff      78ms
+  ✓ budgets            6336ms
+  ✓ seo                40ms
+  ✓ i18n               63ms
+  ✓ policy             75ms
+  ✓ manifest           1131ms
+  - roadmap            0ms
+✓ 20 of 21 steps passed in …ms — 1 skipped: roadmap
+```
+
+`-` is skipped, not passed: `roadmap` is a framework-repo step. The default scaffold ships its
+example slice with a live test, a job test and an e2e test, so `live`, `job` and `e2e` are ticks on
+run one; **with `--no-example`** there is no such test yet, and those three are dashes too. `contract` is **not** among them — the scaffold
+ships `apps/web/api/health.contract.test.ts`, which is what makes it a tick on run one. Nor is
+`exercise`: it needs no test file — it runs every action, query and job the app registers, once,
+against seeded rows — and both shapes write the `apps/web/exercise.ts` it reads. The summary
+names every skip, so a gate that is green because a suite does not exist says so on the one line you
+read. [Tutorial 2](Tutorial-02-First-Feature) turns more of those dashes into ticks.
+
+The list is
+`VERIFY_STEP_NAMES` ([`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: the same steps run here and in the framework repo.
+
+### `budgets` builds before it weighs
+
+`budgets` took 6.3 s above because it built first. Delete the stats and `--verbose` prints the line
+that says so; run it again and it reads the stats it just wrote:
+
+```bash
+rm .x/build-stats.json
+bunx x verify --only budgets --verbose
+bunx x verify --only budgets
+```
+
+```text
+  ✓ budgets            7320ms
+      | built first: build stats were missing — x build --target static --out .x/verify-static (6968ms)
+✓ NOT A GATE RUN — all 1 steps passed in …ms
+  ✓ budgets            324ms
+✓ NOT A GATE RUN — all 1 steps passed in …ms
+```
+
+It builds when `.x/build-stats.json` is missing, written by an earlier measurement rule, or older
+than the newest app source file (tests excluded), and never otherwise: run the gate again with
+nothing edited and the step reads the stats it has. After an edit, the gate pays one static build.
+A build that fails is the step's verdict, under the build's own code and `fix:`.
+
+CI asserts the result: `scaffold-smoke` runs a fresh app's own scripts **once, with no waiver and no fix-follow**, and `budgets` must come back **green** rather than merely not-red — a skip would mean the static build bought nothing ([`scripts/scaffold-gate.ts`](https://github.com/developerz-ai/ultimate/blob/main/scripts/scaffold-gate.ts)).
+
+### The invariant block is typed from your columns
+
+`invariants` is one callback over the whole list, and `c` is typed from the `columns` above it:
+
+```ts
+invariants: (c) => [
+  invariant('post_title_not_blank', c.title.trimmed().minLength(1)),
+  invariant('post_price_non_negative', c.price.minor.atLeast(0)),
+],
+```
+
+`c.titel` is a compile error that names `title`, not a runtime surprise. Everything `x new` and `x g` write typechecks as generated — no `!`, no edit before the first `x verify`.
+
+What still ships broken: [Known gaps](Known-Gaps).
+
+## Run it
+
+<!-- no-run: a server that runs until stopped; the --once fence below is its smoke test -->
+```bash
+bunx x dev
+```
+
+`--once` boots, reports and exits — the shape to paste into a smoke test:
+
+```bash
+bunx x dev --once --port 3100
+```
+
+```text
+{"ts":"2026-11-03T16:48:57.124Z","level":"info","msg":"ultimate web listening on http://localhost:3100"}
+{"ts":"2026-11-03T16:48:57.118Z","level":"info","msg":"sync node ready","buildId":"e6af64a2077e5d60","path":"/_x/sync"}
+{"ts":"2026-11-03T16:48:57.134Z","level":"info","msg":"jobs.worker.started","workerId":"worker-01a1a250-…","queues":["myapp-default","default"]}
+{"ts":"2026-11-03T16:48:57.137Z","level":"info","msg":"jobs.scheduler.started","tasks":1}
+{"ts":"2026-11-03T16:48:57.142Z","level":"info","msg":"live feed in-process","detail":"the embedded database has no walsender; repository writes in this process reach subscribers"}
+  roles web, sync, worker, scheduler
+  panels routes, timeline, live, jobs, db, mail, cache, policy, manifest, services, boundaries
+  manifest /tmp/…/myapp/x.manifest.json
+  introspect http://localhost:3100/_x
+  mcp POST /mcp
+✓ dev ready on http://localhost:3100 — /_x mounted (11 panels), db=embedded events=embedded storage=embedded mail=embedded cdn=none live=in-process
+```
+
+An excerpt, `As of 2026-11-03`: the boot also logs the dev viewer warning, the metrics port and the drain `--once` ends with.
+
+Four roles in one process, isolation simulated rather than skipped. `replicator` is opt-in via `--role`; `migrate` is not a dev role.
+
+### Why no Docker
+
+`.env.development` ships every service key **empty**, and empty means embedded:
+
+```bash
+DATABASE_URL=
+NATS_URL=
+S3_ENDPOINT=
+PORT=3000
+ROLE=web
+```
+
+| Key | Unset means | Set means |
+|---|---|---|
+| `DATABASE_URL` | PGlite in this process, under `.x/pgdata` | that Postgres |
+| `NATS_URL` | in-process fanout | that NATS server |
+| `S3_ENDPOINT` | `.x/storage` on disk | that S3 |
+
+Nothing in the framework branches on `if (dev)` — only the driver behind the seam differs. Same code path, same `db()`, same `enqueue()`. Full table: [CLI reference § x dev](CLI-Reference).
+
+## What each directory is
+
+```
+myapp/
+├── app.config.ts            the one config file — names env KEYS, never values
+├── apps/
+│   ├── web/
+│   │   ├── site/            static, 0kb JS, SEO-critical. May NOT import app/
+│   │   ├── app/             authed, streaming, realtime. Feature slices live here
+│   │   ├── api/             actions only — no rendering, no components
+│   │   ├── shared/          actor type, tokens, primitives. A leaf both surfaces import
+│   │   ├── server.ts        the production entry: ROLE + PORT, nothing else
+│   │   └── prerender.ts     the static entry: one HTML file per `render: 'static'` route,
+│   │                        plus sitemap.xml and robots.txt
+│   ├── admin/               the admin app, gated on `admin:read`
+│   ├── desktop/  mobile/    README stubs, no code
+├── packages/
+│   ├── db/                  schema.ts (the entity export list — the package's public
+│   │                        surface, not the generator's input) + migrations/
+│   ├── domain/              pure types, no I/O
+│   ├── i18n/                catalogs/<locale>.json — one flat file per locale
+│   ├── mcp/                 the app's own MCP surface over its actions
+│   └── ui/                  app components on semantic tokens
+├── docker/                  Dockerfile, .dockerignore, dev + prod compose, helm/
+├── guards/                  one rule per file, run by `x verify`'s boundaries step.
+│                            Every name in SHIPPED_GUARD_NAMES ships; `x doctor`
+│                            lists any missing. Delete one by deleting its file
+├── bin/                     setup.ts — `bun run setup`; `dev` and `verify` are x's own
+└── CLAUDE.md  AGENTS.md     what an agent reads first: one file, AGENTS.md a symlink
+```
+
+Boundaries are a build error, not a note — but `boundaries` is a **step of `x verify`**, not a top-level command. `bunx x boundaries` exits `X_CLI_UNKNOWN_COMMAND`. Run `bunx x verify` and read the `boundaries` line. Full model: [Project layout](Project-Layout).
+
+### The database, first run
+
+`packages/db/migrations` starts **empty**, and `x db gen` is its only writer. Two commands, in this order:
+
+```bash
+bunx x db gen "initial"    # entities → <id>.sql, <id>.snapshot.json, <id>.hash
+bunx x db migrate          # applies them, then diffs the live schema against the ledger it wrote
+```
+
+`bun run setup` runs both — `bun install`, an `.env.development.local` touch, `x db gen "initial"` when the directory holds no `.sql`, `x db migrate`, `x db seed`, then `x manifest`. `x db migrate` is `@ultimat3/db`'s own migrator, the one `ROLE=migrate` runs, so nothing extra has to be installed.
+
+Until the generate has run, `x verify` is **red on its `drift` step** — correct behaviour with a runnable fix, not a defect:
+
+```text
+X_DB_DRIFT: schema differs from migrations
+  cause: packages/db has a schema but no migration recorded it
+  fix:   x db gen "initial"
+```
+
+That is the scaffold **with** the example slice, which declares one entity. `x new --no-example` declares none, and zero entities against zero migrations is agreement rather than drift, so its `drift` step is green from the first run and goes red the moment you write your first `entity()`.
+
+`x new` hand-wrote a `0000_initial.sql` until 2026-08 and that was the defect — a second writer of a directory the generator owns, whose file carried no `.snapshot.json`, so `x db migrate` answered `X_DB_DRIFT` naming `x db gen` and `x db gen` answered `X_MIGRATION_SNAPSHOT_MISSING` naming version control for a file version control never had. Neither `fix:` now names the command that raises the other ([Known gaps](Known-Gaps)).
+
+## The routes are clean
+
+`x routes` on a fresh scaffold reports four file routes and no findings, plus the admin's
+screens. `As of 2026-10`, read off the templates `x new` writes:
+
+| path | surface | render | hydrate | offline | declared by |
+|---|---|---|---|---|---|
+| `/` | site | static | never | precache | `apps/web/site/page.tsx` |
+| `/offline` | site | static | never | precache | `apps/web/site/offline/page.tsx` |
+| `/dashboard` | app | ssr | visible | runtime | `apps/web/app/dashboard/page.tsx` |
+| `/posts` | app | ssr | visible | runtime | `apps/web/app/posts/page.tsx` |
+
+The admin has no page file: `apps/admin/app/admin/admin.ts` declares `defineAdmin()`, which mounts
+`/admin` and a list, detail and form per entity. Those rows name the call and the permissions that
+gate them instead of a file — `defineAdmin() · admin:read + posts:read` — and their `--json` rows
+carry `mount`. `--no-example` drops `/posts`. `x routes` is not a gate step either way, so a finding
+here never fails `x verify` — run it after scaffolding and after every `x g route`.
+
+A read that should not hold up the page goes in a `<Hole>` on a `stream` page ([Routes and render modes](Routes-And-Render-Modes#what-a-hole-does)).
+
+## The five commands worth memorising
+
+| Want | Command |
+|---|---|
+| is it shippable | `bun run verify` (add `--json`) |
+| what is wrong with my environment | `bunx x doctor --json` |
+| what does this error code mean | `bunx x errors explain X_FORBIDDEN` |
+| what does this app contain | `bunx x manifest --json` |
+| what commands exist | `bunx x help` — planned ones are marked `(planned)` and throw `X_NOT_IMPLEMENTED` |
+
+## Next
+
+[Tutorial 2 — your first feature](Tutorial-02-First-Feature): one `entity`, one `policy`, one `action`, one `route`, one test, and the five artifacts a single declaration projects.

package/wiki/Tutorial-02-First-Feature.md

@@ -0,0 +1,339 @@
+# Tutorial 2 — your first feature
+
+Scaffold the slice, register it, migrate it, name the tests. One `action` declaration becomes an HTTP route, an OpenAPI operation, a typed client method, a job handle, an MCP tool and three contract assertions — with no second file to keep in step.
+
+`As of 2026-11-03`. Every command and every output on this page was re-run in the app [tutorial 1](Tutorial-01-First-App) leaves — `bunx create-ultimate myapp`, example slice included, built from this tree's packages (`scripts/scaffold-smoke-overrides.ts`) — by hand, in that order. `scripts/tutorial-run.ts` runs tutorials 1–4 the same way. Timings are that machine's; yours differ.
+
+Series: [1 — first app](Tutorial-01-First-App) · **2** · [3 — auth and admin](Tutorial-03-Auth-And-Admin) · [4 — jobs and realtime](Tutorial-04-Jobs-And-Realtime) · [5 — deploy free](Tutorial-05-Deploy-Free) · [6 — growing up](Tutorial-06-Growing-Up)
+
+## Never hand-write a primitive
+
+```bash
+bunx x g resource todo --dry-run
+```
+
+```text
+  + apps/web/app/todo/entity.ts
+  + apps/web/app/todo/entity.test.ts
+  + apps/web/app/todo/repo.ts
+  + apps/web/app/todo/repo.test.ts
+  + apps/web/app/todo/policy.ts
+  + apps/web/app/todo/policy.test.ts
+  + apps/web/app/todo/actions/create-todo.ts
+  + apps/web/app/todo/actions/create-todo.test.ts
+  + apps/web/app/todo/actions/create-todo.contract.test.ts
+  + apps/web/app/todo/errors.ts
+  + apps/web/app/todo/actions/archive-todo.ts
+  + apps/web/app/todo/actions/archive-todo.test.ts
+  + apps/web/app/todo/actions/archive-todo.contract.test.ts
+  + packages/i18n/catalogs/en.json
+  + apps/web/app/todo/live/todo-list.ts
+  + apps/web/app/todo/live/todo-list.live.test.ts
+  + apps/web/app/todo/live/todo-list.test.ts
+  + apps/web/app/todo/jobs/reindex-todo.ts
+  + apps/web/app/todo/jobs/reindex-todo.job.test.ts
+  + apps/web/app/todo/jobs/reindex-todo.test.ts
+  + apps/web/app/todo/service.ts
+  + apps/web/app/todo/service.test.ts
+  + apps/web/app/todo/ui.tsx
+  + apps/web/app/todo/ui.test.ts
+  + apps/web/app/todo/ui.module.scss
+  + apps/web/app/todo/ui/todo-card.tsx
+  + apps/web/app/todo/todo-form.island.tsx
+  + apps/web/app/todo/todo-form.island.states.ts
+  + apps/web/app/todo/todo-form.island.test.ts
+  + apps/web/app/todos/page.module.scss
+  + apps/web/app/todos/page.e2e.test.ts
+  + apps/web/app/todos/page.tsx
+  + apps/web/app/todos/page.test.ts
+  + apps/web/app/todos/page-db.test.ts
+  + apps/web/shared/roles.ts
+  + apps/web/api/index.ts
+  + packages/db/src/client.ts
+✓ would write 37 file(s) for resource todo — nothing written
+```
+
+**The form is an island, not a `ui/` component** — `todo-form.island.tsx` beside the slice rather than under `ui/`. A `createSignal` needs the browser, `.island.tsx` is what puts a module in the client bundle graph, and the route's `budget.js` is what bounds it. Everything under `ui/` renders on the server and ships no JS.
+
+Drop `--dry-run` to write them:
+
+```bash
+bunx x g resource todo
+```
+
+```text
+✓ wrote 39 file(s) for resource todo — next: …
+```
+
+`x g` never clobbers — an existing file is `X_GENERATE_CONFLICT`; the i18n catalog is merged key-by-key rather than overwritten; and a **slice module** (`entity.ts`, `repo.ts`, `policy.ts`, `errors.ts`) the slice already has is skipped, `--force` included, because it belongs to the slice rather than to the generator that needed it. The last three lines are the wiring: the grants in `roles.ts`, the slice's actions, query and job in `api/index.ts`, and its entity in the db client (`packages/db/src/client.ts`). A file the run would leave unchanged — a catalog merge that gains no key, wiring a previous slice already wrote — is skipped rather than counted. Here `bun run setup` has written `x.manifest.json` and `openapi.json` ([tutorial 1](Tutorial-01-First-App)), so the run re-projects both and prints 39; in an app with neither it prints 37. In a `x new --no-example` app, whose two `package.json`s do not yet name the workspace packages, the same runs print 39 and 41 (42 with `--admin`).
+
+**No migration is in that list.** `x db gen` is the only writer of `packages/db/migrations`, so a new slice is `x g resource todo` and then the two steps below.
+
+| Generator | Emits |
+|---|---|
+| `x g resource <n>` | the whole slice above — 37 files on a dry run in tutorial 1's app, 40 with `--admin` (`As of 2026-11-04`); a real run after `bun run setup` adds the two re-projected artifacts |
+| `x g entity` / `policy` / `action` / `mutator` / `query` / `job` / `task` | that primitive plus its test — **and the slice modules its own source imports**, when the slice has none: `x g job` is 5 files into a bare slice, `x g action` 8. Which ones differ per generator, so a job plants no `policy.ts` ([CLI reference § x g](CLI-Reference)) |
+| `x g route <path> --surface site\|app` | `page.tsx`, its stylesheet, its test, its catalog keys |
+
+`--surface site` on a `resource` is refused: a slice ships a live query and a form with a signal, and `site/` is the never-hydrated surface. Full flag table: [CLI reference § x g](CLI-Reference).
+
+## The layer rule
+
+The slice enforces one call direction, and `x verify`'s `boundaries` step is what makes it real.
+
+| Layer | File | May call |
+|---|---|---|
+| route | `apps/web/app/todos/page.tsx` | actions, queries |
+| action / query | `actions/*.ts`, `live/*.ts` | services |
+| service | `service.ts` | the repo |
+| repo | `repo.ts` | `db()` — the **only** module that may touch the table |
+
+## The entity
+
+```ts
+export const todo = entity('todos', {
+  // Naming the tenant column is what turns tenancy on: a read with no org predicate then fails
+  // with X_TENANCY_UNSCOPED instead of leaking another org's rows.
+  tenant: 'orgId',
+  columns: {
+    id: uuid().primaryKey(),
+    orgId: uuid(),
+    title: text({ max: 200 }),
+    price: money(),              // two physical columns: price_minor bigint + price_currency char(3)
+    createdAt: timestamp().defaultNow(),
+  },
+  invariants: (c) => [
+    invariant('todo_title_not_blank', c.title.trimmed().minLength(1)),
+    invariant('todo_price_non_negative', c.price.minor.atLeast(0)),
+  ],
+  indexes: [{ on: ['orgId', 'createdAt'] }],
+});
+```
+
+`c` is typed from the `columns` above it, so `c.titel` is a compile error naming `title` — see [tutorial 1](Tutorial-01-First-App#the-invariant-block-is-typed-from-your-columns).
+
+Each invariant runs twice from one declaration — in the app on every write, and as a Postgres `CHECK` in the migration. Details: [Entities and migrations](Entities-And-Migrations).
+
+## The policy decides once, everywhere
+
+```ts
+export const canTodoWrite = can<TodoScope>(
+  'todo:write',
+  ({ actor, input }) => actor !== null && actor.orgId === input.orgId,
+);
+```
+
+`can()` checks the grant first and the predicate second, so a denial distinguishes *you may never do this* from *you may, but not in that org*. The generated `policy.test.ts` pins the second gate with an actor who **holds** the grant and is still denied — delete the predicate and that test fails.
+
+`canTodoCreate` is the same grant with the one tenancy rule a create can have — the actor **has** an org — because the row is written under the actor's org, never one named in the body.
+
+The generator also **grants** what it declares, in `apps/web/shared/roles.ts`: `todo:read` to `member`, `todo:write` to `admin` (the dev actor's role). A permission an action requires and no role grants is `X_PERMISSION_UNGRANTED` on `x verify`'s `policy` step — every request to it would answer 403.
+
+Full model: [Policies and authz](Policies-And-Authz).
+
+## The action, and what it projects
+
+```ts
+export const CreateTodoInput = todo.$view(['title', 'price']);
+
+export const createTodo = action({
+  input: CreateTodoInput,
+  output: TodoView,
+  policy: canTodoCreate,
+  cache: { invalidates: [todoTag] },
+  // No `mcp` until you write a real description: an agent reads it to decide to call the tool.
+  async handle({ input, ctx }) { … return service.create({ ...input, orgId }); },
+});
+```
+
+A real insert. The input is the entity's own view of the columns a caller supplies, so a column added to `entity.ts` is one edit to that list; `orgId` comes from `ctx.actor`, never from the body.
+
+<!-- no-run: needs `bunx x dev` serving on :3000 -->
+```bash
+curl -X POST localhost:3000/api/todos/create -H 'content-type: application/json' \
+  -H 'sec-fetch-site: same-origin' -d '{"title":"Ship it","price":{"minor":1250,"currency":"USD"}}'
+```
+
+Five artifacts, read off the real registry with `createTodo.describe()`, `.openapi()`, `.job()`, `.contract()` and `@ultimat3/mcp`'s `toolFrom(createTodo)`:
+
+| Projection | Value, verbatim |
+|---|---|
+| HTTP route | `POST /api/todos/create`, capability `todo:write` |
+| OpenAPI operation | `operationId: "createTodo"`, `summary` from `mcp.description` |
+| MCP tool | none until `mcp: { expose: true, description }` is written; then `createTodo` — the export name verbatim — and every call goes through `createTodo`'s own `invoke`, so its policy is the one authz object, not a copy |
+| Job handle | `action:createTodo` — the same handler, run through the queue |
+| Contract tests | 3 generated assertions: garbage input rejected, anonymous denied, operation present in the spec |
+| Typed client | `.client({ baseUrl })` derives the path by string math, so the browser imports no server code |
+
+```bash
+bunx x actions list
+```
+
+```text
+  name         verb     resource  path                 capability  mcp
+  archivePost  archive  posts     /api/posts/archive   post:write  no
+  archiveTodo  archive  todos     /api/todos/archive   todo:write  no
+  createPost   create   posts     /api/posts/create    post:write  no
+  createTodo   create   todos     /api/todos/create    todo:write  no
+  health       invoke   healths   /api/healths/invoke  public      yes
+✓ 5 actions
+```
+
+`archivePost` and `createPost` are the example `post` slice tutorial 1's app ships with. Rename a column in the entity and every consumer fails typecheck. One rename, N errors, all real work. Every field: [Actions](Actions).
+
+## Registered for you
+
+`x new` writes `apps/web/api/index.ts`, and every `x g` adds the primitives it wrote to it. A job no `defineApi` lists keeps the positional name `job()` gave it — `anonymous-job-2` — and `x verify`'s `manifest` step refuses that as `X_JOB_UNREGISTERED`. After `x g resource todo`:
+
+```ts
+// apps/web/api/index.ts, in an app made with `x new --no-example` — importing it IS the boot
+import { defineApi } from '@ultimat3/action';
+import * as archiveTodo from '../app/todo/actions/archive-todo';
+import * as createTodo from '../app/todo/actions/create-todo';
+import * as reindexTodo from '../app/todo/jobs/reindex-todo';
+import * as todoList from '../app/todo/live/todo-list';
+import * as health from './health';
+
+export const api = defineApi({
+  actions: [health, createTodo, archiveTodo],
+  queries: [todoList],
+  jobs: [reindexTodo],
+});
+```
+
+Tutorial 1's app lists its example `post` slice the same way, ahead of the `todo` lines. The jobs are the half an app cannot skip: the module scan registers actions and queries by export name on its own, and registers no job. Actions and queries are listed for the type — `Api` is what the browser's typed client is shaped from. Each primitive is imported as a **file**, never a directory. Two features exporting one name collide with `X_ACTION_DUPLICATE` rather than merging in silence.
+
+## Migrations
+
+`x g resource` writes no migration and does not touch the entity export list. Two steps.
+
+**1. Export the entity.** `packages/db/src/schema.ts` is the db package's public surface — what the
+rest of the app imports a `todo` from:
+
+```ts
+export { todo } from '@myapp/web/app/todo/entity';
+```
+
+It is **not** what the migration generator reads. `x db gen` diffs the entity **registry**
+(`describeEntities()`), and `x verify`'s `drift` step hashes that same registry alongside the text
+under `packages/db/src/**` — so the entity is already in the diff the moment its own file exists.
+`loadApp` imports every module under `apps/*/{site,app,api,shared}/**` and `packages/*/src/**`, and
+`entity()` registers on import. `examples/dummy` is the proof: it has entities, migrations and a
+green `drift` step, and no `packages/db/src/schema.ts` at all.
+Adding the export line moves the text half of the hash too, which is why the drift below is the same
+either way. `bunx x verify --only drift`:
+
+```text
+  ✗ drift              2161ms
+      X_DB_SCHEMA_UNMIGRATED (packages/db/migrations)
+        cause: table "todos" is declared by the entities and no migration recorded it
+        fix:   bunx x db gen "record todos"
+```
+
+The newest migration is tutorial 1's `initial`, which recorded the example `posts` table; `todos` is
+in no migration yet. The slug is yours to choose; the fix only suggests one.
+
+**2. Generate the migration.** `x db gen` diffs the entity registry against the newest
+migration's snapshot and writes three files — `<id>.sql`, `<id>.snapshot.json` and `<id>.hash` —
+and refreshes the schema dump under `packages/db/schema/` (`todos.sql` under `04_tables/` and
+`05_indexes/`). A migration id is `<stamp>_<slug>`; the stamp is `x db gen`'s own clock:
+
+```bash
+bunx x db gen "add todos"
+```
+
+```text
+✓ migration …_add_todos generated
+```
+
+The 1.1.0 workaround this step used to carry (a hand-written `db-gen.ts` script, and two manual
+edits to the emitted SQL) is gone: all three defects it worked around were fixed in 2.0.0, and
+`scaffold-smoke` in CI runs `x db gen` then `x db migrate` on a fresh scaffold on every push.
+
+Apply them the way production does — same code path, no toolchain:
+
+<!-- no-run: the release-phase path; the x db migrate fence below applies the same migrations -->
+```bash
+ROLE=migrate bun apps/web/server.ts
+```
+
+```text
+{"ts":"2026-11-03T15:52:26.924Z","level":"info","msg":"ultimate migrate applied","applied":1,"available":1,"appVersion":"dev"}
+```
+
+`bunx x db migrate` is that same code path with a drift check after it. Both read
+`packages/db/migrations` and write one `x_migrations` ledger:
+
+```bash
+bunx x db migrate
+```
+
+```text
+✓ migrations applied
+```
+
+The `.hash` sidecar beside each migration is what `drift` compares against, so a fresh clone detects drift with no database and no local state.
+
+## Name the tests after their step
+
+A test's type is its **filename suffix**, not the helper it calls. `contractTest()` inside `create-todo.test.ts` runs under `unit`, and `x test contract` reports `X_TEST_NO_FILES`. `x g` already writes the typed names — `create-todo.contract.test.ts`, `todo-list.live.test.ts`, `reindex-todo.job.test.ts`, `page.e2e.test.ts` in the list above — so this is the rule for a test you add by hand:
+
+| Suffix | Runs in step |
+|---|---|
+| `*.contract.test.ts` | `contract` |
+| `*.live.test.ts` | `live` |
+| `*.job.test.ts` | `job` |
+| `*.e2e.test.ts`, anything under `e2e/` | `e2e` |
+| `*.eval.test.ts` | `eval` |
+
+## The gate, green
+
+```bash
+bunx x verify
+```
+
+Timings, worker counts and the `slowest:` lines trimmed:
+
+```text
+  ✓ typecheck
+  ✓ lint
+  ✓ boundaries
+  ✓ filesize
+  ✓ package-shape
+  ✓ errors
+  ✓ unit
+  ✓ contract
+  ✓ live
+  ✓ job
+  ✓ exercise
+  ✓ e2e
+  ✓ eval
+  ✓ drift
+  ✓ contract-diff
+  ✓ budgets
+  ✓ seo
+  ✓ i18n
+  ✓ policy
+  ✓ manifest
+  - roadmap
+✓ 20 of 21 steps passed in …ms — 1 skipped: roadmap
+```
+
+`live`, `job` and `e2e` were dashes in [tutorial 1](Tutorial-01-First-App); the slice's own typed tests are what they now run. `budgets` builds the site first when no current measurement exists, so it is green on the first run. `e2e` drives a real Chrome; on a machine without one its browser cases skip (`E2E_BROWSER_REQUIRED=1` makes that a refusal). `roadmap` reads `docs/idea/14-roadmap.md`, which an app does not have.
+
+## Drive it from an agent
+
+<!-- no-run: a server that runs until stopped -->
+```bash
+bunx x mcp serve --transport http --port 9229
+```
+
+19 tools, one catalog, the same on `stdio` and `http` — 14 framework tools (`routes.list`, `schema.describe`, `policies.list`, `actions.describe`, `jobs.inspect`, `queue.depth`, `manifest.read`, `errors.explain`, `db.query`, `db.migrate`, `tests.run`, `verify.run`, `logs.tail`, `graph.query`) and five that look at the UI (`ui.shot`, `ui.island`, `ui.inspect`, `ui.interact`, `ui.diff`). `bunx x mcp tools` prints them with their scopes.
+
+`createTodo` reaches an agent's tool list through the app's own surface in `packages/mcp/src/index.ts` (`defineAppMcp({ include: 'exposed' })`), carrying `mcp: { expose: true }` and **the action's own policy** as its authorization. Full model: [MCP and AI](MCP-And-AI).
+
+## Next
+
+[Tutorial 3 — auth and admin](Tutorial-03-Auth-And-Admin): who the actor is, which roles grant which permissions, and the admin surface over the actions you just declared.
+
+Related: [Actions](Actions) · [Entities and migrations](Entities-And-Migrations) · [Testing](Testing) · [Known gaps](Known-Gaps)